exlim/cyberchef
2
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
cyberchef/PAYMENT_RECIPES.md
J8k3 d7a32d1293 docs: trim PAYMENT_RECIPES.md to dev reference, update AGENTS.md 
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>
2026-05-23 00:20:59 -04:00

8.3 KiB
Raw Blame History

Payment Operations Reference

Owner:

  • Jacob Marks, https://jacobmarks.com
  • Fork home: https://github.com/J8k3/CyberChef

User-facing workflow catalog, screenshots, and recipe links: 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

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: [Domain Prefix] [Verb] [Qualifier]

  • Domain prefixes: EMV, DUKPT, PIN Block, PIN Data, PIN IBM 3624, PAN, Card Validation Data, VISA PVV, AS2805, HSM, Payment, MAC, Key, TR-31, TR-34
  • 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
  • Only operations authored in this fork belong in the Payments category — do not add upstream CyberChef ops

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.).

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 Decrypt Data
  • Payment Re-Encrypt Data

MAC

  • MAC Generate
  • MAC Verify

EMV

  • 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
  • EMV Build Script Data
  • EMV Build PIN Change Script Data
  • EMV Generate MAC
  • EMV Verify MAC
  • EMV Generate MAC (PIN Change)
  • EMV Parse TLV

Card Validation

  • Card Validation Data Generate
  • Card Validation Data Verify
  • PAN Generate
  • PAN Parse

PIN

  • PIN Block Build
  • PIN Block Parse
  • PIN Block Translate
  • PIN Block Translate Encrypted
  • PIN Data Generate
  • PIN Data Verify
  • PIN IBM 3624 Offset Generate
  • PIN IBM 3624 Verify
  • VISA PVV Generate
  • VISA PVV Verify

DUKPT

  • DUKPT Derive TDES Key
  • DUKPT Derive AES Key

Key Management

  • Key Generate
  • Key Component Split
  • Key Component Combine
  • Payment Calculate KCV
  • Derive ECDH Key Material
  • AS2805 Generate KEK Validation

Key Containers / HSM

  • TR-31 Parse Key Block
  • TR-34 Parse Key Transport
  • HSM Parse Thales Command
  • HSM Parse Futurex Command

APC Comparison Testing

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

Name Hex
tdes_bdk 0123456789ABCDEFFEDCBA9876543210
aes_bdk FEDCBA98765432100123456789ABCDEF
tdes_dek1 0101010101010101FEFEFEFEFEFEFEFE
tdes_dek2 FEFEFEFEFEFEFEFE0101010101010101
tdes_m3 1111111111111111AAAAAAAAAAAAAAAA
aes_m6 000102030405060708090A0B0C0D0E0F
visa_pvk AAAABBBBCCCCDDDDEEEEFFFFAAAABBBB
ibm3624_pvk BBBBCCCCDDDDEEEEFFFFAAAABBBBCCCC
cvk CCCCDDDDEEEEFFFFAAAABBBBCCCCDDDD
emv_e0 101112131415161718191A1B1C1D1E1F
tdes_pek DDDDEEEEFFFFAAAABBBBCCCCDDDDEEEE
plaintext 0102030405060708
mac_msg 0102030405060708090A0B0C
pan_cvv 4123456789012345
pan_pvv 5432101234567890
service_code 101
pin 1234
ksn_tdes FFFF9876543210E00001
ksn_aes 123456789012345600000001
atc 0001

Results

Operation CyberChef Output APC Output Status Notes
Payment Encrypt Data (TDES ECB) B064B6C2571C65D5 B064B6C2571C65D5 ✅ MATCH
Payment Decrypt Data (TDES ECB) 0102030405060708 0102030405060708 ✅ MATCH
Payment Re-Encrypt Data — API error ❌ BLOCKED D0 keys with NoRestrictions rejected by APC re_encrypt_data — key-mode constraint, not a CyberChef bug
MAC Generate (ISO 9797-3, Method 1) D8749ECF9A6C6932 D8749ECF9A6C6932 ✅ MATCH
MAC Verify (ISO 9797-3) — PASS ✅
MAC Generate (AES-CMAC) E330EE80C0D43370 E330EE80C0D43370 ✅ MATCH
MAC Verify (AES-CMAC) — PASS ✅
EMV Generate MAC BEB0A99CA833D7C8 (Method 2) 1C36D79CE0F2F832 ⚠️ METHOD DEPENDENT Default (Method 2) does not match. Select Method 1 in the padding method arg for output that aligns with systems using zero-pad.
EMV Generate MAC (PIN Change) 3D9E060686858CC0 N/A ⚠️ N/A APC has no direct equivalent endpoint
Card Validation Data Generate (CVV) 703 703 ✅ MATCH
Card Validation Data Generate (CVV2) 111 111 ✅ MATCH
Card Validation Data Verify — PASS ✅
VISA PVV Generate 5596 (visa_pvk) / 6776 (test key) 5596 / 6776 (verify path) ✅ MATCH APC generate_pin_data blocked by compliance warning; cross-validated via verify_pin_data for both keys
VISA PVV Verify — PASS ✅ Both visa_pvk (KCV AAAABBBB…) and test key 0123456789ABCDEF… (KCV 08D7B4) confirmed via APC verify_pin_data
PIN IBM 3624 Offset Generate 0324 0324 (verify path) ✅ MATCH Cross-validated via APC verify_pin_data
PIN IBM 3624 Verify — PASS ✅
EMV Generate ARQC 8C8E19CED4DBBF59 AES-128 rejected ❌ BLOCKED APC verify_auth_request_cryptogram requires AES-256 E0 key; AES-128 rejected. CyberChef implementation (AES-CMAC, Option A session-key derivation) is correct
DUKPT Derive TDES Key IPEK 6AC292FAA1315B4D858AB3A3D7D5933A N/A ✅ VERIFIED Matches published ANSI X9.24-1 test vector
DUKPT Derive AES Key IK/working keys derived N/A ✅ VERIFIED Verified against ANSI X9.24-3 §6.3 official test vectors; APC does not expose derived intermediate keys for direct comparison
DUKPT TDES Encrypt (Payment Encrypt Data) 92A5157E4607D1B0 124F7A32F3F84187 ❌ VARIANT MISMATCH CyberChef follows ANSI X9.24-1 "Data" variant (bytes 5+13 XOR 0xFF); APC uses an undocumented internal variant for data encryption
DUKPT TDES MAC (MAC Generate) AF59E7E8A06F01B2 AF59E7E8A06F01B2 ✅ MATCH APC DukptKeyVariant=REQUEST aligns with CyberChef "MAC Request"

Key Findings

  • APC mac_length is in nibbles (hex digits), not bytes — pass 16 to get an 8-byte MAC.
  • EMV Generate MAC padding method — EMV Generate MAC defaults to Method 2 (ISO 7816-4; standard for EMV issuer scripts). Select Method 1 (zero pad) when the receiving system requires it. Both generate and verify must use the same method.
  • DUKPT TDES data encryption variant — CyberChef follows ANSI X9.24-1 standard (bytes 5 and 13 XOR 0xFF for the "Data" variant). APC applies a different undocumented internal variant. DUKPT MAC operations align correctly (both use MAC Request / REQUEST variant).
  • EMV ARQC requires AES-256 on APC — verify_auth_request_cryptogram rejects AES-128 E0 keys. If testing ARQC against APC, an AES-256 E0 master key is required. CyberChef's AES-CMAC + Option A session-key derivation is standard-compliant.
  • Re-encrypt key mode constraint — D0 keys imported into APC with NoRestrictions: true are blocked by re_encrypt_data. This is an APC API constraint, not a CyberChef limitation.

References