exlim/cyberchef
2
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: trim PAYMENT_RECIPES.md to dev reference, update AGENTS.md

Browse Source 
PAYMENT_RECIPES.md was duplicating content now maintained in
J8k3/CyberChef-Payments (recipe catalog, chaining patterns, validation
status). Trimmed to: naming conventions, operation registry, raw APC
comparison test vectors + results. Added pointer to CyberChef-Payments.

AGENTS.md updated:
- Pre-commit checklist now says: update PAYMENT_RECIPES.md operation
  registry + CyberChef-Payments README if op appears in catalog
- Added paragraph clarifying the two-file split (dev vs. user-facing)
- Naming convention step now explicitly calls out CyberChef-Payments

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
This commit is contained in:
J8k3 2026-05-23 00:20:59 -04:00
parent a50b1f6faf
commit d7a32d1293
2 changed files with 44 additions and 433 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

9
AGENTS.md
View File

@ -68,16 +68,19 @@ This check is for internal development and validation only. APC must never appea
After completing any substantive payment operation work, ask: *"Did I learn anything in this session that isn't captured in AGENTS.md?"* If yes, add it before committing. After completing any substantive payment operation work, ask: *"Did I learn anything in this session that isn't captured in AGENTS.md?"* If yes, add it before committing.
**Before committing any new or changed payment operation, verify all of the following are in the same commit:** **Before committing any new or changed payment operation, verify all of the following are in the same commit:**
- `PAYMENT_RECIPES.md` updated (numbered section + lettered chaining entry if new pattern) - `PAYMENT_RECIPES.md` Operation Registry updated (add/rename/remove the op name)
- `J8k3/CyberChef-Payments` README updated if the op appears in the recipe catalog or validation table
- APC-agent queried for the relevant endpoint and any gap documented - APC-agent queried for the relevant endpoint and any gap documented
- Tests passing - Tests passing
Do not commit the operation first and defer docs or APC check to a follow-up. If the user has to ask whether the docs were updated, the process was not followed. Do not commit the operation first and defer docs or APC check to a follow-up. If the user has to ask whether the docs were updated, the process was not followed.
`PAYMENT_RECIPES.md` is the **developer reference** for this repo: naming conventions, operation registry, and raw APC test vectors. The user-facing recipe catalog, chaining patterns, and validation status live in [J8k3/CyberChef-Payments](https://github.com/J8k3/CyberChef-Payments). Do not duplicate catalog content in `PAYMENT_RECIPES.md`.
When adding, renaming, or removing a payment operation: When adding, renaming, or removing a payment operation:
1. **Update `PAYMENT_RECIPES.md`** — add the operation to the correct numbered section and, if it introduces a new chaining pattern, add a lettered chaining pattern entry. Remove or mark deprecated any operations that are replaced. 1. **Update `PAYMENT_RECIPES.md` Operation Registry** — add, rename, or remove the operation name from the relevant domain group. Remove or mark deprecated any operations that are replaced.
2. **Follow the naming convention** — all payment operation display names use Title Case. Acronyms (DUKPT, AES, EMV, MAC, PAN, TR-31, TR-34, KCV) stay upper-case. Brand names keep their canonical form (`payShield`). Pattern: `[Domain Prefix] [Verb] [Qualifier]` — the domain/protocol prefix comes first so operations sort and scan by topic in the UI list. Example: `EMV Verify MAC`, `DUKPT Derive TDES Key`, `PIN Block Parse`. When a vendor name is a sub-specifier of a PIN method, embed it after the PIN domain prefix: `PIN IBM 3624 Offset Generate`, `PIN IBM 3624 Verify`. See the Naming Convention section in `PAYMENT_RECIPES.md`. 2. **Follow the naming convention** — all payment operation display names use Title Case. Acronyms (DUKPT, AES, EMV, MAC, PAN, TR-31, TR-34, KCV) stay upper-case. Brand names keep their canonical form (`payShield`). Pattern: `[Domain Prefix] [Verb] [Qualifier]` — the domain/protocol prefix comes first so operations sort and scan by topic in the UI list. Example: `EMV Verify MAC`, `DUKPT Derive TDES Key`, `PIN Block Parse`. When a vendor name is a sub-specifier of a PIN method, embed it after the PIN domain prefix: `PIN IBM 3624 Offset Generate`, `PIN IBM 3624 Verify`. See the Naming Convention section in `PAYMENT_RECIPES.md`. **Also update the `J8k3/CyberChef-Payments` README** if the op appears in the recipe catalog.
3. **Only operations written for this fork belong in the Payments category** — do not add upstream CyberChef ops (AES Encrypt, HMAC, CMAC, Triple DES Encrypt, AES Key Wrap, etc.) even as convenience shortcuts. If an op wasn't authored here, it stays in its own upstream category only. 3. **Only operations written for this fork belong in the Payments category** — do not add upstream CyberChef ops (AES Encrypt, HMAC, CMAC, Triple DES Encrypt, AES Key Wrap, etc.) even as convenience shortcuts. If an op wasn't authored here, it stays in its own upstream category only.
4. **Keep `this.name` and file name consistent** — the CyberChef UI shows `this.name`; the file name is the class name in PascalCase. Both should reflect the same intent. 4. **Keep `this.name` and file name consistent** — the CyberChef UI shows `this.name`; the file name is the class name in PascalCase. Both should reflect the same intent.
5. **Do not rename `this.name` without updating `PAYMENT_RECIPES.md`** — stale names in the doc are confusing and break recipe search. 5. **Do not rename `this.name` without updating `PAYMENT_RECIPES.md`** — stale names in the doc are confusing and break recipe search.

468
PAYMENT_RECIPES.md
View File

@ -1,11 +1,14 @@
# Payment Recipe Starters # Payment Operations Reference
Owner: Owner:
- Jacob Marks, `https://jacobmarks.com` - Jacob Marks, `https://jacobmarks.com`
- Fork home: `https://github.com/J8k3/CyberChef` - Fork home: `https://github.com/J8k3/CyberChef`
These recipe starters are for software-only payment-crypto emulation, inspection, regression tests, and interoperability work. **User-facing workflow catalog, screenshots, and recipe links:** [J8k3/CyberChef-Payments](https://github.com/J8k3/CyberChef-Payments)
This file is the **developer reference** for the implementation repo. It covers naming conventions, the operation registry, and raw APC comparison test data. Do not duplicate recipe catalog content here — maintain it in CyberChef-Payments to avoid divergence.
---
## Naming Convention ## Naming Convention
@ -16,476 +19,82 @@ Pattern: `[Domain Prefix] [Verb] [Qualifier]`
- Verbs: Generate, Verify, Parse, Build, Translate, Derive, Calculate, Encrypt, Decrypt, Re-Encrypt - Verbs: Generate, Verify, Parse, Build, Translate, Derive, Calculate, Encrypt, Decrypt, Re-Encrypt
- The prefix comes first so operations sort and scan by topic in the UI list - The prefix comes first so operations sort and scan by topic in the UI list
- Only operations authored in this fork belong in the Payments category — do not add upstream CyberChef ops - Only operations authored in this fork belong in the Payments category — do not add upstream CyberChef ops
- When adding a new payment operation, follow this pattern and update this file.
## UI Arrangement ## UI Arrangement
The `Payments` category is sorted alphabetically. The domain-prefix naming convention means related operations naturally cluster together in the list (all EMV ops together, all PIN Block ops together, etc.). The `Payments` category is sorted alphabetically. The domain-prefix naming convention means related operations naturally cluster together in the list (all EMV ops together, all PIN Block ops together, etc.).
## 1) Encrypt / Decrypt / Re-Encrypt Payment Data ---
Operations: ## Operation Registry
Operations in the **Payments** category, grouped by domain. Update this list when adding, renaming, or removing an operation.
**Encrypt / Decrypt**
- `Payment Encrypt Data` - `Payment Encrypt Data`
- `Payment Decrypt Data` - `Payment Decrypt Data`
- `Payment Re-Encrypt Data` - `Payment Re-Encrypt Data`
Use this when: **MAC**
- 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:
- `MAC Generate` - `MAC Generate`
- `MAC Verify` - `MAC Verify`
Supported methods: **EMV**
- `HMAC SHA-224` - `EMV Build ARQC Data`
- `HMAC SHA-256` - `EMV Parse ARQC Data`
- `HMAC SHA-384` - `EMV Generate ARQC`
- `HMAC SHA-512` - `EMV Verify ARQC`
- `AES-CMAC` - `EMV Build ARPC Data`
- `TDES-CMAC` - `EMV Parse ARPC Data`
- `ISO 9797-1 Algorithm 1` - `EMV Generate ARPC`
- `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:
- `EMV Build Script Data` - `EMV Build Script Data`
- `EMV Build PIN Change Script Data` - `EMV Build PIN Change Script Data`
- `EMV Generate MAC` - `EMV Generate MAC`
- `EMV Verify MAC` - `EMV Verify MAC`
- `EMV Generate MAC (PIN Change)` - `EMV Generate MAC (PIN Change)`
Use this when:
- you want to assemble an issuer-script APDU from named fields
- 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:
- `EMV Build Script Data` / `EMV Build PIN Change Script Data`: all fields supplied via args; ignores the input field — use as the first step in a chained recipe
- `EMV Generate MAC` / `EMV Verify MAC`: issuer-script APDU as hex
- `EMV Generate MAC (PIN Change)`: 5-byte CHANGE REFERENCE DATA header as hex (from `EMV Build PIN Change Script Data`)
Important assumptions:
- these operations do not derive EMV session keys
- `EMV Build Script Data` assembles `CLA | INS | P1 | P2 | Lc | Data`; Lc is computed from data length
- `EMV Build PIN Change Script Data` assembles only the 5-byte command header (`84 24 P1 P2 Lc`); the encrypted PIN block is appended by `EMV Generate MAC (PIN Change)` before computing the MAC
- `EMV Generate MAC (PIN Change)` models a single session integrity key (E2); a full issuer implementation uses three separate keys (E2 integrity, E1 confidentiality, P0 PIN encryption)
- `EMV Generate MAC` and `EMV Verify MAC` expose a **Padding method** selector:
- **Method 2 (default)** — appends `0x80` then zero-pads to the next 8-byte block boundary (ISO 7816-4). Standard for EMV issuer-script MACs.
- **Method 1** — zero-pads to the next block boundary only (no `0x80` sentinel). Used by some host-side implementations and required when interoperating with systems that apply Method 1.
- Both generate and verify must use the same method or verification will always fail.
- `EMV Generate MAC (PIN Change)` always uses Method 2 and does not expose the selector
- `EMV Generate MAC (PIN Change)` expects the new PIN block to already be encrypted before you call it
Recommended chain:
- `EMV Build Script Data` → `EMV Generate MAC`
- `EMV Build PIN Change Script Data` → `EMV Generate MAC (PIN Change)`
## 4) Generate / Verify EMV ARQC And ARPC
Operations:
- `EMV Build ARQC Data`
- `EMV Parse ARQC Data`
- `EMV Generate ARQC`
- `EMV Verify ARQC`
- `EMV Generate ARPC`
- `EMV Build ARPC Data`
- `EMV Parse ARPC Data`
- `EMV Parse TLV` - `EMV Parse TLV`
Use this when: **Card Validation**
- you want to assemble or inspect ARQC/ARPC preimage data by named field
- you already know the exact preassembled EMV data block
- you already have the derived EMV session key
- you need to parse BER-TLV encoded EMV data (DE 55, ICC responses)
Input:
- `EMV Build ARQC Data` / `EMV Build ARPC Data`: all fields supplied via args; ignores the input field — use as the first step in a chained recipe
- `EMV Parse ARQC Data` / `EMV Parse ARPC Data`: flat hex preimage
- `EMV Generate ARQC` / `EMV Verify ARQC` / `EMV Generate ARPC`: preassembled EMV data as hex
- `EMV Parse TLV`: BER-TLV encoded hex (DE 55, ICC response, GPO response)
Important assumptions:
- CDOL1 structure is network-agnostic: the same 10-field 33-byte layout applies across Visa, Mastercard, Amex, Discover, and JCB
- ARPC has two structural variants: Method 1 (Visa/Amex/Discover) and Method 2 (Mastercard) — select the correct method in the arg
- current ARQC/ARPC coverage is the AES-CMAC profile; session-key derivation is not performed here
Recommended chain:
- `EMV Build ARQC Data` → `EMV Generate ARQC` → `EMV Verify ARQC`
## 5) Generate / Verify Card Validation Data
Operations:
- `PAN Generate`
- `PAN Parse`
- `Card Validation Data Generate` - `Card Validation Data Generate`
- `Card Validation Data Verify` - `Card Validation Data Verify`
- `PAN Generate`
- `PAN Parse`
Profiles: **PIN**
- `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
- `PAN Parse` now outputs `cardType`, `cardTypeConfidence`, and `majorIndustryIdentifierDescription` in addition to network and Luhn fields
Recommended chain:
- `PAN Generate` -> `PAN Parse` -> `Card Validation Data Generate`
Use `PAN Generate` when:
- you want a Visa, Mastercard, American Express, or Discover PAN to feed into later recipes
Use `PAN Parse` when:
- you want to confirm network, card type hint, IIN, length, and Luhn validity before continuing
## 6) Generate / Verify Payment PIN Data
Operations:
- `PIN Data Generate`
- `PIN Data Verify`
> **Note:** Encrypted PIN block translation is implemented as `PIN Block Translate Encrypted` (section 7). Use `PIN Block Translate` for clear-format-to-format conversion only.
Use this when:
- you want AWS-style PIN-data naming for clear ISO 9564 block flows
Input:
- `PIN Data Generate`: clear PIN digits
- `PIN Data Verify`: 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:
- `PIN Block Build` - `PIN Block Build`
- `PIN Block Parse` - `PIN Block Parse`
- `PIN Block Translate` - `PIN Block Translate`
- `PIN Block Translate Encrypted` - `PIN Block Translate Encrypted`
- `PIN Data Generate`
Use this when: - `PIN Data Verify`
- you want the lower-level clear PIN-block tools directly
- `PIN Block Translate Encrypted`: decrypt an encrypted PIN block under an incoming zone key (ZPK/PEK), optionally change format, and re-encrypt under an outgoing zone key — this is the acquirer's core PIN routing operation (issue #17)
Input:
- `PIN Block Build`: clear PIN digits
- `PIN Block Parse`: clear PIN block hex
- `PIN Block Translate`: clear PIN block hex
- `PIN Block Translate Encrypted`: encrypted PIN block hex (8 bytes / 16 hex chars)
Important assumptions:
- current clear-block support is ISO formats `0`, `1`, and `3`
- `PIN Block Translate Encrypted` uses TDES-ECB; accepts 2-key (16-byte) or 3-key (24-byte) keys
## 8) Issuer PIN Verification Helpers
Operations:
- `PIN IBM 3624 Offset Generate` - `PIN IBM 3624 Offset Generate`
- `PIN IBM 3624 Verify` - `PIN IBM 3624 Verify`
- `VISA PVV Generate` - `VISA PVV Generate`
- `VISA PVV Verify` - `VISA PVV Verify`
Use this when: **DUKPT**
- 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:
- `DUKPT Derive TDES Key` — TDES DUKPT (10-byte KSN, IPEK-based)
- `DUKPT Derive AES Key` — AES-128 DUKPT per ANSI X9.24-3 (12-byte KSN, IK-based)
- `Derive ECDH Key Material`
- `Key Generate` — random AES-128/192/256, TDES, or custom bytes; optional AES CMAC KCV
- `Key Component Split` — XOR-split a key into 2–8 components for key ceremony use
- `Key Component Combine` — XOR-combine components back into the original key
- `Payment Calculate KCV`
- `AS2805 Generate KEK Validation`
Use this when:
- you need transaction keys, shared secrets, random test keys, KCVs, or AS2805-style KEK-validation lab values
Important assumptions:
- `Key Component Split` and `Key Component Combine` use XOR shares — all N components are required to reconstruct the key (no threshold/Shamir scheme)
- These operations are intended for testing and emulation, not production key ceremonies — production ceremonies must use a certified HSM
- `DUKPT Derive TDES Key` is TDES DUKPT — do not confuse IPEK (TDES) with IK (AES DUKPT)
- `DUKPT Derive AES Key` implements AES-128 via AES-CMAC per ANSI X9.24-3; AES-192/256 are not yet implemented
- `Key Generate` is for test use only — production keys must be generated in an approved HSM
- `AS2805 Generate KEK Validation` is an emulation-oriented helper and explicitly documents its simplifications in the operation comments
## 10) Key Container And HSM Command Inspection
Operations:
- `HSM Parse Thales Command`
- `HSM Parse Futurex Command`
- `TR-31 Parse Key Block`
- `TR-34 Parse Key Transport`
Use this when:
- you need to inspect vendor HSM command syntax, wrapped-key material, or transport frames during testing
Input:
- `HSM Parse Thales Command`: raw legacy host command or response text
- `HSM Parse Futurex Command`: raw bracketed Excrypt command or response text
- `TR-31 Parse Key Block` / `TR-34 Parse 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
- `HSM Parse Thales Command` expects the configured message-header length to be supplied in the op args
- `HSM Parse Futurex Command` treats Excrypt messages as delimiter-based tag/value fields and commonly uses the `AO` field as the command code
- `TR-31 Parse Key Block` decodes all X9.143 header fields with descriptions and PCI compliance flags
- `TR-34 Parse 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:
- `DUKPT Derive TDES Key` - `DUKPT Derive TDES Key`
- `MAC Generate`
Flow:
- derive the transaction key first if you want to inspect it
- or use a DUKPT MAC method directly in `MAC Generate`
- use the same KSN and BDK on verify
## B) AES DUKPT Key Derivation
Operations:
- `DUKPT Derive AES Key` - `DUKPT Derive AES Key`
Flow: **Key Management**
- provide the 16-byte BDK (or IK if you already have it) as hex input - `Key Generate`
- provide the 12-byte KSN (8-byte IKI + 4-byte counter) in the args - `Key Component Split`
- select "Working Key" and a purpose (PIN Encryption, MAC Generation, Data Encryption, etc.) - `Key Component Combine`
- 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:
- `PIN Data Generate` or `PIN Block Build`
- `Payment Encrypt 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:
- `EMV Build ARQC Data`
- `EMV Parse ARQC Data`
- `EMV Generate ARQC`
- `EMV Verify ARQC`
- `EMV Build ARPC Data`
- `EMV Parse ARPC Data`
- `EMV Generate ARPC`
Flow:
- use `EMV Build ARQC Data` (slot 1) to assemble the CDOL1 preimage from named fields
- generate or verify the ARQC with `EMV Generate ARQC` / `EMV Verify ARQC` using the derived session key
- use `EMV Build ARPC Data` (slot 1 of a second recipe) to assemble the ARPC preimage
- generate the ARPC with `EMV Generate ARPC`
- use `EMV Parse ARQC Data` / `EMV Parse ARPC Data` to reverse-parse any flat preimage hex back to named fields
## F) EMV Script MAC And PIN Change
Operations:
- `EMV Build Script Data`
- `EMV Build PIN Change Script Data`
- `EMV Generate MAC`
- `EMV Verify MAC`
- `EMV Generate MAC (PIN Change)`
Flow:
- use `EMV Build Script Data` (slot 1) to assemble the issuer-script APDU from CLA/INS/P1/P2/Data
- use `EMV Generate MAC` with the derived integrity key to compute and append the MAC
- for PIN change: use `EMV Build PIN Change Script Data` (slot 1) to build the `84 24 P1 P2 Lc` header, then use `EMV Generate MAC (PIN Change)` supplying the already-encrypted PIN block as an arg
## G) IBM 3624 / PVV Verification
Operations:
- `PIN IBM 3624 Offset Generate`
- `PIN IBM 3624 Verify`
- `VISA PVV Generate`
- `VISA PVV Verify`
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:
- `PAN Generate`
- `PAN Parse`
- `Card Validation Data Generate`
- `PIN Data Generate`
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:
- `AS2805 Generate KEK Validation`
- `Payment Calculate KCV` - `Payment Calculate KCV`
- `Derive ECDH Key Material`
- `AS2805 Generate KEK Validation`
Flow: **Key Containers / HSM**
- inspect the KEK with `Payment Calculate KCV` - `TR-31 Parse Key Block`
- generate request or response RandomKeySend / RandomKeyReceive values with the AS2805 helper - `TR-34 Parse Key Transport`
## J) Vendor Command Triage
Operations:
- `HSM Parse Thales Command` - `HSM Parse Thales Command`
- `HSM Parse Futurex Command` - `HSM Parse Futurex 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:
- `Key Generate`
- `Payment Calculate KCV`
Flow:
- use `Key Generate` with JSON output to get a random AES-128/192/256 or TDES key plus its CMAC KCV
- cross-check the KCV with `Payment Calculate KCV` if you need to verify against an HSM-generated value
- pipe the hex key directly into derivation, MAC, or encryption recipes
## Validation Status
Validation classes:
- `Verified` — backed by a public standard or official vendor documentation plus deterministic local vectors
- `Vendor-aligned` — behavior is intentionally shaped to AWS Payment Cryptography or scheme/vendor semantics; the full underlying standard is not publicly auditable here
- `Externally cross-checked` — checked against known-good vectors or an external implementation; the governing spec is not public here
- `Test helper` — useful for testing, parsing, or workflow emulation but not a full standards-faithful implementation
Release guidance: `Publish` = safe with normal guardrails; `Publish with guardrails` = keep inline Validation/Security/Assumptions warnings visible.
| Operation | Validation | Primary source(s) | Release |
| --- | --- | --- | --- |
| `PIN Block Build` | Vendor-aligned | AWS `GeneratePinData`; ISO 9564 | Publish with guardrails |
| `PIN Block Parse` | Vendor-aligned | AWS `VerifyPinData`; ISO 9564 | Publish with guardrails |
| `PIN Block Translate` | Vendor-aligned | AWS `TranslatePinData`; ISO 9564 | Publish with guardrails |
| `PIN Block Translate Encrypted` | Vendor-aligned | AWS `TranslatePinData`; ISO 9564; PCI PIN Req 3-3 | Publish with guardrails |
| `PIN Data Generate` | Vendor-aligned | AWS `GeneratePinData` | Publish with guardrails |
| `PIN Data Verify` | Vendor-aligned | AWS `VerifyPinData` | Publish with guardrails |
| `Key Component Split` | Verified | XOR key split — standard PCI key ceremony primitive | Publish with guardrails |
| `Key Component Combine` | Verified | XOR key combine — standard PCI key ceremony primitive | Publish with guardrails |
| `Payment Calculate KCV` | Verified | NIST SP 800-38B; generic AES/TDES/HMAC primitives | Publish |
| `DUKPT Derive TDES Key` | Externally cross-checked | ANSI X9.24-1; AWS DUKPT terminology | Publish with guardrails |
| `DUKPT Derive AES Key` | Externally cross-checked | ANSI X9.24-3 §6.3 official test vectors (x9.org) | Publish with guardrails |
| `Derive ECDH Key Material` | Verified | AWS `TranslateKeyMaterial`; AWS `EcdhDerivationAttributes`; RFC 3394 | Publish |
| `Payment Encrypt Data` | Vendor-aligned | AWS `EncryptData` | Publish with guardrails |
| `Payment Decrypt Data` | Vendor-aligned | AWS `DecryptData` | Publish with guardrails |
| `Payment Re-Encrypt Data` | Vendor-aligned | AWS `ReEncryptData` | Publish with guardrails |
| `MAC Generate` | Verified (HMAC/CMAC); Vendor-aligned (ISO9797/DUKPT/AS2805) | NIST SP 800-38B; AWS MAC overview | Publish with guardrails |
| `MAC Verify` | Verified (HMAC/CMAC); Vendor-aligned (ISO9797/DUKPT/AS2805) | NIST SP 800-38B; AWS MAC overview | Publish with guardrails |
| `EMV Build Script Data` | Verified | ISO 7816-4 APDU structure; EMV issuer script command layout | Publish |
| `EMV Build PIN Change Script Data` | Verified | ISO 7816-4 CHANGE REFERENCE DATA (INS=24); EMV Book 2 PIN change flow | Publish |
| `EMV Generate MAC` | Vendor-aligned | AWS EMV MAC use case | Publish with guardrails |
| `EMV Verify MAC` | Vendor-aligned | AWS EMV MAC use case | Publish with guardrails |
| `EMV Generate MAC (PIN Change)` | Test helper | AWS `GenerateMacEmvPinChange` | Publish with guardrails |
| `EMV Build ARQC Data` | Verified | CDOL1 field layout per EMV Book 3 §10.1 | Publish |
| `EMV Parse ARQC Data` | Verified | CDOL1 field layout per EMV Book 3 §10.1 | Publish |
| `EMV Generate ARQC` | Vendor-aligned | AWS `VerifyAuthRequestCryptogram` | Publish with guardrails |
| `EMV Verify ARQC` | Vendor-aligned | AWS `VerifyAuthRequestCryptogram` | Publish with guardrails |
| `EMV Generate ARPC` | Vendor-aligned | AWS `VerifyAuthRequestCryptogram` issuer flow | Publish with guardrails |
| `EMV Build ARPC Data` | Verified | EMV Book 2 §8.2 (Method 1); Mastercard M/Chip (Method 2) | Publish |
| `EMV Parse ARPC Data` | Verified | EMV Book 2 §8.2 (Method 1); Mastercard M/Chip (Method 2) | Publish |
| `EMV Parse TLV` | Verified | ISO 8825-1 BER-TLV; EMV Books 1–4; EMVCo contactless Book C | Publish |
| `Card Validation Data Generate` | Vendor-aligned | AWS `GenerateCardValidationData` | Publish with guardrails |
| `Card Validation Data Verify` | Vendor-aligned | AWS `VerifyCardValidationData` | Publish with guardrails |
| `PIN IBM 3624 Offset Generate` | Vendor-aligned | AWS IBM 3624 PIN verification object | Publish with guardrails |
| `PIN IBM 3624 Verify` | Vendor-aligned | AWS IBM 3624 PIN verification object | Publish with guardrails |
| `VISA PVV Generate` | Vendor-aligned | AWS VISA PIN verification object | Publish with guardrails |
| `VISA PVV Verify` | Vendor-aligned | AWS VISA PIN verification object | Publish with guardrails |
| `AS2805 Generate KEK Validation` | Test helper | AWS `GenerateAs2805KekValidation` | Publish with guardrails |
| `PAN Generate` | Verified (Luhn/public ranges); Vendor-aligned (curated samples) | Discover public test-card page; Mastercard public AVS scenarios | Publish with guardrails |
| `PAN Parse` | Verified | Public card numbering rules | Publish |
| `TR-31 Parse Key Block` | Test helper | AWS `TranslateKeyMaterial` workflow context | Publish with guardrails |
| `TR-34 Parse Key Transport` | Test helper | AWS `TranslateKeyMaterial` workflow context | Publish with guardrails |
| `HSM Parse Thales Command` | Test helper | Thales payShield command syntax reference | Publish with guardrails |
| `HSM Parse Futurex Command` | Test helper | Futurex Excrypt command syntax reference | Publish with guardrails |
### Release Posture
- Publish the current payment surface with its existing inline warnings intact
- Do not describe the fork as a certified HSM, production key-custody platform, or PCI-scoped control surface
- Describe it as a software emulation and interoperability tool for development, testing, and education
Pre-publish checklist:
1. Rebuild Docker and confirm updated recipe descriptions are visible in the UI
2. Re-run the payment operation subset tests (`npm test` targeting `Payment.mjs`)
3. Spot-check `Populate test data` on argument-heavy operations
## APC Comparison Testing ## APC Comparison Testing
Performed 2026-05-19. All HSM-mimic operations compared against AWS Payment Cryptography (APC) using fixed test vectors imported as APC managed keys. Keys were imported for testing only and scheduled for deletion immediately after. Performed 2026-05-19. HSM-style operations compared against AWS Payment Cryptography (APC) where APC exposed comparable behavior, using fixed test vectors imported as APC managed keys.
### Test Vectors ### Test Vectors
@ -556,4 +165,3 @@ Performed 2026-05-19. All HSM-mimic operations compared against AWS Payment Cryp
- RFC 3394 AES Key Wrap: https://www.rfc-editor.org/rfc/rfc3394 - RFC 3394 AES Key Wrap: https://www.rfc-editor.org/rfc/rfc3394
- Discover public test-card page: https://www.discoverglobalnetwork.com/resources/businesses/check-your-card-reader/ - Discover public test-card page: https://www.discoverglobalnetwork.com/resources/businesses/check-your-card-reader/
- Mastercard AVS test scenarios: https://static.developer.mastercard.com/content/mastercard-send-avs/uploads/avs-test-case-scenario-v4.pdf - Mastercard AVS test scenarios: https://static.developer.mastercard.com/content/mastercard-send-avs/uploads/avs-test-case-scenario-v4.pdf
- Payment card number background: https://en.wikipedia.org/wiki/Payment_card_number