Verify
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 asymmetric KMS keys, see Asymmetric KMS keys in the AWS 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 AWS 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 AWS KMS. The
advantage of using the Verify
operation is that it is performed within AWS KMS. As
a result, it's easy to call, the operation is performed within the FIPS boundary, it is logged
in AWS 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 states of AWS KMS keys in the AWS Key Management Service Developer Guide.
Cross-account use: Yes. To perform this operation with a KMS key in a different AWS account, specify
the key ARN or alias ARN in the value of the KeyId
parameter.
Required permissions: kms:Verify (key policy)
Related operations: Sign
Request Syntax
{
"GrantTokens": [ "string
" ],
"KeyId": "string
",
"Message": blob
,
"MessageType": "string
",
"Signature": blob
,
"SigningAlgorithm": "string
"
}
Request Parameters
For information about the parameters that are common to all actions, see Common Parameters.
The request accepts the following data in JSON format.
In the following list, the required parameters are described first.
- 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 AWS 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.
Type: String
Length Constraints: Minimum length of 1. Maximum length of 2048.
Required: Yes
-
- 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 ofDIGEST
.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.
Type: Base64-encoded binary data object
Length Constraints: Minimum length of 1. Maximum length of 4096.
Required: Yes
- Signature
-
The signature that the
Sign
operation generated.Type: Base64-encoded binary data object
Length Constraints: Minimum length of 1. Maximum length of 6144.
Required: Yes
- SigningAlgorithm
-
The signing algorithm that was used to sign the message. If you submit a different algorithm, the signature verification fails.
Type: String
Valid Values:
RSASSA_PSS_SHA_256 | RSASSA_PSS_SHA_384 | RSASSA_PSS_SHA_512 | RSASSA_PKCS1_V1_5_SHA_256 | RSASSA_PKCS1_V1_5_SHA_384 | RSASSA_PKCS1_V1_5_SHA_512 | ECDSA_SHA_256 | ECDSA_SHA_384 | ECDSA_SHA_512
Required: Yes
- 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 AWS Key Management Service Developer Guide.
Type: Array of strings
Array Members: Minimum number of 0 items. Maximum number of 10 items.
Length Constraints: Minimum length of 1. Maximum length of 8192.
Required: No
- MessageType
-
Tells AWS 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, enterDIGEST
.Important Use the
DIGEST
value only when the value of theMessage
parameter is a message digest. If you use theDIGEST
value with a raw message, the security of the verification operation can be compromised.Type: String
Valid Values:
RAW | DIGEST
Required: No
Response Syntax
{
"KeyId": "string",
"SignatureValid": boolean,
"SigningAlgorithm": "string"
}
Response Elements
If the action is successful, the service sends back an HTTP 200 response.
The following data is returned in JSON format by the service.
- KeyId
-
The Amazon Resource Name (key ARN) of the asymmetric KMS key that was used to verify the signature.
Type: String
Length Constraints: Minimum length of 1. Maximum length of 2048.
- SignatureValid
-
A Boolean value that indicates whether the signature was verified. A value of
True
indicates that theSignature
was produced by signing theMessage
with the specifiedKeyID
andSigningAlgorithm.
If the signature is not verified, theVerify
operation fails with aKMSInvalidSignatureException
exception.Type: Boolean
- SigningAlgorithm
-
The signing algorithm that was used to verify the signature.
Type: String
Valid Values:
RSASSA_PSS_SHA_256 | RSASSA_PSS_SHA_384 | RSASSA_PSS_SHA_512 | RSASSA_PKCS1_V1_5_SHA_256 | RSASSA_PKCS1_V1_5_SHA_384 | RSASSA_PKCS1_V1_5_SHA_512 | ECDSA_SHA_256 | ECDSA_SHA_384 | ECDSA_SHA_512
Errors
For information about the errors that are common to all actions, see Common Errors.
- DependencyTimeoutException
-
The system timed out while trying to fulfill the request. The request can be retried.
HTTP Status Code: 500
- DisabledException
-
The request was rejected because the specified KMS key is not enabled.
HTTP Status Code: 400
- InvalidGrantTokenException
-
The request was rejected because the specified grant token is not valid.
HTTP Status Code: 400
- InvalidKeyUsageException
-
The request was rejected for one of the following reasons:
-
The
KeyUsage
value of the KMS key is incompatible with the API operation. -
The encryption algorithm or signing algorithm specified for the operation is incompatible with the type of key material in the KMS key
(KeySpec
).
For encrypting, decrypting, re-encrypting, and generating data keys, the
KeyUsage
must beENCRYPT_DECRYPT
. For signing and verifying messages, theKeyUsage
must beSIGN_VERIFY
. For generating and verifying message authentication codes (MACs), theKeyUsage
must beGENERATE_VERIFY_MAC
. To find theKeyUsage
of a KMS key, use the DescribeKey operation.To find the encryption or signing algorithms supported for a particular KMS key, use the DescribeKey operation.
HTTP Status Code: 400
-
- KeyUnavailableException
-
The request was rejected because the specified KMS key was not available. You can retry the request.
HTTP Status Code: 500
- KMSInternalException
-
The request was rejected because an internal exception occurred. The request can be retried.
HTTP Status Code: 500
- KMSInvalidSignatureException
-
The request was rejected because the signature verification failed. Signature verification fails when it cannot confirm that signature was produced by signing the specified message with the specified KMS key and signing algorithm.
HTTP Status Code: 400
- 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 KMS key, see Key states of AWS KMS keys in the AWS Key Management Service Developer Guide .
HTTP Status Code: 400
- NotFoundException
-
The request was rejected because the specified entity or resource could not be found.
HTTP Status Code: 400
See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following: