Direct KMS 材料提供程序

注意

我们的客户端加密库已重命名为 AWS 数据库加密 SDK。以下主题提供有关适用于 Java 的 DynamoDB 加密客户端版本 1.x—2.x 以及适用于 Python 的 DynamoDB 加密客户端版本 1.x—3.x 的信息。有关更多信息，请参阅适用于 DynamoDB 的 AWS 数据库加密 SDK 版本支持。

Direct KMS 材料提供程序（Direct KMS 提供程序）借助从不让 AWS Key Management Service（AWS KMS）处于不加密状态的 AWS KMS key 保护您的表项目。此加密材料提供程序为每个表项目返回唯一的加密密钥和签名密钥。为此，它会在您每次加密或解密项目时调用 AWS KMS。

如果您以高频率且大规模地处理 DynamoDB 项目，您可能会超出 AWS KMS 每秒请求次数限制，从而导致处理延迟。如果需要超出限制，请在 AWS Support 中心并创建案例。您也可以考虑使用密钥重复次数使用有限的加密材料提供程序，例如最新提供程序。

要使用 Direct KMS 提供程序，调用方必须具有一个 AWS 账户、至少一个 AWS KMS key，以及在 AWS KMS key 上调用 GenerateDataKey 和 Decrypt 操作的权限。AWS KMS key 必须是对称加密密钥；DynamoDB 加密客户端不支持非对称加密。如果您使用的是 DynamoDB 全局表，则可能需要指定一个 AWS KMS 多区域密钥。有关详细信息，请参阅 使用方法。

注意

使用 Direct KMS 提供程序时，主键属性的名称和值以明文显示在 AWS KMS 加密上下文和相关 AWS KMS 操作的 AWS CloudTrail 日志中。但是，DynamoDB 加密客户端从不公开任意加密属性值的明文。

Direct KMS 提供程序是 DynamoDB 加密客户端支持的几个加密材料提供程序（CMP）之一。有关其他 CMP 的信息，请参阅加密材料提供程序。

有关示例代码，请参阅：

• Java：AwsKmsEncryptedItem

• Python：aws-kms-encrypted-table、aws-kms-encrypted-item

使用方法

要创建 Direct KMS 提供程序，请使用密钥 ID 参数在您的账户中指定对称加密 KMS 密钥。密钥 ID 参数的值可以是 AWS KMS key 的密钥 ID、密钥 ARN、别名名称或别名 ARN。有关密钥标识符的详细信息，请参阅《AWS Key Management Service 开发人员指南》中的密钥标识符。

Direct KMS 提供程序需要对称的加密 KMS 密钥。不能使用非对称 KMS 密钥。但是，可以使用多区域 KMS 键、包含导入的密钥材料的 KMS 密钥，或自定义密钥存储中的 KMS 密钥。您必须对 KMS 密钥拥有 kms:GenerateDataKey 和 kms:Decrypt 权限。因此，您必须使用客户托管式密钥，而不是 AWS 托管密钥或 AWS 拥有的 KMS 密钥。

适用于 Python 的 DynamoDB 加密客户端在密钥 ID 参数值（如果包含该值）中确定从该区域调用 AWS KMS 的区域。否则，它将使用 AWS KMS 客户端中的区域（如果您指定）或您在 AWS SDK for Python (Boto3) 中配置的区域。有关 Python 中的区域选择的信息，请参阅《适用于 Python（Boto3）的 AWS SDK API 参考》中的配置。

如果您指定的客户端包含区域，则适用于 Java 的 DynamoDB 加密客户端将确定从 AWS KMS 客户端中的区域调用 AWS KMS 的区域。否则，它将使用您在 AWS SDK for Java 中配置的区域。有关 AWS SDK for Java 中的区域选择的信息，请参阅《AWS SDK for Java 开发人员指南》中的 AWS 区域 选择。

Java

// Replace the example key ARN and Region with valid values for your application
final String keyArn = 'arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab'
final String region = 'us-west-2'
      
final AWSKMS kms = AWSKMSClientBuilder.standard().withRegion(region).build();
final DirectKmsMaterialProvider cmp = new DirectKmsMaterialProvider(kms, keyArn);

Python

以下示例使用密钥 ARN 指定 AWS KMS key。如果您的密钥标识符不包括 AWS 区域，则 DynamoDB 加密客户端将从已配置的 Botocore 会话（如果有）或 Boto 默认会话中获取区域。

# Replace the example key ID with a valid value
kms_key = 'arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab'
kms_cmp = AwsKmsCryptographicMaterialsProvider(key_id=kms_key)

如果您使用的是 Amazon DynamoDB 全局表，则建议您使用 AWS KMS 多区域密钥对数据进行加密。多区域密钥是不同 AWS 区域 中的 AWS KMS keys，可以互操作，因为这些密钥具有相同的密钥 ID 和密钥材料。有关详细信息，请参阅《AWS Key Management Service 开发人员指南》中的使用多区域密钥。

注意

如果您使用的是全局表版本 2017.11.29，则必须设置属性操作，这样，保留的复制字段就不会被加密或签名。有关详细信息，请参阅 旧版本全局表存在的问题。

要在 DynamoDB 加密客户端中使用多区域密钥，请创建多区域密钥并将其复制到应用程序运行所在的区域。然后将 Direct KMS 提供程序配置为使用 DynamoDB 加密客户端调用 AWS KMS 所在区域中的多区域密钥。

以下示例将 DynamoDB 加密客户端配置为在美国东部（弗吉尼亚州北部）（us-east-1）区域中的加密数据，并使用多区域密钥，在美国西部（俄勒冈州）（us-west-2）区域中对其进行解密。

Java

在此示例中，DynamoDB 加密客户端从 AWS KMS 客户端中的区域中获取调用 AWS KMS 的区域。keyArn 值标识同一区域中的多区域密钥。

// Encrypt in us-east-1

// Replace the example key ARN and Region with valid values for your application
final String usEastKey = 'arn:aws:kms:us-east-1:111122223333:key/mrk-1234abcd12ab34cd56ef1234567890ab'
final String region = 'us-east-1'
      
final AWSKMS kms = AWSKMSClientBuilder.standard().withRegion(region).build();
final DirectKmsMaterialProvider cmp = new DirectKmsMaterialProvider(kms, usEastKey);

// Decrypt in us-west-2

// Replace the example key ARN and Region with valid values for your application
final String usWestKey = 'arn:aws:kms:us-west-2:111122223333:key/mrk-1234abcd12ab34cd56ef1234567890ab'
final String region = 'us-west-2'
      
final AWSKMS kms = AWSKMSClientBuilder.standard().withRegion(region).build();
final DirectKmsMaterialProvider cmp = new DirectKmsMaterialProvider(kms, usWestKey);

Python

在此示例中，DynamoDB 加密客户端从密钥 ARN 中获取从区域中调用 AWS KMS 的区域。

# Encrypt in us-east-1

# Replace the example key ID with a valid value
us_east_key = 'arn:aws:kms:us-east-1:111122223333:key/mrk-1234abcd12ab34cd56ef1234567890ab'
kms_cmp = AwsKmsCryptographicMaterialsProvider(key_id=us_east_key)

# Decrypt in us-west-2

# Replace the example key ID with a valid value
us_west_key = 'arn:aws:kms:us-west-2:111122223333:key/mrk-1234abcd12ab34cd56ef1234567890ab'
kms_cmp = AwsKmsCryptographicMaterialsProvider(key_id=us_west_key)

工作原理

Direct KMS 提供程序返回受您指定的 AWS KMS key 保护的加密密钥和签名密钥，如下图所示。

• 要生成加密材料，Direct KMS 提供程序会要求 AWS KMS 使用您指定的 AWS KMS key 为每个项目生成一个唯一的数据密钥。它从数据密钥的明文副本中派生项目的加密密钥和签名密钥，然后返回加密密钥和签名密钥以及加密的数据密钥，后者存储在项目的材料说明属性中。

  项目加密程序使用加密密钥和签名密钥并尽快将它们从内存中删除。仅其派生自的数据密钥的加密副本保存在加密项目中。

• 要生成解密材料，Direct KMS 提供程序要求 AWS KMS 解密加密数据密钥。然后，它从明文数据密钥派生验证密钥和签名密钥，然后将这些密钥返回至项目加密程序。

  项目加密程序会验证项目，而且如果验证成功，会解密加密的值。然后，它会尽快从内存中删除这些密钥。

获取加密材料

本部分详细介绍了 Direct KMS 提供程序收到来自项目加密程序的加密材料请求时的输入、输出和处理。

输入（来自应用程序）

• AWS KMS key 的密钥 ID。

输入（来自项目加密程序）

• DynamoDB 加密上下文

输出（至项目加密程序）

• 加密密钥（明文）

• 签名密钥

• 在实际材料描述中：这些值保存在客户端将添加到项目的材料描述属性中。

  • amzn-ddb-env-key：由 AWS KMS key 加密的 Base64 编码的数据密钥

  • amzn-ddb-env-alg：加密算法，默认情况下为 AES/256

  • amzn-ddb-sig-alg：签名算法，默认情况下为 HmacSHA256/256

  • amzn-ddb-wrap-alg：kms

处理

1. Direct KMS 提供程序向 AWS KMS 发送使用指定 AWS KMS key 的请求，以便为项目生成唯一数据密钥。该操作会返回明文密钥以及由 AWS KMS key 加密的副本。这称为初始密钥材料。

   请求包括 AWS KMS 加密上下文中的以下明文值。这些非密钥值以加密方式绑定到加密对象，因此，解密时需要相同的加密上下文。您可以使用这些值在 AWS CloudTrail 日志中标识对 AWS KMS 的调用。

   • amzn-ddb-env-alg – 加密算法，默认情况下为 AES/256

   • amzn-ddb-sig-alg – 签名算法，默认情况下为 HmacSHA256/256

   • （可选）aws-kms-table – 表名称

   • （可选）分区键名称 – 分区键值（二进制值采用 Base64 编码）

   • （可选）排序键名称 – 排序键值（二进制值采用 Base64 编码）

   Direct KMS 提供程序从该项目的 DynamoDB 加密上下文中获取 AWS KMS 加密上下文的值。如果 DynamoDB 加密上下文不包括表名称等值，则 AWS KMS 加密上下文中不包含名称-值对。

2. Direct KMS 提供程序从数据密钥派生对称加密密钥和签名密钥。默认情况下，它使用安全哈希算法 (SHA) 256 和基于 RFC5869 HMAC 的密钥派生函数来派生 256 位 AES 对称加密密钥和 256 位 HMAC-SHA-256 签名密钥。

3. Direct KMS 提供程序将输出返回到项目加密程序。

4. 项目加密程序通过使用在实际材料说明中指定的算法，使用加密密钥加密指定的属性并使用签名密钥签署它们。它会尽快从内存中删除明文密钥。

显示更多显示更少

获取解密材料

本部分详细介绍了 Direct KMS 提供程序在从项目加密程序收到解密材料的请求时的输入、输出和处理。

输入（来自应用程序）

• AWS KMS key 的密钥 ID。

  密钥 ID 的值可以是 AWS KMS key 的密钥 ID、密钥 ARN、别名名称或别名 ARN。未包含在密钥 ID 中的任何值，如区域，必须在 AWS 命名配置文件中可用。密钥 ARN 提供了 AWS KMS 需要的所有值。

输入（来自项目加密程序）

• 包含材料描述属性内容的 DynamoDB 加密上下文的副本。

输出（至项目加密程序）

• 加密密钥（明文）

• 签名密钥

处理

1. Direct KMS 提供程序从加密项目中的材料描述属性获取加密数据密钥。

2. 它要求 AWS KMS 使用指定的 AWS KMS key 来解密已加密的数据密钥。此操作会返回明文密钥。

   此请求必须使用用于生成和加密数据密钥的相同的 AWS KMS 加密上下文。

   • aws-kms-table – 表名称

   • 分区键名称 – 分区键值（二进制值采用 Base64 编码）

   • （可选）排序键名称 – 排序键值（二进制值采用 Base64 编码）

   • amzn-ddb-env-alg – 加密算法，默认情况下为 AES/256

   • amzn-ddb-sig-alg – 签名算法，默认情况下为 HmacSHA256/256

3. Direct KMS 提供程序使用安全哈希算法 (SHA) 256 和基于 RFC5869 HMAC 的密钥派生函数来从数据密钥派生 256 位 AES 对称加密密钥和 256 位 HMAC-SHA-256 签名密钥。

4. Direct KMS 提供程序将输出返回到项目加密程序。

5. 项目加密程序将使用此签名密钥验证项目。如果它成功，则会使用对称加密密钥来解决加密的属性值。这些操作使用在实际材料说明中指定的加密和签名算法。项目加密程序它会尽快从内存中删除明文密钥。

显示更多显示更少