AWS KMS ECDH 密钥环

我们的客户端加密库已重命名为 AWS 数据库加密SDK。本开发人员指南仍提供有关 DynamoDB 加密客户端的信息。

重要

AWS KMS ECDH密钥环仅在材质提供者库的 1.5.0 版本中可用。

密 AWS KMS ECDH钥环使用非对称密钥协议AWS KMS keys来派生双方共享的对称包装密钥。首先，密钥环使用 Elliptic Curve Diffie-Hellman (ECDH) 密钥协议算法从发送者密钥对中的私钥和接收者的公钥中派生出共享密KMS钥。然后，密钥环使用共享密钥来派生用于保护您的数据加密密钥的共享包装密钥。 AWS 数据库加密SDK使用 (KDF_CTR_HMAC_SHA384) 派生共享封装密钥的密钥派生函数符合密钥派生NIST建议。

密钥派生函数返回 64 字节的密钥材料。为确保双方使用正确的密钥材料， AWS 数据库加密SDK使用前 32 字节作为承诺密钥，使用最后 32 字节作为共享封装密钥。解密时，如果密钥环无法复制存储在加密记录材料描述字段中的相同承诺密钥和共享包装密钥，则操作将失败。例如，如果您使用配置有 Alice 私钥和 Bob 公钥的密钥环对记录进行加密，则使用 B ob 的私钥和 Alice 的公钥配置的密钥环将复制相同的承诺密钥和共享包装密钥，并能够解密该记录。如果 Bob 的公钥不是来自KMS密钥对，那么 Bob 可以创建一个 Ra w 密ECDH钥环来解密记录。

AWS KMS ECDH密钥环使用-对称密钥对记录进行加密。AES GCM然后使用 AES-使用派生的共享包装密钥对数据密钥进行信封加密GCM。每个 AWS KMS ECDH密钥环只能有一个共享的包装密钥，但您可以在多密 AWS KMS ECDH钥环中单独或与其他密钥环一起包含多个密钥环。

AWS KMS ECDH 密钥环所需权限

AWS 数据库加密SDK不需要 AWS 帐户，也不依赖于任何 AWS 服务。但是，要使用 AWS KMS ECDH密钥环，您需要一个 AWS 帐户，并在密钥环 AWS KMS keys 中拥有以下最低权限。权限因您使用的密钥协议架构而异。

• 要使用密KmsPrivateKeyToStaticPublicKey钥协议架构加密和解密记录，您需要在发送者的非对称KMS密钥对DeriveSharedSecret上使用 kms: GetPublicKey 和 km s:。如果您在实例化密钥环时直接提供发送者DER编码的公钥，则只需要对发送者的非对称密钥对 kms: DeriveSharedSecret 权限。KMS

• 要使用密KmsPublicKeyDiscovery钥协议架构解密记录，您需要对指定的非对称密钥KMS对具有 kms: DeriveSharedSecret 和 kms: GetPublicKey 权限。

创建 AWS KMS ECDH 密钥环

要创建用于加密和解密数据的密 AWS KMS ECDH钥环，必须使用密钥协议架构。KmsPrivateKeyToStaticPublicKey要使用 AWS KMS ECDH密钥协议架构初始化KmsPrivateKeyToStaticPublicKey密钥环，请提供以下值：

• 发件人 AWS KMS key 身份证

  必须标识一个非对称NIST推荐的椭圆曲线 () ECC KMS key pair，其值为。KeyUsage KEY_AGREEMENT发送者的私钥用于派生共享密钥。

• （可选）发件人的公钥

  必须是经DER编码的 X.509 公钥，也称为 SubjectPublicKeyInfo (SPKI)，如 5280 中所定义。RFC

  该 AWS KMS GetPublicKey操作以所需的DER编码格式返回非对称KMS密钥对的公钥。

  要减少密钥环 AWS KMS 拨打的次数，您可以直接提供发件人的公钥。如果没有为发件人的公钥提供任何值，则密钥环会调用 AWS KMS 以检索发送者的公钥。

• 收件人的公钥

  您必须提供收件人DER编码的 X.509 公钥，也称为 SubjectPublicKeyInfo (SPKI)，如 5280 中所定义。RFC

  该 AWS KMS GetPublicKey操作以所需的DER编码格式返回非对称KMS密钥对的公钥。

• 曲线规格

  标识指定密钥对中的椭圆曲线规范。发件人和收件人的密钥对必须具有相同的曲线规格。

  有效值：ECC_NIST_P256、ECC_NIS_P384、ECC_NIST_P512

• （可选）授权令牌列表

  如果您通过授权控制对KMS密钥 AWS KMS ECDH环中密钥的访问权限，则在初始化密钥环时必须提供所有必要的授权令牌。

C# / .NET

以下示例使用包含发件人 AWS KMS ECDH密KMS钥、发件人公钥和收件人公钥的密钥创建密钥环。此示例使用可选senderPublicKey参数来提供发送者的公钥。如果您不提供发件人的公钥，则密钥环会调用 AWS KMS 以检索发件人的公钥。发件人和收件人的密钥对都在ECC_NIST_P256弯曲中。

// Instantiate material providers
var materialProviders = new MaterialProviders(new MaterialProvidersConfig());

// Must be DER-encoded X.509 public keys
var BobPublicKey = new MemoryStream(new byte[] { });
var AlicePublicKey = new MemoryStream(new byte[] { });

// Create the AWS KMS ECDH static keyring
var staticConfiguration = new KmsEcdhStaticConfigurations
{
    KmsPrivateKeyToStaticPublicKey = new KmsPrivateKeyToStaticPublicKeyInput
    {
        SenderKmsIdentifier = "arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab",
        SenderPublicKey = BobPublicKey,
        RecipientPublicKey = AlicePublicKey
    }
};
	    
var createKeyringInput = new CreateAwsKmsEcdhKeyringInput
{
    CurveSpec = ECDHCurveSpec.ECC_NIST_P256,
    KmsClient = new AmazonKeyManagementServiceClient(),
    KeyAgreementScheme = staticConfiguration
};

var keyring = materialProviders.CreateAwsKmsEcdhKeyring(createKeyringInput);

Java

以下示例使用包含发件人 AWS KMS ECDH密KMS钥、发件人公钥和收件人公钥的密钥创建密钥环。此示例使用可选senderPublicKey参数来提供发送者的公钥。如果您不提供发件人的公钥，则密钥环会调用 AWS KMS 以检索发件人的公钥。发件人和收件人的密钥对都在ECC_NIST_P256弯曲中。

// Retrieve public keys
// Must be DER-encoded X.509 public keys                                
ByteBuffer BobPublicKey = getPublicKeyBytes("arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab");
        ByteBuffer AlicePublicKey = getPublicKeyBytes("arn:aws:kms:us-west-2:111122223333:key/0987dcba-09fe-87dc-65ba-ab0987654321"); 

// Create the AWS KMS ECDH static keyring
        final CreateAwsKmsEcdhKeyringInput senderKeyringInput =
          CreateAwsKmsEcdhKeyringInput.builder()
            .kmsClient(KmsClient.create())
            .curveSpec(ECDHCurveSpec.ECC_NIST_P256)
            .KeyAgreementScheme(
              KmsEcdhStaticConfigurations.builder()
                .KmsPrivateKeyToStaticPublicKey(
                  KmsPrivateKeyToStaticPublicKeyInput.builder()
                    .senderKmsIdentifier("arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab")
                    .senderPublicKey(BobPublicKey)
                    .recipientPublicKey(AlicePublicKey)
                    .build()).build()).build();

创建 AWS KMS ECDH发现密钥环

解密时，最佳做法是指定 AWS 数据库加密SDK可以使用的密钥。要遵循此最佳实践，请使用带有 AWS KMS ECDH密钥协议架构的KmsPrivateKeyToStaticPublicKey密钥环。但是，您也可以创建 AWS KMS ECDH发现密钥环，即密钥环，该密 AWS KMS ECDH钥环可以解密任何记录，其中指定密钥对的公KMS钥与存储在加密记录的材料描述字段中的接收者的公钥相匹配。

重要

使用密KmsPublicKeyDiscovery钥协议架构解密记录时，无论谁拥有所有公钥，都将接受所有公钥。

要使用 AWS KMS ECDH密钥协议架构初始化KmsPublicKeyDiscovery密钥环，请提供以下值：

• 收件人的 AWS KMS key 身份证

  必须标识一个非对称NIST推荐的椭圆曲线 () ECC KMS key pair，其值为。KeyUsage KEY_AGREEMENT

• 曲线规格

  标识接收者 ke KMS y pair 中的椭圆曲线规范。

  有效值：ECC_NIST_P256、ECC_NIS_P384、ECC_NIST_P512

• （可选）授权令牌列表

  如果您通过授权控制对KMS密钥 AWS KMS ECDH环中密钥的访问权限，则在初始化密钥环时必须提供所有必要的授权令牌。

C# / .NET

以下示例创建了ECC_NIST_P256曲线上带有密钥对（key pair）的 AWS KMS ECDH发现KMS密钥环。您必须对指定密钥对拥有 km DeriveSharedSecret s: GetPublicKey 和 KMS kms: 权限。此密钥环可以解密任何记录，其中指定密钥对的公KMS钥与存储在加密记录的材料描述字段中的接收者的公钥相匹配。

// Instantiate material providers
var materialProviders = new MaterialProviders(new MaterialProvidersConfig());

// Create the AWS KMS ECDH discovery keyring
var discoveryConfiguration = new KmsEcdhStaticConfigurations
{
    KmsPublicKeyDiscovery = new KmsPublicKeyDiscoveryInput
    {
        RecipientKmsIdentifier = "arn:aws:kms:us-west-2:111122223333:key/0987dcba-09fe-87dc-65ba-ab0987654321"
    }
		    
};
var createKeyringInput = new CreateAwsKmsEcdhKeyringInput
{
    CurveSpec = ECDHCurveSpec.ECC_NIST_P256,
    KmsClient = new AmazonKeyManagementServiceClient(),
    KeyAgreementScheme = discoveryConfiguration
};
var keyring = materialProviders.CreateAwsKmsEcdhKeyring(createKeyringInput);

Java

以下示例创建了ECC_NIST_P256曲线上带有密钥对（key pair）的 AWS KMS ECDH发现KMS密钥环。您必须对指定密钥对拥有 km DeriveSharedSecret s: GetPublicKey 和 KMS kms: 权限。此密钥环可以解密任何记录，其中指定密钥对的公KMS钥与存储在加密记录的材料描述字段中的接收者的公钥相匹配。

// Create the AWS KMS ECDH discovery keyring
final CreateAwsKmsEcdhKeyringInput recipientKeyringInput =
  CreateAwsKmsEcdhKeyringInput.builder()
    .kmsClient(KmsClient.create())
    .curveSpec(ECDHCurveSpec.ECC_NIST_P256)
    .KeyAgreementScheme(
      KmsEcdhStaticConfigurations.builder()
        .KmsPublicKeyDiscovery(
          KmsPublicKeyDiscoveryInput.builder()
            .recipientKmsIdentifier("arn:aws:kms:us-west-2:111122223333:key/0987dcba-09fe-87dc-65ba-ab0987654321").build()
        ).build())
    .build();