Home

⚠️ For the latest documentation, examples, tutorials, and demos, please visit Cossack Labs Documentation Server. ⚠️

What is Acra?

Acra is a database protection suite with special features:

• several layers of access compartmentalisation to the secrets, which enforce better security and provide early detection of malicious behaviour.
• special architecture that grants a high level of usability for developers along with security for the data accumulated by their apps.
• single point of trust, which ensures minimal attack surface, ability to inspect all traffic that touches the attack surface, and consistent risk management.

💻 Request a free Acra Live Demo 💻

Acra has a typical client-server architecture with distinct security roles:

• AcraWriter is a client-side library, a part of your application, that encrypts the data into a special format called AcraStructs in a way that is only can be decryptable by Acra. Application can write AcraStructs to the database or store in files.
• AcraServer is a server-side service that works as database proxy: it sits transparently between your application and the database, listens silently to all the traffic that's coming to and from the database. AcraServer monitors incoming SQL requests and blocks unwanted ones by built-in configurable firewall called AcraCensor. AcraServer sends only allowed requests to the database, upon receiving responses it decrypts the payload and returns plaintext data back to the application. Certain configurations for AcraServer can be adjusted remotely using AcraWebConfig web server.
• AcraTranslator is a separate server-side decryption service, that is not linked to the database at all: it receives AcraStructs as binary blobs via HTTP or gRPC API and returns the plaintext data back. AcraTranslator and AcraServer are fully independent server-side components and can be used together or separately depending on your infrastructure.
• There is also AcraConnector, a client-side daemon, that is responsible for providing encrypted and authenticated connection between application and AcraServer/AcraTranslator. AcraConnector runs under a separate user / in a separate container, and acts as a middleware. It accepts connection from application, adds extra transport encryption layer using TLS or Themis Secure Session, sends data to AcraServer/AcraTranslator, receives result and sends it back to application. AcraConnector is an optional component and can be replaced with TLS v1.2/1.3 directly, however, Themis Secure Session provides better security guarantees 'out of the box' than average TLS configuration found in a wild.

AcraServer currently supports PostgreSQL and MySQL.

One of the key design goals for Acra was to ensure that engineering behind the security guarantees is compatible with modern software development and reliability engineering practices, i.e.:

• with the typical division between application and database,
• with an arbitrary number of application hosts, consumer microservices, and database nodes,
• high level of abstraction in the database usage patterns in the app code.

Security design goals are rather simple (the guarantees are further explained and explored in Security design):

• No amount of data and/or secrets leaked from AcraWriter, AcraConnector and database server could be sufficient for decryption of the data stolen from the database. This should be achieved through cryptography rather than through general system design.
• Sometimes even a well-behaved and trusted client (which is supposed to receive decrypted responses from AcraServer) might become compromised. However, any alteration of the app's data consumption in an unauthorised manner should be noticed, reported and prevented:
  • Acra provides a number of alarm triggers to detect potentially suspicious behaviour and requests from the application. Those triggers are configurable and allow creating unique sets of detection rules specific to the workflow and the app.
  • Acra provides a number of panic scripts, which either shut down the decryption, shut down the database connection, or provide other threat isolation methods.
  • These features are controlled programmatically and are built for modern automated environments.

Getting started with Acra

Prerequisites:

• A client application that is written in either Ruby, Python, PHP, Node.js, or GoLang, which runs on a Linux machine.
• The application talks to PostgreSQL or MySQL database via some language-specific framework (you can use SSL or non-SSL mode between AcraServer and AcraConnector for Acra; in non-SSL mode Secure Session will be used).
• Themis and client application language wrapper are installed on your machine (in most cases it will be installed automatically during AcraWriter installation process).
• Also, if you're installing Acra manually from the GitHub repository, you need to have Themis' dependencies, libssl-dev package is installed, and libcrypto.so is available in $PATH.

Quick start

Read the reference for a quick start here.

Installation

• For trying Acra really quick, for hassle-free testing purposes, you can try Acra with Docker.
• For the real-world hands-on experience, install Acra from the official Cossack Labs repository or
• Download and build Acra from the GitHub repository.

Setup

• Generate keypair (see how to do it here), which will identify this AcraConnector using acra-keymaker utility. AcraServer will recognise this AcraConnector instance by the (previously) specified <client_id>.
• Deploy AcraConnector:
  • Add another system user on the machine that runs your application (for AcraConnector).
  • Deploy AcraConnector binaries to run under that user.
  • Distribute the keys: put the keys generated by acra-keymaker – client_id, client_id_server.pub, and client_id_storage.pub – into the corresponding .acrakeys folder.
  • Run AcraConnector as a service from under this user.
  • Point the database functions in your applications to talk to localhost:9494 (default port) or any other port you've chosen.
• Deploy AcraServer to a separate machine:
  • Place the keys generated by acra-keymaker client_id.pub, client_storage, and client_id_server to the .acrakeys folder.
  • Copy AcraServer public key / Zone key to the .acrakeys folder belonging to:
    • AcraConnector's user,
    • Any user that runs AcraWriter code.
• Integrate AcraWriter:
  • Make client_id_storage.pub accessible to AcraWriter code.
  • Integrate AcraWriter closely following the examples and using either AcraConnector (if available on this machine) or direct database connection.
• Test everything:
  1. Connect AcraConnector to AcraServer, send a regular request to your database through AcraConnector.
     Result: 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.
  2. Upon integrating AcraWriter into your code, try generating an AcraStruct from some payload.
     Result: If you succeed in running AcraWriter code, Themis library is installed properly and some of the keys are located in the expected place.
  3. Write a row with AcraStruct into the database, either directly or through AcraConnector. Request this row through AcraConnector.
     Result: If you see decrypted payload in the response, the scheme works properly.
• Thoroughly read the documentation.
• Use Acra!
• P.S. Feel free to raise an Issue or contact us at info@cossacklabs.com.

Acra and Themis

Acra was built using Themis cryptographic library. Themis' cryptographic services, used via Go wrapper in AcraServer and AcraConnector, and via corresponding language wrappers in AcraWriters, are high-level compositions of carefully chosen, well-known cryptographic primitives.

Currently, you can build Themis with using OpenSSL, LibreSSL, and Google's BoringSSL (but there's a number of experimental build methods for LibSodium, BearSSL, and even CommonCrypto available, too). They provide better security, use the implementations that have passed industry-specific compliance audits, and/or fit the hardware acceleration on your platform.

⚠️ Another reminder! For the latest documentation, example projects, tutorials, demos, and additional materials please visit Cossack Labs Documentation Server. ⚠️