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 Classic

To use customer keys to encrypt your Astra DB Classic 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 database, such as us-east-1.

curl -X GET --url 'https://api.astra.datastax.com/v2/kms/classic/provider/aws/region/REGION/accounts' \
  --header 'Accept: application/json' \
  --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"
  }
]
```
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 start the customer key encryption process:

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

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 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/classic/provider/gcp/region/REGION/accounts' \
  --header 'Accept: application/json' \
  --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"
  }
]
```
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 to register your customer key in your Astra DB organization.

AWS KMS
Google Cloud KMS

curl -X POST --url 'https://api.astra.datastax.com/v2/kms/classic' \
  --header 'Accept: application/json' \
  --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

curl -X POST --url 'https://api.astra.datastax.com/v2/kms/classic' \
  --header 'Accept: application/json' \
  --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.

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

AWS KMS
Google Cloud KMS

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 the database in the same 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.

Initiate the encryption process and get the provider_id, as explained in Create your customer key.
Edit the existing key’s IAM roles 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 the database in the same 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 use the DevOps API to retrieve the customer key registration for a specified cloud provider and region.

AWS KMS
Google Cloud KMS

curl -X GET --url 'https://api.astra.datastax.com/v2/kms/classic/provider/aws/region/REGION' \
  --header 'Accept: application/json' \
  --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:

{
  "orgId": "ORGANIZATION_ID",
  "aws": {
    "keyID": "ARN",
    "region": "REGION**"
  }
}

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

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

{
  "orgId": "ORGANIZATION_ID",
  "gcp": {
    "keyID": "RESOURCE_NAME",
    "region": "REGION"
  }
}

You can also get all registered customer keys for an 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 and region.

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

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

If you want to use default Astra DB Classic 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 and region.
```
curl -X DELETE --url 'https://api.astra.datastax.com/v1/organizations/ORG_ID/kms/provider/PROVIDER/region/REGION' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer APPLICATION_TOKEN'
```
Create a new database.