Terjemahan disediakan oleh mesin penerjemah. Jika konten terjemahan yang diberikan bertentangan dengan versi bahasa Inggris aslinya, utamakan versi bahasa Inggris.

# Gantungan kunci ECDH mentah
<a name="use-raw-ecdh-keyring"></a>


****  

|  | 
| --- |
| Pustaka enkripsi sisi klien kami diubah namanya menjadi SDK Enkripsi AWS Database. Panduan pengembang ini masih memberikan informasi tentang Klien Enkripsi [DynamoDB](legacy-dynamodb-encryption-client.md). | 

**penting**  
Raw ECDH keyring hanya tersedia dengan versi 1.5.0 dari Perpustakaan Penyedia Material.

Raw ECDH keyring menggunakan kurva elips pasangan kunci publik-pribadi yang Anda berikan untuk mendapatkan kunci pembungkus bersama antara dua pihak. Pertama, keyring memperoleh rahasia bersama menggunakan kunci pribadi pengirim, kunci publik penerima, dan algoritma perjanjian kunci Elliptic Curve Diffie-Hellman (ECDH). Kemudian, keyring menggunakan rahasia bersama untuk mendapatkan kunci pembungkus bersama yang melindungi kunci enkripsi data Anda. Fungsi derivasi kunci yang digunakan SDK Enkripsi AWS Database (`KDF_CTR_HMAC_SHA384`) untuk mendapatkan kunci pembungkus bersama sesuai dengan rekomendasi [NIST](https://nvlpubs.nist.gov/nistpubs/SpecialPublications/NIST.SP.800-108r1-upd1.pdf) untuk derivasi kunci.

Fungsi derivasi kunci mengembalikan 64 byte bahan kunci. Untuk memastikan bahwa kedua belah pihak menggunakan materi kunci yang benar, SDK Enkripsi AWS Database menggunakan 32 byte pertama sebagai kunci komitmen dan 32 byte terakhir sebagai kunci pembungkus bersama. Saat mendekripsi, jika keyring tidak dapat mereproduksi kunci komitmen yang sama dan kunci pembungkus bersama yang disimpan di bidang deskripsi material dari catatan terenkripsi, operasi gagal. Misalnya, jika Anda mengenkripsi rekaman dengan keyring yang dikonfigurasi dengan kunci pribadi **Alice** dan kunci publik **Bob**, keyring yang dikonfigurasi dengan kunci pribadi **Bob** dan kunci publik **Alice** akan mereproduksi kunci komitmen yang sama dan kunci pembungkus bersama dan dapat mendekripsi catatan. Jika kunci publik Bob berasal dari AWS KMS key pasangan, maka Bob dapat membuat [keyring AWS KMS ECDH](use-kms-ecdh-keyring.md) untuk mendekripsi catatan.

Raw ECDH keyring mengenkripsi catatan dengan kunci simetris menggunakan AES-GCM. Kunci data kemudian dienkripsi dengan kunci pembungkus bersama turunan menggunakan AES-GCM. [Setiap keyring ECDH Raw hanya dapat memiliki satu kunci pembungkus bersama, tetapi Anda dapat menyertakan beberapa gantungan kunci ECDH mentah, sendiri atau dengan gantungan kunci lainnya, dalam multi-keyring.](use-multi-keyring.md)

Anda bertanggung jawab untuk membuat, menyimpan, dan melindungi kunci pribadi Anda, sebaiknya dalam modul keamanan perangkat keras (HSM) atau sistem manajemen kunci. Pasangan kunci pengirim dan penerima banyak berada pada kurva elips yang sama. AWS Database Encryption SDK mendukung spesifikasi elips cuve berikut:
+ `ECC_NIST_P256`
+ `ECC_NIST_P384`
+ `ECC_NIST_P512`

## Membuat keyring ECDH mentah
<a name="raw-ecdh-create"></a>

Raw ECDH keyring mendukung tiga skema perjanjian utama:`RawPrivateKeyToStaticPublicKey`,, dan. `EphemeralPrivateKeyToStaticPublicKey` `PublicKeyDiscovery` Skema perjanjian utama yang Anda pilih menentukan operasi kriptografi mana yang dapat Anda lakukan dan bagaimana bahan kunci dirakit.

**Topics**
+ [RawPrivateKeyToStaticPublicKey](#raw-ecdh-RawPrivateKeyToStaticPublicKey)
+ [EphemeralPrivateKeyToStaticPublicKey](#raw-ecdh-EphemeralPrivateKeyToStaticPublicKey)
+ [PublicKeyDiscovery](#raw-ecdh-PublicKeyDiscovery)

### RawPrivateKeyToStaticPublicKey
<a name="raw-ecdh-RawPrivateKeyToStaticPublicKey"></a>

Gunakan skema perjanjian `RawPrivateKeyToStaticPublicKey` kunci untuk mengonfigurasi kunci pribadi pengirim dan kunci publik penerima secara statis di keyring. Skema perjanjian kunci ini dapat mengenkripsi dan mendekripsi catatan.

Untuk menginisialisasi keyring ECDH mentah dengan skema perjanjian `RawPrivateKeyToStaticPublicKey` kunci, berikan nilai-nilai berikut:
+ **Kunci pribadi pengirim**

  [Anda harus memberikan kunci pribadi yang dikodekan PEM pengirim ( PrivateKeyInfo struktur PKCS \$18), seperti yang didefinisikan dalam RFC 5958.](https://tools.ietf.org/html/rfc5958#section-2)
+ **Kunci publik penerima**

  [Anda harus memberikan kunci publik X.509 yang dikodekan DER penerima, juga dikenal sebagai `SubjectPublicKeyInfo` (SPKI), sebagaimana didefinisikan dalam RFC 5280.](https://tools.ietf.org/html/rfc5280)

  Anda dapat menentukan kunci publik dari perjanjian kunci asimetris KMS key pair atau kunci publik dari key pair yang dihasilkan di luar. AWS
+ **Spesifikasi kurva**

  Mengidentifikasi spesifikasi kurva elips dalam pasangan kunci yang ditentukan. Pasangan kunci pengirim dan penerima harus memiliki spesifikasi kurva yang sama.

  Nilai valid: `ECC_NIST_P256`, `ECC_NIS_P384`, `ECC_NIST_P512`

------
#### [ C\$1 / .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 ]

Contoh Java berikut menggunakan skema perjanjian `RawPrivateKeyToStaticPublicKey` kunci untuk secara statis mengkonfigurasi kunci pribadi pengirim dan kunci publik penerima. Kedua pasangan kunci berada di `ECC_NIST_P256` kurva.

```
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);
}
```

------
#### [ Rust ]

Contoh Python berikut menggunakan skema perjanjian `raw_ecdh_static_configuration` kunci untuk secara statis mengkonfigurasi kunci pribadi pengirim dan kunci publik penerima. Kedua pasangan kunci harus berada pada kurva yang sama.

```
// Create keyring input
let raw_ecdh_static_configuration_input =
    RawPrivateKeyToStaticPublicKeyInput::builder()
        // Must be a UTF8 PEM-encoded private key
        .sender_static_private_key(private_key_sender_utf8_bytes)
        // Must be a UTF8 DER-encoded X.509 public key
        .recipient_public_key(public_key_recipient_utf8_bytes)
        .build()?;

let raw_ecdh_static_configuration = RawEcdhStaticConfigurations::RawPrivateKeyToStaticPublicKey(raw_ecdh_static_configuration_input);

// Instantiate the material providers library
let mpl_config = MaterialProvidersConfig::builder().build()?;
let mpl = mpl_client::Client::from_conf(mpl_config)?;

// Create raw ECDH static keyring
let raw_ecdh_keyring = mpl
    .create_raw_ecdh_keyring()
    .curve_spec(ecdh_curve_spec)
    .key_agreement_scheme(raw_ecdh_static_configuration)
    .send()
    .await?;
```

------

### EphemeralPrivateKeyToStaticPublicKey
<a name="raw-ecdh-EphemeralPrivateKeyToStaticPublicKey"></a>

Keyrings yang dikonfigurasi dengan skema perjanjian `EphemeralPrivateKeyToStaticPublicKey` kunci membuat key pair baru secara lokal dan mendapatkan kunci pembungkus bersama yang unik untuk setiap panggilan enkripsi.

Skema perjanjian kunci ini hanya dapat mengenkripsi catatan. Untuk mendekripsi catatan yang dienkripsi dengan skema perjanjian `EphemeralPrivateKeyToStaticPublicKey` kunci, Anda harus menggunakan skema perjanjian kunci penemuan yang dikonfigurasi dengan kunci publik penerima yang sama. Untuk mendekripsi, Anda dapat menggunakan keyring ECDH mentah dengan algoritma perjanjian [`PublicKeyDiscovery`](#raw-ecdh-PublicKeyDiscovery)kunci, atau, jika kunci publik penerima berasal dari key pair KMS perjanjian kunci asimetris, Anda dapat menggunakan keyring AWS KMS ECDH dengan skema perjanjian kunci. [KmsPublicKeyDiscovery](use-kms-ecdh-keyring.md#kms-ecdh-discovery) 

Untuk menginisialisasi keyring ECDH mentah dengan skema perjanjian `EphemeralPrivateKeyToStaticPublicKey` kunci, berikan nilai-nilai berikut:
+ **Kunci publik penerima**

  [Anda harus memberikan kunci publik X.509 yang dikodekan DER penerima, juga dikenal sebagai `SubjectPublicKeyInfo` (SPKI), sebagaimana didefinisikan dalam RFC 5280.](https://tools.ietf.org/html/rfc5280)

  Anda dapat menentukan kunci publik dari perjanjian kunci asimetris KMS key pair atau kunci publik dari key pair yang dihasilkan di luar. AWS
+ **Spesifikasi kurva**

  Mengidentifikasi spesifikasi kurva elips dalam kunci publik yang ditentukan.

  Pada enkripsi, keyring membuat key pair baru pada kurva yang ditentukan dan menggunakan kunci pribadi baru dan kunci publik tertentu untuk mendapatkan kunci pembungkus bersama.

  Nilai valid: `ECC_NIST_P256`, `ECC_NIS_P384`, `ECC_NIST_P512`

------
#### [ C\$1 / .NET ]

Contoh berikut membuat keyring ECDH mentah dengan skema perjanjian `EphemeralPrivateKeyToStaticPublicKey` kunci. Pada enkripsi, keyring akan membuat key pair baru secara lokal pada kurva yang ditentukan. `ECC_NIST_P256` 

```
// 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 ]

Contoh berikut membuat keyring ECDH mentah dengan skema perjanjian `EphemeralPrivateKeyToStaticPublicKey` kunci. Pada enkripsi, keyring akan membuat key pair baru secara lokal pada kurva yang ditentukan. `ECC_NIST_P256`

```
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);
}
```

------
#### [ Rust ]

Contoh berikut membuat keyring ECDH mentah dengan skema perjanjian `ephemeral_raw_ecdh_static_configuration` kunci. Pada enkripsi, keyring akan membuat key pair baru secara lokal pada kurva yang ditentukan.

```
// Create EphemeralPrivateKeyToStaticPublicKeyInput
let ephemeral_raw_ecdh_static_configuration_input =
    EphemeralPrivateKeyToStaticPublicKeyInput::builder()
        // Must be a UTF8 DER-encoded X.509 public key
        .recipient_public_key(public_key_recipient_utf8_bytes)
        .build()?;

let ephemeral_raw_ecdh_static_configuration =
    RawEcdhStaticConfigurations::EphemeralPrivateKeyToStaticPublicKey(ephemeral_raw_ecdh_static_configuration_input);

// Instantiate the material providers library
let mpl_config = MaterialProvidersConfig::builder().build()?;
let mpl = mpl_client::Client::from_conf(mpl_config)?;

// Create raw ECDH ephemeral private key keyring
let ephemeral_raw_ecdh_keyring = mpl
    .create_raw_ecdh_keyring()
    .curve_spec(ecdh_curve_spec)
    .key_agreement_scheme(ephemeral_raw_ecdh_static_configuration)
    .send()
    .await?;
```

------

### PublicKeyDiscovery
<a name="raw-ecdh-PublicKeyDiscovery"></a>

Saat mendekripsi, ini adalah praktik terbaik untuk menentukan kunci pembungkus yang dapat digunakan SDK Enkripsi AWS Database. Untuk mengikuti praktik terbaik ini, gunakan keyring ECDH yang menentukan kunci pribadi pengirim dan kunci publik penerima. Namun, Anda juga dapat membuat keyring penemuan ECDH mentah, yaitu gantungan kunci ECDH mentah yang dapat mendekripsi catatan apa pun di mana kunci publik kunci yang ditentukan cocok dengan kunci publik penerima yang disimpan di bidang deskripsi materi dari catatan terenkripsi. Skema perjanjian kunci ini hanya dapat mendekripsi catatan.

**penting**  
Ketika Anda mendekripsi catatan menggunakan skema perjanjian `PublicKeyDiscovery` kunci, Anda menerima semua kunci publik, terlepas dari siapa yang memilikinya.

Untuk menginisialisasi keyring ECDH mentah dengan skema perjanjian `PublicKeyDiscovery` kunci, berikan nilai-nilai berikut:
+ **Kunci pribadi statis penerima**

  [Anda harus memberikan kunci pribadi yang disandikan PEM penerima ( PrivateKeyInfo struktur PKCS \$18), seperti yang didefinisikan dalam RFC 5958.](https://tools.ietf.org/html/rfc5958#section-2)
+ **Spesifikasi kurva**

  Mengidentifikasi spesifikasi kurva elips dalam kunci pribadi yang ditentukan. Pasangan kunci pengirim dan penerima harus memiliki spesifikasi kurva yang sama.

  Nilai valid: `ECC_NIST_P256`, `ECC_NIS_P384`, `ECC_NIST_P512`

------
#### [ C\$1 / .NET ]

Contoh berikut membuat keyring ECDH mentah dengan skema perjanjian `PublicKeyDiscovery` kunci. Gantungan kunci ini dapat mendekripsi catatan apa pun di mana kunci publik dari kunci pribadi yang ditentukan cocok dengan kunci publik penerima yang disimpan di bidang deskripsi materi dari catatan terenkripsi.

```
// 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 ]

Contoh berikut membuat keyring ECDH mentah dengan skema perjanjian `PublicKeyDiscovery` kunci. Gantungan kunci ini dapat mendekripsi catatan apa pun di mana kunci publik dari kunci pribadi yang ditentukan cocok dengan kunci publik penerima yang disimpan di bidang deskripsi materi dari catatan terenkripsi.

```
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);
}
```

------
#### [ Rust ]

Contoh berikut membuat keyring ECDH mentah dengan skema perjanjian `discovery_raw_ecdh_static_configuration` kunci. Keyring ini dapat mendekripsi pesan apa pun di mana kunci publik dari kunci pribadi yang ditentukan cocok dengan kunci publik penerima yang disimpan pada ciphertext pesan.

```
// Create PublicKeyDiscoveryInput
let discovery_raw_ecdh_static_configuration_input =
    PublicKeyDiscoveryInput::builder()
        // Must be a UTF8 PEM-encoded private key
        .recipient_static_private_key(private_key_recipient_utf8_bytes)
        .build()?;

let discovery_raw_ecdh_static_configuration =
    RawEcdhStaticConfigurations::PublicKeyDiscovery(discovery_raw_ecdh_static_configuration_input);

// Create raw ECDH discovery private key keyring
let discovery_raw_ecdh_keyring = mpl
    .create_raw_ecdh_keyring()
    .curve_spec(ecdh_curve_spec)
    .key_agreement_scheme(discovery_raw_ecdh_static_configuration)
    .send()
    .await?;
```

------