Mengenkripsi teks biasa menjadi teks terenkripsi.

Petunjuk operasi

Anda dapat memanggil operasi Enkripsi atau AdvanceEncrypt untuk mengenkripsi teks biasa menjadi teks terenkripsi. Berikut adalah perbedaan antara kedua operasi tersebut:

Enkripsi: Menggunakan versi awal kunci untuk enkripsi. Setelah enkripsi, Anda dapat memanggil operasi Dekripsi atau AdvanceDecrypt untuk mendekripsi data yang telah dienkripsi.
AdvanceEncrypt: Menggunakan versi utama kunci untuk enkripsi. Setelah enkripsi, Anda harus memanggil operasi AdvanceDecrypt untuk mendekripsi data. Hanya kunci simetris dalam instance Key Management Service (KMS) dari tipe manajemen kunci perangkat lunak yang mendukung operasi ini.

Penting

Jika Anda menggunakan kunci simetris dalam instance KMS dari tipe manajemen kunci perangkat lunak dan mengaktifkan rotasi otomatis untuk kunci, Anda harus memanggil operasi AdvanceEncrypt untuk mencegah fitur rotasi kunci menjadi tidak valid. Untuk informasi lebih lanjut tentang rotasi kunci, lihat Konfigurasikan rotasi kunci.

Untuk informasi lebih lanjut tentang spesifikasi kunci, mode enkripsi, dan versi kunci, lihat Spesifikasi kunci untuk enkripsi simetris dan asimetris.

Catatan penggunaan

Pastikan bahwa badan permintaan tidak melebihi 3 MB setelah semua parameter permintaan dikodekan 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 menggunakan kunci simetris dan 1 KB untuk enkripsi dan dekripsi menggunakan kunci asimetris 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 untuk KMS mengenkripsi dan mendekripsi data.

Parameter permintaan

Parameter	Tipe	Diperlukan	Contoh	Deskripsi
KeyId	string	Ya	key-hzz62f1cb66fa42qo****	ID unik global dari kunci. Anda dapat menetapkan parameter ini ke alias yang terikat pada kunci.
Plaintext	bytes	Ya	Data biner	Teks biasa yang ingin Anda enkripsi.
Algoritma	string	Tidak	AES_GCM	Algoritma enkripsi. Jika Anda tidak menetapkan 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 hanya berlaku ketika Algoritma disetel ke AES_GCM atau AES_CBC. Jika Algoritma disetel ke AES_CBC, nilai Iv harus memiliki panjang 16 byte. Jika Algoritma disetel ke AES_GCM, nilai Iv harus memiliki panjang 12 byte. Jika Anda tidak menetapkan parameter ini, KMS menghasilkan angka acak. Penting Kami merekomendasikan agar Anda tidak menetapkan parameter ini.
Aad	biner	Tidak	Data biner	Mode enkripsi GCM yang digunakan untuk mengotentikasi data. Jika kunci adalah kunci simetris dan Algoritma disetel ke AES_GCM atau SM4_GCM, Anda dapat menentukan parameter ini. Penting Jika Anda menentukan parameter ini, Anda harus menentukan parameter ini saat memanggil operasi Dekripsi.
PaddingMode	string	Tidak	PKCS7_PADDING	Mode padding. Parameter ini hanya diperlukan ketika Algoritma 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 sandi dalam byte. Jika teks biasa atau teks terenkripsi masukan memiliki panjang L byte, sistem menambahkan string padding sebesar 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 sandi.

Parameter respons

Parameter	Tipe	Contoh	Deskripsi
Iv	bytes	Data biner	Vektor awal yang digunakan untuk mengenkripsi data. Parameter ini mengembalikan nilai yang valid hanya ketika Algoritma disetel ke AES_GCM atau AES_CBC. Dalam skenario lainnya, nilai kosong dikembalikan.
CiphertextBlob	bytes	Data biner	Teks terenkripsi dari data yang dienkripsi menggunakan kunci. Catatan Ketika algoritma Elliptic Curve Integrated Encryption Scheme (ECIES) digunakan, format teks terenkripsi data yang dikembalikan mengikuti standar SEC 1: Elliptic Curve Cryptography, Version 2.0.
KeyId	string	key-hzz62f1cb66fa42qo****	ID unik global dari kunci. Jika Anda menetapkan KeyId dalam permintaan ke alias kunci, ID kunci yang terikat dengan alias tersebut dikembalikan.
Algorithm	string	AES_GCM	Algoritma enkripsi.
PaddingMode	string	PKCS7_PADDING	Mode padding. Parameter ini mengembalikan nilai yang valid hanya ketika Algoritma disetel ke AES_CBC atau AES_ECB. Dalam kasus lain, nilai kosong dikembalikan.
RequestId	string	475f1620-b9d3-4d35-b5c6-3fbdd941423d	ID permintaan, yang digunakan untuk melokalisasi dan menyelesaikan masalah.

Kode kesalahan

Untuk daftar kode kesalahan, lihat Kode kesalahan layanan.