Smaws_Client_KMS.GenerateDataKeyval request :
Smaws_Lib.Context.t ->
generate_data_key_request ->
(generate_data_key_response,
[> Smaws_Lib.Protocols.AwsJson.error
| `DependencyTimeoutException of dependency_timeout_exception
| `DisabledException of disabled_exception
| `DryRunOperationException of dry_run_operation_exception
| `InvalidGrantTokenException of invalid_grant_token_exception
| `InvalidKeyUsageException of invalid_key_usage_exception
| `KeyUnavailableException of key_unavailable_exception
| `KMSInternalException of kms_internal_exception
| `KMSInvalidStateException of kms_invalid_state_exception
| `NotFoundException of not_found_exception ])
Stdlib.resultReturns 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 a 128-bit SM4 data key (China Regions only), specify a KeySpec value of AES_128 or a NumberOfBytes value of 16. 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.
GenerateDataKey also supports Amazon Web Services Nitro Enclaves, which provide an isolated compute environment in Amazon EC2. To call GenerateDataKey for an Amazon Web Services Nitro enclave, use the Amazon Web Services Nitro Enclaves SDK or any Amazon Web Services SDK. Use the Recipient parameter to provide the attestation document for the enclave. GenerateDataKey returns a copy of the data key encrypted under the specified KMS key, as usual. But instead of a plaintext copy of the data key, the response includes a copy of the data key encrypted under the public key from the attestation document (CiphertextForRecipient). For information about the interaction between KMS and Amazon Web Services Nitro Enclaves, see How Amazon Web Services Nitro Enclaves uses 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:
GenerateDataKey operation to get a data key.Plaintext field of the response) to encrypt your data outside of KMS. Then erase the plaintext data key from memory.CiphertextBlob field of the response) with the encrypted data.To decrypt data outside of KMS:
Decrypt operation to decrypt the encrypted data key. The operation returns a plaintext copy of the data key.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:
DecryptEncryptGenerateDataKeyPairGenerateDataKeyPairWithoutPlaintextGenerateDataKeyWithoutPlaintextEventual consistency: The KMS API follows an eventual consistency model. For more information, see KMS eventual consistency.