# Common use cases AWS Payment Cryptography supports many typical payment cryptographic operations. The following topics act as a guide on how to use these operations for typical common use cases. For a list of all commands, please review the AWS Payment Cryptography API. **Topics** + [Issuers and issuer processors](use-cases-issuers.md) + [Acquiring and payment facilitators](use-cases-acquirers.md) # Issuers and issuer processors Issuer use cases typically consist of a few parts. This section is organized by function (such as working with pins). In a production system, the keys are typically scoped to a given card bin and are created during bin setup rather than inline as shown here. **Topics** + [General Functions](use-cases-issuers.generalfunctions.md) + [Network specific functions](use-cases-issuers.networkfunctions.md) # General Functions **Topics** + [Generate a random pin and the associated PVV and then verify the value](use-cases-issuers.generalfunctions.pvv.md) + [Generate or verify a CVV for a given card](use-cases-issuers.generalfunctions.cvv.md) + [Generate or verify a CVV2 for a specific card](use-cases-issuers.generalfunctions.cvv2.md) + [Generate or verify a iCVV for a specific card](use-cases-issuers.generalfunctions.icvv.md) + [Verify an EMV ARQC and generate an ARPC](use-cases-issuers.generalfunctions.arqc.md) + [Generate and Verify an EMV MAC](use-cases-issuers.generalfunctions.emvmac.md) + [Generate EMV MAC for PIN Change](use-cases-issuers.generalfunctions.emvpinchange.md) # Generate a random pin and the associated PVV and then verify the value **Topics** + [Create the key(s)](#use-cases-issuers.generalfunctions.pvv.setup) + [Generate a random pin, generate PVV and return the encrypted PIN and PVV](#use-cases-issuers.generalfunctions.pvv.generate) + [Validate encrypted PIN using PVV method](#use-cases-issuers.generalfunctions.pvv.verify) ## Create the key(s) In order to generate a random pin and the [PVV](terminology.md#terms.pvv), you'll need two keys, a [Pin Verification Key(PVK)](terminology.md#terms.pvk) for generating the PVV and a [Pin Encryption Key](terminology.md#terms.pek) for encrypting the pin. The pin itself is randomly generated securely inside the service and is not related to either key cryptographically. The PGK must be a key of algorithm TDES\$12KEY based on the PVV algorithm itself. A PEK can be TDES\$12KEY, TDES\$13KEY or AES\$1128. In this case, since the PEK is intended for internal use within your system, AES\$1128 would be a good choice. If a PEK is used for interchange with other systems (e.g. card networks, acquirers, ATMs) or are being moved as part of a migration, TDES\$12KEY may be the more appropriate choice for compatibility reasons. ### Create the PEK ``` $ aws payment-cryptography create-key \ --exportable --key-attributes KeyAlgorithm=AES_128,KeyUsage=TR31_P0_PIN_ENCRYPTION_KEY,\ KeyClass=SYMMETRIC_KEY,\ KeyModesOfUse='{Encrypt=true,Decrypt=true,Wrap=true,Unwrap=true}' --tags='[{"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/ivi5ksfsuplneuyt", "KeyAttributes": { "KeyUsage": "TR31_P0_PIN_ENCRYPTION_KEY", "KeyClass": "SYMMETRIC_KEY", "KeyAlgorithm": "AES_128", "KeyModesOfUse": { "Encrypt": false, "Decrypt": false, "Wrap": false, "Unwrap": false, "Generate": true, "Sign": false, "Verify": true, "DeriveKey": false, "NoRestrictions": false } }, "KeyCheckValue": "7CC9E2", "KeyCheckValueAlgorithm": "CMAC", "Enabled": true, "Exportable": true, "KeyState": "CREATE_COMPLETE", "KeyOrigin": "AWS_PAYMENT_CRYPTOGRAPHY", "CreateTimestamp": "2023-06-05T06:41:46.648000-07:00", "UsageStartTimestamp": "2023-06-05T06: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/ivi5ksfsuplneuyt*. You need that in the next step. ### Create the PVK ``` $ aws payment-cryptography create-key --exportable --key-attributes KeyAlgorithm=TDES_2KEY,KeyUsage=TR31_V2_VISA_PIN_VERIFICATION_KEY,KeyClass=SYMMETRIC_KEY,KeyModesOfUse='{Generate=true,Verify=true}' --tags='[{"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/ov6icy4ryas4zcza", "KeyAttributes": { "KeyUsage": "TR31_V2_VISA_PIN_VERIFICATION_KEY", "KeyClass": "SYMMETRIC_KEY", "KeyAlgorithm": "TDES_2KEY", "KeyModesOfUse": { "Encrypt": false, "Decrypt": false, "Wrap": false, "Unwrap": false, "Generate": true, "Sign": false, "Verify": true, "DeriveKey": false, "NoRestrictions": false } }, "KeyCheckValue": "51A200", "KeyCheckValueAlgorithm": "ANSI_X9_24", "Enabled": true, "Exportable": true, "KeyState": "CREATE_COMPLETE", "KeyOrigin": "AWS_PAYMENT_CRYPTOGRAPHY", "CreateTimestamp": "2023-06-05T06:41:46.648000-07:00", "UsageStartTimestamp": "2023-06-05T06: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/ov6icy4ryas4zcza*. You need that in the next step. ## Generate a random pin, generate PVV and return the encrypted PIN and PVV **Example** In this example, we will generate a new (random) 4 digit pin where the outputs will be an encrypted `PIN block` (PinData.PinBlock) and a `PVV` (pinData.VerificationValue). The key inputs are `PAN`, the `Pin Verification Key`(also known as the pin generation key), the `Pin Encryption Key` and the [PIN Block](terminology.md#terms.pinblock) format. This command requires that the key is of type `TR31_V2_VISA_PIN_VERIFICATION_KEY`. ``` $ aws payment-cryptography-data generate-pin-data --generation-key-identifier arn:aws:payment-cryptography:us-east-2:111122223333:key/37y2tsl45p5zjbh2 --encryption-key-identifier arn:aws:payment-cryptography:us-east-2:111122223333:key/ivi5ksfsuplneuyt --primary-account-number 171234567890123 --pin-block-format ISO_FORMAT_0 --generation-attributes VisaPin={PinVerificationKeyIndex=1} ``` ``` { "GenerationKeyArn": "arn:aws:payment-cryptography:us-east-2:111122223333:key/37y2tsl45p5zjbh2", "GenerationKeyCheckValue": "7F2363", "EncryptionKeyArn": "arn:aws:payment-cryptography:us-east-2:111122223333:key/ivi5ksfsuplneuyt", "EncryptionKeyCheckValue": "7CC9E2", "EncryptedPinBlock": "AC17DC148BDA645E", "PinData": { "VerificationValue": "5507" } } ``` ## Validate encrypted PIN using PVV method **Example** In this example, we will validate a PIN for a given PAN. The PIN is typically provided by the cardholder or user during transaction time for validation and is compared against the value on file (the input from the cardholder is provided as an encrypted value from the terminal or other upstream provider). In order to validate this input, the following values will also be provided at runtime - The encrypted pin, the key used to encrypt the input pin (often referred to as an [IWK](terminology.md#terms.iwk)), `PAN` and the value to verify against (either a `PVV` or `PIN offset`). If AWS Payment Cryptography is able to validate the pin, an http/200 is returned. If the pin is not validated, it will return an http/400. ``` $ aws payment-cryptography-data verify-pin-data --verification-key-identifier arn:aws:payment-cryptography:us-east-2:111122223333:key/37y2tsl45p5zjbh2 --encryption-key-identifier arn:aws:payment-cryptography:us-east-2:111122223333:key/ivi5ksfsuplneuyt --primary-account-number 171234567890123 --pin-block-format ISO_FORMAT_0 --verification-attributes VisaPin="{PinVerificationKeyIndex=1,VerificationValue=5507}" --encrypted-pin-block AC17DC148BDA645E ``` ``` { "VerificationKeyArn": "arn:aws:payment-cryptography:us-east-2:111122223333:key/37y2tsl45p5zjbh2", "VerificationKeyCheckValue": "7F2363", "EncryptionKeyArn": "arn:aws:payment-cryptography:us-east-2:111122223333:key/ivi5ksfsuplneuyt", "EncryptionKeyCheckValue": "7CC9E2", } ``` # Generate or verify a CVV for a given card [CVV](terminology.md#terms.cvv) or CVV1 is a value that is traditionally embedded in a cards magnetic stripe. It is not the same as CVV2 (visible to the cardholder and for use for online purchases). The first step is to create a key. For this tutorial, you create a [CVK](terminology.md#terms.cvk) double-length 3DES (2KEY TDES) key. **Note** CVV, CVV2 and iCVV all use similar if not identical algorithms but vary the input data. All use the same key type TR31\$1C0\$1CARD\$1VERIFICATION\$1KEY but it is recommended to use separate keys for each purpose. These can be distinguished using aliases and/or tags as in the example below. ## Create the key ``` $ aws payment-cryptography create-key --exportable --key-attributes KeyAlgorithm=TDES_2KEY,KeyUsage=TR31_C0_CARD_VERIFICATION_KEY,KeyClass=SYMMETRIC_KEY,KeyModesOfUse='{Generate=true,Verify=true}' --tags='[{"Key":"KEY_PURPOSE","Value":"CVV"},{"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/r52o3wbqxyf6qlqr", "KeyAttributes": { "KeyUsage": "TR31_C0_CARD_VERIFICATION_KEY", "KeyClass": "SYMMETRIC_KEY", "KeyAlgorithm": "TDES_2KEY", "KeyModesOfUse": { "Encrypt": false, "Decrypt": false, "Wrap": false, "Unwrap": false, "Generate": true, "Sign": false, "Verify": true, "DeriveKey": false, "NoRestrictions": false } }, "KeyCheckValue": "DE89F9", "KeyCheckValueAlgorithm": "ANSI_X9_24", "Enabled": true, "Exportable": true, "KeyState": "CREATE_COMPLETE", "KeyOrigin": "AWS_PAYMENT_CRYPTOGRAPHY", "CreateTimestamp": "2023-06-05T06:41:46.648000-07:00", "UsageStartTimestamp": "2023-06-05T06: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/r52o3wbqxyf6qlqr*. You need that in the next step. ## Generate a CVV **Example** In this example, we will generate a [CVV](terminology.md#terms.cvv) for a given PAN with inputs of `PAN`,a service code(as defined by ISO/IEC 7813) of 121 and card expiration date. For all available parameters see [CardVerificationValue1](https://docs.aws.amazon.com/payment-cryptography/latest/DataAPIReference/API_CardVerificationValue1.html) in the API reference guide. ``` $ aws payment-cryptography-data generate-card-validation-data --key-identifier arn:aws:payment-cryptography:us-east-2:111122223333:key/r52o3wbqxyf6qlqr --primary-account-number=171234567890123 --generation-attributes CardVerificationValue1='{CardExpiryDate=1127,ServiceCode=121}' ``` ``` { "KeyArn": "arn:aws:payment-cryptography:us-east-2:111122223333:key/r52o3wbqxyf6qlqr", "KeyCheckValue": "DE89F9", "ValidationData": "801" } ``` ## Validate CVV **Example** In this example, we will verify a [CVV](terminology.md#terms.cvv) for a given PAN with inputs of an CVK, `PAN`, a service code of 121, card expiration date and the CVV provided during the transaction to validate. For all available parameters see, [CardVerificationValue1](https://docs.aws.amazon.com/payment-cryptography/latest/DataAPIReference/API_CardVerificationValue1.html) in the API reference guide. CVV is not a user entered value (like CVV2) but is typically embedded on a magstripe. Consideration should be given to whether it should always validate when provided. ``` $ aws payment-cryptography-data verify-card-validation-data --key-identifier arn:aws:payment-cryptography:us-east-2:111122223333:key/r52o3wbqxyf6qlqr --primary-account-number=171234567890123 --verification-attributes CardVerificationValue1='{CardExpiryDate=1127,ServiceCode=121} --validation-data 801 ``` ``` { "KeyArn": "arn:aws:payment-cryptography:us-east-2:111122223333:key/r52o3wbqxyf6qlqr", "KeyCheckValue": "DE89F9", "ValidationData": "801" } ``` # Generate or verify a CVV2 for a specific card [CVV2](terminology.md#terms.cvv2) is a value that is traditionally provided on the back of a card and is used for online purchases. For virtual cards, it might also be displayed on an app or a screen. Cryptographically, it is the same as CVV1 but with a different service code value. ## Create the key ``` $ aws payment-cryptography create-key --exportable --key-attributes KeyAlgorithm=TDES_2KEY,KeyUsage=TR31_C0_CARD_VERIFICATION_KEY,KeyClass=SYMMETRIC_KEY,KeyModesOfUse='{Generate=true,Verify=true}' --tags='[{"Key":"KEY_PURPOSE","Value":"CVV2"},{"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/7f7g4spf3xcklhzu", "KeyAttributes": { "KeyUsage": "TR31_C0_CARD_VERIFICATION_KEY", "KeyClass": "SYMMETRIC_KEY", "KeyAlgorithm": "TDES_2KEY", "KeyModesOfUse": { "Encrypt": false, "Decrypt": false, "Wrap": false, "Unwrap": false, "Generate": true, "Sign": false, "Verify": true, "DeriveKey": false, "NoRestrictions": false } }, "KeyCheckValue": "AEA5CD", "KeyCheckValueAlgorithm": "ANSI_X9_24", "Enabled": true, "Exportable": true, "KeyState": "CREATE_COMPLETE", "KeyOrigin": "AWS_PAYMENT_CRYPTOGRAPHY", "CreateTimestamp": "2023-06-05T06:41:46.648000-07:00", "UsageStartTimestamp": "2023-06-05T06: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/7f7g4spf3xcklhzu*. You need that in the next step. ## Generate a CVV2 **Example** In this example, we will generate a [CVV2](terminology.md#terms.cvv2) for a given PAN with inputs of `PAN` and card expiration date. For all available parameters see [CardVerificationValue2](https://docs.aws.amazon.com/payment-cryptography/latest/DataAPIReference/API_CardVerificationValue2.html) in the API reference guide. ``` $ aws payment-cryptography-data generate-card-validation-data --key-identifier arn:aws:payment-cryptography:us-east-2:111122223333:key/7f7g4spf3xcklhzu --primary-account-number=171234567890123 --generation-attributes CardVerificationValue2='{CardExpiryDate=1127}' ``` ``` { "KeyArn": "arn:aws:payment-cryptography:us-east-2:111122223333:key/7f7g4spf3xcklhzu", "KeyCheckValue": "AEA5CD", "ValidationData": "321" } ``` ## Validate a CVV2 **Example** In this example, we will verify a [CVV2](terminology.md#terms.cvv2) for a given PAN with inputs of an CVK, `PAN`and card expiration date and the CVV provided during the transaction to validate. For all available parameters see, [CardVerificationValue2](https://docs.aws.amazon.com/payment-cryptography/latest/DataAPIReference/API_CardVerificationValue2.html) in the API reference guide. CVV2 and the other inputs are user entered values. As such, it is not necessarily a sign of an issue that this periodically fails to validate. ``` $ aws payment-cryptography-data verify-card-validation-data --key-identifier arn:aws:payment-cryptography:us-east-2:111122223333:key/7f7g4spf3xcklhzu --primary-account-number=171234567890123 --verification-attributes CardVerificationValue2='{CardExpiryDate=1127} --validation-data 321 ``` ``` { "KeyArn": "arn:aws:payment-cryptography:us-east-2:111122223333:key/7f7g4spf3xcklhzu", "KeyCheckValue": "AEA5CD", "ValidationData": "801" } ``` # Generate or verify a iCVV for a specific card [iCVV](terminology.md#terms.icvv) uses the same algorithm as CVV/CVV2 but iCVV is embedded inside a chip card. Its service code is 999. ## Create the key ``` $ aws payment-cryptography create-key --exportable --key-attributes KeyAlgorithm=TDES_2KEY,KeyUsage=TR31_C0_CARD_VERIFICATION_KEY,KeyClass=SYMMETRIC_KEY,KeyModesOfUse='{Generate=true,Verify=true}' --tags='[{"Key":"KEY_PURPOSE","Value":"ICVV"},{"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/c7dsi763r6s7lfp3", "KeyAttributes": { "KeyUsage": "TR31_C0_CARD_VERIFICATION_KEY", "KeyClass": "SYMMETRIC_KEY", "KeyAlgorithm": "TDES_2KEY", "KeyModesOfUse": { "Encrypt": false, "Decrypt": false, "Wrap": false, "Unwrap": false, "Generate": true, "Sign": false, "Verify": true, "DeriveKey": false, "NoRestrictions": false } }, "KeyCheckValue": "1201FB", "KeyCheckValueAlgorithm": "ANSI_X9_24", "Enabled": true, "Exportable": true, "KeyState": "CREATE_COMPLETE", "KeyOrigin": "AWS_PAYMENT_CRYPTOGRAPHY", "CreateTimestamp": "2023-06-05T06:41:46.648000-07:00", "UsageStartTimestamp": "2023-06-05T06: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/c7dsi763r6s7lfp3*. You need that in the next step. ## Generate a iCVV **Example** In this example, we will generate a [iCVV](terminology.md#terms.icvv) for a given PAN with inputs of `PAN`,a service code(as defined by ISO/IEC 7813) of 999 and card expiration date. For all available parameters see [CardVerificationValue1](https://docs.aws.amazon.com/payment-cryptography/latest/DataAPIReference/API_CardVerificationValue1.html) in the API reference guide. ``` $ aws payment-cryptography-data generate-card-validation-data --key-identifier arn:aws:payment-cryptography:us-east-2:111122223333:key/c7dsi763r6s7lfp3 --primary-account-number=171234567890123 --generation-attributes CardVerificationValue1='{CardExpiryDate=1127,ServiceCode=999}' ``` ``` { "KeyArn": "arn:aws:payment-cryptography:us-east-2:111122223333:key/c7dsi763r6s7lfp3", "KeyCheckValue": "1201FB", "ValidationData": "532" } ``` ## Validate iCVV **Example** For validation, the inputs are CVK, `PAN`, a service code of 999, card expiration date and the iCVV provided during the transaction to validate. For all available parameters see, [CardVerificationValue1](https://docs.aws.amazon.com/payment-cryptography/latest/DataAPIReference/API_CardVerificationValue1.html) in the API reference guide. iCVV is not a user entered value (like CVV2) but is typically embedded on an EMV/chip card. Consideration should be given to whether it should always validate when provided. ``` $ aws payment-cryptography-data verify-card-validation-data --key-identifier arn:aws:payment-cryptography:us-east-2:111122223333:key/c7dsi763r6s7lfp3 --primary-account-number=171234567890123 --verification-attributes CardVerificationValue1='{CardExpiryDate=1127,ServiceCode=999} --validation-data 532 ``` ``` { "KeyArn": "arn:aws:payment-cryptography:us-east-2:111122223333:key/c7dsi763r6s7lfp3", "KeyCheckValue": "1201FB", "ValidationData": "532" } ``` # Verify an EMV ARQC and generate an ARPC [ARQC](terminology.md#terms.arqc) (Authorization Request Cryptogram) is a cryptogram generated by an EMV (chip) card and used to validate the transaction details as well as the use of an authorized card. It incorporates data from the card, terminal and the transaction itself. At validation time on the backend, the same inputs are provided to AWS Payment Cryptography, the cryptogram is internally re-created and this is compared against the value provided with the transaction. In this sense, it is similar to a MAC. [EMV 4.4 Book 2](https://www.emvco.com/specifications/?post_id=80377) defines three aspects of this function - key derivation methods (known as common session key - CSK) to generate one-time transaction keys, a minimum payload and methods for generating a response (ARPC). Individual card schemes may specify additional transactional fields to incorporate or the order those fields appear. Other (generally deprecated) scheme specific derivation schemes exist as well and are covered elsewhere in this documentation. For more information, see [VerifyCardValidationData](https://docs.aws.amazon.com/payment-cryptography/latest/DataAPIReference/API_VerifyCardValidationData.html) in the API guide. ## Create the 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":"CVN18"},{"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. ## Generate an ARQC The ARQC is generated exclusively by an EMV card. As such, AWS Payment Cryptography has no facility for generating such a payload. For test purposes, a number of libraries are available online that can generate an appropriate payload as well as known values that are generally provided by the various schemes. ## Validate an ARQC **Example** If AWS Payment Cryptography is able to validate the ARQC, an http/200 is returned. An ARPC (response) can optionally be provided and in included in the response after the ARQC is validated. ``` $ aws payment-cryptography-data verify-auth-request-cryptogram --auth-request-cryptogram 61EDCC708B4C97B4 --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='{"EmvCommon":{"ApplicationTransactionCounter":"000B", "PanSequenceNumber":"01","PrimaryAccountNumber":"9137631040001422"}}' --auth-response-attributes='{"ArpcMethod2":{"CardStatusUpdate":"12345678"}}' ``` ``` { "KeyArn": "arn:aws:payment-cryptography:us-east-2:111122223333:key/pw3s6nl62t5ushfk", "KeyCheckValue": "08D7B4", "AuthResponseValue":"2263AC85" } ``` # Generate and Verify an EMV MAC EMV MAC is MAC using an input of an EMV derived key and then performing a ISO9797-3 (Retail) MAC over the resulting data. EMV MAC is typically used to send commands to an EMV card such as unblock scripts. **Note** AWS Payment Cryptography does not validate the contents of the script. Please consult your scheme or card manual for details on specific commands to include. For more information, see [MacAlgorithmEmv](https://docs.aws.amazon.com/payment-cryptography/latest/DataAPIReference/API_MacAlgorithmEmv.html) in the API guide. **Topics** + [Create the key](#use-cases-issuers.generalfunctions.emvmac.setup) + [Generate an EMV MAC](#use-cases-issuers.generalfunctions.emvmac.generate) ## Create the key ``` $ aws payment-cryptography create-key --exportable --key-attributes KeyAlgorithm=TDES_2KEY,KeyUsage=TR31_E2_EMV_MKEY_INTEGRITY,KeyClass=SYMMETRIC_KEY,KeyModesOfUse='{DeriveKey=true}' --tags='[{"Key":"KEY_PURPOSE","Value":"CVN18"},{"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_E2_EMV_MKEY_INTEGRITY", "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. ## Generate an EMV MAC The typical flow is that a backend process will generate an EMV script (such as card unblock), sign it using this command (which derives a one-time key specific to one particular card) and then return the MAC. Then the command \$1 MAC are sent to the card to be applied. Sending the command to the card is outside the scope of AWS Payment Cryptography. **Note** This command is meant for commands when no encrypted data (such as PIN) is sent. EMV Encrypt can be combined with this command to append encrypted data to the issuer script prior to calling this command Message Data Message data includes the APDU header and command. While this can vary by implementation, this example is the APDU header for unblock (84 24 00 00 08), following by ATC (0007) and then ARQC of the previous transaction (999E57FD0F47CACE). The service does not validate the contents of this field. Session Key Derivation Mode This field defines how the session key is generated. EMV\$1COMMON\$1SESSION\$1KEY is generally used for the new implementations, while EMV2000 \$1 AMEX \$1 MASTERCARD\$1SESSION\$1KEY \$1 VISA may be used as well. MajorKeyDerivationMode EMV Defines Mode A, B or C. Mode A is the most common and AWS Payment Cryptography currently supports mode A or mode B. PAN The account number, typically available in chip field 5A or ISO8583 field 2 but may also be retrieved from the card system. PSN The card sequence number. If not used, enter 00. SessionKeyDerivationValue This is the per session derivation data. It can either be the last ARQC(ApplicationCryptogram) from field 9F26 or the last ATC from 9F36 depending on the derivation scheme. Padding Padding is automatically applied and uses ISO/IEC 9797-1 padding method 2. **Example** ``` $ aws payment-cryptography-data generate-mac --message-data 84240000080007999E57FD0F47CACE --key-identifier arn:aws:payment-cryptography:us-east-2:111122223333:key/pw3s6nl62t5ushfk --message-data 8424000008999E57FD0F47CACE0007 --generation-attributes EmvMac="{MajorKeyDerivationMode=EMV_OPTION_A,PanSequenceNumber='00',PrimaryAccountNumber='2235521304123282',SessionKeyDerivationMode=EMV_COMMON_SESSION_KEY,SessionKeyDerivationValue={ApplicationCryptogram='999E57FD0F47CACE'}}" ``` ``` { "KeyArn": "arn:aws:payment-cryptography:us-east-2:111122223333:key/pw3s6nl62t5ushfk", "KeyCheckValue": "08D7B4", "Mac":"5652EEDF83EA0D84" } ``` # Generate EMV MAC for PIN Change EMV PIN change combines two operations: generating a MAC for an issuer script and encrypting a new PIN for offline PIN change on an EMV chip card. This command is only needed in certain countries where the pin is stored on the chip card (this is common for European countries). This is commonly used when a cardholder needs to change their PIN and the new PIN must be securely transmitted to the card along with a MAC to verify the command's authenticity. **Note** If you only need to send commands to the card but not change the PIN, consider using [ARPC CSU](https://docs.aws.amazon.com/payment-cryptography/latest/DataAPIReference/API_VerifyAuthRequestCryptogram.html) or [Generate EMV MAC](use-cases-issuers.generalfunctions.emvmac.md) commands instead. For more information, see [GenerateMacEmvPinChange](https://docs.aws.amazon.com/payment-cryptography/latest/DataAPIReference/API_GenerateMacEmvPinChange.html) in the API guide. ## Generate EMV MAC and encrypted PIN for PIN change This operation requires two keys: an EMV integrity key (KeyUsage: TR31\$1E2\$1EMV\$1MKEY\$1INTEGRITY) for MAC generation and an EMV confidentiality key (KeyUsage: TR31\$1E4\$1EMV\$1MKEY\$1CONFIDENTIALITY) for PIN encryption. The typical flow is that a backend process will generate an EMV PIN change script, which includes both the MAC for the issuer script and the encrypted new PIN. The command and encrypted PIN are then sent to the card to update the offline PIN. Sending the command to the card is outside the scope of AWS Payment Cryptography. Message Data Message data includes the APDU command for the issuer script. The service does not validate the contents of this field. New Encrypted PIN Block The new encrypted PIN block that will be sent to the card. This must be provided as an encrypted value using a PIN encryption key. New PIN PEK Identifier The key used to encrypt the new PIN before it's passed to this API. Secure Messaging Integrity Key The EMV integrity key (KeyUsage: TR31\$1E2\$1EMV\$1MKEY\$1INTEGRITY) used for MAC generation. Secure Messaging Confidentiality Key The EMV confidentiality key (KeyUsage: TR31\$1E4\$1EMV\$1MKEY\$1CONFIDENTIALITY) used for PIN encryption. MajorKeyDerivationMode EMV defines Mode A, B, or C. Mode A is the most common and AWS Payment Cryptography currently supports mode A or mode B. Mode The encryption mode, typically CBC for PIN change operations. PAN The account number, typically available in chip field 5A or ISO8583 field 2 but may also be retrieved from the card system. PanSequenceNumber The card sequence number. If not used, enter 00. ApplicationCryptogram This is the per session derivation data, typically the last ARQC from field 9F26. PinBlockLengthPosition Specifies where the PIN block length is encoded. Typically set to NONE. Check your card scheme specifications if you're not sure. PinBlockPaddingType Specifies the padding type for the PIN block. Typically set to NO\$1PADDING. Check your card scheme specifications if you're not sure. **Example** ``` $ aws payment-cryptography-data generate-mac-emv-pin-change \ --message-data 00A4040008A000000004101080D80500000001010A04000000000000 \ --new-encrypted-pin-block 67FB27C75580EFE7 \ --new-pin-pek-identifier arn:aws:payment-cryptography:us-east-2:111122223333:key/ivi5ksfsuplneuyt \ --pin-block-format ISO_FORMAT_0 \ --secure-messaging-confidentiality-key-identifier arn:aws:payment-cryptography:us-east-2:111122223333:key/tqv5yij6wtxx64pi \ --secure-messaging-integrity-key-identifier arn:aws:payment-cryptography:us-east-2:111122223333:key/pw3s6nl62t5ushfk \ --derivation-method-attributes 'EmvCommon={ApplicationCryptogram=1234567890123457,MajorKeyDerivationMode=EMV_OPTION_A,Mode=CBC,PanSequenceNumber=00,PinBlockLengthPosition=NONE,PinBlockPaddingType=NO_PADDING,PrimaryAccountNumber=171234567890123}' ``` ``` { "SecureMessagingIntegrityKeyArn": "arn:aws:payment-cryptography:us-east-2:111122223333:key/pw3s6nl62t5ushfk", "SecureMessagingIntegrityKeyCheckValue": "08D7B4", "SecureMessagingConfidentialityKeyArn": "arn:aws:payment-cryptography:us-east-2:111122223333:key/tqv5yij6wtxx64pi", "SecureMessagingConfidentialityKeyCheckValue": "C1EB8F", "Mac": "5652EEDF83EA0D84", "EncryptedPinBlock": "F1A2B3C4D5E6F7A8" } ``` # Network specific functions **Topics** + [Visa specific functions](use-cases-issuers.networkfunctions.visa.md) + [Mastercard specific functions](use-cases-issuers.networkfunctions.mastercard.md) + [American Express specific functions](use-cases-issuers.networkfunctions.amex.md) + [JCB specific functions](use-cases-issuers.networkfunctions.jcb.md) # Visa specific functions **Topics** + [ARQC - CVN18/CVN22](#use-cases-issuers.networkfunctions.visa.cvn18) + [ARQC - CVN10](#use-cases-issuers.networkfunctions.visa.cvn10) + [3DS CAVV V7](#use-cases-issuers.networkfunctions.visa.cavv-v7) + [dCVV (Dynamic Card Verification Value) - CVN17](#use-cases-issuers.networkfunctions.visa.dcvv) ## ARQC - CVN18/CVN22 CVN18 and CVN22 utilize the [CSK method](use-cases-issuers.generalfunctions.arqc.md) 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 - CVN10 CVN10 is an older Visa method for EMV transactions that uses per card key derivation rather than session (per transaction) derivation and also uses a different payload. For information on the payload contents, please contact the scheme for details. ### 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":"CVN10"},{"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 Visa CVN10. 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 D791093C8A921769 \ --key-identifier arn:aws:payment-cryptography:us-east-2:111122223333:key/pw3s6nl62t5ushfk \ --major-key-derivation-mode EMV_OPTION_A \ --transaction-data 00000000170000000000000008400080008000084016051700000000093800000B03011203000000 \ --session-key-derivation-attributes='{"Visa":{"PanSequenceNumber":"01" \ ,"PrimaryAccountNumber":"9137631040001422"}}' ``` ``` { "KeyArn": "arn:aws:payment-cryptography:us-east-2:111122223333:key/pw3s6nl62t5ushfk", "KeyCheckValue": "08D7B4" } ``` ## 3DS CAVV V7 For Visa Secure (3DS) transactions, a CAVV (Cardholder Authentication Verification Value) is generated by the issuer Access Control Server (ACS). The CAVV is evidence that cardholder authentication occurred, is unique for each authentication transaction and is provided by the acquirer in the authorization message. CAVV v7 binds additional data about the transaction to the approval including elements such as merchant name, purchase amount and purchase date. In this way, it is effectively a cryptographic hash of the transaction payload. Cryptographically, CAVV V7 utilizes the CVV algorithm but the inputs have all been changed/repurposed. Please consult appropriate third party/Visa documentation on how to produce the inputs to generate a CAVV V7 payload. ### Create the key ``` $ aws payment-cryptography create-key --exportable --key-attributes KeyAlgorithm=TDES_2KEY,KeyUsage=TR31_C0_CARD_VERIFICATION_KEY,KeyClass=SYMMETRIC_KEY,KeyModesOfUse='{Generate=true,Verify=true}' --tags='[{"Key":"KEY_PURPOSE","Value":"CAVV-V7"},{"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/dnaeyrjgdjjtw6dk", "KeyAttributes": { "KeyUsage": "TR31_C0_CARD_VERIFICATION_KEY", "KeyClass": "SYMMETRIC_KEY", "KeyAlgorithm": "TDES_2KEY", "KeyModesOfUse": { "Encrypt": false, "Decrypt": false, "Wrap": false, "Unwrap": false, "Generate": true, "Sign": false, "Verify": true, "DeriveKey": false, "NoRestrictions": false } }, "KeyCheckValue": "F3FB13", "KeyCheckValueAlgorithm": "ANSI_X9_24", "Enabled": true, "Exportable": true, "KeyState": "CREATE_COMPLETE", "KeyOrigin": "AWS_PAYMENT_CRYPTOGRAPHY", "CreateTimestamp": "2023-06-05T06:41:46.648000-07:00", "UsageStartTimestamp": "2023-06-05T06: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/dnaeyrjgdjjtw6dk*. You need that in the next step. ### Generate a CAVV V7 **Example** In this example, we will generate a CAVV V7 for a given transactions with inputs as specified in the specifications. Note that for this algorithm, fields may be re-used/re-purposed, so it should not be assumed that the field labels match the inputs. For all available parameters see [CardVerificationValue1](https://docs.aws.amazon.com/payment-cryptography/latest/DataAPIReference/API_CardVerificationValue1.html) in the API reference guide. ``` $ aws payment-cryptography-data generate-card-validation-data --key-identifier arn:aws:payment-cryptography:us-east-2:111122223333:key/dnaeyrjgdjjtw6dk --primary-account-number=171234567890123 --generation-attributes CardVerificationValue1='{CardExpiryDate=9431,ServiceCode=431}' ``` ``` { "KeyArn": "arn:aws:payment-cryptography:us-east-2:111122223333:key/dnaeyrjgdjjtw6dk", "KeyCheckValue": "F3FB13", "ValidationData": "491" } ``` ### Validate CAVV V7 **Example** For validation, the inputs are CVK, the computed input values and the CAVV provided during the transaction to validate. For all available parameters see, [CardVerificationValue1](https://docs.aws.amazon.com/payment-cryptography/latest/DataAPIReference/API_CardVerificationValue1.html) in the API reference guide. CAVV is not a user entered value (like CVV2) but is calculated by the issuer ACS. Consideration should be given to whether it should always validate when provided. ``` $ aws payment-cryptography-data verify-card-validation-data --key-identifier arn:aws:payment-cryptography:us-east-2:111122223333:key/dnaeyrjgdjjtw6dk --primary-account-number=171234567890123 --verification-attributes CardVerificationValue1='{CardExpiryDate=9431,ServiceCode=431} --validation-data 491 ``` ``` { "KeyArn": "arn:aws:payment-cryptography:us-east-2:111122223333:key/dnaeyrjgdjjtw6dk", "KeyCheckValue": "F3FB13", "ValidationData": "491" } ``` ## dCVV (Dynamic Card Verification Value) - CVN17 dCVV (dynamic Card Verification Value) is a Visa-specific dynamic cryptogram used for contactless EMV transactions. It is known as early EMV and it provides enhanced security by generating a unique verification value for each transaction. The dCVV uses inputs including the Primary Account Number (PAN), PAN Sequence Number (PSN), Application Transaction Counter (ATC), unpredictable number, and track data. It is still used in some places, but has mostly been replaced by other algorithms like CVN18. For all available parameters see [DynamicCardVerificationValue](https://docs.aws.amazon.com/payment-cryptography/latest/DataAPIReference/API_DynamicCardVerificationValue.html) in the API reference guide. ### Create key ``` $ aws payment-cryptography create-key --exportable --key-attributes KeyAlgorithm=TDES_2KEY,KeyUsage=TR31_E4_EMV_MKEY_DYNAMIC_NUMBERS,KeyClass=SYMMETRIC_KEY,KeyModesOfUse='{Generate=true,Verify=true}' --tags='[{"Key":"KEY_PURPOSE","Value":"DCVV"},{"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/mw7dn3qxvkfh8ztc", "KeyAttributes": { "KeyUsage": "TR31_E4_EMV_MKEY_DYNAMIC_NUMBERS", "KeyClass": "SYMMETRIC_KEY", "KeyAlgorithm": "TDES_2KEY", "KeyModesOfUse": { "Encrypt": false, "Decrypt": false, "Wrap": false, "Unwrap": false, "Generate": true, "Sign": false, "Verify": true, "DeriveKey": false, "NoRestrictions": false } }, "KeyCheckValue": "A8E4D2", "KeyCheckValueAlgorithm": "ANSI_X9_24", "Enabled": true, "Exportable": true, "KeyState": "CREATE_COMPLETE", "KeyOrigin": "AWS_PAYMENT_CRYPTOGRAPHY", "CreateTimestamp": "2025-02-02T11:45:30.648000-08:00", "UsageStartTimestamp": "2025-02-02T11:45:30.626000-08:00" } } ``` Take note of the `KeyArn` that represents the key, for example *arn:aws:payment-cryptography:us-east-2:111122223333:key/mw7dn3qxvkfh8ztc*. You need that in the next step. ### Generate a dCVV **Example** In this example, we will generate a dCVV for a contactless EMV transaction. The inputs include the PAN, PAN Sequence Number, Application Transaction Counter, unpredictable number, and track data. ``` $ aws payment-cryptography-data generate-card-validation-data --key-identifier arn:aws:payment-cryptography:us-east-2:111122223333:key/mw7dn3qxvkfh8ztc \ --primary-account-number=5111112627662122 \ --generation-attributes DynamicCardVerificationValue='{ApplicationTransactionCounter=01,PanSequenceNumber=00,TrackData=12345,UnpredictableNumber=123}' \ --validation-data-length 5 ``` ``` { "KeyArn": "arn:aws:payment-cryptography:us-east-2:111122223333:key/mw7dn3qxvkfh8ztc", "KeyCheckValue": "A8E4D2", "ValidationData": "36667" } ``` ### Validate dCVV **Example** In this example, we will validate a dCVV provided during a transaction. The same inputs used for generation must be provided for validation. 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/mw7dn3qxvkfh8ztc \ --primary-account-number=5111112627662122 \ --validation-data=36667 \ --verification-attributes DynamicCardVerificationValue='{ApplicationTransactionCounter=01,PanSequenceNumber=00,TrackData=12345,UnpredictableNumber=123}' ``` ``` { "KeyArn": "arn:aws:payment-cryptography:us-east-2:111122223333:key/mw7dn3qxvkfh8ztc", "KeyCheckValue": "A8E4D2" } ``` # Mastercard specific functions **Topics** + [DCVC3](#use-cases-issuers.networkfunctions.mastercard.dcvc) + [ARQC - CVN14/CVN15](#use-cases-issuers.networkfunctions.mastercard.cvn14) + [ARQC - CVN12/CVN13](#use-cases-issuers.networkfunctions.mastercard.cvn12) + [3DS SPA2 AAV](#use-cases-issuers.networkfunctions.mastercard.spa2aav) ## 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](use-cases-issuers.generalfunctions.arqc.md) 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(Secure Payment Application) 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. 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" } ``` # American Express specific functions **Topics** + [CSC1](#use-cases-issuers.networkfunctions.amex.csc) + [CSC2](#use-cases-issuers.networkfunctions.amex.csc2) + [iCSC](#use-cases-issuers.networkfunctions.amex.csc3) + [3DS AEVV](#use-cases-issuers.networkfunctions.amex.3dsaevv) ## CSC1 CSC Version 1 is also known as the Classic CSC Algorithm. The service can provide it as a 3,4 or 5 digit number. For all available parameters see [AmexCardSecurityCodeVersion1](https://docs.aws.amazon.com/payment-cryptography/latest/DataAPIReference/API_AmexCardSecurityCodeVersion1.html) in the API reference guide. ### Create key ``` $ aws payment-cryptography create-key --exportable --key-attributes KeyAlgorithm=TDES_2KEY,KeyUsage=TR31_C0_CARD_VERIFICATION_KEY,KeyClass=SYMMETRIC_KEY,KeyModesOfUse='{Generate=true,Verify=true}' --tags='[{"Key":"KEY_PURPOSE","Value":"CSC1"},{"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/esh6hn7pxdtttzgq", "KeyAttributes": { "KeyUsage": "TR31_C0_CARD_VERIFICATION_KEY", "KeyClass": "SYMMETRIC_KEY", "KeyAlgorithm": "TDES_2KEY", "KeyModesOfUse": { "Encrypt": false, "Decrypt": false, "Wrap": false, "Unwrap": false, "Generate": true, "Sign": false, "Verify": true, "DeriveKey": false, "NoRestrictions": false } }, "KeyCheckValue": "8B5077", "KeyCheckValueAlgorithm": "ANSI_X9_24", "Enabled": true, "Exportable": true, "KeyState": "CREATE_COMPLETE", "KeyOrigin": "AWS_PAYMENT_CRYPTOGRAPHY", "CreateTimestamp": "2023-06-05T06:41:46.648000-07:00", "UsageStartTimestamp": "2023-06-05T06: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/esh6hn7pxdtttzgq*. You need that in the next step. ### Generate a CSC1 **Example** ``` $ aws payment-cryptography-data generate-card-validation-data --key-identifier arn:aws:payment-cryptography:us-east-2:111122223333:key/esh6hn7pxdtttzgq --primary-account-number=344131234567848 --generation-attributes AmexCardSecurityCodeVersion1='{CardExpiryDate=1224}' --validation-data-length 4 ``` ``` { "KeyArn": "arn:aws:payment-cryptography:us-east-2:111122223333:key/esh6hn7pxdtttzgq", "KeyCheckValue": "8B5077", "ValidationData": "3938" } ``` ### Validate the CSC1 **Example** In this example, we will validate a CSC1. 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/esh6hn7pxdtttzgq --primary-account-number=344131234567848 --verification-attributes AmexCardSecurityCodeVersion1='{CardExpiryDate=1224}'' --validation-data 3938 ``` ``` { "KeyArn": "arn:aws:payment-cryptography:us-east-2:111122223333:key/esh6hn7pxdtttzgq", "KeyCheckValue": "8B5077" } ``` ## CSC2 CSC Version 2 is also known as the Enhanced CSC Algorithm. The service can provide it as a 3,4 or 5 digit number. The service code for CSC2 is typically 000. For all available parameters see [AmexCardSecurityCodeVersion2](https://docs.aws.amazon.com/payment-cryptography/latest/DataAPIReference/API_AmexCardSecurityCodeVersion2.html) in the API reference guide. ### Create key ``` $ aws payment-cryptography create-key --exportable --key-attributes KeyAlgorithm=TDES_2KEY,KeyUsage=TR31_C0_CARD_VERIFICATION_KEY,KeyClass=SYMMETRIC_KEY,KeyModesOfUse='{Generate=true,Verify=true}' --tags='[{"Key":"KEY_PURPOSE","Value":"CSC2"},{"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/erlm445qvunmvoda", "KeyAttributes": { "KeyUsage": "TR31_C0_CARD_VERIFICATION_KEY", "KeyClass": "SYMMETRIC_KEY", "KeyAlgorithm": "TDES_2KEY", "KeyModesOfUse": { "Encrypt": false, "Decrypt": false, "Wrap": false, "Unwrap": false, "Generate": true, "Sign": false, "Verify": true, "DeriveKey": false, "NoRestrictions": false } }, "KeyCheckValue": "BF1077", "KeyCheckValueAlgorithm": "ANSI_X9_24", "Enabled": true, "Exportable": true, "KeyState": "CREATE_COMPLETE", "KeyOrigin": "AWS_PAYMENT_CRYPTOGRAPHY", "CreateTimestamp": "2023-06-05T06:41:46.648000-07:00", "UsageStartTimestamp": "2023-06-05T06: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/erlm445qvunmvoda*. You need that in the next step. ### Generate a CSC2 In this example, we will generate a CSC2 with a length of 4. CSC can be generated with a length of 3,4 or 5. For American Express, PANs should be 15 digits and start with 34 or 37. Expiration date is typically formatted as YYMM. Service code may vary - review your manual but typical values are 000, 201 or 702 **Example** ``` $ aws payment-cryptography-data generate-card-validation-data --key-identifier arn:aws:payment-cryptography:us-east-2:111122223333:key/erlm445qvunmvoda --primary-account-number=344131234567848 --generation-attributes AmexCardSecurityCodeVersion2='{CardExpiryDate=2412,ServiceCode=000}' --validation-data-length 4 ``` ``` { "KeyArn": "arn:aws:payment-cryptography:us-east-2:111122223333:key/erlm445qvunmvoda", "KeyCheckValue": "BF1077", "ValidationData": "3982" } ``` ### Validate the CSC2 **Example** In this example, we will validate a CSC2. 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/erlm445qvunmvoda --primary-account-number=344131234567848 --verification-attributes AmexCardSecurityCodeVersion2='{CardExpiryDate=2412,ServiceCode=000}' --validation-data 3982 ``` ``` { "KeyArn": "arn:aws:payment-cryptography:us-east-2:111122223333:key/erlm445qvunmvoda", "KeyCheckValue": "BF1077" } ``` ## iCSC iCSC is also known as a static CSC Algorithm and is calculated using CSC Version 2. The service can provide it as a 3,4 or 5 digit number. Use service code 999 to calculate iCSC for a contact card. Use service code 702 to calculate iCSC for a contactless card. For all available parameters see [AmexCardSecurityCodeVersion2](https://docs.aws.amazon.com/payment-cryptography/latest/DataAPIReference/API_AmexCardSecurityCodeVersion2.html) in the API reference guide. ### Create key ``` $ aws payment-cryptography create-key --exportable --key-attributes KeyAlgorithm=TDES_2KEY,KeyUsage=TR31_C0_CARD_VERIFICATION_KEY,KeyClass=SYMMETRIC_KEY,KeyModesOfUse='{Generate=true,Verify=true}' --tags='[{"Key":"KEY_PURPOSE","Value":"CSC1"},{"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-1:111122223333:key/7vrybrbvjcvwtunv", "KeyAttributes": { "KeyUsage": "TR31_C0_CARD_VERIFICATION_KEY" "KeyAlgorithm": "TDES_2KEY", "KeyClass": "SYMMETRIC_KEY", "KeyModesOfUse": { "Decrypt": false, "DeriveKey": false, "Encrypt": false, "Generate": true, "NoRestrictions": false, "Sign": false, "Unwrap": false, "Verify": true, "Wrap": false }, }, "KeyCheckValue": "7121C7", "KeyCheckValueAlgorithm": "ANSI_X9_24", "Enabled": true, "Exportable": true, "KeyOrigin": "AWS_PAYMENT_CRYPTOGRAPHY", "KeyState": "CREATE_COMPLETE", "CreateTimestamp": "2025-01-29T09:19:21.209000-05:00", "UsageStartTimestamp": "2025-01-29T09:19:21.192000-05:00" } } ``` Take note of the `KeyArn` that represents the key, for example *arn:aws:payment-cryptography:us-east-1:111122223333:key/7vrybrbvjcvwtunv*. You need that in the next step. ### Generate a iCSC In this example, we will generate a iCSC with a length of 4, for a contactless card using service code 702. CSC can be generated with a length of 3,4 or 5. For American Express, PANs should be 15 digits and start with 34 or 37. **Example** ``` $ aws payment-cryptography-data generate-card-validation-data --key-identifier arn:aws:payment-cryptography:us-east-1:111122223333:key/7vrybrbvjcvwtunv --primary-account-number=344131234567848 --generation-attributes AmexCardSecurityCodeVersion2='{CardExpiryDate=1224,ServiceCode=702}' --validation-data-length 4 ``` ``` { "KeyArn": arn:aws:payment-cryptography:us-east-1:111122223333:key/7vrybrbvjcvwtunv, "KeyCheckValue": 7121C7, "ValidationData": "2365" } ``` ### Validate the iCSC **Example** In this example, we will validate a iCSC. 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-1:111122223333:key/7vrybrbvjcvwtunv --primary-account-number=344131234567848 --verification-attributes AmexCardSecurityCodeVersion2='{CardExpiryDate=1224,ServiceCode=702}' --validation-data 2365 ``` ``` { "KeyArn": arn:aws:payment-cryptography:us-east-1:111122223333:key/7vrybrbvjcvwtunv, "KeyCheckValue": 7121C7 } ``` ## 3DS AEVV 3DS AEVV (3-D Secure Account Verification Value) is used for American Express 3-D Secure authentication. It uses the same algorithm as CSC2 but with different input parameters. The expiration date field should be populated with an unpredictable (random) number, and the service code consists of the AEVV Authentication Results Code (1 digit) plus the Second Factor Authentication Code (2 digits). The output length should be 3-digits. For all available parameters see [AmexCardSecurityCodeVersion2](https://docs.aws.amazon.com/payment-cryptography/latest/DataAPIReference/API_AmexCardSecurityCodeVersion2.html) in the API reference guide. ### Create key ``` $ aws payment-cryptography create-key --exportable --key-attributes KeyAlgorithm=TDES_2KEY,KeyUsage=TR31_C0_CARD_VERIFICATION_KEY,KeyClass=SYMMETRIC_KEY,KeyModesOfUse='{Generate=true,Verify=true}' --tags='[{"Key":"KEY_PURPOSE","Value":"3DS_AEVV"},{"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/kw8djn5qxvfh3ztm", "KeyAttributes": { "KeyUsage": "TR31_C0_CARD_VERIFICATION_KEY" "KeyAlgorithm": "TDES_2KEY", "KeyClass": "SYMMETRIC_KEY", "KeyModesOfUse": { "Decrypt": false, "DeriveKey": false, "Encrypt": false, "Generate": true, "NoRestrictions": false, "Sign": false, "Unwrap": false, "Verify": true, "Wrap": false }, }, "KeyCheckValue": "8F3A21", "KeyCheckValueAlgorithm": "ANSI_X9_24", "Enabled": true, "Exportable": true, "KeyOrigin": "AWS_PAYMENT_CRYPTOGRAPHY", "KeyState": "CREATE_COMPLETE", "CreateTimestamp": "2025-02-02T10:30:15.209000-05:00", "UsageStartTimestamp": "2025-02-02T10:30:15.192000-05:00" } } ``` Take note of the `KeyArn` that represents the key, for example *arn:aws:payment-cryptography:us-east-2:111122223333:key/kw8djn5qxvfh3ztm*. You need that in the next step. ### Generate a 3DS AEVV In this example, we will generate a 3DS AEVV with a length of 3. The expiration date field contains an unpredictable (random) number (e.g., 1234), and the service code consists of the AEVV Authentication Results Code (1 digit) plus the Second Factor Authentication Code (2 digits), for example 543 where 5 is the Authentication Results Code and 43 is the Second Factor Authentication Code. For American Express, PANs should be 15 digits and start with 34 or 37. **Example** ``` $ aws payment-cryptography-data generate-card-validation-data --key-identifier arn:aws:payment-cryptography:us-east-2:111122223333:key/kw8djn5qxvfh3ztm --primary-account-number=344131234567848 --generation-attributes AmexCardSecurityCodeVersion2='{CardExpiryDate=1234,ServiceCode=543}' --validation-data-length 3 ``` ``` { "KeyArn": arn:aws:payment-cryptography:us-east-2:111122223333:key/kw8djn5qxvfh3ztm, "KeyCheckValue": 8F3A21, "ValidationData": "921" } ``` ### Validate the 3DS AEVV **Example** In this example, we will validate a 3DS AEVV. 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/kw8djn5qxvfh3ztm --primary-account-number=344131234567848 --verification-attributes AmexCardSecurityCodeVersion2='{CardExpiryDate=1234,ServiceCode=543}' --validation-data 921 ``` ``` { "KeyArn": arn:aws:payment-cryptography:us-east-2:111122223333:key/kw8djn5qxvfh3ztm, "KeyCheckValue": 8F3A21 } ``` # JCB specific functions **Topics** + [ARQC - CVN04](#use-cases-issuers.networkfunctions.jcb.cvn04) + [ARQC - CVN01](#use-cases-issuers.networkfunctions.jcb.cvn01) ## ARQC - CVN04 JCB CVN04 utilizes the [CSK method](use-cases-issuers.generalfunctions.arqc.md) of key derivation. Please see the scheme documentation for details on constructing the transaction data field. ## ARQC - CVN01 CVN01 is an older JCB method for EMV transactions that uses per card key derivation rather than session (per transaction) derivation and also uses a different payload. This message is also used by Visa hence the element name has that name even though it's also used for JCB. For information on the payload contents, please contact the scheme documentation. ### 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":"CVN10"},{"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 JCB CVN01. This uses the same options as the Visa method, hence the name of the parameter. 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 D791093C8A921769 \ --key-identifier arn:aws:payment-cryptography:us-east-2:111122223333:key/pw3s6nl62t5ushfk \ --major-key-derivation-mode EMV_OPTION_A \ --transaction-data 00000000170000000000000008400080008000084016051700000000093800000B03011203000000 \ --session-key-derivation-attributes='{"Visa":{"PanSequenceNumber":"01" \ ,"PrimaryAccountNumber":"9137631040001422"}}' ``` ``` { "KeyArn": "arn:aws:payment-cryptography:us-east-2:111122223333:key/pw3s6nl62t5ushfk", "KeyCheckValue": "08D7B4" } ``` # Acquiring and payment facilitators Acquirers, PSPs and Payment Facilators typically have a different set of cryptographic requirements than issuers. Common use cases include: **Data Decryption** Data (especially pan data) may be encrypted by a payment terminal and need to be decrypted by the backend. [Decrypt Data](https://docs.aws.amazon.com/payment-cryptography/latest/DataAPIReference/API_DecryptData.html) and Encrypt Data support a variety of methods including TDES, AES and DUKPT derivation techniques. The AWS Payment Cryptography service itself is also PCI P2PE compliant and is registered as a PCI P2PE decryption component. **TranslatePin** To maintain PCI PIN compliance, acquiring systems shall not have cardholder pins in the clear after they have been entered on a secure device. Therefore, to pass the pin onward from terminal to a downstream system (such as a payment network or issuer), there is a need to re-encrypt it using a different key than the one that the payment terminal used. [Translate Pin](https://docs.aws.amazon.com/payment-cryptography/latest/DataAPIReference/API_TranslatePinData.html) accomplishes that by converting an encrypted pin from one key to another securely with the servicebbb. Using this command, pins can be converted between various schemes such as TDES, AES and DUKPT derivation and pin block formats such as ISO-0, ISO-3 and ISO-4. **VerifyMac** Data from a payment terminal may be MAC'd to ensure that the data hasn't been modified in transit. [Verify Mac](https://docs.aws.amazon.com/payment-cryptography/latest/DataAPIReference/API_VerifyMac.html) and GenerateMac supports a variety of techniques using symmetric keys including TDES, AES and DUKPT derivation techniques for use with ISO-9797-1 algorithm 1, ISO-9797-1 algorithm 3 (Retail MAC) and CMAC techniques. **Topics** + [Using Dynamic Keys](use-cases-acquirers-dynamickeys.md) # Using Dynamic Keys Dynamic Keys allows one-time or limited use keys to be used for cryptographic operations like `[EncryptData](https://docs.aws.amazon.com/payment-cryptography/latest/DataAPIReference/API_EncryptData.html)`. This flow can be utilized when the key material frequently rotates (such as on every card transaction) and there is a desire to avoid importing the key material into the service. Short-lived keys may be utilized as part of [softPOS/Mpoc](terminology.md#terms.mpoc) or other solutions. **Note** This can be used in lieu of the typical flow using AWS Payment Cryptography, where cryptographic keys are either created or imported into the service and keys are specified using a key alias or key arn. The following operations support Dynamic Keys: + EncryptData + DecryptData + ReEncryptData + TranslatePin ## Decrypting Data The following example shows using Dynamic Keys along with the decrypt command. The key identifier in this case is the wrapping key (KEK) that secures the decryption key (that is provided in the wrapped-key parameter in TR-31 format). The wrapped key shall be key purpose of D0 to be used with decrypt command along with a mode of use of B or D. **Example** ``` $ aws payment-cryptography-data decrypt-data --key-identifier arn:aws:payment-cryptography:us-east-2:111122223333:key/ov6icy4ryas4zcza --cipher-text 1234123412341234123412341234123A --decryption-attributes 'Symmetric={Mode=CBC,InitializationVector=1234123412341234}' --wrapped-key WrappedKeyMaterial={"Tr31KeyBlock"="D0112D0TN00E0000B05A6E82D7FC68B95C84306634B0000DA4701BE9BCA318B3A30A400B059FD4A8DE19924A9D3EE459F24FDE680F8E4A40"} ``` ``` { "KeyArn": "arn:aws:payment-cryptography:us-east-2:111122223333:key/ov6icy4ryas4zcza", "KeyCheckValue": "0A3674", "PlainText": "2E138A746A0032023BEF5B85BA5060BA" } ``` ## Translating a pin The following example shows using Dynamic Keys along with the translate pin command to translate from a dynamic key to a semi-static acquirer working key (AWK). The incoming key identifier in this case is the wrapping key (KEK) that is protecting the dynamic pin encryption key (PEK) that is provided in the TR-31 format. The wrapped key shall be key purpose of `P0` along with a mode of use of B or D. The outgoing key identifier is a key of type `TR31_P0_PIN_ENCRYPTION_KEY` and a mode of use of Encrypt=true,Wrap=true **Example** ``` $ aws payment-cryptography-data translate-pin-data --encrypted-pin-block "C7005A4C0FA23E02" --incoming-translation-attributes=IsoFormat0='{PrimaryAccountNumber=171234567890123}' --incoming-key-identifier alias/PARTNER1_KEK --outgoing-key-identifier alias/ACQUIRER_AWK_PEK --outgoing-translation-attributes IsoFormat0="{PrimaryAccountNumber=171234567890123}" --incoming-wrapped-key WrappedKeyMaterial={"Tr31KeyBlock"="D0112P0TB00S0000EB5D8E63076313162B04245C8CE351C956EA4A16CC32EB3FB61DE3FC75C751734B773F5B645943A854C65740738B8304"} ``` ``` { "PinBlock": "2E66192BDA390C6F", "KeyArn": "arn:aws:payment-cryptography:us-east-2:111122223333:key/ov6icy4ryas4zcza", "KeyCheckValue": "0A3674" } ```