Generates a random data key that is used to locally encrypt data.

This operation creates a random data key, encrypts the data key by 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 locally encrypt your data without using KMS and store the encrypted data together with the ciphertext of the data key. You can obtain the plaintext of the data key from the Plaintext parameter in the response and the ciphertext of the data key from the CiphertextBlob parameter 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. Therefore, you need to store the ciphertext of the data key in persistent storage.

We recommend that you locally encrypt data by performing the following steps:

1. Call the GenerateDataKey operation.

2. Use the plaintext of the data key that you obtain to locally encrypt data without using KMS. Then, delete the plaintext of the data key from the memory.

3. Store the encrypted data together with the ciphertext of the data key that you obtain.

We recommend that you locally decrypt data by performing the following steps:

  • Call the Decrypt 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 locally decrypt data and then delete the plaintext of the data key from the memory.

In this example, a random data key is generated for the CMK whose ID is 7906979c-8e06-46a2-be2d-68e3ccbc****.

Debugging

OpenAPI Explorer automatically calculates the signature value. For your convenience, we recommend that you call this operation in OpenAPI Explorer. OpenAPI Explorer dynamically generates the sample code of the operation for different SDKs.

Request parameters

Parameter Type Required Example Description
Action String Yes GenerateDataKey

The operation that you want to perform. Set the value to GenerateDataKey.

KeyId String Yes 7906979c-8e06-46a2-be2d-68e3ccbc****

The ID of the CMK. The ID must be globally unique.

You can also set this parameter to an alias that is bound to the CMK. For more information, see Alias overview.

KeySpec String No AES_256

The type of the data key that you want to generate. 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 none of the parameters are specified, KMS generates a 256-bit data key. If both parameters are specified, KMS ignores the KeySpec parameter.
NumberOfBytes Integer No 256

The length of the data key that you want to generate. Unit: bytes.

Valid values: 1 to 1024.

Default value:

  • If the KeySpec parameter is set to AES_256, set the value of the NumberOfBytes parameter to 32.
  • If the KeySpec parameter is set to AES_128, set the value of the NumberOfBytes parameter to 16.
EncryptionContext Map No {"Example":"Example"}

The JSON string that consists of key-value pairs.

If you specify this parameter, an equivalent value is required when you call the Decrypt operation. For more information, see EncryptionContext.

For more information about common request parameters, see Common parameters.

Response parameters

Parameter Type Example Description
KeyVersionId String 2ab1a983-7072-4bbc-a582-584b5bd8****

The ID of the CMK version. The ID must be globally unique.

KeyId String 7906979c-8e06-46a2-be2d-68e3ccbc****

The ID of the CMK. The ID must be globally unique.

Note If you set the KeyId parameter in the request to an alias of the CMK, the ID of the CMK to which the alias is bound is returned.
CiphertextBlob String ODZhOWVmZDktM2QxNi00ODk0LWJkNGYtMWZjNDNmM2YyYWJmS7FmDBBQ0BkKsQrtRnidtPwirmDcS0ZuJCU41xxAAWk4Z8qsADfbV0b+i6kQmlvj79dJdGOvtX69Uycs901qOjop4bTS****

The ciphertext of the data key that is encrypted by using the primary version of the specified CMK.

RequestId String 7021b6ec-4be7-4d3c-8a68-1e85d4d515a0

The ID of the request, which is used to locate and troubleshoot issues.

Plaintext String QmFzZTY0IGVuY29kZWQgcGxhaW50****

The Base64 encoded plaintext of the data key.

Examples

Sample requests

http(s)://[Endpoint]/?Action=GenerateDataKey
&KeyId=7906979c-8e06-46a2-be2d-68e3ccbc****
&KeySpec=AES_256
&NumberOfBytes=256
&Common request parameters

Sample success responses

XML format 

HTTP/1.1 200 OK
Content-Type:application/xml

<GenerateDataKeyResponse>
    <KeyVersionId>2ab1a983-7072-4bbc-a582-584b5bd8****</KeyVersionId>
    <KeyId>7906979c-8e06-46a2-be2d-68e3ccbc****</KeyId>
    <CiphertextBlob>ODZhOWVmZDktM2QxNi00ODk0LWJkNGYtMWZjNDNmM2YyYWJmS7FmDBBQ0BkKsQrtRnidtPwirmDcS0ZuJCU41xxAAWk4Z8qsADfbV0b+i6kQmlvj79dJdGOvtX69Uycs901qOjop4bTS****</CiphertextBlob>
    <RequestId>7021b6ec-4be7-4d3c-8a68-1e85d4d515a0</RequestId>
    <Plaintext>QmFzZTY0IGVuY29kZWQgcGxhaW50****</Plaintext>
</GenerateDataKeyResponse>

JSON format 

HTTP/1.1 200 OK
Content-Type:application/json

{
  "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

For a list of error codes, visit the API Error Center.