| 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.Verify
Description
Verifies a digital signature that was generated by the Sign operation.
Verification confirms that an authorized user signed the message with
the specified KMS key and signing algorithm, and the message hasn't
changed since it was signed. If the signature is verified, the value of
the SignatureValid field in the response is True. If the signature
verification fails, the Verify operation fails with an
KMSInvalidSignatureException exception.
A digital signature is generated by using the private key in an asymmetric KMS key. The signature is verified by using the public key in the same asymmetric KMS key. For information about symmetric and asymmetric KMS keys, see Using Symmetric and Asymmetric KMS keys in the Key Management Service Developer Guide.
To verify a digital signature, you can use the Verify operation.
Specify the same asymmetric KMS key, message, and signing algorithm that
were used to produce the signature.
You can also verify the digital signature by using the public key of the
KMS key outside of KMS. Use the GetPublicKey operation to download the
public key in the asymmetric KMS key and then use the public key to
verify the signature outside of KMS. The advantage of using the Verify
operation is that it is performed within KMS. As a result, it's easy to
call, the operation is performed within the FIPS boundary, it is logged
in CloudTrail, and you can use key policy and IAM policy to determine
who is authorized to use the KMS key to verify signatures.
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:Verify (key policy)
Related operations: Sign
Synopsis
- data Verify = Verify' {}
- newVerify :: Text -> ByteString -> ByteString -> SigningAlgorithmSpec -> Verify
- verify_messageType :: Lens' Verify (Maybe MessageType)
- verify_grantTokens :: Lens' Verify (Maybe [Text])
- verify_keyId :: Lens' Verify Text
- verify_message :: Lens' Verify ByteString
- verify_signature :: Lens' Verify ByteString
- verify_signingAlgorithm :: Lens' Verify SigningAlgorithmSpec
- data VerifyResponse = VerifyResponse' {}
- newVerifyResponse :: Int -> VerifyResponse
- verifyResponse_signingAlgorithm :: Lens' VerifyResponse (Maybe SigningAlgorithmSpec)
- verifyResponse_signatureValid :: Lens' VerifyResponse (Maybe Bool)
- verifyResponse_keyId :: Lens' VerifyResponse (Maybe Text)
- verifyResponse_httpStatus :: Lens' VerifyResponse Int
Creating a Request
See: newVerify smart constructor.
Constructors
| Verify' | |
Fields
| |
Instances
Arguments
| :: Text | |
| -> ByteString | |
| -> ByteString | |
| -> SigningAlgorithmSpec | |
| -> Verify |
Create a value of Verify 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:messageType:Verify', verify_messageType - Tells KMS whether the value of the Message parameter is a message or
message digest. The default value, RAW, indicates a message. To indicate
a message digest, enter DIGEST.
Use the DIGEST value only when the value of the Message parameter is
a message digest. If you use the DIGEST value with a raw message, the
security of the verification operation can be compromised.
$sel:grantTokens:Verify', verify_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:keyId:Verify', verify_keyId - Identifies the asymmetric KMS key that will be used to verify the
signature. This must be the same KMS key that was used to generate the
signature. If you specify a different KMS key, the signature
verification fails.
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:message:Verify', verify_message - Specifies the message that was signed. You can submit a raw message of
up to 4096 bytes, or a hash digest of the message. If you submit a
digest, use the MessageType parameter with a value of DIGEST.
If the message specified here is different from the message that was
signed, the signature verification fails. A message and its hash digest
are considered to be the same message.--
-- 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:signature:Verify', verify_signature - The signature that the Sign operation generated.--
-- 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:signingAlgorithm:Verify', verify_signingAlgorithm - The signing algorithm that was used to sign the message. If you submit a
different algorithm, the signature verification fails.
Request Lenses
verify_messageType :: Lens' Verify (Maybe MessageType) Source #
Tells KMS whether the value of the Message parameter is a message or
message digest. The default value, RAW, indicates a message. To indicate
a message digest, enter DIGEST.
Use the DIGEST value only when the value of the Message parameter is
a message digest. If you use the DIGEST value with a raw message, the
security of the verification operation can be compromised.
verify_grantTokens :: Lens' Verify (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.
verify_keyId :: Lens' Verify Text Source #
Identifies the asymmetric KMS key that will be used to verify the signature. This must be the same KMS key that was used to generate the signature. If you specify a different KMS key, the signature verification fails.
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.
verify_message :: Lens' Verify ByteString Source #
Specifies the message that was signed. You can submit a raw message of
up to 4096 bytes, or a hash digest of the message. If you submit a
digest, use the MessageType parameter with a value of DIGEST.
If the message specified here is different from the message that was
signed, the signature verification fails. A message and its hash digest
are considered to be the same message.--
-- 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.
verify_signature :: Lens' Verify ByteString Source #
The signature that the Sign operation generated.--
-- 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.
verify_signingAlgorithm :: Lens' Verify SigningAlgorithmSpec Source #
The signing algorithm that was used to sign the message. If you submit a different algorithm, the signature verification fails.
Destructuring the Response
data VerifyResponse Source #
See: newVerifyResponse smart constructor.
Constructors
| VerifyResponse' | |
Fields
| |
Instances
Arguments
| :: Int | |
| -> VerifyResponse |
Create a value of VerifyResponse 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:signingAlgorithm:Verify', verifyResponse_signingAlgorithm - The signing algorithm that was used to verify the signature.
$sel:signatureValid:VerifyResponse', verifyResponse_signatureValid - A Boolean value that indicates whether the signature was verified. A
value of True indicates that the Signature was produced by signing
the Message with the specified KeyID and SigningAlgorithm. If the
signature is not verified, the Verify operation fails with a
KMSInvalidSignatureException exception.
$sel:keyId:Verify', verifyResponse_keyId - The Amazon Resource Name
(key ARN)
of the asymmetric KMS key that was used to verify the signature.
$sel:httpStatus:VerifyResponse', verifyResponse_httpStatus - The response's http status code.
Response Lenses
verifyResponse_signingAlgorithm :: Lens' VerifyResponse (Maybe SigningAlgorithmSpec) Source #
The signing algorithm that was used to verify the signature.
verifyResponse_signatureValid :: Lens' VerifyResponse (Maybe Bool) Source #
A Boolean value that indicates whether the signature was verified. A
value of True indicates that the Signature was produced by signing
the Message with the specified KeyID and SigningAlgorithm. If the
signature is not verified, the Verify operation fails with a
KMSInvalidSignatureException exception.
verifyResponse_keyId :: Lens' VerifyResponse (Maybe Text) Source #
The Amazon Resource Name (key ARN) of the asymmetric KMS key that was used to verify the signature.
verifyResponse_httpStatus :: Lens' VerifyResponse Int Source #
The response's http status code.