Mastercard specific functions - AWS Payment Cryptography
DCVC3 ARQC - CVN14/CVN15ARQC - CVN12/CVN13 3DS SPA2 AAV

Mastercard specific functions

DCVC3

DCVC3 predates EMV CSK and Mastercard CVN12 schemes and represents another approach for utilizing dynamic keys. It is sometimes repurposed for other use cases as well. In this scheme, the inputs are PAN, PSN, Track1/Track2 data, an unpredictable number and transaction counter (ATC).

Create key

$ aws payment-cryptography create-key --exportable --key-attributes KeyAlgorithm=TDES_2KEY,KeyUsage=TR31_E4_EMV_MKEY_DYNAMIC_NUMBERS,KeyClass=SYMMETRIC_KEY,KeyModesOfUse='{DeriveKey=true}' --tags='[{"Key":"KEY_PURPOSE","Value":"DCVC3"},{"Key":"CARD_BIN","Value":"12345678"}]'

The response echoes back the request parameters, including an ARN for subsequent calls as well as a Key Check Value (KCV).

{
            "Key": {
                "KeyArn": "arn:aws:payment-cryptography:us-east-2:111122223333:key/hrh6qgbi3sk4y3wq",
                "KeyAttributes": {
                    "KeyUsage": "TR31_E4_EMV_MKEY_DYNAMIC_NUMBERS",
                    "KeyClass": "SYMMETRIC_KEY",
                    "KeyAlgorithm": "TDES_2KEY",
                    "KeyModesOfUse": {
                        "Encrypt": false,
                        "Decrypt": false,
                        "Wrap": false,
                        "Unwrap": false,
                        "Generate": false,
                        "Sign": false,
                        "Verify": false,
                        "DeriveKey": true,
                        "NoRestrictions": false
                    }
                },
                "KeyCheckValue": "08D7B4",
                "KeyCheckValueAlgorithm": "ANSI_X9_24",
                "Enabled": true,
                "Exportable": true,
                "KeyState": "CREATE_COMPLETE",
                "KeyOrigin": "AWS_PAYMENT_CRYPTOGRAPHY",
                "CreateTimestamp": "2024-03-07T06:41:46.648000-07:00",
                "UsageStartTimestamp": "2024-03-07T06:41:46.626000-07:00"
            }
        }

Take note of the KeyArn that represents the key, for example arn:aws:payment-cryptography:us-east-2:111122223333:key/hrh6qgbi3sk4y3wq. You need that in the next step.

Generate a DCVC3

Example

Although DCVC3 is typically generated by a chip card, it can also be manually generated such as in this example 

$ aws payment-cryptography-data generate-card-validation-data --key-identifier arn:aws:payment-cryptography:us-east-2:111122223333:key/pw3s6nl62t5ushfk --primary-account-number=5413123456784808 --generation-attributes DynamicCardVerificationCode='{ApplicationTransactionCounter=0000,TrackData=5241060000000069D13052020000000000003F,PanSequenceNumber=00,UnpredictableNumber=00000000}''
{
    "KeyArn": "arn:aws:payment-cryptography:us-east-2:111122223333:key/pw3s6nl62t5ushfk",
    "KeyCheckValue": "08D7B4",
    "ValidationData": "865"
  }

Validate the DCVC3

Example

In this example, we will validate an DCVC3. Note that ATC should be provided as a hex number for instance a counter of 11 should be represented as 000B. The service expects a 3 digit DCVC3, so if you have stored a 4(or 5) digit value, simply truncate the left characters until you have 3 digits (for instance 15321 should result in validation-data value of 321).

If AWS Payment Cryptography is able to validate, an http/200 is returned. If the value is not validated, it will return a http/400 response.

$ aws payment-cryptography-data verify-card-validation-data  --key-identifier arn:aws:payment-cryptography:us-east-2:111122223333:key/pw3s6nl62t5ushfk --primary-account-number=5413123456784808 --verification-attributes DynamicCardVerificationCode='{ApplicationTransactionCounter=000B,TrackData=5241060000000069D13052020000000000003F,PanSequenceNumber=00,UnpredictableNumber=00000001}' --validation-data 398
{
    "KeyArn": "arn:aws:payment-cryptography:us-east-2:111122223333:key/pw3s6nl62t5ushfk",
    "KeyCheckValue": "08D7B4"
  }

ARQC - CVN14/CVN15

CVN14 and CVN15 utilize the EMV CSK method of key derivation. The exact transaction data varies between these two methods - please see the scheme documentation for details on constructing the transaction data field.

ARQC - CVN12/CVN13

CVN12 and CVN13 are older Mastercard-specific method for EMV transactions that incorporates an unpredictable number into the per-transaction derivation and also uses a different payload. For information on the payload contents, please contact the scheme.

Create key

$ aws payment-cryptography create-key --exportable --key-attributes KeyAlgorithm=TDES_2KEY,KeyUsage=TR31_E0_EMV_MKEY_APP_CRYPTOGRAMS,KeyClass=SYMMETRIC_KEY,KeyModesOfUse='{DeriveKey=true}' --tags='[{"Key":"KEY_PURPOSE","Value":"CVN12"},{"Key":"CARD_BIN","Value":"12345678"}]'

The response echoes back the request parameters, including an ARN for subsequent calls as well as a Key Check Value (KCV).

{
            "Key": {
                "KeyArn": "arn:aws:payment-cryptography:us-east-2:111122223333:key/pw3s6nl62t5ushfk",
                "KeyAttributes": {
                    "KeyUsage": "TR31_E0_EMV_MKEY_APP_CRYPTOGRAMS",
                    "KeyClass": "SYMMETRIC_KEY",
                    "KeyAlgorithm": "TDES_2KEY",
                    "KeyModesOfUse": {
                        "Encrypt": false,
                        "Decrypt": false,
                        "Wrap": false,
                        "Unwrap": false,
                        "Generate": false,
                        "Sign": false,
                        "Verify": false,
                        "DeriveKey": true,
                        "NoRestrictions": false
                    }
                },
                "KeyCheckValue": "08D7B4",
                "KeyCheckValueAlgorithm": "ANSI_X9_24",
                "Enabled": true,
                "Exportable": true,
                "KeyState": "CREATE_COMPLETE",
                "KeyOrigin": "AWS_PAYMENT_CRYPTOGRAPHY",
                "CreateTimestamp": "2024-03-07T06:41:46.648000-07:00",
                "UsageStartTimestamp": "2024-03-07T06:41:46.626000-07:00"
            }
        }

Take note of the KeyArn that represents the key, for example arn:aws:payment-cryptography:us-east-2:111122223333:key/pw3s6nl62t5ushfk. You need that in the next step.

Validate the ARQC

Example

In this example, we will validate an ARQC generated using Mastercard CVN12.

If AWS Payment Cryptography is able to validate the ARQC, an http/200 is returned. If the arqc is not validated, it will return a http/400 response.

$ aws payment-cryptography-data verify-auth-request-cryptogram --auth-request-cryptogram 31BE5D49F14A5F01 \
  --key-identifier arn:aws:payment-cryptography:us-east-2:111122223333:key/pw3s6nl62t5ushfk \
  --major-key-derivation-mode EMV_OPTION_A \ 
  --transaction-data 00000000170000000000000008400080008000084016051700000000093800000B1F2201030000000000000000000000000000000000000000000000000000008000000000000000 \
  --session-key-derivation-attributes='{"MastercardSessionKey":{"ApplicationTransactionCounter":"000B","PanSequenceNumber":"01","PrimaryAccountNumber":"5413123456784808","UnpredictableNumber":"00000001"}}'
{
    "KeyArn": "arn:aws:payment-cryptography:us-east-2:111122223333:key/pw3s6nl62t5ushfk",
    "KeyCheckValue": "08D7B4"
  }

3DS SPA2 AAV

SPA2 AAV (Account Authentication Value) is used for Mastercard 3DS transactions (also known as Mastercard Idenity Check). It provides cryptographic authentication for e-commerce transactions using HMAC-based MAC generation. The AAV is generated using transaction-specific data and a shared secret key.

Create key

$ aws payment-cryptography create-key --exportable --key-attributes KeyAlgorithm=HMAC_SHA256,KeyUsage=TR31_M7_HMAC_KEY,KeyClass=SYMMETRIC_KEY,KeyModesOfUse='{Generate=true,Verify=true}' --tags='[{"Key":"KEY_PURPOSE","Value":"SPA2_AAV"},{"Key":"CARD_BIN","Value":"12345678"}]'

The response echoes back the request parameters, including an ARN for subsequent calls as well as a Key Check Value (KCV).

{
            "Key": {
                "KeyArn": "arn:aws:payment-cryptography:us-west-2:111122223333:key/q5vjtshsg67cz5gn",
                "KeyAttributes": {
                    "KeyUsage": "TR31_M7_HMAC_KEY",
                    "KeyClass": "SYMMETRIC_KEY",
                    "KeyAlgorithm": "HMAC_SHA256",
                    "KeyModesOfUse": {
                        "Encrypt": false,
                        "Decrypt": false,
                        "Wrap": false,
                        "Unwrap": false,
                        "Generate": true,
                        "Sign": false,
                        "Verify": true,
                        "DeriveKey": false,
                        "NoRestrictions": false
                    }
                },
                "KeyCheckValue": "C661F9",
                "KeyCheckValueAlgorithm": "HMAC",
                "Enabled": true,
                "Exportable": true,
                "KeyState": "CREATE_COMPLETE",
                "KeyOrigin": "AWS_PAYMENT_CRYPTOGRAPHY",
                "CreateTimestamp": "2024-03-07T06:41:46.648000-07:00",
                "UsageStartTimestamp": "2024-03-07T06:41:46.626000-07:00"
            }
        }

Take note of the KeyArn that represents the key, for example arn:aws:payment-cryptography:us-west-2:111122223333:key/q5vjtshsg67cz5gn. You need that in the next step.

Generate SPA2 AAV

Example

In this example, we will generate the Issuer Authentication Value (IAV) component of the SPA2 AAV using HMAC MAC generation. The message data contains the transaction-specific information that will be authenticated. The format of the message data should follow Mastercard's SPA2 specifications and is not covered in this example.

Note

Please review your Mastercard specifications for the formatting to insert the IAV into the AAV value.

$ aws payment-cryptography-data generate-mac --key-identifier arn:aws:payment-cryptography:us-west-2:111122223333:key/q5vjtshsg67cz5gn --message-data "2226400099919520FFFFd8b448be65694fe7b42f836bad396e9d" --generation-attributes Algorithm=HMAC --region us-west-2
{
    "KeyArn": "arn:aws:payment-cryptography:us-west-2:111122223333:key/q5vjtshsg67cz5gn",
    "KeyCheckValue": "C661F9",
    "Mac": "6FB2405E9D8A4C1F7B173F73ADD1A6DC358531CAB0E9994FC5B62012ADDE91FC"
}

Verify SPA2 AAV

Example

In this example, we will verify an SPA2 AAV. The same message data and MAC value are provided for verification.

If AWS Payment Cryptography is able to validate the MAC, an http/200 is returned. If the MAC is not validated, it will return a http/400 response.

$ aws payment-cryptography-data verify-mac --key-identifier arn:aws:payment-cryptography:us-west-2:111122223333:key/q5vjtshsg67cz5gn --message-data "2226400099919520FFFFd8b448be65694fe7b42f836bad396e9d" --mac "6FB2405E9D8A4C1F7B173F73ADD1A6DC358531CAB0E9994FC5B62012ADDE91FC" --verification-attributes Algorithm=HMAC --region us-west-2
{
    "KeyArn": "arn:aws:payment-cryptography:us-west-2:111122223333:key/q5vjtshsg67cz5gn",
    "KeyCheckValue": "C661F9"
}