GenerateDataKey-阿里云帮助中心

Operation description

For details about the access policies that must be granted to a Resource Access Management (RAM) user or RAM role to invoke this operation, see Access control.
You can invoke this operation through a shared gateway or a dedicated gateway. For more information, see Alibaba Cloud SDK.
- Shared gateway: Access KMS over the Internet or through a VPC endpoint. This method requires that you enable public network access. For more information, see Access keys in a KMS instance over the Internet.
- Dedicated gateway: Access KMS through the 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 you exceed this limit, 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 determined by the performance specifications of your KMS instance. For more information, see Performance data.

Details

This operation generates a random data key (DK), encrypts it by using the customer master key (CMK) that you specify, and returns both the plaintext and ciphertext of the DK. Use the plaintext DK to encrypt data locally outside of KMS. When you store the encrypted data, also store the ciphertext of the DK. You can retrieve the plaintext DK from the Plaintext field and the ciphertext DK from the CiphertextBlob field in the response.

The CMK specified in the request is used only to encrypt the DK and has no effect on DK generation. KMS does not record or store the randomly generated DK. You are responsible for persisting the DK ciphertext.

Use the following procedure to encrypt data locally:

Invoke the GenerateDataKey operation to obtain a DK for data encryption.
Use the plaintext DK (returned in the Plaintext field of the response) to encrypt data locally, then purge the plaintext DK from memory.
Store the DK ciphertext (returned in the CiphertextBlob field of the response) together with the locally encrypted data.

To decrypt data locally:

Invoke the Decrypt operation to decrypt the locally stored DK ciphertext. This operation returns the plaintext DK.
Use the plaintext DK to decrypt data locally, then purge the plaintext DK from memory.

This topic provides an example of generating a random DK for the 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

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:GenerateDataKey

get

*Key

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

kms:tag

None

Request parameters

Parameter	Type	Required	Description	Example
KeyId	string	Yes	The ID of the key. You can also specify a key alias or a key Amazon Resource Name (ARN). For more information about aliases, see Manage key aliases. Note To access a key in another Alibaba Cloud account, you must specify the key ARN. The key ARN format is `acs:kms:${region}:${account}:key/${keyid}`.	key-hzz630494463ejqjx****
KeySpec	string	No	The length of the data key (DK) to generate. Valid values: AES_256: a 256-bit symmetric key. AES_128: a 128-bit symmetric key. Note Use KeySpec or NumberOfBytes to specify the DK length. If neither is specified, KMS generates a 256-bit DK. If both are specified, KMS ignores the KeySpec parameter.	AES_256
NumberOfBytes	integer	No	The length of the data key (DK) to generate, in bytes. Valid values: 1 to 1024. Default value: When KeySpec is set to AES_256, the default value of NumberOfBytes is 32. When KeySpec is set to AES_128, the default value of NumberOfBytes is 16.	256
EncryptionContext	object	No	A JSON string of key-value pairs. If you specify this parameter, you must provide the same parameter when you call the Decrypt operation. For more information, see EncryptionContext.	{"Example":"Example"}
DryRun	string	No	Specifies whether to enable DryRun mode. true: enabled. false (default): disabled. DryRun mode is used to test API calls, verify that you have the required permissions on the relevant resources, and check whether request parameters are configured correctly. When DryRun mode is enabled, KMS always returns a failure with a reason. Possible failure reasons include: DryRunOperationError: The request would succeed if the DryRun parameter were not set. ValidationError: A parameter specified in the request is invalid. AccessDeniedError: You do not have permission to perform the operation on the KMS resource.	false
Recipient	string	No		{ "AttestationDocument":"base64-encoded-attestion-document", "KeyEncryptionAlgorithm":"RSAES_OAEP_SHA_256" }

For details about common request parameters, see Common parameters.

Response elements

Element	Type	Description	Example
	object
KeyVersionId	string	The key version ID. The globally unique identifier of the CMK version.	2ab1a983-7072-4bbc-a582-584b5bd8****
KeyId	string	The key ID. If the KeyId parameter in the request uses a key alias or key ARN, the key ID is also returned in the response.	key-hzz630494463ejqjx****
CiphertextBlob	string	The ciphertext of the data key (DK) encrypted by the primary version of the specified key.	ODZhOWVmZDktM2QxNi00ODk0LWJkNGYtMWZjNDNmM2YyYWJmS7FmDBBQ0BkKsQrtRnidtPwirmDcS0ZuJCU41xxAAWk4Z8qsADfbV0b+i6kQmlvj79dJdGOvtX69Uycs901qOjop4bTS****
RequestId	string	The request ID. The unique identifier generated by Alibaba Cloud for this request. You can use this ID to troubleshoot and locate issues.	7021b6ec-4be7-4d3c-8a68-1e85d4d515a0
Plaintext	string	The Base64 encoding of the plaintext of the data key (DK).	QmFzZTY0IGVuY29kZWQgcGxhaW50****
CiphertextForRecipient	string		NIahY6pgjK4ZMP2R0EmsmBqntrv0AI2rcDyU7Su6uOT9Le7EOvlCpjHJfr9z3M0vkfulQoyuETmKSpYDfixE3auE4MwxloT6D9Gfsk6hm5FV2iAxL//Ms2kLv6K4z6yGi7lKm2yjX4***==

Examples

Success response

JSON format

{
  "KeyVersionId": "2ab1a983-7072-4bbc-a582-584b5bd8****",
  "KeyId": "key-hzz630494463ejqjx****",
  "CiphertextBlob": "ODZhOWVmZDktM2QxNi00ODk0LWJkNGYtMWZjNDNmM2YyYWJmS7FmDBBQ0BkKsQrtRnidtPwirmDcS0ZuJCU41xxAAWk4Z8qsADfbV0b+i6kQmlvj79dJdGOvtX69Uycs901qOjop4bTS****",
  "RequestId": "7021b6ec-4be7-4d3c-8a68-1e85d4d515a0",
  "Plaintext": "QmFzZTY0IGVuY29kZWQgcGxhaW50****",
  "CiphertextForRecipient": "NIahY6pgjK4ZMP2R0EmsmBqntrv0AI2rcDyU7Su6uOT9Le7EOvlCpjHJfr9z3M0vkfulQoyuETmKSpYDfixE3auE4MwxloT6D9Gfsk6hm5FV2iAxL//Ms2kLv6K4z6yGi7lKm2yjX4***=="
}

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.