AWS payment-cryptography documentation change
Summary
Expanded documentation for MAC generation with new algorithm examples (ISO 9797-1 Algorithm 3, CMAC, DUKPT CMAC), added parameter details for mac-length and padding requirements, and included links to API references.
Security assessment
The changes enhance documentation about cryptographic MAC generation features but show no evidence of addressing a specific vulnerability. They provide implementation guidance for security features like HMAC, CMAC, and DUKPT which are authentication mechanisms, improving clarity without patching weaknesses.
Diff
diff --git a/payment-cryptography/latest/userguide/generate-mac.md b/payment-cryptography/latest/userguide/generate-mac.md index c836260ff..2d1499b3f 100644 --- a//payment-cryptography/latest/userguide/generate-mac.md +++ b//payment-cryptography/latest/userguide/generate-mac.md @@ -4,0 +5,2 @@ +HMACISO 9797-1 Algorithm 3CMACDUKPT CMAC + @@ -7 +9 @@ -Generate MAC API is used to authenticate card-related data, such as track data from a card magnetic stripe, by using known data values 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 DUKPT key), HMAC and EMV MAC encryption keys for this operation. @@ -11 +13,28 @@ The input value for `message-data` must be hexBinary data. -In this example, we will generate a HMAC (Hash-Based Message Authentication Code) for card data authentication using HMAC algorithm `HMAC_SHA256` and HMAC encryption key. The key must have KeyUsage set to `TR31_M7_HMAC_KEY` and KeyModesOfUse to `Generate`. The MAC key can either be created with AWS Payment Cryptography by calling [CreateKey](https://docs.aws.amazon.com/payment-cryptography/latest/APIReference/API_CreateKey.html) or imported by calling [ImportKey](https://docs.aws.amazon.com/payment-cryptography/latest/APIReference/API_ImportKey.html). +For more information on all options for this API, see [GenerateMac](https://docs.aws.amazon.com/payment-cryptography/latest/DataAPIReference/API_GenerateMac.html) and [VerifyMac](https://docs.aws.amazon.com/payment-cryptography/latest/DataAPIReference/API_VerifyMac.html). + +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. + +MAC keys can either be created with AWS Payment Cryptography by calling [CreateKey](https://docs.aws.amazon.com/payment-cryptography/latest/APIReference/API_CreateKey.html) or imported by calling [ImportKey](https://docs.aws.amazon.com/payment-cryptography/latest/APIReference/API_ImportKey.html). + +###### Note + +CMAC and HMAC algorithms don't require padding. All others require that the data be padded to the block size of the algorithm, which is multiples of 8 bytes (16 hex characters) for TDES and 16 bytes (32 hex characters) for AES. + +###### Examples + + * Generate HMAC + + * Generate MAC using ISO 9797-1 Algorithm 3 + + * Generate MAC using CMAC + + * Generate MAC using DUKPT CMAC + + + + +## Generate HMAC + +In this example, we will generate a HMAC (Hash-Based Message Authentication Code) for card data authentication using HMAC algorithm `HMAC_SHA256` and HMAC encryption key. The key must have KeyUsage set to `TR31_M7_HMAC_KEY` and KeyModesOfUse to `Generate`. The hash length (e.g. 256) is defined when the key is created and cannot be modified. + +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. @@ -16 +45,2 @@ In this example, we will generate a HMAC (Hash-Based Message Authentication Code - --message-data "3b313038383439303031303733393431353d32343038323236303030373030303f33" + --message-data "3b313038383439303031303733393431353d32343038323236303030373030303f33" \ + --generation-attributes Algorithm=HMAC @@ -22 +52 @@ In this example, we will generate a HMAC (Hash-Based Message Authentication Code - "KeyArn": "arn:aws:payment-cryptography:us-east-2:111122223333:key/qnobl5lghrzunce6, + "KeyArn": "arn:aws:payment-cryptography:us-east-2:111122223333:key/qnobl5lghrzunce6", @@ -27,0 +58,56 @@ In this example, we will generate a HMAC (Hash-Based Message Authentication Code +## Generate MAC using ISO 9797-1 Algorithm 3 + +In this example, we will generate a MAC using ISO 9797-1 Algorithm 3 (Retail MAC) for card data authentication. The key must have KeyUsage set to `TR31_M3_ISO_9797_3_MAC_KEY` and KeyModesOfUse to `Generate`. + + + $ aws payment-cryptography-data generate-mac \ + --key-identifier arn:aws:payment-cryptography:us-east-2:111122223333:key/kwapwa6qaifllw2h \ + --message-data "3b313038383439303031303733393431353d32343038323236303030373030303f33" \ + --generation-attributes="Algorithm=ISO9797_ALGORITHM3" + + + + + { + "KeyArn": "arn:aws:payment-cryptography:us-east-2:111122223333:key/kwapwa6qaifllw2h", + "KeyCheckValue": "2976EA", + "Mac": "A8F7A73DAF87B6D0" + } + + +## Generate MAC using CMAC + +CMAC is most commonly used when the keys are AES but it also supports TDES. In this example, we will generate a MAC using CMAC (ISO 9797-1 Algorithm 5) for card data authentication with an AES key. The key must have KeyUsage set to `TR31_M6_ISO_9797_5_CMAC_KEY` and KeyModesOfUse to `Generate`. + + + $ aws payment-cryptography-data generate-mac \ + --key-identifier arn:aws:payment-cryptography:us-east-2:111122223333:key/tqv5yij6wtxx64pi \ + --message-data "3b313038383439303031303733393431353d32343038323236303030373030303f33" \ + --generation-attributes Algorithm="CMAC" + + + + + { + "KeyArn": "arn:aws:payment-cryptography:us-east-2:111122223333:key/tqv5yij6wtxx64pi", + "KeyCheckValue": "C1EB8F", + "Mac": "1F8C36E63F91E4E93DF7842BF5E2E5F7" + } + + +## Generate MAC using DUKPT CMAC + +In this example, we will generate a MAC using DUKPT (Derived Unique Key Per Transaction) with CMAC for card data authentication. The key must have KeyUsage set to `TR31_B0_BASE_DERIVATION_KEY` and KeyModesOfUse `DeriveKey` set to true. DUKPT keys derive a unique key for each transaction using a Base Derivation Key (BDK) and a Key Serial Number (KSN). + + + $ aws payment-cryptography-data generate-mac --key-identifier arn:aws:payment-cryptography:us-east-2:111122223333:key/qnobl5lghrzunce6 --message-data "3b313038383439303031303733393431353d32343038323236303030373030303f33" --generation-attributes="DukptCmac={KeySerialNumber="932A6E954ABB32DD00000001",Direction=BIDIRECTIONAL}" + + + + + { + "KeyArn": "arn:aws:payment-cryptography:us-east-2:111122223333:key/qnobl5lghrzunce6", + "KeyCheckValue": "C1EB8F" + } + +