Generates a random data key, which can be used to encrypt local data.

This operation creates a random data key, encrypts the data key by using a specific symmetric CMK, and returns the ciphertext of the data key. This operation serves the same purpose as the GenerateDataKey operation. The only difference is that this operation does not return the plaintext of the data key.

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.

Note
  • This operation applies to the scenario when you do not need to use the data key to immediately encrypt data. Before you can use the data key to encrypt data, you must call the Decrypt operation to decrypt the ciphertext of the data key.
  • This operation is also suitable for a distributed system with different trust levels. For example, a system stores data in different partitions based on a preset trust policy. A module creates different partitions and generates different data keys for each partition 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 ciphertext of the data key for a partition first. After decrypting the ciphertext of the data key, modules on the control plane use the plaintext of the data key to encrypt or decrypt data and then clear the plaintext of the data key from the memory. In such a system, the key provider does not need to obtain the plaintext of the data key. It only needs to have the permissions to call the GenerateDataKeyWithoutPlaintext operation. The data producers or consumers do not need to generate new data keys. They only need to have the permissions to call the Decrypt operation.

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 GenerateDataKeyWithoutPlaintext

The operation that you want to perform. Set the value to GenerateDataKeyWithoutPlaintext.
KeyId String Yes 1234abcd-12ab-34cd-56ef-12345678****

The globally unique ID of the CMK. You can also set this parameter to an alias that is bound to the CMK. For more information, see Use aliases.

KeySpec String No AES_256

The length of the data key that you want to generate. Valid values:

  • AES_256: 256-bit symmetric key
  • AES_128: 128-bit symmetric key
Note We recommend that you use the KeySpec or NumberOfBytes parameter to specify the length of a data key. If both of them are not specified, KMS generates a 256-bit data key. If both of them are specified, KMS ignores the KeySpec parameter.
NumberOfBytes Integer No 256

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

Valid values: 1 to 1024.

Unit: bytes.
EncryptionContext Json No {"Example":"Example"}

A 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.

Response parameters

Parameter Type Example Description
CiphertextBlob String ODZhOWVmZDktM2QxNi00ODk0LWJkNGYtMWZjNDNmM2YyYWJmS7FmDBBQ0BkKsQrtRnidtPwirmDcS0ZuJCU41xxAAWk4Z8qsADfbV0b+i6kQmlvj79dJdGOvtX69Uycs901qOjop4bTS****

The ciphertext of the data that is encrypted by using the primary CMK version.
KeyId String 599fa825-17de-417e-9554-bb032cc6****

The globally unique ID of the CMK.

Note If you set the KeyId parameter to an alias, 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 that is used to encrypt the plaintext. It is the primary version of the CMK.

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

The ID of the request.

Examples

Sample requests

https://[Endpoint]/?Action=GenerateDataKeyWithoutPlaintext
&KeyId=1234abcd-12ab-34cd-56ef-12345678****
&<Common request parameters>

Sample success responses

XML format 

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

JSON format 

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

Error codes

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