Add payment cryptography emulation operations, recipes, and validation guardrails by J8k3 · Pull Request #2334 · gchq/CyberChef

J8k3 · 2026-04-25T22:50:14Z

Summary

This PR adds a payment-focused extension surface to CyberChef for software emulation, testing, interoperability work, and education.

It is intentionally documented as software-only tooling rather than a certified HSM or production key-custody surface. AI was used to ensure payment functionality is implemented per specifications or as close to as is possible with publicly available documentation.

What This Adds

A new Payments category with payment-facing operations for:
- data encryption / decryption / re-encryption
- MAC generation / verification
- EMV ARQC / ARPC / MAC helpers
- clear PIN block build / parse / translate
- card validation data
- DUKPT / ECDH / KCV helpers
- test PAN generation / parsing
- TR-31 / TR-34 inspection helpers
Payment recipe and chaining docs:
- PAYMENT_RECIPES.md
- AWS_PAYMENT_CRYPTOGRAPHY_RECIPES.md
- PAYMENT_SIM_RECIPES.md
A validation audit with explicit guardrails:
- PAYMENT_VALIDATION_AUDIT.md
UI improvements for payment operations:
- inline recipe-card guidance
- visible validation / scope / security wording
- built-in test-data population helpers

Validation / Guardrails

The payment operations are explicitly classified in PAYMENT_VALIDATION_AUDIT.md as:

verified against public standards / vectors
vendor-aligned
externally cross-checked
emulation helpers

That status is also surfaced inline on higher-risk operations so users can see scope and limitations in the recipe UI.

Scope Notes

Intended for software emulation, QA, interoperability, and educational use.
Not a certified HSM implementation.
Not presented as a PCI-scoped production key-custody surface.

Verification

Docker build completed successfully from this branch.
Payment-focused vectors and operation tests were added/expanded in tests/operations/tests/Payment.mjs.
Common recipe chains are documented explicitly in the payment docs.

Added a section for Payment Cryptography Extensions detailing the scope, future extensions, non-goals, and organization of custom operations.

CLAassistant · 2026-04-25T22:50:21Z

All committers have signed the CLA.

Merged into a broader workflow that also does builds.

Added steps to install brotli and decompress build files.

Updated links and descriptions for CyberChef Payments.

Revise README for CyberChef Payments updates

- Fix operations path: payment-crypto/ subdirectory never existed; ops live in src/core/operations/ - Fix UI category name: "Payment Cryptography" -> "Payments" - Replace stale future-extensions list with accurate current coverage (DUKPT, PIN blocks, MAC/KCV, EMV, card validation, PAN tools all implemented) - Keep only genuine remaining future work: TR-31 KBPK decryption and AES DUKPT Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

…tyle rule to AGENTS.md Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

Updated links for PIN and EMV generation recipes.

Updated the README to reflect the focus on payment cryptography operations, clarified the development status, and modified section headings.

Corrected typos and improved clarity in the README.

- EMV Build ARQC Data: assembles 10-field CDOL1 preimage from args; outputs hex (chainable into EMV Generate ARQC), JSON, or annotated TLV - EMV Parse ARQC Data: inverse; parses flat 33-byte CDOL1 hex back into named fields - Parse EMV TLV: BER-TLV parser with 102-entry EMV tag dictionary; handles constructed/nested tags, 1- and 2-byte tags, long-form lengths; dictionary mode lists all known tags - Shared libs: EmvCdol.mjs (CDOL1 field defs), EmvTlv.mjs (parser), EmvTlvDictionary.mjs (tag dict) - 12 new tests in Payment.mjs covering all three operations Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

- EMV Build ARPC Data: assembles ARPC preimage from named fields; Method 1 (Visa/Amex/Discover: ARQC+ARC, 10 bytes) and Method 2 (Mastercard: ARQC+CSU+optional PAD, 12-20 bytes); outputs hex (chainable into EMV Generate ARPC), JSON, or annotated - EMV Parse ARPC Data: inverse; parses hex preimage back into named fields by method - Shared lib EmvArpc.mjs with build/parse/format functions - 6 new tests in Payment.mjs Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

Also fixes expectedError test format (OperationErrors surface as result strings, not result.error) and updates PAYMENT_RECIPES.md docs. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

The one-way rule (CyberChef gaps → GitHub issue) didn't cover the return path. New paragraph: discoveries from CyberChef sessions (PCI rules, algorithm edge cases, HSM commands) must be written back into the MCP server in the same session. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

…nebreak 11 ESLint errors across 6 files introduced in the ARQC/ARPC/TLV/Script ops. Also document the constructor-JSDoc and operator-linebreak rules in AGENTS.md to prevent recurrence. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

eslint:tests catches Payment.mjs too — document that npx grunt eslint runs all five targets, not just eslint:core. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

Updated EMV-related recipes in the README.

Domain prefix must come first per AGENTS.md convention. All references updated: op file, Categories.json, tests, PAYMENT_RECIPES.md, lib comment. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

…berChef-Payments - Update opening: workflow-oriented tooling for engineering, debugging, interoperability, development, QA — replaces narrow regulated-env framing - Add explicit links to CyberChef-Payments (workflow catalog) and Payments (KB) near the top - Replace verbose recipe list (24 entries) with 7 representative examples; redirect to J8k3/CyberChef-Payments for the full catalog and screenshots - Fix typo: "Current coverage includes:h" -> "Current coverage includes:" - Rewrite validation section: remove "unfinished product" and "best validation we can do" — replace with scoped statement on standards, vectors, and APC comparison where APIs are comparable - Restructure: What this fork adds / Scope / Validation / Non-goals / Recipes Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

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>

…operations AES DUKPT IK JSON was missing ksn, iki, counter; working key was missing ksn. TDES DUKPT IPEK and session key JSON were missing ksn and bdk. Both now mirror the full derivation context, making json=true self-contained for debugging and cross-validation. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

…ES cipher profiles JSON output shape (covering recent ksn/bdk additions): - DUKPT Derive AES Key: IK JSON output includes ksn, iki, counter - DUKPT Derive TDES Key: IPEK JSON output includes ksn and bdk Payment cipher coverage (previously only AES CBC was tested): - Payment Encrypt/Decrypt Data: TDES ECB (APC cross-validated block 1) - Payment Encrypt/Decrypt Data: TDES CBC (derived from passing re-encrypt chain) - Payment Encrypt Data: DUKPT TDES ECB Data variant (ANSI X9.24-1; APC variant mismatch documented in test comment and PAYMENT_RECIPES.md) Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

…DES CBC Covers the remaining untested cipher profiles in PaymentEncryptData / PaymentDecryptData. Values are pinned from a clean run against the forge upstream library, catching regressions in mode selection, IV wiring, and padding behaviour without re-deriving cryptographic outputs. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

Align wording with the shared standard used across all four repos in this project family. No behavioral change — same rules, consistent text. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

Resolved conflicts from the weekly sync that had been failing since 2026-06-08: - README.md: kept fork branding (cyberchef.jacobmarks.com) and the [p01]-[p25] payment-recipe links, while adopting upstream's updated [10] recipe and new [13] entry (rewritten to the fork domain) so the newly-merged body references resolve. - tests/operations/index.mjs: accepted upstream's deletion. It is now auto-generated by generateOpsIndex.mjs during 'grunt configTests' (and gitignored), so the fork's custom-operation tests are still discovered from tests/operations/tests/. - .github/workflows/: restored to the fork's versions, matching the sync_upstream.yml behaviour (preserves build-and-deploy + sync). Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

…tore The weekly upstream sync hard-failed whenever upstream touched files the fork diverges on (README branding) or removed a now-generated file (tests/operations/index.mjs). It also had a latent bug: the workflow restore ran 'git checkout HEAD -- .github/workflows/' *after* the merge had already auto-committed, so HEAD was the merge commit and the restore was a no-op. - Merge with --no-commit so HEAD stays the pre-merge fork commit, making the workflow restore actually keep the fork's workflows. - Auto-resolve the two recurring conflicts: keep the fork's README, and honour upstream deletions of generated/gitignored files. - Fail loudly (and abort the merge) on any other, unexpected conflict instead of pushing a half-resolved tree. - Exit cleanly when already up to date. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

The v11 sync changed the AESEncrypt/AESDecrypt operation argument layouts (purely additive): - AESDecrypt inserted 'ivLength' at args[2] and appended 'ivFromInput' at args[8]. - AESEncrypt appended 'Include IV in output' at args[6]. PaymentDataCipher still passed the old positional layout, so AESDecrypt read args[7].string off undefined, erroring the 4 Payment Decrypt/ Re-Encrypt tests. Realign both call sites; pass ivFromInput/includeIV 'Off' to preserve the prior behaviour (IV supplied explicitly, never sliced from or prepended to the data). Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

# Conflicts: # README.md

HackingRepo · 2026-06-22T11:48:18Z

@C85297 and @GCHQDeveloper581 those is the kind of PRs introduce vulns and complexity and bugs and massive attack surface because massive code added and diffucult to review, just one mistake will lead to vulns, it need careful review

J8k3 and others added 11 commits February 5, 2026 13:43

Add Payment Cryptography Extensions section to README

8980005

Added a section for Payment Cryptography Extensions detailing the scope, future extensions, non-goals, and organization of custom operations.

Add payment validation and EMV test operations

7433b07

Add payment MAC wrapper operations

3f1b633

Add AWS-style payment wrapper operations

71b0a98

Normalize payment operation names to Camel Case

96a2945

Expand payment parity coverage and chaining docs

1f82976

Add payment PAN generators and fix populated label state

83cdab4

Add payment validation audit and release guardrails

0473b81

Add upstream PR draft for payment work

e59df59

Merge upstream/master into master

e2dfbc4

Trim upstream PR draft

535a466

Fix payment data populate test samples

f17550c

C85297 added the AI Used label Apr 27, 2026

J8k3 and others added 16 commits May 1, 2026 13:35

Merge branch 'master' into master

023d11c

Add workflow to sync with upstream repository

bd05814

Configure Git user for upstream sync in workflow

4c6054a

Update token for GitHub actions in workflow

9a40d19

Merge remote-tracking branch 'upstream/master'

8c10113

Add GitHub Actions workflow for S3 deployment

9b82581

Add GitHub Actions workflow for build and deploy

3346e22

Delete .github/workflows/deploy.yml

0a544fb

Merged into a broader workflow that also does builds.

Update expected result length in chef.help test

f93e7bb

Install brotli and add decompression steps

f7dcf46

Added steps to install brotli and decompress build files.

Revise README for CyberChef Payments updates

337457f

Updated links and descriptions for CyberChef Payments.

Merge pull request #1 from J8k3/J8k3-patch-1

e1b5ae5

Revise README for CyberChef Payments updates

Update payment metadata and restore Docker test baseline

9e99048

Add Thales payShield command parser

1aa5468

Allow overriding test timeout

5cc3849

J8k3 and others added 12 commits May 20, 2026 22:22

Fix lint: expand inline try/catch in KeyComponentCombine; add brace-s…

c44873a

…tyle rule to AGENTS.md Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

Revise CyberChef recipes in README

8d45d90

Updated links for PIN and EMV generation recipes.

Revise README for CyberChef Payments focus

a87e24c

Updated the README to reflect the focus on payment cryptography operations, clarified the development status, and modified section headings.

Fix typos and enhance README clarity

f90fba9

Corrected typos and improved clarity in the README.

Add EMV Build Script Data and Build PIN Change Script Data operations

eeb16ea

Also fixes expectedError test format (OperationErrors surface as result strings, not result.error) and updates PAYMENT_RECIPES.md docs. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

Docs: add EMV Build Script Data ops to PAYMENT_RECIPES.md

a35b5aa

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

Enforce same-commit docs + APC check rule in AGENTS.md

2b9c92b

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

Fix lint: comma-spacing in Payment.mjs test; document full lint command

a44fc20

eslint:tests catches Payment.mjs too — document that npx grunt eslint runs all five targets, not just eslint:core. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

J8k3 force-pushed the master branch from 8c51caf to a44fc20 Compare May 22, 2026 00:03

J8k3 and others added 5 commits May 21, 2026 22:33

Modify EMV recipes in README.md

040da1f

Updated EMV-related recipes in the README.

Rename Parse EMV TLV → EMV Parse TLV (naming convention)

c7a4b63

Domain prefix must come first per AGENTS.md convention. All references updated: op file, Categories.json, tests, PAYMENT_RECIPES.md, lib comment. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

J8k3 force-pushed the master branch from 7cdffeb to 4ce7860 Compare May 23, 2026 14:53

J8k3 and others added 10 commits May 23, 2026 13:03

docs: standardize Session Start and Commit Scope in AGENTS.md

db1e72d

Align wording with the shared standard used across all four repos in this project family. No behavioral change — same rules, consistent text. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

Merge remote-tracking branch 'upstream/master'

7830bac

Merge remote-tracking branch 'upstream/master'

8dd1f09

docs(agents): clarify lint runs locally on W: share, not Docker

65fc961

Merge remote-tracking branch 'upstream/master'

edacc3f

# Conflicts: # README.md

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Add payment cryptography emulation operations, recipes, and validation guardrails#2334

Add payment cryptography emulation operations, recipes, and validation guardrails#2334
J8k3 wants to merge 119 commits into
gchq:masterfrom
J8k3:master

J8k3 commented Apr 25, 2026 •

edited

Loading

Uh oh!

CLAassistant commented Apr 25, 2026 •

edited

Loading

Uh oh!

HackingRepo commented Jun 22, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

Uh oh!

Conversation

J8k3 commented Apr 25, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

What This Adds

Validation / Guardrails

Scope Notes

Verification

Uh oh!

CLAassistant commented Apr 25, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

HackingRepo commented Jun 22, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

J8k3 commented Apr 25, 2026 •

edited

Loading

CLAassistant commented Apr 25, 2026 •

edited

Loading