Generates 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 symmetric CMK, and returns the ciphertext and plaintext of the data key. You can use the plaintext of the data key to encrypt local data in services other than KMS in an offline manner. You must store the ciphertext of the data key when you store the encrypted data. You can obtain the plaintext of the data key by querying the Plaintext value in the response and the ciphertext of the data key by querying the CiphertextBlob value in the response.

The CMK that you specify in the request of this operation is only used to encrypt the data key and is not involved in the 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
We recommend that you encrypt local data in the following way:
  • Call the GenerateDataKey API operation to obtain the plaintext and ciphertext of the data key.
  • Use the plaintext of the data key that you can obtain by querying the Plaintext value in the response to encrypt local data in an offline manner and then clear the plaintext of the data key.
  • Store the encrypted data along with the ciphertext of the data key that you can obtain by querying the CiphertextBlob value in the response.
We recommend that you decrypt local data in the following way:
  • Call the Decrypt API operation to decrypt the locally stored ciphertext of the data key. The plaintext of data key is then returned.
  • Use the plaintext of the data key to encrypt local data in an offline manner and then clear the plaintext of the data key.

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 data key to generate. 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 data key to generate. Unit: bytes.

Value range: 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 Description
KeyId String The globally unique ID of the CMK.
Note If you set the KeyId parameter to the alias of the CMK, the ID of the CMK to which the alias is bound is returned.
KeyVersionId String The ID of the key version used to encrypt plaintext. It is the primary key version of the specified CMK.
Plaintext String The plaintext of the data key, which is encoded in Base64.
CiphertextBlob String The ciphertext of the data key encrypted by using 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",
        "Plaintext": "Base64 encoded plaintext",
        "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>
        <Plaintext>Base64 encoded plaintext</Plaintext>
        <RequestId>7021b6ec-4be7-4d3c-8a68-1e85d4d515a0</RequestId>
</KMS>