Go Python Makefile Shell HTML JavaScript Other
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Failed to load latest commit information.
.circleci Acra ConfigUI integration tests (#161) Apr 13, 2018
acracensor Merge branch 'master' of github.com:cossacklabs/acra into alternative Apr 13, 2018
acrawriter goreport/golint fixes Feb 21, 2017
benchmarks drop sslmode=disable from connection params (#119) Mar 9, 2018
cmd Acra ConfigUI integration tests (#161) Apr 13, 2018
configs Add logging handler support in censor's yaml config Apr 12, 2018
decryptor Add logger-handler to firewall (#151) Apr 12, 2018
docker Docker compose improvements (#165) Apr 13, 2018
examples use firewall in query processing (#136) Mar 27, 2018
fuzz use firewall in query processing (#136) Mar 27, 2018
io goreport/golint fixes Feb 21, 2017
keystore create dir if not exists for public keys (#148) Apr 5, 2018
logging Add logger-handler to firewall (#151) Apr 12, 2018
network fix initializing cert pool (#162) Apr 13, 2018
poison goreport/golint fixes Feb 21, 2017
tests Acra ConfigUI integration tests (#161) Apr 13, 2018
utils update acra version (#164) Apr 13, 2018
wrappers update ruby wrappers (#166) Apr 24, 2018
zone Mozh/t489 configui basicauth (#141) Apr 3, 2018
.gitignore Mozh/t489 configui basicauth (#141) Apr 3, 2018
CHANGELOG.md remove `select` queries from AcraCensor Apr 13, 2018
LICENSE add license Nov 23, 2016
Makefile acra_configui integrated into compose files. Apr 11, 2018
README.md Update README.md Apr 13, 2018
test.sh Add circleci tests for all official go version (#93) Feb 28, 2017


Acra: transparent database encryption server
Database protection suite with selective encryption and intrusion detection.

GitHub release Circle CI Coverage Status
Server platforms Client platforms

Documentation Python sample project Ruby sample project Examples

What is Acra

Acra helps you easily secure your databases in distributed, microservice-rich environments. It allows you to selectively encrypt sensitive records with strong multi-layer cryptography, detect potential intrusions and SQL injections and cryptographically compartmentalize data stored in large sharded schemes. Acra's security model guarantees that if your database or your application become compromised, they will not leak sensitive data, or keys to decrypt them.

Acra gives you means to encrypt the data on the application's side into a special cryptographic container, and store it in the database and then decrypt in secure compartmented area (separate virtual machine/container). Cryptographic design ensures that no secret (password, key, anything) leaked from the application or database is sufficient for decryption of the protected data chunks that originate from it.

Acra was built with specific user experiences in mind:

  • quick and easy integration of security instrumentation.
  • cryptographic protection of data in the threat model where all other parts of the infrastructure could be compromised, and if AcraServer isn't compromised, the data is safe.
  • proper abstraction of all cryptographic processes: you're safe from the risk of choosing the wrong key length or algorithm padding.
  • strong default settings to get you going.
  • intrusion detection to let you know early that something wrong is going on.
  • high degree of configurability to create perfect balance between the extra security features and performance.
  • automation-friendly: most of Acra's features were built to be easily configured / automated from configuration automation environment.
  • limited attack surface: to compromise Acra-powered app, an attacker will need to compromise the separate compartmented server, AcraServer - more specifically - it's key storage, and the database.

Acra is still a product in a early development stage. And any security tools require enourmous human efforts for validation of the methods, code, and finding possible infrastructural weaknesses. Although we do run Acra in production in several instances, we're continuously enhancing and improving it as we go. And Acra still needs ruthless dissection of all of its properties to ensure that the provided security benefits are not rendered useless through implementation problems or increased complexity.


Acra relies on our cryptographic library Themis, which implements high-level cryptosystems based on the best availble open-source implementations of the most reliable ciphers. Acra does not contain any self-made cryptographic primitives or obscure ciphers. Instead, to deliver its unique guarantees, Acra relies on the combination of well-known ciphers and smart key management scheme.


  • Acra source builds and tests with Go versions 1.7 – 1.10.
  • Acra is known to build on:
Distributive Go versions
CentOS 1.8.3 (system)
Debian Stretch 1.7.4 (system)
Debian Jessie latest (1.3.3 is not supported)
Ubuntu Artful 1.8.3 (system)
Ubuntu Xenial 1.6.2 (system)
Ubuntu Trusty latest (1.2.1 is not supported)
i386/Debian Stretch 1.7.4 (system)
i386/Debian Jessie latest (1.3.3 is not supported)
i386/Ubuntu Artful 1.8.3 (system)
i386/Ubuntu Xenial 1.6.2 (system)
i386/Ubuntu Trusty latest (1.2.1 is not supported)
  • Acra currently supports PostgreSQL 9.4+ as the database backend.
  • Starting with Acra 0.77.0, we have integrated Acra with MySQL 5.7+ database, but it is still a fresh feature, which we are extensively testing to ensure its full support. Please report any MySQL bugs you may encounter through Issues. MongoDB support is coming soon, too.
  • Acra has writer libraries for Ruby, Python, Go, and PHP, but you can easily generate AcraStruct containers with Themis for any platform you want.

How does Acra work?

Acra: simplified architecture

After successfully deploying and integrating Acra into your application, follow the 4 steps below:

  • Your app talks to AcraProxy, local daemon, via PostgreSQL/MySQL driver. AcraProxy emulates your normal PostgreSQL/MySQL database, forwards all the requests to AcraServer over a secure channel, and expects a plaintext output back.
  • Then AcraProxy forwards it over the initial database connection to the application. It is connected to AcraServer via Secure Session or TLS, which ensures that the plaintext goes over a protected channel. It is highly desirable to run AcraProxy via a separate user to compartmentalise it from the client-facing code.
  • AcraServer is the core entity that provides decryption services for all the encrypted envelopes that come from the database, and then re-packs database answers for the application. AcraCensor is part of AcraServer that allows customising the firewall rules for all the requests coming to the MySQL database.
  • To write the protected data to the database, you can use AcraWriter library, which generates AcraStructs and helps you integrate it as a type into your ORM or database management code. You will need Acra's public key to do that. AcraStructs generated by AcraWriter are not readable by it — only the server has the right keys to decrypt it.
  • You can connect to both AcraProxy and the database directly when you don't need encrypted reads/writes. However, increased performance might cost you some design elegance (which is sometimes perfectly fine when it's a conscious decision).

To better understand the architecture and data flow, please refer to Architecture and data flow section in the official documentation.

The typical workflow looks like this:

  • The app encrypts some data using AcraWriter, generating AcraStruct with AcraServer public key, and updates the database.
  • The app sends SQL request through AcraProxy, which forwards it to AcraServer.
  • AcraServer passes each query through AcraCensor, which can be configured to blacklist or whitelist some queries. AcraServer forwards the allowed queries to the database. AcraCensor can currently be only enabled for MySQL databases.
  • Upon receiving the answer, AcraServer tries to detect encrypted envelopes (AcraStructs). If it succeeds, AcraServer decrypts payload and replaces them with plaintext answer, which is then returned to AcraProxy over a secure channel.
  • AcraProxy then provides an answer to the application, as if no complex security instrumentation was ever present within the system.

4 steps to start

  • Read the Quick start guide to launch all the components. We provide different ways of installing Acra: using Docker, downloading binaries, building from source.
  • Deploy AcraServer binaries in a separate virtual machine (or try it in a docker container). Generate keys, put AcraServer public key into both clients (AcraProxy and AcraWriter, see next).
  • Deploy AcraProxy on each server where you need to read sensitive data. Generate proxy keys, provide a public key to AcraServer. Point your database access code to AcraProxy, access it as your normal database installation.
  • Integrate AcraWriter into your code where you need to store sensitive data, supply AcraWriter with proper server key.


We fill the Wiki documentation with useful articles about the core Acra concepts, use cases, details on cryptographic and security design.

You might want to:

Project status

This open source version of Acra is an early beta. We're slowly unifying and moving features from its previous incarnation into a community-friendly edition. Please let us know in the Issues whenever you stumble upon a bug, see a possible enhancement, or have a comment on security design.

Contributing to us

If you’d like to contribute your code or other kind of input to Acra, you’re very welcome. Your starting point for contributing should be this Contribution Wiki page.


Acra is licensed as Apache 2 open source software.


If you want to ask a technical question, feel free to raise an issue or write to dev@cossacklabs.com.

To talk to the business wing of Cossack Labs Limited, drop us an email to info@cossacklabs.com.

Blog Twitter CossackLabs Medium CossackLabs