Customer-Managed Encryption Keys (CMEK)

Customer-Managed Encryption Keys (CMEK) allow you to protect data at rest in a CockroachDB Dedicated private cluster using a cryptographic key that is entirely within your control, hosted in a supported cloud provider key-management system (KMS). This key is called the CMEK key.

You can manage your CMEK keys using one or more of the following services:

• Amazon Web Services (AWS) KMS
• Google Cloud Platform (GCP) KMS

To learn more, visit Managing Customer-Managed Encryption Keys (CMEK) for CockroachDB Dedicated.

CockroachDB Dedicated includes support for referring to CMEK keys in Hashicorp Vault Secrets Manager, which can distribute keys stored in multiple KMS systems, as long as the actual keys are stored in AWS KMS or GCP KMS.

CockroachDB Cloud communicates with the KMS platform using the KMS platform's API, and you manage CockroachDB Cloud's access to the CMEK key using the KMS platform's identity and access management (IAM) system. The CMEK key is never present in a cluster and CockroachDB Cloud never has direct access to the CMEK key material. When CMEK is enabled, the CMEK key must be available before the cluster can start and the cluster's newly-written data at rest can be accessed.

This article describes how CMEK works in CockroachDB Dedicated clusters. To configure CMEK, see Managing Customer-Managed Encryption Keys (CMEK) for CockroachDB Dedicated.

Benefits of CMEK

This section describes some of the ways that CMEK can help you protect your data and meet business and regulatory requirements, even when you don't own the underlying infrastructure that hosts your data.

• Enforcement of data retention policies: To ensure that a cluster's data is permanently inaccessible, you can destroy the CMEK key or keys that protect its data.

  Warning:

  Keep these points in mind before destroying a CMEK key:

  • If a CMEK key is destroyed, the cluster's data can't be recovered by you or by CockroachDB Cloud, even by restoring from a CockroachDB Cloud-managed backup. Consider disabling the CMEK key initially instead, so you can restore it if disabling it leads to unexpected results. To take or restore from an encrypted backup using database commands, visit [Take and Restore Encrypted Backups](/docs/v22.2/take-and-restore-encrypted-backups.html).

  • To protect against inadvertent data loss, your KMS platform may impose a waiting period before a key is permanently deleted. Check the documentation for your KMS platform for details about how long before a key deletion is permanent and irreversible.

• Enforcement of data domiciling and locality requirements: In a multi-region cluster, you can confine an individual database to a single region or multiple regions. For more information and limitations, see Data Domiciling with CockroachDB. When you enable CMEK on a multi-region cluster, you can optionally assign a separate CMEK key to each region, or use the same CMEK key for multiple related regions.

• Enforcement of encryption requirements: With CMEK, you have control the CMEK key's encryption strength. The CMEK key's size is determined by what your KMS provider supports.

  You can use your KMS platform's controls to configure the regions where the CMEK key is available, enable automatic rotation schedules for CMEK keys, and view audit logs that show each time the CMEK key is used by CockroachDB Cloud. CockroachDB Cloud does not need any visibility into these details.

• Infrastructure flexibility: If your CMEK keys are stored in multiple KMS systems or tenants, you can use Hashicorp Vault Key Management Secrets Engine to give your cluster access to your CMEK keys, as long as the cluster and keys are stored in the same deployment environment (GCP or AWS).

The following example shows some of the ways that CMEK can help you meet business and regulatory requirements.

Imagine that you have a business requirement to verify that a cluster's data is inaccessible when you delete the cluster. Software as a Service (SaaS) makes such requirements more difficult to verifiably meet, because you don't have visibility into what happens to the cluster's resources after the cluster disappears from your view. This sort of requirement might make it more challenging for your organization to move some workloads to SaaS.

CMEK helps you to enforce such business rules on CockroachDB Cloud clusters. With CMEK, you can actively and verifiably enforce this requirement without waiting for CockroachDB Cloud to destroy the cluster's resources. Instead, with a single operation you can revoke the cluster's ability to use the CMEK key. This will trigger a cluster restart, and the restart will fail because the CMEK key is unavailable. After verifying that the restart has failed, you can delete the cluster in CockroachDB Cloud.

How CMEK works

When you create a CockroachDB Dedicated cluster, its data at rest on cluster disks is not encrypted by default. However, the disks themselves are automatically encrypted by cryptographic keys owned and managed by the cloud providers themselves.

When you enable CMEK on a CockroachDB Dedicated private cluster, CockroachDB Cloud creates two kinds of encryption keys and begins to use them to protect newly-written data at rest. CockroachDB Cloud manages these encryption keys and propagates them to cluster nodes.

1. The data key is a Data Encryption Key (DEK), and is used to encrypt and decrypt cluster data before it is read from or written to disks attached to a cluster's nodes. Each time the cluster is started or restarted, and each time a node and related disks are added to a cluster, CockroachDB Dedicated uses the store key to encrypt and decrypt data keys. Each cluster node maintains its own list of data keys. The data key is automatically rotated monthly and is always encrypted at rest by the store key.

2. The store key is a Key Encryption Key (KEK) that encrypts the data keys at rest. It is encrypted at rest by the CMEK key before being propagated to cluster nodes, and is decrypted in memory on each node when the cluster starts. The store key is not automatically rotated.

For more details about encryption in CockroachDB Cloud, see Encryption At Rest.

Enabling CMEK has no impact on a cluster's existing data.

At the time that you enable CMEK for a cluster, CockroachDB Cloud:

1. Creates the store key and encrypts it using the CMEK key.
2. Creates the data key and encrypts it using the encrypted store key.
3. Propagates the store key and data key to cluster nodes.
4. Starts the cluster.

Going forward:

1. The cluster can start only when the CMEK key is available to decrypt the store key. If the CMEK key becomes unavailable or you revoke the cluster's access to the key, the cluster can't start until access is restored.
2. Each time the store key is rotated, the new store key is also encrypted using the CMEK key.
3. Each time the data key is rotated, the new data key is encrypted using the encrypted store key.
4. Each time a node writes new data to disk, it is encrypted using the current data key. Data is read using the data key that was used to encrypt it.

Rotation of a CMEK key

You can rotate a CMEK key for a CockroachDB Dedicated cluster either by creating a new version of the existing CMEK key or by creating a new CMEK key. At a high level:

To begin using a new version of an existing CMEK key:

1. In your KMS platform, you can either configure automatic rotation for the CMEK key, or you can perform a manual rotation.
2. CockroachDB Cloud does not automatically re-encrypt the store key using the new CMEK key version. For each region you want to update, you must also perform a rotation using the CockroachDB Cloud API without modifying the CMEK key URI. CockroachDB Cloud re-encrypts the store key using the new CMEK key version.

To begin using an entirely new CMEK key:

1. Within your KMS platform, you create a new CMEK key.
2. Next, you perform a rotation using the CockroachDB Cloud API and provide the new CMEK key URI.

To learn more about rotating a CMEK key using the CockroachDB Cloud API, visit Rotate a CMEK key.

Backup and restore operations on a cluster with CMEK

This section describes how enabling CMEK changes backup and restore operations on a cluster.

Backups in CockroachDB Dedicated are triggered in two ways, only one of which is affected by CMEK.

• You can perform a manual backup by using the BACKUP SQL command to back up database objects in a cluster. To restore from a manual backup, you use the RESTORE SQL command. Manual backups are not automatically encrypted, but you can optionally encrypt a manual backup by specifying an encryption key when you run the BACKUP command. Enabling CMEK has no impact on manual backups. To learn about encrypting manual backups, see Take and Restore Encrypted Backups.

• CockroachDB Cloud automatically backs up clusters on a set schedule that is not configurable. You can view, manage, or restore from these backups using the CockroachDB Cloud Console. Managed backups operate on all databases, tables, views, and scheduled jobs in the cluster. Managed backups can be restored only to the cluster where they were taken. Managed backups are automatically encrypted using data keys that are distinct from those used to encrypt the cluster's data.

When CMEK is enabled for a cluster, managed backups change in the following ways:

• You can no longer restore from a managed backup that was taken before CMEK was enabled.
• The data keys used to encrypt managed backups in CockroachDB Cloud are encrypted using the CMEK key before being written to persistent storage.
• The CMEK key must be available before you can restore from an automatic backup.

Limitations

The CMEK feature has the following limitations:

• CMEK can be enabled only on clusters created after April 1, 2022 (AWS) or June 9, 2022 (GCP).
• The cluster must be a private cluster. Refer to Create Private Clusters
• To enable or revoke CMEK on a cluster, you must use the Cloud API. It's not possible to enable CMEK using the CockroachDB Cloud Console.
• If you add a new region to a cluster with CMEK enabled, the new region will not be automatically protected by the CMEK key.

See also

• Managing Customer-Managed Encryption Keys (CMEK) for CockroachDB Dedicated
• Customer-Managed Encryption Keys (CMEK) Frequently Asked Questions (FAQ)
• Create Private Clusters
• Encryption At Rest