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

Docs: AGENTS.md, PAYMENT_RECIPES.md, README.md updates

Browse Source 
- AGENTS.md: add APC cross-reference, security constraint, ESLint, and gap-filing instructions
- PAYMENT_RECIPES.md: DUKPT AES key status to Externally cross-checked; VISA PVV APC results updated with second key cross-check
- README.md: PIN Block Translate Encrypted in coverage list and recipe links

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
This commit is contained in:
J8k3 2026-05-20 21:49:34 -04:00
parent ffc5fcbf41
commit 79ac440b14
3 changed files with 27 additions and 5 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

18
AGENTS.md
View File

@ -35,6 +35,24 @@ Follow `CONTRIBUTING.md` coding conventions: 4-space indentation, CamelCase clas
- Only keep changes together when separating them would make the behavior harder to understand, test, or revert. - Only keep changes together when separating them would make the behavior harder to understand, test, or revert.
- Prefer squash or amend for related consecutive changes — if a follow-up commit only fixes or extends the immediately preceding commit, squash them into one rather than leaving a trail of iterative noise in the log. - Prefer squash or amend for related consecutive changes — if a follow-up commit only fixes or extends the immediately preceding commit, squash them into one rather than leaving a trail of iterative noise in the log.
## APC Cross-Reference (Standing Instruction)
Whenever a payment cryptography question arises — algorithm behavior, key types, format support, operation design, test vector validation — **first query the APC-agent MCP tools** to check what AWS Payment Cryptography exposes for that operation. Use ToolSearch to load the relevant tool before calling it.
If the data is not available via APC-agent (endpoint doesn't exist, key-mode constraint, API gap), **treat that as a documented gap** — file a GitHub issue at `J8k3/CyberChef` capturing the operation, what was tried, and what's needed to close it. Do not guess APC behavior from training data; use the live tools.
This check is for internal development and validation only. APC must never appear in CyberChef UI text (operation names, descriptions, inline help, arg labels).
## Security Constraint
**Never mention AWS, APC, or AWS Payment Cryptography in any CyberChef UI-facing text.** This includes operation names, descriptions, arg labels, inline help text, and output strings. Internal code comments and test file comments are fine.
## ESLint
- Continuation lines inside `args: [` must be aligned to **23 spaces**
- All module-level functions require JSDoc (`jsdoc/require-jsdoc`)
- No unused imports
## Payment Operation Maintenance ## Payment Operation Maintenance
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.

8
PAYMENT_RECIPES.md
View File

@ -398,7 +398,7 @@ Release guidance: `Publish` = safe with normal guardrails; `Publish with guardra
| `PIN Data Verify` | Vendor-aligned | AWS `VerifyPinData` | Publish with guardrails | | `PIN Data Verify` | Vendor-aligned | AWS `VerifyPinData` | Publish with guardrails |
| `Payment Calculate KCV` | Verified | NIST SP 800-38B; generic AES/TDES/HMAC primitives | Publish | | `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 TDES Key` | Externally cross-checked | ANSI X9.24-1; AWS DUKPT terminology | Publish with guardrails |
| `DUKPT Derive AES Key` | Vendor-aligned | ANSI X9.24-3; 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 | | `Derive ECDH Key Material` | Verified | AWS `TranslateKeyMaterial`; AWS `EcdhDerivationAttributes`; RFC 3394 | Publish |
| `Payment Encrypt Data` | Vendor-aligned | AWS `EncryptData` | Publish with guardrails | | `Payment Encrypt Data` | Vendor-aligned | AWS `EncryptData` | Publish with guardrails |
| `Payment Decrypt Data` | Vendor-aligned | AWS `DecryptData` | Publish with guardrails | | `Payment Decrypt Data` | Vendor-aligned | AWS `DecryptData` | Publish with guardrails |
@ -481,13 +481,13 @@ Performed 2026-05-19. All HSM-mimic operations compared against AWS Payment Cryp
| Card Validation Data Generate (CVV) | `703` | `703` | ✅ MATCH | | | Card Validation Data Generate (CVV) | `703` | `703` | ✅ MATCH | |
| Card Validation Data Generate (CVV2) | `111` | `111` | ✅ MATCH | | | Card Validation Data Generate (CVV2) | `111` | `111` | ✅ MATCH | |
| Card Validation Data Verify | — | PASS | ✅ | | | Card Validation Data Verify | — | PASS | ✅ | |
| VISA PVV Generate | `5596` | `5596` (verify path) | ✅ MATCH | APC `generate_pin_data` blocked by compliance warning; cross-validated via `verify_pin_data` | | 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 | ✅ | | | 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 Offset Generate | `0324` | `0324` (verify path) | ✅ MATCH | Cross-validated via APC `verify_pin_data` |
| PIN IBM 3624 Verify | — | PASS | ✅ | | | 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 | | 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 TDES Key | IPEK `6AC292FAA1315B4D858AB3A3D7D5933A` | N/A | ✅ VERIFIED | Matches published ANSI X9.24-1 test vector |
| DUKPT Derive AES Key | IK derived | N/A | ⚠️ N/A | APC does not expose derived intermediate keys for inspection | | 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 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" | | DUKPT TDES MAC (MAC Generate) | `AF59E7E8A06F01B2` | `AF59E7E8A06F01B2` | ✅ MATCH | APC `DukptKeyVariant=REQUEST` aligns with CyberChef "MAC Request" |

6
README.md
View File

@ -24,7 +24,7 @@ Current coverage includes:
- Key metadata inspection and structural validation - Key metadata inspection and structural validation
- DUKPT TDES key derivation (ANSI X9.24-1, 10-byte KSN, IPEK-based) - DUKPT TDES key derivation (ANSI X9.24-1, 10-byte KSN, IPEK-based)
- DUKPT AES key derivation (ANSI X9.24-3, 12-byte KSN, IK-based, AES-128) - DUKPT AES key derivation (ANSI X9.24-3, 12-byte KSN, IK-based, AES-128)
- PIN block format parsing, construction, and translation (ISO 9564 formats 0, 1, 3) - PIN block format parsing, construction, and translation — including encrypted PIN block re-keying between zone keys (ISO 9564 formats 0, 1, 3)
- Payment-specific MAC and KCV utilities (HMAC, AES-CMAC, TDES-CMAC, ISO 9797-1, AS2805, DUKPT variants) - Payment-specific MAC and KCV utilities (HMAC, AES-CMAC, TDES-CMAC, ISO 9797-1, AS2805, DUKPT variants)
- EMV ARQC/ARPC generation and verification - EMV ARQC/ARPC generation and verification
- EMV issuer-script MAC generation and verification - EMV issuer-script MAC generation and verification
@ -81,6 +81,8 @@ Payment-specific recipe chains and standalone operations, pre-loaded at [cyberch
- [PAN Parse: classify a card number by network][p21] - [PAN Parse: classify a card number by network][p21]
- [Card validation data: generate CVV2][p22] - [Card validation data: generate CVV2][p22]
- [Card validation data: verify CVV2][p23] - [Card validation data: verify CVV2][p23]
- [PIN Block Translate Encrypted: re-key between ZPKs (Format 0)][p24]
- [PIN Block Translate Encrypted: re-key with JSON inspection output][p25]
## Live demo ## Live demo
@ -243,3 +245,5 @@ CyberChef is released under the [Apache 2.0 Licence](https://www.apache.org/lice
[p21]: https://cyberchef.jacobmarks.com/#recipe=PAN_Parse()&input=NTQyNTIzMzQzMDEwOTkwMw== [p21]: https://cyberchef.jacobmarks.com/#recipe=PAN_Parse()&input=NTQyNTIzMzQzMDEwOTkwMw==
[p22]: https://cyberchef.jacobmarks.com/#recipe=Card_Validation_Data_Generate('CVV2%20/%20CVC2%20(force%20000)','4123456789012345','02','25','MMYY','101',3,false)&input=MDEyMzQ1Njc4OUFCQ0RFRkZFRENCQTk4NzY1NDMyMTA= [p22]: https://cyberchef.jacobmarks.com/#recipe=Card_Validation_Data_Generate('CVV2%20/%20CVC2%20(force%20000)','4123456789012345','02','25','MMYY','101',3,false)&input=MDEyMzQ1Njc4OUFCQ0RFRkZFRENCQTk4NzY1NDMyMTA=
[p23]: https://cyberchef.jacobmarks.com/#recipe=Card_Validation_Data_Verify('CVV2%20/%20CVC2%20(force%20000)','4123456789012345','02','25','MMYY','101','221')&input=MDEyMzQ1Njc4OUFCQ0RFRkZFRENCQTk4NzY1NDMyMTA= [p23]: https://cyberchef.jacobmarks.com/#recipe=Card_Validation_Data_Verify('CVV2%20/%20CVC2%20(force%20000)','4123456789012345','02','25','MMYY','101','221')&input=MDEyMzQ1Njc4OUFCQ0RFRkZFRENCQTk4NzY1NDMyMTA=
[p24]: https://cyberchef.jacobmarks.com/#recipe=PIN_Block_Translate_Encrypted('DDDDEEEEFFFFAAAABBBBCCCCDDDDEEEE','ISO%20Format%200','5432101234567890','AABBCCDDEEFF00112233445566778899','ISO%20Format%200','5432101234567890',false)&input=N0YzODFEQkY5RjY5MDZDNA==
[p25]: https://cyberchef.jacobmarks.com/#recipe=PIN_Block_Translate_Encrypted('DDDDEEEEFFFFAAAABBBBCCCCDDDDEEEE','ISO%20Format%200','5432101234567890','AABBCCDDEEFF00112233445566778899','ISO%20Format%200','5432101234567890',true)&input=N0YzODFEQkY5RjY5MDZDNA==