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

.github/codeql/codeql-config.yml

@@ -0,0 +1,33 @@
+# CodeQL configuration for Proxmark3 (Iceman fork)
+#
+# EMV terminal emulator code intentionally implements ISO 8583 / EMV retail
+# cryptography (3DES retail MAC, PIN blocks, etc.) for lab interoperability with
+# test cards — not for production payment processing. Planning docs and lab key
+# JSON are excluded from analysis to reduce false positives.
+
+name: "Proxmark3 CodeQL"
+
+paths-ignore:
+  # Planning / spec markdown (no executable code)
+  - doc/planning
+  # Lab test keys and profiles (public interoperability test pack, not live secrets)
+  - client/resources/interac_test_keys.json
+  - client/resources/host_sim_interac.json
+  - client/resources/emv_terminal_profile_interac.json
+  - client/resources/terminal_aid_candidates.json
+  - client/resources/exception_file_sample.txt
+  # Golden fixtures (synthetic / template JSON)
+  - client/src/emv/test/fixtures
+
+query-filters:
+  # Historic EMV / ISO 9797-1 Alg 3 retail MAC and related interop crypto
+  - exclude:
+      id: cpp/weak-cryptographic-algorithm
+    paths:
+      - client/src/emv
+  # Test harness keys in offline unit tests
+  - exclude:
+      id: cpp/hardcoded-credentials
+    paths:
+      - client/src/emv/test
+      - client/src/emv/terminal

.github/workflows/codeql-analysis.yml

@@ -60,10 +60,7 @@ jobs:
       uses: github/codeql-action/init@v3
       with:
         languages: ${{ matrix.language }}
-        # If you wish to specify custom queries, you can do so here or in a config file.
-        # By default, queries listed here will override any specified in a config file.
-        # Prefix the list here with "+" to use these queries and those in the config file.
-        # queries: ./path/to/local/query, your-org/your-repo/queries@main
+        config-file: ./.github/codeql/codeql-config.yml
 
     - name: make clean
       run: make clean

.github/workflows/macos.yml

@@ -137,6 +137,8 @@ jobs:
           ln -s ../luascripts client/build/
           ln -s ../pyscripts client/build/
           ln -s ../lualibs client/build/
+          ln -s ../resources client/build/
+          ln -s ../dictionaries client/build/
 
       - name: Initiate cmake environment
         run: cmake ..

.github/workflows/ubuntu.yml

@@ -104,6 +104,8 @@ jobs:
           ln -s ../luascripts client/build/
           ln -s ../pyscripts client/build/
           ln -s ../lualibs client/build/
+          ln -s ../resources client/build/
+          ln -s ../dictionaries client/build/
 
       - name: Initiate cmake environment
         run: cmake ..

.github/workflows/windows.yml

@@ -91,6 +91,8 @@ jobs:
           ln -s ../luascripts client/build/
           ln -s ../pyscripts client/build/
           ln -s ../lualibs client/build/
+          ln -s ../resources client/build/
+          ln -s ../dictionaries client/build/
 
       - name: Initiate cmake environment
         run: cmake -G"MSYS Makefiles" ..
@@ -171,6 +173,8 @@ jobs:
           ln -s ../luascripts client/build/
           ln -s ../pyscripts client/build/
           ln -s ../lualibs client/build/
+          ln -s ../resources client/build/
+          ln -s ../dictionaries client/build/
 
       - name: Initiate cmake environment
         run: cmake ..

.gitignore

@@ -68,6 +68,12 @@ cov-int/
 !client/resources/felica/*.json
 !client/resources/calypso/
 !client/resources/calypso/*.json
+!client/resources/emv_terminal_profile.json
+!client/resources/scheme_profiles/
+!client/resources/scheme_profiles/*.json
+!client/resources/host_sim_interac.json
+!client/src/emv/test/fixtures/
+!client/src/emv/test/fixtures/**/*.json
 client/src/ui/ui_image.h
 client/src/ui/ui_overlays.h
 client/deps/reveng/bmptst
@@ -122,10 +128,16 @@ fpga_version_info.c
 !.vscode/tasks.json
 
 # docs
+docs/
 !doc/*.json
+!client/resources/interac_test_keys.json
+!client/resources/terminal_aid_candidates.json
+!client/resources/emv_terminal_profile_interac.json
 
 # codeql
 codeql/
+!.github/codeql/
+!.github/codeql/**
 _codeql_detected_source_root
 
 =======

AGENTS.md

@@ -0,0 +1,31 @@
+# AGENTS.md
+
+## Cursor Cloud specific instructions
+
+This repo is the **Proxmark3 (Iceman fork)** — firmware + host client for an RFID research
+device. The cloud VM has **no physical Proxmark3 attached**, so all device I/O commands are
+unavailable; develop and test against the **host client in OFFLINE mode** plus the offline
+test suite.
+
+### Build (non-obvious gotcha: use gcc, not the default clang)
+- The VM's default `cc`/`c++` alternatives point to **clang**, but the client fails to build
+  under clang (`-Werror` macro redefinition in `client/deps/reveng/config.h`). CI uses gcc.
+  Always build with gcc:
+  - Full build (firmware `bootrom`/`armsrc`/`recovery` + host `client` + tools):
+    `make clean && make -j$(nproc) CC=gcc CXX=g++ LD=g++`
+  - Client only: `make client -j$(nproc) CC=gcc CXX=g++ LD=g++`
+- Firmware always cross-compiles with `arm-none-eabi-gcc` regardless of the `CC` setting.
+- Standard build/flash/run docs: `doc/md/Use_of_Proxmark/0_Compilation-Instructions.md`.
+
+### Test / lint
+- Offline test suite (matches CI): `make check` (full) or `make client/check` (client only).
+  Driven by `tools/pm3_tests.sh`. Tests marked `( slow )` are skipped by default.
+- `make style` (needs `astyle`) and `make miscchecks` (needs `recode`) are the formatting/lint
+  helpers; both are optional and not installed by default.
+
+### Run (offline, no hardware)
+- Interactive offline client: `client/proxmark3` (run with **no port** argument) or `./pm3 --offline`.
+- Device commands like `hw status`, `hw tune`, and any tag read/write report "not available in
+  this mode" — this is expected without hardware. Offline compute commands work, e.g.
+  `wiegand encode/decode`, `data`/trace analysis, `hf mf` offline, key-recovery tools.
+- The runtime warning `QStandardPaths: XDG_RUNTIME_DIR not set` is harmless.

CHANGELOG.md

@@ -3,6 +3,7 @@ All notable changes to this project will be documented in this file.
 This project uses the changelog in accordance with [keepchangelog](http://keepachangelog.com/). Please use this to write notable changes, which is not the same as git commit log...
 
 ## [unreleased][unreleased]
+- Added `emv terminal` — EMV payment **terminal emulator** for lab/research use (contactless + contact paths): full phase engine (`run`/`step`), host simulator (ARQC/ARPC), scheme profiles (`--profile auto|interac|visa|mc`), golden CI fixtures (`emv terminal test --golden`), session export/redaction, mock APDU replay, TCP mock acquirer, Lua bindings, PCAP trace export, legal-use banner, and **`emv terminal crypto`** playground with human-readable card digest (`--summary`), quick AFL, PPSE AID fallback, and export compare. **Not a certified payment terminal — no warranty — authorized test cards only.** Planning docs: `doc/planning/emv-terminal-emulator/` (see OPERATOR-GUIDE.md and SPEC-security-privacy.md).
 - Improved `lf cotag reader` and `lf cotag demod`: Reimplementation and enhancement of proxmark3 COTAG support
 - Added `hf felica sim` command (@kormax)
 - Added `mad read`, `mad write`, `mad verify`, `mad decode`, `mad encode` commands with typed struct MAD API (@AlxCzl)

README.md

@@ -56,12 +56,13 @@ The Proxmark3 is the swiss-army tool of RFID, allowing for interactions with the
 | ------------------- |:-------------------:| -------------------:|
 |[Notes on UART](/doc/uart_notes.md)|[Notes on Termux / Android](/doc/termux_notes.md)|[Notes on paths](/doc/path_notes.md)|
 |[Notes on frame format](/doc/new_frame_format.md)|[Notes on tracelog / wireshark](/doc/trace_notes.md)|[Notes on EMV](/doc/emv_notes.md)|
-|[Notes on external flash](/doc/ext_flash_notes.md)|[Notes on loclass](/doc/loclass_notes.md)|[Notes on Coverity Scan Config & Run](/doc/md/Development/Coverity-Scan-Config-and-Run.md)|
-|[Notes on file formats used with Proxmark3](/doc/extensions_notes.md)|[Notes on MFU binary format](/doc/mfu_binary_format_notes.md)|[Notes on FPGA & ARM](/doc/fpga_arm_notes.md)|
-|[Developing standalone mode](/armsrc/Standalone/readme.md)|[Wiki about standalone mode](https://github.com/RfidResearchGroup/proxmark3/wiki/Standalone-mode)|[Notes on Magic UID cards](/doc/magic_cards_notes.md)|
-|[Notes on Color usage](/doc/colors_notes.md)|[Makefile vs CMake](/doc/md/Development/Makefile-vs-CMake.md)|[Notes on Cloner guns](/doc/cloner_notes.md)|
-|[Notes on cliparser usage](/doc/cliparser.md)|[Notes on clocks](/doc/clocks.md)|[Notes on MIFARE DESFire](/doc/desfire.md)|
-|[Notes on CIPURSE](/doc/cipurse.md)|[Notes on NDEF type4a](/doc/ndef_type4a.md)|[Unofficial MIFARE DESFire bible](/doc/unofficial_desfire_bible.md)|[Notes on iClass legrec-legbrute key recovery](/doc/iclass_legrec_legbrute_key_recovery.md)|[Notes on downgrade attacks](/doc/hid_downgrade.md)|||
+|[EMV Terminal Emulator planning](/doc/planning/emv-terminal-emulator/README.md)|[Notes on external flash](/doc/ext_flash_notes.md)|[Notes on loclass](/doc/loclass_notes.md)|
+|[Notes on Coverity Scan Config & Run](/doc/md/Development/Coverity-Scan-Config-and-Run.md)|[Notes on file formats used with Proxmark3](/doc/extensions_notes.md)|[Notes on MFU binary format](/doc/mfu_binary_format_notes.md)|
+|[Notes on FPGA & ARM](/doc/fpga_arm_notes.md)|[Developing standalone mode](/armsrc/Standalone/readme.md)|[Wiki about standalone mode](https://github.com/RfidResearchGroup/proxmark3/wiki/Standalone-mode)|
+|[Notes on Magic UID cards](/doc/magic_cards_notes.md)|[Notes on Color usage](/doc/colors_notes.md)|[Makefile vs CMake](/doc/md/Development/Makefile-vs-CMake.md)|
+|[Notes on Cloner guns](/doc/cloner_notes.md)|[Notes on cliparser usage](/doc/cliparser.md)|[Notes on clocks](/doc/clocks.md)|
+|[Notes on MIFARE DESFire](/doc/desfire.md)|[Notes on CIPURSE](/doc/cipurse.md)|[Notes on NDEF type4a](/doc/ndef_type4a.md)|
+|[Unofficial MIFARE DESFire bible](/doc/unofficial_desfire_bible.md)|[Notes on iClass legrec-legbrute key recovery](/doc/iclass_legrec_legbrute_key_recovery.md)|[Notes on downgrade attacks](/doc/hid_downgrade.md)|
 
 # How to build?
 

client/CMakeLists.txt

@@ -321,6 +321,14 @@ set (TARGET_SOURCES
         ${PM3_ROOT}/client/src/emv/test/cryptotest.c
         ${PM3_ROOT}/client/src/emv/test/dda_test.c
         ${PM3_ROOT}/client/src/emv/test/sda_test.c
+        ${PM3_ROOT}/client/src/emv/test/terminal_cvm_test.c
+        ${PM3_ROOT}/client/src/emv/test/terminal_crypto_test.c
+        ${PM3_ROOT}/client/src/emv/test/terminal_exception_test.c
+        ${PM3_ROOT}/client/src/emv/test/terminal_host_test.c
+        ${PM3_ROOT}/client/src/emv/test/terminal_pcap_test.c
+        ${PM3_ROOT}/client/src/emv/test/terminal_replay_test.c
+        ${PM3_ROOT}/client/src/emv/test/terminal_sim_export_test.c
+        ${PM3_ROOT}/client/src/emv/test/terminal_taa_test.c
         ${PM3_ROOT}/client/src/emv/cmdemv.c
         ${PM3_ROOT}/client/src/emv/crypto.c
         ${PM3_ROOT}/client/src/emv/crypto_polarssl.c
@@ -333,6 +341,48 @@ set (TARGET_SOURCES
         ${PM3_ROOT}/client/src/emv/emvcore.c
         ${PM3_ROOT}/client/src/emv/emvjson.c
         ${PM3_ROOT}/client/src/emv/tlv.c
+        ${PM3_ROOT}/client/src/emv/terminal/emv_term_arqc.c
+        ${PM3_ROOT}/client/src/emv/terminal/emv_term_banner.c
+        ${PM3_ROOT}/client/src/emv/terminal/emv_term_capabilities.c
+        ${PM3_ROOT}/client/src/emv/terminal/emv_term_cmd.c
+        ${PM3_ROOT}/client/src/emv/terminal/emv_term_crypto.c
+        ${PM3_ROOT}/client/src/emv/terminal/emv_term_crypto_cmd.c
+        ${PM3_ROOT}/client/src/emv/terminal/emv_term_crypto_digest.c
+        ${PM3_ROOT}/client/src/emv/terminal/emv_term_ctx.c
+        ${PM3_ROOT}/client/src/emv/terminal/emv_term_exception.c
+        ${PM3_ROOT}/client/src/emv/terminal/emv_term_golden.c
+        ${PM3_ROOT}/client/src/emv/terminal/emv_term_host.c
+        ${PM3_ROOT}/client/src/emv/terminal/emv_term_host_tcp.c
+        ${PM3_ROOT}/client/src/emv/terminal/emv_term_load.c
+        ${PM3_ROOT}/client/src/emv/terminal/emv_term_lua.c
+        ${PM3_ROOT}/client/src/emv/terminal/emv_term_mock.c
+        ${PM3_ROOT}/client/src/emv/terminal/emv_term_pcap.c
+        ${PM3_ROOT}/client/src/emv/terminal/emv_term_pin_prompt.c
+        ${PM3_ROOT}/client/src/emv/terminal/emv_term_probe.c
+        ${PM3_ROOT}/client/src/emv/terminal/emv_term_profile.c
+        ${PM3_ROOT}/client/src/emv/terminal/emv_term_reader_session.c
+        ${PM3_ROOT}/client/src/emv/terminal/emv_term_redact.c
+        ${PM3_ROOT}/client/src/emv/terminal/emv_term_replay.c
+        ${PM3_ROOT}/client/src/emv/terminal/emv_term_scheme.c
+        ${PM3_ROOT}/client/src/emv/terminal/emv_term_secure.c
+        ${PM3_ROOT}/client/src/emv/terminal/emv_term_session.c
+        ${PM3_ROOT}/client/src/emv/terminal/emv_term_session_view.c
+        ${PM3_ROOT}/client/src/emv/terminal/emv_term_sim_export.c
+        ${PM3_ROOT}/client/src/emv/terminal/emv_term_timing.c
+        ${PM3_ROOT}/client/src/emv/terminal/emv_term_tlv.c
+        ${PM3_ROOT}/client/src/emv/terminal/emv_term_tvr.c
+        ${PM3_ROOT}/client/src/emv/terminal/emv_terminal.c
+        ${PM3_ROOT}/client/src/emv/terminal/emv_transaction.c
+        ${PM3_ROOT}/client/src/emv/terminal/phase_caa.c
+        ${PM3_ROOT}/client/src/emv/terminal/phase_complete.c
+        ${PM3_ROOT}/client/src/emv/terminal/phase_cvm.c
+        ${PM3_ROOT}/client/src/emv/terminal/phase_init.c
+        ${PM3_ROOT}/client/src/emv/terminal/phase_oda.c
+        ${PM3_ROOT}/client/src/emv/terminal/phase_online.c
+        ${PM3_ROOT}/client/src/emv/terminal/phase_restrict.c
+        ${PM3_ROOT}/client/src/emv/terminal/phase_scripts.c
+        ${PM3_ROOT}/client/src/emv/terminal/phase_taa.c
+        ${PM3_ROOT}/client/src/emv/terminal/phase_trm.c
         ${PM3_ROOT}/client/src/fido/additional_ca.c
         ${PM3_ROOT}/client/src/fido/cbortools.c
         ${PM3_ROOT}/client/src/fido/cose.c

client/Makefile

@@ -834,9 +834,59 @@ SRCS =  mifare/aiddesfire.c \
         emv/emvcore.c \
         emv/emvjson.c\
         emv/tlv.c \
+        emv/terminal/emv_term_ctx.c \
+        emv/terminal/emv_term_profile.c \
+        emv/terminal/emv_term_session.c \
+        emv/terminal/emv_term_tvr.c \
+        emv/terminal/emv_term_load.c \
+        emv/terminal/emv_transaction.c \
+        emv/terminal/phase_init.c \
+        emv/terminal/phase_oda.c \
+        emv/terminal/phase_restrict.c \
+        emv/terminal/phase_cvm.c \
+        emv/terminal/phase_trm.c \
+        emv/terminal/phase_taa.c \
+        emv/terminal/phase_caa.c \
+        emv/terminal/phase_online.c \
+        emv/terminal/phase_complete.c \
+        emv/terminal/emv_terminal.c \
+        emv/terminal/emv_term_cmd.c \
+        emv/terminal/emv_term_arqc.c \
+        emv/terminal/emv_term_host.c \
+        emv/terminal/emv_term_scheme.c \
+        emv/terminal/emv_term_mock.c \
+        emv/terminal/emv_term_golden.c \
+        emv/terminal/emv_term_secure.c \
+        emv/terminal/emv_term_pin_prompt.c \
+        emv/terminal/emv_term_exception.c \
+        emv/terminal/emv_term_redact.c \
+        emv/terminal/emv_term_session_view.c \
+        emv/terminal/phase_scripts.c \
+        emv/terminal/emv_term_sim_export.c \
+        emv/terminal/emv_term_host_tcp.c \
+        emv/terminal/emv_term_lua.c \
+        emv/terminal/emv_term_reader_session.c \
+        emv/terminal/emv_term_banner.c \
+        emv/terminal/emv_term_pcap.c \
+        emv/terminal/emv_term_replay.c \
+        emv/terminal/emv_term_timing.c \
+        emv/terminal/emv_term_tlv.c \
+        emv/terminal/emv_term_probe.c \
+        emv/terminal/emv_term_crypto.c \
+        emv/terminal/emv_term_crypto_digest.c \
+        emv/terminal/emv_term_crypto_cmd.c \
+        emv/terminal/emv_term_capabilities.c \
         emv/test/crypto_test.c\
         emv/test/cryptotest.c\
         emv/test/cda_test.c\
+        emv/test/terminal_taa_test.c\
+        emv/test/terminal_host_test.c\
+        emv/test/terminal_cvm_test.c\
+        emv/test/terminal_crypto_test.c\
+        emv/test/terminal_exception_test.c\
+        emv/test/terminal_sim_export_test.c\
+        emv/test/terminal_pcap_test.c\
+        emv/test/terminal_replay_test.c\
         emv/test/dda_test.c\
         emv/test/sda_test.c\
         fido/additional_ca.c \

client/experimental_lib/CMakeLists.txt

@@ -241,6 +241,14 @@ set (TARGET_SOURCES
         ${PM3_ROOT}/client/src/emv/test/cryptotest.c
         ${PM3_ROOT}/client/src/emv/test/dda_test.c
         ${PM3_ROOT}/client/src/emv/test/sda_test.c
+        ${PM3_ROOT}/client/src/emv/test/terminal_cvm_test.c
+        ${PM3_ROOT}/client/src/emv/test/terminal_crypto_test.c
+        ${PM3_ROOT}/client/src/emv/test/terminal_exception_test.c
+        ${PM3_ROOT}/client/src/emv/test/terminal_host_test.c
+        ${PM3_ROOT}/client/src/emv/test/terminal_pcap_test.c
+        ${PM3_ROOT}/client/src/emv/test/terminal_replay_test.c
+        ${PM3_ROOT}/client/src/emv/test/terminal_sim_export_test.c
+        ${PM3_ROOT}/client/src/emv/test/terminal_taa_test.c
         ${PM3_ROOT}/client/src/emv/cmdemv.c
         ${PM3_ROOT}/client/src/emv/crypto.c
         ${PM3_ROOT}/client/src/emv/crypto_polarssl.c
@@ -253,6 +261,48 @@ set (TARGET_SOURCES
         ${PM3_ROOT}/client/src/emv/emvcore.c
         ${PM3_ROOT}/client/src/emv/emvjson.c
         ${PM3_ROOT}/client/src/emv/tlv.c
+        ${PM3_ROOT}/client/src/emv/terminal/emv_term_arqc.c
+        ${PM3_ROOT}/client/src/emv/terminal/emv_term_banner.c
+        ${PM3_ROOT}/client/src/emv/terminal/emv_term_capabilities.c
+        ${PM3_ROOT}/client/src/emv/terminal/emv_term_cmd.c
+        ${PM3_ROOT}/client/src/emv/terminal/emv_term_crypto.c
+        ${PM3_ROOT}/client/src/emv/terminal/emv_term_crypto_cmd.c
+        ${PM3_ROOT}/client/src/emv/terminal/emv_term_crypto_digest.c
+        ${PM3_ROOT}/client/src/emv/terminal/emv_term_ctx.c
+        ${PM3_ROOT}/client/src/emv/terminal/emv_term_exception.c
+        ${PM3_ROOT}/client/src/emv/terminal/emv_term_golden.c
+        ${PM3_ROOT}/client/src/emv/terminal/emv_term_host.c
+        ${PM3_ROOT}/client/src/emv/terminal/emv_term_host_tcp.c
+        ${PM3_ROOT}/client/src/emv/terminal/emv_term_load.c
+        ${PM3_ROOT}/client/src/emv/terminal/emv_term_lua.c
+        ${PM3_ROOT}/client/src/emv/terminal/emv_term_mock.c
+        ${PM3_ROOT}/client/src/emv/terminal/emv_term_pcap.c
+        ${PM3_ROOT}/client/src/emv/terminal/emv_term_pin_prompt.c
+        ${PM3_ROOT}/client/src/emv/terminal/emv_term_probe.c
+        ${PM3_ROOT}/client/src/emv/terminal/emv_term_profile.c
+        ${PM3_ROOT}/client/src/emv/terminal/emv_term_reader_session.c
+        ${PM3_ROOT}/client/src/emv/terminal/emv_term_redact.c
+        ${PM3_ROOT}/client/src/emv/terminal/emv_term_replay.c
+        ${PM3_ROOT}/client/src/emv/terminal/emv_term_scheme.c
+        ${PM3_ROOT}/client/src/emv/terminal/emv_term_secure.c
+        ${PM3_ROOT}/client/src/emv/terminal/emv_term_session.c
+        ${PM3_ROOT}/client/src/emv/terminal/emv_term_session_view.c
+        ${PM3_ROOT}/client/src/emv/terminal/emv_term_sim_export.c
+        ${PM3_ROOT}/client/src/emv/terminal/emv_term_timing.c
+        ${PM3_ROOT}/client/src/emv/terminal/emv_term_tlv.c
+        ${PM3_ROOT}/client/src/emv/terminal/emv_term_tvr.c
+        ${PM3_ROOT}/client/src/emv/terminal/emv_terminal.c
+        ${PM3_ROOT}/client/src/emv/terminal/emv_transaction.c
+        ${PM3_ROOT}/client/src/emv/terminal/phase_caa.c
+        ${PM3_ROOT}/client/src/emv/terminal/phase_complete.c
+        ${PM3_ROOT}/client/src/emv/terminal/phase_cvm.c
+        ${PM3_ROOT}/client/src/emv/terminal/phase_init.c
+        ${PM3_ROOT}/client/src/emv/terminal/phase_oda.c
+        ${PM3_ROOT}/client/src/emv/terminal/phase_online.c
+        ${PM3_ROOT}/client/src/emv/terminal/phase_restrict.c
+        ${PM3_ROOT}/client/src/emv/terminal/phase_scripts.c
+        ${PM3_ROOT}/client/src/emv/terminal/phase_taa.c
+        ${PM3_ROOT}/client/src/emv/terminal/phase_trm.c
         ${PM3_ROOT}/client/src/fido/additional_ca.c
         ${PM3_ROOT}/client/src/fido/cbortools.c
         ${PM3_ROOT}/client/src/fido/cose.c