Encrypt
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 key rotation is enabled for that software-protected key, call AdvanceEncrypt instead of Encrypt. Otherwise, the key rotation feature does not take effect. For more information, see Configure key rotation.
For more information about key specifications, encryption modes, secret key encryption, and key versions, see Key types and specifications.
Usage notes
All request parameters are encoded with Protocol Buffers. The resulting request body cannot exceed 3 MB. If the data volume exceeds 3 MB, the server rejects the request and returns HTTP status code 413.
For a single encrypt or decrypt call, keep the data within the following limits:
Key type | Recommended maximum data volume |
Symmetric key | 6 KB |
Asymmetric key | 1 KB |
If your data exceeds these limits, use envelope encryption instead. For more information, see Envelope encryption.
The larger the data volume in a single call, the higher the risk of network transmission failure, the longer the transmission takes, and the longer the KMS instance needs to complete data encryption or decryption.
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) used for data encryption. Applies only when the encryption algorithm (Algorithm) is AES_GCM, AES_CBC, or SM4_GCM. Valid lengths: 16 bytes when Algorithm is AES_CBC; 12 bytes when Algorithm is AES_GCM or SM4_GCM. If not specified, KMS generates a random value. Do not set this parameter and let KMS generate it randomly. |
| Aad | binary | No | Binary data | The additional authenticated data (AAD) used for GCM-mode authentication during data encryption. You can set this parameter when the key is a symmetric key and the encryption algorithm (Algorithm) is AES_GCM or SM4_GCM. If you set this parameter, you must pass the same value when you call Decrypt to decrypt the encrypted data. |
| 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 data encryption. Returns a valid value only when the encryption algorithm (Algorithm) is AES_GCM, AES_CBC, or SM4_GCM; returns an empty value in all other cases. |
| CiphertextBlob | bytes | Binary data | The ciphertext BLOB of the data after it is encrypted with the specified key. Note: When the Elliptic Curve Integrated Encryption Scheme (ECIES) algorithm is used, the returned ciphertext format complies with the SEC 1: Elliptic Curve Cryptography, Version 2.0 standard. |
| KeyId | string | key-hzz62f1cb66fa42qo**** | The globally unique identifier of the key. If you specified a key alias in the KeyId request parameter, this response element returns the globally unique identifier 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 ID of the request. Alibaba Cloud generates this unique identifier for the request. You can use it to troubleshoot and locate issues. |
Error codes
For a list of error codes, see Service error codes.