AWS SDK Version 3 for .NET
API Reference

AWS services or capabilities described in AWS Documentation may vary by region/location. Click Getting Started with Amazon AWS to see specific differences applicable to the China (Beijing) Region.

Generates a unique data key. This operation returns a plaintext copy of the data key and a copy that is encrypted under a customer master key (CMK) that you specify. You can use the plaintext key to encrypt your data outside of KMS and store the encrypted data key with the encrypted data.

GenerateDataKey returns a unique data key for each request. The bytes in the key are not related to the caller or CMK that is used to encrypt the data key.

To generate a data key, you need to specify the customer master key (CMK) that will be used to encrypt the data key. You must also specify the length of the data key using either the KeySpec or NumberOfBytes field (but not both). For common key lengths (128-bit and 256-bit symmetric keys), we recommend that you use KeySpec. To perform this operation on a CMK in a different AWS account, specify the key ARN or alias ARN in the value of the KeyId parameter.

You will find the plaintext copy of the data key in the Plaintext field of the response, and the encrypted copy of the data key in the CiphertextBlob field.

We recommend that you use the following pattern to encrypt data locally in your application:

  1. Use the GenerateDataKey operation to get a data encryption key.

  2. Use the plaintext data key (returned in the Plaintext field of the response) to encrypt data locally, then erase the plaintext data key from memory.

  3. Store the encrypted data key (returned in the CiphertextBlob field of the response) alongside the locally encrypted data.

To decrypt data locally:

  1. Use the Decrypt operation to decrypt the encrypted data key. The operation returns a plaintext copy of the data key.

  2. Use the plaintext data key to decrypt data locally, then erase the plaintext data key from memory.

To get only an encrypted copy of the data key, use GenerateDataKeyWithoutPlaintext. To get a cryptographically secure random byte string, use GenerateRandom.

You can use the optional encryption context to add additional security to your encryption operation. When you specify an EncryptionContext in the GenerateDataKey operation, you must specify the same encryption context (a case-sensitive exact match) in your request to Decrypt the data key. Otherwise, the request to decrypt fails with an InvalidCiphertextException. For more information, see Encryption Context in the AWS Key Management Service Developer Guide.

The result of this operation varies with the key state of the CMK. For details, see How Key State Affects Use of a Customer Master Key in the AWS Key Management Service Developer Guide.

Note:

For .NET Core and PCL this operation is only available in asynchronous form. Please refer to GenerateDataKeyAsync.

Namespace: Amazon.KeyManagementService
Assembly: AWSSDK.KeyManagementService.dll
Version: 3.x.y.z

Syntax

C#
public virtual GenerateDataKeyResponse GenerateDataKey(
         GenerateDataKeyRequest request
)
Parameters
request
Type: Amazon.KeyManagementService.Model.GenerateDataKeyRequest

Container for the necessary parameters to execute the GenerateDataKey service method.

Return Value
The response from the GenerateDataKey service method, as returned by KeyManagementService.

Exceptions

ExceptionCondition
DependencyTimeoutException The system timed out while trying to fulfill the request. The request can be retried.
DisabledException The request was rejected because the specified CMK is not enabled.
InvalidGrantTokenException The request was rejected because the specified grant token is not valid.
InvalidKeyUsageException The request was rejected because the specified KeySpec value is not valid.
KeyUnavailableException The request was rejected because the specified CMK was not available. The request can be retried.
KMSInternalException The request was rejected because an internal exception occurred. The request can be retried.
KMSInvalidStateException The request was rejected because the state of the specified resource is not valid for this request. For more information about how key state affects the use of a CMK, see How Key State Affects Use of a Customer Master Key in the AWS Key Management Service Developer Guide.
NotFoundException The request was rejected because the specified entity or resource could not be found.

Examples

The following example generates a 256-bit symmetric data encryption key (data key) in two formats. One is the unencrypted (plainext) data key, and the other is the data key encrypted with the specified customer master key (CMK).

To generate a data key


var response = client.GenerateDataKey(new GenerateDataKeyRequest 
{
    KeyId = "alias/ExampleAlias", // The identifier of the CMK to use to encrypt the data key. You can use the key ID or Amazon Resource Name (ARN) of the CMK, or the name or ARN of an alias that refers to the CMK.
    KeySpec = "AES_256" // Specifies the type of data key to return.
});

MemoryStream ciphertextBlob = response.CiphertextBlob; // The encrypted data key.
string keyId = response.KeyId; // The ARN of the CMK that was used to encrypt the data key.
MemoryStream plaintext = response.Plaintext; // The unencrypted (plaintext) data key.

            

Version Information

.NET Framework:
Supported in: 4.5, 4.0, 3.5

Portable Class Library:
Supported in: Windows Store Apps
Supported in: Windows Phone 8.1
Supported in: Xamarin Android
Supported in: Xamarin iOS (Unified)
Supported in: Xamarin.Forms

See Also