GenerateDataKey

Generates a unique symmetric data key for client-side encryption.

Description

The `GenerateDataKey` operation generates a unique symmetric data key and returns both the plaintext version of the key and a copy that is encrypted under a KMS key that you specify. You can use the plaintext key to encrypt your data outside of QKMS and store the encrypted data key with the encrypted data.

note

• The KMS key you specify must be a symmetric encryption KMS key.
• You must specify the KMS key that will be used to encrypt the data key.
• The generated data key can be used to encrypt data outside of QKMS.
• The encrypted version of the data key can only be decrypted by QKMS.

Request Syntax

Headers

Name	Description	Required	Type
Content-Type	Must be "application/x-amz-json-1.1"	Yes	string
X-Amz-Target	Must be "TrentService.GenerateDataKey"	Yes	string

Request Body

Name	Description	Required	Type
KeyId	The identifier of the KMS key to use to encrypt the data key. This can be the key ID or key ARN of the KMS key.	Yes	string
KeySpec	Specifies the type of data key to generate. Valid Values: AES_256 |AES_128. You must specify either KeySpec or NumberOfBytes, but not both.	No	string
NumberOfBytes	The length of the data key in bytes. For example, use 64 to generate a 512-bit data key. You must specify either KeySpec or NumberOfBytes, but not both.	No	integer
EncryptionContext	A set of key-value pairs that helps you identify the data key when you need to decrypt it later.	No	map
GrantTokens	A list of grant tokens that represent grants that allow this operation.	No	array

POST / HTTP/1.1

Content-Type: application/x-amz-json-1.1

X-Amz-Target: TrentService.GenerateDataKey

{ "KeyId": "1234abcd-12ab-34cd-56ef-1234567890ab", "KeySpec": "AES_256", "EncryptionContext": { "Purpose": "Test" } }

Values in italics indicate user input and should be replaced with actual values.

Examples

Example 1: Generate a data key

POST / HTTP/1.1

Content-Type: application/x-amz-json-1.1

X-Amz-Target: TrentService.GenerateDataKey

{ "KeyId": "1234abcd-12ab-34cd-56ef-1234567890ab", "KeySpec": "AES_256" }

Values in italics indicate user input and should be replaced with actual values.

HTTP/1.1 200 OK

Content-Type: application/x-amz-json-1.1

{ "KeyId": "arn:verenc:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab", "Plaintext": "Base64-encoded plaintext key", "CiphertextBlob": "Base64-encoded encrypted data key" }

Values in italics indicate variable response values.

Response Elements

Name	Description	Required	Type
CiphertextBlob	The encrypted copy of the data key.	No	String
KeyId	The Amazon Resource Name (ARN) of the KMS key that encrypted the data key.	No	String
Plaintext	The plaintext data key. Use this value to encrypt your data outside of QKMS.	No	String

Special Errors

Error Code	Description
DependencyTimeoutException	The system timed out while trying to fulfill the request.
DisabledException	The request was rejected because the specified KMS key is disabled.
InvalidGrantTokenException	The request was rejected because a grant token was invalid.
InvalidKeyUsageException	The request was rejected because the specified KeyUsage value is not valid for this operation.
KeyUnavailableException	The request was rejected because the specified KMS key was not available.
KMSInternalException	An internal error occurred.
KMSInvalidStateException	The request was rejected because the key state is not valid for this operation.
NotFoundException	The request was rejected because the specified entity or resource could not be found.

Permissions

To use the `GenerateDataKey` operation, you must have the following permissions:

• `kms:GenerateDataKey` on the KMS key (specified in the policy)
• `kms:Decrypt` on the KMS key (to decrypt the data key)

Try It Out

Test GenerateDataKey

Generate a data key for client-side encryption.

Coming Soon

This feature is currently under development and will be available soon.