Bring your own encryption keys for Astra DB Classic

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 Classic 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 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

Astra DB Serverless

AWS

A supported region, such as us-east-2

Astra DB Serverless

Google Cloud

A supported region, such as us-east1

If you only plan to have Astra DB Classic 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 Serverless and Astra DB Classic databases, you also need separate encryption keys for your Serverless databases, even you plan to deploy them to the same regions as your Astra DB Classic databases. For information about creating keys for Serverless databases, see Bring your own encryption keys for Astra DB Serverless.

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 Classic

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 Classic 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 Classic 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 Serverless 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.
On the Overview page, click the relevant organization name.
In the Settings navigation menu, click Security.
In the Key Encryption section, click Add Keys.
For Database Type, select Classic.
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.

Keep this window open while you create your key.

This is especially important for Google Cloud. If you exit the Add Key dialog or the Astra Portal, the Cloud Provider ID for Google Cloud is discarded.

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/classic/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-1
- 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/classic" \
--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-1

Use the DevOps API to start the customer key encryption process:

curl -sS -L -X POST "https://api.astra.datastax.com/v2/kms/classic/provider/gcp/accounts" \
--header "Authorization: Bearer APPLICATION_TOKEN" \
--header "Content-Type: application/json"

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/classic/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"
  }
]
```
Only call GET /v2/kms/classic/provider/gcp/region/REGION/accounts once for each GCP region. Each time you call this endpoint, the GCP region’s previous provider_id is discarded and becomes invalid.
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/classic" \
--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 Classic 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 keys, rotate keys, or delete keys.

View customer keys

You can 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/classic/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 (for AWS) or resource name (for GCP):

{
  "orgId": "ORGANIZATION_ID",
  "PROVIDER": {
    "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. The following DevOps API request deletes the key registered in the specified organization for the specified cloud provider and region:

curl -sS -L -X DELETE "https://api.astra.datastax.com/v1/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 Classic process, including redeploying databases.

Use default encryption

If you want to use default Astra DB Classic 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.

The following DevOps API request deletes the key registered in the specified organization for the specified cloud provider and region:
```
curl -sS -L -X DELETE "https://api.astra.datastax.com/v1/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.