Verify
Verifies a digital signature that was generated by the Sign operation.
Description
The `Verify` operation uses an asymmetric KMS key to verify a digital signature. This operation is the complement of the `Sign` operation. If the signature is valid, the `Verify` operation returns a `SignatureValid` value of `true`. If the signature is not valid, the operation returns a `SignatureValid` value of `false`.
note
- The KMS key must be asymmetric and its `KeyUsage` must be `SIGN_VERIFY`.
- The maximum message size is 4096 bytes.
- The message type and signing algorithm must match those used in the Sign request.
- You can also verify the signature outside of QKMS using the public key.
Request Syntax
POST / HTTP/1.1
Content-Type: application/x-amz-json-1.1
X-Amz-Target: TrentService.Verify
{
"KeyId": "1234abcd-12ab-34cd-56ef-1234567890ab",
"Message": "SGVsbG8gV29ybGQ=",
"MessageType": "RAW",
"Signature": "Base64-encoded signature",
"SigningAlgorithm": "RSASSA_PSS_SHA_256"
}
Values in italics indicate user input and should be replaced with actual values.
Request Parameters
Headers
| Name | Description | Required | Type |
|---|---|---|---|
| Content-Type | Must be "application/x-amz-json-1.1" | Yes | string |
| X-Amz-Target | Must be "TrentService.Verify" | Yes | string |
Request Body
| Name | Description | Required | Type |
|---|---|---|---|
| KeyId | Identifies the asymmetric KMS key that will be used to verify the signature. This must be the ID or ARN of an asymmetric KMS key with a KeyUsage of SIGN_VERIFY. | Yes | string |
| Message | The message that was signed. Specify the same message that was specified in the Sign request. | Yes | blob |
| MessageType | Specifies the type of the message. Valid values are RAW or DIGEST. | No | string |
| Signature | The signature that you want to verify. Pass in the value of the Signature field that was returned by the Sign operation. | Yes | blob |
| SigningAlgorithm | The signing algorithm that was used to sign the message. This must be the same algorithm that was used in the Sign request. | Yes | string |
| GrantTokens | A list of grant tokens. Use grant tokens when your permission to call this operation comes from a new grant that has not yet achieved eventual consistency. | No | array |
Examples
Example 1: Verify a signature using RSA
POST / HTTP/1.1
Content-Type: application/x-amz-json-1.1
X-Amz-Target: TrentService.Verify
{
"KeyId": "1234abcd-12ab-34cd-56ef-1234567890ab",
"Message": "SGVsbG8gV29ybGQ=",
"MessageType": "RAW",
"Signature": "Base64-encoded signature",
"SigningAlgorithm": "RSASSA_PSS_SHA_256"
}
Values in italics indicate user input and should be replaced with actual values.
HTTP/1.1 200 OK
Content-Type: application/x-amz-json-1.1
{
"KeyId": "arn:verenc:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab",
"SignatureValid": true,
"SigningAlgorithm": "RSASSA_PSS_SHA_256"
}
Values in italics indicate variable response values.
Example 2: Verify a signature of a message digest using ECC
POST / HTTP/1.1
Content-Type: application/x-amz-json-1.1
X-Amz-Target: TrentService.Verify
{
"KeyId": "1234abcd-12ab-34cd-56ef-1234567890ab",
"Message": "Base64-encoded message digest",
"MessageType": "DIGEST",
"Signature": "Base64-encoded signature",
"SigningAlgorithm": "ECDSA_SHA_384"
}
Values in italics indicate user input and should be replaced with actual values.
HTTP/1.1 200 OK
Content-Type: application/x-amz-json-1.1
{
"KeyId": "arn:verenc:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab",
"SignatureValid": true,
"SigningAlgorithm": "ECDSA_SHA_384"
}
Values in italics indicate variable response values.
Response Syntax
HTTP/1.1 200 OK
Content-Type: application/x-amz-json-1.1
{
"KeyId": "string",
"SignatureValid": "boolean",
"SigningAlgorithm": "string"
}
Values in italics indicate variable response values.
Response Elements
| Name | Description | Required | Type |
|---|---|---|---|
| KeyId | The Amazon Resource Name (ARN) of the asymmetric KMS key that was used to verify the signature. | No | String |
| SignatureValid | A Boolean value that indicates whether the signature is valid. | No | String |
| SigningAlgorithm | The signing algorithm that was used to verify the signature. | No | String |
Special Errors
| Error Code | Description |
|---|---|
| DependencyTimeoutException | The system timed out while trying to fulfill the request. |
| DisabledException | The request was rejected because the specified KMS key is disabled. |
| InvalidKeyUsageException | The request was rejected because the specified KeyId value cannot be used for this operation. |
| KeyUnavailableException | The request was rejected because the specified KMS key was not available. |
| KMSInternalException | The request was rejected because an internal error occurred. |
| KMSInvalidStateException | The request was rejected because the key state is not valid for this operation. |
| NotFoundException | The request was rejected because the specified entity or resource could not be found. |
| SignatureInvalidException | The request was rejected because the signature verification failed. |
Permissions
To use the `Verify` operation, you must have the following permissions:
- `kms:Verify` on the KMS key (specified in the policy)
Try It Out
Test Verify
Verify a digital signature for a message or message digest.
Coming Soon
This feature is currently under development and will be available soon.