Bring your own encryption keys for Astra DB Serverless

Encryption is a widely accepted security mechanism, and Astra DB provides data encryption by default. Customer keys give you additional control over your encryption keys and access to data at rest. Customer keys are also known as customer managed keys, bring your own keys, and custom encryption keys.

Astra DB Serverless supports customer key encryption for databases deployed to AWS and Google Cloud regions.

Databases that aren’t encrypted by customer keys use Astra DB-provided encryption keys.

Prerequisites

Configure customer keys before you create databases that will use those keys. You can’t use a new customer key for an existing database.

You need access to your cloud provider’s key management console:
- AWS Key Management Service customer managed keys (AWS KMS CMK)
- Google Cloud Key Management Service customer-managed encryption keys (Google Cloud KMS CMEK).
Your Astra DB organization must be on the Pay As You Go or Enterprise subscription plan because customer key encryption is a premium feature.

Additionally, customer keys can incur billed charges in your cloud provider. For more information, see AWS KMS Pricing, AWS KMS Quotas, and the Google Cloud CMEK documentation.
You need the Organization Administrator or a custom role with key management permissions.

Determine how many keys you need

You need one customer key for each combination of database type, cloud provider, and region. For example, each of the following combinations requires its own key:

Database type Cloud provider Region

Database type	Cloud provider	Region
Astra DB Serverless	AWS	A supported region, such as `us-east-2`
Astra DB Serverless	Google Cloud	A supported region, such as `us-east1`
Astra DB Classic	AWS	A supported region, such as `us-east-2`
Astra DB Classic	Google Cloud	A supported region, such as `us-east1`

Astra DB Serverless

AWS

A supported region, such as us-east-2

Astra DB Serverless

Google Cloud

A supported region, such as us-east1

Astra DB Classic

AWS

A supported region, such as us-east-2

Astra DB Classic

Google Cloud

A supported region, such as us-east1

If you only plan to have Astra DB Serverless databases, then you need one key for each cloud provider and region where you plan to deploy your databases. For example, if you plan to create databases in us-east-2 and ap-south-1, you need two keys (one key for each region).

If you plan to have both Astra DB Classic and Astra DB Serverless databases, you also need separate encryption keys for your Classic databases, even you plan to deploy them to the same regions as your Astra DB Serverless databases. For information about creating keys for Classic databases, see Bring your own encryption keys for Astra DB Classic.

For multi-region databases, you need a key for each region where you plan to deploy the databases.

If you have multiple Astra DB organizations, DataStax recommends separate keys for each organization.

Configure customer keys for Astra DB Serverless

Configure customer keys before you create databases that will use those keys. You can’t use a new customer key for an existing database.

To use a customer key to encrypt an Astra DB Serverless database, you must do the following:

Create and register a key: Create a key in your cloud provider’s KMS console, and then register it in your Astra DB organization.
Deploy databases: In the same cloud provider and region as the key, create a database or add a region to an existing database. Upon deployment, Astra DB uses the previously-registered key for encryption.

Your Astra DB organization uses the same key to encrypt all Astra DB Serverless databases that you deploy to the key’s cloud provider and region. If you want to use customer key encryption for other cloud providers, regions, or Astra DB Classic databases, see Expand customer key encryption.

Create and register your customer key

Create a key in your cloud provider’s KMS console, and then register it in your Astra DB organization. This process requires access to both Astra DB and your cloud provider.

Astra Portal
DevOps API

In the Astra Portal header, click Settings.
In the Settings navigation menu, click the name of the current organization, and then select the organization where you want to use your own encryption key.
In the Settings navigation menu, click Security.
In the Key Encryption section, click Add Keys.
For Database Type, select Serverless.
For Provider and Region, select the cloud provider and supported region where you plan to create your customer key and deploy your database.
After your select a region, note the Cloud Provider ID, which is a unique identifier for a DataStax-owned AWS account or Google Cloud project. You will use the this ID to define allowed principals in your key’s IAM policy.

Some Google Cloud regions have two provider IDs. If you select a region with two provider IDs, you must include both IDs in your key’s IAM policy.
Open a new browser tab, and then create an encryption key in your cloud provider’s KMS console:
- AWS KMS
- Google Cloud KMS
In AWS KMS, create a symmetric encryption key in the same region that you selected in the Astra Portal.

Edit the key policy to include the following policy statement:

{ "Sid": "Allow an external account to use this KMS key", "Effect": "Allow", "Principal": { "AWS": "arn:aws:iam::PROVIDER_ID:role/creator" }, "Action": [ "kms:EnableKey", "kms:Encrypt", "kms:Decrypt", "kms:GenerateDataKey", "kms:GenerateDataKeyWithoutPlaintext", "kms:ReEncryptTo", "kms:ReEncryptFrom", "kms:DescribeKey" ], "Resource": "*" },

In the allowed principals, replace PROVIDER_ID with the Cloud Provider ID from the Astra Portal. For more information, see AWS account principals.

The key policy must include the following permissions and actions, some of which are included in the default key policy:

Enable IAM User Permissions

Allow an external account to use this KMS key

Allow attachment of persistent resources

kms:CreateGrant

kms:ListGrants

kms:RevokeGrant

Copy the key’s ARN.

In the Astra Portal, paste the key’s ARN in the Key ID field, and then click Add Key.
In Google Cloud KMS, create a key ring in the same region that you selected in the Astra Portal.

Create a symmetric encryption key with the Protection level set to Software.

Grant IAM roles on the key with the following principals, which are Google Cloud default service accounts:

PROVIDER_ID-compute@developer.gserviceaccount.com service-PROVIDER_ID@compute-system.iam.gserviceaccount.com service-PROVIDER_ID@gs-project-accounts.iam.gserviceaccount.com

Replace PROVIDER_ID with the Cloud Provider ID from the Astra Portal. If your Google Cloud region has two provider IDs, add principals for both IDs (six principals in total).

Create a custom role or use the Cloud KMS Admin and Cloud KMS Crypto Operator predefined roles to grant minimum required permissions, including cryptoKeyVersions.useToDecrypt and cryptoKeyVersions.useToEncrypt.

Copy the key’s resource name.

In the Astra Portal, paste your key’s resource name in the Key ID field, and then click Add Key.

AWS KMS
Google Cloud KMS

Use the DevOps API to get the DataStax-owned AWS account ID for your key’s IAM policy:
```
curl -sS -L -X GET "https://api.astra.datastax.com/v2/kms/provider/aws/region/REGION/accounts" \
--header "Authorization: Bearer APPLICATION_TOKEN" \
--header "Content-Type: application/json"
```
Replace the following:
- REGION: A supported AWS region where you plan to create your customer key and your database, such as us-east-2
- APPLICATION_TOKEN: An application token with the Read CMK Key and Write CMK Key permissions

Copy the provider_id from the response:

[
  {
    "organization_id": "ORGANIZATION_ID",
    "provider_id": "PROVIDER_ID",
    "provider": "aws"
  }
]

In AWS KMS, create a symmetric encryption key in the same region that you used in the previous DevOps API request.

Edit the key policy to include the following policy statement:

        {
            "Sid": "Allow an external account to use this KMS key",
            "Effect": "Allow",
            "Principal": {
                "AWS": "arn:aws:iam::PROVIDER_ID:role/creator"
            },
            "Action": [
                "kms:EnableKey",
                "kms:Encrypt",
                "kms:Decrypt",
                "kms:GenerateDataKey",
                "kms:GenerateDataKeyWithoutPlaintext",
                "kms:ReEncryptTo",
                "kms:ReEncryptFrom",
                "kms:DescribeKey"
            ],
            "Resource": "*"
        },

In the allowed principals, replace PROVIDER_ID with the provider_id that was returned by the DevOps API. For more information, see AWS account principals.

The key policy must include the following permissions and actions, some of which are included in the default key policy:

Enable IAM User Permissions
Allow an external account to use this KMS key
Allow attachment of persistent resources
kms:CreateGrant
kms:ListGrants
kms:RevokeGrant

Copy the key’s ARN.
Use the DevOps API to register your customer key in your Astra DB organization:
```
curl -sS -L -X POST "https://api.astra.datastax.com/v2/kms" \
--header "Authorization: Bearer APPLICATION_TOKEN" \
--header "Content-Type: application/json" \
--data '{
  "orgId": "ORGANIZATION_ID",
  "aws": {
    "keyID": "ARN",
    "region": "REGION"
  }
}'
```
Replace the following:
- APPLICATION_TOKEN: Your Astra DB application token
- ORGANIZATION_ID: Your Astra DB organization ID
- ARN: Your key’s ARN from AWS KMS
- REGION: The region where you created your key, such as us-east-2

Use the DevOps API to get the DataStax-owned Google Cloud project ID for your key’s IAM policy:
```
curl -sS -L -X GET "https://api.astra.datastax.com/v2/kms/provider/gcp/region/REGION/accounts" \
--header "Authorization: Bearer APPLICATION_TOKEN" \
--header "Content-Type: application/json"
```
Replace the following:
- REGION: A supported Google Cloud region where you plan to create your customer key and your database, such as us-east1
- APPLICATION_TOKEN: An application token with the Read CMK Key and Write CMK Key permissions

Copy the provider_id from the response:

[
  {
    "organization_id": "ORGANIZATION_ID",
    "provider_id": "PROVIDER_ID",
    "provider": "gcp"
  }
]

In Google Cloud KMS, create a key ring in the same region that you used in the previous DevOps API request.
Create a symmetric encryption key with the Protection level set to Software.
Grant IAM roles on the key with the following principals, which are Google Cloud default service accounts:
```
PROVIDER_ID-compute@developer.gserviceaccount.com
service-PROVIDER_ID@compute-system.iam.gserviceaccount.com
service-PROVIDER_ID@gs-project-accounts.iam.gserviceaccount.com
```
Replace PROVIDER_ID with the provider_id that was returned by the DevOps API. If your Google Cloud region has two provider IDs, add principals for both IDs (six principals in total).
Create a custom role or use the Cloud KMS Admin and Cloud KMS Crypto Operator predefined roles to grant minimum required permissions, including cryptoKeyVersions.useToDecrypt and cryptoKeyVersions.useToEncrypt.
Copy the key’s resource name.
Use the DevOps API to register your customer key in your Astra DB organization:
```
curl -sS -L -X POST "https://api.astra.datastax.com/v2/kms" \
--header "Authorization: Bearer APPLICATION_TOKEN" \
--header "Content-Type: application/json" \
--data '{
  "orgId": "ORGANIZATION_ID",
  "gcp": {
    "keyID": "RESOURCE_NAME",
    "region": "REGION"
  }
}'
```
Replace the following:
- APPLICATION_TOKEN: Your Astra DB application token
- ORGANIZATION_ID: Your Astra DB organization ID
- RESOURCE_NAME: Your key’s resource name from Google Cloud KMS
- REGION: The region where you created your key, such as us-east1

Deploy databases

After registering your customer key, create a database or add a region to a multi-region database in the same cloud provider and region as the customer key.

To use customer key encryption for a database, you must deploy the database in the same cloud provider and region as the key.

When you deploy a database in a region with a registered encryption key, the database is encrypted with that key. If you deploy a database to a region that does not have a registered key, the database uses default Astra DB encryption.

Expand customer key encryption

After you register a customer key in your Astra DB organization, that one key encrypts all Astra DB Serverless databases that you deploy to the key’s cloud provider and region.

Because Astra DB requires that you use region-specific customer keys, you need multiple keys to cover multiple regions.

To use customer key encryption for databases deployed to different regions, including multi-region databases, you must create and register a key in each region where you plan to deploy those databases.

Create and register all keys before you deploy your databases.

For more information about customer key coverage and calculating how many keys you need, see Prerequisites.

Manage customer keys

After registering customer keys in your organization, you might need to inspect key statuses, rotate keys, or delete keys.

View customer keys

You can inspect registered customer keys in the Astra Portal or with the DevOps API. The Astra Portal includes a status indicating whether the key is in use by any databases.

Astra Portal
DevOps API

There are two ways to check the status of your customer keys in the Astra Portal.

Organization settings

In the Astra Portal header, click Settings.
On the Overview page, click the relevant organization name.
In the Settings navigation menu, click Security.

The Key Encryption section lists the keys for Astra DB Serverless databases that exist in the selected organization.

Database details

In the Astra Portal navigation menu, select an Astra DB Serverless database.
In the Regions section, click More, and then select Details.

The Region Usage details include the status of customer keys used by this database in each region where the database is deployed.

Possible key statuses include:

In-Use: A database is actively using the customer key.
Available: The customer key is available to your organization, but the key is not in use by any databases. To use a customer key for encryption, a database must be deployed to the same cloud provider and region as the customer key. Additionally, the database must have been deployed after you registered the key in your Astra DB organization.

Use the DevOps API to retrieve the customer key registration for a specified cloud provider (aws or gcp) and region:

curl -sS -L -X GET "https://api.astra.datastax.com/v2/kms/provider/PROVIDER/region/REGION" \
--header "Authorization: Bearer APPLICATION_TOKEN" \
--header "Content-Type: application/json"

A successful response includes the organization ID, provider, and region, as well as the keyID, which is the registered key’s ARN or resource name:

{
  "orgId": "ORGANIZATION_ID",
  "provider": "AWS_OR_GCP",
  {
    "keyID": "ARN_OR_RESOURCE_NAME",
    "region": "REGION"
  }
}

You can also get all registered customer keys for an organization.

Rotate customer keys

AWS KMS and Google Cloud KMS provide automatic rotation through key versioning. You can manage this in your cloud provider’s KMS console. For more information, see Rotating AWS KMS keys, and Google Cloud KMS key rotation.

If automatic key versioning is not sufficient, you can replace a customer key by contacting DataStax Support or doing the following:

Delete the key in your cloud provider.
Delete all databases that use the key.

For multi-region databases, you must remove the relevant region from the database.

Make sure you export your data before terminating your database. Terminating a database also deletes its data and backups.
Remove the key registration from your organization:

You can do this from your organization’s Security settings or with the DevOps API. The following DevOps API request deletes the key registered in the specified organization for the specified cloud provider (aws or gcp) and region:
```
curl -sS -L -X DELETE "https://api.astra.datastax.com/v2/organizations/ORG_ID/kms/provider/PROVIDER/region/REGION" \
--header "Authorization: Bearer APPLICATION_TOKEN" \
--header "Content-Type: application/json"
```
Repeat the entire Configure customer keys for Astra DB Serverless process, including redeploying databases.

Use default encryption

If you want to use default Astra DB Serverless encryption instead of customer key encryption, you can contact DataStax Support or do the following:

Delete the key in your cloud provider.
Delete all databases that use the key.

For multi-region databases, you must remove the relevant region from the database.

Make sure you export your data before terminating your database. Terminating a database also deletes its data and backups.
Remove the key registration from your organization. This is required so that Astra DB doesn’t attempt to encrypt new databases with a nonexistent key.

You can do this from your organization’s Security settings or with the DevOps API. The following DevOps API request deletes the key registered in the specified organization for the specified cloud provider (aws or gcp) and region:
```
curl -sS -L -X DELETE "https://api.astra.datastax.com/v2/organizations/ORG_ID/kms/provider/PROVIDER/region/REGION" \
--header "Authorization: Bearer APPLICATION_TOKEN" \
--header "Content-Type: application/json"
```
Create new databases or redeploy multi-region databases.