diff --git a/PAYMENT_RECIPES.md b/PAYMENT_RECIPES.md index 5ea0af5c..fe965b6b 100644 --- a/PAYMENT_RECIPES.md +++ b/PAYMENT_RECIPES.md @@ -9,18 +9,27 @@ These recipe starters are for software-only payment-crypto emulation, inspection 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, KCV, and parser utilities next +- 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` @@ -38,6 +47,7 @@ Important assumptions: - 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` @@ -69,6 +79,7 @@ Important assumptions: - EMV MAC is handled by the dedicated EMV MAC operations below ## 3) Generate / Verify EMV MAC + Operations: - `Generate EMV MAC` - `Verify EMV MAC` @@ -88,6 +99,7 @@ Important assumptions: - `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` @@ -105,6 +117,7 @@ Important assumptions: - these operations do not assemble CDOL data or derive issuer/session keys ## 5) Generate / Verify Card Validation Data + Operations: - `Generate Test PAN` - `Parse PAN` @@ -123,6 +136,7 @@ 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` @@ -131,20 +145,21 @@ 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, IIN, length, and Luhn validity before continuing +- you want to confirm network, card type hint, IIN, length, and Luhn validity before continuing + +## 6) Generate / Verify Payment PIN Data -## 6) Generate / Translate / Verify Payment PIN Data Operations: - `Generate Payment PIN Data` -- `Translate 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 -- `Translate Payment PIN Data`: clear PIN block hex - `Verify Payment PIN Data`: clear PIN block hex Important assumptions: @@ -152,6 +167,7 @@ Important assumptions: - 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` @@ -169,6 +185,7 @@ 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` @@ -186,43 +203,52 @@ Important assumptions: - 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 And Validation +## 9) Key Derivation, Generation, And Validation + Operations: -- `Derive DUKPT Key` +- `Derive DUKPT 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, KCVs, or AS2805-style KEK-validation lab values +- you need transaction keys, shared secrets, random test keys, KCVs, or AS2805-style KEK-validation lab values Important assumptions: -- `Derive DUKPT Key` is TDES DUKPT, not AES DUKPT +- `Derive DUKPT 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 B9 envelope` +- `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 B9 envelope`: full payload as text or hex, depending on the operation comment +- `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 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) DUKPT MAC +## A) TDES DUKPT MAC + Operations: - `Derive DUKPT Key` - `Generate Payment MAC` @@ -232,7 +258,19 @@ Flow: - or use a DUKPT MAC method directly in `Generate Payment MAC` - use the same KSN and BDK on verify -## B) ECDH Wrap / Unwrap +## 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` @@ -246,7 +284,8 @@ Flow: Important assumption: - this is not a full TR-34 or AWS `TranslateKeyMaterial` implementation by itself -## C) Clear PIN Block To Encrypted PIN Data +## D) Clear PIN Block To Encrypted PIN Data + Operations: - `Generate Payment PIN Data` or `Build PIN Block` - `Encrypt Payment Data` @@ -255,16 +294,8 @@ Flow: - generate the clear ISO PIN block first - encrypt that block under the desired AES or TDES profile -## D) Re-Encrypt Payment Data -Operations: -- `Re-Encrypt Payment Data` - -Flow: -- define the source decrypt profile -- define the target encrypt profile -- keep the payload in hex end to end - ## E) EMV ARQC / ARPC Review + Operations: - `Generate EMV ARQC` - `Verify EMV ARQC` @@ -276,6 +307,7 @@ Flow: - build the response preimage and generate the ARPC ## F) EMV Script MAC And PIN Change + Operations: - `Generate EMV MAC` - `Verify EMV MAC` @@ -287,6 +319,7 @@ Flow: - 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` @@ -299,6 +332,7 @@ Flow: - 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` @@ -307,10 +341,11 @@ Operations: Flow: - generate a curated or locally generated brand-valid PAN -- parse it to confirm brand and Luhn validity +- 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` @@ -320,11 +355,23 @@ Flow: - generate request or response RandomKeySend / RandomKeyReceive values with the AS2805 helper ## J) Vendor Command Triage + Operations: -- `Parse Thales payShield command` -- `Parse Futurex Excrypt command` +- `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