Integrating AcraServer into infrastructure #

How AcraServer works #

Refer to AcraServer architecture page to find out deep description of internals and how it works.

AcraServer installation #

There are multiple ways to install AcraServer. You will also need utilities like acra-keys that come along.

Key generation #

You will need some keys in order to launch AcraServer, so let’s do it first.

The first one will be used to protect all the other keys, it should be base64-encoded and passed to Acra services in ACRA_MASTER_KEY environment variable.

Like this: ACRA_MASTER_KEY="$(cat /tmp/master_key | base64)" acra-server ...

The second key is responsible for data encryption. There are actually more kinds of keys, read more about that on Acra keys inventory.

It is also possible to store keys in a Redis database, see Scalable KV storages.

Note about Client ID #

When generating a key, you will always have to bind it with a Client ID or Zone ID (zones are deprecated since 0.94.0, will be removed in 0.95.0). AcraServer distinguishes applications by Client ID and uses different encryption keys for different clients.

AcraServer configuration #

Refer to AcraServer configuration page.

AcraConnector (optional) #

AcraConnector is as intermediate proxy between the application and AcraServer. Why would you need yet another proxy? Well, there are a couple of reasons:

Providing secure transport to AcraServer: if application does not support TLS, does communicate with AcraServer on remote host, and you want to ensure the communication channel is safe
Specifying which Client ID to use: when using TLS, you will have to use client IDs derived from some certificate properties (such as serial number), but with AcraConnector you can use whatever ID you want by simply setting configuration option when launching AcraConnector

AcraConnector usually lives on the same host as the application, but is isolated a bit (running as different user, in separate docker container and so on).

Data migration #

There are few things you need to know before using AcraServer encryption features.

Changes on application side #

As soon as you have running instance of AcraServer, you can try redirecting you application(s) to it

Change the host:port part of connection to make application connect to AcraServer
Make sure application will accept TLS certificate configured in AcraServer
No need to change database credentials

Poison records #

If the client application is hacked and the attacker is trying to decrypt all the data, you can detect it using poison records.

AcraServer (similarly as AcraTranslator) has ability to detect poison records and stop executing the request, preventing the data from leaking to an untrusted destination. To learn more about AcraServer cmd configuration you can refer here.

AcraWriter integration (optional) #

One of the things available in enterprise edition is part of SDK called AcraWriter that allows data encryption right inside the application. This feature is not frequently needed, but may help in situations where transport encryption is not enough.