Acra Tutorials

About Acra tutorials

This is a page containing all the materials marked as "Tutorials" for Acra. It was created for the purposes of an easy whole-text search through all the tutorials at once for those who find it convenient. However, it's recommended that you see the Tutorials and How-tos section on the main Acra page or make use of the "Search" form on top of each product page (Themis, Acra, Hermes) on the main Cossack Labs Documentation page.

Tuning Acra for additional features

Acra is designed to provide optimal security model out of the box, as well as to provide a number of ways for controlling (and sometimes programmatically reconfiguring) some of the security and performance properties.

Strategies for increased security

Wholecell vs Injectedcell

  • Injectedcell (--acrastruct_injectedcell_enable CLI parameter) can be used as a means of security through obscurity: you can hide AcraStruct in a large JPEG picture, and store it, thus increasing the complexity of locating the sensitive data.

Zones

  • If you have a lot of resources to run Acra on, or a small number of users, you can map each user to a separate Zone. This will make each user compartmented key-wise.

Strategies for increased performance

Some performance metrics

During the feature freeze of 0.75 and when we were researching insane memory leaks, we did a few performance tests to understand how much performance penalty Acra will impose on the full roundtrip to the app and back. We wrote 10k rows, requested 10k requests:

- read write
without acra 6.263646909 sec 36.397444647 sec
without zone, no encrypted records 21.764239688 sec -
without zone, all encrypted records 34.915005008 sec 70.29645783
with zone, no encrypted records 22.799269264 sec -
with zone, all encrypted records 37.159501001 sec 74.951257645 sec

The goal was to never exceed 10x performance penalty (typical for using interpreted languages with random quality libraries and poor concurrency). Writes are 2x slower, reads are 6 times slower max. It is worth mentioning that compiling Themis while changing the underlying cryptography backend to some more robust implementations of crypto primitives can significantly improve Acra performance.

Wholecell vs Injectedcell

  • Performance-wise, wholecell is much faster than injectedcell because it doesn't require scanning the whole byte stream.
  • If you're using injectedcell mode, you might want to limit the length of your database response - the longer it is, the longer it scans for AcraStruct.

Zones

  • The more Zones and Zone keys you've got, the longer it takes to scan through the database response.

Trying Acra with Docker

You can use containers with Acra. Acra works well with Docker. However, we advise only going the "Acra in Docker containers" route for testing purposes, and NOT in a real-world production environment.

This is why this document is called "Trying Acra with Docker", not "Using Acra with Docker in a Production Setting".

Precautions

Storing keys safely when using Docker is problematic. Docker is immutable and Zones/keys are not. This means that you might want to attach some storage and end up making the keys accessible to attackers. There are multiple ways to solve this problem and it will be addressed in a convenient and secure fashion in the future releases of Acra.

Using Acra in Docker

The following example relies on pre-made config files and pre-made examples. They were prepared for a quick try-out and for product architecture learning purposes. The idea was to show the interactions between Acra components in detail and to simplify the process of first acquaintance with the product. We recommend that you create your own configurations for the production environment, the one strictly dependent on your infrastructure requirements.

Our Docker Compose files were created using v3 compose file format. Please check your docker engine and Docker Compose versions in the docker official compatibility table.

Download Acra

git clone https://github.com/cossacklabs/acra
cd acra

Quick launch!

WARNING! Do not use these configurations to store sensitive data! It is dangerous! They are meant for test-driving purposes only!

All that you need for your first try of Acra is to launch the selected scheme from the docker subdirectory:

docker-compose -f docker/<compose_file_name>.yml up

This will create docker/.acrakeys directory structure, generate all the key pairs, put them into appropriate directories, create DB, add DB user, grant them appropriate privileges and launch all the components.

Now you can connect to (you can see the default DB name and credentials inside the Docker Compose file):

Port Component In docker-compose examples with
9191/tcp AcraServer/AcraConnector API zonemode
9393/tcp AcraServer absent AcraConnector
9494/tcp AcraConnector present AcraConnector
8000/tcp AcraWebconfig present AcraConnector and SecureSession
5432/tcp PostgreSQL PostgreSQL
3306/tcp MySQL MySQL

Normal launch

Description of components

There are several different dockerfiles in docker subdirectory: * acra-authmanager.dockerfile - resulting image with AcraAuthmanager tool * acra-connector.dockerfile - resulting image with AcraConnector * acra-server.dockerfile - resulting image with AcraServer * acra-keymaker.dockerfile - resulting image with AcraKeymaker tool * acra-webconfig.dockerfile - resulting image with AcraWebconfig component

  • acra-build.dockerfile - intermediate image for compiling all the Acra components;

  • mysql-nossl.dockerfile - MySQL server container with disabled SSL

  • mysql-ssl.dockerfile - MySQL server container with example SSL certificates (located at ssl/mysql directory)
  • postgresql-ssl.dockerfile - Postgresql server container with example SSL certificates (located at ssl/postgresql directory)

All the images are already built and uploaded to the Docker Hub Cossack Labs repository, so you can use them in a traditional manner:

docker run <options> cossacklabs/<component> <arguments>

You do not need to do it, but you may want to build all the images from current sources manually. To do that, type:

make docker

After that step, you'll get the described above pre-built images (intermediate acra-build image will be wiped out after the build is complete).

All docker images have tags. When we build them, we set appropriate tags for each image:

  • sliding tags:

    • stable and latest - stable branch, recommended, default;
    • master and current - master branch of GitHub repository.
  • fixed tags:

    • <full_commit_tag> - specify the exact commit in the repository;
    • <version> - choose version tag.

An image usually has two (commit, version) or four (+ branch, latest/current) tags.

Compose files

We wanted you to be able to easily try the most useful schemes that we prepared as Docker Compose files in the docker subdirectory. The name of each Docker Compose file describes its components and their interconnections in a simple form. For example: docker-compose.pgsql-nossl-server-ssession-proxy.yml is a scheme with Postgresql DB, AcraServer, and AcraConnector, connected to AcraServer through the Secure Session link.

The examples contain references to acra-keymaker and acra-authmanager containers inside. They are used for creation and distribution of the necessary keys. They were included for simplification of the test launch and should not be used in production schemes (where the keys should be generated manually and deployed to an appropriate host according to the security rules of your infrastructure).

Check out the docker/README for examples and descriptions of compose files.

You're most likely to want to set some variables before launch.

Please write ACRA_MASTER_KEY to environmental variable, or check KeyManagement page for more details:

export ACRA_MASTER_KEY=$(echo -n "My_Very_Long_Key_Phrase_ge_32_chars" | base64)

Define the Client ID:

export ACRA_CLIENT_ID="MyClientID"

Optionally you may specify a docker image tag, which can be one of the following:

  • stable or latest - stable branch, recommended, default;
  • master or current - master branch of the GitHub repository;
  • <full_commit_tag> - specify the exact commit in repository;
  • <version> - choose version tag.
# Examples:
# branch
export ACRA_DOCKER_IMAGE_TAG="master"
# commit tag
export ACRA_DOCKER_IMAGE_TAG="2d2348f440aa0c20b20cd23c49dd34eb0d42d6a5"
# version
export ACRA_DOCKER_IMAGE_TAG="0.76-33-g8b16bc2"

Please define the database name and user credentials:

# for Postgresql
export POSTGRES_DB="<db_name>"
export POSTGRES_USER="<user_name>"
export POSTGRES_PASSWORD="<user_password>"

# for MySQL
export MYSQL_ONETIME_PASSWORD="<mysql_onetime_password>"
export MYSQL_ROOT_PASSWORD="<mysql_root_password>"
export MYSQL_DATABASE="<db_name>"
export MYSQL_USER="<user_name>"
export MYSQL_PASSWORD="<user_password>"

For access to AcraWebConfig HTTP interface, you can define:

export ACRA_HTTPAUTH_USER=<http_auth_user>
export ACRA_HTTPAUTH_PASSWORD=<http_auth_password>

Now you can run docker-compose:

    docker-compose -f docker/<compose_file_name> up

And connect to ports described above.

Example application

In the following examples, we will assume that the schemes are running and all the environment variables are set as described in the code block below. For your convenience, we recommend that you perform the following actions in two different shell windows: run the Docker in one and the examples in another.

Please define the same set of environment variables in both shell windows before proceeding to the next steps:

export ACRA_MASTER_KEY=$(echo -n "t6VS72b8nRTzGdLudfNeDSLhuC67vAsR" | base64)
export ACRA_CLIENT_ID="test"
export POSTGRES_DB="acra"
export POSTGRES_USER="dbuser"
export POSTGRES_PASSWORD="dbpassword"
export ACRA_CLIENT_ID="acraclient"

Install the dependencies for the example application:

(shell window #2)

Before running examples/python/*.py, please perform these initial steps:

python3 -m venv acra_env
source acra_env/bin/activate
pip install -U pip
pip install -r examples/python/requirements.txt

To Use Acra without Zones:

Launch docker-compose file (shell window #1)

docker-compose -f docker/docker-compose.pgsql-nossl-server-ssession-proxy.yml up

Print data in the database (shell window #2)

Depending on your system configurations, you may be required to change the owner of the docker/.acrakeys structure, which is created by Docker daemon, to have access to it. In this case, use:

sudo chown $(whoami) -R docker/.acrakeys
python examples/python/example_without_zone.py \

--public_key=docker/.acrakeys/acra-writer/${ACRA_CLIENT_ID}_storage.pub \
    --db_user=${POSTGRES_USER} \
    --db_password=${POSTGRES_PASSWORD} \
    --host=127.0.0.1 \
    --port=5432 \
    --print

You should see nothing.

But let's add some data now! (shell window #2)

python examples/python/example_without_zone.py \

--public_key=docker/.acrakeys/acra-writer/${ACRA_CLIENT_ID}_storage.pub \
    --db_user=${POSTGRES_USER} \
    --db_password=${POSTGRES_PASSWORD} \
    --host=127.0.0.1 \
    --port=5432 \
    --data="data1"

python examples/python/example_without_zone.py \

--public_key=docker/.acrakeys/acra-writer/${ACRA_CLIENT_ID}_storage.pub \
    --db_user=${POSTGRES_USER} \
    --db_password=${POSTGRES_PASSWORD} \
    --host=127.0.0.1 \
    --port=5432 \
    --data="data2"

We've added data, let's print it:

python examples/python/example_without_zone.py \

--public_key=docker/.acrakeys/acra-writer/${ACRA_CLIENT_ID}_storage.pub \
    --db_user=${POSTGRES_USER} \
    --db_password=${POSTGRES_PASSWORD} \
    --host=127.0.0.1 \
    --port=5432 \
    --print

You will see some incomrehensible string of characters, something like b'""""""""UEC2\x00\x00\x00-d\x18e\xbc\x03.\x9fi\xecc\xbb\xfe\xa0.... This is what the data looks like in an encrypted form.

To make sure that the data is really encrypted, you can connect to the database directly and make a pure select in the psql terminal (you will be asked for password, which you set for variable POSTGRES_PASSWORD):

echo "select * from test_example_without_zone" | \
    psql -h127.0.0.1 -p5432 -U${POSTGRES_USER} acra

Now it is encrypted data. Let's read the data through AcraConnector by specifying port 9494 instead of 5432:

python examples/python/example_without_zone.py \

--public_key=docker/.acrakeys/acra-writer/${ACRA_CLIENT_ID}_storage.pub \
    --db_user=${POSTGRES_USER} \
    --db_password=${POSTGRES_PASSWORD} \
    --host=127.0.0.1 \
    --port=9494 \
    --print

Now you will see the decrypted data via Acra in the data column, i.e. b'data1'.

Using Acra in Docker with Zones

WARNING: Shutdown the previous containers and delete docker/.acrakeys first!

Use:
(shell window #1)

docker-compose -f docker/docker-compose.pgsql-nossl-server-ssession-proxy.yml down
rm -rf docker/.acrakeys

Launch docker-compose file (shell window #1)

docker-compose -f docker/docker-compose.pgsql-nossl-server-ssession-proxy_zonemode.yml up

Print data in database: (shell window #2) Depending on your system configurations, you may be required to change the owner of the docker/.acrakeys structure, which is created by the Docker daemon, to have access to it. In this case, use:

sudo chown $(whoami) -R docker/.acrakeys
python examples/python/example_with_zone.py \
    --db_user=${POSTGRES_USER} \
    --db_password=${POSTGRES_PASSWORD} \
    --host=127.0.0.1 \
    --port=5432 \
    --print

Nothing should be printed. But let's add some data using a Python script example_with_zone.py:

python examples/python/example_with_zone.py \
    --db_user=${POSTGRES_USER} \
    --db_password=${POSTGRES_PASSWORD} \
    --host=127.0.0.1 \
    --port=5432 \
    --data="data1"

The script will print:

data: data1
zone: DDDDDDDDmufclpqHJfnTDJZW
saved with zone: DDDDDDDDmufclpqHJfnTDJZW

This script made a request to HTTP API of AcraServer through AcraConnector to add a new Zone and used the response (Zone Id and Zone public key) for encrypting the data. zone: DDDDDDDDmufclpqHJfnTDJZW is the Zone Id that should be used for fetching the decrypted data via AcraServer.

Let's print the data now: (shell window #2)

python examples/python/example_with_zone.py \
    --db_user=${POSTGRES_USER} \
    --db_password=${POSTGRES_PASSWORD} \
    --host=127.0.0.1 \
    --port=5432 \
    --print

We should see something like:

id  - zone - data -   raw_data
92075 - b'without zone' - b'""""""""UEC2\x00\x00\x00-E\xf90\x93\x031]\xb8\xd9\x04\xf3\xc1R\x95U1sd\xcd\xe6\xca\xef4\x14K.\xd3\xa7\xbb\x8d\x80\x18\x84v4o\x1d \'\x04&T\x00\x00\x00\x00\x01\x01@\x0c\x00\x00\x00\x10\x00\x00\x00 \x00\x00\x00Ri\xf0,\x91\xe8\xb3Y\x861\xaend\x10\x89t\xe3\xa6\x8e\xe3\xbf8+."\x17\xd2s\xd3\xc4m\xa5\xbf+\xce\x85G9\xca\x15\x01X\xd3\x87;$2\xed\xd5\xca7\xec!\x07\xcb\xee\xd9\xd7\xd8Y1\x00\x00\x00\x00\x00\x00\x00\x00\x01\x01@\x0c\x00\x00\x00\x10\x00\x00\x00\x05\x00\x00\x00\x9f\xd0\x1f\x7fkZ\xaah\xb9\xe2s\x15!#wj2(\x0b[o\r\x01\xcf\xacC\xdbt\x86\xae\xd4\xb2\xb8' - (zone: DDDDDDDDmufclpqHJfnTDJZW) - data1

Here b'without zone' is a hardcoded string in example script for demonstrating the usage without Zones.

Let's try to print what's going on with AcraProxy on port 9494: (shell window #2)

python examples/python/example_with_zone.py \
    --db_user=${POSTGRES_USER} \
    --db_password=${POSTGRES_PASSWORD} \
    --host=127.0.0.1 \
    --port=9494 \
    --print

We will see that nothing happened because AcraServer now fails to match Zone Id and so it doesn't decrypt the data. The only logging that happens now happens on AcraServer. This needs to be done to make sure that the attackers are not able to figure out what exactly is wrong with their attempts to perform decryption.

Let's try print for using AcraProxy port 9494 and passing the correct Zone ID (shell window #2)

python examples/python/example_with_zone.py \
    --db_user=${POSTGRES_USER} \
    --db_password=${POSTGRES_PASSWORD} \
    --host=127.0.0.1 \
    --port=9494 \
    --print \
    --zone_id=DDDDDDDDmufclpqHJfnTDJZW

Note: Use your own generated Zone Id here, it should be different from the one in the example

Now we can see the decrypted data:

use zone_id:  DDDDDDDDmufclpqHJfnTDJZW
id  - zone - data -   raw_data
92075 - b'DDDDDDDDmufclpqHJfnTDJZW' - data1 - (zone: DDDDDDDDmufclpqHJfnTDJZW) - data1

Let's see how the data is stored in the database (you will be asked for the password, which you set for the variable POSTGRES_PASSWORD):

echo "select * from test_example_with_zone" | \
    psql -h127.0.0.1 -p5432 -U${POSTGRES_USER} acra

Now, let's try print for the data with incorrect Zone Id through AcraConnector:

python examples/python/example_with_zone.py \
    --db_user=${POSTGRES_USER} \
    --db_password=${POSTGRES_PASSWORD} \
    --host=127.0.0.1 \
    --port=9494 \
    --print \
    --zone_id=DDDDDDDDINCORRECTZONEIDW

You will see that AcraServer couldn't decrypt and passed the data as is.

Using Acra to Protect Your Django App

Note: This tutorial is an extensive step-by-step guide for those who have never used Themis and Acra before. There is also a much shorter version for the experienced Acra users. If it’s your very first encounter with Acra, keep reading.

Intro

Acra is a database security suite, which protects you against data leaks and many typical application threats through strong selective encryption and intrusion detection capabilities.

It is based on our Themis cryptographic library with extreme security and usability for developers in mind (you can read more about Themis' cryptography in Acra here.

Acra is most useful for:

  • Selective protection of sensitive data,
  • Autosharded databases,
  • Microservices,
  • Situations with severe time constraints (aka "pressing deadlines" ;).

Acra is developer-oriented, with convenient infrastructure, and easily provides strong security and full granular control over your data.

The main basic components of Acra are:

  • AcraServer - a separate daemon that runs in an isolated environment (separate virtual machine or physical server), which is responsible for holding all the secrets required to decrypt the data and for actually decrypting this data.
  • AcraWriter - a client-side library, which integrates into the app flow either through ORM or directly, and provides the means to encrypt the sensitive data via generating AcraStructs.
  • AcraConnector - a client-side daemon that runs under a separate user / in a separate container, and which acts as a database listener that redirects all the queries to AcraServer and feeds the results back to the app.

This tutorial guides you through a typical process of integrating Acra into a Python web app. More specifically - into an app running on Django framework using a popular example many Django users start their development journey with - djangoproject.com repository. We’ll integrate Acra into Django Project to provide cryptographic protection of blog posts.

Security model

Acra provides selective encryption and only protects the records you want to protect.

With AcraWriter, the records to be encrypted are wrapped in a function that outputs an AcraStruct (cryptographic container decryptable by AcraServer). AcraStruct is then stored in a database.

In Acra’s threat model, we assume that anything but AcraServer can be compromised and that any piece of data can leak outside. For Acra to stay secure, only AcraServer must stay secure. However, if AcraServer is compromised, the whole implementation of Acra will make no sense.

With Acra we strive to provide 2 main programmatic security guarantees:

  • G1: Even if all the other parts of the system are compromised, as long as AcraServer is secure, the attacker won’t collect enough data for decryption of the protected materials (database entries in our case).

  • G2: If the attacker alters the app’s behaviour in such a way that makes it request all the protected (encrypted) data from the database, AcraServer detects it and reacts accordingly by triggering pre-set alarms and panic blocks. This is currently carried out with the help of poison records in the database, which would never have been called up - except for an event of a hack/breach. In the future, more intrusion detection features besides poison records are planned.

If it is explicitly stated that the output for Zone Id must precede the AcraStruct, Acra Server will search for certain strings called Zone Ids (“Zones”) when analysing the database output stream. Zones let Acra know that within this record a private key corresponding to the Zone Id should be used for the actual decryption of AcraStructs.

Zones are the way to cryptographically compartmentalise records in an already-encrypted environment. They rely on different private keys on the server side. When using Zone keys, you get an additional 3rd guarantee:

  • G3: If the attacker manages to compromise the system and modify the app to extract all the records protected by Zone keys, he/she will have to reverse-engineer both the storage model and the Zone identification to be able to request all of them correctly.

Deploying infrastructure

In a perfect world, you’d be running different elements of Acra, as well as your database, on 3 separate machines - one for PostgreSQL, one for AcraServer, and one for AcraConnector + AcraWriter + your Django web app. This implies an immediate introduction of Acra into a real production setting, which we realise is far from a realistic course of events (at least on your very first try of Acra). So this tutorial is more focused on the things you can hands-on try out and tinker with on just 2 or even 1 machine through the creation of different users and containers (i.e. Docker, a test-only implementation of which for Acra is described at the end of this tutorial).

In this detailed architectural scheme we see how components of Acra, application, and database relate and interact with each other:

Put simply, the application talks to AcraConnector. AcraConnector pretends to be a database listener that uses standard PostgreSQL protocol and send the request to AcraServer using Secure Session (socket protection protocol). AcraServer sends a request to the database using the regular PostgreSQL protocol and receives an answer. If AcraServer detects the presence of AcraStruct while parsing the answer, it attempts to decrypt it and replace AcraStruct with a plaintext result in the answer (if decryption is unsuccessful, AcraServer will forward the answer as is). AcraServer returns the data to AcraConnector which returns it to the application. If Zones are used, AcraServer will use a corresponding private key to decrypt the next detected AcraStruct upon detecting ZoneId. AcraServer will ignore the AcraStruct if no Zone Id is detected before the AcraStruct.

All the dependencies mentioned in this tutorial need to be installed on all the machines/containers running Acra (or for both separate users of AcraServer and AcraConnector) unless it’s explicitly specified that some Acra components should only be installed for a separate user/machine running AcraServer or AcraConnector. All the commands starting with 'go' are meant to be executed from 'acra' folder (the folder with the repository code) on any machine.

In this tutorial, we assume that you have a fully operational PostgreSQL (as Acra transfers and receives data “as is” to and from PostgreSQL database and then processes it - parses the messages - according to the PostgreSQL protocol) and operate on Linux machines (with Python environment and Django framework installed). It’s also crucial that you have libssl-dev installed with libcrypto.so in $PATH before proceeding.

Note that before PostgreSQL 9, only escape_bytea mode was present. Now the hex mode is used by default. If your PostgreSQL uses escape_bytea, set this parameter during the installation process using the following command: $GOPATH/bin/acra-server --db_host=127.0.0.1 --pgsql_escape_bytea

This might seem daunting, but in reality, Acra is easy to install. Let’s go!

Step 1. Install GoLang dependencies:

sudo apt-get install git golang libssl-dev make build-essential

and set your $GOPATH to the place where you will store the code.

Step 2. Install Themis

To install Themis, use:

    git clone https://github.com/cossacklabs/themis.git
    cd themis
    make
    sudo make install

Step 3. Build keymaker

    go get github.com/cossacklabs/acra/cmd/acra-keymaker

It’s preferable to build the key maker and generate the keys on the machine that’s going to host AcraServer. This is the secure way to deal with the keys, as according to Acra’s threat model, we expect that any data stored outside of AcraServer can be compromised. Which is why we strongly advise against using all the components of Acra on a single machine (i.e. with the help of Docker containers) for anything more serious than testing and tinkering.

Step 4. Generate the transport, storage keys, and master key

Generate master key for AcraServer:

$GOPATH/bin/acra-keymaker --generate_master_key=master.key    

Export the key to the environment variable in base64 format:

export ACRA_MASTER_KEY=`cat master.key | base64`

Generate keys into ./.acrakeys directory structure:

/bin/bash $GOPATH/src/github.com/cossacklabs/acra/scripts/generate-keys.sh \
    --keys_dir ./.acrakeys \
    --client_id yourID
./.acrakeys/yourID_server
./.acrakeys/yourID_server.pub
./.acrakeys/yourID_storage
./.acrakeys/yourID_storage.pub

Here yourID is a placeholder for the Id name of your choice. You’re allowed to use 5-256 symbols (inclusively) that include Latin symbols, numbers, “-” (minus symbol), “_” (underscore), and “ ” (space).

The generator will generate and place the keys into the .acrakeys directory (you can change this with --output argument).

For a few minutes, let the keys rest where they are - they will be necessary after you have installed AcraServer, AcraConnector, and AcraWriter (please see Key management in the Themis documentation).

AcraServer

Yet another reminder that AcraServer needs to be installed on a separate computer/virtual machine/container and with SSL turned off in PostgreSQL.

Step 5. Build AcraServer

The installation starts with adding a new user for AcraServer:

    sudo useradd -m acra-server
    sudo su acra-server
    cd ~/
    export GOPATH=`pwd`

Now, build AcraServer:

    go get github.com/cossacklabs/acra/cmd/acra-server

AcraServer should have AcraConnector's public transport key, and Acra Server's public transport key must be given to AcraConnector.This is necessary for accepting connections via Secure Session from clients.

Put .acrakeys/yourID.pub + .acrakeys/yourID_server + .acrakeys/yourID_storage into AcraServer’s key folder with proper permissions (folder 700, private keys 600 - permissions are assigned during the generation process, and permissions for AcraConnector and AcraWriter keys are the same).

Before launching AcraServer, you need to perform the following first (the keys for this were generated in Step 4.):

/bin/bash $GOPATH/src/github.com/cossacklabs/acra/scripts/generate-keys.sh \
    --keys_dir ./.acrakeys \
    --client_id yourID

Launch AcraServer with:

    $GOPATH/bin/acra-server --db_host=127.0.0.1

The command above can be complemented with --db_port=5432 -v to adjust the listener port and to add logs quickly. There are more parameters available, and you can find them in the documentation page for Acra, but for the present goal - namely, for an easy integration of Acra into a Django app, the default parameters will do.

You can also run with the options from config. Copy the example config:

    $REPO_DIR/configs/acra-server.yaml

or from

$GOPATH/src/github.com/cossacklabs/acra/configs/acra-server.yaml

Or generate the config yourself:

    $GOPATH/bin/acra-server --dump_config > acra-server.yaml

and run:

    $GOPATH/bin/acra-server --config_file=acra-server.yaml

Proper logging is set with:

    $GOPATH/bin/acra-server --db_host=127.0.0.1 -v

You’ll also need an explicit server_id that is used as an identifier for Secure Session between AcraConnector and AcraServer:

    $GOPATH/bin/acra-server --db_host=127.0.0.1 --securesession_id=server_id_name_of_your_choice

If you changed the server Id to some server_id_name_of_your_choice, specify this Id for AcraConnector using:

    $GOPATH/bin/acra-connector --acraserver_securesession_id=server_id_name_of_your_choice

By default, AcraServer listens on port 9393, but you can set a custom port (just don’t forget to follow the instructions on specifying a custom port for AcraConnector further in this tutorial) if there is a need:

    $GOPATH/bin/acra-server --db_host=127.0.0.1 --incoming_connection_port=3000

Here 3000 is the customisable part.

Step 6. Build AcraConnector

AcraConnector should run under a separate user on the same machine as your Django web app (or in a separate container for testing purposes). All the database requests need to be directed to AcraConnector, which then pretends to be a database listener (a local proxy) and relays all the requests to AcraServer (on a separate machine/in a separate container), listens back and returns the responses to the app.

Install AcraConnector:

    go get github.com/cossacklabs/acra/cmd/acra-connector

Put .acrakeys/yourID + .acrakeys/yourID_server.pub to AcraConnector’s key folder (.acrakeys or anything you chose in --keys_output_dir). AcraConnector’s own public key should already have been given to AcraServer to establish Secure Session connection. Pre-shared public keys enforce maximum secrecy and easy-to-manage authentication, and - as you can see - require minimal intervention on your side or into your code for successful implementation.

Upon launch with the default settings, AcraConnector will start listening on port 9494 and will attempt to connect to AcraServer on port 9393. To initialise, use:

    $GOPATH/bin/acra-connector --acraserver_connection_host=127.0.0.1 --client_id=yourID -v

Let’s change the port AcraConnector is listening on:

    $GOPATH/bin/acra-connector --client_id=client_name --acraserver_connection_host=acra.server.host --acraserver_connection_port=5432

Now AcraConnector will be listening on port 5432 (your custom port). This is important if you want the launch of AcraConnector to be transparent for the app (if your app connected to PostgreSQL on 5432).

You can also launch AcraConnector with the options from example config, just copy it from:

    $REPO_DIR/configs/acra-connector.yaml

or from:

    $GOPATH/src/github.com/cossacklabs/acra/configs/acra-connector.yaml

If you want, you can generate an example config yourself. Use:

    $GOPATH/bin/acra-connector --dump_config > acra-connector.yaml

And run:

    $GOPATH/bin/acra-connector --config_file=acra-connector.yaml

These instructions should be enough to get you up and running with AcraConnector. Now you can proceed to the actual integration of Acra into a Django web app. For more advanced ways of setting up and launching AcraConnector, you can read the dedicated documentation section.

Integration

Step 7. Integrating Acra with Django

Since in our example we’ll be integrating Acra into DjangoProject to protect blog posts, you need to clone DjangoProject’s repository (to the same machine/container that is running AcraConnector) with:

    git clone https://github.com/django/djangoproject.com.git

AcraWriter comes into play next. It is basically Themis that is generating AcraStructs with keys you've made available to AcraWriter. You can encrypt sensitive data by generating AcraStructs with AcraWriter anywhere in your app. AcraWriter can be used whenever you need to encrypt sensitive records. Install AcraWriter:

    pip install acrawriter     

AcraWriter should have AcraServer's public key. This is necessary for encryption of AcraStructs in such a way that would only be read by AcraServer.

And AcraServer’s public key(s) to the public storage keys need to be given to AcraWriter. This is used for decryption of AcraStructs that AcraWriter has produced. Put .acrakeys/yourID_storage.pub into any folder where your AcraWriter's function can access it.

To continue with the correct key distribution for our purposes, you need to save AcraServer’s public key to settings as ACRA_SERVER_PUBLIC_KEY through executing the following:

# djangoproject/settings/common.py
import json
import os
from pathlib import Path
from base64 import b64decode
.
.
.
ACRA_SERVER_PUBLIC_KEY = b64decode(SECRETS.get('acra_server_public_key'))

This AcraServer public key needs to be copied and pasted into a conf/secrets.json created for this purpose in a form of a base64 string:

{
    . . .
    "acra_server_public_key": "VUVDMgAAAC1w3M1uArNP+AWNhmOi6+bR6SXadlPbAh3XFnBuOnLziPeHn70T"
    . . .
}

Next, use model fields from acrawriter.django module:

# blog/models.py
. . .
import acrawriter.django
. . .

class Entry(models.Model):
    . . .
    headline = acrawriter.django.CharField(max_length=200)
    summary = acrawriter.django.TextField()
    summary_html = acrawriter.django.TextField()
    body = acrawriter.django.TextField()
    body_html = acrawriter.django.TextField()
    author = acrawriter.django.CharField(max_length=100)
    . . .

Continued:

# members/models.py
. . .
import acrawriter.django
. . . 


class IndividualMember(models.Model):
    email = acrawriter.django.EmailField(unique=True)
    contact_email = acrawriter.django.EmailField()
    billing_email = acrawriter.django.EmailField(blank=True, help_text='If different from contact email.',)
    . . .

Run migrations to bring it all together:

    python manage.py makemigrations
    python manage.py migrate

If you’ve been successful with implementing all the previous steps, your Django app should now be connecting to your local AcraConnector. To proceed with integration, run AcraConnector on port 5432 and now change db_host/trac_db_host in your conf/secrets.conf to 127.0.0.1 like this:

{ 
  "secret_key": "xyz",
  "db_host": "127.0.0.1",
  "trac_db_host": "127.0.0.1",
  "acra_server_public_key": "VUVDMgAAAC1w3M1uArNP+AWNhmOi6+bR6SXadlPbAh3XFnBuOnLziPeHn70T"
}

The final step in the process of integration Acra with Django Project is adding AcraWriter to the requirements/common.txt:

. . .
stripe==1.43.0
Sphinx==1.4.9
acrawriter==1.0.0

This completes the process of integrating a fully operational Acra into your Django web app in a real-life setup that uses different machines/users.

Result

To test your Acra setup:

  • Connect AcraConnector to AcraServer, send a regular request to your database through AcraConnector. If you see the answer, AcraConnector and AcraWriter are able to connect and forward signals back and forth. It means that the network and the keys are fine.

  • Upon integrating AcraWriter into your code, try generating an AcraStruct from some payload. If you succeed in running AcraWriter code, Themis library is installed properly and the keys are located in the expected places.

  • Write a row with AcraStruct into the database, either directly or through AcraConnector. Request this row through AcraConnector. If you see the decrypted payload in the response, the scheme works properly.

To test the work of Acra on your DjangoProject web app, launch it locally, and go to 127.0.0.1:8000/admin/. Add a new Entry post or a new IndividualMember and make sure that everything is displayed correctly in the list of objects. Then connect to the database and see for yourself that the data from the table has turned into unintelligible encrypted text - use:

    psql -h127.0.0.1 -p 5432 -U test --dbname=djangoproject -c "select * from blog_entry;" 

Note: AcraConnector must listen on 5432.

If the database returns all the data it contains in encrypted form, everything is working properly and you’ve successfully integrated Acra into your Django app!

If You Want to Try Acra in Containers First

We’ve made some special effort to make Acra work with Docker. However, please remember that using Acra with containers is violating its basic security guarantee. Docker is immutable, and zones/keys are not. This means you might want to attach some storage and end up leaving keys accessible to attackers. So use Acra with Docker for testing purposes only.

To simply test the waters of using Acra, you can use pre-made config files and examples below - they can also serve as a reference for integrating Acra with a Django app.

You’ll need to download Acra, just like it was described above:

    git clone https://github.com/cossacklabs/acra
    cd acra

And start AcraServer, AcraConnector, and PostgreSQL in separate Docker containers:

    docker-compose -f docker/docker-compose.pgsql-nossl-server-ssession-connector.yml up -d
  • -f use specified docker-compose*.yml file
  • -d run in background

After executing this command, you will have a running PostgreSQL with test:test user:password with forwarded 5432 port, AcraServer with keys that you generated above, and AcraConnector that forwards port 9494.

Note: Don’t forget to stop your local PostgreSQL if you run it before launching the Docker with PostgreSQL in a container or you’ll get an error from 2 instances of an application trying to listen on the same port.

By default, Docker will create 3 containers with the following names: docker_acra-server_1, docker_acra-connector_1, and docker_pg_1.

Install the example application dependencies:

virtualenv --python=python3 acra_env
source acra_env/bin/activate
pip install -r examples/python/requirements.txt 

Create a database:

    echo "create database acra with encoding utf8;" | psql -h 127.0.0.1 -p 5432 -U test

You’ll be asked to input the password for PostgreSQL (test) and you’re ready to proceed.

Using Acra in Docker Without Implementing Zones

Let’s print the contents of the database:

    python examples/python/example_without_zone.py --public_key=.acrakeys/client_storage.pub --db_user=test --db_password=test --host=127.0.0.1 --port=5432 --print

You should see nothing because there is no data in the database. But let’s add something:

python examples/python/example_without_zone.py --public_key=.acrakeys/client_storage.pub --db_user=test --db_password=test --host=127.0.0.1 --port=5432 --data="data1"

python examples/python/example_without_zone.py --public_key=.acrakeys/client_storage.pub --db_user=test --db_password=test --host=127.0.0.1 --port=5432 --data="data2"

And let’s try printing now:

python examples/python/example_without_zone.py --public_key=.acrakeys/client_storage.pub --db_user=test --db_password=test --host=127.0.0.1 --port=5432 --print

You will see an unreadable mishmash of numbers and letters - something like this:

    b'""""""""UEC2\x00\x00\x00-d\x18e\xbc\x03.\x9fi\xecc\xbb\xfe\xa0...    

To make sure that the data is really encrypted, you can connect directly to the database and make pure select in the PostgreSQL terminal:

 echo "select * from test_example_without_zone" | psql -h127.0.0.1 -p5432 -Utest acra

Now the data is encrypted and you know it. Let's read the data through AcraConnector by specifying port 9494 instead of 5432:

    python examples/python/example_without_zone.py --public_key=.acrakeys/client_storage.pub --db_user=test --db_password=test --host=127.0.0.1 --port=9494 --print

You will see the decrypted data via Acra in the data column, i.e. b'data1'. Acra is working!

Using Acra in Docker with Zones

Shut down the previous active Docker containers before proceeding with this method! Use:

    docker-compose -f docker/docker-compose.pgsql-nossl-server-ssession-connector.yml down

Use this .yml file to start AcraServer that supports Zones:

    docker-compose -f docker/docker-compose.pgsql-nossl-server-ssession-connector_zonemode.yml up -d

This command is similar to the command used for starting AcraServer without the support of Zones, but now AcraServer will also forward port 9191, which should be used for requests to HTTP API (adding Zones).

Create the database:

    echo "create database acra with encoding utf8;" | psql -h 127.0.0.1 -p 5432 -U test

Print the data contained in the database:

    python examples/python/example_with_zone.py --db_user=test --db_password=test --host=127.0.0.1 --port=5432 --print

Just like in the example above (using Docker with Acra without Zones), the command should print nothing, but now let’s add some data by running a Python script example_with_zone.py for that:

   python examples/python/example_with_zone.py --db_user=test --db_password=test --host=127.0.0.1 --port=5432 --data="data1"

The script will print:

data: data1
zone: DDDDDDDDmufclpqHJfnTDJZW
saved with zone: DDDDDDDDmufclpqHJfnTDJZW

It made a request to HTTP API of AcraServer through AcraConnector to add a new Zone and used the response (Zone Id and Zone public key) for encrypting the data. zone: DDDDDDDDmufclpqHJfnTDJZW is the Zone Id that should be used for fetching decrypted data via AcraServer.

If we print the data now, we will see something like this:

python examples/python/example_with_zone.py --db_user=test --db_password=test --host=127.0.0.1 --port=5432 --print
id  - zone - data -   raw_data
92075 - b'without zone' - b'""""""""UEC2\x00\x00\x00-E\xf90\x93\x031]\xb8\xd9\x04\xf3\xc1R\x95U1sd\xcd\xe6\xca\xef4\x14K.\xd3\xa7\xbb\x8d\x80\x18\x84v4o\x1d \'\x04&T\x00\x00\x00\x00\x01\x01@\x0c\x00\x00\x00\x10\x00\x00\x00 \x00\x00\x00Ri\xf0,\x91\xe8\xb3Y\x861\xaend\x10\x89t\xe3\xa6\x8e\xe3\xbf8+."\x17\xd2s\xd3\xc4m\xa5\xbf+\xce\x85G9\xca\x15\x01X\xd3\x87;$2\xed\xd5\xca7\xec!\x07\xcb\xee\xd9\xd7\xd8Y1\x00\x00\x00\x00\x00\x00\x00\x00\x01\x01@\x0c\x00\x00\x00\x10\x00\x00\x00\x05\x00\x00\x00\x9f\xd0\x1f\x7fkZ\xaah\xb9\xe2s\x15\xwj2\x0b[o\r\x01\xcf\xacC\xdbt\x86\xae\xd4\xb2\xb8' - (zone: DDDDDDDDmufclpqHJfnTDJZW) - data1

Here b'without zone' is a hardcoded string in example script for demonstrating usage without Zones.

Now let’s try to print what’s happening on port 9494 (used by AcraConnector):

    python examples/python/example_with_zone.py --db_user=test --db_password=test --host=127.0.0.1 --port=9494 --print

Nothing will happen because now AcraServer fails to match Zone Id and it doesn’t decrypt the data. All the logging happens on AcraServer only. This needs to be done to make sure that attackers are unable to figure out what exactly is wrong with their attempts at performing decryption.

With a correct Zone Id and AcraConnector listening on port 9494 everything will work correctly (use your own Zone ID, it must be different from the one provided in the example below):

    python examples/python/example_with_zone.py --db_user=test --db_password=test --host=127.0.0.1 --port=9494 --print --zone_id=DDDDDDDDmufclpqHJfnTDJZW

Now we’ll be able to see the decrypted data:

use zone_id:  DDDDDDDDmufclpqHJfnTDJZW
id  - zone - data -   raw_data
92075 - b'DDDDDDDDmufclpqHJfnTDJZW' - data1 - (zone: DDDDDDDDmufclpqHJfnTDJZW) - data1

Let’s see how the data is stored in the database:

    echo "select * from test_example_with_zone" | psql -h127.0.0.1 -p5432 -Utest acra

And if we try to print the data with incorrect Zone Id through AcraConnector, we’ll see that AcraServer didn’t decrypt it and passed the data as is:

    python examples/python/example_with_zone.py --db_user=test --db_password=test --host=127.0.0.1 --port=9494 --print --zone_id=DDDDDDDDINCORRECTZONEIDW

Congratulations! Acra is now working with Zones!

Conclusion

As you can see, establishing cryptographic protection for the data in your web app with Acra is a very straightforward and simple process. We hope that this tutorial was fun and informative and that you will be using Acra in the future. If you only tried the Docker-based examples, try running Acra in a real world setup - it’s just as convenient.

You can also check out a similar Acra tutorial for RubyGems.

Integrating Acra with DjangoProject - short version

This tutorial shows a typical process for integrating Acra into a Python web app. More specifically - an app running on Django framework. It is based on the popular example many Django users start their development journey with - djangoproject.com repository.

We will be integrating AcraWriter to protect blog posts.

This tutorial assumes that you have both AcraServer and PostgreSQL up and running.

You may browse the modified repository here.

Step 1. Clone repo

git clone https://github.com/django/djangoproject.com.git

Step 2. Install AcraWriter

pip install acrawriter

Step 3. Save AcraServer public key to settings

Save AcraServer public key to settings as ACRA_SERVER_PUBLIC_KEY:

# djangoproject/settings/common.py
import json
import os
from base64 import b64decode
.
.
.
ACRA_SERVER_PUBLIC_KEY = b64decode(SECRETS.get('acra_server_public_key'))

Step 4. Create conf/secrets.json and paste AcraServer public key as base64 string

{
    . . .
    "acra_server_public_key": "VUVDMgAAAC1w3M1uArNP+AWNhmOi6+bR6SXadlPbAh3XFnBuOnLziPeHn70T"
    . . .
}

Step 5. Use model fields from acrawriter.django module

# blog/models.py
. . .
import acrawriter.django
. . .

class Entry(models.Model):
    . . .
    headline = acrawriter.django.CharField(max_length=200)
    summary = acrawriter.django.TextField()
    summary_html = acrawriter.django.TextField()
    body = acrawriter.django.TextField()
    body_html = acrawriter.django.TextField()
    author = acrawriter.django.CharField(max_length=100)
    . . .
# members/models.py
. . .
import acrawriter.django
. . . 


class IndividualMember(models.Model):
    email = acrawriter.django.EmailField(unique=True)
    contact_email = acrawriter.django.EmailField()
    billing_email = acrawriter.django.EmailField(blank=True, help_text='If different from contact email.',)
    . . .

Step 6. Run migrations

python manage.py makemigrations
python manage.py migrate

Update database connection settings

Now your app should connect to local AcraConnector. Run AcraConnector on the same port as before and change db_host/trac_db_host in your conf/secrets.conf to 127.0.0.1

{ 
  "secret_key": "xyz",
  "db_host": "127.0.0.1",
  "trac_db_host": "127.0.0.1",
  "acra_server_public_key": "VUVDMgAAAC1w3M1uArNP+AWNhmOi6+bR6SXadlPbAh3XFnBuOnLziPeHn70T"
}

Step 7. Add AcraWriter to requirements/common.txt

. . .
stripe==1.43.0
Sphinx==1.4.9
acrawriter==1.0.0

Congratulations! You've integrated Acra.

Using Acra to Protect Your Rails App

Note: This tutorial is an extensive step-by-step guide for those who have never used Themis and Acra before. There is also a much shorter version for the experienced Acra users. If it’s your very first encounter with Acra, keep reading.

Intro

Acra is a database security suite, which protects you against data leaks and many typical application threats through strong selective encryption and intrusion detection capabilities.

It is based on our Themis cryptographic library with extreme security and usability for developers in mind (you can read more about Themis' cryptography in Acra here.

Acra is most useful for:

  • Selective protection of sensitive data,
  • Autosharded databases,
  • Microservices,
  • Situations with severe time constraints (aka "pressing deadlines" ;).

Acra is developer-oriented, with convenient infrastructure, and easily provides strong security and full granular control over your data.

The main basic components of Acra are:

  • AcraServer - a separate daemon that runs in an isolated environment (separate virtual machine or physical server), which is responsible for holding all the secrets required to decrypt the data and for actually decrypting this data.
  • AcraWriter - a client-side library, which integrates into the app flow either through ORM or directly, and provides the means to encrypt the sensitive data via generating AcraStructs.
  • AcraProxy - a client-side daemon that runs under a separate user / in a separate container, and which acts as a database listener that redirects all the queries to AcraServer and feeds the results back to the app.

This tutorial guides you through a typical process of integrating Acra into an app running on Ruby on Rails framework. It is based on the popular example many Ruby users start their development learning with – rubygems.org repository. RubyGems is a package manager for Ruby that provides a standard format for distributing Ruby programs and libraries in a self-contained format called a "gem". We’ll integrate Acra into it to provide cryptographic protection of the gem descriptions – i.e. author name, email, app description, etc.

Security model

Acra provides selective encryption and only protects the records you want to protect.

With AcraWriter, the records to be encrypted are wrapped in a function that outputs an AcraStruct (cryptographic container decryptable by AcraServer). AcraStruct is then stored in a database.

In Acra’s threat model, we assume that anything but AcraServer can be compromised and that any piece of data can leak outside. For Acra to stay secure, only AcraServer must stay secure. However, if AcraServer is compromised, the whole implementation of Acra will make no sense.

With Acra we strive to provide 2 main programmatic security guarantees:

  • G1: Even if all the other parts of the system are compromised, as long as AcraServer is secure, the attacker won’t collect enough data for decryption of the protected materials (database entries in our case).

  • G2: If the attacker alters the app’s behaviour in such a way that makes it request all the protected (encrypted) data from the database, AcraServer detects it and reacts accordingly by triggering pre-set alarms and panic blocks. This is currently carried out with the help of poison records in the database, which would never have been called up - except for an event of a hack/breach. In the future, more intrusion detection features besides poison records are planned.

If it is explicitly stated that the output for Zone Id must precede the AcraStruct, Acra Server will search for certain strings called Zone IDs (“Zones”) when analysing the database output stream. Zones let Acra know that within this record a private key corresponding to the Zone Id should be used for the actual decryption of AcraStructs.

Zones are the way to cryptographically compartmentalise records in an already-encrypted environment. They rely on different private keys on the server side. When using Zone keys, you get an additional 3rd guarantee:

  • G3: If the attacker manages to compromise the system and modify the app to extract all the records protected by Zone keys, he/she will have to reverse-engineer both the storage model and the Zone identification to be able to request all of them correctly.

Deploying infrastructure

In a perfect world, you’d be running different elements of Acra, as well as your database, on 3 separate machines - one for PostgreSQL, one for AcraServer, and one for AcraConnector + AcraWriter + your Rails app. This implies an immediate introduction of Acra into a real production setting, which we realise is far from a realistic course of events (at least on your very first try of Acra). So this tutorial is more focused on the things you can hands-on try out and tinker with on just 2 or even 1 machine through the creation of different users and containers (i.e. Docker, a test-only implementation of which for Acra is described at the end of this tutorial ("If you want to try Acra in containers)).

In this detailed architectural scheme we see how components of Acra, application, and database relate and interact with each other:

Put simply, the application talks to AcraConnector. AcraConnector pretends to be a database listener that uses standard PostgreSQL protocol and send the request to AcraServer using Secure Session (socket protection protocol). AcraServer sends a request to the database using the regular PostgreSQL protocol and receives an answer. If AcraServer detects the presence of AcraStruct while parsing the answer, it attempts to decrypt it and replace AcraStruct with a plaintext result in the answer (if decryption is unsuccessful, AcraServer will forward the answer as is). AcraServer returns the data to AcraConnector which returns it to the application. If Zones are used, AcraServer will use a corresponding private key to decrypt the next detected AcraStruct upon detecting ZoneId. AcraServer will ignore the AcraStruct if no Zone Id is detected before the AcraStruct.

All the dependencies mentioned in this tutorial need to be installed on all the machines/containers running Acra (or for both separate users of AcraServer and AcraConnector), unless it’s explicitly specified that some Acra components should only be installed for a separate user/machine running AcraServer or AcraConnector. All the commands starting with 'go' are meant to be executed from 'acra' folder (the folder with the repository code) on any machine.

In this tutorial, we assume that you have a fully operational PostgreSQL (as Acra transfers and receives data “as is” to and from PostgreSQL database and then processes it - parses the messages - according to the PostgreSQL protocol) and operate on Linux machines (with with Ruby environment and Rails framework installed). It’s also crucial that you have libssl-dev installed with libcrypto.so in $PATH before proceeding.

Note that before PostgreSQL 9, only escape_bytea mode was present. Now the hex mode is used by default. If your PostgreSQL uses escape_bytea, set this parameter during the installation process using the following command: $GOPATH/bin/acra-server --db_host=127.0.0.1 --escape_bytea

This might appear complicated, but in reality, Acra is easy to install. Let’s go!

Step 1. Install GoLang dependencies:

sudo apt-get install git golang libssl-dev make build-essential

and set your $GOPATH to the place where you will store the code.

Step 2. Install Themis

To install Themis, use:

    git clone https://github.com/cossacklabs/themis.git
    cd themis
    make
    sudo make install

Step 3. Build keymaker:

    go get github.com/cossacklabs/acra/cmd/acra-keymaker

It’s preferable to build the key maker and generate the keys on the machine that’s going to host AcraServer. This is the secure way to deal with the keys, as according to Acra’s threat model, we expect that any data stored outside of AcraServer can be compromised. Which is why we strongly advise against using all the components of Acra on a single machine (i.e. with the help of Docker containers) for anything more serious than testing and tinkering.

Step 4. Generate the transport, storage keys, and master key

Generate master key for AcraServer:

$GOPATH/bin/acra-keymaker --generate_master_key=master.key    

Export the key to the environment variable in base64 format:

export ACRA_MASTER_KEY=`cat master.key | base64`

Generate keys into ./.acrakeys directory structure:

/bin/bash $GOPATH/src/github.com/cossacklabs/acra/scripts/generate-keys.sh \
    --keys_dir ./.acrakeys \
    --client_id yourID
./.acrakeys/yourID_server
./.acrakeys/yourID_server.pub
./.acrakeys/yourID_storage
./.acrakeys/yourID_storage.pub

Here yourID is a placeholder for the Id name of your choice. You’re allowed to use 5-256 symbols (inclusively) that include Latin symbols, numbers, “-” (minus symbol), “_” (underscore), and “ ” (space).

The generator will generate and place the keys into the .acrakeys directory (you can change this with --output argument).

For a few minutes, let the keys rest where they are - they will be necessary after you have installed AcraServer, AcraProxy, and AcraWriter (if you’d like to read more about the keys, please see Key Management).

AcraServer

Yet another reminder that AcraServer needs to be installed on a separate computer/virtual machine/container and with SSL turned off in PostgreSQL.

Step 5. Build AcraServer

The installation starts with adding a new user for AcraServer:

    sudo useradd -m acra-server
    sudo su acra-server
    cd ~/
    export GOPATH=`pwd`

Now build AcraServer:

    go get github.com/cossacklabs/acra/cmd/acra-server

AcraServer should have AcraConnector's public transport key, and Acra Server's public transport key must be given to AcraConnector.This is necessary for accepting connections via Secure Session from clients.

Put .acrakeys/yourID.pub + .acrakeys/yourID_server + .acrakeys/yourID_storage into AcraServer’s key folder with proper permissions (folder 700, private keys 600 - permissions are assigned during the generation process, and permissions for AcraConnector and AcraWriter keys are the same).

Before launching AcraServer, you need to perform the following first (the keys for this were generated in Step 4.):

/bin/bash $GOPATH/src/github.com/cossacklabs/acra/scripts/generate-keys.sh \
    --keys_dir ./.acrakeys \
    --client_id yourID

Launch AcraServer with:

    $GOPATH/bin/acra-server --db_host=127.0.0.1

The command above can be complemented with --db_port=5432 -v to adjust the listener port and to add logs quickly. There are more parameters available, and you can find them in the documentation page for Acra, but for the present goal - namely, for an easy integration of Acra into a Ruby app, the default parameters will do.

You can also run with the options from config. Copy the example config:

   $REPO_DIR/configs/acra-server.yaml

or from

    $GOPATH/src/github.com/cossacklabs/acra/configs/acra-server.yaml

Or generate the config yourself:

    $GOPATH/bin/acra-server --dump_config > acra-server.yaml

and run:

    $GOPATH/bin/acra-server --config_file=acra-server.yaml

Proper logging is set with:

    $GOPATH/bin/acra-server --db_host=127.0.0.1 -v

You’ll also need an explicit server_id that is used as an identifier for Secure Session between AcraConnector and AcraServer:

    $GOPATH/bin/acra-server --db_host=127.0.0.1 --securesession_id=server_id_name_of_your_choice

If you changed the server Id to some server_id_name_of_your_choice, specify this Id for AcraConnector using:

    $GOPATH/bin/acra-connector --acraserver_securesession_id=server_id_name_of_your_choice

By default, AcraServer listens on port 9393, but you can set a custom port (just don’t forget to follow the instructions on specifying a custom port for AcraConnector further in this tutorial) if there is a need:

    $GOPATH/bin/acra-server --db_host=127.0.0.1 --incoming_connection_port=3000

Here 3000 is the customisable part.

Step 6. Build AcraConnector

AcraConnector should run under a separate user on the same machine as your Rails app (or in a separate container for testing purposes). All the database requests need to be directed to AcraConnector, which then pretends to be a database listener (a local proxy) and relays all the requests to AcraServer (on a separate machine/in a separate container), listens back and returns the responses to the app.

Install AcraConnector:

    go get github.com/cossacklabs/acra/cmd/acra-connector

Put .acrakeys/yourID + .acrakeys/yourID_server.pub to AcraConnector’s key folder (.acrakeys or anything you chose in --keys_output_dir). AcraConnector’s own public key should already have been given to AcraServer to establish Secure Session connection. Pre-shared public keys enforce maximum secrecy and easy-to-manage authentication, and - as you can see - require minimal intervention on your side or into your code for successful implementation.

Upon launch with the default settings, AcraConnector will start listening on port 9494 and will attempt to connect to AcraServer on port 9393. To initialise, use:

    $GOPATH/bin/acra-connector --acraserver_connection_host=127.0.0.1 --client_id=yourID -v

Let’s change the port AcraConnector is listening on:

    $GOPATH/bin/acra-connector --client_id=client_name --acraserver_connection_host=acra.server.host --acraserver_connection_port=5432

Now AcraConnector will be listening on port 5432 (your custom port). This is important if you want the launch of AcraConnector to be transparent for the app (if your app connected to PostgreSQL on 5432).

You can also launch AcraConnector with the options from example config - just copy it from:

    $REPO_DIR/configs/acra-connector.yaml

Or from:

    $GOPATH/src/github.com/cossacklabs/acra/configs/acra-connector.yaml

If you want, you can generate an example config yourself. Use:

    $GOPATH/bin/acra-connector --dump_config > acra-connector.yaml

And run:

    $GOPATH/bin/acra-connector --config_file=acra-connector.yaml

These instructions should be enough to get you up and running with AcraConnector, and you can proceed to the actual integration of Acra into a Rails app. For more advanced ways of setting up and launching AcraConnector, please see the corresponding fragment of Acra documentation.

Integration

Step 7. Integrating Acra with Rails

Since in our example we’ll be integrating Acra into a Ruby web app - namely RubyGems app running on Ruby on Rails framework - to protect the gem descriptions, i.e. name of the app author, email, summary, license, app description, etc.. Here, for example, is what our own rubygem specification for Acra looks like:

To protect similar fields in your own gems, you need to start with cloning the rubygems.org repository (to the same machine/container that is running AcraConnector) with:

    git clone https://github.com/rubygems/rubygems.org.git

Visit your local RubyGems sign up page and register with your email address, username, and a password. After the registration, verify your email using the following command: psql -h127.0.0.1 --dbname=acra -Utest -c 'update users set email_confirmed=TRUE where id = (select max(id) from users);'

AcraWriter comes into play next. It is basically Themis that is generating AcraStructs with the keys you've made available to AcraWriter. You can encrypt your sensitive data by generating AcraStructs with AcraWriter anywhere in your app. AcraWriter can be used whenever you need to encrypt sensitive records (in our case - gem descriptions).

Install AcraWriter:

gem install acrawriter

Step 7.1 Install activerecord_acrawriter

Note: This only works with Ruby > 2.2 because that is a requirement of Active Record

This gem adds a new type to Active Record for transparent encryption:

gem install activerecord_acrawriter    

Step 8. Add AcraServer public key to config/secrets.yml

To proceed with integrating Acra into your Rails app, you need to add the AcraServer public key into your rubygems.org/config/secrets.yml file, like this:

Development:
      secret_key_base: 
 01ade4a4dc594f4e2f1711f225adc0ad38b1f4e0b965191a43eea8a658a97d8d5f7a1255791c491f14ca638d4bbc7d82d8990040e266e3d898670605f2e5676f
      acra_public_key: VUVDMgAAAC1w3M1uArNP+AWNhmOi6+bR6SXadlPbAh3XFnBuOnLziPeHn70T # base64

Step 9. Use AcraType on the gem fields you want to encrypt

Encrypt the unresolved_name field in the Dependency model:

    require 'activerecord_acrawriter'
    . . .
    class Dependency < ActiveRecord::Base
        . . .
        attribute :unresolved_name, AcraType.new
        . . .

Encrypt authors, description, and summary fields in the Version model:

    require 'activerecord_acrawriter'
    . . .
    class Version < ActiveRecord::Base
        . . .
        class AuthorType < AcraType
          def cast_value(value)
             if value.is_a?(Array)
                value = value.join(', ')
                super(value)
            else
              super
            end
          end
        end

        attribute :authors, AuthorType.new
        attribute :description, AcraType.new
        attribute :summary, AcraType.new

Step 10. Add activerecord_acrawriter to your gemfile

Add the activerecord_acrawriter dependencies to the project:

    . . .
    gem 'sprockets-rails', '~> 3.1.0'
    gem 'rack-attack'
    gem 'activerecord_acrawriter'

    group :development, :test do
      gem 'rubocop', require: false
      gem 'toxiproxy', '~> 0.1.3'
    end
    . . .

This completes the process of integrating a fully operational Acra into your Ruby on Rails app in a real-life setup that uses different machines/users.

Result and testing

To test your Acra setup:

  • Connect AcraConnector to AcraServer, send a regular request to your database through AcraConnector. If you see the answer, AcraConnector and AcraWriter are able to connect and forward signals back and forth. It means that the network and the keys are fine.

  • Upon integrating AcraWriter into your code, try generating an AcraStruct from some payload. If you succeed in running AcraWriter code, Themis library is installed properly and the keys are located in the expected places.

  • Write a row with AcraStruct into the database, either directly or through AcraConnector. Request this row through AcraConnector. If you see the decrypted payload in the response, the scheme works properly.

And now, let’s test the whole setup through pushing a gem with its info protected by Acra. Use the username, email, and password you entered during the registration.

Note: RubyGems saves the credentials in ~/.gem/credentials so you only need to log in once.

To publish version 0.1.0 of a new gem named ‘my-protected-gem’:

    gem push my-protected-gem --host=http://127.0.0.1:3000
    Enter your RubyGems.org credentials.
    Don't have an account yet? Create one at https://rubygems.org/sign_up
       Email:   email@thatyouregistred.with
    Password:
    Signed in.
    Pushing gem to RubyGems.org...
    Successfully registered gem: my-protected-gem (0.1.0)

Now you need to open the gem at:

    http://127.0.0.1:3000/gems/my-protected-gem

It should return you the plaintext data that you’ve entered (author, email, etc.). To see that everything is, in fact, encrypted and Acra works properly, send these 2 queries directly to the database, they should return an “incomprehensible” mishmash of symbols in which the data turns after the encryption:

    select authors, description, summary from versions where rubygem_id=(select max(id) from rubygems);

    select unresolved_name from dependencies where rubygem_id = (select max(id) from rubygems);

If the database returns all the data it contains in encrypted form, everything is working properly and you’ve successfully integrated Acra into your Ruby app!

Note: A gem can have dependencies and if those are missing from rubygems.org or locally, the names of the unresolved dependencies go to the “unresolved_name”. So the latter example will only return the encrypted data for “unresolved_name” field if there are some names of dependencies added to "unresolved_name". Otherwise, it will return nothing.

If You Want to Try Acra in Containers

We’ve made some special effort to make Acra work with Docker. However, please remember that using Acra with containers is violating its basic security guarantee. Docker is immutable, and zones/keys are not. This means you might want to attach some storage and end up leaving keys accessible to attackers. So use Acra with Docker for testing purposes only.

To simply test the waters of using Acra, you can use pre-made config files and examples below - they can also serve as a reference for integrating Acra with a Ruby app.

You’ll need to download Acra, just like it was described above:

    git clone https://github.com/cossacklabs/acra
    cd acra

And start AcraServer, AcraConnector, and PostgreSQL in separate Docker containers:

    docker-compose -f docker/docker-compose.pgsql-nossl-server-ssession-connector.yml up -d
  • -f use specified docker-compose*.yml file
  • -d run in background

After executing this command, you will have a running PostgreSQL with test:test user:password with forwarded 5432 port, AcraServer with keys that you generated above, and AcraConnector that forwards port 9494.

Don’t forget to stop your local PostgreSQL if you run it before launching the Docker with PostgreSQL in a container or you’ll get an error from 2 instances of an application trying to listen on the same port.

By default, Docker will create 3 containers with the following names: docker_acra-server_1, docker_acra-connector_1, and docker_pg_1.

Install the example application dependencies:

    cd examples/ruby
    gem install bundler
    bundle install

Create a database:

    psql -h127.0.0.1 -U test -c "create database acra with encoding 'utf8'";

Note: Either name your database gemcutter_development (to follow the default rubygems practice or come up with a custom name - in this case the custom name is acra. Don’t forget to change the database name in the
config/database.yml file afterwards. Use this database name in all the following commands below.

You’ll be asked to input the password for PostgreSQL (test) and you’re ready to proceed. Copy the keys that we generated previously:

    cp -r ../../.acrakeys
    ruby example.rb

To test that the database contains only encrypted data, use:

    psql -h127.0.0.1 -Utest --dbname=acra -c "select * from test"

It will return the data in an encrypted form:

    data | raw_data
    FXIYCZZT | FXIYCZZT
    psql -h127.0.0.1 -Utest --dbname=acra -c "select * from test"
    id | data | raw_data
     28215 |
\x2222222222222222554543320000002d0950cb9003c7809eb6371e3bf0609821119b3340cd9e06168f10613d9859773cba97d9c9ca2027042654000000000101400c0000001000000020000000328887e
e14cd2e91c934286e4d47256dc7c5b9bb8bfb42ccee37c6eaa329f03afad64fd87dce9040ee4656108e9a1befedf5ffe70b70a8324ca1ccfe3400000000000000000101400c0000001000000008000000dab41aa5830
54653d79645c723070b7a2e55b9643abbad47cc02843b62e81249ed15ee31 | FXIYCZZT

Now the data is encrypted and you see it. Acra is working!

Using Acra in Docker with Zones

Shut down the previous active Docker containers before proceeding with this method! Use:

    docker-compose -f docker/docker-compose.pgsql-nossl-server-ssession-connector.yml down

Use this .yml file to start AcraServer that supports Zones:

    docker-compose -f docker/docker-compose.pgsql-nossl-server-ssession-connector_zonemode.yml up -d

Create the database in a new container:

    psql -h127.0.0.1 -U test -c "create database acra with encoding 'utf8'";

Note: By default, AcraConnector will listen on port 5432.

Add a new ZoneId:

    docker exec docker_acra-server_1 acra-addzone --output_dir=/keys

The output will look something like this:

{"id":"DDDDDDDDdwjzKTZyKnIprHdc","public_key":"VUVDMgAAAC31i9rcAnNZFHkqfHnbgMQqJWjcXOYGhxAjYHJ5Rh7mMEC5dyjT"}

Now you need to copy the info for your "id" and "public key" from the output to the example_with_zone.rb and replace the existing examples example_with_zone.rb with your own data.

zone_data = JSON.parse('{"id":"DDDDDDDDhydxgNoxWYxYRZzf","public_key":"VUVDMgAAAC11q5/TAmIAS42yyuNISRCsbl56D/yBH0iSZ9nmVfhdaOP0mwSH"}')

Let’s run the example:

    ruby example_with_zone.rb    

The output will be:

    zone | data | raw_data
    DDDDDDDDdwjzKTZyKnIprHdc | HDDNXEIU | HDDNXEIU    

And finally, let’s test that the database only contains encrypted data:

    psql -h127.0.0.1 -Utest --dbname=acra -c "select * from test2"
id| zone |data | raw_data 
45387 | \x444444444444444464776a7a4b545a794b6e497072486463 | \x2222222222222222554543320000002de7f416d202f70fcae099312ce72ce603d4ed7129cb3f2aca484c572c19a03e81e90a907d5420
27042654000000000101400c0000001000000020000000dd51dcaa49820982611b4544466c4d5422edd0fde075bad9febbcdbbfc4ae61064e8a27ba6935e3d655707f76392bea54ebd14497d56fc07b3e6eb3a340000
0000000000000101400c00000010000000080000005d2cb195d8d0258079b4c5542da9184dc58ae21ce537f61dec7ea457ade32521731dfbdf | HDDNXEIU

You see the data is in encrypted form. Congratulations! Acra is now working with Zones!

Conclusion

As you can see, establishing cryptographic protection for the data in your web app with Acra is a very straightforward and simple process. We hope that this tutorial was fun and informative and that you will be using Acra in the future. If you only tried the Docker-based examples, try running Acra in a real-world setup - it’s just as convenient.

You can also check out a similar Acra tutorial for Django Project.

Integrating Acra with RubyGems - short version

This tutorial outlines a typical process of integrating Acra into a Ruby web app (more specifically, an app running on Ruby on Rails framework). It is based on the popular example many Ruby users start their development learning with - rubygems.org repository.

Here we will integrate AcraWriter to protect the gem descriptions.

This tutorial assumes that you have both AcraServer and PostgreSQL up and running.

You can browse the modified repository here.

Step 1. Clone repo

git clone https://github.com/rubygems/rubygems.org.git

Step 2. Install AcraWriter

gem install acrawriter

Step 2.1 Install activerecord_acrawriter

This gem adds a new type to Active Record for transparent encryption

Note: This only works with Ruby > 2.2 because that is a requirement of Active Record

gem install activerecord_acrawriter

Step 3. Add AcraServer public key to config/secrets.yml

development:
  secret_key_base: 01ade4a4dc594f4e2f1711f225adc0ad38b1f4e0b965191a43eea8a658a97d8d5f7a1255791c491f14ca638d4bbc7d82d8990040e266e3d898670605f2e5676f
  acra_public_key: VUVDMgAAAC1w3M1uArNP+AWNhmOi6+bR6SXadlPbAh3XFnBuOnLziPeHn70T # base64

Step 4. Use AcraType on the fields that you want to encrypt

Encrypt unresolved_name field in Dependency model:

# app/models/dependency.rb
require 'activerecord_acrawriter'
. . .
class Dependency < ActiveRecord::Base
    . . .
    attribute :unresolved_name, AcraType.new
    . . .

Encrypt authors, description, and summary fields in the Version model:

require 'activerecord_acrawriter'
. . .
class Version < ActiveRecord::Base
    . . .
    class AuthorType < AcraType
      def cast_value(value)
         if value.is_a?(Array)
            value = value.join(', ')
            super(value)
        else
          super
        end
      end
    end

    attribute :authors, AuthorType.new
    attribute :description, AcraType.new
    attribute :summary, AcraType.new

Step 5. Add activerecord_acrawriter to Gemfile:

. . .
gem 'sprockets-rails', '~> 3.1.0'
gem 'rack-attack'
gem 'activerecord_acrawriter'

group :development, :test do
  gem 'rubocop', require: false
  gem 'toxiproxy', '~> 0.1.3'
end
. . .

Voila! Congratulations, you've integrated Acra with Ruby Gems.

Migration guide - Acra 0.77.0 to Acra 0.80.0

Please read the migration guide if at some point you used Acra version 0.77.0 - in Acra 0.80.0 some radical renaming was applied throughout. Here is the detailed migration guide.

The migration guide of moving from Acra 0.77.0 to Acra 0.80.0.

We did a global renaming of Acra components and configuration parameters for most of them. We believe that updated naming will decrease confusion about components' functions and will make Acra setup and usage easier.

If you were using Acra before 0.80.0 release you might want to update configuration files and parameter names.

The main services:

Old name New name Function
AcraServer AcraServer decrypts data from database
AcraWriter AcraWriter encrypts data on client side
AcraProxy AcraConnector encrypts traffic between client and server using Themis Secure Session
AcraCensor AcraCensor firewall, part of AcraServer, blocks suspicious SQL requests to the database
AcraConfigUI AcraWebConfig lightweight HTTP web server for managing AcraServer's certain configuration options

Utilities:

Old name New name Function
acra_rollback AcraRollback decrypts the whole database
acra_genkeys AcraKeymaker generates encryption keys for storage and transport for Acra components
acra_genauth AcraAuthmanager generates user accounts for AcraWebConfig
acra_genpoisonrecord AcraPoisonRecordMaker generates poision records for databases
acra_addzone AcraAddzone generates Zones header for AcraWriter

Configuration parameters

AcraServer configuration

Check out the full guide to AcraServer.

Old name New name Function
--censor_config --acracensor_config_file Path to AcraCensor configuration file
--tls --acraconnector_tls_transport_enable Use tls to encrypt transport between AcraServer and AcraConnector/client
--no_encryption --acraconnector_transport_encryption_disable Use raw transport (tcp/unix socket) between AcraServer and AcraConnector/client (don't use this flag if you not connect to database with ssl/tls)
--injectedcell --acrastruct_injectedcell_enable Acrastruct may be injected into any place of data cell
--wholecell --acrastruct_wholecell_enable Acrastruct will stored in whole data cell (default true)
--auth_keys --auth_keys Path to basic auth passwords. To add user, use: ./acra-authmanager --set --user <user> --pwd <pwd> (default "configs/auth.keys")
--client_id --client_id Expected client id of AcraConnector in mode without encryption
--config --config_file path to config
-d -d Turn on debug logging
--db_host --db_host Host to db
--db_port --db_port Port to db (default 5432)
-ds -ds Turn on http debug server
--dumpconfig --dump_config dump config
--enable_http_api --http_api_enable Enable HTTP API
--commands_port --incoming_connection_api_port Port for AcraServer for HTTP API (default 9090)
--connection_api_string --incoming_connection_api_string Connection string for api like tcp://x.x.x.x:yyyy or unix:///path/to/socket (default "tcp://0.0.0.0:9090/")
--close_connections_timeout --incoming_connection_close_timeout Time that AcraServer will wait (in seconds) on restart before closing all connections (default 10)
--host --incoming_connection_host Host for AcraServer (default "0.0.0.0")
--port --incoming_connection_port Port for AcraServer (default 9393)
--connection_string --incoming_connection_string Connection string like tcp://x.x.x.x:yyyy or unix:///path/to/socket (default "tcp://0.0.0.0:9393/")
--keys_dir --keys_dir Folder from which will be loaded keys (default ".acrakeys")
--logging_format --logging_format Logging format: plaintext, json or CEF (default "plaintext")
--mysql --mysql_enable Handle MySQL connections
--escape_bytea --pgsql_escape_bytea Escape format for Postgresql bytea data
--hex_bytea --pgsql_hex_bytea Hex format for Postgresql bytea data (default)
--poisonscript --poison_run_script_file Execute script on detecting poison record
--poisonshutdown --poison_shutdown_enable Stop on detecting poison record
--postgresql --postgresql_enable Handle Postgresql connections (default true)
--server_id --securesession_id Id that will be sent in secure session (default "acra_server")
--tls_ca --tls_ca Path to root certificate which will be used with system root certificates to validate Postgresql's and AcraConnector's certificate
--tls_cert --tls_cert Path to tls certificate
--tls_sni --tls_db_sni Expected Server Name (SNI) from Postgresql
--tls_key --tls_key Path to private key that will be used in TLS handshake with AcraConnector as server's key and Postgresql as client's key
--zonemode --zonemode_enable Turn on zone mode
-v -v Log to stderr

AcraConnector configuration

Check out the full guide to AcraConnector.

Old name New name Function
--acra_commands_port --acraserver_api_connection_port Port of Acra HTTP api (default 9090)
--acra_api_connection_string --acraserver_api_connection_string Connection string to Acra's API like tcp://x.x.x.x:yyyy or unix:///path/to/socket
--acra_host --acraserver_connection_host IP or domain to AcraServer daemon
--acra_port --acraserver_connection_port Port of AcraServer daemon (default 9393)
--acra_connection_string --acraserver_connection_string Connection string to AcraServer like tcp://x.x.x.x:yyyy or unix:///path/to/socket
--acra_id --acraserver_securesession_id Expected id from AcraServer for Secure Session (default "acra_server")
--tls --acraserver_tls_transport_enable Use tls to encrypt transport between AcraServer and AcraConnector/client
--no_encryption --acraserver_transport_encryption_disable Use raw transport (tcp/unix socket) between acraserver and acraproxy/client (don't use this flag if you not connect to database with ssl/tls
--client_id --client_id Client id
--config --config_file path to config
--dumpconfig --dump_config dump config
--enable_http_api --http_api_enable Enable HTTP API
--command_port --incoming_connection_api_port Port for AcraConnector HTTP api (default 9191)
--connection_api_string --incoming_connection_api_string Connection string like tcp://x.x.x.x:yyyy or unix:///path/to/socket (default "tcp://127.0.0.1:9191/")
--port --incoming_connection_port Port to AcraConnector (default 9494)
--connection_string --incoming_connection_string Connection string like tcp://x.x.x.x:yyyy or unix:///path/to/socket (default "tcp://127.0.0.1:9494/")
--keys_dir --keys_dir Folder from which will be loaded keys (default ".acrakeys")
--logging_format --logging_format Logging format: plaintext, json or CEF (default "plaintext")
--tls_sni --tls_acraserver_sni Expected Server Name (SNI) from AcraServer
--tls_ca --tls_ca Path to root certificate which will be used with system root certificates to validate AcraServer's certificate
--tls_cert --tls_cert Path to certificate
--tls_key --tls_key Path to private key that will be used in TLS handshake with AcraServer
--disable_user_check --user_check_disable Disable checking that connections from app running from another user
-v -v Log to stderr

AcraWebConfig configuration

Check out the full guide to AcraWebConfig.

Old name New name Function
--config --config_file path to config
-d -d Turn on debug logging
--acra_host --destination_host Host for AcraServer HTTP endpoint or AcraConnector (default "localhost")
--acra_port --destination_port Port for AcraServer HTTP endpoint or AcraConnector (default 9191)
--dumpconfig --dump_config dump config
--auth_mode --http_auth_mode Mode for basic auth. Possible values: auth_on/auth_off_local/auth_off (default "auth_on")
--host --incoming_connection_host Host for AcraWebconfig HTTP endpoint (default "127.0.0.1")
--port --incoming_connection_port Port for AcraWebconfig HTTP endpoint (default 8000)
--logging_format --logging_format Logging format: plaintext, json or CEF (default "plaintext")
--static_path --static_path Path to static content (default "cmd/acra-webconfig/static")

AcraRollback configuration

Check out the full guide to AcraRollback.

Old name New name Function
--client_id --client_id Client id should be name of file with private key
--config --config_file path to config
--connection_string --connection_string Connection string for db
--dumpconfig --dump_config dump config
--escape --escape Escape bytea format
--execute --execute Execute inserts
--insert --insert Query for insert decrypted data with placeholders (pg: $n, mysql: ?)
--keys_dir --keys_dir Folder from which the keys will be loaded (default ".acrakeys")
--mysql --mysql_enable Handle MySQL connections
--output_file --output_file File for store inserts queries (default "decrypted.sql")
--postgresql --postgresql_enable Handle Postgresql connections
--select --select Query to fetch data for decryption
--zonemode --zonemode_enable Turn on zone mode

AcraKeymaker configuration

Check out the full guide to Key management.

Old name New name Function
--client_id --client_id Client id (default "client")
--config --config_file path to config
--dumpconfig --dump_config dump config
--acraproxy --generate_acraconnector_keys Create keypair for AcraConnector only
--acraserver --generate_acraserver_keys Create keypair for AcraServer only
--basicauth --generate_acrawebconfig_keys Create symmetric key for AcraWebconfig's basic auth db
--storage --generate_acrawriter_keys Create keypair for data encryption/decryption
--master_key --generate_master_key Generate new random master key and save to file
--output --keys_output_dir Folder where will be saved keys (default ".acrakeys")
--output_public --keys_public_output_dir Folder where will be saved public key (default ".acrakeys")

AcraPoisonRecordMaker configuration

Check out the full guide to Poison records.

Old name New name Function
--config --config_file path to config
--data_length --data_length Length of random data for data block in acrastruct. -1 is random in range 1..100 (default -1)
--dumpconfig --dump_config dump config
--keys_dir --keys_dir Folder from which will be loaded keys (default ".acrakeys")

AcraAddzone configuration

Check out the full guide to Zones.

Old name New name Function
--config --config_file path to config
--dumpconfig --dump_config dump config
-fs --fs_keystore_enable Use filesystem key store (default true)
--output_dir --keys_output_dir Folder where will be saved generated zone keys (default ".acrakeys")

Onepage tutorials for Acra

You've reached the end of the onepage tutorials for Acra. You can also find all the tutorials at their separate pages through the Tutorials and How Tos section of the Acra product page.