AWS KMS ECDH 鑰匙圈

我們的用戶端加密程式庫已重新命名為 AWS 資料庫加密 SDK。本開發人員指南仍提供 DynamoDB 加密用戶端的相關資訊。

重要

AWS KMS ECDH 鑰匙圈僅適用於材料提供者資料庫的 1.5.0 版。

AWS KMS ECDH 金鑰圈使用非對稱金鑰協定AWS KMS keys來衍生雙方之間的共用對稱包裝金鑰。首先，金鑰圈會使用橢圓曲線迪菲-赫爾曼 (ECDH) 金鑰合約演算法，從寄件者的 KMS key pair 中的私密金鑰和收件者的公開金鑰衍生共用密碼。然後，金鑰圈會使用共用密碼衍生共用包裝金鑰，以保護您的資料加密金鑰。 AWS 資料庫加密 SDK 使用 (KDF_CTR_HMAC_SHA384) 衍生共用包裝金鑰的金鑰衍生函數，符合 NIST 金鑰衍生的建議。

密鑰派生函數返回 64 個字節的鍵控材料。為了確保雙方使用正確的金鑰資料，資料 AWS 庫加密 SDK 會使用前 32 個位元組做為承諾金鑰，最後 32 個位元組作為共用包裝金鑰。解密時，如果金鑰圈無法重現儲存在加密記錄之 [資料描述] 欄位中的相同承諾金鑰和共用包裝金鑰，作業就會失敗。例如，如果您使用以 Alice 私密金鑰和 Bob 公開金鑰設定的金鑰圈來加密記錄，則使用 Bob 的私密金鑰和 Alice 的公開金鑰設定的金鑰圈將會重現相同的承諾金鑰和共用包裝金鑰，並且能夠解密記錄。如果 Bob 的公開金鑰不是來自 KMS key pair，則 Bob 可以建立原始 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鑰合約結構描述加密GetPublicKey和解密記錄，您需要寄件者的非對稱 KMS key pair DeriveSharedSecret 上的 kms: 和 kms:。如果您在實體化金鑰圈時直接提供寄件者的 DER 編碼公開金鑰，則只需要 kms: 寄件者非對稱 KMS key pair 的DeriveSharedSecret權限。

• 若要使用金KmsPublicKeyDiscovery鑰合約結構描述解密記錄，您需要指定的非對稱 KMS key pair 的 kms: DeriveSharedSecret 和 kms: GetPublicKey 權限。

建立一個 AWS KMS ECDH 金鑰圈

若要建立加密和解密資料的 AWS KMS ECDH 金鑰圈，您必須使用金鑰合約結構描述KmsPrivateKeyToStaticPublicKey。若要使用KmsPrivateKeyToStaticPublicKey金鑰合約結構描述初始化 AWS KMS ECDH 金鑰圈，請提供下列值：

• 寄件者 AWS KMS key 識別碼

  必須識別非對稱 NIST 建議的橢圓曲線 (ECC) KMS key pair，其值為。KeyUsage KEY_AGREEMENT發件人的私鑰用於導出共享密鑰。

• (選擇性) 寄件者的公開金鑰

  必須是一個德編碼的 X.509 公開金鑰，也稱為 SubjectPublicKeyInfo (SPKI)，如 RFC 5280 中所定義。

  此 AWS KMS GetPublicKey作業會以必要的 DER 編碼格式傳回非對稱 KMS key pair 的公開金鑰。

  若要減少金鑰圈 AWS KMS 撥打的通話次數，您可以直接提供寄件者的公開金鑰。如果沒有為寄件者的公開金鑰提供值，金鑰圈會呼叫擷 AWS KMS 取寄件者的公開金鑰。

• 收件者的公開金鑰

  您必須提供收件者的 DER 編碼 X.509 公開金鑰，也稱為 SubjectPublicKeyInfo (SPKI)，如 RFC 5280 中所定義。

  此 AWS KMS GetPublicKey作業會以必要的 DER 編碼格式傳回非對稱 KMS key pair 的公開金鑰。

• 曲線規格

  識別指定索引鍵對中的橢圓曲線規格。寄件者和收件者的金鑰配對必須具有相同的曲線規格。

  有效值：ECC_NIST_P256、ECC_NIS_P384、ECC_NIST_P512

• （可選）授予令牌列表

  如果您使用授權控制 AWS KMS ECDH 金鑰圈中 KMS 金鑰的存取權，則必須在初始化金鑰環時提供所有必要的授權權杖。

Java

下列範例會使用寄件者的 KMS 金鑰、寄件者的公開金鑰和收件者的公開金鑰建立 AWS KMS ECDH 金鑰圈。此範例使用選用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 金鑰 key pair 的公開金鑰與儲存在加密記錄之 [材料描述] 欄位中的收件者公開金鑰相符的任何記錄。

重要

當您使用金KmsPublicKeyDiscovery鑰合約結構描述解密記錄時，您會接受所有公開金鑰，不論其擁有者為何。

若要使用KmsPublicKeyDiscovery金鑰合約結構描述初始化 AWS KMS ECDH 金鑰圈，請提供下列值：

• 收件人的 AWS KMS key 識別碼

  必須識別非對稱 NIST 建議的橢圓曲線 (ECC) KMS key pair，其值為。KeyUsage KEY_AGREEMENT

• 曲線規格

  識別收件者的 KMS key pair 中的橢圓曲線規格。

  有效值：ECC_NIST_P256、ECC_NIS_P384、ECC_NIST_P512

• （可選）授予令牌列表

  如果您使用授權控制 AWS KMS ECDH 金鑰圈中 KMS 金鑰的存取權，則必須在初始化金鑰環時提供所有必要的授權權杖。

Java

下列範例會在曲線上建立具有 KMS key pair 的 AWS KMS ECDH 探索金鑰圈。ECC_NIST_P256您必須擁有指定 KMS key pair 的 kms: GetPublicKey 和 kms: DeriveSharedSecret 權限。此金鑰圈可以解密指定 KMS key pair 的公開金鑰與儲存在加密記錄之材料描述欄位中的收件者公開金鑰相符的任何記錄。

// 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();