Bring your own encryption keys

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.

To encrypt your Astra DB databases, you can use AWS Key Management Service customer managed keys (AWS KMS CMK) and Google Cloud Key Management Service customer-managed encryption keys (Google Cloud KMS CMEK).

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

Customer keys require a paid subscription plan, and they can incur billed charges from your cloud provider. For more information, see AWS Key Management Service Pricing, AWS KMS Quotas, and Google Cloud customer-managed encryption keys in the Google Cloud documentation.

If you terminate a database that uses a customer key, make sure you destroy the associated key in your cloud provider’s KMS console.

Prerequisites

An active Astra account
An application token with the Organization Administrator role or a custom role with the Read CMK Key and Write CMK Key organization permissions
Your organization ID, which you can get from any Astra Portal URL, such as astra.datastax.com/org/ORGANIZATION_ID/

Configure customer keys for Astra DB Serverless

To use customer keys to encrypt your Astra DB Serverless databases, do the following:

Complete the prerequisites.
Create your key in your cloud provider’s KMS console.
Register your key in your Astra DB organization.

You must create and register the customer key before you create the database that will use that key. You can’t use a new customer key for an existing database.
Create your database with the same cloud provider and region as the associated key. Upon creation, the database uses the registered key for encryption.

Create your customer key

AWS KMS
Google Cloud KMS

Use the DevOps API to get the provider_id that allows Astra DB to use your customer key to encrypt your database. Replace REGION with a supported AWS region where you plan to create your customer key and your database, such as us-east-1.
```
curl -X GET --url 'https://api.astra.datastax.com/v2/kms/provider/aws/region/REGION/accounts' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer APPLICATION_TOKEN'
```
Copy the provider_id from the response. When you configure your key’s IAM policy, you must include the provider_id in the allowed principals.
```
[
  {
    "organization_id": "ORGANIZATION_ID",
    "provider_id": "PROVIDER_ID",
    "provider": "aws"
  }
]
```
Alternatively, you can get the provider_id from the Astra Portal. Go to Settings, click Security, and then click Add Keys. The Project ID is your provider_id.
In AWS KMS, create a symmetric encryption key in the same region that you used to get the provider_id.

Edit the key policy to include the following policy statement with your provider_id:

        {
            "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": "*"
        },

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

Get the key ARN that you will use to register the key in your Astra DB organization.

Use the DevOps API to get the provider_id that allows Astra DB to use your customer key to encrypt your database. Replace REGION with the supported Google Cloud region where you plan to create your customer key and your database, such as us-east1.
```
curl -X GET --url 'https://api.astra.datastax.com/v2/kms/provider/gcp/region/REGION/accounts' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer APPLICATION_TOKEN'
```
Copy the provider_id from the response. When you configure your key’s IAM roles, you must include the provider_id in the allowed principals.
```
[
  {
    "organization_id": "ORGANIZATION_ID",
    "provider_id": "PROVIDER_ID",
    "provider": "gcp"
  }
]
```
Alternatively, you can get the provider_id from the Astra Portal. Go to Settings, click Security, and then click Add Keys. The Project ID is your provider_id.
In Google Cloud KMS, create a key ring in the same region that you used to get the provider_id.
Create a symmetric encryption key with the Protection level set to Software.
Grant IAM roles on the key with sufficient permissions and the following principals:
```
PROVIDER_ID-compute@developer.gserviceaccount.com
service-PROVIDER_ID@compute-system.iam.gserviceaccount.com
service-PROVIDER_ID@gs-project-accounts.iam.gserviceaccount.com
```
You can create a custom role or use the Cloud KMS Admin and Cloud KMS Crypto Operator predefined roles to cover minimum required permissions, including cryptoKeyVersions.useToDecrypt and cryptoKeyVersions.useToEncrypt. You can modify the key’s role at any time if the permissions are too limited or too broad.
Get the key’s resource name that you will use to register the key in your Astra DB organization.

Register your customer key

Use the DevOps API or the Astra Portal to register your customer key in your Astra DB organization.

AWS KMS
Google Cloud KMS
Astra Portal

curl -X POST --url 'https://api.astra.datastax.com/v2/kms' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer APPLICATION_TOKEN'
--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

A successful request returns a 200 OK status code.

curl -X POST --url 'https://api.astra.datastax.com/v2/kms' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer APPLICATION_TOKEN'
--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

A successful request returns a 200 OK status code.

In the Astra Portal, go to Settings, and then click Security.
In the Key Encryption section, click Add Keys.
In the Provider field, select your KMS cloud provider.
In the Region field, select the region where you created your key.
In the Key ID field, enter your key’s ARN or resource name.
Click Add Key.

Create your database

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

After registering your customer key, create an Astra DB Serverless database with the same cloud provider and region as the customer key.

Configure additional keys, databases, or regions

In each Astra DB organization, you can have only one customer key for each cloud provider and region combination. For example, you can have one key for AWS us-east-1 and one key for Google Cloud us-east1.

To encrypt multi-region databases, you must create and register a key in each region where you plan to deploy the database. Don’t deploy the database to the additional regions until you register keys for those regions.

To enable customer key encryption for a separate database in a different region, repeat the entire process of key creation, registration, and database creation.

To encrypt a separate database in the same region as an existing customer key, do the following:

Get the provider_id, as explained in Create your customer key.
Edit the existing key’s IAM policy to include additional principals with the new provider_id. Don’t remove any principals that are associated with your existing databases.
After you add the additional principals, Create your database with the same cloud provider and region as your customer key. You don’t need to register the key again because you’re using a key that you already registered in your organization.

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.

DevOps API
Astra Portal

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

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

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.

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

In the Astra Portal navigation menu, click Settings, and then click Security. In the Key Encryption section, you can see the keys you’ve added for Astra DB Serverless databases in the current organization. To view keys for other organizations, you must switch organizations.
In the Astra Portal navigation menu, select a Astra DB Serverless database. In the Regions section, click more_vert More Options, 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 have the same cloud provider and region as the customer key that it uses, and you must create the database after you register the key in your Astra DB organization.

Rotate or delete customer keys

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

Replace a key
Use default encryption

If key versioning is not sufficient, you can contact DataStax Support or do the following:

Delete the key in your cloud provider.
Delete the associated database.

Remove the key registration from your organization. The following request deletes the key registered in the specified organization for the specified cloud provider (aws or gcp) and region.

curl -X DELETE --url 'https://api.astra.datastax.com/v2/organizations/ORG_ID/kms/provider/PROVIDER/region/REGION' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer APPLICATION_TOKEN'

Repeat the entire Configure customer keys for Astra DB Serverless process, including creating a new database for the new key.

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

Delete the key in your cloud provider.
Delete the associated database.
Remove the key registration from your organization. This is required so that Astra DB doesn’t attempt to encrypt the new database with a nonexistent key. The following request deletes the key registered in the specified organization for the specified cloud provider (aws or gcp) and region.
```
curl -X DELETE --url 'https://api.astra.datastax.com/v2/organizations/ORG_ID/kms/provider/PROVIDER/region/REGION' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer APPLICATION_TOKEN'
```
Create a new database.