Prerequisites Specifying the AWS KMS key for a new ledger Updating the AWS KMS key of an existing ledger Monitoring your AWS KMS keys

Using customer managed keys in Amazon QLDB

You can use the AWS Management Console, the AWS Command Line Interface (AWS CLI), or the QLDB API to specify the AWS KMS key for new ledgers and existing ledgers in Amazon QLDB. The following topics describe how to manage and monitor the usage of your customer managed keys in QLDB.

Topics

Prerequisites
Specifying the AWS KMS key for a new ledger
Updating the AWS KMS key of an existing ledger
Monitoring your AWS KMS keys

Prerequisites

Before you can protect a QLDB ledger with a customer managed key, you must first create the key in AWS Key Management Service (AWS KMS). You must also specify a key policy that allows QLDB to create grants on that AWS KMS key on your behalf.

Creating a customer managed key

To create a customer managed key, follow the steps in Creating symmetric encryption KMS keys in the AWS Key Management Service Developer Guide. QLDB doesn't support asymmetric keys.

Setting a key policy

Key policies are the primary way to control access to customer managed keys in AWS KMS. Every customer managed key must have exactly one key policy. The statements in the key policy document determine who has permission to use the KMS key and how they can use it. For more information, see Using key policies in AWS KMS.

You can specify a key policy when you create your customer managed key. To change a key policy for an existing customer managed key, see Changing a key policy.

To allow QLDB to use your customer managed key, the key policy must include permissions for the following AWS KMS actions:

kms:CreateGrant – Adds a grant to a customer managed key. Grants control access to a specified KMS key.

When you create or update a ledger with a specified customer managed key, QLDB creates grants that allow access to the grant operations that it requires. The grant operations include the following:
kms:DescribeKey – Returns detailed information about a customer managed key. QLDB uses this information to validate the key.

Key policy example

The following is a key policy example that you can use for QLDB. This policy allows principals that are authorized to use QLDB from the account 111122223333 to call the DescribeKey and CreateGrant operations on the resource arn:aws:kms:us-east-1:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab.

To use this policy, replace us-east-1, 111122223333, and 1234abcd-12ab-34cd-56ef-1234567890ab in the example with your own information.


{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Sid" : "Allow access to principals authorized to use Amazon QLDB",
            "Effect" : "Allow",
            "Principal" : {
                "AWS" : "*"
            },
            "Action" : [
                "kms:DescribeKey",
                "kms:CreateGrant"
            ],
            "Resource" : "arn:aws:kms:us-east-1:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab",
            "Condition" : {
                "StringEquals" : {
                    "kms:ViaService" : "qldb.us-east-1.amazonaws.com",
                    "kms:CallerAccount" : "111122223333"
                }
            }
        }
    ]
}

Specifying the AWS KMS key for a new ledger

Follow these steps to specify a KMS key when you create new ledger using the QLDB console or the AWS CLI.

You can specify a customer managed key by using an ID, alias, or Amazon Resource Name (ARN). To learn more, see Key identifiers (KeyId) in the AWS Key Management Service Developer Guide.

Note

Cross-Region keys are not supported. The specified KMS key must be in the same AWS Region as your ledger.

Sign in to the AWS Management Console, and open the Amazon QLDB console at https://console.aws.amazon.com/qldb.
Choose Create Ledger.
On the Create Ledger page, do the following:
- Ledger information – Enter a Ledger name that is unique among all ledgers in the current AWS account and Region.
- Permissions mode – Choose a permissions mode to assign to the ledger:
  - Allow all
  - Standard (Recommended)
- Encrypt data at rest – Choose the type of KMS key to use for encryption at rest:
  - Use AWS owned KMS key – Use a KMS key that is owned and managed by AWS on your behalf. This is the default option and requires no additional setup.
  - Choose a different AWS KMS key – Use a symmetric encryption KMS key in your account that you create, own, and manage.
    
    To create a new key by using the AWS KMS console, choose Create an AWS KMS key. For more information, see Creating symmetric encryption KMS keys in the AWS Key Management Service Developer Guide.
    
    To use an existing KMS key, choose one from the dropdown list or specify a KMS key ARN.
When the settings are as you want them, choose Create ledger.

You can access your QLDB ledger when its status becomes Active. This can take several minutes.

Use the AWS CLI to create a ledger in QLDB with the default AWS owned key or a customer managed key.

Example – To create a ledger with the default AWS owned key


aws qldb create-ledger --name my-example-ledger --permissions-mode STANDARD

Example – To create a ledger with a customer managed key


aws qldb create-ledger \
    --name my-example-ledger \
    --permissions-mode STANDARD \
    --kms-key arn:aws:kms:us-east-1:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab

Updating the AWS KMS key of an existing ledger

You can also use the QLDB console or the AWS CLI to update the KMS key of an existing ledger to an AWS owned key or a customer managed key at any time.

Note

Amazon QLDB launched support for customer managed AWS KMS keys on July 22, 2021. Any ledgers that were created before the launch are protected by AWS owned keys by default, but are currently not eligible for encryption at rest using customer managed keys.

You can view the creation time of your ledger on the QLDB console.

Key changes in QLDB are asynchronous. The ledger is fully accessible without any performance impact while the key change is being processed. The amount of time it takes to update a key varies depending on the ledger size.

You can specify a customer managed key by using an ID, alias, or Amazon Resource Name (ARN). To learn more, see Key identifiers (KeyId) in the AWS Key Management Service Developer Guide.

Note

Cross-Region keys are not supported. The specified KMS key must be in the same AWS Region as your ledger.

Sign in to the AWS Management Console, and open the Amazon QLDB console at https://console.aws.amazon.com/qldb.
In the navigation pane, choose Ledgers.
In the list of ledgers, select the ledger that you want to update, and then choose Edit ledger.
On the Edit ledger page, choose the type of KMS key to use for encryption at rest:
- Use AWS owned KMS key – Use a KMS key that is owned and managed by AWS on your behalf. This is the default option and requires no additional setup.
- Choose a different AWS KMS key – Use a symmetric encryption KMS key in your account that you create, own, and manage.
  
  To create a new key by using the AWS KMS console, choose Create an AWS KMS key. For more information, see Creating symmetric encryption KMS keys in the AWS Key Management Service Developer Guide.
  
  To use an existing KMS key, choose one from the dropdown list or specify a KMS key ARN.
Choose Confirm changes.

Use the AWS CLI to update an existing ledger in QLDB with the default AWS owned key or a customer managed key.

Example – To update a ledger with the default AWS owned key


aws qldb update-ledger --name my-example-ledger --kms-key AWS_OWNED_KMS_KEY

Example – To update a ledger with a customer managed key


aws qldb update-ledger \
    --name my-example-ledger \
    --kms-key arn:aws:kms:us-east-1:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab

Monitoring your AWS KMS keys

If you use a customer managed key to protect your Amazon QLDB ledgers, you can use AWS CloudTrail or Amazon CloudWatch Logs to track the requests that QLDB sends to AWS KMS on your behalf. For more information, see Monitoring AWS KMS keys in the AWS Key Management Service Developer Guide.

The following examples are CloudTrail log entries for the operations CreateGrant, GenerateDataKey, Decrypt, Encrypt, and DescribeKey.

CreateGrant

When you specify a customer managed key to protect your ledger, QLDB sends CreateGrant requests to AWS KMS on your behalf to allow access to your KMS key. In addition, QLDB uses the RetireGrant operation to remove grants when you delete a ledger.

The grants that QLDB creates are specific to a ledger. The principal in the CreateGrant request is the user who created the table.

The event that records the CreateGrant operation is similar to the following example event. The parameters include the Amazon Resource Name (ARN) of the customer managed key, the grantee principal and retiring principal (the QLDB service), and the operations that the grant covers.


{
    "eventVersion": "1.08",
    "userIdentity": {
        "type": "AssumedRole",
        "principalId": "AKIAIOSFODNN7EXAMPLE:sample-user",
        "arn": "arn:aws:sts::111122223333:assumed-role/Admin/sample-user",
        "accountId": "111122223333",
        "accessKeyId": "AKIAI44QH8DHBEXAMPLE",
        "sessionContext": {
            "sessionIssuer": {
                "type": "Role",
                "principalId": "AKIAIOSFODNN7EXAMPLE",
                "arn": "arn:aws:iam::111122223333:role/Admin",
                "accountId": "111122223333",
                "userName": "Admin"
            },
            "webIdFederationData": {},
            "attributes": {
                "mfaAuthenticated": "false",
                "creationDate": "2021-06-04T21:37:11Z"
            }
        },
        "invokedBy": "qldb.amazonaws.com"
    },
    "eventTime": "2021-06-04T21:40:00Z",
    "eventSource": "kms.amazonaws.com",
    "eventName": "CreateGrant",
    "awsRegion": "us-west-2",
    "sourceIPAddress": "qldb.amazonaws.com",
    "userAgent": "qldb.amazonaws.com",
    "requestParameters": {
        "keyId": "arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab",
        "granteePrincipal": "qldb.us-west-2.amazonaws.com",
        "operations": [
            "DescribeKey",
            "GenerateDataKey",
            "Decrypt",
            "Encrypt"
        ],
        "retiringPrincipal": "qldb.us-west-2.amazonaws.com"
    },
    "responseElements": {
        "grantId": "b3c83f999187ccc0979ef2ff86a1572237b6bba309c0ebce098c34761f86038a"
    },
    "requestID": "e99188d7-3b82-424e-b63e-e086d848ed60",
    "eventID": "88dc7ba5-4952-4d36-9ca8-9ab5d9598bab",
    "readOnly": false,
    "resources": [
        {
            "accountId": "111122223333",
            "type": "AWS::KMS::Key",
            "ARN": "arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab"
        }
    ],
    "eventType": "AwsApiCall",
    "managementEvent": true,
    "eventCategory": "Management",
    "recipientAccountId": "111122223333"
}

GenerateDataKey

When you specify a customer managed key to protect your ledger, QLDB creates a unique data key. It sends a GenerateDataKey request to AWS KMS that specifies the customer managed key for the ledger.

The event that records the GenerateDataKey operation is similar to the following example event. The user is the QLDB service account. The parameters include the ARN of the customer managed key, a data key specifier that requires a 32-byte length, and the encryption context that identifies the internal key hierarchy node.


{
    "eventVersion": "1.08",
    "userIdentity": {
        "type": "AWSService",
        "invokedBy": "qldb.amazonaws.com"
    },
    "eventTime": "2021-06-04T21:40:01Z",
    "eventSource": "kms.amazonaws.com",
    "eventName": "GenerateDataKey",
    "awsRegion": "us-west-2",
    "sourceIPAddress": "qldb.amazonaws.com",
    "userAgent": "qldb.amazonaws.com",
    "requestParameters": {
        "keyId": "arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab",
        "numberOfBytes": 32,
        "encryptionContext": {
            "key-hierarchy-node-id": "LY4HWMnkeZWKYi6MlitVJC",
            "key-hierarchy-node-version": "1"
        }
    },
    "responseElements": null,
    "requestID": "786977c9-e77c-467a-bff5-9ad5124a4462",
    "eventID": "b3f082cb-3e75-454e-bf0a-64be13075436",
    "readOnly": true,
    "resources": [
        {
            "accountId": "111122223333",
            "type": "AWS::KMS::Key",
            "ARN": "arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab"
        }
    ],
    "eventType": "AwsApiCall",
    "managementEvent": true,
    "eventCategory": "Management",
    "recipientAccountId": "111122223333",
    "sharedEventID": "26688de5-0b1c-43d3-bc4f-a18029b08446"
}

Decrypt

When you access a ledger, QLDB calls the Decrypt operation to decrypt the ledger's stored data key so that it can access the encrypted data in the ledger.

The event that records the Decrypt operation is similar to the following example event. The user is the QLDB service account. The parameters include the ARN of the customer managed key and the encryption context that identifies the internal key hierarchy node.


{
    "eventVersion": "1.08",
    "userIdentity": {
        "type": "AWSService",
        "invokedBy": "qldb.amazonaws.com"
    },
    "eventTime": "2021-06-04T21:40:56Z",
    "eventSource": "kms.amazonaws.com",
    "eventName": "Decrypt",
    "awsRegion": "us-west-2",
    "sourceIPAddress": "qldb.amazonaws.com",
    "userAgent": "qldb.amazonaws.com",
    "requestParameters": {
        "keyId": "arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab",
        "encryptionAlgorithm": "SYMMETRIC_DEFAULT",
        "encryptionContext": {
            "key-hierarchy-node-id": "LY4HWMnkeZWKYi6MlitVJC",
            "key-hierarchy-node-version": "1"
        }
    },
    "responseElements": null,
    "requestID": "28f2dd18-3cc1-4fe2-82f7-5154f4933ebf",
    "eventID": "603ad5d4-4744-4505-9c21-bd4a6cbd4b20",
    "readOnly": true,
    "resources": [
        {
            "accountId": "111122223333",
            "type": "AWS::KMS::Key",
            "ARN": "arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab"
        }
    ],
    "eventType": "AwsApiCall",
    "managementEvent": true,
    "eventCategory": "Management",
    "recipientAccountId": "111122223333",
    "sharedEventID": "7b6ce3e3-a764-42ec-8f90-5418c97ec411"
}

Encrypt

QLDB calls the Encrypt operation to encrypt plaintext into ciphertext using your customer managed key.

The event that records the Encrypt operation is similar to the following example event. The user is the QLDB service account. The parameters include the ARN of the customer managed key and the encryption context that specifies the internal unique ID of the ledger.


{
    "eventVersion": "1.08",
    "userIdentity": {
        "type": "AWSService",
        "invokedBy": "qldb.amazonaws.com"
    },
    "eventTime": "2021-06-04T21:40:01Z",
    "eventSource": "kms.amazonaws.com",
    "eventName": "Encrypt",
    "awsRegion": "us-west-2",
    "sourceIPAddress": "qldb.amazonaws.com",
    "userAgent": "qldb.amazonaws.com",
    "requestParameters": {
        "keyId": "arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab",
        "encryptionContext": {
            "LedgerId": "F6qRNziJLUXA4Vy2ZUv8YY"
        },
        "encryptionAlgorithm": "SYMMETRIC_DEFAULT"
    },
    "responseElements": null,
    "requestID": "b2daca7d-4606-4302-a2d7-5b3c8d30c64d",
    "eventID": "b8aace05-2e37-4fed-ae6f-a45a1c6098df",
    "readOnly": true,
    "resources": [
        {
            "accountId": "111122223333",
            "type": "AWS::KMS::Key",
            "ARN": "arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab"
        }
    ],
    "eventType": "AwsApiCall",
    "managementEvent": true,
    "eventCategory": "Management",
    "recipientAccountId": "111122223333",
    "sharedEventID": "ce420ab0-288e-4b4f-aee8-541e18a28aa5"
}

DescribeKey

QLDB calls the DescribeKey operation to determine whether the KMS key that you specified exists in the AWS account and Region.

The event that records the DescribeKey operation is similar to the following example event. The principal is the user in your AWS account who specified the KMS key. The parameters include the ARN of the customer managed key.


{
    "eventVersion": "1.08",
    "userIdentity": {
        "type": "AssumedRole",
        "principalId": "AKIAIOSFODNN7EXAMPLE:sample-user",
        "arn": "arn:aws:sts::111122223333:assumed-role/Admin/sample-user",
        "accountId": "111122223333",
        "accessKeyId": "AKIAI44QH8DHBEXAMPLE",
        "sessionContext": {
            "sessionIssuer": {
                "type": "Role",
                "principalId": "AKIAIOSFODNN7EXAMPLE",
                "arn": "arn:aws:iam::111122223333:role/Admin",
                "accountId": "111122223333",
                "userName": "Admin"
            },
            "webIdFederationData": {},
            "attributes": {
                "mfaAuthenticated": "false",
                "creationDate": "2021-06-04T21:37:11Z"
            }
        },
        "invokedBy": "qldb.amazonaws.com"
    },
    "eventTime": "2021-06-04T21:40:00Z",
    "eventSource": "kms.amazonaws.com",
    "eventName": "DescribeKey",
    "awsRegion": "us-west-2",
    "sourceIPAddress": "qldb.amazonaws.com",
    "userAgent": "qldb.amazonaws.com",
    "requestParameters": {
        "keyId": "arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab"
    },
    "responseElements": null,
    "requestID": "a30586af-c783-4d25-8fda-33152c816c36",
    "eventID": "7a9caf07-2b27-44ab-afe4-b259533ebb88",
    "readOnly": true,
    "resources": [
        {
            "accountId": "111122223333",
            "type": "AWS::KMS::Key",
            "ARN": "arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab"
        }
    ],
    "eventType": "AwsApiCall",
    "managementEvent": true,
    "eventCategory": "Management",
    "recipientAccountId": "111122223333"
}

Warning Javascript is disabled or is unavailable in your browser.

To use the Amazon Web Services Documentation, Javascript must be enabled. Please refer to your browser's Help pages for instructions.

Document Conventions

How it works

Encryption in transit