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:

  1. Create a key in your cloud provider’s KMS console.

  2. Register the key in your Astra DB organization.

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

  1. 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/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-2

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

  2. 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"
  }
]
    Get a provider ID from the Astra Portal

    1. In the Astra Portal navigation menu, click Settings, and then click Security.

    2. In the Key Encrpytion section, click Add Keys.

      The Cloud Provider Account ID is a provider_id.

  3. In AWS KMS, create a symmetric encryption key in the same region that you used to get the provider_id.

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

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

  1. 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/provider/gcp/region/REGION/accounts" \
--header "Authorization: Bearer APPLICATION_TOKEN" \
--header "Content-Type: application/json"

    Replace the following:

  2. 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"
  }
]
    Get a provider ID from the Astra Portal

    1. In the Astra Portal navigation menu, click Settings, and then click Security.

    2. In the Key Encrpytion section, click Add Keys.

      The Project ID is a provider_id.

  3. In Google Cloud KMS, create a key ring in the same region that you used to get the provider_id.

  4. Create a symmetric encryption key with the Protection level set to Software.

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

  6. 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 -L -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 as us-east-2

A successful request returns a 200 OK status code.

curl -sS -L -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 as us-east1

A successful request returns a 200 OK status code.

  1. In the Astra Portal navigation menu, click Settings, and then click Security.

  2. In the Key Encrpytion section, click Add Keys.

  3. In the Provider field, select your KMS cloud provider.

  4. In the Region field, select the region where you created your key.

  5. In the Key ID field, enter your key’s ARN or resource name.

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

You must create the provider_id and add it to the key’s IAM policy before you deploy the database. For more information, see What are Provider IDs.

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

  • Organization settings

  • Database details

  1. In the Astra Portal navigation menu, click Settings, and then click Security.

    The Key Encrpytion section lists the keys for Astra DB Serverless databases that exist in the selected organization.

  1. In the Astra Portal navigation menu, select a Astra DB Serverless database.

  2. In the Regions section, click More, 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:

  1. Delete the key in your cloud provider.

  2. Delete the associated database.

  3. 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 -sS -L -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"

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

  1. Delete the key in your cloud provider.

  2. Delete the associated database.

  3. 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 -sS -L -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"

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

Was this helpful?

Give Feedback

How can we improve the documentation?

© 2024 DataStax | Privacy policy | Terms of use

Apache, Apache Cassandra, Cassandra, Apache Tomcat, Tomcat, Apache Lucene, Apache Solr, Apache Hadoop, Hadoop, Apache Pulsar, Pulsar, Apache Spark, Spark, Apache TinkerPop, TinkerPop, Apache Kafka and Kafka are either registered trademarks or trademarks of the Apache Software Foundation or its subsidiaries in Canada, the United States and/or other countries. Kubernetes is the registered trademark of the Linux Foundation.

General Inquiries: +1 (650) 389-6000, info@datastax.com