cyberchef/PAYMENT_RECIPES.md

# Payment Recipe Starters

Owner:
- Jacob Marks, `https://jacobmarks.com`
- Fork home: `https://github.com/J8k3/CyberChef`

These recipe starters are for software-only payment-crypto emulation, inspection, regression tests, and interoperability work.

For AWS operation mapping, see `AWS_PAYMENT_CRYPTOGRAPHY_RECIPES.md`.
For validation posture, standards references, and release guardrails, see `PAYMENT_VALIDATION_AUDIT.md`.

## Naming Convention

All payment operation display names follow **Title Case** throughout. Acronyms (DUKPT, AES, EMV, MAC, PAN, PVV, KCV, ARQC, ARPC, TR-31, TR-34) are always upper-case. Brand names retain their canonical capitalisation (`payShield`).

Pattern: `[Verb] [Optional Qualifier] [Noun]`
- Verbs: Generate, Verify, Parse, Build, Translate, Derive, Calculate, Encrypt, Decrypt, Re-Encrypt
- When adding a new payment operation, follow this pattern and update this file.

## UI Arrangement

The `Payments` category is arranged in this order:
- payment-facing wrappers first
- EMV and card-validation flows next
- PIN and issuer-verification helpers after that
- key derivation, generation, KCV, and parser utilities next
- generic crypto primitives last for chaining

That keeps common testing tasks near the top without hiding the underlying `HMAC`, `CMAC`, cipher, and key-wrap primitives that some chains still need.

## 1) Encrypt / Decrypt / Re-Encrypt Payment Data

Operations:
- `Encrypt Payment Data`
- `Decrypt Payment Data`
- `Re-Encrypt Payment Data`

Use this when:
- you want payment-facing names for AES, TDES, or the implemented DUKPT-TDES profiles
- you want one operation for decrypt-then-encrypt rewrapping

Input:
- plaintext or ciphertext in the selected input format

Important assumptions:
- current derived-data coverage is AES, TDES, and the implemented DUKPT-TDES profiles
- this is software emulation and does not model AWS key ARNs or HSM custody

## 2) Generate / Verify Payment MAC

Operations:
- `Generate Payment MAC`
- `Verify Payment MAC`

Supported methods:
- `HMAC SHA-224`
- `HMAC SHA-256`
- `HMAC SHA-384`
- `HMAC SHA-512`
- `AES-CMAC`
- `TDES-CMAC`
- `ISO 9797-1 Algorithm 1`
- `ISO 9797-1 Algorithm 3`
- `AS2805-4.1`
- `DUKPT MAC Request CMAC`
- `DUKPT MAC Response CMAC`
- `DUKPT ISO 9797-1 Algorithm 1`
- `DUKPT ISO 9797-1 Algorithm 3`

Use this when:
- you want one payment-facing MAC surface instead of deciding between generic `HMAC`, `CMAC`, ISO9797, DUKPT, and AS2805 yourself

Input:
- message data in the selected input format

Important assumptions:
- ISO9797 and AS2805 methods use clear TDES keys in software
- DUKPT methods expect a clear BDK plus full KSN
- EMV MAC is handled by the dedicated EMV MAC operations below

## 3) Generate / Verify EMV MAC

Operations:
- `Generate EMV MAC`
- `Verify EMV MAC`
- `Generate EMV MAC For PIN Change`

Use this when:
- you already have the EMV session integrity key
- you want issuer-script MAC generation or verification
- you need a dedicated offline PIN-change MAC helper

Input:
- issuer-script or EMV command payload as hex

Important assumptions:
- these operations do not derive EMV session keys
- they apply retail-MAC style EMV MAC generation with ISO9797 padding method 2
- `Generate EMV MAC For PIN Change` expects the new PIN block to already be encrypted before you call it

## 4) Generate / Verify EMV ARQC And ARPC

Operations:
- `Generate EMV ARQC`
- `Verify EMV ARQC`
- `Generate EMV ARPC`

Use this when:
- you already know the exact preassembled EMV data block
- you already have the derived EMV session key

Input:
- preassembled EMV cryptogram input data as hex

Important assumptions:
- current coverage is the implemented AES-CMAC profile
- these operations do not assemble CDOL data or derive issuer/session keys

## 5) Generate / Verify Card Validation Data

Operations:
- `Generate Test PAN`
- `Parse PAN`
- `Generate Card Validation Data`
- `Verify Card Validation Data`

Profiles:
- `CVV / CVC (use service code arg)`
- `CVV2 / CVC2 (force 000)`
- `iCVV (force 999)`

Input:
- combined CVK pair as clear hex

Important assumptions:
- CVV2 forces service code `000`
- iCVV forces service code `999`
- this is a clear-key software emulation of common card-validation flows
- `Parse PAN` now outputs `cardType`, `cardTypeConfidence`, and `majorIndustryIdentifierDescription` in addition to network and Luhn fields

Recommended chain:
- `Generate Test PAN` -> `Parse PAN` -> `Generate Card Validation Data`

Use `Generate Test PAN` when:
- you want a Visa, Mastercard, American Express, or Discover PAN to feed into later recipes

Use `Parse PAN` when:
- you want to confirm network, card type hint, IIN, length, and Luhn validity before continuing

## 6) Generate / Verify Payment PIN Data

Operations:
- `Generate Payment PIN Data`
- `Verify Payment PIN Data`

> **Note:** `Translate Payment PIN Data` is deprecated — use `Translate PIN Block` (section 7) instead. See issue #4.

Use this when:
- you want AWS-style PIN-data naming for clear ISO 9564 block flows

Input:
- `Generate Payment PIN Data`: clear PIN digits
- `Verify Payment PIN Data`: clear PIN block hex

Important assumptions:
- these wrappers currently cover clear ISO formats `0`, `1`, and `3`
- encrypted PEK/BDK translation is still done by chaining lower-level steps

## 7) Build / Parse / Translate PIN Block

Operations:
- `Build PIN Block`
- `Parse PIN Block`
- `Translate PIN Block`

Use this when:
- you want the lower-level clear PIN-block tools directly

Input:
- `Build PIN Block`: clear PIN digits
- `Parse PIN Block`: clear PIN block hex
- `Translate PIN Block`: clear PIN block hex

Important assumptions:
- current clear-block support is ISO formats `0`, `1`, and `3`

## 8) Issuer PIN Verification Helpers

Operations:
- `Generate IBM 3624 PIN Offset`
- `Verify IBM 3624 PIN`
- `Generate VISA PVV`
- `Verify VISA PVV`

Use this when:
- you need issuer-side PIN verification artifacts rather than PIN blocks

Input:
- clear PIN digits

Important assumptions:
- these helpers use clear PVKs in software
- IBM 3624 expects a decimalization table and validation data
- VISA PVV uses the common PAN/PVKI/PIN assembly described in the inline comments

## 9) Key Derivation, Generation, And Validation

Operations:
- `Derive DUKPT TDES Key` — TDES DUKPT (10-byte KSN, IPEK-based)
- `Derive DUKPT AES Key` — AES-128 DUKPT per ANSI X9.24-3 (12-byte KSN, IK-based)
- `Derive ECDH Key Material`
- `Generate Key` — random AES-128/192/256, TDES, or custom bytes; optional AES CMAC KCV
- `Calculate Payment KCV`
- `Generate AS2805 KEK Validation`

Use this when:
- you need transaction keys, shared secrets, random test keys, KCVs, or AS2805-style KEK-validation lab values

Important assumptions:
- `Derive DUKPT TDES Key` is TDES DUKPT — do not confuse IPEK (TDES) with IK (AES DUKPT)
- `Derive DUKPT AES Key` implements AES-128 via AES-CMAC per ANSI X9.24-3; AES-192/256 are not yet implemented
- `Generate Key` is for test use only — production keys must be generated in an approved HSM
- `Generate AS2805 KEK Validation` is an emulation-oriented helper and explicitly documents its simplifications in the operation comments

## 10) Key Container And HSM Command Inspection

Operations:
- `Parse Thales payShield Command`
- `Parse Futurex Excrypt Command`
- `Parse TR-31 Key Block`
- `Parse TR-34 Key Transport`

Use this when:
- you need to inspect vendor HSM command syntax, wrapped-key material, or transport frames during testing

Input:
- `Parse Thales payShield Command`: raw legacy host command or response text
- `Parse Futurex Excrypt Command`: raw bracketed Excrypt command or response text
- `Parse TR-31 Key Block` / `Parse TR-34 Key Transport`: full payload as text or hex, depending on the operation comment

Important assumptions:
- the Thales and Futurex parsers currently focus on visible message syntax, delimiters, command identification, and field splitting rather than deep per-command semantic decoding
- `Parse Thales payShield Command` expects the configured message-header length to be supplied in the op args
- `Parse Futurex Excrypt Command` treats Excrypt messages as delimiter-based tag/value fields and commonly uses the `AO` field as the command code
- `Parse TR-31 Key Block` decodes all X9.143 header fields with descriptions and PCI compliance flags
- `Parse TR-34 Key Transport` handles B0–B9 message types, error codes, and peeks at the outer ASN.1 SEQUENCE of the CMS envelope

## Chaining Patterns

## A) TDES DUKPT MAC

Operations:
- `Derive DUKPT TDES Key`
- `Generate Payment MAC`

Flow:
- derive the transaction key first if you want to inspect it
- or use a DUKPT MAC method directly in `Generate Payment MAC`
- use the same KSN and BDK on verify

## B) AES DUKPT Key Derivation

Operations:
- `Derive DUKPT AES Key`

Flow:
- provide the 16-byte BDK (or IK if you already have it) as hex input
- provide the 12-byte KSN (8-byte IKI + 4-byte counter) in the args
- select "Working Key" and a purpose (PIN Encryption, MAC Generation, Data Encryption, etc.)
- use JSON output to inspect the full BDK → IK → transaction key → working key chain

## C) ECDH Wrap / Unwrap

Operations:
- `Derive ECDH Key Material`
- `AES Key Wrap`
- `AES Key Unwrap`

Flow:
- derive the shared secret
- optionally run a KDF if you need a specific KEK size
- feed the resulting key into `AES Key Wrap` or `AES Key Unwrap`

Important assumption:
- this is not a full TR-34 or AWS `TranslateKeyMaterial` implementation by itself

## D) Clear PIN Block To Encrypted PIN Data

Operations:
- `Generate Payment PIN Data` or `Build PIN Block`
- `Encrypt Payment Data`

Flow:
- generate the clear ISO PIN block first
- encrypt that block under the desired AES or TDES profile

## E) EMV ARQC / ARPC Review

Operations:
- `Generate EMV ARQC`
- `Verify EMV ARQC`
- `Generate EMV ARPC`

Flow:
- build the exact request-data preimage outside the op
- generate or verify the ARQC with the derived session key
- build the response preimage and generate the ARPC

## F) EMV Script MAC And PIN Change

Operations:
- `Generate EMV MAC`
- `Verify EMV MAC`
- `Generate EMV MAC For PIN Change`

Flow:
- assemble the issuer-script APDU body as hex
- use the derived integrity key
- append the already-encrypted PIN block when generating the PIN-change MAC

## G) IBM 3624 / PVV Verification

Operations:
- `Generate IBM 3624 PIN Offset`
- `Verify IBM 3624 PIN`
- `Generate VISA PVV`
- `Verify VISA PVV`

Flow:
- keep the clear PIN in the input field
- keep issuer validation data, PAN, PVKI, decimalization table, and PVK in the args
- use the JSON output when you need to inspect how the verification artifact was assembled

## H) Brand Test Card Setup

Operations:
- `Generate Test PAN`
- `Parse PAN`
- `Generate Card Validation Data`
- `Generate Payment PIN Data`

Flow:
- generate a curated or locally generated brand-valid PAN
- parse it to confirm brand, card type hint, and Luhn validity
- feed the PAN into CVV, PIN, EMV, or parser recipes

## I) AS2805 KEK Validation

Operations:
- `Generate AS2805 KEK Validation`
- `Calculate Payment KCV`

Flow:
- inspect the KEK with `Calculate Payment KCV`
- generate request or response RandomKeySend / RandomKeyReceive values with the AS2805 helper

## J) Vendor Command Triage

Operations:
- `Parse Thales payShield Command`
- `Parse Futurex Excrypt Command`

Flow:
- paste the raw host message first before trying to interpret the business meaning
- use the parsed command code, delimiters, header, trailer, or tag/value split to confirm what family of command you are looking at
- follow with lower-level payment, EMV, PIN, or key-container recipes only after the transport syntax is understood

## K) Generate And Verify A Test Key

Operations:
- `Generate Key`
- `Calculate Payment KCV`

Flow:
- use `Generate Key` with JSON output to get a random AES-128/192/256 or TDES key plus its CMAC KCV
- cross-check the KCV with `Calculate Payment KCV` if you need to verify against an HSM-generated value
- pipe the hex key directly into derivation, MAC, or encryption recipes