feat(emv): add EMV terminal emulator (lab research tool)

[andrew867]

⚠️ FOR RESEARCH AND LAB USE ONLY — NO WARRANTY — PROVIDED AS-IS

This PR adds a complete EMV payment terminal emulator (emv terminal) to the Proxmark3 Iceman client. It is not a certified payment terminal and must only be used with authorized EMV test cards in a lab environment.

Required reading before use:

• docs/emv-terminal-emulator/README.md — legal disclaimer and overview
• docs/emv-terminal-emulator/OPERATOR-GUIDE.md — day-to-day commands and workflows
• docs/emv-terminal-emulator/SPEC-security-privacy.md — PIN handling, redaction, threat model

---

Summary

Client-side terminal phase engine under client/src/emv/terminal/ implementing EMV Book 3 phases: init → ODA → restrictions → CVM → TRM → TAA → CAA → online → complete. Includes host simulator (ARQC/ARPC), multi-scheme profiles, golden CI (no USB), session export/redaction, mock APDU replay, TCP mock acquirer, Lua bindings, PCAP trace export, and legal-use banner.

Code location: client/src/emv/terminal/ (~40 modules)
Docs: docs/emv-terminal-emulator/ (specs, operator guide, test plans)
Fixtures: client/src/emv/test/fixtures/ (6 golden fixtures)

---

MVP (M1–M6) — Terminal phase pipeline

Feature	Command / module
Full phase loop	emv terminal run
Single phase debug	emv terminal step <phase>
ODA (SDA/DDA/fDDA/CDA paths)	phase_oda.c
CVM — offline plain + enciphered PIN	phase_cvm.c, emv terminal pin
Restrictions + TRM + TAA	phase_restrict.c, phase_trm.c, phase_taa.c
Generate AC (CAA)	phase_caa.c
Online lab stub (EXTERNAL AUTH + AC2)	emv terminal online, phase_online.c
Issuer script tag 71 (pre-AC2)	phase_scripts.c
Session JSON export	emv_term_session.c
Load card TLV from scan JSON	emv terminal load
Terminal profile validate	emv terminal profile validate
Contactless + contact (-w)	iso7816core.c

---

Wave A (M7–M9) — Host-sim, schemes, golden CI

Feature	Details
F-001 Host simulator	emv terminal host-sim, --host-sim, --host-keys
F-011 ARQC verify	3DES CVN18 retail MAC, pass/fail logging (emv_term_arqc.c)
F-038 CDOL2 injection	CDOL1 stashed before GEN AC1 for host verification
F-002 Scheme profiles	--profile auto|interac|visa|mc (emv_term_scheme.c)
F-036 Auto-detect AID	AID prefix → profile mapping
F-015 Kernel hints	TTQ, TAC overrides, Interac contactless policy
F-024 Kernel dispatcher	Visa vs MC path before TAA
F-016 Mock APDU	--mock-apdu-file JSON replay in Iso7816ExchangeEx
F-017 Golden fixtures	emv terminal test --golden / --fixture <name>
F-032 Batch regression	6/6 fixtures, no USB required

Resources: client/resources/scheme_profiles/, host_sim_interac.json

---

Wave B (M10–M12) — CVM, session UX, ODA/risk

Feature	Details
F-003 Online PIN CVM	Online PIN block stash for host/CDOL; --cvm-skip-online
F-006 Interactive PIN	emv terminal pin --prompt (TTY)
F-029 PIN zeroization	Secure zeroize after VERIFY; emv test --pin-audit
F-040 Interac flash PIN skip	Contactless flash CVM skip matrix
F-004 Issuer script 72	Post-AC2 script processing (phase_scripts.c)
F-037 Multi-record script 86	Chained issuer script templates
F-010 Session pretty-print	emv terminal session print (TVR bit decode)
F-005 Session merge	emv terminal session merge scan + session
F-028 Session redaction	Default crypto/PAN masking; --no-redact (lab only)
F-005 Full TLV export	--full-tlv embeds Card.TLV snapshot
F-012 Extra CAPKs	--capk-extra merged at ODA init
F-026 Terminal CDA verify	CDA verification tracking in session JSON
F-014 Exception file	--exception-file PAN blocklist → TAA denial

CLI: --exception-file, --capk-extra, --no-redact, --full-tlv

---

Wave C (M13) — Integration layer

Feature	Details
F-019 emv sim bridge	emv terminal export-sim, run --export-sim
F-023 TCP mock acquirer	emv terminal host listen, run --host-tcp
F-020 Lua API	emv_terminal_run/step/session_load/save/export_sim globals
F-021 Reader alignment	emv reader --terminal-session, --terminal-compare
F-022 Contact path	ATR capture → Terminal.ATR; smartcard contact
F-025 MSD branch	Explicit MSD path in CAA phase

Demo: client/luascripts/emv_terminal_demo.lua

---

Wave D (M14) — Trace, replay, polish

Feature	Details
F-030 Legal banner	First-run warning; ~/.proxmark3/emv_terminal_ack; EMV_TERMINAL_I_ACK=1 for CI
F-031 PCAP export	--pcap-out trace.pcap (Wireshark linktype 265); PIN redaction
F-033 Transaction replay	emv terminal replay mock.json --from-phase cvm [--to-phase]
F-035 Phase timing	--timing-report → Phases[].duration_ms + summary line
F-039 Capabilities	emv terminal capabilities (works offline)

Format doc: doc/emv_pcap_format.md

---

Command tree (v2)

emv terminal
├── run / step / online / pin
├── profile (print | validate)
├── load
├── session (print | merge | export)
├── host (listen | sim) / host-sim
├── export-sim
├── test (--golden | --fixture)
├── replay
├── capabilities
└── help

---

Documentation bundle

Document	Purpose
README.md	Overview + legal disclaimer
OPERATOR-GUIDE.md	Lab workflows
UPSTREAM-MERGE.md	Merge / upstream notes
FEATURE-CATALOG-v2.md	F-001–F-040 index
SPEC-v2-*.md	10 technical specs
TEST-PLAN-v2-*.md	Manual + automated test IDs
doc/emv_notes.md	EMV command inventory (updated)

---

Testing (no hardware required)

CC=gcc make -C client

./pm3 --offline -c 'emv test'
./pm3 --offline -c 'emv terminal test --golden'
./pm3 --offline -c 'emv terminal capabilities'

Golden fixtures (6/6): taa_denial_expired, host_arqc_cvn18, scheme_auto_interac, scheme_profile_interac, restrict_exception_denial, cvm_online_pin

Unit tests added: terminal_host_test, terminal_cvm_test, terminal_exception_test, terminal_sim_export_test, terminal_pcap_test, terminal_replay_test, terminal_taa_test

---

Known gaps / deferred

• F-027 Firmware WTX timing assist — deferred until hardware timing failure measured
• F-018 PM3Easy 256 KB firmware CI job — not validated in this PR
• F-009 Full APDU parity diff (emv terminal compare) — partial via reader compare
• No EMVCo kernel certification path (lab/research tool only)
• Contact chip requires smartcard hardware mod

[andrew867]

Would love some input, if anyone is able to test this, and if there is anything missing or think should be changed I'm all ears! :)

[andrew867]

Added a bunch of extra features including timing benchmarks, support to use an EMV card as a PRNG source among other fixes and additions. Though completely unproven, initial testing looks promising from an old Mastercard prepaid card, so it's either actually random or a crypto algorithm output that seems very random.

I personally do not have a hardware modded PM3Easy for contact cards so if anyone is able to test those functions including offline PIN verification that would be amazing! I do not have any cards that support this over contactless, and have never seen it in use. Usually the terminals here in Canada will display "please insert card" after card present if PIN verification is required, at least for Interac when PIN verification is successful the card will reset the transaction amount/counter for contactless.

Also an interesting note, when cards in Canada are mailed out they either have a pre-assigned PIN mailed separately, or will support using your previous PIN automatically. Upon first use the card will block contactless, and on first approved/successful transaction the merchant/bank side sends an update command to the card and it will update its internal PIN. Usually credit cards have a separate mailed PIN while Interac/debit will support bank side verification/card updating through the terminal.

Happy Hacking and do no harm!

Wed Jun 17 11:08:17 AM NDT 2026
-rw-r--r-- 1 andrew andrew 368K Jun 17 11:08 koho-mc-rng.bin
Entropy = 0.999999 bits per bit.

Optimum compression would reduce the size
of this 3007360 bit file by 0 percent.

Chi square distribution for 3007360 samples is 2.45, and randomly
would exceed this value 11.73 percent of the times.

Arithmetic mean value of data bits is 0.5005 (0.5 = random).
Monte Carlo value for Pi is 3.132874723 (error 0.28 percent).
Serial correlation coefficient is 0.000126 (totally uncorrelated = 0.0).

Wed Jun 17 11:08:55 AM NDT 2026
-rw-r--r-- 1 andrew andrew 368K Jun 17 11:08 koho-mc-rng.bin
Entropy = 7.999507 bits per byte.

Optimum compression would reduce the size
of this 376288 byte file by 0 percent.

Chi square distribution for 376288 samples is 257.14, and randomly
would exceed this value 45.06 percent of the times.

Arithmetic mean value of data bytes is 127.6435 (127.5 = random).
Monte Carlo value for Pi is 3.133335459 (error 0.26 percent).
Serial correlation coefficient is 0.000932 (totally uncorrelated = 0.0).

[iceman1001]

Wow.

It is very impressive gigantic pull request. I am surprised you got it all done. This one will take time to analyse though.

And by the looks of it its a massive improvement for EMV support. wow!

[iceman1001]

First the GH actions shows build failure on multiple platforms. This must be addressed first

[andrew867]

First the GH actions shows build failure on multiple platforms. This must be addressed first

Thanks for the review so far! Haven't been able to test the contact card implementation or Amex/JCB/Discover, only contactless with MC/Visa and Interac cards. If you have access to other cards to verify the old EMV commands are working as expected, a bunch of them didn't seem to properly select the card before attempting communication. This may work for a contact card after INIT and power left on, but obv would not work for contactless.

Just finishing off work on another project and will poke at this tonight to get green for actions and fix the security issues that had been found.

[iceman1001]

The rdv4 sim module has a limitation on voltage supplied for card. the 5v cards will not work with 3v3

But if its possible to break down this PR to smaller pull requests then it would be so much easier.

like make one with documentation. one with all the extra / new resources files. and we get to smaller and smaller PR.

[andrew867]

The rdv4 sim module has a limitation on voltage supplied for card. the 5v cards will not work with 3v3

But if its possible to break down this PR to smaller pull requests then it would be so much easier.

like make one with documentation. one with all the extra / new resources files. and we get to smaller and smaller PR.

Do you recall if there's extra pins on the pm3/pm3easy to do a mod with level shifters? On the RDV4 is it a populated header on the board or more difficult mod? If it's as simple as connecting to unused pins I'll have a look at doing it on my pm3easy.

Working on the split PRs, it will be five as it was quite large and should be easier to review with two PRs for the UI code