Returns a unique symmetric data key for use outside of KMS. This operation returns a plaintext copy of the data key and a copy that is encrypted under a symmetric encryption KMS key that you specify. The bytes in the plaintext key are random; they are not related to the caller or the KMS key. You can use the plaintext key to encrypt your data outside of KMS and store the encrypted data key with the encrypted data.
To generate a data key, specify the symmetric encryption KMS key that will be used to encrypt the data key. You cannot use an asymmetric KMS key to encrypt data keys. To get the type of your KMS key, use the
DescribeKey operation.
You must also specify the length of the data key. Use either the
KeySpec
or
NumberOfBytes
parameters (but not both). For 128-bit and 256-bit data keys, use the
KeySpec
parameter.
To generate an SM4 data key (China Regions only), specify a
KeySpec
value of
AES_128
or
NumberOfBytes
value of
128
. The symmetric encryption key used in China Regions to encrypt your data key is an SM4 encryption key.
To get only an encrypted copy of the data key, use
GenerateDataKeyWithoutPlaintext. To generate an asymmetric data key pair, use the
GenerateDataKeyPair or
GenerateDataKeyPairWithoutPlaintext operation. To get a cryptographically secure random byte string, use
GenerateRandom.
You can use an optional encryption context to add additional security to the encryption operation. If you specify an
EncryptionContext
, you must specify the same encryption context (a case-sensitive exact match) when decrypting the encrypted data key. Otherwise, the request to decrypt fails with an
InvalidCiphertextException
. For more information, see
Encryption Context in the
Key Management Service Developer Guide.
Applications in Amazon Web Services Nitro Enclaves can call this operation by using the
Amazon Web Services Nitro Enclaves Development Kit. For information about the supporting parameters, see
How Amazon Web Services Nitro Enclaves use KMS in the
Key Management Service Developer Guide.
The KMS key that you use for this operation must be in a compatible key state. For details, see
Key states of KMS keys in the
Key Management Service Developer Guide.
How to use your data key We recommend that you use the following pattern to encrypt data locally in your application. You can write your own code or use a client-side encryption library, such as the
Amazon Web Services Encryption SDK, the
Amazon DynamoDB Encryption Client, or
Amazon S3 client-side encryption to do these tasks for you.
To encrypt data outside of KMS:
- Use the
GenerateDataKey
operation to get a data key. - Use the plaintext data key (in the
Plaintext
field of the response) to encrypt your data outside of KMS. Then erase the plaintext data key from memory. - Store the encrypted data key (in the
CiphertextBlob
field of the response) with the encrypted data.
To decrypt data outside of KMS:
- Use the Decrypt operation to decrypt the encrypted data key. The operation returns a plaintext copy of the data key.
- Use the plaintext data key to decrypt data outside of KMS, then erase the plaintext data key from memory.
Cross-account use: Yes. To perform this operation with a KMS key in a different Amazon Web Services account, specify the key ARN or alias ARN in the value of the
KeyId
parameter.
Required permissions:
kms:GenerateDataKey (key policy)
Related operations: