ArangoDB v3.13 is under development and not released yet. This documentation is not final and potentially incomplete.

Encryption at Rest

You can secure the physical storage media of an ArangoDB deployment by letting it encrypt the database directories

ArangoDB Enterprise Edition ArangoGraph

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 Encryption feature comes in.

The Encryption feature of ArangoDB will encrypt 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.

The ArangoGraph Insights Platform has encryption at rest as well as in transit set on by default and cannot be disabled. For more information, see the ArangoGraph documentation.

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 single 32-byte key per server. It is recommended to use a different key for each server (when operating in a cluster configuration).

Make sure to protect the encryption keys! That means:

  • Do not write them to persistent disks or your server(s), always store them on an in-memory (tmpfs) filesystem.

  • Transport your keys safely to your server(s). There are various tools for managing secrets like this (e.g. vaultproject.io ).

  • Store a copy of your key offline in a safe place. If you lose your key, there is NO way to get your data back.

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.

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. 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 output the encryption on standard output and exit.

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.

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.

To enable smooth rollout of new keys you can use the new option --rocksdb.encryption-keyfolder to provide a set of secrets. arangod will then store the master key encrypted with the provided secrets.

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

To start an arangod instance only one of the secrets needs to be correct, this should guard against service interruptions during the rotation process.

Please be aware that the encryption at rest key rotation is an experimental feature, and its APIs and behavior are still subject to change.

On this page