Encryption at rest

Encrypt your YugabyteDB cluster

Encryption at rest →  across different products

YugabyteDB YugabyteDB YugabyteDB Anywhere YugabyteDB Anywhere YugabyteDB Aeon YugabyteDB Aeon

For added security, you can encrypt your clusters (including backups) using a customer managed key (CMK) residing in a cloud provider Key Management Service (KMS). You grant YugabyteDB Aeon access to the key with the requisite permissions to perform cryptographic operations using the key to secure the databases in your clusters.

You can enable YugabyteDB EAR for a cluster as follows:

  • On the Security page of the Create Cluster wizard when you create your cluster.
  • On the cluster Settings tab under Encryption at rest (database version 2.16.7 and later only).

Note that, regardless of whether you enable YugabyteDB EAR for a cluster, YugabyteDB Aeon uses volume encryption for all data at rest, including your account data, your clusters, and their backups. Data is AES-256 encrypted using native cloud provider technologies - S3 and EBS volume encryption for AWS, Azure disk encryption, and server-side and persistent disk encryption for GCP. Volume encryption keys are managed by the cloud provider and anchored by hardware security appliances.

How the CMK encrypts the cluster

The CMK you create in your cloud provider KMS does not encrypt cluster data directly. The CMK is the master key. It encrypts (wraps) each universe (cluster) key. YugabyteDB Aeon keeps those wrapped copies, and backup metadata includes them.

A universe key protects data on disk by encrypting the data encryption key (DEK) for each data file. The cluster keeps a registry of universe keys, encrypted with the latest universe key. YugabyteDB Aeon generates the universe keys. You do not create them in AWS, Azure, or GCP. For the full key hierarchy, refer to Encryption at rest in YugabyteDB Anywhere. (Note that Anywhere uses the same key names and calls a cluster a universe.)

Limitations

  • You can't enable cluster EAR on clusters with YugabyteDB versions earlier than 2.16.7.

  • Enabling EAR can impact cluster performance. You should monitor your workload after enabling this feature.

Prerequisites

To use AWS KMS, you need the following:

  • Single-region symmetric encryption key created in AWS KMS. The key resource policy should include the following actions:
    • kms:Encrypt
    • kms:Decrypt
    • kms:GenerateDataKeyWithoutPlaintext
    • kms:DescribeKey
    • kms:ListAliases
  • Amazon Resource Name (ARN) of the CMK. For more information, refer to Amazon Resource Names in the AWS documentation.
  • An access key for an IAM identity with permission to encrypt and decrypt using the CMK. An access key consists of an access key ID and the secret access key. For more information, refer to Managing access keys for IAM users in the AWS documentation.

For more information on AWS KMS, refer to AWS Key Management Service in the AWS documentation.

Create a key vault using the Azure portal. The following settings are required:

  • Set the vault permission model as Vault access policy.

  • Add the application to the key vault access policies with the minimum key management operations permissions of Get and Create (unless you are pre-creating the key), as well as cryptographic operations permissions of Unwrap Key and Wrap Key.

    Required permissions are as follows:

    "permissions": [ {
    "actions": [
      "Microsoft.KeyVault/vaults/keys/read",
      "Microsoft.KeyVault/vaults/read"
    ],
    "notActions": [],
    "dataActions": [
      "Microsoft.KeyVault/vaults/keys/read",
      "Microsoft.KeyVault/vaults/keyrotationpolicies/read",
      "Microsoft.KeyVault/vaults/keys/wrap/action",
      "Microsoft.KeyVault/vaults/keys/unwrap/action"
    ],
    "notDataActions": []
} ]

If you are planning to use an existing cryptographic key with the same name, it must meet the following criteria:

  • The primary key version should be in the Enabled state.
  • The activation date should either be disabled or set to a date before the KMS configuration creation.
  • The expiration date should be disabled.
  • Permitted operations should have at least WRAP_KEY and UNWRAP_KEY.
  • The key rotation policy should not be defined in order to avoid automatic rotation.

In addition, you need the client ID and secret for an application registered in Azure with permission to encrypt and decrypt using the CMK. Refer to Create a new client secret in the Microsoft documentation.

For more information, refer to the Azure Key Vault documentation.

To use Cloud KMS, you need the following:

  • CMK (AKA customer-managed encryption key or CMEK) created in Cloud KMS.
  • Cloud KMS resource ID. You can copy the resource ID from KMS Management page in the Google Cloud console. Do not include the key version. For more information, refer to Getting a Cloud KMS resource ID in the GCP documentation.
  • A service account that has been granted the following permissions on the CMK:
    • cloudkms.keyRings.get
    • cloudkms.cryptoKeys.get
    • cloudkms.cryptoKeyVersions.useToEncrypt
    • cloudkms.cryptoKeyVersions.useToDecrypt
    • cloudkms.locations.generateRandomBytes
  • Service account credentials. These credentials are used to authorize your use of the CMK. This is the key file (JSON) that you downloaded when creating credentials for the service account. For more information, refer to Create credentials for a service account in the GCP documentation.

For more information on GCP KMS, refer to Cloud Key Management Service overview in the GCP documentation.

Encrypt a cluster using a CMK

You can enable EAR using a CMK for clusters (database version 2.16.7 and later only) as follows:

  1. On the cluster Settings tab, select Encryption at rest.
  2. Click Enable Cluster Encryption at Rest.
  3. Enter the Amazon Resource Name (ARN) of the CMK to use to encrypt the cluster.
  4. Provide an access key of an IAM identity with permissions for the CMK. An access key consists of an access key ID and the secret access key.

You can enable EAR using a CMK for clusters (database version 2.16.7 and later only) as follows:

  1. On the cluster Settings tab, select Encryption at rest.
  2. Click Enable Cluster Encryption at Rest.
  3. Provide the Azure tenant ID, the vault URI (for example, https://myvault.vault.azure.net), and the name of the key.
  4. Enter the client ID and secret for an application with permission to encrypt and decrypt using the CMK.

You can enable EAR using a CMK for clusters (database version 2.16.7 and later only) as follows:

  1. On the cluster Settings tab, select Encryption at rest.
  2. Click Enable Cluster Encryption at Rest.
  3. Enter the resource ID of the key ring where the CMK is stored.
  4. Click Add Key to select the credentials JSON file you downloaded when creating credentials for the service account that has permissions to encrypt and decrypt using the CMK.

Click Save when you are done.

YugabyteDB Aeon validates the CMK and, if successful, generates a universe key and starts encrypting the data. Only new data is encrypted. Existing data remains unencrypted until compaction rewrites it under that universe key. You cannot see what fraction of existing data has been rewritten. To force a full rewrite, contact Yugabyte Support.

To disable cluster EAR, click Disable Encryption at Rest. YugabyteDB Aeon uses lazy decryption to decrypt the cluster.

Rotate your CMK

When you edit the CMK configuration, YugabyteDB Aeon rotates the master key (your CMK) only. The existing universe keys stay in place. See How the CMK encrypts the cluster.

Deleting your CMK

Deleting the CMK that is currently configured makes YugabyteDB Aeon unable to unwrap the universe keys it stores for the cluster, including the copies recorded in backup metadata. As a result you will no longer be able to decrypt clusters or backups encrypted using the key.

You can remove a previous CMK after every full and incremental backup taken before the key rotation has passed its retention period and been deleted. The cluster keeps a record that it used that CMK. Removing the key from your cloud KMS does not delete that record.

For example, if your oldest backup from before the rotation expires 30 days from now, keep the previous CMK for 30 days. Keep it for at least as long as your backup retention period.

To rotate the CMK used for EAR, do the following:

  1. On the cluster Settings tab, select Encryption at rest.

  2. Click Edit CMK Configuration.

  3. For AWS, provide the following details:

    • Customer managed key (CMK): Enter the Amazon Resource Name (ARN) of the new CMK to use to encrypt the cluster.
    • Access key: Provide an access key of an IAM identity with permissions for the CMK. An access key consists of an access key ID and the secret access key.

    For Azure, provide the following details:

    • Provide the Azure tenant ID, the vault URI (for example, https://myvault.vault.azure.net), and the name of the new key.
    • Enter the client ID and secret for the application with permission to encrypt and decrypt using the CMK.

    For GCP:

    • Resource ID: Enter the resource ID of the key ring where the new CMK is stored.
    • Service Account Credentials: Click Add Key to select the credentials JSON file you downloaded when creating credentials for the service account that has permissions to encrypt and decrypt using the CMK.

  4. Click Save.

YugabyteDB Aeon then does the following:

  • Every universe key that YugabyteDB Aeon stores for the cluster is re-wrapped with the new CMK immediately, including keys that still protect files compaction has not rewritten. No new universe key is generated. Backups taken after the rotation record those re-wrapped keys, so restoring them requires the new CMK. The cluster's universe key registry and the data on disk stay as they are.
  • The previous CMK is still required to restore backups taken before the rotation.