Update PAYMENT_RECIPES.md: fix stale names, add new operations, naming convention section
This commit is contained in:
Jacob Marks
parent
c32be5a5c5
commit
5e473899ea
@ -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
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user