Copyright | (c) 2013-2015 Brendan Hay |
---|---|
License | Mozilla Public License, v. 2.0. |
Maintainer | Brendan Hay <brendan.g.hay@gmail.com> |
Stability | auto-generated |
Portability | non-portable (GHC extensions) |
Safe Haskell | None |
Language | Haskell2010 |
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.
See: AWS API Reference for GenerateDataKey.
- generateDataKey :: Text -> GenerateDataKey
- data GenerateDataKey
- gdkKeySpec :: Lens' GenerateDataKey (Maybe DataKeySpec)
- gdkEncryptionContext :: Lens' GenerateDataKey (HashMap Text Text)
- gdkNumberOfBytes :: Lens' GenerateDataKey (Maybe Natural)
- gdkGrantTokens :: Lens' GenerateDataKey [Text]
- gdkKeyId :: Lens' GenerateDataKey Text
- generateDataKeyResponse :: Int -> Text -> ByteString -> ByteString -> GenerateDataKeyResponse
- data GenerateDataKeyResponse
- gdkrsStatus :: Lens' GenerateDataKeyResponse Int
- gdkrsKeyId :: Lens' GenerateDataKeyResponse Text
- gdkrsPlaintext :: Lens' GenerateDataKeyResponse ByteString
- gdkrsCiphertextBlob :: Lens' GenerateDataKeyResponse ByteString
Creating a Request
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:
data GenerateDataKey Source
See: generateDataKey
smart constructor.
Request Lenses
gdkKeySpec :: Lens' GenerateDataKey (Maybe DataKeySpec) Source
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) Source
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) Source
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] Source
For more information, see Grant Tokens.
gdkKeyId :: Lens' GenerateDataKey Text Source
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 Source
:: Int | |
-> Text | |
-> ByteString | |
-> ByteString | |
-> 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:
data GenerateDataKeyResponse Source
See: generateDataKeyResponse
smart constructor.
Response Lenses
gdkrsStatus :: Lens' GenerateDataKeyResponse Int Source
The response status code.
gdkrsKeyId :: Lens' GenerateDataKeyResponse Text Source
System generated unique identifier of the key to be used to decrypt the encrypted copy of the data key.
gdkrsPlaintext :: Lens' GenerateDataKeyResponse ByteString Source
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 Source
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.