AWS Key Management Service
API Reference (API Version 2014-11-01)

Decrypt

Decrypts ciphertext. Ciphertext is plaintext that has been previously encrypted by using any of the following operations:

Whenever possible, use key policies to give users permission to call the Decrypt operation on the CMK, instead of IAM policies. Otherwise, you might create an IAM user policy that gives the user Decrypt permission on all CMKs. This user could decrypt ciphertext that was encrypted by CMKs in other accounts if the key policy for the cross-account CMK permits it. If you must use an IAM policy for Decrypt permissions, limit the user to particular CMKs or particular trusted accounts.

The result of this operation varies with the key state of the CMK. For details, see How Key State Affects Use of a Customer Master Key in the AWS Key Management Service Developer Guide.

Request Syntax

{ "CiphertextBlob": blob, "EncryptionContext": { "string" : "string" }, "GrantTokens": [ "string" ] }

Request Parameters

For information about the parameters that are common to all actions, see Common Parameters.

The request accepts the following data in JSON format.

Note

In the following list, the required parameters are described first.

CiphertextBlob

Ciphertext to be decrypted. The blob includes metadata.

Type: Base64-encoded binary data object

Length Constraints: Minimum length of 1. Maximum length of 6144.

Required: Yes

EncryptionContext

The encryption context. If this was specified in the Encrypt function, it must be specified here or the decryption operation will fail. For more information, see Encryption Context.

Type: String to string map

Required: No

GrantTokens

A list of grant tokens.

For more information, see Grant Tokens in the AWS Key Management Service Developer Guide.

Type: Array of strings

Array Members: Minimum number of 0 items. Maximum number of 10 items.

Length Constraints: Minimum length of 1. Maximum length of 8192.

Required: No

Response Syntax

{ "KeyId": "string", "Plaintext": blob }

Response Elements

If the action is successful, the service sends back an HTTP 200 response.

The following data is returned in JSON format by the service.

KeyId

ARN of the key used to perform the decryption. This value is returned if no errors are encountered during the operation.

Type: String

Length Constraints: Minimum length of 1. Maximum length of 2048.

Plaintext

Decrypted plaintext data. When you use the HTTP API or the AWS CLI, the value is Base64-encoded. Otherwise, it is not encoded.

Type: Base64-encoded binary data object

Length Constraints: Minimum length of 1. Maximum length of 4096.

Errors

For information about the errors that are common to all actions, see Common Errors.

DependencyTimeoutException

The system timed out while trying to fulfill the request. The request can be retried.

HTTP Status Code: 500

DisabledException

The request was rejected because the specified CMK is not enabled.

HTTP Status Code: 400

InvalidCiphertextException

The request was rejected because the specified ciphertext, or additional authenticated data incorporated into the ciphertext, such as the encryption context, is corrupted, missing, or otherwise invalid.

HTTP Status Code: 400

InvalidGrantTokenException

The request was rejected because the specified grant token is not valid.

HTTP Status Code: 400

KeyUnavailableException

The request was rejected because the specified CMK was not available. The request can be retried.

HTTP Status Code: 500

KMSInternalException

The request was rejected because an internal exception occurred. The request can be retried.

HTTP Status Code: 500

KMSInvalidStateException

The request was rejected because the state of the specified resource is not valid for this request.

For more information about how key state affects the use of a CMK, see How Key State Affects Use of a Customer Master Key in the AWS Key Management Service Developer Guide.

HTTP Status Code: 400

NotFoundException

The request was rejected because the specified entity or resource could not be found.

HTTP Status Code: 400

Examples

The following examples are formatted for legibility.

Example Request

POST / HTTP/1.1 Host: kms.us-west-2.amazonaws.com Content-Length: 293 X-Amz-Target: TrentService.Decrypt X-Amz-Date: 20160517T204035Z Content-Type: application/x-amz-json-1.1 Authorization: AWS4-HMAC-SHA256\ Credential=AKIAI44QH8DHBEXAMPLE/20160517/us-west-2/kms/aws4_request,\ SignedHeaders=content-type;host;x-amz-date;x-amz-target,\ Signature=545b0c3bfd9223b8ef7e6293ef3ccac37a83d415ee3112d2e5c70727d2a49c46 {"CiphertextBlob": "CiDPoCH188S65r5Cy7pAhIFJMXDlU7mewhSlYUpuQIVBrhKmAQEBAgB4z6Ah9fPEuua+Qsu6QISBSTFw5VO5nsIUpWFKbkCFQa4AAAB9MHsGCSqGSIb3DQEHBqBuMGwCAQAwZwYJKoZIhvcNAQcBMB4GCWCGSAFlAwQBLjARBAxLc9b6QThC9jB/ZjYCARCAOt8la8qXLO5wB3JH2NlwWWzWRU2RKqpO9A/0psE5UWwkK6CnwoeC3Zj9Q0A66apZkbRglFfY1lTY+Tc="}

Example Response

HTTP/1.1 200 OK Server: Server Date: Tue, 17 May 2016 20:40:40 GMT Content-Type: application/x-amz-json-1.1 Content-Length: 146 Connection: keep-alive x-amzn-RequestId: 9e02f41f-1c6f-11e6-af63-ab8791945da7 { "KeyId": "arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab", "Plaintext": "VGhpcyBpcyBEYXkgMSBmb3IgdGhlIEludGVybmV0Cg==" }

See Also

For more information about using this API in one of the language-specific AWS SDKs, see the following: