Generates a data key.
Usage notes
Overview
This operation generates a data key by using a random number generator, encrypts the data key by using the initial version of a Key Management Service (KMS) key, and then returns the plaintext data key and ciphertext data key. You can use the plaintext data key to encrypt data outside KMS. Plaintext specifies the plaintext data key. After encryption, you must store the ciphertext data key (CiphertextBlob), initial vector (Iv), encryption algorithm (Algorithm), and authentication data (Aad), which will be used to decrypt data.
For more information about key specifications and encryption modes, see Key types and specifications.
Only the Galois/Counter Mode (GCM) mode is supported when you encrypt a data key.
KMS uses a high-quality random number generator to generate a data key, which is independent of the KMS key material used to encrypt the data key.
Difference between GenerateDataKey and AdvanceGenerateDataKey
You can call the AdvanceGenerateDataKey operation and the GenerateDataKey operation to generate a data key. The following section describes the differences between the two operations:
GenerateDataKey: The initial version of a key is used for encryption. After encryption, you must store the ciphertext data key (CiphertextBlob), initial vector (Iv), encryption algorithm (Algorithm), and authentication data (Aad). You can call the Decrypt or AdvanceDecrypt operation to decrypt data.
AdvanceGenerateDataKey: You can call this operation only for a symmetric key in KMS instances of the software key management type. The primary version of a key is used for encryption. After encryption, you must store the ciphertext data key (CiphertextBlob) and authentication data (Aad). You must call the AdvanceDecrypt operation to decrypt data.
ImportantIf you use a symmetric key in KMS instances of the software key management type and enable automatic rotation for the key, you must call the AdvanceGenerateDataKey operation to generate a data key to prevent the key rotation feature from becoming invalid. For more information about automatic key rotation, see Configure key rotation.
Request parameters
Parameter | Type | Required | Example | Description |
KeyId | string | Yes | key-hzz62f1cb66fa42qo**** | The globally unique ID of the key. You can also set the value to an alias that is bound to the key. |
NumberOfBytes | int | Yes | 32 | The length of the data key to be generated. |
Aad | binary | No | Binary data | The 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 this parameter is specified, you must specify the same parameter when you call the Decrypt operation. |
Response parameters
Parameter | Type | Example | Description |
KeyId | string | key-hzz62f1cb66fa42qo**** | The globally unique ID of the key. If KeyId in the request is set to an alias, the globally unique ID of the key to which the alias is bound is returned in the response. |
Iv | bytes | Binary data | The 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 value for Iv to decrypt the data key. |
Plaintext | bytes | Binary plaintext | The plaintext data key. |
CiphertextBlob | bytes | Binary ciphertext | The ciphertext data key. |
Algorithm | string | AES_GCM | The encryption algorithm. |
RequestId | string | 475f1620-b9d3-4d35-b5c6-3fbdd941423d | The request ID. |
Error codes
For a list of error codes, see Service error codes.