Mengenkripsi teks biasa menjadi teks terenkripsi. - Key Management Service

Topik ini menjelaskan cara mengenkripsi teks biasa menjadi teks terenkripsi.

Petunjuk operasi

Operasi ini hanya dapat digunakan untuk kunci simetris dalam instance Key Management Service (KMS) tipe manajemen kunci perangkat lunak. Untuk informasi lebih lanjut tentang spesifikasi kunci, mode enkripsi, dan versi kunci, lihat Spesifikasi Kunci untuk Enkripsi Simetris dan Asimetris.

Anda dapat menggunakan operasi AdvanceEncrypt atau Encrypt untuk mengenkripsi teks biasa menjadi teks terenkripsi. Perhatikan perbedaan berikut antara kedua operasi:

AdvanceEncrypt: Versi utama kunci digunakan untuk mengenkripsi teks biasa menjadi teks terenkripsi. Anda harus memanggil operasi AdvanceDecrypt untuk mendekripsi teks terenkripsi.
Encrypt: Versi awal kunci digunakan untuk mengenkripsi teks biasa menjadi teks terenkripsi. Anda dapat memanggil operasi Decrypt atau AdvanceDecrypt untuk mendekripsi teks terenkripsi.

Penting

Jika Anda mengaktifkan rotasi kunci otomatis, Anda harus menggunakan operasi AdvanceEncrypt untuk mencegah fitur rotasi kunci menjadi tidak valid. Untuk informasi lebih lanjut tentang rotasi kunci otomatis, lihat Konfigurasi Rotasi Kunci.

Catatan penggunaan

Pastikan bahwa badan permintaan tidak melebihi 3 MB setelah semua parameter permintaan dienkripsi menggunakan Protocol Buffers. Jika badan permintaan melebihi 3 MB, server akan menolak permintaan dan mengembalikan kode status HTTP 413. Kami merekomendasikan agar Anda membatasi ukuran data hingga 6 KB untuk enkripsi dan dekripsi dalam satu operasi. Jika data melebihi batas tersebut, kami merekomendasikan penggunaan enkripsi amplop. Untuk informasi lebih lanjut, lihat Gunakan Enkripsi Amplop.

Catatan

Jumlah data yang besar dalam satu enkripsi atau dekripsi meningkatkan risiko kegagalan jaringan, memperpanjang waktu transmisi jaringan, serta durasi yang diperlukan oleh KMS untuk mengenkripsi dan mendekripsi data.

Parameter permintaan

Parameter	Tipe	Diperlukan	Contoh	Deskripsi
KeyId	string	Ya	key-hzz62f1cb66fa42qo****	ID unik global dari kunci. Anda dapat menyetel parameter ini ke alias yang terikat pada kunci. Penting Kunci harus merupakan kunci simetris dalam instance KMS tipe manajemen kunci perangkat lunak.
Plaintext	bytes	Ya	Data biner	Teks biasa yang ingin Anda enkripsi.
Algorithm	string	Tidak	AES_GCM	Algoritma enkripsi. Jika Anda tidak menyetel parameter ini, KMS menggunakan nilai default. Untuk informasi lebih lanjut, lihat Spesifikasi kunci untuk enkripsi simetris dan asimetris.
Iv	bytes	Tidak	Data biner	Vektor awal yang digunakan untuk mengenkripsi data. Parameter ini berlaku hanya ketika Algorithm disetel ke AES_GCM atau AES_CBC. Jika Algorithm disetel ke AES_CBC, nilai Iv harus 16 byte panjangnya. Jika Algorithm disetel ke AES_GCM, nilai Iv harus 12 byte panjangnya. Jika Anda tidak menyetel parameter ini, KMS menghasilkan angka acak. Penting Kami merekomendasikan agar Anda tidak menyetel parameter ini.
Aad	binary	Tidak	Data biner	Data autentikasi saat mode GCM digunakan untuk mengenkripsi kunci data. Jika Algorithm disetel ke AES_GCM, Anda dapat menggunakan parameter ini sesuai dengan kebutuhan bisnis Anda. Penting Jika Aad disetel, Anda harus menyetel parameter yang sama saat Anda memanggil operasi AdvanceDecrypt.
PaddingMode	string	Tidak	PKCS7_PADDING	Mode padding. Parameter ini diperlukan hanya ketika Algorithm disetel ke AES_CBC atau AES_ECB. Nilai yang valid: PKCS7_PADDING: Padding PKCS#7 digunakan. Ini adalah nilai default. Panjang teks biasa atau teks terenkripsi mungkin bukan kelipatan bulat dari ukuran blok cipher dalam byte. Jika input teks biasa atau teks terenkripsi adalah L byte panjangnya, sistem menambahkan string padding sepanjang K -(L mod K) byte. Setiap string padding memiliki panjang K -(L mod K) byte. NO_PADDING: String padding tidak ditambahkan ke teks biasa. Panjang teks biasa harus merupakan kelipatan bulat dari ukuran blok cipher dalam byte.

Parameter respons

Parameter	Tipe	Contoh	Deskripsi
CiphertextBlob	bytes	Data biner	Teks terenkripsi dari teks biasa yang dienkripsi menggunakan kunci. Catatan CiphertextBlob berisi informasi tentang KeyId, Algorithm, PaddingMode, dan Iv. Anda hanya perlu menyetel CiphertextBlob saat Anda memanggil operasi AdvanceDecrypt untuk mendekripsi data.
Algorithm	string	AES_GCM	Algoritma enkripsi.
KeyId	string	key-hzz62f1cb66fa42qo****	ID unik global dari kunci. Jika Anda menyetel KeyId dalam permintaan ke alias kunci, ID kunci yang terikat pada alias dikembalikan.
KeyVersionId	string	key-hzz62f1cb66fa42qopd9s-17kedv****	Versi kunci. Versi utama digunakan.
Iv	bytes	Data biner	Vektor awal yang digunakan untuk mengenkripsi data. Nilai valid dikembalikan hanya ketika Algorithm disetel ke AES_GCM atau AES_CBC. Dalam skenario lain, nilai kosong dikembalikan.
PaddingMode	string	PKCS7_PADDING	Mode padding. Parameter ini mengembalikan nilai valid hanya ketika Algorithm disetel ke AES_CBC atau AES_ECB. Dalam skenario lain, nilai kosong dikembalikan.
RequestId	string	c0037a6d-7784-4ef2-a692-288fdefc7b9d	ID permintaan, yang digunakan untuk melokasi dan menyelesaikan masalah.

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. Catatan Enkripsi asimetris digunakan untuk enkripsi data atau pertukaran kunci lintas domain keamanan. Dalam hal ini, KMS tidak digunakan di salah satu sisi.

Untuk daftar kode kesalahan, lihat Kode Kesalahan Layanan.