Add customer keys

Astra DB Classic allows you to associate keys from a cloud provider’s key management service (KMS) with customer keys in Astra DB.

When you add customer keys, your Astra DB databases with the same cloud provider and region as the key are encrypted through the cloud provider’s customer key in the storage buckets.

This feature requires a paid plan.

You can manage customer keys in the Astra Portal or you can use the DevOps API to programmatically manage your customer keys:

Create an association between an AWS KMS customer-managed key (CMK) and your Astra DB data in a specific region.
List all customer keys that are associated with protecting the AWS-based Astra DB data for your organization.
List a specific customer key for an organization, based on the specified cloud provider (aws) and region combination.

Prerequisites

An active Astra account with the Organization Administrator role, Database Administrator role, or a custom role that has org-cmk-read and org-cmk-write permissions.
An Astra DB Classic database with the same cloud provider and region as your intended customer key.
An application token
Your organization ID, which is in any Astra Portal URL, such as https://astra.DataStax.com/org/ORGANIZATION_ID.

Set up a customer key

You can add only one customer key for each provider-region combination.

Get your provider_id via REST API call:

curl --request GET \
 --url 'https://api.astra.DataStax.com/v2/kms/provider/PROVIDER/region/REGION/accounts' \
 --header 'Accept: application/json' \
 --header 'Authorization: Bearer APPLICATION_TOKEN'

Results

[{"organization_id":"<organization_id>","provider_id":"<provider_id>","provider":"aws"}]%

Copy the 'provider_id', which you’ll specify during your AWS KMS Customer Managed Key configuration. AWS uses this provider_id to grant Astra DB permission to access this account.

After authenticating into your AWS organization and account, navigate to the Key Management Service (KMS) page.
Click the left sidebar link for Customer managed keys.
Click Create key.
Choose the Symmetric option for a single key, which encrypts and decrypts data for your Astra DB database in an Amazon S3 bucket. Click Next.
On Add labels, enter a memorable alias for your CMK, such as DataStax-byok-cmk. Optionally, provide a brief Description and user-defined Tags. Click Next.
On Define key administrative permissions, select your Key administrators from IAM users and roles. Select whether to Allow key administrators to delete this key. Click Next.
On Define key usage permissions, select your Key users from IAM users and roles, and optionally add Other AWS Accounts. Click Next.
On the Review page, review the selected options and generated Key policy.

Manually edit the Key policy to add this section 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": "*"
        },

Ensure that you have at least these actions defined with your ARN values:
- Enable IAM User Permissions
- Allow an external account to use this KMS key
- Allow attachment of persistent resources
  - kms:CreateGrant
  - kms:ListGrants
  - kms:RevokeGrant

Click Finish.

Your new key is available on the Customer managed keys page.

On the AWS KMS Customer managed keys page, you click the alias name you defined. Copy the ARN of the key, which is the keyID that you’ll provide to Add Keys in the Astra Portal Security Settings or in the DevOps API /v2/kms POST request payload.

Add the new customer key to Astra Portal

DevOps v2 API to manage customer keys

After your CMK is set up with the assigned role and permissions, you can use the DevOps API to submit calls that create and view associated customer keys for your Astra DB data. Submit DevOps API calls to create and view customer keys in your Astra DB organization. If you are using Postman for your API calls, ensure you use the raw option to enter the body of your API call.

For descriptions of the /v2/kms calls, see the sections below. For more, see the DevOps v2 API reference details.

Create a customer key for Astra DB

Use the following POST to create a customer key in Astra DB that will be associated with an existing Customer Managed Key in the AWS Key Management Service (KMS).

In the request payload, specify your Astra DB organizationID, and the keyID of the Customer Managed Key that you created in AWS KMS, and the region. In each Astra DB organization, there can be one customer key for a given cloud provider and region combination. A successful customer key creation returns 200 OK in the response.

curl --request POST \
  --url 'https://api.astra.DataStax.com/v2/kms' \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer APPLICATION_TOKEN' \
  --data '{
  "orgId": "ORGANIZATION_ID",
  "aws": {
    "keyID": "ARN",
    "region": "REGION"
  }
}'

Results

When the key is found for the given provider and region, the 200 OK response contains:

{
  "orgId": "The ID of your organization",
  "aws":
  {
    "keyID": "The ID of the provider account where DataStax stores your data buckets",
    "region": "region-name"
  }
}

Other potential response codes:

400 Bad request.
403 The user is forbidden to perform the operation.
500 A server error occurred.

{
  "errors": [
    {
      "description": "STRING",
      "internalCode": "STRING",
      "internalTxId": "STRING"
    }
  ]
}

Get all customer keys in an Astra DB organization

Retrieve all existing customer keys of an Astra DB organization.

curl --request GET \
 --url 'https://api.astra.DataStax.com/v2/kms' \
 --header 'Accept: application/json' \
 --header 'Authorization: Bearer APPLICATION_TOKEN'

Results

When one or more keys are found for the organization, the 200 OK response contains, for each key:

[
  {
    "OrganizationID": "*ORGANIZATION_ID*",
    "CloudProvider": "aws",
    {
      "keyID": "ARN",
      "region": "REGION"
    }
  }
]

If there are no keys setup for the organization, the 404 response contains:

{
  "description": "Organization: ORGANIZATION_ID does not have
                  any CMKs associated with it."
}

Other potential response codes:

400 Bad request.
403 The user is forbidden to perform the operation.
500 A server error occurred.

Get a single customer key in an Astra DB organization

Retrieves a customer key in an Astra DB organization for a given cloud provider and region combination. The provider value in this case should be aws.

curl --request GET \
 --url 'https://api.astra.DataStax.com/v2/kms/provider/aws/region/REGION/accounts' \
 --header 'Accept: application/json' \
 --header 'Authorization: Bearer APPLICATION_TOKEN'

Results

When the key is found for the given provider and region, the 200 OK response contains:

{
  "orgId": "The ID of your organization",
  "provider": "aws":
  {
    "keyID": "The ID of the provider account where DataStax stores your data buckets",
    "region": "region-name"
  }
}

If there are no keys setup for the organization’s provider and region combination, the 404 response contains:

{
  "description": "Could not find PROVIDER data in
                  region REGION for organization ORGANIZATION_ID."
}

Other potential response codes:

400 Bad request.
403 The user is forbidden to perform the operation.
500 A server error occurred.

Get an array of Astra DB cloud provider accounts

Retrieves a customer key in an Astra DB organization for a given cloud provider and region combination. The provider value in this case should be aws.

The GET response also returns the provider ID of the storage account where your Amazon S3 buckets exist. If not done already, you can use this information to configure or modify (back in the AWS Key Management Service) your KMS Customer Managed Key, so that Astra DB has access to the key.

curl --request GET \
 --url 'https://api.astra.DataStax.com/v2/kms/provider/aws/region/REGION/accounts' \
 --header 'Accept: application/json' \
 --header 'Authorization: Bearer APPLICATION_TOKEN'

Results

When the key is found for the given provider and region, the 200 OK response contains an array of:

[
  {
    "organization_id": "ID of your organization",
    "provider_id": "ID of the provider account
                   where DataStax stores your data buckets",
    "provider": "aws"
  }
]

If there are no keys setup for the organization’s provider and region combination, the 404 response contains:

{
  "description": "Could not find PROVIDER data in
                  region REGION for organization ORGANIZATION_ID."
}

Other potential response codes:

400 Bad request.
403 The user is forbidden to perform the operation.
500 A server error occurred.

Add customer keys

Prerequisites

Set up a customer key

Add the new customer key to Astra Portal

DevOps v2 API to manage customer keys

Create a customer key for Astra DB

Get all customer keys in an Astra DB organization

Get a single customer key in an Astra DB organization

Get an array of Astra DB cloud provider accounts

See also

Was this helpful?

Give Feedback