AWS payment-cryptography: Clarify mac-length units and HMAC behavior for GenerateMac
Summary
Expanded documentation of the mac-length parameter, specifying units per algorithm (hex chars for ISO 9797-1/CMAC/AS2805/DUKPT, bytes for EMV MAC, ignored for HMAC) and clarifying HMAC always returns full hash output.
Security assessment
Clarifies cryptographic MAC generation semantics (truncation and algorithm-specific units), which is security-relevant guidance for correct MAC usage but does not fix a specific vulnerability.
Evidence
+The mac-length parameter has no effect for HMAC. The output MAC is always the full hash output, for example 64 hex characters for `HMAC_SHA256`. To use a shorter MAC, truncate the output in your code.
Diff
diff --git a/payment-cryptography/latest/userguide/generate-mac.md b/payment-cryptography/latest/userguide/generate-mac.md index 80608f8..84304e7 100644 --- a//payment-cryptography/latest/userguide/generate-mac.md +++ b//payment-cryptography/latest/userguide/generate-mac.md @@ -11 +11 @@ HMACISO 9797-1 Algorithm 3CMACDUKPT CMAC -Generate MAC API is used to authenticate card-related data, such as track data from a card magnetic stripe, by using known cryptographic keys to generate a MAC (Message Authentication Code) for data validation between sending and receiving parties. The data used to generate MAC includes message data, secret MAC encryption key and MAC algorithm to generate a unique MAC value for transmission. The receiving party of the MAC will use the same MAC message data, MAC encryption key, and algorithm to reproduce another MAC value for comparison and data authentication. Even if one character of the message changes or the MAC key used for verification is not identical, the resulting MAC value is different. The API supports ISO 9797-1 Algorithm 1 and ISO 9797-1 Algorithm 3 MAC (using a static MAC key and a derived DUKPT key), HMAC and EMV MAC encryption keys for this operation. +Generate MAC API is used to authenticate card-related data, such as track data from a card magnetic stripe, by using known cryptographic keys to generate a MAC (Message Authentication Code) for data validation between sending and receiving parties. The data used to generate MAC includes message data, secret MAC encryption key and MAC algorithm to generate a unique MAC value for transmission. The receiving party of the MAC will use the same MAC message data, MAC encryption key, and algorithm to reproduce another MAC value for comparison and data authentication. Even if one character of the message changes or the MAC key used for verification is not identical, the resulting MAC value is different. The API supports ISO 9797-1 Algorithm 1 and ISO 9797-1 Algorithm 3 MAC (using a static MAC key and a Derived Unique Key Per Transaction (DUKPT) key), HMAC and EMV MAC encryption keys for this operation. @@ -17 +17,12 @@ For more information on all options for this API, see [GenerateMac](https://docs -The optional parameter mac-length allows you to truncate the output value (although this can also be done within your code). A length of 8 refers to 8 bytes or 16 hex characters. +You can use the optional mac-length parameter to truncate the output value. You can also truncate the output in your code. The unit of mac-length depends on the MAC algorithm: + + * ISO 9797-1, CMAC, AS2805, and DUKPT – number of hex characters. For example, a length of 8 refers to 8 hex characters (4 bytes). + + * EMV MAC – number of bytes. + + * HMAC – currently ignored. + + + + +For valid values per algorithm, see [GenerateMac](https://docs.aws.amazon.com/payment-cryptography/latest/DataAPIReference/API_GenerateMac.html). @@ -42 +53 @@ In this example, we will generate a HMAC (Hash-Based Message Authentication Code -The optional mac-length parameter will trim the output MAC, although this can be performed outside the service as well. This value is in bytes, so a value of 16 will expect a hex string of length 32. +The mac-length parameter has no effect for HMAC. The output MAC is always the full hash output, for example 64 hex characters for `HMAC_SHA256`. To use a shorter MAC, truncate the output in your code.