Request Syntax URI Request Parameters Request Body Response Syntax Response Elements Errors See Also

GenerateMac

Generates a Message Authentication Code (MAC) cryptogram within AWS Payment Cryptography.

You can use this operation to authenticate card-related data by using known data values to generate MAC for data validation between the sending and receiving parties. This operation uses message data, a secret encryption key and MAC algorithm to generate a unique MAC value for transmission. The receiving party of the MAC must use the same message data, secret encryption key and MAC algorithm to reproduce another MAC value for comparision.

You can use this operation to generate a DUPKT, CMAC, HMAC or EMV MAC by setting generation attributes and algorithm to the associated values. The MAC generation encryption key must have valid values for KeyUsage such as TR31_M7_HMAC_KEY for HMAC generation, and they key must have KeyModesOfUse set to Generate and Verify.

For information about valid keys for this operation, see Understanding key attributes and Key types for specific data operations in the AWS Payment Cryptography User Guide.

Cross-account use: This operation can't be used across different AWS accounts.

Related operations:

VerifyMac

Request Syntax


POST /mac/generate HTTP/1.1
Content-type: application/json

{
   "GenerationAttributes": { ... },
   "KeyIdentifier": "string",
   "MacLength": number,
   "MessageData": "string"
}

URI Request Parameters

The request does not use any URI parameters.

Request Body

The request accepts the following data in JSON format.

GenerationAttributes

The attributes and data values to use for MAC generation within AWS Payment Cryptography.

Type: MacAttributes object

Note: This object is a Union. Only one member of this object can be specified or returned.

Required: Yes

KeyIdentifier

The keyARN of the MAC generation encryption key.

Type: String

Length Constraints: Minimum length of 7. Maximum length of 322.

Pattern: arn:aws:payment-cryptography:[a-z]{2}-[a-z]{1,16}-[0-9]+:[0-9]{12}:(key/[0-9a-zA-Z]{16,64}|alias/[a-zA-Z0-9/_-]+)$|^alias/[a-zA-Z0-9/_-]+

Required: Yes

MacLength

The length of a MAC under generation.

Type: Integer

Valid Range: Minimum value of 4. Maximum value of 16.

Required: No

MessageData

The data for which a MAC is under generation. This value must be hexBinary.

Type: String

Length Constraints: Minimum length of 2. Maximum length of 4096.

Pattern: (?:[0-9a-fA-F][0-9a-fA-F])+

Required: Yes

Response Syntax


HTTP/1.1 200
Content-type: application/json

{
   "KeyArn": "string",
   "KeyCheckValue": "string",
   "Mac": "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.

KeyArn

The keyARN of the encryption key that AWS Payment Cryptography uses for MAC generation.

Type: String

Length Constraints: Minimum length of 70. Maximum length of 150.

Pattern: arn:aws:payment-cryptography:[a-z]{2}-[a-z]{1,16}-[0-9]+:[0-9]{12}:key/[0-9a-zA-Z]{16,64}

KeyCheckValue

The key check value (KCV) of the encryption key. The KCV is used to check if all parties holding a given key have the same key or to detect that a key has changed.

AWS Payment Cryptography computes the KCV according to the CMAC specification.

Type: String

Length Constraints: Minimum length of 4. Maximum length of 16.

Pattern: [0-9a-fA-F]+

Mac

The MAC cryptogram generated within AWS Payment Cryptography.

Type: String

Length Constraints: Minimum length of 4. Maximum length of 128.

Pattern: [0-9a-fA-F]+

Errors

AccessDeniedException

You do not have sufficient access to perform this action.

HTTP Status Code: 403

InternalServerException

The request processing has failed because of an unknown error, exception, or failure.

HTTP Status Code: 500

ResourceNotFoundException

The request was denied due to an invalid resource error.

HTTP Status Code: 404

ThrottlingException

The request was denied due to request throttling.

HTTP Status Code: 429

ValidationException

The request was denied due to an invalid request error.

HTTP Status Code: 400