Decrypts ciphertext into plaintext.
Operating instructions
After you call the Encrypt or GenerateDataKey operation to generate ciphertext, you can call the Decrypt operation to decrypt the ciphertext.
Usage notes
The request body cannot exceed 3 MB after encoding with Protocol Buffers. If the request body exceeds 3 MB, the server returns HTTP 413.
Keep data within the following size limits per operation to reduce network failure risk and minimize latency:
Symmetric keys: 6 KB
Asymmetric keys: 1 KB
High amounts of data in a single encryption or decryption operation raise the risk of network failures, prolong the time required for network transmission, and extend the duration required for KMS to encrypt and decrypt data.
For data that exceeds these limits, 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 an alias bound to the key. |
| Algorithm | string | No | AES_GCM | The decryption algorithm. Must match the algorithm used for encryption. For supported key specifications and algorithms, see Key types and specifications. |
| Iv | bytes | No | Binary data | The initialization vector (IV). Required when Algorithm is AES_GCM or AES_CBC. Must match the IV used during encryption. Valid lengths: 12 bytes for AES_GCM, 16 bytes for AES_CBC. |
| CiphertextBlob | bytes | Yes | Binary data | The ciphertext to decrypt. When using the Elliptic Curve Integrated Encryption Scheme (ECIES) algorithm, the ciphertext format follows the SEC 1: Elliptic Curve Cryptography, Version 2.0 standards. |
| Aad | bytes | No | Binary data | The additional authenticated data (AAD). Maximum 8,192 bytes. Required when Algorithm is AES_GCM or SM4_GCM and AAD was specified during encryption. Must match the value used during encryption. |
| PaddingMode | string | No | PKCS7_PADDING | The padding mode. Required when Algorithm is AES_CBC or AES_ECB. Must match the value used during encryption. Valid values: PKCS7_PADDING (default), NO_PADDING. |
PaddingMode values
`PKCS7_PADDING` (default): Uses PKCS#7 padding. The plaintext length does not need to be a multiple of the cipher block size. If the plaintext is L bytes long, the system adds K-(L mod K) bytes of padding, where K is the cipher block size in bytes.
`NO_PADDING`: No padding. The plaintext length must be an integer multiple of the cipher block size.
Response parameters
| Parameter | Type | Example | Description |
|---|---|---|---|
| Plaintext | bytes | Binary data | The decrypted plaintext. |
| KeyId | string | key-hzz62f1cb66fa42qo**** | The globally unique ID of the key used for decryption. If you specified an alias in the request, the ID of the key to which the alias is bound is returned. |
| Algorithm | string | AES_GCM | The decryption algorithm. |
| PaddingMode | string | PKCS7_PADDING | The padding mode. |
| RequestId | string | 475f1620-b9d3-4d35-b5c6-3fbdd941423d | The request ID. |
Error codes
| HTTP status code | Error code | Error message | Description |
|---|---|---|---|
| 500 | InternalFailure | Internal Failure. | The request failed due to one of the following causes: the ciphertext does not meet algorithm requirements (for example, using SHA-1 during RSA RSAES_OAEP_SHA_256 decryption, or a ciphertext length that is not a multiple of 16 bytes during AES_ECB decryption); or the specified key does not match the key used for encryption. If neither cause applies, submit a ticket to contact technical support. |
For a complete list of error codes, see Service error codes.