Encrypts plaintext into ciphertext.
Operation description
Key Management Service (KMS) provides two encrypt operations: Encrypt and AdvanceEncrypt. The key difference is which key version is used and which decrypt operation you must call afterward.
| Encrypt | AdvanceEncrypt | |
|---|---|---|
| Key version used | Initial version | Primary version |
| Compatible decrypt operations | Decrypt or AdvanceDecrypt | AdvanceDecrypt only |
If you use a symmetric key in a software key management instance and enable automatic rotation, use AdvanceEncrypt instead of Encrypt. Using Encrypt with automatic rotation enabled causes the key rotation feature to stop working. For more information, see Configure key rotation.
For details on key specifications, encryption modes, and key versions, see Key types and specifications.
Usage notes
The request body cannot exceed 3 MB after encoding with Protocol Buffers. If the limit is exceeded, the server rejects the request and returns HTTP 413.
For a single encrypt or decrypt operation, keep data within these limits:
Symmetric keys: 6 KB
Asymmetric keys: 1 KB
For larger data, use envelope encryption.
Large payloads increase the risk of network failures, extend transmission time, and add latency to KMS processing.
Request parameters
| Parameter | Type | Required | Example | Description |
|---|---|---|---|---|
| KeyId | string | Yes | key-hzz62f1cb66fa42qo**** | The globally unique ID of the key. You can also specify an alias bound to the key. |
| Plaintext | bytes | Yes | Binary data | The plaintext to encrypt. |
| Algorithm | string | No | AES_GCM | The encryption algorithm. If not specified, KMS uses the default algorithm for the key. For more information, see Key types and specifications. |
| Iv | bytes | No | Binary data | The initialization vector (IV) for encryption. Applies only when Algorithm is set to AES_GCM or AES_CBC. Valid lengths: 12 bytes for AES_GCM, 16 bytes for AES_CBC. If not specified, KMS generates a random value. Do not set this parameter. |
| Aad | binary | No | Binary data | The additional authenticated data (AAD) for GCM-mode authentication. Applies when the key is a symmetric key and Algorithm is set to AES_GCM or SM4_GCM. If specified, you must also pass the same value when calling Decrypt. |
| PaddingMode | string | No | PKCS7_PADDING | The padding mode. Required only when Algorithm is set to AES_CBC or AES_ECB. Valid values: PKCS7_PADDING (default) and NO_PADDING. |
PaddingMode values
`PKCS7_PADDING` (default): Uses PKCS#7 padding. If the input is L bytes, KMS adds K − (L mod K) padding bytes, where K is the cipher block size.
`NO_PADDING`: No padding is added. The plaintext length must be an integer multiple of the cipher block size.
Response elements
| Parameter | Type | Example | Description |
|---|---|---|---|
| Iv | bytes | Binary data | The initialization vector (IV) used for encryption. Returns a value only when Algorithm is AES_GCM or AES_CBC; empty otherwise. |
| CiphertextBlob | bytes | Binary data | The encrypted ciphertext. When the Elliptic Curve Integrated Encryption Scheme (ECIES) algorithm is used, the ciphertext format follows SEC 1: Elliptic Curve Cryptography, Version 2.0 standards. |
| KeyId | string | key-hzz62f1cb66fa42qo**** | The globally unique ID of the key. If you specified an alias in the request, this field returns the ID of the key bound to that alias. |
| Algorithm | string | AES_GCM | The encryption algorithm. |
| PaddingMode | string | PKCS7_PADDING | The padding mode. Returns a value only when Algorithm is AES_CBC or AES_ECB; empty otherwise. |
| RequestId | string | 475f1620-b9d3-4d35-b5c6-3fbdd941423d | The request ID, used to locate and troubleshoot issues. |
Error codes
For a list of error codes, see Service error codes.