Encryption at rest: How to use customer managed keys to encrypt tables in Amazon Keyspaces

You can use the console or CQL statements to specify the AWS KMS key for new tables and update the encryption keys of existing tables in Amazon Keyspaces. The following topic outlines how to implement customer managed keys for new and existing tables.

Prerequisites: Create a customer managed key using AWS KMS and grant permissions to Amazon Keyspaces

Before you can protect an Amazon Keyspaces table with a customer managed key, you must first create the key in AWS Key Management Service (AWS KMS) and then authorize Amazon Keyspaces to use that key.

Step 1: Create a customer managed key using AWS KMS

To create a customer managed key to be used to protect an Amazon Keyspaces table, you can follow the steps in Creating symmetric encryption KMS keys using the console or the AWS API.

Step 2: Authorize the use of your customer managed key

Before you can choose a customer managed key to protect an Amazon Keyspaces table, the policies on that customer managed key must give Amazon Keyspaces permission to use it on your behalf. You have full control over the policies and grants on the customer managed key. You can provide these permissions in a key policy, an IAM policy, or a grant.

Amazon Keyspaces doesn't need additional authorization to use the default AWS owned key to protect the Amazon Keyspaces tables in your AWS account.

The following topics show how to configure the required permissions using IAM policies and grants that allow Amazon Keyspaces tables to use a customer managed key.

Key policy for customer managed keys

When you select a customer managed key to protect an Amazon Keyspaces table, Amazon Keyspaces gets permission to use the customer managed key on behalf of the principal who makes the selection. That principal, a user or role, must have the permissions on the customer managed key that Amazon Keyspaces requires.

At a minimum, Amazon Keyspaces requires the following permissions on a customer managed key:

Example key policy

For example, the following example key policy provides only the required permissions. The policy has the following effects:

Before using an example key policy, replace the example principals with actual principals from your AWS account.

{
  "Id": "key-policy-cassandra",
  "Version":"2012-10-17",
  "Statement": [
    {
      "Sid" : "Allow access through Amazon Keyspaces for all principals in the account that are authorized to use Amazon Keyspaces",
      "Effect": "Allow",
      "Principal": {"AWS": "arn:aws:iam::111122223333:user/db-lead"},
      "Action": [
        "kms:Encrypt",
        "kms:Decrypt",
        "kms:ReEncrypt*",
        "kms:GenerateDataKey*",
        "kms:DescribeKey",
        "kms:CreateGrant"
      ],
      "Resource": "*",      
      "Condition": { 
         "StringLike": {
           "kms:ViaService" : "cassandra.*.amazonaws.com"
         }
      }
    },
    {
      "Sid":  "Allow administrators to view the customer managed key and revoke grants",
      "Effect": "Allow",
      "Principal": {
        "AWS": "arn:aws:iam::111122223333:role/db-team"
       },
      "Action": [
        "kms:Describe*",
        "kms:Get*",
        "kms:List*",
        "kms:RevokeGrant"
      ],
      "Resource": "*"
    }
  ]
}

Using grants to authorize Amazon Keyspaces

In addition to key policies, Amazon Keyspaces uses grants to set permissions on a customer managed key. To view the grants on a customer managed key in your account, use the ListGrants operation. Amazon Keyspaces doesn't need grants, or any additional permissions, to use the AWS owned key to protect your table.

Amazon Keyspaces uses the grant permissions when it performs background system maintenance and continuous data protection tasks. It also uses grants to generate table keys.

Each grant is specific to a table. If the account includes multiple tables encrypted under the same customer managed key, there is a grant of each type for each table. The grant is constrained by the Amazon Keyspaces encryption context, which includes the table name and the AWS account ID. The grant includes permission to retire the grant if it's no longer needed.

To create the grants, Amazon Keyspaces must have permission to call CreateGrant on behalf of the user who created the encrypted table.

The key policy can also allow the account to revoke the grant on the customer managed key. However, if you revoke the grant on an active encrypted table, Amazon Keyspaces will not be able to protect and maintain the table.

Step 3: Specify a customer managed key for a new table

Follow these steps to specify the customer managed key on a new table using the Amazon Keyspaces console or CQL.

Create an encrypted table using a customer managed key (console)

Create a new table using a customer managed key for encryption at rest (CQL)

To create a new table that uses a customer managed key for encryption at rest, you can use the CREATE TABLE statement as shown in the following example. Make sure to replace the key ARN with an ARN for a valid key with permissions granted to Amazon Keyspaces.

CREATE TABLE my_keyspace.my_table(id bigint, name text, place text STATIC, PRIMARY KEY(id, name)) WITH CUSTOM_PROPERTIES = {
        'encryption_specification':{
                'encryption_type': 'CUSTOMER_MANAGED_KMS_KEY', 
                'kms_key_identifier':'arn:aws:kms:eu-west-1:5555555555555:key/11111111-1111-111-1111-111111111111'
            }
    };

If you receive an Invalid Request Exception, you need to confirm that the customer managed key is valid and Amazon Keyspaces has the required permissions. To confirm that the key has been configured correctly, see Troubleshooting key access in the AWS Key Management Service Developer Guide.

Step 4: Update the encryption key of an existing table

You can also use the Amazon Keyspaces console or CQL to change the encryption keys of an existing table between an AWS owned key and a customer managed KMS key at any time.

Update an existing table with the new customer managed key (console)

Update the encryption key used for an existing table

To change the encryption key of an existing table, you use the ALTER TABLE statement to specify a customer managed key for encryption at rest. Make sure to replace the key ARN with an ARN for a valid key with permissions granted to Amazon Keyspaces.

ALTER TABLE my_keyspace.my_table WITH CUSTOM_PROPERTIES = {     
              'encryption_specification':{ 
                      'encryption_type': 'CUSTOMER_MANAGED_KMS_KEY', 
                      'kms_key_identifier':'arn:aws:kms:eu-west-1:5555555555555:key/11111111-1111-111-1111-111111111111'     
                  } 
         };

If you receive an Invalid Request Exception, you need to confirm that the customer managed key is valid and Amazon Keyspaces has the required permissions. To confirm that the key has been configured correctly, see Troubleshooting key access in the AWS Key Management Service Developer Guide.

To change the encryption key back to the default encryption at rest option with AWS owned keys, you can use the ALTER TABLE statement as shown in the following example.

ALTER TABLE my_keyspace.my_table WITH CUSTOM_PROPERTIES = {
                'encryption_specification':{
                      'encryption_type' : 'AWS_OWNED_KMS_KEY' 
                    } 
         };

Step 5: Use the Amazon Keyspaces encryption context in logs

An encryption context is a set of key–value pairs that contain arbitrary nonsecret data. When you include an encryption context in a request to encrypt data, AWS KMS cryptographically binds the encryption context to the encrypted data. To decrypt the data, you must pass in the same encryption context.

Amazon Keyspaces uses the same encryption context in all AWS KMS cryptographic operations. If you use a customer managed key to protect your Amazon Keyspaces table, you can use the encryption context to identify the use of the customer managed key in audit records and logs. It also appears in plaintext in logs, such as in logs for AWS CloudTrail and Amazon CloudWatch Logs.

In its requests to AWS KMS, Amazon Keyspaces uses an encryption context with three key–value pairs.

"encryptionContextSubset": {
    "aws:cassandra:keyspaceName": "my_keyspace",
    "aws:cassandra:tableName": "mytable"
    "aws:cassandra:subscriberId": "111122223333"
}

Step 6: Configure monitoring with AWS CloudTrail

If you use a customer managed key to protect your Amazon Keyspaces tables, you can use AWS CloudTrail logs to track the requests that Amazon Keyspaces sends to AWS KMS on your behalf.

The GenerateDataKey, DescribeKey, Decrypt, and CreateGrant requests are discussed in this section. In addition, Amazon Keyspaces uses a RetireGrant operation to remove a grant when you delete a table.