Anda dapat memanggil operasi ini untuk menghasilkan kunci data dan mengenkripsi data menggunakan enkripsi amplop dari Key Management Service (KMS).
Catatan penggunaan
Ikhtisar
Operasi ini menghasilkan kunci data menggunakan generator angka acak, mengenkripsi kunci data menggunakan versi utama KMS key, dan mengembalikan kunci data teks biasa serta kunci data teks terenkripsi. Anda dapat menggunakan kunci data teks biasa untuk mengenkripsi data di luar KMS. Plaintext menunjukkan kunci data teks biasa. Pastikan menyimpan kunci data teks terenkripsi dan data autentikasi (Aad) yang digunakan untuk mendekripsi data.
Hanya mode Galois/Counter Mode (GCM) yang didukung saat mengenkripsi kunci data.
KMS menggunakan generator angka acak berkualitas tinggi untuk menghasilkan kunci data, yang independen dari materi kunci KMS yang digunakan untuk mengenkripsi kunci data.
Perbedaan antara AdvanceGenerateDataKey dan GenerateDataKey
Anda dapat memanggil operasi AdvanceGenerateDataKey atau GenerateDataKey untuk menghasilkan kunci data. Berikut adalah perbedaan antara kedua operasi tersebut:
AdvanceGenerateDataKey: Versi utama kunci digunakan untuk enkripsi. Setelah enkripsi, Anda harus menyimpan kunci data teks terenkripsi (CiphertextBlob) dan data autentikasi (Aad). Untuk mendekripsi data, panggil operasi AdvanceDecrypt.
GenerateDataKey: Versi awal kunci digunakan untuk enkripsi. Setelah enkripsi, Anda harus menyimpan kunci data teks terenkripsi (CiphertextBlob), vektor awal (Iv), algoritma enkripsi (Algorithm), dan data autentikasi (Aad). Anda dapat memanggil operasi Decrypt atau AdvanceDecrypt untuk mendekripsi data.
Jika rotasi kunci otomatis diaktifkan, Anda harus memanggil operasi AdvanceGenerateDataKey untuk menghasilkan kunci data guna mencegah fitur rotasi kunci menjadi tidak valid. Untuk informasi lebih lanjut tentang rotasi kunci, lihat Konfigurasi Rotasi Kunci.
Batasan
Operasi ini hanya dapat dipanggil untuk kunci simetris dalam instance KMS tipe manajemen kunci perangkat lunak. Untuk informasi lebih lanjut tentang spesifikasi kunci dan mode enkripsi, lihat Tipe dan Spesifikasi Kunci.
Parameter permintaan
Parameter | Tipe | Diperlukan | Contoh | Deskripsi |
KeyId | string | Ya. | key-hzz62f1cb66fa42qo**** | ID unik global dari kunci. Anda dapat menetapkan nilai ke alias yang terikat pada kunci. Penting Kunci harus berupa kunci simetris dalam instance KMS tipe manajemen kunci perangkat lunak. |
NumberOfBytes | int | Ya | 32 | Panjang kunci data yang akan dihasilkan. |
Aad | binary | Tidak | Data biner | Data autentikasi saat Anda mengenkripsi kunci data dalam mode GCM. Penting Jika Anda menentukan parameter ini, Anda harus menentukan Aad saat Anda memanggil operasi AdvanceDecrypt. |
Parameter respons
Parameter | Tipe | Contoh | Deskripsi |
CiphertextBlob | bytes | Teks terenkripsi biner | Kunci data teks terenkripsi. Catatan CiphertextBlob berisi informasi seperti ID kunci (KeyId), algoritma enkripsi (Algorithm), dan vektor awal (Iv) yang digunakan untuk mengenkripsi data. Saat Anda memanggil operasi AdvanceDecrypt untuk mendekripsi data, Anda hanya perlu mengonfigurasi CiphertextBlob dan Aad. |
Plaintext | bytes | Teks biasa biner | Kunci data teks biasa. |
KeyId | string | key-hzz62f1cb66fa42qo**** | ID unik global dari kunci. Jika KeyId dalam permintaan diatur ke alias, ID unik global dari kunci yang terikat dengan alias dikembalikan dalam respons. |
KeyVersionId | string | key-hzz62f1cb66fa42qo****-17kedv**** | ID versi kunci yang digunakan untuk mengenkripsi kunci data. |
Algorithm | string | AES_GCM | Algoritma enkripsi. |
Iv | bytes | Data biner | Vektor awal yang digunakan untuk mengenkripsi kunci data. |
RequestId | string | c0065a6d-7784-4ef2-a692-288fdcbc7b9d | ID permintaan. |
Kode kesalahan
Kode status HTTP | Kode kesalahan | Pesan kesalahan | Deskripsi |
404 | Forbidden.OnlySymmetricKeySupported | Kunci %s bukan kunci simetris. API hanya mendukung kunci simetris. | Hanya kunci simetris yang didukung. |
Untuk daftar kode kesalahan, lihat Kode Kesalahan Layanan.