Weâre overhauling Dgraphâs docs to make them clearer and more approachable. If
you notice any issues during this transition or have suggestions, please
let us know.
For migrating unencrypted data to a new Dgraph cluster with encryption
enabled, you need to export the database and import
data, preferably using the bulk
loader.
Set up encryption
To enable encryption, we need to pass a file that stores the data encryption key with the option--encryption key-file=value
. The key size must be 16, 24, or
32 bytes long, and the key size determines the corresponding block size for AES
encryption (AES-128, AES-192, and AES-256, respectively).
You can use the following command to create the encryption key file (set count
to the desired key size):
On a macOS you may have to use
LC_CTYPE=C; tr -dc 'a-zA-Z0-9' < /dev/urandom | dd bs=1 count=32 of=enc_key_file
.
To view the key use cat enc_key_file
. --vault
superflagâs options to
enable encryption, as
explained below.
Turn on encryption
Here is an example that starts one Zero server and one Alpha server with the encryption feature turned on:--encryption key-file
option to each of the Alphas.
Once an Alpha has encryption enabled, the encryption key must be provided in
order to start the Alpha server. If the Alpha server restarts, the
--encryption key-file
option must be set along with the key to restart
successfully.
Storing encryption key secret in HashiCorp Vault
You can save the encryption key secret in HashiCorp Vault K/V Secret instead of as file on Dgraph Alpha. To use HashiCorp Vault, meet the following prerequisites for the Vault Server.-
Ensure that the Vault server is accessible from Dgraph Alpha and configured
using URL
http://fqdn[ip]:port
. - Enable AppRole Auth method and enable KV Secrets Engine.
-
Save the value of the key (16, 24, or 32 bytes long) that Dgraph Alpha uses
in a KV Secret path
(K/V Version 1 or
K/V Version 2). For
example, you can upload this below to KV Secrets Engine Version 2 path of
secret/data/dgraph/alpha
: -
Create or use a role with an attached policy that grants access to the
secret. For example, the following policy would grant access to
secret/data/dgraph/alpha
: -
Using the
role_id
generated from the previous step, create a correspondingsecret_id
, and copy therole_id
andsecret_id
over to local files, like./dgraph/vault/role_id
and./dgraph/vault/secret_id
, thatâs used by Dgraph Alpha nodes.
The key format for the
enc-field
option can be defined using enc-format
with the values base64
(default) or raw
.Example using Dgraph CLI with HashiCorp Vault configuration
The following example shows how to use Dgraph with a Vault server that holds the encryption key:--encryption key-file
flag or the --vault
superflag with appropriate
superflag options to each of the Dgraph Alpha nodes.
After an Alpha node has encryption enabled, you must provide the encryption key
to start the Alpha server. If the Alpha server restarts, the
--encryption key-file
or the --vault
superflagâs options must be set along
with the key to restart successfully.
Turn off encryption
You can use Live Loader or Bulk Loader to decrypt the data while importing.Change encryption key
The master encryption key set by the--encryption key-file
option (or one used
in Vault KV store) doesnât change automatically. The master encryption key
encrypts underlying data keys which are changed on a regular basis
automatically (more info about this is covered on the encryption-at-rest
blog post).
Changing the existing key to a new one is called key rotation. You can rotate
the master encryption key by using the badger rotate
command on both p and w
directories for each Alpha. To maintain availability in HA cluster
configurations, you can do this rotate the key one Alpha at a time in a rolling
manner.
Youâll need both the current key and the new key in two different files. Specify
the directory you rotate (âpâ or âwâ) for the --dir
flag, the old key for the
--old-key-path
flag, and the new key with the --new-key-path
flag.
new_enc_key_file
key file to use the new
key.