Generates a random data key for local data encryption.
Operation description
Precautions
-
For information about the access policy that a RAM user or RAM role needs to call this OpenAPI, see Resource Access Management.
-
You can call this API 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 domain name. This method requires you to enable public network access. 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 queries per second (QPS) limit for a single user is 1,000. If you exceed this limit, API calls are throttled, which may affect your business. We recommend that you call the API within this limit.
Calls through a dedicated gateway: The QPS limit for a single user depends on the computing performance of your KMS instance. For more information, see Performance metrics.
Details
This API generates a random data key, encrypts it with a specified symmetric customer master key (CMK), and returns the ciphertext of the data key. This API provides the same features as GenerateDataKey. The only difference is that this API does not return the plaintext of the data key.
The CMK that you specify in the request is used only to encrypt the data key. It is not used to generate the data key. KMS does not record or store the randomly generated data key.
This API is suitable for systems that do not need to immediately use the data key for data encryption. When encryption is required, the system calls the Decrypt API to decrypt the ciphertext of the data key.
This API is also suitable for distributed systems with different trust levels. For example, your system stores data in different partitions based on a defined policy. A module pre-creates these data partitions and generates a unique data key for each one. After this module initializes the control plane, it acts as a key distributor and does not produce or consume data. When data plane modules produce and consume data, they first retrieve the ciphertext of the data key for a partition. They then decrypt the ciphertext and use the plaintext data key to encrypt or decrypt data. Finally, they purge the plaintext data key from memory. In such a system, the key distributor does not need to access the plaintext of the data key. It only requires the `GenerateDataKeyWithoutPlaintext` permission for the relevant CMK. Data producers and consumers do not need to generate new data keys. They only require the `Decrypt` permission for the relevant CMK.
Try it now
Test
RAM authorization
Request parameters
|
Parameter |
Type |
Required |
Description |
Example |
| KeyId |
string |
Yes |
The globally unique identifier of the CMK. You can also specify an alias that is bound to the CMK. For more information about how to use an alias, see Alias overview. |
599fa825-17de-417e-9554-bb032cc6**** |
| KeySpec |
string |
No |
The length of the data key to generate. Valid values:
Note
Use KeySpec or NumberOfBytes to specify the length of the data key. If you do not specify either parameter, 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 to generate. |
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 the DryRun mode.
The DryRun mode is used to test API calls, verify your permissions on the required resources, and check if the request parameters are valid. If you enable the DryRun mode, KMS returns a failure response with a reason. The failure reasons include the following:
|
false |
Response elements
|
Element |
Type |
Description |
Example |
|
object |
|||
| KeyVersionId |
string |
The ID of the key version used to encrypt the plaintext. This is the primary version of the specified CMK. |
2ab1a983-7072-4bbc-a582-584b5bd8**** |
| KeyId |
string |
The globally unique identifier of the CMK. Note
If you use an alias of the CMK in the KeyId parameter of the request, the ID of the CMK is returned. |
599fa825-17de-417e-9554-bb032cc6**** |
| CiphertextBlob |
string |
The ciphertext of the data key. The data key is encrypted by the primary version of the specified CMK. |
ODZhOWVmZDktM2QxNi00ODk0LWJkNGYtMWZjNDNmM2YyYWJmS7FmDBBQ0BkKsQrtRnidtPwirmDcS0ZuJCU41xxAAWk4Z8qsADfbV0b+i6kQmlvj79dJdGOvtX69Uycs901qOjop4bTS**** |
| RequestId |
string |
The ID of the request. This ID is a globally unique identifier generated by Alibaba Cloud for the request. You can use this ID to troubleshoot and locate issues. |
7021b6ec-4be7-4d3c-8a68-1e85d4d515a0 |
Examples
Success response
JSON format
{
"KeyVersionId": "2ab1a983-7072-4bbc-a582-584b5bd8****",
"KeyId": "599fa825-17de-417e-9554-bb032cc6****",
"CiphertextBlob": "ODZhOWVmZDktM2QxNi00ODk0LWJkNGYtMWZjNDNmM2YyYWJmS7FmDBBQ0BkKsQrtRnidtPwirmDcS0ZuJCU41xxAAWk4Z8qsADfbV0b+i6kQmlvj79dJdGOvtX69Uycs901qOjop4bTS****",
"RequestId": "7021b6ec-4be7-4d3c-8a68-1e85d4d515a0"
}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. |
| 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.