This doc provides information about how to take and restore encrypted backups in the following ways:
Encrypted BACKUP
is an Enterprise-only feature. However, you can take full backups without an Enterprise license.
Use AWS Key Management Service
You can encrypt full or incremental backups with AWS Key Management Service (KMS) by using the kms
option. Files written by the backup (BACKUP
manifest and data files) are encrypted using a 256-bit crypto-random generated data key. This data key is encrypted with the provided AWS KMS URI(s) and stored alongside the BACKUP
data in an ENCRYPTION_INFO
file, which is used when restoring the backed-up data.
On RESTORE
, CockroachDB reads the ENCRYPTION_INFO
file and attempts to decrypt the encrypted data key using the KMS URI provided in the RESTORE
statement. Once CockroachDB successfully obtains the unencrypted data key, the BACKUP
manifest and data files will be decrypted and the restoration will proceed. Similarly, the same KMS URI is needed to decrypt the file to list the contents of the backup when using SHOW BACKUP
.
When used with incremental backups, the kms
option is applied to all the backup file URLs, which means each incremental must include at least one of the KMS URIs used to take the full backup. It can be any subset of the original URIs, but you cannot include any new KMS URIs. Similarly, when used with locality-aware backups, the KMS URI provided is applied to files in all localities.
For more information about AWS KMS, see the documentation.
Generate a customer master key (CMK)
Before you can use AWS KMS to encrypt a CockroachDB backup, you must first generate a customer master key (CMK). This is the master key generated by AWS KMS and it never leaves the KMS. It contains key-related metadata and key material to encrypt/decrypt other data. The key material can never be exported, deleted, or extracted. CockroachDB expects the CMK to be symmetric (256 bit).
There is also the option to use multi-region encryption on your data. At the time of BACKUP
, you can provide multiple AWS KMS URIs, each referencing a CMK in a different AWS region. This allows CockroachDB to save multiple versions of the encrypted data key used to encrypt the backup data, one per AWS KMS URI. With these encrypted versions of the data key stored alongside the encrypted backup data, a user can RESTORE
the encrypted data using any one of the KMS URIs that were supplied during backup. In the case of a single KMS region outage, the data can be decrypted with any of the CMKs from the other regions.
AWS KMS URI format
The AWS KMS URI must use the following format:
aws:///<cmk>?AUTH=<auth_type>®ION=<region>
The AWS URI requires the following:
Component | Description |
---|---|
aws:/// |
The AWS scheme. Note the triple slash (/// ). |
<cmk> |
The key identifiers used to reference the CMK that should be used to encrypt or decrypt. For information about the supported formats, see the AWS KMS docs. |
AUTH=<auth_type> |
The user-specified credentials.
|
REGION=<region> |
The region of the CMK. |
See below for examples.
Examples
- Take an encrypted backup with AWS KMS
- Take a backup with multi-region encryption
- Restore from an encrypted backup with AWS KMS
Take an encrypted backup with AWS KMS
To take an encrypted backup with AWS KMS, use the kms
option:
> BACKUP INTO 's3://{BUCKET NAME}/{PATH}?AWS_ACCESS_KEY_ID={KEY ID}&AWS_SECRET_ACCESS_KEY={SECRET ACCESS KEY}'
WITH kms = 'aws:///<cmk>?AWS_ACCESS_KEY_ID={KEY ID}&AWS_SECRET_ACCESS_KEY={SECRET ACCESS KEY}®ION=us-east-1';
job_id | status | fraction_completed | rows | index_entries | bytes
---------------------+-----------+--------------------+------+---------------+----------
594193600274956289 | succeeded | 1 | 2689 | 1217 | 1420108
(1 row)
Take a backup with multi-region encryption
To take a backup with multi-region encryption, use the kms
option to specify a comma-separated list of KMS URIs:
> BACKUP INTO 's3://{BUCKET NAME}/{PATH}?AWS_ACCESS_KEY_ID={KEY ID}&AWS_SECRET_ACCESS_KEY={SECRET ACCESS KEY}'
WITH KMS=(
'aws:///<cmk>?AUTH=implicit®ION=us-east-1',
'aws:///<cmk>?AUTH=implict®ION=us-west-1'
);
job_id | status | fraction_completed | rows | index_entries | bytes
---------------------+-----------+--------------------+------+---------------+--------
594471427115220993 | succeeded | 1 | 20 | 2 | 1026
(1 row)
Restore from an encrypted backup with AWS KMS
To decrypt an encrypted backup, use the kms
option and any subset of the KMS URIs that was used to take the backup.
For example, the encrypted backup created in the first example can be restored with:
> RESTORE FROM LATEST IN 's3://{BUCKET NAME}/{PATH}?AWS_ACCESS_KEY_ID={KEY ID}&AWS_SECRET_ACCESS_KEY={SECRET ACCESS KEY}'
WITH kms = 'aws:///<cmk>?AWS_ACCESS_KEY_ID={KEY ID}&AWS_SECRET_ACCESS_KEY={SECRET ACCESS KEY}®ION=us-east-1';
job_id | status | fraction_completed | rows | index_entries | bytes
---------------------+-----------+--------------------+------+---------------+----------
594193600274956291 | succeeded | 1 | 2689 | 1217 | 1420108
(1 row)
To restore from a specific backup, use RESTORE FROM {subdirectory} IN ...
.
Use a passphrase
You can encrypt full or incremental backups with a passphrase by using the encryption_passphrase
option. Files written by the backup (including BACKUP
manifests and data files) are encrypted using the specified passphrase to derive a key. To restore the encrypted backup, the same encryption_passphrase
option (with the same passphrase) must be included in the RESTORE
statement.
When used with incremental backups, the encryption_passphrase
option is applied to all the backup file URLs, which means the same passphrase must be used when appending another incremental backup to an existing backup. Similarly, when used with locality-aware backups, the passphrase provided is applied to files in all localities.
Encryption is done using AES-256-GCM, and GCM is used to both encrypt and authenticate the files. A random salt is used to derive a once-per-backup AES key from the specified passphrase, and then a random initialization vector is used per-file. CockroachDB uses PBKDF2 with 64,000 iterations for the key derivation.
BACKUP
and RESTORE
will use more memory when using encryption, as both the plain-text and cipher-text of a given file are held in memory during encryption and decryption.
For an example of an encrypted backup, see Create an encrypted backup.
Examples
The following examples make use of:
- Amazon S3 connection strings. For guidance on connecting to other storage options or using other authentication parameters instead, read Use Cloud Storage for Bulk Operations.
- The default
AUTH=specified
parameter. For guidance on usingAUTH=implicit
authentication with Amazon S3 buckets instead, read Use Cloud Storage for Bulk Operations — Authentication.
Take an encrypted backup using a passphrase
To take an encrypted backup, use the encryption_passphrase
option:
> BACKUP INTO 's3://{BUCKET NAME}/{PATH}?AWS_ACCESS_KEY_ID={KEY ID}&AWS_SECRET_ACCESS_KEY={SECRET ACCESS KEY}' WITH encryption_passphrase = 'password123';
job_id | status | fraction_completed | rows | index_entries | bytes
---------------------+-----------+--------------------+------+---------------+---------
543214409874014209 | succeeded | 1 | 2597 | 1028 | 467701
(1 row)
To restore, use the same encryption_passphrase
. See the example below for more details.
Restore from an encrypted backup using a passphrase
To decrypt an encrypted backup, use the encryption_passphrase
option option and the same passphrase that was used to create the backup.
For example, the encrypted backup created in the previous example can be restored with:
> RESTORE FROM LATEST IN 's3://{BUCKET NAME}/{PATH}?AWS_ACCESS_KEY_ID={KEY ID}&AWS_SECRET_ACCESS_KEY={SECRET ACCESS KEY}' WITH encryption_passphrase = 'password123';
job_id | status | fraction_completed | rows | index_entries | bytes
---------------------+-----------+--------------------+------+---------------+---------
543217488273801217 | succeeded | 1 | 2597 | 1028 | 467701
(1 row)
To restore from a specific backup, use RESTORE FROM {subdirectory} IN ...
.