AdvanceDecrypt
Decrypts ciphertext generated by a symmetric key in a Key Management Service (KMS) software key management instance.
Operation description
Call this operation to decrypt ciphertext that was encrypted by calling AdvanceEncrypt, AdvanceGenerateDataKey, Encrypt, or GenerateDataKey. The key must be a symmetric key in a KMS instance of the software key management type.
For details on supported key specifications and encryption modes, see Key types and specifications.
Usage notes
Keep the request body under 3 MB after Protocol Buffers encoding. If the request body exceeds 3 MB, the server rejects the request and returns HTTP 413.
Limit the data size to 6 KB for encryption and decryption in a single operation. For larger data, use envelope encryption.
Large payloads increase the risk of network failures, extend transmission time, and increase KMS processing latency.
Request parameters
Parameter | Type | Required | Example | Description |
CiphertextBlob | bytes | Yes | Binary data | The ciphertext to decrypt. |
KeyId | string | No | key-hzz62f1cb66fa42qo**** | The globally unique ID of the key, or an alias bound to the key. Required only when decrypting ciphertext generated by the Encrypt or GenerateDataKey operation. |
Algorithm | string | No | AES_GCM | The decryption algorithm. Required only when decrypting ciphertext generated by the Encrypt or GenerateDataKey operation. Must match the algorithm used during encryption. |
Iv | bytes | No | Binary data | The initialization vector (IV). Required only when decrypting ciphertext generated by the Encrypt or GenerateDataKey operation and Algorithm is set to AES_GCM or AES_CBC. Must match the IV used during encryption. Valid lengths: 16 bytes for AES_CBC, 12 bytes for AES_GCM. |
Aad | bytes | No | Binary data | The additional authenticated data (AAD). Maximum length: 8,192 bytes. Required only when Algorithm is AES_GCM and AAD was specified during encryption. Must match the AAD used during encryption. |
PaddingMode | string | No | PKCS7_PADDING | The padding mode. Required when Algorithm is AES_CBC or AES_ECB. Must match the padding mode used during encryption. Valid values: PKCS7_PADDING (default): PKCS#7 padding. If the plaintext is L bytes, the system adds K − (L mod K) bytes of padding, where K is the cipher block size. 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 the request specified an alias, the actual key ID is returned. |
KeyVersionId | string | key-hzz62f1cb66fa42qo**-17kedv** | The ID of the key version used to decrypt the ciphertext. |
Algorithm | string | AES_GCM | The decryption algorithm. |
PaddingMode | string | PKCS7_PADDING | The padding mode. Returned only when Algorithm is AES_CBC or AES_ECB. Empty otherwise. |
RequestId | string | c0037a6d-7784-4ef2-a692-288fdcbc7b9d | The request ID, used for troubleshooting. |
Error codes
HTTP status code | Error code | Error message | Description |
404 | Forbidden.OnlySymmetricKeySupported | The key %s is not a symmetric key. The API only supports symmetric keys. | Only symmetric keys are supported. |
500 | InternalFailure | Internal Failure. | Possible causes: the ciphertext does not meet the requirements (for example, the ciphertext was not generated by calling the AdvanceEncrypt operation), or the specified key does not match the key used for encryption. |
For a complete list of error codes, see Service error codes.