Terjemahan disediakan oleh mesin penerjemah. Jika konten terjemahan yang diberikan bertentangan dengan versi bahasa Inggris aslinya, utamakan versi bahasa Inggris.
# AWS Encryption SDK bahasa pemrograman
AWS Encryption SDK Ini tersedia untuk bahasa pemrograman berikut. Semua implementasi bahasa dapat dioperasikan secara interoperable. Anda dapat mengenkripsi dengan satu implementasi bahasa dan mendekripsi dengan yang lain. Interoperabilitas mungkin tunduk pada kendala bahasa. Jika demikian, kendala ini dijelaskan dalam topik tentang implementasi bahasa. Selain itu, saat mengenkripsi dan mendekripsi, Anda harus menggunakan keyring yang kompatibel, atau kunci master dan penyedia kunci master. Lihat perinciannya di [Kompatibilitas keyring](choose-keyring.md#keyring-compatibility).
**Topics**
+ [C](c-language.md)
+ [.NET](dot-net.md)
+ [Go](go.md)
+ [Java](java.md)
+ [JavaScript](javascript.md)
+ [Python](python.md)
+ [Karat](rust.md)
+ [Antarmuka baris perintah](crypto-cli.md)
# AWS Encryption SDK for C
AWS Encryption SDK for C Ini menyediakan pustaka enkripsi sisi klien untuk pengembang yang menulis aplikasi di C. Ini juga berfungsi sebagai dasar untuk implementasi AWS Encryption SDK dalam bahasa pemrograman tingkat tinggi.
Seperti semua implementasi AWS Encryption SDK, AWS Encryption SDK for C menawarkan fitur perlindungan data tingkat lanjut. Ini termasuk [enkripsi amplop](concepts.md#envelope-encryption), data otentikasi tambahan (AAD), dan [rangkaian algoritma](concepts.md#crypto-algorithm) kunci simetris yang aman, diautentikasi, seperti AES-GCM 256-bit dengan derivasi dan penandatanganan kunci.
Semua implementasi khusus bahasa sepenuhnya dapat AWS Encryption SDK dioperasikan. [Misalnya, Anda dapat mengenkripsi data dengan AWS Encryption SDK for C dan mendekripsi dengan [implementasi bahasa yang didukung](programming-languages.md), termasuk CLI Enkripsi AWS .](crypto-cli.md)
AWS Encryption SDK for C Membutuhkan AWS SDK untuk C\$1\$1 untuk berinteraksi dengan AWS Key Management Service (AWS KMS). Anda perlu menggunakannya hanya jika Anda menggunakan [AWS KMS keyring](use-kms-keyring.md) opsional. Namun, AWS Encryption SDK tidak memerlukan AWS KMS atau AWS layanan lainnya.
**Pelajari Lebih Lanjut**
+ Untuk detail tentang pemrograman dengan AWS Encryption SDK for C, lihat [contoh C](c-examples.md), [contoh](https://github.com/aws/aws-encryption-sdk-c/tree/master/examples) di [aws-encryption-sdk-c repositori aktif](https://github.com/aws/aws-encryption-sdk-c/) GitHub, dan dokumentasi [AWS Encryption SDK for C API](https://aws.github.io/aws-encryption-sdk-c/html/).
+ Untuk diskusi tentang cara menggunakan data AWS Encryption SDK for C untuk mengenkripsi sehingga Anda dapat mendekripsi dalam beberapa Wilayah AWS, lihat [Cara mendekripsi ciphertext di beberapa wilayah dengan di C di](https://aws.amazon.com/blogs/security/how-to-decrypt-ciphertexts-multiple-regions-aws-encryption-sdk-in-c/) Blog Keamanan. AWS Encryption SDK AWS
**Topics**
+ [Menginstal](c-language-installation.md)
+ [Menggunakan C SDK](c-language-using.md)
+ [Contoh](c-examples.md)
# Instalasi AWS Encryption SDK for C
Instal versi terbaru dari file AWS Encryption SDK for C.
**catatan**
[Semua versi yang AWS Encryption SDK for C lebih awal dari 2.0.0 sedang dalam fase. end-of-support](https://docs.aws.amazon.com/sdkref/latest/guide/maint-policy.html#version-life-cycle)
Anda dapat memperbarui dengan aman dari versi 2.0. *x* dan yang lebih baru ke versi terbaru AWS Encryption SDK for C tanpa kode atau perubahan data apa pun. Namun, [fitur keamanan baru](about-versions.md#version-2) diperkenalkan di versi 2.0. *x* tidak kompatibel ke belakang. Untuk memperbarui dari versi lebih awal dari 1.7. *x* ke versi 2.0. *x* dan yang lebih baru, Anda harus terlebih dahulu memperbarui ke yang terbaru 1. *x* versi AWS Encryption SDK for C. Lihat perinciannya di [Migrasi Anda AWS Encryption SDK](migration.md).
Anda dapat menemukan petunjuk terperinci untuk menginstal dan membangun [file README](https://github.com/aws/aws-encryption-sdk-c/#readme) dari [aws-encryption-sdk-c](https://github.com/aws/aws-encryption-sdk-c/)repositori. AWS Encryption SDK for C Ini termasuk instruksi untuk membangun di Amazon Linux, Ubuntu, macOS, dan platform Windows.
Sebelum Anda mulai, putuskan apakah Anda ingin menggunakan [AWS KMS gantungan kunci](use-kms-keyring.md) di. AWS Encryption SDK Jika Anda menggunakan AWS KMS keyring, Anda perlu menginstal. AWS SDK untuk C\$1\$1 AWS SDK diperlukan untuk berinteraksi dengan [AWS Key Management Service](https://docs.aws.amazon.com/kms/latest/developerguide/)(AWS KMS). Ketika Anda menggunakan AWS KMS keyrings, AWS Encryption SDK digunakan AWS KMS untuk menghasilkan dan melindungi kunci enkripsi yang melindungi data Anda.
Anda tidak perlu menginstal AWS SDK untuk C\$1\$1 jika Anda menggunakan jenis keyring lain, seperti keyring AES mentah, keyring RSA mentah, atau multi-keyring yang tidak menyertakan keyring. AWS KMS Namun, saat menggunakan tipe keyring mentah, Anda perlu membuat dan melindungi kunci pembungkus mentah Anda sendiri.
Jika Anda mengalami masalah dengan instalasi Anda, [ajukan masalah](https://github.com/aws/aws-encryption-sdk-c/issues) di `aws-encryption-sdk-c` repositori atau gunakan tautan umpan balik apa pun di halaman ini.
# Menggunakan AWS Encryption SDK for C
Topik ini menjelaskan beberapa fitur yang tidak didukung dalam implementasi bahasa pemrograman lainnya. AWS Encryption SDK for C
Contoh di bagian ini menunjukkan cara menggunakan [versi 2.0. ](about-versions.md)*x* dan yang lebih baru AWS Encryption SDK for C. Untuk contoh yang menggunakan versi sebelumnya, temukan rilis Anda di daftar [Rilis](https://github.com/aws/aws-encryption-sdk-c/releases) dari [aws-encryption-sdk-c repositori repositori](https://github.com/aws/aws-encryption-sdk-c/) di. GitHub
Untuk detail tentang pemrograman dengan AWS Encryption SDK for C, lihat [contoh C](c-examples.md), [contoh](https://github.com/aws/aws-encryption-sdk-c/tree/master/examples) di [aws-encryption-sdk-c repositori aktif](https://github.com/aws/aws-encryption-sdk-c/) GitHub, dan dokumentasi [AWS Encryption SDK for C API](https://aws.github.io/aws-encryption-sdk-c/html/).
Lihat juga: [Gantungan kunci](choose-keyring.md)
**Topics**
+ [
## Pola untuk mengenkripsi dan mendekripsi data
](#c-language-using-pattern)
+ [
## Penghitungan referensi
](#c-language-using-release)
## Pola untuk mengenkripsi dan mendekripsi data
Bila Anda menggunakan AWS Encryption SDK for C, Anda mengikuti pola yang mirip dengan ini: membuat [keyring](concepts.md#keyring), membuat [CMM](concepts.md#crypt-materials-manager) yang menggunakan keyring, membuat sesi yang menggunakan CMM (dan keyring), dan kemudian memproses sesi.
1. Memuat string kesalahan.
Panggil `aws_cryptosdk_load_error_strings()` metode dalam kode C atau C \$1\$1 Anda. Ini memuat informasi kesalahan yang sangat berguna untuk debugging.
Anda hanya perlu memanggilnya sekali, seperti dalam `main` metode Anda.
```
/* Load error strings for debugging */
aws_cryptosdk_load_error_strings();
```
2. Buat keyring.
Konfigurasikan [keyring](concepts.md#keyring) Anda dengan tombol pembungkus yang ingin Anda gunakan untuk mengenkripsi kunci data Anda. Contoh ini menggunakan [AWS KMS keyring](use-kms-keyring.md) dengan satu AWS KMS key, tetapi Anda dapat menggunakan semua jenis keyring sebagai gantinya.
Untuk mengidentifikasi AWS KMS key dalam keyring enkripsi di AWS Encryption SDK for C, tentukan [kunci ARN atau [alias](https://docs.aws.amazon.com/kms/latest/developerguide/concepts.html#key-id-alias-arn) ARN](https://docs.aws.amazon.com/kms/latest/developerguide/concepts.html#key-id-key-ARN). Dalam keyring dekripsi, Anda harus menggunakan kunci ARN. Lihat perinciannya di [Mengidentifikasi AWS KMS keys dalam AWS KMS keyring](use-kms-keyring.md#kms-keyring-id).
```
const char * KEY_ARN = "arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab"
struct aws_cryptosdk_keyring *kms_keyring =
Aws::Cryptosdk::KmsKeyring::Builder().Build(KEY_ARN);
```
3. Buat sesi.
Dalam AWS Encryption SDK for C, Anda menggunakan *sesi* untuk mengenkripsi pesan teks biasa tunggal atau mendekripsi pesan ciphertext tunggal, terlepas dari ukurannya. Sesi mempertahankan status pesan selama pemrosesannya.
Konfigurasikan sesi Anda dengan pengalokasi, keyring, dan mode: atau. `AWS_CRYPTOSDK_ENCRYPT` `AWS_CRYPTOSDK_DECRYPT` Jika Anda perlu mengubah mode sesi, gunakan `aws_cryptosdk_session_reset` metode ini.
Saat Anda membuat sesi dengan keyring, AWS Encryption SDK for C secara otomatis membuat manajer materi kriptografi default (CMM) untuk Anda. Anda tidak perlu membuat, memelihara, atau menghancurkan objek ini.
Misalnya, sesi berikut menggunakan pengalokasi dan keyring yang didefinisikan pada langkah 1. Saat Anda mengenkripsi data, modenya adalah`AWS_CRYPTOSDK_ENCRYPT`.
```
struct aws_cryptosdk_session * session = aws_cryptosdk_session_new_from_keyring_2(allocator, AWS_CRYPTOSDK_ENCRYPT, kms_keyring);
```
4. Enkripsi atau dekripsi data.
Untuk memproses data dalam sesi, gunakan `aws_cryptosdk_session_process` metode ini. Jika buffer input cukup besar untuk menampung seluruh plaintext, dan buffer output cukup besar untuk menampung seluruh ciphertext, Anda dapat menelepon. `aws_cryptosdk_session_process_full` Namun, jika Anda perlu menangani data streaming, Anda dapat menelepon `aws_cryptosdk_session_process` dalam satu lingkaran. Sebagai contoh, lihat contoh [file\$1streaming.cpp](https://github.com/aws/aws-encryption-sdk-c/blob/master/examples/file_streaming.cpp). `aws_cryptosdk_session_process_full`Ini diperkenalkan dalam AWS Encryption SDK versi 1.9. *x* dan 2.2. *x*.
Ketika sesi dikonfigurasi untuk mengenkripsi data, bidang plaintext menjelaskan input dan bidang ciphertext menggambarkan output. `plaintext`Bidang menyimpan pesan yang ingin Anda enkripsi dan `ciphertext` bidang mendapatkan [pesan terenkripsi](message-format.md) yang dikembalikan oleh metode enkripsi.
```
/* Encrypting data */
aws_cryptosdk_session_process_full(session,
ciphertext,
ciphertext_buffer_size,
&ciphertext_length,
plaintext,
plaintext_length)
```
Ketika sesi dikonfigurasi untuk mendekripsi data, bidang ciphertext menjelaskan input dan bidang plaintext menggambarkan output. `ciphertext`Bidang menyimpan [pesan terenkripsi](message-format.md) yang dikembalikan oleh metode enkripsi, dan `plaintext` bidang mendapatkan pesan teks biasa yang dikembalikan oleh metode dekripsi.
Untuk mendekripsi data, panggil metode. `aws_cryptosdk_session_process_full`
```
/* Decrypting data */
aws_cryptosdk_session_process_full(session,
plaintext,
plaintext_buffer_size,
&plaintext_length,
ciphertext,
ciphertext_length)
```
## Penghitungan referensi
Untuk mencegah kebocoran memori, pastikan untuk melepaskan referensi Anda ke semua objek yang Anda buat saat Anda selesai menggunakannya. Jika tidak, Anda akan berakhir dengan kebocoran memori. SDK menyediakan metode untuk mempermudah tugas ini.
Setiap kali Anda membuat objek induk dengan salah satu objek anak berikut, objek induk mendapatkan dan mempertahankan referensi ke objek anak, sebagai berikut:
+ Sebuah [keyring](concepts.md#keyring), seperti membuat sesi dengan keyring
+ [Manajer materi kriptografi](concepts.md#crypt-materials-manager) default (CMM), seperti membuat sesi atau CMM khusus dengan CMM default
+ [Cache kunci data](data-key-caching.md), seperti membuat CMM caching dengan keyring dan cache
Kecuali Anda memerlukan referensi independen ke objek anak, Anda dapat melepaskan referensi Anda ke objek anak segera setelah Anda membuat objek induk. Referensi yang tersisa untuk objek anak dilepaskan ketika objek induk dihancurkan. Pola ini memastikan bahwa Anda mempertahankan referensi ke setiap objek hanya selama Anda membutuhkannya, dan Anda tidak membocorkan memori karena referensi yang belum dirilis.
Anda hanya bertanggung jawab untuk merilis referensi ke objek anak yang Anda buat secara eksplisit. Anda tidak bertanggung jawab untuk mengelola referensi ke objek apa pun yang dibuat SDK untuk Anda. Jika SDK membuat objek, seperti CMM default yang ditambahkan `aws_cryptosdk_caching_cmm_new_from_keyring` metode ke sesi, SDK mengelola pembuatan dan penghancuran objek dan referensinya.
Dalam contoh berikut, ketika Anda membuat sesi dengan [keyring](concepts.md#keyring), sesi mendapatkan referensi ke keyring, dan mempertahankan referensi itu sampai sesi dihancurkan. Jika Anda tidak perlu mempertahankan referensi tambahan ke keyring, Anda dapat menggunakan `aws_cryptosdk_keyring_release` metode untuk melepaskan objek keyring segera setelah sesi dibuat. Metode ini mengurangi jumlah referensi untuk keyring. Referensi sesi ke keyring dilepaskan saat Anda menelepon `aws_cryptosdk_session_destroy` untuk menghancurkan sesi.
```
// The session gets a reference to the keyring.
struct aws_cryptosdk_session *session =
aws_cryptosdk_session_new_from_keyring_2(alloc, AWS_CRYPTOSDK_ENCRYPT, keyring);
// After you create a session with a keyring, release the reference to the keyring object.
aws_cryptosdk_keyring_release(keyring);
```
Untuk tugas yang lebih kompleks, seperti menggunakan kembali keyring untuk beberapa sesi atau menentukan rangkaian algoritme dalam CMM, Anda mungkin perlu mempertahankan referensi independen ke objek. Jika demikian, jangan segera panggil metode rilis. Sebagai gantinya, lepaskan referensi Anda saat Anda tidak lagi menggunakan objek, selain menghancurkan sesi.
Teknik penghitungan referensi ini juga berfungsi ketika Anda menggunakan alternatif CMMs, seperti CMM caching untuk caching [kunci data](data-key-caching.md). Saat Anda membuat CMM caching dari cache dan keyring, CMM caching mendapatkan referensi ke kedua objek. Kecuali Anda membutuhkannya untuk tugas lain, Anda dapat melepaskan referensi independen Anda ke cache dan keyring segera setelah CMM caching dibuat. Kemudian, ketika Anda membuat sesi dengan CMM caching, Anda dapat melepaskan referensi Anda ke CMM caching.
Perhatikan bahwa Anda hanya bertanggung jawab untuk merilis referensi ke objek yang Anda buat secara eksplisit. Objek yang dibuat metode untuk Anda, seperti CMM default yang mendasari CMM caching, dikelola oleh metode.
```
/ Create the caching CMM from a cache and a keyring.
struct aws_cryptosdk_cmm *caching_cmm = aws_cryptosdk_caching_cmm_new_from_keyring(allocator, cache, kms_keyring, NULL, 60, AWS_TIMESTAMP_SECS);
// Release your references to the cache and the keyring.
aws_cryptosdk_materials_cache_release(cache);
aws_cryptosdk_keyring_release(kms_keyring);
// Create a session with the caching CMM.
struct aws_cryptosdk_session *session = aws_cryptosdk_session_new_from_cmm_2(allocator, AWS_CRYPTOSDK_ENCRYPT, caching_cmm);
// Release your references to the caching CMM.
aws_cryptosdk_cmm_release(caching_cmm);
// ...
aws_cryptosdk_session_destroy(session);
```
# AWS Encryption SDK for C contoh
Contoh berikut menunjukkan cara menggunakan untuk mengenkripsi dan AWS Encryption SDK for C mendekripsi data.
Contoh di bagian ini menunjukkan cara menggunakan versi 2.0. *x* dan kemudian AWS Encryption SDK for C. Untuk contoh yang menggunakan versi sebelumnya, temukan rilis Anda di daftar [Rilis](https://github.com/aws/aws-encryption-sdk-c/releases) dari [aws-encryption-sdk-c repositori repositori](https://github.com/aws/aws-encryption-sdk-c/) di. GitHub
Ketika Anda menginstal dan membangun AWS Encryption SDK for C, kode sumber untuk ini dan contoh lainnya disertakan dalam `examples` subdirektori, dan mereka dikompilasi dan dibangun ke dalam `build` direktori. Anda juga dapat menemukannya di [contoh](https://github.com/aws/aws-encryption-sdk-c/tree/master/examples) subdirektori [aws-encryption-sdk-c](https://github.com/aws/aws-encryption-sdk-c/)repositori di. GitHub
**Topics**
+ [
## Mengenkripsi dan mendekripsi string
](#c-example-strings)
## Mengenkripsi dan mendekripsi string
Contoh berikut menunjukkan kepada Anda bagaimana menggunakan AWS Encryption SDK for C untuk mengenkripsi dan mendekripsi string.
Contoh ini menampilkan [AWS KMS keyring](use-kms-keyring.md), jenis keyring yang menggunakan AWS KMS key in [AWS Key Management Service (AWS KMS)](https://docs.aws.amazon.com/kms/latest/developerguide/) untuk menghasilkan dan mengenkripsi kunci data. Contohnya termasuk kode yang ditulis dalam C \$1\$1. Yang AWS Encryption SDK for C mengharuskan AWS SDK untuk C\$1\$1 untuk memanggil AWS KMS saat menggunakan AWS KMS keyrings. Jika Anda menggunakan keyring yang tidak berinteraksi AWS KMS, seperti keyring AES mentah, keyring RSA mentah, atau multi-keyring yang tidak menyertakan keyring, tidak diperlukan. AWS KMS AWS SDK untuk C\$1\$1
Untuk bantuan membuat AWS KMS key, lihat [Membuat Kunci](https://docs.aws.amazon.com/kms/latest/developerguide/create-keys.html) di *Panduan AWS Key Management Service Pengembang*. Untuk bantuan mengidentifikasi AWS KMS keys dalam AWS KMS gantungan kunci, lihat[Mengidentifikasi AWS KMS keys dalam AWS KMS keyring](use-kms-keyring.md#kms-keyring-id).
**Lihat contoh kode lengkap**: [string.cpp](https://github.com/aws/aws-encryption-sdk-c/blob/master/examples/string.cpp)
**Topics**
+ [
### Enkripsi string
](#c-example-string-encrypt)
+ [
### Dekripsi string
](#c-example-string-decrypt)
### Enkripsi string
Bagian pertama dari contoh ini menggunakan AWS KMS keyring dengan satu AWS KMS key untuk mengenkripsi string plaintext.
Langkah 1. Memuat string kesalahan.
Panggil `aws_cryptosdk_load_error_strings()` metode dalam kode C atau C \$1\$1 Anda. Ini memuat informasi kesalahan yang sangat berguna untuk debugging.
Anda hanya perlu memanggilnya sekali, seperti dalam `main` metode Anda.
```
/* Load error strings for debugging */
aws_cryptosdk_load_error_strings();
```
Langkah 2: Bangun keyring.
Buat AWS KMS keyring untuk enkripsi. Keyring dalam contoh ini dikonfigurasi dengan satu AWS KMS key, tetapi Anda dapat mengonfigurasi AWS KMS keyring dengan beberapa AWS KMS keys, termasuk AWS KMS keys di akun yang berbeda Wilayah AWS dan berbeda.
Untuk mengidentifikasi AWS KMS key dalam keyring enkripsi di AWS Encryption SDK for C, tentukan [kunci ARN atau [alias](https://docs.aws.amazon.com/kms/latest/developerguide/concepts.html#key-id-alias-arn) ARN](https://docs.aws.amazon.com/kms/latest/developerguide/concepts.html#key-id-key-ARN). Dalam keyring dekripsi, Anda harus menggunakan kunci ARN. Lihat perinciannya di [Mengidentifikasi AWS KMS keys dalam AWS KMS keyring](use-kms-keyring.md#kms-keyring-id).
[Mengidentifikasi AWS KMS keys dalam AWS KMS keyring](use-kms-keyring.md#kms-keyring-id)
Ketika Anda membuat keyring dengan beberapa AWS KMS keys, Anda menentukan yang AWS KMS key digunakan untuk menghasilkan dan mengenkripsi kunci data plaintext, dan array opsional tambahan yang mengenkripsi kunci data plaintext AWS KMS keys yang sama. Dalam hal ini, Anda hanya menentukan generator AWS KMS key.
Sebelum menjalankan kode ini, ganti contoh kunci ARN dengan yang valid.
```
const char * key_arn = "arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab";
struct aws_cryptosdk_keyring *kms_keyring =
Aws::Cryptosdk::KmsKeyring::Builder().Build(key_arn);
```
Langkah 3: Buat sesi.
Buat sesi menggunakan pengalokasi, enumerator mode, dan keyring.
Setiap sesi membutuhkan mode: baik `AWS_CRYPTOSDK_ENCRYPT` untuk mengenkripsi atau `AWS_CRYPTOSDK_DECRYPT` mendekripsi. Untuk mengubah mode sesi yang ada, gunakan `aws_cryptosdk_session_reset` metode ini.
Setelah membuat sesi dengan keyring, Anda dapat melepaskan referensi ke keyring menggunakan metode yang disediakan SDK. Sesi mempertahankan referensi ke objek keyring selama masa pakainya. Referensi ke keyring dan objek sesi dilepaskan saat Anda menghancurkan sesi. Teknik [penghitungan referensi](c-language-using.md#c-language-using-release) ini membantu mencegah kebocoran memori dan mencegah objek dilepaskan saat sedang digunakan.
```
struct aws_cryptosdk_session *session =
aws_cryptosdk_session_new_from_keyring_2(alloc, AWS_CRYPTOSDK_ENCRYPT, kms_keyring);
/* When you add the keyring to the session, release the keyring object */
aws_cryptosdk_keyring_release(kms_keyring);
```
Langkah 4: Atur konteks enkripsi.
[Konteks enkripsi adalah data](concepts.md#encryption-context) otentikasi tambahan yang sewenang-wenang dan tidak rahasia. Ketika Anda menyediakan konteks enkripsi pada enkripsi, AWS Encryption SDK kriptografis mengikat konteks enkripsi ke ciphertext sehingga konteks enkripsi yang sama diperlukan untuk mendekripsi data. Menggunakan konteks enkripsi adalah opsional, tetapi kami merekomendasikannya sebagai praktik terbaik.
Pertama, buat tabel hash yang menyertakan string konteks enkripsi.
```
/* Allocate a hash table for the encryption context */
int set_up_enc_ctx(struct aws_allocator *alloc, struct aws_hash_table *my_enc_ctx)
// Create encryption context strings
AWS_STATIC_STRING_FROM_LITERAL(enc_ctx_key1, "Example");
AWS_STATIC_STRING_FROM_LITERAL(enc_ctx_value1, "String");
AWS_STATIC_STRING_FROM_LITERAL(enc_ctx_key2, "Company");
AWS_STATIC_STRING_FROM_LITERAL(enc_ctx_value2, "MyCryptoCorp");
// Put the key-value pairs in the hash table
aws_hash_table_put(my_enc_ctx, enc_ctx_key1, (void *)enc_ctx_value1, &was_created)
aws_hash_table_put(my_enc_ctx, enc_ctx_key2, (void *)enc_ctx_value2, &was_created)
```
Dapatkan pointer yang bisa berubah ke konteks enkripsi dalam sesi. Kemudian, gunakan `aws_cryptosdk_enc_ctx_clone` fungsi untuk menyalin konteks enkripsi ke dalam sesi. Simpan salinan `my_enc_ctx` sehingga Anda dapat memvalidasi nilai setelah mendekripsi data.
Konteks enkripsi adalah bagian dari sesi, bukan parameter yang diteruskan ke fungsi proses sesi. Ini menjamin bahwa konteks enkripsi yang sama digunakan untuk setiap segmen pesan, bahkan jika fungsi proses sesi dipanggil beberapa kali untuk mengenkripsi seluruh pesan.
```
struct aws_hash_table *session_enc_ctx = aws_cryptosdk_session_get_enc_ctx_ptr_mut(session);
aws_cryptosdk_enc_ctx_clone(alloc, session_enc_ctx, my_enc_ctx)
```
Langkah 5: Enkripsi string.
Untuk mengenkripsi string plaintext, gunakan `aws_cryptosdk_session_process_full` metode dengan sesi dalam mode enkripsi. Metode ini, diperkenalkan dalam AWS Encryption SDK versi 1.9. *x* dan 2.2. *x*, dirancang untuk enkripsi dan dekripsi non-streaming. Untuk menangani streaming data, panggil `aws_cryptosdk_session_process` dalam satu lingkaran.
Saat mengenkripsi, bidang plaintext adalah bidang input; bidang ciphertext adalah bidang keluaran. Saat pemrosesan selesai, `ciphertext_output` bidang berisi [pesan terenkripsi](concepts.md#message), termasuk ciphertext aktual, kunci data terenkripsi, dan konteks enkripsi. Anda dapat mendekripsi pesan terenkripsi ini dengan menggunakan AWS Encryption SDK untuk setiap bahasa pemrograman yang didukung.
```
/* Gets the length of the plaintext that the session processed */
size_t ciphertext_len_output;
if (AWS_OP_SUCCESS != aws_cryptosdk_session_process_full(session,
ciphertext_output,
ciphertext_buf_sz_output,
&ciphertext_len_output,
plaintext_input,
plaintext_len_input)) {
aws_cryptosdk_session_destroy(session);
return 8;
}
```
Langkah 6: Bersihkan sesi.
Langkah terakhir menghancurkan sesi termasuk referensi ke CMM dan keyring.
Jika Anda lebih suka, alih-alih menghancurkan sesi, Anda dapat menggunakan kembali sesi dengan keyring dan CMM yang sama untuk mendekripsi string, atau untuk mengenkripsi atau mendekripsi pesan lain. Untuk menggunakan sesi untuk mendekripsi, gunakan `aws_cryptosdk_session_reset` metode untuk mengubah mode ke. `AWS_CRYPTOSDK_DECRYPT`
### Dekripsi string
Bagian kedua dari contoh ini mendekripsi pesan terenkripsi yang berisi ciphertext dari string asli.
Langkah 1: Muat string kesalahan.
Panggil `aws_cryptosdk_load_error_strings()` metode dalam kode C atau C \$1\$1 Anda. Ini memuat informasi kesalahan yang sangat berguna untuk debugging.
Anda hanya perlu memanggilnya sekali, seperti dalam `main` metode Anda.
```
/* Load error strings for debugging */
aws_cryptosdk_load_error_strings();
```
Langkah 2: Bangun keyring.
Saat Anda mendekripsi data AWS KMS, Anda meneruskan [pesan terenkripsi yang dikembalikan oleh](concepts.md#message) API enkripsi. [Decrypt API](https://docs.aws.amazon.com/kms/latest/APIReference/API_Decrypt.html) tidak mengambil AWS KMS key sebagai input. Sebaliknya, AWS KMS menggunakan yang sama AWS KMS key untuk mendekripsi ciphertext yang digunakan untuk mengenkripsi itu. Namun, AWS Encryption SDK memungkinkan Anda menentukan AWS KMS keyring dengan enkripsi dan AWS KMS keys dekripsi.
Saat mendekripsi, Anda dapat mengonfigurasi keyring hanya dengan AWS KMS keys yang ingin Anda gunakan untuk mendekripsi pesan terenkripsi. Misalnya, Anda mungkin ingin membuat keyring hanya dengan AWS KMS key yang digunakan oleh peran tertentu dalam organisasi Anda. Tidak AWS Encryption SDK akan pernah menggunakan AWS KMS key kecuali muncul di keyring dekripsi. Jika SDK tidak dapat mendekripsi kunci data terenkripsi dengan menggunakan keyring AWS KMS keys dalam yang Anda berikan, baik karena tidak ada AWS KMS keys dalam keyring yang digunakan untuk mengenkripsi salah satu kunci data, atau karena pemanggil tidak memiliki izin untuk menggunakan AWS KMS keys dalam keyring untuk mendekripsi, panggilan dekripsi gagal.
[Ketika Anda menentukan AWS KMS key untuk keyring dekripsi, Anda harus menggunakan kunci ARN.](https://docs.aws.amazon.com/kms/latest/developerguide/concepts.html#key-id-key-ARN) [Alias](https://docs.aws.amazon.com/kms/latest/developerguide/concepts.html#key-id-alias-arn) hanya ARNs diizinkan dalam gantungan kunci enkripsi. Untuk bantuan mengidentifikasi AWS KMS keys dalam AWS KMS gantungan kunci, lihat[Mengidentifikasi AWS KMS keys dalam AWS KMS keyring](use-kms-keyring.md#kms-keyring-id).
Dalam contoh ini, kami menentukan keyring yang dikonfigurasi dengan yang sama AWS KMS key digunakan untuk mengenkripsi string. Sebelum menjalankan kode ini, ganti contoh kunci ARN dengan yang valid.
```
const char * key_arn = "arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab"
struct aws_cryptosdk_keyring *kms_keyring =
Aws::Cryptosdk::KmsKeyring::Builder().Build(key_arn);
```
Langkah 3: Buat sesi.
Buat sesi menggunakan pengalokasi dan keyring. Untuk mengkonfigurasi sesi untuk dekripsi, konfigurasikan sesi dengan mode. `AWS_CRYPTOSDK_DECRYPT`
Setelah membuat sesi dengan keyring, Anda dapat melepaskan referensi ke keyring menggunakan metode yang disediakan SDK. Sesi mempertahankan referensi ke objek keyring selama masa pakainya, dan sesi dan keyring dilepaskan saat Anda menghancurkan sesi. Teknik penghitungan referensi ini membantu mencegah kebocoran memori dan mencegah objek dilepaskan saat sedang digunakan.
```
struct aws_cryptosdk_session *session =
aws_cryptosdk_session_new_from_keyring_2(alloc, AWS_CRYPTOSDK_DECRYPT, kms_keyring);
/* When you add the keyring to the session, release the keyring object */
aws_cryptosdk_keyring_release(kms_keyring);
```
Langkah 4: Dekripsi string.
Untuk mendekripsi string, gunakan `aws_cryptosdk_session_process_full` metode dengan sesi yang dikonfigurasi untuk dekripsi. Metode ini, diperkenalkan dalam AWS Encryption SDK versi 1.9. *x* dan 2.2. *x*, dirancang untuk enkripsi dan dekripsi non-streaming. Untuk menangani streaming data, panggil `aws_cryptosdk_session_process` dalam satu lingkaran.
Saat mendekripsi, bidang ciphertext adalah bidang input dan bidang plaintext adalah bidang keluaran. `ciphertext_input`Bidang menyimpan [pesan terenkripsi yang dikembalikan](message-format.md) oleh metode enkripsi. Saat pemrosesan selesai, `plaintext_output` bidang berisi string plaintext (didekripsi).
```
size_t plaintext_len_output;
if (AWS_OP_SUCCESS != aws_cryptosdk_session_process_full(session,
plaintext_output,
plaintext_buf_sz_output,
&plaintext_len_output,
ciphertext_input,
ciphertext_len_input)) {
aws_cryptosdk_session_destroy(session);
return 13;
}
```
Langkah 5: Verifikasi konteks enkripsi.
Pastikan bahwa konteks enkripsi yang sebenarnya — yang digunakan untuk mendekripsi pesan — berisi konteks enkripsi yang Anda berikan saat mengenkripsi pesan. Konteks enkripsi yang sebenarnya mungkin mencakup pasangan tambahan, karena [pengelola materi kriptografi](concepts.md#crypt-materials-manager) (CMM) dapat menambahkan pasangan ke konteks enkripsi yang disediakan sebelum mengenkripsi pesan.
Di dalam AWS Encryption SDK for C, Anda tidak diharuskan untuk menyediakan konteks enkripsi saat mendekripsi karena konteks enkripsi disertakan dalam pesan terenkripsi yang dikembalikan SDK. Namun, sebelum mengembalikan pesan teks biasa, fungsi dekripsi Anda harus memverifikasi bahwa semua pasangan dalam konteks enkripsi yang disediakan muncul dalam konteks enkripsi yang digunakan untuk mendekripsi pesan.
Pertama, dapatkan pointer read-only ke tabel hash di sesi. Tabel hash ini berisi konteks enkripsi yang digunakan untuk mendekripsi pesan.
```
const struct aws_hash_table *session_enc_ctx = aws_cryptosdk_session_get_enc_ctx_ptr(session);
```
Kemudian, loop melalui konteks enkripsi dalam tabel `my_enc_ctx` hash yang Anda salin saat mengenkripsi. Verifikasi bahwa setiap pasangan dalam tabel `my_enc_ctx` hash yang digunakan untuk mengenkripsi muncul di tabel `session_enc_ctx` hash yang digunakan untuk mendekripsi. Jika ada kunci yang hilang, atau kunci itu memiliki nilai yang berbeda, hentikan pemrosesan dan tulis pesan kesalahan.
```
for (struct aws_hash_iter iter = aws_hash_iter_begin(my_enc_ctx); !aws_hash_iter_done(&iter);
aws_hash_iter_next(&iter)) {
struct aws_hash_element *session_enc_ctx_kv_pair;
aws_hash_table_find(session_enc_ctx, iter.element.key, &session_enc_ctx_kv_pair)
if (!session_enc_ctx_kv_pair ||
!aws_string_eq(
(struct aws_string *)iter.element.value, (struct aws_string *)session_enc_ctx_kv_pair->value)) {
fprintf(stderr, "Wrong encryption context!\n");
abort();
}
}
```
Langkah 6: Bersihkan sesi.
Setelah Anda memverifikasi konteks enkripsi, Anda dapat menghancurkan sesi, atau menggunakannya kembali. Jika Anda perlu mengkonfigurasi ulang sesi, gunakan `aws_cryptosdk_session_reset` metode ini.
```
aws_cryptosdk_session_destroy(session);
```
# AWS Encryption SDK untuk .NET
The AWS Encryption SDK for .NET adalah pustaka enkripsi sisi klien untuk pengembang yang menulis aplikasi dalam C \$1 dan bahasa pemrograman.NET lainnya. Hal ini didukung di Windows, macOS, dan Linux.
**catatan**
Versi 4.0.0 AWS Encryption SDK untuk .NET menyimpang dari Spesifikasi Pesan. AWS Encryption SDK Akibatnya, pesan yang dienkripsi oleh versi 4.0.0 hanya dapat didekripsi oleh versi 4.0.0 atau yang lebih baru untuk .NET. AWS Encryption SDK Mereka tidak dapat didekripsi oleh implementasi bahasa pemrograman lainnya.
Versi 4.0.1 AWS Encryption SDK untuk .NET menulis pesan sesuai dengan Spesifikasi AWS Encryption SDK Pesan, dan interoperable dengan implementasi bahasa pemrograman lainnya. Secara default, versi 4.0.1 dapat membaca pesan yang dienkripsi oleh versi 4.0.0. Namun, jika Anda tidak ingin mendekripsi pesan yang dienkripsi oleh versi 4.0.0, Anda dapat menentukan [https://github.com/aws/aws-encryption-sdk/tree/mainline/AwsEncryptionSDK/runtimes/net/Examples/NetV4_0_0Example.cs](https://github.com/aws/aws-encryption-sdk/tree/mainline/AwsEncryptionSDK/runtimes/net/Examples/NetV4_0_0Example.cs)properti untuk mencegah klien membaca pesan-pesan ini. Untuk informasi lebih lanjut, lihat [catatan rilis v4.0.1](https://github.com/aws/aws-encryption-sdk/releases/tag/v4.0.1) di aws-encryption-sdk repositori di. GitHub
AWS Encryption SDK Untuk .NET berbeda dari beberapa implementasi bahasa pemrograman lainnya dengan AWS Encryption SDK cara berikut:
+ Tidak ada dukungan untuk [caching kunci data](data-key-caching.md)
**catatan**
Versi 4. *x* dari AWS Encryption SDK untuk .NET mendukung [keyring AWS KMS Hierarchical, solusi](use-hierarchical-keyring.md) caching bahan kriptografi alternatif.
+ Tidak ada dukungan untuk streaming data
+ [Tidak ada pencatatan atau jejak tumpukan](#dot-net-debugging) dari AWS Encryption SDK untuk .NET
+ [Membutuhkan AWS SDK untuk .NET](#dot-net-install)
The AWS Encryption SDK for .NET mencakup semua fitur keamanan yang diperkenalkan dalam versi 2.0. *x* dan yang lebih baru dari implementasi bahasa lain dari. AWS Encryption SDK Namun, jika Anda menggunakan AWS Encryption SDK untuk.NET untuk mendekripsi data yang dienkripsi oleh pra-2.0. *x* versi implementasi bahasa lain dari AWS Encryption SDK, Anda mungkin perlu menyesuaikan [kebijakan komitmen](concepts.md#commitment-policy) Anda. Lihat perinciannya di [Cara menetapkan kebijakan komitmen Anda](migrate-commitment-policy.md#migrate-commitment-step1).
The AWS Encryption SDK for .NET adalah produk dari AWS Encryption SDK in [Dafny](https://github.com/dafny-lang/dafny/blob/master/README.md), bahasa verifikasi formal di mana Anda menulis spesifikasi, kode untuk mengimplementasikannya, dan bukti untuk mengujinya. Hasilnya adalah perpustakaan yang mengimplementasikan fitur-fitur AWS Encryption SDK dalam kerangka kerja yang menjamin kebenaran fungsional.
**Pelajari Lebih Lanjut**
+ Untuk contoh yang menunjukkan cara mengonfigurasi opsi di AWS Encryption SDK, seperti menentukan rangkaian algoritme alternatif, membatasi kunci data terenkripsi, dan menggunakan kunci AWS KMS Multi-region, lihat. [Mengkonfigurasi AWS Encryption SDK](configure.md)
+ Untuk detail tentang pemrograman dengan AWS Encryption SDK for .NET, lihat [https://github.com/aws/aws-encryption-sdk/tree/mainline/AwsEncryptionSDK/runtimes/net/](https://github.com/aws/aws-encryption-sdk/tree/mainline/AwsEncryptionSDK/runtimes/net/)direktori aws-encryption-sdk repositori di. GitHub
**Topics**
+ [Instal dan bangun](#dot-net-install)
+ [Debugging](#dot-net-debugging)
+ [Contoh](dot-net-examples.md)
## Instalasi AWS Encryption SDK untuk .NET
AWS Encryption SDK Untuk .NET tersedia sebagai [https://www.nuget.org/packages/AWS.Cryptography.EncryptionSDK](https://www.nuget.org/packages/AWS.Cryptography.EncryptionSDK)paket di NuGet. Untuk detail tentang menginstal dan membangun AWS Encryption SDK untuk .NET, lihat file [README.md](https://github.com/aws/aws-encryption-sdk/tree/mainline/AwsEncryptionSDK/runtimes/net/#readme) di repositori. `aws-encryption-sdk-net`
**Versi 3.x**
Versi 3. *x* dari AWS Encryption SDK untuk .NET mendukung .NET Framework 4.5.2 - 4.8 hanya pada Windows. Ini mendukung .NET Core 3.0\$1 dan .NET 5.0 dan kemudian pada semua sistem operasi yang didukung.
**Versi 4.x**
Versi 4. *x* dari AWS Encryption SDK untuk .NET mendukung .NET 6.0 dan .NET Framework net48 dan yang lebih baru. Versi 4. *x* membutuhkan AWS SDK untuk.NET v3.
**Versi 5.x**
Versi 5. *x* dari AWS Encryption SDK untuk .NET mendukung .NET 6.0 dan .NET Framework net48 dan yang lebih baru. Versi 5. *x* membutuhkan versi 2. *x* dari Material Providers Library (MPL) dan AWS SDK for .NET v4.
AWS Encryption SDK Untuk .NET membutuhkan SDK untuk .NET bahkan jika Anda tidak menggunakan kunci AWS Key Management Service (AWS KMS). Itu diinstal dengan NuGet paket. Namun, kecuali Anda menggunakan AWS KMS kunci, AWS Encryption SDK untuk .NET tidak memerlukan Akun AWS, AWS kredensi, atau interaksi dengan layanan apa pun AWS . Untuk bantuan menyiapkan AWS akun jika Anda membutuhkannya, lihat[Menggunakan AWS Encryption SDK dengan AWS KMS](getting-started.md).
## Debugging AWS Encryption SDK untuk .NET
The AWS Encryption SDK for .NET tidak menghasilkan log apa pun. Pengecualian di AWS Encryption SDK for .NET menghasilkan pesan pengecualian, tetapi tidak ada jejak tumpukan.
Untuk membantu Anda men-debug, pastikan untuk mengaktifkan login. SDK untuk .NET Log dan pesan kesalahan dari SDK untuk .NET dapat membantu Anda membedakan kesalahan yang timbul SDK untuk .NET dari yang ada di AWS Encryption SDK untuk .NET. Untuk bantuan terkait SDK untuk .NET logging, lihat [AWSLogging](https://docs.aws.amazon.com/sdk-for-net/v4/developer-guide/net-dg-config-other.html#config-setting-awslogging)di *Panduan AWS SDK untuk .NET Pengembang*. (Untuk melihat topiknya, perluas bagian **konten Open to view .NET Framework**.)
# AWS Encryption SDK untuk contoh.NET
Contoh berikut menunjukkan pola pengkodean dasar yang Anda gunakan saat pemrograman dengan AWS Encryption SDK for .NET. Secara khusus, Anda membuat instance perpustakaan AWS Encryption SDK dan penyedia materi. Kemudian, sebelum memanggil setiap metode, Anda membuat instance objek yang mendefinisikan input untuk metode tersebut. Ini sangat mirip dengan pola pengkodean yang Anda gunakan di SDK untuk .NET.
Untuk contoh yang menunjukkan cara mengonfigurasi opsi di AWS Encryption SDK, seperti menentukan rangkaian algoritme alternatif, membatasi kunci data terenkripsi, dan menggunakan kunci AWS KMS Multi-region, lihat. [Mengkonfigurasi AWS Encryption SDK](configure.md)
Untuk lebih banyak contoh pemrograman dengan AWS Encryption SDK untuk .NET, lihat [contoh](https://github.com/aws/aws-encryption-sdk/tree/mainline/AwsEncryptionSDK/runtimes/net/Examples) di `aws-encryption-sdk-net` direktori `aws-encryption-sdk` repositori pada. GitHub
## Mengenkripsi data di untuk .NET AWS Encryption SDK
Contoh ini menunjukkan pola dasar untuk mengenkripsi data. Ini mengenkripsi file kecil dengan kunci data yang dilindungi oleh satu kunci AWS KMS pembungkus.
Langkah 1: Buat instance AWS Encryption SDK dan perpustakaan penyedia materi.
Mulailah dengan membuat instance perpustakaan penyedia AWS Encryption SDK dan materi. Anda akan menggunakan metode dalam AWS Encryption SDK untuk mengenkripsi dan mendekripsi data. Anda akan menggunakan metode di pustaka penyedia materi untuk membuat keyrings yang menentukan kunci mana yang melindungi data Anda.
Cara Anda membuat instance AWS Encryption SDK dan pustaka penyedia materi berbeda antara versi 3. *x* dan 4. *x* dari AWS Encryption SDK untuk .NET. Semua langkah berikut adalah sama untuk kedua versi 3. *x* dan 4. *x* dari AWS Encryption SDK untuk .NET.
```
// Instantiate the AWS Encryption SDK and material providers
var encryptionSdk = AwsEncryptionSdkFactory.CreateDefaultAwsEncryptionSdk();
var materialProviders =
AwsCryptographicMaterialProvidersFactory.CreateDefaultAwsCryptographicMaterialProviders();
```
```
// Instantiate the AWS Encryption SDK and material providers
var esdk = new ESDK(new AwsEncryptionSdkConfig());
var mpl = new MaterialProviders(new MaterialProvidersConfig());
```
Langkah 2: Buat objek input untuk keyring.
Setiap metode yang membuat keyring memiliki kelas objek input yang sesuai. Misalnya, untuk membuat objek masukan untuk `CreateAwsKmsKeyring()` metode, buat instance `CreateAwsKmsKeyringInput` kelas.
Meskipun input untuk keyring ini tidak menentukan [kunci generator, kunci](use-kms-keyring.md#kms-keyring-encrypt) KMS tunggal yang ditentukan oleh `KmsKeyId` parameter adalah kunci generator. Ini menghasilkan dan mengenkripsi kunci data yang mengenkripsi data.
Objek masukan ini membutuhkan AWS KMS klien untuk kunci KMS. Wilayah AWS Untuk membuat AWS KMS klien, buat instance `AmazonKeyManagementServiceClient` kelas di. SDK untuk .NET Memanggil `AmazonKeyManagementServiceClient()` konstruktor tanpa parameter membuat klien dengan nilai default.
Dalam AWS KMS keyring yang digunakan untuk mengenkripsi dengan AWS Encryption SDK for .NET, Anda dapat [mengidentifikasi kunci KMS dengan menggunakan ID kunci, kunci](use-kms-keyring.md#kms-keyring-id) ARN, nama alias, atau alias ARN. Dalam AWS KMS keyring yang digunakan untuk mendekripsi, Anda harus menggunakan ARN kunci untuk mengidentifikasi setiap kunci KMS. Jika Anda berencana untuk menggunakan kembali keyring enkripsi Anda untuk mendekripsi, gunakan pengenal ARN kunci untuk semua kunci KMS.
```
string keyArn = "arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab";
// Instantiate the keyring input object
var kmsKeyringInput = new CreateAwsKmsKeyringInput
{
KmsClient = new AmazonKeyManagementServiceClient(),
KmsKeyId = keyArn
};
```
Langkah 3: Buat keyring.
Untuk membuat keyring, panggil metode keyring dengan objek input keyring. Contoh ini menggunakan `CreateAwsKmsKeyring()` metode, yang hanya membutuhkan satu kunci KMS.
```
var keyring = materialProviders.CreateAwsKmsKeyring(kmsKeyringInput);
```
Langkah 4: Tentukan konteks enkripsi.
[Konteks enkripsi](concepts.md#encryption-context) adalah elemen opsional, tetapi sangat direkomendasikan dari operasi kriptografi dalam. AWS Encryption SDK Anda dapat menentukan satu atau lebih pasangan nilai kunci non-rahasia.
Dengan versi 4. *x* dari AWS Encryption SDK untuk .NET, Anda dapat memerlukan konteks enkripsi di semua permintaan enkripsi dengan [konteks enkripsi CMM yang diperlukan](configure.md#config-required-encryption-context-cmm).
```
// Define the encryption context
var encryptionContext = new Dictionary()
{
{"purpose", "test"}
};
```
Langkah 5: Buat objek input untuk mengenkripsi.
Sebelum memanggil `Encrypt()` metode, buat instance dari `EncryptInput` kelas.
```
string plaintext = File.ReadAllText("C:\\Documents\\CryptoTest\\TestFile.txt");
// Define the encrypt input
var encryptInput = new EncryptInput
{
Plaintext = plaintext,
Keyring = keyring,
EncryptionContext = encryptionContext
};
```
Langkah 6: Enkripsi plaintext.
Gunakan `Encrypt()` metode AWS Encryption SDK untuk mengenkripsi plaintext menggunakan keyring yang Anda tentukan.
`Encrypt() `Metode `EncryptOutput` yang dikembalikan memiliki metode untuk mendapatkan pesan terenkripsi (`Ciphertext`), konteks enkripsi, dan rangkaian algoritma.
```
var encryptOutput = encryptionSdk.Encrypt(encryptInput);
```
Langkah 7: Dapatkan pesan terenkripsi.
`Decrypt()`Metode dalam AWS Encryption SDK for .NET mengambil `Ciphertext` anggota `EncryptOutput` instance.
`Ciphertext`Anggota `EncryptOutput` objek adalah [pesan terenkripsi](concepts.md#message), objek portabel yang mencakup data terenkripsi, kunci data terenkripsi, dan metadata, termasuk konteks enkripsi. Anda dapat menyimpan pesan terenkripsi dengan aman untuk waktu yang lama atau mengirimkannya ke `Decrypt()` metode untuk memulihkan teks biasa.
```
var encryptedMessage = encryptOutput.Ciphertext;
```
## Mendekripsi dalam mode ketat di untuk.NET AWS Encryption SDK
Praktik terbaik menyarankan Anda menentukan kunci yang Anda gunakan untuk mendekripsi data, opsi yang dikenal sebagai mode *ketat*. Hanya AWS Encryption SDK menggunakan kunci KMS yang Anda tentukan dalam keyring Anda untuk mendekripsi ciphertext. Kunci dalam keyring dekripsi Anda harus menyertakan setidaknya salah satu kunci yang mengenkripsi data.
Contoh ini menunjukkan pola dasar dekripsi dalam mode ketat dengan AWS Encryption SDK untuk .NET.
Langkah 1: Buat instantiate perpustakaan penyedia AWS Encryption SDK dan materi.
```
// Instantiate the AWS Encryption SDK and material providers
var esdk = new ESDK(new AwsEncryptionSdkConfig());
var mpl = new MaterialProviders(new MaterialProvidersConfig());
```
Langkah 2: Buat objek input untuk keyring Anda.
Untuk menentukan parameter untuk metode keyring, buat objek input. Setiap metode keyring di AWS Encryption SDK for .NET memiliki objek input yang sesuai. Karena contoh ini menggunakan `CreateAwsKmsKeyring()` metode untuk membuat keyring, itu membuat instance `CreateAwsKmsKeyringInput` kelas untuk input.
Dalam keyring dekripsi, Anda harus menggunakan ARN kunci untuk mengidentifikasi kunci KMS.
```
string keyArn = "arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab";
// Instantiate the keyring input object
var kmsKeyringInput = new CreateAwsKmsKeyringInput
{
KmsClient = new AmazonKeyManagementServiceClient(),
KmsKeyId = keyArn
};
```
Langkah 3: Buat keyring.
Untuk membuat keyring dekripsi, contoh ini menggunakan `CreateAwsKmsKeyring()` metode dan objek input keyring.
```
var keyring = materialProviders.CreateAwsKmsKeyring(kmsKeyringInput);
```
Langkah 4: Buat objek input untuk mendekripsi.
Untuk membuat objek masukan untuk `Decrypt()` metode, buat instance kelas. `DecryptInput`
`Ciphertext`Parameter `DecryptInput()` konstruktor mengambil `Ciphertext` anggota `EncryptOutput` objek yang dikembalikan `Encrypt()` metode. `Ciphertext`Properti mewakili [pesan terenkripsi](concepts.md#message), yang mencakup data terenkripsi, kunci data terenkripsi, dan metadata yang diperlukan untuk mendekripsi pesan. AWS Encryption SDK
Dengan versi 4. *x* dari AWS Encryption SDK untuk .NET, Anda dapat menggunakan `EncryptionContext` parameter opsional untuk menentukan konteks enkripsi Anda dalam `Decrypt()` metode.
Gunakan `EncryptionContext` parameter untuk memverifikasi bahwa konteks enkripsi yang digunakan pada enkripsi *disertakan* dalam konteks enkripsi yang digunakan untuk mendekripsi ciphertext. AWS Encryption SDK Menambahkan pasangan ke konteks enkripsi, termasuk tanda tangan digital jika Anda menggunakan rangkaian algoritme dengan penandatanganan, seperti rangkaian algoritme default.
```
var encryptedMessage = encryptOutput.Ciphertext;
var decryptInput = new DecryptInput
{
Ciphertext = encryptedMessage,
Keyring = keyring,
EncryptionContext = encryptionContext // OPTIONAL
};
```
Langkah 5: Dekripsi ciphertext.
```
var decryptOutput = encryptionSdk.Decrypt(decryptInput);
```
Langkah 6: Verifikasi konteks enkripsi - Versi 3. *x*
`Decrypt()`Metode versi 3. *x* dari AWS Encryption SDK untuk .NET tidak mengambil konteks enkripsi. Ini mendapatkan nilai konteks enkripsi dari metadata dalam pesan terenkripsi. Namun, sebelum mengembalikan atau menggunakan plaintext, ini adalah praktik terbaik untuk memverifikasi bahwa konteks enkripsi yang digunakan untuk mendekripsi ciphertext mencakup konteks enkripsi yang Anda berikan saat mengenkripsi.
Verifikasi bahwa konteks enkripsi yang digunakan pada enkripsi *disertakan* dalam konteks enkripsi yang digunakan untuk mendekripsi ciphertext. AWS Encryption SDK Menambahkan pasangan ke konteks enkripsi, termasuk tanda tangan digital jika Anda menggunakan rangkaian algoritme dengan penandatanganan, seperti rangkaian algoritme default.
```
// Verify the encryption context
string contextKey = "purpose";
string contextValue = "test";
if (!decryptOutput.EncryptionContext.TryGetValue(contextKey, out var decryptContextValue)
|| !decryptContextValue.Equals(contextValue))
{
throw new Exception("Encryption context does not match expected values");
}
```
## Mendekripsi dengan keyring penemuan di for .NET AWS Encryption SDK
Daripada menentukan kunci KMS untuk dekripsi, Anda dapat memberikan keyring AWS KMS *penemuan, yang merupakan keyring* yang tidak menentukan kunci KMS apa pun. Keyring penemuan memungkinkan AWS Encryption SDK dekripsi data dengan menggunakan kunci KMS mana pun yang dienkripsi, asalkan penelepon memiliki izin dekripsi pada kunci tersebut. Untuk praktik terbaik, tambahkan filter penemuan yang membatasi kunci KMS yang dapat digunakan untuk kunci khusus Akun AWS partisi tertentu.
The AWS Encryption SDK for .NET menyediakan keyring penemuan dasar yang membutuhkan AWS KMS klien dan penemuan multi-keyring yang mengharuskan Anda menentukan satu atau lebih. Wilayah AWS Klien dan Wilayah membatasi kunci KMS yang dapat digunakan untuk mendekripsi pesan terenkripsi. Objek input untuk kedua keyring mengambil filter penemuan yang direkomendasikan.
Contoh berikut menunjukkan pola untuk mendekripsi data dengan keyring AWS KMS penemuan dan filter penemuan.
Langkah 1: Buat instance AWS Encryption SDK dan perpustakaan penyedia materi.
```
// Instantiate the AWS Encryption SDK and material providers
var esdk = new ESDK(new AwsEncryptionSdkConfig());
var mpl = new MaterialProviders(new MaterialProvidersConfig());
```
Langkah 2: Buat objek input untuk keyring.
Untuk menentukan parameter untuk metode keyring, buat objek input. Setiap metode keyring di AWS Encryption SDK for .NET memiliki objek input yang sesuai. Karena contoh ini menggunakan `CreateAwsKmsDiscoveryKeyring()` metode untuk membuat keyring, itu membuat instance `CreateAwsKmsDiscoveryKeyringInput` kelas untuk input.
```
List accounts = new List { "111122223333" };
var discoveryKeyringInput = new CreateAwsKmsDiscoveryKeyringInput
{
KmsClient = new AmazonKeyManagementServiceClient(),
DiscoveryFilter = new DiscoveryFilter()
{
AccountIds = accounts,
Partition = "aws"
}
};
```
Langkah 3: Buat keyring.
Untuk membuat keyring dekripsi, contoh ini menggunakan `CreateAwsKmsDiscoveryKeyring()` metode dan objek input keyring.
```
var discoveryKeyring = materialProviders.CreateAwsKmsDiscoveryKeyring(discoveryKeyringInput);
```
Langkah 4: Buat objek input untuk mendekripsi.
Untuk membuat objek masukan untuk `Decrypt()` metode, buat instance kelas. `DecryptInput` Nilai `Ciphertext` parameter adalah `Ciphertext` anggota `EncryptOutput` objek yang dikembalikan `Encrypt()` metode.
Dengan versi 4. *x* dari AWS Encryption SDK untuk .NET, Anda dapat menggunakan `EncryptionContext` parameter opsional untuk menentukan konteks enkripsi Anda dalam `Decrypt()` metode.
Gunakan `EncryptionContext` parameter untuk memverifikasi bahwa konteks enkripsi yang digunakan pada enkripsi *disertakan* dalam konteks enkripsi yang digunakan untuk mendekripsi ciphertext. AWS Encryption SDK Menambahkan pasangan ke konteks enkripsi, termasuk tanda tangan digital jika Anda menggunakan rangkaian algoritme dengan penandatanganan, seperti rangkaian algoritme default.
```
var ciphertext = encryptOutput.Ciphertext;
var decryptInput = new DecryptInput
{
Ciphertext = ciphertext,
Keyring = discoveryKeyring,
EncryptionContext = encryptionContext // OPTIONAL
};
var decryptOutput = encryptionSdk.Decrypt(decryptInput);
```
Langkah 5: Verifikasi konteks enkripsi - Versi 3. *x*
`Decrypt()`Metode versi 3. *x* dari AWS Encryption SDK untuk .NET tidak mengambil konteks enkripsi pada`Decrypt()`. Ini mendapatkan nilai konteks enkripsi dari metadata dalam pesan terenkripsi. Namun, sebelum mengembalikan atau menggunakan plaintext, ini adalah praktik terbaik untuk memverifikasi bahwa konteks enkripsi yang digunakan untuk mendekripsi ciphertext mencakup konteks enkripsi yang Anda berikan saat mengenkripsi.
Verifikasi bahwa konteks enkripsi yang digunakan pada enkripsi *disertakan* dalam konteks enkripsi yang digunakan untuk mendekripsi ciphertext. AWS Encryption SDK Menambahkan pasangan ke konteks enkripsi, termasuk tanda tangan digital jika Anda menggunakan rangkaian algoritme dengan penandatanganan, seperti rangkaian algoritme default.
```
// Verify the encryption context
string contextKey = "purpose";
string contextValue = "test";
if (!decryptOutput.EncryptionContext.TryGetValue(contextKey, out var decryptContextValue)
|| !decryptContextValue.Equals(contextValue))
{
throw new Exception("Encryption context does not match expected values");
}
```
# AWS Encryption SDK untuk Go
Topik ini menjelaskan cara menginstal dan menggunakan AWS Encryption SDK for Go. Untuk detail tentang pemrograman dengan AWS Encryption SDK for Go, lihat direktori [go](https://github.com/aws/aws-encryption-sdk/tree/mainline/releases/go/encryption-sdk/) dari aws-encryption-sdk repositori di. GitHub
The AWS Encryption SDK for Go berbeda dari beberapa implementasi bahasa pemrograman lainnya dengan AWS Encryption SDK cara berikut:
+ Tidak ada dukungan untuk [caching kunci data](data-key-caching.md). Namun, AWS Encryption SDK for Go mendukung [keyring AWS KMS Hierarchical, solusi caching](use-hierarchical-keyring.md) bahan kriptografi alternatif.
+ Tidak ada dukungan untuk streaming data
The AWS Encryption SDK for Go mencakup semua fitur keamanan yang diperkenalkan di versi 2.0. *x* dan yang lebih baru dari implementasi bahasa lain dari. AWS Encryption SDK Namun, jika Anda menggunakan AWS Encryption SDK for Go untuk mendekripsi data yang dienkripsi oleh pra-2.0. *x* versi implementasi bahasa lain dari AWS Encryption SDK, Anda mungkin perlu menyesuaikan [kebijakan komitmen](concepts.md#commitment-policy) Anda. Lihat perinciannya di [Cara menetapkan kebijakan komitmen Anda](migrate-commitment-policy.md#migrate-commitment-step1).
The AWS Encryption SDK for Go adalah produk dari AWS Encryption SDK in [Dafny](https://github.com/dafny-lang/dafny/blob/master/README.md), bahasa verifikasi formal di mana Anda menulis spesifikasi, kode untuk mengimplementasikannya, dan bukti untuk mengujinya. Hasilnya adalah perpustakaan yang mengimplementasikan fitur-fitur AWS Encryption SDK dalam kerangka kerja yang menjamin kebenaran fungsional.
**Pelajari Lebih Lanjut**
+ Untuk contoh yang menunjukkan cara mengonfigurasi opsi di AWS Encryption SDK, seperti menentukan rangkaian algoritme alternatif, membatasi kunci data terenkripsi, dan menggunakan kunci AWS KMS Multi-region, lihat. [Mengkonfigurasi AWS Encryption SDK](configure.md)
+ Untuk contoh yang menunjukkan cara mengonfigurasi dan menggunakan AWS Encryption SDK for Go, lihat [contoh Go](https://github.com/aws/aws-encryption-sdk/tree/mainline/releases/go/encryption-sdk/examples) di aws-encryption-sdk repositori aktif. GitHub
**Topics**
+ [
## Prasyarat
](#prerequisites-go)
+ [
## Penginstalan
](#go-installation)
## Prasyarat
Sebelum Anda menginstal AWS Encryption SDK for Go, pastikan Anda memiliki prasyarat berikut.
**Versi Go yang didukung**
Go 1.23 atau yang lebih baru diperlukan oleh AWS Encryption SDK for Go.
Untuk informasi selengkapnya tentang mengunduh dan menginstal Go, lihat [Instalasi Go](https://go.dev/doc/install).
## Penginstalan
Instal versi terbaru AWS Encryption SDK untuk Go. Untuk detail tentang menginstal dan membangun AWS Encryption SDK untuk Go, lihat [README.md](https://github.com/aws/aws-encryption-sdk/tree/mainline/releases/go/encryption-sdk/README.md) di direktori go repositori di aws-encryption-sdk. GitHub
**Pasang versi terbaru**
+ Instal AWS Encryption SDK untuk Go
```
go get github.com/aws/aws-encryption-sdk/releases/go/encryption-sdk@latest
```
+ Instal [Perpustakaan Penyedia Materi Kriptografi](https://github.com/aws/aws-cryptographic-material-providers-library) (MPL)
```
go get github.com/aws/aws-cryptographic-material-providers-library/releases/go/mpl
```
# AWS Encryption SDK for Java
Topik ini menjelaskan cara menginstal dan menggunakan AWS Encryption SDK for Java. Untuk detail tentang pemrograman dengan AWS Encryption SDK for Java, lihat [aws-encryption-sdk-java](https://github.com/aws/aws-encryption-sdk-java/)repositori di. GitHub Untuk dokumentasi API, lihat [Javadoc](https://aws.github.io/aws-encryption-sdk-java/) untuk dokumen. AWS Encryption SDK for Java
**Topics**
+ [
## Prasyarat
](#java-prerequisites)
+ [
## Penginstalan
](#java-installation)
+ [Contoh](java-example-code.md)
## Prasyarat
Sebelum Anda menginstal AWS Encryption SDK for Java, pastikan Anda memiliki prasyarat berikut.
**Lingkungan pengembangan Java**
Anda akan membutuhkan Java 8 atau yang lebih baru. Di situs web Oracle, buka [Unduhan Java SE](https://www.oracle.com/java/technologies/downloads/), kemudian unduh dan instal Java SE Development Kit (JDK).
Jika Anda menggunakan Oracle JDK, Anda juga harus mengunduh dan menginstal [File Java Cryptography Extension (JCE) Unlimited Strength Jurisdiction Policy](http://www.oracle.com/java/technologies/javase-jce8-downloads.html).
**Kastil Goyang**
AWS Encryption SDK for Java Membutuhkan Kastil [Bouncy.](https://www.bouncycastle.org/download/bouncy-castle-java/)
+ AWS Encryption SDK for Java versi 1.6.1 dan yang lebih baru menggunakan Bouncy Castle untuk membuat serial dan deserialisasi objek kriptografi. Anda dapat menggunakan Bouncy Castle atau [Bouncy Castle FIPS](https://www.bouncycastle.org/about/bouncy-castle-fips-faq/) untuk memenuhi persyaratan ini. **Untuk bantuan menginstal dan mengonfigurasi FIPS Bouncy Castle, lihat [Dokumentasi BC FIPS](https://www.bouncycastle.org/documentation/), terutama **Panduan Pengguna** dan Kebijakan Keamanan.** PDFs
+ Versi sebelumnya AWS Encryption SDK for Java menggunakan API kriptografi Bouncy Castle untuk Java. Persyaratan ini hanya dipenuhi oleh Kastil Bouncy non-FIPS.
Jika Anda tidak memiliki Bouncy Castle, buka [Unduh Bouncy Castle for Java untuk](https://bouncycastle.org/download/bouncy-castle-java/) mengunduh file penyedia yang sesuai dengan JDK Anda. [Anda juga dapat menggunakan [Apache Maven](https://maven.apache.org/) untuk mendapatkan artefak untuk penyedia Bouncy Castle standar ([bcprov-ext-jdk15on](https://mvnrepository.com/artifact/org.bouncycastle/bcprov-ext-jdk15on)) atau artefak untuk Bouncy Castle FIPS (bc-fips).](https://mvnrepository.com/artifact/org.bouncycastle/bc-fips)
**AWS SDK untuk Java**
Versi 3. *x* dari AWS Encryption SDK for Java membutuhkan AWS SDK for Java 2.x, bahkan jika Anda tidak menggunakan AWS KMS gantungan kunci.
Versi 2. *x* atau sebelumnya AWS Encryption SDK for Java tidak memerlukan AWS SDK untuk Java. Namun, AWS SDK untuk Java diperlukan untuk menggunakan [AWS Key Management Service](https://aws.amazon.com/kms/)(AWS KMS) sebagai penyedia kunci utama. Dimulai pada AWS Encryption SDK for Java versi 2.4.0, AWS Encryption SDK for Java mendukung versi 1.x dan 2.x dari versi. AWS SDK untuk Java AWS Encryption SDK kode untuk AWS SDK untuk Java 1.x dan 2.x dapat dioperasikan. Misalnya, Anda dapat mengenkripsi data dengan AWS Encryption SDK kode yang mendukung AWS SDK untuk Java 1.x dan mendekripsi menggunakan kode yang mendukung AWS SDK for Java 2.x (atau sebaliknya). Versi yang AWS Encryption SDK for Java lebih awal dari 2.4.0 hanya mendukung AWS SDK untuk Java 1.x. Untuk informasi tentang memperbarui versi Anda AWS Encryption SDK, lihat[Migrasi Anda AWS Encryption SDK](migration.md).
Saat memperbarui AWS Encryption SDK for Java kode Anda dari AWS SDK untuk Java 1.x ke AWS SDK for Java 2.x, ganti referensi ke [`AWSKMS`antarmuka](https://docs.aws.amazon.com/AWSJavaSDK/latest/javadoc/com/amazonaws/services/kms/package-summary.html) di AWS SDK untuk Java 1.x dengan referensi ke [`KmsClient`antarmuka](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/services/kms/package-summary.html) di. AWS SDK for Java 2.x AWS Encryption SDK for Java Tidak mendukung [`KmsAsyncClient`antarmuka](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/services/kms/KmsAsyncClient.html). Juga, perbarui kode Anda untuk menggunakan objek AWS KMS-related di `kmssdkv2` namespace, bukan namespace. `kms`
Untuk menginstal AWS SDK untuk Java, gunakan Apache Maven.
+ Untuk [mengimpor keseluruhan AWS SDK untuk Java](https://docs.aws.amazon.com/sdk-for-java/latest/developer-guide/setup-project-maven.html#build-the-entire-sdk-into-your-project) sebagai dependensi, deklarasikan dalam file Anda. `pom.xml`
+ Untuk membuat dependensi hanya untuk AWS KMS modul di AWS SDK untuk Java 1.x, ikuti instruksi untuk [menentukan modul tertentu](https://docs.aws.amazon.com/sdk-for-java/v1/developer-guide/setup-project-maven.html#modules-dependencies), dan atur ke. `artifactId` `aws-java-sdk-kms`
+ Untuk membuat dependensi hanya untuk AWS KMS modul di AWS SDK untuk Java 2.x, ikuti instruksi untuk [menentukan](https://docs.aws.amazon.com/sdk-for-java/latest/developer-guide/setup-project-maven.html#modules-dependencies) modul tertentu. Atur `groupId` ke `software.amazon.awssdk` dan `artifactId` ke`kms`.
Untuk perubahan lainnya, lihat [Apa yang berbeda antara AWS SDK untuk Java 1.x dan 2.x di Panduan](https://docs.aws.amazon.com/sdk-for-java/latest/developer-guide/migration-whats-different.html) AWS SDK for Java 2.x Pengembang.
Contoh Java dalam Panduan AWS Encryption SDK Pengembang menggunakan file AWS SDK for Java 2.x.
## Penginstalan
Instal versi terbaru dari file AWS Encryption SDK for Java.
**catatan**
[Semua versi yang AWS Encryption SDK for Java lebih awal dari 2.0.0 sedang dalam fase. end-of-support](https://docs.aws.amazon.com/sdkref/latest/guide/maint-policy.html#version-life-cycle)
Anda dapat memperbarui dengan aman dari versi 2.0. *x* dan yang lebih baru ke versi terbaru AWS Encryption SDK for Java tanpa kode atau perubahan data. Namun, [fitur keamanan baru](about-versions.md#version-2) diperkenalkan di versi 2.0. *x* tidak kompatibel ke belakang. Untuk memperbarui dari versi lebih awal dari 1.7. *x* ke versi 2.0. *x* dan yang lebih baru, Anda harus terlebih dahulu memperbarui ke yang terbaru 1. *x* versi AWS Encryption SDK. Lihat perinciannya di [Migrasi Anda AWS Encryption SDK](migration.md).
Anda dapat menginstal dengan cara berikut. AWS Encryption SDK for Java
**Secara manual**
Untuk menginstal AWS Encryption SDK for Java, kloning atau unduh [aws-encryption-sdk-java](https://github.com/aws/aws-encryption-sdk-java/) GitHubrepositori.
**Menggunakan Apache Maven**
AWS Encryption SDK for Java Ini tersedia melalui [Apache Maven dengan definisi ketergantungan](https://maven.apache.org/) berikut.
```
com.amazonawsaws-encryption-sdk-java3.0.0
```
Setelah Anda menginstal SDK, mulailah dengan melihat [contoh kode Java](java-example-code.md) dalam panduan ini dan [Javadoc](https://aws.github.io/aws-encryption-sdk-java/) aktif. GitHub
# AWS Encryption SDK for Java contoh
Contoh berikut menunjukkan cara menggunakan untuk mengenkripsi dan AWS Encryption SDK for Java mendekripsi data. Contoh-contoh ini menunjukkan cara menggunakan versi 3. *x* dan yang lebih baru AWS Encryption SDK for Java. Versi 3. *x* dari yang AWS Encryption SDK for Java membutuhkan AWS SDK for Java 2.x. Versi 3. *x* dari AWS Encryption SDK for Java menggantikan [penyedia kunci master](concepts.md#master-key-provider) dengan [keyrings](concepts.md#keyring). Untuk contoh yang menggunakan versi sebelumnya, temukan rilis Anda di daftar [Rilis [aws-encryption-sdk-java](https://github.com/aws/aws-encryption-sdk-java/)](https://github.com/aws/aws-encryption-sdk-java/releases)repositori di. GitHub
**Topics**
+ [String](#java-example-strings)
+ [Aliran byte](#java-example-streams)
+ [Aliran byte dengan beberapa penyedia kunci master](#java-example-multiple-providers)
## Mengenkripsi dan mendekripsi string
Contoh berikut menunjukkan cara menggunakan versi 3. *x* dari AWS Encryption SDK for Java untuk mengenkripsi dan mendekripsi string. Sebelum menggunakan string, ubah menjadi array byte.
Contoh ini menggunakan [AWS KMS keyring](use-kms-keyring.md). Saat Anda mengenkripsi dengan AWS KMS keyring, Anda dapat menggunakan ID kunci, ARN kunci, nama alias, atau alias ARN untuk mengidentifikasi kunci KMS. Saat mendekripsi, Anda harus menggunakan ARN kunci untuk mengidentifikasi kunci KMS.
Ketika Anda memanggil `encryptData()` metode, ia mengembalikan [pesan terenkripsi](concepts.md#message) (`CryptoResult`) yang mencakup ciphertext, kunci data terenkripsi, dan konteks enkripsi. Ketika Anda memanggil `getResult` `CryptoResult` objek, ia mengembalikan versi string yang dikodekan basis-64 dari [pesan terenkripsi](message-format.md) yang dapat Anda teruskan ke metode. `decryptData()`
Demikian pula, ketika Anda memanggil`decryptData()`, `CryptoResult` objek yang dikembalikan berisi pesan teks biasa AWS KMS key dan ID. Sebelum aplikasi Anda mengembalikan plaintext, verifikasi bahwa AWS KMS key ID dan konteks enkripsi dalam pesan terenkripsi adalah yang Anda harapkan.
```
// Copyright Amazon.com Inc. or its affiliates. All Rights Reserved.
// SPDX-License-Identifier: Apache-2.0
package com.amazonaws.crypto.keyrings;
import com.amazonaws.encryptionsdk.AwsCrypto;
import com.amazonaws.encryptionsdk.CommitmentPolicy;
import com.amazonaws.encryptionsdk.CryptoResult;
import software.amazon.cryptography.materialproviders.IKeyring;
import software.amazon.cryptography.materialproviders.MaterialProviders;
import software.amazon.cryptography.materialproviders.model.CreateAwsKmsMultiKeyringInput;
import software.amazon.cryptography.materialproviders.model.MaterialProvidersConfig;
import java.nio.charset.StandardCharsets;
import java.util.Arrays;
import java.util.Collections;
import java.util.Map;
/**
* Encrypts and then decrypts data using an AWS KMS Keyring.
*
*
Arguments:
*
*
*
Key ARN: For help finding the Amazon Resource Name (ARN) of your AWS KMS customer master
* key (CMK), see 'Viewing Keys' at
* http://docs.aws.amazon.com/kms/latest/developerguide/viewing-keys.html
*
*/
public class BasicEncryptionKeyringExample {
private static final byte[] EXAMPLE_DATA = "Hello World".getBytes(StandardCharsets.UTF_8);
public static void main(final String[] args) {
final String keyArn = args[0];
encryptAndDecryptWithKeyring(keyArn);
}
public static void encryptAndDecryptWithKeyring(final String keyArn) {
// 1. Instantiate the SDK
// This builds the AwsCrypto client with the RequireEncryptRequireDecrypt commitment policy,
// which means this client only encrypts using committing algorithm suites and enforces
// that the client will only decrypt encrypted messages that were created with a committing
// algorithm suite.
// This is the default commitment policy if you build the client with
// `AwsCrypto.builder().build()`
// or `AwsCrypto.standard()`.
final AwsCrypto crypto =
AwsCrypto.builder()
.withCommitmentPolicy(CommitmentPolicy.RequireEncryptRequireDecrypt)
.build();
// 2. Create the AWS KMS keyring.
// This example creates a multi keyring, which automatically creates the KMS client.
final MaterialProviders materialProviders =
MaterialProviders.builder()
.MaterialProvidersConfig(MaterialProvidersConfig.builder().build())
.build();
final CreateAwsKmsMultiKeyringInput keyringInput =
CreateAwsKmsMultiKeyringInput.builder().generator(keyArn).build();
final IKeyring kmsKeyring = materialProviders.CreateAwsKmsMultiKeyring(keyringInput);
// 3. Create an encryption context
// We recommend using an encryption context whenever possible
// to protect integrity. This sample uses placeholder values.
// For more information see:
// blogs.aws.amazon.com/security/post/Tx2LZ6WBJJANTNW/How-to-Protect-the-Integrity-of-Your-Encrypted-Data-by-Using-AWS-Key-Management
final Map encryptionContext =
Collections.singletonMap("ExampleContextKey", "ExampleContextValue");
// 4. Encrypt the data
final CryptoResult encryptResult =
crypto.encryptData(kmsKeyring, EXAMPLE_DATA, encryptionContext);
final byte[] ciphertext = encryptResult.getResult();
// 5. Decrypt the data
final CryptoResult decryptResult =
crypto.decryptData(
kmsKeyring,
ciphertext,
// Verify that the encryption context in the result contains the
// encryption context supplied to the encryptData method
encryptionContext);
// 6. Verify that the decrypted plaintext matches the original plaintext
assert Arrays.equals(decryptResult.getResult(), EXAMPLE_DATA);
}
}
```
## Mengenkripsi dan mendekripsi aliran byte
Contoh berikut menunjukkan cara menggunakan untuk mengenkripsi dan AWS Encryption SDK mendekripsi aliran byte.
Contoh ini menggunakan [keyring Raw AES](use-raw-aes-keyring.md).
Saat mengenkripsi, contoh ini menggunakan `AwsCrypto.builder() .withEncryptionAlgorithm()` metode untuk menentukan rangkaian algoritma tanpa tanda tangan [digital](concepts.md#digital-sigs). Saat mendekripsi, untuk memastikan bahwa ciphertext tidak ditandatangani, contoh ini menggunakan metode ini. `createUnsignedMessageDecryptingStream()` `createUnsignedMessageDecryptingStream()`Metode, gagal jika menemukan ciphertext dengan tanda tangan digital.
Jika Anda mengenkripsi dengan rangkaian algoritme default, yang menyertakan tanda tangan digital, gunakan `createDecryptingStream()` metode ini sebagai gantinya, seperti yang ditunjukkan pada contoh berikutnya.
```
// Copyright Amazon.com Inc. or its affiliates. All Rights Reserved.
// SPDX-License-Identifier: Apache-2.0
package com.amazonaws.crypto.keyrings;
import com.amazonaws.encryptionsdk.AwsCrypto;
import com.amazonaws.encryptionsdk.CommitmentPolicy;
import com.amazonaws.encryptionsdk.CryptoAlgorithm;
import com.amazonaws.encryptionsdk.CryptoInputStream;
import com.amazonaws.encryptionsdk.jce.JceMasterKey;
import com.amazonaws.util.IOUtils;
import software.amazon.cryptography.materialproviders.IKeyring;
import software.amazon.cryptography.materialproviders.MaterialProviders;
import software.amazon.cryptography.materialproviders.model.AesWrappingAlg;
import software.amazon.cryptography.materialproviders.model.CreateRawAesKeyringInput;
import software.amazon.cryptography.materialproviders.model.MaterialProvidersConfig;
import java.io.FileInputStream;
import java.io.FileOutputStream;
import java.io.IOException;
import java.nio.ByteBuffer;
import java.security.SecureRandom;
import java.util.Collections;
import java.util.Map;
import javax.crypto.SecretKey;
import javax.crypto.spec.SecretKeySpec;
/**
*
* Encrypts and then decrypts a file under a random key.
*
*
* Arguments:
*
*
Name of file containing plaintext data to encrypt
*
*
*
* This program demonstrates using a standard Java {@link SecretKey} object as a {@link IKeyring} to
* encrypt and decrypt streaming data.
*/
public class FileStreamingKeyringExample {
private static String srcFile;
public static void main(String[] args) throws IOException {
srcFile = args[0];
// In this example, we generate a random key. In practice,
// you would get a key from an existing store
SecretKey cryptoKey = retrieveEncryptionKey();
// Create a Raw Aes Keyring using the random key and an AES-GCM encryption algorithm
final MaterialProviders materialProviders = MaterialProviders.builder()
.MaterialProvidersConfig(MaterialProvidersConfig.builder().build())
.build();
final CreateRawAesKeyringInput keyringInput = CreateRawAesKeyringInput.builder()
.wrappingKey(ByteBuffer.wrap(cryptoKey.getEncoded()))
.keyNamespace("Example")
.keyName("RandomKey")
.wrappingAlg(AesWrappingAlg.ALG_AES128_GCM_IV12_TAG16)
.build();
IKeyring keyring = materialProviders.CreateRawAesKeyring(keyringInput);
// Instantiate the SDK.
// This builds the AwsCrypto client with the RequireEncryptRequireDecrypt commitment policy,
// which means this client only encrypts using committing algorithm suites and enforces
// that the client will only decrypt encrypted messages that were created with a committing
// algorithm suite.
// This is the default commitment policy if you build the client with
// `AwsCrypto.builder().build()`
// or `AwsCrypto.standard()`.
// This example encrypts with an algorithm suite that doesn't include signing for faster decryption,
// since this use case assumes that the contexts that encrypt and decrypt are equally trusted.
final AwsCrypto crypto = AwsCrypto.builder()
.withCommitmentPolicy(CommitmentPolicy.RequireEncryptRequireDecrypt)
.withEncryptionAlgorithm(CryptoAlgorithm.ALG_AES_256_GCM_HKDF_SHA512_COMMIT_KEY)
.build();
// Create an encryption context to identify the ciphertext
Map context = Collections.singletonMap("Example", "FileStreaming");
// Because the file might be too large to load into memory, we stream the data, instead of
//loading it all at once.
FileInputStream in = new FileInputStream(srcFile);
CryptoInputStream encryptingStream = crypto.createEncryptingStream(keyring, in, context);
FileOutputStream out = new FileOutputStream(srcFile + ".encrypted");
IOUtils.copy(encryptingStream, out);
encryptingStream.close();
out.close();
// Decrypt the file. Verify the encryption context before returning the plaintext.
// Since the data was encrypted using an unsigned algorithm suite, use the recommended
// createUnsignedMessageDecryptingStream method, which only accepts unsigned messages.
in = new FileInputStream(srcFile + ".encrypted");
CryptoInputStream decryptingStream = crypto.createUnsignedMessageDecryptingStream(keyring, in);
// Does it contain the expected encryption context?
if (!"FileStreaming".equals(decryptingStream.getCryptoResult().getEncryptionContext().get("Example"))) {
throw new IllegalStateException("Bad encryption context");
}
// Write the plaintext data to disk.
out = new FileOutputStream(srcFile + ".decrypted");
IOUtils.copy(decryptingStream, out);
decryptingStream.close();
out.close();
}
/**
* In practice, this key would be saved in a secure location.
* For this demo, we generate a new random key for each operation.
*/
private static SecretKey retrieveEncryptionKey() {
SecureRandom rnd = new SecureRandom();
byte[] rawKey = new byte[16]; // 128 bits
rnd.nextBytes(rawKey);
return new SecretKeySpec(rawKey, "AES");
}
}
```
## Mengenkripsi dan mendekripsi aliran byte dengan multi-keyring
Contoh berikut menunjukkan cara menggunakan AWS Encryption SDK dengan [multi-keyring](use-multi-keyring.md). Bila Anda menggunakan multi-keyring untuk mengenkripsi data, salah satu kunci pembungkus di salah satu keyrings nya dapat mendekripsi data tersebut. Contoh ini menggunakan [AWS KMS keyring dan keyring](use-kms-keyring.md) [Raw RSA sebagai keyring](use-raw-rsa-keyring.md) anak.
Contoh ini mengenkripsi dengan [rangkaian algoritme default](supported-algorithms.md), yang mencakup tanda tangan [digital](concepts.md#digital-sigs). Saat streaming, AWS Encryption SDK rilis plaintext setelah pemeriksaan integritas, tetapi sebelum memverifikasi tanda tangan digital. Untuk menghindari penggunaan plaintext sampai tanda tangan diverifikasi, contoh ini menyangga plaintext, dan menuliskannya ke disk hanya ketika dekripsi dan verifikasi selesai.
```
// Copyright Amazon.com Inc. or its affiliates. All Rights Reserved.
// SPDX-License-Identifier: Apache-2.0
package com.amazonaws.crypto.keyrings;
import com.amazonaws.encryptionsdk.AwsCrypto;
import com.amazonaws.encryptionsdk.CommitmentPolicy;
import com.amazonaws.encryptionsdk.CryptoOutputStream;
import com.amazonaws.util.IOUtils;
import software.amazon.cryptography.materialproviders.IKeyring;
import software.amazon.cryptography.materialproviders.MaterialProviders;
import software.amazon.cryptography.materialproviders.model.CreateAwsKmsMultiKeyringInput;
import software.amazon.cryptography.materialproviders.model.CreateMultiKeyringInput;
import software.amazon.cryptography.materialproviders.model.CreateRawRsaKeyringInput;
import software.amazon.cryptography.materialproviders.model.MaterialProvidersConfig;
import software.amazon.cryptography.materialproviders.model.PaddingScheme;
import java.io.ByteArrayInputStream;
import java.io.ByteArrayOutputStream;
import java.io.FileInputStream;
import java.io.FileOutputStream;
import java.nio.ByteBuffer;
import java.security.GeneralSecurityException;
import java.security.KeyPair;
import java.security.KeyPairGenerator;
import java.util.Collections;
/**
*
* Encrypts a file using both AWS KMS Key and an asymmetric key pair.
*
*
* Arguments:
*
*
Key ARN: For help finding the Amazon Resource Name (ARN) of your AWS KMS key,
* see 'Viewing Keys' at http://docs.aws.amazon.com/kms/latest/developerguide/viewing-keys.html
*
*
Name of file containing plaintext data to encrypt
*
*
* You might use AWS Key Management Service (AWS KMS) for most encryption and decryption operations, but
* still want the option of decrypting your data offline independently of AWS KMS. This sample
* demonstrates one way to do this.
*
* The sample encrypts data under both an AWS KMS key and an "escrowed" RSA key pair
* so that either key alone can decrypt it. You might commonly use the AWS KMS key for decryption. However,
* at any time, you can use the private RSA key to decrypt the ciphertext independent of AWS KMS.
*
* This sample uses the RawRsaKeyring to generate a RSA public-private key pair
* and saves the key pair in memory. In practice, you would store the private key in a secure offline
* location, such as an offline HSM, and distribute the public key to your development team.
*/
public class EscrowedEncryptKeyringExample {
private static ByteBuffer publicEscrowKey;
private static ByteBuffer privateEscrowKey;
public static void main(final String[] args) throws Exception {
// This sample generates a new random key for each operation.
// In practice, you would distribute the public key and save the private key in secure
// storage.
generateEscrowKeyPair();
final String kmsArn = args[0];
final String fileName = args[1];
standardEncrypt(kmsArn, fileName);
standardDecrypt(kmsArn, fileName);
escrowDecrypt(fileName);
}
private static void standardEncrypt(final String kmsArn, final String fileName) throws Exception {
// Encrypt with the KMS key and the escrowed public key
// 1. Instantiate the SDK
// This builds the AwsCrypto client with the RequireEncryptRequireDecrypt commitment policy,
// which means this client only encrypts using committing algorithm suites and enforces
// that the client will only decrypt encrypted messages that were created with a committing
// algorithm suite.
// This is the default commitment policy if you build the client with
// `AwsCrypto.builder().build()`
// or `AwsCrypto.standard()`.
final AwsCrypto crypto = AwsCrypto.builder()
.withCommitmentPolicy(CommitmentPolicy.RequireEncryptRequireDecrypt)
.build();
// 2. Create the AWS KMS keyring.
// This example creates a multi keyring, which automatically creates the KMS client.
final MaterialProviders matProv = MaterialProviders.builder()
.MaterialProvidersConfig(MaterialProvidersConfig.builder().build())
.build();
final CreateAwsKmsMultiKeyringInput keyringInput = CreateAwsKmsMultiKeyringInput.builder()
.generator(kmsArn)
.build();
IKeyring kmsKeyring = matProv.CreateAwsKmsMultiKeyring(keyringInput);
// 3. Create the Raw Rsa Keyring with Public Key.
final CreateRawRsaKeyringInput encryptingKeyringInput = CreateRawRsaKeyringInput.builder()
.keyName("Escrow")
.keyNamespace("Escrow")
.paddingScheme(PaddingScheme.OAEP_SHA512_MGF1)
.publicKey(publicEscrowKey)
.build();
IKeyring rsaPublicKeyring = matProv.CreateRawRsaKeyring(encryptingKeyringInput);
// 4. Create the multi-keyring.
final CreateMultiKeyringInput createMultiKeyringInput = CreateMultiKeyringInput.builder()
.generator(kmsKeyring)
.childKeyrings(Collections.singletonList(rsaPublicKeyring))
.build();
IKeyring multiKeyring = matProv.CreateMultiKeyring(createMultiKeyringInput);
// 5. Encrypt the file
// To simplify this code example, we omit the encryption context. Production code should always
// use an encryption context.
final FileInputStream in = new FileInputStream(fileName);
final FileOutputStream out = new FileOutputStream(fileName + ".encrypted");
final CryptoOutputStream encryptingStream = crypto.createEncryptingStream(multiKeyring, out);
IOUtils.copy(in, encryptingStream);
in.close();
encryptingStream.close();
}
private static void standardDecrypt(final String kmsArn, final String fileName) throws Exception {
// Decrypt with the AWS KMS key and the escrow public key.
// 1. Instantiate the SDK.
// This builds the AwsCrypto client with the RequireEncryptRequireDecrypt commitment policy,
// which means this client only encrypts using committing algorithm suites and enforces
// that the client will only decrypt encrypted messages that were created with a committing
// algorithm suite.
// This is the default commitment policy if you build the client with
// `AwsCrypto.builder().build()`
// or `AwsCrypto.standard()`.
final AwsCrypto crypto = AwsCrypto.builder()
.withCommitmentPolicy(CommitmentPolicy.RequireEncryptRequireDecrypt)
.build();
// 2. Create the AWS KMS keyring.
// This example creates a multi keyring, which automatically creates the KMS client.
final MaterialProviders matProv = MaterialProviders.builder()
.MaterialProvidersConfig(MaterialProvidersConfig.builder().build())
.build();
final CreateAwsKmsMultiKeyringInput keyringInput = CreateAwsKmsMultiKeyringInput.builder()
.generator(kmsArn)
.build();
IKeyring kmsKeyring = matProv.CreateAwsKmsMultiKeyring(keyringInput);
// 3. Create the Raw Rsa Keyring with Public Key.
final CreateRawRsaKeyringInput encryptingKeyringInput = CreateRawRsaKeyringInput.builder()
.keyName("Escrow")
.keyNamespace("Escrow")
.paddingScheme(PaddingScheme.OAEP_SHA512_MGF1)
.publicKey(publicEscrowKey)
.build();
IKeyring rsaPublicKeyring = matProv.CreateRawRsaKeyring(encryptingKeyringInput);
// 4. Create the multi-keyring.
final CreateMultiKeyringInput createMultiKeyringInput = CreateMultiKeyringInput.builder()
.generator(kmsKeyring)
.childKeyrings(Collections.singletonList(rsaPublicKeyring))
.build();
IKeyring multiKeyring = matProv.CreateMultiKeyring(createMultiKeyringInput);
// 5. Decrypt the file
// To simplify this code example, we omit the encryption context. Production code should always
// use an encryption context.
final FileInputStream in = new FileInputStream(fileName + ".encrypted");
final FileOutputStream out = new FileOutputStream(fileName + ".decrypted");
// Since we are using a signing algorithm suite, we avoid streaming decryption directly to the output file,
// to ensure that the trailing signature is verified before writing any untrusted plaintext to disk.
final ByteArrayOutputStream plaintextBuffer = new ByteArrayOutputStream();
final CryptoOutputStream decryptingStream = crypto.createDecryptingStream(multiKeyring, plaintextBuffer);
IOUtils.copy(in, decryptingStream);
in.close();
decryptingStream.close();
final ByteArrayInputStream plaintextReader = new ByteArrayInputStream(plaintextBuffer.toByteArray());
IOUtils.copy(plaintextReader, out);
out.close();
}
private static void escrowDecrypt(final String fileName) throws Exception {
// You can decrypt the stream using only the private key.
// This method does not call AWS KMS.
// 1. Instantiate the SDK
final AwsCrypto crypto = AwsCrypto.standard();
// 2. Create the Raw Rsa Keyring with Private Key.
final MaterialProviders matProv = MaterialProviders.builder()
.MaterialProvidersConfig(MaterialProvidersConfig.builder().build())
.build();
final CreateRawRsaKeyringInput encryptingKeyringInput = CreateRawRsaKeyringInput.builder()
.keyName("Escrow")
.keyNamespace("Escrow")
.paddingScheme(PaddingScheme.OAEP_SHA512_MGF1)
.publicKey(publicEscrowKey)
.privateKey(privateEscrowKey)
.build();
IKeyring escrowPrivateKeyring = matProv.CreateRawRsaKeyring(encryptingKeyringInput);
// 3. Decrypt the file
// To simplify this code example, we omit the encryption context. Production code should always
// use an encryption context.
final FileInputStream in = new FileInputStream(fileName + ".encrypted");
final FileOutputStream out = new FileOutputStream(fileName + ".deescrowed");
final CryptoOutputStream decryptingStream = crypto.createDecryptingStream(escrowPrivateKeyring, out);
IOUtils.copy(in, decryptingStream);
in.close();
decryptingStream.close();
}
private static void generateEscrowKeyPair() throws GeneralSecurityException {
final KeyPairGenerator kg = KeyPairGenerator.getInstance("RSA");
kg.initialize(4096); // Escrow keys should be very strong
final KeyPair keyPair = kg.generateKeyPair();
publicEscrowKey = RawRsaKeyringExample.getPEMPublicKey(keyPair.getPublic());
privateEscrowKey = RawRsaKeyringExample.getPEMPrivateKey(keyPair.getPrivate());
}
}
```
# AWS Encryption SDK for JavaScript
AWS Encryption SDK for JavaScript Ini dirancang untuk menyediakan pustaka enkripsi sisi klien untuk pengembang yang menulis aplikasi browser web di JavaScript atau aplikasi server web di Node.js.
Seperti semua implementasi AWS Encryption SDK, AWS Encryption SDK for JavaScript menawarkan fitur perlindungan data tingkat lanjut. Ini termasuk [enkripsi amplop](concepts.md#envelope-encryption), data otentikasi tambahan (AAD), dan [rangkaian algoritma](concepts.md#crypto-algorithm) kunci simetris yang aman, diautentikasi, seperti AES-GCM 256-bit dengan derivasi dan penandatanganan kunci.
Semua implementasi khusus bahasa dirancang agar dapat dioperasikan, tunduk pada kendala bahasa. AWS Encryption SDK Untuk detail tentang batasan bahasa, lihat. JavaScript [Kompatibilitas AWS Encryption SDK for JavaScript](javascript-compatibility.md)
**Pelajari Lebih Lanjut**
+ Untuk detail tentang pemrograman dengan AWS Encryption SDK for JavaScript, lihat [aws-encryption-sdk-javascript](https://github.com/aws/aws-encryption-sdk-javascript/)repositori di. GitHub
+ Untuk contoh pemrograman, lihat [AWS Encryption SDK for JavaScript contoh](js-examples.md) dan modul [example-browser](https://github.com/aws/aws-encryption-sdk-javascript/tree/master/modules/example-browser) dan [example-node](https://github.com/aws/aws-encryption-sdk-javascript/tree/master/modules/example-node) di repositori. [aws-encryption-sdk-javascript](https://github.com/aws/aws-encryption-sdk-javascript/)
+ Untuk contoh dunia nyata menggunakan data AWS Encryption SDK for JavaScript untuk mengenkripsi dalam aplikasi web, lihat [Cara mengaktifkan enkripsi di browser dengan AWS Encryption SDK for JavaScript dan Node.js](https://aws.amazon.com/blogs/security/how-to-enable-encryption-browser-aws-encryption-sdk-javascript-node-js/) di Blog AWS Keamanan.
**Topics**
+ [Kompatibilitas](javascript-compatibility.md)
+ [Penginstalan](javascript-installation.md)
+ [Modul](javascript-modules.md)
+ [Contoh](js-examples.md)
# Kompatibilitas AWS Encryption SDK for JavaScript
AWS Encryption SDK for JavaScript Ini dirancang untuk dapat dioperasikan dengan implementasi bahasa lain dari. AWS Encryption SDK Dalam kebanyakan kasus, Anda dapat mengenkripsi data dengan AWS Encryption SDK for JavaScript dan mendekripsi dengan implementasi bahasa lain, termasuk Antarmuka Baris [AWS Encryption SDK Perintah](crypto-cli.md). Dan Anda dapat menggunakan AWS Encryption SDK for JavaScript untuk mendekripsi [pesan terenkripsi yang](concepts.md#message) dihasilkan oleh implementasi bahasa lain dari. AWS Encryption SDK
Namun, ketika Anda menggunakan AWS Encryption SDK for JavaScript, Anda perlu menyadari beberapa masalah kompatibilitas dalam implementasi JavaScript bahasa dan di browser web.
Selain itu, saat menggunakan implementasi bahasa yang berbeda, pastikan untuk mengonfigurasi penyedia kunci master, kunci master, dan gantungan kunci yang kompatibel. Lihat perinciannya di [Kompatibilitas keyring](choose-keyring.md#keyring-compatibility).
## AWS Encryption SDK for JavaScript kompatibilitas
JavaScript Implementasi AWS Encryption SDK berbeda dari implementasi bahasa lain dengan cara berikut:
+ Operasi enkripsi AWS Encryption SDK for JavaScript tidak mengembalikan ciphertext nonframed. Namun, AWS Encryption SDK for JavaScript wasiat mendekripsi ciphertext berbingkai dan tidak dibingkai yang dikembalikan oleh implementasi bahasa lain dari. AWS Encryption SDK
+ Mulai dari Node.js versi 12.9.0, Node.js mendukung opsi pembungkus kunci RSA berikut:
+ OAEP dengan SHA1,, SHA256, SHA384 atau SHA512
+ OAEP dengan dan dengan SHA1 MGF1 SHA1
+ PKCS1v15
+ Sebelum versi 12.9.0, Node.js hanya mendukung opsi pembungkus kunci RSA berikut:
+ OAEP dengan dan dengan SHA1 MGF1 SHA1
+ PKCS1v15
## Kompabilitas peramban
Beberapa browser web tidak mendukung operasi kriptografi dasar yang AWS Encryption SDK for JavaScript diperlukan. Anda dapat mengkompensasi beberapa operasi yang hilang dengan mengonfigurasi fallback untuk WebCrypto API yang diterapkan browser.
**Keterbatasan browser web**
Keterbatasan berikut umum untuk semua browser web:
+ WebCrypto API tidak mendukung pembungkus PKCS1v15 kunci.
+ Browser tidak mendukung kunci 192-bit.
**Operasi kriptografi yang diperlukan**
Ini AWS Encryption SDK for JavaScript membutuhkan operasi berikut di browser web. Jika browser tidak mendukung operasi ini, itu tidak kompatibel dengan. AWS Encryption SDK for JavaScript
+ Browser harus menyertakan`crypto.getRandomValues()`, yang merupakan metode untuk menghasilkan nilai acak kriptografis. Untuk informasi tentang versi browser web yang mendukung`crypto.getRandomValues()`, lihat [Dapatkah Saya Menggunakan kripto. getRandomValues()?](https://caniuse.com/#feat=getrandomvalues) .
**Fallback yang dibutuhkan**
Ini AWS Encryption SDK for JavaScript membutuhkan perpustakaan dan operasi berikut di browser web. Jika Anda mendukung browser web yang tidak memenuhi persyaratan ini, Anda harus mengonfigurasi fallback. Jika tidak, upaya untuk AWS Encryption SDK for JavaScript menggunakan browser akan gagal.
+ WebCrypto API, yang melakukan operasi kriptografi dasar dalam aplikasi web, tidak tersedia untuk semua browser. Untuk informasi tentang versi browser web yang mendukung kriptografi web, lihat [Dapatkah Saya Menggunakan Kriptografi Web?](https://caniuse.com/#feat=cryptography) .
+ Versi modern dari browser web Safari tidak mendukung enkripsi AES-GCM nol byte, yang diperlukan. AWS Encryption SDK Jika browser mengimplementasikan WebCrypto API, tetapi tidak dapat menggunakan AES-GCM untuk mengenkripsi nol byte, browser AWS Encryption SDK for JavaScript menggunakan pustaka fallback hanya untuk enkripsi nol-byte. Ini menggunakan WebCrypto API untuk semua operasi lainnya.
Untuk mengonfigurasi fallback untuk salah satu batasan, tambahkan pernyataan berikut ke kode Anda. Dalam fungsi [ConfigurefallBack](https://github.com/aws/aws-encryption-sdk-javascript/blob/master/modules/web-crypto-backend/src/backend-factory.ts#L78), tentukan pustaka yang mendukung fitur yang hilang. Contoh berikut menggunakan Microsoft Research JavaScript Cryptography Library (`msrcrypto`), tetapi Anda dapat menggantinya dengan perpustakaan yang kompatibel. Untuk contoh lengkapnya, lihat [fallback.ts](https://github.com/aws/aws-encryption-sdk-javascript/blob/master/modules/example-browser/src/fallback.ts).
```
import { configureFallback } from '@aws-crypto/client-browser'
configureFallback(msrCrypto)
```
# Memasang AWS Encryption SDK for JavaScript
AWS Encryption SDK for JavaScript Terdiri dari kumpulan modul yang saling bergantung. Beberapa modul hanyalah kumpulan modul yang dirancang untuk bekerja sama. Beberapa modul dirancang untuk bekerja secara mandiri. Beberapa modul diperlukan untuk semua implementasi; beberapa lainnya hanya diperlukan untuk kasus khusus. Untuk informasi tentang modul di AWS Encryption SDK for JavaScript, lihat [Modul di AWS Encryption SDK for JavaScript](javascript-modules.md) dan `README.md` file di masing-masing modul di [aws-encryption-sdk-javascript](https://github.com/aws/aws-encryption-sdk-javascript/tree/master/modules)repositori pada. GitHub
**catatan**
[Semua versi yang AWS Encryption SDK for JavaScript lebih awal dari 2.0.0 sedang dalam fase. end-of-support](https://docs.aws.amazon.com/sdkref/latest/guide/maint-policy.html#version-life-cycle)
Anda dapat memperbarui dengan aman dari versi 2.0. *x* dan yang lebih baru ke versi terbaru AWS Encryption SDK for JavaScript tanpa kode atau perubahan data. Namun, [fitur keamanan baru](about-versions.md#version-2) diperkenalkan di versi 2.0. *x* tidak kompatibel ke belakang. Untuk memperbarui dari versi lebih awal dari 1.7. *x* ke versi 2.0. *x* dan yang lebih baru, Anda harus terlebih dahulu memperbarui ke yang terbaru 1. *x* versi AWS Encryption SDK for JavaScript. Lihat perinciannya di [Migrasi Anda AWS Encryption SDK](migration.md).
Untuk menginstal modul, gunakan [manajer paket npm](https://www.npmjs.com/get-npm).
Misalnya, untuk menginstal `client-node` modul, yang mencakup semua modul yang Anda butuhkan untuk memprogram dengan AWS Encryption SDK for JavaScript di Node.js, gunakan perintah berikut.
```
npm install @aws-crypto/client-node
```
Untuk menginstal `client-browser` modul, yang mencakup semua modul yang perlu Anda program dengan AWS Encryption SDK for JavaScript di browser, gunakan perintah berikut.
```
npm install @aws-crypto/client-browser
```
Untuk contoh kerja tentang cara menggunakan AWS Encryption SDK for JavaScript, lihat contoh di `example-node` dan `example-browser` modul di [aws-encryption-sdk-javascript](https://github.com/aws/aws-encryption-sdk-javascript/)repositori pada. GitHub
# Modul di AWS Encryption SDK for JavaScript
Modul di AWS Encryption SDK for JavaScript membuatnya mudah untuk menginstal kode yang Anda butuhkan untuk proyek Anda.
## Modul untuk JavaScript Node.js
[simpul klien](https://github.com/aws/aws-encryption-sdk-javascript/tree/master/modules/client-node)
Termasuk semua modul yang Anda butuhkan untuk memprogram dengan AWS Encryption SDK for JavaScript di Node.js.
[caching-materials-manager-node](https://github.com/aws/aws-encryption-sdk-javascript/tree/master/modules/caching-materials-manager-node)
Mengekspor fungsi yang mendukung fitur [caching kunci data](data-key-caching.md) AWS Encryption SDK for JavaScript di Node.js.
[dekripsi-simpul](https://github.com/aws/aws-encryption-sdk-javascript/tree/master/modules/decrypt-node)
Mengekspor fungsi yang mendekripsi dan memverifikasi pesan terenkripsi yang mewakili aliran data dan data. Termasuk dalam `client-node` modul.
[enkripsi-simpul](https://github.com/aws/aws-encryption-sdk-javascript/tree/master/modules/encrypt-node)
Mengekspor fungsi yang mengenkripsi dan menandatangani berbagai jenis data. Termasuk dalam `client-node` modul.
[contoh-simpul](https://github.com/aws/aws-encryption-sdk-javascript/tree/master/modules/example-node)
Mengekspor contoh kerja pemrograman dengan AWS Encryption SDK for JavaScript di Node.js. Termasuk contoh berbagai jenis gantungan kunci dan berbagai jenis data.
[hkdf-simpul](https://github.com/aws/aws-encryption-sdk-javascript/tree/master/modules/hkdf-node)
Mengekspor [Fungsi Derivasi Kunci (HKDF) berbasis HMAC](https://en.wikipedia.org/wiki/HKDF) yang digunakan di Node.js AWS Encryption SDK for JavaScript dalam rangkaian algoritma tertentu. AWS Encryption SDK for JavaScript Di browser menggunakan fungsi HKDF asli di API. WebCrypto
[integrasi-simpul](https://github.com/aws/aws-encryption-sdk-javascript/tree/master/modules/integration-node)
Mendefinisikan pengujian yang memverifikasi bahwa AWS Encryption SDK for JavaScript di Node.js kompatibel dengan implementasi bahasa lain dari file. AWS Encryption SDK
[kms-keyring-node](https://github.com/aws/aws-encryption-sdk-javascript/tree/master/modules/kms-keyring-node)
Mengekspor fungsi yang mendukung AWS KMS keyrings di Node.js.
[raw-aes-keyring-node](https://github.com/aws/aws-encryption-sdk-javascript/tree/master/modules/raw-aes-keyring-node)
Mengekspor fungsi yang mendukung [keyrings Raw AES di Node.js](use-raw-aes-keyring.md).
[raw-rsa-keyring-node](https://github.com/aws/aws-encryption-sdk-javascript/tree/master/modules/raw-rsa-keyring-node)
Mengekspor fungsi yang mendukung [keyring Raw RSA di Node.js](use-raw-rsa-keyring.md).
## Modul untuk JavaScript Browser
[peramban klien](https://github.com/aws/aws-encryption-sdk-javascript/tree/master/modules/client-browser)
Termasuk semua modul yang Anda butuhkan untuk memprogram dengan AWS Encryption SDK for JavaScript di browser.
[caching-materials-manager-browser](https://github.com/aws/aws-encryption-sdk-javascript/tree/master/modules/caching-materials-manager-browser)
Mengekspor fungsi yang mendukung fitur [caching kunci data](data-key-caching.md) untuk JavaScript di browser.
[dekripsi-browser](https://github.com/aws/aws-encryption-sdk-javascript/tree/master/modules/decrypt-browser)
Mengekspor fungsi yang mendekripsi dan memverifikasi pesan terenkripsi yang mewakili aliran data dan data.
[browser terenkripsi](https://github.com/aws/aws-encryption-sdk-javascript/tree/master/modules/encrypt-browser)
Mengekspor fungsi yang mengenkripsi dan menandatangani berbagai jenis data.
[contoh-browser](https://github.com/aws/aws-encryption-sdk-javascript/tree/master/modules/example-browser)
Contoh kerja pemrograman dengan AWS Encryption SDK for JavaScript di browser. Termasuk contoh berbagai jenis gantungan kunci dan berbagai jenis data.
[integrasi-browser](https://github.com/aws/aws-encryption-sdk-javascript/tree/master/modules/integration-browser)
Mendefinisikan tes yang memverifikasi bahwa AWS Encryption SDK for Java Script di browser kompatibel dengan implementasi bahasa lain dari file. AWS Encryption SDK
[kms-keyring-browser](https://github.com/aws/aws-encryption-sdk-javascript/tree/master/modules/kms-keyring-browser)
Mengekspor fungsi yang mendukung [AWS KMS keyrings](use-kms-keyring.md) di browser.
[raw-aes-keyring-browser](https://github.com/aws/aws-encryption-sdk-javascript/tree/master/modules/raw-aes-keyring-browser)
Mengekspor fungsi yang mendukung [keyrings Raw AES di browser](use-raw-aes-keyring.md).
[raw-rsa-keyring-browser](https://github.com/aws/aws-encryption-sdk-javascript/tree/master/modules/raw-rsa-keyring-browser)
Mengekspor fungsi yang mendukung [keyring Raw RSA di browser](use-raw-rsa-keyring.md).
## Modul untuk semua implementasi
[bahan tembolok](https://github.com/aws/aws-encryption-sdk-javascript/tree/master/modules/cache-material)
Mendukung fitur [caching kunci data](data-key-caching.md). Menyediakan kode untuk merakit materi kriptografi yang di-cache dengan setiap kunci data.
[kms-keyring](https://github.com/aws/aws-encryption-sdk-javascript/tree/master/modules/kms-keyring)
Mengekspor fungsi yang mendukung keyrings [KMS.](use-kms-keyring.md)
[manajemen material](https://github.com/aws/aws-encryption-sdk-javascript/tree/master/modules/material-management)
Menerapkan [manajer bahan kriptografi](concepts.md#crypt-materials-manager) (CMM).
[gantungan kunci mentah](https://github.com/aws/aws-encryption-sdk-javascript/tree/master/modules/raw-keyring)
Fungsi ekspor diperlukan untuk gantungan kunci AES dan RSA mentah.
[serialisasi](https://github.com/aws/aws-encryption-sdk-javascript/tree/master/modules/serialize)
Mengekspor fungsi yang digunakan SDK untuk membuat serial outputnya.
[web-crypto-backend](https://github.com/aws/aws-encryption-sdk-javascript/tree/master/modules/web-crypto-backend)
Mengekspor fungsi yang menggunakan WebCrypto API AWS Encryption SDK for JavaScript di browser.
# AWS Encryption SDK for JavaScript contoh
Contoh berikut menunjukkan cara menggunakan untuk mengenkripsi dan AWS Encryption SDK for JavaScript mendekripsi data.
Anda dapat menemukan lebih banyak contoh penggunaan modul [example-node dan [example-browser AWS Encryption SDK for JavaScript](https://github.com/aws/aws-encryption-sdk-javascript/tree/master/modules/example-browser)](https://github.com/aws/aws-encryption-sdk-javascript/tree/master/modules/example-node) di repositori pada. [aws-encryption-sdk-javascript](https://github.com/aws/aws-encryption-sdk-javascript/) GitHub Modul contoh ini tidak diinstal ketika Anda menginstal `client-browser` atau `client-node` modul.
**Lihat contoh kode lengkap**[: Node: kms\$1simple.ts, [Browser: kms\$1simple.ts](https://github.com/aws/aws-encryption-sdk-javascript/blob/master/modules/example-node/src/kms_simple.ts)](https://github.com/aws/aws-encryption-sdk-javascript/blob/master/modules/example-browser/src/kms_simple.ts)
**Topics**
+ [
## Mengenkripsi data dengan keyring AWS KMS
](#javascript-example-encrypt)
+ [
## Mendekripsi data dengan keyring AWS KMS
](#javascript-example-decrypt)
## Mengenkripsi data dengan keyring AWS KMS
Contoh berikut menunjukkan kepada Anda bagaimana menggunakan AWS Encryption SDK for JavaScript untuk mengenkripsi dan mendekripsi string pendek atau array byte.
Contoh ini menampilkan [AWS KMS keyring](use-kms-keyring.md), jenis keyring yang menggunakan AWS KMS key untuk menghasilkan dan mengenkripsi kunci data. Untuk bantuan membuat AWS KMS key, lihat [Membuat Kunci](https://docs.aws.amazon.com/kms/latest/developerguide/create-keys.html) di *Panduan AWS Key Management Service Pengembang*. Untuk bantuan mengidentifikasi AWS KMS keys dalam AWS KMS gantungan kunci, lihat [Mengidentifikasi AWS KMS keys dalam AWS KMS keyring](use-kms-keyring.md#kms-keyring-id)
Langkah 1: Tetapkan kebijakan komitmen.
Dimulai pada versi 1.7. *x* dari AWS Encryption SDK for JavaScript, Anda dapat mengatur kebijakan komitmen ketika Anda memanggil `buildClient` fungsi baru yang membuat instance AWS Encryption SDK klien. `buildClient`Fungsi ini mengambil nilai yang disebutkan yang mewakili kebijakan komitmen Anda. Ini mengembalikan `decrypt` fungsi yang diperbarui `encrypt` dan memberlakukan kebijakan komitmen Anda saat Anda mengenkripsi dan mendekripsi.
Contoh berikut menggunakan `buildClient` fungsi untuk menentukan [kebijakan komitmen default](migrate-commitment-policy.md),`REQUIRE_ENCRYPT_REQUIRE_DECRYPT`. Anda juga dapat menggunakan `buildClient` untuk membatasi jumlah kunci data terenkripsi dalam pesan terenkripsi. Untuk informasi selengkapnya, lihat [Membatasi kunci data terenkripsi](configure.md#config-limit-keys).
```
import {
KmsKeyringBrowser,
KMS,
getClient,
buildClient,
CommitmentPolicy,
} from '@aws-crypto/client-browser'
const { encrypt, decrypt } = buildClient(
CommitmentPolicy.REQUIRE_ENCRYPT_REQUIRE_DECRYPT
)
```
```
import {
KmsKeyringNode,
buildClient,
CommitmentPolicy,
} from '@aws-crypto/client-node'
const { encrypt, decrypt } = buildClient(
CommitmentPolicy.REQUIRE_ENCRYPT_REQUIRE_DECRYPT
)
```
Langkah 2: Bangun keyring.
Buat AWS KMS keyring untuk enkripsi.
Saat mengenkripsi dengan AWS KMS keyring, Anda harus menentukan *kunci generator, yaitu kunci* yang digunakan untuk menghasilkan kunci data plaintext dan mengenkripsinya. AWS KMS key Anda juga dapat menentukan nol atau lebih *kunci tambahan* yang mengenkripsi kunci data teks biasa yang sama. Keyring mengembalikan kunci data plaintext dan satu salinan terenkripsi dari kunci data tersebut untuk masing-masing AWS KMS key di keyring, termasuk kunci generator. Untuk mendekripsi data, Anda perlu mendekripsi salah satu kunci data terenkripsi.
Untuk menentukan keyring enkripsi di dalam AWS Encryption SDK for JavaScript, Anda dapat menggunakan [pengenal AWS KMS kunci yang didukung](use-kms-keyring.md#kms-keyring-id). AWS KMS keys Contoh ini menggunakan kunci generator, yang diidentifikasi oleh [alias ARN](https://docs.aws.amazon.com/kms/latest/developerguide/concepts.html#key-id-alias-ARN), dan satu kunci tambahan, yang diidentifikasi oleh ARN [kunci](https://docs.aws.amazon.com/kms/latest/developerguide/concepts.html#key-id-key-ARN).
Jika Anda berencana untuk menggunakan kembali AWS KMS keyring Anda untuk mendekripsi, Anda harus menggunakan kunci ARNs untuk mengidentifikasi di AWS KMS keys keyring.
Sebelum menjalankan kode ini, ganti AWS KMS key pengidentifikasi contoh dengan pengidentifikasi yang valid. Anda harus memiliki [izin yang diperlukan untuk menggunakan AWS KMS keys di](use-kms-keyring.md#kms-keyring-permissions) keyring.
Mulailah dengan memberikan kredensil Anda ke browser. AWS Encryption SDK for JavaScript Contohnya menggunakan [webpack. DefinePlugin](https://webpack.js.org/plugins/define-plugin/), yang menggantikan konstanta kredenal dengan kredensil Anda yang sebenarnya. Tetapi Anda dapat menggunakan metode apa pun untuk memberikan kredensil Anda. Kemudian, gunakan kredensialnya untuk membuat klien. AWS KMS
```
declare const credentials: {accessKeyId: string, secretAccessKey:string, sessionToken:string }
const clientProvider = getClient(KMS, {
credentials: {
accessKeyId,
secretAccessKey,
sessionToken
}
})
```
Selanjutnya, tentukan AWS KMS keys untuk kunci generator dan kunci tambahan. Kemudian, buat AWS KMS keyring menggunakan AWS KMS klien dan. AWS KMS keys
```
const generatorKeyId = 'arn:aws:kms:us-west-2:111122223333:alias/EncryptDecrypt'
const keyIds = ['arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab']
const keyring = new KmsKeyringBrowser({ clientProvider, generatorKeyId, keyIds })
```
```
const generatorKeyId = 'arn:aws:kms:us-west-2:111122223333:alias/EncryptDecrypt'
const keyIds = ['arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab']
const keyring = new KmsKeyringNode({ generatorKeyId, keyIds })
```
Langkah 3: Atur konteks enkripsi.
[Konteks enkripsi adalah data](concepts.md#encryption-context) otentikasi tambahan yang sewenang-wenang dan tidak rahasia. Ketika Anda menyediakan konteks enkripsi pada enkripsi, AWS Encryption SDK kriptografis mengikat konteks enkripsi ke ciphertext sehingga konteks enkripsi yang sama diperlukan untuk mendekripsi data. Menggunakan konteks enkripsi adalah opsional, tetapi kami merekomendasikannya sebagai praktik terbaik.
Buat objek sederhana yang mencakup pasangan konteks enkripsi. Kunci dan nilai dalam setiap pasangan harus berupa string.
```
const context = {
stage: 'demo',
purpose: 'simple demonstration app',
origin: 'us-west-2'
}
```
```
const context = {
stage: 'demo',
purpose: 'simple demonstration app',
origin: 'us-west-2'
}
```
Langkah 4: Enkripsi data.
Untuk mengenkripsi data plaintext, panggil fungsi. `encrypt` Masukkan AWS KMS keyring, data plaintext, dan konteks enkripsi.
`encrypt`Fungsi mengembalikan [pesan terenkripsi](concepts.md#message) (`result`) yang berisi data terenkripsi, kunci data terenkripsi, dan metadata penting, termasuk konteks enkripsi dan tanda tangan.
Anda dapat [mendekripsi pesan terenkripsi ini](#javascript-example-decrypt) dengan menggunakan AWS Encryption SDK untuk bahasa pemrograman yang didukung.
```
const plaintext = new Uint8Array([1, 2, 3, 4, 5])
const { result } = await encrypt(keyring, plaintext, { encryptionContext: context })
```
```
const plaintext = 'asdf'
const { result } = await encrypt(keyring, plaintext, { encryptionContext: context })
```
## Mendekripsi data dengan keyring AWS KMS
Anda dapat menggunakan AWS Encryption SDK for JavaScript untuk mendekripsi pesan terenkripsi dan memulihkan data asli.
Dalam contoh ini, kami mendekripsi data yang kami enkripsi dalam contoh. [Mengenkripsi data dengan keyring AWS KMS](#javascript-example-encrypt)
Langkah 1: Tetapkan kebijakan komitmen.
Dimulai pada versi 1.7. *x* dari AWS Encryption SDK for JavaScript, Anda dapat mengatur kebijakan komitmen ketika Anda memanggil `buildClient` fungsi baru yang membuat instance AWS Encryption SDK klien. `buildClient`Fungsi ini mengambil nilai yang disebutkan yang mewakili kebijakan komitmen Anda. Ini mengembalikan `decrypt` fungsi yang diperbarui `encrypt` dan memberlakukan kebijakan komitmen Anda saat Anda mengenkripsi dan mendekripsi.
Contoh berikut menggunakan `buildClient` fungsi untuk menentukan [kebijakan komitmen default](migrate-commitment-policy.md),`REQUIRE_ENCRYPT_REQUIRE_DECRYPT`. Anda juga dapat menggunakan `buildClient` untuk membatasi jumlah kunci data terenkripsi dalam pesan terenkripsi. Untuk informasi selengkapnya, lihat [Membatasi kunci data terenkripsi](configure.md#config-limit-keys).
```
import {
KmsKeyringBrowser,
KMS,
getClient,
buildClient,
CommitmentPolicy,
} from '@aws-crypto/client-browser'
const { encrypt, decrypt } = buildClient(
CommitmentPolicy.REQUIRE_ENCRYPT_REQUIRE_DECRYPT
)
```
```
import {
KmsKeyringNode,
buildClient,
CommitmentPolicy,
} from '@aws-crypto/client-node'
const { encrypt, decrypt } = buildClient(
CommitmentPolicy.REQUIRE_ENCRYPT_REQUIRE_DECRYPT
)
```
Langkah 2: Bangun keyring.
Untuk mendekripsi data, masukkan [pesan terenkripsi](concepts.md#message) (`result`) yang dikembalikan fungsi. `encrypt` Pesan terenkripsi mencakup data terenkripsi, kunci data terenkripsi, dan metadata penting, termasuk konteks enkripsi dan tanda tangan.
Anda juga harus menentukan [AWS KMS keyring](use-kms-keyring.md) saat mendekripsi. Anda dapat menggunakan keyring yang sama yang digunakan untuk mengenkripsi data atau keyring yang berbeda. Agar berhasil, setidaknya satu AWS KMS key di keyring dekripsi harus dapat mendekripsi salah satu kunci data terenkripsi dalam pesan terenkripsi. Karena tidak ada kunci data yang dihasilkan, Anda tidak perlu menentukan kunci generator dalam keyring dekripsi. Jika Anda melakukannya, kunci generator dan kunci tambahan diperlakukan dengan cara yang sama.
[Untuk menentukan AWS KMS key untuk keyring dekripsi di AWS Encryption SDK for JavaScript, Anda harus menggunakan kunci ARN.](https://docs.aws.amazon.com/kms/latest/developerguide/concepts.html#key-id-key-ARN) Kalau tidak, AWS KMS key tidak dikenali. Untuk bantuan mengidentifikasi AWS KMS keys dalam AWS KMS gantungan kunci, lihat [Mengidentifikasi AWS KMS keys dalam AWS KMS keyring](use-kms-keyring.md#kms-keyring-id)
Jika Anda menggunakan keyring yang sama untuk mengenkripsi dan mendekripsi, gunakan kunci ARNs untuk mengidentifikasi di keyring. AWS KMS keys
Dalam contoh ini, kami membuat keyring yang hanya menyertakan salah satu dari keyring enkripsi. AWS KMS keys Sebelum menjalankan kode ini, ganti contoh kunci ARN dengan yang valid. Anda harus memiliki `kms:Decrypt` izin pada AWS KMS key.
Mulailah dengan memberikan kredensil Anda ke browser. AWS Encryption SDK for JavaScript Contohnya menggunakan [webpack. DefinePlugin](https://webpack.js.org/plugins/define-plugin/), yang menggantikan konstanta kredenal dengan kredensil Anda yang sebenarnya. Tetapi Anda dapat menggunakan metode apa pun untuk memberikan kredensil Anda. Kemudian, gunakan kredensialnya untuk membuat klien. AWS KMS
```
declare const credentials: {accessKeyId: string, secretAccessKey:string, sessionToken:string }
const clientProvider = getClient(KMS, {
credentials: {
accessKeyId,
secretAccessKey,
sessionToken
}
})
```
Selanjutnya, buat AWS KMS keyring menggunakan AWS KMS klien. Contoh ini hanya menggunakan salah satu AWS KMS keys dari keyring enkripsi.
```
const keyIds = ['arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab']
const keyring = new KmsKeyringBrowser({ clientProvider, keyIds })
```
```
const keyIds = ['arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab']
const keyring = new KmsKeyringNode({ keyIds })
```
Langkah 3: Dekripsi data.
Selanjutnya, panggil `decrypt` fungsinya. Masukkan keyring dekripsi yang baru saja Anda buat (`keyring`) dan [pesan terenkripsi](concepts.md#message) yang dikembalikan oleh fungsi (). `encrypt` `result` AWS Encryption SDK Menggunakan keyring untuk mendekripsi salah satu kunci data terenkripsi. Kemudian menggunakan kunci data plaintext untuk mendekripsi data.
Jika panggilan berhasil, `plaintext` bidang berisi data plaintext (didekripsi). `messageHeader`Bidang berisi metadata tentang proses dekripsi, termasuk konteks enkripsi yang digunakan untuk mendekripsi data.
```
const { plaintext, messageHeader } = await decrypt(keyring, result)
```
```
const { plaintext, messageHeader } = await decrypt(keyring, result)
```
Langkah 4: Verifikasi konteks enkripsi.
[Konteks enkripsi](concepts.md#encryption-context) yang digunakan untuk mendekripsi data disertakan dalam header pesan (`messageHeader`) yang dikembalikan `decrypt` fungsi. Sebelum aplikasi Anda mengembalikan data plaintext, verifikasi bahwa konteks enkripsi yang Anda berikan saat mengenkripsi disertakan dalam konteks enkripsi yang digunakan saat mendekripsi. Ketidakcocokan mungkin menunjukkan bahwa data telah dirusak, atau bahwa Anda tidak mendekripsi ciphertext yang tepat.
Saat memverifikasi konteks enkripsi, tidak memerlukan kecocokan persis. Saat Anda menggunakan algoritma enkripsi dengan penandatanganan, [pengelola materi kriptografi](concepts.md#crypt-materials-manager) (CMM) menambahkan kunci penandatanganan publik ke konteks enkripsi sebelum mengenkripsi pesan. Tetapi semua pasangan konteks enkripsi yang Anda kirimkan harus disertakan dalam konteks enkripsi yang dikembalikan.
Pertama, dapatkan konteks enkripsi dari header pesan. Kemudian, verifikasi bahwa setiap pasangan kunci-nilai dalam konteks enkripsi asli (`context`) cocok dengan pasangan kunci-nilai dalam konteks enkripsi yang dikembalikan (). `encryptionContext`
```
const { encryptionContext } = messageHeader
Object
.entries(context)
.forEach(([key, value]) => {
if (encryptionContext[key] !== value) throw new Error('Encryption Context does not match expected values')
})
```
```
const { encryptionContext } = messageHeader
Object
.entries(context)
.forEach(([key, value]) => {
if (encryptionContext[key] !== value) throw new Error('Encryption Context does not match expected values')
})
```
Jika pemeriksaan konteks enkripsi berhasil, Anda dapat mengembalikan data teks biasa.
# AWS Encryption SDK for Python
Topik ini menjelaskan cara menginstal dan menggunakan AWS Encryption SDK for Python. Untuk detail tentang pemrograman dengan AWS Encryption SDK for Python, lihat [aws-encryption-sdk-python](https://github.com/aws/aws-encryption-sdk-python/)repositori di. GitHub Untuk dokumentasi API, lihat [Membaca Dokumen.](https://aws-encryption-sdk-python.readthedocs.io/en/latest/)
**Topics**
+ [
## Prasyarat
](#python-prerequisites)
+ [
## Penginstalan
](#python-installation)
+ [Contoh](python-example-code.md)
## Prasyarat
Sebelum Anda menginstal AWS Encryption SDK for Python, pastikan Anda memiliki prasyarat berikut.
**Versi Python yang didukung**
Python 3.8 atau yang lebih baru diperlukan oleh AWS Encryption SDK for Python versi 3.2.0 dan yang lebih baru.
[AWS Cryptographic Material Providers Library](https://github.com/aws/aws-cryptographic-material-providers-library) (MPL) adalah dependensi opsional untuk yang AWS Encryption SDK for Python diperkenalkan di versi 4. *x*. Jika Anda berniat menginstal MPL, Anda harus menggunakan Python 3.11 atau yang lebih baru.
Versi sebelumnya dari AWS Encryption SDK dukungan Python 2.7 dan Python 3.4 dan yang lebih baru, tetapi kami menyarankan Anda menggunakan versi terbaru dari versi. AWS Encryption SDK
Untuk mengunduh Python, lihat [Unduh Python](https://www.python.org/downloads/).
**Alat instalasi pip untuk Python**
`pip`termasuk dalam Python 3.6 dan versi yang lebih baru, meskipun Anda mungkin ingin memutakhirkannya. Untuk informasi selengkapnya tentang memutakhirkan atau menginstal`pip`, lihat [Instalasi](https://pip.pypa.io/en/latest/installation/) di `pip` dokumentasi.
## Penginstalan
Instal versi terbaru dari file AWS Encryption SDK for Python.
**catatan**
[Semua versi yang AWS Encryption SDK for Python lebih awal dari 3.0.0 sedang dalam fase. end-of-support](https://docs.aws.amazon.com/sdkref/latest/guide/maint-policy.html#version-life-cycle)
Anda dapat memperbarui dengan aman dari versi 2.0. *x* dan yang lebih baru ke versi terbaru AWS Encryption SDK tanpa kode atau perubahan data. Namun, [fitur keamanan baru](about-versions.md#version-2) diperkenalkan di versi 2.0. *x* tidak kompatibel ke belakang. Untuk memperbarui dari versi lebih awal dari 1.7. *x* ke versi 2.0. *x* dan yang lebih baru, Anda harus terlebih dahulu memperbarui ke yang terbaru 1. *x* versi AWS Encryption SDK. Lihat perinciannya di [Migrasi Anda AWS Encryption SDK](migration.md).
Gunakan `pip` untuk menginstal AWS Encryption SDK for Python, seperti yang ditunjukkan dalam contoh berikut.
**Pasang versi terbaru**
```
pip install "aws-encryption-sdk[MPL]"
```
`[MPL]`Akhiran menginstal [Perpustakaan Penyedia Materi AWS Kriptografi](https://github.com/aws/aws-cryptographic-material-providers-library) (MPL). MPL berisi konstruksi untuk mengenkripsi dan mendekripsi data Anda. MPL adalah dependensi opsional untuk AWS Encryption SDK for Python diperkenalkan di versi 4. *x*. Kami sangat merekomendasikan menginstal MPL. Namun, jika Anda tidak berniat menggunakan MPL, Anda dapat menghilangkan akhiran. `[MPL]`
Untuk detail selengkapnya tentang penggunaan pip untuk menginstal dan memutakhirkan paket, lihat [Menginstal Paket](https://packaging.python.org/tutorials/installing-packages/).
AWS Encryption SDK for Python Membutuhkan [perpustakaan kriptografi](https://cryptography.io/en/latest/) (pyca/kriptografi) di semua platform. Semua versi menginstal dan membangun `cryptography` perpustakaan `pip` secara otomatis di Windows. `pip`8.1 dan yang lebih baru secara otomatis menginstal dan membangun `cryptography` di Linux. Jika Anda menggunakan versi sebelumnya `pip` dan lingkungan Linux Anda tidak memiliki alat yang diperlukan untuk membangun `cryptography` perpustakaan, Anda perlu menginstalnya. Untuk informasi selengkapnya, lihat [Membangun Kriptografi di Linux](https://cryptography.io/en/latest/installation.html#building-cryptography-on-linux).
Versi 1.10.0 dan 2.5.0 dari AWS Encryption SDK for Python pin ketergantungan [kriptografi](https://cryptography.io/en/latest/) antara 2.5.0 dan 3.3.2. Versi lain dari AWS Encryption SDK for Python menginstal versi terbaru kriptografi. Jika Anda memerlukan versi kriptografi lebih lambat dari 3.3.2, kami sarankan Anda menggunakan versi utama terbaru dari. AWS Encryption SDK for Python
Untuk versi pengembangan terbaru AWS Encryption SDK for Python, buka [aws-encryption-sdk-python](https://github.com/aws/aws-encryption-sdk-python/)repositori di. GitHub
Setelah Anda menginstal AWS Encryption SDK for Python, mulailah dengan melihat [kode contoh Python dalam panduan](python-example-code.md) ini.
# AWS Encryption SDK for Python kode contoh
Contoh berikut menunjukkan cara menggunakan untuk mengenkripsi dan AWS Encryption SDK for Python mendekripsi data.
Contoh di bagian ini menunjukkan cara menggunakan versi 4. *x* dari AWS Encryption SDK for Python dengan ketergantungan [Perpustakaan Penyedia Materi Kriptografi](https://github.com/aws/aws-cryptographic-material-providers-library) opsional ()`aws-cryptographic-material-providers`. Untuk melihat contoh yang menggunakan versi sebelumnya, atau penginstalan tanpa pustaka penyedia materi (MPL), temukan rilis Anda di daftar [Rilis [aws-encryption-sdk-python](https://github.com/aws/aws-encryption-sdk-python/)](https://github.com/aws/aws-encryption-sdk-python/releases)repositori di. GitHub
Bila Anda menggunakan versi 4. *x* dari AWS Encryption SDK for Python dengan MPL, ia menggunakan [keyrings](choose-keyring.md) untuk melakukan enkripsi [amplop](concepts.md#envelope-encryption). AWS Encryption SDK Ini menyediakan gantungan kunci yang kompatibel dengan penyedia kunci utama yang Anda gunakan di versi sebelumnya. Untuk informasi selengkapnya, lihat [Kompatibilitas keyring](choose-keyring.md#keyring-compatibility). Untuk contoh tentang migrasi dari penyedia kunci utama ke keyrings, lihat [Contoh Migrasi](https://github.com/aws/aws-encryption-sdk-python/tree/master/examples/src/migration) di `aws-encryption-sdk-python` repositori pada; GitHub
**Topics**
+ [String](#python-example-strings)
+ [Aliran byte](#python-example-streams)
## Mengenkripsi dan mendekripsi string
Contoh berikut menunjukkan cara menggunakan untuk mengenkripsi dan AWS Encryption SDK mendekripsi string. Contoh ini menggunakan [AWS KMS keyring](use-kms-keyring.md) dengan kunci KMS enkripsi simetris.
Contoh ini membuat instance AWS Encryption SDK klien dengan [kebijakan komitmen default](migrate-commitment-policy.md),. `REQUIRE_ENCRYPT_REQUIRE_DECRYPT` Untuk informasi selengkapnya, lihat [Menetapkan kebijakan komitmen Anda](migrate-commitment-policy.md).
```
# Copyright Amazon.com Inc. or its affiliates. All Rights Reserved.
# SPDX-License-Identifier: Apache-2.0
"""
This example sets up the KMS Keyring
The AWS KMS keyring uses symmetric encryption KMS keys to generate, encrypt and
decrypt data keys. This example creates a KMS Keyring and then encrypts a custom input EXAMPLE_DATA
with an encryption context. This example also includes some sanity checks for demonstration:
1. Ciphertext and plaintext data are not the same
2. Encryption context is correct in the decrypted message header
3. Decrypted plaintext value matches EXAMPLE_DATA
These sanity checks are for demonstration in the example only. You do not need these in your code.
AWS KMS keyrings can be used independently or in a multi-keyring with other keyrings
of the same or a different type.
"""
import boto3
from aws_cryptographic_material_providers.mpl import AwsCryptographicMaterialProviders
from aws_cryptographic_material_providers.mpl.config import MaterialProvidersConfig
from aws_cryptographic_material_providers.mpl.models import CreateAwsKmsKeyringInput
from aws_cryptographic_material_providers.mpl.references import IKeyring
from typing import Dict # noqa pylint: disable=wrong-import-order
import aws_encryption_sdk
from aws_encryption_sdk import CommitmentPolicy
EXAMPLE_DATA: bytes = b"Hello World"
def encrypt_and_decrypt_with_keyring(
kms_key_id: str
):
"""Demonstrate an encrypt/decrypt cycle using an AWS KMS keyring.
Usage: encrypt_and_decrypt_with_keyring(kms_key_id)
:param kms_key_id: KMS Key identifier for the KMS key you want to use for encryption and
decryption of your data keys.
:type kms_key_id: string
"""
# 1. Instantiate the encryption SDK client.
# This builds the client with the REQUIRE_ENCRYPT_REQUIRE_DECRYPT commitment policy,
# which enforces that this client only encrypts using committing algorithm suites and enforces
# that this client will only decrypt encrypted messages that were created with a committing
# algorithm suite.
# This is the default commitment policy if you were to build the client as
# `client = aws_encryption_sdk.EncryptionSDKClient()`.
client = aws_encryption_sdk.EncryptionSDKClient(
commitment_policy=CommitmentPolicy.REQUIRE_ENCRYPT_REQUIRE_DECRYPT
)
# 2. Create a boto3 client for KMS.
kms_client = boto3.client('kms', region_name="us-west-2")
# 3. Optional: create encryption context.
# Remember that your encryption context is NOT SECRET.
encryption_context: Dict[str, str] = {
"encryption": "context",
"is not": "secret",
"but adds": "useful metadata",
"that can help you": "be confident that",
"the data you are handling": "is what you think it is",
}
# 4. Create your keyring
mat_prov: AwsCryptographicMaterialProviders = AwsCryptographicMaterialProviders(
config=MaterialProvidersConfig()
)
keyring_input: CreateAwsKmsKeyringInput = CreateAwsKmsKeyringInput(
kms_key_id=kms_key_id,
kms_client=kms_client
)
kms_keyring: IKeyring = mat_prov.create_aws_kms_keyring(
input=keyring_input
)
# 5. Encrypt the data with the encryptionContext.
ciphertext, _ = client.encrypt(
source=EXAMPLE_DATA,
keyring=kms_keyring,
encryption_context=encryption_context
)
# 6. Demonstrate that the ciphertext and plaintext are different.
# (This is an example for demonstration; you do not need to do this in your own code.)
assert ciphertext != EXAMPLE_DATA, \
"Ciphertext and plaintext data are the same. Invalid encryption"
# 7. Decrypt your encrypted data using the same keyring you used on encrypt.
plaintext_bytes, _ = client.decrypt(
source=ciphertext,
keyring=kms_keyring,
# Provide the encryption context that was supplied to the encrypt method
encryption_context=encryption_context,
)
# 8. Demonstrate that the decrypted plaintext is identical to the original plaintext.
# (This is an example for demonstration; you do not need to do this in your own code.)
assert plaintext_bytes == EXAMPLE_DATA, \
"Decrypted plaintext should be identical to the original plaintext. Invalid decryption"
```
## Mengenkripsi dan mendekripsi aliran byte
Contoh berikut menunjukkan cara menggunakan untuk mengenkripsi dan AWS Encryption SDK mendekripsi aliran byte. Contoh ini menggunakan [keyring Raw AES](use-raw-aes-keyring.md).
Contoh ini membuat instance AWS Encryption SDK klien dengan [kebijakan komitmen default](migrate-commitment-policy.md),. `REQUIRE_ENCRYPT_REQUIRE_DECRYPT` Lihat informasi yang lebih lengkap di [Menetapkan kebijakan komitmen Anda](migrate-commitment-policy.md).
```
# Copyright Amazon.com Inc. or its affiliates. All Rights Reserved.
# SPDX-License-Identifier: Apache-2.0
"""
This example demonstrates file streaming for encryption and decryption.
File streaming is useful when the plaintext or ciphertext file/data is too large to load into
memory. Therefore, the AWS Encryption SDK allows users to stream the data, instead of loading it
all at once in memory. In this example, we demonstrate file streaming for encryption and decryption
using a Raw AES keyring. However, you can use any keyring with streaming.
This example creates a Raw AES Keyring and then encrypts an input stream from the file
`plaintext_filename` with an encryption context to an output (encrypted) file `ciphertext_filename`.
It then decrypts the ciphertext from `ciphertext_filename` to a new file `decrypted_filename`.
This example also includes some sanity checks for demonstration:
1. Ciphertext and plaintext data are not the same
2. Encryption context is correct in the decrypted message header
3. Decrypted plaintext value matches EXAMPLE_DATA
These sanity checks are for demonstration in the example only. You do not need these in your code.
See raw_aes_keyring_example.py in the same directory for another raw AES keyring example
in the AWS Encryption SDK for Python.
"""
import filecmp
import secrets
from aws_cryptographic_material_providers.mpl import AwsCryptographicMaterialProviders
from aws_cryptographic_material_providers.mpl.config import MaterialProvidersConfig
from aws_cryptographic_material_providers.mpl.models import AesWrappingAlg, CreateRawAesKeyringInput
from aws_cryptographic_material_providers.mpl.references import IKeyring
from typing import Dict # noqa pylint: disable=wrong-import-order
import aws_encryption_sdk
from aws_encryption_sdk import CommitmentPolicy
def encrypt_and_decrypt_with_keyring(
plaintext_filename: str,
ciphertext_filename: str,
decrypted_filename: str
):
"""Demonstrate a streaming encrypt/decrypt cycle.
Usage: encrypt_and_decrypt_with_keyring(plaintext_filename
ciphertext_filename
decrypted_filename)
:param plaintext_filename: filename of the plaintext data
:type plaintext_filename: string
:param ciphertext_filename: filename of the ciphertext data
:type ciphertext_filename: string
:param decrypted_filename: filename of the decrypted data
:type decrypted_filename: string
"""
# 1. Instantiate the encryption SDK client.
# This builds the client with the REQUIRE_ENCRYPT_REQUIRE_DECRYPT commitment policy,
# which enforces that this client only encrypts using committing algorithm suites and enforces
# that this client will only decrypt encrypted messages that were created with a committing
# algorithm suite.
# This is the default commitment policy if you were to build the client as
# `client = aws_encryption_sdk.EncryptionSDKClient()`.
client = aws_encryption_sdk.EncryptionSDKClient(
commitment_policy=CommitmentPolicy.REQUIRE_ENCRYPT_REQUIRE_DECRYPT
)
# 2. The key namespace and key name are defined by you.
# and are used by the Raw AES keyring to determine
# whether it should attempt to decrypt an encrypted data key.
key_name_space = "Some managed raw keys"
key_name = "My 256-bit AES wrapping key"
# 3. Optional: create encryption context.
# Remember that your encryption context is NOT SECRET.
encryption_context: Dict[str, str] = {
"encryption": "context",
"is not": "secret",
"but adds": "useful metadata",
"that can help you": "be confident that",
"the data you are handling": "is what you think it is",
}
# 4. Generate a 256-bit AES key to use with your keyring.
# In practice, you should get this key from a secure key management system such as an HSM.
# Here, the input to secrets.token_bytes() = 32 bytes = 256 bits
static_key = secrets.token_bytes(32)
# 5. Create a Raw AES keyring
# We choose to use a raw AES keyring, but any keyring can be used with streaming.
mat_prov: AwsCryptographicMaterialProviders = AwsCryptographicMaterialProviders(
config=MaterialProvidersConfig()
)
keyring_input: CreateRawAesKeyringInput = CreateRawAesKeyringInput(
key_namespace=key_name_space,
key_name=key_name,
wrapping_key=static_key,
wrapping_alg=AesWrappingAlg.ALG_AES256_GCM_IV12_TAG16
)
raw_aes_keyring: IKeyring = mat_prov.create_raw_aes_keyring(
input=keyring_input
)
# 6. Encrypt the data stream with the encryptionContext
with open(plaintext_filename, 'rb') as pt_file, open(ciphertext_filename, 'wb') as ct_file:
with client.stream(
mode='e',
source=pt_file,
keyring=raw_aes_keyring,
encryption_context=encryption_context
) as encryptor:
for chunk in encryptor:
ct_file.write(chunk)
# 7. Demonstrate that the ciphertext and plaintext are different.
# (This is an example for demonstration; you do not need to do this in your own code.)
assert not filecmp.cmp(plaintext_filename, ciphertext_filename), \
"Ciphertext and plaintext data are the same. Invalid encryption"
# 8. Decrypt your encrypted data stream using the same keyring you used on encrypt.
with open(ciphertext_filename, 'rb') as ct_file, open(decrypted_filename, 'wb') as pt_file:
with client.stream(
mode='d',
source=ct_file,
keyring=raw_aes_keyring,
encryption_context=encryption_context
) as decryptor:
for chunk in decryptor:
pt_file.write(chunk)
# 10. Demonstrate that the decrypted plaintext is identical to the original plaintext.
# (This is an example for demonstration; you do not need to do this in your own code.)
assert filecmp.cmp(plaintext_filename, decrypted_filename), \
"Decrypted plaintext should be identical to the original plaintext. Invalid decryption"
```
# AWS Encryption SDK untuk Rust
Topik ini menjelaskan cara menginstal dan menggunakan AWS Encryption SDK for Rust. Untuk detail tentang pemrograman dengan AWS Encryption SDK for Rust, lihat direktori [Rust](https://github.com/aws/aws-encryption-sdk-dafny/tree/mainline/AwsEncryptionSDK/runtimes/rust/) dari aws-encryption-sdk repositori di. GitHub
The AWS Encryption SDK for Rust berbeda dari beberapa implementasi bahasa pemrograman lainnya dengan AWS Encryption SDK cara berikut:
+ Tidak ada dukungan untuk [caching kunci data](data-key-caching.md). Namun, AWS Encryption SDK for Rust mendukung [keyring AWS KMS Hierarchical, solusi](use-hierarchical-keyring.md) caching bahan kriptografi alternatif.
+ Tidak ada dukungan untuk streaming data
The AWS Encryption SDK for Rust mencakup semua fitur keamanan yang diperkenalkan dalam versi 2.0. *x* dan yang lebih baru dari implementasi bahasa lain dari. AWS Encryption SDK Namun, jika Anda menggunakan for Rust AWS Encryption SDK untuk mendekripsi data yang dienkripsi oleh pra-2.0. *x* versi implementasi bahasa lain dari AWS Encryption SDK, Anda mungkin perlu menyesuaikan [kebijakan komitmen](concepts.md#commitment-policy) Anda. Lihat perinciannya di [Cara menetapkan kebijakan komitmen Anda](migrate-commitment-policy.md#migrate-commitment-step1).
The AWS Encryption SDK for Rust adalah produk dari AWS Encryption SDK in [Dafny](https://github.com/dafny-lang/dafny/blob/master/README.md), bahasa verifikasi formal di mana Anda menulis spesifikasi, kode untuk mengimplementasikannya, dan bukti untuk mengujinya. Hasilnya adalah perpustakaan yang mengimplementasikan fitur-fitur AWS Encryption SDK dalam kerangka kerja yang menjamin kebenaran fungsional.
**Pelajari Lebih Lanjut**
+ Untuk contoh yang menunjukkan cara mengonfigurasi opsi di AWS Encryption SDK, seperti menentukan rangkaian algoritme alternatif, membatasi kunci data terenkripsi, dan menggunakan kunci AWS KMS Multi-region, lihat. [Mengkonfigurasi AWS Encryption SDK](configure.md)
+ Untuk contoh yang menunjukkan cara mengonfigurasi dan menggunakan AWS Encryption SDK untuk Rust, lihat [contoh Rust](https://github.com/aws/aws-encryption-sdk-dafny/tree/mainline/AwsEncryptionSDK/runtimes/rust/examples) di aws-encryption-sdk repositori aktif. GitHub
**Topics**
+ [
## Prasyarat
](#prerequisites-rust)
+ [
## Penginstalan
](#rust-installation)
+ [Contoh](rust-examples.md)
## Prasyarat
Sebelum Anda menginstal AWS Encryption SDK untuk Rust, pastikan Anda memiliki prasyarat berikut.
**Instal Rust dan Cargo**
Instal rilis stabil [Rust](https://www.rust-lang.org/) saat ini menggunakan [rustup](https://rustup.rs/).
Untuk informasi lebih lanjut tentang mengunduh dan menginstal rustup, lihat [prosedur instalasi](https://doc.rust-lang.org/cargo/getting-started/installation.html) di The Cargo Book.
## Penginstalan
The AWS Encryption SDK for Rust tersedia sebagai [https://crates.io/crates/aws-esdk](https://crates.io/crates/aws-esdk)peti di Crates.io. Untuk detail tentang menginstal dan membangun AWS Encryption SDK untuk Rust, lihat [README.md di repositori](https://github.com/aws/aws-encryption-sdk/tree/mainline) di. aws-encryption-sdk GitHub
Anda dapat menginstal AWS Encryption SDK for Rust dengan cara berikut.
**Secara manual**
Untuk menginstal AWS Encryption SDK for Rust, kloning atau unduh [aws-encryption-sdk](https://github.com/aws/aws-encryption-sdk/tree/mainline) GitHub repositori.
**Menggunakan Crates.io**
Jalankan perintah Cargo berikut di direktori proyek Anda:
```
cargo add aws-esdk
```
Atau tambahkan baris berikut ke Cargo.toml Anda:
```
aws-esdk = ""
```
# AWS Encryption SDK untuk kode contoh Rust
Contoh berikut menunjukkan pola pengkodean dasar yang Anda gunakan saat memprogram dengan AWS Encryption SDK for Rust. Secara khusus, Anda membuat instance perpustakaan AWS Encryption SDK dan penyedia materi. Kemudian, sebelum memanggil setiap metode, Anda membuat instance objek yang mendefinisikan input untuk metode tersebut.
Untuk contoh yang menunjukkan cara mengonfigurasi opsi di AWS Encryption SDK, seperti menentukan rangkaian algoritme alternatif dan membatasi kunci data terenkripsi, lihat [contoh Rust di repositori](https://github.com/aws/aws-encryption-sdk-dafny/tree/mainline/AwsEncryptionSDK/runtimes/rust/examples/) aktif. aws-encryption-sdk GitHub
## Mengenkripsi dan mendekripsi data di for Rust AWS Encryption SDK
Contoh ini menunjukkan pola dasar untuk mengenkripsi dan mendekripsi data. Ini mengenkripsi file kecil dengan kunci data yang dilindungi oleh satu kunci AWS KMS pembungkus.
**Langkah 1: Instantiate. AWS Encryption SDK**
Anda akan menggunakan metode dalam AWS Encryption SDK untuk mengenkripsi dan mendekripsi data.
```
let esdk_config = AwsEncryptionSdkConfig::builder().build()?;
let esdk_client = esdk_client::Client::from_conf(esdk_config)?;
```
**Langkah 2: Buat AWS KMS klien.**
```
let sdk_config = aws_config::load_defaults(aws_config::BehaviorVersion::latest()).await;
let kms_client = aws_sdk_kms::Client::new(&sdk_config);
```
**Opsional: Buat konteks enkripsi Anda.**
```
let encryption_context = HashMap::from([
("encryption".to_string(), "context".to_string()),
("is not".to_string(), "secret".to_string()),
("but adds".to_string(), "useful metadata".to_string()),
("that can help you".to_string(), "be confident that".to_string()),
("the data you are handling".to_string(), "is what you think it is".to_string()),
]);
```
**Langkah 3: Buat instance perpustakaan penyedia materi.**
Anda akan menggunakan metode di pustaka penyedia materi untuk membuat keyrings yang menentukan kunci mana yang melindungi data Anda.
```
let mpl_config = MaterialProvidersConfig::builder().build()?;
let mpl = mpl_client::Client::from_conf(mpl_config)?;
```
**Langkah 4: Buat AWS KMS keyring.**
Untuk membuat keyring, panggil metode keyring dengan objek input keyring. Contoh ini menggunakan `create_aws_kms_keyring()` metode dan menentukan satu kunci KMS.
```
let kms_keyring = mpl
.create_aws_kms_keyring()
.kms_key_id(kms_key_id)
.kms_client(kms_client)
.send()
.await?;
```
**Langkah 5: Enkripsi plaintext.**
```
let plaintext = example_data.as_bytes();
let encryption_response = esdk_client.encrypt()
.plaintext(plaintext)
.keyring(kms_keyring.clone())
.encryption_context(encryption_context.clone())
.send()
.await?;
let ciphertext = encryption_response
.ciphertext
.expect("Unable to unwrap ciphertext from encryption response");
```
**Langkah 6: Dekripsi data terenkripsi Anda menggunakan keyring yang sama yang Anda gunakan pada enkripsi.**
```
let decryption_response = esdk_client.decrypt()
.ciphertext(ciphertext)
.keyring(kms_keyring)
// Provide the encryption context that was supplied to the encrypt method
.encryption_context(encryption_context)
.send()
.await?;
let decrypted_plaintext = decryption_response
.plaintext
.expect("Unable to unwrap plaintext from decryption response");
```
# AWS Encryption SDK antarmuka baris perintah
AWS Encryption SDK Command Line Interface (AWS Encryption CLI) memungkinkan Anda untuk menggunakan AWS Encryption SDK untuk mengenkripsi dan mendekripsi data secara interaktif di baris perintah dan skrip. Anda tidak perlu keahlian kriptografi atau pemrograman.
**catatan**
[Versi CLI AWS Enkripsi lebih awal dari 4.0.0 sedang dalam fase. end-of-support](https://docs.aws.amazon.com/sdkref/latest/guide/maint-policy.html#version-life-cycle)
Anda dapat memperbarui dengan aman dari versi 2.1. *x* dan yang lebih baru ke versi terbaru CLI AWS Enkripsi tanpa perubahan kode atau data apa pun. Namun, [fitur keamanan baru](about-versions.md#version-2) diperkenalkan di versi 2.1. *x* tidak kompatibel ke belakang. Untuk memperbarui dari versi 1.7. *x* atau sebelumnya, Anda harus terlebih dahulu memperbarui ke yang terbaru 1. *x* versi CLI AWS Enkripsi. Lihat perinciannya di [Migrasi Anda AWS Encryption SDK](migration.md).
Fitur keamanan baru awalnya dirilis dalam AWS Enkripsi CLI versi 1.7. *x* dan 2.0. *x*. Namun, AWS Enkripsi CLI versi 1.8. *x* menggantikan versi 1.7. *x* dan AWS Enkripsi CLI 2.1. *x* menggantikan 2.0. *x*. Untuk detailnya, lihat [penasihat keamanan](https://github.com/aws/aws-encryption-sdk-cli/security/advisories/GHSA-2xwp-m7mq-7q3r) yang relevan di [aws-encryption-sdk-cli](https://github.com/aws/aws-encryption-sdk-cli/)repositori di. GitHub
Seperti semua implementasi AWS Encryption SDK, CLI AWS Enkripsi menawarkan fitur perlindungan data tingkat lanjut. [Ini termasuk [enkripsi amplop](https://docs.aws.amazon.com/encryption-sdk/latest/developer-guide/how-it-works.html#envelope-encryption), data otentikasi tambahan (AAD), dan [rangkaian algoritma](https://docs.aws.amazon.com/encryption-sdk/latest/developer-guide/supported-algorithms.html) kunci simetris yang aman, diautentikasi, seperti AES-GCM 256-bit dengan derivasi kunci, komitmen kunci, dan penandatanganan.](concepts.md#key-commitment)
CLI AWS Enkripsi dibangun di atas [AWS Encryption SDK for Python](python.md)dan didukung di Linux, macOS, dan Windows. Anda dapat menjalankan perintah dan skrip untuk mengenkripsi dan mendekripsi data Anda di shell pilihan Anda di Linux atau macOS, di jendela Command Prompt (cmd.exe) di Windows, dan di konsol di sistem apa pun. PowerShell
Semua implementasi khusus bahasa, termasuk AWS CLI Enkripsi AWS Encryption SDK, dapat dioperasikan secara interoperable. Misalnya, Anda dapat mengenkripsi data dengan [AWS Encryption SDK for Java](java.md)dan mendekripsi dengan CLI Enkripsi AWS .
Topik ini memperkenalkan CLI AWS Enkripsi, menjelaskan cara menginstal dan menggunakannya, dan memberikan beberapa contoh untuk membantu Anda memulai. Untuk memulai dengan cepat, lihat [Cara Mengenkripsi dan Mendekripsi Data Anda dengan AWS CLI Enkripsi](https://aws.amazon.com/blogs/security/how-to-encrypt-and-decrypt-your-data-with-the-aws-encryption-cli/) di Blog Keamanan. AWS Untuk informasi lebih rinci, lihat [Baca Dokumen](https://aws-encryption-sdk-cli.readthedocs.io/en/latest/), dan bergabunglah dengan kami dalam mengembangkan CLI AWS Enkripsi di [aws-encryption-sdk-cli](https://github.com/aws/aws-encryption-sdk-cli/)repositori. GitHub
**Performa**
CLI AWS Enkripsi dibangun di atas file. AWS Encryption SDK for Python Setiap kali Anda menjalankan CLI, Anda memulai instance baru runtime Python. Untuk meningkatkan kinerja, bila memungkinkan, gunakan satu perintah alih-alih serangkaian perintah independen. Misalnya, jalankan satu perintah yang memproses file dalam direktori secara rekursif alih-alih menjalankan perintah terpisah untuk setiap file.
**Topics**
+ [Menginstal CLI](crypto-cli-install.md)
+ [Cara menggunakan CLI](crypto-cli-how-to.md)
+ [Contoh](crypto-cli-examples.md)
+ [Referensi sintaks dan parameter](crypto-cli-reference.md)
+ [Versi](crypto-cli-versions.md)
# Menginstal antarmuka baris AWS Encryption SDK perintah
Topik ini menjelaskan cara menginstal CLI AWS Enkripsi. Untuk informasi lebih lanjut, lihat [aws-encryption-sdk-cli](https://github.com/aws/aws-encryption-sdk-cli/)repositori GitHub dan [Baca Dokumen.](https://aws-encryption-sdk-cli.readthedocs.io/en/latest/)
**Topics**
+ [
## Memasang prasyarat
](#crypto-cli-prerequisites)
+ [Menginstal CLI](#install-sdk-cli)
## Memasang prasyarat
CLI AWS Enkripsi dibangun di atas file. AWS Encryption SDK for Python Untuk menginstal CLI AWS Enkripsi, Anda memerlukan Python dan, alat manajemen paket `pip` Python. Python dan `pip` tersedia di semua platform yang didukung.
Instal prasyarat berikut sebelum Anda menginstal CLI Enkripsi, AWS
**Python**
Python 3.8 atau yang lebih baru diperlukan oleh Encryption AWS CLI versi 4.2.0 dan yang lebih baru.
Versi sebelumnya dari AWS Encryption CLI mendukung Python 2.7 dan 3.4 dan yang lebih baru, tetapi kami menyarankan Anda menggunakan versi terbaru dari Encryption CLI. AWS
Python termasuk dalam sebagian besar instalasi Linux dan macOS, tetapi Anda perlu meningkatkan ke Python 3.6 atau yang lebih baru. Kami menyarankan Anda menggunakan versi terbaru Python. Pada Windows, Anda harus menginstal Python; itu tidak diinstal secara default. [Untuk mengunduh dan menginstal Python, lihat unduhan Python.](https://www.python.org/downloads/)
Untuk menentukan apakah Python diinstal, pada baris perintah, ketik berikut ini.
```
python
```
Untuk memeriksa versi Python, gunakan parameter `-V` (huruf besar V).
```
python -V
```
Di Windows, setelah Anda menginstal Python, tambahkan path ke `Python.exe` file ke nilai variabel lingkungan **Path**.
Secara default, Python dipasang di direktori semua pengguna atau di direktori profil pengguna (`$home`atau`%userprofile%`) di subdirektori. `AppData\Local\Programs\Python` Untuk menemukan lokasi `Python.exe` file di sistem Anda, periksa salah satu kunci registri berikut. Anda dapat menggunakan PowerShell untuk mencari registri.
```
PS C:\> dir HKLM:\Software\Python\PythonCore\version\InstallPath
# -or-
PS C:\> dir HKCU:\Software\Python\PythonCore\version\InstallPath
```
**pip**
`pip`adalah manajer paket Python. Untuk menginstal CLI AWS Enkripsi dan dependensinya, Anda memerlukan `pip` 8.1 atau lebih baru. Untuk bantuan menginstal atau meningkatkan`pip`, lihat [Instalasi](https://pip.pypa.io/en/latest/installing/) dalam `pip` dokumentasi.
Pada instalasi Linux, versi `pip` lebih awal dari 8.1 tidak dapat membangun pustaka **kriptografi** yang dibutuhkan AWS CLI Enkripsi. Jika Anda memilih untuk tidak memperbarui `pip` versi, Anda dapat menginstal alat build secara terpisah. Untuk informasi selengkapnya, lihat [Membangun kriptografi di Linux](https://cryptography.io/en/latest/installation.html#building-cryptography-on-linux).
**AWS Command Line Interface**
AWS Command Line Interface (AWS CLI) diperlukan hanya jika Anda menggunakan AWS KMS keys in AWS Key Management Service (AWS KMS) dengan CLI AWS Enkripsi. Jika Anda menggunakan [penyedia kunci master](concepts.md#master-key-provider) yang berbeda, tidak AWS CLI diperlukan.
Untuk menggunakan AWS KMS keys CLI AWS Enkripsi, Anda perlu [menginstal](https://docs.aws.amazon.com/cli/latest/userguide/installing.html) dan [mengkonfigurasi](https://docs.aws.amazon.com/cli/latest/userguide/cli-chap-getting-started.html#cli-quick-configuration) file. AWS CLI Konfigurasi membuat kredensional yang Anda gunakan untuk mengautentikasi agar AWS KMS tersedia untuk CLI Enkripsi AWS .
## Menginstal dan memperbarui CLI AWS Enkripsi
Instal CLI AWS Enkripsi versi terbaru. [Ketika Anda menggunakan `pip` untuk menginstal CLI AWS Enkripsi, secara otomatis menginstal pustaka yang dibutuhkan CLI, termasuk, pustaka kriptografi Python, [AWS Encryption SDK for Python](python.md)dan file. [AWS SDK untuk Python (Boto3)](https://boto3.amazonaws.com/v1/documentation/api/latest/index.html)](https://cryptography.io/en/latest/)
**catatan**
[Versi CLI AWS Enkripsi lebih awal dari 4.0.0 sedang dalam fase. end-of-support](https://docs.aws.amazon.com/sdkref/latest/guide/maint-policy.html#version-life-cycle)
Anda dapat memperbarui dengan aman dari versi 2.1. *x* dan yang lebih baru ke versi terbaru CLI AWS Enkripsi tanpa perubahan kode atau data apa pun. Namun, [fitur keamanan baru](about-versions.md#version-2) diperkenalkan di versi 2.1. *x* tidak kompatibel ke belakang. Untuk memperbarui dari versi 1.7. *x* atau sebelumnya, Anda harus terlebih dahulu memperbarui ke yang terbaru 1. *x* versi CLI AWS Enkripsi. Lihat perinciannya di [Migrasi Anda AWS Encryption SDK](migration.md).
Fitur keamanan baru awalnya dirilis dalam AWS Enkripsi CLI versi 1.7. *x* dan 2.0. *x*. Namun, AWS Enkripsi CLI versi 1.8. *x* menggantikan versi 1.7. *x* dan AWS Enkripsi CLI 2.1. *x* menggantikan 2.0. *x*. Untuk detailnya, lihat [penasihat keamanan](https://github.com/aws/aws-encryption-sdk-cli/security/advisories/GHSA-2xwp-m7mq-7q3r) yang relevan di [aws-encryption-sdk-cli](https://github.com/aws/aws-encryption-sdk-cli/)repositori di. GitHub
**Untuk menginstal versi terbaru dari AWS Encryption CLI**
```
pip install aws-encryption-sdk-cli
```
**Untuk meng-upgrade ke versi terbaru dari AWS Encryption CLI**
```
pip install --upgrade aws-encryption-sdk-cli
```
**Untuk menemukan nomor versi CLI AWS Enkripsi Anda dan AWS Encryption SDK**
```
aws-encryption-cli --version
```
Output mencantumkan nomor versi kedua pustaka.
```
aws-encryption-sdk-cli/2.1.0 aws-encryption-sdk/2.0.0
```
**Untuk meng-upgrade ke versi terbaru dari AWS Encryption CLI**
```
pip install --upgrade aws-encryption-sdk-cli
```
Menginstal CLI AWS Enkripsi juga menginstal versi terbaru dari AWS SDK untuk Python (Boto3), jika belum diinstal. Jika Boto3 diinstal, penginstal memverifikasi versi Boto3 dan memperbaruinya jika diperlukan.
**Untuk menemukan versi Boto3 yang Anda instal**
```
pip show boto3
```
**Untuk memperbarui ke versi terbaru Boto3**
```
pip install --upgrade boto3
```
Untuk menginstal versi CLI AWS Enkripsi yang saat ini sedang dalam pengembangan, lihat [aws-encryption-sdk-cli](https://github.com/aws/aws-encryption-sdk-cli/)repositori aktif. GitHub
Untuk detail selengkapnya tentang penggunaan `pip` untuk menginstal dan memutakhirkan paket Python, lihat dokumentasi [pip](https://pip.pypa.io/en/stable/quickstart/).
# Cara menggunakan CLI AWS Enkripsi
Topik ini menjelaskan cara menggunakan parameter dalam CLI AWS Enkripsi. Sebagai contoh, lihat [Contoh CLI AWS Enkripsi](crypto-cli-examples.md). Untuk dokumentasi selengkapnya, lihat [Membaca Dokumen.](https://aws-encryption-sdk-cli.readthedocs.io/en/latest/) Sintaks yang ditunjukkan dalam contoh ini adalah untuk AWS Enkripsi CLI versi 2.1. *x* dan kemudian.
**catatan**
[Versi CLI AWS Enkripsi lebih awal dari 4.0.0 sedang dalam fase. end-of-support](https://docs.aws.amazon.com/sdkref/latest/guide/maint-policy.html#version-life-cycle)
Anda dapat memperbarui dengan aman dari versi 2.1. *x* dan yang lebih baru ke versi terbaru CLI AWS Enkripsi tanpa perubahan kode atau data apa pun. Namun, [fitur keamanan baru](about-versions.md#version-2) diperkenalkan di versi 2.1. *x* tidak kompatibel ke belakang. Untuk memperbarui dari versi 1.7. *x* atau sebelumnya, Anda harus terlebih dahulu memperbarui ke yang terbaru 1. *x* versi CLI AWS Enkripsi. Lihat perinciannya di [Migrasi Anda AWS Encryption SDK](migration.md).
Fitur keamanan baru awalnya dirilis dalam AWS Enkripsi CLI versi 1.7. *x* dan 2.0. *x*. Namun, AWS Enkripsi CLI versi 1.8. *x* menggantikan versi 1.7. *x* dan AWS Enkripsi CLI 2.1. *x* menggantikan 2.0. *x*. Untuk detailnya, lihat [penasihat keamanan](https://github.com/aws/aws-encryption-sdk-cli/security/advisories/GHSA-2xwp-m7mq-7q3r) yang relevan di [aws-encryption-sdk-cli](https://github.com/aws/aws-encryption-sdk-cli/)repositori di. GitHub
Untuk contoh yang menunjukkan cara menggunakan fitur keamanan yang membatasi kunci data terenkripsi, lihat. [Membatasi kunci data terenkripsi](configure.md#config-limit-keys)
Untuk contoh yang menunjukkan cara menggunakan kunci AWS KMS Multi-region, lihat[Menggunakan Multi-region AWS KMS keys](configure.md#config-mrks).
**Topics**
+ [
## Cara mengenkripsi dan mendekripsi data
](#crypto-cli-e-d-intro)
+ [
## Cara menentukan kunci pembungkus
](#crypto-cli-master-key)
+ [
## Cara memberikan masukan
](#crypto-cli-input)
+ [
## Cara menentukan lokasi output
](#crypto-cli-output)
+ [
## Cara menggunakan konteks enkripsi
](#crypto-cli-encryption-context)
+ [
## Cara menentukan kebijakan komitmen
](#crypto-cli-commitment-policy)
+ [
## Cara menyimpan parameter dalam file konfigurasi
](#crypto-cli-config-file)
## Cara mengenkripsi dan mendekripsi data
AWS Enkripsi CLI menggunakan fitur AWS Encryption SDK untuk membuatnya mudah untuk mengenkripsi dan mendekripsi data dengan aman.
**catatan**
`--master-keys`Parameter tidak digunakan lagi di versi 1.8. *x* dari CLI AWS Enkripsi dan dihapus dalam versi 2.1. *x*. Sebagai gantinya, gunakan `--wrapping-keys` parameternya. Dimulai pada versi 2.1. *x*, `--wrapping-keys` parameter diperlukan saat mengenkripsi dan mendekripsi. Lihat perinciannya di [AWS Encryption SDK Sintaks CLI dan referensi parameter](crypto-cli-reference.md).
+ Saat Anda mengenkripsi data di CLI AWS Enkripsi, Anda menentukan data teks biasa dan kunci [pembungkus](concepts.md#master-key) (*atau kunci master*), seperti in (). AWS KMS key AWS Key Management Service AWS KMS Jika Anda menggunakan penyedia kunci master kustom, Anda juga perlu menentukan penyedia. Anda juga menentukan lokasi keluaran untuk [pesan terenkripsi](concepts.md#message) dan untuk metadata tentang operasi enkripsi. [Konteks enkripsi](concepts.md#encryption-context) bersifat opsional, tetapi disarankan.
Dalam versi 1.8. *x*, `--commitment-policy` parameter diperlukan saat Anda menggunakan `--wrapping-keys` parameter; jika tidak maka tidak valid. Dimulai pada versi 2.1. *x*, `--commitment-policy` parameternya opsional, tetapi disarankan.
```
aws-encryption-cli --encrypt --input myPlaintextData \
--wrapping-keys key=1234abcd-12ab-34cd-56ef-1234567890ab \
--output myEncryptedMessage \
--metadata-output ~/metadata \
--encryption-context purpose=test \
--commitment-policy require-encrypt-require-decrypt
```
CLI AWS Enkripsi mengenkripsi data Anda di bawah kunci data unik. Kemudian mengenkripsi kunci data di bawah kunci pembungkus yang Anda tentukan. Ia mengembalikan [pesan terenkripsi](concepts.md#message) dan metadata tentang operasi. Pesan terenkripsi berisi data terenkripsi Anda (*ciphertext*) dan salinan kunci data terenkripsi. Anda tidak perlu khawatir tentang menyimpan, mengelola, atau kehilangan kunci data.
+ Ketika Anda mendekripsi data, Anda meneruskan pesan terenkripsi Anda, konteks enkripsi opsional, dan lokasi untuk output plaintext dan metadata. Anda juga menentukan kunci pembungkus yang dapat digunakan CLI AWS Enkripsi untuk mendekripsi pesan, atau memberi tahu CLI AWS Enkripsi bahwa ia dapat menggunakan kunci pembungkus apa pun yang mengenkripsi pesan.
Dimulai pada versi 1.8. *x*, `--wrapping-keys` parameternya opsional saat mendekripsi, tetapi disarankan. Dimulai pada versi 2.1. *x*, `--wrapping-keys` parameter diperlukan saat mengenkripsi dan mendekripsi.
Saat mendekripsi, Anda dapat menggunakan atribut **kunci** `--wrapping-keys` parameter untuk menentukan kunci pembungkus yang mendekripsi data Anda. Menentukan kunci AWS KMS pembungkus saat mendekripsi adalah opsional, tetapi ini adalah [praktik terbaik](best-practices.md) yang mencegah Anda menggunakan kunci yang tidak ingin Anda gunakan. Jika Anda menggunakan penyedia kunci master kustom, Anda harus menentukan penyedia dan kunci pembungkus.
Jika Anda tidak menggunakan atribut **kunci**, Anda harus menyetel [atribut **penemuan**](#discovery-cli-attribute) `--wrapping-keys` parameter ke`true`, yang memungkinkan CLI AWS Enkripsi mendekripsi menggunakan kunci pembungkus apa pun yang mengenkripsi pesan.
Sebagai praktik terbaik, gunakan `--max-encrypted-data-keys` parameter untuk menghindari dekripsi pesan yang salah dengan jumlah kunci data terenkripsi yang berlebihan. Tentukan jumlah yang diharapkan dari kunci data terenkripsi (satu untuk setiap kunci pembungkus yang digunakan dalam enkripsi) atau maksimum yang wajar (seperti 5). Lihat perinciannya di [Membatasi kunci data terenkripsi](configure.md#config-limit-keys).
`--buffer`Parameter mengembalikan plaintext hanya setelah semua input diproses, termasuk memverifikasi tanda tangan digital jika ada.
`--decrypt-unsigned`Parameter mendekripsi ciphertext dan memastikan bahwa pesan tidak ditandatangani sebelum dekripsi. Gunakan parameter ini jika Anda menggunakan `--algorithm` parameter dan memilih rangkaian algoritme tanpa penandatanganan digital untuk mengenkripsi data. Jika ciphertext ditandatangani, dekripsi gagal.
Anda dapat menggunakan `--decrypt` atau `--decrypt-unsigned` untuk dekripsi tetapi tidak keduanya.
```
aws-encryption-cli --decrypt --input myEncryptedMessage \
--wrapping-keys key=1234abcd-12ab-34cd-56ef-1234567890ab \
--output myPlaintextData \
--metadata-output ~/metadata \
--max-encrypted-data-keys 1 \
--buffer \
--encryption-context purpose=test \
--commitment-policy require-encrypt-require-decrypt
```
CLI AWS Enkripsi menggunakan kunci pembungkus untuk mendekripsi kunci data dalam pesan terenkripsi. Kemudian menggunakan kunci data untuk mendekripsi data Anda. Ini mengembalikan data plaintext dan metadata Anda tentang operasi.
## Cara menentukan kunci pembungkus
Saat Anda mengenkripsi data di CLI AWS Enkripsi, Anda perlu menentukan setidaknya [satu kunci pembungkus](concepts.md#master-key) (*atau* kunci master). Anda dapat menggunakan AWS KMS keys in AWS Key Management Service (AWS KMS), kunci pembungkus dari [penyedia kunci master](concepts.md#master-key-provider) kustom, atau keduanya. Penyedia kunci master kustom dapat berupa penyedia kunci master Python yang kompatibel.
Untuk menentukan kunci pembungkus di versi 1.8. *x* dan kemudian, gunakan `--wrapping-keys` parameter (`-w`). Nilai parameter ini adalah kumpulan [atribut](#cli-master-key-attributes) dengan `attribute=value` format. Atribut yang Anda gunakan bergantung pada penyedia kunci master dan perintah.
+ **AWS KMS**. Dalam perintah enkripsi, Anda harus menentukan `--wrapping-keys` parameter dengan atribut **kunci**. Dimulai pada versi 2.1. *x*, `--wrapping-keys` parameter juga diperlukan dalam perintah dekripsi. Saat mendekripsi, `--wrapping-keys` parameter harus memiliki atribut **kunci** atau atribut **penemuan** dengan nilai `true` (tetapi tidak keduanya). Atribut lainnya adalah opsional.
+ **Penyedia kunci master kustom**. Anda harus menentukan `--wrapping-keys` parameter di setiap perintah. Nilai parameter harus memiliki atribut **kunci** dan **penyedia**.
Anda dapat menyertakan [beberapa `--wrapping-keys` parameter](#cli-many-cmks) dan beberapa atribut **kunci** dalam perintah yang sama.
### Membungkus atribut parameter kunci
Nilai `--wrapping-keys` parameter terdiri dari atribut berikut dan nilainya. `--wrapping-keys`Parameter (atau `--master-keys` parameter) diperlukan di semua perintah enkripsi. Dimulai pada versi 2.1. *x*, `--wrapping-keys` parameter juga diperlukan saat mendekripsi.
Jika nama atau nilai atribut menyertakan spasi atau karakter khusus, lampirkan nama dan nilai dalam tanda kutip. Misalnya, `--wrapping-keys key=12345 "provider=my cool provider"`.
**Kunci: Tentukan kunci pembungkus**
Gunakan atribut **kunci** untuk mengidentifikasi kunci pembungkus. Saat mengenkripsi, nilainya dapat berupa pengidentifikasi kunci apa pun yang dikenali oleh penyedia kunci utama.
```
--wrapping-keys key=1234abcd-12ab-34cd-56ef-1234567890ab
```
Dalam perintah enkripsi, Anda harus menyertakan setidaknya satu atribut **kunci** dan nilai. Untuk mengenkripsi kunci data Anda di bawah beberapa kunci pembungkus, gunakan [beberapa atribut **kunci**](#cli-many-cmks).
```
aws-encryption-cli --encrypt --wrapping-keys key=1234abcd-12ab-34cd-56ef-1234567890ab key=1a2b3c4d-5e6f-1a2b-3c4d-5e6f1a2b3c4d
```
Dalam perintah enkripsi yang digunakan AWS KMS keys, nilai **kunci dapat berupa ID kunci**, ARN kuncinya, nama alias, atau alias ARN. **Misalnya, perintah enkripsi ini menggunakan alias ARN dalam nilai atribut kunci.** 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*.
```
aws-encryption-cli --encrypt --wrapping-keys key=arn:aws:kms:us-west-2:111122223333:alias/ExampleAlias
```
Dalam perintah dekripsi yang menggunakan penyedia kunci master kustom, atribut **kunci** dan **penyedia** diperlukan.
```
\\ Custom master key provider
aws-encryption-cli --decrypt --wrapping-keys provider='myProvider' key='100101'
```
Dalam perintah dekripsi yang digunakan AWS KMS, Anda dapat menggunakan atribut **kunci** untuk menentukan yang akan digunakan AWS KMS keys untuk mendekripsi, atau [atribut **penemuan**](#discovery-cli-attribute) dengan nilai`true`, yang memungkinkan AWS CLI Enkripsi menggunakan apa pun AWS KMS key yang digunakan untuk mengenkripsi pesan. Jika Anda menentukan AWS KMS key, itu harus menjadi salah satu kunci pembungkus yang digunakan untuk mengenkripsi pesan.
Menentukan kunci pembungkus adalah praktik [AWS Encryption SDK terbaik](best-practices.md). Ini memastikan bahwa Anda menggunakan yang ingin AWS KMS key Anda gunakan.
Dalam perintah dekripsi, nilai atribut **kunci** harus berupa [ARN](https://docs.aws.amazon.com/kms/latest/developerguide/concepts.html#key-id-key-ARN) kunci.
```
\\ AWS KMS key
aws-encryption-cli --decrypt --wrapping-keys key=arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab
```
**Penemuan: Gunakan apa saja AWS KMS key saat mendekripsi**
Jika Anda tidak perlu membatasi penggunaan saat mendekripsi, Anda dapat menggunakan atribut **penemuan** dengan nilai. AWS KMS keys `true` Nilai `true` memungkinkan CLI AWS Enkripsi untuk mendekripsi menggunakan apa pun AWS KMS key yang mengenkripsi pesan. Jika Anda tidak menentukan atribut **penemuan**, penemuan adalah `false` (default). Atribut **penemuan** hanya valid dalam perintah dekripsi dan hanya ketika pesan dienkripsi dengan. AWS KMS keys
Atribut **penemuan** dengan nilai `true` adalah alternatif untuk menggunakan atribut **kunci** untuk menentukan AWS KMS keys. Saat mendekripsi pesan yang dienkripsi AWS KMS keys, setiap `--wrapping-keys` parameter harus memiliki atribut **kunci** atau atribut **penemuan** dengan nilai`true`, tetapi tidak keduanya.
Ketika penemuan benar, sebaiknya gunakan atribut **partisi penemuan dan **akun** penemuan** untuk membatasi yang AWS KMS keys digunakan pada atribut yang Anda tentukan. Akun AWS Dalam contoh berikut, atribut **penemuan** memungkinkan CLI AWS Enkripsi untuk menggunakan apa pun AWS KMS key dalam yang ditentukan. Akun AWS
```
aws-encryption-cli --decrypt --wrapping-keys \
discovery=true \
discovery-partition=aws \
discovery-account=111122223333 \
discovery-account=444455556666
```
**Penyedia: Tentukan penyedia kunci utama**
Atribut **provider** mengidentifikasi [penyedia kunci master](concepts.md#master-key-provider). Nilai default adalah`aws-kms`, yang mewakili AWS KMS. Jika Anda menggunakan penyedia kunci master yang berbeda, atribut **penyedia** diperlukan.
```
--wrapping-keys key=12345 provider=my_custom_provider
```
Untuk informasi selengkapnya tentang penggunaan penyedia kunci master kustom (non-⸺-AWS KMS), lihat topik **Konfigurasi Lanjutan** dalam file [README](https://github.com/aws/aws-encryption-sdk-cli/blob/master/README.rst) untuk repositori [CLI AWS Enkripsi](https://github.com/aws/aws-encryption-sdk-cli/).
**Wilayah: Tentukan Wilayah AWS**
Gunakan atribut **region** untuk menentukan Wilayah AWS dari AWS KMS key. Atribut ini hanya valid dalam perintah enkripsi dan hanya ketika penyedia kunci master. AWS KMS
```
--encrypt --wrapping-keys key=alias/primary-key region=us-east-2
```
AWS Enkripsi perintah CLI menggunakan Wilayah AWS yang ditentukan dalam nilai atribut **kunci** jika termasuk wilayah, seperti ARN. jika nilai **kunci** menentukan Wilayah AWS, atribut **region** diabaikan.
Atribut **region** lebih diutamakan daripada spesifikasi wilayah lainnya. Jika Anda tidak menggunakan atribut region, perintah AWS Encryption CLI menggunakan yang Wilayah AWS ditentukan dalam [profil AWS CLI bernama](https://docs.aws.amazon.com/cli/latest/userguide/cli-configure-files.html#cli-configure-files-using-profiles) Anda, jika ada, atau profil default Anda.
**Profil: Tentukan profil bernama**
Gunakan atribut **profil** untuk menentukan [profil AWS CLI bernama](https://docs.aws.amazon.com/cli/latest/userguide/cli-configure-files.html#cli-configure-files-using-profiles). Profil bernama dapat mencakup kredensil dan file. Wilayah AWS Atribut ini hanya valid jika penyedia kunci master AWS KMS.
```
--wrapping-keys key=alias/primary-key profile=admin-1
```
Anda dapat menggunakan atribut **profil** untuk menentukan kredensi alternatif dalam perintah enkripsi dan dekripsi. **Dalam perintah enkripsi, CLI AWS Enkripsi menggunakan Wilayah AWS dalam profil bernama hanya ketika nilai kunci tidak menyertakan wilayah dan tidak **ada** atribut wilayah.** Dalam perintah dekripsi, profil Wilayah AWS dalam nama diabaikan.
### Cara menentukan beberapa tombol pembungkus
Anda dapat menentukan beberapa tombol pembungkus (atau *kunci master*) di setiap perintah.
Jika Anda menentukan lebih dari satu kunci pembungkus, kunci pembungkus pertama menghasilkan dan mengenkripsi kunci data yang digunakan untuk mengenkripsi data Anda. Kunci pembungkus lainnya mengenkripsi kunci data yang sama. [Pesan terenkripsi](concepts.md#message) yang dihasilkan berisi data terenkripsi (“ciphertext”) dan kumpulan kunci data terenkripsi, satu dienkripsi oleh setiap kunci pembungkus. Setiap pembungkus dapat mendekripsi satu kunci data terenkripsi dan kemudian mendekripsi data.
Ada dua cara untuk menentukan beberapa kunci pembungkus:
+ Sertakan beberapa atribut **kunci** dalam nilai `--wrapping-keys` parameter.
```
$key_oregon=arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab
$key_ohio=arn:aws:kms:us-east-2:111122223333:key/0987ab65-43cd-21ef-09ab-87654321cdef
--wrapping-keys key=$key_oregon key=$key_ohio
```
+ Sertakan beberapa `--wrapping-keys` parameter dalam perintah yang sama. Gunakan sintaks ini ketika nilai atribut yang Anda tentukan tidak berlaku untuk semua kunci pembungkus dalam perintah.
```
--wrapping-keys region=us-east-2 key=alias/test_key \
--wrapping-keys region=us-west-1 key=alias/test_key
```
Atribut **penemuan** dengan nilai `true` memungkinkan CLI AWS Enkripsi menggunakan apa pun AWS KMS key yang mengenkripsi pesan. Jika Anda menggunakan beberapa `--wrapping-keys` parameter dalam perintah yang sama, menggunakan `discovery=true` `--wrapping-keys` parameter apa pun secara efektif mengesampingkan batas atribut **kunci** di parameter lain`--wrapping-keys`.
Misalnya, dalam perintah berikut, atribut **kunci** dalam `--wrapping-keys` parameter pertama membatasi CLI AWS Enkripsi ke yang ditentukan. AWS KMS key Namun, atribut **penemuan** di `--wrapping-keys` parameter kedua memungkinkan CLI AWS Enkripsi menggunakan apa pun AWS KMS key di akun yang ditentukan untuk mendekripsi pesan.
```
aws-encryption-cli --decrypt \
--wrapping-keys key=arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab \
--wrapping-keys discovery=true \
discovery-partition=aws \
discovery-account=111122223333 \
discovery-account=444455556666
```
## Cara memberikan masukan
[Operasi enkripsi di CLI AWS Enkripsi mengambil data teks biasa sebagai input dan mengembalikan pesan terenkripsi.](concepts.md#message) Operasi dekripsi mengambil pesan terenkripsi sebagai input dan mengembalikan data plaintext.
`--input`Parameter (`-i`), yang memberi tahu AWS Encryption CLI di mana menemukan input, diperlukan di semua perintah Encryption AWS CLI.
Anda dapat memberikan masukan dengan salah satu cara berikut:
+ Gunakan file.
```
--input myData.txt
```
+ Gunakan pola nama file.
```
--input testdir/*.xml
```
+ Gunakan pola nama direktori atau direktori. Ketika input adalah direktori, `--recursive` parameter (`-r`,`-R`) diperlukan.
```
--input testdir --recursive
```
+ Input pipa ke perintah (stdin). Gunakan nilai `-` untuk `--input` parameter. (`--input`Parameter selalu diperlukan.)
```
echo 'Hello World' | aws-encryption-cli --encrypt --input -
```
## Cara menentukan lokasi output
`--output`Parameter memberi tahu CLI AWS Enkripsi tempat menulis hasil operasi enkripsi atau dekripsi. Hal ini diperlukan dalam setiap perintah AWS Enkripsi CLI. CLI AWS Enkripsi membuat file output baru untuk setiap file input dalam operasi.
Jika file keluaran sudah ada, secara default, CLI AWS Enkripsi mencetak peringatan, lalu menimpa file tersebut. Untuk mencegah penimpaan, gunakan `--interactive` parameter, yang meminta Anda untuk konfirmasi sebelum menimpa, atau`--no-overwrite`, yang melewatkan input jika output akan menyebabkan penimpaan. Untuk menekan peringatan penimpaan, gunakan. `--quiet` Untuk menangkap kesalahan dan peringatan dari CLI AWS Enkripsi, gunakan operator `2>&1` pengalihan untuk menuliskannya ke aliran output.
**catatan**
Perintah yang menimpa file output dimulai dengan menghapus file output. Jika perintah gagal, file output mungkin sudah dihapus.
Anda dapat lokasi output dalam beberapa cara.
+ Tentukan nama file. Jika Anda menentukan jalur ke file, semua direktori di jalur harus ada sebelum perintah berjalan.
```
--output myEncryptedData.txt
```
+ Tentukan direktori. Direktori output harus ada sebelum perintah berjalan.
Jika input berisi subdirektori, perintah mereproduksi subdirektori di bawah direktori yang ditentukan.
```
--output Test
```
Ketika lokasi output adalah direktori (tanpa nama file), CLI AWS Enkripsi membuat nama file output berdasarkan nama file input ditambah akhiran. Enkripsi operasi append `.encrypted` ke nama file input dan operasi dekripsi ditambahkan. `.decrypted` Untuk mengubah sufiks, gunakan `--suffix` parameter.
Misalnya, jika Anda mengenkripsi`file.txt`, perintah enkripsi dibuat. `file.txt.encrypted` Jika Anda mendekripsi`file.txt.encrypted`, perintah dekripsi akan dibuat. `file.txt.encrypted.decrypted`
+ Tulis ke baris perintah (stdout). Masukkan nilai `-` untuk `--output` parameter. Anda dapat menggunakan `--output -` untuk menyalurkan output ke perintah atau program lain.
```
--output -
```
## Cara menggunakan konteks enkripsi
AWS Enkripsi CLI memungkinkan Anda menyediakan konteks enkripsi dalam mengenkripsi dan mendekripsi perintah. Ini tidak diperlukan, tetapi ini adalah praktik terbaik kriptografi yang kami rekomendasikan.
*Konteks enkripsi* adalah jenis data *otentikasi tambahan* yang sewenang-wenang dan non-rahasia. Dalam CLI AWS Enkripsi, konteks enkripsi terdiri dari kumpulan pasangan. `name=value` Anda dapat menggunakan konten apa pun dalam pasangan, termasuk informasi tentang file, data yang membantu Anda menemukan operasi enkripsi di log, atau data yang diperlukan oleh hibah atau kebijakan Anda.
**Dalam perintah enkripsi**
Konteks enkripsi yang Anda tentukan dalam perintah enkripsi, bersama dengan pasangan tambahan apa pun yang ditambahkan [CMM](concepts.md#crypt-materials-manager), terikat secara kriptografis ke data terenkripsi. Ini juga termasuk (dalam teks biasa) dalam [pesan terenkripsi](concepts.md#encryption-context) yang dikembalikan oleh perintah. Jika Anda menggunakan AWS KMS key, konteks enkripsi juga mungkin muncul dalam teks biasa dalam catatan audit dan log, seperti. AWS CloudTrail
Contoh berikut menunjukkan konteks enkripsi dengan tiga `name=value` pasang.
```
--encryption-context purpose=test dept=IT class=confidential
```
**Dalam perintah dekripsi**
Dalam perintah dekripsi, konteks enkripsi membantu Anda mengonfirmasi bahwa Anda mendekripsi pesan terenkripsi yang tepat.
Anda tidak diharuskan untuk menyediakan konteks enkripsi dalam perintah dekripsi, bahkan jika konteks enkripsi digunakan pada enkripsi. Namun, jika Anda melakukannya, CLI AWS Enkripsi memverifikasi bahwa setiap elemen dalam konteks enkripsi perintah dekripsi cocok dengan elemen dalam konteks enkripsi pesan terenkripsi. Jika ada elemen yang tidak cocok, perintah dekripsi gagal.
Misalnya, perintah berikut mendekripsi pesan terenkripsi hanya jika konteks enkripsi termasuk. `dept=IT`
```
aws-encryption-cli --decrypt --encryption-context dept=IT ...
```
Konteks enkripsi adalah bagian penting dari strategi keamanan Anda. Namun, ketika memilih konteks enkripsi, ingatlah bahwa nilainya bukan rahasia. Jangan sertakan data rahasia apa pun dalam konteks enkripsi.
**Untuk menentukan konteks enkripsi**
+ Dalam perintah **enkripsi**, gunakan `--encryption-context` parameter dengan satu atau lebih `name=value` pasangan. Gunakan spasi untuk memisahkan setiap pasangan.
```
--encryption-context name=value [name=value] ...
```
+ Dalam perintah **dekripsi**, nilai `--encryption-context` parameter dapat mencakup `name=value` pasangan, `name` elemen (tanpa nilai), atau kombinasi keduanya.
```
--encryption-context name[=value] [name] [name=value] ...
```
Jika `name` atau `value` dalam `name=value` pasangan menyertakan spasi atau karakter khusus, lampirkan seluruh pasangan dalam tanda kutip.
```
--encryption-context "department=software engineering" "Wilayah AWS=us-west-2"
```
Misalnya, perintah enkripsi ini mencakup konteks enkripsi dengan dua pasang, `purpose=test` dan`dept=23`.
```
aws-encryption-cli --encrypt --encryption-context purpose=test dept=23 ...
```
Perintah dekripsi ini akan berhasil. Konteks enkripsi dalam setiap perintah adalah bagian dari konteks enkripsi asli.
```
\\ Any one or both of the encryption context pairs
aws-encryption-cli --decrypt --encryption-context dept=23 ...
\\ Any one or both of the encryption context names
aws-encryption-cli --decrypt --encryption-context purpose ...
\\ Any combination of names and pairs
aws-encryption-cli --decrypt --encryption-context dept purpose=test ...
```
Namun, perintah dekripsi ini akan gagal. Konteks enkripsi dalam pesan terenkripsi tidak mengandung elemen yang ditentukan.
```
aws-encryption-cli --decrypt --encryption-context dept=Finance ...
aws-encryption-cli --decrypt --encryption-context scope ...
```
## Cara menentukan kebijakan komitmen
Untuk menetapkan [kebijakan komitmen](concepts.md#commitment-policy) untuk perintah, gunakan [`--commitment-policy`parameter](crypto-cli-reference.md#syntax-commitment-policy). Parameter ini diperkenalkan dalam versi 1.8. *x*. Ini berlaku dalam perintah enkripsi dan dekripsi. Kebijakan komitmen yang Anda tetapkan hanya berlaku untuk perintah yang muncul. Jika Anda tidak menetapkan kebijakan komitmen untuk suatu perintah, CLI AWS Enkripsi menggunakan nilai default.
Misalnya, nilai parameter berikut menetapkan kebijakan komitmen`require-encrypt-allow-decrypt`, yang selalu mengenkripsi dengan komitmen utama, tetapi akan mendekripsi ciphertext yang dienkripsi dengan atau tanpa komitmen utama.
```
--commitment-policy require-encrypt-allow-decrypt
```
## Cara menyimpan parameter dalam file konfigurasi
Anda dapat menghemat waktu dan menghindari kesalahan pengetikan dengan menyimpan parameter dan nilai CLI AWS Enkripsi yang sering digunakan dalam file konfigurasi.
*File konfigurasi adalah file* teks yang berisi parameter dan nilai untuk perintah CLI AWS Enkripsi. Ketika Anda merujuk ke file konfigurasi dalam perintah AWS Encryption CLI, referensi digantikan oleh parameter dan nilai dalam file konfigurasi. Efeknya sama adalah jika Anda mengetik konten file di baris perintah. File konfigurasi dapat memiliki nama apa pun dan dapat ditemukan di direktori mana pun yang dapat diakses pengguna saat ini.
Contoh file konfigurasi berikut,`key.conf`, menentukan dua AWS KMS keys di Wilayah yang berbeda.
```
--wrapping-keys key=arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab
--wrapping-keys key=arn:aws:kms:us-east-2:111122223333:key/0987ab65-43cd-21ef-09ab-87654321cdef
```
Untuk menggunakan file konfigurasi dalam perintah, awali nama file dengan tanda at (`@`). Di PowerShell konsol, gunakan karakter backtick untuk keluar dari tanda at (``@`).
Perintah contoh ini menggunakan `key.conf` file dalam perintah enkripsi.
------
#### [ Bash ]
```
$ aws-encryption-cli -e @key.conf -i hello.txt -o testdir
```
------
#### [ PowerShell ]
```
PS C:\> aws-encryption-cli -e `@key.conf -i .\Hello.txt -o .\TestDir
```
------
**Aturan file konfigurasi**
Aturan untuk menggunakan file konfigurasi adalah sebagai berikut:
+ Anda dapat menyertakan beberapa parameter di setiap file konfigurasi dan mencantumkannya dalam urutan apa pun. Buat daftar setiap parameter dengan nilainya (jika ada) pada baris terpisah.
+ Gunakan `#` untuk menambahkan komentar ke semua atau sebagian baris.
+ Anda dapat menyertakan referensi ke file konfigurasi lainnya. Jangan gunakan backtick untuk menghindari `@` tanda, bahkan masuk PowerShell.
+ Jika Anda menggunakan tanda kutip dalam file konfigurasi, teks yang dikutip tidak dapat menjangkau beberapa baris.
Misalnya, ini adalah isi dari `encrypt.conf` file contoh.
```
# Archive Files
--encrypt
--output /archive/logs
--recursive
--interactive
--encryption-context class=unclassified dept=IT
--suffix # No suffix
--metadata-output ~/metadata
@caching.conf # Use limited caching
```
Anda juga dapat menyertakan beberapa file konfigurasi dalam sebuah perintah. Perintah contoh ini menggunakan file `encrypt.conf` dan `master-keys.conf` konfigurasi.
------
#### [ Bash ]
```
$ aws-encryption-cli -i /usr/logs @encrypt.conf @master-keys.conf
```
------
#### [ PowerShell ]
```
PS C:\> aws-encryption-cli -i $home\Test\*.log `@encrypt.conf `@master-keys.conf
```
------
**Berikutnya:** [Coba contoh AWS Encryption CLI](crypto-cli-examples.md)
# Contoh CLI AWS Enkripsi
Gunakan contoh berikut untuk mencoba CLI AWS Enkripsi pada platform yang Anda inginkan. Untuk bantuan dengan kunci master dan parameter lainnya, lihat[Cara menggunakan CLI AWS Enkripsi](crypto-cli-how-to.md). Untuk referensi cepat, lihat[AWS Encryption SDK Sintaks CLI dan referensi parameter](crypto-cli-reference.md).
**catatan**
Contoh berikut menggunakan sintaks untuk AWS Enkripsi CLI versi 2.1. *x*.
Fitur keamanan baru awalnya dirilis dalam AWS Enkripsi CLI versi 1.7. *x* dan 2.0. *x*. Namun, AWS Enkripsi CLI versi 1.8. *x* menggantikan versi 1.7. *x* dan AWS Enkripsi CLI 2.1. *x* menggantikan 2.0. *x*. Untuk detailnya, lihat [penasihat keamanan](https://github.com/aws/aws-encryption-sdk-cli/security/advisories/GHSA-2xwp-m7mq-7q3r) yang relevan di [aws-encryption-sdk-cli](https://github.com/aws/aws-encryption-sdk-cli/)repositori di. GitHub
Untuk contoh yang menunjukkan cara menggunakan fitur keamanan yang membatasi kunci data terenkripsi, lihat. [Membatasi kunci data terenkripsi](configure.md#config-limit-keys)
Untuk contoh yang menunjukkan cara menggunakan kunci AWS KMS Multi-region, lihat[Menggunakan Multi-region AWS KMS keys](configure.md#config-mrks).
**Topics**
+ [
## Mengenkripsi file
](#cli-example-encrypt-file)
+ [
## Mendekripsi file
](#cli-example-decrypt-file)
+ [
## Mengenkripsi semua file dalam direktori
](#cli-example-encrypt-directory)
+ [
## Mendekripsi semua file dalam direktori
](#cli-example-decrypt-directory)
+ [
## Mengenkripsi dan mendekripsi pada baris perintah
](#cli-example-stdin)
+ [
## Menggunakan beberapa kunci master
](#cli-example-multimaster)
+ [
## Mengenkripsi dan mendekripsi dalam skrip
](#cli-example-script)
+ [
## Menggunakan caching kunci data
](#cli-example-caching)
## Mengenkripsi file
Contoh ini menggunakan CLI AWS Enkripsi untuk mengenkripsi isi `hello.txt` file, yang berisi string “Hello World”.
Ketika Anda menjalankan perintah enkripsi pada file, CLI AWS Enkripsi mendapatkan konten file, menghasilkan kunci [data unik](concepts.md#DEK), mengenkripsi konten file di bawah kunci data, dan kemudian menulis pesan [terenkripsi ke](concepts.md#message) file baru.
Perintah pertama menyimpan ARN kunci dari AWS KMS key variabel. `$keyArn` Saat mengenkripsi dengan AWS KMS key, Anda dapat mengidentifikasinya dengan menggunakan ID kunci, ARN kunci, nama alias, atau alias ARN. 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*.
Perintah kedua mengenkripsi isi file. Perintah menggunakan `--encrypt` parameter untuk menentukan operasi dan `--input` parameter untuk menunjukkan file yang akan dienkripsi. [`--wrapping-keys`Parameter](crypto-cli-how-to.md#crypto-cli-master-key), dan atribut **kunci** yang diperlukan, beri tahu perintah untuk menggunakan yang AWS KMS key diwakili oleh kunci ARN.
Perintah menggunakan `--metadata-output` parameter untuk menentukan file teks untuk metadata tentang operasi enkripsi. Sebagai praktik terbaik, perintah menggunakan `--encryption-context` parameter untuk menentukan [konteks enkripsi](crypto-cli-how-to.md#crypto-cli-encryption-context).
Perintah ini juga menggunakan [`--commitment-policy`parameter](crypto-cli-reference.md#syntax-commitment-policy) untuk menetapkan kebijakan komitmen secara eksplisit. Dalam versi 1.8. *x*, parameter ini diperlukan saat Anda menggunakan `--wrapping-keys` parameter. Dimulai pada versi 2.1. *x*, `--commitment-policy` parameternya opsional, tetapi disarankan.
Nilai `--output` parameter, titik (.), memberi tahu perintah untuk menulis file output ke direktori saat ini.
------
#### [ Bash ]
```
\\ To run this example, replace the fictitious key ARN with a valid value.
$ keyArn=arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab
$ aws-encryption-cli --encrypt \
--input hello.txt \
--wrapping-keys key=$keyArn \
--metadata-output ~/metadata \
--encryption-context purpose=test \
--commitment-policy require-encrypt-require-decrypt \
--output .
```
------
#### [ PowerShell ]
```
# To run this example, replace the fictitious key ARN with a valid value.
PS C:\> $keyArn = 'arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab'
PS C:\> aws-encryption-cli --encrypt `
--input Hello.txt `
--wrapping-keys key=$keyArn `
--metadata-output $home\Metadata.txt `
--commitment-policy require-encrypt-require-decrypt `
--encryption-context purpose=test `
--output .
```
------
Ketika perintah enkripsi berhasil, itu tidak mengembalikan output apa pun. Untuk menentukan apakah perintah berhasil, periksa nilai Boolean dalam variabel. `$?` Ketika perintah berhasil, nilai dari `$?` adalah `0` (Bash) atau `True` (PowerShell). Ketika perintah gagal, nilai `$?` adalah bukan nol (Bash) atau `False` (PowerShell).
------
#### [ Bash ]
```
$ echo $?
0
```
------
#### [ PowerShell ]
```
PS C:\> $?
True
```
------
Anda juga dapat menggunakan perintah daftar direktori untuk melihat bahwa perintah enkripsi membuat file baru,`hello.txt.encrypted`. Karena perintah enkripsi tidak menentukan nama file untuk output, CLI AWS Enkripsi menulis output ke file dengan nama yang sama dengan file input ditambah `.encrypted` akhiran. Untuk menggunakan akhiran yang berbeda, atau menekan sufiks, gunakan parameter. `--suffix`
`hello.txt.encrypted`File berisi [pesan terenkripsi](concepts.md#message) yang mencakup ciphertext `hello.txt` file, salinan kunci data terenkripsi, dan metadata tambahan, termasuk konteks enkripsi.
------
#### [ Bash ]
```
$ ls
hello.txt hello.txt.encrypted
```
------
#### [ PowerShell ]
```
PS C:\> dir
Directory: C:\TestCLI
Mode LastWriteTime Length Name
---- ------------- ------ ----
-a---- 9/15/2017 5:57 PM 11 Hello.txt
-a---- 9/17/2017 1:06 PM 585 Hello.txt.encrypted
```
------
## Mendekripsi file
Contoh ini menggunakan CLI AWS Enkripsi untuk mendekripsi isi `Hello.txt.encrypted` file yang dienkripsi pada contoh sebelumnya.
Perintah dekripsi menggunakan `--decrypt` parameter untuk menunjukkan operasi dan `--input` parameter untuk mengidentifikasi file yang akan didekripsi. Nilai `--output` parameter adalah titik yang mewakili direktori saat ini.
`--wrapping-keys`Parameter dengan atribut **kunci menentukan kunci** pembungkus yang digunakan untuk mendekripsi pesan terenkripsi. Dalam dekripsi perintah dengan AWS KMS keys, nilai atribut kunci harus berupa [ARN](https://docs.aws.amazon.com/kms/latest/developerguide/concepts.html#key-id-key-ARN) kunci. `--wrapping-keys`Parameter diperlukan dalam perintah dekripsi. Jika Anda menggunakan AWS KMS keys, Anda dapat menggunakan atribut **kunci** untuk menentukan AWS KMS keys untuk mendekripsi atau atribut **penemuan** dengan nilai `true` (tetapi tidak keduanya). Jika Anda menggunakan penyedia kunci master kustom, atribut **kunci** dan **penyedia** diperlukan.
[`--commitment-policy`Parameternya](crypto-cli-reference.md#syntax-commitment-policy) opsional dimulai pada versi 2.1. *x*, tetapi disarankan. Menggunakannya secara eksplisit membuat maksud Anda jelas, bahkan jika Anda menentukan nilai default,. `require-encrypt-require-decrypt`
`--encryption-context`Parameter ini opsional dalam perintah dekripsi, bahkan ketika [konteks enkripsi](crypto-cli-how-to.md#crypto-cli-encryption-context) disediakan dalam perintah enkripsi. Dalam hal ini, perintah dekripsi menggunakan konteks enkripsi yang sama yang disediakan dalam perintah enkripsi. Sebelum mendekripsi, AWS CLI Enkripsi memverifikasi bahwa konteks enkripsi dalam pesan terenkripsi menyertakan pasangan. `purpose=test` Jika tidak, perintah dekripsi gagal.
`--metadata-output`Parameter menentukan file untuk metadata tentang operasi dekripsi. Nilai `--output` parameter, titik (.), menulis file output ke direktori saat ini.
Sebagai praktik terbaik, gunakan `--max-encrypted-data-keys` parameter untuk menghindari dekripsi pesan yang salah dengan jumlah kunci data terenkripsi yang berlebihan. Tentukan jumlah yang diharapkan dari kunci data terenkripsi (satu untuk setiap kunci pembungkus yang digunakan dalam enkripsi) atau maksimum yang wajar (seperti 5). Lihat perinciannya di [Membatasi kunci data terenkripsi](configure.md#config-limit-keys).
Plaintext `--buffer` mengembalikan hanya setelah semua input diproses, termasuk memverifikasi tanda tangan digital jika ada.
------
#### [ Bash ]
```
\\ To run this example, replace the fictitious key ARN with a valid value.
$ keyArn=arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab
$ aws-encryption-cli --decrypt \
--input hello.txt.encrypted \
--wrapping-keys key=$keyArn \
--commitment-policy require-encrypt-require-decrypt \
--encryption-context purpose=test \
--metadata-output ~/metadata \
--max-encrypted-data-keys 1 \
--buffer \
--output .
```
------
#### [ PowerShell ]
```
\\ To run this example, replace the fictitious key ARN with a valid value.
PS C:\> $keyArn = 'arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab'
PS C:\> aws-encryption-cli --decrypt `
--input Hello.txt.encrypted `
--wrapping-keys key=$keyArn `
--commitment-policy require-encrypt-require-decrypt `
--encryption-context purpose=test `
--metadata-output $home\Metadata.txt `
--max-encrypted-data-keys 1 `
--buffer `
--output .
```
------
Ketika perintah dekripsi berhasil, itu tidak mengembalikan output apa pun. Untuk menentukan apakah perintah berhasil, dapatkan nilai `$?` variabel. Anda juga dapat menggunakan perintah daftar direktori untuk melihat bahwa perintah tersebut membuat file baru dengan `.decrypted` akhiran. [Untuk melihat konten plaintext, gunakan perintah untuk mendapatkan konten file, seperti `cat` atau Get-Content.](https://docs.microsoft.com/en-us/powershell/module/microsoft.powershell.management/get-content)
------
#### [ Bash ]
```
$ ls
hello.txt hello.txt.encrypted hello.txt.encrypted.decrypted
$ cat hello.txt.encrypted.decrypted
Hello World
```
------
#### [ PowerShell ]
```
PS C:\> dir
Directory: C:\TestCLI
Mode LastWriteTime Length Name
---- ------------- ------ ----
-a---- 9/17/2017 1:01 PM 11 Hello.txt
-a---- 9/17/2017 1:06 PM 585 Hello.txt.encrypted
-a---- 9/17/2017 1:08 PM 11 Hello.txt.encrypted.decrypted
PS C:\> Get-Content Hello.txt.encrypted.decrypted
Hello World
```
------
## Mengenkripsi semua file dalam direktori
Contoh ini menggunakan CLI Enkripsi untuk mengenkripsi isi semua file dalam direktori. AWS
Ketika sebuah perintah mempengaruhi beberapa file, CLI AWS Enkripsi memproses setiap file satu per satu. Ini mendapatkan isi file, mendapatkan [kunci data](concepts.md#DEK) unik untuk file dari kunci master, mengenkripsi konten file di bawah kunci data, dan menulis hasilnya ke file baru di direktori output. Akibatnya, Anda dapat mendekripsi file output secara independen.
Daftar `TestDir` direktori ini menunjukkan file plaintext yang ingin kita enkripsi.
------
#### [ Bash ]
```
$ ls testdir
cool-new-thing.py hello.txt employees.csv
```
------
#### [ PowerShell ]
```
PS C:\> dir C:\TestDir
Directory: C:\TestDir
Mode LastWriteTime Length Name
---- ------------- ------ ----
-a---- 9/12/2017 3:11 PM 2139 cool-new-thing.py
-a---- 9/15/2017 5:57 PM 11 Hello.txt
-a---- 9/17/2017 1:44 PM 46 Employees.csv
```
------
Perintah pertama menyimpan [Amazon Resource Name (ARN)](https://docs.aws.amazon.com/kms/latest/developerguide/viewing-keys.html#find-cmk-id-arn) dari AWS KMS key variabel. `$keyArn`
Perintah kedua mengenkripsi konten file dalam `TestDir` direktori dan menulis file konten terenkripsi ke direktori. `TestEnc` Jika `TestEnc` direktori tidak ada, perintah gagal. Karena lokasi input adalah direktori, `--recursive` parameter diperlukan.
[`--wrapping-keys`Parameter](crypto-cli-how-to.md#crypto-cli-master-key), dan atribut **kunci** yang diperlukan, tentukan kunci pembungkus yang akan digunakan. Perintah enkripsi mencakup [konteks enkripsi](crypto-cli-how-to.md#crypto-cli-encryption-context),`dept=IT`. Saat Anda menentukan konteks enkripsi dalam perintah yang mengenkripsi beberapa file, konteks enkripsi yang sama digunakan untuk semua file.
Perintah ini juga memiliki `--metadata-output` parameter untuk memberi tahu CLI AWS Enkripsi tempat menulis metadata tentang operasi enkripsi. CLI AWS Enkripsi menulis satu catatan metadata untuk setiap file yang dienkripsi.
[`--commitment-policy parameter`](crypto-cli-how-to.md#crypto-cli-commitment-policy)Ini opsional dimulai pada versi 2.1. *x*, tetapi disarankan. Jika perintah atau skrip gagal karena tidak dapat mendekripsi ciphertext, pengaturan kebijakan komitmen eksplisit dapat membantu Anda mendeteksi masalah dengan cepat.
Ketika perintah selesai, CLI AWS Enkripsi menulis file terenkripsi ke `TestEnc` direktori, tetapi tidak mengembalikan output apa pun.
Perintah terakhir mencantumkan file dalam `TestEnc` direktori. Ada satu file output dari konten terenkripsi untuk setiap file input konten plaintext. Karena perintah tidak menentukan akhiran alternatif, perintah enkripsi ditambahkan `.encrypted` ke masing-masing nama file input.
------
#### [ Bash ]
```
# To run this example, replace the fictitious key ARN with a valid master key identifier.
$ keyArn=arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab
$ aws-encryption-cli --encrypt \
--input testdir --recursive\
--wrapping-keys key=$keyArn \
--encryption-context dept=IT \
--commitment-policy require-encrypt-require-decrypt \
--metadata-output ~/metadata \
--output testenc
$ ls testenc
cool-new-thing.py.encrypted employees.csv.encrypted hello.txt.encrypted
```
------
#### [ PowerShell ]
```
# To run this example, replace the fictitious key ARN with a valid master key identifier.
PS C:\> $keyArn = arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab
PS C:\> aws-encryption-cli --encrypt `
--input .\TestDir --recursive `
--wrapping-keys key=$keyArn `
--encryption-context dept=IT `
--commitment-policy require-encrypt-require-decrypt `
--metadata-output .\Metadata\Metadata.txt `
--output .\TestEnc
PS C:\> dir .\TestEnc
Directory: C:\TestEnc
Mode LastWriteTime Length Name
---- ------------- ------ ----
-a---- 9/17/2017 2:32 PM 2713 cool-new-thing.py.encrypted
-a---- 9/17/2017 2:32 PM 620 Hello.txt.encrypted
-a---- 9/17/2017 2:32 PM 585 Employees.csv.encrypted
```
------
## Mendekripsi semua file dalam direktori
Contoh ini mendekripsi semua file dalam direktori. Dimulai dengan file di `TestEnc` direktori yang dienkripsi dalam contoh sebelumnya.
------
#### [ Bash ]
```
$ ls testenc
cool-new-thing.py.encrypted hello.txt.encrypted employees.csv.encrypted
```
------
#### [ PowerShell ]
```
PS C:\> dir C:\TestEnc
Directory: C:\TestEnc
Mode LastWriteTime Length Name
---- ------------- ------ ----
-a---- 9/17/2017 2:32 PM 2713 cool-new-thing.py.encrypted
-a---- 9/17/2017 2:32 PM 620 Hello.txt.encrypted
-a---- 9/17/2017 2:32 PM 585 Employees.csv.encrypted
```
------
Perintah dekripsi ini mendekripsi semua file dalam TestEnc direktori dan menulis file plaintext ke direktori. TestDec `--wrapping-keys`Parameter dengan atribut **kunci** dan nilai [ARN kunci](https://docs.aws.amazon.com/kms/latest/developerguide/concepts.html#key-id-key-ARN) memberi tahu AWS CLI Enkripsi yang akan digunakan AWS KMS keys untuk mendekripsi file. Perintah menggunakan `--interactive` parameter untuk memberi tahu CLI AWS Enkripsi untuk meminta Anda sebelum menimpa file dengan nama yang sama.
Perintah ini juga menggunakan konteks enkripsi yang disediakan saat file dienkripsi. Saat mendekripsi beberapa file, AWS CLI Enkripsi memeriksa konteks enkripsi setiap file. Jika pemeriksaan konteks enkripsi pada file apa pun gagal, CLI AWS Enkripsi menolak file, menulis peringatan, mencatat kegagalan dalam metadata, dan kemudian terus memeriksa file yang tersisa. Jika CLI AWS Enkripsi gagal mendekripsi file karena alasan lain, seluruh perintah dekripsi segera gagal.
Dalam contoh ini, pesan terenkripsi di semua file input berisi elemen konteks `dept=IT` enkripsi. Namun, jika Anda mendekripsi pesan dengan konteks enkripsi yang berbeda, Anda mungkin masih dapat memverifikasi bagian dari konteks enkripsi. Misalnya, jika beberapa pesan memiliki konteks enkripsi `dept=finance` dan yang lainnya memiliki`dept=IT`, Anda dapat memverifikasi bahwa konteks enkripsi selalu berisi `dept` nama tanpa menentukan nilainya. Jika Anda ingin lebih spesifik, Anda dapat mendekripsi file dalam perintah terpisah.
Perintah dekripsi tidak mengembalikan output apa pun, tetapi Anda dapat menggunakan perintah daftar direktori untuk melihat bahwa itu membuat file baru dengan akhiran. `.decrypted` Untuk melihat konten plaintext, gunakan perintah untuk mendapatkan konten file.
------
#### [ Bash ]
```
# To run this example, replace the fictitious key ARN with a valid master key identifier.
$ keyArn=arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab
$ aws-encryption-cli --decrypt \
--input testenc --recursive \
--wrapping-keys key=$keyArn \
--encryption-context dept=IT \
--commitment-policy require-encrypt-require-decrypt \
--metadata-output ~/metadata \
--max-encrypted-data-keys 1 \
--buffer \
--output testdec --interactive
$ ls testdec
cool-new-thing.py.encrypted.decrypted hello.txt.encrypted.decrypted employees.csv.encrypted.decrypted
```
------
#### [ PowerShell ]
```
# To run this example, replace the fictitious key ARN with a valid master key identifier.
PS C:\> $keyArn = 'arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab'
PS C:\> aws-encryption-cli --decrypt `
--input C:\TestEnc --recursive `
--wrapping-keys key=$keyArn `
--encryption-context dept=IT `
--commitment-policy require-encrypt-require-decrypt `
--metadata-output $home\Metadata.txt `
--max-encrypted-data-keys 1 `
--buffer `
--output C:\TestDec --interactive
PS C:\> dir .\TestDec
Mode LastWriteTime Length Name
---- ------------- ------ ----
-a---- 10/8/2017 4:57 PM 2139 cool-new-thing.py.encrypted.decrypted
-a---- 10/8/2017 4:57 PM 46 Employees.csv.encrypted.decrypted
-a---- 10/8/2017 4:57 PM 11 Hello.txt.encrypted.decrypted
```
------
## Mengenkripsi dan mendekripsi pada baris perintah
Contoh-contoh ini menunjukkan cara menyalurkan input ke perintah (stdin) dan menulis output ke baris perintah (stdout). Mereka menjelaskan cara merepresentasikan stdin dan stdout dalam sebuah perintah dan cara menggunakan alat pengkodean Base64 bawaan untuk mencegah shell salah menafsirkan karakter non-ASCII.
Contoh ini menyalurkan string teks biasa ke perintah enkripsi dan menyimpan pesan terenkripsi dalam variabel. Kemudian, ia menyalurkan pesan terenkripsi dalam variabel ke perintah dekripsi, yang menulis outputnya ke pipeline (stdout).
Contohnya terdiri dari tiga perintah:
+ Perintah pertama menyimpan [ARN kunci](https://docs.aws.amazon.com/kms/latest/developerguide/concepts.html#key-id-key-ARN) dari AWS KMS key variabel. `$keyArn`
------
#### [ Bash ]
```
$ keyArn=arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab
```
------
#### [ PowerShell ]
```
PS C:\> $keyArn = 'arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab'
```
------
+ Perintah kedua `Hello World` menyalurkan string ke perintah enkripsi dan menyimpan hasilnya dalam `$encrypted` variabel.
`--output`Parameter `--input` dan diperlukan di semua perintah AWS Enkripsi CLI. Untuk menunjukkan bahwa input sedang disalurkan ke perintah (stdin), gunakan tanda hubung (`-`) untuk nilai parameter. `--input` Untuk mengirim output ke baris perintah (stdout), gunakan tanda hubung untuk nilai parameter. `--output`
`--encode`Parameter Base64-mengkodekan output sebelum mengembalikannya. Ini mencegah shell salah menafsirkan karakter non-ASCII dalam pesan terenkripsi.
Karena perintah ini hanyalah bukti konsep, kami menghilangkan konteks enkripsi dan menekan metadata (). `-S`
------
#### [ Bash ]
```
$ encrypted=$(echo 'Hello World' | aws-encryption-cli --encrypt -S \
--input - --output - --encode \
--wrapping-keys key=$keyArn )
```
------
#### [ PowerShell ]
```
PS C:\> $encrypted = 'Hello World' | aws-encryption-cli --encrypt -S `
--input - --output - --encode `
--wrapping-keys key=$keyArn
```
------
+ Perintah ketiga menyalurkan pesan terenkripsi dalam `$encrypted` variabel ke perintah dekripsi.
Perintah dekripsi ini digunakan `--input -` untuk menunjukkan bahwa input berasal dari pipeline (stdin) dan `--output -` untuk mengirim output ke pipeline (stdout). (Parameter input mengambil lokasi input, bukan byte input yang sebenarnya, sehingga Anda tidak dapat menggunakan `$encrypted` variabel sebagai nilai `--input` parameter.)
Contoh ini menggunakan atribut **penemuan** `--wrapping-keys` parameter untuk memungkinkan CLI AWS Enkripsi menggunakan apapun AWS KMS key untuk mendekripsi data. Itu tidak menentukan [kebijakan komitmen](concepts.md#commitment-policy), sehingga menggunakan nilai default untuk versi 2.1. *x* dan kemudian, `require-encrypt-require-decrypt`
Karena output dienkripsi dan kemudian dikodekan, perintah dekripsi menggunakan `--decode` parameter untuk memecahkan kode input yang dikodekan Base64 sebelum mendekripsi. Anda juga dapat menggunakan `--decode` parameter untuk memecahkan kode input yang dikodekan Base64 sebelum mengenkripsinya.
Sekali lagi, perintah menghilangkan konteks enkripsi dan menekan metadata (-). `S`
------
#### [ Bash ]
```
$ echo $encrypted | aws-encryption-cli --decrypt --wrapping-keys discovery=true --input - --output - --decode --buffer -S
Hello World
```
------
#### [ PowerShell ]
```
PS C:\> $encrypted | aws-encryption-cli --decrypt --wrapping-keys discovery=$true --input - --output - --decode --buffer -S
Hello World
```
------
Anda juga dapat melakukan operasi enkripsi dan dekripsi dalam satu perintah tanpa variabel intervensi.
Seperti pada contoh sebelumnya, `--output` parameter `--input` dan memiliki `-` nilai dan perintah menggunakan `--encode` parameter untuk menyandikan output dan `--decode` parameter untuk memecahkan kode input.
------
#### [ Bash ]
```
$ keyArn=arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab
$ echo 'Hello World' |
aws-encryption-cli --encrypt --wrapping-keys key=$keyArn --input - --output - --encode -S |
aws-encryption-cli --decrypt --wrapping-keys discovery=true --input - --output - --decode -S
Hello World
```
------
#### [ PowerShell ]
```
PS C:\> $keyArn = 'arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab'
PS C:\> 'Hello World' |
aws-encryption-cli --encrypt --wrapping-keys key=$keyArn --input - --output - --encode -S |
aws-encryption-cli --decrypt --wrapping-keys discovery=$true --input - --output - --decode -S
Hello World
```
------
## Menggunakan beberapa kunci master
Contoh ini menunjukkan cara menggunakan beberapa kunci master saat mengenkripsi dan mendekripsi data di CLI Enkripsi. AWS
Bila Anda menggunakan beberapa kunci master untuk mengenkripsi data, salah satu kunci master dapat digunakan untuk mendekripsi data. Strategi ini memastikan bahwa Anda dapat mendekripsi data bahkan jika salah satu kunci master tidak tersedia. Jika Anda menyimpan data terenkripsi dalam beberapa Wilayah AWS, strategi ini memungkinkan Anda menggunakan kunci master di Wilayah yang sama untuk mendekripsi data.
Saat Anda mengenkripsi dengan beberapa kunci master, kunci master pertama memainkan peran khusus. Ini menghasilkan kunci data yang digunakan untuk mengenkripsi data. Kunci master yang tersisa mengenkripsi kunci data teks biasa. [Pesan terenkripsi yang](concepts.md#message) dihasilkan mencakup data terenkripsi dan kumpulan kunci data terenkripsi, satu untuk setiap kunci master. Meskipun kunci master pertama menghasilkan kunci data, salah satu kunci master dapat mendekripsi salah satu kunci data, yang dapat digunakan untuk mendekripsi data.
**Mengenkripsi dengan tiga kunci utama**
Perintah contoh ini menggunakan tiga kunci pembungkus untuk mengenkripsi `Finance.log` file, satu di masing-masing tiga. Wilayah AWS
Ini menulis pesan terenkripsi ke direktori. `Archive` Perintah menggunakan `--suffix` parameter tanpa nilai untuk menekan akhiran, sehingga nama file input dan output akan sama.
Perintah menggunakan `--wrapping-keys` parameter dengan tiga atribut **kunci**. Anda juga dapat menggunakan beberapa `--wrapping-keys` parameter dalam perintah yang sama.
Untuk mengenkripsi file log, CLI AWS Enkripsi meminta kunci pembungkus pertama dalam daftar`$key1`,, untuk menghasilkan kunci data yang digunakannya untuk mengenkripsi data. Kemudian, ia menggunakan masing-masing kunci pembungkus lainnya untuk mengenkripsi salinan teks biasa dari kunci data yang sama. Pesan terenkripsi dalam file output mencakup ketiga kunci data terenkripsi.
------
#### [ Bash ]
```
$ key1=arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab
$ key2=arn:aws:kms:us-east-2:111122223333:key/0987ab65-43cd-21ef-09ab-87654321cdef
$ key3=arn:aws:kms:ap-southeast-1:111122223333:key/1a2b3c4d-5e6f-1a2b-3c4d-5e6f1a2b3c4d
$ aws-encryption-cli --encrypt --input /logs/finance.log \
--output /archive --suffix \
--encryption-context class=log \
--metadata-output ~/metadata \
--wrapping-keys key=$key1 key=$key2 key=$key3
```
------
#### [ PowerShell ]
```
PS C:\> $key1 = 'arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab'
PS C:\> $key2 = 'arn:aws:kms:us-east-2:111122223333:key/0987ab65-43cd-21ef-09ab-87654321cdef'
PS C:\> $key3 = 'arn:aws:kms:ap-southeast-1:111122223333:key/1a2b3c4d-5e6f-1a2b-3c4d-5e6f1a2b3c4d'
PS C:\> aws-encryption-cli --encrypt --input D:\Logs\Finance.log `
--output D:\Archive --suffix `
--encryption-context class=log `
--metadata-output $home\Metadata.txt `
--wrapping-keys key=$key1 key=$key2 key=$key3
```
------
Perintah ini mendekripsi salinan `Finance.log` file yang dienkripsi dan menulisnya ke `Finance.log.clear` file di direktori. `Finance` Untuk mendekripsi data yang dienkripsi di bawah tiga AWS KMS keys, Anda dapat menentukan tiga AWS KMS keys atau subset yang sama. Contoh ini hanya menentukan salah satu dari. AWS KMS keys
Untuk memberi tahu CLI AWS Enkripsi yang AWS KMS keys akan digunakan untuk mendekripsi data Anda, gunakan atribut **kunci parameter**. `--wrapping-keys` Saat mendekripsi dengan AWS KMS keys, nilai atribut **kunci** harus berupa [ARN](https://docs.aws.amazon.com/kms/latest/developerguide/concepts.html#key-id-key-ARN) kunci.
Anda harus memiliki izin untuk memanggil [Decrypt API](https://docs.aws.amazon.com/kms/latest/APIReference/API_Decrypt.html) pada yang AWS KMS keys Anda tentukan. Untuk informasi selengkapnya, lihat [Otentikasi dan Kontrol Akses untuk AWS KMS](https://docs.aws.amazon.com/kms/latest/developerguide/control-access.html).
Sebagai praktik terbaik, contoh ini menggunakan `--max-encrypted-data-keys` parameter untuk menghindari dekripsi pesan yang salah dengan jumlah kunci data terenkripsi yang berlebihan. Meskipun contoh ini hanya menggunakan satu kunci pembungkus untuk dekripsi, pesan terenkripsi memiliki tiga (3) kunci data terenkripsi; satu untuk masing-masing dari tiga kunci pembungkus yang digunakan saat mengenkripsi. Tentukan jumlah yang diharapkan dari kunci data terenkripsi atau nilai maksimum yang wajar, seperti 5. Jika Anda menentukan nilai maksimum kurang dari 3, perintah gagal. Lihat perinciannya di [Membatasi kunci data terenkripsi](configure.md#config-limit-keys).
------
#### [ Bash ]
```
$ aws-encryption-cli --decrypt --input /archive/finance.log \
--wrapping-keys key=$key1 \
--output /finance --suffix '.clear' \
--metadata-output ~/metadata \
--max-encrypted-data-keys 3 \
--buffer \
--encryption-context class=log
```
------
#### [ PowerShell ]
```
PS C:\> aws-encryption-cli --decrypt `
--input D:\Archive\Finance.log `
--wrapping-keys key=$key1 `
--output D:\Finance --suffix '.clear' `
--metadata-output .\Metadata\Metadata.txt `
--max-encrypted-data-keys 3 `
--buffer `
--encryption-context class=log
```
------
## Mengenkripsi dan mendekripsi dalam skrip
Contoh ini menunjukkan cara menggunakan CLI AWS Enkripsi dalam skrip. Anda dapat menulis skrip yang hanya mengenkripsi dan mendekripsi data, atau skrip yang mengenkripsi atau mendekripsi sebagai bagian dari proses manajemen data.
Dalam contoh ini, skrip mendapatkan koleksi file log, mengompresnya, mengenkripsi mereka, dan kemudian menyalin file terenkripsi ke bucket Amazon S3. Skrip ini memproses setiap file secara terpisah, sehingga Anda dapat mendekripsi dan mengembangkannya secara independen.
Saat Anda mengompres dan mengenkripsi file, pastikan untuk mengompres sebelum Anda mengenkripsi. Data yang dienkripsi dengan benar tidak dapat dikompresi.
**Awas**
Hati-hati saat mengompresi data yang mencakup rahasia dan data yang mungkin dikendalikan oleh aktor jahat. Ukuran akhir dari data terkompresi mungkin secara tidak sengaja mengungkapkan informasi sensitif tentang isinya.
------
#### [ Bash ]
```
# Continue running even if an operation fails.
set +e
dir=$1
encryptionContext=$2
s3bucket=$3
s3folder=$4
masterKeyProvider="aws-kms"
metadataOutput="/tmp/metadata-$(date +%s)"
compress(){
gzip -qf $1
}
encrypt(){
# -e encrypt
# -i input
# -o output
# --metadata-output unique file for metadata
# -m masterKey read from environment variable
# -c encryption context read from the second argument.
# -v be verbose
aws-encryption-cli -e -i ${1} -o $(dirname ${1}) --metadata-output ${metadataOutput} -m key="${masterKey}" provider="${masterKeyProvider}" -c "${encryptionContext}" -v
}
s3put (){
# copy file argument 1 to s3 location passed into the script.
aws s3 cp ${1} ${s3bucket}/${s3folder}
}
# Validate all required arguments are present.
if [ "${dir}" ] && [ "${encryptionContext}" ] && [ "${s3bucket}" ] && [ "${s3folder}" ] && [ "${masterKey}" ]; then
# Is $dir a valid directory?
test -d "${dir}"
if [ $? -ne 0 ]; then
echo "Input is not a directory; exiting"
exit 1
fi
# Iterate over all the files in the directory, except *gz and *encrypted (in case of a re-run).
for f in $(find ${dir} -type f \( -name "*" ! -name \*.gz ! -name \*encrypted \) ); do
echo "Working on $f"
compress ${f}
encrypt ${f}.gz
rm -f ${f}.gz
s3put ${f}.gz.encrypted
done;
else
echo "Arguments: "
echo " and ENV var \$masterKey must be set"
exit 255
fi
```
------
#### [ PowerShell ]
```
#Requires -Modules AWSPowerShell, Microsoft.PowerShell.Archive
Param
(
[Parameter(Mandatory)]
[ValidateScript({Test-Path $_})]
[String[]]
$FilePath,
[Parameter()]
[Switch]
$Recurse,
[Parameter(Mandatory=$true)]
[String]
$wrappingKeyID,
[Parameter()]
[String]
$masterKeyProvider = 'aws-kms',
[Parameter(Mandatory)]
[ValidateScript({Test-Path $_})]
[String]
$ZipDirectory,
[Parameter(Mandatory)]
[ValidateScript({Test-Path $_})]
[String]
$EncryptDirectory,
[Parameter()]
[String]
$EncryptionContext,
[Parameter(Mandatory)]
[ValidateScript({Test-Path $_})]
[String]
$MetadataDirectory,
[Parameter(Mandatory)]
[ValidateScript({Test-S3Bucket -BucketName $_})]
[String]
$S3Bucket,
[Parameter()]
[String]
$S3BucketFolder
)
BEGIN {}
PROCESS {
if ($files = dir $FilePath -Recurse:$Recurse)
{
# Step 1: Compress
foreach ($file in $files)
{
$fileName = $file.Name
try
{
Microsoft.PowerShell.Archive\Compress-Archive -Path $file.FullName -DestinationPath $ZipDirectory\$filename.zip
}
catch
{
Write-Error "Zip failed on $file.FullName"
}
# Step 2: Encrypt
if (-not (Test-Path "$ZipDirectory\$filename.zip"))
{
Write-Error "Cannot find zipped file: $ZipDirectory\$filename.zip"
}
else
{
# 2>&1 captures command output
$err = (aws-encryption-cli -e -i "$ZipDirectory\$filename.zip" `
-o $EncryptDirectory `
-m key=$wrappingKeyID provider=$masterKeyProvider `
-c $EncryptionContext `
--metadata-output $MetadataDirectory `
-v) 2>&1
# Check error status
if ($? -eq $false)
{
# Write the error
$err
}
elseif (Test-Path "$EncryptDirectory\$fileName.zip.encrypted")
{
# Step 3: Write to S3 bucket
if ($S3BucketFolder)
{
Write-S3Object -BucketName $S3Bucket -File "$EncryptDirectory\$fileName.zip.encrypted" -Key "$S3BucketFolder/$fileName.zip.encrypted"
}
else
{
Write-S3Object -BucketName $S3Bucket -File "$EncryptDirectory\$fileName.zip.encrypted"
}
}
}
}
}
}
```
------
## Menggunakan caching kunci data
Contoh ini menggunakan [caching kunci data](data-key-caching.md) dalam perintah yang mengenkripsi sejumlah besar file.
Secara default, CLI AWS Enkripsi (dan versi lain dari AWS Encryption SDK) menghasilkan kunci data unik untuk setiap file yang dienkripsi. Meskipun menggunakan kunci data unik untuk setiap operasi adalah praktik terbaik kriptografi, penggunaan kembali kunci data yang terbatas dapat diterima untuk beberapa situasi. Jika Anda mempertimbangkan caching kunci data, konsultasikan dengan insinyur keamanan untuk memahami persyaratan keamanan aplikasi Anda dan tentukan ambang keamanan yang tepat untuk Anda.
Dalam contoh ini, caching kunci data mempercepat operasi enkripsi dengan mengurangi frekuensi permintaan ke penyedia kunci master.
Perintah dalam contoh ini mengenkripsi direktori besar dengan beberapa subdirektori yang berisi total sekitar 800 file log kecil. Perintah pertama menyimpan ARN dari AWS KMS key dalam variabel. `keyARN` Perintah kedua mengenkripsi semua file dalam direktori input (rekursif) dan menulisnya ke direktori arsip. Perintah menggunakan `--suffix` parameter untuk menentukan `.archive` sufiks.
`--caching`Parameter memungkinkan caching kunci data. Atribut **kapasitas**, yang membatasi jumlah kunci data dalam cache, diatur ke 1, karena pemrosesan file serial tidak pernah menggunakan lebih dari satu kunci data pada satu waktu. Atribut **max\$1age**, yang menentukan berapa lama kunci data cache dapat digunakan, diatur ke 10 detik.
Atribut **max\$1messages\$1encrypted** opsional disetel ke 10 pesan, sehingga satu kunci data tidak pernah digunakan untuk mengenkripsi lebih dari 10 file. Membatasi jumlah file yang dienkripsi oleh setiap kunci data mengurangi jumlah file yang akan terpengaruh jika kunci data dikompromikan.
Untuk menjalankan perintah ini pada file log yang dihasilkan sistem operasi Anda, Anda mungkin memerlukan izin administrator (`sudo`di Linux; **Jalankan sebagai Administrator** di Windows).
------
#### [ Bash ]
```
$ keyArn=arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab
$ aws-encryption-cli --encrypt \
--input /var/log/httpd --recursive \
--output ~/archive --suffix .archive \
--wrapping-keys key=$keyArn \
--encryption-context class=log \
--suppress-metadata \
--caching capacity=1 max_age=10 max_messages_encrypted=10
```
------
#### [ PowerShell ]
```
PS C:\> $keyARN = 'arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab'
PS C:\> aws-encryption-cli --encrypt `
--input C:\Windows\Logs --recursive `
--output $home\Archive --suffix '.archive' `
--wrapping-keys key=$keyARN `
--encryption-context class=log `
--suppress-metadata `
--caching capacity=1 max_age=10 max_messages_encrypted=10
```
------
Untuk menguji efek caching kunci data, contoh ini menggunakan cmdlet [Measure-Command](https://docs.microsoft.com/en-us/powershell/module/microsoft.powershell.utility/measure-command) in. PowerShell Ketika Anda menjalankan contoh ini tanpa caching kunci data, dibutuhkan sekitar 25 detik untuk menyelesaikannya. Proses ini menghasilkan kunci data baru untuk setiap file dalam direktori.
```
PS C:\> Measure-Command {aws-encryption-cli --encrypt `
--input C:\Windows\Logs --recursive `
--output $home\Archive --suffix '.archive' `
--wrapping-keys key=$keyARN `
--encryption-context class=log `
--suppress-metadata }
Days : 0
Hours : 0
Minutes : 0
Seconds : 25
Milliseconds : 453
Ticks : 254531202
TotalDays : 0.000294596298611111
TotalHours : 0.00707031116666667
TotalMinutes : 0.42421867
TotalSeconds : 25.4531202
TotalMilliseconds : 25453.1202
```
Caching kunci data membuat proses lebih cepat, bahkan ketika Anda membatasi setiap kunci data hingga maksimal 10 file. Perintah sekarang membutuhkan waktu kurang dari 12 detik untuk menyelesaikan dan mengurangi jumlah panggilan ke penyedia kunci master menjadi 1/10 dari nilai aslinya.
```
PS C:\> Measure-Command {aws-encryption-cli --encrypt `
--input C:\Windows\Logs --recursive `
--output $home\Archive --suffix '.archive' `
--wrapping-keys key=$keyARN `
--encryption-context class=log `
--suppress-metadata `
--caching capacity=1 max_age=10 max_messages_encrypted=10}
Days : 0
Hours : 0
Minutes : 0
Seconds : 11
Milliseconds : 813
Ticks : 118132640
TotalDays : 0.000136727592592593
TotalHours : 0.00328146222222222
TotalMinutes : 0.196887733333333
TotalSeconds : 11.813264
TotalMilliseconds : 11813.264
```
Jika Anda menghilangkan `max_messages_encrypted` batasan, semua file dienkripsi di bawah kunci data yang sama. Perubahan ini meningkatkan risiko menggunakan kembali kunci data tanpa membuat proses lebih cepat. Namun, ini mengurangi jumlah panggilan ke penyedia kunci master menjadi 1.
```
PS C:\> Measure-Command {aws-encryption-cli --encrypt `
--input C:\Windows\Logs --recursive `
--output $home\Archive --suffix '.archive' `
--wrapping-keys key=$keyARN `
--encryption-context class=log `
--suppress-metadata `
--caching capacity=1 max_age=10}
Days : 0
Hours : 0
Minutes : 0
Seconds : 10
Milliseconds : 252
Ticks : 102523367
TotalDays : 0.000118661304398148
TotalHours : 0.00284787130555556
TotalMinutes : 0.170872278333333
TotalSeconds : 10.2523367
TotalMilliseconds : 10252.3367
```
# AWS Encryption SDK Sintaks CLI dan referensi parameter
Topik ini menyediakan diagram sintaks dan deskripsi parameter singkat untuk membantu Anda menggunakan AWS Encryption SDK Command Line Interface (CLI). Untuk bantuan dengan kunci pembungkus dan parameter lainnya, lihat[Cara menggunakan CLI AWS Enkripsi](crypto-cli-how-to.md). Sebagai contoh, lihat [Contoh CLI AWS Enkripsi](crypto-cli-examples.md). Untuk dokumentasi selengkapnya, lihat [Membaca Dokumen.](https://aws-encryption-sdk-cli.readthedocs.io/en/latest/)
**Topics**
+ [
## AWS Sintaks CLI enkripsi
](#crypto-cli-syntax)
+ [
## AWS Parameter baris perintah CLI enkripsi
](#crypto-cli-parameters)
+ [
## Parameter lanjutan
](#cli-advanced-parameters)
## AWS Sintaks CLI enkripsi
Diagram sintaks AWS Enkripsi CLI ini menunjukkan sintaks untuk setiap tugas yang Anda lakukan dengan CLI Enkripsi. AWS Mereka mewakili sintaks yang direkomendasikan dalam AWS Enkripsi CLI versi 2.1. *x* dan kemudian.
Fitur keamanan baru awalnya dirilis dalam AWS Enkripsi CLI versi 1.7. *x* dan 2.0. *x*. Namun, AWS Enkripsi CLI versi 1.8. *x* menggantikan versi 1.7. *x* dan AWS Enkripsi CLI 2.1. *x* menggantikan 2.0. *x*. Untuk detailnya, lihat [penasihat keamanan](https://github.com/aws/aws-encryption-sdk-cli/security/advisories/GHSA-2xwp-m7mq-7q3r) yang relevan di [aws-encryption-sdk-cli](https://github.com/aws/aws-encryption-sdk-cli/)repositori di. GitHub
**catatan**
Kecuali dicatat dalam deskripsi parameter, setiap parameter atau atribut hanya dapat digunakan sekali dalam setiap perintah.
Jika Anda menggunakan atribut yang parameter tidak mendukung, CLI AWS Enkripsi mengabaikan atribut yang tidak didukung tanpa peringatan atau kesalahan.
**Mencari bantuan**
Untuk mendapatkan sintaks AWS Enkripsi CLI lengkap dengan deskripsi parameter, gunakan atau. `--help` `-h`
```
aws-encryption-cli (--help | -h)
```
**Dapatkan versinya**
Untuk mendapatkan nomor versi instalasi CLI AWS Enkripsi Anda, gunakan. `--version` Pastikan untuk menyertakan versi saat Anda mengajukan pertanyaan, melaporkan masalah, atau berbagi tips tentang menggunakan CLI AWS Enkripsi.
```
aws-encryption-cli --version
```
**Enkripsi data**
Diagram sintaks berikut menunjukkan parameter yang digunakan **encrypt** perintah.
```
aws-encryption-cli --encrypt
--input [--recursive] [--decode]
--output