diff --git a/AGENTS.md b/AGENTS.md index 9cdc563a..ef828ae8 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -26,6 +26,7 @@ - Otherwise group a commit around one coherent class of change, not multiple unrelated fixes or refactors. - Split work before committing when a reviewer would benefit from evaluating the pieces independently. - 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. ## Payment Operation Maintenance diff --git a/AWS_PAYMENT_CRYPTOGRAPHY_RECIPES.md b/AWS_PAYMENT_CRYPTOGRAPHY_RECIPES.md deleted file mode 100644 index f3869ec6..00000000 --- a/AWS_PAYMENT_CRYPTOGRAPHY_RECIPES.md +++ /dev/null @@ -1,212 +0,0 @@ -# AWS Payment Cryptography Recipe Coverage - -Owner: -- Jacob Marks, `https://jacobmarks.com` -- Fork home: `https://github.com/J8k3/CyberChef` - -This guide maps AWS Payment Cryptography Data Plane operations to the current payment-facing CyberChef surface. -For validation posture, standards references, and release guardrails, see `PAYMENT_VALIDATION_AUDIT.md`. - -Source baseline: -- AWS Payment Cryptography Data Plane API Reference: https://docs.aws.amazon.com/payment-cryptography/latest/DataAPIReference/Welcome.html -- AWS Data Plane actions list: https://docs.aws.amazon.com/payment-cryptography/latest/DataAPIReference/API_Operations.html - -Coverage legend: -- `Direct`: there is a payment-facing operation or straightforward recipe chain for the software-emulation shape of the AWS action -- `Chained`: there is no single operation, but the flow is cleanly achievable by chaining existing operations -- `Emulated`: there is a dedicated operation, but the inline comments call out simplifications versus AWS or HSM custody semantics - -## Coverage Summary - -| AWS operation | Coverage | Use | -| --- | --- | --- | -| `EncryptData` | `Direct` | `Payment Encrypt Data` | -| `DecryptData` | `Direct` | `Payment Decrypt Data` | -| `ReEncryptData` | `Direct` | `Payment Re-Encrypt Data` | -| `GenerateMac` | `Direct` | `MAC Generate` or `EMV Generate MAC` | -| `VerifyMac` | `Direct` | `MAC Verify` or `EMV Verify MAC` | -| `VerifyAuthRequestCryptogram` | `Direct` | `EMV Verify ARQC` | -| `GenerateCardValidationData` | `Direct` | `Card Validation Data Generate` | -| `VerifyCardValidationData` | `Direct` | `Card Validation Data Verify` | -| `GeneratePinData` | `Direct` / `Chained` | `PIN Data Generate`, `IBM 3624 Generate PIN Offset`, `VISA PVV Generate` | -| `TranslatePinData` | `Direct` / `Chained` | `Translate Payment PIN Data` or clear PIN block plus cipher chaining | -| `VerifyPinData` | `Direct` | `PIN Data Verify`, `IBM 3624 Verify PIN`, `VISA PVV Verify` | -| `TranslateKeyMaterial` | `Chained` | `Derive ECDH Key Material` + wrap/unwrap + TR-31/TR-34 helpers | -| `GenerateAs2805KekValidation` | `Emulated` | `AS2805 Generate KEK Validation` | -| `GenerateMacEmvPinChange` | `Direct` / `Emulated` | `EMV Generate MAC (PIN Change)` | - -## AWS `EncryptData` -Preferred operation: -- `Payment Encrypt Data` - -Good chain: -- `DUKPT Derive TDES Key` -> `Triple DES Encrypt` -- `Derive ECDH Key Material` -> KDF if needed -> `AES Encrypt` - -Notes: -- use the payment wrapper when you want payment terminology in one operation -- use the generic ciphers directly when you need fine-grained mode control - -## AWS `DecryptData` -Preferred operation: -- `Payment Decrypt Data` - -Good chain: -- `DUKPT Derive TDES Key` -> `Triple DES Decrypt` -- `Derive ECDH Key Material` -> KDF if needed -> `AES Decrypt` - -## AWS `ReEncryptData` -Preferred operation: -- `Payment Re-Encrypt Data` - -Good chain: -- `Payment Decrypt Data` -> `Payment Encrypt Data` - -## AWS `GenerateMac` -Preferred operations: -- `MAC Generate` -- `EMV Generate MAC` - -Current MAC coverage: -- HMAC SHA-224 / 256 / 384 / 512 -- AES-CMAC -- TDES-CMAC -- ISO 9797-1 Algorithm 1 -- ISO 9797-1 Algorithm 3 -- AS2805-4.1 -- DUKPT TDES-CMAC -- DUKPT ISO 9797-1 Algorithm 1 -- DUKPT ISO 9797-1 Algorithm 3 -- EMV retail-MAC style generation with a provided session key - -Use `EMV Generate MAC` when: -- the AWS flow is EMV-session-key based rather than a static or DUKPT MAC key - -## AWS `VerifyMac` -Preferred operations: -- `MAC Verify` -- `EMV Verify MAC` - -Use the same method, padding rule, and key context as generation. - -## AWS `VerifyAuthRequestCryptogram` -Preferred operation: -- `EMV Verify ARQC` - -Good chain: -- preassemble the ARQC input block -- derive or supply the session key -- verify the ARQC - -Important assumption: -- current ARQC / ARPC support is the implemented AES-CMAC profile - -## AWS `GenerateCardValidationData` -Preferred operation: -- `Card Validation Data Generate` - -Profiles: -- CVV / CVC -- CVV2 / CVC2 -- iCVV - -## AWS `VerifyCardValidationData` -Preferred operation: -- `Card Validation Data Verify` - -## AWS `GeneratePinData` -Preferred operations: -- `PIN Data Generate` -- `IBM 3624 Generate PIN Offset` -- `VISA PVV Generate` - -Use: -- `PIN Data Generate` for clear ISO format `0`, `1`, and `3` PIN blocks -- `IBM 3624 Generate PIN Offset` for issuer-host offset workflows -- `VISA PVV Generate` for PVV workflows - -Good chains: -- clear PIN -> `PIN Data Generate` -> `Payment Encrypt Data` -- clear PIN -> `IBM 3624 Generate PIN Offset` -- clear PIN -> `VISA PVV Generate` - -## AWS `TranslatePinData` -Preferred operation: -- `Translate Payment PIN Data` - -Good chains: -- `PIN Block Parse` -> inspect -> `PIN Block Translate` -- `Payment Decrypt Data` -> `Translate Payment PIN Data` -> `Payment Encrypt Data` - -Important assumption: -- the direct wrapper is for clear ISO PIN-block translation -- encrypted-key-custody semantics are still emulated by chaining - -## AWS `VerifyPinData` -Preferred operations: -- `PIN Data Verify` -- `IBM 3624 Verify PIN` -- `VISA PVV Verify` - -Use: -- `PIN Data Verify` for clear ISO PIN blocks -- `IBM 3624 Verify PIN` for issuer offset checks -- `VISA PVV Verify` for PVV checks - -## AWS `TranslateKeyMaterial` -Preferred chain: -- `Derive ECDH Key Material` -- KDF if needed -- `AES Key Wrap` or `AES Key Unwrap` -- `TR-31 Parse Key Block` -- `TR-34 Parse Key Transport` - -Important assumption: -- this is a recipe chain, not a single HSM-like rewrap boundary - -## AWS `GenerateAs2805KekValidation` -Preferred operation: -- `AS2805 Generate KEK Validation` - -Important assumption: -- this is an explicit software emulation helper -- the operation comments call out that it does not claim exact HSM-side AS2805 node-initialization behavior - -## AWS `GenerateMacEmvPinChange` -Preferred operation: -- `EMV Generate MAC (PIN Change)` - -Good chain: -- build or obtain the encrypted target PIN block -- assemble the issuer-script APDU body -- generate the PIN-change MAC - -Important assumption: -- the helper expects the new PIN block to already be encrypted - -## Common Chains - -## A) DUKPT Request MAC -- `MAC Generate` - -Method: -- `DUKPT MAC Request CMAC` -- or `DUKPT ISO 9797-1 Algorithm 1` -- or `DUKPT ISO 9797-1 Algorithm 3` - -## B) EMV Issuer Script MAC -- `EMV Generate MAC` -- `EMV Verify MAC` - -## C) EMV PIN Change -- `EMV Generate MAC (PIN Change)` - -## D) Clear PIN To Encrypted PIN Data -- `PIN Data Generate` -- `Payment Encrypt Data` - -## E) ECDH-Based Key Translation Lab Flow -- `Derive ECDH Key Material` -- `AES Key Unwrap` -- `AES Key Wrap` -- `TR-31 Parse Key Block` diff --git a/README.md b/README.md index a3d0d202..a56d5346 100755 --- a/README.md +++ b/README.md @@ -53,7 +53,34 @@ They appear in the CyberChef UI under the **Payments** category. Recipe starter docs: - [PAYMENT_RECIPES.md](PAYMENT_RECIPES.md) -- [AWS_PAYMENT_CRYPTOGRAPHY_RECIPES.md](AWS_PAYMENT_CRYPTOGRAPHY_RECIPES.md) + +### Payment recipe examples + +Payment-specific recipe chains and standalone operations, pre-loaded at [cyberchef.jacobmarks.com][1]: + + - [VISA PVV: generate PVV from clear PIN][p01] + - [VISA PVV: generate then verify (full chain)][p02] + - [IBM 3624: generate PIN offset][p03] + - [IBM 3624: generate then verify (full chain)][p04] + - [EMV: generate ARQC][p05] + - [EMV: generate then verify ARQC (full chain)][p06] + - [EMV: generate ARPC issuer response][p07] + - [EMV: generate issuer-script MAC][p08] + - [EMV: verify issuer-script MAC][p09] + - [Payment MAC: generate AES-CMAC][p10] + - [Payment MAC: verify AES-CMAC][p11] + - [DUKPT TDES: derive IPEK from BDK][p12] + - [DUKPT TDES: derive PIN session key][p13] + - [PIN Block: build ISO Format 0 then parse (full chain)][p14] + - [TR-31 key block: parse and inspect header fields][p15] + - [HSM: parse Thales payShield command][p16] + - [HSM: parse Futurex Excrypt command][p17] + - [Payment KCV: compute AES-CMAC key check value][p18] + - [Key Generate then KCV (fresh key with check value)][p19] + - [PAN Generate: Visa curated test card number][p20] + - [PAN Parse: classify a card number by network][p21] + - [Card validation data: generate CVV2][p22] + - [Card validation data: verify CVV2][p23] ## Live demo @@ -193,3 +220,26 @@ CyberChef is released under the [Apache 2.0 Licence](https://www.apache.org/lice [10]: https://cyberchef.jacobmarks.com/#recipe=Register('(.%7B32%7D)',true,false)Drop_bytes(0,32,false)AES_Decrypt(%7B'option':'Hex','string':'1748e7179bd56570d51fa4ba287cc3e5'%7D,%7B'option':'Hex','string':'$R0'%7D,'CTR','Hex','Raw',%7B'option':'Hex','string':''%7D)&input=NTFlMjAxZDQ2MzY5OGVmNWY3MTdmNzFmNWI0NzEyYWYyMGJlNjc0YjNiZmY1M2QzODU0NjM5NmVlNjFkYWFjNDkwOGUzMTljYTNmY2Y3MDg5YmZiNmIzOGVhOTllNzgxZDI2ZTU3N2JhOWRkNmYzMTFhMzk0MjBiODk3OGU5MzAxNGIwNDJkNDQ3MjZjYWVkZjU0MzZlYWY2NTI0MjljMGRmOTRiNTIxNjc2YzdjMmNlODEyMDk3YzI3NzI3M2M3YzcyY2Q4OWFlYzhkOWZiNGEyNzU4NmNjZjZhYTBhZWUyMjRjMzRiYTNiZmRmN2FlYjFkZGQ0Nzc2MjJiOTFlNzJjOWU3MDlhYjYwZjhkYWY3MzFlYzBjYzg1Y2UwZjc0NmZmMTU1NGE1YTNlYzI5MWNhNDBmOWU2MjlhODcyNTkyZDk4OGZkZDgzNDUzNGFiYTc5YzFhZDE2NzY3NjlhN2MwMTBiZjA0NzM5ZWNkYjY1ZDk1MzAyMzcxZDYyOWQ5ZTM3ZTdiNGEzNjFkYTQ2OGYxZWQ1MzU4OTIyZDJlYTc1MmRkMTFjMzY2ZjMwMTdiMTRhYTAxMWQyYWYwM2M0NGY5NTU3OTA5OGExNWUzY2Y5YjQ0ODZmOGZmZTljMjM5ZjM0ZGU3MTUxZjZjYTY1MDBmZTRiODUwYzNmMWMwMmU4MDFjYWYzYTI0NDY0NjE0ZTQyODAxNjE1YjhmZmFhMDdhYzgyNTE0OTNmZmRhN2RlNWRkZjMzNjg4ODBjMmI5NWIwMzBmNDFmOGYxNTA2NmFkZDA3MWE2NmNmNjBlNWY0NmYzYTIzMGQzOTdiNjUyOTYzYTIxYTUzZg [11]: https://cyberchef.jacobmarks.com/#recipe=XOR(%7B'option':'Hex','string':'3a'%7D,'Standard',false)To_Hexdump(16,false,false)&input=VGhlIGFuc3dlciB0byB0aGUgdWx0aW1hdGUgcXVlc3Rpb24gb2YgbGlmZSwgdGhlIFVuaXZlcnNlLCBhbmQgZXZlcnl0aGluZyBpcyA0Mi4 [12]: https://cyberchef.jacobmarks.com/#recipe=Magic(3,false,false)&input=V1VhZ3dzaWFlNm1QOGdOdENDTFVGcENwQ0IyNlJtQkRvREQ4UGFjZEFtekF6QlZqa0syUXN0RlhhS2hwQzZpVVM3UkhxWHJKdEZpc29SU2dvSjR3aGptMWFybTg2NHFhTnE0UmNmVW1MSHJjc0FhWmM1VFhDWWlmTmRnUzgzZ0RlZWpHWDQ2Z2FpTXl1QlY2RXNrSHQxc2NnSjg4eDJ0TlNvdFFEd2JHWTFtbUNvYjJBUkdGdkNLWU5xaU45aXBNcTFaVTFtZ2tkYk51R2NiNzZhUnRZV2hDR1VjOGc5M1VKdWRoYjhodHNoZVpud1RwZ3FoeDgzU1ZKU1pYTVhVakpUMnptcEM3dVhXdHVtcW9rYmRTaTg4WXRrV0RBYzFUb291aDJvSDRENGRkbU5LSldVRHBNd21uZ1VtSzE0eHdtb21jY1BRRTloTTE3MkFQblNxd3hkS1ExNzJSa2NBc3lzbm1qNWdHdFJtVk5OaDJzMzU5d3I2bVMyUVJQ + [p01]: https://cyberchef.jacobmarks.com/#recipe=VISA_PVV_Generate('0123456789ABCDEFFEDCBA9876543210','5432101234567890',1,false)&input=MTIzNA== + [p02]: https://cyberchef.jacobmarks.com/#recipe=VISA_PVV_Generate('0123456789ABCDEFFEDCBA9876543210','5432101234567890',1,false)VISA_PVV_Verify('0123456789ABCDEFFEDCBA9876543210','5432101234567890',1,'1234',true)&input=MTIzNA== + [p03]: https://cyberchef.jacobmarks.com/#recipe=IBM_3624_Generate_PIN_Offset('0123456789ABCDEFFEDCBA9876543210','0123456789012345','5432101234567890','F',false)&input=MTIzNA== + [p04]: https://cyberchef.jacobmarks.com/#recipe=IBM_3624_Generate_PIN_Offset('0123456789ABCDEFFEDCBA9876543210','0123456789012345','5432101234567890','F',false)IBM_3624_Verify_PIN('0123456789ABCDEFFEDCBA9876543210','0123456789012345','5432101234567890','F','1234',true)&input=MTIzNA== + [p05]: https://cyberchef.jacobmarks.com/#recipe=EMV_Generate_ARQC('00112233445566778899AABBCCDDEEFF',8,false)&input=MDAwMTAyMDMwNDA1MDYwNzA4MDkwQTBCMEMwRDBFMEY= + [p06]: https://cyberchef.jacobmarks.com/#recipe=EMV_Generate_ARQC('00112233445566778899AABBCCDDEEFF',8,false)EMV_Verify_ARQC('00112233445566778899AABBCCDDEEFF',8,'000102030405060708090A0B0C0D0E0F',true)&input=MDAwMTAyMDMwNDA1MDYwNzA4MDkwQTBCMEMwRDBFMEY= + [p07]: https://cyberchef.jacobmarks.com/#recipe=EMV_Generate_ARPC('00112233445566778899AABBCCDDEEFF',8,false)&input=MTEyMjMzNDQ1NTY2Nzc4ODk5MDBBQUJCQ0NEREVFRkY= + [p08]: https://cyberchef.jacobmarks.com/#recipe=EMV_Generate_MAC('0123456789ABCDEFFEDCBA9876543210',8,false)&input=ODQyNDAwMDAwODk5OUU1N0ZEMEY0N0NBQ0UwMDA3 + [p09]: https://cyberchef.jacobmarks.com/#recipe=EMV_Verify_MAC('0123456789ABCDEFFEDCBA9876543210','22CB48394DFD1977',true)&input=ODQyNDAwMDAwODk5OUU1N0ZEMEY0N0NBQ0UwMDA3 + [p10]: https://cyberchef.jacobmarks.com/#recipe=MAC_Generate('Hex','AES-CMAC','00112233445566778899AABBCCDDEEFF','Hex','','Method%201',8,false)&input=MTEyMjMzNDQ1NTY2Nzc4OA== + [p11]: https://cyberchef.jacobmarks.com/#recipe=MAC_Verify('Hex','AES-CMAC','00112233445566778899AABBCCDDEEFF','Hex','','Method%201','339AF1AD1650E908',true)&input=MTEyMjMzNDQ1NTY2Nzc4OA== + [p12]: https://cyberchef.jacobmarks.com/#recipe=DUKPT_Derive_TDES_Key('Derive%20IPEK','FFFF9876543210E00008','None',false)&input=MDEyMzQ1Njc4OUFCQ0RFRkZFRENCQTk4NzY1NDMyMTA= + [p13]: https://cyberchef.jacobmarks.com/#recipe=DUKPT_Derive_TDES_Key('Derive%20Session%20Key','FFFF9876543210E00008','PIN',false)&input=MDEyMzQ1Njc4OUFCQ0RFRkZFRENCQTk4NzY1NDMyMTA= + [p14]: https://cyberchef.jacobmarks.com/#recipe=PIN_Block_Build('ISO%20Format%200','5432101234567890',false)PIN_Block_Parse('ISO%20Format%200','5432101234567890')&input=MTIzNA== + [p15]: https://cyberchef.jacobmarks.com/#recipe=TR-31_Parse_Key_Block(false)&input=RDAxMTJQMEFFMDBFMDAwMDEwRUY5OTkwQzgwMkMzRUM3REEwNEM2OUFENjhBNzFCMjM4ODBEQzZDQTY0QjY0Q0UyRTVGMUE0RDA5NTJBM0E= + [p16]: https://cyberchef.jacobmarks.com/#recipe=HSM_Parse_Thales_Command()&input=SEVBREhFMDEyMzQ1Njc4OUFCQ0RFRjAwMTEyMjMzNDQ1NTY2NzclMDBUQUlM + [p17]: https://cyberchef.jacobmarks.com/#recipe=HSM_Parse_Futurex_Command()&input=W0FPR01BQztGUzY7UlYwMDExMjIzMzQ0NTU2Njc3O10= + [p18]: https://cyberchef.jacobmarks.com/#recipe=Payment_Calculate_KCV('Hex','AES-CMAC%20(Empty)',6)&input=MDEyMzQ1Njc4OUFCQ0RFRkZFRENCQTk4NzY1NDMyMTA= + [p19]: https://cyberchef.jacobmarks.com/#recipe=Key_Generate('AES-128%20(16%20bytes)',16,false,false)Payment_Calculate_KCV('Hex','AES-CMAC%20(Empty)',6) + [p20]: https://cyberchef.jacobmarks.com/#recipe=PAN_Generate('Visa','Curated%20sample',16,'Any',true) + [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= + [p23]: https://cyberchef.jacobmarks.com/#recipe=Card_Validation_Data_Verify('CVV2%20/%20CVC2%20(force%20000)','4123456789012345','02','25','MMYY','101','221')&input=MDEyMzQ1Njc4OUFCQ0RFRkZFRENCQTk4NzY1NDMyMTA=