Encrypts plaintext into ciphertext.
Usage notes
Both Encrypt and AdvanceEncrypt encrypt plaintext into ciphertext. The key difference is which key version each operation uses:
| Operation | Key version used | Supported decryption operations |
|---|---|---|
| Encrypt | Initial version | Decrypt and AdvanceDecrypt are both supported |
| AdvanceEncrypt | Primary version | AdvanceDecrypt only |
AdvanceEncrypt is supported only for symmetric keys in Key Management Service (KMS) instances of the software key management type.
If you use a symmetric key in a software key management KMS instance with automatic rotation enabled, use AdvanceEncrypt instead of Encrypt. Using Encrypt with automatic key rotation causes the key rotation feature to become invalid. For details, see Configure key rotation.
For information about key specifications, encryption modes, and key versions, see Key types and specifications.
Request size limits
After encoding with Protocol Buffers, the request body must not exceed 3 MB. If it does, the server returns HTTP 413.
To reduce the risk of network failures and minimize transmission time, keep data within these limits per operation:
Symmetric keys: 6 KB
Asymmetric keys: 1 KB
If your data exceeds these limits, use envelope encryption. For details, see Use envelope encryption.
Request parameters
| Parameter | Type | Required | Example | Description |
|---|---|---|---|---|
| KeyId | string | Yes | key-hzz62f1cb66fa42qo**** | The globally unique ID of the key. You can also specify a key 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 supported algorithms by key type, see Key types and specifications. |
| Iv | bytes | No | Binary data | The initialization vector (IV) for encryption. Applies only when Algorithm is AES_GCM or AES_CBC. Valid lengths: 12 bytes for AES_GCM, 16 bytes for AES_CBC. If not specified, KMS generates a random IV. Important Leave this parameter unset and let KMS generate the IV automatically. |
| Aad | binary | No | Binary data | The additional authenticated data (AAD) for GCM-mode encryption. Applies when the key is a symmetric key and Algorithm is AES_GCM or SM4_GCM. Important If you specify this parameter, you must pass the same value when calling Decrypt. |
| PaddingMode | string | No | PKCS7_PADDING | The padding mode. Required only when Algorithm is AES_CBC or AES_ECB. Valid values: PKCS7_PADDING (default), NO_PADDING. |
PaddingMode values
`PKCS7_PADDING` (default): Applies PKCS#7 padding. If the input is L bytes and the cipher block size is K bytes, the padding length is K − (L mod K) bytes. Use this mode when the plaintext length is not a multiple of the cipher block size.
`NO_PADDING`: No padding is applied. The plaintext length must be an exact multiple of the cipher block size.
Response elements
| Parameter | Type | Example | Description |
|---|---|---|---|
| Iv | bytes | Binary data | The initialization vector used for encryption. Returns a value only when Algorithm is AES_GCM or AES_CBC; otherwise returns empty. |
| CiphertextBlob | bytes | Binary data | The encrypted ciphertext. When the Elliptic Curve Integrated Encryption Scheme (ECIES) algorithm is used, the ciphertext format follows the SEC 1: Elliptic Curve Cryptography, Version 2.0 standard. |
| KeyId | string | key-hzz62f1cb66fa42qo**** | The globally unique ID of the key used for encryption. If you specified a key alias in the request, the actual key ID is returned. |
| Algorithm | string | AES_GCM | The encryption algorithm used. |
| PaddingMode | string | PKCS7_PADDING | The padding mode used. Returns a value only when Algorithm is AES_CBC or AES_ECB; otherwise returns empty. |
| 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.