GenerateDataKey - Key Management Service - Alibaba Cloud Documentation Center

Operation description

For information about the permissions that are required to call this operation, see Resource Access Management.
This operation can be called using a shared gateway or a dedicated gateway. For more information, see Alibaba Cloud SDK.
- Shared gateway: You can access KMS over the Internet or a VPC. To access KMS over the Internet, you must enable the public endpoint. For more information, see Access keys in a KMS instance over the Internet.
- Dedicated gateway: You can access KMS using the private endpoint of KMS (<YOUR_KMS_INSTANCE_ID>.cryptoservice.kms.aliyuncs.com).

QPS limits

If you use a shared gateway to call this operation, the queries per second (QPS) limit for a single user is 1,000. If the limit is exceeded, API calls are throttled. This may affect your business. We recommend that you call this operation at a reasonable rate.
If you use a dedicated gateway to call this operation, the QPS limit for a single user is based on the computing performance of your KMS instance. For more information, see Performance metrics.

Description

This operation generates a random data key, encrypts the data key using the specified customer master key (CMK), and returns the plaintext and ciphertext of the data key. You can use the plaintext of the data key to encrypt data locally and outside of KMS. When you store the encrypted data, you must also store the ciphertext of the data key. You can obtain the plaintext of the data key from the Plaintext field and the ciphertext of the data key from the CiphertextBlob field in the response.

The CMK that you specify in the request is used only to encrypt the data key. It is not involved in the generation of the data key. KMS does not record or store the randomly generated data key. You are responsible for the persistence of the ciphertext of the data key.

We recommend that you perform the following steps to encrypt data locally:

1. Call the GenerateDataKey operation to obtain a data key for data encryption.

2. Use the plaintext of the data key returned in the Plaintext field of the response to encrypt data locally. Then, clear the plaintext of the data key from memory.

3. Store the ciphertext of the data key returned in the CiphertextBlob field of the response together with the encrypted data.

To decrypt data locally:

Call the Decrypt operation to decrypt the stored ciphertext of the data key. This operation returns the plaintext of the data key.
Use the plaintext of the data key to decrypt data locally. Then, clear the plaintext of the data key from memory.

This topic provides an example of how to generate a random data key for a key with the ID key-hzz630494463ejqjx****.

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
KeyId	string	Yes	The ID of the key. You can also specify the alias or the key resource name (ARN) of the key. For more information about aliases, see Manage aliases. Note When you access a key in another Alibaba Cloud account, you must enter the ARN of the key. The key ARN is in the format of `acs:kms:${region}:${account}:key/${keyid}`.	7906979c-8e06-46a2-be2d-68e3ccbc****
KeySpec	string	No	The length of the data key to be generated. Valid values: AES_256: a 256-bit symmetric key. AES_128: a 128-bit symmetric key. Note We recommend that you use the KeySpec or NumberOfBytes parameter to specify the length of a data key. If you do not specify either of the parameters, KMS generates a 256-bit data key. If you specify both parameters, KMS ignores the KeySpec parameter.	AES_256
NumberOfBytes	integer	No	The length of the data key that you want to generate. Unit: bytes. Valid values: 1 to 1024. Default values: If you set KeySpec to AES_256, the default value of NumberOfBytes is 32. If you set KeySpec to AES_128, the default value of NumberOfBytes is 16.	256
EncryptionContext	object	No	A JSON string that consists of key-value pairs. If you specify this parameter, you must also specify the same parameter when you call the Decrypt operation. For more information, see EncryptionContext.	{"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 the API call. It verifies whether you have the permissions to access the specified resources and whether the request parameters are valid. If you enable the DryRun mode, KMS always returns a failure response and a failure reason. The failure reasons include the following: DryRunOperationError: The request succeeds if the DryRun parameter is not specified. ValidationError: The parameters specified in the request are invalid. AccessDeniedError: You are not authorized to perform this operation on the KMS resource.	false

For information about common request parameters, see Common parameters.

Response parameters

Parameter	Type	Description	Example
	object
KeyVersionId	string	The globally unique identifier of the key version.	2ab1a983-7072-4bbc-a582-584b5bd8****
KeyId	string	The ID of the key. If you use a key alias or key ARN in the KeyId parameter of the request, the key ID is also returned in the response.	7906979c-8e06-46a2-be2d-68e3ccbc****
CiphertextBlob	string	The ciphertext of the data key encrypted by the primary version of the specified key.	ODZhOWVmZDktM2QxNi00ODk0LWJkNGYtMWZjNDNmM2YyYWJmS7FmDBBQ0BkKsQrtRnidtPwirmDcS0ZuJCU41xxAAWk4Z8qsADfbV0b+i6kQmlvj79dJdGOvtX69Uycs901qOjop4bTS****
RequestId	string	The ID of the request, which is a unique identifier generated by Alibaba Cloud for the request. You can use the request ID to troubleshoot and locate issues.	7021b6ec-4be7-4d3c-8a68-1e85d4d515a0
Plaintext	string	The Base64-encoded plaintext of the data key.	QmFzZTY0IGVuY29kZWQgcGxhaW50****

Examples

Success response

JSON format

{
  "KeyVersionId": "2ab1a983-7072-4bbc-a582-584b5bd8****",
  "KeyId": "7906979c-8e06-46a2-be2d-68e3ccbc****",
  "CiphertextBlob": "ODZhOWVmZDktM2QxNi00ODk0LWJkNGYtMWZjNDNmM2YyYWJmS7FmDBBQ0BkKsQrtRnidtPwirmDcS0ZuJCU41xxAAWk4Z8qsADfbV0b+i6kQmlvj79dJdGOvtX69Uycs901qOjop4bTS****",
  "RequestId": "7021b6ec-4be7-4d3c-8a68-1e85d4d515a0",
  "Plaintext": "QmFzZTY0IGVuY29kZWQgcGxhaW50****"
}

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.