| Copyright | (c) 2013-2021 Brendan Hay |
|---|---|
| License | Mozilla Public License, v. 2.0. |
| Maintainer | Brendan Hay <brendan.g.hay+amazonka@gmail.com> |
| Stability | auto-generated |
| Portability | non-portable (GHC extensions) |
| Safe Haskell | None |
Amazonka.KMS.Decrypt
Description
Decrypts ciphertext that was encrypted by a KMS key using any of the following operations:
- Encrypt
- GenerateDataKey
- GenerateDataKeyPair
- GenerateDataKeyWithoutPlaintext
- GenerateDataKeyPairWithoutPlaintext
You can use this operation to decrypt ciphertext that was encrypted under a symmetric or asymmetric KMS key. When the KMS key is asymmetric, you must specify the KMS key and the encryption algorithm that was used to encrypt the ciphertext. For information about symmetric and asymmetric KMS keys, see Using Symmetric and Asymmetric KMS keys in the Key Management Service Developer Guide.
The Decrypt operation also decrypts ciphertext that was encrypted outside of KMS by the public key in an KMS asymmetric KMS key. However, it cannot decrypt ciphertext produced by other libraries, such as the Amazon Web Services Encryption SDK or Amazon S3 client-side encryption. These libraries return a ciphertext format that is incompatible with KMS.
If the ciphertext was encrypted under a symmetric KMS key, the KeyId
parameter is optional. KMS can get this information from metadata that
it adds to the symmetric ciphertext blob. This feature adds durability
to your implementation by ensuring that authorized users can decrypt
ciphertext decades after it was encrypted, even if they've lost track
of the key ID. However, specifying the KMS key is always recommended as
a best practice. When you use the KeyId parameter to specify a KMS
key, KMS only uses the KMS key you specify. If the ciphertext was
encrypted under a different KMS key, the Decrypt operation fails. This
practice ensures that you use the KMS key that you intend.
Whenever possible, use key policies to give users permission to call the
Decrypt operation on a particular KMS key, instead of using IAM
policies. Otherwise, you might create an IAM user policy that gives the
user Decrypt permission on all KMS keys. This user could decrypt
ciphertext that was encrypted by KMS keys in other accounts if the key
policy for the cross-account KMS key permits it. If you must use an IAM
policy for Decrypt permissions, limit the user to particular KMS keys
or particular trusted accounts. For details, see
Best practices for IAM policies
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 state: Effect on your KMS key in the Key Management Service Developer Guide.
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:Decrypt (key policy)
Related operations:
- Encrypt
- GenerateDataKey
- GenerateDataKeyPair
- ReEncrypt
Synopsis
- data Decrypt = Decrypt' {}
- newDecrypt :: ByteString -> Decrypt
- decrypt_keyId :: Lens' Decrypt (Maybe Text)
- decrypt_encryptionContext :: Lens' Decrypt (Maybe (HashMap Text Text))
- decrypt_grantTokens :: Lens' Decrypt (Maybe [Text])
- decrypt_encryptionAlgorithm :: Lens' Decrypt (Maybe EncryptionAlgorithmSpec)
- decrypt_ciphertextBlob :: Lens' Decrypt ByteString
- data DecryptResponse = DecryptResponse' {}
- newDecryptResponse :: Int -> DecryptResponse
- decryptResponse_keyId :: Lens' DecryptResponse (Maybe Text)
- decryptResponse_plaintext :: Lens' DecryptResponse (Maybe ByteString)
- decryptResponse_encryptionAlgorithm :: Lens' DecryptResponse (Maybe EncryptionAlgorithmSpec)
- decryptResponse_httpStatus :: Lens' DecryptResponse Int
Creating a Request
See: newDecrypt smart constructor.
Constructors
| Decrypt' | |
Fields
| |
Instances
Arguments
| :: ByteString | |
| -> Decrypt |
Create a value of Decrypt with all optional fields omitted.
Use generic-lens or optics to modify other optional fields.
The following record fields are available, with the corresponding lenses provided for backwards compatibility:
$sel:keyId:Decrypt', decrypt_keyId - Specifies the KMS key that KMS uses to decrypt the ciphertext. Enter a
key ID of the KMS key that was used to encrypt the ciphertext.
This parameter is required only when the ciphertext was encrypted under an asymmetric KMS key. If you used a symmetric KMS key, KMS can get the KMS key from metadata that it adds to the symmetric ciphertext blob. However, it is always recommended as a best practice. This practice ensures that you use the KMS key that you intend.
To specify a KMS key, use its key ID, key ARN, alias name, or alias ARN.
When using an alias name, prefix it with "alias/". To specify a KMS
key in a different Amazon Web Services account, you must use the key ARN
or alias ARN.
For example:
- Key ID:
1234abcd-12ab-34cd-56ef-1234567890ab - Key ARN:
arn:aws:kms:us-east-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab - Alias name:
alias/ExampleAlias - Alias ARN:
arn:aws:kms:us-east-2:111122223333:alias/ExampleAlias
To get the key ID and key ARN for a KMS key, use ListKeys or DescribeKey. To get the alias name and alias ARN, use ListAliases.
$sel:encryptionContext:Decrypt', decrypt_encryptionContext - Specifies the encryption context to use when decrypting the data. An
encryption context is valid only for
cryptographic operations
with a symmetric KMS key. The standard asymmetric encryption algorithms
that KMS uses do not support an encryption context.
An encryption context is a collection of non-secret key-value pairs that represents additional authenticated data. When you use an encryption context to encrypt data, you must specify the same (an exact case-sensitive match) encryption context to decrypt the data. An encryption context is optional when encrypting with a symmetric KMS key, but it is highly recommended.
For more information, see Encryption Context in the Key Management Service Developer Guide.
$sel:grantTokens:Decrypt', decrypt_grantTokens - A list of grant tokens.
Use a grant token when your permission to call this operation comes from a new grant that has not yet achieved eventual consistency. For more information, see Grant token and Using a grant token in the Key Management Service Developer Guide.
$sel:encryptionAlgorithm:Decrypt', decrypt_encryptionAlgorithm - Specifies the encryption algorithm that will be used to decrypt the
ciphertext. Specify the same algorithm that was used to encrypt the
data. If you specify a different algorithm, the Decrypt operation
fails.
This parameter is required only when the ciphertext was encrypted under
an asymmetric KMS key. The default value, SYMMETRIC_DEFAULT,
represents the only supported algorithm that is valid for symmetric KMS
keys.
$sel:ciphertextBlob:Decrypt', decrypt_ciphertextBlob - Ciphertext to be decrypted. The blob includes metadata.--
-- Note: This Lens automatically encodes and decodes Base64 data.
-- 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.
Request Lenses
decrypt_keyId :: Lens' Decrypt (Maybe Text) Source #
Specifies the KMS key that KMS uses to decrypt the ciphertext. Enter a key ID of the KMS key that was used to encrypt the ciphertext.
This parameter is required only when the ciphertext was encrypted under an asymmetric KMS key. If you used a symmetric KMS key, KMS can get the KMS key from metadata that it adds to the symmetric ciphertext blob. However, it is always recommended as a best practice. This practice ensures that you use the KMS key that you intend.
To specify a KMS key, use its key ID, key ARN, alias name, or alias ARN.
When using an alias name, prefix it with "alias/". To specify a KMS
key in a different Amazon Web Services account, you must use the key ARN
or alias ARN.
For example:
- Key ID:
1234abcd-12ab-34cd-56ef-1234567890ab - Key ARN:
arn:aws:kms:us-east-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab - Alias name:
alias/ExampleAlias - Alias ARN:
arn:aws:kms:us-east-2:111122223333:alias/ExampleAlias
To get the key ID and key ARN for a KMS key, use ListKeys or DescribeKey. To get the alias name and alias ARN, use ListAliases.
decrypt_encryptionContext :: Lens' Decrypt (Maybe (HashMap Text Text)) Source #
Specifies the encryption context to use when decrypting the data. An encryption context is valid only for cryptographic operations with a symmetric KMS key. The standard asymmetric encryption algorithms that KMS uses do not support an encryption context.
An encryption context is a collection of non-secret key-value pairs that represents additional authenticated data. When you use an encryption context to encrypt data, you must specify the same (an exact case-sensitive match) encryption context to decrypt the data. An encryption context is optional when encrypting with a symmetric KMS key, but it is highly recommended.
For more information, see Encryption Context in the Key Management Service Developer Guide.
decrypt_grantTokens :: Lens' Decrypt (Maybe [Text]) Source #
A list of grant tokens.
Use a grant token when your permission to call this operation comes from a new grant that has not yet achieved eventual consistency. For more information, see Grant token and Using a grant token in the Key Management Service Developer Guide.
decrypt_encryptionAlgorithm :: Lens' Decrypt (Maybe EncryptionAlgorithmSpec) Source #
Specifies the encryption algorithm that will be used to decrypt the
ciphertext. Specify the same algorithm that was used to encrypt the
data. If you specify a different algorithm, the Decrypt operation
fails.
This parameter is required only when the ciphertext was encrypted under
an asymmetric KMS key. The default value, SYMMETRIC_DEFAULT,
represents the only supported algorithm that is valid for symmetric KMS
keys.
decrypt_ciphertextBlob :: Lens' Decrypt ByteString Source #
Ciphertext to be decrypted. The blob includes metadata.--
-- Note: This Lens automatically encodes and decodes Base64 data.
-- 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.
Destructuring the Response
data DecryptResponse Source #
See: newDecryptResponse smart constructor.
Constructors
| DecryptResponse' | |
Fields
| |
Instances
Arguments
| :: Int | |
| -> DecryptResponse |
Create a value of DecryptResponse with all optional fields omitted.
Use generic-lens or optics to modify other optional fields.
The following record fields are available, with the corresponding lenses provided for backwards compatibility:
$sel:keyId:Decrypt', decryptResponse_keyId - The Amazon Resource Name
(key ARN)
of the KMS key that was used to decrypt the ciphertext.
$sel:plaintext:DecryptResponse', decryptResponse_plaintext - Decrypted plaintext data. When you use the HTTP API or the Amazon Web
Services CLI, the value is Base64-encoded. Otherwise, it is not
Base64-encoded.--
-- Note: This Lens automatically encodes and decodes Base64 data.
-- 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.
$sel:encryptionAlgorithm:Decrypt', decryptResponse_encryptionAlgorithm - The encryption algorithm that was used to decrypt the ciphertext.
$sel:httpStatus:DecryptResponse', decryptResponse_httpStatus - The response's http status code.
Response Lenses
decryptResponse_keyId :: Lens' DecryptResponse (Maybe Text) Source #
The Amazon Resource Name (key ARN) of the KMS key that was used to decrypt the ciphertext.
decryptResponse_plaintext :: Lens' DecryptResponse (Maybe ByteString) Source #
Decrypted plaintext data. When you use the HTTP API or the Amazon Web
Services CLI, the value is Base64-encoded. Otherwise, it is not
Base64-encoded.--
-- Note: This Lens automatically encodes and decodes Base64 data.
-- 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.
decryptResponse_encryptionAlgorithm :: Lens' DecryptResponse (Maybe EncryptionAlgorithmSpec) Source #
The encryption algorithm that was used to decrypt the ciphertext.
decryptResponse_httpStatus :: Lens' DecryptResponse Int Source #
The response's http status code.