Generating data keys
Authorized users can use the GenerateDataKey API (and related APIs) to request a specific type of data key or a random key of arbitrary length. This topic provides a simplified view of this API operation. For details, see the GenerateDataKey APIs in the AWS Key Management Service API Reference.
The following is the GenerateDataKey
request syntax.
{ “EncryptionContext”: {“string” : “string”}, “GrantTokens”: [“string”], “KeyId”: “string”, “NumberOfBytes”: “number” }
The request accepts the following data in JSON format.
- KeyId
-
Key identifier of the key used to encrypt the data key. This value must identify a symmetric encryption KMS key.
This parameter is required.
- NumberOfBytes
-
An integer that contains the number of bytes to generate. This parameter is required.
Caller must provide either
KeySpec
orNumberOfBytes
, but not both. - EncryptionContext
-
(Optional) Name-value pair that contains additional data to authenticate during the encryption and decryption processes that use the key.
- GrantTokens
-
(Optional) A list of grant tokens that represent grants that provide permissions to generate or use a key. For more information on grants and grant tokens, see Authentication and access control for AWS KMS in the AWS Key Management Service Developer Guide.
After authenticating the command, AWS KMS, acquires the current active EKT associated with the KMS key. It passes the EKT along with your provided request and any encryption context to an HSM over a protected session between the AWS KMS host and an HSM in the domain.
The HSM does the following:
-
Generates the requested secret material and hold it in volatile memory.
-
Decrypts the EKT matching the key ID of the KMS key that is defined in the request to obtain the active HBK = Decrypt(DKi, EKT).
-
Generates a random nonce N.
-
Generates a 256-bit AES-GCM derived encryption key K from HBK and N.
-
Encrypts the secret material ciphertext = Encrypt(K, context, secret).
GenerateDataKey
returns the plaintext secret material and the ciphertext to
you over the secure channel between the AWS KMS host and the HSM. AWS KMS then sends it to you
over the TLS session. AWS KMS does not retain the plaintext or ciphertext. Without possession of
the ciphertext, the encryption context, and the authorization to use the
KMS key, the underlying secret cannot be returned.
The following is the response syntax.
{ "CiphertextBlob": "blob", "KeyId": "string", "Plaintext": "blob" }
The management of data keys is left to you as the application developer. For best practice client-side encryption with AWS KMS data keys (but not data key pairs), you can use the AWS Encryption SDK.
Data keys can be rotated at any frequency. Further, the data key can be reencrypted under
a different KMS key or a rotated KMS key using the ReEncrypt
API operation.
For details, see ReEncrypt in the
AWS Key Management Service API Reference.