Generates a data key encrypted under the initial version of a Key Management Service (KMS) key, and returns both the plaintext and ciphertext of the data key.
Operation description
Use this operation to implement envelope encryption: encrypt your data locally with the plaintext data key, then store the ciphertext data key alongside your encrypted data. Only the ciphertext data key needs to be stored — discard the plaintext after use.
After the operation completes, store all of the following fields. They are required to decrypt the data key later:
CiphertextBlob— the encrypted data keyIv— the initialization vector (IV) used during encryptionAlgorithm— the encryption algorithmAad— the additional authenticated data (AAD), if provided
Only Galois/Counter Mode (GCM) is supported when encrypting the data key. KMS uses a high-quality random number generator to produce the data key, which is independent of the KMS key material.
For information about key types and specifications, see Key types and specifications.
GenerateDataKey vs. AdvanceGenerateDataKey
Both operations generate a data key, but differ in which key version is used for encryption and which decrypt operations are supported.
| Attribute | GenerateDataKey | AdvanceGenerateDataKey |
|---|---|---|
| Key version used | Initial version | Primary version |
| Fields to store | CiphertextBlob, Iv, Algorithm, Aad | CiphertextBlob, Aad |
| Supported decrypt operations | Decrypt or AdvanceDecrypt | AdvanceDecrypt only |
| Scope | All symmetric keys | Software key management type symmetric keys only |
If you use a symmetric key in a software key management KMS instance with automatic key rotation enabled, call AdvanceGenerateDataKey instead. 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. Also accepts an alias bound to the key. |
| NumberOfBytes | int | Yes | 32 | The length of the data key to generate, in bytes. |
| Aad | binary | No | Binary data | The additional authenticated data (AAD) used in GCM mode when encrypting the data key. If specified, provide the same value when calling the Decrypt operation to decrypt the data key. |
Response elements
| Parameter | Type | Example | Description |
|---|---|---|---|
| KeyId | string | key-hzz62f1cb66fa42qo**** | The globally unique ID of the KMS key. If the request used an alias, the ID of the key bound to that alias is returned. |
| Iv | bytes | Binary data | The initialization vector (IV) used when encrypting the data key. Provide this value when calling the Decrypt operation. |
| Plaintext | bytes | Binary plaintext | The plaintext data key. Use this to encrypt your data, then discard it from memory. |
| CiphertextBlob | bytes | Binary ciphertext | The ciphertext data key. Store this alongside your encrypted data. |
| Algorithm | string | AES_GCM | The encryption algorithm used to encrypt the data key. |
| RequestId | string | 475f1620-b9d3-4d35-b5c6-3fbdd941423d | The request ID. |
Error codes
For a list of error codes, see Service error codes.