Let's take a few steps back to see the bigger picture: the client application generates requests and sends them through the chain of Acra's services to receive decrypted plaintext in the end.
What if the attackers compromise the app deeply and badly enough so they are able to alter its behaviour? From a simple SQL injection to remote/local code execution errors, there are threats, which make your application a source of risk once it's been compromised. Our idea is that since AcraServer is the only entity that decrypts sensitive data and sees all the requests addressed to it, it is AcraServer's responsibility to tell the good behaviour from bad and to take appropriate action.
Poison records are the records specifically designed and crafted in such a way that they wouldn't be queried by a user under normal circumstances. Yet poison records will be included in the outputs of
SELECT * requests. Upon passing AcraServer, they will inform it of untypical behaviour. The goal of using poison records is simple — to detect adversaries trying to download full tables / full database from the application server or trying to run full scans in their injected queries.
Poison records are the first of many database self-defence features planned for Acra
The concept: In a regular environment, users never query all the records will full-scan requests and their select statements are filtered by certain WHERE clauses. If this is your case, you'll benefit from using poison records. In essence, a poison record is a flawed AcraStruct, encrypted with a special Zone key. This design ensures that matching happens in the cryptographic layer, but without significant computational expenses.
AcraServer's key storage contains a special key, which is used for recognition of poison records. This key is generated either after a query passes through AcraServer, or upon running poison record generation utility AcraPoisonRecordMaker (but you will have to move the keys into AcraServer's key directory manually).
For example, you can run AcraServer with MySQL database:
$ docker-compose -f docker/docker-compose.mysql-nossl-server-ssession-connector.yml up $ docker ps CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES fa5c8a717f82 cossacklabs/acra-webconfig:master "/acra-webconfig -st…" 5 minutes ago Up 5 minutes 0.0.0.0:8000->8000/tcp docker_acra-webconfig_1 74ab6172fa41 cossacklabs/acra-connector:master "/acra-connector --a…" 5 minutes ago Up 5 minutes 9191/tcp, 0.0.0.0:9494->9494/tcp docker_acra-connector_1 19e2160e7c2f cossacklabs/acra-server:master "/acra-server --mysq…" 6 minutes ago Up 5 minutes docker_acra-server_1 732610db0946 docker_mysql "docker-entrypoint.s…" 6 minutes ago Up 6 minutes 0.0.0.0:3306->3306/tcp docker_mysql_1
Then run AcraPoisonRecordMaker:
$ docker exec -it docker_acra-server_1 /acra-poisonrecordmaker --keys_dir=/keys IiIiIiIiIiJVRUMyAAAALZT3kRMDW8biNub1xNvp8h8VMUGF2RZJ6aMEcu2tYrv9SRt23T8gJwQmVAAAAAABAUAMAAAAEAAAACAAAADM9OG4Y+XeOgQ1lotlwD3HFF3zfemKwqi3hW/jUt9pecCuSPJOcLydlYCDN9SX9THSwB66SO4JZAjuEVRwAAAAAAAAAAABAUAMAAAAEAAAAEQAAAB8M92tf6mWIegFfvwpKRU0rxvo24/N6PzmaAr3SpgIyldLPwSpm5Ly+TgDXGvaCcbV47DV/Qn/YmKnT2FJW8xh5Wyj7IKBoVxzqdvLkfE2VfbjdfekQeICEB/smYYQCKk=
The output is base64-encoded poison record that you should decode and insert into your data in the database as binary data.
There is one useful additional parameter that AcraPoisonRecordMaker has:
It will change the size of the generated random data in the poison record. This is useful for transforming the data inside the poison records to resemble your data in lengths.
For instance, if you store data that’s typically 2kb in size, use the following option:
docker exec -it docker_acra-server_1 /acra-poisonrecordmaker --keys_dir=/keys --data_length=2048
Poison records are generated by a special utility – AcraPoisonRecordMaker. To install it, run:
go get github.com/cossacklabs/acra/cmd/acra-poisonrecordmaker
First, please make sure that you have
ACRA_MASTER_KEY stored as an environmental variable (
echo $ACRA_MASTER_KEY should display key). If you haven't generated keys before, read Key generation page. After generating
ACRA_MASTER_KEY, assign it to a variable like this:
export ACRA_MASTER_KEY=$(echo -n "My_Very_Long_Key_Phrase_ge_32_chars" | base64)
Your output will look something like this:
It's a base64-encoded poison record that you should decode and insert into your data in the database as binary data.
NOTE: For AcraPoisonRecordMaker to work, the key folder has to have proper permissions (as set originally by acra-keymaker):
It is best to keep this utility and the corresponding keys on AcraServer.
Poison records are useful signals for controlling the system's behaviour. With their help you can either:
$GOPATH/bin/acra-server --db_host=127.0.0.1 --poison_shutdown_enable
$GOPATH/bin/acra-server --db_host=127.0.0.1 --poison_run_script_file=/path/to/file
$GOPATH/bin/acra-server --db_host=127.0.0.1 --poison_run_script_file=/path/to/file --poison_shutdown_enable
AcraPoisonRecordMaker has an additional parameter
--data_length that will change the size of the generated random data in the poison record. You should use this option to transform the data inside the poison records to resemble your typical data. Ideally, a poison record should look like any other record in your database. And if you store 1k-2k data, you should use this option:
* When naming our special type of data containers (records) created scpecifically for raising an alarm within Acra-powered infrastructure on detection of suspicious behaviour, we were pretty sure we've seen the term "poison records" used elsewhere in the same context before. But as it turned out, we've pioneered this particular database protection tool. Here is a description of what poison records are, what they do, and how to create and use them.