BYOK AWS with Astra DB console

Encryption is a widely accepted mechanism to secure data against breaches. By default, DataStax Astra DB encrypts data, and cloud providers such as AWS offer encryption solutions. However, you may want to further limit data access, because cloud providers have access to the keys and ultimately to the data.

To address this security concern, Astra DB allows you to associate a Customer Managed Key (one per region) that you defined in the AWS Key Management Service (KMS) with a Customer Key that you create in Astra DB.

In this topic, we’ll use these terms:

  • Bring Your Own Key (BYOK) refers to the overall capability.

  • Customer Managed Key (CMK) refers to a particular key type in the AWS Key Management Service (KMS).

  • Customer Key refers to the corresponding key association in Astra DB.

This BYOK feature:

  • Is available for serverless Astra DB databases with these cloud providers:

  • Is not available in the Astra DB Free Tier.

  • Free Tier users: instead of submitting a Support ticket, click the Chat icon in the Astra DB console’s lower-right corner. Ask the DataStax onboarding representative about options to upgrade your organization and use BYOK.

Introduction

Data encryption is defined as a process that transforms data into an encoded format. Once encoded, the data is incomprehensible without being decrypted. Data encryption is essential for organizations in all industries because it protects data from unauthorized access. When thinking of data encryption, two main scenarios are often considered:

  • Data at rest

    Encrypting data while it is stored in the file storage in use.

  • Data in transit

    Encrypting data while it travels through private or public networks.

BYOK allows customers to manage encryption for data at rest.

Benefits

BYOK allows you to take full control of the encryption keys when storing data in the cloud. AWS KMS provides protection against data breaches by alerting you when tampering occurs. In KMS, you can configure specific policies to adhere to compliance guidelines, such as auditing, key rotation, and access.

Setting up a corresponding Customer Key for an AWS-based Astra DB database enables the separation of:

  • The encrypted lock

  • The key that encrypts/decrypts data

This separation of lock and key is considered a best practice to secure data via encryption.

After setting up a Customer Managed Key (CMK) in your AWS account’s Key Management Service, use the Astra DB console, or the DataStax DevOps API, to associate an existing AWS CMK with a Customer Key in Astra DB.

In Astra DB console, under Organization Settings, see the Key Encryption section of Security Settings.

In addition to the console UI, BYOK provides three DataStax DevOps API calls that allow you to programmatically:

  • Create a new association between a CMK (created in AWS KMS) and your Astra DB data, in a specific region.

  • List all Customer Keys that are associated with protecting the AWS-based Astra DB data for your organization.

  • List a specific Customer Key for an organization, based on the specified cloud provider (aws) & region combination.

Please contact DataStax Support if you need to delete Customer Keys from your Astra DB organization. If you agree, the DataStax Support team may perform the key deletion on your behalf. Once a registered association with an AWS KMS Customer Managed Key is deleted from your Astra DB organization, the default data encryption provided by Astra DB is used.

Prerequisites

  1. Create your Astra DB database using the Astra DB console. In the case of this BYOK feature, create an AWS-based database, and choose one of the available regions to start.

  2. Set up a Customer Managed Key (one per region, as needed) in the AWS KMS.

  3. Ensure you have the required Roles and permissions.

  4. Ensure that you know your Astra DB organization ID. When you log into the Astra DB console, your organization ID is in the generated URL. For example, in the URL https://astra.datastax.com/org/a99999c7-b934-436c-9999-9999999a3b5d/manage, the organization ID is a99999c7-b934-436c-9999-9999999a3b5d.

Multi-region support

The BYOK feature is supported in multi-region Astra DB environments; however, each region is encrypted using its own key. Keys cannot be shared across regions. For a given organization:

  • if you have an Astra DB database that spans multiple regions,

  • and if you’ve defined a Customer Managed Key in AWS or Google Cloud,

  • create a Customer Key in each (provider + region) combination.

Pricing

There is no additional cost to using BYOK with Astra DB. As noted previously, BYOK is not available in the Astra DB Free Tier.

Customer Managed Keys in AWS may incur a monthly fee, and a fee for use in excess of the AWS free tier. The fees are counted against the AWS KMS quotas for your AWS account. For details, see:

Roles and permissions

The following Astra DB roles can manage Customer Keys.

  • Organization Administrator

  • Database Administrator

To manage Customer Keys, your Astra DB account must have these permissions enabled.

  • org-cmk-read

  • org-cmk-write

AWS KMS console

Before you create a Customer Managed Key in the AWS Key Management Service (KMS), submit the following REST API call:

curl --request GET \
 --url 'https://api.astra.datastax.com/v2/kms/provider/<provider>/region/<region>/accounts' \
 --header 'Accept: application/json' \
 --header 'Authorization: Bearer <application_token>'

The GET’s response includes the provider_id of the AWS account where DataStax will store your S3 buckets. Copy the ID number returned in the GET’s response. Then, when you configure your AWS KMS Customer Managed Key (see the steps below), you’ll specify this account number, and grant DataStax permission to access this account.

  1. After authenticating into your AWS organization and account, search for, or navigate to, the Key Management Service (KMS).

  2. On the KMS page, click the left sidebar link for Customer managed keys.

  3. Click Create key.

  4. Choose the Symmetric option for a single key, which will be used to encrypt and decrypt data for your Astra DB database in an Amazon S3 bucket. Click Next.

  5. On Add labels, enter a memorable alias for your CMK, such as datastax-byok-cmk, and optionally provide a brief Description and user-defined Tags. Click Next.

  6. On Define key administrative permissions, decide if you want to keep the option to Allow key administrators to delete this key. Also on this dialog, expand the down arrow in Key administrators section and select the relevant AWS accounts. Click Next.

  7. On Define key usage permissions, decide which AWS accounts you want to authorize for the CMK’s usage. For now, skip the Other AWS Accounts option; there’s an option on the next screen to edit the in-progress Key policy definition. Click Next.

  8. On the Review page, check the selected options, and then scroll through the generated Key policy. There are a couple manual edits to perform. Add the full section (see below) that starts with:

            {
                "Sid": "Allow an external account to use this KMS key",
                .
                .
                .
            }
  9. Ensure that you have actions defined that are shown in the following example. Of course, your arn:aws:iam::…​ values will be different. The first sample ARN shown below is the account owner’s ID, and the second ARN in this sample is the ID of the AWS S3 storage account.

    Again, to get the appropriate storage account ID value, if you haven’t already, use the following GET to retrieve the provider_id of the account that DataStax will use, and for which you’ll grant access permission.

    curl --request GET \
     --url 'https://api.astra.datastax.com/v2/kms/provider/<provider>/region/<region>/accounts' \
     --header 'Accept: application/json' \
     --header 'Authorization: Bearer <application_token>'

    Make sure that your Key policy here in KMS, again in the section under "Allow an external account to use this KMS key", is using the intended S3 storage account ID’s arn:aws:iam::<storage-account-id>:role/creator value.

    {
        "Version": "2012-10-17",
        "Id": "key-consolepolicy-3",
        "Statement": [
            {
                "Sid": "Enable IAM User Permissions",
                "Effect": "Allow",
                "Principal": {
                    "AWS": "arn:aws:iam::111111111111:root"
                },
                "Action": "kms:*",
                "Resource": "*"
            },
            {
                "Sid": "Allow an external account to use this KMS key",
                "Effect": "Allow",
                "Principal": {
                    "AWS": "arn:aws:iam::222222222222:role/creator"
                },
                "Action": [
                    "kms:EnableKey",
                    "kms:Encrypt",
                    "kms:Decrypt",
                    "kms:GenerateDataKey",
                    "kms:GenerateDataKeyWithoutPlaintext",
                    "kms:ReEncryptTo",
                    "kms:ReEncryptFrom",
                    "kms:DescribeKey"
                ],
                "Resource": "*"
            },
            {
                "Sid": "Allow attachment of persistent resources",
                "Effect": "Allow",
                "Principal": {
                    "AWS": "arn:aws:iam::222222222222:role/creator"
                },
                "Action": [
                    "kms:CreateGrant",
                    "kms:ListGrants",
                    "kms:RevokeGrant"
                ],
                "Resource": "*"
            }
        ]
    }

    In your edits, match the kms:…​ values in the Action:…​ section, under the Sid label that begins with "Allow an external account to use this KMS key". Ensure that your Key policy has the following actions defined. To use the KMS CMK with your Astra DB data, DataStax requires these eight actions:

                "Action": [
                    "kms:EnableKey",
                    "kms:Encrypt",
                    "kms:Decrypt",
                    "kms:GenerateDataKey",
                    "kms:GenerateDataKeyWithoutPlaintext",
                    "kms:ReEncryptTo",
                    "kms:ReEncryptFrom",
                    "kms:DescribeKey"
                ]

    You can copy/paste in those values (if not present already) into your KMS CMK’s Key policy textbox.

    If you have questions, please contact us at Astra DB Product Management.

  10. Also, in the Key policy section that starts with:

                "Sid": "Allow attachment of persistent resources",

    Be sure to use the three actions shown in the sample below:

    "Action": [
                    "kms:CreateGrant",
                    "kms:ListGrants",
                    "kms:RevokeGrant"
                ],
  11. When you are ready, click Finish.

  12. On the AWS KMS Customer managed keys page, notice the alias name that you defined for your newly created CMK and its ID value.

Copy the ARN of the key you just created. That ARN can serve as the keyID that you’ll provide in:

  • Astra DB console’s Add Keys UI of your organization’s Security Settings

  • Or in the DevOps API /v2/kms POST request payload

Astra DB console’s Security Settings & Key Encryption

Reminder: By default, Astra DB encrypts data. The BYOK feature enhances data security by allowing you to instead associate a Customer Key in Astra DB with a Customer Managed Key (CMK) that you defined via a cloud provider, such as in the AWS Key Management Service (KMS).

Adding a new Customer Key

Having completed the steps in AWS KMS to set up a CMK, and granted DataStax access to your S3 buckets, follow these steps in Astra DB console to add a new Customer Key:

  1. From your Organization name near the Astra DB console’s upper-left corner, click Organization Settings, and navigate to Security Settings.

  2. On Security Settings, if your account includes the necessary permissions and roles, notice Key Encryption, a Premium feature.

    Astra DB console’s Security Settings and Key Encryption UI
  3. In Key Encryption, click Add Keys.

  4. In Add your Keys:

    1. Set Amazon Web Services as the cloud provider type.

    2. Select the same region used by your AWS KMS Customer Managed Key and the Astra DB database that will have its data encrypted.

    3. Paste in the Amazon Resource Name (ARN) value that you copied from the AWS KMS console, as outlined in the AWS KMS console section above.

    4. Click Add Key.

  5. When you’re ready, click Done.

Customer Key status indicators

After completing the steps above, existing and subsequently created Astra DB databases in the organization — that have the same provider + region combination —  are encrypted via the cloud provider’s Customer Managed Key (CMK) in the storage buckets.

On the Overview tab of the **Dashboard, see the indicators for resources secured by a Customer Key:

  • On Security Settings > Key Encryption

  • On the Overview tab of the Dashboard

Here’s an example on Key Encryption with status indicators:

Astra DB key status in Key Encryption UI

  • In-Use means a database in your organization is actively using the Customer Key.

  • Available status indicates a Customer Key has been added for your organization, but no Astra DB database with that Provider and Region combination is using the key.

Here’s an example with the key icon for the current database, indicating a Customer Key is used to protect its data:

Astra DB database details has Customer Key icon

Region Details also has a status indicator for any Customer Keys.