Generates a data key for envelope encryption using Key Management Service (KMS). The operation returns both the plaintext data key and the ciphertext data key. Use the plaintext data key to encrypt data outside KMS, then store the ciphertext data key and authentication data (Aad) for later decryption.
How it works
The operation uses a high-quality random number generator to produce a data key, independent of the KMS key material. It then encrypts the data key using the primary key version of the specified KMS key in Galois/Counter Mode (GCM).
If automatic key rotation is enabled, call AdvanceGenerateDataKey (not GenerateDataKey) to generate data keys. Using GenerateDataKey when key rotation is enabled causes the rotation feature to stop working. For details, see Configure key rotation.
AdvanceGenerateDataKey vs GenerateDataKey
Both operations generate a data key, but they differ in which key version is used for encryption and what data you must store afterward.
| Aspect | AdvanceGenerateDataKey | GenerateDataKey |
|---|---|---|
| Key version used for encryption | Primary key version | Initial key version |
| Data to store after encryption | CiphertextBlob, Aad | CiphertextBlob, Iv, Algorithm, Aad |
| Supported decrypt operation | AdvanceDecrypt | Decrypt or AdvanceDecrypt |
Limits
This operation supports only symmetric keys in KMS instances of the software key management type. For supported key specifications, see Key types and specifications.
Only GCM mode is supported for data key encryption.
Request parameters
| Parameter | Type | Required | Example | Description |
|---|---|---|---|---|
| KeyId | string | Yes | key-hzz62f1cb66fa42qo**** | The globally unique ID of the KMS key, or an alias bound to the key. The key must be a symmetric key in a software key management type KMS instance. |
| NumberOfBytes | int | Yes | 32 | The length of the data key to generate. |
| Aad | binary | No | Binary data | The authentication data for GCM-mode encryption. If specified, you must also pass the same Aad value when calling AdvanceDecrypt. |
Response elements
| Parameter | Type | Example | Description |
|---|---|---|---|
| CiphertextBlob | bytes | Binary ciphertext | The ciphertext data key. This field encodes the key ID (KeyId), encryption algorithm (Algorithm), and initial vector (Iv) used during encryption. To decrypt, pass only CiphertextBlob and Aad to AdvanceDecrypt. |
| Plaintext | bytes | Binary plaintext | The plaintext data key. Use this to encrypt data outside KMS. |
| KeyId | string | key-hzz62f1cb66fa42qo**** | The globally unique ID of the KMS key. If the request KeyId was an alias, this field returns the ID of the key the alias is bound to. |
| KeyVersionId | string | key-hzz62f1cb66fa42qo****-17kedv**** | The ID of the key version used to encrypt the data key. |
| Algorithm | string | AES_GCM | The encryption algorithm used to encrypt the data key. |
| Iv | bytes | Binary data | The initial vector used to encrypt the data key. |
| RequestId | string | c0065a6d-7784-4ef2-a692-288fdcbc7b9d | The request ID. |
Error codes
| HTTP status code | Error code | Error message | Description |
|---|---|---|---|
| 404 | Forbidden.OnlySymmetricKeySupported | The key %s is not a symmetric key. The API only supports symmetric keys. | Only symmetric keys are supported. |
For a full list of error codes, see Service error codes.