Encryption at Rest

ArangoDB Enterprise Edition AMP

When you store sensitive data in your ArangoDB database, you want to protect that data under all circumstances. At runtime you will protect it with SSL transport encryption and strong authentication, but when the data is already on disk, you also need protection. That is where the on-disk encryption feature comes in.

Encryption at rest encrypts all data that ArangoDB is storing in your database before it is written to disk.

The data is encrypted with AES-256-CTR, which is a strong encryption algorithm, that is very suitable for multi-processor environments. This means that your data is safe, but your database is still fast, even under load.

Hardware acceleration for encryption and decryption is automatically used if available. The required AES-NI instruction set (Advanced Encryption Standard New Instructions) is available on the majority of Intel and AMD processors from the last decade. The benefits over a software-only implementation are better performance and resistance to side-channel attacks.

The encryption feature is supported by all ArangoDB deployment modes.

Limitations

The encryption feature has the following limitations:

• Encrypting a single collection is not supported: all the databases are encrypted.
• It is not possible to enable encryption at runtime: if you have existing data you will need to take a backup first, then enable encryption and start your server on an empty data-directory, and finally restore your backup.

Encryption keys

The encryption feature of ArangoDB requires a 32-byte key per server. You can supply multiple keys using a key folder for key rotation, but any one of them is enough to start the server. It is recommended to use a different key for each server (when operating in a cluster configuration).

Configuration

To activate encryption of your database, you need to supply an encryption key to the server.

Make sure to pass this option the very first time you start your database. You cannot encrypt a database that already exists. Once a database is encrypted, you need to provide a key every time you start the server.

There are multiple ways of supplying the encryption key but you can only use one of them at a time. If you specify more than one of the --rocksdb.encryption-keyfile, --rocksdb.encryption-key-generator, and --rocksdb.encryption-keyfolder startup options, then the server refuses to start. See Rotating encryption keys about supplying a set of keys using a folder.

Encryption key stored in file

Pass the following option to arangod:

$ arangod --rocksdb.encryption-keyfile=/mytmpfs/mySecretKey ...

The file /mytmpfs/mySecretKey must contain the encryption key, which needs to be exactly 32 bytes long. The server reads the file as is and does not trim it, so a trailing newline or other whitespace makes the key invalid and the server refuses to start. This file must be secured, so that only arangod can access it. You should also ensure that in case someone steals the hardware, they will not be able to read the file. For example, by encrypting /mytmpfs or creating an in-memory file-system under /mytmpfs.

Encryption key generated by a program

Pass the following option to arangod:

$ arangod --rocksdb.encryption-key-generator=path-to-my-generator ...

The program path-to-my-generator outputs the encryption key on standard output and exits. The server removes leading and trailing whitespace from the output and ignores the exit code of the program. After trimming, the key needs to be exactly 32 bytes long.

Kubernetes encryption secret

If you use kube-arangodb then use the spec.rocksdb.encryption.keySecretName setting to specify the name of the Kubernetes secret to be used for encryption. See the kube-arangodb documentation .

Creating keys

The encryption keyfile must contain 32 bytes of random data, without any additional characters like a trailing newline.

You can create it with a command line this.

dd if=/dev/random bs=1 count=32 of=yourSecretKeyFile

For security, it is best to create these keys offline (away from your database servers) and directly store them in your secret management tool.

Rotating encryption keys

ArangoDB supports rotating the user supplied encryption at rest key. This is implemented via key indirection. At initial startup, the first found user-supplied key is used as the internal master key. Alternatively, the internal master key can be generated from random characters if the startup option --rocksdb.encryption-gen-internal-key is set to true.

It is possible to change the user supplied encryption at rest key via the HTTP API. This API is disabled by default, but can be turned on by setting the startup option --rocksdb.encryption-key-rotation to true. Rotating the key requires a superuser JWT. The API is not available on Coordinators.

A rotation reads the user key again from the key source that the instance is configured with and re-encrypts the internal master key with it. It is not limited to a particular key source. It works with the mutually exclusive --rocksdb.encryption-keyfile, --rocksdb.encryption-key-generator, and --rocksdb.encryption-keyfolder startup options alike, but a key folder is recommended because it allows for a rollout without a risky time window:

• If you use a single key file or a key generator, you need to replace the key before you call the API. Until the rotation succeeds, the instance cannot be restarted because the new key doesn’t match the internal keystore yet.
• If you use a key folder, the instance can be started with any one of the keys in the folder, guarding against service interruptions during the rotation.

To use a folder of keys, pass the following option to arangod:

$ arangod --rocksdb.encryption-keyfolder=/mytmpfs/mySecrets ...

arangod then stores the master key encrypted with each of the provided secrets, so that only one of the secrets needs to be correct in order to start the instance.

The folder must exist and contain at least one key file. Only regular files in the folder are read as keys (symbolic links to regular files are followed), and each of them needs to contain exactly 32 bytes, without trimming. Hidden files (with names starting with a dot), files with a .tmp file extension, and subfolders are ignored. The files are not read in a defined order. If the folder contains multiple keys at the initial startup and you don’t set --rocksdb.encryption-gen-internal-key to true, then which key becomes the internal master key is therefore not predictable.

A rotation always uses the keys that are in the folder at the time you call the API. It re-encrypts the master key with every key it finds there and discards the internal keystore entries of keys that you removed from the folder. You can therefore roll out a new key like this:

1. Add the new key as an additional file to the key folder.
2. Call the key rotation API. The master key is now stored encrypted with the old as well as the new key, and the instance can be started with either.
3. Remove the old key file from the key folder.
4. Call the key rotation API again. The master key is now only stored encrypted with the new key, and the old key can no longer unlock it.