Generates a plaintext data key and its encrypted counterpart using a KMS key.
Usage notes
Overview
GenerateDataKey uses a random number generator to create a data key, encrypts it using the initial version of a Key Management Service (KMS) key, and returns both the plaintext data key and the ciphertext data key. Use the plaintext data key to encrypt data outside KMS. After encryption, store the ciphertext data key (CiphertextBlob), the initial vector (Iv), the encryption algorithm (Algorithm), and the additional authenticated data (Aad) — all four values are required to decrypt the data later.
For more information about key specifications and encryption modes, see Key types and specifications.
Only Galois/Counter Mode (GCM) is supported when encrypting a data key.
KMS uses a high-quality random number generator to produce the data key. This generator operates independently of the KMS key material used to encrypt the data key.
Difference between GenerateDataKey and AdvanceGenerateDataKey
Both GenerateDataKey and AdvanceGenerateDataKey generate a data key. The following table describes the key differences:
| GenerateDataKey | AdvanceGenerateDataKey | |
|---|---|---|
| Key version used | Initial version | Primary version |
| Supported key type | Any supported key | Symmetric keys in software key management KMS instances only |
| Values to store after encryption | CiphertextBlob, Iv, Algorithm, Aad | CiphertextBlob, Aad |
| Decrypt operations | Decrypt or AdvanceDecrypt | AdvanceDecrypt only |
If you use a symmetric key in a software key management KMS instance with automatic rotation enabled, call AdvanceGenerateDataKey instead of GenerateDataKey. Using GenerateDataKey in this configuration causes the key rotation feature to stop working. For more information, see Configure key rotation.
Request parameters
| Parameter | Type | Required | Example | Description |
|---|---|---|---|---|
| KeyId | string | Yes | key-hzz62f1cb66fa42qo**** | The globally unique ID of the KMS key. You can also specify an alias bound to the key. |
| NumberOfBytes | int | Yes | 32 | The length of the data key to generate. |
| Aad | binary | No | Binary data | The additional authenticated data (Aad) used to authenticate the data key during encryption. GCM mode is the only supported encryption mode. If you specify this parameter, pass the same value when calling the Decrypt operation. |
Response parameters
| Parameter | Type | Example | Description |
|---|---|---|---|
| KeyId | string | key-hzz62f1cb66fa42qo**** | The globally unique ID of the KMS key. If the request specified an alias, this field returns the ID of the key to which the alias is bound. |
| Iv | bytes | Binary data | The initial vector used when the data key was encrypted. When calling the Decrypt operation to decrypt the data key, you must specify a valid value for Iv. |
| 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.