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 Serverless 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 Serverless
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 a Astra DB Serverless database, 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 --location -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 asus-east-1
-
APPLICATION_TOKEN
: An application token with the Read CMK Key and Write CMK Key permissionsA
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 theprovider_id
in the allowed principals.[ { "organization_id": "ORGANIZATION_ID", "provider_id": "PROVIDER_ID", "provider": "aws" } ]
Alternatively, you can get a
provider_id
from the Astra Portal. Go to Settings, click Security, and then click Add Keys. The Cloud Provider Account ID is aprovider_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 will link your customer key to a database:curl -sS --location -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 asus-east1
-
APPLICATION_TOKEN
: An application token with the Read CMK Key and Write CMK Key permissionsA
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 roles, you must include theprovider_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 aprovider_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
andcryptoKeyVersions.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 -sS --location -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 asus-east-1
A successful request returns a 200 OK
status code.
curl -sS --location -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 asus-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.
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 Serverless 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
-
Keys for multiple regions
-
One key for multiple 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.
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.
To encrypt a new database in the same region as an existing customer key, do the following:
+
. 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 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.
+
A You must create the |
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 -sS --location -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.
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 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
-
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 (
aws
orgcp
) and region.curl -sS --location -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 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
orgcp
) and region.curl -sS --location -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"
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.