Generates a data key.

Usage notes

The GenerateDataKey operation returns the plaintext data key and ciphertext data key. You can use the plaintext data key to encrypt data outside Key Management Service (KMS). The Plaintext parameter specifies the plaintext data key. KMS does not record or store randomly generated data keys. When you store encrypted data, you also need to store the ciphertext data key, which is specified by CiphertextBlob, and store Iv, Aad, and Algorithm.

The key specified by KeyId in the request is used only to encrypt the plaintext data key. The key is not used to generate a data key

Request message definition

message GenerateDataKeyRequest {
     string KeyId = 1;
     int32 NumberOfBytes = 2;
     bytes Aad = 3;

Request parameters

KeyIdstringYeskey-hzz62f1cb66fa42qo****The globally unique ID of the key. You can also set the value to an alias that is bound to the key.
NumberOfBytesintYes 32The length of the data key to be generated.
Aad binaryNoBinary dataThe Galois/Counter Mode (GCM) mode that is used to authenticate the data when the data key is encrypted.
Important Only the GCM mode is supported when you encrypt a data key. If you specify this parameter, you must specify the parameter when you call the Decrypt operation.

Response message definition

message GenerateDataKeyResponse {
     string KeyId = 1;
     bytes  Iv = 2;
     bytes  Plaintext = 3;
     bytes  CiphertextBlob = 4;
     string RequestId = 5;
     string Algorithm = 6;

Response parameters

KeyIdstringkey-hzz62f1cb66fa42qo****The globally unique ID of the key. If KeyId in the request is set to an alias, the globally unique identifier of the key to which the alias is bound is returned in the response.
IvbytesBinary dataThe initial vector that is used when the data key is encrypted.
Note When you call the Decrypt operation to decrypt the data key, you must specify a valid Iv value to decrypt the data key.
PlaintextbytesBinary plaintextThe plaintext data key.
CiphertextBlobbytesBinary ciphertextThe ciphertext data key.
AlgorithmstringAES_GCMThe encryption algorithm.
RequestIdstring475f1620-b9d3-4d35-b5c6-3fbdd941423dThe ID of the request, which is used to locate and troubleshoot issues.

Error codes

For more information about error codes, see Common error codes.