You can call this operation to generate a random data key, which can be used to encrypt local data.

This operation creates a random data key, encrypts the data key with the specified CMK, and returns the ciphertext of the data key. This operation serves the same purpose as the GenerateDataKey API operation, but it does not return the plaintext of the data key.

Like in the GenerateDataKey API operation, the CMK that you specify in the request of this operation is only used to encrypt the data key and is independent of generation of the data key. KMS does not record or store the generated data key, so you need to implement persistence of the data key cipher.

Note

This operation is suitable for a system that does not require the data key to encrypt data immediately, because you must call the Decrypt API operation to decrypt the data key cipher before using the data key to encrypt data.

This operation is also fit for a distributed system with different trust levels. The system stores data in different partitions based on the preset trust policy. A module creates different partitions and generates different data keys for these partitions in advance. This module is not involved in data production and consumption after it completes initialization of the control plane. This module is the key provider. When producing and consuming data, modules on the control plane obtain the data key ciphertext of a partition first. After decrypting the data key ciphertext, modules on the control plane the data key plaintext to encrypt or decrypt data and then clear the data key plaintext from the memory. In such a system, the key provider does not obtain data key plaintext and only need to have the permissions call the GenerateDataKeyWithoutPlaintext API operation. The data producer or consumer does not generate new data keys and only need to have the permissions call the Decrypt API operation.

Request parameters

Parameter Type Required Description
KeyId String Yes The globally unique ID of the CMK. This parameter can also be specified as an alias bound to the CMK. For more information, see Use aliases.
KeySpec String No Specifies the length of the generated data key. AES_256 indicates 256-bit symmetric keys and AES_128 indicates 128-bit symmetric keys.

Valid values: AES_256 and AES_128

Note

We recommend that you use the KeySpec or NumberOfBytes parameter to specify the length of data keys.

  • If neither of the two parameters is specified, KMS generates 256-bit data keys.
  • If both of them are specified, the KeySpec value is ignored.
NumberOfBytes Integer No Specifies the length of the generated data key. Unit: bytes.

Valid values: 1 to 1024

Note

We recommend that you use the KeySpec or NumberOfBytes parameter to specify the length of data keys.

  • If neither of the two parameters is specified, KMS generates 256-bit data keys.
  • If both of them are specified, the KeySpec value is ignored.
EncryptionContext String to string map No The JSON string of the key-value pair. If you specify this parameter here, it is also required when you call the Decrypt API operation. For more information, see Encryption Context.

Response parameters

Parameter Type Decription
KeyId String The globally unique ID of the CMK.
Note If an alias of the CMK is used as the value of the KeyId parameter, the ID of the CMK that the alias is bound to will be returned in the response.
KeyVersionId String The ID of the key version used to encrypt plaintext. It is the primary key version of the specified CMK.
CiphertextBlob String The ciphertext of the data key encrypted with the primary CMK version.

Examples

Sample requests

https://kms.cn-hangzhou.aliyuncs.com/?Action=GenerateDataKey
&KeyId=<cmkid or aliasname>
&KeySpec=AES_256
&EncryptionContext={"Example":"Example"}
&<Common request parameters>

Sample responses

JSON format

//json response
{
        "CiphertextBlob": "CiphertextBlob",
        "KeyId": "599fa825-17de-417e-9554-bb032cc6****",
        "KeyVersionId": "2ab1a983-7072-4bbc-a582-584b5bd8ecf3",
        "RequestId": "7021b6ec-4be7-4d3c-8a68-1e85d4d515a0"
}   

XML format

//xml response
<KMS>
        <CiphertextBlob>CiphertextBlob</CiphertextBlob>
        <KeyId>599fa825-17de-417e-9554-bb032cc6****</KeyId>
        <KeyVersionId>2ab1a983-7072-4bbc-a582-584b5bd8ecf3</KeyVersionId>
        <RequestId>7021b6ec-4be7-4d3c-8a68-1e85d4d515a0</RequestId>
</KMS>