Call GenerateDataKey to generate a random data key. You can use the data key to encrypt local data.

This operation creates a random data key, encrypts the data key with the specified CMK, and returns the ciphertext and plaintext of the data key. You can use the returned plaintext to encrypt local data in services other than KMS in an offline manner. When storing encrypted data, you also need to store the ciphertext of the data key. 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 specified in the request 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.

We recommend that you encrypt local data in the following way:

  • Call GenerateDataKey API operation to obtain the data encryption 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:

  • CallDecrypt 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.

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 1234abcd-12ab-34cd-56ef-12345678****

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 AES_256

The length of the generated data key. 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 data keys. If neither is specified, KMS generates 256-bit data key. If both are specified, KMS ignores the KeySpec parameter.
NumberOfBytes Integer No 256

Specifies the length of the data key to generate.

Value range: 1 to 1024

Unit: bytes.

EncryptionContext Json No {"Example":"Example"}

The JSON string of the key-value pair. If you specify this parameter, it is also required when you call the Decrypt API operation. For more information, see EncryptionContext.

Response parameters

Parameter Type Example Description
CiphertextBlob String ODZhOWVmZDktM2QxNi00ODk0LWJkNGYtMWZjNDNmM2YyYWJmS7FmDBBQ0BkKsQrtRnidtPwirmDcS0ZuJCU41xxAAWk4Z8qsADfbV0b+i6kQmlvj79dJdGOvtX69Uycs901qOjop4bTSl0oQ

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

KeyId String 599 fa825-17 de-417e-9554-bb032cc6 instance account number *

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 2ab1a983-7072-4bbc-a582-584b5bd8****

The ID of the key version used to encrypt plaintext. It is the primary key version of the specified CMK.

Plaintext String Cost

The plaintext of the data key, which is encoded in Base64.

RequestId String 7021 b6 ec-4be7-4d3c-8a68-1e85d4d515a0

The ID of the request.

Examples

Sample requests

http(s)://[Endpoint]/? Action=GenerateDataKey
&KeyId=1234abcd-12ab-34cd-56ef-12345678****
&<Common request parameters>

Sample success responses

XML format

<KMS>
          <CiphertextBlob>ODZhOWVmZDktM2QxNi00ODk0LWJkNGYtMWZjNDNmM2YyYWJmS7FmDBBQ0BkKsQrtRnidtPwirmDcS0ZuJCU41xxAAWk4Z8qsADfbV0b+i6kQmlvj79dJdGOvtX69Uycs901qOjop4bTSl0oQ</CiphertextBlob>
          <KeyId>599fa825-17de-417e-9554-bb032cc6****</KeyId>
          <KeyVersionId>2ab1a983-7072-4bbc-a582-584b5bd8****</KeyVersionId>
          <Plaintext>QmFzZTY0IGVuY29kZWQgcGxhaW50ZXh0</Plaintext>
          <RequestId>7021b6ec-4be7-4d3c-8a68-1e85d4d515a0</RequestId>
</KMS>

JSON format

{
        "CiphertextBlob": "ODZhOWVmZDktM2QxNi00ODk0LWJkNGYtMWZjNDNmM2YyYWJmS7FmDBBQ0BkKsQrtRnidtPwirmDcS0ZuJCU41xxAAWk4Z8qsADfbV0b+i6kQmlvj79dJdGOvtX69Uycs901qOjop4bTSl0oQ",
        "KeyId": "599fa825-17de-417e-9554-bb032cc6****",
        "KeyVersionId": "2ab1a983-7072-4bbc-a582-584b5bd8****",
        "Plaintext": "QmFzZTY0IGVuY29kZWQgcGxhaW50ZXh0",
        "RequestId": "7021b6ec-4be7-4d3c-8a68-1e85d4d515a0"
}

Error codes

HTTP status code Error code Error message Description
400 Throttling Request was denied due to request throttling. This message returned because your traffic in this period has exceeded the limit. If your business requirements are not met, submit a ticket.

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