Add customer keys

Astra DB allows you to associate your defined key from the cloud provider’s key management service (KMS) with a Customer Key in Astra DB.

This feature is available for paid DB Classic users with AWS, supported with the DevOps API. In the DevOps API, there are calls that allow you to programmatically manage customer keys:

  • Create a new association between a CMK (created in AWS KMS) 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) & region combination.

Prerequisites

  • You have an active Astra account.

  • You have the Organization Administrator or Database Administrator role, or a custom role with the org-cmk-read and org-cmk-write permissions enabled.

  • Create an Astra DB database using the Astra Portal based with the cloud provider you will create a customer key.

  • Your application token, which you can generate from your database Overview in the Astra Portal.

  • Ensure that you know your Astra Portal organization ID. When you log into the Astra DB console, your organization ID is in the generated URL. For example, in the URL https://astra.DataStax.com/org/a99999c7-b934-436c-9999-9999999a3b5d, the organization ID is a99999c7-b934-436c-9999-9999999a3b5d.

Set up a customer key

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

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

  2. After authenticating into your AWS organization and account, navigate to the Key Management Service (KMS) page.

  3. Click the left sidebar link for Customer managed keys.

  4. Click Create key.

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

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

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

  8. On Define key usage permissions, select your Key users from IAM users and roles, and optionally add Other AWS Accounts. Click Next.

  9. On the Review page, review the selected options and generated Key policy.

  10. 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": "*"
            },
  11. 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

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

Once your CMK with assigned role and permissions are setup, 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 & 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.

The Security Settings page displays any defined Customer Keys in your organization.

Security Settings displays keys for your organization.

These are the possible statuses:

In-Use

A database in your organization is actively using the key.

Available

Indicates a Customer Key has been added for your organization, but no Astra DB Classic database with that Provider and Region combination is using the key.

Once you add your customer keys, your Astra DB databases in the organization with the same provider and region combination are encrypted via the cloud provider’s customer key in the storage buckets.

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