VerifyMac
Verifies the integrity and authenticity of a message using a message authentication code (MAC).
Description
The `VerifyMac` operation uses a KMS key to verify a message authentication code (MAC). This operation is the complement of the `GenerateMAC` operation. If the MAC is valid, the `VerifyMac` operation returns a `MacValid` value of `true`. If the MAC is not valid, the operation returns a `MacValid` value of `false`.
note
- The KMS key must have a `KeyUsage` value of `GENERATE_VERIFY_MAC`.
- The maximum message size is 4096 bytes.
- The MAC algorithm must match the one used in the GenerateMAC request.
Request Syntax
POST / HTTP/1.1
Content-Type: application/x-amz-json-1.1
X-Amz-Target: TrentService.VerifyMac
{
"KeyId": "1234abcd-12ab-34cd-56ef-1234567890ab",
"Message": "SGVsbG8gV29ybGQ=",
"MacAlgorithm": "HMAC_SHA_256",
"Mac": "Base64-encoded MAC value"
}
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.VerifyMac" | Yes | string |
Request Body
| Name | Description | Required | Type |
|---|---|---|---|
| KeyId | Identifies the KMS key that will be used to verify the MAC. This must be the ID or ARN of a KMS key with a KeyUsage of GENERATE_VERIFY_MAC. | Yes | string |
| Message | The message that was used to generate the MAC. The message can be up to 4096 bytes. | Yes | blob |
| MacAlgorithm | The MAC algorithm that was used to generate the MAC. Valid values are HMAC_SHA_224, HMAC_SHA_256, HMAC_SHA_384, or HMAC_SHA_512. | Yes | string |
| Mac | The MAC to verify. This is the value of the MAC field that was returned by the GenerateMAC operation. | Yes | blob |
| 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 MAC using HMAC-SHA-256
POST / HTTP/1.1
Content-Type: application/x-amz-json-1.1
X-Amz-Target: TrentService.VerifyMac
{
"KeyId": "1234abcd-12ab-34cd-56ef-1234567890ab",
"Message": "SGVsbG8gV29ybGQ=",
"MacAlgorithm": "HMAC_SHA_256",
"Mac": "Base64-encoded MAC value"
}
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",
"MacValid": true,
"MacAlgorithm": "HMAC_SHA_256"
}
Values in italics indicate variable response values.
Example 2: Verify a MAC using HMAC-SHA-512
POST / HTTP/1.1
Content-Type: application/x-amz-json-1.1
X-Amz-Target: TrentService.VerifyMac
{
"KeyId": "1234abcd-12ab-34cd-56ef-1234567890ab",
"Message": "SGVsbG8gV29ybGQ=",
"MacAlgorithm": "HMAC_SHA_512",
"Mac": "Base64-encoded MAC value"
}
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",
"MacValid": true,
"MacAlgorithm": "HMAC_SHA_512"
}
Values in italics indicate variable response values.
Response Syntax
HTTP/1.1 200 OK
Content-Type: application/x-amz-json-1.1
{
"KeyId": "string",
"MacValid": "boolean",
"MacAlgorithm": "string"
}
Values in italics indicate variable response values.
Response Elements
| Name | Description | Required | Type |
|---|---|---|---|
| KeyId | The Amazon Resource Name (ARN) of the KMS key that was used to verify the MAC. | No | String |
| MacValid | A Boolean value that indicates whether the MAC is valid. | No | String |
| MacAlgorithm | The MAC algorithm that was used to verify the MAC. | 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. |
| MacInvalidException | The request was rejected because the MAC verification failed. |
Permissions
To use the `VerifyMac` operation, you must have the following permissions:
- `kms:VerifyMac` on the KMS key (specified in the policy)
Try It Out
Test VerifyMac
Verify a message authentication code (MAC) for a message.
Coming Soon
This feature is currently under development and will be available soon.