Terjemahan disediakan oleh mesin penerjemah. Jika konten terjemahan yang diberikan bertentangan dengan versi bahasa Inggris aslinya, utamakan versi bahasa Inggris.
# Gantungan kunci
****
| |
| --- |
| 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). |
AWS Database Encryption SDK menggunakan *keyrings* untuk melakukan enkripsi [amplop](concepts.md#envelope-encryption). Keyrings menghasilkan, mengenkripsi, dan mendekripsi kunci data. Keyrings menentukan sumber kunci data unik yang melindungi setiap catatan terenkripsi, dan kunci [pembungkus yang mengenkripsi kunci](concepts.md#wrapping-key) data tersebut. Anda menentukan keyring saat mengenkripsi dan keyring yang sama atau berbeda saat mendekripsi.
[Anda dapat menggunakan setiap keyring satu per satu atau menggabungkan keyrings menjadi multi-keyring.](use-multi-keyring.md) Meskipun sebagian besar keyrings dapat menghasilkan, mengenkripsi, dan mendekripsi kunci data, Anda dapat membuat keyring yang hanya melakukan satu operasi tertentu, seperti keyring yang hanya menghasilkan kunci data, dan menggunakan keyring tersebut dalam kombinasi dengan yang lain.
Kami menyarankan Anda menggunakan keyring yang melindungi kunci pembungkus Anda dan melakukan operasi kriptografi dalam batas aman, seperti AWS KMS keyring, yang menggunakan AWS KMS keys yang tidak pernah meninggalkan () tidak terenkripsi. [AWS Key Management Service](https://docs.aws.amazon.com/kms/latest/developerguide/)AWS KMS Anda juga dapat menulis keyring yang menggunakan kunci pembungkus yang disimpan dalam modul keamanan perangkat keras Anda (HSMs) atau dilindungi oleh layanan kunci utama lainnya.
Keyring Anda menentukan kunci pembungkus yang melindungi kunci data Anda, dan akhirnya, data Anda. Gunakan kunci pembungkus paling aman yang praktis untuk tugas Anda. Bila memungkinkan gunakan kunci pembungkus yang dilindungi oleh modul keamanan perangkat keras (HSM) atau infrastruktur manajemen kunci, seperti kunci KMS in [AWS Key Management Service](https://docs.aws.amazon.com/kms/latest/developerguide/)(AWS KMS) atau kunci enkripsi di. [AWS CloudHSM](https://docs.aws.amazon.com/cloudhsm/latest/userguide/)
AWS Database Encryption SDK menyediakan beberapa konfigurasi keyrings dan keyring, dan Anda dapat membuat keyring kustom Anda sendiri. Anda juga dapat membuat [multi-keyring](use-multi-keyring.md) yang menyertakan satu atau lebih gantungan kunci dari jenis yang sama atau berbeda.
**Topics**
+ [Cara kerja gantungan kunci](#using-keyrings)
+ [AWS KMS gantungan kunci](use-kms-keyring.md)
+ [AWS KMS Gantungan kunci hierarkis](use-hierarchical-keyring.md)
+ [AWS KMS Gantungan kunci ECDH](use-kms-ecdh-keyring.md)
+ [Gantungan kunci AES mentah](use-raw-aes-keyring.md)
+ [Gantungan kunci RSA mentah](use-raw-rsa-keyring.md)
+ [Gantungan kunci ECDH mentah](use-raw-ecdh-keyring.md)
+ [Multi-gantungan kunci](use-multi-keyring.md)
## Cara kerja gantungan kunci
****
| |
| --- |
| 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). |
Saat Anda mengenkripsi dan menandatangani bidang di database Anda, SDK Enkripsi AWS Database meminta keyring untuk materi enkripsi. Keyring mengembalikan kunci data plaintext, salinan kunci data yang dienkripsi oleh masing-masing kunci pembungkus di keyring, dan kunci MAC yang terkait dengan kunci data. AWS Database Encryption SDK menggunakan kunci plaintext untuk mengenkripsi data, dan kemudian menghapus kunci data plaintext dari memori sesegera mungkin. Kemudian, AWS Database Encryption SDK menambahkan [deskripsi material](concepts.md#material-description) yang mencakup kunci data terenkripsi dan informasi lainnya, seperti enkripsi dan instruksi penandatanganan. SDK Enkripsi AWS Database menggunakan kunci MAC untuk menghitung Kode Otentikasi Pesan Berbasis Hash (HMACs) melalui kanonikalisasi deskripsi materi dan semua bidang yang ditandai atau. `ENCRYPT_AND_SIGN` `SIGN_ONLY`
Saat mendekripsi data, Anda dapat menggunakan keyring yang sama dengan yang Anda gunakan untuk mengenkripsi data, atau yang lain. Untuk mendekripsi data, keyring dekripsi harus memiliki akses ke setidaknya satu kunci pembungkus di keyring enkripsi.
AWS Database Encryption SDK meneruskan kunci data terenkripsi dari deskripsi material ke keyring, dan meminta keyring untuk mendekripsi salah satu dari mereka. Keyring menggunakan kunci pembungkusnya untuk mendekripsi salah satu kunci data terenkripsi dan mengembalikan kunci data plaintext. AWS Database Encryption SDK menggunakan kunci data plaintext untuk mendekripsi data. Jika tidak ada kunci pembungkus di keyring yang dapat mendekripsi salah satu kunci data terenkripsi, operasi dekripsi gagal.
[Anda dapat menggunakan keyring tunggal atau juga menggabungkan keyrings dari jenis yang sama atau jenis yang berbeda ke dalam multi-keyring.](use-multi-keyring.md) Saat Anda mengenkripsi data, multi-keyring mengembalikan salinan kunci data yang dienkripsi oleh semua kunci pembungkus di semua keyring yang terdiri dari multi-keyring dan kunci MAC yang terkait dengan kunci data. Anda dapat mendekripsi data menggunakan keyring dengan salah satu tombol pembungkus di multi-keyring.
# AWS KMS gantungan kunci
****
| |
| --- |
| 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). |
AWS KMS Keyring menggunakan enkripsi simetris atau RSA asimetris [AWS KMS keys](https://docs.aws.amazon.com/kms/latest/developerguide/concepts.html#master_keys)untuk menghasilkan, mengenkripsi, dan mendekripsi kunci data. AWS Key Management Service (AWS KMS) melindungi kunci KMS Anda dan melakukan operasi kriptografi dalam batas FIPS. Kami menyarankan Anda menggunakan AWS KMS keyring, atau keyring dengan properti keamanan serupa, bila memungkinkan.
Anda juga dapat menggunakan kunci KMS Multi-wilayah simetris dalam keyring. AWS KMS Untuk detail dan contoh selengkapnya menggunakan Multi-region AWS KMS keys, lihat[Menggunakan Multi-region AWS KMS keys](#config-mrks). Untuk informasi tentang kunci Multi-region, lihat [Menggunakan kunci Multi-region](https://docs.aws.amazon.com/kms/latest/developerguide/multi-region-keys-overview.html) di Panduan *AWS Key Management Service Pengembang*.
AWS KMS gantungan kunci dapat mencakup dua jenis kunci pembungkus:
+ **Kunci generator**: Menghasilkan kunci data teks biasa dan mengenkripsinya. Sebuah keyring yang mengenkripsi data harus memiliki satu kunci generator.
+ **Kunci tambahan**: Mengenkripsi kunci data teks biasa yang dihasilkan oleh kunci generator. AWS KMS keyrings dapat memiliki nol atau lebih tombol tambahan.
Anda harus memiliki kunci generator untuk mengenkripsi catatan. Ketika AWS KMS keyring hanya memiliki satu AWS KMS kunci, kunci itu digunakan untuk menghasilkan dan mengenkripsi kunci data.
Seperti semua gantungan kunci, AWS KMS gantungan kunci dapat digunakan secara independen atau dalam [multi-keyring](use-multi-keyring.md) dengan gantungan kunci lain dari jenis yang sama atau berbeda.
**Topics**
+ [Izin yang diperlukan untuk keyrings AWS KMS](#kms-keyring-permissions)
+ [Mengidentifikasi AWS KMS keys dalam AWS KMS keyring](#kms-keyring-id)
+ [Membuat AWS KMS keyring](#kms-keyring-create)
+ [Menggunakan Multi-region AWS KMS keys](#config-mrks)
+ [Menggunakan AWS KMS keyring penemuan](#kms-keyring-discovery)
+ [Menggunakan AWS KMS keyring penemuan regional](#kms-keyring-regional)
## Izin yang diperlukan untuk keyrings AWS KMS
SDK Enkripsi AWS Database tidak memerlukan Akun AWS dan tidak bergantung pada apa pun Layanan AWS. Namun, untuk menggunakan AWS KMS keyring, Anda memerlukan izin minimum Akun AWS dan berikut pada keyring Anda. AWS KMS keys
+ Untuk mengenkripsi dengan AWS KMS keyring, Anda memerlukan GenerateDataKey izin [kms:](https://docs.aws.amazon.com/kms/latest/APIReference/API_GenerateDataKey.html) pada kunci generator. Anda memerlukan izin [KMS: Encrypt](https://docs.aws.amazon.com/kms/latest/APIReference/API_Encrypt.html) pada semua kunci tambahan di keyring. AWS KMS
+ Untuk mendekripsi dengan AWS KMS keyring, Anda memerlukan izin [KMS: Decrypt](https://docs.aws.amazon.com/kms/latest/APIReference/API_Decrypt.html) pada setidaknya satu kunci di keyring. AWS KMS
+ Untuk mengenkripsi dengan multi-keyring yang terdiri dari AWS KMS keyrings, Anda memerlukan GenerateDataKey izin [kms:](https://docs.aws.amazon.com/kms/latest/APIReference/API_GenerateDataKey.html) pada kunci generator di keyring generator. Anda memerlukan izin [KMS: Encrypt](https://docs.aws.amazon.com/kms/latest/APIReference/API_Encrypt.html) pada semua kunci lain di semua keyrings lainnya. AWS KMS
+ Untuk mengenkripsi dengan AWS KMS keyring RSA asimetris, Anda tidak perlu [kms: GenerateDataKey atau [KMS:Encrypt](https://docs.aws.amazon.com/kms/latest/APIReference/API_Encrypt.html)](https://docs.aws.amazon.com/kms/latest/APIReference/API_GenerateDataKey.html) karena Anda harus menentukan materi kunci publik yang ingin Anda gunakan untuk enkripsi saat Anda membuat keyring. Tidak ada AWS KMS panggilan yang dilakukan saat mengenkripsi dengan keyring ini. [Untuk mendekripsi dengan AWS KMS keyring RSA asimetris, Anda memerlukan izin KMS: Dekripsi.](https://docs.aws.amazon.com/kms/latest/APIReference/API_Decrypt.html)
Untuk informasi selengkapnya tentang izin AWS KMS keys, lihat [Otentikasi dan kontrol akses](https://docs.aws.amazon.com/kms/latest/developerguide/control-access.html) di Panduan *AWS Key Management Service Pengembang*.
## Mengidentifikasi AWS KMS keys dalam AWS KMS keyring
AWS KMS Keyring dapat mencakup satu atau lebih AWS KMS keys. Untuk menentukan AWS KMS key dalam AWS KMS keyring, gunakan pengenal AWS KMS kunci yang didukung. Pengidentifikasi kunci yang dapat Anda gunakan untuk mengidentifikasi AWS KMS key dalam keyring bervariasi dengan operasi dan implementasi bahasa. Untuk detail tentang pengidentifikasi kunci AWS KMS key, lihat [Pengidentifikasi Kunci di Panduan AWS Key Management Service](https://docs.aws.amazon.com/kms/latest/developerguide/concepts.html#key-id) *Pengembang*.
Sebagai praktik terbaik, gunakan pengenal kunci paling spesifik yang praktis untuk tugas Anda.
+ [Untuk mengenkripsi dengan AWS KMS keyring, Anda dapat menggunakan [ID kunci, ARN kunci](https://docs.aws.amazon.com/kms/latest/developerguide/concepts.html#key-id-key-id)[, [nama alias, atau alias](https://docs.aws.amazon.com/kms/latest/developerguide/concepts.html#key-id-alias-name) ARN](https://docs.aws.amazon.com/kms/latest/developerguide/concepts.html#key-id-key-ARN) untuk mengenkripsi data.](https://docs.aws.amazon.com/kms/latest/developerguide/concepts.html#key-id-alias-ARN)
**catatan**
Jika Anda menentukan nama alias atau alias ARN untuk kunci KMS dalam keyring enkripsi, operasi enkripsi menyimpan ARN kunci yang saat ini terkait dengan alias dalam metadata kunci data terenkripsi. Itu tidak menyimpan alias. Perubahan pada alias tidak memengaruhi kunci KMS yang digunakan untuk mendekripsi kunci data terenkripsi Anda.
+ Untuk mendekripsi dengan AWS KMS keyring, Anda harus menggunakan ARN kunci untuk mengidentifikasi. AWS KMS keys Lihat perinciannya di [Memilih tombol pembungkus](configure.md#config-keys).
+ Dalam keyring yang digunakan untuk enkripsi dan dekripsi, Anda harus menggunakan ARN kunci untuk mengidentifikasi. AWS KMS keys
Saat mendekripsi, AWS Database Encryption SDK mencari AWS KMS keyring untuk kunci AWS KMS key yang dapat mendekripsi salah satu kunci data terenkripsi. Secara khusus, SDK Enkripsi AWS Database menggunakan pola berikut untuk setiap kunci data terenkripsi dalam deskripsi material.
+ AWS Database Encryption SDK mendapatkan ARN kunci AWS KMS key yang mengenkripsi kunci data dari metadata deskripsi material.
+ AWS Database Encryption SDK mencari keyring dekripsi untuk ARN dengan kunci AWS KMS key yang cocok.
+ Jika menemukan ARN AWS KMS key dengan kunci yang cocok di keyring, SDK Enkripsi AWS Database meminta AWS KMS untuk menggunakan kunci KMS untuk mendekripsi kunci data terenkripsi.
+ Jika tidak, ia melompat ke kunci data terenkripsi berikutnya, jika ada.
## Membuat AWS KMS keyring
Anda dapat mengonfigurasi setiap AWS KMS keyring dengan satu AWS KMS key atau beberapa AWS KMS keys yang sama atau berbeda Akun AWS dan Wilayah AWS. AWS KMS key Harus berupa kunci enkripsi simetris (`SYMMETRIC_DEFAULT`) atau kunci KMS RSA asimetris. Anda juga dapat menggunakan enkripsi simetris [Multi-region KMS key](#config-mrks). Anda dapat menggunakan satu atau lebih AWS KMS keyring dalam [multi-keyring](use-multi-keyring.md).
Anda dapat membuat AWS KMS keyring yang mengenkripsi dan mendekripsi data, atau Anda dapat membuat AWS KMS gantungan kunci khusus untuk mengenkripsi atau mendekripsi. Saat Anda membuat AWS KMS keyring untuk mengenkripsi data, Anda harus menentukan *kunci generator*, AWS KMS key yang digunakan untuk menghasilkan kunci data plaintext dan mengenkripsinya. Kunci data secara matematis tidak terkait dengan kunci KMS. Kemudian, jika Anda memilih, Anda dapat menentukan tambahan AWS KMS keys yang mengenkripsi kunci data plaintext yang sama. Untuk mendekripsi bidang terenkripsi yang dilindungi oleh keyring ini, keyring dekripsi yang Anda gunakan harus menyertakan setidaknya satu dari yang ditentukan dalam keyring, atau tidak. AWS KMS keys AWS KMS keys( AWS KMS Gantungan kunci tanpa AWS KMS keys dikenal sebagai [gantungan kunci AWS KMS penemuan](#kms-keyring-discovery).)
Semua kunci pembungkus dalam keyring enkripsi atau multi-keyring harus dapat mengenkripsi kunci data. Jika ada kunci pembungkus gagal untuk mengenkripsi, metode enkripsi gagal. Akibatnya, penelepon harus memiliki [izin yang diperlukan](#kms-keyring-permissions) untuk semua kunci di keyring. Jika Anda menggunakan keyring penemuan untuk mengenkripsi data, sendiri atau dalam multi-keyring, operasi enkripsi gagal.
Contoh berikut menggunakan `CreateAwsKmsMrkMultiKeyring` metode untuk membuat AWS KMS keyring dengan kunci KMS enkripsi simetris. `CreateAwsKmsMrkMultiKeyring`Metode ini secara otomatis membuat AWS KMS klien dan memastikan bahwa keyring akan menangani kunci Single-region dan Multi-region dengan benar. Contoh-contoh ini menggunakan [kunci ARNs](https://docs.aws.amazon.com/kms/latest/developerguide/concepts.html#key-id-key-ARN) untuk mengidentifikasi kunci KMS. Untuk detailnya, lihat [Mengidentifikasi AWS KMS keys dalam AWS KMS keyring](#kms-keyring-id)
------
#### [ Java ]
```
final MaterialProviders matProv = MaterialProviders.builder()
.MaterialProvidersConfig(MaterialProvidersConfig.builder().build())
.build();
final CreateAwsKmsMrkMultiKeyringInput keyringInput = CreateAwsKmsMrkMultiKeyringInput.builder()
.generator(kmsKeyArn)
.build();
final IKeyring kmsKeyring = matProv.CreateAwsKmsMrkMultiKeyring(keyringInput);
```
------
#### [ C\$1 / .NET ]
```
var matProv = new MaterialProviders(new MaterialProvidersConfig());
var createAwsKmsMrkMultiKeyringInput = new CreateAwsKmsMrkMultiKeyringInput
{
Generator = kmsKeyArn
};
var awsKmsMrkMultiKeyring = matProv.CreateAwsKmsMrkMultiKeyring(createAwsKmsMrkMultiKeyringInput);
```
------
#### [ Rust ]
```
let provider_config = MaterialProvidersConfig::builder().build()?;
let mat_prov = client::Client::from_conf(provider_config)?;
let kms_keyring = mat_prov
.create_aws_kms_mrk_multi_keyring()
.generator(kms_key_id)
.send()
.await?;
```
------
Contoh berikut menggunakan `CreateAwsKmsRsaKeyring` metode untuk membuat AWS KMS keyring dengan kunci KMS RSA asimetris. Untuk membuat AWS KMS keyring RSA asimetris, berikan nilai berikut.
+ `kmsClient`: buat AWS KMS klien baru
+ `kmsKeyID`: kunci ARN yang mengidentifikasi kunci KMS RSA asimetris Anda
+ `publicKey`: file PEM yang dikodekan UTF-8 yang mewakili kunci publik dari kunci yang Anda kirimkan ByteBuffer `kmsKeyID`
+ `encryptionAlgorithm`: algoritma enkripsi harus `RSAES_OAEP_SHA_256` atau `RSAES_OAEP_SHA_1`
------
#### [ Java ]
```
final MaterialProviders matProv = MaterialProviders.builder()
.MaterialProvidersConfig(MaterialProvidersConfig.builder().build())
.build();
final CreateAwsKmsRsaKeyringInput createAwsKmsRsaKeyringInput =
CreateAwsKmsRsaKeyringInput.builder()
.kmsClient(KmsClient.create())
.kmsKeyId(rsaKMSKeyArn)
.publicKey(publicKey)
.encryptionAlgorithm(EncryptionAlgorithmSpec.RSAES_OAEP_SHA_256)
.build();
IKeyring awsKmsRsaKeyring = matProv.CreateAwsKmsRsaKeyring(createAwsKmsRsaKeyringInput);
```
------
#### [ C\$1 / .NET ]
```
var matProv = new MaterialProviders(new MaterialProvidersConfig());
var createAwsKmsRsaKeyringInput = new CreateAwsKmsRsaKeyringInput
{
KmsClient = new AmazonKeyManagementServiceClient(),
KmsKeyId = rsaKMSKeyArn,
PublicKey = publicKey,
EncryptionAlgorithm = EncryptionAlgorithmSpec.RSAES_OAEP_SHA_256
};
IKeyring awsKmsRsaKeyring = matProv.CreateAwsKmsRsaKeyring(createAwsKmsRsaKeyringInput);
```
------
#### [ Rust ]
```
let mpl_config = MaterialProvidersConfig::builder().build()?;
let mpl = mpl_client::Client::from_conf(mpl_config)?;
let sdk_config = aws_config::load_defaults(aws_config::BehaviorVersion::latest()).await;
let kms_rsa_keyring = mpl
.create_aws_kms_rsa_keyring()
.kms_key_id(rsa_kms_key_arn)
.public_key(public_key)
.encryption_algorithm(aws_sdk_kms::types::EncryptionAlgorithmSpec::RsaesOaepSha256)
.kms_client(aws_sdk_kms::Client::new(&sdk_config))
.send()
.await?;
```
------
## Menggunakan Multi-region AWS KMS keys
Anda dapat menggunakan Multi-region AWS KMS keys sebagai kunci pembungkus di SDK Enkripsi AWS Database. Jika Anda mengenkripsi dengan kunci Multi-wilayah dalam satu Wilayah AWS, Anda dapat mendekripsi menggunakan kunci Multi-wilayah terkait di yang berbeda. Wilayah AWS
Kunci KMS Multi-Region adalah satu AWS KMS keys set berbeda Wilayah AWS yang memiliki bahan kunci dan ID kunci yang sama. Anda dapat menggunakan kunci *terkait* ini seolah-olah mereka adalah kunci yang sama di Wilayah yang berbeda. Kunci Multi-Region mendukung pemulihan bencana umum dan skenario pencadangan yang memerlukan enkripsi di satu Wilayah dan mendekripsi di Wilayah yang berbeda tanpa melakukan panggilan lintas wilayah. AWS KMS Untuk informasi tentang kunci Multi-region, lihat [Menggunakan kunci Multi-region](https://docs.aws.amazon.com/kms/latest/developerguide/multi-region-keys-overview.html) di Panduan *AWS Key Management Service Pengembang*.
Untuk mendukung kunci Multi-region, AWS Database Encryption SDK menyertakan AWS KMS multi-Region-aware keyrings. `CreateAwsKmsMrkMultiKeyring`Metode ini mendukung kunci Single-region dan Multi-region.
+ Untuk kunci wilayah Tunggal, multi-Region-aware simbol berperilaku seperti keyring wilayah Tunggal AWS KMS . Ini mencoba untuk mendekripsi ciphertext hanya dengan kunci Single-region yang mengenkripsi data. Untuk menyederhanakan pengalaman AWS KMS keyring Anda, sebaiknya gunakan `CreateAwsKmsMrkMultiKeyring` metode ini setiap kali Anda menggunakan kunci KMS enkripsi simetris.
+ Untuk kunci Multi-region, multi-Region-aware simbol mencoba mendekripsi ciphertext dengan kunci Multi-region yang sama yang mengenkripsi data atau dengan kunci Multi-region terkait di Wilayah yang Anda tentukan.
Dalam multi-Region-aware gantungan kunci yang mengambil lebih dari satu kunci KMS, Anda dapat menentukan beberapa kunci Single-region dan Multi-region. Namun, Anda hanya dapat menentukan satu kunci dari setiap set kunci Multi-wilayah terkait. Jika Anda menentukan lebih dari satu pengenal kunci dengan ID kunci yang sama, panggilan konstruktor gagal.
Contoh berikut membuat AWS KMS keyring dengan kunci KMS Multi-region. Contoh menentukan kunci Multi-region sebagai kunci generator dan kunci Single-region sebagai kunci anak.
------
#### [ Java ]
```
final MaterialProviders matProv = MaterialProviders.builder()
.MaterialProvidersConfig(MaterialProvidersConfig.builder().build())
.build();
final CreateAwsKmsMrkMultiKeyringInput createAwsKmsMrkMultiKeyringInput =
CreateAwsKmsMrkMultiKeyringInput.builder()
.generator(multiRegionKeyArn)
.kmsKeyIds(Collections.singletonList(kmsKeyArn))
.build();
IKeyring awsKmsMrkMultiKeyring = matProv.CreateAwsKmsMrkMultiKeyring(createAwsKmsMrkMultiKeyringInput);
```
------
#### [ C\$1 / .NET ]
```
var matProv = new MaterialProviders(new MaterialProvidersConfig());
var createAwsKmsMrkMultiKeyringInput = new CreateAwsKmsMrkMultiKeyringInput
{
Generator = multiRegionKeyArn,
KmsKeyIds = new List { kmsKeyArn }
};
var awsKmsMrkMultiKeyring = matProv.CreateAwsKmsMrkMultiKeyring(createAwsKmsMrkMultiKeyringInput);
```
------
#### [ Rust ]
```
let mpl_config = MaterialProvidersConfig::builder().build()?;
let mpl = mpl_client::Client::from_conf(mpl_config)?;
let aws_kms_mrk_multi_keyring = mpl
.create_aws_kms_mrk_multi_keyring()
.generator(multiRegion_key_arn)
.kms_key_ids(vec![key_arn.to_string()])
.send()
.await?;
```
------
Saat Anda menggunakan AWS KMS gantungan kunci Multi-wilayah, Anda dapat mendekripsi ciphertext dalam mode ketat atau mode temukan. Untuk mendekripsi ciphertext dalam mode ketat, buat instance simbol multi-Region-aware dengan kunci ARN dari kunci Multi-region terkait di wilayah yang Anda dekripsi ciphertext. Jika Anda menentukan kunci ARN dari kunci Multi-wilayah terkait di Wilayah yang berbeda (misalnya, wilayah tempat catatan dienkripsi), multi-Region-aware simbol akan membuat panggilan lintas wilayah untuk itu. AWS KMS key
Saat mendekripsi dalam mode ketat, multi-Region-aware simbol membutuhkan kunci ARN. Ini hanya menerima satu ARN kunci dari setiap set kunci Multi-wilayah terkait.
Anda juga dapat mendekripsi dalam *mode penemuan* dengan tombol AWS KMS Multi-wilayah. Saat mendekripsi dalam mode penemuan, Anda tidak menentukan apa pun. AWS KMS keys(Untuk informasi tentang gantungan kunci AWS KMS penemuan wilayah tunggal, lihat[Menggunakan AWS KMS keyring penemuan](#kms-keyring-discovery).)
Jika Anda dienkripsi dengan kunci Multi-region, multi-Region-aware simbol dalam mode penemuan akan mencoba mendekripsi dengan menggunakan kunci Multi-wilayah terkait di Wilayah lokal. Jika tidak ada; panggilan gagal. Dalam mode penemuan, SDK Enkripsi AWS Database tidak akan mencoba panggilan lintas wilayah untuk kunci Multi-wilayah yang digunakan untuk enkripsi.
## Menggunakan AWS KMS keyring penemuan
Saat mendekripsi, ini adalah praktik terbaik untuk menentukan kunci pembungkus yang dapat digunakan SDK Enkripsi AWS Database. Untuk mengikuti praktik terbaik ini, gunakan keyring AWS KMS dekripsi yang membatasi kunci AWS KMS pembungkus ke kunci yang Anda tentukan. Namun, Anda juga dapat membuat *keyring AWS KMS penemuan*, yaitu AWS KMS keyring yang tidak menentukan kunci pembungkus apa pun.
AWS Database Encryption SDK menyediakan keyring AWS KMS penemuan standar dan keyring penemuan untuk AWS KMS kunci Multi-region. Untuk informasi tentang menggunakan kunci Multi-region dengan AWS Database Encryption SDK, lihat. [Menggunakan Multi-region AWS KMS keys](#config-mrks)
Karena tidak menentukan kunci pembungkus apa pun, keyring penemuan tidak dapat mengenkripsi data. Jika Anda menggunakan keyring penemuan untuk mengenkripsi data, sendiri atau dalam multi-keyring, operasi enkripsi gagal.
Saat mendekripsi, keyring penemuan memungkinkan SDK Enkripsi AWS Database meminta AWS KMS untuk mendekripsi kunci data terenkripsi apa pun dengan menggunakan kunci yang dienkripsi, terlepas dari siapa AWS KMS key yang memiliki atau memiliki akses ke sana. AWS KMS key Panggilan hanya berhasil ketika penelepon memiliki `kms:Decrypt` izin pada. AWS KMS key
**penting**
Jika Anda menyertakan keyring AWS KMS penemuan dalam [multi-keyring dekripsi, keyring](use-multi-keyring.md) penemuan mengesampingkan semua batasan kunci KMS yang ditentukan oleh gantungan kunci lain di multi-keyring. Multi-keyring berperilaku seperti keyring yang paling tidak membatasi. Jika Anda menggunakan keyring penemuan untuk mengenkripsi data, sendiri atau dalam multi-keyring, operasi enkripsi gagal
AWS Database Encryption SDK menyediakan keyring AWS KMS penemuan untuk kenyamanan. Namun, kami menyarankan Anda menggunakan keyring yang lebih terbatas bila memungkinkan karena alasan berikut.
+ **Keaslian** — Keyring AWS KMS penemuan dapat menggunakan apa pun AWS KMS key yang digunakan untuk mengenkripsi kunci data dalam deskripsi materi, selama penelepon memiliki izin untuk menggunakannya untuk mendekripsi. AWS KMS key Ini mungkin bukan AWS KMS key yang ingin digunakan penelepon. Misalnya, salah satu kunci data terenkripsi mungkin telah dienkripsi di bawah yang kurang aman AWS KMS key yang dapat digunakan siapa pun.
+ **Latensi dan kinerja** — Keyring AWS KMS penemuan mungkin terlihat lebih lambat daripada keyring lain karena SDK Enkripsi AWS Database mencoba mendekripsi semua kunci data terenkripsi, termasuk yang dienkripsi oleh AWS KMS keys di lain Akun AWS dan Wilayah, dan AWS KMS keys bahwa pemanggil tidak memiliki izin untuk digunakan untuk dekripsi.
[Jika Anda menggunakan keyring penemuan, kami sarankan Anda menggunakan [*filter penemuan*](configure.md#config-discovery) untuk membatasi kunci KMS yang dapat digunakan untuk kunci yang ditentukan Akun AWS dan partisi.](https://docs.aws.amazon.com/general/latest/gr/aws-arns-and-namespaces.html) Untuk bantuan menemukan ID akun dan partisi Anda, lihat [Akun AWS Pengenal Anda](https://docs.aws.amazon.com/general/latest/gr/acct-identifiers.html) dan format [ARN](https://docs.aws.amazon.com/general/latest/gr/aws-arns-and-namespaces.html#arns-syntax) di. *Referensi Umum AWS*
Contoh kode berikut membuat instance keyring penemuan dengan filter AWS KMS penemuan yang membatasi kunci KMS yang dapat digunakan SDK Enkripsi AWS Database untuk yang ada di partisi dan akun contoh. `aws` `111122223333`
Sebelum menggunakan kode ini, ganti contoh Akun AWS dan nilai partisi dengan nilai yang valid untuk Anda Akun AWS dan partisi. Jika kunci KMS Anda berada di Wilayah Tiongkok, gunakan nilai `aws-cn` partisi. Jika kunci KMS Anda masuk AWS GovCloud (US) Regions, gunakan nilai `aws-us-gov` partisi. Untuk yang lainnya Wilayah AWS, gunakan nilai `aws` partisi.
------
#### [ Java ]
```
// Create discovery filter
DiscoveryFilter discoveryFilter = DiscoveryFilter.builder()
.partition("aws")
.accountIds(111122223333)
.build();
// Create the discovery keyring
CreateAwsKmsMrkDiscoveryMultiKeyringInput createAwsKmsMrkDiscoveryMultiKeyringInput = CreateAwsKmsMrkDiscoveryMultiKeyringInput.builder()
.discoveryFilter(discoveryFilter)
.build();
IKeyring decryptKeyring = matProv.CreateAwsKmsMrkDiscoveryMultiKeyring(createAwsKmsMrkDiscoveryMultiKeyringInput);
```
------
#### [ C\$1 / .NET ]
```
// Create discovery filter
var discoveryFilter = new DiscoveryFilter
{
Partition = "aws",
AccountIds = 111122223333
};
// Create the discovery keyring
var createAwsKmsMrkDiscoveryMultiKeyringInput = new CreateAwsKmsMrkDiscoveryMultiKeyringInput
{
DiscoveryFilter = discoveryFilter
};
var decryptKeyring = matProv.CreateAwsKmsMrkDiscoveryMultiKeyring(createAwsKmsMrkDiscoveryMultiKeyringInput);
```
------
#### [ Rust ]
```
// Create discovery filter
let discovery_filter = DiscoveryFilter::builder()
.partition("aws")
.account_ids(111122223333)
.build()?;
// Create the discovery keyring
let decrypt_keyring = mpl
.create_aws_kms_mrk_discovery_multi_keyring()
.discovery_filter(discovery_filter)
.send()
.await?;
```
------
## Menggunakan AWS KMS keyring penemuan regional
*Keyring penemuan AWS KMS regional* adalah keyring yang tidak menentukan kunci ARNs KMS. Sebaliknya, ini memungkinkan SDK Enkripsi AWS Database untuk mendekripsi hanya menggunakan kunci KMS pada khususnya. Wilayah AWS
Saat mendekripsi dengan keyring penemuan AWS KMS regional, SDK Enkripsi AWS Database mendekripsi kunci data terenkripsi yang dienkripsi di bawah kunci yang ditentukan. AWS KMS key Wilayah AWS Agar berhasil, penelepon harus memiliki `kms:Decrypt` izin setidaknya satu dari yang AWS KMS keys ditentukan Wilayah AWS yang mengenkripsi kunci data.
Seperti keyrings penemuan lainnya, keyring penemuan regional tidak berpengaruh pada enkripsi. Ini hanya berfungsi saat mendekripsi bidang terenkripsi. Jika Anda menggunakan keyring penemuan regional dalam multi-keyring yang digunakan untuk mengenkripsi dan mendekripsi, ini hanya efektif saat mendekripsi. Jika Anda menggunakan keyring penemuan Multi-wilayah untuk mengenkripsi data, sendiri atau dalam multi-keyring, operasi enkripsi gagal.
**penting**
Jika Anda menyertakan keyring penemuan AWS KMS regional dalam [multi-keyring dekripsi, keyring](use-multi-keyring.md) penemuan regional mengesampingkan semua batasan kunci KMS yang ditentukan oleh gantungan kunci lain di multi-keyring. Multi-keyring berperilaku seperti keyring yang paling tidak membatasi. Keyring AWS KMS penemuan tidak berpengaruh pada enkripsi saat digunakan sendiri atau dalam multi-keyring.
Keyring penemuan regional di SDK Enkripsi AWS Database mencoba mendekripsi hanya dengan kunci KMS di Wilayah yang ditentukan. Saat Anda menggunakan keyring penemuan, Anda mengonfigurasi Wilayah pada AWS KMS klien. Implementasi SDK Enkripsi AWS Database ini tidak memfilter kunci KMS menurut Wilayah, tetapi AWS KMS akan gagal dalam permintaan dekripsi untuk kunci KMS di luar Wilayah yang ditentukan.
Jika Anda menggunakan keyring penemuan, sebaiknya gunakan *filter penemuan* untuk membatasi kunci KMS yang digunakan dalam dekripsi ke kunci yang ditentukan dan partisi. Akun AWS
Misalnya, kode berikut membuat keyring penemuan AWS KMS regional dengan filter penemuan. Keyring ini membatasi SDK Enkripsi AWS Database ke kunci KMS di akun 111122223333 di Wilayah AS Barat (Oregon) (us-west-2).
------
#### [ Java ]
```
// Create the discovery filter
DiscoveryFilter discoveryFilter = DiscoveryFilter.builder()
.partition("aws")
.accountIds(111122223333)
.build();
// Create the discovery keyring
CreateAwsKmsMrkDiscoveryMultiKeyringInput createAwsKmsMrkDiscoveryMultiKeyringInput = CreateAwsKmsMrkDiscoveryMultiKeyringInput.builder()
.discoveryFilter(discoveryFilter)
.regions("us-west-2")
.build();
IKeyring decryptKeyring = matProv.CreateAwsKmsMrkDiscoveryMultiKeyring(createAwsKmsMrkDiscoveryMultiKeyringInput);
```
------
#### [ C\$1 / .NET ]
```
// Create discovery filter
var discoveryFilter = new DiscoveryFilter
{
Partition = "aws",
AccountIds = 111122223333
};
// Create the discovery keyring
var createAwsKmsMrkDiscoveryMultiKeyringInput = new CreateAwsKmsMrkDiscoveryMultiKeyringInput
{
DiscoveryFilter = discoveryFilter,
Regions = us-west-2
};
var decryptKeyring = matProv.CreateAwsKmsMrkDiscoveryMultiKeyring(createAwsKmsMrkDiscoveryMultiKeyringInput);
```
------
#### [ Rust ]
```
// Create discovery filter
let discovery_filter = DiscoveryFilter::builder()
.partition("aws")
.account_ids(111122223333)
.build()?;
// Create the discovery keyring
let decrypt_keyring = mpl
.create_aws_kms_mrk_discovery_multi_keyring()
.discovery_filter(discovery_filter)
.regions(us-west-2)
.send()
.await?;
```
------
# AWS KMS Gantungan kunci hierarkis
****
| |
| --- |
| 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). |
**catatan**
Mulai 24 Juli 2023, kunci cabang yang dibuat selama pratinjau pengembang tidak didukung. Buat kunci cabang baru untuk terus menggunakan toko kunci yang Anda buat selama pratinjau pengembang.
Dengan keyring AWS KMS Hierarkis, Anda dapat melindungi materi kriptografi Anda di bawah kunci KMS enkripsi simetris tanpa menelepon AWS KMS setiap kali Anda mengenkripsi atau mendekripsi catatan. Ini adalah pilihan yang baik untuk aplikasi yang perlu meminimalkan panggilan ke AWS KMS, dan aplikasi yang dapat menggunakan kembali beberapa materi kriptografi tanpa melanggar persyaratan keamanan mereka.
Hierarchical keyring adalah solusi caching materi kriptografi yang mengurangi jumlah AWS KMS panggilan dengan menggunakan *kunci cabang yang AWS KMS dilindungi yang disimpan dalam tabel Amazon DynamoDB, dan kemudian secara lokal menyimpan materi kunci cabang* yang digunakan dalam operasi enkripsi dan dekripsi. Tabel DynamoDB berfungsi sebagai penyimpanan kunci yang mengelola dan melindungi kunci cabang. Ini menyimpan kunci cabang aktif dan semua versi sebelumnya dari kunci cabang. Kunci cabang *aktif* adalah versi kunci cabang terbaru. Keyring Hierarkis menggunakan kunci enkripsi data unik untuk setiap permintaan enkripsi dan mengenkripsi setiap kunci enkripsi data dengan kunci pembungkus unik yang berasal dari kunci cabang aktif. Keyring Hierarkis tergantung pada hierarki yang ditetapkan antara kunci cabang aktif dan kunci pembungkus turunannya.
Keyring Hierarkis biasanya menggunakan setiap versi kunci cabang untuk memenuhi beberapa permintaan. Tetapi Anda mengontrol sejauh mana kunci cabang aktif digunakan kembali dan menentukan seberapa sering kunci cabang aktif diputar. Versi aktif dari kunci cabang tetap aktif sampai Anda [memutarnya](rotate-branch-key.md). Versi sebelumnya dari kunci cabang aktif tidak akan digunakan untuk melakukan operasi enkripsi, tetapi masih dapat ditanyakan dan digunakan dalam operasi dekripsi.
Ketika Anda membuat instance keyring Hierarchical, itu membuat cache lokal. Anda menentukan [batas cache](#cache-limit) yang menentukan jumlah waktu maksimum materi kunci cabang disimpan dalam cache lokal sebelum kedaluwarsa dan dikeluarkan dari cache. Hierarchical keyring membuat satu AWS KMS panggilan untuk mendekripsi kunci cabang dan merakit materi kunci cabang saat pertama kali a `branch-key-id` ditentukan dalam suatu operasi. Kemudian, materi kunci cabang disimpan dalam cache lokal dan digunakan kembali untuk semua operasi enkripsi dan dekripsi yang menentukan itu `branch-key-id` sampai batas cache berakhir. Menyimpan materi kunci cabang di cache lokal mengurangi AWS KMS panggilan. Misalnya, pertimbangkan batas cache 15 menit. Jika Anda melakukan 10.000 operasi enkripsi dalam batas cache tersebut, [AWS KMS keyring tradisional](use-kms-keyring.md) perlu melakukan 10.000 AWS KMS panggilan untuk memenuhi 10.000 operasi enkripsi. Jika Anda memiliki satu aktif`branch-key-id`, keyring Hierarkis hanya perlu membuat satu AWS KMS panggilan untuk memenuhi 10.000 operasi enkripsi.
Cache lokal memisahkan bahan enkripsi dari bahan dekripsi. Materi enkripsi dirakit dari kunci cabang aktif dan digunakan kembali untuk semua operasi enkripsi hingga batas cache berakhir. Materi dekripsi dirakit dari ID kunci cabang dan versi yang diidentifikasi dalam metadata bidang terenkripsi, dan digunakan kembali untuk semua operasi dekripsi yang terkait dengan ID kunci cabang dan versi hingga batas cache berakhir. Cache lokal dapat menyimpan beberapa versi kunci cabang yang sama pada satu waktu. Ketika cache lokal dikonfigurasi untuk menggunakan a[branch key ID supplier](#branch-key-id-supplier), itu juga dapat menyimpan materi kunci cabang dari beberapa kunci cabang aktif pada satu waktu.
**catatan**
Semua penyebutan *keyring Hierarkis* dalam SDK Enkripsi AWS Database mengacu pada keyring Hierarkis. AWS KMS
**Topics**
+ [Cara kerjanya](#how-hierarchical-keyring-works)
+ [Prasyarat](#hierarchical-keyring-prereqs)
+ [Izin yang diperlukan](#hierarchical-keyring-permissions)
+ [Pilih cache](#hierarchical-keyring-caches)
+ [Buat keyring Hierarkis](#initialize-hierarchical-keyring)
+ [Menggunakan keyring Hierarkis untuk enkripsi yang dapat dicari](#searchable-encryption-hierarchical-keyrings)
## Cara kerjanya
Panduan berikut menjelaskan bagaimana keyring Hierarkis merakit bahan enkripsi dan dekripsi, dan panggilan berbeda yang dibuat oleh keyring untuk mengenkripsi dan mendekripsi operasi. Untuk detail teknis tentang derivasi kunci pembungkus dan proses enkripsi kunci data plaintext, lihat Detail teknis keyring [AWS KMS hierarkis](reference.md#hierarchical-keyring-details).
**Enkripsi dan tandatangani**
Panduan berikut menjelaskan bagaimana keyring Hierarkis merakit bahan enkripsi dan memperoleh kunci pembungkus yang unik.
1. Metode enkripsi meminta keyring Hierarkis untuk materi enkripsi. Keyring menghasilkan kunci data plaintext, lalu memeriksa untuk melihat apakah ada materi kunci cabang yang valid di cache lokal untuk menghasilkan kunci pembungkus. Jika ada materi kunci cabang yang valid, keyring dilanjutkan ke **Langkah** 4.
1. Jika tidak ada materi kunci cabang yang valid, keyring Hierarkis menanyakan penyimpanan kunci untuk kunci cabang aktif.
1. Key store memanggil AWS KMS untuk mendekripsi kunci cabang aktif dan mengembalikan kunci cabang aktif plaintext. Data yang mengidentifikasi kunci cabang aktif diserialisasi untuk memberikan data otentikasi tambahan (AAD) dalam panggilan dekripsi ke. AWS KMS
1. Toko kunci mengembalikan kunci cabang plaintext dan data yang mengidentifikasinya, seperti versi kunci cabang.
1. Hierarchical keyring merakit materi kunci cabang (kunci cabang plaintext dan versi kunci cabang) dan menyimpan salinannya di cache lokal.
1. Keyring Hierarchical memperoleh kunci pembungkus unik dari kunci cabang plaintext dan garam acak 16-byte. Ini menggunakan kunci pembungkus turunan untuk mengenkripsi salinan kunci data teks biasa.
Metode enkripsi menggunakan bahan enkripsi untuk mengenkripsi dan menandatangani catatan. Untuk informasi selengkapnya tentang cara catatan dienkripsi dan ditandatangani di SDK Enkripsi AWS Database, lihat [Mengenkripsi](how-it-works.md#encrypt-and-sign) dan menandatangani.
**Dekripsi dan verifikasi**
Panduan berikut menjelaskan bagaimana keyring Hierarkis merakit bahan dekripsi dan mendekripsi kunci data terenkripsi.
1. Metode dekripsi mengidentifikasi kunci data terenkripsi dari bidang deskripsi material dari catatan terenkripsi, dan meneruskannya ke keyring Hierarkis.
1. Hierarchical keyring deserialisasi data yang mengidentifikasi kunci data terenkripsi, termasuk versi kunci cabang, garam 16-byte, dan informasi lain yang menjelaskan bagaimana kunci data dienkripsi.
Untuk informasi selengkapnya, lihat [AWS KMS Rincian teknis keyring hierarkis](reference.md#hierarchical-keyring-details).
1. Keyring hierarkis memeriksa untuk melihat apakah ada materi kunci cabang yang valid di cache lokal yang cocok dengan versi kunci cabang yang diidentifikasi pada **Langkah** 2. Jika ada materi kunci cabang yang valid, keyring dilanjutkan ke **Langkah** 6.
1. **Jika tidak ada materi kunci cabang yang valid, keyring Hierarkis menanyakan penyimpanan kunci untuk kunci cabang yang cocok dengan versi kunci cabang yang diidentifikasi pada Langkah 2.**
1. Key store memanggil AWS KMS untuk mendekripsi kunci cabang dan mengembalikan kunci cabang aktif plaintext. Data yang mengidentifikasi kunci cabang aktif diserialisasi untuk memberikan data otentikasi tambahan (AAD) dalam panggilan dekripsi ke. AWS KMS
1. Toko kunci mengembalikan kunci cabang plaintext dan data yang mengidentifikasinya, seperti versi kunci cabang.
1. Hierarchical keyring merakit materi kunci cabang (kunci cabang plaintext dan versi kunci cabang) dan menyimpan salinannya di cache lokal.
1. Keyring Hierarchical menggunakan bahan kunci cabang yang dirakit dan garam 16-byte yang diidentifikasi pada **Langkah 2** untuk mereproduksi kunci pembungkus unik yang mengenkripsi kunci data.
1. Keyring Hierarkis menggunakan kunci pembungkus yang direproduksi untuk mendekripsi kunci data dan mengembalikan kunci data plaintext.
Metode dekripsi menggunakan bahan dekripsi dan kunci data teks biasa untuk mendekripsi dan memverifikasi catatan. Untuk informasi selengkapnya tentang cara rekaman didekripsi dan diverifikasi di SDK Enkripsi AWS Database, lihat [Mendekripsi](how-it-works.md#decrypt-and-verify) dan memverifikasi.
## Prasyarat
Sebelum Anda membuat dan menggunakan keyring Hierarkis, pastikan prasyarat berikut terpenuhi.
+ Anda, atau administrator toko kunci Anda, telah [membuat toko kunci](create-keystore.md) dan [membuat setidaknya satu kunci cabang aktif](create-branch-keys.md).
+ Anda telah [mengonfigurasi tindakan penyimpanan utama Anda](keystore-actions.md#config-keystore-actions).
**catatan**
Cara Anda mengonfigurasi tindakan penyimpanan kunci menentukan operasi apa yang dapat Anda lakukan dan kunci KMS apa yang dapat digunakan oleh keyring Hierarkis. Untuk informasi selengkapnya, lihat [Tindakan penyimpanan kunci](keystore-actions.md).
+ Anda memiliki AWS KMS izin yang diperlukan untuk mengakses dan menggunakan kunci penyimpanan dan cabang kunci. Untuk informasi selengkapnya, lihat [Izin yang diperlukan](#hierarchical-keyring-permissions).
+ Anda telah meninjau jenis cache yang didukung dan mengonfigurasi jenis cache yang paling sesuai dengan kebutuhan Anda. Untuk informasi selengkapnya, lihat [Pilih cache](#hierarchical-keyring-caches)
## Izin yang diperlukan
SDK Enkripsi AWS Database tidak memerlukan Akun AWS dan tidak bergantung pada apa pun Layanan AWS. Namun, untuk menggunakan keyring Hierarkis, Anda memerlukan izin minimum Akun AWS dan berikut pada enkripsi simetris di AWS KMS key toko kunci Anda.
+ [Untuk mengenkripsi dan mendekripsi data dengan keyring Hierarkis, Anda memerlukan KMS: Decrypt.](https://docs.aws.amazon.com/kms/latest/APIReference/API_Decrypt.html)
+ Untuk [membuat](create-branch-keys.md) dan [memutar](rotate-branch-key.md) kunci cabang, Anda memerlukan [kms: GenerateDataKeyWithoutPlaintext](https://docs.aws.amazon.com/kms/latest/APIReference/API_GenerateDataKeyWithoutPlaintext.html) dan [kms](https://docs.aws.amazon.com/kms/latest/APIReference/API_ReEncrypt.html):. ReEncrypt
Untuk informasi selengkapnya tentang mengontrol akses ke kunci cabang dan penyimpanan kunci Anda, lihat[Menerapkan izin yang paling tidak diistimewakan](keystore-least-privilege.md).
## Pilih cache
Keyring Hierarkis mengurangi jumlah panggilan yang dilakukan AWS KMS dengan menyimpan materi kunci cabang secara lokal yang digunakan dalam operasi enkripsi dan dekripsi. Sebelum [Anda membuat keyring Hierarkis](#initialize-hierarchical-keyring) Anda, Anda perlu memutuskan jenis cache yang ingin Anda gunakan. Anda dapat menggunakan cache default atau menyesuaikan cache agar sesuai dengan kebutuhan Anda.
Keyring Hierarkis mendukung jenis cache berikut:
+ [Cache default](#cache-default)
+ [MultiThreaded cache](#cache-multithreaded)
+ [StormTracking cache](#cache-stormtracking)
+ [Cache bersama](#cache-shared)
### Cache default
Untuk sebagian besar pengguna, cache Default memenuhi persyaratan threading mereka. Cache Default dirancang untuk mendukung lingkungan yang sangat multithreaded. Ketika entri materi kunci cabang kedaluwarsa, cache Default mencegah beberapa utas memanggil AWS KMS dengan memberi tahu satu utas bahwa entri materi kunci cabang akan kedaluwarsa 10 detik sebelumnya. Ini memastikan bahwa hanya satu utas yang mengirimkan permintaan AWS KMS untuk menyegarkan cache.
Default dan StormTracking cache mendukung model threading yang sama, tetapi Anda hanya perlu menentukan kapasitas entri untuk menggunakan cache Default. Untuk kustomisasi cache yang lebih terperinci, gunakan file. [StormTracking cache](#cache-stormtracking)
Kecuali Anda ingin menyesuaikan jumlah entri materi kunci cabang yang dapat disimpan di cache lokal, Anda tidak perlu menentukan jenis cache saat Anda membuat keyring Hierarkis. Jika Anda tidak menentukan jenis cache, keyring Hierarkis menggunakan jenis cache Default dan menetapkan kapasitas entri ke 1000.
Untuk menyesuaikan cache Default, tentukan nilai berikut:
+ **Kapasitas entri**: membatasi jumlah entri materi kunci cabang yang dapat disimpan di cache lokal.
------
#### [ Java ]
```
.cache(CacheType.builder()
.Default(DefaultCache.builder()
.entryCapacity(100)
.build())
```
------
#### [ C\$1 / .NET ]
```
CacheType defaultCache = new CacheType
{
Default = new DefaultCache{EntryCapacity = 100}
};
```
------
#### [ Rust ]
```
let cache: CacheType = CacheType::Default(
DefaultCache::builder()
.entry_capacity(100)
.build()?,
);
```
------
### MultiThreaded cache
MultiThreaded Cache aman digunakan di lingkungan multithreaded, tetapi tidak menyediakan fungsionalitas apa pun untuk meminimalkan atau panggilan Amazon AWS KMS DynamoDB. Akibatnya, ketika entri materi kunci cabang kedaluwarsa, semua utas akan diberitahukan pada saat yang sama. Ini dapat menghasilkan beberapa AWS KMS panggilan untuk menyegarkan cache.
Untuk menggunakan MultiThreaded cache, tentukan nilai berikut:
+ **Kapasitas entri**: membatasi jumlah entri materi kunci cabang yang dapat disimpan di cache lokal.
+ **Ukuran ekor pemangkasan entri**: menentukan jumlah entri yang akan dipangkas jika kapasitas masuk tercapai.
------
#### [ Java ]
```
.cache(CacheType.builder()
.MultiThreaded(MultiThreadedCache.builder()
.entryCapacity(100)
.entryPruningTailSize(1)
.build())
```
------
#### [ C\$1 / .NET ]
```
CacheType multithreadedCache = new CacheType
{
MultiThreaded = new MultiThreadedCache
{
EntryCapacity = 100,
EntryPruningTailSize = 1
}
};
```
------
#### [ Rust ]
```
CacheType::MultiThreaded(
MultiThreadedCache::builder()
.entry_capacity(100)
.entry_pruning_tail_size(1)
.build()?)
```
------
### StormTracking cache
StormTracking Cache dirancang untuk mendukung lingkungan yang sangat multithreaded. Ketika entri materi kunci cabang kedaluwarsa, StormTracking cache mencegah beberapa utas memanggil AWS KMS dengan memberi tahu satu utas bahwa entri materi kunci cabang akan kedaluwarsa sebelumnya. Ini memastikan bahwa hanya satu utas yang mengirimkan permintaan AWS KMS untuk menyegarkan cache.
Untuk menggunakan StormTracking cache, tentukan nilai berikut:
+ **Kapasitas entri**: membatasi jumlah entri materi kunci cabang yang dapat disimpan di cache lokal.
Nilai default: 1000 entri
+ **Ukuran ekor pemangkasan entri**: menentukan jumlah entri bahan kunci cabang untuk dipangkas sekaligus.
Nilai default: 1 entri
+ **Masa tenggang**: mendefinisikan jumlah detik sebelum kedaluwarsa bahwa upaya untuk menyegarkan materi kunci cabang dilakukan.
Nilai default: 10 detik
+ **Interval rahmat**: mendefinisikan jumlah detik antara upaya untuk menyegarkan materi kunci cabang.
Nilai default: 1 detik
+ **Fan out**: mendefinisikan jumlah upaya simultan yang dapat dilakukan untuk menyegarkan materi kunci cabang.
Nilai default: 20 upaya
+ **In flight time to live (TTL)**: mendefinisikan jumlah detik hingga upaya untuk menyegarkan materi kunci cabang habis waktu. Setiap kali cache kembali `NoSuchEntry` sebagai respons terhadap a`GetCacheEntry`, kunci cabang tersebut dianggap *dalam penerbangan* sampai kunci yang sama ditulis dengan `PutCache` entri.
Nilai default: 10 detik
+ **Tidur**: mendefinisikan jumlah detik bahwa sebuah utas harus tidur jika `fanOut` terlampaui.
Nilai default: 20 milidetik
------
#### [ Java ]
```
.cache(CacheType.builder()
.StormTracking(StormTrackingCache.builder()
.entryCapacity(100)
.entryPruningTailSize(1)
.gracePeriod(10)
.graceInterval(1)
.fanOut(20)
.inFlightTTL(10)
.sleepMilli(20)
.build())
```
------
#### [ C\$1 / .NET ]
```
CacheType stormTrackingCache = new CacheType
{
StormTracking = new StormTrackingCache
{
EntryCapacity = 100,
EntryPruningTailSize = 1,
FanOut = 20,
GraceInterval = 1,
GracePeriod = 10,
InFlightTTL = 10,
SleepMilli = 20
}
};
```
------
#### [ Rust ]
```
CacheType::StormTracking(
StormTrackingCache::builder()
.entry_capacity(100)
.entry_pruning_tail_size(1)
.grace_period(10)
.grace_interval(1)
.fan_out(20)
.in_flight_ttl(10)
.sleep_milli(20)
.build()?)
```
------
### Cache bersama
Secara default, keyring Hierarkis membuat cache lokal baru setiap kali Anda membuat instance keyring. Namun, cache Bersama dapat membantu menghemat memori dengan memungkinkan Anda berbagi cache di beberapa gantungan kunci Hierarkis. Daripada membuat cache materi kriptografi baru untuk setiap keyring Hierarkis yang Anda buat instance, cache Bersama hanya menyimpan satu cache dalam memori, yang dapat digunakan oleh semua gantungan kunci Hierarkis yang mereferensikannya. Cache bersama membantu mengoptimalkan penggunaan memori dengan menghindari duplikasi materi kriptografi di seluruh keyrings. Sebagai gantinya, gantungan kunci Hierarkis dapat mengakses cache dasar yang sama, mengurangi jejak memori secara keseluruhan.
Saat Anda membuat cache Bersama, Anda masih menentukan jenis cache. Anda dapat menentukan[Cache default](#cache-default),[MultiThreaded cache](#cache-multithreaded), atau [StormTracking cache](#cache-stormtracking) sebagai jenis cache, atau mengganti cache kustom yang kompatibel.
**Partisi**
Beberapa keyrings Hierarkis dapat menggunakan satu cache Bersama. Saat Anda membuat keyring Hierarkis dengan cache Bersama, Anda dapat menentukan ID **partisi** opsional. ID partisi membedakan keyring Hierarkis mana yang menulis ke cache. Jika dua keyrings hirarkis mereferensikan ID partisi yang sama[logical key store name](create-keystore.md#logical-key-store-name), dan ID kunci cabang kedua keyrings akan berbagi entri cache yang sama dalam cache. Jika Anda membuat dua gantungan kunci Hierarkis dengan cache Bersama yang sama, tetapi partisi yang berbeda IDs, setiap keyring hanya akan mengakses entri cache dari partisi yang ditunjuk sendiri dalam cache Bersama. Partisi bertindak sebagai divisi logis dalam cache bersama, memungkinkan setiap keyring Hierarkis beroperasi secara independen pada partisi yang ditunjuk sendiri, tanpa mengganggu data yang disimpan di partisi lain.
Jika Anda bermaksud untuk menggunakan kembali atau berbagi entri cache di partisi, Anda harus menentukan ID partisi Anda sendiri. Saat Anda meneruskan ID partisi ke keyring Hierarkis Anda, keyring dapat menggunakan kembali entri cache yang sudah ada di cache Bersama, daripada harus mengambil dan mengotorisasi ulang materi kunci cabang lagi. Jika Anda tidak menentukan ID partisi, ID partisi unik secara otomatis ditetapkan ke keyring setiap kali Anda membuat instance keyring Hierarkis.
Prosedur berikut menunjukkan cara membuat cache Bersama dengan [tipe cache Default](#cache-default) dan meneruskannya ke keyring Hierarkis.
1. Buat `CryptographicMaterialsCache` (CMC) menggunakan [Material Providers Library](https://github.com/aws/aws-cryptographic-material-providers-library) (MPL).
------
#### [ Java ]
```
// Instantiate the MPL
final MaterialProviders matProv =
MaterialProviders.builder()
.MaterialProvidersConfig(MaterialProvidersConfig.builder().build())
.build();
// Create a CacheType object for the Default cache
final CacheType cache =
CacheType.builder()
.Default(DefaultCache.builder().entryCapacity(100).build())
.build();
// Create a CMC using the default cache
final CreateCryptographicMaterialsCacheInput cryptographicMaterialsCacheInput =
CreateCryptographicMaterialsCacheInput.builder()
.cache(cache)
.build();
final ICryptographicMaterialsCache sharedCryptographicMaterialsCache =
matProv.CreateCryptographicMaterialsCache(cryptographicMaterialsCacheInput);
```
------
#### [ C\$1 / .NET ]
```
// Instantiate the MPL
var materialProviders = new MaterialProviders(new MaterialProvidersConfig());
// Create a CacheType object for the Default cache
var cache = new CacheType { Default = new DefaultCache{EntryCapacity = 100} };
// Create a CMC using the default cache
var cryptographicMaterialsCacheInput = new CreateCryptographicMaterialsCacheInput {Cache = cache};
var sharedCryptographicMaterialsCache = materialProviders.CreateCryptographicMaterialsCache(cryptographicMaterialsCacheInput);
```
------
#### [ Rust ]
```
// Instantiate the MPL
let mpl_config = MaterialProvidersConfig::builder().build()?;
let mpl = mpl_client::Client::from_conf(mpl_config)?;
// Create a CacheType object for the default cache
let cache: CacheType = CacheType::Default(
DefaultCache::builder()
.entry_capacity(100)
.build()?,
);
// Create a CMC using the default cache
let shared_cryptographic_materials_cache: CryptographicMaterialsCacheRef = mpl.
create_cryptographic_materials_cache()
.cache(cache)
.send()
.await?;
```
------
1. Buat `CacheType` objek untuk cache Bersama.
Lulus yang `sharedCryptographicMaterialsCache` Anda buat di **Langkah 1** ke `CacheType` objek baru.
------
#### [ Java ]
```
// Create a CacheType object for the sharedCryptographicMaterialsCache
final CacheType sharedCache =
CacheType.builder()
.Shared(sharedCryptographicMaterialsCache)
.build();
```
------
#### [ C\$1 / .NET ]
```
// Create a CacheType object for the sharedCryptographicMaterialsCache
var sharedCache = new CacheType { Shared = sharedCryptographicMaterialsCache };
```
------
#### [ Rust ]
```
// Create a CacheType object for the shared_cryptographic_materials_cache
let shared_cache: CacheType = CacheType::Shared(shared_cryptographic_materials_cache);
```
------
1. Lewati `sharedCache` objek dari **Langkah 2** ke keyring Hierarkis Anda.
Saat Anda membuat keyring Hierarkis dengan cache Bersama, Anda dapat secara opsional menentukan entri `partitionID` untuk berbagi cache di beberapa gantungan kunci Hierarkis. Jika Anda tidak menentukan ID partisi, keyring Hierarkis secara otomatis menetapkan keyring ID partisi unik.
**catatan**
Keyring Hierarkis Anda akan berbagi entri cache yang sama dalam cache Bersama jika Anda membuat dua atau lebih keyrings yang mereferensikan ID partisi yang sama[logical key store name](create-keystore.md#logical-key-store-name), dan ID kunci cabang. Jika Anda tidak ingin beberapa keyrings berbagi entri cache yang sama, Anda harus menggunakan ID partisi unik untuk setiap keyring Hierarkis.
Contoh berikut membuat keyring Hierarkis dengan[branch key ID supplier](#branch-key-id-supplier), dan [batas cache](#cache-limit) 600 detik. Untuk informasi selengkapnya tentang nilai yang ditentukan dalam konfigurasi keyring Hierarkis berikut, lihat. [Buat keyring Hierarkis](#initialize-hierarchical-keyring)
------
#### [ Java ]
```
// Create the Hierarchical keyring
final CreateAwsKmsHierarchicalKeyringInput keyringInput =
CreateAwsKmsHierarchicalKeyringInput.builder()
.keyStore(keystore)
.branchKeyIdSupplier(branchKeyIdSupplier)
.ttlSeconds(600)
.cache(sharedCache)
.partitionID(partitionID)
.build();
final IKeyring hierarchicalKeyring = matProv.CreateAwsKmsHierarchicalKeyring(keyringInput);
```
------
#### [ C\$1 / .NET ]
```
// Create the Hierarchical keyring
var createKeyringInput = new CreateAwsKmsHierarchicalKeyringInput
{
KeyStore = keystore,
BranchKeyIdSupplier = branchKeyIdSupplier,
Cache = sharedCache,
TtlSeconds = 600,
PartitionId = partitionID
};
var keyring = materialProviders.CreateAwsKmsHierarchicalKeyring(createKeyringInput);
```
------
#### [ Rust ]
```
// Create the Hierarchical keyring
let keyring1 = mpl
.create_aws_kms_hierarchical_keyring()
.key_store(key_store1)
.branch_key_id(branch_key_id.clone())
// CryptographicMaterialsCacheRef is an Rc (Reference Counted), so if you clone it to
// pass it to different Hierarchical Keyrings, it will still point to the same
// underlying cache, and increment the reference count accordingly.
.cache(shared_cache.clone())
.ttl_seconds(600)
.partition_id(partition_id.clone())
.send()
.await?;
```
------
## Buat keyring Hierarkis
Untuk membuat keyring Hierarkis, Anda harus memberikan nilai-nilai berikut:
+ **Nama toko kunci**
Nama tabel DynamoDB yang Anda, atau administrator toko utama Anda, dibuat untuk berfungsi sebagai toko kunci Anda.
+
**Batas waktu cache untuk hidup (TTL)**
Jumlah waktu dalam hitungan detik entri materi kunci cabang dalam cache lokal dapat digunakan sebelum kedaluwarsa. Batas cache TTL menentukan seberapa sering klien memanggil AWS KMS untuk mengotorisasi penggunaan kunci cabang. Nilai ini harus lebih besar dari nol. Setelah batas cache TTL berakhir, entri tidak pernah disajikan, dan akan diusir dari cache lokal.
+ **Pengidentifikasi kunci cabang**
Anda dapat mengonfigurasi secara statis `branch-key-id` yang mengidentifikasi satu kunci cabang aktif di toko kunci Anda, atau memberikan pemasok ID kunci cabang.
*Pemasok ID kunci cabang* menggunakan bidang yang disimpan dalam konteks enkripsi untuk menentukan kunci cabang mana yang diperlukan untuk mendekripsi catatan. Secara default, hanya partisi dan kunci pengurutan yang disertakan dalam konteks enkripsi. Namun, Anda dapat menggunakan [tindakan `SIGN_AND_INCLUDE_IN_ENCRYPTION_CONTEXT` kriptografi](concepts.md#crypt-actions) untuk memasukkan bidang tambahan dalam konteks enkripsi.
Kami sangat menyarankan menggunakan pemasok ID kunci cabang untuk database multitenant di mana setiap penyewa memiliki kunci cabang mereka sendiri. Anda dapat menggunakan pemasok ID kunci cabang untuk membuat nama yang ramah IDs untuk kunci cabang Anda agar mudah mengenali ID kunci cabang yang benar untuk penyewa tertentu. Misalnya, nama ramah memungkinkan Anda merujuk ke kunci cabang sebagai `tenant1` gantinya`b3f61619-4d35-48ad-a275-050f87e15122`.
Untuk operasi dekripsi, Anda dapat mengonfigurasi secara statis satu keyring Hierarkis untuk membatasi dekripsi ke penyewa tunggal, atau Anda dapat menggunakan pemasok ID kunci cabang untuk mengidentifikasi penyewa mana yang bertanggung jawab untuk mendekripsi catatan.
+ **(Opsional) Sebuah cache**
Jika Anda ingin menyesuaikan jenis cache atau jumlah entri materi kunci cabang yang dapat disimpan di cache lokal, tentukan jenis cache dan kapasitas entri saat Anda menginisialisasi keyring.
Keyring Hierarkis mendukung jenis cache berikut: Default,, MultiThreaded StormTracking, dan Shared. Untuk informasi selengkapnya dan contoh yang menunjukkan cara menentukan setiap jenis cache, lihat[Pilih cache](#hierarchical-keyring-caches).
Jika Anda tidak menentukan cache, keyring Hierarkis secara otomatis menggunakan jenis cache Default dan menetapkan kapasitas entri ke 1000.
+ **(Opsional) Sebuah ID partisi**
Jika Anda menentukan[Cache bersama](#cache-shared), Anda dapat secara opsional menentukan ID partisi. ID partisi membedakan keyring Hierarkis mana yang menulis ke cache. Jika Anda bermaksud untuk menggunakan kembali atau berbagi entri cache di partisi, Anda harus menentukan ID partisi Anda sendiri. Anda dapat menentukan string apa pun untuk ID partisi. Jika Anda tidak menentukan ID partisi, ID partisi unik secara otomatis ditetapkan ke keyring saat pembuatan.
Untuk informasi selengkapnya, lihat [Partitions](#shared-cache-partitions).
**catatan**
Keyring Hierarkis Anda akan berbagi entri cache yang sama dalam cache Bersama jika Anda membuat dua atau lebih keyrings yang mereferensikan ID partisi yang sama[logical key store name](create-keystore.md#logical-key-store-name), dan ID kunci cabang. Jika Anda tidak ingin beberapa keyrings berbagi entri cache yang sama, Anda harus menggunakan ID partisi unik untuk setiap keyring Hierarkis.
+ **(Opsional) Daftar Token Hibah**
Jika Anda mengontrol akses ke kunci KMS di keyring Hierarkis Anda dengan [hibah](https://docs.aws.amazon.com/kms/latest/developerguide/grants.html), Anda harus menyediakan semua token hibah yang diperlukan saat Anda menginisialisasi keyring.
### Buat keyring Hierarkis dengan ID kunci cabang statis
Contoh berikut menunjukkan cara membuat keyring Hierarkis dengan ID kunci cabang statis, TTL[Cache default](#cache-default), dan batas cache 600 detik.
------
#### [ Java ]
```
final MaterialProviders matProv = MaterialProviders.builder()
.MaterialProvidersConfig(MaterialProvidersConfig.builder().build())
.build();
final CreateAwsKmsHierarchicalKeyringInput keyringInput = CreateAwsKmsHierarchicalKeyringInput.builder()
.keyStore(branchKeyStoreName)
.branchKeyId(branch-key-id)
.ttlSeconds(600)
.build();
final Keyring hierarchicalKeyring = matProv.CreateAwsKmsHierarchicalKeyring(keyringInput);
```
------
#### [ C\$1 / .NET ]
```
var matProv = new MaterialProviders(new MaterialProvidersConfig());
var keyringInput = new CreateAwsKmsHierarchicalKeyringInput
{
KeyStore = keystore,
BranchKeyIdSupplier = branchKeyIdSupplier,
TtlSeconds = 600
};
var hierarchicalKeyring = matProv.CreateAwsKmsHierarchicalKeyring(keyringInput);
```
------
#### [ Rust ]
```
let mpl_config = MaterialProvidersConfig::builder().build()?;
let mpl = mpl_client::Client::from_conf(mpl_config)?;
let hierarchical_keyring = mpl
.create_aws_kms_hierarchical_keyring()
.branch_key_id(branch_key_id)
.key_store(branch_key_store_name)
.ttl_seconds(600)
.send()
.await?;
```
------
### Buat keyring Hierarkis dengan pemasok ID kunci cabang
Prosedur berikut menunjukkan cara membuat keyring Hierarkis dengan pemasok ID kunci cabang.
1. Buat pemasok ID kunci cabang
Contoh berikut membuat nama ramah untuk dua kunci cabang yang dibuat pada **Langkah 1**, dan panggilan `CreateDynamoDbEncryptionBranchKeyIdSupplier` untuk membuat pemasok ID kunci cabang dengan AWS Database Encryption SDK untuk klien DynamoDB.
------
#### [ Java ]
```
// Create friendly names for each branch-key-id
class ExampleBranchKeyIdSupplier implements IDynamoDbKeyBranchKeyIdSupplier {
private static String branchKeyIdForTenant1;
private static String branchKeyIdForTenant2;
public ExampleBranchKeyIdSupplier(String tenant1Id, String tenant2Id) {
this.branchKeyIdForTenant1 = tenant1Id;
this.branchKeyIdForTenant2 = tenant2Id;
}
// Create the branch key ID supplier
final DynamoDbEncryption ddbEnc = DynamoDbEncryption.builder()
.DynamoDbEncryptionConfig(DynamoDbEncryptionConfig.builder().build())
.build();
final BranchKeyIdSupplier branchKeyIdSupplier = ddbEnc.CreateDynamoDbEncryptionBranchKeyIdSupplier(
CreateDynamoDbEncryptionBranchKeyIdSupplierInput.builder()
.ddbKeyBranchKeyIdSupplier(new ExampleBranchKeyIdSupplier(branch-key-ID-tenant1, branch-key-ID-tenant2))
.build()).branchKeyIdSupplier();
```
------
#### [ C\$1 / .NET ]
```
// Create friendly names for each branch-key-id
class ExampleBranchKeyIdSupplier : DynamoDbKeyBranchKeyIdSupplierBase {
private String _branchKeyIdForTenant1;
private String _branchKeyIdForTenant2;
public ExampleBranchKeyIdSupplier(String tenant1Id, String tenant2Id) {
this._branchKeyIdForTenant1 = tenant1Id;
this._branchKeyIdForTenant2 = tenant2Id;
}
// Create the branch key ID supplier
var ddbEnc = new DynamoDbEncryption(new DynamoDbEncryptionConfig());
var branchKeyIdSupplier = ddbEnc.CreateDynamoDbEncryptionBranchKeyIdSupplier(
new CreateDynamoDbEncryptionBranchKeyIdSupplierInput
{
DdbKeyBranchKeyIdSupplier = new ExampleBranchKeyIdSupplier(branch-key-ID-tenant1, branch-key-ID-tenant2)
}).BranchKeyIdSupplier;
```
------
#### [ Rust ]
```
// Create friendly names for each branch_key_id
pub struct ExampleBranchKeyIdSupplier {
branch_key_id_for_tenant1: String,
branch_key_id_for_tenant2: String,
}
impl ExampleBranchKeyIdSupplier {
pub fn new(tenant1_id: &str, tenant2_id: &str) -> Self {
Self {
branch_key_id_for_tenant1: tenant1_id.to_string(),
branch_key_id_for_tenant2: tenant2_id.to_string(),
}
}
}
// Create the branch key ID supplier
let dbesdk_config = DynamoDbEncryptionConfig::builder().build()?;
let dbesdk = dbesdk_client::Client::from_conf(dbesdk_config)?;
let supplier = ExampleBranchKeyIdSupplier::new(tenant1_branch_key_id, tenant2_branch_key_id);
let branch_key_id_supplier = dbesdk
.create_dynamo_db_encryption_branch_key_id_supplier()
.ddb_key_branch_key_id_supplier(supplier)
.send()
.await?
.branch_key_id_supplier
.unwrap();
```
------
1. Buat keyring Hierarkis
Contoh berikut menginisialisasi keyring Hierarkis dengan pemasok ID kunci cabang yang dibuat pada **Langkah 1**, batas cache TLL 600 detik, dan ukuran cache maksimum 1000.
------
#### [ Java ]
```
final MaterialProviders matProv = MaterialProviders.builder()
.MaterialProvidersConfig(MaterialProvidersConfig.builder().build())
.build();
final CreateAwsKmsHierarchicalKeyringInput keyringInput = CreateAwsKmsHierarchicalKeyringInput.builder()
.keyStore(keystore)
.branchKeyIdSupplier(branchKeyIdSupplier)
.ttlSeconds(600)
.cache(CacheType.builder() //OPTIONAL
.Default(DefaultCache.builder()
.entryCapacity(100)
.build())
.build())
.build();
final Keyring hierarchicalKeyring = matProv.CreateAwsKmsHierarchicalKeyring(keyringInput);
```
------
#### [ C\$1 / .NET ]
```
var matProv = new MaterialProviders(new MaterialProvidersConfig());
var keyringInput = new CreateAwsKmsHierarchicalKeyringInput
{
KeyStore = keystore,
BranchKeyIdSupplier = branchKeyIdSupplier,
TtlSeconds = 600,
Cache = new CacheType
{
Default = new DefaultCache { EntryCapacity = 100 }
}
};
var hierarchicalKeyring = matProv.CreateAwsKmsHierarchicalKeyring(keyringInput);
```
------
#### [ Rust ]
```
let mpl_config = MaterialProvidersConfig::builder().build()?;
let mpl = mpl_client::Client::from_conf(mpl_config)?;
let hierarchical_keyring = mpl
.create_aws_kms_hierarchical_keyring()
.branch_key_id_supplier(branch_key_id_supplier)
.key_store(key_store)
.ttl_seconds(600)
.send()
.await?;
```
------
## Menggunakan keyring Hierarkis untuk enkripsi yang dapat dicari
[Enkripsi yang dapat dicari](searchable-encryption.md) memungkinkan Anda untuk mencari catatan terenkripsi tanpa mendekripsi seluruh database. [Ini dicapai dengan mengindeks nilai plaintext dari bidang terenkripsi dengan suar.](beacons.md) Untuk mengimplementasikan enkripsi yang dapat dicari, Anda harus menggunakan keyring Hierarkis.
`CreateKey`Operasi penyimpanan kunci menghasilkan kunci cabang dan kunci *suar*. Kunci cabang digunakan dalam enkripsi catatan dan operasi dekripsi. Kunci suar digunakan untuk menghasilkan suar.
Kunci cabang dan kunci suar dilindungi oleh yang sama dengan AWS KMS key yang Anda tentukan saat membuat layanan toko kunci Anda. Setelah panggilan `CreateKey` operasi AWS KMS untuk menghasilkan kunci cabang, ia memanggil [kms: GenerateDataKeyWithoutPlaintext](https://docs.aws.amazon.com/kms/latest/APIReference/API_GenerateDataKeyWithoutPlaintext.html) kedua kalinya untuk menghasilkan kunci suar menggunakan permintaan berikut.
```
{
"EncryptionContext": {
"branch-key-id" : "branch-key-id",
"type" : type,
"create-time" : "timestamp",
"tablename" : "the logical table name for your key store",
"kms-arn" : the KMS key ARN,
"hierarchy-version" : 1
},
"KeyId": "the KMS key ARN",
"NumberOfBytes": "32"
}
```
Setelah menghasilkan kedua kunci, `CreateKey` operasi memanggil [ddb: TransactWriteItems](https://docs.aws.amazon.com/amazondynamodb/latest/APIReference/API_TransactWriteItems.html) untuk menulis dua item baru yang akan mempertahankan kunci cabang dan kunci suar di toko kunci cabang Anda.
Saat Anda [mengonfigurasi suar standar](configure-beacons.md#config-standard-beacons), SDK Enkripsi AWS Database menanyakan penyimpanan kunci untuk kunci suar. Kemudian, ia menggunakan fungsi derivasi extract-and-expand kunci berbasis HMAC ([HKDF](https://en.wikipedia.org/wiki/HKDF)) untuk menggabungkan kunci suar dengan nama suar [standar untuk membuat kunci HMAC untuk suar](beacons.md#standard-beacon-overview) yang diberikan.
Tidak seperti kunci cabang, hanya ada satu versi kunci suar per `branch-key-id` di toko kunci. Kunci suar tidak pernah diputar.
### Mendefinisikan sumber kunci suar Anda
Saat Anda menentukan [versi beacon](using-beacons.md#beacon-version) untuk beacon standar dan gabungan Anda, Anda harus mengidentifikasi kunci suar dan menentukan batas waktu cache untuk hidup (TTL) untuk materi kunci suar. Materi kunci suar disimpan dalam cache lokal terpisah dari kunci cabang. Cuplikan berikut menunjukkan bagaimana mendefinisikan untuk database penyewa `keySource` tunggal. Identifikasi kunci suar Anda dengan yang `branch-key-id` terkait dengannya.
------
#### [ Java ]
```
keySource(BeaconKeySource.builder()
.single(SingleKeyStore.builder()
.keyId(branch-key-id)
.cacheTTL(6000)
.build())
.build())
```
------
#### [ C\$1 / .NET ]
```
KeySource = new BeaconKeySource
{
Single = new SingleKeyStore
{
KeyId = branch-key-id,
CacheTTL = 6000
}
}
```
------
#### [ Rust ]
```
.key_source(BeaconKeySource::Single(
SingleKeyStore::builder()
// `keyId` references a beacon key.
// For every branch key we create in the keystore,
// we also create a beacon key.
// This beacon key is not the same as the branch key,
// but is created with the same ID as the branch key.
.key_id(branch_key_id)
.cache_ttl(6000)
.build()?,
))
```
------
**Mendefinisikan sumber suar dalam database multitenant**
Jika Anda memiliki database multitenant, Anda harus menentukan nilai-nilai berikut saat mengkonfigurasi. `keySource`
+
**keyFieldName**
Mendefinisikan nama bidang yang menyimpan yang `branch-key-id` terkait dengan kunci suar yang digunakan untuk menghasilkan suar untuk penyewa tertentu. `keyFieldName`Bisa berupa string apa saja, tetapi harus unik untuk semua bidang lain di database Anda. Saat Anda menulis catatan baru ke database Anda, `branch-key-id` yang mengidentifikasi kunci suar yang digunakan untuk menghasilkan suar apa pun untuk catatan itu disimpan di bidang ini. Anda harus menyertakan bidang ini dalam kueri suar Anda dan mengidentifikasi bahan kunci suar yang sesuai yang diperlukan untuk menghitung ulang suar. Untuk informasi selengkapnya, lihat [Menanyakan beacon dalam database multitenant](searchable-encryption-multitenant.md#query-multitenant-beacons).
+ **CacheTTL**
Jumlah waktu dalam hitungan detik entri bahan kunci suar dalam cache suar lokal dapat digunakan sebelum kedaluwarsa. Nilai ini harus lebih besar dari nol. Ketika batas cache TTL kedaluwarsa, entri diusir dari cache lokal.
+ **(Opsional) Sebuah cache**
Jika Anda ingin menyesuaikan jenis cache atau jumlah entri materi kunci cabang yang dapat disimpan di cache lokal, tentukan jenis cache dan kapasitas entri saat Anda menginisialisasi keyring.
Keyring Hierarkis mendukung jenis cache berikut: Default,, MultiThreaded StormTracking, dan Shared. Untuk informasi selengkapnya dan contoh yang menunjukkan cara menentukan setiap jenis cache, lihat[Pilih cache](#hierarchical-keyring-caches).
Jika Anda tidak menentukan cache, keyring Hierarkis secara otomatis menggunakan jenis cache Default dan menetapkan kapasitas entri ke 1000.
Contoh berikut membuat keyring Hierarkis dengan pemasok ID kunci cabang TLL batas cache 600 detik, dan kapasitas entri 1000.
```
final MaterialProviders matProv = MaterialProviders.builder()
.MaterialProvidersConfig(MaterialProvidersConfig.builder().build())
.build();
final CreateAwsKmsHierarchicalKeyringInput keyringInput = CreateAwsKmsHierarchicalKeyringInput.builder()
.keyStore(branchKeyStoreName)
.branchKeyIdSupplier(branchKeyIdSupplier)
.ttlSeconds(600)
.cache(CacheType.builder() //OPTIONAL
.Default(DefaultCache.builder()
.entryCapacity(1000)
.build())
.build());
final IKeyring hierarchicalKeyring = matProv.CreateAwsKmsHierarchicalKeyring(keyringInput);
```
```
var matProv = new MaterialProviders(new MaterialProvidersConfig());
var keyringInput = new CreateAwsKmsHierarchicalKeyringInput
{
KeyStore = keystore,
BranchKeyIdSupplier = branchKeyIdSupplier,
TtlSeconds = 600,
Cache = new CacheType
{
Default = new DefaultCache { EntryCapacity = 1000 }
}
};
var hierarchicalKeyring = matProv.CreateAwsKmsHierarchicalKeyring(keyringInput);
```
```
let provider_config = MaterialProvidersConfig::builder().build()?;
let mat_prov = client::Client::from_conf(provider_config)?;
let kms_keyring = mat_prov
.create_aws_kms_hierarchical_keyring()
.branch_key_id(branch_key_id)
.key_store(key_store)
.ttl_seconds(600)
.send()
.await?;
```
# AWS KMS Gantungan kunci ECDH
****
| |
| --- |
| 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**
Gantungan kunci AWS KMS ECDH hanya tersedia dengan versi 1.5.0 atau yang lebih baru dari Perpustakaan Penyedia Material.
Gantungan kunci AWS KMS ECDH menggunakan kesepakatan kunci asimetris [AWS KMS keys](https://docs.aws.amazon.com/kms/latest/developerguide/key-types.html)untuk mendapatkan kunci pembungkus simetris bersama antara dua pihak. Pertama, keyring menggunakan algoritma perjanjian kunci Elliptic Curve Diffie-Hellman (ECDH) untuk mendapatkan rahasia bersama dari kunci pribadi di KMS key pair pengirim dan kunci publik penerima. 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 bukan dari key pair KMS, maka Bob dapat membuat [keyring ECDH mentah](use-raw-ecdh-keyring.md) untuk mendekripsi catatan.
Keyring AWS KMS ECDH mengenkripsi catatan dengan kunci simetris menggunakan AES-GCM. Kunci data kemudian dienkripsi dengan kunci pembungkus bersama turunan menggunakan AES-GCM. [Setiap keyring AWS KMS ECDH hanya dapat memiliki satu kunci pembungkus bersama, tetapi Anda dapat menyertakan beberapa gantungan kunci AWS KMS ECDH, sendiri atau dengan gantungan kunci lainnya, dalam multi-keyring.](use-multi-keyring.md)
**Topics**
+ [Izin yang diperlukan untuk gantungan kunci AWS KMS ECDH](#kms-ecdh-permissions)
+ [Membuat keyring AWS KMS ECDH](#kms-ecdh-create)
+ [Membuat keyring AWS KMS penemuan ECDH](#kms-ecdh-discovery)
## Izin yang diperlukan untuk gantungan kunci AWS KMS ECDH
SDK Enkripsi AWS Database tidak memerlukan AWS akun dan tidak bergantung pada AWS layanan apa pun. Namun, untuk menggunakan keyring AWS KMS ECDH, Anda memerlukan AWS akun dan izin minimum berikut pada keyring Anda. AWS KMS keys Izin bervariasi berdasarkan skema perjanjian kunci yang Anda gunakan.
+ Untuk mengenkripsi dan mendekripsi catatan menggunakan skema perjanjian `KmsPrivateKeyToStaticPublicKey` kunci, Anda memerlukan [kms: GetPublicKey dan kms: DeriveSharedSecret](https://docs.aws.amazon.com/kms/latest/APIReference/API_GetPublicKey.html) [pada key pair KMS *asimetris*](https://docs.aws.amazon.com/kms/latest/APIReference/API_DeriveSharedSecret.html) pengirim. Jika Anda langsung memberikan kunci publik yang dienkode DER pengirim saat membuat instance keyring, Anda hanya perlu DeriveSharedSecret izin [kms: pada key pair KMS asimetris](https://docs.aws.amazon.com/kms/latest/APIReference/API_DeriveSharedSecret.html) pengirim.
+ Untuk mendekripsi catatan menggunakan skema perjanjian `KmsPublicKeyDiscovery` kunci, Anda memerlukan GetPublicKey izin [kms: DeriveSharedSecret dan kms:](https://docs.aws.amazon.com/kms/latest/APIReference/API_DeriveSharedSecret.html) pada key [pair KMS](https://docs.aws.amazon.com/kms/latest/APIReference/API_GetPublicKey.html) asimetris yang ditentukan.
## Membuat keyring AWS KMS ECDH
Untuk membuat keyring AWS KMS ECDH yang mengenkripsi dan mendekripsi data, Anda harus menggunakan skema perjanjian kunci. `KmsPrivateKeyToStaticPublicKey` Untuk menginisialisasi keyring AWS KMS ECDH dengan skema perjanjian `KmsPrivateKeyToStaticPublicKey` kunci, berikan nilai-nilai berikut:
+ **ID Pengirim AWS KMS key **
Harus mengidentifikasi asymmetric NIST recommended elliptic curve (ECC) KMS key pair dengan nilai. `KeyUsage` `KEY_AGREEMENT` Kunci pribadi pengirim digunakan untuk mendapatkan rahasia bersama.
+ **(Opsional) Kunci publik pengirim**
[Harus berupa kunci publik X.509 yang dikodekan DER, juga dikenal sebagai `SubjectPublicKeyInfo` (SPKI), sebagaimana didefinisikan dalam RFC 5280.](https://tools.ietf.org/html/rfc5280)
AWS KMS [GetPublicKey](https://docs.aws.amazon.com/kms/latest/APIReference/API_GetPublicKey.html)Operasi mengembalikan kunci publik dari key pair KMS asimetris dalam format yang dienkode DER yang diperlukan.
Untuk mengurangi jumlah AWS KMS panggilan yang dilakukan keyring Anda, Anda dapat langsung memberikan kunci publik pengirim. Jika tidak ada nilai yang diberikan untuk kunci publik pengirim, keyring akan memanggil AWS KMS untuk mengambil kunci publik pengirim.
+ **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)
AWS KMS [GetPublicKey](https://docs.aws.amazon.com/kms/latest/APIReference/API_GetPublicKey.html)Operasi mengembalikan kunci publik dari key pair KMS asimetris dalam format yang dienkode DER yang diperlukan.
+ **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`
+ **(Opsional) Daftar Token Hibah**
Jika Anda mengontrol akses ke kunci KMS di keyring AWS KMS ECDH Anda dengan [hibah, Anda harus memberikan semua token hibah](https://docs.aws.amazon.com/kms/latest/developerguide/grants.html) yang diperlukan saat Anda menginisialisasi keyring.
------
#### [ C\$1 / .NET ]
Contoh berikut membuat keyring AWS KMS ECDH dengan kunci KMS pengirim, kunci publik pengirim, dan kunci publik penerima. Contoh ini menggunakan `senderPublicKey` parameter opsional untuk menyediakan kunci publik pengirim. Jika Anda tidak memberikan kunci publik pengirim, keyring akan memanggil AWS KMS untuk mengambil kunci publik pengirim. Pasangan kunci pengirim dan penerima berada di `ECC_NIST_P256` kurva.
```
// 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 ]
Contoh berikut membuat keyring AWS KMS ECDH dengan kunci KMS pengirim, kunci publik pengirim, dan kunci publik penerima. Contoh ini menggunakan `senderPublicKey` parameter opsional untuk menyediakan kunci publik pengirim. Jika Anda tidak memberikan kunci publik pengirim, keyring akan memanggil AWS KMS untuk mengambil kunci publik pengirim. Pasangan kunci pengirim dan penerima berada di `ECC_NIST_P256` kurva.
```
// 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();
```
------
#### [ Rust ]
Contoh berikut membuat keyring AWS KMS ECDH dengan kunci KMS pengirim, kunci publik pengirim, dan kunci publik penerima. Contoh ini menggunakan `sender_public_key` parameter opsional untuk menyediakan kunci publik pengirim. Jika Anda tidak memberikan kunci publik pengirim, keyring akan memanggil AWS KMS untuk mengambil kunci publik pengirim.
```
// Retrieve public keys
// Must be DER-encoded X.509 keys
let public_key_file_content_sender = std::fs::read_to_string(Path::new(EXAMPLE_KMS_ECC_PUBLIC_KEY_FILENAME_SENDER))?;
let parsed_public_key_file_content_sender = parse(public_key_file_content_sender)?;
let public_key_sender_utf8_bytes = parsed_public_key_file_content_sender.contents();
let public_key_file_content_recipient = std::fs::read_to_string(Path::new(EXAMPLE_KMS_ECC_PUBLIC_KEY_FILENAME_RECIPIENT))?;
let parsed_public_key_file_content_recipient = parse(public_key_file_content_recipient)?;
let public_key_recipient_utf8_bytes = parsed_public_key_file_content_recipient.contents();
// Create KmsPrivateKeyToStaticPublicKeyInput
let kms_ecdh_static_configuration_input =
KmsPrivateKeyToStaticPublicKeyInput::builder()
.sender_kms_identifier(arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab)
// Must be a UTF8 DER-encoded X.509 public key
.sender_public_key(public_key_sender_utf8_bytes)
// Must be a UTF8 DER-encoded X.509 public key
.recipient_public_key(public_key_recipient_utf8_bytes)
.build()?;
let kms_ecdh_static_configuration = KmsEcdhStaticConfigurations::KmsPrivateKeyToStaticPublicKey(kms_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 AWS KMS ECDH keyring
let kms_ecdh_keyring = mpl
.create_aws_kms_ecdh_keyring()
.kms_client(kms_client)
.curve_spec(ecdh_curve_spec)
.key_agreement_scheme(kms_ecdh_static_configuration)
.send()
.await?;
```
------
## Membuat keyring AWS KMS penemuan ECDH
Saat mendekripsi, ini adalah praktik terbaik untuk menentukan kunci yang dapat digunakan SDK Enkripsi AWS Database. Untuk mengikuti praktik terbaik ini, gunakan gantungan kunci AWS KMS ECDH dengan skema perjanjian `KmsPrivateKeyToStaticPublicKey` kunci. Namun, Anda juga dapat membuat keyring penemuan AWS KMS ECDH, yaitu keyring AWS KMS ECDH yang dapat mendekripsi catatan apa pun di mana kunci publik dari key pair KMS yang ditentukan cocok dengan kunci publik *penerima yang disimpan di bidang deskripsi material dari catatan terenkripsi*.
**penting**
Ketika Anda mendekripsi catatan menggunakan skema perjanjian `KmsPublicKeyDiscovery` kunci, Anda menerima semua kunci publik, terlepas dari siapa yang memilikinya.
Untuk menginisialisasi keyring AWS KMS ECDH dengan skema perjanjian `KmsPublicKeyDiscovery` kunci, berikan nilai-nilai berikut:
+ ** AWS KMS key ID Penerima**
Harus mengidentifikasi asymmetric NIST recommended elliptic curve (ECC) KMS key pair dengan nilai. `KeyUsage` `KEY_AGREEMENT`
+ **Spesifikasi kurva**
Mengidentifikasi spesifikasi kurva eliptik dalam key pair KMS penerima.
Nilai valid: `ECC_NIST_P256`, `ECC_NIS_P384`, `ECC_NIST_P512`
+ **(Opsional) Daftar Token Hibah**
Jika Anda mengontrol akses ke kunci KMS di keyring AWS KMS ECDH Anda dengan [hibah, Anda harus memberikan semua token hibah](https://docs.aws.amazon.com/kms/latest/developerguide/grants.html) yang diperlukan saat Anda menginisialisasi keyring.
------
#### [ C\$1 / .NET ]
Contoh berikut membuat keyring penemuan AWS KMS ECDH dengan key pair KMS pada kurva. `ECC_NIST_P256` Anda harus memiliki DeriveSharedSecret izin [kms: GetPublicKey](https://docs.aws.amazon.com/kms/latest/APIReference/API_GetPublicKey.html) dan [kms:](https://docs.aws.amazon.com/kms/latest/APIReference/API_DeriveSharedSecret.html) pada key pair KMS yang ditentukan. Keyring ini dapat mendekripsi catatan apa pun di mana kunci publik dari key pair KMS yang ditentukan cocok dengan kunci publik penerima yang disimpan di bidang deskripsi material dari catatan terenkripsi.
```
// 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 ]
Contoh berikut membuat keyring penemuan AWS KMS ECDH dengan key pair KMS pada kurva. `ECC_NIST_P256` Anda harus memiliki DeriveSharedSecret izin [kms: GetPublicKey](https://docs.aws.amazon.com/kms/latest/APIReference/API_GetPublicKey.html) dan [kms:](https://docs.aws.amazon.com/kms/latest/APIReference/API_DeriveSharedSecret.html) pada key pair KMS yang ditentukan. Keyring ini dapat mendekripsi catatan apa pun di mana kunci publik dari key pair KMS yang ditentukan cocok dengan kunci publik penerima yang disimpan di bidang deskripsi material dari catatan terenkripsi.
```
// 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();
```
------
#### [ Rust ]
```
// Create KmsPublicKeyDiscoveryInput
let kms_ecdh_discovery_static_configuration_input =
KmsPublicKeyDiscoveryInput::builder()
.recipient_kms_identifier(ecc_recipient_key_arn)
.build()?;
let kms_ecdh_discovery_static_configuration = KmsEcdhStaticConfigurations::KmsPublicKeyDiscovery(kms_ecdh_discovery_static_configuration_input);
// Instantiate the material providers library
let mpl_config = MaterialProvidersConfig::builder().build()?;
let mpl = mpl_client::Client::from_conf(mpl_config)?;
// Create AWS KMS ECDH discovery keyring
let kms_ecdh_discovery_keyring = mpl
.create_aws_kms_ecdh_keyring()
.kms_client(kms_client.clone())
.curve_spec(ecdh_curve_spec)
.key_agreement_scheme(kms_ecdh_discovery_static_configuration)
.send()
.await?;
```
------
# Gantungan kunci AES mentah
****
| |
| --- |
| 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). |
SDK Enkripsi AWS Database memungkinkan Anda menggunakan kunci simetris AES yang Anda berikan sebagai kunci pembungkus yang melindungi kunci data Anda. Anda perlu membuat, menyimpan, dan melindungi materi utama, sebaiknya dalam modul keamanan perangkat keras (HSM) atau sistem manajemen kunci. Gunakan keyring Raw AES saat Anda perlu memberikan kunci pembungkus dan mengenkripsi kunci data secara lokal atau offline.
Raw AES keyring mengenkripsi data dengan menggunakan algoritma AES-GCM dan kunci pembungkus yang Anda tentukan sebagai array byte. [Anda hanya dapat menentukan satu kunci pembungkus di setiap keyring Raw AES, tetapi Anda dapat menyertakan beberapa gantungan kunci Raw AES, sendiri atau dengan gantungan kunci lainnya, dalam multi-keyring.](use-multi-keyring.md)
**Ruang nama dan nama kunci**
*Untuk mengidentifikasi kunci AES dalam keyring, keyring Raw AES menggunakan *namespace kunci dan nama kunci* yang Anda berikan.* Nilai-nilai ini bukan rahasia. Mereka muncul dalam teks biasa dalam [deskripsi materi](concepts.md#material-description) yang ditambahkan SDK Enkripsi AWS Database ke catatan. Sebaiknya gunakan namespace kunci HSM atau sistem manajemen kunci Anda dan nama kunci yang mengidentifikasi kunci AES dalam sistem itu.
**catatan**
Namespace kunci dan nama kunci setara dengan kolom *ID Penyedia* (atau *Penyedia*) dan *ID Kunci* di kolom. `JceMasterKey`
Jika Anda membuat keyring yang berbeda untuk mengenkripsi dan mendekripsi bidang tertentu, namespace dan nilai nama sangat penting. Jika namespace kunci dan nama kunci dalam keyring dekripsi bukan kecocokan yang tepat dan peka huruf besar/kecil untuk namespace kunci dan nama kunci dalam keyring enkripsi, keyring dekripsi tidak digunakan, meskipun byte materi kunci identik.
Misalnya, Anda mungkin mendefinisikan keyring Raw AES dengan namespace `HSM_01` kunci dan nama kunci. `AES_256_012` Kemudian, Anda menggunakan keyring itu untuk mengenkripsi beberapa data. Untuk mendekripsi data tersebut, buat keyring Raw AES dengan namespace kunci, nama kunci, dan material kunci yang sama.
Contoh berikut menunjukkan cara membuat keyring Raw AES. `AESWrappingKey`Variabel mewakili materi utama yang Anda berikan.
------
#### [ Java ]
```
final CreateRawAesKeyringInput keyringInput = CreateRawAesKeyringInput.builder()
.keyName("AES_256_012")
.keyNamespace("HSM_01")
.wrappingKey(AESWrappingKey)
.wrappingAlg(AesWrappingAlg.ALG_AES256_GCM_IV12_TAG16)
.build();
final MaterialProviders matProv = MaterialProviders.builder()
.MaterialProvidersConfig(MaterialProvidersConfig.builder().build())
.build();
IKeyring rawAesKeyring = matProv.CreateRawAesKeyring(keyringInput);
```
------
#### [ C\$1 / .NET ]
```
var keyNamespace = "HSM_01";
var keyName = "AES_256_012";
// This example uses the key generator in Bouncy Castle to generate the key material.
// In production, use key material from a secure source.
var aesWrappingKey = new MemoryStream(GeneratorUtilities.GetKeyGenerator("AES256").GenerateKey());
// Create the keyring
var keyringInput = new CreateRawAesKeyringInput
{
KeyNamespace = keyNamespace,
KeyName = keyName,
WrappingKey = AESWrappingKey,
WrappingAlg = AesWrappingAlg.ALG_AES256_GCM_IV12_TAG16
};
var matProv = new MaterialProviders(new MaterialProvidersConfig());
IKeyring rawAesKeyring = matProv.CreateRawAesKeyring(keyringInput);
```
------
#### [ Rust ]
```
let mpl_config = MaterialProvidersConfig::builder().build()?;
let mpl = mpl_client::Client::from_conf(mpl_config)?;
let raw_aes_keyring = mpl
.create_raw_aes_keyring()
.key_name("AES_256_012")
.key_namespace("HSM_01")
.wrapping_key(aes_key_bytes)
.wrapping_alg(AesWrappingAlg::AlgAes256GcmIv12Tag16)
.send()
.await?;
```
------
# Gantungan kunci RSA mentah
****
| |
| --- |
| 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). |
Raw RSA keyring melakukan enkripsi asimetris dan dekripsi kunci data dalam memori lokal dengan kunci publik dan pribadi RSA yang Anda berikan. Anda perlu membuat, menyimpan, dan melindungi kunci pribadi, sebaiknya dalam modul keamanan perangkat keras (HSM) atau sistem manajemen kunci. Fungsi enkripsi mengenkripsi kunci data di bawah kunci publik RSA. Fungsi dekripsi mendekripsi kunci data menggunakan kunci pribadi. Anda dapat memilih dari antara beberapa mode padding RSA.
Raw RSA keyring yang mengenkripsi dan mendekripsi harus menyertakan kunci publik asimetris dan private key pair. Namun, Anda dapat mengenkripsi data dengan keyring Raw RSA yang hanya memiliki kunci publik, dan Anda dapat mendekripsi data dengan keyring Raw RSA yang hanya memiliki kunci pribadi. [Anda dapat menyertakan keyring Raw RSA apa pun dalam multi-keyring.](use-multi-keyring.md) Jika Anda mengonfigurasi keyring Raw RSA dengan kunci publik dan pribadi, pastikan bahwa mereka adalah bagian dari key pair yang sama.
Raw RSA keyring setara dengan dan berinteraksi dengan [JceMasterKey](https://aws.github.io/aws-encryption-sdk-java/com/amazonaws/encryptionsdk/jce/JceMasterKey.html)in AWS Encryption SDK for Java ketika mereka digunakan dengan kunci enkripsi asimetris RSA.
**catatan**
Raw RSA keyring tidak mendukung kunci KMS asimetris. [Untuk menggunakan kunci KMS RSA asimetris, buat keyring.AWS KMS](use-kms-keyring.md)
**Ruang nama dan nama**
*Untuk mengidentifikasi materi kunci RSA dalam keyring, keyring Raw RSA menggunakan *namespace kunci dan nama kunci* yang Anda berikan.* Nilai-nilai ini bukan rahasia. Mereka muncul dalam teks biasa dalam [deskripsi materi](concepts.md#material-description) yang ditambahkan SDK Enkripsi AWS Database ke catatan. Sebaiknya gunakan namespace kunci dan nama kunci yang mengidentifikasi key pair RSA (atau kunci privatnya) di HSM atau sistem manajemen kunci Anda.
**catatan**
Namespace kunci dan nama kunci setara dengan kolom *ID Penyedia* (atau *Penyedia*) dan *ID Kunci* di kolom. `JceMasterKey`
Jika Anda membuat keyring yang berbeda untuk mengenkripsi dan mendekripsi catatan yang diberikan, namespace dan nilai nama sangat penting. Jika namespace kunci dan nama kunci dalam keyring dekripsi bukan kecocokan yang tepat dan peka huruf besar/kecil untuk namespace kunci dan nama kunci dalam keyring enkripsi, keyring dekripsi tidak digunakan, bahkan jika kunci tersebut berasal dari key pair yang sama.
Namespace kunci dan nama kunci dari bahan kunci dalam enkripsi dan dekripsi keyrings harus sama apakah keyring berisi kunci publik RSA, kunci pribadi RSA, atau kedua kunci dalam key pair. Misalnya, Anda mengenkripsi data dengan keyring Raw RSA untuk kunci publik RSA dengan namespace kunci dan nama `HSM_01` kunci. `RSA_2048_06` Untuk mendekripsi data tersebut, buat keyring Raw RSA dengan kunci pribadi (atau key pair), dan namespace dan nama kunci yang sama.
**Mode bantalan**
Anda harus menentukan mode padding untuk keyring Raw RSA yang digunakan untuk enkripsi dan dekripsi, atau menggunakan fitur implementasi bahasa Anda yang menentukannya untuk Anda.
AWS Encryption SDK Mendukung mode padding berikut, tunduk pada kendala masing-masing bahasa. Kami merekomendasikan mode padding [OAEP](https://tools.ietf.org/html/rfc8017#section-7.1), terutama OAEP dengan SHA-256 dan dengan SHA-256 Padding. MGF1 Mode [PKCS1](https://tools.ietf.org/html/rfc8017#section-7.2)padding hanya didukung untuk kompatibilitas mundur.
+ OAEP dengan SHA-1 dan MGF1 dengan SHA-1 Padding
+ OAEP dengan SHA-256 dan dengan SHA-256 Padding MGF1
+ OAEP dengan SHA-384 dan dengan Padding SHA-384 MGF1
+ OAEP dengan SHA-512 dan dengan Padding SHA-512 MGF1
+ PKCS1 v1.5 Bantalan
Contoh Java berikut menunjukkan cara membuat keyring RSA Raw dengan kunci publik dan pribadi dari key pair RSA dan OAEP dengan SHA-256 dan dengan mode padding SHA-256. MGF1 `RSAPrivateKey`Variabel `RSAPublicKey` dan mewakili materi utama yang Anda berikan.
------
#### [ Java ]
```
final CreateRawRsaKeyringInput keyringInput = CreateRawRsaKeyringInput.builder()
.keyName("RSA_2048_06")
.keyNamespace("HSM_01")
.paddingScheme(PaddingScheme.OAEP_SHA256_MGF1)
.publicKey(RSAPublicKey)
.privateKey(RSAPrivateKey)
.build();
final MaterialProviders matProv = MaterialProviders.builder()
.MaterialProvidersConfig(MaterialProvidersConfig.builder().build())
.build();
IKeyring rawRsaKeyring = matProv.CreateRawRsaKeyring(keyringInput);
```
------
#### [ C\$1 / .NET ]
```
var keyNamespace = "HSM_01";
var keyName = "RSA_2048_06";
// Get public and private keys from PEM files
var publicKey = new MemoryStream(System.IO.File.ReadAllBytes("RSAKeyringExamplePublicKey.pem"));
var privateKey = new MemoryStream(System.IO.File.ReadAllBytes("RSAKeyringExamplePrivateKey.pem"));
// Create the keyring input
var keyringInput = new CreateRawRsaKeyringInput
{
KeyNamespace = keyNamespace,
KeyName = keyName,
PaddingScheme = PaddingScheme.OAEP_SHA512_MGF1,
PublicKey = publicKey,
PrivateKey = privateKey
};
// Create the keyring
var matProv = new MaterialProviders(new MaterialProvidersConfig());
var rawRsaKeyring = matProv.CreateRawRsaKeyring(keyringInput);
```
------
#### [ Rust ]
```
let mpl_config = MaterialProvidersConfig::builder().build()?;
let mpl = mpl_client::Client::from_conf(mpl_config)?;
let raw_rsa_keyring = mpl
.create_raw_rsa_keyring()
.key_name("RSA_2048_06")
.key_namespace("HSM_01")
.padding_scheme(PaddingScheme::OaepSha256Mgf1)
.public_key(RSA_public_key)
.private_key(RSA_private_key)
.send()
.await?;
```
------
# Gantungan kunci ECDH mentah
****
| |
| --- |
| 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
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
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
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
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?;
```
------
# Multi-gantungan kunci
****
| |
| --- |
| 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). |
Anda dapat menggabungkan keyrings menjadi multi-keyring. *Multi-keyring* adalah keyring yang terdiri dari satu atau lebih gantungan kunci individu dari jenis yang sama atau berbeda. Efeknya seperti menggunakan beberapa gantungan kunci dalam satu seri. Bila Anda menggunakan multi-keyring untuk mengenkripsi data, salah satu kunci pembungkus di salah satu keyrings nya dapat mendekripsi data tersebut.
*Saat Anda membuat multi-keyring untuk mengenkripsi data, Anda menunjuk salah satu keyring sebagai keyring generator.* Semua gantungan kunci lainnya dikenal sebagai *gantungan kunci anak*. Generator keyring menghasilkan dan mengenkripsi kunci data plaintext. Kemudian, semua kunci pembungkus di semua keyring anak mengenkripsi kunci data teks biasa yang sama. Multi-keyring mengembalikan kunci plaintext dan satu kunci data terenkripsi untuk setiap kunci pembungkus di multi-keyring. Jika keyring generator adalah keyring [KMS, kunci generator di AWS KMS keyring](use-kms-keyring.md) menghasilkan dan mengenkripsi kunci plaintext. Kemudian, semua tambahan AWS KMS keys di AWS KMS keyring, dan semua kunci pembungkus di semua keyring anak di multi-keyring, mengenkripsi kunci plaintext yang sama.
Saat mendekripsi, AWS Database Encryption SDK menggunakan keyrings untuk mencoba mendekripsi salah satu kunci data terenkripsi. Gantungan kunci dipanggil dalam urutan yang ditentukan dalam multi-keyring. Pemrosesan berhenti segera setelah kunci apa pun di keyring apa pun dapat mendekripsi kunci data terenkripsi.
Untuk membuat multi-keyring, pertama-tama buat instance keyrings anak. Dalam contoh ini, kami menggunakan AWS KMS keyring dan keyring Raw AES, tetapi Anda dapat menggabungkan keyrings yang didukung dalam multi-keyring.
------
#### [ Java ]
```
// 1. Create the raw AES keyring.
final MaterialProviders matProv = MaterialProviders.builder()
.MaterialProvidersConfig(MaterialProvidersConfig.builder().build())
.build();
final CreateRawAesKeyringInput createRawAesKeyringInput = CreateRawAesKeyringInput.builder()
.keyName("AES_256_012")
.keyNamespace("HSM_01")
.wrappingKey(AESWrappingKey)
.wrappingAlg(AesWrappingAlg.ALG_AES256_GCM_IV12_TAG16)
.build();
IKeyring rawAesKeyring = matProv.CreateRawAesKeyring(createRawAesKeyringInput);
// 2. Create the AWS KMS keyring.
final CreateAwsKmsMrkMultiKeyringInput createAwsKmsMrkMultiKeyringInput = CreateAwsKmsMrkMultiKeyringInput.builder()
.generator(kmsKeyArn)
.build();
IKeyring awsKmsMrkMultiKeyring = matProv.CreateAwsKmsMrkMultiKeyring(createAwsKmsMrkMultiKeyringInput);
```
------
#### [ C\$1 / .NET ]
```
// 1. Create the raw AES keyring.
var keyNamespace = "HSM_01";
var keyName = "AES_256_012";
var matProv = new MaterialProviders(new MaterialProvidersConfig());
var createRawAesKeyringInput = new CreateRawAesKeyringInput
{
KeyName = "keyName",
KeyNamespace = "myNamespaces",
WrappingKey = AESWrappingKey,
WrappingAlg = AesWrappingAlg.ALG_AES256_GCM_IV12_TAG16
};
var rawAesKeyring = matProv.CreateRawAesKeyring(createRawAesKeyringInput);
// 2. Create the AWS KMS keyring.
// We create a MRK multi keyring, as this interface also supports
// single-region KMS keys,
// and creates the KMS client for us automatically.
var createAwsKmsMrkMultiKeyringInput = new CreateAwsKmsMrkMultiKeyringInput
{
Generator = keyArn
};
var awsKmsMrkMultiKeyring = matProv.CreateAwsKmsMrkMultiKeyring(createAwsKmsMrkMultiKeyringInput);
```
------
#### [ Rust ]
```
// 1. Create the raw AES keyring
let mpl_config = MaterialProvidersConfig::builder().build()?;
let mpl = mpl_client::Client::from_conf(mpl_config)?;
let raw_aes_keyring = mpl
.create_raw_aes_keyring()
.key_name("AES_256_012")
.key_namespace("HSM_01")
.wrapping_key(aes_key_bytes)
.wrapping_alg(AesWrappingAlg::AlgAes256GcmIv12Tag16)
.send()
.await?;
// 2. Create the AWS KMS keyring
let aws_kms_mrk_multi_keyring = mpl
.create_aws_kms_mrk_multi_keyring()
.generator(key_arn)
.send()
.await?;
```
------
Selanjutnya, buat multi-keyring dan tentukan keyring generatornya, jika ada. Dalam contoh ini, kami membuat multi-keyring di mana keyring adalah AWS KMS keyring generator dan keyring AES adalah keyring anak.
------
#### [ Java ]
`CreateMultiKeyringInput`Konstruktor Java memungkinkan Anda menentukan keyring generator dan keyrings anak. `createMultiKeyringInput`Objek yang dihasilkan tidak dapat diubah.
```
final CreateMultiKeyringInput createMultiKeyringInput = CreateMultiKeyringInput.builder()
.generator(awsKmsMrkMultiKeyring)
.childKeyrings(Collections.singletonList(rawAesKeyring))
.build();
IKeyring multiKeyring = matProv.CreateMultiKeyring(createMultiKeyringInput);
```
------
#### [ C\$1 / .NET ]
`CreateMultiKeyringInput`Konstruktor.NET memungkinkan Anda menentukan keyring generator dan keyrings anak. `CreateMultiKeyringInput`Objek yang dihasilkan tidak dapat diubah.
```
var createMultiKeyringInput = new CreateMultiKeyringInput
{
Generator = awsKmsMrkMultiKeyring,
ChildKeyrings = new List { rawAesKeyring }
};
var multiKeyring = matProv.CreateMultiKeyring(createMultiKeyringInput);
```
------
#### [ Rust ]
```
let multi_keyring = mpl
.create_multi_keyring()
.generator(aws_kms_mrk_multi_keyring)
.child_keyrings(vec![raw_aes_keyring.clone()])
.send()
.await?;
```
------
Sekarang, Anda dapat menggunakan multi-keyring untuk mengenkripsi dan mendekripsi data.