Network.AWS.KMS.GenerateDataKey

Generates a data key that you can use in your application to locally encrypt data. This call returns a plaintext version of the key in the Plaintext field of the response object and an encrypted copy of the key in the CiphertextBlob field. The key is encrypted by using the master key specified by the KeyId field. To decrypt the encrypted key, pass it to the Decrypt API.

We recommend that you use the following pattern to locally encrypt data: call the GenerateDataKey API, use the key returned in the Plaintext response field to locally encrypt data, and then erase the plaintext data key from memory. Store the encrypted data key (contained in the CiphertextBlob field) alongside of the locally encrypted data.

You should not call the Encrypt function to re-encrypt your data keys within a region. GenerateDataKey always returns the data key encrypted and tied to the customer master key that will be used to decrypt it. There is no need to decrypt it twice.

If you decide to use the optional EncryptionContext parameter, you must also store the context in full or at least store enough information along with the encrypted data to be able to reconstruct the context when submitting the ciphertext to the Decrypt API. It is a good practice to choose a context that you can reconstruct on the fly to better secure the ciphertext. For more information about how this parameter is used, see Encryption Context.

To decrypt data, pass the encrypted data key to the Decrypt API. Decrypt uses the associated master key to decrypt the encrypted data key and returns it as plaintext. Use the plaintext data key to locally decrypt your data and then erase the key from memory. You must specify the encryption context, if any, that you specified when you generated the key. The encryption context is logged by CloudTrail, and you can use this log to help track the use of particular data.

Creating a Request

generateDataKey

Arguments

:: Text

gdkKeyId

-> GenerateDataKey

Creates a value of GenerateDataKey with the minimum fields required to make a request.

Use one of the following lenses to modify other fields as desired:

• gdkKeySpec
• gdkEncryptionContext
• gdkNumberOfBytes
• gdkGrantTokens
• gdkKeyId

data GenerateDataKey

See: generateDataKey smart constructor.

Instances

Eq GenerateDataKey

Methods

(==) :: GenerateDataKey -> GenerateDataKey -> Bool

(/=) :: GenerateDataKey -> GenerateDataKey -> Bool

Data GenerateDataKey

Methods

gfoldl :: (forall d b. Data d => c (d -> b) -> d -> c b) -> (forall g. g -> c g) -> GenerateDataKey -> c GenerateDataKey

gunfold :: (forall b r. Data b => c (b -> r) -> c r) -> (forall r. r -> c r) -> Constr -> c GenerateDataKey

toConstr :: GenerateDataKey -> Constr

dataTypeOf :: GenerateDataKey -> DataType

dataCast1 :: Typeable (* -> *) t => (forall d. Data d => c (t d)) -> Maybe (c GenerateDataKey)

dataCast2 :: Typeable (* -> * -> *) t => (forall d e. (Data d, Data e) => c (t d e)) -> Maybe (c GenerateDataKey)

gmapT :: (forall b. Data b => b -> b) -> GenerateDataKey -> GenerateDataKey

gmapQl :: (r -> r' -> r) -> r -> (forall d. Data d => d -> r') -> GenerateDataKey -> r

gmapQr :: (r' -> r -> r) -> r -> (forall d. Data d => d -> r') -> GenerateDataKey -> r

gmapQ :: (forall d. Data d => d -> u) -> GenerateDataKey -> [u]

gmapQi :: Int -> (forall d. Data d => d -> u) -> GenerateDataKey -> u

gmapM :: Monad m => (forall d. Data d => d -> m d) -> GenerateDataKey -> m GenerateDataKey

gmapMp :: MonadPlus m => (forall d. Data d => d -> m d) -> GenerateDataKey -> m GenerateDataKey

gmapMo :: MonadPlus m => (forall d. Data d => d -> m d) -> GenerateDataKey -> m GenerateDataKey

Read GenerateDataKey

Methods

readsPrec :: Int -> ReadS GenerateDataKey

readList :: ReadS [GenerateDataKey]

readPrec :: ReadPrec GenerateDataKey

readListPrec :: ReadPrec [GenerateDataKey]

Show GenerateDataKey

Methods

showsPrec :: Int -> GenerateDataKey -> ShowS

show :: GenerateDataKey -> String

showList :: [GenerateDataKey] -> ShowS

Generic GenerateDataKey

Associated Types

type Rep GenerateDataKey :: * -> *

Methods

from :: GenerateDataKey -> Rep GenerateDataKey x

to :: Rep GenerateDataKey x -> GenerateDataKey

Hashable GenerateDataKey

Methods

hashWithSalt :: Int -> GenerateDataKey -> Int

hash :: GenerateDataKey -> Int

NFData GenerateDataKey

Methods

rnf :: GenerateDataKey -> ()

AWSRequest GenerateDataKey

Associated Types

type Rs GenerateDataKey :: *

Methods

request :: GenerateDataKey -> Request GenerateDataKey

response :: MonadResource m => Logger -> Service -> Proxy * GenerateDataKey -> ClientResponse -> m (Response GenerateDataKey)

ToPath GenerateDataKey

Methods

toPath :: GenerateDataKey -> ByteString

ToHeaders GenerateDataKey

Methods

toHeaders :: GenerateDataKey -> [Header]

ToQuery GenerateDataKey

Methods

toQuery :: GenerateDataKey -> QueryString

ToJSON GenerateDataKey

Methods

toJSON :: GenerateDataKey -> Value

toEncoding :: GenerateDataKey -> Encoding

type Rep GenerateDataKey

type Rep GenerateDataKey = D1 (MetaData "GenerateDataKey" "Network.AWS.KMS.GenerateDataKey" "amazonka-kms-1.4.4-CcxNJiRfZEW9YOdWrceDWF" False) (C1 (MetaCons "GenerateDataKey'" PrefixI True) ((:*:) ((:*:) (S1 (MetaSel (Just Symbol "_gdkKeySpec") NoSourceUnpackedness SourceStrict DecidedStrict) (Rec0 (Maybe DataKeySpec))) (S1 (MetaSel (Just Symbol "_gdkEncryptionContext") NoSourceUnpackedness SourceStrict DecidedStrict) (Rec0 (Maybe (Map Text Text))))) ((:*:) (S1 (MetaSel (Just Symbol "_gdkNumberOfBytes") NoSourceUnpackedness SourceStrict DecidedStrict) (Rec0 (Maybe Nat))) ((:*:) (S1 (MetaSel (Just Symbol "_gdkGrantTokens") NoSourceUnpackedness SourceStrict DecidedStrict) (Rec0 (Maybe [Text]))) (S1 (MetaSel (Just Symbol "_gdkKeyId") NoSourceUnpackedness SourceStrict DecidedStrict) (Rec0 Text))))))

type Rs GenerateDataKey

type Rs GenerateDataKey = GenerateDataKeyResponse

Request Lenses

gdkKeySpec :: Lens' GenerateDataKey (Maybe DataKeySpec)

Value that identifies the encryption algorithm and key size to generate a data key for. Currently this can be AES_128 or AES_256.

gdkEncryptionContext :: Lens' GenerateDataKey (HashMap Text Text)

Name/value pair that contains additional data to be authenticated during the encryption and decryption processes that use the key. This value is logged by AWS CloudTrail to provide context around the data encrypted by the key.

gdkNumberOfBytes :: Lens' GenerateDataKey (Maybe Natural)

Integer that contains the number of bytes to generate. Common values are 128, 256, 512, and 1024. 1024 is the current limit. We recommend that you use the KeySpec parameter instead.

gdkGrantTokens :: Lens' GenerateDataKey [Text]

A list of grant tokens.

For more information, see Grant Tokens in the AWS Key Management Service Developer Guide.

gdkKeyId :: Lens' GenerateDataKey Text

A unique identifier for the customer master key. This value can be a globally unique identifier, a fully specified ARN to either an alias or a key, or an alias name prefixed by "alias/".

• Key ARN Example - arn:aws:kms:us-east-1:123456789012:key/12345678-1234-1234-1234-123456789012
• Alias ARN Example - arn:aws:kms:us-east-1:123456789012:alias/MyAliasName
• Globally Unique Key ID Example - 12345678-1234-1234-1234-123456789012
• Alias Name Example - alias/MyAliasName

Destructuring the Response

generateDataKeyResponse

Arguments

:: Int

gdkrsResponseStatus

-> Text

gdkrsKeyId

-> ByteString

gdkrsPlaintext

-> ByteString

gdkrsCiphertextBlob

-> GenerateDataKeyResponse

Creates a value of GenerateDataKeyResponse with the minimum fields required to make a request.

Use one of the following lenses to modify other fields as desired:

• gdkrsResponseStatus
• gdkrsKeyId
• gdkrsPlaintext
• gdkrsCiphertextBlob

data GenerateDataKeyResponse

See: generateDataKeyResponse smart constructor.

Instances

Eq GenerateDataKeyResponse

Methods

(==) :: GenerateDataKeyResponse -> GenerateDataKeyResponse -> Bool

(/=) :: GenerateDataKeyResponse -> GenerateDataKeyResponse -> Bool

Data GenerateDataKeyResponse

Methods

gfoldl :: (forall d b. Data d => c (d -> b) -> d -> c b) -> (forall g. g -> c g) -> GenerateDataKeyResponse -> c GenerateDataKeyResponse

gunfold :: (forall b r. Data b => c (b -> r) -> c r) -> (forall r. r -> c r) -> Constr -> c GenerateDataKeyResponse

toConstr :: GenerateDataKeyResponse -> Constr

dataTypeOf :: GenerateDataKeyResponse -> DataType

dataCast1 :: Typeable (* -> *) t => (forall d. Data d => c (t d)) -> Maybe (c GenerateDataKeyResponse)

dataCast2 :: Typeable (* -> * -> *) t => (forall d e. (Data d, Data e) => c (t d e)) -> Maybe (c GenerateDataKeyResponse)

gmapT :: (forall b. Data b => b -> b) -> GenerateDataKeyResponse -> GenerateDataKeyResponse

gmapQl :: (r -> r' -> r) -> r -> (forall d. Data d => d -> r') -> GenerateDataKeyResponse -> r

gmapQr :: (r' -> r -> r) -> r -> (forall d. Data d => d -> r') -> GenerateDataKeyResponse -> r

gmapQ :: (forall d. Data d => d -> u) -> GenerateDataKeyResponse -> [u]

gmapQi :: Int -> (forall d. Data d => d -> u) -> GenerateDataKeyResponse -> u

gmapM :: Monad m => (forall d. Data d => d -> m d) -> GenerateDataKeyResponse -> m GenerateDataKeyResponse

gmapMp :: MonadPlus m => (forall d. Data d => d -> m d) -> GenerateDataKeyResponse -> m GenerateDataKeyResponse

gmapMo :: MonadPlus m => (forall d. Data d => d -> m d) -> GenerateDataKeyResponse -> m GenerateDataKeyResponse

Read GenerateDataKeyResponse

Methods

readsPrec :: Int -> ReadS GenerateDataKeyResponse

readList :: ReadS [GenerateDataKeyResponse]

readPrec :: ReadPrec GenerateDataKeyResponse

readListPrec :: ReadPrec [GenerateDataKeyResponse]

Show GenerateDataKeyResponse

Methods

showsPrec :: Int -> GenerateDataKeyResponse -> ShowS

show :: GenerateDataKeyResponse -> String

showList :: [GenerateDataKeyResponse] -> ShowS

Generic GenerateDataKeyResponse

Associated Types

type Rep GenerateDataKeyResponse :: * -> *

Methods

from :: GenerateDataKeyResponse -> Rep GenerateDataKeyResponse x

to :: Rep GenerateDataKeyResponse x -> GenerateDataKeyResponse

NFData GenerateDataKeyResponse

Methods

rnf :: GenerateDataKeyResponse -> ()

type Rep GenerateDataKeyResponse

type Rep GenerateDataKeyResponse = D1 (MetaData "GenerateDataKeyResponse" "Network.AWS.KMS.GenerateDataKey" "amazonka-kms-1.4.4-CcxNJiRfZEW9YOdWrceDWF" False) (C1 (MetaCons "GenerateDataKeyResponse'" PrefixI True) ((:*:) ((:*:) (S1 (MetaSel (Just Symbol "_gdkrsResponseStatus") NoSourceUnpackedness SourceStrict DecidedUnpack) (Rec0 Int)) (S1 (MetaSel (Just Symbol "_gdkrsKeyId") NoSourceUnpackedness SourceStrict DecidedStrict) (Rec0 Text))) ((:*:) (S1 (MetaSel (Just Symbol "_gdkrsPlaintext") NoSourceUnpackedness SourceStrict DecidedStrict) (Rec0 (Sensitive Base64))) (S1 (MetaSel (Just Symbol "_gdkrsCiphertextBlob") NoSourceUnpackedness SourceStrict DecidedStrict) (Rec0 Base64)))))

Response Lenses

gdkrsResponseStatus :: Lens' GenerateDataKeyResponse Int

The response status code.

gdkrsKeyId :: Lens' GenerateDataKeyResponse Text

System generated unique identifier of the key to be used to decrypt the encrypted copy of the data key.

gdkrsPlaintext :: Lens' GenerateDataKeyResponse ByteString

Plaintext that contains the data key. Use this for encryption and decryption and then remove it from memory as soon as possible.

Note: This Lens automatically encodes and decodes Base64 data, despite what the AWS documentation might say. The underlying isomorphism will encode to Base64 representation during serialisation, and decode from Base64 representation during deserialisation. This Lens accepts and returns only raw unencoded data.

gdkrsCiphertextBlob :: Lens' GenerateDataKeyResponse ByteString

Ciphertext that contains the encrypted data key. You must store the blob and enough information to reconstruct the encryption context so that the data encrypted by using the key can later be decrypted. You must provide both the ciphertext blob and the encryption context to the Decrypt API to recover the plaintext data key and decrypt the object.

If you are using the CLI, the value is Base64 encoded. Otherwise, it is not encoded.

Note: This Lens automatically encodes and decodes Base64 data, despite what the AWS documentation might say. The underlying isomorphism will encode to Base64 representation during serialisation, and decode from Base64 representation during deserialisation. This Lens accepts and returns only raw unencoded data.