# Data operations
After you have established an AWS Payment Cryptography key, it can be used to perform cryptographic operations. Different operations perform different types of activity ranging from encryption, hashing as well as domain specific algorithms such as CVV2 generation.
Encrypted data cannot be decrypted without the matching decryption key (the symmetric key or private key depending on the encryption type). Hashing and domain specific algorithms similarly cannot be verified without the symmetric key or public key.
For information on valid key types for specific operations please see [Valid keys for cryptographic operations](crypto-ops-validkeys-ops.md)
**Note**
We recommend using test data when in a non-production environment. Using production keys and data (PAN, BDK ID, etc.) in a non-production environment may impact your compliance scope such as for PCI DSS and PCI P2PE.
**Topics**
+ [Encrypt, Decrypt and Re-encrypt data](crypto-ops.encryptdecrypt.md)
+ [Generate and verify card data](crypto-ops-carddata.md)
+ [Generate, translate and verify PIN data](data-operations.pindata.md)
+ [Verify auth request (ARQC) cryptogram](data-operations.verifyauthrequestcryptogram.md)
+ [Generate and verify MAC](crypto-ops-mac.md)
+ [Valid keys for cryptographic operations](crypto-ops-validkeys-ops.md)
# Encrypt, Decrypt and Re-encrypt data
Encryption and Decryption methods can be used to encrypt or decrypt data using a variety of symmetric and asymmetric techniques including TDES, AES and RSA. These methods also support keys derived using [DUKPT](terminology.md#terms.dukpt) and [EMV](terminology.md#terms.emv) techniques. For use cases where you wish to secure data under a new key without exposing the underlying data, the ReEncrypt command can also be used.
**Note**
When using the encrypt/decrypt functions, all inputs are assumed to be in hexBinary - for instance a value of 1 will be input as 31 (hex) and a lower case t is represented as 74 (hex). All outputs are in hexBinary as well.
For details on all available options, please consult the API Guide for [Encrypt](https://docs.aws.amazon.com/payment-cryptography/latest/DataAPIReference/API_EncryptData.html), [Decrypt](https://docs.aws.amazon.com/payment-cryptography/latest/DataAPIReference/API_DecryptData.html), and [Re-Encrypt](https://docs.aws.amazon.com/payment-cryptography/latest/DataAPIReference/API_ReEncryptData.html).
**Topics**
+ [Encrypt data](encrypt-data.md)
+ [Decrypt data](decrypt-data.md)
# Encrypt data
The `Encrypt Data` API is used to encrypt data using symmetric and asymmetric data encryption keys as well as [DUKPT](terminology.md#terms.dukpt) and [EMV](terminology.md#terms.emv) derived keys. Various algorithms and variations are supported including `TDES`, `RSA` and `AES`.
The primary inputs are the encryption key used to encrypt the data, the plaintext data in hexBinary format to be encrypted and encryption attributes such as initialization vector and mode for block ciphers such as TDES. The plaintext data needs to be in multiples of 8 bytes for `TDES`, 16 bytes for `AES` and the length of the key in the case of `RSA`. Symmetric key inputs (TDES, AES, DUKPT, EMV) should be padded in cases where the input data does not meet these requirements. The following table shows the maximum length of plaintext for each type of key and the padding type that you define in `EncryptionAttributes` for RSA keys.
| Padding type | RSA\$12048 | RSA\$13072 | RSA\$14096 |
| --- | --- | --- | --- |
| OAEP SHA1 | 428 | 684 | 940 |
| OAEP SHA256 | 380 | 636 | 892 |
| OAEP SHA512 | 252 | 508 | 764 |
| PKCS1 | 488 | 744 | 1000 |
| None | 488 | 744 | 1000 |
The primary outputs include the encrypted data as ciphertext in hexBinary format and the checksum value for the encryption key. For details on all available options, please consult the API Guide for [Encrypt](https://docs.aws.amazon.com/payment-cryptography/latest/DataAPIReference/API_EncryptData.html).
**Topics**
+ [Encrypt data using AES symmetric key](#w2aac15c16c11c13)
+ [Encrypt data using DUKPT key](#w2aac15c16c11c15)
+ [Encrypt data using EMV-derived symmetric key](#w2aac15c16c11c17)
+ [Encrypt data using an RSA key](#crypto-ops.encrypt-rsa)
## Encrypt data using AES symmetric key
**Note**
All examples assume the relevant key already exists. Keys can be created using the [CreateKey](create-keys.md) operation or imported using the [ImportKey](keys-import.md) operation.
**Example**
In this example, we will encrypt plaintext data using a symmetric key which has been created using the [CreateKey](create-keys.md) Operation or imported using the [ImportKey](keys-import.md) Operation. For this operation, the key must have KeyModesOfUse set to `Encrypt` and KeyUsage set to `TR31_D0_SYMMETRIC_DATA_ENCRYPTION_KEY`. Please see [Keys for Cryptographic Operations](crypto-ops-validkeys-ops.md) for more options.
```
$ aws payment-cryptography-data encrypt-data --key-identifier arn:aws:payment-cryptography:us-east-2:111122223333:key/tqv5yij6wtxx64pi --plain-text 31323334313233343132333431323334 --encryption-attributes 'Symmetric={Mode=CBC}'
```
```
{
"KeyArn": "arn:aws:payment-cryptography:us-east-2:111122223333:key/tqv5yij6wtxx64pi",
"KeyCheckValue": "71D7AE",
"CipherText": "33612AB9D6929C3A828EB6030082B2BD"
}
```
## Encrypt data using DUKPT key
**Example**
In this example, we will encrypt plaintext data using a [DUKPT](terminology.md#terms.dukpt) key. AWS Payment Cryptography supports `TDES` and `AES` DUKPT keys. For this operation, the key must have KeyModesOfUse set to `DeriveKey` and KeyUsage set to `TR31_B0_BASE_DERIVATION_KEY`. Please see [Keys for Cryptographic Operations](crypto-ops-validkeys-ops.md) for more options.
```
$ aws payment-cryptography-data encrypt-data --key-identifier arn:aws:payment-cryptography:us-east-2:111122223333:key/tqv5yij6wtxx64pi --plain-text 31323334313233343132333431323334 --encryption-attributes 'Dukpt={KeySerialNumber=FFFF9876543210E00001}'
```
```
{
"KeyArn": "arn:aws:payment-cryptography:us-east-2:111122223333:key/tqv5yij6wtxx64pi",
"KeyCheckValue": "71D7AE",
"CipherText": "33612AB9D6929C3A828EB6030082B2BD"
}
```
## Encrypt data using EMV-derived symmetric key
**Example**
In this example, we will encrypt clear text data using an EMV-derived symmetric key which has already been created. You might use a command such as this to send data to an EMV card. For this operation, the key must have KeyModesOfUse set to `Derive` and KeyUsage set to `TR31_E1_EMV_MKEY_CONFIDENTIALITY` or `TR31_E6_EMV_MKEY_OTHER`. Please see [Keys for Cryptographic Operations](crypto-ops-validkeys-ops.md) for more details.
```
$ aws payment-cryptography-data encrypt-data --key-identifier arn:aws:payment-cryptography:us-east-2:111122223333:key/tqv5yij6wtxx64pi --plain-text 33612AB9D6929C3A828EB6030082B2BD --encryption-attributes 'Emv={MajorKeyDerivationMode=EMV_OPTION_A,PanSequenceNumber=27,PrimaryAccountNumber=1000000000000432,SessionDerivationData=02BB000000000000, InitializationVector=1500000000000999,Mode=CBC}'
```
```
{
"KeyArn": "arn:aws:payment-cryptography:us-east-2:111122223333:key/tqv5yij6wtxx64pi",
"KeyCheckValue": "71D7AE",
"CipherText": "33612AB9D6929C3A828EB6030082B2BD"
}
```
## Encrypt data using an RSA key
**Example**
In this example, we will encrypt plaintext data using an [RSA public key](terminology.md#terms.publickey) which has been imported using the [ImportKey](keys-import.md) operation. For this operation, the key must have KeyModesOfUse set to `Encrypt` and KeyUsage set to `TR31_D1_ASYMMETRIC_KEY_FOR_DATA_ENCRYPTION`. Please see [Keys for Cryptographic Operations](crypto-ops-validkeys-ops.md) for more options.
For PKCS \$17 or other padding schemes not currently supported, please apply prior to calling the service and select no padding by omitting the padding indicator * 'Asymmetric=\$1\$1'*
```
$ aws payment-cryptography-data encrypt-data --key-identifier arn:aws:payment-cryptography:us-east-2:111122223333:key/thfezpmsalcfwmsg --plain-text 31323334313233343132333431323334 --encryption-attributes 'Asymmetric={PaddingType=OAEP_SHA256}'
```
```
{
"CipherText": "12DF6A2F64CC566D124900D68E8AFEAA794CA819876E258564D525001D00AC93047A83FB13 \
E73F06329A100704FA484A15A49F06A7A2E55A241D276491AA91F6D2D8590C60CDE57A642BC64A897F4832A3930 \
0FAEC7981102CA0F7370BFBF757F271EF0BB2516007AB111060A9633D1736A9158042D30C5AE11F8C5473EC70F067 \
72590DEA1638E2B41FAE6FB1662258596072B13F8E2F62F5D9FAF92C12BB70F42F2ECDCF56AADF0E311D4118FE3591 \
FB672998CCE9D00FFFE05D2CD154E3120C5443C8CF9131C7A6A6C05F5723B8F5C07A4003A5A6173E1B425E2B5E42AD \
7A2966734309387C9938B029AFB20828ACFC6D00CD1539234A4A8D9B94CDD4F23A",
"KeyArn": "arn:aws:payment-cryptography:us-east-1:111122223333:key/5dza7xqd6soanjtb",
"KeyCheckValue": "FF9DE9CE"
}
```
# Decrypt data
The `Decrypt Data` API is used to decrypt data using symmetric and asymmetric data encryption keys as well as [DUKPT](terminology.md#terms.dukpt) and [EMV](terminology.md#terms.emv) derived keys. Various algorithms and variations are supported including `TDES`, `RSA` and `AES`.
The primary inputs are the decryption key used to decrypt the data, the ciphertext data in hexBinary format to be decrypted and decryption attributes such as initialization vector, mode as block ciphers etc. The primary outputs include the decrypted data as plaintext in hexBinary format and the checksum value for the decryption key. For details on all available options, please consult the API Guide for [Decrypt](https://docs.aws.amazon.com/payment-cryptography/latest/DataAPIReference/API_DecryptData.html).
**Topics**
+ [Decrypt data using AES symmetric key](#w2aac15c16c13b9)
+ [Decrypt data using DUKPT key](#w2aac15c16c13c11)
+ [Decrypt data using EMV-derived symmetric key](#w2aac15c16c13c13)
+ [Decrypt data using an RSA key](#crypto-ops.decrypt-rsa)
## Decrypt data using AES symmetric key
**Example**
In this example, we will decrypt ciphertext data using a symmetric key. This example shows an `AES` key but `TDES_2KEY` and `TDES_3KEY` are also supported. For this operation, the key must have KeyModesOfUse set to `Decrypt` and KeyUsage set to `TR31_D0_SYMMETRIC_DATA_ENCRYPTION_KEY`. Please see [Keys for Cryptographic Operations](crypto-ops-validkeys-ops.md) for more options.
```
$ aws payment-cryptography-data decrypt-data --key-identifier arn:aws:payment-cryptography:us-east-2:111122223333:key/tqv5yij6wtxx64pi --cipher-text 33612AB9D6929C3A828EB6030082B2BD --decryption-attributes 'Symmetric={Mode=CBC}'
```
```
{
"KeyArn": "arn:aws:payment-cryptography:us-east-2:111122223333:key/tqv5yij6wtxx64pi",
"KeyCheckValue": "71D7AE",
"PlainText": "31323334313233343132333431323334"
}
```
## Decrypt data using DUKPT key
**Note**
Using decrypt-data with DUKPT for P2PE transactions may return credit card PAN and other cardholder data to your application that will need to accounted for when determining its PCI DSS scope.
**Example**
In this example, we will decrypt ciphertext data using a [DUKPT](terminology.md#terms.dukpt) key which has been created using the [CreateKey](create-keys.md) Operation or imported using the [ImportKey](keys-import.md) Operation. For this operation, the key must have KeyModesOfUse set to `DeriveKey` and KeyUsage set to `TR31_B0_BASE_DERIVATION_KEY`. Please see [Keys for Cryptographic Operations](crypto-ops-validkeys-ops.md) for more options. When you use `DUKPT`, for `TDES` algorithm, the ciphertext data length must be a multiple of 16 bytes. For `AES` algorithm, the ciphertext data length must be a multiple of 32 bytes.
```
$ aws payment-cryptography-data decrypt-data --key-identifier arn:aws:payment-cryptography:us-east-2:111122223333:key/tqv5yij6wtxx64pi --cipher-text 33612AB9D6929C3A828EB6030082B2BD --decryption-attributes 'Dukpt={KeySerialNumber=FFFF9876543210E00001}'
```
```
{
"KeyArn": "arn:aws:payment-cryptography:us-east-2:111122223333:key/tqv5yij6wtxx64pi",
"KeyCheckValue": "71D7AE",
"PlainText": "31323334313233343132333431323334"
}
```
## Decrypt data using EMV-derived symmetric key
**Example**
In this example, we will decrypt ciphertext data using an EMV-derived symmetric key which has been created using the [CreateKey](create-keys.md) operation or imported using the [ImportKey](keys-import.md) operation. For this operation, the key must have KeyModesOfUse set to `Derive` and KeyUsage set to `TR31_E1_EMV_MKEY_CONFIDENTIALITY` or `TR31_E6_EMV_MKEY_OTHER`. Please see [Keys for Cryptographic Operations](crypto-ops-validkeys-ops.md) for more details.
```
$ aws payment-cryptography-data decrypt-data --key-identifier arn:aws:payment-cryptography:us-east-2:111122223333:key/tqv5yij6wtxx64pi --cipher-text 33612AB9D6929C3A828EB6030082B2BD --decryption-attributes 'Emv={MajorKeyDerivationMode=EMV_OPTION_A,PanSequenceNumber=27,PrimaryAccountNumber=1000000000000432,SessionDerivationData=02BB000000000000, InitializationVector=1500000000000999,Mode=CBC}'
```
```
{
"KeyArn": "arn:aws:payment-cryptography:us-east-2:111122223333:key/tqv5yij6wtxx64pi",
"KeyCheckValue": "71D7AE",
"PlainText": "31323334313233343132333431323334"
}
```
## Decrypt data using an RSA key
**Example**
In this example, we will decrypt ciphertext data using an [RSA key pair](terminology.md#terms.privatekey) which has been created using the [CreateKey](create-keys.md) operation. For this operation, the key must have KeyModesOfUse set to enable `Decrypt` and KeyUsage set to `TR31_D1_ASYMMETRIC_KEY_FOR_DATA_ENCRYPTION`. Please see [Keys for Cryptographic Operations](crypto-ops-validkeys-ops.md) for more options.
For PKCS \$17 or other padding schemes not currently supported, please select no padding by omitting the padding indicator * 'Asymmetric=\$1\$1'* and remove padding subsequent to calling the service.
```
$ aws payment-cryptography-data decrypt-data \
--key-identifier arn:aws:payment-cryptography:us-east-2:111122223333:key/5dza7xqd6soanjtb --cipher-text 8F4C1CAFE7A5DEF9A40BEDE7F2A264635C... \
--decryption-attributes 'Asymmetric={PaddingType=OAEP_SHA256}'
```
```
{
"KeyArn": "arn:aws:payment-cryptography:us-east-1:111122223333:key/5dza7xqd6soanjtb",
"KeyCheckValue": "FF9DE9CE",
"PlainText": "31323334313233343132333431323334"
}
```
# Generate and verify card data
Generate and verify card data incorporates data derived from card data, for instance CVV, CVV2, CVC and DCVV.
**Topics**
+ [Generate card data](generate-card-data.md)
+ [Verify card data](verify-card-data.md)
# Generate card data
The `Generate Card Data` API is used to generate card data using algorithms such as CVV,CVV2 or Dynamic CVV2. To see what keys can be used for this command, please see [Valid keys for cryptographic operations](crypto-ops-validkeys-ops.md) section.
Many cryptographic values such as CVV, CVV2, iCVV, CAVV V7 use the same cryptographic algorithm but vary the input values. For instance [CardVerificationValue1](https://docs.aws.amazon.com/payment-cryptography/latest/DataAPIReference/API_CardVerificationValue1.html) has inputs of ServiceCode, Card Number and Expiration Date. While [CardVerificationValue2](https://docs.aws.amazon.com/payment-cryptography/latest/DataAPIReference/API_CardVerificationValue2.html) only has two of these inputs, this is because for CVV2/CVC2, the ServiceCode is fixed at 000. Similarly, for iCVV the ServiceCode is fixed at 999. Some algorithms may repurpose the existing fields such as CAVV V8 in which case you will need to consult your provider manual for the correct input values.
**Note**
Expiration date must be entered in the same format (such as MMYY vs. YYMM) for generation and validation to produce correct results.
# Generate CVV2
**Example**
In this example, we will generate a CVV2 for a given PAN with inputs of `PAN` and card expiration date. This assumes that you have a card verification key [generated](create-keys.md#cvvkey-example).
```
$ aws payment-cryptography-data generate-card-validation-data --key-identifier arn:aws:payment-cryptography:us-east-2:111122223333:key/tqv5yij6wtxx64pi --primary-account-number=171234567890123 --generation-attributes CardVerificationValue2={CardExpiryDate=0123}
```
```
{
"KeyArn": "arn:aws:payment-cryptography:us-east-2:111122223333:key/tqv5yij6wtxx64pi",
"KeyCheckValue": "CADDA1",
"ValidationData": "801"
}
```
# Generate 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 of 999 and card expiration date. This assumes that you have a card verification key [generated](create-keys.md#cvvkey-example).
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/tqv5yij6wtxx64pi --primary-account-number=171234567890123 --generation-attributes CardVerificationValue1='{CardExpiryDate=1127,ServiceCode=999}'
```
```
{
"KeyArn": "arn:aws:payment-cryptography:us-east-2:111122223333:key/tqv5yij6wtxx64pi",
"KeyCheckValue": "CADDA1",
"ValidationData": "801"
}
```
# Verify card data
`Verify Card Data` is used to verify data that has been created using payment algorithms that rely on encryption principals such as `DISCOVER_DYNAMIC_CARD_VERIFICATION_CODE`.
The input values are typically provided as part of an inbound transaction to an issuer or supporting platform partner. To verify an ARQC cryptogram (used for EMV chips cards), please see [Verify ARQC](data-operations.verifyauthrequestcryptogram.md).
For more information, see [VerifyCardValidationData](https://docs.aws.amazon.com/payment-cryptography/latest/DataAPIReference/API_VerifyCardValidationData.html) in the API guide.
If the value is verified, then the api will return http/200. If the value is not verified, it will return http/400.
# Verify CVV2
**Example**
In this example, we will validate a CVV/CVV2 for a given PAN. The CVV2 is typically provided by the cardholder or user during transaction time for validation. In order to validate their input, the following values will be provided at runtime - [Key to Use for validation (CVK)](create-keys.md#cvvkey-example), `PAN`, card expiration date and CVV2 entered. Card expiration format must match that used in initial value generation.
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 verify-card-validation-data --key-identifier arn:aws:payment-cryptography:us-east-2:111122223333:key/tqv5yij6wtxx64pi --primary-account-number=171234567890123 --verification-attributes CardVerificationValue2={CardExpiryDate=0123} --validation-data 801
```
```
{
"KeyArn": "arn:aws:payment-cryptography:us-east-2:111122223333:key/tqv5yij6wtxx64pi",
"KeyCheckValue": "CADDA1"
}
```
# Verify iCVV
**Example**
In this example, we will verify a [iCVV](terminology.md#terms.icvv) for a given PAN with inputs of [Key to Use for validation (CVK)](create-keys.md#cvvkey-example), `PAN`, a service code of 999, card expiration date and the iCVV provided by the transaction to validate.
iCVV is not a user entered value (like CVV2) but embedded on an EMV card. Consideration should be given to whether it should always validate when provided.
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 verify-card-validation-data --key-identifier arn:aws:payment-cryptography:us-east-2:111122223333:key/tqv5yij6wtxx64pi --primary-account-number=171234567890123 --verification-attributes CardVerificationValue1='{CardExpiryDate=1127,ServiceCode=999} --validation-data 801
```
```
{
"KeyArn": "arn:aws:payment-cryptography:us-east-2:111122223333:key/tqv5yij6wtxx64pi",
"KeyCheckValue": "CADDA1",
"ValidationData": "801"
}
```
# Generate, translate and verify PIN data
PIN data functions allow you to generate random pins, pin verification values (PVV) and validate inbound encrypted pins against PVV or PIN Offsets.
Pin translation allows you to translate a pin from one working key to another without exposing the pin in clear text as specified by PCI PIN Requirement 1.
**Note**
As PIN generation and validation are typically issuer functions and PIN translation is a typical acquirer function, we recommend that you consider least priviledged access and set policies appropriately for your systems use case.
**Topics**
+ [Translate PIN data](translate-pin-data.md)
+ [Generate PIN data](generate-pin-data.md)
+ [Verify PIN data](verify-pin-data.md)
# Translate PIN data
Translate PIN data functions are used for translating encrypted PIN data from one set of keys to another without the encrypted data leaving the HSM. It is used for P2PE encryption where the working keys should change but the processing system either doesn't need to, or is not permitted to, decrypt the data. The primary inputs are the encrypted data, the encryption key used to encrypt the data, the parameters used to generate the input values. The other set of inputs are the requested output parameters such as the key to be used to encrypt the output and the parameters used to create that output. The primary outputs are a newly encrypted dataset as well as the parameters used to generate it.
**Note**
For PCI compliance, the incoming and outgoing PrimaryAccountNumber values must match. Translating a PIN from one PAN to another is not permitted.
**Topics**
+ [PIN from PEK to DUKPT](#crypto-ops-pindata.pektodukpt)
+ [PIN from PEK to PEK](#crypto-ops-pindata.pektopek)
## PIN from PEK to DUKPT
**Example**
In this example, we will translate a PIN from an AES ISO 4 PIN Block using the [DUKPT](terminology.md#terms.dukpt) to PEK TDES encryption using ISO 0 PIN block. This is common where a payment terminal encrypts a pin in ISO 4 and then it may be translated back to TDES for downstream processing if the next connection doesn't yet support AES.
```
$ aws payment-cryptography-data translate-pin-data --encrypted-pin-block "AC17DC148BDA645E" --outgoing-translation-attributes=IsoFormat0='{PrimaryAccountNumber=171234567890123}' --outgoing-key-identifier arn:aws:payment-cryptography:us-east-2:111122223333:key/ivi5ksfsuplneuyt --incoming-key-identifier arn:aws:payment-cryptography:us-east-2:111122223333:key/4pmyquwjs3yj4vwe --incoming-translation-attributes IsoFormat4="{PrimaryAccountNumber=171234567890123}" --incoming-dukpt-attributes KeySerialNumber="FFFF9876543210E00008"
```
```
{
"PinBlock": "1F4209C670E49F83E75CC72E81B787D9",
"KeyArn": "arn:aws:payment-cryptography:us-east-2:111122223333:key/ivi5ksfsuplneuyt",
"KeyCheckValue": "7CC9E2"
}
```
## PIN from PEK to PEK
**Example**
In this example, we translate a PIN encrypted under one PEK (PIN Encryption Key) to another PEK. This is commonly used when routing transactions between different systems or partners that use different encryption keys, while maintaining PCI PIN compliance by keeping the PIN encrypted throughout the process. Both keys use TDES 3KEY encryption in this example, but a variety of options are available including AES ISO-4 to TDES ISO-0, DUKPT to PEK, or AS2805 to PEK.
```
$ aws payment-cryptography-data translate-pin-data --encrypted-pin-block "AC17DC148BDA645E" \
--incoming-translation-attributes IsoFormat0='{PrimaryAccountNumber=171234567890123}' \
--incoming-key-identifier arn:aws:payment-cryptography:us-east-2:111122223333:key/ivi5ksfsuplneuyt \
--outgoing-translation-attributes IsoFormat0='{PrimaryAccountNumber=171234567890123}' \
--outgoing-key-identifier arn:aws:payment-cryptography:us-east-2:111122223333:key/alsuwfxug3pgy6xh
```
```
{
"PinBlock": "E8F2A6C4D1B93E7F",
"KeyArn": "arn:aws:payment-cryptography:us-east-2:111122223333:key/alsuwfxug3pgy6xh",
"KeyCheckValue": "9A325B"
}
```
The output PIN block is now encrypted under the second PEK and can be safely transmitted to the downstream system that holds the corresponding key.
# Generate PIN data
Generate PIN data functions are used for generating PIN-related values, such as [PVV](terminology.md#terms.pvv) and pin block offsets used for validating pin entry by users during transaction or authorization time. This API can also generate a new random pin using various algorithms.
# Generate a random pin and matching Visa PVV
**Example**
In this example, we will generate a new (random) pin where the outputs will be an encrypted `PIN block` (PinData.PinBlock) and a `PVV` (pinData.Offset). The key inputs are `PAN`, the `Pin Verification Key`, the `Pin Encryption Key` and the `PIN block 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"
}
}
```
# Generate a Visa PVV for a known pin
**Example**
In this example, we will generate a PVV for a given (encrypted) pin. An encrypted pin may be received upstream such as from a payment terminal or from a cardholder using the [ user selectable pin flow](https://github.com/aws-samples/samples-for-payment-cryptography-service/tree/main/python_sdk_example/ecdh_flows). The key inputs are `PAN`, the `Pin Verification Key`, the `Pin Encryption Key`, the `Encrypted Pin Block` and the `PIN block format`.
```
$ 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 VisaPinVerificationValue={PinVerificationKeyIndex=1,EncryptedPinBlock=AA584CED31790F37}
```
```
{
"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"
}
}
```
# Generate IBM3624 pin offset for a pin
IBM 3624 PIN Offset also sometimes called the IBM method. This method generates a natural/intermediate PIN using the validation data (typically the PAN) and a PIN Key (PVK). Natural pins are effectively a derived value and being deterministic are very efficient to handle for an issuer because no pin data needs to be stored at a cardholder level. The most obvious con is that this scheme doesn't account for cardholder selectable or random pins. To allow for those types of pins, an offset algorithm was added to the scheme. The offset represents the difference between the user selected(or random) pin and the natural key. The offset value is stored by the card issuer or card processor. At transaction time, the AWS Payment Cryptography service internally recalculates the natural pin and applies the offset to find the pin. It then compares this against the value provided by the transaction authorization.
Several options exist for IBM3624:
+ `Ibm3624NaturalPin` will output the natural pin and an encrypted pin block
+ `Ibm3624PinFromOffset` will generate an encrypted pin block given an offset
+ `Ibm3624RandomPin` will generate a random pin and then the matching offset and encrypted pin block.
+ `Ibm3624PinOffset` generates the pin offset given a user selected pin.
Internal to AWS Payment Cryptography, the following steps are performed:
+ Pad the provided pan to 16 characters. If <16 are provided, pad on the right hand side using the provided padding character.
+ Encrypts the validation data using the PIN generation key.
+ Decimalize the encrypted data using the decimalization table. This maps hexidecimal digits to decimal digits for instance 'A' may map to 9 and 1 may map to 1.
+ Get the first 4 digits from a hexidecimal representation of the output. This is the natural pin.
+ If a user selected or random pin was generated, modulo subtract the natural pin with customer pin. The result is the pin offset.
**Topics**
+ [Example: Generate IBM3624 pin offset for a pin](#generate-ibm3624-random-example)
## Example: Generate IBM3624 pin offset for a pin
In this example, we will generate a new (random) pin where the outputs will be an encrypted `PIN block` (PinData.PinBlock) and an `IBM3624` offset value (pinData.Offset). The inputs are `PAN`, validation data (typically the pan), padding character, the `Pin Verification Key`, the `Pin Encryption Key` and the `PIN block format`.
This command requires that the pin generation key is of type `TR31_V1_IBM3624_PIN_VERIFICATION_KEY` and the encryption key is of type `TR31_P0_PIN_ENCRYPTION_KEY`
**Example**
The following example shows generating a random pin then outputting the encrypted pin block and IBM3624 offset value using Ibm3624RandomPin
```
$ 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 Ibm3624RandomPin="{DecimalizationTable=9876543210654321,PinValidationDataPadCharacter=D,PinValidationData=171234567890123}"
```
```
{
"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": {
"PinOffset": "5507"
}
}
```
# Verify PIN data
Verify PIN data functions are used for verifying whether a pin is correct. This typically involves comparing the pin value previously stored against what was entered by the cardholder at a POI. These functions compare two values without exposing the underlying value of either source.
## 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 key used to encrypt the input pin (this is often an `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",
}
```
## Validate encrypted PIN using PVV method - error bad pin
**Example**
In this example, we will attempt to validate a PIN for a given PAN but it will fail due to the pin being incorrect.
When using SDKs, this appears as \$1"Message":"Pin block verification failed.","Reason":"INVALID\$1PIN"\$1
```
$ 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=9999}" --encrypted-pin-block AC17DC148BDA645E
```
```
An error occurred (VerificationFailedException) when calling the VerifyPinData operation: Pin block verification failed.
```
## Validate encrypted PIN using PVV method - error bad inputs
**Example**
In this example, we will attempt to validate a PIN for a given PAN but it will fail due to bad inputs and the incoming data was not a valid pin. Common causes are: 1/wrong key being used 2/input parameters such as pan or pin block format are incorrect 3/pin block is corrupted.
```
$ aws payment-cryptography-data verify-pin-data --verification-key-identifier arn:aws:payment-cryptography:us-east-2:111122223333:key/37y2tsl45p5zjbh2 --encryption-key-identifier --primary-account-number 171234567890123 --pin-block-format ISO_FORMAT_0 --verification-attributes VisaPin="{PinVerificationKeyIndex=1,VerificationValue=9999}" --encrypted-pin-block AC17DC148BDA645E
```
```
An error occurred (ValidationException) when calling the VerifyPinData operation: Pin block provided is invalid. Please check your input to ensure all field values are correct.
```
# Validate a PIN against previously stored IBM3624 pin offset
In this example, we will validate a cardholder provided PIN against the pin offset stored on file with the card issuer/processor. The inputs are similar to [Generate IBM3624 pin offset for a pin](generate-ibm3624.md) with the additional of the encrypted pin provided by the payment terminal (or other upstream provider such as card network). If the pin matches, the api will return http 200. where the outputs will be an encrypted `PIN block` (PinData.PinBlock) and an `IBM3624` offset value (pinData.Offset).
This command requires that the pin generation key is of type `TR31_V1_IBM3624_PIN_VERIFICATION_KEY` and the encryption key is of type `TR31_P0_PIN_ENCRYPTION_KEY`
**Example**
```
$ 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 Ibm3624RandomPin="{DecimalizationTable=9876543210654321,PinValidationDataPadCharacter=D,PinValidationData=171234567890123}"
```
```
{
"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": {
"PinOffset": "5507"
}
}
```
# Verify auth request (ARQC) cryptogram
The verify auth request cryptogram API is used for verifying [ARQC](terminology.md#terms.arqc). The generation of the ARQC is outside of the scope of the AWS Payment Cryptography and is typically performed on an EMV Chip Card (or digital equivalent such as mobile wallet) during transaction authorization time. An ARQC is unique to each transactions and is intended to cryptographically show both the validity of the card as well as to ensure that the transaction data exactly matches the current (expected) transaction.
AWS Payment Cryptography provides a variety of options for validating ARQC and generating optional ARPC values including those defined in [EMV 4.4 Book 2](https://www.emvco.com/specifications/?post_id=80377) and other schemes used by Visa and Mastercard. For a full list of all available options, please see the VerifyCardValidationData section in the [API Guide](https://docs.aws.amazon.com/payment-cryptography/latest/DataAPIReference/API_VerifyCardValidationData.html).
ARQC cryptograms typically require the following inputs (although this may vary by implementation):
+ [PAN](terminology.md#terms.pan) - Specified in the PrimaryAccountNumber field
+ [PAN Sequence Number (PSN)](terminology.md#terms.psn) - specified in the PanSequenceNumber field
+ Key Derivation Method such as Common Session Key (CSK) - Specified in the SessionKeyDerivationAttributes
+ Master Key Derivation Mode (such as EMV Option A) - Specified in the MajorKeyDerivationMode
+ Transaction data - a string of various transaction, terminal and card data such as Amount and Date - specified in the TransactionData field
+ [Issuer Master Key](terminology.md#terms.imk) - the master key used to derive the cryptogram (AC) key used to protect individual transactions and specified in the KeyIdentifier field
**Topics**
+ [Building transaction data](#w2aac15c25c13)
+ [Transaction data padding](#w2aac15c25c15)
+ [Examples](#w2aac15c25c17)
## Building transaction data
The exact content (and order) of the transaction data field varies by implementation and network scheme but the minimum recommended fields (and concatenation sequence) is defined in [EMV 4.4 Book 2 Section 8.1.1 - Data Selection](https://www.emvco.com/specifications/?post_id=80377). If the first three fields are amount (17.00), other amount (0.00) and country of purchase, that would result in the transaction data beginning as follows:
+ 000000001700 - amount - 12 positions implied two digit decimal
+ 000000000000 - other amount - 12 positions implied two digit decimal
+ 0124 - four digit country code
+ Output (partial) Transaction Data - 0000000017000000000000000124
## Transaction data padding
Transaction data should be padded prior to sending to the service. Most schemes use ISO 9797 Method 2 padding, where a hex string is appended by hex 80 followed by 00 until the field is a multiple of the encryption block size; 8 bytes or 16 characters for TDES and 16 bytes or 32 characters for AES. The alternative (method 1) is not as common but uses only 00 as the padding characters.
### ISO 9797 Method 1 Padding
Unpadded: 00000000170000000000000008400080008000084016051700000000093800000B03011203 (74 characters or 37 bytes)
Padded: 00000000170000000000000008400080008000084016051700000000093800000B03011203**000000** (80 characters or 40 bytes)
### ISO 9797 Method 2 Padding
Unpadded: 00000000170000000000000008400080008000084016051700000000093800000B1F220103000000 (80 characters or 40 bytes)
Padded: 00000000170000000000000008400080008000084016051700000000093800000B1F220103000000**8000000000000000** (88 characters or 44 bytes)
## Examples
### Visa CVN10
**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 then ARCQ (Authorization Request Cryptogram) 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"
}
```
### Visa CVN18 and Visa CVN22
**Example**
In this example, we will validate an ARQC generated using Visa CVN18 or CVN22. The cryptographic operations are the same between CVN18 and CVN22 but the data contained within transaction data varies. Compared to CVN10, a completely different cryptogram is generated even with the same inputs.
If AWS Payment Cryptography is able to validate the ARQC, an http/200 is returned. If the ARCQ is not validated, it will return an http/400.
```
$ 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 00000000170000000000000008400080008000084016051700000000093800000B1F22010300000000000 \
00000000000000000000000000000000000000000008000000000000000
--session-key-derivation-attributes='{"EmvCommon":{"ApplicationTransactionCounter":"000B", \
"PanSequenceNumber":"01","PrimaryAccountNumber":"9137631040001422"}}'
```
```
{
"KeyArn": "arn:aws:payment-cryptography:us-east-2:111122223333:key/pw3s6nl62t5ushfk",
"KeyCheckValue": "08D7B4"
}
```
# Generate and verify MAC
Message Authentication Codes (MAC) are typically used to authenticate the integrity of a message (whether it's been modified). Cryptographic hashes such as HMAC (Hash-Based Message Authentication Code), CBC-MAC and CMAC (Cipher-based Message Authentication Code) provide additional assurance of the sender of the MAC by utilizing cryptography. HMAC is based on hash functions while CMAC is based on block ciphers. The service also supports ISO9797 Algorithms 1 and 3 which are types of CBC-MACs.
All MAC algorithms of this service combine a cryptographic hash function and a shared secret key. They take a message and a secret key, such as the key material in a key, and return a unique tag or mac. If even one character of the message changes, or if the secret key changes, the resulting tag is entirely different. By requiring a secret key, cryptographic MACs also provides authenticity; it is impossible to generate an identical mac without the secret key. Cryptographic MACs are sometimes called symmetric signatures, because they work like digital signatures, but use a single key for both signing and verification.
AWS Payment Cryptography supports several types of MACs:
**ISO9797 ALGORITHM 1**
Denoted by `KeyUsage` of ISO9797\$1ALGORITHM1. If the field isn't a multiple of block size (8 bytes/16 hex characters for TDES, 16 bytes/32 characters for AES, AWS Payment Cryptography automatically applies ISO9797 Padding Method 1. If other padding methods are needed, you can apply them prior to calling the service.
**ISO9797 ALGORITHM 3 (Retail MAC)**
Denoted by `KeyUsage` of ISO9797\$1ALGORITHM3. The same padding rules apply as Algorithm 1
**ISO9797 ALGORITHM 5 (CMAC)**
Denoted by `KeyUsage` of TR31\$1M6\$1ISO\$19797\$15\$1CMAC\$1KEY
**HMAC**
Denoted by `KeyUsage` of TR31\$1M7\$1HMAC\$1KEY including HMAC\$1SHA224, HMAC\$1SHA256, HMAC\$1SHA384 and HMAC\$1SHA512
**AS2805.4.1 MAC**
Denoted by `KeyUsage` of TR31\$1M0\$1ISO\$116609\$1MAC\$1KEY. For more details on AS2805, see [AS2805](advanced.regional.as2805.md)
**DUKPT MAC**
DUKPT MAC is typically used to confirm the source and payload of messages to/from payment terminals. It derives a key using DUKPT derivation techniques and then performs the MAC. Keys used with this option are denoted by a `KeyUsage` of TR31\$1B0\$1BASE\$1DERIVATION\$1KEY.
**EMV MAC**
EMV MAC is typically referred to as an integrity key in EMV documentation. It derives a key using EMV derivation techniques and then utilizes ISO9797\$1ALGORITHM3 internally. It is typically used to send issuer scripts to a chip card for reprogramming. Keys used with this option are denoted by a `KeyUsage` of TR31\$1E2\$1EMV\$1MKEY\$1INTEGRITY. If you are both sending a script and update an offline pin, see [GenerateMacEmvPinChange](https://docs.aws.amazon.com/payment-cryptography/latest/DataAPIReference/API_GenerateMacEmvPinChange) that performs both of these operations.
**Topics**
+ [Generate MAC](generate-mac.md)
+ [Verify MAC](verify-mac.md)
# Generate MAC
Generate MAC API is used to authenticate card-related data, such as track data from a card magnetic stripe, by using known cryptographic keys to generate a MAC (Message Authentication Code) for data validation between sending and receiving parties. The data used to generate MAC includes message data, secret MAC encryption key and MAC algorithm to generate a unique MAC value for transmission. The receiving party of the MAC will use the same MAC message data, MAC encryption key, and algorithm to reproduce another MAC value for comparison and data authentication. Even if one character of the message changes or the MAC key used for verification is not identical, the resulting MAC value is different. The API supports ISO 9797-1 Algorithm 1 and ISO 9797-1 Algorithm 3 MAC (using a static MAC key and a derived DUKPT key), HMAC and EMV MAC encryption keys for this operation.
The input value for `message-data` must be hexBinary data.
For more information on all options for this API, see [GenerateMac](https://docs.aws.amazon.com/payment-cryptography/latest/DataAPIReference/API_GenerateMac.html) and [VerifyMac](https://docs.aws.amazon.com/payment-cryptography/latest/DataAPIReference/API_VerifyMac.html).
The optional parameter mac-length allows you to truncate the output value (although this can also be done within your code). A length of 8 refers to 8 bytes or 16 hex characters.
MAC keys can either be created with AWS Payment Cryptography by calling [CreateKey](https://docs.aws.amazon.com/payment-cryptography/latest/APIReference/API_CreateKey.html) or imported by calling [ImportKey](https://docs.aws.amazon.com/payment-cryptography/latest/APIReference/API_ImportKey.html).
**Note**
CMAC and HMAC algorithms don't require padding. All others require that the data be padded to the block size of the algorithm, which is multiples of 8 bytes (16 hex characters) for TDES and 16 bytes (32 hex characters) for AES.
**Topics**
+ [Generate HMAC](#generate-mac-hmac)
+ [Generate MAC using ISO 9797-1 Algorithm 3](#generate-mac-iso9797-alg3)
+ [Generate MAC using CMAC](#generate-mac-cmac)
+ [Generate MAC using DUKPT CMAC](#generate-mac-dukpt-cmac)
## Generate HMAC
In this example, we will generate a HMAC (Hash-Based Message Authentication Code) for card data authentication using HMAC algorithm `HMAC_SHA256` and HMAC encryption key. The key must have KeyUsage set to `TR31_M7_HMAC_KEY` and KeyModesOfUse to `Generate`. The hash length (e.g. 256) is defined when the key is created and cannot be modified.
The optional mac-length parameter will trim the output MAC, although this can be performed outside the service as well. This value is in bytes, so a value of 16 will expect a hex string of length 32.
**Example**
```
$ aws payment-cryptography-data generate-mac \
--key-identifier arn:aws:payment-cryptography:us-east-2:111122223333:key/qnobl5lghrzunce6 \
--message-data "3b313038383439303031303733393431353d32343038323236303030373030303f33" \
--generation-attributes Algorithm=HMAC
```
```
{
"KeyArn": "arn:aws:payment-cryptography:us-east-2:111122223333:key/qnobl5lghrzunce6",
"KeyCheckValue": "2976E7",
"Mac": "ED87F26E961C6D0DDB78DA5038AA2BDDEA0DCE03E5B5E96BDDD494F4A7AA470C"
}
```
## Generate MAC using ISO 9797-1 Algorithm 3
In this example, we will generate a MAC using ISO 9797-1 Algorithm 3 (Retail MAC) for card data authentication. The key must have KeyUsage set to `TR31_M3_ISO_9797_3_MAC_KEY` and KeyModesOfUse to `Generate`.
**Example**
```
$ aws payment-cryptography-data generate-mac \
--key-identifier arn:aws:payment-cryptography:us-east-2:111122223333:key/kwapwa6qaifllw2h \
--message-data "3b313038383439303031303733393431353d32343038323236303030373030303f33" \
--generation-attributes="Algorithm=ISO9797_ALGORITHM3"
```
```
{
"KeyArn": "arn:aws:payment-cryptography:us-east-2:111122223333:key/kwapwa6qaifllw2h",
"KeyCheckValue": "2976EA",
"Mac": "A8F7A73DAF87B6D0"
}
```
## Generate MAC using CMAC
CMAC is most commonly used when the keys are AES but it also supports TDES. In this example, we will generate a MAC using CMAC (ISO 9797-1 Algorithm 5) for card data authentication with an AES key. The key must have KeyUsage set to `TR31_M6_ISO_9797_5_CMAC_KEY` and KeyModesOfUse to `Generate`.
**Example**
```
$ aws payment-cryptography-data generate-mac \
--key-identifier arn:aws:payment-cryptography:us-east-2:111122223333:key/tqv5yij6wtxx64pi \
--message-data "3b313038383439303031303733393431353d32343038323236303030373030303f33" \
--generation-attributes Algorithm="CMAC"
```
```
{
"KeyArn": "arn:aws:payment-cryptography:us-east-2:111122223333:key/tqv5yij6wtxx64pi",
"KeyCheckValue": "C1EB8F",
"Mac": "1F8C36E63F91E4E93DF7842BF5E2E5F7"
}
```
## Generate MAC using DUKPT CMAC
In this example, we will generate a MAC using DUKPT (Derived Unique Key Per Transaction) with CMAC for card data authentication. The key must have KeyUsage set to `TR31_B0_BASE_DERIVATION_KEY` and KeyModesOfUse `DeriveKey` set to true. DUKPT keys derive a unique key for each transaction using a Base Derivation Key (BDK) and a Key Serial Number (KSN).
**Example**
```
$ aws payment-cryptography-data generate-mac --key-identifier arn:aws:payment-cryptography:us-east-2:111122223333:key/qnobl5lghrzunce6 --message-data "3b313038383439303031303733393431353d32343038323236303030373030303f33" --generation-attributes="DukptCmac={KeySerialNumber="932A6E954ABB32DD00000001",Direction=BIDIRECTIONAL}"
```
```
{
"KeyArn": "arn:aws:payment-cryptography:us-east-2:111122223333:key/qnobl5lghrzunce6",
"KeyCheckValue": "C1EB8F"
}
```
# Verify MAC
Verify MAC API is used to verify MAC (Message Authentication Code) for card-related data authentication. It must use the same encryption key used during generate MAC to re-produce MAC value for authentication. The MAC encryption key can either be created with AWS Payment Cryptography by calling [CreateKey](https://docs.aws.amazon.com/payment-cryptography/latest/APIReference/API_CreateKey.html) or imported by calling [ImportKey](https://docs.aws.amazon.com/payment-cryptography/latest/APIReference/API_ImportKey.html). The API supports DUKPT MAC, HMAC and EMV MAC encryption keys for this operation.
If the value is verified, then response parameter `MacDataVerificationSuccessful` will return `Http/200`, otherwise `Http/400` with a message indicating that `Mac verification failed`.
**Topics**
+ [Verify HMAC](#verify-mac-hmac)
+ [Verify MAC using DUKPT CMAC](#verify-mac-dukpt-cmac)
## Verify HMAC
In this example, we will verify a HMAC (Hash-Based Message Authentication Code) for card data authentication using HMAC algorithm `HMAC_SHA256` and HMAC encryption key. The key must have KeyUsage set to `TR31_M7_HMAC_KEY` and KeyModesOfUse `Verify` set to true.
**Example**
```
$ aws payment-cryptography-data verify-mac \
--key-identifier arn:aws:payment-cryptography:us-east-2:111122223333:key/qnobl5lghrzunce6 \
--message-data "3b343038383439303031303733393431353d32343038323236303030373030303f33" \
--mac ED87F26E961C6D0DDB78DA5038AA2BDDEA0DCE03E5B5E96BDDD494F4A7AA470C \
--verification-attributes Algorithm=HMAC_SHA256
```
```
{
"KeyArn": "arn:aws:payment-cryptography:us-east-2:111122223333:key/qnobl5lghrzunce6",
"KeyCheckValue": "2976E7"
}
```
## Verify MAC using DUKPT CMAC
In this example, we will verify a MAC using DUKPT (Derived Unique Key Per Transaction) with CMAC for card data authentication. The key must have KeyUsage set to `TR31_B0_BASE_DERIVATION_KEY` and KeyModesOfUse `DeriveKey` set to true. DUKPT keys derive a unique key for each transaction using a Base Derivation Key (BDK) and a Key Serial Number (KSN). The value of DukptKeyVariant must match between sender and receiver. REQUEST will typically be used from terminal to backend, VERIFY from backend to terminal and BIDIRECTIONAL when a single key is used in both directions.
**Example**
```
$ aws payment-cryptography-data verify-mac \
--key-identifier arn:aws:payment-cryptography:us-east-2:111122223333:key/tqv5yij6wtxx64pi \
--message-data "3b343038383439303031303733393431353d32343038323236303030373030303f33" \
--mac D8E804EE74BF1D909A2C01C0BDE8EF34 \
--verification-attributes DukptCmac='{"KeySerialNumber":"932A6E954ABB32DD00000001","DukptKeyVariant":"BIDIRECTIONAL"}'
```
```
{
"KeyArn": "arn:aws:payment-cryptography:us-east-2:111122223333:key/tqv5yij6wtxx64pi",
"KeyCheckValue": "C1EB8F"
}
```
# Valid keys for cryptographic operations
Certain keys can only be used for certain operations. Additionally, some operations may limit the key modes of use for keys. Please see the following table for allowed combinations.
**Note**
Certain combinations, although permitted, may create unusable situations such as generating CVV codes `(generate)` but then unable to verify them `(verify)`.
**Topics**
+ [GenerateCardData](#w2aac15c31b9)
+ [VerifyCardData](#w2aac15c31c11)
+ [GeneratePinData (for VISA/ABA schemes)](#w2aac15c31c15)
+ [GeneratePinData (for `IBM3624`)](#w2aac15c31c17)
+ [VerifyPinData (for VISA/ABA schemes)](#w2aac15c31c21)
+ [VerifyPinData (for `IBM3624`)](#w2aac15c31c23)
+ [Decrypt Data](#w2aac15c31c27)
+ [Encrypt Data](#w2aac15c31c33)
+ [Translate Pin Data](#w2aac15c31c39)
+ [Generate/Verify MAC](#crypto-ops-validkeys.generatemac)
+ [GenerateMacEmvPinChange](#crypto-ops-validkeys.generatemacemvpinchange)
+ [VerifyAuthRequestCryptogram](#w2aac15c31c51)
+ [Import/Export Key](#crypto-ops-validkeys.importexport)
+ [Unused key types](#w2aac15c31c57)
## GenerateCardData
| API Endpoint | Cryptographic Operation or Algorithm | Allowed Key Usage | Allowed Key Algorithm | Allowed combination of key modes of use |
| --- | --- | --- | --- | --- |
| GenerateCardData | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/payment-cryptography/latest/userguide/crypto-ops-validkeys-ops.html) | TR31\$1C0\$1CARD\$1VERIFICATION\$1KEY | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/payment-cryptography/latest/userguide/crypto-ops-validkeys-ops.html) | \$1 Generate = true \$1,\$1 Generate = true, Verify = true \$1 |
| GenerateCardData | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/payment-cryptography/latest/userguide/crypto-ops-validkeys-ops.html) | TR31\$1C0\$1CARD\$1VERIFICATION\$1KEY | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/payment-cryptography/latest/userguide/crypto-ops-validkeys-ops.html) | \$1 Generate = true \$1,\$1 Generate = true, Verify = true \$1 |
| GenerateCardData | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/payment-cryptography/latest/userguide/crypto-ops-validkeys-ops.html) | TR31\$1E6\$1EMV\$1MKEY\$1OTHER | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/payment-cryptography/latest/userguide/crypto-ops-validkeys-ops.html) | \$1 DeriveKey = true \$1 |
| GenerateCardData | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/payment-cryptography/latest/userguide/crypto-ops-validkeys-ops.html) | TR31\$1E4\$1EMV\$1MKEY\$1DYNAMIC\$1NUMBERS | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/payment-cryptography/latest/userguide/crypto-ops-validkeys-ops.html) | \$1 DeriveKey = true \$1 |
| GenerateCardData | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/payment-cryptography/latest/userguide/crypto-ops-validkeys-ops.html) | TR31\$1E6\$1EMV\$1MKEY\$1OTHER | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/payment-cryptography/latest/userguide/crypto-ops-validkeys-ops.html) | \$1 DeriveKey = true \$1 |
## VerifyCardData
| Cryptographic Operation or Algorithm | Allowed Key Usage | Allowed Key Algorithm | Allowed combination of key modes of use |
| --- | --- | --- | --- |
| [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/payment-cryptography/latest/userguide/crypto-ops-validkeys-ops.html) | TR31\$1C0\$1CARD\$1VERIFICATION\$1KEY | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/payment-cryptography/latest/userguide/crypto-ops-validkeys-ops.html) | \$1 Generate = true \$1,\$1 Generate = true, Verify = true \$1 |
| [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/payment-cryptography/latest/userguide/crypto-ops-validkeys-ops.html) | TR31\$1C0\$1CARD\$1VERIFICATION\$1KEY | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/payment-cryptography/latest/userguide/crypto-ops-validkeys-ops.html) | \$1 Generate = true \$1,\$1 Generate = true, Verify = true \$1 |
| [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/payment-cryptography/latest/userguide/crypto-ops-validkeys-ops.html) | TR31\$1E6\$1EMV\$1MKEY\$1OTHER | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/payment-cryptography/latest/userguide/crypto-ops-validkeys-ops.html) | \$1 DeriveKey = true \$1 |
| [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/payment-cryptography/latest/userguide/crypto-ops-validkeys-ops.html) | TR31\$1E4\$1EMV\$1MKEY\$1DYNAMIC\$1NUMBERS | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/payment-cryptography/latest/userguide/crypto-ops-validkeys-ops.html) | \$1 DeriveKey = true \$1 |
| [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/payment-cryptography/latest/userguide/crypto-ops-validkeys-ops.html) | TR31\$1E6\$1EMV\$1MKEY\$1OTHER | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/payment-cryptography/latest/userguide/crypto-ops-validkeys-ops.html) | \$1 DeriveKey = true \$1 |
## GeneratePinData (for VISA/ABA schemes)
`VISA_PIN or VISA_PIN_VERIFICATION_VALUE`
| Key Type | Allowed Key Usage | Allowed Key Algorithm | Allowed combination of key modes of use |
| --- | --- | --- | --- |
| PIN Encryption Key | TR31\$1P0\$1PIN\$1ENCRYPTION\$1KEY | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/payment-cryptography/latest/userguide/crypto-ops-validkeys-ops.html) | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/payment-cryptography/latest/userguide/crypto-ops-validkeys-ops.html) |
| PIN Generation Key | TR31\$1V2\$1VISA\$1PIN\$1VERIFICATION\$1KEY | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/payment-cryptography/latest/userguide/crypto-ops-validkeys-ops.html) | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/payment-cryptography/latest/userguide/crypto-ops-validkeys-ops.html) |
## GeneratePinData (for `IBM3624`)
`IBM3624_PIN_OFFSET,IBM3624_NATURAL_PIN,IBM3624_RANDOM_PIN, IBM3624_PIN_FROM_OFFSET)`
| Key Type | Allowed Key Usage | Allowed Key Algorithm | Allowed combination of key modes of use |
| --- | --- | --- | --- |
| PIN Encryption Key | TR31\$1P0\$1PIN\$1ENCRYPTION\$1KEY | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/payment-cryptography/latest/userguide/crypto-ops-validkeys-ops.html) | For IBM3624\$1NATURAL\$1PIN, IBM3624\$1RANDOM\$1PIN, IBM3624\$1PIN\$1FROM\$1OFFSET [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/payment-cryptography/latest/userguide/crypto-ops-validkeys-ops.html) For IBM3624\$1PIN\$1OFFSET [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/payment-cryptography/latest/userguide/crypto-ops-validkeys-ops.html) |
| PIN Generation Key | TR31\$1V1\$1IBM3624\$1PIN\$1VERIFICATION\$1KEY | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/payment-cryptography/latest/userguide/crypto-ops-validkeys-ops.html) | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/payment-cryptography/latest/userguide/crypto-ops-validkeys-ops.html) |
## VerifyPinData (for VISA/ABA schemes)
`VISA_PIN`
| Key Type | Allowed Key Usage | Allowed Key Algorithm | Allowed combination of key modes of use |
| --- | --- | --- | --- |
| PIN Encryption Key | TR31\$1P0\$1PIN\$1ENCRYPTION\$1KEY | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/payment-cryptography/latest/userguide/crypto-ops-validkeys-ops.html) | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/payment-cryptography/latest/userguide/crypto-ops-validkeys-ops.html) |
| PIN Generation Key | TR31\$1V2\$1VISA\$1PIN\$1VERIFICATION\$1KEY | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/payment-cryptography/latest/userguide/crypto-ops-validkeys-ops.html) | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/payment-cryptography/latest/userguide/crypto-ops-validkeys-ops.html) |
## VerifyPinData (for `IBM3624`)
`IBM3624_PIN_OFFSET,IBM3624_NATURAL_PIN,IBM3624_RANDOM_PIN, IBM3624_PIN_FROM_OFFSET)`
| Key Type | Allowed Key Usage | Allowed Key Algorithm | Allowed combination of key modes of use |
| --- | --- | --- | --- |
| PIN Encryption Key | TR31\$1P0\$1PIN\$1ENCRYPTION\$1KEY | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/payment-cryptography/latest/userguide/crypto-ops-validkeys-ops.html) | For IBM3624\$1NATURAL\$1PIN, IBM3624\$1RANDOM\$1PIN, IBM3624\$1PIN\$1FROM\$1OFFSET [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/payment-cryptography/latest/userguide/crypto-ops-validkeys-ops.html) |
| PIN Verification Key | TR31\$1V1\$1IBM3624\$1PIN\$1VERIFICATION\$1KEY | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/payment-cryptography/latest/userguide/crypto-ops-validkeys-ops.html) | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/payment-cryptography/latest/userguide/crypto-ops-validkeys-ops.html) |
## Decrypt Data
| Key Type | Allowed Key Usage | Allowed Key Algorithm | Allowed combination of key modes of use |
| --- | --- | --- | --- |
| DUKPT | TR31\$1B0\$1BASE\$1DERIVATION\$1KEY | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/payment-cryptography/latest/userguide/crypto-ops-validkeys-ops.html) | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/payment-cryptography/latest/userguide/crypto-ops-validkeys-ops.html) |
| EMV | TR31\$1E1\$1EMV\$1MKEY\$1CONFIDENTIALITY TR31\$1E6\$1EMV\$1MKEY\$1OTHER | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/payment-cryptography/latest/userguide/crypto-ops-validkeys-ops.html) | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/payment-cryptography/latest/userguide/crypto-ops-validkeys-ops.html) |
| RSA | TR31\$1D1\$1ASYMMETRIC\$1KEY\$1FOR\$1DATA\$1ENCRYPTION | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/payment-cryptography/latest/userguide/crypto-ops-validkeys-ops.html) | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/payment-cryptography/latest/userguide/crypto-ops-validkeys-ops.html) |
| Symmetric keys | TR31\$1D0\$1SYMMETRIC\$1DATA\$1ENCRYPTION\$1KEY | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/payment-cryptography/latest/userguide/crypto-ops-validkeys-ops.html) | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/payment-cryptography/latest/userguide/crypto-ops-validkeys-ops.html) |
## Encrypt Data
| Key Type | Allowed Key Usage | Allowed Key Algorithm | Allowed combination of key modes of use |
| --- | --- | --- | --- |
| DUKPT | TR31\$1B0\$1BASE\$1DERIVATION\$1KEY | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/payment-cryptography/latest/userguide/crypto-ops-validkeys-ops.html) | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/payment-cryptography/latest/userguide/crypto-ops-validkeys-ops.html) |
| EMV | TR31\$1E1\$1EMV\$1MKEY\$1CONFIDENTIALITY TR31\$1E6\$1EMV\$1MKEY\$1OTHER | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/payment-cryptography/latest/userguide/crypto-ops-validkeys-ops.html) | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/payment-cryptography/latest/userguide/crypto-ops-validkeys-ops.html) |
| RSA | TR31\$1D1\$1ASYMMETRIC\$1KEY\$1FOR\$1DATA\$1ENCRYPTION | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/payment-cryptography/latest/userguide/crypto-ops-validkeys-ops.html) | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/payment-cryptography/latest/userguide/crypto-ops-validkeys-ops.html) |
| Symmetric keys | TR31\$1D0\$1SYMMETRIC\$1DATA\$1ENCRYPTION\$1KEY | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/payment-cryptography/latest/userguide/crypto-ops-validkeys-ops.html) | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/payment-cryptography/latest/userguide/crypto-ops-validkeys-ops.html) |
## Translate Pin Data
| Direction | Key Type | Allowed Key Usage | Allowed Key Algorithm | Allowed combination of key modes of use |
| --- | --- | --- | --- | --- |
| Inbound Data Source | DUKPT | TR31\$1B0\$1BASE\$1DERIVATION\$1KEY | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/payment-cryptography/latest/userguide/crypto-ops-validkeys-ops.html) | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/payment-cryptography/latest/userguide/crypto-ops-validkeys-ops.html) |
| Inbound Data Source | non-DUKPT (PEK, AWK, IWK, etc) | TR31\$1P0\$1PIN\$1ENCRYPTION\$1KEY | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/payment-cryptography/latest/userguide/crypto-ops-validkeys-ops.html) | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/payment-cryptography/latest/userguide/crypto-ops-validkeys-ops.html) |
| Outbound Data Target | DUKPT | TR31\$1B0\$1BASE\$1DERIVATION\$1KEY | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/payment-cryptography/latest/userguide/crypto-ops-validkeys-ops.html) | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/payment-cryptography/latest/userguide/crypto-ops-validkeys-ops.html) |
| Outbound Data Target | non-DUKPT (PEK, IWK, AWK, etc) | TR31\$1P0\$1PIN\$1ENCRYPTION\$1KEY | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/payment-cryptography/latest/userguide/crypto-ops-validkeys-ops.html) | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/payment-cryptography/latest/userguide/crypto-ops-validkeys-ops.html) |
## Generate/Verify MAC
MAC keys are used for creating cryptographic hashes of a message/body of data. It is not recommended to create a key with limited key modes of use as you will be unable to perform the matching operation. However, you may import/export a key with only one operation if the other system is intended to perform the other half of the operation pair.
| Allowed Key Usage | Allowed Key Usage | Allowed Key Algorithm | Allowed combination of key modes of use |
| --- | --- | --- | --- |
| MAC Key | TR31\$1M1\$1ISO\$19797\$11\$1MAC\$1KEY | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/payment-cryptography/latest/userguide/crypto-ops-validkeys-ops.html) | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/payment-cryptography/latest/userguide/crypto-ops-validkeys-ops.html) |
| MAC Key (Retail MAC) | TR31\$1M1\$1ISO\$19797\$13\$1MAC\$1KEY | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/payment-cryptography/latest/userguide/crypto-ops-validkeys-ops.html) | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/payment-cryptography/latest/userguide/crypto-ops-validkeys-ops.html) |
| MAC Key (CMAC) | TR31\$1M6\$1ISO\$19797\$15\$1CMAC\$1KEY | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/payment-cryptography/latest/userguide/crypto-ops-validkeys-ops.html) | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/payment-cryptography/latest/userguide/crypto-ops-validkeys-ops.html) |
| MAC Key (HMAC) | TR31\$1M7\$1HMAC\$1KEY | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/payment-cryptography/latest/userguide/crypto-ops-validkeys-ops.html) | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/payment-cryptography/latest/userguide/crypto-ops-validkeys-ops.html) |
| MAC Key (AS2805) | TR31\$1M0\$1ISO\$116609\$1MAC\$1KEY | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/payment-cryptography/latest/userguide/crypto-ops-validkeys-ops.html) | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/payment-cryptography/latest/userguide/crypto-ops-validkeys-ops.html) |
## GenerateMacEmvPinChange
GenerateMacEmvPinChange combines MAC generation and PIN encryption for EMV offline PIN change operations. This operation requires two different key types: an integrity key for MAC generation and a confidentiality key for PIN encryption.
| Key Type | Allowed Key Usage | Allowed Key Algorithm | Allowed combination of key modes of use |
| --- | --- | --- | --- |
| Secure Messaging Integrity Key | TR31\$1E2\$1EMV\$1MKEY\$1INTEGRITY | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/payment-cryptography/latest/userguide/crypto-ops-validkeys-ops.html) | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/payment-cryptography/latest/userguide/crypto-ops-validkeys-ops.html) |
| Secure Messaging Confidentiality Key | TR31\$1E1\$1EMV\$1MKEY\$1CONFIDENTIALITY | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/payment-cryptography/latest/userguide/crypto-ops-validkeys-ops.html) | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/payment-cryptography/latest/userguide/crypto-ops-validkeys-ops.html) |
| Current PIN PEK (PIN Encryption Key) | TR31\$1P0\$1PIN\$1ENCRYPTION\$1KEY | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/payment-cryptography/latest/userguide/crypto-ops-validkeys-ops.html) | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/payment-cryptography/latest/userguide/crypto-ops-validkeys-ops.html) |
| New PIN PEK (PIN Encryption Key) | TR31\$1P0\$1PIN\$1ENCRYPTION\$1KEY | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/payment-cryptography/latest/userguide/crypto-ops-validkeys-ops.html) | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/payment-cryptography/latest/userguide/crypto-ops-validkeys-ops.html) |
| ARQC Key Only applies for Visa and Amex derivation schemes. | TR31\$1E0\$1EMV\$1MKEY\$1APP\$1CRYPTOGRAMS | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/payment-cryptography/latest/userguide/crypto-ops-validkeys-ops.html) | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/payment-cryptography/latest/userguide/crypto-ops-validkeys-ops.html) |
## VerifyAuthRequestCryptogram
| Allowed Key Usage | EMV Option | Allowed Key Algorithm | Allowed combination of key modes of use |
| --- | --- | --- | --- |
| [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/payment-cryptography/latest/userguide/crypto-ops-validkeys-ops.html) | TR31\$1E0\$1EMV\$1MKEY\$1APP\$1CRYPTOGRAMS | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/payment-cryptography/latest/userguide/crypto-ops-validkeys-ops.html) | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/payment-cryptography/latest/userguide/crypto-ops-validkeys-ops.html) |
## Import/Export Key
| Operation Type | Allowed Key Usage | Allowed Key Algorithm | Allowed combination of key modes of use |
| --- | --- | --- | --- |
| TR-31 Wrapping Key | TR31\$1K1\$1KEY\$1BLOCK\$1PROTECTION\$1KEY TR31\$1K0\$1KEY\$1ENCRYPTION\$1KEY | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/payment-cryptography/latest/userguide/crypto-ops-validkeys-ops.html) | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/payment-cryptography/latest/userguide/crypto-ops-validkeys-ops.html) |
| Import of trusted CA | TR31\$1S0\$1ASYMMETRIC\$1KEY\$1FOR\$1DIGITAL\$1SIGNATURE | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/payment-cryptography/latest/userguide/crypto-ops-validkeys-ops.html) | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/payment-cryptography/latest/userguide/crypto-ops-validkeys-ops.html) |
| Import of public key certificate for asymmetric encryption | TR31\$1D1\$1ASYMMETRIC\$1KEY\$1FOR\$1DATA\$1ENCRYPTION | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/payment-cryptography/latest/userguide/crypto-ops-validkeys-ops.html) | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/payment-cryptography/latest/userguide/crypto-ops-validkeys-ops.html) |
| Key used to key agreement algorithms such as ECDH | TR31\$1K3\$1ASYMMETRIC\$1KEY\$1FOR\$1KEY\$1AGREEMENT | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/payment-cryptography/latest/userguide/crypto-ops-validkeys-ops.html) | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/payment-cryptography/latest/userguide/crypto-ops-validkeys-ops.html) |
## Unused key types
The following key types are not currently used by AWS Payment Cryptography
+ TR31\$1P1\$1PIN\$1GENERATION\$1KEY