Decrypt - Key Management Service - Alibaba Cloud Documentation Center

Operation description

Precautions

For details about the access policies that Resource Access Management (RAM) users or RAM roles need to invoke this API operation, see Access control.
This operation can be invoked through a shared gateway or a dedicated gateway. For more information, see Alibaba Cloud SDK.
- Shared gateway: Access KMS through public network access or a VPC endpoint. This method requires you to enable the public network switch. For more information, see Access keys in a KMS instance over the Internet.
- Dedicated gateway: Access KMS through a KMS private endpoint (<YOUR_KMS_INSTANCE_ID>.cryptoservice.kms.aliyuncs.com).

QPS limits

Calls through a shared gateway: The QPS limit for a single user is 1,000 calls per second. If the limit is exceeded, API calls are throttled, which may affect your business. Call this operation at a reasonable rate.
Calls through a dedicated gateway: The QPS limit for a single user is based on the performance specifications of your KMS instance. For more information, see Performance data.

Try it now

Try this API in OpenAPI Explorer, no manual signing needed. Successful calls auto-generate SDK code matching your parameters. Download it with built-in credential security for local usage.

Test

RAM authorization

The table below describes the authorization required to call this API. You can define it in a Resource Access Management (RAM) policy. The table's columns are detailed below:

Action: The actions can be used in the Action element of RAM permission policy statements to grant permissions to perform the operation.
API: The API that you can call to perform the action.
Access level: The predefined level of access granted for each API. Valid values: create, list, get, update, and delete.
Resource type: The type of the resource that supports authorization to perform the action. It indicates if the action supports resource-level permission. The specified resource must be compatible with the action. Otherwise, the policy will be ineffective.
- For APIs with resource-level permissions, required resource types are marked with an asterisk (*). Specify the corresponding Alibaba Cloud Resource Name (ARN) in the Resource element of the policy.
- For APIs without resource-level permissions, it is shown as All Resources. Use an asterisk (*) in the Resource element of the policy.
Condition key: The condition keys defined by the service. The key allows for granular control, applying to either actions alone or actions associated with specific resources. In addition to service-specific condition keys, Alibaba Cloud provides a set of common condition keys applicable across all RAM-supported services.
Dependent action: The dependent actions required to run the action. To complete the action, the RAM user or the RAM role must have the permissions to perform all dependent actions.

Action

Access level

Resource type

Condition key

Dependent action

kms:Decrypt

get

*Key

acs:kms:{#regionId}:{#accountId}:key/{#KeyId}

kms:tag

None

Request parameters

Parameter	Type	Required	Description	Example
CiphertextBlob	string	Yes	The ciphertext to decrypt. The ciphertext can be generated by the following API operations: GenerateDataKey Encrypt GenerateDataKeyWithoutPlaintext	DZhOWVmZDktM2QxNi00ODk0LWJkNGYtMWZjNDNmM2YyYWJmaaSl+TztSIMe43nbTH/Z1Wr4XfLftKhAciUmDQXuMRl4WTvKhxjMThjK****
EncryptionContext	object	No	A JSON string of key/value pairs. Note If you specified EncryptionContext when calling GenerateDataKey, Encrypt, or GenerateDataKeyWithoutPlaintext to encrypt data, you must provide the same parameter when decrypting. For more information, see EncryptionContext.	{"Example":"Example"}
DryRun	string	No	Specifies whether to enable DryRun mode. Valid values: true: Enabled. false (default): Disabled. DryRun mode is used to test API calls, verify whether you have the required permissions on the relevant resources, and check whether the request parameters are configured correctly. When DryRun mode is enabled, KMS always returns a failure with a reason. The failure reasons include the following: DryRunOperationError: The request would succeed if the DryRun parameter is not specified. ValidationError: A parameter specified in the request is invalid. AccessDeniedError: You do not have permission to perform this operation on the KMS resource.	false
Recipient	string	No		{ "AttestationDocument":"base64-encoded-attestion-document", "KeyEncryptionAlgorithm":"RSAES_OAEP_SHA_256" }

Response elements

Element	Type	Description	Example
	object
KeyVersionId	string	The identifier of the key version under the customer master key (CMK) that was used to decrypt the ciphertext.	2ab1a983-7072-4bbc-a582-584b5bd8****
KeyId	string	The ID of the CMK used to decrypt the ciphertext. The globally unique identifier of the CMK.	202b9877-5a25-46e3-a763-e20791b5****
RequestId	string	The request ID. This is a unique identifier generated by Alibaba Cloud for the request. You can use it to troubleshoot and locate issues.	207596a2-36d3-4840-b1bd-f87044699bd7
Plaintext	string	The decrypted plaintext.	tRYXuCwgja12xxO1N/gZERDDCLw9doZEQiPDk/Bv****
CiphertextForRecipient	string		NIahY6pgjK4ZMP2R0EmsmBqntrv0AI2rcDyU7Su6uOT9Le7EOvlCpjHJfr9z3M0vkfulQoyuETmKSpYDfixE3auE4MwxloT6D9Gfsk6hm5FV2iAxL//Ms2kLv6K4z6yGi7lKm2yjX4***==

Examples

Success response

JSON format

{
  "KeyVersionId": "2ab1a983-7072-4bbc-a582-584b5bd8****",
  "KeyId": "202b9877-5a25-46e3-a763-e20791b5****",
  "RequestId": "207596a2-36d3-4840-b1bd-f87044699bd7",
  "Plaintext": "tRYXuCwgja12xxO1N/gZERDDCLw9doZEQiPDk/Bv****",
  "CiphertextForRecipient": "NIahY6pgjK4ZMP2R0EmsmBqntrv0AI2rcDyU7Su6uOT9Le7EOvlCpjHJfr9z3M0vkfulQoyuETmKSpYDfixE3auE4MwxloT6D9Gfsk6hm5FV2iAxL//Ms2kLv6K4z6yGi7lKm2yjX4***==\n"
}

Error codes

HTTP status code	Error code	Error message	Description
400	UnsupportedOperation	This action is not supported.	The operation is not supported.
404	Forbidden.AliasNotFound	The specified Alias is not found.	The error message returned because the specified alias does not exist.
404	Forbidden.KeyNotFound	The specified Key is not found.	The error message returned because the specified CMK does not exist.
409	Rejected.Disabled	The request was rejected because the key state is Disabled.	The request was rejected because the key state is Disabled.
409	Rejected.PendingDeletion	The request was rejected because the key state is PendingDeletion.	The request was rejected because the key state is PendingDeletion.
409	Rejected.Unavailable	The request was rejected because the key state is Unavailable.	The request was denied because the key status is unavailable.

See Error Codes for a complete list.

Release notes

See Release Notes for a complete list.