Acra
Acra
by Cossack Labs

VERSION 0.85.0

OS Ubuntu 18.04

Create Acra Droplet

Description

Acra encryption suite — data protection in distributed applications, web and mobile apps that use PostgreSQL/MySQL RDBMS.

Acra provides selective encryption, multi-layered access control, SQL firewall (SQL injections prevention), database leakage prevention, and intrusion detection capabilities in a convenient, developer-friendly package. See the full list of features in Acra repository.

Acra's cryptographic design ensures that no secret (password, key, etc.) leaked from the application or database will be sufficient for decryption of the protected data chunks that originate from it.

Acra minimises the attack surface, detects unauthorised behaviour, and prevents the leakage, informing operators of the incident underway. Acra provides a solid foundation for encryption-demanding regulations. As an additional configuration for better security, Acra supports client-side encryption (using client-side AcraWriter libraries).

AcraServer is a network service that works as a database proxy: it transparently sits between your application and the database and silently listens to all the traffic coming to and from the database. AcraServer monitors the incoming SQL requests and blocks the unwanted ones using the built-in configurable SQL firewall. On receiving SQL queries, AcraServer parses each query, encrypts the desired values into AcraStructs (special cryptographic containers), and passes the modified queries to the database and the database response – back to the client application.

When the client application wants to read the data, it sends a read query to the database (via AcraServer). Upon retrieving the database response, AcraServer tries to detect AcraStructs, decrypts them, and returns the decrypted data to the application.

Software Included

PackageVersionLicense
AcraServer CE0.85.0Apache 2.0
Docker CE18.09.3Apache 2
OpenSSL1.1.0gApache 2

Getting started after deploying Acra

This 1-Click App contains the most important component of Acra encryption suite — AcraServer (there exist more Acra components that allow supporting extra security features like client-side encryption, NoSQL databases, stronger transport encryption, key rotation, and rollback). Acra 1-Click app is the ideal minimum for learning and exploring with Acra.

There is a detailed tutorial to help you install Acra 1-click App through DigitalOcean Marketplace in our blog.

AcraServer configuration options

AcraServer can work in different modes, depending on the infrastructure: server-side encryption (Transparent proxy mode, where AcraServer both encrypts and decrypts the data) or client-side encryption (where client application encrypts the data and AcraServer only decrypts it).

Acra 1-Click App has an interactive configuration script that prepares AcraServer for work as a Transparent encryption proxy with PostgreSQL database.

Read about other possible configuration options in Acra's GitHub repository or check out the example applications for typical infrastructures (using Python and Ruby web applications, AcraServer and various databases).

Configuring AcraServer in Transparent encryption mode with an interactive script

In Transparent encryption mode, AcraServer works as database proxy, encrypting and decrypting sensitive data from SQL requests.

The high-level scheme looks like this:

We used DigitalOcean PostgreSQL as a database.

To get this scheme to work, we will configure each component step-by-step:

  • VM
    • hostname
    • firewall
  • AcraServer (with the help of this script):
    • encryption keys
    • TLS certificates
    • connection to DB
    • tables and columns that will be encrypted (special configuration file known as encryptor_config_file)
  • Database:
    • convert columns that you plan to encrypt to binary type
  • Application:
    • connection to AcraServer instead of Database

Configuring DigitalOcean PostgreSQL database

1. Create DigitalOcean cloud PostgreSQL database, create a role and a database with desired names.

You'll get credentials that we'll use in the next steps:


* DB host
* DB port
* DB name
* ROLE name
* ROLE password
* TLS CA certificate

2. Connect directly to the database and create a test table.


PGSQL_USER="your_login"
PGSQL_PASSWORD="your_pgsql_password"
PGSQL_HOST="DB_host"
PGSQL_PORT="DB_port"
psql "postgresql://${PGSQL_USER}:${PGSQL_PASSWORD}@${PGSQL_HOST}:${PGSQL_PORT}/${PGSQL_USER}?sslmode=require"

Create a table that we'll use in this example:


CREATE TABLE users(
 id serial PRIMARY KEY,
 name VARCHAR (50) UNIQUE NOT NULL,
 password VARCHAR (50) NOT NULL,
 email VARCHAR (355) UNIQUE NOT NULL
);

Configuring AcraServer

Connect to the newly created AcraServer 1-Click App:


AS_HOST="AcraServer_VM_IP"
ssh root@$AS_HOST

Right after the automatic connection is established, configuration script will start. This script will perform most of these actions for you. You can run this configurer as many times as necessary, in case you need to change something: server_configure.py

Step by step answer the questions:

1.1. Hostname

1.2. Hosts that are allowed to connect. Put here the host, which will be connected to the database through AcraServer. Do not forget to include your own host if you plan to play with the infrastructure manually.

You can get your external IP using:


dig @resolver1.opendns.com ANY myip.opendns.com +short

1.3. Configure TLS. DigitalOcean generates individual TLS chain for each PostgreSQL instance. That chain use self-signed CA certificate. AcraServer needs this CA to be able to verify the certificate of the database server. Paste the certificate into the configurator when you're prompted for it.

1.4. Configure the connection to the database: host and port.

1.5. Configure the structure of tables in your database. For this example, use:

  • Table: users
  • Columns (column1 column2 ...): id name password email
  • Encrypted columns (column1 column2 ...): name password email

After that, you'll get a server that's fully configured and is ready to work.

Configuring client application

Convert the fields in the database table that you plan to encrypt into binary format:


PGSQL_USER="your_login"
PGSQL_PASSWORD="your_pgsql_password"
PGSQL_HOST="DB_host"
PGSQL_PORT="DB_port"
psql "postgresql://${PGSQL_USER}:${PGSQL_PASSWORD}@${PGSQL_HOST}:${PGSQL_PORT}/${PGSQL_USER}?sslmode=require"

ALTER TABLE users
ALTER COLUMN name TYPE bytea USING name::bytea,
ALTER COLUMN password TYPE bytea USING password::bytea,
ALTER COLUMN email TYPE bytea USING email::bytea;

You can now work with your database transparently through AcraServer. Just like if you were working with it directly.


PGSQL_USER="your_login"
PGSQL_PASSWORD="your_pgsql_password"
AS_HOST_FQDN="FQDN_of_host"
psql "postgres://${PGSQL_USER}:${PGSQL_PASSWORD}@${AS_HOST_FQDN}:9393/defaultdb?sslmode=require"

Using AcraServer 1-Click App in production settings

Configure Acra 1-Click App to use it for your exact needs and situation.

If you use MySQL, PostgreSQL, or MariaDB – configure AcraServer to connect to your specific database. If you configure server-side encryption, almost no changes in your backend app are required (you only need to change the type of all encrypted fields to binary). If you prefer client-side encryption, Acra has client-side libraries (AcraWriter) for 10+ languages and platforms (with new ones being added frequently).

If you use NoSQL database or any other file storage, you can use Acra for client-side encryption. Download AcraWriter library for your backend app and deploy AcraTranslator into your infrastructure to decrypt the data.

For production use, we suggest that you configure Acra directly from configuration files and follow the configuration-as-a-code approach (instead of using the server_configure.py script above). You’ll need to generate your own keys, connect to your own database, use strong TLS, configure the SQL firewall, and preferably use client-side encryption.

Please refer to Acra's configuration guides and examples and Acra’s documentation.

Head over to a detailed tutorial for an easy start with Acra 1-click App on DigitalOcean Marketplace.

API Creation

In addition to creating a Droplet from the Acra 1-Click App via the control panel, you can also use the DigitalOcean API.

As an example, to create a 4GB Acra Droplet in the SFO2 region, you can use the following curl command. You’ll need to either save your API access token to an environment variable or substitute it into the command below.


  curl -X POST -H 'Content-Type: application/json' \
       -H 'Authorization: Bearer '$TOKEN'' -d \
      '{"name":"choose_a_name","region":"sfo2","size":"s-2vcpu-4gb","image":"acra-18-04"}' \
      "https://api.digitalocean.com/v2/droplets"
      

Support Details

Supported By:Cossack Labs
Hours:9 to 18 GMT+0
Support URL:https://github.com/cossacklabs/acra
Support Email:dev@cossacklabs.com

Learn More

Product Docs

Technical overviews, how-tos, release notes, and support material

Tutorials

DevOps and development guidelines

API Docs

Run your resources programmatically

Ask a question

Connect, share and learn