# 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"
}
```