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.

Astra DB Classic supports the following customer key providers:

Use of customer keys in Astra DB requires a paid subscription plan. Customer keys can incur billed charges from your cloud provider. For more information, see AWS KMS Pricing, AWS KMS Quotas, and the Google Cloud CMEK documentation.

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

What are Provider IDs

A provider ID (provider_id) is a placeholder for a future database. You need one provider ID for each database that you want to encrypt, including instances of multi-region databases. For example:

If you plan to create separate, single-region databases in the same region, you need one provider ID for each database.
If you plan to create separate, single-region databases in different regions, you need one provider ID for each database.
If you plan to create a multi-region database, you need one provider ID for each region where you plan to deploy the database.

In contrast, a customer key enables encryption for an entire region. Therefore, you need only one customer key for each region. 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).

When you create a customer key, attach provider IDs to the key in the key’s IAM policy. You must include enough provider IDs to account for all the databases that you plan to deploy to that region. A deployment can be a single-region database or an instance of a multi-region database. For example, if you plan to deploy three databases to us-east-2, you must include at least three provider IDs in the key’s IAM policy.

Then, you register the key in your Astra DB organization, which makes it available for use when you deploy databases in that organization. You only need to register the key once. You can add provider IDs from the key’s IAM policy without re-registering the key.

A key’s assigned provider IDs represent "open seats" for databases. When you deploy a database in a region with a registered encryption key, the database consumes an unclaimed provider ID from the key’s IAM policy, if one is available. If there are no unclaimed provider IDs when you deploy the database, then the database uses default Astra DB encryption.

Provider IDs are consumed automatically when you deploy databases in regions with registered encryption keys.

For example, if you attach three provider IDs to a key, the provider IDs are automatically consumed by the next three databases that anyone in your organization deploys in that region.

As a best practice, generate the provider ID and add it to the key’s IAM policy immediately before you deploy a database that you want to encrypt.

Terminating a database or removing a region from a multi-region database does not release the provider ID for reuse. Once a database claims a provider ID, it can’t be used again.

Configure customer keys for Astra DB Classic

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.

To use customer keys to encrypt an Astra DB Classic databases, do the following:

Create a key in your cloud provider’s KMS console.
Register the key in your Astra DB organization.
Deploy your database in the same cloud provider and region as the associated key. Upon creation, the database uses the registered key for encryption.

To encrypt additional databases or regions, see Configure additional keys, databases, or regions.

Create your customer key

AWS KMS
Google Cloud KMS

Use the DevOps API to get the provider_id that will link your customer key to a database:

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

A provider_id is a placeholder for a future database. You need one provider ID for each database that you want to encrypt, including instances of multi-region databases. For more information, see What are Provider IDs.

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 -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 provider_id that will link your customer key to a database:

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

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

A successful request returns a 200 OK status code.

Deploy your database

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

After registering your customer key, deploy an Astra DB Classic database in the same cloud provider and region as the customer key. To deploy a database you can either create a database or add a region to a multi-region database.

When you deploy a database in a region with a registered encryption key, the database consumes an unclaimed provider ID from the key’s IAM policy, if one is available. If there are no unclaimed provider IDs when you deploy the database, then the database uses default Astra DB encryption. For more information, see What are Provider IDs.

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.

If you need to encrypt multiple databases or regions, you must understand the relationship between provider IDs and customer keys. See What are Provider IDs.

Multi-region databases

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.

If you already have a key for a region where you want to deploy a multi-region database, you must generate a provider_id and add it to your key’s IAM policy before you deploy the database to the region.

Use keys for multiple regions

Customer keys are region-specific. You can’t use the same key for multiple regions.

To enable customer key encryption in multiple regions, you must complete the process of key creation and registration for each region.

Use a key for multiple databases

To encrypt a new database in the same region as an existing customer key, you must create a new provider_id and add it to the key’s IAM policy before you deploy the database.

AWS KMS
Google Cloud KMS

Follow the steps in Create your customer key to get a new provider_id.
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, Deploy your 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.

Follow the steps in Create your customer key to initiate the encryption process and get a new provider_id.
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 -sS -L -X GET "https://api.astra.datastax.com/v2/kms/classic/provider/aws/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:

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

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

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
Delete an encrypted database

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 -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 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 -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 a new database.

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

The deleted database’s provider_id can’t be used by any other database.

Bring your own encryption keys

What are Provider IDs

Configure customer keys for Astra DB Classic

Create your customer key

Register your customer key

Deploy your database

Configure additional keys, databases, or regions

Multi-region databases

Use keys for multiple regions

Use a key for multiple databases

View customer keys

Rotate or delete customer keys

Was this helpful?

Give Feedback