GenerateMAC
Generates a message authentication code (MAC) for a message using a KMS key.
Description
The `GenerateMAC` operation uses the specified KMS key and MAC algorithm to generate a message authentication code (MAC). A MAC is a cryptographic value that helps ensure data integrity and authenticity.
note
- The KMS key must have a `KeyUsage` value of `GENERATE_VERIFY_MAC`.
- The maximum message size is 4096 bytes.
- To verify the MAC, use the `VerifyMAC` operation.
Request Syntax
POST / HTTP/1.1
Content-Type: application/x-amz-json-1.1
X-Amz-Target: TrentService.GenerateMAC
{
"KeyId": "1234abcd-12ab-34cd-56ef-1234567890ab",
"Message": "SGVsbG8gV29ybGQ=",
"MacAlgorithm": "HMAC_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.GenerateMAC" | Yes | string |
Request Body
| Name | Description | Required | Type |
|---|---|---|---|
| KeyId | Specifies the KMS key to use for MAC generation. The KMS key must have a KeyUsage of GENERATE_VERIFY_MAC. | Yes | string |
| Message | The message to be authenticated. The message can contain up to 4096 bytes. | Yes | blob |
| MacAlgorithm | The MAC algorithm to use. Valid values are HMAC_SHA_224, HMAC_SHA_256, HMAC_SHA_384, or HMAC_SHA_512. | 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: Generate a MAC using HMAC-SHA-256
POST / HTTP/1.1
Content-Type: application/x-amz-json-1.1
X-Amz-Target: TrentService.GenerateMAC
{
"KeyId": "1234abcd-12ab-34cd-56ef-1234567890ab",
"Message": "SGVsbG8gV29ybGQ=",
"MacAlgorithm": "HMAC_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",
"MAC": "Base64-encoded MAC value",
"MacAlgorithm": "HMAC_SHA_256"
}
Values in italics indicate variable response values.
Example 2: Generate a MAC using HMAC-SHA-512
POST / HTTP/1.1
Content-Type: application/x-amz-json-1.1
X-Amz-Target: TrentService.GenerateMAC
{
"KeyId": "1234abcd-12ab-34cd-56ef-1234567890ab",
"Message": "SGVsbG8gV29ybGQ=",
"MacAlgorithm": "HMAC_SHA_512"
}
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",
"MAC": "Base64-encoded MAC value",
"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",
"MAC": "blob",
"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 used to generate the MAC. | No | String |
| MAC | The generated MAC in base64-encoded format. | No | String |
| MacAlgorithm | The MAC algorithm that was used to generate 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. |
Permissions
To use the `GenerateMAC` operation, you must have the following permissions:
- `kms:GenerateMAC` on the KMS key (specified in the policy)
Try It Out
Test GenerateMAC
Generate a message authentication code (MAC) for a message.
Coming Soon
This feature is currently under development and will be available soon.