本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。
# 在 Amazon QLDB 中使用客户托管的密钥
您可以使用 AWS 管理控制台、 AWS Command Line Interface (AWS CLI) 或 QLDB API 为 Amazon QLDB 中的新账 AWS KMS key 本和现有账本指定。以下主题介绍如何在 QLDB 中管理和监控客户托管密钥的使用情况。
**Topics**
+ [先决条件](#encryption-at-rest.using-cust-keys.prereqs)
+ [为新分类账指定 AWS KMS key](#encryption-at-rest.using-cust-keys.specify)
+ [更新现有分类账的 AWS KMS key](#encryption-at-rest.using-cust-keys.update)
+ [监控 AWS KMS keys](#encryption-at-rest.using-cust-keys.monitor)
## 先决条件
必须先在 () 中创建密钥，然后才能使用客户托管密钥保护 QLDB 账本。 AWS Key Management Service AWS KMS您还必须指定一项密钥策略，允许 QLDB 代表您创建授权。 AWS KMS key
**在 中创建客户托管的密钥**
要创建客户托管密钥，请按照*《AWS Key Management Service 开发人员指南》*的[创建对称加密 KMS 密钥](https://docs.aws.amazon.com/kms/latest/developerguide/create-keys.html#create-symmetric-cmk)中的步骤进行操作。QLDB 不支持[非对称密钥](https://docs.aws.amazon.com/kms/latest/developerguide/symmetric-asymmetric.html)。
**设置密钥策略**
密钥策略是控制中客户托管密钥访问权限的主要方法 AWS KMS。每个 KMS 密钥必须只有一个密钥策略。密钥策略文档中的语句确定谁有权使用 KMS 密钥以及如何使用它。有关更多信息，请参阅[中的使用密钥策略 AWS KMS](https://docs.aws.amazon.com/kms/latest/developerguide/key-policies.html)。
创建客户托管式密钥时，可以指定密钥策略。要更改现有客户托管密钥的密钥策略，请参阅[更改密钥策略](https://docs.aws.amazon.com/kms/latest/developerguide/key-policy-modifying.html)。
要允许 QLDB 使用您的客户托管密钥，密钥策略必须包含以下操作的权限： AWS KMS
+ [kms: CreateGrant](https://docs.aws.amazon.com/kms/latest/APIReference/API_CreateGrant.html) — 向客户托管密钥添加[授权](https://docs.aws.amazon.com/kms/latest/developerguide/grants.html)。授予对指定 KMS 密钥的控制访问权限。
当您使用指定的客户管理密钥创建或更新账本时，QLDB 会创建授权，以允许访问其所需的[授权操作](https://docs.aws.amazon.com/kms/latest/developerguide/grants.html#terms-grant-operations)。授权操作包括：
+ [GenerateDataKey](https://docs.aws.amazon.com/kms/latest/APIReference/API_GenerateDataKey.html)
+ [Decrypt](https://docs.aws.amazon.com/kms/latest/APIReference/API_Decrypt.html)
+ [Encrypt](https://docs.aws.amazon.com/kms/latest/APIReference/API_Encrypt.html)
+ [kms: DescribeKey](https://docs.aws.amazon.com/kms/latest/APIReference/API_DescribeKey.html) — 返回有关客户托管密钥的详细信息。QLDB 使用此信息来验证密钥。
**密钥策略示例**
以下是您可以 用于 QLDB 的一个示例密钥策略。此策略略允许经授权使用 QLDB 的账户`111122223333`委托人调用资源 `arn:aws:kms:us-east-1:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab` 上的 `DescribeKey` 和 `CreateGrant` 操作。
要使用此政策，请用您自己的信息替换*us-east-1*示例*1234abcd-12ab-34cd-56ef-1234567890ab*中的*111122223333*、和。
```
{
"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"
}
}
}
]
}
```
## 为新分类账指定 AWS KMS key
使用 QLDB 控制台或 AWS CLI创建新分类账时，请按照以下步骤指定 KMS 密钥。
要指定客户托管的密钥，您可以使用其密钥 ID、Amazon 资源名称（ARN）、别名或别名 ARN。要了解更多信息，请参阅《*AWS Key Management Service 开发者指南》*中的[密钥标识符 (KeyId)](https://docs.aws.amazon.com/kms/latest/developerguide/concepts.html#key-id)。
**注意**
不支持跨区域密钥。指定的 KMS 密钥必须与您的账本 AWS 区域 相同。
### 创建分类账（控制台）
1. [登录并打开亚马逊 QLDB 控制台，网址为 /qldb。 AWS 管理控制台 https://console.aws.amazon.com](https://console.aws.amazon.com/qldb)
1. 选择 **创建分类账**。
1. 在 **创建分类账** 页面上，执行以下操作：
+ **分类帐信息**-输入在当前 AWS 账户 和区域的所有分类帐中唯一的分类**帐名称**。
+ **权限模式** - 选择要分配给分类帐的权限模式：
+ **允许全部**
+ **标准**（*已推荐*）
+ **加密静态数据**：选择用于静态加密的 KMS 密钥类型：
+ **使用 AWS 拥有的 KMS 密**钥-使用由 AWS 您代表拥有和管理的 KMS 密钥。这是默认选项，无需额外设置。
+ **选择其他 AWS KMS 密钥**-在您的账户中使用由您创建、拥有和管理的对称加密 KMS 密钥。
要使用 AWS KMS 控制台创建新密钥，请选择**创建 AWS KMS 密钥**。有关更多信息，请参阅 [AWS Key Management Service 开发人员指南](https://docs.aws.amazon.com/kms/latest/developerguide/create-keys.html#create-symmetric-cmk) 中的*创建对称加密 KMS 密钥*。
要使用现有 KMS 密钥，请从下拉列表中选择一个密钥或指定 KMS 密钥 ARN。
1. 根据需要进行设置后，选择 **创建分类账**。
当 QLDB 分类账的状态变为“**活跃**”时，您可以访问该 QLDB 分类账。这个过程可能需要几分钟。
### 创建分类账（AWS CLI）
使用在 AWS CLI QLDB 中使用 AWS 拥有的密钥 默认密钥或客户托管密钥创建账本。
**Example — 使用默认 AWS 拥有的密钥创建分类账**
```
aws qldb create-ledger --name my-example-ledger --permissions-mode STANDARD
```
**Example — 创建包含客户托管密钥的分类账**
```
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
```
## 更新现有分类账的 AWS KMS key
您也可以随时使用 QLDB 控制台或 AWS CLI 将现有账本的 KMS 密钥更新 AWS 拥有的密钥 为或客户托管密钥。
**注意**
亚马逊 QLDB 于 2021 年 7 月 22 日推出了对客户 AWS KMS keys 管理的支持。默认情况下，在发布之前创建的所有账本都 AWS 拥有的密钥 受到保护，但目前不符合使用客户托管密钥进行静态加密的资格。
您可在 QLDB 控制台查看分类账的创建时间。
QLDB 中的关键更改为异步类型。在处理关键变更期间，分类账完全可以访问，不会对性能产生任何影响。秘钥更新所用时间因分类账大小而异。
要指定客户托管的密钥，您可以使用其密钥 ID、Amazon 资源名称（ARN）、别名或别名 ARN。要了解更多信息，请参阅《*AWS Key Management Service 开发者指南》*中的[密钥标识符 (KeyId)](https://docs.aws.amazon.com/kms/latest/developerguide/concepts.html#key-id)。
**注意**
不支持跨区域密钥。指定的 KMS 密钥必须与您的账本 AWS 区域 相同。
### 创建分类账（控制台）
1. [登录并打开亚马逊 QLDB 控制台，网址为 /qldb。 AWS 管理控制台 https://console.aws.amazon.com](https://console.aws.amazon.com/qldb)
1. 在导航窗格中，选择**分类账**。
1. 在分类账列表中，选择要更新的分类帐，然后选择**编辑分类账**。
1. 在**编辑分类账**页面上，选择用于静态加密的 KMS 密钥类型：
+ **使用 AWS 拥有的 KMS 密**钥-使用由 AWS 您代表拥有和管理的 KMS 密钥。这是默认选项，无需额外设置。
+ **选择其他 AWS KMS 密钥**-在您的账户中使用由您创建、拥有和管理的对称加密 KMS 密钥。
要使用 AWS KMS 控制台创建新密钥，请选择**创建 AWS KMS 密钥**。有关更多信息，请参阅 [AWS Key Management Service 开发人员指南](https://docs.aws.amazon.com/kms/latest/developerguide/create-keys.html#create-symmetric-cmk) 中的*创建对称加密 KMS 密钥*。
要使用现有 KMS 密钥，请从下拉列表中选择一个密钥或指定 KMS 密钥 ARN。
1. 选择“**确认更改**”。
### 更新分类账（AWS CLI）
使用使用 AWS 拥有的密钥 默认密钥或客户托管密钥更新 QLDB 中的现有账本。 AWS CLI
**Example — 使用默认 AWS 拥有的密钥创建分类账**
```
aws qldb update-ledger --name my-example-ledger --kms-key AWS_OWNED_KMS_KEY
```
**Example — 更新包含客户托管密钥的分类账**
```
aws qldb update-ledger \
--name my-example-ledger \
--kms-key arn:aws:kms:us-east-1:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab
```
## 监控 AWS KMS keys
如果您使用客户托管密钥来保护您的 Amazon QLDB 账本，则可以使用[AWS CloudTrail](https://docs.aws.amazon.com/awscloudtrail/latest/userguide/cloudtrail-user-guide.html)或 [A CloudWatch mazon](https://docs.aws.amazon.com/AmazonCloudWatch/latest/logs/WhatIsCloudWatchLogs.html) Logs 来跟踪 QLDB 代表您发送的请求。 AWS KMS 有关更多信息，请参阅 *AWS Key Management Service 开发人员指南* 中的 [监控 AWS KMS keys](https://docs.aws.amazon.com/kms/latest/developerguide/monitoring-overview.html)。
以下示例是操作`CreateGrant`、、`GenerateDataKey``Decrypt``Encrypt`、和的 CloudTrail 日志条目`DescribeKey`。
**CreateGrant**
当您指定客户托管密钥来保护您的账本时，QLDB `CreateGrant` 会代表您向发送请求 AWS KMS 以允许访问您的 KMS 密钥。此外，当您删除分类账时，QLDB 会使用 `RetireGrant` 该操作来删除授权。
创建的授权特定于表。CreateGrant 请求`CreateGrant`的委托人是创建了表的用户。
记录 `CreateGrant` 操作的事件与以下示例事件类似。参数包括表的 CMK 的 Amazon 资源名称（ARN）、被授权委托人和停用委托人（ 服务）以及授权涵盖的操作。
```
{
"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**
当您指定客户托管密钥来保护分类账时，QLDB 会创建一个唯一的数据密钥。它向发送`GenerateDataKey`请求 AWS KMS ，指定账本的客户托管密钥。
记录 `GenerateDataKey` 操作的事件与以下示例事件类似。该用户是 QLDB 服务账户。这些参数包括客户管理的密钥的 ARN、一个要求为 32 字节长度的数据密钥说明符，以及标识内部密钥层次节点的加密上下文。
```
{
"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**
当您访问分类账时，QLDB 会调用 `Decrypt` 操作来解密分类账存储的数据密钥，以便它可以访问分类账中的加密数据。
记录 `Decrypt` 操作的事件与以下示例事件类似。该用户是 QLDB 服务账户。这些参数包括客户托管密钥的 ARN 和标识内部密钥层次结构节点的加密上下文。
```
{
"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 会调用 `Encrypt` 该操作使用您的客户托管密钥将明文加密为密文。
记录 `Encrypt` 操作的事件与以下示例事件类似。该用户是 QLDB 服务账户。这些参数包括客户托管密钥的 ARN 和指定分类账内部唯一 ID 的加密上下文。
```
{
"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 会调用 `DescribeKey` 操作来确定您指定的 KMS 密钥是否存在于 AWS 账户 和区域中。
记录 `DescribeKey` 操作的事件与以下示例事件类似。委托 AWS 账户 人是您中指定 KMS 密钥的用户。参数包括客户自主管理型密钥的 ARN。
```
{
"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"
}
```