Take and Restore Encrypted Backups

On this page

This doc provides information about how to take and restore encrypted backups in the following ways:

• Using AWS Key Management Service (KMS)
• Using a passphrase

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>&REGION=<region>

The AWS URI requires the following:

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}&REGION=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&REGION=us-east-1',
      'aws:///<cmk>?AUTH=implict&REGION=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}&REGION=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.

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 using AUTH=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 ....

See also

• BACKUP
• RESTORE
• Take Full and Incremental Backups
• Take and Restore Locality-aware Backups
• Take Backups with Revision History and Restore from a Point-in-time
• SQL DUMP
• IMPORT
• Use the Built-in SQL Client
• Other Cockroach Commands

Was this helpful?