原始ECDH鑰匙圈 - AWS 資料庫加密 SDK
建立原始ECDH金鑰圈

本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。

原始ECDH鑰匙圈

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

原始ECDH金鑰圈僅適用於材料提供者資源庫的 1.5.0 版。

Raw 金ECDH鑰圈會使用您提供的橢圓曲線公開-私密金鑰配對，以衍生雙方之間的共用包裝金鑰。首先，金鑰圈會使用寄件者的私密金鑰、收件者的公開金鑰和橢圓曲線 Diffie-Hellman () 金鑰合約演算法衍生共用密碼。ECDH然後，金鑰圈會使用共用密碼衍生共用包裝金鑰，以保護您的資料加密金鑰。 AWS 資料庫加密SDK使用 (KDF_CTR_HMAC_SHA384) 衍生共用包裝金鑰的金鑰衍生函數，符合金鑰衍生的NIST建議。

密鑰派生函數返回 64 個字節的鍵控材料。為了確保雙方使用正確的金鑰資料，資料 AWS 庫加密SDK會使用前 32 個位元組做為承諾金鑰，最後 32 個位元組作為共用包裝金鑰。解密時，如果金鑰圈無法重現儲存在加密記錄之 [資料描述] 欄位中的相同承諾金鑰和共用包裝金鑰，作業就會失敗。例如，如果您使用以 Alice 私密金鑰和 Bob 公開金鑰設定的金鑰圈來加密記錄，則使用 Bob 的私密金鑰和 Alice 的公開金鑰設定的金鑰圈將會重現相同的承諾金鑰和共用包裝金鑰，並且能夠解密記錄。如果 Bob 的公鑰來自一 AWS KMS key 對，則 Bob 可以建立金AWS KMS ECDH鑰圈來解密記錄。

Raw 金ECDH鑰環使用-來加密記錄的對稱金鑰。AES GCM然後使用-，使用派生的共享包裝密鑰對數據密鑰進AES行包絡加密GCM。每個 Raw 金ECDH鑰圈只能有一個共用包裝金鑰，但您可以在多重金鑰圈中包含多個 Raw ECDH 鑰匙圈，單獨或與其他鑰匙圈一起包含多個 Raw 鑰匙圈。

您必須負責產生、儲存及保護您的私密金鑰，最好是在硬體安全模組 (HSM) 或金鑰管理系統中。寄件者和收件者的金鑰配對大部分位於相同的橢圓曲線上。「資 AWS 料庫加密」SDK 支援下列橢圓切割規格：

  • ECC_NIST_P256

  • ECC_NIST_P384

  • ECC_NIST_P512

建立原始ECDH金鑰圈

Raw 金ECDH鑰圈支援三個金鑰合約結構描述：RawPrivateKeyToStaticPublicKeyEphemeralPrivateKeyToStaticPublicKey、和PublicKeyDiscovery。您選取的金鑰協定結構描述會決定您可以執行哪些密碼編譯作業，以及鍵控材料的組合方式。

RawPrivateKeyToStaticPublicKey

使用RawPrivateKeyToStaticPublicKey金鑰合約結構描述，在金鑰圈中以靜態方式設定寄件者的私密金鑰和收件者的公開金鑰。此金鑰合約結構描述可以加密和解密記錄。

若要使用RawPrivateKeyToStaticPublicKey金鑰協定結構描述初始化 Raw 金鑰ECDH圈，請提供下列值：

C# / .NET
// Instantiate material providers
var materialProviders = new MaterialProviders(new MaterialProvidersConfig());
	    var BobPrivateKey = new MemoryStream(new byte[] { });
	    var AlicePublicKey = new MemoryStream(new byte[] { });

	    // Create the Raw ECDH static keyring
	    var staticConfiguration = new RawEcdhStaticConfigurations()
	    {
		    RawPrivateKeyToStaticPublicKey = new RawPrivateKeyToStaticPublicKeyInput
		    {
			    SenderStaticPrivateKey = BobPrivateKey,
			    RecipientPublicKey = AlicePublicKey
		    }
	    };
	    
	    var createKeyringInput = new CreateRawEcdhKeyringInput() 
	    {
		    CurveSpec = ECDHCurveSpec.ECC_NIST_P256,
		    KeyAgreementScheme = staticConfiguration 
	    };

	    var keyring = materialProviders.CreateRawEcdhKeyring(createKeyringInput);
Java

下列 Java 範例會使用RawPrivateKeyToStaticPublicKey金鑰合約結構描述，以靜態方式設定寄件者的私密金鑰和收件者的公開金鑰。兩個鍵對都在ECC_NIST_P256曲線上。

private static void StaticRawKeyring() {
    // Instantiate material providers
    final MaterialProviders materialProviders =
      MaterialProviders.builder()
        .MaterialProvidersConfig(MaterialProvidersConfig.builder().build())
        .build();

    KeyPair senderKeys = GetRawEccKey();
    KeyPair recipient = GetRawEccKey();

    // Create the Raw ECDH static keyring
    final CreateRawEcdhKeyringInput rawKeyringInput =
      CreateRawEcdhKeyringInput.builder()
        .curveSpec(ECDHCurveSpec.ECC_NIST_P256)
        .KeyAgreementScheme(
          RawEcdhStaticConfigurations.builder()
            .RawPrivateKeyToStaticPublicKey(
                RawPrivateKeyToStaticPublicKeyInput.builder()
                  // Must be a PEM-encoded private key
                  .senderStaticPrivateKey(ByteBuffer.wrap(senderKeys.getPrivate().getEncoded()))
                  // Must be a DER-encoded X.509 public key
                  .recipientPublicKey(ByteBuffer.wrap(recipient.getPublic().getEncoded()))
                  .build()
            )
            .build()
        ).build();

    final IKeyring staticKeyring = materialProviders.CreateRawEcdhKeyring(rawKeyringInput);
}

EphemeralPrivateKeyToStaticPublicKey

使用EphemeralPrivateKeyToStaticPublicKey金鑰合約結構描述設定的金鑰圈會在本機建立新的 key pair，並為每個加密呼叫衍生唯一的共用包裝金鑰。

此金鑰合約結構描述只能加密記錄。若要解密使用EphemeralPrivateKeyToStaticPublicKey金鑰合約結構描述加密的記錄，您必須使用以相同收件者公開金鑰設定的探索金鑰合約結構描述。若要解密，您可以使用原始金ECDH鑰圈搭配PublicKeyDiscovery金鑰合約演算法，或者，如果收件者的公開金鑰來自非對稱金鑰合約金KMS鑰組，您可以使用金鑰 AWS KMS ECDH圈搭配KmsPublicKeyDiscovery金鑰合約結構描述。

若要使用EphemeralPrivateKeyToStaticPublicKey金鑰協定結構描述初始化 Raw 金鑰ECDH圈，請提供下列值：

C# / .NET

下列範例會使用EphemeralPrivateKeyToStaticPublicKey金鑰協定結構描述建立 Raw 金鑰ECDH圈。在加密時，密鑰環將在指定的ECC_NIST_P256曲線上本地創建一個新的密 key pair。

// Instantiate material providers
var materialProviders = new MaterialProviders(new MaterialProvidersConfig());
	    var AlicePublicKey = new MemoryStream(new byte[] { });

	    // Create the Raw ECDH ephemeral keyring
	    var ephemeralConfiguration = new RawEcdhStaticConfigurations()
	    {
		    EphemeralPrivateKeyToStaticPublicKey = new EphemeralPrivateKeyToStaticPublicKeyInput
		    {
			    RecipientPublicKey = AlicePublicKey
		    }
	    };
	    
	    var createKeyringInput = new CreateRawEcdhKeyringInput() 
	    {
		    CurveSpec = ECDHCurveSpec.ECC_NIST_P256,
		    KeyAgreementScheme = ephemeralConfiguration
	    };

	    var keyring = materialProviders.CreateRawEcdhKeyring(createKeyringInput);
Java

下列範例會使用EphemeralPrivateKeyToStaticPublicKey金鑰協定結構描述建立 Raw 金鑰ECDH圈。在加密時，密鑰環將在指定的ECC_NIST_P256曲線上本地創建一個新的密 key pair。

private static void EphemeralRawEcdhKeyring() {
    // Instantiate material providers
    final MaterialProviders materialProviders =
      MaterialProviders.builder()
        .MaterialProvidersConfig(MaterialProvidersConfig.builder().build())
        .build();

    ByteBuffer recipientPublicKey = getPublicKeyBytes();

    // Create the Raw ECDH ephemeral keyring
    final CreateRawEcdhKeyringInput ephemeralInput =
      CreateRawEcdhKeyringInput.builder()
        .curveSpec(ECDHCurveSpec.ECC_NIST_P256)
        .KeyAgreementScheme(
          RawEcdhStaticConfigurations.builder()
            .EphemeralPrivateKeyToStaticPublicKey(
              EphemeralPrivateKeyToStaticPublicKeyInput.builder()
                .recipientPublicKey(recipientPublicKey)
                .build()
            )
            .build()
        ).build();

    final IKeyring ephemeralKeyring = materialProviders.CreateRawEcdhKeyring(ephemeralInput);
}

PublicKeyDiscovery

解密時，最佳做法是指定 AWS 資料庫加密SDK可以使用的包裝金鑰。若要遵循此最佳做法，請使用金ECDH鑰圈來指定寄件者的私密金鑰和收件者的公開金鑰。不過，您也可以建立 Raw ECDH 探索金鑰圈，也就是說，Raw 金ECDH鑰圈可以解密指定金鑰的公開金鑰符合儲存在加密記錄的材料描述欄位中的收件者公開金鑰的任何記錄。此金鑰合約結構描述只能解密記錄。

重要

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

若要使用PublicKeyDiscovery金鑰協定結構描述初始化 Raw 金鑰ECDH圈，請提供下列值：

  • 收件者的靜態私密金鑰

    您必須提供收件者PEM編碼的私密金鑰 (PKCS#8 PrivateKeyInfo 結構)，如 RFC5958 中所定義。

  • 曲線規格

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

    有效值：ECC_NIST_P256、ECC_NIS_P384、ECC_NIST_P512

C# / .NET

下列範例會使用PublicKeyDiscovery金鑰協定結構描述建立 Raw 金鑰ECDH圈。此金鑰圈可以解密指定私密金鑰的公開金鑰與儲存在加密記錄的材料描述欄位中的收件者公開金鑰相符的任何記錄。

// Instantiate material providers
var materialProviders = new MaterialProviders(new MaterialProvidersConfig());
	    var AlicePrivateKey = new MemoryStream(new byte[] { });

	    // Create the Raw ECDH discovery keyring
	    var discoveryConfiguration = new RawEcdhStaticConfigurations()
	    {
		    PublicKeyDiscovery = new PublicKeyDiscoveryInput
		    {
			    RecipientStaticPrivateKey = AlicePrivateKey
		    }
	    };
	    
	    var createKeyringInput = new CreateRawEcdhKeyringInput() 
	    {
		    CurveSpec = ECDHCurveSpec.ECC_NIST_P256,
		    KeyAgreementScheme = discoveryConfiguration 
	    };

	    var keyring = materialProviders.CreateRawEcdhKeyring(createKeyringInput);
Java

下列範例會使用PublicKeyDiscovery金鑰協定結構描述建立 Raw 金鑰ECDH圈。此金鑰圈可以解密指定私密金鑰的公開金鑰與儲存在加密記錄的材料描述欄位中的收件者公開金鑰相符的任何記錄。

private static void RawEcdhDiscovery() {
    // Instantiate material providers
    final MaterialProviders materialProviders =
      MaterialProviders.builder()
        .MaterialProvidersConfig(MaterialProvidersConfig.builder().build())
        .build();

    KeyPair recipient = GetRawEccKey();

    // Create the Raw ECDH discovery keyring
    final CreateRawEcdhKeyringInput rawKeyringInput =
      CreateRawEcdhKeyringInput.builder()
        .curveSpec(ECDHCurveSpec.ECC_NIST_P256)
        .KeyAgreementScheme(
          RawEcdhStaticConfigurations.builder()
            .PublicKeyDiscovery(
              PublicKeyDiscoveryInput.builder()
                // Must be a PEM-encoded private key
                .recipientStaticPrivateKey(ByteBuffer.wrap(sender.getPrivate().getEncoded()))
                .build()
            )
            .build()
        ).build();

    final IKeyring publicKeyDiscovery  = materialProviders.CreateRawEcdhKeyring(rawKeyringInput);
}