diff --git a/src/current/v23.1/take-and-restore-encrypted-backups.md b/src/current/v23.1/take-and-restore-encrypted-backups.md index 1da266441ef..93806d67c73 100644 --- a/src/current/v23.1/take-and-restore-encrypted-backups.md +++ b/src/current/v23.1/take-and-restore-encrypted-backups.md @@ -20,13 +20,15 @@ This doc provides information about how to take and restore encrypted backups in ## Use Key Management Service -You can encrypt full or incremental backups with AWS KMS, Google Cloud KMS, or Azure Key Vault by using the [`kms` option]({% link {{ page.version.version }}/backup.md %}#options). 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 KMS URI(s) and stored alongside the `BACKUP` data in an `ENCRYPTION_INFO` file, which is used when restoring the backed-up data. +You can encrypt [full or incremental backups]({% link {{ page.version.version }}/take-full-and-incremental-backups.md %}) with AWS KMS, Google Cloud KMS, or Azure Key Vault by using the [`kms` option]({% link {{ page.version.version }}/backup.md %}#options). -On [`RESTORE`]({% link {{ page.version.version }}/restore.md %}), 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`]({% link {{ page.version.version }}/show-backup.md %}#show-an-encrypted-backup). +During the [backup process]({% link {{ page.version.version }}/backup-architecture.md %}), a cryptographically secure 32-byte (256-bit) key is generated. Individual data files are encrypted with the backup-specific random key using AES-GCM-256. This backup-specific random key is then encrypted using the Key Management Service (KMS) APIs provided by the relevant cloud provider—AWS KMS, Google Cloud KMS, or Azure Key Vault. The resulting encrypted version of the random key is then stored within the backup metadata in the `ENCRYPTION_INFO` file. -When used with [incremental backups]({% link {{ page.version.version }}/take-full-and-incremental-backups.md %}#incremental-backups), the `kms` option is applied to all the [backup file URLs]({% link {{ page.version.version }}/backup.md %}#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]({% link {{ page.version.version }}/take-and-restore-locality-aware-backups.md %}), the KMS URI provided is applied to files in all localities. +Note that the encryption algorithm for the random key is determined by the specific cloud provider. [AWS](https://docs.aws.amazon.com/kms/latest/developerguide/concepts.html#symmetric-cmks) and [GCP](https://cloud.google.com/kms/docs/algorithms#symmetric_encryption_algorithms) use symmetric encryption with [AES-GCM-256](https://en.wikipedia.org/wiki/Galois/Counter_Mode). [Azure](https://learn.microsoft.com/en-us/azure/security/fundamentals/encryption-atrest) uses asymmetric encryption with RSA-OAEP-256. -For more information about AWS KMS, see the [documentation](https://aws.amazon.com/kms/). For more information about Google Cloud KMS, see the [documentation](https://cloud.google.com/kms/docs). +During a restore job, CockroachDB retrieves the encrypted random key from the backup metadata and attempts to decrypt it using the KMS URI specified in the [`RESTORE`]({% link {{ page.version.version }}/restore.md %}) statement. Once successfully decrypted, CockroachDB uses this key to decrypt the [`BACKUP`]({% link {{ page.version.version }}/backup.md %}) manifest and data files. Similarly, the same KMS URI is required for decrypting the files when listing the backup contents using [`SHOW BACKUP`]({% link {{ page.version.version }}/show-backup.md %}). + +When incremental backups are in use, the `kms` option is applied to all backup file URLs. Therefore, each incremental backup must include at least one of the KMS URIs used during the full backup. This subset can consist of any combination of the original URIs, but you cannot introduce new KMS URIs. Likewise, when taking [locality-aware backups](#locality-aware-backup-with-kms-encryption), the specified KMS URI is applied to files across all localities. ### Generate a KMS key @@ -36,7 +38,7 @@ Before you can use a KMS to encrypt a CockroachDB backup, you must first generat CockroachDB also supports [kms encryption](#take-a-locality-aware-backup-with-kms-encryption) for your locality-aware backup. At the time of `BACKUP`, you can [provide multiple KMS URIs](#aws-kms-uri-format), each referencing a KMS key in a different region. This allows CockroachDB to save multiple versions of the encrypted data key used to encrypt the backup data, one per 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 KMS keys from the other regions. -#### Add a new KMS key to an existing backup +### Add a new KMS key to an existing backup To add a new KMS key to an existing backup, use the [`ALTER BACKUP`]({% link {{ page.version.version }}/alter-backup.md %}) statement. `ALTER BACKUP` allows for new KMS encryption keys to be applied to an existing chain of encrypted backups (full and incremental). Once completed, subsequent `BACKUP`, `RESTORE`, and [`SHOW BACKUP`]({% link {{ page.version.version }}/show-backup.md %}) statements can use any of the existing or new KMS URIs to decrypt the backup. @@ -154,7 +156,7 @@ BACKUP INTO 's3://{BUCKET NAME}?AWS_ACCESS_KEY_ID={KEY ID}&AWS_SECRET_ACCESS_KEY #### Take a locality-aware backup with kms encryption -To take a [locality-aware backup with kms encryption](#locality-aware-backup-with-kms-encryption), use the `kms` option to specify a comma-separated list of KMS URIs: +To take a [locality-aware backup]({% link {{ page.version.version }}/take-and-restore-locality-aware-backups.md %}) with kms encryption, use the `kms` option to specify a comma-separated list of KMS URIs: {% include_cached copy-clipboard.html %} ~~~ sql diff --git a/src/current/v23.2/take-and-restore-encrypted-backups.md b/src/current/v23.2/take-and-restore-encrypted-backups.md index ebda739f1e5..f999949fd80 100644 --- a/src/current/v23.2/take-and-restore-encrypted-backups.md +++ b/src/current/v23.2/take-and-restore-encrypted-backups.md @@ -20,13 +20,15 @@ This doc provides information about how to take and restore encrypted backups in ## Use Key Management Service -You can encrypt full or incremental backups with AWS KMS, Google Cloud KMS, or Azure Key Vault by using the [`kms` option]({% link {{ page.version.version }}/backup.md %}#options). 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 KMS URI(s) and stored alongside the `BACKUP` data in an `ENCRYPTION_INFO` file, which is used when restoring the backed-up data. +You can encrypt [full or incremental backups]({% link {{ page.version.version }}/take-full-and-incremental-backups.md %}) with AWS KMS, Google Cloud KMS, or Azure Key Vault by using the [`kms` option]({% link {{ page.version.version }}/backup.md %}#options). -On [`RESTORE`]({% link {{ page.version.version }}/restore.md %}), 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`]({% link {{ page.version.version }}/show-backup.md %}#show-an-encrypted-backup). +During the [backup process]({% link {{ page.version.version }}/backup-architecture.md %}), a cryptographically secure 32-byte (256-bit) key is generated. Individual data files are encrypted with the backup-specific random key using AES-GCM-256. This backup-specific random key is then encrypted using the Key Management Service (KMS) APIs provided by the relevant cloud provider—AWS KMS, Google Cloud KMS, or Azure Key Vault. The resulting encrypted version of the random key is then stored within the backup metadata in the `ENCRYPTION_INFO` file. -When used with [incremental backups]({% link {{ page.version.version }}/take-full-and-incremental-backups.md %}#incremental-backups), the `kms` option is applied to all the [backup file URLs]({% link {{ page.version.version }}/backup.md %}#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]({% link {{ page.version.version }}/take-and-restore-locality-aware-backups.md %}), the KMS URI provided is applied to files in all localities. +Note that the encryption algorithm for the random key is determined by the specific cloud provider. [AWS](https://docs.aws.amazon.com/kms/latest/developerguide/concepts.html#symmetric-cmks) and [GCP](https://cloud.google.com/kms/docs/algorithms#symmetric_encryption_algorithms) use symmetric encryption with [AES-GCM-256](https://en.wikipedia.org/wiki/Galois/Counter_Mode). [Azure](https://learn.microsoft.com/en-us/azure/security/fundamentals/encryption-atrest) uses asymmetric encryption with RSA-OAEP-256. -For more information about AWS KMS, see the [documentation](https://aws.amazon.com/kms/). For more information about Google Cloud KMS, see the [documentation](https://cloud.google.com/kms/docs). +During a restore job, CockroachDB retrieves the encrypted random key from the backup metadata and attempts to decrypt it using the KMS URI specified in the [`RESTORE`]({% link {{ page.version.version }}/restore.md %}) statement. Once successfully decrypted, CockroachDB uses this key to decrypt the [`BACKUP`]({% link {{ page.version.version }}/backup.md %}) manifest and data files. Similarly, the same KMS URI is required for decrypting the files when listing the backup contents using [`SHOW BACKUP`]({% link {{ page.version.version }}/show-backup.md %}). + +When incremental backups are in use, the `kms` option is applied to all backup file URLs. Therefore, each incremental backup must include at least one of the KMS URIs used during the full backup. This subset can consist of any combination of the original URIs, but you cannot introduce new KMS URIs. Likewise, when taking [locality-aware backups](#locality-aware-backup-with-kms-encryption), the specified KMS URI is applied to files across all localities. ### Generate a KMS key @@ -36,7 +38,7 @@ Before you can use a KMS to encrypt a CockroachDB backup, you must first generat CockroachDB also supports [kms encryption](#take-a-locality-aware-backup-with-kms-encryption) for your locality-aware backup. At the time of `BACKUP`, you can [provide multiple KMS URIs](#aws-kms-uri-format), each referencing a KMS key in a different region. This allows CockroachDB to save multiple versions of the encrypted data key used to encrypt the backup data, one per 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 KMS keys from the other regions. -#### Add a new KMS key to an existing backup +### Add a new KMS key to an existing backup To add a new KMS key to an existing backup, use the [`ALTER BACKUP`]({% link {{ page.version.version }}/alter-backup.md %}) statement. `ALTER BACKUP` allows for new KMS encryption keys to be applied to an existing chain of encrypted backups (full and incremental). Once completed, subsequent `BACKUP`, `RESTORE`, and [`SHOW BACKUP`]({% link {{ page.version.version }}/show-backup.md %}) statements can use any of the existing or new KMS URIs to decrypt the backup. @@ -154,7 +156,7 @@ BACKUP INTO 's3://{BUCKET NAME}?AWS_ACCESS_KEY_ID={KEY ID}&AWS_SECRET_ACCESS_KEY #### Take a locality-aware backup with kms encryption -To take a [locality-aware backup with kms encryption](#locality-aware-backup-with-kms-encryption), use the `kms` option to specify a comma-separated list of KMS URIs: +To take a [locality-aware backup]({% link {{ page.version.version }}/take-and-restore-locality-aware-backups.md %}) with kms encryption, use the `kms` option to specify a comma-separated list of KMS URIs: {% include_cached copy-clipboard.html %} ~~~ sql