ReEncrypt - Key Management Service - Alibaba Cloud Documentation Center

Operation description

Notes

For more information about the access policy required to grant a RAM user or RAM role the permission to call this OpenAPI, see Resource Access Management.
You can call this API only using a shared gateway, not a dedicated gateway. For more information, see Alibaba Cloud SDK.

When you call an API using a shared gateway, you access KMS through an Internet or a VPC domain name. This method requires you to enable Internet access. For more information, see Access keys in a KMS instance over the Internet.

QPS limits

You can call this API only using a shared gateway. The single-user queries per second (QPS) limit for this API is 750. If this limit is exceeded, API calls are throttled, which may affect your business. We recommend that you call this API within the specified limit.

Details

You can use the ReEncrypt operation in the following scenarios:

After a customer master key (CMK) is rotated, you can use the latest key version to re-encrypt data. For more information about automatic key rotation, see Automatic key rotation.
You can re-encrypt data by changing the encryption context without changing the master key.
You can re-encrypt data or a data key that is encrypted by one master key with another master key in KMS.

The ReEncrypt operation requires the following permissions:

The kms:ReEncryptFrom permission for the source master key.
The kms:ReEncryptTo permission for the destination master key.
You can use kms:ReEncrypt* to grant both permissions.

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

No authorization for this operation. If you encounter issues with this operation, contact technical support.

Request parameters

Parameter	Type	Required	Description	Example
CiphertextBlob	string	Yes	The ciphertext that you want to re-encrypt. This parameter can be the ciphertext that is returned after symmetric or asymmetric key encryption. Symmetric encryption: the ciphertext that is returned after you call the Encrypt, GenerateDataKey, GenerateDataKeyWithoutPlaintext, or GenerateAndExportDataKey operation. Asymmetric key encryption: the data that is encrypted using a public key after you call the GenerateAndExportDataKey operation, or the data that is encrypted using an asymmetric public key in an external system.	ODZhOWVmZDktM2QxNi00ODk0LWJkNGYtMWZjNDNmM2YyYWJmS7FmDBBQ0BkKsQrtRnidtPwirmDcS0ZuJCU41xxAAWk4Z8qsADfbV0b+i6kQmlvj79dJdGOvtX69Uycs901q********
SourceKeyId	string	No	The ID of the master key that is used to decrypt the ciphertext. The globally unique identifier of the master key. Note You must specify this parameter when CiphertextBlob is the data that is encrypted using a public key after asymmetric key encryption.	5c438b18-05be-40ad-b6c2-3be6752c****
SourceKeyVersionId	string	No	The ID of the key version that is used to decrypt the ciphertext. Note You must specify this parameter when CiphertextBlob is the data that is encrypted using a public key after asymmetric key encryption.	2ab1a983-7072-4bbc-a582-584b5bd8****
SourceEncryptionAlgorithm	string	No	If CiphertextBlob is the result of public key encryption, specify the public key encryption algorithm. For more information about the algorithms, see AsymmetricDecrypt. Valid values: RSAES_OAEP_SHA_256 RSAES_OAEP_SHA_1 SM2PKE Note You must specify this parameter when CiphertextBlob is the data that is encrypted using a public key after asymmetric key encryption.	RSAES_OAEP_SHA_256
SourceEncryptionContext	object	No	A JSON string that consists of key-value pairs. If you specify this parameter when you call the Encrypt, GenerateDataKey, GenerateDataKeyWithoutPlaintext, or GenerateAndExportDataKey operation, you must specify the same parameter to decrypt the data. For more information, see EncryptionContext. Note You must specify this parameter when CiphertextBlob is the ciphertext that is returned after symmetric encryption.	{"Example":"Example"}
DestinationKeyId	string	Yes	The ID of the symmetric master key that is used to re-encrypt the data after the ciphertext is decrypted.	1234abcd-12ab-34cd-56ef-12345678****
DestinationEncryptionContext	object	No	A JSON string that consists of key-value pairs. This parameter specifies the encryption context for the destination master key.	{"Example":"Example"}
DryRun	string	No	Specifies whether to enable the DryRun mode. true: enables the DryRun mode. false (default): disables the DryRun mode. The DryRun mode is used to test API calls, verify whether you have the permissions to perform operations on the required resources, and check whether the request parameters are valid. If you enable the DryRun mode, KMS always returns a failure and a reason for the failure. The reasons for the failure include the following: DryRunOperationError: The request would have succeeded if the DryRun parameter was not configured. ValidationError: The parameters specified in the request are invalid. AccessDeniedError: You are not authorized to perform the operation on the KMS resource.	false

Response parameters

Parameter	Type	Description	Example
	object
KeyId	string	The ID of the master key that is used to decrypt the ciphertext. The globally unique identifier of the master key.	2ab1a983-7072-4bbc-a582-584b5bd8****
KeyVersionId	string	The ID of the key version that is used to decrypt the ciphertext of the master key.	202b9877-5a25-46e3-a763-e20791b5****
CiphertextBlob	string	The ciphertext that is re-encrypted using the specified master key.	DZhOWVmZDktM2QxNi00ODk0LWJkNGYtMWZjNDNmM2YyYWJmaaSl+TztSIMe43nbTH/Z1Wr4XfLftKhAciUmDQXuMRl4WTvKhxjMThjK****
RequestId	string	The ID of the request. This ID is a globally unique identifier that is generated by Alibaba Cloud for the request. You can use this ID to troubleshoot issues.	207596a2-36d3-4840-b1bd-f87044699bd7

Examples

Success response

JSON format

{
  "KeyId": "2ab1a983-7072-4bbc-a582-584b5bd8****",
  "KeyVersionId": "202b9877-5a25-46e3-a763-e20791b5****",
  "CiphertextBlob": "DZhOWVmZDktM2QxNi00ODk0LWJkNGYtMWZjNDNmM2YyYWJmaaSl+TztSIMe43nbTH/Z1Wr4XfLftKhAciUmDQXuMRl4WTvKhxjMThjK****",
  "RequestId": "207596a2-36d3-4840-b1bd-f87044699bd7"
}

Error codes

HTTP status code	Error code	Error message	Description
400	InvalidParameter	The specified parameter is not valid.	An invalid value is specified for the parameter.
500	InternalFailure	Internal Failure.
404	InvalidAccessKeyId.NotFound	The Access Key ID provided does not exist in our records.
404	Forbidden.KeyNotFound	The specified Key is not found.	The error message returned because the specified CMK does not exist.

See Error Codes for a complete list.

Release notes

See Release Notes for a complete list.