diff --git a/CHANGELOG.md b/CHANGELOG.md index 3d5ac5633..b36f5d335 100644 --- a/CHANGELOG.md +++ b/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 tools script `tools/ePassport/ePassport` - kivy python3 script that dumps a passport with BAC/CAN and a nice viewer (@iceman1001) - Added tools script `external_sam_read.py` enabling PM3 3 Easy and Proxmark 5 to use an external SIM/SAM reader for `hf iclass sam` and `hf seos sam` commands (@antiklesys) - Added `nfc encode` and `hf mfu ndefwrite` - build NDEF URI/Text/AAR records and write them to Ultralight tags (@0x6r1an0y) - Fixed `hf emrtd info` - the picture viewer now scales images to the window instead of pinning them at native size (@iceman1001) diff --git a/Makefile b/Makefile index a7f15666b..625e0ca6f 100644 --- a/Makefile +++ b/Makefile @@ -195,10 +195,13 @@ hitag2crack/%: FORCE hitag2crack/clean: FORCE hitag2crack/_clean_pycache hitag2crack/_clean_pycache: find . -type d -name __pycache__ -exec rm -rfv \{\} + +ePassport/%: FORCE + $(info [*] MAKE $@) + $(Q)$(MAKE) --no-print-directory -C tools/ePassport $(patsubst ePassport/%,%,$@) DESTDIR=$(MYDESTDIR) FORCE: # Dummy target to force remake in the subdirectories, even if files exist (this Makefile doesn't know about the prerequisites) -.PHONY: all host clean install uninstall help _test bootrom fullimage recovery client mfc_card_only mfc_card_reader mfulc_des_brute mfd_aes_brute hitag2crack style miscchecks release FORCE udev accessrights cleanifplatformchanged +.PHONY: all host clean install uninstall help _test bootrom fullimage recovery client mfc_card_only mfc_card_reader mfulc_des_brute mfd_aes_brute hitag2crack ePassport style miscchecks release FORCE udev accessrights cleanifplatformchanged help: @echo "Multi-OS Makefile" diff --git a/tools/ePassport/.gitignore b/tools/ePassport/.gitignore new file mode 100644 index 000000000..9cee763e5 --- /dev/null +++ b/tools/ePassport/.gitignore @@ -0,0 +1,18 @@ +__pycache__/ +*.pyc +.pytest_cache/ + +# Nothing derived from a real document belongs in this tree. Dumps hold a +# live portrait and MRZ; screenshots of them are just as identifying. The +# sample dumps are generated - see tools_make_sample.py - and the tests build +# their own copy into a temporary directory. +samples/ +dumps/ +docs/ +*.log +*.png +*.jpg +*.jpeg +*.bin +*.p7b +*.der diff --git a/tools/ePassport/Makefile b/tools/ePassport/Makefile new file mode 100644 index 000000000..5fd79964c --- /dev/null +++ b/tools/ePassport/Makefile @@ -0,0 +1,47 @@ +# ePassport - an eMRTD viewer for the Proxmark3. +# +# Nothing here builds: the app is a Python script run in place. These targets +# are the housekeeping around it. + +PYTHON ?= python3 +SAMPLEDIR ?= samples + +.PHONY: help run test format samples clean distclean check + +help: + @echo "ePassport" + @echo + @echo " make run launch the app" + @echo " make test run the test suite (no hardware needed)" + @echo " make samples generate fabricated sample dumps into $(SAMPLEDIR)/" + @echo " make format reformat with black" + @echo " make clean remove __pycache__ and test caches" + @echo " make distclean clean, plus the generated samples" + @echo + @echo " PYTHON=$(PYTHON) (override if your dependencies live in a venv)" + +run: + $(PYTHON) ./ePassport + +test: + $(PYTHON) -m pytest tests/ -q + +check: test + +format: + $(PYTHON) -m black epassport tests tools_*.py + +samples: + $(PYTHON) tools_make_sample.py $(SAMPLEDIR) + +# Byte-code and test caches only - never anything a person put here. +clean: _clean_pycache + rm -rf .pytest_cache + +_clean_pycache: + find . -type d -name __pycache__ -exec rm -rf \{\} + + +# Also drop the generated dumps. They are rebuilt by `make samples`, and +# nothing derived from a document is kept in this tree. +distclean: clean + rm -rf $(SAMPLEDIR) diff --git a/tools/ePassport/README.md b/tools/ePassport/README.md new file mode 100644 index 000000000..a7d3fcc74 --- /dev/null +++ b/tools/ePassport/README.md @@ -0,0 +1,436 @@ +# ePassport + +An ePassport (eMRTD) viewer: reads a passport chip through the Proxmark3 and +renders it as a passport data page. + +Everything runs **offline**. No telemetry, no cloud OCR, no network calls of +any kind — every font and asset is bundled. + +``` +./ePassport # normal use +./ePassport --dump DIR # open a saved dump, no hardware +./ePassport --dry-run pm3.log --dump DIR # replay a session you recorded +./ePassport --help +``` + +`ePassport` is a plain executable script — run it from anywhere, by path or +from a symlink; there is nothing to install and no `PYTHONPATH` to set. If a +dependency is missing it says which one, which interpreter it used, and the +exact command to fix it. + +It needs an interpreter that has the requirements. With a virtualenv, either +activate it first or point at it directly: + +```bash +/path/to/venv/bin/python ./ePassport +``` + +--- + +## Install + +```bash +python3 -m pip install -r requirements.txt +``` + +Kivy is required. Everything else is optional and the app degrades with a +message telling you what to install: + +| Missing | What stops working | +|---|---| +| `opencv-python-headless` | the Scan screen (camera) | +| `pytesseract` + the `tesseract-ocr` binary | MRZ OCR — manual entry still works | +| `Pillow` / `glymur` | portrait decoding (DG2 is usually JPEG2000) | +| `asn1crypto` / `cryptography` | EF_SOD inspection and the DG hash table | + +For the best OCR accuracy install the OCR-B or `mrz` traineddata; the app picks +it up automatically and falls back to `eng` with a character whitelist. + +`sudo apt install xclip` enables Kivy's cut-buffer support. The app filters +the noisy `[CRITICAL] [Cutbuffer]` complaint either way; nothing depends on it. + +## Relationship to proxmark3 + +This app **does not modify the proxmark3 tree**. The only coupling is the `pm3` +CLI, invoked in one-shot command mode: + +``` +pm3 -c "hf emrtd dump -n -d -e --dir " +pm3 -c "hf emrtd info --dir " # offline mode +``` + +The binary is located via `$PM3_BIN` → the configured path → `PATH` → `~/pm3/pm3` +→ the `./pm3` wrapper of an enclosing proxmark3 source tree. + +The country-name table in `emrtd/countries.py` is **generated** from the +proxmark3 client's own ISO-3166 table (`fdxbCountryMapping` in +`client/src/cmdlffdxb.c`). Regenerate it with: + +```bash +python3 tools_gen_countries.py ../../client/src/cmdlffdxb.c +``` + +### Authentication + +| You have | Enter | What runs | +|---|---|---| +| The MRZ | document number + both dates, or line 2 | PACE with the MRZ, falling back to BAC | +| The CAN | the number printed on the data page | `--can` (PACE only) | + +The **CAN** is the short number printed on the data page — usually 6 digits. +It is a PACE password, so it is mutually exclusive with the MRZ, and BAC can +never use it. The Authentication dropdown forces `--pace` or `--bac` when you +want to test one path; leave it on Automatic otherwise. + +Wrong CANs are counted by the chip and the password will eventually block, so +that failure is called out separately from a wrong MRZ. + +### Two things worth knowing about `hf emrtd` + +- **All three of `-n/-d/-e` must be supplied**, or the client silently drops to + no-BAC mode and fails on any protected passport. The app refuses a partial + triple rather than passing it on. +- **The `pm3` wrapper blocks forever** waiting for a device when none is + attached. The app watches for that line and reports "No Proxmark3 found" + immediately instead of sitting on the timeout. + +## Using it + +1. **Scan** the MRZ with a camera, or **type** the three values. A full 44-char + MRZ line 2 takes precedence and is passed as `-m`, which avoids + field-splitting mistakes. +2. **Read** — pm3 runs on a worker thread and streams into the LOG tab, with a + determinate progress bar and a Cancel that actually kills the process. +3. The dump is parsed from the **binaries** (BER-TLV), never scraped from + `hf emrtd info` stdout, and rendered as a data page. + +Tabs across the top: `DATA PAGE` · `PERSONAL` (DG11) · `ISSUER` (DG12) · +`SECURITY` (SOD/DG14/DG15) · `FILES` · `LOG`. + +### Output + +The app is quiet by default. Kivy 2.3 takes its log level from +`~/.kivy/config.ini`, which is shared with every other Kivy app on the machine, +so rather than rewrite that the app drops Kivy's console handler and installs +its own for warnings and above. pytesseract (which logs a full tesseract +command line per frame), OpenCV and its V4L2 backend are quietened the same +way. `-v` puts all of it back. + +### Resizing + +The page is laid out **once** at a fixed resolution and then drawn scaled, so a +resize costs a matrix multiply rather than a full re-flow. Re-flowing it on +every resize event re-rendered every label and regenerated the security print +several times a frame, which made dragging a window edge crawl and the contents +jitter as text reflowed under the cursor. + +Measured over twenty resize steps: + +| | Before | After | +|---|---|---| +| Page widget redraws per step | 21 | 0 | +| Label re-renders per step | 65 | 11 (window chrome only) | +| Time in text rendering | 182 ms | 10 ms | + +Two supporting fixes: redraws are coalesced onto a `Clock` trigger so `pos` and +`size` changing separately cannot cause three redraws in one frame, and MRZ +glyphs are cached per (character, size) — an MRZ is ~90 characters drawn from +an alphabet of 37, so it was building ninety textures to show at most +thirty-seven distinct ones. + +### Why a document may not fill the window + +Both formats are always scaled as large as they fit without distorting, so +neither is ever "shrunk" — but a document and a window are different shapes, +and only one of the two dimensions can fill. Whichever document is closer to +the window's shape uses more of it: + +| Window content shape | Passport (1.42) | Card (1.59) | +|---|---|---| +| 1.61 (wide) | 88% wide, 100% tall | 99% wide, 100% tall | +| 1.42 (the default) | **100% wide, 100% tall** | 100% wide, 90% tall | +| 2.59 (very wide) | 55% wide, 100% tall | 61% wide, 100% tall | + +The default window is sized so its **content area comes out at the reference +document's own 125:88**, so a passport fills it exactly on first run. Stretch +the window wide and both documents will letterbox at the sides; that is the +shape mismatch, not the app giving up on the space. + +### Small windows + +The minimum window is 760x520 and the app remembers the size you leave it at. +Everything is built to survive that: + +- the passport page scales as a unit and keeps its aspect; +- the tab strip shares its width rather than claiming fixed slots; +- the FILES table uses proportional columns, so the state column does not fall + off the edge; +- the hex viewer fits **16, 8 or 4 bytes per row** to whatever width the pane + has, because a hex dump must not wrap. + +### Speed + +An MRZ scan settles in roughly a second. What that took: + +| Change | Effect | +|---|---| +| Cheap pre-gate before OCR (`looks_like_text`) | a badly framed strip costs ~0.3 ms instead of ~400 ms | +| Skip frames already processed | no repeat OCR of an identical frame | +| Pace the loop instead of adding to it | the interval no longer stacks on top of the work | +| Cache the language lookup | it shelled out to tesseract every frame | +| Stop escalating variants with no signal | 2 passes instead of 3 on hopeless frames | +| Remember the last winning variant | dim lighting costs 1 pass, not 3 | + +Measured on a live camera: mean OCR pass 381 ms → 163 ms, time to acceptance +3.1 s → 1.3 s, with accuracy unchanged on the synthetic bench. + +The gate runs *after* deskew — it measures horizontal bands of ink, and tilted +text smears those bands together. + +An in-process binding (`tesserocr`) is ~3× faster per call than re-launching +the tesseract binary, and was tried. It is **not** used: the PyPI wheel bundles +its own leptonica, and pairing that with a system `tessdata` directory hung +indefinitely mid-recognition. A backend that can wedge the OCR thread is worse +than a slower one. + +### Cameras + +The Scan screen enumerates capture devices by name from +`/sys/class/video4linux` — without opening them, because opening a device is +disruptive if something else is using it. + +- **No camera**: the screen says so and offers **Rescan for devices**. Manual + entry is always available and works just as well. +- **One or more**: a dropdown lists them by name (`0: IPEVO Ziggi-HD Plus`). + The choice is remembered. + +Linux commonly exposes several `/dev/videoN` nodes for one physical camera, +only one of which delivers frames — `isOpened()` returns true for the others. +The app therefore treats a successful *read* as the test, and falls back to a +neighbouring index automatically. **Rescan** probes every device to label the +dead ones `(no frames)`; it stops the preview first so the probe and the +capture thread do not fight over the device. + +Only line 2 is needed for BAC, so the scan accepts a lone line 2 when its five +check digits — composite included — all pass. + +### What a "valid" MRZ scan does and does not prove + +A scan is accepted only when every check digit validates **and** two +consecutive frames agree. That still does not prove the document number is +right. The 7-3-1 checksum is taken modulo 10 and its weights are coprime with +10, so swapping a character for one whose value differs by a multiple of 10 +leaves every check digit — composite included — unchanged. The blind pairs are +`L`/`1`, `S`/`8`, `G`/`6`, `Z`/`5`, `I`/`8`, `D`/`3` … which are exactly the +swaps OCR is most likely to make. + +That is why a scan **fills the entry form and stops** rather than starting a +read, and why the form flags the document number for a second look. If BAC +then fails, the document number is the first thing to check. + +(Confusions that are *not* blind, such as `O` read as `0` in a country code, +are repaired automatically by position before validation.) + +### Drawing the page + +A TD1 is an ID-1 card (85.6 x 54 mm), not a small passport data page +(125 x 88 mm), and its three-line MRZ takes about a quarter of its height +against an eighth for a passport's two lines. The page is drawn at whichever +shape the document really is. + +**Two scale modes**, because you cannot have both at once. OCR-B is a fixed +2.54 mm pitch on every format, but a character is 2.97% of a card's width and +only 2.03% of a passport's — so a card's MRZ is inherently half again as large +relative to its own document: + +| Mode | What it gives you | What it costs | +|---|---|---| +| **Fit window** (default) | every document fills the window | a card's MRZ prints ~1.5x a passport's on screen | +| **True size** | MRZ print identical across formats, as in the hand | a card is drawn two thirds the width, leaving margins | + +Opening a dump re-fits the page for whatever format it turns out to be, so the +button is a preference you set once, not something to press after every load. +The toolbar button swaps them and the choice is remembered. It is labelled +with the **action**, like the chrome button beside it: reading "Fit window" +means clicking will fit the window, so you are currently at true size. A +passport looks identical either way; only formats smaller than the reference +page differ. + +Within the band, the MRZ block is sized to fit in **both** directions — the +smaller of the width- and height-derived sizes wins, and a block that does not +fill the width is centred. Fitting the width alone pushed a card's MRZ out over +the fields above it; leaving a full line of air between rows then shrank it +until it no longer reached the margins. + +The **portrait** is sized from the page width and the real 35 x 45 photo shape, +capped against the space above the band — a fraction of page height alone made +it swallow a short card. The frame keeps the photo aspect whichever constraint +binds, so an image never sits letterboxed in white bars. + +The guilloche is generated procedurally (superimposed hypotrochoids at low +alpha) — nothing is traced from a real document's security print. It is clipped +to the printed frame **geometrically**, with a Liang-Barsky segment clip, not +with a stencil: this widget can sit inside another `StencilView`, and Kivy's +nested stencils do not intersect, so an inner stencil silently stops clipping +anything. That bug had the pattern spilling past the page edge onto the +window background. + +Text over the pattern measures about 15:1 contrast, well clear of the 4.5:1 +floor. + +### Fields that may not be there + +DG11 and DG12 are optional and plenty of real passports omit them entirely — +place of birth, date of issue and issuing authority are printed on the page but +never written to the chip. Those fields say **"not on chip"** rather than +showing an empty value, so a missing data group is not mistaken for a parse +failure. + +The **personal number** is recovered from the MRZ optional-data field when +DG11 is absent — several states, Sweden among them, put the national identity +number there. The field's caption says `PERSONAL No. (FROM MRZ)` when it came +from that fallback. + +### What the SECURITY tab does and does not check + +It hashes each dumped data group and compares against the hash table inside +EF_SOD, marking every DG **match / MISMATCH / not checked**. It does **not** +validate the signer certificate chain — that needs the issuing country's CSCA +certificate, which the app deliberately does not fetch. + +## Where your reads go + +Every read writes to: + +``` +~/.local/share/ePassport/dumps// +``` + +created `0700`. The app was previously called `pm3-passport`; if a directory +of that name exists it is moved to the new one on first run, so earlier reads +are carried across rather than orphaned. You do not need to remember that: **Dumps…** in the toolbar +lists every read with its timestamp and contents. From there you can open one, +delete one with the bin button, open the folder in your file manager, or clear +out the empty directories left behind by reads that failed. The path is also in +the status bar (click it) and in the log at the start of every read. + +Deleting always asks first, and says what it is about to destroy — a dump holds +a real portrait and a real MRZ. + +**Opening a dump from elsewhere** (a colleague's, or the generated samples): +**Dumps… → Samples…** goes straight to `./samples`, and **Browse…** opens a +picker with one-click jumps to **Recent**, **Dumps**, **Samples**, **Working +dir** and **Home**, plus a path box you can type or paste into. + +The picker reopens **beside the last dump you loaded**, so picking a second +dump next to the first does not mean navigating there again. Shortcuts that do +not exist are not shown — `Samples` only appears once you have generated them — +and duplicates collapse, so `Recent` and `Samples` do not both appear when they +are the same folder. + +## Your data + +- Dumps are `0700` and there is a **Delete dump** button. +- MRZ values and document numbers are never written outside that directory. +- "Remember" on the entry screen defaults to **off** — those values are live + credential material. +- The app is strictly read-only: it displays what the chip returns, and no + field is editable. + +## Development + +```bash +make test # 297 tests, no hardware needed +make samples # generate the fabricated dumps into ./samples +make clean # drop __pycache__ and the test cache +make distclean # the above, plus the generated samples +make format # reformat with black +make help # the rest +``` + +The proxmark3 root `Makefile` recurses in here too, following the same pattern +it uses for `hitag2crack`: + +```bash +make ePassport/clean # from the repository root +make ePassport/test +make ePassport/help +``` + +ePassport is deliberately **not** in the root `TARGETS`, so a plain `make` or +`make clean` at the top level does not touch it — it builds nothing and is not +part of the firmware or client build. + +`make` shells out to `python3`; if your dependencies live in a virtualenv, +point it at that interpreter: + +```bash +make test PYTHON=/path/to/venv/bin/python +``` + +The same without `make`: + +```bash +python3 -m pytest tests/ -q +python3 tools_make_sample.py [DIR] # generate the sample dumps +python3 -m epassport.emrtd samples/td3_utopia # headless: parse and print +python3 -m black epassport tests tools_*.py +``` + +### Nothing derived from a document is checked in + +This tree carries **no dumps, no logs and no images**. A dump holds a live +portrait and MRZ, and a screenshot of one is just as identifying — so none of +it belongs in version control, not even the fabricated kind, and `.gitignore` +refuses the file types outright. + +What you need instead is generated: + +```bash +python3 tools_make_sample.py [DIR] # fabricated dumps, default ./samples +``` + +They are documents of the fictional ICAO specimen state "Utopia": no real +personal data, no real security print. `td3_utopia` carries a genuinely signed +EF_SOD, `td3_utopia_tampered` is the same document with DG2 swapped after +signing so the SECURITY tab has a MISMATCH to show, and `td1_utopia_idcard` is +a TD1 card with no DG11/DG12 or SOD. + +The tests never touch that directory: `tests/conftest.py` builds its own copy +into a temporary directory, and the recorded pm3 sessions used by the +`--dry-run` tests are inline in `tests/test_pm3_client.py`. + +To replay a real session, record it yourself: + +```bash +pm3 -c "hf emrtd dump -n ... -d ... -e ..." | tee pm3.log +``` + +### Layout + +``` +Makefile run / test / format / clean +ePassport the executable; everything below is the implementation +epassport/ + app.py app, screens, worker threads + __main__.py shim so `python3 -m epassport` still works + config.py paths, settings, 0700 data dir + pm3/client.py subprocess, streaming, cancel, timeout + pm3/errors.py typed failures + plain-English remedies + emrtd/tlv.py BER-TLV reader + emrtd/mrz.py TD1/TD2/TD3, check digits, date window + emrtd/dg.py per-DG decoders -> PassportRecord + emrtd/sod.py optional CMS/SOD inspection + emrtd/images.py JPEG/JP2 carving out of CBEFF blobs + emrtd/model.py PassportRecord: the single UI-facing object + ocr/ camera thread, OCR pipeline, accept rule + ui/ Kivy widgets and .kv files +``` + +**Threading contract:** the pm3 subprocess, file parsing, image decoding and +OCR all run off the main thread; UI mutation happens only via +`Clock.schedule_once`. The app never freezes while a dump runs. + +**Single source of truth:** every parser produces one `PassportRecord`, and the +UI binds only to that — which is why "open saved dump" and "read from card" are +the same rendering path. diff --git a/tools/ePassport/ePassport b/tools/ePassport/ePassport new file mode 100755 index 000000000..3b9ae1eb5 --- /dev/null +++ b/tools/ePassport/ePassport @@ -0,0 +1,61 @@ +#!/usr/bin/env python3 +"""ePassport - an ePassport (eMRTD) viewer for the Proxmark3. + +Run this file directly; there is nothing to install: + + ./ePassport + ./ePassport --dump ~/.local/share/ePassport/dumps/ + ./ePassport --help + +It works from any directory, and does not need to be on PYTHONPATH. +""" + +from __future__ import annotations + +import os +import sys + +HERE = os.path.dirname(os.path.abspath(__file__)) +if HERE not in sys.path: + sys.path.insert(0, HERE) + +MISSING = """\ +ePassport needs a dependency that is not installed here: + + {error} + +Interpreter: {python} + +Install the requirements into the environment you are running: + + {python} -m pip install -r {requirements} + +If you keep the dependencies in a virtualenv, activate it first, or run this +script with that interpreter directly: + + /path/to/venv/bin/python {script} +""" + + +def fail_missing(error: Exception) -> int: + sys.stderr.write( + MISSING.format( + error=error, + python=sys.executable, + requirements=os.path.join(HERE, "requirements.txt"), + script=os.path.abspath(__file__), + ) + ) + return 1 + + +def main() -> int: + try: + from epassport.app import main as run + except ImportError as exc: + return fail_missing(exc) + return run(sys.argv[1:]) + + +if __name__ == "__main__": + raise SystemExit(main()) diff --git a/tools/ePassport/epassport/__init__.py b/tools/ePassport/epassport/__init__.py new file mode 100644 index 000000000..e69de29bb diff --git a/tools/ePassport/epassport/__main__.py b/tools/ePassport/epassport/__main__.py new file mode 100644 index 000000000..6096f7a4f --- /dev/null +++ b/tools/ePassport/epassport/__main__.py @@ -0,0 +1,14 @@ +"""Support ``python3 -m epassport``. + +The real entry point is the ``ePassport`` script in the project root; this +shim only exists so the module form keeps working. +""" + +from __future__ import annotations + +import sys + +from .app import main + +if __name__ == "__main__": + raise SystemExit(main(sys.argv[1:])) diff --git a/tools/ePassport/epassport/app.py b/tools/ePassport/epassport/app.py new file mode 100644 index 000000000..f27df9a25 --- /dev/null +++ b/tools/ePassport/epassport/app.py @@ -0,0 +1,689 @@ +"""ePassport: an ePassport (eMRTD) viewer. + +Everything runs offline. The only coupling to proxmark3 is the ``pm3`` CLI. + +Run it with the ``ePassport`` script in the project root:: + + ./ePassport + ./ePassport --dump samples/td3_utopia + ./ePassport --dry-run --dump +""" + +from __future__ import annotations + +import argparse +import logging +import os +import subprocess +import sys +import threading +from pathlib import Path + +os.environ.setdefault("KIVY_NO_ARGS", "1") + +# Quieten the noisy libraries BEFORE importing them. Kivy 2.3 takes its log +# level from ~/.kivy/config.ini, which is shared with every other Kivy app on +# the machine and is not ours to rewrite - so drop its console handler instead +# and re-install our own for warnings and above (see _install_kivy_logging). +# OpenCV and its V4L2 backend read their verbosity from the environment. +_VERBOSE = any(flag in sys.argv for flag in ("-v", "--verbose")) +if not _VERBOSE: + os.environ.setdefault("KIVY_NO_CONSOLELOG", "1") +os.environ.setdefault("OPENCV_LOG_LEVEL", "DEBUG" if _VERBOSE else "ERROR") +os.environ.setdefault("OPENCV_VIDEOIO_DEBUG", "1" if _VERBOSE else "0") + +from kivy.config import Config # noqa: E402 + +# Set the minimum size here rather than on Window: assigning Window.minimum_* +# warns while the other half of the pair is still zero, whichever order it is +# done in. +# Screen space is worth being careful with: the passport page scales as a +# unit, so the window can go a long way down before anything stops being +# readable. +Config.set("graphics", "minimum_width", "760") +Config.set("graphics", "minimum_height", "520") + +from kivy.app import App # noqa: E402 +from kivy.clock import Clock # noqa: E402 +from kivy.core.window import Window # noqa: E402 +from kivy.properties import ( # noqa: E402 + BooleanProperty, + DictProperty, + NumericProperty, + ObjectProperty, + StringProperty, +) +from kivy.uix.boxlayout import BoxLayout # noqa: E402 +from kivy.uix.screenmanager import NoTransition, Screen, ScreenManager # noqa: E402 + +from .config import Settings, dumps_dir, new_dump_dir # noqa: E402 +from .emrtd.dg import load_dump # noqa: E402 +from .emrtd.model import PassportRecord # noqa: E402 +from .ocr.camera import opencv_available # noqa: E402 +from .ocr.mrz_ocr import tesseract_available # noqa: E402 +from .pm3 import errors # noqa: E402 +from .pm3.client import BacInput, Pm3Client, Pm3Result # noqa: E402 +from .ui import load_kv, theme # noqa: E402 + +log = logging.getLogger("epassport") + +#: What the window manager shows. +APP_TITLE = "ePassport" + +#: How many files a full dump writes, for the progress bar's denominator when +#: EF_COM has not been read yet. +DEFAULT_EXPECTED_FILES = 9 + + +class Root(BoxLayout): + """The window: screen manager plus the status bar.""" + + +class ViewerScreen(Screen): + """The passport book: tab strip, page area, progress and error panel.""" + + +class Pm3PassportApp(App): + """The application object. Owns the record, the client and the threads.""" + + record = ObjectProperty(None, allownone=True, rebind=True) + palette = DictProperty(theme.LIGHT) + dark = BooleanProperty(False) + + busy = BooleanProperty(False) + progress = NumericProperty(0.0) + progress_text = StringProperty("") + status_connection = StringProperty("idle") + status_bac = StringProperty("-") + status_auth = StringProperty("None") + status_dump_dir = StringProperty("") + + scale_mode = StringProperty("fit") + camera_available = BooleanProperty(False) + ocr_available = BooleanProperty(False) + ocr_reason = StringProperty("") + + def __init__(self, args: argparse.Namespace, **kwargs) -> None: + super().__init__(**kwargs) + self.args = args + self.settings = Settings.load() + if args.pm3_binary: + self.settings.pm3_binary = args.pm3_binary + self.client = Pm3Client( + self.settings.pm3_binary or None, + timeout=self.settings.timeout_seconds, + dry_run_log=args.dry_run, + ) + self._worker: threading.Thread | None = None + self._tab_pages: dict[int, object] = {} + + # ------------------------------------------------------------ build + def build(self): + # ``App.title`` is a StringProperty: setting it as a class attribute + # shadows the property and the window keeps Kivy's default name. + self.title = APP_TITLE + Window.set_title(APP_TITLE) + load_kv() + self.dark = self.settings.dark_chrome + self.scale_mode = self.settings.page_scale_mode + self.palette = theme.palette(self.dark) + self.record = PassportRecord() + self.camera_available = opencv_available() + self.ocr_available, self.ocr_reason = tesseract_available() + self._restore_window_size() + root = Root() + self.root_widget = root + Clock.schedule_once(self._post_build, 0) + return root + + def _restore_window_size(self) -> None: + """Reopen at the size the user last left, not a size we insist on.""" + width, height = self.settings.window_width, self.settings.window_height + if width >= 760 and height >= 520: + Window.size = (width, height) + Window.bind(on_resize=self._remember_window_size) + + def _remember_window_size(self, _window, width: int, height: int) -> None: + if width < 100 or height < 100: # a minimise, not a resize + return + self.settings.window_width = int(width) + self.settings.window_height = int(height) + self._window_size_dirty = True + + def _post_build(self, *_args) -> None: + entry = self.screen("entry") + if entry is not None and self.settings.remember_bac: + entry.remember = True + entry.fill( + self.settings.last_document_number, + self.settings.last_date_of_birth, + self.settings.last_date_of_expiry, + ) + scan = self.screen("scan") + if scan is not None: + scan.on_accept = self._on_mrz_scanned + scan.on_camera_change = self._remember_camera + scan.camera_index = self.settings.camera_index + self.status_connection = "pm3: " + ( + str(self.client.binary) if self.client.binary else "not found" + ) + if self.args.dry_run: + self.status_connection = f"dry run: {self.args.dry_run}" + self.select_tab(0) + if self.args.dump and not self.args.dry_run: + self.load_dump_dir(Path(self.args.dump)) + + # ---------------------------------------------------------- helpers + @property + def manager(self) -> ScreenManager | None: + return self.root_widget.ids.get("sm") if hasattr(self, "root_widget") else None + + def screen(self, name: str): + manager = self.manager + if manager is None: + return None + return manager.get_screen(name) if manager.has_screen(name) else None + + def goto(self, name: str) -> None: + manager = self.manager + if manager is not None and manager.has_screen(name): + manager.transition = NoTransition() + manager.current = name + + def goto_entry(self) -> None: + scan = self.screen("scan") + if scan is not None: + scan.stop() + self.goto("entry") + + def goto_scan(self) -> None: + scan = self.screen("scan") + if scan is None: + return + self.goto("scan") + scan.camera_index = self.settings.camera_index + scan.start() + + def goto_viewer(self) -> None: + self.goto("viewer") + + # ------------------------------------------------------- tab handling + def select_tab(self, index: int) -> None: + viewer = self.screen("viewer") + if viewer is None: + return + strip = viewer.ids.get("tabs") + turner = viewer.ids.get("pages") + if strip is None or turner is None: + return + strip.active_index = index + for tab in strip.children: + tab.active = tab.index == index + page = self._page_for(index) + if page is not None: + turner.show(page) + + def _page_for(self, index: int): + """Build a tab's page on first use, then reuse it.""" + if index in self._tab_pages: + page = self._tab_pages[index] + else: + from .ui.passport import AspectBox, PassportPage + from .ui.tabs.pages import ( + FilesPage, + IssuerPage, + LogPage, + PersonalPage, + SecurityPage, + ) + + if index == 0: + from .ui.passport import PagePlate + + box = AspectBox() + page = box + self._passport_page = PassportPage() + from .ui.passport import PX_PER_MM + + reference = ( + theme.REFERENCE_PAGE_MM[0] * PX_PER_MM, + theme.REFERENCE_PAGE_MM[1] * PX_PER_MM, + ) + plate = PagePlate(size=reference) + plate.add_widget(self._passport_page) + box.add_widget(plate) + else: + cls, title = { + 1: (PersonalPage, "Additional personal details · EF_DG11"), + 2: (IssuerPage, "Additional document details · EF_DG12"), + 3: (SecurityPage, "Document security · EF_SOD, EF_DG14, EF_DG15"), + 4: (FilesPage, "Dumped files"), + 5: (LogPage, "pm3 client output"), + }[index] + page = cls(title=title, palette=self.palette) + self._tab_pages[index] = page + if index == 0: + self._apply_scale_mode() + self._apply_record_to(page) + return page + + def _apply_record_to(self, page) -> None: + if page is None: + return + if hasattr(page, "record"): + page.record = self.record + if hasattr(self, "_passport_page") and page is self._tab_pages.get(0): + self._passport_page.record = self.record + if hasattr(page, "refresh"): + page.refresh() + + def on_record(self, *_args) -> None: + for page in self._tab_pages.values(): + self._apply_record_to(page) + + # --------------------------------------------------------------- log + @property + def log_pane(self): + page = self._tab_pages.get(5) + return page.ids.get("logpane") if page is not None else None + + def append_log(self, line: str) -> None: + """Thread-safe: LogPane queues and flushes on the Kivy clock.""" + pane = self.log_pane + if pane is None: + self._page_for(5) + pane = self.log_pane + if pane is not None: + pane.append(line) + + def clear_log(self) -> None: + pane = self.log_pane + if pane is not None: + pane.clear() + + # --------------------------------------------------------- reading + def start_read(self) -> None: + """Kick off a dump on a worker thread. Never blocks the UI.""" + if self.busy: + return + entry = self.screen("entry") + if entry is None: + return + bac, problem = entry.validated_input() + if bac is None: + self.show_error(errors.MissingBacInputError(), detail=problem) + return + if self.client.binary is None and not self.args.dry_run: + self.show_error(errors.Pm3NotFound()) + return + + if entry.remember: + self.settings.remember_bac = True + self.settings.last_document_number = entry.document_number + self.settings.last_date_of_birth = entry.date_of_birth + self.settings.last_date_of_expiry = entry.date_of_expiry + else: + self.settings.remember_bac = False + self.settings.forget_bac() + self.settings.save() + + directory = new_dump_dir() + self.hide_error() + self.busy = True + self.progress = 0.0 + self.progress_text = "starting pm3…" + self.status_bac = "attempting…" + self.status_auth = bac.mechanism + self.status_dump_dir = str(directory) + self.select_tab(5) + self.goto_viewer() + + command = Pm3Client.build_command("dump", bac, directory) + self.append_log(f'[=] pm3 -c "{command}"') + self._worker = threading.Thread( + target=self._read_worker, + args=(command, directory), + name="ePassport-read", + daemon=True, + ) + self._worker.start() + + def _read_worker(self, command: str, directory: Path) -> None: + """Runs off the UI thread: pm3, then parsing, then a single UI hop.""" + result = self.client.run( + command, + on_line=self.append_log, + on_progress=self._on_progress, + dump_dir=directory, + expected_files=DEFAULT_EXPECTED_FILES, + ) + # In dry-run mode the log is replayed but no files are written, so + # --dump doubles as "the dump this log would have produced". + source = ( + Path(self.args.dump) + if (self.args.dry_run and self.args.dump) + else directory + ) + record: PassportRecord | None = None + if result.error is None: + try: + record = load_dump(source) + except Exception as exc: # a bad dump must not crash the app + log.exception("parsing the dump failed") + self.append_log(f"[!!] could not parse the dump: {exc}") + Clock.schedule_once(lambda *_: self._read_finished(result, record), 0) + + def _on_progress(self, done: int, total: int, name: str) -> None: + total = total or DEFAULT_EXPECTED_FILES + Clock.schedule_once(lambda *_: self._set_progress(done, total, name), 0) + + def _set_progress(self, done: int, total: int, name: str) -> None: + self.progress = min(1.0, done / total) if total else 0.0 + self.progress_text = f"{name} ({done}/{total})" + + def _read_finished(self, result: Pm3Result, record: PassportRecord | None) -> None: + self.busy = False + self.progress = 1.0 if result.ok else 0.0 + self.progress_text = "" + if result.error is not None: + self.status_bac = "failed" + self.status_auth = "None" + self.show_error(result.error) + self.select_tab(5) + return + self.status_bac = "success" + mechanism = errors.detect_mechanism(result.lines) + if mechanism: + self.status_auth = mechanism + if record is not None: + self.record = record + self.status_dump_dir = str(record.source_dir or "") + self.select_tab(0) + for warning in record.warnings: + self.append_log(f"[!] {warning}") + + def cancel_read(self) -> None: + """Kill the pm3 process. The app stays fully usable afterwards.""" + if not self.busy: + return + self.append_log("[!] cancelling…") + self.client.cancel() + + # ------------------------------------------------------- saved dumps + def load_dump_dir(self, directory: Path) -> None: + """Open an existing dump - no hardware needed.""" + directory = Path(directory).expanduser() + if not directory.is_dir(): + self.show_error(errors.Pm3Error("not a directory"), detail=str(directory)) + return + self.append_log(f"[=] opening saved dump {directory}") + self.status_connection = "offline dump" + self.status_auth = "None (offline)" + + def work() -> None: + try: + record = load_dump(directory) + except Exception as exc: + log.exception("parsing the dump failed") + Clock.schedule_once(lambda *_: self.append_log(f"[!!] {exc}"), 0) + return + Clock.schedule_once(lambda *_: self._dump_loaded(record), 0) + + threading.Thread(target=work, name="ePassport-open", daemon=True).start() + + def _dump_loaded(self, record: PassportRecord) -> None: + self.record = record + self.status_bac = "n/a (offline)" + self.status_dump_dir = str(record.source_dir or "") + self.settings.last_dump_dir = str(record.source_dir or "") + self.settings.save() + self.hide_error() + self.select_tab(0) + self.goto_viewer() + for warning in record.warnings: + self.append_log(f"[!] {warning}") + + def open_dumps_browser(self) -> None: + """List the app's own dumps. Answers "where did my read go?".""" + from .ui.dialogs import DumpsPopup + + DumpsPopup(on_choice=self.load_dump_dir).open() + + def open_dump_dialog(self, start: str | None = None) -> None: + from .config import browse_start + from .ui.dialogs import ChooseDirPopup + + # Reopen where the last dump was picked from, so browsing to a second + # dump beside the first does not mean navigating there again. + ChooseDirPopup( + start=start or str(browse_start(self.settings.last_dump_dir)), + on_choice=self.load_dump_dir, + ).open() + + def open_samples_dialog(self) -> None: + """Jump straight to the generated sample dumps.""" + from .config import samples_dir + + directory = samples_dir() + if directory is None: + self.append_log("[!] no samples yet - generate them with: make samples") + return + self.open_dump_dialog(str(directory)) + + def export_file(self) -> None: + from .ui.dialogs import ChooseDirPopup + + page = self._tab_pages.get(4) + if page is None: + return + + def chosen(directory: Path) -> None: + page.status = page.export_selected(str(directory)) + + ChooseDirPopup(start=str(Path.home()), on_choice=chosen).open() + + def open_dump_dir(self) -> None: + """Open the dump directory in the desktop file manager.""" + directory = self.status_dump_dir + if not directory: + return + try: + subprocess.Popen(["xdg-open", directory], start_new_session=True) + except OSError as exc: + self.append_log(f"[!] could not open {directory}: {exc}") + + def forget_current_dump(self) -> None: + """The loaded dump has just been deleted from under us.""" + self.status_dump_dir = "" + self.record = PassportRecord() + self.append_log("[=] the loaded dump was deleted") + + def delete_dump(self) -> None: + from .ui.dialogs import ConfirmPopup + + directory = self.status_dump_dir + if not directory: + return + + def do_delete() -> None: + import shutil + + try: + shutil.rmtree(directory) + except OSError as exc: + self.append_log(f"[!] could not delete {directory}: {exc}") + return + self.append_log(f"[=] deleted {directory}") + self.forget_current_dump() + + ConfirmPopup( + title_text="Delete this dump?", + message=f"{directory}\n\nThis permanently removes the dumped personal data.", + confirm_action=do_delete, + ).open() + + # -------------------------------------------------------------- misc + def _on_mrz_scanned(self, parsed) -> None: + entry = self.screen("entry") + if entry is not None: + entry.set_line2(parsed.mrz_line2) + entry.fill( + parsed.bac_document_number, + parsed.date_of_birth.value, + parsed.date_of_expiry.value, + ) + Clock.schedule_once(lambda *_: self.goto("entry"), 0.35) + + def _remember_camera(self, index: int) -> None: + """Persist the camera the user picked (or that we fell back to).""" + if self.settings.camera_index == index: + return + self.settings.camera_index = index + self.settings.save() + + def toggle_scale_mode(self) -> None: + """Swap between filling the window and true relative size. + + A card's MRZ is proportionally larger than a passport's, so a document + cannot both fill the window and print its MRZ at the same size as + another format. This picks which of the two you want. + """ + from .ui.passport import FIT_TO_WINDOW, TRUE_SCALE + + self.scale_mode = ( + TRUE_SCALE if self.scale_mode == FIT_TO_WINDOW else FIT_TO_WINDOW + ) + self.settings.page_scale_mode = self.scale_mode + self.settings.save() + self._apply_scale_mode() + + def _apply_scale_mode(self) -> None: + box = self._tab_pages.get(0) + if box is not None and hasattr(box, "scale_mode"): + box.scale_mode = self.scale_mode + + def toggle_dark(self) -> None: + self.dark = not self.dark + self.palette = theme.palette(self.dark) + self.settings.dark_chrome = self.dark + self.settings.save() + for page in self._tab_pages.values(): + if hasattr(page, "palette"): + page.palette = self.palette + if hasattr(page, "refresh"): + page.refresh() + + def show_error(self, error: errors.Pm3Error, *, detail: str = "") -> None: + for name in ("entry", "viewer"): + screen = self.screen(name) + panel = screen.ids.get("error_panel") if screen is not None else None + if panel is not None: + panel.title = error.title + panel.detail = detail or getattr(error, "detail", "") + panel.remedy = error.remedy + panel.visible = True + + def hide_error(self) -> None: + for name in ("entry", "viewer"): + screen = self.screen(name) + panel = screen.ids.get("error_panel") if screen is not None else None + if panel is not None: + panel.visible = False + + def on_stop(self) -> None: + if getattr(self, "_window_size_dirty", False): + self.settings.save() + self.client.cancel() + scan = self.screen("scan") + if scan is not None: + scan.stop() + + +USAGE = """\ +An ePassport (eMRTD) viewer for the Proxmark3. + +Reads a passport chip over the pm3 CLI and renders it as a data page. +Everything runs offline; nothing is ever uploaded. + +Examples: + ePassport read a passport (needs a Proxmark3) + ePassport --dump DIR open a saved dump, no hardware needed + ePassport --dry-run LOG --dump DIR replay a pm3 log you recorded yourself +""" + + +def parse_args(argv: list[str]) -> argparse.Namespace: + parser = argparse.ArgumentParser( + prog="ePassport", + description=USAGE, + formatter_class=argparse.RawDescriptionHelpFormatter, + ) + parser.add_argument( + "--dump", metavar="DIR", help="open a saved dump directory at startup" + ) + parser.add_argument( + "--dry-run", + metavar="LOG", + help="replay a recorded pm3 log instead of running pm3", + ) + parser.add_argument("--pm3-binary", metavar="PATH", help="path to the pm3 client") + parser.add_argument("-v", "--verbose", action="store_true", help="debug logging") + return parser.parse_args(argv) + + +class _KivyNoise(logging.Filter): + """Drop Kivy messages that only report a missing optional helper. + + The clipboard cut-buffer probe logs a CRITICAL plus a full traceback when + xclip and xsel are absent, which is a dozen lines of alarming noise about + something the app never uses. + """ + + NOISE = ("Cutbuffer", "Unable to find any valuable Cutbuffer provider") + + def filter(self, record: logging.LogRecord) -> bool: + message = record.getMessage() + return not any(token in message for token in self.NOISE) + + +def _install_kivy_logging(verbose: bool) -> None: + """Give Kivy a handler of ours, since its own console one is disabled.""" + from kivy.logger import Logger + + if verbose: + return # Kivy kept its own console handler + handler = logging.StreamHandler() + handler.setFormatter(logging.Formatter("%(levelname)s kivy: %(message)s")) + handler.addFilter(_KivyNoise()) + Logger.addHandler(handler) + Logger.setLevel(logging.WARNING) + + +def quieten_libraries(verbose: bool) -> None: + """Stop third-party libraries logging into our console. + + pytesseract logs the whole tesseract command line - including the temp + file path - at DEBUG for every single frame, which at several frames a + second buries everything else. + """ + level = logging.DEBUG if verbose else logging.WARNING + for name in ("pytesseract", "PIL", "matplotlib", "kivy", "glymur", "asn1crypto"): + logging.getLogger(name).setLevel(level) + try: + import cv2 + + cv2.setLogLevel(4 if verbose else 1) # 4 = DEBUG, 1 = FATAL/silent + except Exception: + pass + + +def main(argv: list[str] | None = None) -> int: + args = parse_args(argv if argv is not None else sys.argv[1:]) + logging.basicConfig( + level=logging.DEBUG if args.verbose else logging.INFO, + format="%(levelname)s %(name)s: %(message)s", + ) + quieten_libraries(args.verbose) + _install_kivy_logging(args.verbose) + Pm3PassportApp(args).run() + return 0 diff --git a/tools/ePassport/epassport/assets/fonts/DejaVuSans-Bold.ttf b/tools/ePassport/epassport/assets/fonts/DejaVuSans-Bold.ttf new file mode 100644 index 000000000..426812b9b Binary files /dev/null and b/tools/ePassport/epassport/assets/fonts/DejaVuSans-Bold.ttf differ diff --git a/tools/ePassport/epassport/assets/fonts/DejaVuSans.ttf b/tools/ePassport/epassport/assets/fonts/DejaVuSans.ttf new file mode 100644 index 000000000..fb0bd945a Binary files /dev/null and b/tools/ePassport/epassport/assets/fonts/DejaVuSans.ttf differ diff --git a/tools/ePassport/epassport/assets/fonts/DejaVuSansMono-Bold.ttf b/tools/ePassport/epassport/assets/fonts/DejaVuSansMono-Bold.ttf new file mode 100644 index 000000000..eeff2f2d5 Binary files /dev/null and b/tools/ePassport/epassport/assets/fonts/DejaVuSansMono-Bold.ttf differ diff --git a/tools/ePassport/epassport/assets/fonts/DejaVuSansMono.ttf b/tools/ePassport/epassport/assets/fonts/DejaVuSansMono.ttf new file mode 100644 index 000000000..538ee2723 Binary files /dev/null and b/tools/ePassport/epassport/assets/fonts/DejaVuSansMono.ttf differ diff --git a/tools/ePassport/epassport/assets/fonts/DejaVuSerif-Bold.ttf b/tools/ePassport/epassport/assets/fonts/DejaVuSerif-Bold.ttf new file mode 100644 index 000000000..fd4f498a5 Binary files /dev/null and b/tools/ePassport/epassport/assets/fonts/DejaVuSerif-Bold.ttf differ diff --git a/tools/ePassport/epassport/assets/fonts/DejaVuSerif.ttf b/tools/ePassport/epassport/assets/fonts/DejaVuSerif.ttf new file mode 100644 index 000000000..daf016501 Binary files /dev/null and b/tools/ePassport/epassport/assets/fonts/DejaVuSerif.ttf differ diff --git a/tools/ePassport/epassport/assets/fonts/LICENSE-DejaVu.txt b/tools/ePassport/epassport/assets/fonts/LICENSE-DejaVu.txt new file mode 100644 index 000000000..b3d93a123 --- /dev/null +++ b/tools/ePassport/epassport/assets/fonts/LICENSE-DejaVu.txt @@ -0,0 +1,78 @@ +Format: https://www.debian.org/doc/packaging-manuals/copyright-format/1.0/ +Upstream-Name: DejaVu fonts +Upstream-Author: Stepan Roh (original author), + see /usr/share/doc/fonts-dejavu-core/AUTHORS for full list +Source: https://dejavu-fonts.github.io/ + +Files: * +Copyright: Copyright (c) 2003 by Bitstream, Inc. All Rights Reserved. + Bitstream Vera is a trademark of Bitstream, Inc. + DejaVu changes are in public domain. +License: bitstream-vera + Permission is hereby granted, free of charge, to any person obtaining a copy + of the fonts accompanying this license ("Fonts") and associated + documentation files (the "Font Software"), to reproduce and distribute the + Font Software, including without limitation the rights to use, copy, merge, + publish, distribute, and/or sell copies of the Font Software, and to permit + persons to whom the Font Software is furnished to do so, subject to the + following conditions: + . + The above copyright and trademark notices and this permission notice shall + be included in all copies of one or more of the Font Software typefaces. + . + The Font Software may be modified, altered, or added to, and in particular + the designs of glyphs or characters in the Fonts may be modified and + additional glyphs or characters may be added to the Fonts, only if the fonts + are renamed to names not containing either the words "Bitstream" or the word + "Vera". + . + This License becomes null and void to the extent applicable to Fonts or Font + Software that has been modified and is distributed under the "Bitstream + Vera" names. + . + The Font Software may be sold as part of a larger software package but no + copy of one or more of the Font Software typefaces may be sold by itself. + . + THE FONT SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS + OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTIES OF MERCHANTABILITY, + FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT OF COPYRIGHT, PATENT, + TRADEMARK, OR OTHER RIGHT. IN NO EVENT SHALL BITSTREAM OR THE GNOME + FOUNDATION BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, INCLUDING + ANY GENERAL, SPECIAL, INDIRECT, INCIDENTAL, OR CONSEQUENTIAL DAMAGES, + WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF + THE USE OR INABILITY TO USE THE FONT SOFTWARE OR FROM OTHER DEALINGS IN THE + FONT SOFTWARE. + . + Except as contained in this notice, the names of Gnome, the Gnome + Foundation, and Bitstream Inc., shall not be used in advertising or + otherwise to promote the sale, use or other dealings in this Font Software + without prior written authorization from the Gnome Foundation or Bitstream + Inc., respectively. For further information, contact: fonts at gnome dot + org. + +Files: debian/* +Copyright: (C) 2005-2006 Peter Cernak + (C) 2006-2011 Davide Viti + (C) 2011-2013 Christian Perrier + (C) 2013 Fabian Greffrath +License: GPL-2+ + This program is free software; you can redistribute it + and/or modify it under the terms of the GNU General Public + License as published by the Free Software Foundation; either + version 2 of the License, or (at your option) any later + version. + . + This program is distributed in the hope that it will be + useful, but WITHOUT ANY WARRANTY; without even the implied + warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR + PURPOSE. See the GNU General Public License for more + details. + . + You should have received a copy of the GNU General Public + License along with this package; if not, write to the Free + Software Foundation, Inc., 51 Franklin St, Fifth Floor, + Boston, MA 02110-1301 USA + . + On Debian systems, the full text of the GNU General Public + License version 2 can be found in the file + /usr/share/common-licenses/GPL-2'. diff --git a/tools/ePassport/epassport/config.py b/tools/ePassport/epassport/config.py new file mode 100644 index 000000000..6393cadae --- /dev/null +++ b/tools/ePassport/epassport/config.py @@ -0,0 +1,264 @@ +"""Paths, persisted settings and the app data directory. + +Dumps contain live personal data, so the data directory is created 0700 and +nothing sensitive is written outside it. +""" + +from __future__ import annotations + +import datetime as dt +import json +import logging +import os +from dataclasses import asdict, dataclass, field +from pathlib import Path + +log = logging.getLogger(__name__) + +APP_NAME = "ePassport" + +#: Directory names this app used to go by. Dumps hold real personal data and +#: are not reproducible without the document in hand, so a rename must carry +#: them across rather than silently start a fresh, empty directory. +LEGACY_NAMES = ("pm3-passport",) + + +def _adopt_legacy(base: Path, name: str) -> Path: + """Return ``base/name``, moving an older directory into place first.""" + path = base / name + if path.exists(): + return path + for legacy in LEGACY_NAMES: + old = base / legacy + if not old.is_dir(): + continue + try: + old.rename(path) + except OSError as exc: + log.warning("could not move %s to %s: %s", old, path, exc) + return old # keep using the old location rather than lose it + log.info("moved %s to %s", old, path) + return path + return path + + +def data_dir() -> Path: + """``$XDG_DATA_HOME/ePassport``, created 0700.""" + base = os.environ.get("XDG_DATA_HOME") or (Path.home() / ".local" / "share") + path = _adopt_legacy(Path(base), APP_NAME) + path.mkdir(parents=True, exist_ok=True) + _harden(path) + return path + + +def config_path() -> Path: + base = os.environ.get("XDG_CONFIG_HOME") or (Path.home() / ".config") + path = _adopt_legacy(Path(base), APP_NAME) + path.mkdir(parents=True, exist_ok=True) + _harden(path) + return path / "settings.json" + + +def dumps_dir() -> Path: + path = data_dir() / "dumps" + path.mkdir(parents=True, exist_ok=True) + _harden(path) + return path + + +def new_dump_dir(now: dt.datetime | None = None) -> Path: + """A fresh, app-managed directory named for the UTC timestamp.""" + stamp = (now or dt.datetime.now(dt.timezone.utc)).strftime("%Y%m%dT%H%M%SZ") + path = dumps_dir() / stamp + suffix = 1 + while path.exists(): + path = dumps_dir() / f"{stamp}-{suffix}" + suffix += 1 + path.mkdir(parents=True) + _harden(path) + return path + + +@dataclass +class DumpEntry: + """One dump directory, as listed in the Dumps browser.""" + + path: Path + modified: float = 0.0 + files: int = 0 + size: int = 0 + + @property + def name(self) -> str: + return self.path.name + + @property + def when(self) -> str: + """The UTC stamp in the directory name, rendered readably.""" + stem = self.path.name + try: + moment = dt.datetime.strptime(stem[:16], "%Y%m%dT%H%M%SZ") + except ValueError: + return stem + return moment.strftime("%Y-%m-%d %H:%M:%S UTC") + + @property + def is_empty(self) -> bool: + return self.files == 0 + + @property + def summary(self) -> str: + if self.is_empty: + return "empty - the read did not complete" + return f"{self.files} files, {self.size / 1024:.1f} kB" + + +def list_dumps() -> list[DumpEntry]: + """Every dump in the app's dumps directory, newest first.""" + root = dumps_dir() + out: list[DumpEntry] = [] + for entry in root.iterdir(): + if not entry.is_dir(): + continue + files = [f for f in entry.iterdir() if f.is_file()] + try: + modified = entry.stat().st_mtime + except OSError: + modified = 0.0 + out.append( + DumpEntry( + path=entry, + modified=modified, + files=len(files), + size=sum(f.stat().st_size for f in files if f.is_file()), + ) + ) + # Sort by the UTC stamp in the name: several dumps created in the same + # second share an mtime, and the resulting order looks arbitrary. The + # name is the read time and is unique by construction. + return sorted(out, key=lambda d: (d.name, d.modified), reverse=True) + + +def prune_empty_dumps() -> int: + """Remove dump directories left behind by reads that never produced a file.""" + removed = 0 + for entry in list_dumps(): + if entry.is_empty: + try: + entry.path.rmdir() + removed += 1 + except OSError as exc: + log.debug("could not remove empty dump %s: %s", entry.path, exc) + return removed + + +def _harden(path: Path) -> None: + try: + path.chmod(0o700) + except OSError as exc: # e.g. a mounted share that ignores modes + log.debug("could not chmod 0700 %s: %s", path, exc) + + +def browse_start(last_dump: str = "") -> Path: + """Where the folder picker should open. + + A dump you opened last time was picked *inside* some folder, so offer that + folder again rather than the app's own dumps directory - otherwise every + trip through the picker starts from scratch. + """ + if last_dump: + candidate = Path(last_dump).expanduser().resolve() + if candidate.is_dir(): + if candidate.parent.is_dir(): + return candidate.parent + elif candidate.parent.is_dir(): + return candidate.parent + return dumps_dir() + + +def project_root() -> Path: + """The directory holding the ``ePassport`` script and ``samples/``.""" + return Path(__file__).resolve().parent.parent + + +def samples_dir() -> Path | None: + """The generated sample dumps, if they have been built. + + They are not checked in - ``tools_make_sample.py`` creates them - so this + is None until someone runs it. + """ + path = project_root() / "samples" + return path if path.is_dir() else None + + +def assets_dir() -> Path: + return Path(__file__).resolve().parent / "assets" + + +def font(name: str) -> str: + """Path to a bundled font, falling back to Kivy's default if absent.""" + candidate = assets_dir() / "fonts" / name + return str(candidate) if candidate.is_file() else "Roboto" + + +@dataclass +class Settings: + """Persisted user settings. Deliberately holds no MRZ data by default.""" + + pm3_binary: str = "" + timeout_seconds: float = 120.0 + camera_index: int = 0 + dark_chrome: bool = False + remember_bac: bool = False + last_document_number: str = "" + last_date_of_birth: str = "" + last_date_of_expiry: str = "" + last_dump_dir: str = "" + tesseract_cmd: str = "" + #: "fit" fills the window with whatever document is loaded; "true" puts + #: every format on one millimetre scale, so MRZ print matches across them. + page_scale_mode: str = "fit" + #: Chosen so the content area comes out at the reference document's own + #: 125:88 - otherwise a passport is letterboxed on first run, which reads + #: as the app failing to use the window rather than as a shape mismatch. + window_width: int = 1100 + window_height: int = 850 + warnings: list[str] = field(default_factory=list) + + # -- persistence ------------------------------------------------------ + @classmethod + def load(cls, path: Path | None = None) -> "Settings": + path = path or config_path() + if not path.is_file(): + return cls() + try: + raw = json.loads(path.read_text(encoding="utf-8")) + except (OSError, json.JSONDecodeError) as exc: + log.warning("ignoring unreadable settings file %s: %s", path, exc) + return cls() + known = {f for f in cls.__dataclass_fields__} + settings = cls(**{k: v for k, v in raw.items() if k in known}) + if not settings.remember_bac: + settings.forget_bac() + return settings + + def save(self, path: Path | None = None) -> None: + path = path or config_path() + data = asdict(self) + if not self.remember_bac: + for key in ( + "last_document_number", + "last_date_of_birth", + "last_date_of_expiry", + ): + data[key] = "" + try: + path.write_text(json.dumps(data, indent=2), encoding="utf-8") + path.chmod(0o600) + except OSError as exc: + log.warning("could not save settings to %s: %s", path, exc) + + def forget_bac(self) -> None: + self.last_document_number = "" + self.last_date_of_birth = "" + self.last_date_of_expiry = "" diff --git a/tools/ePassport/epassport/emrtd/__init__.py b/tools/ePassport/epassport/emrtd/__init__.py new file mode 100644 index 000000000..e69de29bb diff --git a/tools/ePassport/epassport/emrtd/__main__.py b/tools/ePassport/epassport/emrtd/__main__.py new file mode 100644 index 000000000..1fe76c292 --- /dev/null +++ b/tools/ePassport/epassport/emrtd/__main__.py @@ -0,0 +1,120 @@ +"""Parse a dump directory and print the resulting PassportRecord. + + python3 -m epassport.emrtd samples/td3_utopia + +This is the headless half of the app: no Kivy, no hardware. +""" + +from __future__ import annotations + +import sys +from pathlib import Path + +from .dg import load_dump +from .model import PassportRecord + + +def render(record: PassportRecord) -> str: + out: list[str] = [] + add = out.append + add(f"source : {record.source_dir}") + m = record.mrz + if m: + add(f"MRZ kind : {m.kind}") + add(f"document type : {m.document_type} ({m.document_code})") + add(f"issuing state : {m.issuing_state} - {m.issuing_state_name}") + add(f"surname : {m.surname}") + add(f"given names : {m.given_names}") + add(f"doc number : {m.document_number.value} [{m.document_number.badge}]") + add(f"nationality : {m.nationality} - {m.nationality_name}") + add(f"date of birth : {m.dob_text} [{m.date_of_birth.badge}]") + add(f"sex : {m.sex_label}") + add(f"date of expiry: {m.expiry_text} [{m.date_of_expiry.badge}]") + add(f"composite : [{m.composite.badge}]") + add( + f"check digits : {'all valid' if m.all_checks_ok else 'FAILED: ' + ', '.join(m.failed_checks())}" + ) + for line in m.lines: + add(f" {line}") + else: + add("MRZ : (none)") + + add("") + add( + f"EF_COM : LDS {record.com.lds_version} Unicode {record.com.unicode_version}" + ) + add(f" announced DG: {record.com.present_dgs}") + + p = record.personal + if not p.is_empty(): + add("") + add("DG11 personal :") + for key, value in vars(p).items(): + if value: + add(f" {key:<20}: {value}") + + d = record.document + if not d.is_empty(): + add("") + add("DG12 document :") + for key, value in vars(d).items(): + if value and not key.startswith("image_"): + add(f" {key:<20}: {value}") + + s = record.security + if s.protocols or s.aa_algorithm: + add("") + add("DG14/15 :") + for proto in s.protocols: + add(f" protocol : {proto}") + if s.aa_algorithm: + add(f" AA public key : {s.aa_algorithm} {s.aa_key_size}") + + add("") + add("EF_SOD :") + if not record.sod.available: + add(f" {record.sod.message}") + else: + add(f" hash algorithm : {record.sod.hash_algorithm}") + add(f" signature algorithm : {record.sod.signature_algorithm}") + add(f" signer subject : {record.sod.signer_subject}") + add(f" signer issuer : {record.sod.signer_issuer}") + add(f" valid : {record.sod.valid_from} .. {record.sod.valid_to}") + for row in record.sod.hashes: + add(f" DG{row.dg:<2} {row.status:<12} {row.expected[:32]}...") + + add("") + add("images :") + add(f" DG2 portrait : {len(record.portrait_png)} bytes PNG") + add(f" DG5 portrait : {len(record.displayed_portrait_png)} bytes PNG") + add(f" DG7 signature : {len(record.signature_png)} bytes PNG") + + add("") + add("files :") + for f in record.files: + if f.state == "absent" and not f.size: + continue + add(f" {f.name:<16} {f.size:>7} {f.state_label}") + + if record.warnings: + add("") + add("warnings :") + for w in record.warnings: + add(f" - {w}") + return "\n".join(out) + + +def main(argv: list[str]) -> int: + if len(argv) != 2: + print(__doc__) + return 2 + directory = Path(argv[1]) + if not directory.is_dir(): + print(f"not a directory: {directory}", file=sys.stderr) + return 1 + print(render(load_dump(directory))) + return 0 + + +if __name__ == "__main__": + raise SystemExit(main(sys.argv)) diff --git a/tools/ePassport/epassport/emrtd/countries.py b/tools/ePassport/epassport/emrtd/countries.py new file mode 100644 index 000000000..77015f841 --- /dev/null +++ b/tools/ePassport/epassport/emrtd/countries.py @@ -0,0 +1,274 @@ +"""ICAO / ISO-3166 alpha-3 code -> country name. + +GENERATED FILE - do not edit by hand. Regenerate with:: + + python3 tools_gen_countries.py /client/src/cmdlffdxb.c + +Names are taken verbatim from the proxmark3 client's own ISO-3166 table +(``fdxbCountryMapping`` in ``client/src/cmdlffdxb.c``); the numeric -> +alpha-3 bridge and the ICAO-specific non-ISO codes are applied by the +generator. No runtime dependencies. +""" + +from __future__ import annotations + +COUNTRIES: dict[str, str] = { + "ABW": "Aruba", + "AFG": "Afghanistan", + "AGO": "Angola", + "AIA": "Anguilla", + "ALB": "Albania", + "AND": "Andorra", + "ARE": "United Arab Emirates", + "ARG": "Argentina", + "ARM": "Armenia", + "ASM": "American Samoa", + "ATA": "Antarctica", + "ATF": "French Southern Territories", + "ATG": "Antigua and Barbuda", + "AUT": "Austria", + "AZE": "Azerbaijan", + "BEL": "Belgium", + "BEN": "Benin", + "BES": "Bonaire", + "BFA": "Burkina Faso", + "BGD": "Bangladesh", + "BGR": "Bulgaria", + "BHR": "Bahrain", + "BHS": "The Bahamas", + "BIH": "Bosnia and Herzegovina", + "BLR": "Belarus", + "BLZ": "Belize", + "BMU": "Bermuda", + "BOL": "Bolivia", + "BRA": "Brazil", + "BRB": "Barbados", + "BTN": "Bhutan", + "BVT": "Bouvet Island", + "BWA": "Botswana", + "CAF": "Central African Republic", + "CAN": "Canada", + "CHE": "Switzerland", + "CHL": "Chile", + "CHN": "China", + "CIV": "Ivory Coast", + "CMR": "Cameroon", + "COD": "Democratic Republic of the Congo", + "COG": "Republic of the Congo", + "COK": "Cook Islands", + "COL": "Colombia", + "COM": "Comoros", + "CPV": "Cape Verde", + "CUB": "Cuba", + "CUW": "Curaçao", + "CYP": "Cyprus", + "CZE": "Czech Republic", + "D": "Germany", + "DEU": "Germany", + "DJI": "Djibouti", + "DMA": "Dominica", + "DOM": "Dominican Republic", + "DZA": "Algeria", + "EGY": "Egypt", + "ERI": "Eritrea", + "ESH": "Western Sahara", + "ESP": "Spain", + "EST": "Estonia", + "ETH": "Ethiopia", + "EUE": "European Union", + "FIN": "Finland", + "FJI": "Fiji", + "FLK": "Falkland Islands", + "FRA": "France", + "FRO": "Faroe Islands", + "FSM": "Federated States of Micronesia", + "GAB": "Gabon", + "GBD": "British Overseas Territories Citizen", + "GBN": "British National (Overseas)", + "GBO": "British Overseas Citizen", + "GBP": "British Protected Person", + "GBR": "United Kingdom", + "GBS": "British Subject", + "GEO": "Georgia (country)", + "GGY": "Bailiwick of Guernsey", + "GHA": "Ghana", + "GIB": "Gibraltar", + "GIN": "Guinea", + "GLP": "Guadeloupe", + "GMB": "The Gambia", + "GNB": "Guinea-Bissau", + "GRD": "Grenada", + "GRL": "Greenland", + "GTM": "Guatemala", + "GUF": "French Guiana", + "GUM": "Guam", + "GUY": "Guyana", + "HKG": "Hong Kong", + "HND": "Honduras", + "HRV": "Croatia", + "HTI": "Haiti", + "HUN": "Hungary", + "IDN": "Indonesia", + "IMN": "Isle of Man", + "IND": "India", + "IOT": "British Indian Ocean Territory", + "IRL": "Republic of Ireland", + "IRN": "Iran (Islamic Republic of)", + "IRQ": "Iraq", + "ISL": "Iceland", + "ISR": "Israel", + "ITA": "Italy", + "JEY": "Jersey", + "JOR": "Jordan", + "KAZ": "Kazakhstan", + "KEN": "Kenya", + "KGZ": "Kyrgyzstan", + "KHM": "Cambodia", + "KIR": "Kiribati", + "KNA": "Saint Kitts and Nevis", + "KOR": "South Korea", + "KWT": "Kuwait", + "LAO": "Laos", + "LBN": "Lebanon", + "LBR": "Liberia", + "LBY": "Libya", + "LCA": "Saint Lucia", + "LIE": "Liechtenstein", + "LKA": "Sri Lanka", + "LSO": "Lesotho", + "LTU": "Lithuania", + "LUX": "Luxembourg", + "LVA": "Latvia", + "MAC": "Macau", + "MAF": "Collectivity of Saint Martin", + "MAR": "Morocco", + "MCO": "Monaco", + "MDA": "Moldova", + "MDG": "Madagascar", + "MDV": "Maldives", + "MEX": "Mexico", + "MHL": "Marshall Islands", + "MKD": "North Macedonia", + "MLI": "Mali", + "MLT": "Malta", + "MMR": "Myanmar", + "MNE": "Montenegro", + "MNG": "Mongolia", + "MOZ": "Mozambique", + "MRT": "Mauritania", + "MSR": "Montserrat", + "MTQ": "Martinique", + "MUS": "Mauritius", + "MWI": "Malawi", + "MYS": "Malaysia", + "MYT": "Mayotte", + "NAM": "Namibia", + "NCL": "New Caledonia", + "NER": "Niger", + "NFK": "Norfolk Island", + "NGA": "Nigeria", + "NIC": "Nicaragua", + "NIU": "Niue", + "NLD": "Kingdom of the Netherlands", + "NOR": "Norway", + "NPL": "Nepal", + "NRU": "Nauru", + "NZL": "New Zealand", + "OMN": "Oman", + "PAK": "Pakistan", + "PAN": "Panama", + "PCN": "Pitcairn Islands", + "PHL": "Philippines", + "PLW": "Palau", + "PNG": "Papua New Guinea", + "POL": "Poland", + "PRI": "Puerto Rico", + "PRK": "North Korea", + "PRT": "Portugal", + "PRY": "Paraguay", + "PSE": "State of Palestine", + "PYF": "French Polynesia", + "QAT": "Qatar", + "REU": "Réunion", + "RKS": "Kosovo", + "ROU": "Romania", + "RUS": "Russia", + "RWA": "Rwanda", + "SAU": "Saudi Arabia", + "SDN": "Sudan", + "SGP": "Singapore", + "SGS": "South Georgia and the South Sandwich Islands", + "SHN": "Saint Helena", + "SJM": "Svalbard", + "SLB": "Solomon Islands", + "SLE": "Sierra Leone", + "SLV": "El Salvador", + "SMR": "San Marino", + "SOM": "Somalia", + "SPM": "Saint Pierre and Miquelon", + "SRB": "Serbia", + "STP": "São Tomé and Príncipe", + "SUR": "Suriname", + "SVK": "Slovakia", + "SVN": "Slovenia", + "SWE": "Sweden", + "SWZ": "Eswatini", + "SYC": "Seychelles", + "SYR": "Syria", + "TCA": "Turks and Caicos Islands", + "TCD": "Chad", + "TGO": "Togo", + "THA": "Thailand", + "TJK": "Tajikistan", + "TKL": "Tokelau", + "TKM": "Turkmenistan", + "TLS": "East Timor", + "TON": "Tonga", + "TTO": "Trinidad and Tobago", + "TUN": "Tunisia", + "TUR": "Turkey", + "TUV": "Tuvalu", + "TWN": "Taiwan", + "TZA": "Tanzania", + "UGA": "Uganda", + "UKR": "Ukraine", + "UMI": "United States Minor Outlying Islands", + "UNA": "United Nations Specialized Agency", + "UNK": "Kosovo (UNMIK)", + "UNO": "United Nations Organization", + "USA": "United States", + "UTO": "Utopia", + "UZB": "Uzbekistan", + "VAT": "Holy See", + "VCT": "Saint Vincent and the Grenadines", + "VGB": "British Virgin Islands", + "VIR": "United States Virgin Islands", + "VNM": "Vietnam", + "VUT": "Vanuatu", + "WSM": "Samoa", + "XBA": "African Development Bank", + "XCC": "Caribbean Community", + "XCO": "Common Market for Eastern and Southern Africa", + "XDC": "Southern African Development Community", + "XEC": "Economic Community of West African States", + "XIM": "African Export-Import Bank", + "XOM": "Sovereign Military Order of Malta", + "XPO": "International Criminal Police Organization", + "XXA": "Stateless person", + "XXB": "Refugee", + "XXC": "Refugee (other)", + "XXX": "Unspecified nationality", + "YEM": "Yemen", + "ZAF": "South Africa", + "ZMB": "Zambia", + "ZWE": "Zimbabwe", + "ZZZ": "Unknown", +} + + +def country_name(code: str) -> str: + """Full country name for an MRZ alpha-3 code, or the code itself.""" + if not code: + return "" + key = code.strip().upper().rstrip("<") + return COUNTRIES.get(key, key) diff --git a/tools/ePassport/epassport/emrtd/dg.py b/tools/ePassport/epassport/emrtd/dg.py new file mode 100644 index 000000000..34b6361df --- /dev/null +++ b/tools/ePassport/epassport/emrtd/dg.py @@ -0,0 +1,362 @@ +"""Per-data-group decoders: dump directory in, :class:`PassportRecord` out. + +Values are parsed from the binaries, never scraped from ``hf emrtd info`` +stdout - TLV is stable, printed text is not. +""" + +from __future__ import annotations + +import logging +from pathlib import Path + +from . import images, tlv +from .model import ( + ComInfo, + DocumentDetails, + DumpFile, + FileState, + PassportRecord, + PersonalDetails, + SecurityInfo, +) +from .mrz import MrzError, parse as parse_mrz + +log = logging.getLogger(__name__) + +#: Files pm3 writes, in the order the FILES tab lists them. Mirrors +#: ``dg_table`` in ``client/src/cmdhfemrtd.c``. +DG_FILES: tuple[tuple[str, int, str, bool], ...] = ( + ("EF_COM", 0x60, "Header and Data Group Presence Information", False), + ("EF_DG1", 0x61, "Details recorded in MRZ", False), + ("EF_DG2", 0x75, "Encoded Face", False), + ("EF_DG3", 0x63, "Encoded Finger(s)", True), + ("EF_DG4", 0x76, "Encoded Eye(s)", True), + ("EF_DG5", 0x65, "Displayed Portrait", False), + ("EF_DG6", 0x66, "Reserved for Future Use", False), + ("EF_DG7", 0x67, "Displayed Signature or Usual Mark", False), + ("EF_DG8", 0x68, "Data Feature(s)", False), + ("EF_DG9", 0x69, "Structure Feature(s)", False), + ("EF_DG10", 0x6A, "Substance Feature(s)", False), + ("EF_DG11", 0x6B, "Additional Personal Detail(s)", False), + ("EF_DG12", 0x6C, "Additional Document Detail(s)", False), + ("EF_DG13", 0x6D, "Optional Detail(s)", False), + ("EF_DG14", 0x6E, "Security Options", False), + ("EF_DG15", 0x6F, "Active Authentication Public Key Info", False), + ("EF_DG16", 0x70, "Person(s) to Notify", False), + ("EF_SOD", 0x77, "Document Security Object", False), + ("EF_CardAccess", 0x00, "PACE SecurityInfos", False), + ("EF_CardSecurity", 0x00, "PACE SecurityInfos for Chip Auth Mapping", False), +) + +#: EF_COM's 5C tag list maps DG tags back to data-group numbers. +TAG_TO_DG: dict[int, int] = { + 0x61: 1, + 0x75: 2, + 0x63: 3, + 0x76: 4, + 0x65: 5, + 0x66: 6, + 0x67: 7, + 0x68: 8, + 0x69: 9, + 0x6A: 10, + 0x6B: 11, + 0x6C: 12, + 0x6D: 13, + 0x6E: 14, + 0x6F: 15, + 0x70: 16, +} + + +def read_dump_file(directory: Path, name: str) -> tuple[Path | None, bytes]: + """Find ``name`` in ``directory``, accepting ``.bin`` or ``.BIN``.""" + for suffix in (".bin", ".BIN", ".Bin", ""): + candidate = directory / f"{name}{suffix}" + if candidate.is_file(): + try: + return candidate, candidate.read_bytes() + except OSError as exc: + log.warning("cannot read %s: %s", candidate, exc) + return candidate, b"" + return None, b"" + + +# ---------------------------------------------------------------- EF_COM +def parse_com(data: bytes) -> ComInfo: + nodes = tlv.parse(data) + info = ComInfo() + raw_lds = tlv.find_value(nodes, 0x5F01) + raw_uni = tlv.find_value(nodes, 0x5F36) + if raw_lds: + info.lds_version = _dotted(tlv.text(raw_lds), 2) + if raw_uni: + info.unicode_version = _dotted(tlv.text(raw_uni), 2) + taglist = tlv.find_value(nodes, 0x5C) or b"" + info.present_tags = list(taglist) + info.present_dgs = sorted({TAG_TO_DG[t] for t in taglist if t in TAG_TO_DG}) + return info + + +def _dotted(digits: str, group: int) -> str: + """``0107`` -> ``01.07``; ``040000`` -> ``04.00.00``.""" + clean = "".join(ch for ch in digits if ch.isdigit()) + if not clean: + return digits + return ".".join(clean[i : i + group] for i in range(0, len(clean), group)) + + +# ---------------------------------------------------------------- EF_DG1 +def parse_dg1(data: bytes): + """Return the parsed MRZ from EF_DG1 (tag 61 -> 5F1F), or None.""" + nodes = tlv.parse(data) + raw = tlv.find_value(nodes, 0x5F1F) + if raw is None: + return None + text = tlv.text(raw).replace(" ", "") + for width in (44, 36, 30): + if len(text) % width == 0 and len(text) // width in (2, 3): + lines = [text[i : i + width] for i in range(0, len(text), width)] + try: + return parse_mrz(lines) + except MrzError: + continue + try: + return parse_mrz(text) + except MrzError as exc: + log.warning("EF_DG1 does not contain a usable MRZ: %s", exc) + return None + + +# --------------------------------------------------------------- EF_DG11 +_DG11_TAGS = { + 0x5F0E: "full_name", + 0x5F10: "personal_number", + 0x5F11: "place_of_birth", + 0x5F2B: "full_date_of_birth", + 0x5F42: "address", + 0x5F12: "telephone", + 0x5F13: "profession", + 0x5F14: "title", + 0x5F15: "personal_summary", + 0x5F18: "custody_information", +} + + +def parse_dg11(data: bytes) -> PersonalDetails: + nodes = tlv.parse(data) + out = PersonalDetails() + for tag, attr in _DG11_TAGS.items(): + hit = tlv.find(nodes, tag) + if hit is None: + continue + value = _clean_field(hit.value, numeric=attr == "full_date_of_birth") + setattr(out, attr, value) + other = tlv.find(nodes, 0xA0) # other names, wrapped in a count + 5F0F list + if other is not None: + out.other_names = [ + _clean_field(n.value) for n in other.find_all(0x5F0F) if n.value + ] + return out + + +# --------------------------------------------------------------- EF_DG12 +_DG12_TAGS = { + 0x5F19: "issuing_authority", + 0x5F26: "date_of_issue", + 0x5F1B: "endorsements", + 0x5F1C: "tax_exit_requirements", + 0x5F55: "personalization_time", + 0x5F56: "personalization_device", +} + + +def parse_dg12(data: bytes) -> DocumentDetails: + nodes = tlv.parse(data) + out = DocumentDetails() + for tag, attr in _DG12_TAGS.items(): + hit = tlv.find(nodes, tag) + if hit is None: + continue + setattr(out, attr, _clean_field(hit.value, numeric=attr.startswith("date"))) + for tag, attr in ((0x5F1D, "image_of_front"), (0x5F1E, "image_of_rear")): + hit = tlv.find(nodes, tag) + if hit is not None: + setattr(out, attr, hit.value) + other = tlv.find(nodes, 0xA0) + if other is not None: + out.other_persons = [ + _clean_field(n.value) for n in other.find_all(0x5F1A) if n.value + ] + return out + + +def _clean_field(raw: bytes, *, numeric: bool = False) -> str: + """Decode an LDS text field. ``<`` is a separator, not a literal.""" + text = tlv.text(raw) + if numeric: + # Dates are sometimes BCD-packed rather than ASCII. + if text and not text.strip("0123456789"): + return text + if len(raw) == 4: + return raw.hex() + return text.replace("<<", ", ").replace("<", " ").strip().rstrip(",").strip() + + +# ----------------------------------------------------------- EF_DG14/15 +_SECURITY_OIDS = { + "0.4.0.127.0.7.2.2.1.1": "PACE (DH, generic mapping)", + "0.4.0.127.0.7.2.2.1.2": "PACE (ECDH, generic mapping)", + "0.4.0.127.0.7.2.2.3.2": "Terminal Authentication (ECDSA)", + "0.4.0.127.0.7.2.2.4": "PACE info", + "0.4.0.127.0.7.2.2.5": "Chip Authentication (public key)", + "0.4.0.127.0.7.2.2.3.1": "Terminal Authentication (RSA)", + "2.23.136.1.1.5": "Active Authentication", + "0.4.0.127.0.7.2.2.1": "Chip Authentication", +} + + +def parse_security(dg14: bytes, dg15: bytes) -> SecurityInfo: + out = SecurityInfo() + if dg14: + out.dg14_hex = dg14.hex().upper() + out.protocols = _oid_summary(dg14) + if dg15: + out.dg15_hex = dg15.hex().upper() + _describe_aa_key(dg15, out) + return out + + +def _oid_summary(data: bytes) -> list[str]: + """Best-effort list of security protocol OIDs found in DG14.""" + try: + from asn1crypto.core import ObjectIdentifier + except ImportError: + return [] + found: list[str] = [] + pos = 0 + while True: + idx = data.find(b"\x06", pos) + if idx < 0 or idx + 1 >= len(data): + break + length = data[idx + 1] + chunk = data[idx : idx + 2 + length] + pos = idx + 1 + if length == 0 or length > 32 or idx + 2 + length > len(data): + continue + try: + oid = ObjectIdentifier.load(chunk).dotted + except Exception: + continue + label = _SECURITY_OIDS.get(oid) + entry = f"{oid} {label}" if label else oid + if entry not in found: + found.append(entry) + return found + + +def _describe_aa_key(dg15: bytes, out: SecurityInfo) -> None: + """Decode the SubjectPublicKeyInfo in DG15 (tag 6F).""" + nodes = tlv.parse(dg15) + spki = nodes[0].value if nodes and nodes[0].tag == 0x6F else dg15 + out.aa_public_key_hex = spki.hex().upper() + try: + from cryptography.hazmat.primitives.serialization import load_der_public_key + except ImportError: + out.aa_algorithm = "install 'cryptography' to decode the AA public key" + return + try: + key = load_der_public_key(spki) + except Exception as exc: + out.aa_algorithm = f"undecodable ({exc.__class__.__name__})" + return + out.aa_algorithm = type(key).__name__.replace("_", "").replace("PublicKey", "") + size = getattr(key, "key_size", None) + if size: + out.aa_key_size = f"{size} bit" + + +# ---------------------------------------------------------------- images +def extract_image(data: bytes) -> bytes: + """Carve the image out of a CBEFF-wrapped DG and return PNG bytes.""" + if not data: + return b"" + png, blob = images.decode_to_png(data) + if png is None and blob is not None: + log.info( + "found %s image at offset %d but no decoder produced a PNG", + blob.fmt, + blob.offset, + ) + return png or b"" + + +# ----------------------------------------------------------- whole dump +def load_dump(directory: Path) -> PassportRecord: + """Parse a pm3 dump directory into a :class:`PassportRecord`.""" + directory = Path(directory) + record = PassportRecord(source_dir=directory) + raw: dict[str, bytes] = {} + + for name, _tag, note, eac in DG_FILES: + path, data = read_dump_file(directory, name) + entry = DumpFile(name=name, path=path, size=len(data), note=note, data=data) + if data: + entry.state = FileState.PRESENT + raw[name] = data + elif eac: + entry.state = FileState.PROTECTED + else: + entry.state = FileState.ABSENT + record.files.append(entry) + + if "EF_COM" in raw: + record.com = parse_com(raw["EF_COM"]) + + if "EF_DG1" in raw: + record.mrz = parse_dg1(raw["EF_DG1"]) + if record.mrz is None: + record.warnings.append( + "EF_DG1 is present but its MRZ could not be decoded." + ) + _mark(record, "EF_DG1", FileState.UNREADABLE) + else: + record.warnings.append("EF_DG1 is missing - no MRZ to render.") + + if "EF_DG2" in raw: + record.portrait_png = extract_image(raw["EF_DG2"]) + if not record.portrait_png: + record.warnings.append( + "EF_DG2 is present but the portrait could not be decoded." + ) + if "EF_DG5" in raw: + record.displayed_portrait_png = extract_image(raw["EF_DG5"]) + if "EF_DG7" in raw: + record.signature_png = extract_image(raw["EF_DG7"]) + + if "EF_DG11" in raw: + record.personal = parse_dg11(raw["EF_DG11"]) + if "EF_DG12" in raw: + record.document = parse_dg12(raw["EF_DG12"]) + record.security = parse_security(raw.get("EF_DG14", b""), raw.get("EF_DG15", b"")) + + from .sod import parse_sod # local import: optional dependencies + + record.sod = parse_sod(raw.get("EF_SOD", b""), raw) + + # EF_COM claims data groups that may not have been dumped: reconcile. + for number in record.com.present_dgs: + entry = record.file(f"EF_DG{number}") + if entry is not None and entry.state == FileState.ABSENT: + entry.state = ( + FileState.PROTECTED if number in (3, 4) else FileState.UNREADABLE + ) + entry.note += " (announced in EF_COM, not in dump)" + + return record + + +def _mark(record: PassportRecord, name: str, state: str) -> None: + entry = record.file(name) + if entry is not None: + entry.state = state diff --git a/tools/ePassport/epassport/emrtd/images.py b/tools/ePassport/epassport/emrtd/images.py new file mode 100644 index 000000000..5d5216b66 --- /dev/null +++ b/tools/ePassport/epassport/emrtd/images.py @@ -0,0 +1,125 @@ +"""Locate and decode biometric images inside CBEFF-wrapped data groups. + +DG2/DG5/DG7 wrap the actual image in an ISO/IEC 19794-5 (or 19794-4) header +whose length fields are not always trustworthy in the wild. Rather than trust +them we scan for the image magic, which is what the pm3 client does too. +""" + +from __future__ import annotations + +import io +import logging +from dataclasses import dataclass + +log = logging.getLogger(__name__) + +JPEG_MAGIC = b"\xff\xd8\xff" +JP2_MAGIC = b"\x00\x00\x00\x0c\x6a\x50\x20\x20" # JP2 signature box +J2K_MAGIC = b"\xff\x4f\xff\x51" # raw JPEG2000 codestream +PNG_MAGIC = b"\x89PNG\r\n\x1a\n" + + +@dataclass +class ImageBlob: + """Raw image bytes carved out of a data group.""" + + data: bytes + fmt: str # "jpeg" | "jp2" | "j2k" | "png" + offset: int + + @property + def suffix(self) -> str: + return {"jpeg": ".jpg", "jp2": ".jp2", "j2k": ".j2k", "png": ".png"}[self.fmt] + + +def find_image(buf: bytes) -> ImageBlob | None: + """Return the first embedded image found in ``buf``, or None.""" + candidates: list[tuple[int, str]] = [] + for magic, fmt in ( + (JPEG_MAGIC, "jpeg"), + (JP2_MAGIC, "jp2"), + (J2K_MAGIC, "j2k"), + (PNG_MAGIC, "png"), + ): + idx = buf.find(magic) + if idx >= 0: + candidates.append((idx, fmt)) + if not candidates: + return None + offset, fmt = min(candidates) + return ImageBlob(data=buf[offset:], fmt=fmt, offset=offset) + + +def to_png(blob: ImageBlob) -> bytes | None: + """Transcode an image blob to PNG bytes for Kivy. + + Kivy cannot load JPEG2000, and its JPEG loader is fussy about the odd + truncated stream, so everything goes through Pillow / glymur first. + Returns None when no decoder for the format is installed. + """ + if blob.fmt in ("jpeg", "png"): + png = _png_via_pillow(blob.data) + if png is not None: + return png + if blob.fmt in ("jp2", "j2k"): + png = _png_via_pillow( + blob.data + ) # Pillow has JPEG2000 support when built with openjpeg + if png is not None: + return png + return _png_via_glymur(blob.data) + return None + + +def _png_via_pillow(data: bytes) -> bytes | None: + try: + from PIL import Image + except ImportError: + log.warning("Pillow is not installed - cannot decode portrait") + return None + try: + with Image.open(io.BytesIO(data)) as im: + im.load() + out = io.BytesIO() + im.convert("RGB").save(out, format="PNG") + return out.getvalue() + except Exception as exc: # a truncated portrait must not kill the render + log.info("Pillow could not decode image: %s", exc) + return None + + +def _png_via_glymur(data: bytes) -> bytes | None: + try: + import glymur + import numpy as np + from PIL import Image + except ImportError: + log.warning("glymur/numpy/Pillow missing - cannot decode JPEG2000 portrait") + return None + import tempfile + from pathlib import Path + + tmp = Path(tempfile.mkdtemp(prefix="pm3passport-jp2-")) / "portrait.jp2" + try: + tmp.write_bytes(data) + arr = glymur.Jp2k(str(tmp))[:] + out = io.BytesIO() + Image.fromarray(np.asarray(arr)).convert("RGB").save(out, format="PNG") + return out.getvalue() + except Exception as exc: + log.info("glymur could not decode JPEG2000: %s", exc) + return None + finally: + try: + tmp.unlink(missing_ok=True) + tmp.parent.rmdir() + except OSError: + pass + + +def decode_to_png(buf: bytes) -> tuple[bytes | None, ImageBlob | None]: + """Convenience: carve an image out of a DG and transcode it to PNG.""" + blob = find_image(buf) + if blob is None: + return None, None + return to_png(blob), blob diff --git a/tools/ePassport/epassport/emrtd/model.py b/tools/ePassport/epassport/emrtd/model.py new file mode 100644 index 000000000..d19516085 --- /dev/null +++ b/tools/ePassport/epassport/emrtd/model.py @@ -0,0 +1,267 @@ +"""The single UI-facing object. + +Everything the GUI renders comes from :class:`PassportRecord`. Reading a card +and opening a saved dump produce the same object, so there is exactly one +rendering path. +""" + +from __future__ import annotations + +from dataclasses import dataclass, field +from pathlib import Path + +from .mrz import Mrz + + +class FileState: + """Why a data group is or is not in the dump.""" + + PRESENT = "present" + ABSENT = "absent" + PROTECTED = "protected" # EAC / PACE - readable only with terminal auth + UNREADABLE = "unreadable" # present on the chip but the parse failed + + +@dataclass +class DumpFile: + """One file from the dump directory, as shown in the FILES tab.""" + + name: str + path: Path | None + size: int = 0 + state: str = FileState.ABSENT + note: str = "" + data: bytes = b"" + + @property + def state_label(self) -> str: + return { + FileState.PRESENT: "present", + FileState.ABSENT: "not present", + FileState.PROTECTED: "protected", + FileState.UNREADABLE: "unreadable", + }.get(self.state, self.state) + + +@dataclass +class PersonalDetails: + """EF_DG11 - additional personal details.""" + + full_name: str = "" + other_names: list[str] = field(default_factory=list) + personal_number: str = "" + full_date_of_birth: str = "" + place_of_birth: str = "" + address: str = "" + telephone: str = "" + profession: str = "" + title: str = "" + personal_summary: str = "" + custody_information: str = "" + + def is_empty(self) -> bool: + return not any(vars(self).values()) + + +@dataclass +class DocumentDetails: + """EF_DG12 - additional document details.""" + + issuing_authority: str = "" + date_of_issue: str = "" + other_persons: list[str] = field(default_factory=list) + endorsements: str = "" + tax_exit_requirements: str = "" + image_of_front: bytes = b"" + image_of_rear: bytes = b"" + personalization_time: str = "" + personalization_device: str = "" + + def is_empty(self) -> bool: + return not any(v for k, v in vars(self).items() if not k.startswith("image_")) + + +@dataclass +class SecurityInfo: + """EF_DG14 / EF_DG15 - chip security options and AA public key.""" + + protocols: list[str] = field(default_factory=list) + aa_algorithm: str = "" + aa_key_size: str = "" + aa_public_key_hex: str = "" + dg14_hex: str = "" + dg15_hex: str = "" + + +@dataclass +class SodHash: + """One row of the EF_SOD data-group hash table.""" + + dg: int + expected: str + actual: str = "" + status: str = "not checked" # "match" | "MISMATCH" | "not checked" + + +@dataclass +class SodInfo: + """EF_SOD summary. ``available`` is False when the parser is missing.""" + + available: bool = False + message: str = "" + hash_algorithm: str = "" + signature_algorithm: str = "" + ldsversion: str = "" + signer_subject: str = "" + signer_issuer: str = "" + signer_serial: str = "" + valid_from: str = "" + valid_to: str = "" + hashes: list[SodHash] = field(default_factory=list) + + @property + def mismatches(self) -> list[SodHash]: + return [h for h in self.hashes if h.status == "MISMATCH"] + + +@dataclass +class ComInfo: + """EF_COM - which data groups the chip claims to hold.""" + + lds_version: str = "" + unicode_version: str = "" + present_tags: list[int] = field(default_factory=list) + present_dgs: list[int] = field(default_factory=list) + + +@dataclass +class PassportRecord: + """Everything the UI knows about one document.""" + + source_dir: Path | None = None + mrz: Mrz | None = None + com: ComInfo = field(default_factory=ComInfo) + personal: PersonalDetails = field(default_factory=PersonalDetails) + document: DocumentDetails = field(default_factory=DocumentDetails) + security: SecurityInfo = field(default_factory=SecurityInfo) + sod: SodInfo = field(default_factory=SodInfo) + files: list[DumpFile] = field(default_factory=list) + portrait_png: bytes = b"" + signature_png: bytes = b"" + displayed_portrait_png: bytes = b"" + warnings: list[str] = field(default_factory=list) + + # -- derived, purely for display ------------------------------------- + @property + def surname(self) -> str: + return self.mrz.surname if self.mrz else "" + + @property + def given_names(self) -> str: + if self.mrz and self.mrz.given_names: + return self.mrz.given_names + return "" + + @property + def display_name(self) -> str: + parts = [self.given_names, self.surname] + return " ".join(p for p in parts if p) or "UNKNOWN" + + # -- fields that live in optional data groups ------------------------- + # + # DG11 and DG12 are optional, and plenty of real passports omit them + # entirely - the data is printed on the page but never written to the + # chip. Distinguish "the chip does not carry this" from "empty", so the + # page can say so instead of showing a bare dash. + NOT_ON_CHIP = "not on chip" + + def _optional(self, value: str, dg: int) -> str: + if value: + return value + return self.NOT_ON_CHIP if not self.has_dg(dg) else "" + + @property + def place_of_birth(self) -> str: + return self._optional(self.personal.place_of_birth, 11) + + @property + def issuing_authority(self) -> str: + return self._optional(self.document.issuing_authority, 12) + + @property + def date_of_issue(self) -> str: + formatted = _icao_long_date(self.document.date_of_issue) + return self._optional(formatted, 12) + + @property + def personal_number(self) -> str: + """DG11's personal number, else the MRZ optional-data field. + + Several states - Sweden among them - put the national identity number + in the MRZ optional-data field and ship no DG11 at all, so the value + is recoverable even when the chip carries no personal details. + """ + if self.personal.personal_number: + return self.personal.personal_number + if self.mrz is not None: + optional = self.mrz.optional_data.value.strip() + if optional: + return optional + return self._optional("", 11) + + @property + def personal_number_source(self) -> str: + """Where :attr:`personal_number` came from, for an honest caption.""" + if self.personal.personal_number: + return "DG11" + if self.mrz is not None and self.mrz.optional_data.value.strip(): + return "MRZ" + return "" + + def is_missing(self, value: str) -> bool: + return value == self.NOT_ON_CHIP + + @property + def full_date_of_birth(self) -> str: + """DG11's YYYYMMDD birth date if present, else the MRZ's.""" + long = _icao_long_date(self.personal.full_date_of_birth) + if long: + return long + return self.mrz.dob_text if self.mrz else "" + + def file(self, name: str) -> DumpFile | None: + for f in self.files: + if f.name.upper() == name.upper(): + return f + return None + + def has_dg(self, number: int) -> bool: + f = self.file(f"EF_DG{number}") + return f is not None and f.state == FileState.PRESENT + + +_MONTHS = ( + "JAN", + "FEB", + "MAR", + "APR", + "MAY", + "JUN", + "JUL", + "AUG", + "SEP", + "OCT", + "NOV", + "DEC", +) + + +def _icao_long_date(value: str) -> str: + """``20200401`` -> ``01 APR 2020``. Anything else passes through.""" + digits = "".join(ch for ch in value if ch.isdigit()) + if len(digits) != 8: + return value + year, month, day = digits[0:4], int(digits[4:6]), int(digits[6:8]) + if not 1 <= month <= 12: + return value + return f"{day:02d} {_MONTHS[month - 1]} {year}" diff --git a/tools/ePassport/epassport/emrtd/mrz.py b/tools/ePassport/epassport/emrtd/mrz.py new file mode 100644 index 000000000..85a5cbf05 --- /dev/null +++ b/tools/ePassport/epassport/emrtd/mrz.py @@ -0,0 +1,566 @@ +"""ICAO 9303 machine-readable zone parsing. + +Supports TD1 (3x30), TD2 (2x36) and TD3 / MRV-A (2x44). Everything is pure +logic so it is unit-testable without hardware, a GUI or a dump. +""" + +from __future__ import annotations + +import datetime as _dt +import re +from dataclasses import dataclass, field +from typing import Iterable + +from .countries import country_name + +FILLER = "<" +_WEIGHTS = (7, 3, 1) +_VALID_CHARS = re.compile(r"^[0-9A-Z<]*$") + +#: Common OCR confusions, applied before validation. Keys are what tesseract +#: tends to emit for a filler or a digit in an OCR-B strip. +OCR_CONFUSIONS: dict[str, str] = { + "«": "<", + "»": "<", + "_": "<", + "—": "<", + "–": "<", + "-": "<", + "~": "<", + "*": "<", + " ": "", + "\t": "", +} + + +class MrzError(ValueError): + """Raised when a string cannot be interpreted as an MRZ at all.""" + + +def char_value(ch: str) -> int: + """Numeric weight of one MRZ character (``<``=0, digits, ``A``=10..``Z``=35).""" + if ch == FILLER: + return 0 + if ch.isdigit(): + return int(ch) + if "A" <= ch <= "Z": + return ord(ch) - ord("A") + 10 + raise MrzError(f"character {ch!r} is not valid in an MRZ") + + +def check_digit(data: str) -> str: + """7-3-1 weighted modulo-10 check digit for ``data``.""" + total = 0 + for i, ch in enumerate(data): + total += char_value(ch) * _WEIGHTS[i % 3] + return str(total % 10) + + +def verify(data: str, digit: str) -> bool: + """True when ``digit`` is the correct check digit for ``data``. + + A filler in the check position is accepted only when the field itself is + entirely filler, which is how optional-data fields are left blank. + """ + if digit == FILLER: + return set(data) <= {FILLER} + if not digit.isdigit(): + return False + try: + return check_digit(data) == digit + except MrzError: + return False + + +def clean_line(raw: str) -> str: + """Normalise a single OCR'd line: upper-case, fix confusions, drop noise.""" + out = raw.strip().upper() + for bad, good in OCR_CONFUSIONS.items(): + out = out.replace(bad, good) + return "".join(ch for ch in out if ch.isalnum() or ch == FILLER) + + +def fix_numeric(field_text: str) -> str: + """Coerce a field that must be digits (dates, check digits).""" + table = { + "O": "0", + "Q": "0", + "D": "0", + "U": "0", + "I": "1", + "L": "1", + "T": "1", + "Z": "2", + "A": "4", + "S": "5", + "G": "6", + "B": "8", + "R": "8", + } + return "".join(table.get(ch, ch) for ch in field_text) + + +def fix_alpha(field_text: str) -> str: + """Coerce a field that must be letters (country codes, sex).""" + table = {"0": "O", "1": "I", "2": "Z", "4": "A", "5": "S", "6": "G", "8": "B"} + return "".join(table.get(ch, ch) for ch in field_text) + + +#: Per-format field maps: ``(line index, start, stop, kind)``. ``kind`` is +#: "n" for digits-only, "a" for letters-only; unlisted spans are alphanumeric +#: and left alone. These let OCR output be repaired by position, which is the +#: difference between reading "UT0" and reading "UTO". +FIELD_MAPS: dict[str, tuple[tuple[int, int, int, str], ...]] = { + "TD3": ( + (0, 0, 2, "a"), + (0, 2, 5, "a"), + (1, 9, 10, "n"), + (1, 10, 13, "a"), + (1, 13, 19, "n"), + (1, 19, 20, "n"), + (1, 20, 21, "a"), + (1, 21, 27, "n"), + (1, 27, 28, "n"), + (1, 42, 43, "n"), + (1, 43, 44, "n"), + ), + "TD2": ( + (0, 0, 2, "a"), + (0, 2, 5, "a"), + (1, 9, 10, "n"), + (1, 10, 13, "a"), + (1, 13, 19, "n"), + (1, 19, 20, "n"), + (1, 20, 21, "a"), + (1, 21, 27, "n"), + (1, 27, 28, "n"), + (1, 35, 36, "n"), + ), + "TD1": ( + (0, 0, 2, "a"), + (0, 2, 5, "a"), + (0, 14, 15, "n"), + (1, 0, 6, "n"), + (1, 6, 7, "n"), + (1, 7, 8, "a"), + (1, 8, 14, "n"), + (1, 14, 15, "n"), + (1, 15, 18, "a"), + (1, 29, 30, "n"), + (2, 0, 30, "a"), + ), +} + + +def coerce_lines(lines: list[str], kind: str | None = None) -> list[str]: + """Repair OCR confusions by field position. + + A digit-only field never legitimately contains ``O``; a country code never + contains ``0``. Applying that knowledge before validating turns a great + many near-misses into clean reads. Filler ``<`` is always left alone. + """ + if kind is None: + try: + kind = detect_kind(lines) + except MrzError: + return lines + spans = FIELD_MAPS.get(kind) + if spans is None: + return lines + out = [list(line) for line in lines] + for index, start, stop, mode in spans: + if index >= len(out): + continue + row = out[index] + if stop > len(row): + continue + fixer = fix_numeric if mode == "n" else fix_alpha + for pos in range(start, stop): + ch = row[pos] + if ch != FILLER: + row[pos] = fixer(ch) + return ["".join(row) for row in out] + + +def blind_confusions() -> dict[str, set[str]]: + """Character swaps the 7-3-1 check digits mathematically cannot detect. + + A check digit is a weighted sum taken modulo 10, and the weights 7, 3 and + 1 are all coprime with 10. So substituting a character whose value + differs by a multiple of 10 changes the sum by a multiple of 10 and leaves + every check digit - including the composite - untouched, in any position. + + Character values are ``<``=0, ``0``-``9``=0-9, ``A``-``Z``=10-35, so the + blind pairs are things like ``L``(21) for ``1``(1) and ``S``(28) for + ``8``(8) - which are also precisely the swaps OCR is most likely to make. + """ + alphabet = "0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZ" + out: dict[str, set[str]] = {} + for a in alphabet: + for b in alphabet: + if a != b and (char_value(a) - char_value(b)) % 10 == 0: + out.setdefault(a, set()).add(b) + return out + + +#: The subset of :func:`blind_confusions` that a scanner realistically makes: +#: pairs that look alike *and* are invisible to the check digits. +VISUAL_BLIND_PAIRS: tuple[tuple[str, str], ...] = ( + ("L", "1"), + ("S", "8"), + ("G", "6"), + ("Z", "5"), + ("I", "8"), + ("D", "3"), + ("B", "1"), + ("C", "2"), + ("A", "0"), + ("E", "4"), +) + + +def blind_characters() -> set[str]: + """Characters involved in a visually plausible, undetectable swap.""" + out: set[str] = set() + for a, b in VISUAL_BLIND_PAIRS: + out.add(a) + out.add(b) + return out + + +def ambiguous_positions(value: str) -> list[int]: + """Indices of ``value`` that a check digit could not vouch for.""" + blind = blind_characters() + return [i for i, ch in enumerate(value) if ch in blind] + + +@dataclass +class Checked: + """A field value plus the verdict of its check digit.""" + + value: str + digit: str = "" + ok: bool | None = None # None = no check digit defined for this field + + @property + def badge(self) -> str: + return "" if self.ok is None else ("OK" if self.ok else "BAD") + + +def _expand_year(yy: int, *, past: bool, today: _dt.date) -> int: + """Sliding-window expansion of a two-digit ICAO year. + + Dates of birth are in the past, expiry dates are (usually) in the future; + that is the only reliable disambiguation ICAO gives us. + """ + century = today.year // 100 * 100 + year = century + yy + if past: + if year > today.year: + year -= 100 + else: + # Allow a modest amount of "already expired" before rolling back. + if year < today.year - 20: + year += 100 + elif year > today.year + 30: + year -= 100 + return year + + +def parse_date( + yymmdd: str, *, past: bool, today: _dt.date | None = None +) -> _dt.date | None: + """Expand ``YYMMDD`` to a real date, or None when unparseable.""" + today = today or _dt.date.today() + digits = fix_numeric(yymmdd) + if len(digits) != 6 or not digits.isdigit(): + return None + yy, mm, dd = int(digits[0:2]), int(digits[2:4]), int(digits[4:6]) + if not 1 <= mm <= 12 or not 1 <= dd <= 31: + return None + try: + return _dt.date(_expand_year(yy, past=past, today=today), mm, dd) + except ValueError: + return None + + +def format_date(value: _dt.date | None, raw: str) -> str: + """Passport-page style date: ``01 JAN 1989``. Falls back to the raw digits.""" + if value is None: + return raw + return f"{value.day:02d} {value.strftime('%b').upper()} {value.year}" + + +def split_names(field_text: str) -> tuple[str, str]: + """Split the MRZ name field into ``(surname, given names)``.""" + body = field_text.rstrip(FILLER) + if "<<" in body: + surname, _, given = body.partition("<<") + else: + surname, given = body, "" + return ( + surname.replace(FILLER, " ").strip(), + " ".join(part for part in given.replace(FILLER, " ").split() if part), + ) + + +@dataclass +class Mrz: + """A fully decoded machine-readable zone.""" + + kind: str # "TD1" | "TD2" | "TD3" + lines: list[str] + document_code: str = "" + issuing_state: str = "" + surname: str = "" + given_names: str = "" + document_number: Checked = field(default_factory=Checked) + nationality: str = "" + date_of_birth: Checked = field(default_factory=Checked) + sex: str = "" + date_of_expiry: Checked = field(default_factory=Checked) + optional_data: Checked = field(default_factory=Checked) + optional_data2: str = "" + composite: Checked = field(default_factory=Checked) + dob: _dt.date | None = None + expiry: _dt.date | None = None + + # -- convenience for the UI ------------------------------------------ + @property + def raw(self) -> str: + return "\n".join(self.lines) + + @property + def issuing_state_name(self) -> str: + return country_name(self.issuing_state) + + @property + def nationality_name(self) -> str: + return country_name(self.nationality) + + @property + def sex_label(self) -> str: + return {"M": "M", "F": "F", "X": "X", FILLER: "X", "": "X"}.get( + self.sex, self.sex + ) + + @property + def document_type(self) -> str: + first = self.document_code[:1] + return { + "P": "PASSPORT", + "I": "IDENTITY CARD", + "A": "IDENTITY CARD", + "C": "IDENTITY CARD", + "V": "VISA", + "D": "DIPLOMATIC", + }.get(first, self.document_code or "DOCUMENT") + + @property + def dob_text(self) -> str: + return format_date(self.dob, self.date_of_birth.value) + + @property + def expiry_text(self) -> str: + return format_date(self.expiry, self.date_of_expiry.value) + + @property + def all_checks_ok(self) -> bool: + return all( + c.ok is not False + for c in ( + self.document_number, + self.date_of_birth, + self.date_of_expiry, + self.optional_data, + self.composite, + ) + ) + + def failed_checks(self) -> list[str]: + names = { + "document number": self.document_number, + "date of birth": self.date_of_birth, + "date of expiry": self.date_of_expiry, + "optional data": self.optional_data, + "composite": self.composite, + } + return [label for label, c in names.items() if c.ok is False] + + # -- what the pm3 client needs --------------------------------------- + @property + def bac_document_number(self) -> str: + """Document number as pm3 wants it: <=9 chars, no trailing filler.""" + return self.document_number.value.rstrip(FILLER)[:9] + + @property + def mrz_line2(self) -> str: + """The 44/36-char second line for ``hf emrtd -m``, or "" for TD1.""" + return self.lines[1] if self.kind in ("TD2", "TD3") else "" + + +def _lines_of(text_or_lines: str | Iterable[str]) -> list[str]: + if isinstance(text_or_lines, str): + raw = re.split(r"[\r\n]+", text_or_lines) + else: + raw = list(text_or_lines) + return [clean_line(line) for line in raw if clean_line(line)] + + +def detect_kind(lines: list[str]) -> str: + lengths = [len(line) for line in lines] + if len(lines) == 3 and all(n == 30 for n in lengths): + return "TD1" + if len(lines) == 2 and all(n == 36 for n in lengths): + return "TD2" + if len(lines) == 2 and all(n == 44 for n in lengths): + return "TD3" + raise MrzError(f"unrecognised MRZ geometry: {len(lines)} lines of {lengths}") + + +def _extended_document_number( + number_field: str, digit: str, optional: str +) -> tuple[str, str, bool, str]: + """Handle document numbers longer than 9 characters. + + ICAO encodes the overflow in the optional-data field: the check position + of the number holds ``<`` and the optional field holds ``rest`` plus the + real check digit. Returns ``(number, digit, ok, remaining_optional)``. + """ + if digit != FILLER: + return number_field.rstrip(FILLER), digit, verify(number_field, digit), optional + body = optional.rstrip(FILLER) + if len(body) < 2: + # Filler check digit with nothing to extend: nothing to verify. + return number_field.rstrip(FILLER), digit, False, optional + rest, real_digit = body[:-1], body[-1] + full = number_field.rstrip(FILLER) + rest + return full, real_digit, verify(full, real_digit), "" + + +def parse(text_or_lines: str | Iterable[str], *, today: _dt.date | None = None) -> Mrz: + """Parse an MRZ. Raises :class:`MrzError` only on structural problems. + + Bad check digits are recorded, never fatal - a real passport with a + scanner-mangled digit must still render. + """ + lines = _lines_of(text_or_lines) + if not lines: + raise MrzError("no MRZ lines given") + kind = detect_kind(lines) + for line in lines: + if not _VALID_CHARS.match(line): + raise MrzError("MRZ contains characters outside [0-9A-Z<]") + + if kind == "TD3": + return _parse_td3(lines, today) + if kind == "TD2": + return _parse_td2(lines, today) + return _parse_td1(lines, today) + + +def _finish(mrz: Mrz, today: _dt.date | None) -> Mrz: + mrz.dob = parse_date(mrz.date_of_birth.value, past=True, today=today) + mrz.expiry = parse_date(mrz.date_of_expiry.value, past=False, today=today) + return mrz + + +def _parse_td3(lines: list[str], today: _dt.date | None) -> Mrz: + l1, l2 = lines + surname, given = split_names(l1[5:44]) + number, ndigit, number_ok, optional = _extended_document_number( + l2[0:9], l2[9], l2[28:42] + ) + mrz = Mrz( + kind="TD3", + lines=lines, + document_code=l1[0:2].rstrip(FILLER), + issuing_state=l1[2:5].rstrip(FILLER), + surname=surname, + given_names=given, + document_number=Checked(number, ndigit, number_ok), + nationality=l2[10:13].rstrip(FILLER), + date_of_birth=Checked(l2[13:19], l2[19], verify(l2[13:19], l2[19])), + sex=l2[20], + date_of_expiry=Checked(l2[21:27], l2[27], verify(l2[21:27], l2[27])), + optional_data=Checked( + l2[28:42].rstrip(FILLER), l2[42], verify(l2[28:42], l2[42]) + ), + composite=Checked( + "", + l2[43], + verify(l2[0:10] + l2[13:20] + l2[21:43], l2[43]), + ), + ) + return _finish(mrz, today) + + +def _parse_td2(lines: list[str], today: _dt.date | None) -> Mrz: + l1, l2 = lines + surname, given = split_names(l1[5:36]) + mrz = Mrz( + kind="TD2", + lines=lines, + document_code=l1[0:2].rstrip(FILLER), + issuing_state=l1[2:5].rstrip(FILLER), + surname=surname, + given_names=given, + document_number=Checked(l2[0:9].rstrip(FILLER), l2[9], verify(l2[0:9], l2[9])), + nationality=l2[10:13].rstrip(FILLER), + date_of_birth=Checked(l2[13:19], l2[19], verify(l2[13:19], l2[19])), + sex=l2[20], + date_of_expiry=Checked(l2[21:27], l2[27], verify(l2[21:27], l2[27])), + optional_data=Checked(l2[28:35].rstrip(FILLER)), + composite=Checked("", l2[35], verify(l2[0:10] + l2[13:20] + l2[21:35], l2[35])), + ) + return _finish(mrz, today) + + +def _parse_td1(lines: list[str], today: _dt.date | None) -> Mrz: + l1, l2, l3 = lines + surname, given = split_names(l3) + number, ndigit, number_ok, optional = _extended_document_number( + l1[5:14], l1[14], l1[15:30] + ) + mrz = Mrz( + kind="TD1", + lines=lines, + document_code=l1[0:2].rstrip(FILLER), + issuing_state=l1[2:5].rstrip(FILLER), + surname=surname, + given_names=given, + document_number=Checked(number, ndigit, number_ok), + nationality=l2[15:18].rstrip(FILLER), + date_of_birth=Checked(l2[0:6], l2[6], verify(l2[0:6], l2[6])), + sex=l2[7], + date_of_expiry=Checked(l2[8:14], l2[14], verify(l2[8:14], l2[14])), + optional_data=Checked(optional.rstrip(FILLER) or l1[15:30].rstrip(FILLER)), + optional_data2=l2[18:29].rstrip(FILLER), + composite=Checked( + "", + l2[29], + verify(l1[5:30] + l2[0:7] + l2[8:15] + l2[18:29], l2[29]), + ), + ) + return _finish(mrz, today) + + +def build_td3_line2( + document_number: str, + dob: str, + expiry: str, + *, + nationality: str = "", + sex: str = FILLER, + optional: str = "", +) -> str: + """Rebuild a TD3 line 2 from BAC inputs, for the ``hf emrtd -m`` path.""" + num = (document_number.upper().rstrip(FILLER) + FILLER * 9)[:9] + nat = (nationality.upper() + FILLER * 3)[:3] + opt = (optional.upper() + FILLER * 14)[:14] + head = num + check_digit(num) + nat + mid = dob + check_digit(dob) + (sex or FILLER)[0] + tail = expiry + check_digit(expiry) + opt + check_digit(opt) + line = head + mid + tail + composite = check_digit(line[0:10] + line[13:20] + line[21:43]) + return line + composite diff --git a/tools/ePassport/epassport/emrtd/sod.py b/tools/ePassport/epassport/emrtd/sod.py new file mode 100644 index 000000000..9cbe4de31 --- /dev/null +++ b/tools/ePassport/epassport/emrtd/sod.py @@ -0,0 +1,172 @@ +"""EF_SOD inspection: signer summary plus the data-group hash table. + +Entirely optional. When ``asn1crypto`` is not installed the module returns a +:class:`SodInfo` that tells the user what to install, rather than nothing. +""" + +from __future__ import annotations + +import hashlib +import logging + +from . import tlv +from .model import SodHash, SodInfo + +log = logging.getLogger(__name__) + +#: OID -> hashlib name, for the digest algorithm named inside the LDS object. +_HASH_OIDS = { + "1.3.14.3.2.26": "sha1", + "2.16.840.1.101.3.4.2.1": "sha256", + "2.16.840.1.101.3.4.2.2": "sha384", + "2.16.840.1.101.3.4.2.3": "sha512", + "2.16.840.1.101.3.4.2.4": "sha224", +} + +_DG_FILE = {n: f"EF_DG{n}" for n in range(1, 17)} + + +def parse_sod(data: bytes, raw_files: dict[str, bytes] | None = None) -> SodInfo: + """Decode EF_SOD and cross-check the DG hashes against the dumped files.""" + if not data: + return SodInfo(available=False, message="EF_SOD was not dumped.") + + try: + from asn1crypto import cms + except ImportError: + return SodInfo( + available=False, + message="Install 'asn1crypto' (and 'cryptography') to inspect EF_SOD.", + ) + + # EF_SOD wraps the CMS ContentInfo in an application tag 0x77. + nodes = tlv.parse(data) + payload = nodes[0].value if nodes and nodes[0].tag == 0x77 else data + + try: + content = cms.ContentInfo.load(payload) + signed: "cms.SignedData" = content["content"] + except Exception as exc: + return SodInfo( + available=False, message=f"EF_SOD is not decodable CMS SignedData: {exc}" + ) + + info = SodInfo(available=True) + try: + _fill_signer(signed, info) + except Exception as exc: # never let a weird cert kill the whole tab + log.info("could not summarise SOD signer: %s", exc) + info.message = f"signer details unavailable ({exc.__class__.__name__})" + + try: + _fill_hashes(signed, info, raw_files or {}) + except Exception as exc: + log.info("could not read the SOD hash table: %s", exc) + info.message = ( + info.message + "; " if info.message else "" + ) + "DG hash table unreadable" + + return info + + +def _fill_signer(signed, info: SodInfo) -> None: + algos = signed["digest_algorithms"] + if len(algos): + info.hash_algorithm = _algo_name(algos[0]["algorithm"].dotted) + + signers = signed["signer_infos"] + if len(signers): + signer = signers[0] + info.signature_algorithm = signer["signature_algorithm"]["algorithm"].native + + certs = signed["certificates"] + if certs is None or not len(certs): + info.signer_subject = "(no document signer certificate in EF_SOD)" + return + cert = certs[0].chosen + info.signer_subject = cert.subject.human_friendly + info.signer_issuer = cert.issuer.human_friendly + info.signer_serial = format(cert.serial_number, "X") + validity = cert["tbs_certificate"]["validity"] + info.valid_from = str(validity["not_before"].native) + info.valid_to = str(validity["not_after"].native) + + +def _fill_hashes(signed, info: SodInfo, raw_files: dict[str, bytes]) -> None: + from asn1crypto.core import ( + Any, + Integer, + ObjectIdentifier, + OctetString, + PrintableString, + Sequence, + SequenceOf, + ) + + encap = signed["encap_content_info"] + lds_der = encap["content"].native + if not lds_der: + return + + class DataGroupHash(Sequence): + _fields = [("dataGroupNumber", Integer), ("dataGroupHashValue", OctetString)] + + class DataGroupHashValues(SequenceOf): + # ICAO 9303 part 10 defines this as a SEQUENCE OF, not a SET OF. Get + # that wrong and every real EF_SOD fails with "tag should have been + # 17, but 16 was found". + _child_spec = DataGroupHash + + class AlgorithmIdentifier(Sequence): + _fields = [ + ("algorithm", ObjectIdentifier), + ("parameters", Any, {"optional": True}), + ] + + class LDSVersionInfo(Sequence): + _fields = [ + ("ldsVersion", PrintableString), + ("unicodeVersion", PrintableString), + ] + + class LDSSecurityObject(Sequence): + _fields = [ + ("version", Integer), + ("hashAlgorithm", AlgorithmIdentifier), + ("dataGroupHashValues", DataGroupHashValues), + # Present when version is v1; absent from v0 documents. + ("ldsVersionInfo", LDSVersionInfo, {"optional": True}), + ] + + lds = LDSSecurityObject.load(lds_der) + info.ldsversion = str(lds["version"].native) + oid = lds["hashAlgorithm"]["algorithm"].dotted + info.hash_algorithm = _algo_name(oid) + hashlib_name = _HASH_OIDS.get(oid, "") + + rows: list[SodHash] = [] + for entry in lds["dataGroupHashValues"]: + number = int(entry["dataGroupNumber"].native) + expected = bytes(entry["dataGroupHashValue"].native) + row = SodHash(dg=number, expected=expected.hex().upper()) + blob = raw_files.get(_DG_FILE.get(number, ""), b"") + if blob and hashlib_name: + actual = hashlib.new(hashlib_name, blob).digest() + row.actual = actual.hex().upper() + row.status = "match" if actual == expected else "MISMATCH" + elif not blob: + row.status = "not checked" + else: + row.status = "not checked" + rows.append(row) + info.hashes = sorted(rows, key=lambda r: r.dg) + + +def _algo_name(oid: str) -> str: + return { + "1.3.14.3.2.26": "SHA-1", + "2.16.840.1.101.3.4.2.1": "SHA-256", + "2.16.840.1.101.3.4.2.2": "SHA-384", + "2.16.840.1.101.3.4.2.3": "SHA-512", + "2.16.840.1.101.3.4.2.4": "SHA-224", + }.get(oid, oid) diff --git a/tools/ePassport/epassport/emrtd/tlv.py b/tools/ePassport/epassport/emrtd/tlv.py new file mode 100644 index 000000000..957583e8b --- /dev/null +++ b/tools/ePassport/epassport/emrtd/tlv.py @@ -0,0 +1,194 @@ +"""Minimal BER-TLV reader for eMRTD data groups. + +Deliberately dependency-free: eMRTD LDS files are plain BER-TLV and the +structures we care about are shallow. Anything malformed degrades to a +partial parse rather than an exception, because real dumps are sometimes +truncated when a card is pulled out of the field. +""" + +from __future__ import annotations + +from dataclasses import dataclass, field +from typing import Iterator, Sequence + + +class TlvError(ValueError): + """Raised when a buffer cannot be parsed as BER-TLV at all.""" + + +@dataclass +class Tlv: + """One BER-TLV node. + + ``tag`` keeps the full encoded tag as an int (``0x5F1F`` stays 0x5F1F). + Constructed nodes carry ``children``; primitive nodes carry ``value``. + """ + + tag: int + value: bytes + constructed: bool + children: list["Tlv"] = field(default_factory=list) + offset: int = 0 + + @property + def tag_hex(self) -> str: + n = self.tag + width = 2 + while n >= 1 << (width * 4): + width += 2 + return f"{n:0{width}X}" + + def find(self, tag: int) -> "Tlv | None": + """Depth-first search for the first node with ``tag``.""" + for node in self.walk(): + if node.tag == tag: + return node + return None + + def find_all(self, tag: int) -> list["Tlv"]: + return [node for node in self.walk() if node.tag == tag] + + def walk(self) -> Iterator["Tlv"]: + yield self + for child in self.children: + yield from child.walk() + + def dump(self, indent: int = 0) -> str: + pad = " " * indent + if self.constructed: + head = f"{pad}{self.tag_hex} [{len(self.value)}] {{" + body = "\n".join(c.dump(indent + 1) for c in self.children) + return f"{head}\n{body}\n{pad}}}" if body else f"{head}}}" + preview = self.value[:24].hex().upper() + if len(self.value) > 24: + preview += "..." + return f"{pad}{self.tag_hex} [{len(self.value)}] {preview}" + + +def _read_tag(buf: bytes, pos: int) -> tuple[int, bool, int]: + """Return ``(tag, constructed, new_pos)``.""" + if pos >= len(buf): + raise TlvError("truncated tag") + first = buf[pos] + tag = first + pos += 1 + constructed = bool(first & 0x20) + if first & 0x1F == 0x1F: # multi-byte tag + while True: + if pos >= len(buf): + raise TlvError("truncated multi-byte tag") + b = buf[pos] + tag = (tag << 8) | b + pos += 1 + if not b & 0x80: + break + if tag > 0xFFFFFFFF: + raise TlvError("tag too long") + return tag, constructed, pos + + +def _read_length(buf: bytes, pos: int) -> tuple[int, int]: + """Return ``(length, new_pos)``. Indefinite length is rejected.""" + if pos >= len(buf): + raise TlvError("truncated length") + first = buf[pos] + pos += 1 + if first < 0x80: + return first, pos + n = first & 0x7F + if n == 0: + raise TlvError("indefinite length not supported") + if n > 4: + raise TlvError(f"length field of {n} bytes is unreasonable") + if pos + n > len(buf): + raise TlvError("truncated long-form length") + length = int.from_bytes(buf[pos : pos + n], "big") + return length, pos + n + + +def parse(buf: bytes | bytearray, *, strict: bool = False) -> list[Tlv]: + """Parse a whole buffer into a list of top-level TLV nodes. + + With ``strict=False`` (the default) a trailing garbage/truncation stops + the parse and returns what was decoded so far. + """ + data = bytes(buf) + out: list[Tlv] = [] + pos = 0 + while pos < len(data): + # Skip 0x00 / 0xFF padding between objects. + if data[pos] in (0x00, 0xFF): + pos += 1 + continue + start = pos + try: + tag, constructed, pos = _read_tag(data, pos) + length, pos = _read_length(data, pos) + except TlvError: + if strict: + raise + break + end = pos + length + if end > len(data): + if strict: + raise TlvError( + f"tag {tag:X} claims {length} bytes, buffer has {len(data) - pos}" + ) + end = len(data) + value = data[pos:end] + node = Tlv(tag=tag, value=value, constructed=constructed, offset=start) + if constructed: + node.children = parse(value, strict=strict) + out.append(node) + pos = end + return out + + +def parse_one(buf: bytes | bytearray, *, strict: bool = False) -> Tlv: + """Parse and return the single expected top-level node.""" + nodes = parse(buf, strict=strict) + if not nodes: + raise TlvError("empty TLV buffer") + return nodes[0] + + +def find(nodes: Sequence[Tlv], tag: int) -> Tlv | None: + for node in nodes: + hit = node.find(tag) + if hit is not None: + return hit + return None + + +def find_value(nodes: Sequence[Tlv], tag: int) -> bytes | None: + hit = find(nodes, tag) + return None if hit is None else hit.value + + +def text(value: bytes | None) -> str: + """Decode an LDS text field. Falls back to latin-1, never raises.""" + if not value: + return "" + try: + return value.decode("utf-8").rstrip("\x00").strip() + except UnicodeDecodeError: + return value.decode("latin-1").rstrip("\x00").strip() + + +def encode_tag(tag: int) -> bytes: + length = 1 + while tag >= 1 << (length * 8): + length += 1 + return tag.to_bytes(length, "big") + + +def encode_length(n: int) -> bytes: + if n < 0x80: + return bytes([n]) + raw = n.to_bytes((n.bit_length() + 7) // 8, "big") + return bytes([0x80 | len(raw)]) + raw + + +def encode(tag: int, value: bytes) -> bytes: + """Build a TLV. Used by the sample-dump generator and the tests.""" + return encode_tag(tag) + encode_length(len(value)) + value diff --git a/tools/ePassport/epassport/ocr/__init__.py b/tools/ePassport/epassport/ocr/__init__.py new file mode 100644 index 000000000..e69de29bb diff --git a/tools/ePassport/epassport/ocr/camera.py b/tools/ePassport/epassport/ocr/camera.py new file mode 100644 index 000000000..23b119ec1 --- /dev/null +++ b/tools/ePassport/epassport/ocr/camera.py @@ -0,0 +1,282 @@ +"""Camera capture on a worker thread, frames handed to Kivy as textures. + +``kivy.uix.camera.Camera`` is unreliable on Linux, so this drives +``cv2.VideoCapture`` directly and blits the frames itself. +""" + +from __future__ import annotations + +import logging +import threading +import time +from dataclasses import dataclass +from typing import Callable + +log = logging.getLogger(__name__) + +#: How many /dev/videoN nodes to probe when the configured index fails. +PROBE_LIMIT = 6 + + +def opencv_available() -> bool: + try: + import cv2 # noqa: F401 + except ImportError: + return False + return True + + +@dataclass +class Frame: + """One captured frame: raw BGR array plus its dimensions.""" + + array: object # numpy.ndarray, kept untyped so numpy stays optional + width: int + height: int + + +class CameraThread: + """Grabs frames in the background and calls ``on_frame`` with each one. + + ``on_frame`` runs on the capture thread - never touch Kivy widgets from + it; schedule with ``Clock`` instead. + """ + + def __init__( + self, + index: int = 0, + *, + width: int = 1280, + height: int = 720, + fps: float = 30.0, + on_frame: Callable[[Frame], None] | None = None, + on_error: Callable[[str], None] | None = None, + ) -> None: + self.index = index + self.width = width + self.height = height + self.interval = 1.0 / max(fps, 1.0) + self.on_frame = on_frame + self.on_error = on_error + self._thread: threading.Thread | None = None + self._stop = threading.Event() + self._capture = None + self.last_error = "" + + # -- lifecycle --------------------------------------------------------- + def start(self) -> bool: + if self._thread is not None: + return True + if not opencv_available(): + self._fail( + "OpenCV is not installed - run: pip install opencv-python-headless" + ) + return False + self._stop.clear() + self._thread = threading.Thread( + target=self._run, name="ePassport-camera", daemon=True + ) + self._thread.start() + return True + + def stop(self) -> None: + """Release the camera. Safe to call twice, and from the UI thread.""" + self._stop.set() + thread, self._thread = self._thread, None + if thread is not None and thread.is_alive(): + thread.join(timeout=2.0) + + @property + def running(self) -> bool: + return self._thread is not None and self._thread.is_alive() + + # -- capture loop ------------------------------------------------------ + def _open(self, cv2, index: int): + """Open one index, or return None. + + V4L2 exposes metadata-only nodes that open successfully but never + deliver a frame, so a successful first read is the real test. + """ + capture = cv2.VideoCapture(index) + if not capture.isOpened(): + capture.release() + return None + capture.set(cv2.CAP_PROP_FRAME_WIDTH, self.width) + capture.set(cv2.CAP_PROP_FRAME_HEIGHT, self.height) + ok, frame = capture.read() + if not ok or frame is None: + capture.release() + return None + return capture + + def _run(self) -> None: + import cv2 + + # Many Linux systems expose several /dev/videoN for one physical + # camera, only one of which actually delivers frames - so try the + # neighbours rather than giving up on the configured index. + tried: list[int] = [] + capture = None + for index in [self.index] + [i for i in range(PROBE_LIMIT) if i != self.index]: + tried.append(index) + capture = self._open(cv2, index) + if capture is not None: + if index != self.index: + log.info( + "camera %d delivered no frames, using %d", self.index, index + ) + self.index = index + break + if capture is None: + self._fail( + "No working camera found (tried " + + ", ".join(f"/dev/video{i}" for i in tried) + + "). Check permissions, or set the index in Settings." + ) + return + self._capture = capture + misses = 0 + try: + while not self._stop.is_set(): + started = time.monotonic() + ok, frame = capture.read() + if not ok or frame is None: + misses += 1 + if misses > 30: + self._fail("The camera stopped delivering frames.") + break + time.sleep(0.05) + continue + misses = 0 + if self.on_frame is not None: + try: + self.on_frame(Frame(frame, frame.shape[1], frame.shape[0])) + except Exception: # a bad consumer must not kill capture + log.exception("camera frame consumer raised") + elapsed = time.monotonic() - started + if elapsed < self.interval: + time.sleep(self.interval - elapsed) + finally: + capture.release() + self._capture = None + + def _fail(self, message: str) -> None: + self.last_error = message + log.warning("camera: %s", message) + if self.on_error is not None: + self.on_error(message) + + +def frame_to_texture(frame: Frame): + """Convert a BGR frame to a Kivy texture (RGB, right way up).""" + import cv2 + from kivy.graphics.texture import Texture + + rgb = cv2.cvtColor(frame.array, cv2.COLOR_BGR2RGB) + flipped = cv2.flip(rgb, 0) # Kivy textures start at the bottom-left + texture = Texture.create(size=(frame.width, frame.height), colorfmt="rgb") + texture.blit_buffer(flipped.tobytes(), colorfmt="rgb", bufferfmt="ubyte") + return texture + + +@dataclass +class CameraDevice: + """One selectable capture device.""" + + index: int + name: str = "" + path: str = "" + #: V4L2 sub-index within the physical device. 0 is the capture node; + #: higher numbers are usually metadata-only and deliver no frames. + node: int = 0 + works: bool | None = None # None = not probed yet + + @property + def label(self) -> str: + name = self.name or "camera" + suffix = {True: "", False: " (no frames)", None: ""}[self.works] + return f"{self.index}: {name}{suffix}" + + +#: Where Linux advertises V4L2 devices, and their human-readable names. +V4L2_SYSFS = "/sys/class/video4linux" + + +def _sysfs_devices(root=None) -> list[CameraDevice]: + """Enumerate V4L2 devices by name, without opening them.""" + from pathlib import Path as _Path + + root = _Path(root or V4L2_SYSFS) + if not root.is_dir(): + return [] + devices: list[CameraDevice] = [] + for entry in sorted(root.glob("video*")): + try: + index = int(entry.name.removeprefix("video")) + except ValueError: + continue + name = _read_text(entry / "name") + node = _read_int(entry / "index", default=0) + devices.append( + CameraDevice(index=index, name=name, path=f"/dev/{entry.name}", node=node) + ) + return devices + + +def _read_text(path) -> str: + try: + return path.read_text(encoding="utf-8", errors="replace").strip() + except OSError: + return "" + + +def _read_int(path, *, default: int) -> int: + text = _read_text(path) + try: + return int(text) + except ValueError: + return default + + +def list_cameras( + *, probe: bool = False, limit: int = PROBE_LIMIT, root=None +) -> list[CameraDevice]: + """Every capture device we could offer the user. + + Enumeration is by name from sysfs where available, because opening a + device to look at it is disruptive if something else is using it. Pass + ``probe=True`` to additionally check which ones deliver frames - that is + slow, so do it on a worker thread. + """ + devices = _sysfs_devices(root) + if not devices: + devices = [CameraDevice(index=i, name=f"camera {i}") for i in range(limit)] + if probe and opencv_available(): + for device in devices: + device.works = probe_camera(device.index) + # A device that delivers frames sorts above one that does not. + devices.sort(key=lambda d: (d.works is not True, d.node, d.index)) + else: + devices.sort(key=lambda d: (d.node, d.index)) + return devices + + +def probe_camera(index: int) -> bool: + """True when this index actually delivers a frame.""" + if not opencv_available(): + return False + import cv2 + + capture = cv2.VideoCapture(index) + try: + if not capture.isOpened(): + return False + ok, frame = capture.read() + return bool(ok and frame is not None) + finally: + capture.release() + + +def list_camera_indices(limit: int = PROBE_LIMIT) -> list[int]: + """Indices that deliver frames. Slow; call off the UI thread.""" + return [d.index for d in list_cameras(probe=True, limit=limit) if d.works] diff --git a/tools/ePassport/epassport/ocr/mrz_ocr.py b/tools/ePassport/epassport/ocr/mrz_ocr.py new file mode 100644 index 000000000..89124b1cd --- /dev/null +++ b/tools/ePassport/epassport/ocr/mrz_ocr.py @@ -0,0 +1,598 @@ +"""MRZ OCR: preprocess a cropped strip, run tesseract, accept only clean reads. + +A candidate is accepted only when its check digits validate *and* two +consecutive frames agree. That is what stops a single hallucinated digit from +being fed to BAC. +""" + +from __future__ import annotations + +import logging +import re +import threading +from functools import lru_cache +from dataclasses import dataclass, field + +from ..emrtd import mrz as mrzlib + +log = logging.getLogger(__name__) + +#: The only characters tesseract is allowed to emit. +WHITELIST = "0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZ<" +TESSERACT_CONFIG = f"--psm 6 -c tessedit_char_whitelist={WHITELIST}" + +#: Valid MRZ line widths, longest first so TD3 wins ties. +LINE_WIDTHS = (44, 36, 30) + + +def use_private_tempdir() -> None: + """Point tesseract's scratch files at the app's own 0700 directory. + + The subprocess backend hands images to the tesseract binary through a temp + file. By default that lands in /tmp, which would put a picture of + somebody's MRZ outside the app data dir - so redirect it before any OCR + happens. The in-process backend writes nothing at all. + """ + import tempfile + + from ..config import data_dir + + scratch = data_dir() / "ocr-tmp" + scratch.mkdir(parents=True, exist_ok=True) + try: + scratch.chmod(0o700) + except OSError: + pass + tempfile.tempdir = str(scratch) + + +def clear_private_tempdir() -> None: + """Delete any OCR scratch files left behind.""" + from ..config import data_dir + + scratch = data_dir() / "ocr-tmp" + if not scratch.is_dir(): + return + for leftover in scratch.iterdir(): + try: + leftover.unlink() + except OSError: + pass + + +# ------------------------------------------------------------------ engine +# An in-process binding (tesserocr) would avoid re-launching tesseract for +# every frame and is roughly three times faster per call. It was tried and +# rejected: the PyPI wheel bundles its own leptonica, and pairing that with a +# system tessdata directory hung indefinitely mid-recognition. A backend that +# can wedge the OCR thread is worse than a slower one, so this stays on the +# subprocess path. The cost is mitigated instead by not calling it as often - +# see :func:`looks_like_text` and the frame-change check in the scan loop. + + +def tesseract_available() -> tuple[bool, str]: + """``(available, reason)`` - the reason is shown in the disabled tooltip.""" + try: + import pytesseract + except ImportError: + return False, "pytesseract is not installed - run: pip install pytesseract" + try: + pytesseract.get_tesseract_version() + except Exception: + return ( + False, + "the tesseract binary is not installed - run: sudo apt install tesseract-ocr", + ) + return True, "" + + +@lru_cache(maxsize=1) +def best_language() -> str: + """Prefer OCR-B / mrz traineddata when installed, else plain eng. + + Cached: the lookup shells out to tesseract, and paying that on every frame + cost more than several of the image-processing steps combined. + """ + try: + import pytesseract + + langs = set(pytesseract.get_languages(config="")) + except Exception: + return "eng" + for candidate in ("mrz", "ocrb", "OCRB"): + if candidate in langs: + return candidate + return "eng" + + +# ------------------------------------------------------------- preprocessing +#: Tesseract wants a decent x-height. An MRZ strip below this many pixels +#: tall gets upscaled before it is handed over. +MIN_STRIP_HEIGHT = 120 + +#: Above this the strip is downscaled. Past roughly this height extra pixels +#: buy no accuracy on the test set and only cost time. +MAX_STRIP_HEIGHT = 190 + + +def normalize_scale(image): + """Scale a cropped strip into the band tesseract reads best.""" + import cv2 + + h = image.shape[0] + if h == 0: + return image + if h < MIN_STRIP_HEIGHT: + factor, interp = MIN_STRIP_HEIGHT / h, cv2.INTER_CUBIC + elif h > MAX_STRIP_HEIGHT: + factor, interp = MAX_STRIP_HEIGHT / h, cv2.INTER_AREA + else: + return image + return cv2.resize(image, None, fx=factor, fy=factor, interpolation=interp) + + +def to_gray(image): + import cv2 + + return cv2.cvtColor(image, cv2.COLOR_BGR2GRAY) if image.ndim == 3 else image + + +def deskew(image): + """Rotate a strip upright using the orientation of all its text pixels. + + ``minAreaRect`` over every dark pixel is far more stable than over the + single largest contour, which on a thresholded MRZ is usually the page + border rather than any text. + """ + import cv2 + + gray = to_gray(image) + _, mask = cv2.threshold(gray, 0, 255, cv2.THRESH_BINARY_INV + cv2.THRESH_OTSU) + points = cv2.findNonZero(mask) + if points is None or len(points) < 50: + return image + angle = cv2.minAreaRect(points)[-1] + if angle < -45: + angle += 90 + elif angle > 45: + angle -= 90 + if abs(angle) < 0.4 or abs(angle) > 15: + return image + h, w = image.shape[:2] + matrix = cv2.getRotationMatrix2D((w / 2, h / 2), angle, 1.0) + return cv2.warpAffine( + image, matrix, (w, h), flags=cv2.INTER_CUBIC, borderMode=cv2.BORDER_REPLICATE + ) + + +def variant_plain(image): + """Grayscale only. + + Usually the best input: thresholding an already-clean print tends to eat + the long runs of '<' fillers, which is what makes a line the wrong length. + """ + import cv2 + + return cv2.bilateralFilter(to_gray(image), 5, 40, 40) + + +def variant_clahe_otsu(image): + """Contrast-equalise, then a global Otsu threshold. Good for dim frames.""" + import cv2 + + gray = to_gray(image) + equalized = cv2.createCLAHE(clipLimit=2.0, tileGridSize=(8, 8)).apply(gray) + blurred = cv2.GaussianBlur(equalized, (3, 3), 0) + _, binary = cv2.threshold(blurred, 0, 255, cv2.THRESH_BINARY + cv2.THRESH_OTSU) + return binary + + +def variant_adaptive(image): + """Adaptive threshold, with a block wide enough not to eat filler runs.""" + import cv2 + + gray = to_gray(image) + equalized = cv2.createCLAHE(clipLimit=2.0, tileGridSize=(8, 8)).apply(gray) + return cv2.adaptiveThreshold( + equalized, 255, cv2.ADAPTIVE_THRESH_MEAN_C, cv2.THRESH_BINARY, 61, 15 + ) + + +#: Tried in order; the first variant yielding a check-digit-valid MRZ wins, so +#: the common case costs exactly one tesseract call. +VARIANTS = ( + ("plain", variant_plain), + ("clahe-otsu", variant_clahe_otsu), + ("adaptive", variant_adaptive), +) + +#: The variant that last produced a valid read is tried first next time. +#: Lighting does not change between frames, so the winner rarely does either - +#: and on a dim page this turns three tesseract calls back into one. +_last_winner: str = "" + + +def ordered_variants() -> tuple[tuple[str, object], ...]: + if not _last_winner: + return VARIANTS + return tuple(sorted(VARIANTS, key=lambda item: item[0] != _last_winner)) + + +def preprocess(image, *, deskew_first: bool = True): + """Single-variant preprocessing: deskew, rescale, CLAHE + Otsu.""" + prepared = deskew(image) if deskew_first else image + return variant_clahe_otsu(normalize_scale(prepared)) + + +#: The crop is taken slightly wider than the drawn guide, so a page held at a +#: slight angle does not lose its first or last character to the box edge. +GUIDE_MARGIN = 0.03 + + +def crop_to_guide( + image, guide: tuple[float, float, float, float], *, margin: float = GUIDE_MARGIN +): + """Crop a BGR frame to the guide rectangle, as fractions (x, y, w, h). + + ``y`` is measured from the TOP of the frame, matching how the guide reads + in the UI. + """ + h, w = image.shape[:2] + fx, fy, fw, fh = guide + pad_x, pad_y = fw * margin, fh * margin + fx, fw = fx - pad_x, fw + 2 * pad_x + fy, fh = fy - pad_y, fh + 2 * pad_y + x0 = max(0, int(fx * w)) + y0 = max(0, int(fy * h)) + x1 = min(w, int((fx + fw) * w)) + y1 = min(h, int((fy + fh) * h)) + if x1 - x0 < 20 or y1 - y0 < 10: + return image + return image[y0:y1, x0:x1] + + +# -------------------------------------------------------------- recognition +def ocr_text(image, *, lang: str | None = None) -> str: + """Run tesseract over a preprocessed image.""" + import pytesseract + + return pytesseract.image_to_string( + image, lang=lang or best_language(), config=TESSERACT_CONFIG + ) + + +#: The filler character; long runs of it are what OCR miscounts. +FILLER_CHAR = "<" + +#: How many characters a line may be off its format width and still be +#: repaired - but only ever by adding or removing filler. +WIDTH_SLACK = 12 + + +def looks_like_line2(line: str) -> bool: + """True when a line has line 2's date fields where they belong. + + Line 2 ends in the composite check digit, so unlike a name line it must + never be padded out with fillers - the padding would silently displace a + check digit. The two six-digit date runs are a cheap, reliable tell. + """ + return len(line) >= 28 and line[13:19].isdigit() and line[21:27].isdigit() + + +def _fit_to_width(line: str, width: int) -> str | None: + """Pad or trim a line to ``width`` using only its trailing fillers. + + Trailing fillers on a name line carry no information, so restoring them is + safe. Anything else - in particular a line 2, whose last character is a + check digit - is rejected rather than mangled into shape. + """ + if len(line) == width: + return line + if abs(len(line) - width) > WIDTH_SLACK: + return None + if len(line) < width: + if not line.endswith(FILLER_CHAR) or looks_like_line2(line): + return None + return line + FILLER_CHAR * (width - len(line)) + excess = len(line) - width + if line[-excess:] != FILLER_CHAR * excess: + return None + return line[:-excess] + + +def candidate_lines(raw: str) -> list[str]: + """Every line that is an MRZ width, flattened. Kept for callers/tests.""" + seen: list[str] = [] + for lines in candidates_by_width(raw).values(): + for line in lines: + if line not in seen: + seen.append(line) + return seen + + +def candidates_by_width(raw: str) -> dict[int, list[str]]: + """Fit each OCR'd line to *every* width it could plausibly be. + + A line of 38 characters could be a 44-wide line that lost six fillers or a + 36-wide one that gained two; guessing costs a real read, so both are + offered and the check digits decide. + """ + buckets: dict[int, list[str]] = {width: [] for width in LINE_WIDTHS} + for line in raw.splitlines(): + cleaned = mrzlib.clean_line(line) + if not cleaned: + continue + for width in LINE_WIDTHS: + fitted = _fit_to_width(cleaned, width) + if fitted is not None and fitted not in buckets[width]: + buckets[width].append(fitted) + return buckets + + +def group_candidates(lines: list[str]) -> list[list[str]]: + """Group same-width lines into 2- or 3-line MRZ candidates.""" + groups: list[list[str]] = [] + for width, count in ((44, 2), (36, 2), (30, 3)): + run = [line for line in lines if len(line) == width] + for start in range(0, max(0, len(run) - count + 1)): + groups.append(run[start : start + count]) + return [g for g in groups if len(g) in (2, 3)] + + +#: A synthetic line 1 used to validate a lone line 2. TD3 and TD2 put every +#: one of their check digits - including the composite - inside line 2, so a +#: line 2 on its own is fully self-validating, and it carries everything BAC +#: needs. TD1 spreads its composite across two lines and is excluded. +_LINE2_ONLY_HEAD = { + 44: "P "OcrResult | None": + """Validate a lone MRZ line 2. Returns None unless every check passes.""" + head = _LINE2_ONLY_HEAD.get(len(line)) + if head is None: + return None + for attempt in (mrzlib.coerce_lines([head, line]), [head, line]): + try: + parsed = mrzlib.parse(attempt) + except mrzlib.MrzError: + continue + if parsed.all_checks_ok: + return OcrResult( + mrz=parsed, + lines=[attempt[1]], + line2_only=True, + reason="line 2 only - check digits valid, enough for BAC", + ) + return None + + +def groups_from_raw(raw: str) -> list[list[str]]: + """All plausible line groupings for one OCR pass, widest format first.""" + buckets = candidates_by_width(raw) + groups: list[list[str]] = [] + for width, count in ((44, 2), (36, 2), (30, 3)): + run = buckets.get(width, []) + for start in range(0, max(0, len(run) - count + 1)): + groups.append(run[start : start + count]) + return groups + + +@dataclass +class OcrResult: + """One OCR attempt.""" + + mrz: mrzlib.Mrz | None = None + lines: list[str] = field(default_factory=list) + raw: str = "" + accepted: bool = False + reason: str = "" + #: Which preprocessing variant produced this read, for diagnostics. + variant: str = "" + #: True when only line 2 was recovered. It self-validates and carries + #: everything BAC needs, but the holder's name is not available. + line2_only: bool = False + + @property + def unverifiable_characters(self) -> str: + """Document-number characters the check digits cannot vouch for. + + Valid check digits do NOT mean the document number is right: swaps + like L/1 or S/8 are invisible to the 7-3-1 scheme. The user gets the + value in an editable box precisely so they can eyeball these. + """ + if self.mrz is None: + return "" + number = self.mrz.document_number.value + positions = mrzlib.ambiguous_positions(number) + return "".join(sorted({number[i] for i in positions})) + + @property + def checks_ok(self) -> bool: + return self.mrz is not None and self.mrz.all_checks_ok + + +#: A strip must have at least this fraction of dark pixels to be worth an OCR +#: call. An empty desk or a hand over the lens has almost none. +MIN_INK = 0.010 +MAX_INK = 0.60 + + +def ink_bands(mask, *, floor: float) -> int: + """Count horizontal bands of ink - i.e. how many lines of text there are.""" + rows = mask.mean(axis=1) / 255.0 + bands = 0 + run = 0 + for value in rows: + if value > floor: + run += 1 + else: + if run >= 3: # a stray speckled row is not a line of text + bands += 1 + run = 0 + if run >= 3: + bands += 1 + return bands + + +def looks_like_text(image) -> tuple[bool, str]: + """Cheap gate: does this strip plausibly hold MRZ lines? + + One OCR pass costs a few hundred milliseconds; this costs microseconds. + Rejecting frames of desk, hand or half a passport photo here is what keeps + the scan responsive while the user is still lining the document up. + + Returns ``(worth_trying, reason)`` so the UI can say something useful. + """ + import cv2 + + gray = to_gray(image) + if gray.size == 0: + return False, "no image" + _, mask = cv2.threshold(gray, 0, 255, cv2.THRESH_BINARY_INV + cv2.THRESH_OTSU) + ink = float(mask.mean()) / 255.0 + if ink < MIN_INK: + return False, "hold the MRZ inside the box" + if ink > MAX_INK: + return False, "too dark - move into better light" + # The MRZ is two or three dense, well-separated bands. A photo, a hand or + # the top half of the page gives one big blob or none at all. + bands = ink_bands(mask, floor=max(ink * 1.5, 0.02)) + if bands < 2: + return False, "line up both MRZ lines inside the box" + return True, "" + + +def read_frame( + image, + *, + guide: tuple[float, float, float, float] | None = None, + lang: str | None = None, +) -> OcrResult: + """Full pipeline for one frame. + + Each preprocessing variant is tried in turn and the first that produces a + check-digit-valid MRZ wins; if none does, the most promising partial read + is returned so the UI can show progress instead of silence. + """ + try: + cropped = crop_to_guide(image, guide) if guide else image + # Deskew first: the gate measures horizontal bands of ink, and tilted + # text smears those bands into one. Straightening costs ~2 ms, far + # less than the OCR pass the gate is there to avoid. + straightened = deskew(cropped) + worth_trying, why = looks_like_text(straightened) + if not worth_trying: + return OcrResult(reason=why) + straightened = normalize_scale(straightened) + except Exception as exc: + return OcrResult(reason=f"preprocessing failed: {exc}") + + global _last_winner + language = lang or best_language() + best = OcrResult(reason="nothing recognised") + for attempt, (name, variant) in enumerate(ordered_variants()): + try: + raw = ocr_text(variant(straightened), lang=language) + except Exception as exc: + return OcrResult(reason=f"OCR failed: {exc}") + result = parse_raw(raw) + result.variant = name + if result.checks_ok: + _last_winner = name + return result + if _score(result) > _score(best): + best = result + # Escalate to another variant only while there is something to work + # with. If two passes have found no line of MRZ length at all, the + # frame is not framed right and a third pass will not change that - + # the next frame is only milliseconds away. + if attempt >= 1 and not best.lines and best.mrz is None: + break + return best + + +def _score(result: OcrResult) -> int: + """Rank partial reads so the UI shows the closest attempt, not the last.""" + if result.mrz is not None: + return 100 - len(result.mrz.failed_checks()) + return len(result.lines) + + +def parse_raw(raw: str) -> OcrResult: + """Turn raw tesseract text into a validated MRZ, or explain why not. + + Candidate lines are repaired by field position before validation: a + digits-only field never legitimately holds an 'O'. If no complete MRZ + survives, a self-validating line 2 is accepted on its own - it carries + every value BAC needs. + """ + fallback: OcrResult | None = None + for group in groups_from_raw(raw): + for attempt in (mrzlib.coerce_lines(group), group): + try: + parsed = mrzlib.parse(attempt) + except mrzlib.MrzError: + continue + if parsed.all_checks_ok: + return OcrResult( + mrz=parsed, lines=attempt, raw=raw, reason="check digits valid" + ) + if fallback is None: + fallback = OcrResult( + mrz=parsed, + lines=attempt, + raw=raw, + reason="check digits failed: " + ", ".join(parsed.failed_checks()), + ) + + buckets = candidates_by_width(raw) + for width in (44, 36): + for line in buckets.get(width, []): + lone = try_line2_only(line) + if lone is not None: + lone.raw = raw + return lone + + if fallback is not None: + return fallback + seen = candidate_lines(raw) + if not seen: + return OcrResult(raw=raw, reason="no line of MRZ length found") + return OcrResult( + raw=raw, lines=seen, reason="lines found but none parsed as an MRZ" + ) + + +class Acceptor: + """Accept only when check digits pass and two consecutive frames agree.""" + + def __init__(self, *, required_agreements: int = 2) -> None: + self.required = required_agreements + self._last: tuple[str, ...] | None = None + self._streak = 0 + + def offer(self, result: OcrResult) -> OcrResult: + """Feed one OCR result; the returned result carries ``accepted``.""" + if result.mrz is None or not result.checks_ok: + self._last = None + self._streak = 0 + return result + key = tuple(result.lines) + if key == self._last: + self._streak += 1 + else: + self._last = key + self._streak = 1 + if self._streak >= self.required: + result.accepted = True + result.reason = f"accepted after {self._streak} matching frames" + else: + result.reason = f"check digits valid, waiting for confirmation ({self._streak}/{self.required})" + return result + + def reset(self) -> None: + self._last = None + self._streak = 0 diff --git a/tools/ePassport/epassport/pm3/__init__.py b/tools/ePassport/epassport/pm3/__init__.py new file mode 100644 index 000000000..e69de29bb diff --git a/tools/ePassport/epassport/pm3/client.py b/tools/ePassport/epassport/pm3/client.py new file mode 100644 index 000000000..051501aac --- /dev/null +++ b/tools/ePassport/epassport/pm3/client.py @@ -0,0 +1,496 @@ +"""Drive the pm3 client in one-shot command mode, from a worker thread. + +The client is never invoked through a shell: the whole ``-c`` command string +is one argv element and every MRZ-derived value is validated against +``[0-9A-Z<]`` before it is allowed anywhere near it. +""" + +from __future__ import annotations + +import os +import re +import shutil +import signal +import subprocess +import threading +import time +from dataclasses import dataclass, field +from pathlib import Path +from typing import Callable, Iterable, Sequence + +from . import errors + +#: Matches every ANSI CSI/OSC escape the client emits for colour. +ANSI_RE = re.compile(r"\x1B(?:[@-Z\\-_]|\[[0-?]*[ -/]*[@-~]|\][^\x07]*(?:\x07|\x1B\\))") + +#: The only characters ICAO allows in an MRZ. Everything else is rejected +#: before it reaches the command string. +MRZ_SAFE = re.compile(r"^[0-9A-Z<]+$") + +#: The Card Access Number is printed on the document and is always numeric. +#: The client accepts 1-14 digits and warns when it is not the usual 6. +CAN_SAFE = re.compile(r"^[0-9]{1,14}$") +CAN_USUAL_LENGTH = 6 + +#: How the chip should be unlocked. ``auto`` lets the client try PACE and +#: fall back to BAC, which is what you want unless you are testing. +AUTH_AUTO = "auto" +AUTH_PACE = "pace" +AUTH_BAC = "bac" + + +def validate_can(value: str) -> str: + """Normalise a Card Access Number, or raise :class:`ValidationError`.""" + digits = value.strip() + if not digits: + raise ValidationError("CAN is empty") + if not CAN_SAFE.match(digits): + raise ValidationError("CAN must be 1-14 digits, numbers only") + return digits + + +#: pm3 prints one of these per data group while dumping. +_PROGRESS_RE = re.compile( + r"(?:Read|Dumping|Saved)\s+(?:file\s+)?(EF_[A-Za-z0-9_]+)", re.I +) +_SAVED_RE = re.compile(r"saved to\s+(.+?)\s*$", re.I) + + +def strip_ansi(text: str) -> str: + return ANSI_RE.sub("", text) + + +class ValidationError(ValueError): + """Raised for input that must never reach the pm3 command string.""" + + +def validate_mrz_field(value: str, *, name: str, maxlen: int | None = None) -> str: + up = value.strip().upper() + if not up: + raise ValidationError(f"{name} is empty") + if not MRZ_SAFE.match(up): + raise ValidationError(f"{name} may only contain 0-9, A-Z and '<'") + if maxlen is not None and len(up) > maxlen: + raise ValidationError(f"{name} must be at most {maxlen} characters") + return up + + +def validate_date(value: str, *, name: str) -> str: + digits = value.strip() + if not re.fullmatch(r"\d{6}", digits): + raise ValidationError(f"{name} must be exactly 6 digits, YYMMDD") + month, day = int(digits[2:4]), int(digits[4:6]) + if not 1 <= month <= 12: + raise ValidationError(f"{name}: month {month:02d} is not 01-12") + if not 1 <= day <= 31: + raise ValidationError(f"{name}: day {day:02d} is not a valid day") + return digits + + +@dataclass +class BacInput: + """The key material for the chip. + + Either the MRZ (as the ``-n``/``-d``/``-e`` triple or a full line 2) or a + Card Access Number. The two are mutually exclusive as PACE passwords, and + BAC can only ever use the MRZ. The pm3 client enforces the same rules; + checking here just turns a failed run into a sentence. + """ + + document_number: str = "" + date_of_birth: str = "" + date_of_expiry: str = "" + mrz_line2: str = "" + can: str = "" + mode: str = AUTH_AUTO + + @property + def has_mrz(self) -> bool: + return bool( + self.mrz_line2.strip() + or ( + self.document_number.strip() + and self.date_of_birth.strip() + and self.date_of_expiry.strip() + ) + ) + + @property + def has_can(self) -> bool: + return bool(self.can.strip()) + + @property + def mechanism(self) -> str: + """What this input will attempt, for the status bar.""" + if self.mode == AUTH_BAC: + return "BAC" + if self.has_can: + return "PACE (CAN)" + if self.mode == AUTH_PACE: + return "PACE (MRZ)" + return "PACE/BAC (MRZ)" + + def warnings(self) -> list[str]: + """Non-fatal notes to show before a read.""" + if self.can and len(self.can) != CAN_USUAL_LENGTH: + return [ + f"The CAN is usually {CAN_USUAL_LENGTH} digits; yours is " + f"{len(self.can)}. Trying it anyway." + ] + return [] + + def validated(self) -> "BacInput": + """Return a normalised copy, or raise :class:`ValidationError`.""" + if self.mode not in (AUTH_AUTO, AUTH_PACE, AUTH_BAC): + raise ValidationError(f"unknown authentication mode {self.mode!r}") + if self.has_can and self.has_mrz: + raise ValidationError( + "the CAN and the MRZ are mutually exclusive - supply one or the other" + ) + if self.mode == AUTH_BAC and self.has_can and not self.has_mrz: + raise ValidationError("BAC needs MRZ data; the CAN is a PACE-only password") + if self.mode == AUTH_PACE and not (self.has_can or self.has_mrz): + raise ValidationError("PACE needs a password: supply a CAN, or the MRZ") + if self.has_can: + return BacInput(can=validate_can(self.can), mode=self.mode) + if self.mrz_line2.strip(): + line = validate_mrz_field(self.mrz_line2, name="MRZ line 2") + if len(line) not in (36, 44): + raise ValidationError( + "MRZ line 2 must be 44 characters (TD3) or 36 (TD2)" + ) + return BacInput(mrz_line2=line, mode=self.mode) + # All three or none - a partial triple silently drops pm3 to no-BAC mode. + missing = [ + name + for name, value in ( + ("document number", self.document_number), + ("date of birth", self.date_of_birth), + ("date of expiry", self.date_of_expiry), + ) + if not value.strip() + ] + if missing: + raise ValidationError("missing " + ", ".join(missing)) + return BacInput( + document_number=validate_mrz_field( + self.document_number, name="document number", maxlen=9 + ), + date_of_birth=validate_date(self.date_of_birth, name="date of birth"), + date_of_expiry=validate_date(self.date_of_expiry, name="date of expiry"), + mode=self.mode, + ) + + def args(self) -> list[str]: + """The pm3 argument fragment for this key material.""" + if self.can: + out = ["--can", self.can] + elif self.mrz_line2: + out = ["-m", self.mrz_line2] + else: + out = [ + "-n", + self.document_number, + "-d", + self.date_of_birth, + "-e", + self.date_of_expiry, + ] + if self.mode == AUTH_PACE: + out.append("--pace") + elif self.mode == AUTH_BAC: + out.append("--bac") + return out + + def is_empty(self) -> bool: + return not (self.has_mrz or self.has_can) + + +@dataclass +class Pm3Result: + """Outcome of one pm3 invocation.""" + + command: str + argv: list[str] + returncode: int | None + lines: list[str] = field(default_factory=list) + error: errors.Pm3Error | None = None + duration: float = 0.0 + dump_dir: Path | None = None + + @property + def ok(self) -> bool: + return self.error is None and self.returncode == 0 + + @property + def text(self) -> str: + return "\n".join(self.lines) + + +def find_pm3_binary(configured: str | os.PathLike[str] | None = None) -> Path | None: + """$PM3_BIN -> configured path -> PATH -> ~/pm3/pm3 -> repo-relative ./pm3.""" + candidates: list[Path] = [] + env = os.environ.get("PM3_BIN") + if env: + candidates.append(Path(env).expanduser()) + if configured: + candidates.append(Path(configured).expanduser()) + which = shutil.which("pm3") + if which: + candidates.append(Path(which)) + candidates.append(Path.home() / "pm3" / "pm3") + # Developing inside a proxmark3 tree: walk up looking for its ./pm3 wrapper. + for parent in Path(__file__).resolve().parents: + wrapper = parent / "pm3" + if wrapper.is_file() and (parent / "client").is_dir(): + candidates.append(wrapper) + break + for candidate in candidates: + if candidate.is_file(): + return candidate + return None + + +class Pm3Client: + """Runs ``pm3 -c ""`` and streams its output line by line. + + Call :meth:`run` from a worker thread - it blocks. ``on_line`` is invoked + for every stripped output line as it arrives, ``on_progress`` with + ``(done, total, label)`` whenever a data group is read. + """ + + def __init__( + self, + binary: str | os.PathLike[str] | None = None, + *, + timeout: float = 120.0, + dry_run_log: str | os.PathLike[str] | None = None, + ) -> None: + self.binary = find_pm3_binary(binary) + self.timeout = timeout + self.dry_run_log = Path(dry_run_log) if dry_run_log else None + self._process: subprocess.Popen[str] | None = None + self._lock = threading.Lock() + self._cancelled = threading.Event() + + # -- command construction -------------------------------------------- + @staticmethod + def build_command( + subcommand: str, + bac: BacInput | None, + dump_dir: Path | None, + extra: Sequence[str] = (), + ) -> str: + """Build the single ``-c`` string. Never interpolates raw user input.""" + parts = ["hf", "emrtd", subcommand] + if bac is not None and not bac.is_empty(): + parts += bac.validated().args() + if dump_dir is not None: + parts += ["--dir", str(dump_dir)] + parts += list(extra) + return " ".join(parts) + + def argv_for(self, command: str) -> list[str]: + if self.binary is None: + raise errors.Pm3NotFound() + if not os.access(self.binary, os.X_OK): + raise errors.Pm3NotExecutable(detail=str(self.binary)) + return [str(self.binary), "-c", command] + + # -- execution -------------------------------------------------------- + def run( + self, + command: str, + *, + on_line: Callable[[str], None] | None = None, + on_progress: Callable[[int, int, str], None] | None = None, + dump_dir: Path | None = None, + expected_files: int = 0, + ) -> Pm3Result: + """Run one pm3 command to completion. Blocks; never raises for a + pm3-level failure - the failure lands in ``result.error``.""" + self._cancelled.clear() + started = time.monotonic() + + if self.dry_run_log is not None: + return self._replay(command, on_line, on_progress, dump_dir, started) + + try: + argv = self.argv_for(command) + except errors.Pm3Error as exc: + return Pm3Result(command=command, argv=[], returncode=None, error=exc) + + lines: list[str] = [] + seen_files: set[str] = set() + + def emit(raw: str) -> None: + line = strip_ansi(raw.rstrip("\n")) + lines.append(line) + if on_line is not None: + on_line(line) + match = _PROGRESS_RE.search(line) + if match and on_progress is not None: + name = match.group(1) + if name not in seen_files: + seen_files.add(name) + on_progress(len(seen_files), expected_files, name) + + try: + process = subprocess.Popen( + argv, + stdout=subprocess.PIPE, + stderr=subprocess.STDOUT, + text=True, + bufsize=1, + start_new_session=True, # own process group, so cancel kills children + cwd=str(self.binary.parent) if self.binary else None, + ) + except OSError as exc: + return Pm3Result( + command=command, + argv=argv, + returncode=None, + error=errors.Pm3NotFound(detail=str(exc)), + ) + + with self._lock: + self._process = process + + timed_out = False + deadline = started + self.timeout + try: + assert process.stdout is not None + for raw in process.stdout: + emit(raw) + if self._cancelled.is_set(): + break + if time.monotonic() > deadline: + timed_out = True + break + if timed_out or self._cancelled.is_set(): + self._terminate(process) + returncode = process.wait(timeout=10) + except Exception as exc: # pragma: no cover - defensive + self._terminate(process) + returncode = process.poll() + lines.append(f"[ePassport] {exc.__class__.__name__}: {exc}") + finally: + with self._lock: + self._process = None + + result = Pm3Result( + command=command, + argv=argv, + returncode=returncode, + lines=lines, + duration=time.monotonic() - started, + dump_dir=dump_dir, + ) + if self._cancelled.is_set(): + result.error = errors.CancelledError() + elif timed_out: + result.error = errors.TimeoutError_( + detail=f"no completion within {self.timeout:.0f} s" + ) + else: + result.error = errors.classify(lines) + return result + + # -- cancellation ----------------------------------------------------- + def cancel(self) -> None: + """Ask the running command to stop. Safe to call from the UI thread.""" + self._cancelled.set() + with self._lock: + process = self._process + if process is not None: + self._terminate(process) + + @property + def running(self) -> bool: + with self._lock: + return self._process is not None + + @staticmethod + def _terminate(process: subprocess.Popen[str]) -> None: + """SIGTERM the whole process group, SIGKILL it 3 s later.""" + if process.poll() is not None: + return + try: + os.killpg(os.getpgid(process.pid), signal.SIGTERM) + except (ProcessLookupError, PermissionError, OSError): + try: + process.terminate() + except OSError: + return + try: + process.wait(timeout=3) + return + except subprocess.TimeoutExpired: + pass + try: + os.killpg(os.getpgid(process.pid), signal.SIGKILL) + except (ProcessLookupError, PermissionError, OSError): + try: + process.kill() + except OSError: + pass + + # -- dry run ---------------------------------------------------------- + def _replay( + self, + command: str, + on_line: Callable[[str], None] | None, + on_progress: Callable[[int, int, str], None] | None, + dump_dir: Path | None, + started: float, + ) -> Pm3Result: + """Replay a recorded pm3 log so the whole app works with no hardware.""" + try: + raw = self.dry_run_log.read_text(encoding="utf-8", errors="replace") + except OSError as exc: + return Pm3Result( + command=command, + argv=[], + returncode=None, + error=errors.Pm3Error(str(exc)), + ) + lines: list[str] = [] + seen: set[str] = set() + for raw_line in raw.splitlines(): + if self._cancelled.is_set(): + return Pm3Result( + command=command, + argv=[], + returncode=None, + lines=lines, + error=errors.CancelledError(), + ) + line = strip_ansi(raw_line) + lines.append(line) + if on_line is not None: + on_line(line) + match = _PROGRESS_RE.search(line) + if match and on_progress is not None: + name = match.group(1) + if name not in seen: + seen.add(name) + on_progress(len(seen), 0, name) + time.sleep(0.01) # worker thread only - keeps the log pane readable + return Pm3Result( + command=command, + argv=["", str(self.dry_run_log)], + returncode=0, + lines=lines, + error=errors.classify(lines), + duration=time.monotonic() - started, + dump_dir=dump_dir, + ) + + +def count_expected_files(lines: Iterable[str]) -> int: + """How many data groups EF_COM announced, for a determinate progress bar.""" + for line in lines: + match = re.search(r"announced.*?(\[[^\]]*\])", line) + if match: + return len([p for p in match.group(1).strip("[]").split(",") if p.strip()]) + return 0 diff --git a/tools/ePassport/epassport/pm3/errors.py b/tools/ePassport/epassport/pm3/errors.py new file mode 100644 index 000000000..00c47191d --- /dev/null +++ b/tools/ePassport/epassport/pm3/errors.py @@ -0,0 +1,208 @@ +"""Typed pm3 failures, each carrying a plain-English remedy for the UI.""" + +from __future__ import annotations + +import re +from dataclasses import dataclass + + +class Pm3Error(Exception): + """Base class. ``title`` and ``remedy`` are what the UI panel shows.""" + + title = "Proxmark3 error" + remedy = "See the log pane for the raw client output." + + def __init__(self, message: str = "", *, detail: str = "") -> None: + super().__init__(message or self.title) + self.detail = detail + + @property + def message(self) -> str: + return str(self) + + +class Pm3NotFound(Pm3Error): + title = "pm3 client not found" + remedy = ( + "Set the pm3 binary path in Settings, or put 'pm3' on your PATH.\n" + "In a proxmark3 source tree the wrapper script is at ./pm3." + ) + + +class Pm3NotExecutable(Pm3Error): + title = "pm3 client is not executable" + remedy = "Run: chmod +x " + + +class NoDeviceError(Pm3Error): + title = "No Proxmark3 found" + remedy = ( + "Plug the Proxmark3 in and check it enumerates (ls /dev/ttyACM*).\n" + "If you are in the dialout group you may need to log out and back in." + ) + + +class PortBusyError(Pm3Error): + title = "Proxmark3 port is busy" + remedy = "Another pm3 session already owns the device - close it and try again." + + +class NoCardError(Pm3Error): + title = "No passport in the field" + remedy = ( + "Lay the passport flat on the antenna, data page down, and keep it still.\n" + "Passport covers are shielded: open the book so the chip page is over the coil." + ) + + +class CardLostError(Pm3Error): + title = "Lost the card mid-transaction" + remedy = "The chip left the field before the dump finished. Do not move the passport while it reads." + + +class BacFailedError(Pm3Error): + title = "BAC authentication failed" + remedy = ( + "Check the MRZ digits. Both dates are YYMMDD, not DDMMYY:\n" + " date of birth - the holder's, from MRZ line 2 positions 14-19\n" + " date of expiry - MRZ line 2 positions 22-27\n" + "The document number must include its trailing '<' fillers only if you typed the full field." + ) + + +class PaceOnlyError(Pm3Error): + title = "Document requires PACE" + remedy = ( + "This chip refuses BAC and only speaks PACE.\n" + "Supply the Card Access Number (CAN) printed on the document, or leave the\n" + "mode on Automatic so the client tries PACE with the MRZ first." + ) + + +class CanWrongError(Pm3Error): + title = "Wrong CAN" + remedy = ( + "The document rejected that Card Access Number.\n" + "The CAN is the short number printed on the data page - usually 6 digits,\n" + "often next to the photo or in the machine-readable zone's margin.\n" + "Careful: the chip counts wrong attempts and will block the password." + ) + + +class PaceFailedError(Pm3Error): + title = "PACE authentication failed" + remedy = ( + "The chip accepted the password but the PACE exchange did not complete.\n" + "Keep the document still on the antenna and try again; if it persists,\n" + "force BAC with the MRZ instead." + ) + + +class PaceAlgorithmError(Pm3Error): + title = "PACE algorithm rejected" + remedy = ( + "The document refused the PACE algorithm the client offered.\n" + "Try the MRZ with BAC instead - this chip wants something 'hf emrtd'\n" + "does not currently negotiate." + ) + + +class MissingBacInputError(Pm3Error): + title = "Incomplete BAC input" + remedy = "Document number, date of birth and date of expiry are all required, or a full 44-char MRZ line 2." + + +class TimeoutError_(Pm3Error): + title = "pm3 timed out" + remedy = "The client did not finish in time. Raise the timeout in Settings, or check the device." + + +class CancelledError(Pm3Error): + title = "Cancelled" + remedy = "The read was cancelled." + + +@dataclass(frozen=True) +class _Rule: + pattern: re.Pattern[str] + exc: type[Pm3Error] + + +#: Matched against every log line, in order. Patterns are taken from the +#: strings the client and the pm3 wrapper actually print - see +#: client/src/cmdhfemrtd.c and the pm3 shell script. +RULES: tuple[_Rule, ...] = ( + _Rule(re.compile(r"Waiting for Proxmark3 to appear", re.I), NoDeviceError), + _Rule(re.compile(r"No port found", re.I), NoDeviceError), + _Rule(re.compile(r"insufficient privileges", re.I), NoDeviceError), + _Rule( + re.compile( + r"(port .* busy|Resource temporarily unavailable|Device or resource busy)", + re.I, + ), + PortBusyError, + ), + _Rule(re.compile(r"OFFLINE.*mode", re.I), NoDeviceError), + _Rule(re.compile(r"Did you supply the correct MRZ info", re.I), BacFailedError), + _Rule( + re.compile(r"Challenge failed, rnd_ifd does not match", re.I), BacFailedError + ), + _Rule( + re.compile(r"enforces authentication, but you didn't supply MRZ data", re.I), + MissingBacInputError, + ), + _Rule(re.compile(r"Couldn't get challenge", re.I), CardLostError), + _Rule(re.compile(r"Couldn't select the MRTD application", re.I), NoCardError), + _Rule(re.compile(r"Can't select card", re.I), NoCardError), + _Rule( + re.compile(r"(iso14443a card select failed|No known/supported 14a tag)", re.I), + NoCardError, + ), + _Rule(re.compile(r"Failed to read EF_COM", re.I), CardLostError), + # PACE, most specific first: a wrong password is actionable, the rest is not. + _Rule(re.compile(r"PACE.*wrong password", re.I), CanWrongError), + _Rule(re.compile(r"PACE: invalid CAN", re.I), CanWrongError), + _Rule( + re.compile(r"CAN (has to be numeric|length is incorrect)", re.I), CanWrongError + ), + _Rule(re.compile(r"PACE.*rejected the algorithm", re.I), PaceAlgorithmError), + _Rule( + re.compile(r"PACE.*(authentication token is wrong|echoed our ephemeral)", re.I), + PaceFailedError, + ), + _Rule( + re.compile( + r"PACE: .*(failed|got no response|malformed|missing data object)", re.I + ), + PaceFailedError, + ), + _Rule(re.compile(r"PACE needs a password", re.I), MissingBacInputError), + _Rule(re.compile(r"mutually exclusive", re.I), MissingBacInputError), + _Rule(re.compile(r"BAC needs MRZ data", re.I), MissingBacInputError), + _Rule(re.compile(r"PACE.*(only|required|not supported)", re.I), PaceOnlyError), +) + + +#: Lines that mean authentication succeeded, and by which mechanism. +SUCCESS_PATTERNS: tuple[tuple[re.Pattern[str], str], ...] = ( + (re.compile(r"Authentication with PACE successful", re.I), "PACE"), + (re.compile(r"Basic Access Control successful", re.I), "BAC"), +) + + +def detect_mechanism(lines: list[str]) -> str: + """Which mechanism actually unlocked the chip, or "" if none did.""" + for pattern, name in SUCCESS_PATTERNS: + for line in lines: + if pattern.search(line): + return name + return "" + + +def classify(lines: list[str]) -> Pm3Error | None: + """Return the most specific failure implied by the collected log lines.""" + for rule in RULES: + for line in lines: + if rule.pattern.search(line): + return rule.exc(detail=line.strip()) + return None diff --git a/tools/ePassport/epassport/ui/__init__.py b/tools/ePassport/epassport/ui/__init__.py new file mode 100644 index 000000000..56e2c0592 --- /dev/null +++ b/tools/ePassport/epassport/ui/__init__.py @@ -0,0 +1,32 @@ +"""Kivy UI package. Importing it registers every bundled ``.kv`` rule set.""" + +from __future__ import annotations + +from pathlib import Path + +_LOADED = False + +#: Load order matters: leaf widgets before the pages that use them. +KV_FILES = ( + "widgets/fields.kv", + "passport.kv", + "tabs/tabs.kv", + "entry.kv", + "scan.kv", + "app.kv", +) + + +def load_kv() -> None: + """Load every ``.kv`` file exactly once.""" + global _LOADED + if _LOADED: + return + from kivy.lang import Builder + + here = Path(__file__).resolve().parent + for name in KV_FILES: + path = here / name + if path.is_file(): + Builder.load_file(str(path)) + _LOADED = True diff --git a/tools/ePassport/epassport/ui/app.kv b/tools/ePassport/epassport/ui/app.kv new file mode 100644 index 000000000..6f06a5bd0 --- /dev/null +++ b/tools/ePassport/epassport/ui/app.kv @@ -0,0 +1,426 @@ +#:import theme epassport.ui.theme +#:import TabStrip epassport.ui.tabs.tabs.TabStrip +#:import BookTab epassport.ui.tabs.tabs.BookTab +#:import PageTurn epassport.ui.tabs.tabs.PageTurn +#:import ErrorPanel epassport.ui.entry.ErrorPanel +#:import EntryScreen epassport.ui.entry.EntryScreen +#:import ScanScreen epassport.ui.scan.ScanScreen +#:import BinButton epassport.ui.widgets.binbutton.BinButton + +: + orientation: "vertical" + canvas.before: + Color: + rgba: app.palette["bg"] + Rectangle: + pos: self.pos + size: self.size + + # ---- toolbar --------------------------------------------------------- + BoxLayout: + size_hint_y: None + height: dp(32) + padding: dp(8), dp(4) + spacing: dp(6) + canvas.before: + Color: + rgba: app.palette["panel"] + Rectangle: + pos: self.pos + size: self.size + Color: + rgba: app.palette["border"] + Line: + points: [self.x, self.y, self.right, self.y] + width: 1 + + Button: + text: "New read" + size_hint_x: None + width: dp(96) + font_name: theme.FONT_LABEL + font_size: sp(12) + on_release: app.goto_entry() + + Button: + text: "Dumps…" + size_hint_x: None + width: dp(74) + font_name: theme.FONT_LABEL + font_size: sp(11) + on_release: app.open_dumps_browser() + + Button: + text: "Delete dump" + size_hint_x: None + width: dp(110) + font_name: theme.FONT_LABEL + font_size: sp(12) + disabled: not app.status_dump_dir + on_release: app.delete_dump() + + Widget: + + Button: + text: "True size" if app.scale_mode == "fit" else "Fit window" + size_hint_x: None + width: dp(90) + font_name: theme.FONT_LABEL + font_size: sp(11) + on_release: app.toggle_scale_mode() + + Button: + text: "Dark chrome" if not app.dark else "Light chrome" + size_hint_x: None + width: dp(120) + font_name: theme.FONT_LABEL + font_size: sp(12) + on_release: app.toggle_dark() + + # ---- screens --------------------------------------------------------- + ScreenManager: + id: sm + + ViewerScreen: + name: "viewer" + + EntryScreen: + name: "entry" + palette: app.palette + + ScanScreen: + name: "scan" + palette: app.palette + + # ---- status bar ------------------------------------------------------ + BoxLayout: + size_hint_y: None + height: dp(21) + padding: dp(8), 0 + spacing: dp(10) + canvas.before: + Color: + rgba: app.palette["panel"] + Rectangle: + pos: self.pos + size: self.size + Color: + rgba: app.palette["border"] + Line: + points: [self.x, self.top, self.right, self.top] + width: 1 + + Label: + text: app.status_connection + font_name: theme.FONT_MONO + font_size: sp(10) + color: app.palette["text_dim"] + halign: "left" + valign: "middle" + text_size: self.size + shorten: True + + Label: + text: "BAC: " + app.status_bac + font_name: theme.FONT_MONO + font_size: sp(10) + color: theme.OK if app.status_bac == "success" else (theme.BAD if app.status_bac == "failed" else app.palette["text_dim"]) + size_hint_x: None + width: dp(120) + halign: "left" + valign: "middle" + text_size: self.size + + Label: + text: "auth: " + app.status_auth + font_name: theme.FONT_MONO + font_size: sp(10) + color: app.palette["text_dim"] + size_hint_x: None + width: dp(120) + halign: "left" + valign: "middle" + text_size: self.size + + Button: + text: app.status_dump_dir or "no dump" + font_name: theme.FONT_MONO + font_size: sp(10) + color: app.palette["accent"] if app.status_dump_dir else app.palette["text_dim"] + background_color: 0, 0, 0, 0 + disabled: not app.status_dump_dir + halign: "right" + valign: "middle" + text_size: self.size + shorten: True + shorten_from: "left" + on_release: app.open_dump_dir() + +: + BoxLayout: + orientation: "vertical" + + # progress + cancel + BoxLayout: + size_hint_y: None + height: dp(28) if app.busy else 0 + opacity: 1 if app.busy else 0 + padding: dp(12), dp(4) + spacing: dp(10) + Label: + text: app.progress_text + font_name: theme.FONT_MONO + font_size: sp(11) + color: app.palette["text_dim"] + size_hint_x: None + width: dp(240) + halign: "left" + valign: "middle" + text_size: self.size + ProgressBar: + max: 1.0 + value: app.progress + Button: + text: "Cancel" + size_hint_x: None + width: dp(90) + font_name: theme.FONT_LABEL_BOLD + font_size: sp(12) + on_release: app.cancel_read() + + ErrorPanel: + id: error_panel + palette: app.palette + + TabStrip: + id: tabs + palette: app.palette + on_kv_post: + self.clear_widgets() + [self.add_widget(BookTab(text=t, index=i, palette=app.palette, on_release=lambda w: app.select_tab(w.index))) for i, t in enumerate(theme.TAB_TITLES)] + + BoxLayout: + padding: dp(6), 0, dp(6), dp(6) + PageTurn: + id: pages + +: + title: "Choose a folder" + size_hint: 0.8, 0.8 + title_color: theme.POPUP_TITLE + separator_color: app.palette["accent"] + on_kv_post: root.build_shortcuts() + BoxLayout: + orientation: "vertical" + spacing: dp(6) + padding: dp(8) + canvas.before: + Color: + rgba: app.palette["panel"] + Rectangle: + pos: self.pos + size: self.size + + # Jump straight to the places dumps actually live. + BoxLayout: + id: shortcuts + size_hint_y: None + height: dp(28) + spacing: dp(6) + + # ...and type or paste anything else. + BoxLayout: + size_hint_y: None + height: dp(30) + spacing: dp(6) + TextInput: + id: pathbox + text: chooser.path + multiline: False + font_name: theme.FONT_MONO + font_size: sp(11) + padding: dp(6), dp(6) + background_color: app.palette["field_bg"] + foreground_color: app.palette["text"] + cursor_color: app.palette["accent"] + on_text_validate: root.go_to_typed(self.text) + Button: + text: "Go" + size_hint_x: None + width: dp(50) + font_size: sp(11) + on_release: root.go_to_typed(pathbox.text) + + FileChooserListView: + id: chooser + path: root.start + dirselect: True + on_selection: root.on_chooser_selection(self.selection) + + Label: + text: root.selection + font_name: theme.FONT_MONO + font_size: sp(11) + color: app.palette["text"] + size_hint_y: None + height: dp(20) + halign: "left" + valign: "middle" + text_size: self.size + shorten: True + shorten_from: "left" + + BoxLayout: + size_hint_y: None + height: dp(34) + spacing: dp(8) + Button: + text: "Cancel" + on_release: root.dismiss() + Button: + text: "Choose this folder" + on_release: root.choose() + +: + title: root.title_text + size_hint: None, None + size: dp(480), dp(240) + title_color: theme.POPUP_TITLE + separator_color: theme.BAD + BoxLayout: + orientation: "vertical" + padding: dp(14) + spacing: dp(10) + canvas.before: + Color: + rgba: app.palette["panel"] + Rectangle: + pos: self.pos + size: self.size + Label: + text: root.message + font_name: theme.FONT_LABEL + font_size: sp(12) + color: app.palette["text"] + halign: "left" + valign: "top" + text_size: self.size + BoxLayout: + size_hint_y: None + height: dp(38) + spacing: dp(8) + Button: + text: "Cancel" + on_release: root.dismiss() + Button: + text: root.confirm_text + on_release: root.confirm() + +: + size_hint_y: None + height: dp(40) + spacing: dp(8) + padding: dp(6), 0 + BoxLayout: + orientation: "vertical" + Label: + text: root.when + font_name: theme.FONT_LABEL_BOLD + font_size: sp(12) + color: app.palette["text_dim"] if root.empty else app.palette["text"] + halign: "left" + valign: "bottom" + text_size: self.size + Label: + text: root.summary + font_name: theme.FONT_MONO + font_size: sp(10) + color: theme.WARN if root.empty else app.palette["text_dim"] + halign: "left" + valign: "top" + text_size: self.size + Button: + text: "Open" + size_hint_x: None + width: dp(66) + font_name: theme.FONT_LABEL + font_size: sp(11) + disabled: root.empty + on_release: root.dispatch("on_open") + BinButton: + size_hint: None, None + size: dp(30), dp(30) + pos_hint: {"center_y": 0.5} + tint: app.palette["text_dim"] + on_release: root.dispatch("on_delete") + +: + title: "Dumps read by this app" + size_hint: 0.8, 0.8 + title_color: theme.POPUP_TITLE + separator_color: app.palette["accent"] + BoxLayout: + orientation: "vertical" + padding: dp(8) + spacing: dp(6) + # Kivy's default modal background is dark whatever our palette says, + # so paint the panel ourselves and keep control of the contrast. + canvas.before: + Color: + rgba: app.palette["panel"] + Rectangle: + pos: self.pos + size: self.size + Label: + text: root.status + font_name: theme.FONT_MONO + font_size: sp(10) + color: app.palette["text_dim"] + size_hint_y: None + height: dp(20) + halign: "left" + valign: "middle" + text_size: self.size + shorten: True + shorten_from: "left" + ScrollView: + bar_width: dp(6) + GridLayout: + id: rows + cols: 1 + size_hint_y: None + height: self.minimum_height + spacing: dp(2) + BoxLayout: + size_hint_y: None + height: dp(34) + spacing: dp(6) + Button: + text: "Open folder" + font_name: theme.FONT_LABEL + font_size: sp(11) + on_release: root.open_folder() + Button: + text: "Remove empty" + font_name: theme.FONT_LABEL + font_size: sp(11) + on_release: root.prune() + Button: + text: "Samples…" + font_name: theme.FONT_LABEL + font_size: sp(11) + disabled: not root.has_samples + on_release: root.dismiss() or app.open_samples_dialog() + Button: + text: "Browse…" + font_name: theme.FONT_LABEL + font_size: sp(11) + on_release: root.dismiss() or app.open_dump_dialog() + Widget: + Button: + text: "Close" + size_hint_x: None + width: dp(80) + font_name: theme.FONT_LABEL + font_size: sp(11) + on_release: root.dismiss() diff --git a/tools/ePassport/epassport/ui/dialogs.py b/tools/ePassport/epassport/ui/dialogs.py new file mode 100644 index 000000000..4929138e4 --- /dev/null +++ b/tools/ePassport/epassport/ui/dialogs.py @@ -0,0 +1,244 @@ +"""Small popups: pick a directory, confirm a destructive action. + +Kivy's FileChooser is used rather than a native dialog so the app has no +desktop-portal dependency and stays entirely self-contained. +""" + +from __future__ import annotations + +from pathlib import Path +from typing import Callable + +from kivy.app import App +from kivy.metrics import dp, sp +from kivy.properties import BooleanProperty, ObjectProperty, StringProperty +from kivy.uix.boxlayout import BoxLayout +from kivy.uix.popup import Popup + + +class ChooseDirPopup(Popup): + """Directory picker. Calls ``on_choice(Path)`` with the chosen folder. + + Navigating to a dump by hand is tedious, so the places one actually keeps + them are one click away, and the path is typeable for everything else. + """ + + start = StringProperty("") + selection = StringProperty("") + + def __init__( + self, *, start: str, on_choice: Callable[[Path], None], **kwargs + ) -> None: + self.start = start if Path(start).is_dir() else str(Path.home()) + self.selection = self.start + self._on_choice = on_choice + super().__init__(**kwargs) + + # -- quick jumps ------------------------------------------------------- + @staticmethod + def shortcuts() -> list[tuple[str, Path]]: + """``(label, path)`` for every shortcut that actually exists.""" + from kivy.app import App + + from ..config import browse_start, dumps_dir, samples_dir + + app = App.get_running_app() + last = getattr(getattr(app, "settings", None), "last_dump_dir", "") + candidates: list[tuple[str, Path | None]] = [ + ("Recent", browse_start(last) if last else None), + ("Dumps", dumps_dir()), + ("Samples", samples_dir()), + ("Working dir", Path.cwd()), + ("Home", Path.home()), + ] + seen: set[Path] = set() + out: list[tuple[str, Path]] = [] + for label, path in candidates: + if path is None or not path.is_dir(): + continue + resolved = path.resolve() + if resolved in seen: + continue # e.g. launched from the project root + seen.add(resolved) + out.append((label, resolved)) + return out + + def build_shortcuts(self) -> None: + from kivy.uix.button import Button + + box = self.ids.get("shortcuts") + if box is None: + return + box.clear_widgets() + for label, path in self.shortcuts(): + button = Button( + text=label, font_size=sp(11), size_hint_x=None, width=dp(96) + ) + button.bind(on_release=lambda _w, p=path: self.jump(p)) + box.add_widget(button) + + def jump(self, path: Path) -> None: + """Point the chooser at ``path``.""" + chooser = self.ids.get("chooser") + if chooser is not None and path.is_dir(): + chooser.path = str(path) + self.selection = str(path) + + def go_to_typed(self, text: str) -> None: + """Accept a typed or pasted path.""" + target = Path(text.strip()).expanduser() + if target.is_dir(): + self.jump(target) + elif target.parent.is_dir(): + self.jump(target.parent) + + # -- selection --------------------------------------------------------- + def choose(self) -> None: + target = Path(self.selection or self.start) + self.dismiss() + if target.is_dir(): + self._on_choice(target) + + def on_chooser_selection(self, paths: list[str]) -> None: + """A file selection means 'this file's folder'.""" + if not paths: + return + chosen = Path(paths[0]) + self.selection = str(chosen if chosen.is_dir() else chosen.parent) + + +class DumpRow(BoxLayout): + """One dump in the browser: when it was read, and what it holds.""" + + __events__ = ("on_open", "on_delete") + + when = StringProperty("") + summary = StringProperty("") + path = StringProperty("") + empty = BooleanProperty(False) + palette = ObjectProperty(None) + + def on_open(self, *_args) -> None: + """Default handler; the browser binds over this.""" + + def on_delete(self, *_args) -> None: + """Default handler; the browser binds over this.""" + + +class DumpsPopup(Popup): + """Browse the app's own dump directory. + + "Where did my read go?" should never need a file manager, so this lists + every dump with its timestamp and contents, and can open the folder. + """ + + status = StringProperty("") + + def __init__(self, *, on_choice: Callable[[Path], None], **kwargs) -> None: + self._on_choice = on_choice + super().__init__(**kwargs) + self.refresh() + + def refresh(self) -> None: + from ..config import dumps_dir, list_dumps + from .. import ui # noqa: F401 (kv rules are already loaded) + + entries = list_dumps() + box = self.ids.get("rows") + if box is None: + return + box.clear_widgets() + app = App.get_running_app() + palette = getattr(app, "palette", None) + for entry in entries: + row = DumpRow( + when=entry.when, + summary=entry.summary, + path=str(entry.path), + empty=entry.is_empty, + palette=palette, + ) + row.bind(on_open=lambda widget: self.choose(widget.path)) + row.bind(on_delete=lambda widget: self.confirm_delete(widget.path)) + box.add_widget(row) + self.status = f"{len(entries)} dump(s) in {dumps_dir()}" + if not entries: + self.status = f"No dumps yet. They will appear in {dumps_dir()}" + + def choose(self, path: str) -> None: + self.dismiss() + self._on_choice(Path(path)) + + def confirm_delete(self, path: str) -> None: + """Ask first: a dump holds the live personal data of a real document.""" + target = Path(path) + ConfirmPopup( + title_text="Delete this dump?", + message=( + f"{target}\n\n" + "This permanently removes the dumped files, including the " + "portrait and the MRZ. It cannot be undone." + ), + confirm_text="Delete", + confirm_action=lambda: self.delete(target), + ).open() + + def delete(self, target: Path) -> None: + import shutil + + try: + shutil.rmtree(target) + except OSError as exc: + self.status = f"Could not delete {target.name}: {exc}" + return + app = App.get_running_app() + if app is not None and getattr(app, "status_dump_dir", "") == str(target): + app.forget_current_dump() + self.refresh() + self.status = f"Deleted {target.name}" + + @property + def has_samples(self) -> bool: + from ..config import samples_dir + + return samples_dir() is not None + + def open_folder(self) -> None: + from ..config import dumps_dir + + _open_in_file_manager(dumps_dir()) + + def prune(self) -> None: + from ..config import prune_empty_dumps + + removed = prune_empty_dumps() + self.refresh() + if removed: + self.status = f"Removed {removed} empty dump(s)." + + +def _open_in_file_manager(path) -> None: + import subprocess + + try: + subprocess.Popen(["xdg-open", str(path)], start_new_session=True) + except OSError: + pass + + +class ConfirmPopup(Popup): + """Yes/no confirmation for anything destructive.""" + + title_text = StringProperty("") + message = StringProperty("") + confirm_text = StringProperty("Delete") + #: Deliberately NOT named ``on_confirm``: Kivy treats any constructor + #: keyword starting with ``on_`` as an event binding, so passing + #: ``on_confirm=callback`` silently binds an observer and leaves the + #: property None - the dialog then confirms and does nothing. + confirm_action = ObjectProperty(None) + + def confirm(self) -> None: + self.dismiss() + if callable(self.confirm_action): + self.confirm_action() diff --git a/tools/ePassport/epassport/ui/entry.kv b/tools/ePassport/epassport/ui/entry.kv new file mode 100644 index 000000000..4a16c2442 --- /dev/null +++ b/tools/ePassport/epassport/ui/entry.kv @@ -0,0 +1,281 @@ +#:import theme epassport.ui.theme +#:import entry epassport.ui.entry + +: + caption: "" + hint: "" + error: "" + value: "" + sanitizer: None + orientation: "vertical" + size_hint_y: None + height: dp(58) + spacing: dp(2) + Label: + text: root.caption + font_name: theme.FONT_LABEL_BOLD + font_size: sp(11) + color: app.palette["text_dim"] + size_hint_y: None + height: dp(15) + halign: "left" + valign: "middle" + text_size: self.size + TextInput: + id: box + text: root.value + on_text: root.value = root.sanitizer(self.text) if root.sanitizer else self.text + hint_text: root.hint + multiline: False + font_name: theme.FONT_MONO + font_size: sp(15) + size_hint_y: None + height: dp(30) + padding: dp(8), dp(6) + background_color: app.palette["field_bg"] + foreground_color: app.palette["text"] + cursor_color: app.palette["accent"] + Label: + text: root.error + font_name: theme.FONT_LABEL + font_size: sp(10) + color: theme.BAD + size_hint_y: None + height: dp(13) + halign: "left" + valign: "middle" + text_size: self.size + +: + orientation: "vertical" + size_hint_y: None + height: self.minimum_height if root.visible else 0 + opacity: 1 if root.visible else 0 + padding: dp(14) + spacing: dp(6) + canvas.before: + Color: + rgba: theme.BAD[0], theme.BAD[1], theme.BAD[2], 0.10 + RoundedRectangle: + pos: self.pos + size: self.size + radius: [dp(6)] + Color: + rgba: theme.BAD[0], theme.BAD[1], theme.BAD[2], 0.55 + Line: + rounded_rectangle: (self.x, self.y, self.width, self.height, dp(6)) + width: 1.2 + Label: + text: root.title + font_name: theme.FONT_LABEL_BOLD + font_size: sp(15) + color: theme.BAD + size_hint_y: None + height: self.texture_size[1] + text_size: self.width, None + halign: "left" + Label: + text: root.detail + font_name: theme.FONT_MONO + font_size: sp(11) + color: app.palette["text_dim"] + size_hint_y: None + height: self.texture_size[1] if root.detail else 0 + text_size: self.width, None + halign: "left" + Label: + text: root.remedy + font_name: theme.FONT_LABEL + font_size: sp(13) + color: app.palette["text"] + size_hint_y: None + height: self.texture_size[1] + text_size: self.width, None + halign: "left" + +: + on_kv_post: root.revalidate() + document_number: docnum.value + date_of_birth: dob.value + date_of_expiry: expiry.value + mrz_line2: line2.value + can: canbox.value + + BoxLayout: + orientation: "vertical" + padding: dp(28) + spacing: dp(10) + + Label: + text: "Chip access key material" + font_name: theme.FONT_LABEL_BOLD + font_size: sp(18) + color: app.palette["accent"] + size_hint_y: None + height: dp(30) + halign: "left" + valign: "middle" + text_size: self.size + + Label: + text: "Use the MRZ (all three values, both dates YYMMDD), or the CAN printed on the data page." + font_name: theme.FONT_LABEL + font_size: sp(12) + color: app.palette["text_dim"] + size_hint_y: None + height: dp(20) + halign: "left" + valign: "middle" + text_size: self.size + + BoxLayout: + size_hint_y: None + height: dp(58) + spacing: dp(14) + + PmField: + id: docnum + caption: "DOCUMENT NUMBER" + hint: "L898902C3" + sanitizer: entry.sanitize_docnum + error: root.docnum_error + + PmField: + id: dob + caption: "DATE OF BIRTH (YYMMDD)" + hint: "740812" + sanitizer: entry.sanitize_date + error: root.dob_error + size_hint_x: 0.7 + + PmField: + id: expiry + caption: "DATE OF EXPIRY (YYMMDD)" + hint: "120415" + sanitizer: entry.sanitize_date + error: root.expiry_error + size_hint_x: 0.7 + + PmField: + id: line2 + caption: "OR MRZ LINE 2 (44 CHARACTERS - TAKES PRECEDENCE)" + hint: "L898902C36UTO7408122F1204159ZE184226B<<<<<10" + sanitizer: entry.sanitize_line2 + error: root.line2_error + + BoxLayout: + size_hint_y: None + height: dp(58) + spacing: dp(14) + + PmField: + id: canbox + caption: "CAN" + hint: "123456" + error: root.can_error + sanitizer: entry.sanitize_can + size_hint_x: None + width: dp(240) + + BoxLayout: + orientation: "vertical" + spacing: dp(2) + Label: + text: "AUTHENTICATION" + font_name: theme.FONT_LABEL_BOLD + font_size: sp(11) + color: app.palette["text_dim"] + size_hint_y: None + height: dp(15) + halign: "left" + valign: "middle" + text_size: self.size + Spinner: + id: auth_picker + text: root.auth_label + values: list(entry.AUTH_LABELS.values()) + size_hint_y: None + height: dp(30) + font_name: theme.FONT_LABEL + font_size: sp(12) + sync_height: True + on_text: root.auth_label = self.text + Widget: + size_hint_y: None + height: dp(13) + + Label: + text: root.auth_note + font_name: theme.FONT_LABEL + font_size: sp(11) + color: app.palette["text_dim"] + size_hint_y: None + height: dp(18) + halign: "left" + valign: "middle" + text_size: self.size + + Label: + text: root.derived_note + font_name: theme.FONT_LABEL + font_size: sp(11) + color: app.palette["text_dim"] + size_hint_y: None + height: dp(18) + halign: "left" + valign: "middle" + text_size: self.size + + BoxLayout: + size_hint_y: None + height: dp(30) + spacing: dp(8) + CheckBox: + id: remember_box + size_hint_x: None + width: dp(30) + active: root.remember + on_active: root.remember = self.active + Label: + text: "Remember these values (they are live credential material)" + font_name: theme.FONT_LABEL + font_size: sp(12) + color: app.palette["text_dim"] + halign: "left" + valign: "middle" + text_size: self.size + + ErrorPanel: + id: error_panel + palette: app.palette + + Widget: + + BoxLayout: + size_hint_y: None + height: dp(40) + spacing: dp(10) + + Button: + text: "Scan MRZ with camera" + font_name: theme.FONT_LABEL + font_size: sp(13) + disabled: not app.camera_available + on_release: app.goto_scan() + + Button: + text: "Open a saved dump…" + font_name: theme.FONT_LABEL + font_size: sp(13) + on_release: app.open_dumps_browser() + + Widget: + + Button: + text: "Read passport" + font_name: theme.FONT_LABEL_BOLD + font_size: sp(14) + size_hint_x: None + width: dp(170) + disabled: not root.valid or app.busy + on_release: app.start_read() diff --git a/tools/ePassport/epassport/ui/entry.py b/tools/ePassport/epassport/ui/entry.py new file mode 100644 index 000000000..70d5420fc --- /dev/null +++ b/tools/ePassport/epassport/ui/entry.py @@ -0,0 +1,324 @@ +"""Manual BAC entry: the three fields, or a full MRZ line 2 that wins.""" + +from __future__ import annotations + +import re +from dataclasses import dataclass + +from kivy.properties import BooleanProperty, ObjectProperty, StringProperty +from kivy.uix.boxlayout import BoxLayout +from kivy.uix.screenmanager import Screen + +from ..emrtd import mrz as mrzlib +from ..pm3.client import AUTH_AUTO, AUTH_BAC, AUTH_PACE, BacInput, ValidationError +from . import theme + +_DIGITS = re.compile(r"[^0-9]") +_MRZ_CHARS = re.compile(r"[^0-9A-Z<]") + + +def sanitize_docnum(text: str) -> str: + return _MRZ_CHARS.sub("", text.upper())[:9] + + +def sanitize_date(text: str) -> str: + return _DIGITS.sub("", text)[:6] + + +def sanitize_line2(text: str) -> str: + return _MRZ_CHARS.sub("", text.upper())[:44] + + +def sanitize_can(text: str) -> str: + return _DIGITS.sub("", text)[:14] + + +#: Labels for the authentication picker, in the order they are offered. +AUTH_LABELS: dict[str, str] = { + AUTH_AUTO: "Automatic (PACE, then BAC)", + AUTH_PACE: "PACE only", + AUTH_BAC: "BAC only", +} +AUTH_BY_LABEL: dict[str, str] = {label: mode for mode, label in AUTH_LABELS.items()} + + +def date_problem(text: str) -> str: + """Live validation message for a YYMMDD field, or "" when it is fine.""" + if len(text) < 6: + return "YYMMDD" + month, day = int(text[2:4]), int(text[4:6]) + if not 1 <= month <= 12: + return "month must be 01-12" + days = (31, 29, 31, 30, 31, 30, 31, 31, 30, 31, 30, 31)[month - 1] + if not 1 <= day <= days: + return f"day must be 01-{days:02d}" + return "" + + +@dataclass +class FormState: + """The outcome of validating the entry form. + + Kept free of Kivy so it can be tested directly - the version of this logic + that lived only inside the widget shipped a bug where entering a CAN left + the MRZ field markers set, which kept the Read button disabled on a form + that was perfectly valid. + """ + + docnum_error: str = "" + dob_error: str = "" + expiry_error: str = "" + line2_error: str = "" + can_error: str = "" + note: str = "" + valid: bool = False + + @property + def fields_ok(self) -> bool: + return not ( + self.docnum_error + or self.dob_error + or self.expiry_error + or self.line2_error + or self.can_error + ) + + +def auth_hint(mode: str, can: str) -> str: + """One line describing what pressing Read will actually attempt.""" + if can and len(can) != 6: + return ( + f"A CAN is usually 6 digits; yours is {len(can)}. It will still be tried." + ) + if can: + return "PACE with the Card Access Number printed on the data page." + if mode == AUTH_BAC: + return "Forcing BAC - PACE will not be attempted." + if mode == AUTH_PACE: + return "Forcing PACE with the MRZ - no BAC fallback if it fails." + return "PACE is tried first, then BAC." + + +def validate_form( + *, + document_number: str = "", + date_of_birth: str = "", + date_of_expiry: str = "", + mrz_line2: str = "", + can: str = "", + mode: str = AUTH_AUTO, +) -> FormState: + """Validate the entry form. + + A CAN alone is enough, and it *replaces* the MRZ - so entering one must + clear the MRZ field markers rather than leaving "required" behind. + """ + state = FormState() + using_can = bool(can) + # A complete line 2 already carries the document number and both dates, + # so it stands on its own - the three boxes are then just a convenience. + line2_complete = bool(mrz_line2) and len(mrz_line2) in (36, 44) + + if using_can: + if not 1 <= len(can) <= 14: + state.can_error = "1-14 digits" + elif document_number or date_of_birth or date_of_expiry or mrz_line2: + state.can_error = "clear the MRZ fields - the CAN replaces them" + elif line2_complete: + pass # nothing else is required + else: + state.docnum_error = "" if document_number else "required" + state.dob_error = date_problem(date_of_birth) + state.expiry_error = date_problem(date_of_expiry) + if mrz_line2: + state.line2_error = f"{len(mrz_line2)}/44 characters" + + untouched = not ( + using_can or document_number or date_of_birth or date_of_expiry or mrz_line2 + ) + try: + build_input( + document_number=document_number, + date_of_birth=date_of_birth, + date_of_expiry=date_of_expiry, + mrz_line2=mrz_line2, + can=can, + mode=mode, + ).validated() + except ValidationError as exc: + # An untouched form is not an error; the field markers already say + # what is still needed. + state.note = "" if untouched else str(exc) + state.valid = False + return state + + # A field-level problem is the reason Read is disabled, so say that rather + # than describing an attempt that is not going to happen. + state.note = state.can_error if state.can_error else auth_hint(mode, can) + state.valid = state.fields_ok + return state + + +def build_input( + *, + document_number: str = "", + date_of_birth: str = "", + date_of_expiry: str = "", + mrz_line2: str = "", + can: str = "", + mode: str = AUTH_AUTO, +) -> BacInput: + """Assemble the key material, preferring the least error-prone form.""" + if can: + return BacInput(can=can, mode=mode) + if mrz_line2 and len(mrz_line2) in (36, 44): + # A whole line 2 avoids field-splitting mistakes entirely. + return BacInput(mrz_line2=mrz_line2, mode=mode) + return BacInput( + document_number=document_number, + date_of_birth=date_of_birth, + date_of_expiry=date_of_expiry, + mode=mode, + ) + + +class EntryScreen(Screen): + """The manual-entry form. ``Read`` stays disabled until inputs validate.""" + + document_number = StringProperty("") + date_of_birth = StringProperty("") + date_of_expiry = StringProperty("") + mrz_line2 = StringProperty("") + can = StringProperty("") + auth_label = StringProperty(AUTH_LABELS[AUTH_AUTO]) + remember = BooleanProperty(False) + + docnum_error = StringProperty("") + dob_error = StringProperty("") + expiry_error = StringProperty("") + line2_error = StringProperty("") + can_error = StringProperty("") + valid = BooleanProperty(False) + derived_note = StringProperty("") + auth_note = StringProperty("") + + palette = ObjectProperty(theme.LIGHT) + + # -- live validation --------------------------------------------------- + def on_document_number(self, *_args) -> None: + self._validate() + + def on_date_of_birth(self, *_args) -> None: + self._validate() + + def on_date_of_expiry(self, *_args) -> None: + self._validate() + + def on_mrz_line2(self, *_args) -> None: + self._autofill_from_line2() + self._validate() + + def on_can(self, *_args) -> None: + self._validate() + + def on_auth_label(self, *_args) -> None: + self._validate() + + @property + def auth_mode(self) -> str: + return AUTH_BY_LABEL.get(self.auth_label, AUTH_AUTO) + + def _autofill_from_line2(self) -> None: + """A clean line 2 populates the three boxes and takes precedence.""" + line = self.mrz_line2 + self.derived_note = "" + if len(line) not in (36, 44): + return + head = "P None: + """Validate once the widget tree exists and its bindings have settled, + so the guidance line is never blank on first show.""" + from kivy.clock import Clock + + Clock.schedule_once(lambda *_: self._validate(), 0) + + def _validate(self) -> None: + state = validate_form( + document_number=self.document_number, + date_of_birth=self.date_of_birth, + date_of_expiry=self.date_of_expiry, + mrz_line2=self.mrz_line2, + can=self.can, + mode=self.auth_mode, + ) + self.docnum_error = state.docnum_error + self.dob_error = state.dob_error + self.expiry_error = state.expiry_error + self.line2_error = state.line2_error + self.can_error = state.can_error + self.auth_note = state.note + self.valid = state.valid + + # -- what the app asks for -------------------------------------------- + def bac_input(self) -> BacInput: + return build_input( + document_number=self.document_number, + date_of_birth=self.date_of_birth, + date_of_expiry=self.date_of_expiry, + mrz_line2=self.mrz_line2, + can=self.can, + mode=self.auth_mode, + ) + + def validated_input(self) -> tuple[BacInput | None, str]: + try: + return self.bac_input().validated(), "" + except ValidationError as exc: + return None, str(exc) + + def set_field(self, field_id: str, text: str) -> None: + """Write into a text box. Values flow box -> field -> screen, so this + is the only correct way to fill the form programmatically.""" + field = self.ids.get(field_id) + if field is not None and "box" in field.ids: + field.ids.box.text = text + + def fill(self, document_number: str, dob: str, expiry: str) -> None: + self.set_field("docnum", sanitize_docnum(document_number)) + self.set_field("dob", sanitize_date(dob)) + self.set_field("expiry", sanitize_date(expiry)) + + def set_line2(self, text: str) -> None: + self.set_field("line2", sanitize_line2(text)) + + +class ErrorPanel(BoxLayout): + """The BAC-failed / no-card / no-device panel: title, cause, remedy.""" + + title = StringProperty("") + detail = StringProperty("") + remedy = StringProperty("") + visible = BooleanProperty(False) + palette = ObjectProperty(theme.LIGHT) diff --git a/tools/ePassport/epassport/ui/passport.kv b/tools/ePassport/epassport/ui/passport.kv new file mode 100644 index 000000000..58c3ea4e7 --- /dev/null +++ b/tools/ePassport/epassport/ui/passport.kv @@ -0,0 +1,207 @@ +#:import theme epassport.ui.theme +#:import Guilloche epassport.ui.widgets.guilloche.Guilloche +#:import Portrait epassport.ui.widgets.portrait.Portrait +#:import MrzStrip epassport.ui.widgets.mrzstrip.MrzStrip +#:import DataField epassport.ui.widgets.fields.DataField + +: + canvas.before: + Color: + rgba: 0, 0, 0, 0.20 + Rectangle: + pos: self.x + dp(4), self.y - dp(4) + size: self.size + + # No StencilView wrapper here: Guilloche clips its own security print to + # the printed frame, and nesting that inside another stencil stops the + # inner one taking effect - Kivy's nested stencils do not intersect. + Guilloche: + pos: root.pos + size: root.size + bottom_inset: root.height * root.band_fraction + + BoxLayout: + orientation: "vertical" + pos: root.pos + size: root.size + padding: 0, root.height * theme.PAGE_TOP_PAD, 0, 0 + spacing: root.height * theme.PAGE_GAP + + # ---- header band ------------------------------------------------- + BoxLayout: + size_hint_y: None + height: root.height * theme.PAGE_HEADER + padding: root.height * 0.062, 0, root.height * 0.062, 0 + + Label: + text: (root.mrz.issuing_state_name.upper() if root.mrz else "NO DOCUMENT LOADED") + font_name: theme.FONT_VALUE + font_size: root.height * 0.044 + color: theme.LABEL + halign: "left" + valign: "middle" + text_size: self.size + shorten: True + + Label: + text: (root.mrz.document_type if root.mrz else "") + font_name: theme.FONT_LABEL_BOLD + font_size: root.height * 0.026 + color: theme.LABEL + halign: "right" + valign: "middle" + text_size: self.size + + # ---- portrait column + field column ------------------------------ + BoxLayout: + spacing: root.height * 0.040 + padding: root.height * 0.062, 0, root.height * 0.062, root.height * theme.PAGE_BOTTOM_PAD + + # The portrait is sized from the page WIDTH and the real 35x45 + # photo aspect, capped against the space above the MRZ band - a + # fraction of page height alone makes it swallow a short card. + BoxLayout: + orientation: "vertical" + size_hint_x: None + width: root.width * theme.PHOTO_WIDTH_FRACTION + spacing: root.height * 0.016 + + # The frame keeps the 35x45 photo shape whichever constraint + # binds, so the image never letterboxes inside white bars. + Portrait: + png: root.record.portrait_png if root.record else b"" + size_hint: None, None + height: min(root.width * theme.PHOTO_WIDTH_FRACTION / theme.PHOTO_ASPECT, root.height * root.content_fraction * theme.PHOTO_MAX_CONTENT_SHARE) + width: self.height * theme.PHOTO_ASPECT + + BoxLayout: + size_hint_y: None + height: root.height * root.content_fraction * 0.22 + spacing: root.height * 0.018 + + Portrait: + png: root.record.portrait_png if root.record else b"" + ghost: True + size_hint_x: None + width: self.height * theme.PHOTO_ASPECT + + Portrait: + png: root.record.signature_png if root.record else b"" + ghost: True + opacity_level: 0.85 + + Widget: + + # ---- the fields, laid out row by row -------------------------- + BoxLayout: + orientation: "vertical" + spacing: root.height * 0.004 + + BoxLayout: + size_hint_y: 0.135 + spacing: root.height * 0.020 + DataField: + size_hint_x: 0.16 + label_text: "TYPE" + value_text: root.mrz.document_code if root.mrz else "" + value_font_size: root.height * 0.038 + label_font_size: root.height * 0.0185 + DataField: + size_hint_x: 0.20 + label_text: "CODE" + value_text: root.mrz.issuing_state if root.mrz else "" + value_font_size: root.height * 0.038 + label_font_size: root.height * 0.0185 + DataField: + size_hint_x: 0.64 + label_text: "PASSPORT No. / No. DU PASSEPORT" + value_text: root.value("document_number") if root.mrz else "" + check: root.check_state("document_number") if root.mrz else "none" + value_font_size: root.height * 0.038 + label_font_size: root.height * 0.0185 + + DataField: + size_hint_y: 0.165 + label_text: "SURNAME / NOM" + value_text: root.record.surname if root.record else "" + value_font_size: root.height * 0.046 + label_font_size: root.height * 0.0185 + + DataField: + size_hint_y: 0.165 + label_text: "GIVEN NAMES / PRENOMS" + value_text: root.record.given_names if root.record else "" + value_font_size: root.height * 0.046 + label_font_size: root.height * 0.0185 + + BoxLayout: + size_hint_y: 0.145 + spacing: root.height * 0.020 + DataField: + size_hint_x: 0.40 + label_text: "NATIONALITY / NATIONALITE" + value_text: (root.mrz.nationality_name.upper() if root.mrz else "") + value_font_size: root.height * 0.031 + label_font_size: root.height * 0.0185 + DataField: + size_hint_x: 0.42 + label_text: "DATE OF BIRTH" + value_text: root.record.full_date_of_birth if root.record else "" + check: root.check_state("date_of_birth") if root.mrz else "none" + value_font_size: root.height * 0.031 + label_font_size: root.height * 0.0185 + DataField: + size_hint_x: 0.18 + label_text: "SEX / SEXE" + value_text: (root.mrz.sex_label if root.mrz else "") + value_font_size: root.height * 0.031 + label_font_size: root.height * 0.0185 + + BoxLayout: + size_hint_y: 0.145 + spacing: root.height * 0.020 + DataField: + size_hint_x: 0.56 + label_text: "PLACE OF BIRTH / LIEU DE NAISSANCE" + value_text: (root.record.place_of_birth or "-") if root.record else "" + dim: not (root.record and root.record.place_of_birth) or root.record.is_missing(root.record.place_of_birth) + value_font_size: root.height * 0.031 + label_font_size: root.height * 0.0185 + DataField: + size_hint_x: 0.44 + label_text: ("PERSONAL No. (FROM MRZ)" if (root.record and root.record.personal_number_source == "MRZ") else "PERSONAL No. / No. PERSONNEL") + value_text: (root.record.personal_number or "-") if root.record else "" + dim: not (root.record and root.record.personal_number) or root.record.is_missing(root.record.personal_number) + value_font_size: root.height * 0.031 + label_font_size: root.height * 0.0185 + + BoxLayout: + size_hint_y: 0.145 + spacing: root.height * 0.020 + DataField: + size_hint_x: 0.30 + label_text: "DATE OF ISSUE" + value_text: (root.record.date_of_issue or "-") if root.record else "" + dim: not (root.record and root.record.date_of_issue) or root.record.is_missing(root.record.date_of_issue) + value_font_size: root.height * 0.028 + label_font_size: root.height * 0.0185 + DataField: + size_hint_x: 0.40 + label_text: "AUTHORITY / AUTORITE" + value_text: (root.record.issuing_authority or "-") if root.record else "" + dim: not (root.record and root.record.issuing_authority) or root.record.is_missing(root.record.issuing_authority) + value_font_size: root.height * 0.025 + label_font_size: root.height * 0.0185 + DataField: + size_hint_x: 0.30 + label_text: "DATE OF EXPIRY" + value_text: (root.mrz.expiry_text if root.mrz else "") + check: root.check_state("date_of_expiry") if root.mrz else "none" + value_font_size: root.height * 0.028 + label_font_size: root.height * 0.0185 + + # ---- MRZ strip --------------------------------------------------- + MrzStrip: + lines: root.mrz.lines if root.mrz else [] + size_hint_y: None + height: root.height * root.band_fraction diff --git a/tools/ePassport/epassport/ui/passport.py b/tools/ePassport/epassport/ui/passport.py new file mode 100644 index 000000000..4f2bf5f5f --- /dev/null +++ b/tools/ePassport/epassport/ui/passport.py @@ -0,0 +1,219 @@ +"""The passport data page: the widget the whole app exists to draw. + +It binds only to a :class:`PassportRecord`, so "read from card" and "open a +saved dump" render through exactly the same code. +""" + +from __future__ import annotations + +from kivy.properties import ( + ListProperty, + NumericProperty, + ObjectProperty, + OptionProperty, +) +from kivy.uix.floatlayout import FloatLayout +from kivy.uix.scatter import Scatter +from kivy.uix.widget import Widget + +from ..emrtd.model import PassportRecord +from . import theme + +#: The page is laid out once at this resolution and then scaled. Nothing on +#: it is interactive, so scaling a finished plate is both faster and steadier +#: than re-flowing every label each time the window moves a pixel. +PX_PER_MM = 8.0 + + +class PagePlate(Scatter): + """Holds the page at a fixed size and draws it scaled. + + A Scatter applies a matrix, so its children keep their own geometry: the + text does not re-render, the security print does not regenerate, and a + resize costs a matrix multiply instead of a full re-layout. + """ + + def __init__(self, **kwargs) -> None: + kwargs.setdefault("do_rotation", False) + kwargs.setdefault("do_scale", False) + kwargs.setdefault("do_translation", False) + kwargs.setdefault("auto_bring_to_front", False) + # The plate keeps a fixed size; without this the enclosing FloatLayout + # stretches it to fill, and fights every size we set. + kwargs.setdefault("size_hint", (None, None)) + super().__init__(**kwargs) + + def on_touch_down(self, touch): # the page is display-only + return False + + +#: How the page is scaled into the available area. +#: +#: A card's MRZ takes 2.97% of its width per character; a passport's takes +#: 2.03%. So scaling both documents to the same screen width necessarily +#: makes the card's MRZ half again as large, and making the MRZ match +#: necessarily means drawing the card smaller. You can have one or the other, +#: which is why this is a setting rather than a decision. +FIT_TO_WINDOW = "fit" # fill the area; MRZ print differs between formats +TRUE_SCALE = "true" # one mm scale; MRZ print identical, small doc stays small + +SCALE_MODES = (FIT_TO_WINDOW, TRUE_SCALE) + + +def page_scale( + mode: str, + area: tuple[float, float], + page_px: tuple[float, float], + reference_px: tuple[float, float], +) -> float: + """Scale factor for a page of ``page_px`` inside ``area``. + + ``FIT_TO_WINDOW`` fills the area with whatever document is loaded. + ``TRUE_SCALE`` scales every format identically, so a card comes out as + much smaller than a data page as it really is. + """ + area_w, area_h = area + if area_w <= 0 or area_h <= 0: + return 1.0 + if mode == TRUE_SCALE: + ref_w, ref_h = reference_px + return min(area_w / ref_w, area_h / ref_h) + page_w, page_h = page_px + if page_w <= 0 or page_h <= 0: + return 1.0 + return min(area_w / page_w, area_h / page_h) + + +class AspectBox(FloatLayout): + """Scales the page plate into the available area.""" + + #: One of :data:`SCALE_MODES`. + scale_mode = OptionProperty(FIT_TO_WINDOW, options=list(SCALE_MODES)) + + def on_scale_mode(self, *_args) -> None: + self._trigger_layout() + + def do_layout(self, *args, **kwargs) -> None: + # Only scale and position here. Assigning sizes during a layout pass + # re-triggers the pass, which recurses. + ref_w, ref_h = theme.REFERENCE_PAGE_MM + for child in self.children: + w, h = self.width, self.height + if w <= 0 or h <= 0 or not child.width or not child.height: + continue + page = self._page_of(child) + page_w = page.width if page is not None else child.width + page_h = page.height if page is not None else child.height + + scale = page_scale( + self.scale_mode, + (w, h), + (page_w, page_h), + (ref_w * PX_PER_MM, ref_h * PX_PER_MM), + ) + + if abs(child.scale - scale) > 1e-6: + child.scale = scale + + # Centre the *document*, which may sit inset on a larger plate. + offset_x = page.x * scale if page is not None else 0.0 + offset_y = page.y * scale if page is not None else 0.0 + child.pos = ( + self.x + (w - page_w * scale) / 2.0 - offset_x, + self.y + (h - page_h * scale) / 2.0 - offset_y, + ) + super().do_layout(*args, **kwargs) + + @staticmethod + def _page_of(child): + if hasattr(child, "page_size_mm"): + return child + for grandchild in getattr(child, "children", ()): + if hasattr(grandchild, "page_size_mm"): + return grandchild + return None + + +class PassportPage(Widget): + """The rendered data page. Set :attr:`record` and it redraws itself.""" + + record = ObjectProperty(None, allownone=True, rebind=True) + #: Width/height of the document being shown, and the MRZ band's share of + #: its height. Both depend on the format: see ``theme.PAGE_GEOMETRY``. + page_aspect = NumericProperty(theme.PAGE_ASPECT) + #: Physical size in millimetres; the parent scales every format from this. + page_size_mm = ListProperty(list(theme.REFERENCE_PAGE_MM)) + band_fraction = NumericProperty(theme.band_fraction("TD3")) + content_fraction = NumericProperty(theme.content_fraction("TD3")) + #: Mirrors ``record.mrz``. A Kivy property so ``.kv`` can actually bind + #: to it - a plain Python @property is invisible to the binding machinery. + mrz = ObjectProperty(None, allownone=True, rebind=True) + + def __init__(self, **kwargs) -> None: + super().__init__(**kwargs) + ref_w, ref_h = theme.REFERENCE_PAGE_MM + self.size = (ref_w * PX_PER_MM, ref_h * PX_PER_MM) + self.size_hint = (None, None) + if self.record is None: + self.record = PassportRecord() + + def on_record(self, _instance, value: PassportRecord | None) -> None: + self.mrz = value.mrz if value else None + kind = self.mrz.kind if self.mrz else None + self.page_aspect = theme.page_aspect(kind) + self.page_size_mm = list(theme.page_size_mm(kind)) + self.band_fraction = theme.band_fraction(kind) + self.content_fraction = theme.content_fraction(kind) + + def on_page_size_mm(self, *_args) -> None: + """Take the new format's size and centre it on the fixed plate. + + The plate itself never changes size - resizing a Scatter from inside a + layout pass sends the whole thing into a loop - so a smaller document + simply occupies less of it. + """ + doc_w, doc_h = self.page_size_mm + ref_w, ref_h = theme.REFERENCE_PAGE_MM + size = (doc_w * PX_PER_MM, doc_h * PX_PER_MM) + if tuple(self.size) != size: + self.size = size + self.pos = ( + (ref_w * PX_PER_MM - size[0]) / 2.0, + (ref_h * PX_PER_MM - size[1]) / 2.0, + ) + # The fit depends on the document's size, so a new format has to be + # re-fitted. Without this, opening a card after a passport kept the + # passport's scale and the card sat small until something else forced + # a layout. + self.refit() + + def refit(self) -> None: + """Ask the enclosing :class:`AspectBox` to scale the page again.""" + parent = self.parent + while parent is not None: + # Only the AspectBox lays out; the plate between us is a Scatter + # and has no layout of its own. + if isinstance(parent, AspectBox): + parent._trigger_layout() + return + parent = parent.parent + + # -- helpers used by passport.kv -------------------------------------- + def check_state(self, name: str) -> str: + """'ok' / 'bad' / 'none' for one MRZ field, for the little badge.""" + m = self.mrz + if m is None: + return "none" + field = getattr(m, name, None) + if field is None or getattr(field, "ok", None) is None: + return "none" + return "ok" if field.ok else "bad" + + def value(self, name: str, default: str = "") -> str: + m = self.mrz + if m is None: + return default + got = getattr(m, name, None) + if got is None: + return default + return getattr(got, "value", got) or default diff --git a/tools/ePassport/epassport/ui/scan.kv b/tools/ePassport/epassport/ui/scan.kv new file mode 100644 index 000000000..9d00967ac --- /dev/null +++ b/tools/ePassport/epassport/ui/scan.kv @@ -0,0 +1,154 @@ +#:import theme epassport.ui.theme +#:import GuideOverlay epassport.ui.scan.GuideOverlay + +: + BoxLayout: + orientation: "vertical" + padding: dp(16) + spacing: dp(10) + + BoxLayout: + size_hint_y: None + height: dp(32) + spacing: dp(10) + + Label: + text: "Scan the MRZ" + font_name: theme.FONT_LABEL_BOLD + font_size: sp(18) + color: app.palette["accent"] + halign: "left" + valign: "middle" + text_size: self.size + + # 0 cameras: say so. 1..n: offer the dropdown. + Label: + text: "No camera detected" + font_name: theme.FONT_LABEL_BOLD + font_size: sp(12) + color: theme.WARN + size_hint_x: None + width: dp(0) if root.has_cameras else dp(180) + opacity: 0 if root.has_cameras else 1 + halign: "right" + valign: "middle" + text_size: self.size + + Label: + text: "CAMERA" + font_name: theme.FONT_LABEL_BOLD + font_size: sp(11) + color: app.palette["text_dim"] + size_hint_x: None + width: dp(60) if root.has_cameras else dp(0) + opacity: 1 if root.has_cameras else 0 + halign: "right" + valign: "middle" + text_size: self.size + + Spinner: + id: camera_picker + text: root.camera_label + values: root.camera_choices + disabled: not root.has_cameras + size_hint_x: None + width: dp(280) if root.has_cameras else dp(0) + opacity: 1 if root.has_cameras else 0 + font_name: theme.FONT_LABEL + font_size: sp(12) + sync_height: True + on_text: root.select_camera(self.text) + + Button: + text: "Rescan" if root.has_cameras else "Rescan for devices" + size_hint_x: None + width: dp(90) if root.has_cameras else dp(160) + font_name: theme.FONT_LABEL + font_size: sp(12) + on_release: root.refresh_cameras(probe=True) + + FloatLayout: + canvas.before: + Color: + rgba: app.palette["log_bg"] + Rectangle: + pos: self.pos + size: self.size + canvas.after: + Color: + rgba: theme.OK[0], theme.OK[1], theme.OK[2], (0.30 if root.accepted else 0) + Rectangle: + pos: self.pos + size: self.size + Image: + id: preview + fit_mode: "contain" + pos_hint: {"x": 0, "y": 0} + size_hint: 1, 1 + # An Image with no texture draws an untextured quad, which is + # a solid white panel. Keep it hidden until a frame arrives. + opacity: 1 if self.texture else 0 + + Label: + text: ("No camera detected on this machine." if not root.has_cameras else "Starting camera\u2026") + font_name: theme.FONT_LABEL + font_size: sp(14) + color: app.palette["text_dim"] + opacity: 0 if preview.texture else 1 + pos_hint: {"center_x": 0.5, "center_y": 0.5} + size_hint: None, None + size: self.texture_size + # The overlay covers the preview widget but draws against the + # letterboxed image inside it, computed as ONE expression so a + # position is never derived from a stale size. + GuideOverlay: + id: overlay + pos_hint: {"x": 0, "y": 0} + size_hint: 1, 1 + # Zero rect while there is no picture, so no stray box or + # scrim is drawn over an empty panel. + image_rect: + [preview.center_x - preview.norm_image_size[0] / 2.0, \ + preview.center_y - preview.norm_image_size[1] / 2.0, \ + preview.norm_image_size[0], preview.norm_image_size[1]] \ + if preview.texture else [0, 0, 0, 0] + + Label: + text: root.status + font_name: theme.FONT_LABEL_BOLD + font_size: sp(13) + color: theme.OK if root.accepted else app.palette["text"] + size_hint_y: None + height: dp(22) + halign: "left" + valign: "middle" + text_size: self.size + + Label: + text: root.detail + font_name: theme.FONT_MONO + font_size: sp(11) + color: app.palette["text_dim"] + size_hint_y: None + height: dp(34) + halign: "left" + valign: "top" + text_size: self.size + + BoxLayout: + size_hint_y: None + height: dp(40) + spacing: dp(10) + Button: + text: "Enter manually" + font_name: theme.FONT_LABEL + font_size: sp(13) + on_release: app.goto_entry() + Widget: + Button: + text: "Cancel" + font_name: theme.FONT_LABEL + font_size: sp(13) + size_hint_x: None + width: dp(120) + on_release: app.goto_entry() diff --git a/tools/ePassport/epassport/ui/scan.py b/tools/ePassport/epassport/ui/scan.py new file mode 100644 index 000000000..cc31f6e2c --- /dev/null +++ b/tools/ePassport/epassport/ui/scan.py @@ -0,0 +1,390 @@ +"""The Scan screen: live preview, guide rectangle, OCR at ~4 fps off-thread.""" + +from __future__ import annotations + +import threading +import time + +from kivy.clock import Clock +from kivy.graphics import Color, Line, Rectangle +from kivy.properties import ( + BooleanProperty, + ListProperty, + NumericProperty, + ObjectProperty, + StringProperty, +) +from kivy.uix.image import Image as KivyImage +from kivy.uix.screenmanager import Screen +from kivy.uix.widget import Widget + +from ..ocr import mrz_ocr +from ..ocr.camera import ( + CameraDevice, + CameraThread, + frame_to_texture, + list_cameras, + opencv_available, +) +from . import theme + +#: The guide rectangle as fractions of the CAMERA FRAME, roughly the MRZ +#: aspect. The overlay is drawn over the letterboxed image rather than the +#: widget, so these same fractions describe both what the user sees and what +#: :func:`mrz_ocr.crop_to_guide` cuts out. +GUIDE = (0.06, 0.60, 0.88, 0.26) + +#: Target period between OCR attempts. The loop subtracts however long the +#: last attempt took, so this paces the work instead of adding to it. +OCR_INTERVAL = 0.12 + + +class GuideOverlay(Widget): + """The framing rectangle drawn over the live preview. + + The overlay fills the same area as the preview widget, but draws against + :attr:`image_rect` - the letterboxed picture inside it. Anything else and + the box the user frames stops matching the region actually cropped, which + is the whole point of having a guide. + """ + + guide = ListProperty(list(GUIDE)) + ok = BooleanProperty(False) + #: ``(x, y, w, h)`` of the displayed image in window coordinates. Set as + #: one expression, never as separate pos/size bindings - those are applied + #: in an order that can compute a position from a stale size. + image_rect = ListProperty([0, 0, 0, 0]) + + def __init__(self, **kwargs) -> None: + super().__init__(**kwargs) + self.bind(image_rect=self._redraw, guide=self._redraw, ok=self._redraw) + + def _redraw(self, *_args) -> None: + self.canvas.after.clear() + rx, ry, rw, rh = self.image_rect + if rw < 8 or rh < 8: + return + fx, fy, fw, fh = self.guide + x = rx + fx * rw + # The guide is expressed top-down; Kivy's origin is bottom-left. + y = ry + (1.0 - fy - fh) * rh + w, h = fw * rw, fh * rh + with self.canvas.after: + self._draw_scrim(rx, ry, rw, rh, x, y, w, h) + Color(*(theme.OK if self.ok else (1, 1, 1, 0.9))) + Line(rectangle=(x, y, w, h), width=2.0) + corner = min(w, h) * 0.18 + for cx, cy, dx, dy in ( + (x, y, 1, 1), + (x + w, y, -1, 1), + (x, y + h, 1, -1), + (x + w, y + h, -1, -1), + ): + Line( + points=[cx, cy + dy * corner, cx, cy, cx + dx * corner, cy], + width=3.0, + ) + + def _draw_scrim(self, rx, ry, rw, rh, x, y, w, h) -> None: + """Dim everything outside the box, so the target area is unmistakable.""" + Color(0, 0, 0, 0.45) + Rectangle(pos=(rx, y + h), size=(rw, ry + rh - (y + h))) # above + Rectangle(pos=(rx, ry), size=(rw, y - ry)) # below + Rectangle(pos=(rx, y), size=(x - rx, h)) # left + Rectangle(pos=(x + w, y), size=(rx + rw - (x + w), h)) # right + + +class ScanScreen(Screen): + """Camera preview plus the OCR worker. Always optional.""" + + status = StringProperty("") + detail = StringProperty("") + accepted = BooleanProperty(False) + frozen = BooleanProperty(False) + camera_index = NumericProperty(0) + camera_choices = ListProperty([]) + camera_label = StringProperty("") + #: 0 means "no camera on this machine" - the Scan screen then exists only + #: to tell the user so and offer a rescan. + camera_count = NumericProperty(0) + has_cameras = BooleanProperty(False) + palette = ObjectProperty(theme.LIGHT) + + def __init__(self, **kwargs) -> None: + super().__init__(**kwargs) + self._camera: CameraThread | None = None + self._acceptor = mrz_ocr.Acceptor() + self._latest = None + self._frame_counter = 0 + self._latest_lock = threading.Lock() + self._ocr_thread: threading.Thread | None = None + #: One event per run. Re-entering the screen must not resurrect the + #: previous run's worker, which is what a single shared event did. + self._stop_ocr = threading.Event() + self._stop_ocr.set() + self._devices: list[CameraDevice] = [] + self._probe_thread: threading.Thread | None = None + #: The dropdown writes back into :attr:`camera_label`, so setting that + #: label in code would re-enter :meth:`select_camera` and restart the + #: camera mid-open. Suppress the echo instead. + self._setting_label = False + self.on_accept = None # set by the app: callable(mrz) + self.on_camera_change = None # set by the app: callable(index) + + # -- lifecycle --------------------------------------------------------- + def start(self) -> None: + if not opencv_available(): + self.status = "OpenCV is not installed" + self.detail = "pip install opencv-python-headless" + return + available, reason = mrz_ocr.tesseract_available() + if not available: + self.status = "OCR unavailable" + self.detail = reason + " - you can still type the MRZ manually." + else: + self.status = ( + "Lay the data page flat and fill the box with the two bottom lines" + ) + self.detail = "" + self.stop() # never leave a previous camera or worker running + self.refresh_cameras() # names only - probing would fight for the device + if not self._devices: + self.status = "No camera found" + self.detail = ( + "Connect a camera and press Rescan, or use Enter manually - " + "typing the MRZ works just as well." + ) + return + self.accepted = False + self.frozen = False + self._acceptor.reset() + mrz_ocr.use_private_tempdir() + self._camera = CameraThread( + index=int(self.camera_index), + on_frame=self._on_frame, + on_error=lambda msg: Clock.schedule_once( + lambda *_: self._show_error(msg), 0 + ), + ) + self._camera.start() + if available: + # One event per run: re-entering the screen must not resurrect the + # previous run's worker, which a single shared event allowed. + stop = threading.Event() + self._stop_ocr = stop + self._ocr_thread = threading.Thread( + target=self._ocr_loop, + args=(stop,), + name="ePassport-ocr", + daemon=True, + ) + self._ocr_thread.start() + + # -- device list ------------------------------------------------------- + def refresh_cameras(self, *, probe: bool = False) -> None: + """Populate the dropdown. + + Names come from sysfs without opening anything. Probing which device + actually delivers frames means opening every one of them, which fights + with the capture thread for the device - so it only happens on an + explicit Rescan, with the preview stopped first. + """ + self._apply_devices(list_cameras()) + if not probe: + return + + was_running = self._camera is not None + self.stop() + + def work() -> None: + devices = list_cameras(probe=True) + Clock.schedule_once( + lambda *_: self._probe_finished(devices, was_running), 0 + ) + + self._probe_thread = threading.Thread( + target=work, name="ePassport-camlist", daemon=True + ) + self._probe_thread.start() + + def _probe_finished(self, devices: list[CameraDevice], restart: bool) -> None: + self._apply_devices(devices) + working = [d for d in devices if d.works] + if working and self._device_for(int(self.camera_index)) not in working: + self.camera_index = working[0].index + self._set_label(working[0].label) + if callable(self.on_camera_change): + self.on_camera_change(working[0].index) + self.status = ( + f"{len(working)} working camera(s) found" + if working + else "No camera delivered a frame - check permissions" + ) + if restart: + self.start() + + def _apply_devices(self, devices: list[CameraDevice]) -> None: + # Keep any "works" verdict we already established. + known = {d.index: d.works for d in self._devices if d.works is not None} + for device in devices: + if device.works is None and device.index in known: + device.works = known[device.index] + self._devices = devices + self.camera_choices = [d.label for d in devices] + self.camera_count = len(devices) + self.has_cameras = bool(devices) + current = self._device_for(int(self.camera_index)) + if current is not None: + self._set_label(current.label) + elif self.camera_choices: + self._set_label(self.camera_choices[0]) + else: + self._set_label("") + + def _set_label(self, label: str) -> None: + """Set the dropdown's text without it echoing back as a selection.""" + if label == self.camera_label: + return + self._setting_label = True + try: + self.camera_label = label + finally: + self._setting_label = False + + def _device_for(self, index: int) -> CameraDevice | None: + for device in self._devices: + if device.index == index: + return device + return None + + def select_camera(self, label: str) -> None: + """Switch to the device the user picked and restart the preview.""" + if self._setting_label or not label: + return # our own update echoing back, not a user choice + for device in self._devices: + if device.label != label: + continue + if device.index == int(self.camera_index) and self._camera is not None: + return + self.camera_index = device.index + self.camera_label = label + if callable(self.on_camera_change): + self.on_camera_change(device.index) + self.start() + return + + def _sync_label_to_camera(self) -> None: + """Frames are arriving, so record which device actually works - and + follow along if the capture thread fell back to another index.""" + camera = self._camera + if camera is None: + return + device = self._device_for(camera.index) + if device is not None and device.works is not True: + device.works = True + self.camera_choices = [d.label for d in self._devices] + if int(self.camera_index) != camera.index: + self.camera_index = camera.index + if device is not None: + self._set_label(device.label) + if callable(self.on_camera_change): + self.on_camera_change(camera.index) + + def stop(self) -> None: + """Release the camera and the OCR worker. Idempotent.""" + self._stop_ocr.set() + mrz_ocr.clear_private_tempdir() + thread, self._ocr_thread = self._ocr_thread, None + if thread is not None and thread.is_alive(): + thread.join(timeout=2.0) + camera, self._camera = self._camera, None + if camera is not None: + camera.stop() + probe, self._probe_thread = self._probe_thread, None + if probe is not None and probe.is_alive(): + probe.join(timeout=5.0) + + def on_leave(self, *_args) -> None: + self.stop() + + # -- capture thread ---------------------------------------------------- + def _on_frame(self, frame) -> None: + if self.frozen: + return + with self._latest_lock: + self._latest = frame + self._frame_counter += 1 + Clock.schedule_once(lambda *_: self._blit(frame), 0) + + def _blit(self, frame) -> None: + if self.frozen: + return + self._sync_label_to_camera() + preview: KivyImage | None = self.ids.get("preview") + if preview is None: + return + try: + preview.texture = frame_to_texture(frame) + except Exception: + pass + + # -- OCR thread -------------------------------------------------------- + def _ocr_loop(self, stop: threading.Event) -> None: + seen = 0 + while not stop.is_set(): + started = time.monotonic() + frame = None + if not self.frozen: + with self._latest_lock: + frame = self._latest + counter = self._frame_counter + # Re-reading a frame we already processed cannot tell us + # anything new, and OCR is the most expensive thing here. + if frame is not None and counter == seen: + frame = None + else: + seen = counter + if frame is not None: + result = mrz_ocr.read_frame(frame.array, guide=GUIDE) + if stop.is_set(): + return + result = self._acceptor.offer(result) + Clock.schedule_once(lambda *_, r=result: self._on_result(r), 0) + # Pace the loop: sleep only the remainder of the interval, so a + # slow OCR pass does not have a full sleep added on top of it. + elapsed = time.monotonic() - started + if elapsed < OCR_INTERVAL: + stop.wait(OCR_INTERVAL - elapsed) + + def _on_result(self, result: mrz_ocr.OcrResult) -> None: + overlay: GuideOverlay | None = self.ids.get("overlay") + if overlay is not None: + overlay.ok = result.checks_ok + if result.mrz is not None: + self.detail = " ".join(result.lines) + self.status = result.reason or "scanning…" + if result.accepted and not self.accepted: + self._accept(result) + + def _accept(self, result: mrz_ocr.OcrResult) -> None: + """Freeze, flash green, release the camera, hand the MRZ to the app.""" + self.accepted = True + self.frozen = True + self.status = ( + "Line 2 captured - that is everything BAC needs" + if result.line2_only + else "MRZ captured" + ) + blind = result.unverifiable_characters + if blind: + self.detail = ( + "Check the document number: the MRZ check digits cannot tell " + f"{', '.join(blind)} apart from their look-alikes." + ) + self.stop() + if callable(self.on_accept): + self.on_accept(result.mrz) + + def _show_error(self, message: str) -> None: + self.status = "Camera error" + self.detail = message diff --git a/tools/ePassport/epassport/ui/tabs/__init__.py b/tools/ePassport/epassport/ui/tabs/__init__.py new file mode 100644 index 000000000..daeae2552 --- /dev/null +++ b/tools/ePassport/epassport/ui/tabs/__init__.py @@ -0,0 +1 @@ +"""The book tabs down the right edge of the passport.""" diff --git a/tools/ePassport/epassport/ui/tabs/pages.py b/tools/ePassport/epassport/ui/tabs/pages.py new file mode 100644 index 000000000..0669960c7 --- /dev/null +++ b/tools/ePassport/epassport/ui/tabs/pages.py @@ -0,0 +1,333 @@ +"""The five non-passport tabs: PERSONAL, ISSUER, SECURITY, FILES and LOG.""" + +from __future__ import annotations + +import shutil +from pathlib import Path + +from kivy.clock import Clock +from kivy.properties import ( + ListProperty, + NumericProperty, + ObjectProperty, + StringProperty, +) +from kivy.uix.behaviors import ButtonBehavior +from kivy.uix.boxlayout import BoxLayout +from kivy.uix.label import Label + +from ...emrtd.model import FileState, PassportRecord +from .. import theme +from .tabs import TabPage + + +class KeyValueRow(BoxLayout): + """One ``label: value`` line in a detail tab.""" + + key = StringProperty("") + value = StringProperty("") + palette = ObjectProperty(theme.LIGHT) + + +class DetailPage(TabPage): + """A scrolling list of key/value rows.""" + + rows = ListProperty([]) + empty_text = StringProperty("Nothing to show.") + + def set_rows(self, pairs: list[tuple[str, str]]) -> None: + self.rows = [(k, v) for k, v in pairs if v] + + def on_rows(self, *_args) -> None: + Clock.schedule_once(self._rebuild, 0) + + def _rebuild(self, *_args) -> None: + box = self.ids.get("rows_box") + if box is None: + return + box.clear_widgets() + for key, value in self.rows: + box.add_widget(KeyValueRow(key=key, value=value, palette=self.palette)) + + +class PersonalPage(DetailPage): + """EF_DG11 - additional personal details.""" + + def refresh(self) -> None: + record: PassportRecord | None = self.record + if record is None: + self.set_rows([]) + return + p = record.personal + self.set_rows( + [ + ("Full name", p.full_name), + ("Other names", ", ".join(p.other_names)), + ("Personal number", p.personal_number), + ( + "Full date of birth", + record.full_date_of_birth if p.full_date_of_birth else "", + ), + ("Place of birth", p.place_of_birth), + ("Address", p.address), + ("Telephone", p.telephone), + ("Profession", p.profession), + ("Title", p.title), + ("Personal summary", p.personal_summary), + ("Custody information", p.custody_information), + ] + ) + self.empty_text = ( + "EF_DG11 is not present on this document." + if not record.has_dg(11) + else "EF_DG11 is present but held no readable fields." + ) + + +class IssuerPage(DetailPage): + """EF_DG12 - additional document details.""" + + def refresh(self) -> None: + record: PassportRecord | None = self.record + if record is None: + self.set_rows([]) + return + d = record.document + self.set_rows( + [ + ("Issuing authority", d.issuing_authority), + ("Date of issue", record.date_of_issue), + ("Endorsements / observations", d.endorsements), + ("Tax / exit requirements", d.tax_exit_requirements), + ("Other persons", ", ".join(d.other_persons)), + ("Personalization time", d.personalization_time), + ("Personalization device", d.personalization_device), + ("LDS version", record.com.lds_version), + ("Unicode version", record.com.unicode_version), + ( + "Data groups announced", + ", ".join(f"DG{n}" for n in record.com.present_dgs), + ), + ] + ) + self.empty_text = ( + "EF_DG12 is not present on this document." + if not record.has_dg(12) + else "EF_DG12 is present but held no readable fields." + ) + + +class HashRow(BoxLayout): + """One row of the EF_SOD data-group hash table.""" + + dg = StringProperty("") + status = StringProperty("") + digest = StringProperty("") + palette = ObjectProperty(theme.LIGHT) + + @property + def status_color(self): + return { + "match": theme.OK, + "MISMATCH": theme.BAD, + }.get(self.status, theme.WARN) + + +class SecurityPage(TabPage): + """EF_SOD signer summary, the DG hash table and DG14/DG15.""" + + rows = ListProperty([]) + hashes = ListProperty([]) + headline = StringProperty("") + headline_color = ObjectProperty(theme.WARN) + + def on_rows(self, *_args) -> None: + Clock.schedule_once(self._rebuild, 0) + + def on_hashes(self, *_args) -> None: + Clock.schedule_once(self._rebuild, 0) + + def _rebuild(self, *_args) -> None: + box = self.ids.get("rows_box") + if box is None: + return + box.clear_widgets() + if self.hashes: + box.add_widget( + KeyValueRow(key="Data group hashes", value="", palette=self.palette) + ) + for dg, status, digest in self.hashes: + box.add_widget( + HashRow(dg=dg, status=status, digest=digest, palette=self.palette) + ) + box.add_widget(KeyValueRow(key="", value="", palette=self.palette)) + for key, value in self.rows: + box.add_widget(KeyValueRow(key=key, value=value, palette=self.palette)) + + def refresh(self) -> None: + record: PassportRecord | None = self.record + if record is None: + self.rows, self.hashes = [], [] + self.headline = "No document loaded." + return + sod = record.sod + if not sod.available: + self.headline = sod.message or "EF_SOD could not be inspected." + self.headline_color = theme.WARN + self.hashes = [] + else: + mismatches = sod.mismatches + unchecked = [h for h in sod.hashes if h.status == "not checked"] + if mismatches: + self.headline = f"{len(mismatches)} data group hash MISMATCH - contents do not match the signature" + self.headline_color = theme.BAD + elif not sod.hashes: + self.headline = "EF_SOD carries no data-group hash table." + self.headline_color = theme.WARN + elif unchecked: + self.headline = f"{len(sod.hashes) - len(unchecked)} of {len(sod.hashes)} data groups hash-matched" + self.headline_color = theme.WARN + else: + self.headline = f"All {len(sod.hashes)} data groups hash-matched" + self.headline_color = theme.OK + self.hashes = [(f"DG{h.dg}", h.status, h.expected) for h in sod.hashes] + + sec = record.security + self.rows = [ + (k, v) + for k, v in ( + ("Hash algorithm", sod.hash_algorithm), + ("Signature algorithm", sod.signature_algorithm), + ("LDS security object version", sod.ldsversion), + ("Signer subject", sod.signer_subject), + ("Signer issuer", sod.signer_issuer), + ("Signer serial", sod.signer_serial), + ("Certificate valid from", sod.valid_from), + ("Certificate valid to", sod.valid_to), + ("DG14 protocols", "\n".join(sec.protocols)), + ("DG15 AA public key", f"{sec.aa_algorithm} {sec.aa_key_size}".strip()), + ) + if v + ] + if not record.has_dg(14) and not record.has_dg(15): + self.rows.append(("DG14 / DG15", "not present on this document")) + # A note about the signature itself: we verify hashes, not the chain. + if sod.available: + self.rows.append( + ( + "Note", + "Hashes are checked against the dumped files. The signer certificate " + "chain is NOT validated - that needs the issuing country's CSCA.", + ) + ) + + +class FileRow(ButtonBehavior, BoxLayout): + """One row of the FILES table.""" + + name = StringProperty("") + size_text = StringProperty("") + state = StringProperty("") + selected = ObjectProperty(False) + palette = ObjectProperty(theme.LIGHT) + + @property + def state_color(self): + return { + FileState.PRESENT: theme.OK, + FileState.PROTECTED: theme.WARN, + FileState.UNREADABLE: theme.BAD, + }.get(self.state, theme.LIGHT["text_dim"]) + + +class FilesPage(TabPage): + """Every dumped file, with a hex viewer and an Export button.""" + + files = ListProperty([]) + selected_name = StringProperty("") + selected_data = ObjectProperty(b"") + status = StringProperty("") + dump_dir = StringProperty("") + + def refresh(self) -> None: + record: PassportRecord | None = self.record + if record is None: + self.files = [] + self.selected_data = b"" + return + self.dump_dir = str(record.source_dir or "") + self.files = [ + (f.name, _size_text(f), f.state, f.note) + for f in record.files + if f.state != FileState.ABSENT or f.size + ] + present = [f for f in record.files if f.state == FileState.PRESENT] + if present: + Clock.schedule_once(lambda *_: self.select(present[0].name), 0) + else: + self.selected_name = "" + self.selected_data = b"" + + def on_files(self, *_args) -> None: + Clock.schedule_once(self._rebuild, 0) + + def _rebuild(self, *_args) -> None: + box = self.ids.get("files_box") + if box is None: + return + box.clear_widgets() + for name, size_text, state, note in self.files: + row = FileRow( + name=name, + size_text=size_text, + state=state, + palette=self.palette, + selected=name == self.selected_name, + ) + row.bind(on_release=lambda widget: self.select(widget.name)) + box.add_widget(row) + + def on_selected_name(self, *_args) -> None: + for row in ( + self.ids.get("files_box").children if self.ids.get("files_box") else [] + ): + row.selected = row.name == self.selected_name + + def select(self, name: str) -> None: + record: PassportRecord | None = self.record + if record is None: + return + entry = record.file(name) + self.selected_name = name + self.selected_data = entry.data if entry else b"" + + def export_selected(self, destination: str) -> str: + """Copy the selected file elsewhere. Returns a status message.""" + record: PassportRecord | None = self.record + if record is None or not self.selected_name: + return "Nothing selected." + entry = record.file(self.selected_name) + if entry is None or entry.path is None: + return f"{self.selected_name} has no file on disk." + target = Path(destination).expanduser() / entry.path.name + try: + shutil.copy2(entry.path, target) + except OSError as exc: + return f"Export failed: {exc}" + return f"Exported to {target}" + + +def _size_text(entry) -> str: + if entry.state == FileState.PRESENT: + return f"{entry.size:,} B" + return "-" + + +class LogPage(TabPage): + """The live pm3 output. Owns no state; the app pushes lines into it.""" + + line_count = NumericProperty(0) + + +class LabelValue(Label): + """Selectable-looking value label used across the detail tabs.""" diff --git a/tools/ePassport/epassport/ui/tabs/tabs.kv b/tools/ePassport/epassport/ui/tabs/tabs.kv new file mode 100644 index 000000000..325e4c8d0 --- /dev/null +++ b/tools/ePassport/epassport/ui/tabs/tabs.kv @@ -0,0 +1,366 @@ +#:import theme epassport.ui.theme +#:import HexView epassport.ui.widgets.hexview.HexView +#:import LogPane epassport.ui.widgets.logpane.LogPane + +: + font_name: theme.FONT_LABEL_BOLD + font_size: sp(10) + color: theme.VALUE if self.active else self.palette["text_dim"] + halign: "center" + valign: "middle" + text_size: self.size + shorten: True + shorten_from: "right" + canvas.before: + # An inactive tab is tucked down a few pixels so the active one reads + # as the front page of the book. + Color: + rgba: self.palette["tab_active"] if self.active else self.palette["tab"] + RoundedRectangle: + pos: self.x, self.y + size: self.width, self.height - (0 if self.active else dp(3)) + radius: [dp(6), dp(6), 0, 0] + Color: + rgba: self.palette["border"] + Line: + rounded_rectangle: (self.x, self.y, self.width, self.height - (0 if self.active else dp(3)), dp(6)) + width: 1 + +: + orientation: "horizontal" + size_hint_y: None + height: dp(26) + spacing: dp(3) + padding: dp(2), 0, dp(2), 0 + +: + size_hint_y: None + height: max(dp(20), caption.texture_size[1], value.texture_size[1]) + dp(6) + spacing: dp(10) + padding: 0, dp(3), 0, dp(3) + # Both labels are pinned to the top of the row and sized to their own + # text. Letting one fill the row while the other did not left the caption + # riding a few pixels above its value. + Label: + id: caption + text: root.key + font_name: theme.FONT_LABEL_BOLD + font_size: sp(12) + color: root.palette["text_dim"] + size_hint: None, None + width: dp(190) + height: self.texture_size[1] + pos_hint: {"top": 1} + halign: "right" + valign: "top" + text_size: self.width, None + Label: + id: value + text: root.value + font_name: theme.FONT_LABEL + font_size: sp(13) + color: root.palette["text"] + size_hint_y: None + height: self.texture_size[1] + pos_hint: {"top": 1} + halign: "left" + valign: "top" + text_size: self.width, None + +: + orientation: "vertical" + padding: dp(12) + spacing: dp(6) + + Label: + text: root.title + font_name: theme.FONT_LABEL_BOLD + font_size: sp(16) + color: root.palette["accent"] + size_hint_y: None + height: dp(26) + halign: "left" + valign: "middle" + text_size: self.size + + Label: + text: root.empty_text + font_name: theme.FONT_LABEL + font_size: sp(13) + color: root.palette["text_dim"] + size_hint_y: None + height: dp(24) if not root.rows else 0 + opacity: 0 if root.rows else 1 + halign: "left" + valign: "middle" + text_size: self.size + + ScrollView: + do_scroll_x: False + bar_width: dp(6) + GridLayout: + cols: 1 + size_hint_y: None + height: self.minimum_height + spacing: dp(2) + id: rows_box + +: + size_hint_y: None + height: dp(20) + spacing: dp(8) + Label: + text: root.dg + font_name: theme.FONT_MONO + font_size: sp(12) + color: root.palette["text"] + size_hint_x: None + width: dp(60) + halign: "right" + valign: "middle" + text_size: self.size + Label: + text: root.status + font_name: theme.FONT_LABEL_BOLD + font_size: sp(12) + color: root.status_color + size_hint_x: None + width: dp(110) + halign: "left" + valign: "middle" + text_size: self.size + Label: + text: root.digest + font_name: theme.FONT_MONO + font_size: sp(11) + color: root.palette["text_dim"] + halign: "left" + valign: "middle" + text_size: self.size + shorten: True + shorten_from: "right" + +: + orientation: "vertical" + padding: dp(12) + spacing: dp(6) + + Label: + text: root.title + font_name: theme.FONT_LABEL_BOLD + font_size: sp(16) + color: root.palette["accent"] + size_hint_y: None + height: dp(26) + halign: "left" + valign: "middle" + text_size: self.size + + Label: + text: root.headline + font_name: theme.FONT_LABEL_BOLD + font_size: sp(14) + color: root.headline_color + size_hint_y: None + height: dp(30) + halign: "left" + valign: "middle" + text_size: self.size + + ScrollView: + do_scroll_x: False + bar_width: dp(6) + GridLayout: + cols: 1 + size_hint_y: None + height: self.minimum_height + spacing: dp(2) + id: rows_box + +: + size_hint_y: None + height: dp(22) + spacing: dp(6) + canvas.before: + Color: + rgba: (list(root.palette["accent"][:3]) + [0.16]) if root.selected else (0, 0, 0, 0) + Rectangle: + pos: self.pos + size: self.size + # Proportional columns: fixed pixel widths pushed the state column off the + # edge as soon as the window got narrow. + Label: + text: root.name + font_name: theme.FONT_MONO + font_size: sp(11) + color: root.palette["text"] + size_hint_x: 0.44 + halign: "left" + valign: "middle" + text_size: self.size + shorten: True + shorten_from: "right" + Label: + text: root.size_text + font_name: theme.FONT_MONO + font_size: sp(11) + color: root.palette["text_dim"] + size_hint_x: 0.28 + halign: "right" + valign: "middle" + text_size: self.size + Label: + text: root.state + font_name: theme.FONT_LABEL_BOLD + font_size: sp(10) + color: root.state_color + size_hint_x: 0.28 + halign: "left" + valign: "middle" + text_size: self.size + shorten: True + shorten_from: "right" + +: + orientation: "vertical" + padding: dp(12) + spacing: dp(6) + + BoxLayout: + size_hint_y: None + height: dp(26) + Label: + text: root.title + font_name: theme.FONT_LABEL_BOLD + font_size: sp(16) + color: root.palette["accent"] + halign: "left" + valign: "middle" + text_size: self.size + Label: + text: root.status + font_name: theme.FONT_LABEL + font_size: sp(12) + color: root.palette["text_dim"] + halign: "right" + valign: "middle" + text_size: self.size + + BoxLayout: + spacing: dp(12) + + BoxLayout: + orientation: "vertical" + size_hint_x: 0.44 + spacing: dp(6) + ScrollView: + do_scroll_x: False + bar_width: dp(6) + GridLayout: + cols: 1 + size_hint_y: None + height: self.minimum_height + id: files_box + BoxLayout: + size_hint_y: None + height: dp(30) + spacing: dp(8) + Button: + text: "Export…" + font_name: theme.FONT_LABEL + font_size: sp(11) + disabled: not root.selected_name + on_release: app.export_file() + Button: + text: "Open folder" + font_name: theme.FONT_LABEL + font_size: sp(11) + disabled: not root.dump_dir + on_release: app.open_dump_dir() + + HexView: + id: hexview + data: root.selected_data + title: root.selected_name + available_width: self.width + +: + orientation: "vertical" + spacing: dp(4) + Label: + text: (root.title + " " + "{:,} bytes".format(root.byte_count)) if root.title else "" + font_name: theme.FONT_LABEL_BOLD + font_size: sp(12) + color: app.palette["text_dim"] + size_hint_y: None + height: dp(20) + halign: "left" + valign: "middle" + text_size: self.size + ScrollView: + bar_width: dp(6) + canvas.before: + Color: + rgba: app.palette["log_bg"] + Rectangle: + pos: self.pos + size: self.size + Label: + text: root.text + font_name: theme.FONT_MONO + font_size: sp(11) + color: app.palette["log_text"] + padding: dp(8), dp(8) + size_hint: None, None + size: self.texture_size + halign: "left" + valign: "top" + +: + orientation: "vertical" + padding: dp(12) + spacing: dp(6) + BoxLayout: + size_hint_y: None + height: dp(26) + Label: + text: root.title + font_name: theme.FONT_LABEL_BOLD + font_size: sp(16) + color: root.palette["accent"] + halign: "left" + valign: "middle" + text_size: self.size + Button: + text: "Clear" + size_hint_x: None + width: dp(80) + font_name: theme.FONT_LABEL + font_size: sp(12) + on_release: app.clear_log() + LogPane: + id: logpane + +: + ScrollView: + id: scroller + bar_width: dp(6) + canvas.before: + Color: + rgba: app.palette["log_bg"] + Rectangle: + pos: self.pos + size: self.size + Label: + text: root.text + markup: True + font_name: theme.FONT_MONO + font_size: sp(11) + color: app.palette["log_text"] + padding: dp(10), dp(8) + size_hint_y: None + size_hint_x: 1 + height: self.texture_size[1] + text_size: self.width, None + halign: "left" + valign: "top" diff --git a/tools/ePassport/epassport/ui/tabs/tabs.py b/tools/ePassport/epassport/ui/tabs/tabs.py new file mode 100644 index 000000000..fca3e3451 --- /dev/null +++ b/tools/ePassport/epassport/ui/tabs/tabs.py @@ -0,0 +1,96 @@ +"""Book tabs plus the page-turn transition between them. + +The animation is deliberately cheap: an x-scale squeeze with a short fade, +which reads as a page flipping without any 3D machinery. +""" + +from __future__ import annotations + +from kivy.animation import Animation +from kivy.properties import ( + BooleanProperty, + ListProperty, + NumericProperty, + ObjectProperty, + StringProperty, +) +from kivy.uix.behaviors import ButtonBehavior +from kivy.uix.boxlayout import BoxLayout +from kivy.uix.floatlayout import FloatLayout +from kivy.uix.label import Label +from kivy.uix.scatter import Scatter + +from .. import theme + + +class BookTab(ButtonBehavior, Label): + """One tab in the strip above the page, shaped like a book tab.""" + + active = BooleanProperty(False) + index = NumericProperty(0) + palette = ObjectProperty(theme.LIGHT) + + +class TabStrip(BoxLayout): + """The row of tabs above the page. Fires ``on_select`` with the index.""" + + titles = ListProperty(list(theme.TAB_TITLES)) + active_index = NumericProperty(0) + palette = ObjectProperty(theme.LIGHT) + + __events__ = ("on_select",) + + def on_select(self, index: int) -> None: + """Default handler - kv binds over this.""" + + def select(self, index: int) -> None: + if index == self.active_index: + return + self.active_index = index + self.dispatch("on_select", index) + + +class PageTurn(FloatLayout): + """Swaps its single child with a short page-turn squeeze.""" + + duration = NumericProperty(0.16) + + def __init__(self, **kwargs) -> None: + super().__init__(**kwargs) + self._current = None + + def show(self, widget, *, animate: bool = True) -> None: + """Put ``widget`` on screen, turning the page if one is already there.""" + if widget is self._current: + return + old = self._current + self._current = widget + widget.size_hint = (1, 1) + widget.pos_hint = {"x": 0, "y": 0} + + if old is None or not animate: + self.clear_widgets() + self.add_widget(widget) + return + + def _swap(*_args) -> None: + self.clear_widgets() + self.add_widget(widget) + widget.opacity = 0 + Animation(opacity=1, duration=self.duration, t="out_quad").start(widget) + + old.opacity = 1 + anim = Animation(opacity=0, duration=self.duration, t="in_quad") + anim.bind(on_complete=_swap) + anim.start(old) + + +class TabPage(BoxLayout): + """Base class for the non-passport tabs: a titled panel.""" + + title = StringProperty("") + palette = ObjectProperty(theme.LIGHT) + record = ObjectProperty(None, allownone=True, rebind=True) + + def refresh(self) -> None: + """Called when a new record arrives. Subclasses override.""" diff --git a/tools/ePassport/epassport/ui/theme.py b/tools/ePassport/epassport/ui/theme.py new file mode 100644 index 000000000..1058ef672 --- /dev/null +++ b/tools/ePassport/epassport/ui/theme.py @@ -0,0 +1,172 @@ +"""Colours, fonts and metrics. + +The passport page is always paper-light; only the surrounding chrome follows +the dark-mode setting, exactly as a real book stays paper under any desk lamp. +""" + +from __future__ import annotations + +from ..config import font + +# -- the page -------------------------------------------------------------- +PAPER = (0.960, 0.945, 0.905, 1) # warm off-white +PAPER_EDGE = (0.870, 0.845, 0.790, 1) +GRAIN = (0.55, 0.50, 0.42, 0.030) +GUILLOCHE = (0.42, 0.50, 0.62, 0.15) +GUILLOCHE_WARM = (0.62, 0.48, 0.40, 0.11) + +LABEL = (0.38, 0.45, 0.55, 1) # muted blue-grey, small caps +VALUE = (0.09, 0.10, 0.14, 1) # near-black +VALUE_DIM = (0.35, 0.36, 0.42, 1) +#: The MRZ band is barely lighter than the paper, and slightly translucent so +#: the security print still shows through. A solid white panel reads as a UI +#: element pasted onto the page rather than as part of the document. +MRZ_BAND = (0.966, 0.952, 0.913, 0.88) +MRZ_RULE = (0.74, 0.71, 0.65, 1) +MRZ_TEXT = (0.07, 0.08, 0.11, 1) +RULE = (0.72, 0.70, 0.64, 1) +PORTRAIT_FRAME = (0.55, 0.53, 0.48, 1) + +OK = (0.13, 0.52, 0.28, 1) +BAD = (0.72, 0.17, 0.14, 1) +WARN = (0.78, 0.52, 0.10, 1) + +# -- the chrome ------------------------------------------------------------ +LIGHT = { + "bg": (0.878, 0.878, 0.886, 1), + "panel": (0.945, 0.945, 0.953, 1), + "text": (0.11, 0.12, 0.15, 1), + "text_dim": (0.42, 0.44, 0.48, 1), + "accent": (0.13, 0.29, 0.52, 1), + "tab": (0.815, 0.800, 0.770, 1), + "tab_active": (0.960, 0.945, 0.905, 1), + "border": (0.72, 0.72, 0.74, 1), + "log_bg": (0.14, 0.15, 0.18, 1), + "log_text": (0.80, 0.83, 0.86, 1), + "field_bg": (1, 1, 1, 1), +} + +DARK = { + "bg": (0.106, 0.114, 0.133, 1), + "panel": (0.149, 0.161, 0.188, 1), + "text": (0.88, 0.89, 0.91, 1), + "text_dim": (0.58, 0.60, 0.65, 1), + "accent": (0.42, 0.62, 0.92, 1), + "tab": (0.196, 0.212, 0.247, 1), + "tab_active": (0.960, 0.945, 0.905, 1), + "border": (0.27, 0.29, 0.34, 1), + "log_bg": (0.078, 0.086, 0.102, 1), + "log_text": (0.78, 0.81, 0.85, 1), + "field_bg": (0.196, 0.212, 0.247, 1), +} + +# -- fonts ----------------------------------------------------------------- +FONT_MRZ = font("DejaVuSansMono.ttf") +FONT_MRZ_BOLD = font("DejaVuSansMono-Bold.ttf") +FONT_VALUE = font("DejaVuSerif-Bold.ttf") +FONT_VALUE_LIGHT = font("DejaVuSerif.ttf") +FONT_LABEL = font("DejaVuSans.ttf") +FONT_LABEL_BOLD = font("DejaVuSans-Bold.ttf") +FONT_MONO = FONT_MRZ + +#: Real document geometry, in millimetres, per MRZ format. A TD1 identity +#: card is not a small passport: it is a different shape, and its three-line +#: MRZ takes a quarter of its height rather than an eighth. +#: +#: kind: (width, height, mrz band height) +PAGE_GEOMETRY: dict[str, tuple[float, float, float]] = { + "TD3": (125.0, 88.0, 11.5), # passport data page + "TD2": (125.0, 88.0, 11.5), # same booklet, two shorter lines + "TD1": (85.6, 54.0, 15.0), # ID-1 card, three lines +} + +#: Everything is drawn to one millimetre scale, chosen so this reference +#: document exactly fills the available area. A smaller document is therefore +#: drawn smaller - which is the point: an ID-1 card really is two thirds the +#: width of a passport data page, and only at true relative size do the two +#: come out with the same MRZ print size, as they do in the hand. +REFERENCE_PAGE_MM = (PAGE_GEOMETRY["TD3"][0], PAGE_GEOMETRY["TD3"][1]) + +#: Used when no document is loaded. +PAGE_ASPECT = PAGE_GEOMETRY["TD3"][0] / PAGE_GEOMETRY["TD3"][1] + + +def page_size_mm(kind: str | None) -> tuple[float, float]: + """Physical size of the document, in millimetres.""" + width, height, _band = PAGE_GEOMETRY.get(kind or "", PAGE_GEOMETRY["TD3"]) + return (width, height) + + +def content_fraction(kind: str | None) -> float: + """Share of the page height left for the portrait and the fields.""" + return ( + 1.0 + - PAGE_TOP_PAD + - PAGE_HEADER + - PAGE_GAP + - PAGE_BOTTOM_PAD + - band_fraction(kind) + ) + + +def page_aspect(kind: str | None) -> float: + """Width/height of the document, so a card is not drawn as a passport.""" + width, height, _band = PAGE_GEOMETRY.get(kind or "", PAGE_GEOMETRY["TD3"]) + return width / height + + +#: Space the window chrome takes from the page area, in pixels: horizontal +#: padding either side, and toolbar + tab strip + status bar vertically. +#: Measured from a running window; the test suite checks it still holds. +WINDOW_CHROME_PX = (12, 85) + + +def window_for_reference(width: int = 1100) -> tuple[int, int]: + """A window size whose content area matches the reference document. + + Open at any other shape and a passport is letterboxed on first run, which + reads as the app failing to use the window rather than as the document + and the window being different shapes. + """ + pad_w, chrome_h = WINDOW_CHROME_PX + return (width, round((width - pad_w) / PAGE_ASPECT + chrome_h)) + + +#: Page furniture, as fractions of the page height. Named here so the ``.kv`` +#: rule and the layout maths cannot drift apart. +PAGE_TOP_PAD = 0.050 +PAGE_HEADER = 0.080 +PAGE_GAP = 0.006 +PAGE_BOTTOM_PAD = 0.030 + +#: A passport photo is 35 x 45 mm, about 28% of the document width on both a +#: data page and a card - so the portrait is sized from the width, not from a +#: page height that now differs per format. Held a little under 28% so the +#: field labels beside it are not squeezed into truncation. +PHOTO_WIDTH_FRACTION = 0.25 +PHOTO_ASPECT = 35.0 / 45.0 +#: ...but never more than this share of the space above the MRZ band. +PHOTO_MAX_CONTENT_SHARE = 0.66 + + +def band_fraction(kind: str | None) -> float: + """The MRZ band's share of the page height, for this format.""" + _width, height, band = PAGE_GEOMETRY.get(kind or "", PAGE_GEOMETRY["TD3"]) + return band / height + + +TAB_TITLES = ("DATA PAGE", "PERSONAL", "ISSUER", "SECURITY", "FILES", "LOG") + +#: Kivy draws a popup's title bar from its own dark atlas image whatever our +#: palette says, so the title needs a colour that works against dark - in both +#: chrome themes. +POPUP_TITLE = (0.93, 0.94, 0.96, 1) + + +def palette(dark: bool) -> dict[str, tuple[float, float, float, float]]: + return DARK if dark else LIGHT + + +def small_caps(text: str) -> str: + """Data-page labels are set in caps; the font does the rest.""" + return text.upper() diff --git a/tools/ePassport/epassport/ui/widgets/__init__.py b/tools/ePassport/epassport/ui/widgets/__init__.py new file mode 100644 index 000000000..e69de29bb diff --git a/tools/ePassport/epassport/ui/widgets/binbutton.py b/tools/ePassport/epassport/ui/widgets/binbutton.py new file mode 100644 index 000000000..da2ad6cb2 --- /dev/null +++ b/tools/ePassport/epassport/ui/widgets/binbutton.py @@ -0,0 +1,108 @@ +"""A small drawn wastebasket button. + +The bundled DejaVu fonts have no U+1F5D1 WASTEBASKET, and relying on a system +emoji font would mean shipping a button that renders as tofu on some machines. +Drawing it with canvas primitives costs a few lines and always looks the same. +""" + +from __future__ import annotations + +from kivy.graphics import Color, Line, Rectangle +from kivy.properties import BooleanProperty, ListProperty, NumericProperty +from kivy.uix.behaviors import ButtonBehavior +from kivy.uix.widget import Widget + +from .. import theme + + +class BinButton(ButtonBehavior, Widget): + """A wastebasket icon that behaves like a button. + + Turns red while pressed, so an accidental brush of the mouse is visibly + different from a committed click on something destructive. + """ + + #: Icon colour when idle. + tint = ListProperty(list(theme.LIGHT["text_dim"])) + #: Colour while the button is held down. + active_tint = ListProperty(list(theme.BAD)) + disabled_tint = ListProperty([0.45, 0.45, 0.48, 0.45]) + line_width = NumericProperty(1.4) + hovered = BooleanProperty(False) + + def __init__(self, **kwargs) -> None: + super().__init__(**kwargs) + self.bind( + pos=self._redraw, + size=self._redraw, + state=self._redraw, + disabled=self._redraw, + tint=self._redraw, + ) + self._redraw() + + def _colour(self) -> list[float]: + if self.disabled: + return list(self.disabled_tint) + if self.state == "down": + return list(self.active_tint) + return list(self.tint) + + def _redraw(self, *_args) -> None: + self.canvas.clear() + w, h = self.size + if w < 8 or h < 8: + return + # Work inside a square, centred, so the icon never distorts. + side = min(w, h) * 0.72 + x = self.x + (w - side) / 2.0 + y = self.y + (h - side) / 2.0 + colour = self._colour() + + body_w = side * 0.62 + body_h = side * 0.62 + body_x = x + (side - body_w) / 2.0 + body_y = y + side * 0.06 + lid_y = body_y + body_h + side * 0.06 + + with self.canvas: + Color(*colour) + # Lid, with a handle above it. + Rectangle(pos=(x + side * 0.10, lid_y), size=(side * 0.80, side * 0.09)) + Line( + rectangle=( + x + side * 0.36, + lid_y + side * 0.11, + side * 0.28, + side * 0.10, + ), + width=self.line_width, + ) + # Body: a slight taper, drawn as four lines. + taper = side * 0.06 + Line( + points=[ + body_x, + body_y + body_h, + body_x + taper, + body_y, + body_x + body_w - taper, + body_y, + body_x + body_w, + body_y + body_h, + ], + width=self.line_width, + joint="miter", + ) + # Three ribs. + for fraction in (0.30, 0.50, 0.70): + rib_x = body_x + body_w * fraction + Line( + points=[ + rib_x, + body_y + body_h * 0.16, + rib_x, + body_y + body_h * 0.84, + ], + width=1.0, + ) diff --git a/tools/ePassport/epassport/ui/widgets/fields.kv b/tools/ePassport/epassport/ui/widgets/fields.kv new file mode 100644 index 000000000..c12595c2f --- /dev/null +++ b/tools/ePassport/epassport/ui/widgets/fields.kv @@ -0,0 +1,59 @@ +#:import theme epassport.ui.theme + +: + font_name: theme.FONT_LABEL_BOLD + font_size: sp(root.parent.label_font_size if hasattr(root.parent, "label_font_size") else 10) + color: theme.LABEL + halign: "left" + valign: "bottom" + text_size: self.width, None + size_hint_y: None + height: self.texture_size[1] + shorten: True + shorten_from: "right" + +: + font_name: theme.FONT_VALUE + color: theme.VALUE + halign: "left" + valign: "top" + text_size: self.width, None + size_hint_y: None + height: self.texture_size[1] + shorten: True + shorten_from: "right" + +: + font_name: theme.FONT_LABEL_BOLD + font_size: sp(13) + size_hint: None, None + size: dp(16), dp(16) + +: + orientation: "vertical" + spacing: dp(1) + size_hint_y: None + height: caption.height + value_row.height + dp(3) + + FieldLabel: + id: caption + text: root.label_text + font_size: sp(root.label_font_size) + letter_spacing: 1 + + BoxLayout: + id: value_row + size_hint_y: None + height: max(value.height, dp(14)) + spacing: dp(4) + + FieldValue: + id: value + text: root.value_text + font_size: sp(root.value_font_size) + color: theme.VALUE_DIM if root.dim else theme.VALUE + font_name: theme.FONT_VALUE_LIGHT if root.dim else theme.FONT_VALUE + + CheckBadge: + state: root.check + pos_hint: {"top": 1} diff --git a/tools/ePassport/epassport/ui/widgets/fields.py b/tools/ePassport/epassport/ui/widgets/fields.py new file mode 100644 index 000000000..a070b2925 --- /dev/null +++ b/tools/ePassport/epassport/ui/widgets/fields.py @@ -0,0 +1,46 @@ +"""Data-page field: a small-caps label above a heavier value, plus a check badge.""" + +from __future__ import annotations + +from kivy.properties import ( + BooleanProperty, + NumericProperty, + OptionProperty, + StringProperty, +) +from kivy.uix.boxlayout import BoxLayout +from kivy.uix.label import Label + +from .. import theme + + +class FieldLabel(Label): + """The muted blue-grey caption above a value.""" + + +class FieldValue(Label): + """The dark, heavier value itself.""" + + +class CheckBadge(Label): + """A small tick/cross for one MRZ check digit. Never blocks display.""" + + state = OptionProperty("none", options=("none", "ok", "bad")) + + def on_state(self, *_args) -> None: + self.text = {"none": "", "ok": "✓", "bad": "✗"}[self.state] + self.color = {"none": (0, 0, 0, 0), "ok": theme.OK, "bad": theme.BAD}[ + self.state + ] + + +class DataField(BoxLayout): + """One label/value pair as it appears on the data page.""" + + label_text = StringProperty("") + value_text = StringProperty("") + check = OptionProperty("none", options=("none", "ok", "bad")) + value_font_size = NumericProperty(17) + label_font_size = NumericProperty(10) + dim = BooleanProperty(False) + source_note = StringProperty("") diff --git a/tools/ePassport/epassport/ui/widgets/guilloche.py b/tools/ePassport/epassport/ui/widgets/guilloche.py new file mode 100644 index 000000000..a083a32a2 --- /dev/null +++ b/tools/ePassport/epassport/ui/widgets/guilloche.py @@ -0,0 +1,240 @@ +"""Procedural guilloche background. + +Superimposed Lissajous/spirograph line families drawn straight onto the Kivy +canvas. Nothing here is traced from a real document's security print, and the +alpha is kept low enough that text over it stays well above 4.5:1 contrast. +""" + +from __future__ import annotations + +import math + +from kivy.clock import Clock +from kivy.graphics import Color, Line, Rectangle +from kivy.properties import BooleanProperty, NumericProperty +from kivy.uix.widget import Widget + +from .. import theme + + +def clip_polyline(points: list[float], rect) -> list[list[float]]: + """Split a flat ``[x0, y0, x1, y1, ...]`` polyline against ``rect``. + + Returns the runs that lie inside, with the crossing points interpolated so + each run ends exactly on the boundary. Doing this in geometry rather than + with a stencil keeps the result identical wherever the widget is nested. + + Most of a rosette sits inside the frame, so segments with both ends inside + take a four-comparison fast path; only the ones actually crossing an edge + pay for the full clip. + """ + rx, ry, rw, rh = rect + xmax, ymax = rx + rw, ry + rh + runs: list[list[float]] = [] + current: list[float] = [] + inside_prev = None + + for index in range(0, len(points) - 2, 2): + x0, y0, x1, y1 = points[index : index + 4] + if inside_prev is None: + inside_prev = rx <= x0 <= xmax and ry <= y0 <= ymax + inside_next = rx <= x1 <= xmax and ry <= y1 <= ymax + + if inside_prev and inside_next: + if current: + current += [x1, y1] + else: + current = [x0, y0, x1, y1] + inside_prev = inside_next + continue + + segment = _clip_segment(x0, y0, x1, y1, rect) + inside_prev = inside_next + if segment is None: + if len(current) >= 4: + runs.append(current) + current = [] + continue + cx0, cy0, cx1, cy1 = segment + if not current: + current = [cx0, cy0, cx1, cy1] + elif current[-2] == cx0 and current[-1] == cy0: + current += [cx1, cy1] + else: + # The line re-entered the rectangle somewhere else. + if len(current) >= 4: + runs.append(current) + current = [cx0, cy0, cx1, cy1] + + if len(current) >= 4: + runs.append(current) + return runs + + +def _clip_segment(x0: float, y0: float, x1: float, y1: float, rect): + """Liang-Barsky clip of one segment to ``(x, y, w, h)``. None if outside.""" + rx, ry, rw, rh = rect + xmin, xmax = rx, rx + rw + ymin, ymax = ry, ry + rh + dx, dy = x1 - x0, y1 - y0 + t0, t1 = 0.0, 1.0 + for p, q in ((-dx, x0 - xmin), (dx, xmax - x0), (-dy, y0 - ymin), (dy, ymax - y0)): + if p == 0: + if q < 0: + return None # parallel to this edge and outside it + continue + t = q / p + if p < 0: + if t > t1: + return None + t0 = max(t0, t) + else: + if t < t0: + return None + t1 = min(t1, t) + if t0 > t1: + return None + return (x0 + t0 * dx, y0 + t0 * dy, x0 + t1 * dx, y0 + t1 * dy) + + +class Guilloche(Widget): + """Paper, rosette line families and a subtle grain, in that order.""" + + #: How many line families to superimpose. Two reads as security print; + #: more turns into mush at small sizes. + families = NumericProperty(3) + detail = NumericProperty(560) + show_grain = BooleanProperty(True) + #: Height of the MRZ band at the foot of the page. The inner rule stops + #: there, because on a real document the band's own hairline closes the + #: frame - a rule running behind the band leaves a stub poking out. + bottom_inset = NumericProperty(0) + + def __init__(self, **kwargs) -> None: + super().__init__(**kwargs) + # Coalesce redraws: a resize changes pos and size separately, and + # rebuilding the security print three times per frame is what made + # dragging a window edge crawl. + self._trigger = Clock.create_trigger(self._redraw, -1) + self.bind( + pos=self._trigger, + size=self._trigger, + families=self._trigger, + bottom_inset=self._trigger, + ) + self._trigger() + + def _redraw(self, *_args) -> None: + self.canvas.before.clear() + w, h = self.size + if w < 8 or h < 8: + return + frame = self._frame_rect(w, h) + with self.canvas.before: + Color(*theme.PAPER) + Rectangle(pos=self.pos, size=self.size) + # Security print belongs inside the printed frame. The curves are + # clipped geometrically rather than with a stencil: this widget can + # sit inside another StencilView, and Kivy's nested stencils do not + # intersect, so an inner stencil silently stops clipping. + self._draw_rosettes(w, h, frame) + self._draw_border(w, h, frame) + if self.show_grain: + self._draw_grain(w, h) + + # -- line families ---------------------------------------------------- + def _draw_rosettes(self, w: float, h: float, frame) -> None: + """Rosettes: one large pale family, one tighter warm one, one corner.""" + m = min(w, h) + specs = ( + # (cx, cy, R, r, d, colour, width, turns) + ( + 0.68 * w, + 0.52 * h, + m * 0.40, + m * 0.0625, + m * 0.20, + theme.GUILLOCHE, + 1.0, + 8, + ), + ( + 0.26 * w, + 0.40 * h, + m * 0.27, + m * 0.0450, + m * 0.13, + theme.GUILLOCHE_WARM, + 0.9, + 6, + ), + ( + 0.88 * w, + 0.86 * h, + m * 0.15, + m * 0.0250, + m * 0.08, + theme.GUILLOCHE, + 0.8, + 6, + ), + ) + for cx, cy, big, small, offset, colour, width, turns in specs[ + : int(self.families) + ]: + Color(*colour) + curve = self._hypotrochoid(cx, cy, big, small, offset, turns) + # Clip in geometry, not with a stencil: this widget may sit inside + # another StencilView and Kivy's nested stencils do not intersect. + for run in clip_polyline(curve, frame): + Line(points=run, width=width) + + def _hypotrochoid( + self, cx: float, cy: float, big: float, small: float, offset: float, turns: int + ) -> list[float]: + """Classic spirograph curve, sampled densely enough to look drawn.""" + points: list[float] = [] + steps = int(self.detail) + span = turns * 2 * math.pi + ratio = (big - small) / small if small else 1.0 + for i in range(steps + 1): + t = span * i / steps + x = cx + (big - small) * math.cos(t) + offset * math.cos(ratio * t) + y = cy + (big - small) * math.sin(t) - offset * math.sin(ratio * t) + points += [self.x + x, self.y + y] + return points + + # -- paper -------------------------------------------------------------- + def _frame_rect(self, w: float, h: float) -> tuple[float, float, float, float]: + """The printed frame as ``(x, y, width, height)``. + + The rosettes are clipped to this and the inner rule is drawn on it, so + the security print and the frame can never disagree. + """ + inset = min(w, h) * 0.022 + floor = self.y + max(inset, self.bottom_inset) + top = self.y + h - inset + return (self.x + inset, floor, w - 2 * inset, max(0.0, top - floor)) + + def _draw_border(self, w: float, h: float, frame) -> None: + Color(*theme.PAPER_EDGE) + Line(rectangle=(self.x + 1, self.y + 1, w - 2, h - 2), width=1.2) + Color(*theme.RULE) + fx, fy, fw, fh = frame + # Three sides only: the MRZ band's own hairline closes the fourth, and + # a rule running on behind the band leaves a stub poking out. + Line(points=[fx, fy, fx, fy + fh, fx + fw, fy + fh, fx + fw, fy], width=0.9) + + def _draw_grain(self, w: float, h: float) -> None: + """Faint horizontal fibres - deterministic, so redraws do not shimmer.""" + Color(*theme.GRAIN) + step = max(3.0, h / 90.0) + y = 0.0 + n = 0 + while y < h: + phase = (n * 37) % 100 / 100.0 + x0 = self.x + w * 0.02 + phase * w * 0.10 + x1 = self.x + w * 0.98 - ((n * 53) % 100) / 100.0 * w * 0.10 + Line(points=[x0, self.y + y, x1, self.y + y], width=0.6) + y += step + n += 1 diff --git a/tools/ePassport/epassport/ui/widgets/hexview.py b/tools/ePassport/epassport/ui/widgets/hexview.py new file mode 100644 index 000000000..b47104a40 --- /dev/null +++ b/tools/ePassport/epassport/ui/widgets/hexview.py @@ -0,0 +1,94 @@ +"""Classic hex dump: offset, 16 bytes of hex, ASCII gutter.""" + +from __future__ import annotations + +from kivy.properties import NumericProperty, ObjectProperty, StringProperty +from kivy.uix.boxlayout import BoxLayout + +#: Beyond this the pane renders a prefix and says so - a 25 kB DG2 as one +#: Label would stall the UI thread for seconds. +MAX_BYTES = 64 * 1024 + + +def hexdump(data: bytes, *, width: int = 16, limit: int = MAX_BYTES) -> str: + """Render ``data`` as an offset/hex/ASCII dump.""" + if not data: + return "(empty)" + body = data[:limit] + rows: list[str] = [] + for offset in range(0, len(body), width): + chunk = body[offset : offset + width] + hex_part = " ".join(f"{b:02X}" for b in chunk) + gap = " " * (width - len(chunk)) + ascii_part = "".join(chr(b) if 0x20 <= b < 0x7F else "." for b in chunk) + rows.append(f"{offset:08X} {hex_part}{gap} |{ascii_part}|") + if len(data) > limit: + rows.append(f"... {len(data) - limit} more bytes not shown") + return "\n".join(rows) + + +#: Row widths to try, widest first. A hex dump must not wrap, so instead of +#: letting it overflow we fit fewer bytes per row into a narrow pane. +ROW_WIDTHS = (16, 8, 4) + + +class HexView(BoxLayout): + """Shows :attr:`data` as a hex dump that fits the pane it is given.""" + + data = ObjectProperty(b"") + title = StringProperty("") + byte_count = NumericProperty(0) + text = StringProperty("(no file selected)") + #: Width available for the dump, in pixels. Set from the ``.kv`` rule. + available_width = NumericProperty(0) + row_bytes = NumericProperty(16) + + def on_data(self, _instance, value: bytes) -> None: + self.byte_count = len(value or b"") + self._rebuild() + + def on_available_width(self, *_args) -> None: + self._rebuild() + + def _rebuild(self) -> None: + width = self.fit_row_bytes(self.available_width) + if width != self.row_bytes: + self.row_bytes = width + self.text = hexdump(self.data or b"", width=width) + + def fit_row_bytes(self, available: float) -> int: + """Largest row width whose rendered line fits in ``available`` pixels.""" + if available <= 0: + return ROW_WIDTHS[0] + for count in ROW_WIDTHS: + if measure_row_width(count) <= available: + return count + return ROW_WIDTHS[-1] + + +def sample_row(count: int) -> str: + """A worst-case row of ``count`` bytes, for measuring.""" + return ( + f"{0:08X} " + " ".join("FF" for _ in range(count)) + " |" + "W" * count + "|" + ) + + +_row_width_cache: dict[int, float] = {} + + +def measure_row_width(count: int) -> float: + """Rendered width of a ``count``-byte row, in pixels. Cached.""" + if count in _row_width_cache: + return _row_width_cache[count] + from kivy.core.text import Label as CoreLabel + from kivy.metrics import sp + + from .. import theme + + label = CoreLabel( + text=sample_row(count), font_size=sp(11), font_name=theme.FONT_MONO + ) + label.refresh() + width = float(label.texture.size[0]) + sp(20) # padding and the scrollbar + _row_width_cache[count] = width + return width diff --git a/tools/ePassport/epassport/ui/widgets/logpane.py b/tools/ePassport/epassport/ui/widgets/logpane.py new file mode 100644 index 000000000..7edaa5c89 --- /dev/null +++ b/tools/ePassport/epassport/ui/widgets/logpane.py @@ -0,0 +1,80 @@ +"""Monospace, autoscrolling log pane fed line by line from the pm3 worker.""" + +from __future__ import annotations + +from collections import deque + +from kivy.clock import Clock +from kivy.properties import BooleanProperty, NumericProperty, StringProperty +from kivy.uix.boxlayout import BoxLayout + +#: pm3 prefixes every line; colour them the way the client does. +_PREFIX_COLOURS = { + "[+]": "33cc66", + "[=]": "9aa4b2", + "[!]": "e0b341", + "[!!]": "ff6b6b", + "[-]": "ff6b6b", + "[?]": "6bb8ff", + "[#]": "9aa4b2", + "[usb]": "6bb8ff", +} + + +class LogPane(BoxLayout): + """Holds at most :attr:`max_lines` lines and autoscrolls to the newest.""" + + max_lines = NumericProperty(4000) + autoscroll = BooleanProperty(True) + text = StringProperty("") + + def __init__(self, **kwargs) -> None: + self._lines: deque[str] = deque(maxlen=int(self.max_lines)) + self._pending: list[str] = [] + self._scheduled = False + super().__init__(**kwargs) + + # -- worker-thread safe ----------------------------------------------- + def append(self, line: str) -> None: + """Queue a line. Safe to call from any thread.""" + self._pending.append(line) + if not self._scheduled: + self._scheduled = True + Clock.schedule_once(self._flush, 0) + + def _flush(self, *_args) -> None: + self._scheduled = False + if not self._pending: + return + pending, self._pending = self._pending, [] + for line in pending: + self._lines.append(_markup(line)) + self.text = "\n".join(self._lines) + if self.autoscroll and "scroller" in self.ids: + Clock.schedule_once(lambda *_: setattr(self.ids.scroller, "scroll_y", 0), 0) + + def clear(self) -> None: + self._lines.clear() + self._pending.clear() + self.text = "" + + @property + def raw_text(self) -> str: + """The log without markup, for copy/export.""" + return "\n".join(_strip_markup(line) for line in self._lines) + + +def _markup(line: str) -> str: + escaped = line.replace("&", "&").replace("[", "&bl;").replace("]", "&br;") + for prefix, colour in _PREFIX_COLOURS.items(): + token = prefix.replace("[", "&bl;").replace("]", "&br;") + if escaped.startswith(token): + return f"[color=#{colour}]{token}[/color]{escaped[len(token):]}" + return escaped + + +def _strip_markup(line: str) -> str: + import re + + out = re.sub(r"\[/?color[^\]]*\]", "", line) + return out.replace("&bl;", "[").replace("&br;", "]").replace("&", "&") diff --git a/tools/ePassport/epassport/ui/widgets/mrzstrip.py b/tools/ePassport/epassport/ui/widgets/mrzstrip.py new file mode 100644 index 000000000..2273f8375 --- /dev/null +++ b/tools/ePassport/epassport/ui/widgets/mrzstrip.py @@ -0,0 +1,162 @@ +"""The MRZ strip along the bottom of the data page. + +Rendered verbatim from EF_DG1 - this is the one place the raw ``<`` fillers +stay, because that is what is actually printed on the document. +""" + +from __future__ import annotations + +from dataclasses import dataclass + +from kivy.graphics import Color, Line, Rectangle +from kivy.properties import ListProperty, NumericProperty +from kivy.uix.widget import Widget +from kivy.clock import Clock +from kivy.core.text import Label as CoreLabel + +from .. import theme + +#: Ratio of glyph advance to font size for the bundled monospace face, and +#: the baseline-to-baseline spacing as a multiple of the font size. +CHAR_ADVANCE = 1.0 / 1.55 +#: Baseline-to-baseline as a multiple of the font size. Printed MRZ lines sit +#: close together; leaving a full line of air between them makes three lines +#: shrink until they no longer span the document. +LINE_SPACING = 1.15 + +#: Air above and below the block, as a fraction of one line. +BLOCK_PADDING = 0.25 + + +@dataclass +class RowLayout: + """How one MRZ block is placed inside its band.""" + + font_size: float + char_width: float + line_height: float + block_height: float + indent: float = 0.0 + + +def fit_rows( + rows: list[str], width: float, height: float, *, margin: float, scale: float = 1.0 +) -> RowLayout: + """Size an MRZ block so it fits the band in *both* directions. + + Fitting only the width blows a three-line TD1 clean out of the band and + over the fields above it: 30 characters stretched across the page make a + font tall enough that three lines of it no longer fit. So take the + smaller of the width-derived and height-derived sizes. + """ + row_count = max(1, len(rows)) + widest = max((len(row) for row in rows), default=1) or 1 + usable_width = max(1.0, width * (1.0 - 2 * margin)) + # Leave half a line of breathing room above and below the block. + usable_height = max(1.0, height / (row_count + BLOCK_PADDING)) + + from_width = usable_width / widest / CHAR_ADVANCE + from_height = usable_height / LINE_SPACING + font_size = max(5.0, min(from_width, from_height) * scale) + + char_width = font_size * CHAR_ADVANCE + line_height = font_size * LINE_SPACING + # Centre a block that no longer fills the width - a height-limited TD1 + # would otherwise sit hard against the left margin. + indent = max(0.0, (usable_width - char_width * widest) / 2.0) + return RowLayout( + font_size=font_size, + char_width=char_width, + line_height=line_height, + block_height=line_height * row_count, + indent=indent, + ) + + +#: Rendered glyphs, keyed by (character, font size). An MRZ is ~90 +#: characters drawn from an alphabet of 37, so without this a redraw builds +#: ninety textures to show at most thirty-seven distinct ones. +_GLYPHS: dict[tuple[str, int], object] = {} +_GLYPH_CACHE_LIMIT = 600 + + +def glyph_texture(char: str, font_size: float): + """A cached texture for one MRZ character at one size.""" + key = (char, int(round(font_size))) + texture = _GLYPHS.get(key) + if texture is None: + label = CoreLabel( + text=char, font_size=key[1], font_name=theme.FONT_MRZ, color=theme.MRZ_TEXT + ) + label.refresh() + texture = label.texture + if len(_GLYPHS) >= _GLYPH_CACHE_LIMIT: + # A resize sweeps through many sizes; do not grow without bound. + _GLYPHS.clear() + _GLYPHS[key] = texture + return texture + + +class MrzStrip(Widget): + """Monospace, letter-spaced, on a band that runs the full page width. + + On a real document the machine-readable zone is a full-bleed band at the + foot of the page, very slightly lighter than the surrounding paper, with a + hairline rule above it. It is not a boxed-in panel, so this widget draws + edge to edge and takes no horizontal inset from the page layout. + """ + + lines = ListProperty([]) + font_scale = NumericProperty(1.0) + #: Left margin as a fraction of the width, matching ICAO's print area. + margin = NumericProperty(0.055) + + def __init__(self, **kwargs) -> None: + super().__init__(**kwargs) + self._trigger = Clock.create_trigger(self._redraw, -1) + self.bind( + pos=self._trigger, + size=self._trigger, + lines=self._trigger, + font_scale=self._trigger, + margin=self._trigger, + ) + + def _redraw(self, *_args) -> None: + self.canvas.clear() + w, h = self.size + if w < 20 or h < 10: + return + rows = [line for line in self.lines if line] + with self.canvas: + Color(*theme.MRZ_BAND) + Rectangle(pos=self.pos, size=self.size) + # A hairline rule, not a border: the band has no sides or bottom. + Color(*theme.MRZ_RULE) + Line(points=[self.x, self.top, self.right, self.top], width=1.0) + if rows: + self._draw_rows(rows, w, h) + + def _draw_rows(self, rows: list[str], w: float, h: float) -> None: + """Lay the characters out on a fixed pitch, left-aligned in the band.""" + layout = fit_rows(rows, w, h, margin=self.margin, scale=self.font_scale) + left = self.x + w * self.margin + layout.indent + top = self.y + (h + layout.block_height) / 2.0 + h * 0.06 + + for index, row in enumerate(rows): + baseline = top - layout.line_height * (index + 1) + for offset, ch in enumerate(row): + if ch == " ": + continue + tex = glyph_texture(ch, layout.font_size) + Color(*theme.MRZ_TEXT) + Rectangle( + texture=tex, + pos=( + left + + offset * layout.char_width + + (layout.char_width - tex.width) / 2.0, + baseline, + ), + size=tex.size, + ) diff --git a/tools/ePassport/epassport/ui/widgets/portrait.py b/tools/ePassport/epassport/ui/widgets/portrait.py new file mode 100644 index 000000000..522acec72 --- /dev/null +++ b/tools/ePassport/epassport/ui/widgets/portrait.py @@ -0,0 +1,97 @@ +"""Portrait frame, ghost portrait and the placeholder silhouette.""" + +from __future__ import annotations + +import io + +from kivy.clock import Clock +from kivy.core.image import Image as CoreImage +from kivy.graphics import Color, Ellipse, Line, Rectangle +from kivy.properties import BooleanProperty, NumericProperty, ObjectProperty +from kivy.uix.widget import Widget + +from .. import theme + + +def texture_from_png(png: bytes): + """Kivy texture from in-memory PNG bytes, or None.""" + if not png: + return None + try: + return CoreImage(io.BytesIO(png), ext="png").texture + except Exception: + return None + + +class Portrait(Widget): + """A letterboxed portrait in a thin frame. + + ``ghost`` renders the same image at low opacity with no frame, which is + what the small repeat image on a real data page looks like. + """ + + png = ObjectProperty(b"", allownone=True) + ghost = BooleanProperty(False) + opacity_level = NumericProperty(1.0) + + def __init__(self, **kwargs) -> None: + self._texture = None + super().__init__(**kwargs) + self._trigger = Clock.create_trigger(self._redraw, -1) + self.bind( + pos=self._trigger, size=self._trigger, png=self._on_png, ghost=self._trigger + ) + self._on_png() + + def _on_png(self, *_args) -> None: + self._texture = texture_from_png(self.png or b"") + self._trigger() + + def _redraw(self, *_args) -> None: + self.canvas.clear() + w, h = self.size + if w < 4 or h < 4: + return + alpha = 0.25 if self.ghost else self.opacity_level + with self.canvas: + if self._texture is None: + # A ghost is a faint repeat of the portrait. With no image + # there is nothing to repeat, and a placeholder silhouette + # just reads as a smudge on the page. + if self.ghost: + return + self._draw_placeholder(w, h, alpha) + else: + self._draw_image(w, h, alpha) + if not self.ghost: + Color(*theme.PORTRAIT_FRAME) + Line(rectangle=(self.x, self.y, w, h), width=1.2) + + def _draw_image(self, w: float, h: float, alpha: float) -> None: + tex = self._texture + scale = min(w / tex.width, h / tex.height) + tw, th = tex.width * scale, tex.height * scale + if not self.ghost: + Color(1, 1, 1, 1) + Rectangle(pos=self.pos, size=self.size) + Color(1, 1, 1, alpha) + Rectangle( + texture=tex, + pos=(self.x + (w - tw) / 2, self.y + (h - th) / 2), + size=(tw, th), + ) + + def _draw_placeholder(self, w: float, h: float, alpha: float) -> None: + """The 'no DG2' silhouette: head and shoulders, nothing face-like.""" + Color(0.90, 0.89, 0.86, alpha) + Rectangle(pos=self.pos, size=self.size) + Color(0.68, 0.67, 0.64, alpha) + head = min(w, h) * 0.34 + Ellipse(pos=(self.x + w / 2 - head / 2, self.y + h * 0.52), size=(head, head)) + body = w * 0.78 + Ellipse( + pos=(self.x + w / 2 - body / 2, self.y + h * 0.05), + size=(body, h * 0.52), + angle_start=-90, + angle_end=90, + ) diff --git a/tools/ePassport/requirements.txt b/tools/ePassport/requirements.txt new file mode 100644 index 000000000..71a6642a7 --- /dev/null +++ b/tools/ePassport/requirements.txt @@ -0,0 +1,19 @@ +# ePassport runtime dependencies. Everything runs offline; nothing here +# phones home. Install with: python3 -m pip install -r requirements.txt +kivy>=2.3.0 + +# Optional - the app degrades gracefully when these are absent. +opencv-python-headless>=4.8 ; python_version >= "3.10" # camera capture (Scan screen) +pytesseract>=0.3.10 # MRZ OCR (needs the tesseract binary) +Pillow>=10.0 # JPEG portrait decode +glymur>=0.12 # JPEG2000 portrait decode (DG2 is usually JP2) +asn1crypto>=1.5 # EF_SOD inspection +cryptography>=41.0 # EF_SOD certificate details + +# Development only. +pytest>=7.0 +black>=23.0 + +# Generation only - not needed at runtime. Used by tools_gen_countries.py to +# bridge the proxmark3 client's ISO-3166 numeric table to MRZ alpha-3 codes. +pycountry>=23.12 diff --git a/tools/ePassport/samples/td1_utopia_idcard/EF_COM.bin b/tools/ePassport/samples/td1_utopia_idcard/EF_COM.bin new file mode 100644 index 000000000..87134f1c8 --- /dev/null +++ b/tools/ePassport/samples/td1_utopia_idcard/EF_COM.bin @@ -0,0 +1 @@ +`_0107_6040000\auc \ No newline at end of file diff --git a/tools/ePassport/samples/td1_utopia_idcard/EF_DG1.bin b/tools/ePassport/samples/td1_utopia_idcard/EF_DG1.bin new file mode 100644 index 000000000..001765a1a --- /dev/null +++ b/tools/ePassport/samples/td1_utopia_idcard/EF_DG1.bin @@ -0,0 +1 @@ +a]_ZI Path: + """Every sample dump, built into a temporary directory.""" + import tools_make_sample + + return tools_make_sample.build_all(tmp_path_factory.mktemp("samples")) + + +@pytest.fixture(scope="session") +def td3(samples: Path) -> Path: + """A TD3 passport with DG11/DG12 and a signed EF_SOD.""" + return samples / "td3_utopia" + + +@pytest.fixture(scope="session") +def td3_tampered(samples: Path) -> Path: + """The same document with DG2 replaced after signing.""" + return samples / "td3_utopia_tampered" + + +@pytest.fixture(scope="session") +def td1(samples: Path) -> Path: + """A TD1 identity card: no DG11/DG12, no EF_SOD.""" + return samples / "td1_utopia_idcard" diff --git a/tools/ePassport/tests/test_camera.py b/tools/ePassport/tests/test_camera.py new file mode 100644 index 000000000..6e300cfb6 --- /dev/null +++ b/tools/ePassport/tests/test_camera.py @@ -0,0 +1,138 @@ +"""Camera enumeration, selection, and the zero-camera path.""" + +from __future__ import annotations + +import pytest + +from epassport.ocr import camera as cam + + +def test_device_label_is_index_plus_name() -> None: + device = cam.CameraDevice(index=2, name="IPEVO Ziggi-HD Plus") + assert device.label == "2: IPEVO Ziggi-HD Plus" + + +def test_device_label_marks_a_node_that_delivers_nothing() -> None: + device = cam.CameraDevice(index=1, name="Webcam", works=False) + assert "(no frames)" in device.label + assert ( + "(no frames)" not in cam.CameraDevice(index=0, name="Webcam", works=True).label + ) + + +def test_listing_without_probe_opens_nothing(monkeypatch) -> None: + """Enumerating must not disturb a camera another process is using.""" + opened: list[int] = [] + + def boom(index): # pragma: no cover - must never run + opened.append(index) + raise AssertionError("listing must not open devices") + + monkeypatch.setattr(cam, "probe_camera", boom) + cam.list_cameras(probe=False) + assert opened == [] + + +def test_listing_sorts_working_devices_first(monkeypatch) -> None: + devices = [ + cam.CameraDevice(index=0, name="Cam", node=0), + cam.CameraDevice(index=1, name="Cam", node=1), + ] + monkeypatch.setattr(cam, "_sysfs_devices", lambda root=None: devices) + monkeypatch.setattr(cam, "opencv_available", lambda: True) + monkeypatch.setattr(cam, "probe_camera", lambda index: index == 1) + got = cam.list_cameras(probe=True) + assert got[0].index == 1 and got[0].works is True + + +def test_no_devices_at_all_yields_an_empty_list(monkeypatch) -> None: + monkeypatch.setattr(cam, "_sysfs_devices", lambda root=None: []) + monkeypatch.setattr(cam, "opencv_available", lambda: True) + monkeypatch.setattr(cam, "probe_camera", lambda index: False) + assert cam.list_cameras(probe=True, limit=3) == [] or all( + not d.works for d in cam.list_cameras(probe=True, limit=3) + ) + + +def test_sysfs_parsing_reads_names_and_skips_junk(tmp_path) -> None: + root = tmp_path / "video4linux" + for name, index, label in ( + ("video0", "0", "IPEVO Ziggi-HD Plus"), + ("video1", "1", "IPEVO Ziggi-HD Plus"), + ): + node = root / name + node.mkdir(parents=True) + (node / "name").write_text(label + "\n") + (node / "index").write_text(index + "\n") + (root / "videoX").mkdir() # not a number: must be skipped + (root / "video2").mkdir() # no name/index files: must still be listed + + devices = cam._sysfs_devices(root) + assert [d.index for d in devices] == [0, 1, 2] + assert devices[0].name == "IPEVO Ziggi-HD Plus" + assert devices[0].node == 0 and devices[1].node == 1 + assert devices[0].path == "/dev/video0" + assert devices[2].name == "" # missing file degrades, does not raise + + +def test_missing_sysfs_falls_back_to_numbered_indices(tmp_path) -> None: + devices = cam.list_cameras(limit=3, root=tmp_path / "nope") + assert [d.index for d in devices] == [0, 1, 2] + + +def test_capture_node_sorts_before_metadata_node(tmp_path) -> None: + root = tmp_path / "video4linux" + for name, node in (("video0", "1"), ("video1", "0")): + entry = root / name + entry.mkdir(parents=True) + (entry / "name").write_text("Cam") + (entry / "index").write_text(node) + devices = cam.list_cameras(root=root) + assert devices[0].index == 1, "the node with V4L2 index 0 is the capture node" + + +class _FakeScreen: + """The label/selection interplay, without importing Kivy.""" + + def __init__(self) -> None: + self.camera_label = "" + self._setting_label = False + self.selections: list[str] = [] + + def _set_label(self, label: str) -> None: + if label == self.camera_label: + return + self._setting_label = True + try: + self.camera_label = label + self.on_text(label) # the Spinner echoes every text change back + finally: + self._setting_label = False + + def on_text(self, label: str) -> None: + self.select_camera(label) + + def select_camera(self, label: str) -> None: + if self._setting_label or not label: + return + self.selections.append(label) + + +def test_setting_the_label_does_not_count_as_a_user_selection() -> None: + """The dropdown writes back, which would restart the camera mid-open.""" + screen = _FakeScreen() + screen._set_label("0: Cam") + assert screen.selections == [] + + +def test_a_real_user_selection_is_honoured() -> None: + screen = _FakeScreen() + screen._set_label("0: Cam") + screen.on_text("1: Other Cam") + assert screen.selections == ["1: Other Cam"] + + +def test_empty_selection_is_ignored() -> None: + screen = _FakeScreen() + screen.on_text("") + assert screen.selections == [] diff --git a/tools/ePassport/tests/test_config.py b/tools/ePassport/tests/test_config.py new file mode 100644 index 000000000..e297a3bec --- /dev/null +++ b/tools/ePassport/tests/test_config.py @@ -0,0 +1,63 @@ +"""Settings persistence, and the promise that BAC data is not kept by default.""" + +from __future__ import annotations + +import json +from pathlib import Path + +from epassport.config import Settings, new_dump_dir + + +def test_defaults_do_not_remember_credentials() -> None: + settings = Settings() + assert settings.remember_bac is False + assert settings.last_document_number == "" + + +def test_saving_without_remember_strips_the_bac_fields(tmp_path: Path) -> None: + path = tmp_path / "settings.json" + settings = Settings( + last_document_number="L898902C3", + last_date_of_birth="740812", + last_date_of_expiry="120415", + remember_bac=False, + ) + settings.save(path) + raw = json.loads(path.read_text()) + assert raw["last_document_number"] == "" + assert raw["last_date_of_birth"] == "" + assert raw["last_date_of_expiry"] == "" + + +def test_saving_with_remember_keeps_them(tmp_path: Path) -> None: + path = tmp_path / "settings.json" + Settings(last_document_number="L898902C3", remember_bac=True).save(path) + assert json.loads(path.read_text())["last_document_number"] == "L898902C3" + assert Settings.load(path).last_document_number == "L898902C3" + + +def test_settings_file_is_owner_only(tmp_path: Path) -> None: + path = tmp_path / "settings.json" + Settings().save(path) + assert path.stat().st_mode & 0o077 == 0 + + +def test_corrupt_settings_file_falls_back_to_defaults(tmp_path: Path) -> None: + path = tmp_path / "settings.json" + path.write_text("{ this is not json") + assert Settings.load(path).timeout_seconds == 120.0 + + +def test_unknown_keys_are_ignored(tmp_path: Path) -> None: + path = tmp_path / "settings.json" + path.write_text(json.dumps({"camera_index": 2, "from_the_future": True})) + assert Settings.load(path).camera_index == 2 + + +def test_dump_dirs_are_unique_and_owner_only(monkeypatch, tmp_path: Path) -> None: + monkeypatch.setenv("XDG_DATA_HOME", str(tmp_path)) + first = new_dump_dir() + second = new_dump_dir() + assert first != second + assert first.stat().st_mode & 0o077 == 0 + assert first.parent.stat().st_mode & 0o077 == 0 diff --git a/tools/ePassport/tests/test_dg_parse.py b/tools/ePassport/tests/test_dg_parse.py new file mode 100644 index 000000000..3690d8f82 --- /dev/null +++ b/tools/ePassport/tests/test_dg_parse.py @@ -0,0 +1,202 @@ +"""Data-group decoding, driven by the checked-in synthetic dumps.""" + +from __future__ import annotations + +from pathlib import Path + +import pytest + +from epassport.emrtd import dg +from epassport.emrtd.model import FileState +from epassport.emrtd.tlv import encode + + +@pytest.fixture(scope="session") +def record(td3: Path): + return dg.load_dump(td3) + + +# ------------------------------------------------------------- synthetic +def test_parse_com_tag_list() -> None: + com = dg.parse_com( + encode( + 0x60, + encode(0x5F01, b"0107") + + encode(0x5F36, b"040000") + + encode(0x5C, b"\x61\x75\x6b"), + ) + ) + assert com.lds_version == "01.07" + assert com.unicode_version == "04.00.00" + assert com.present_dgs == [1, 2, 11] + + +def test_parse_dg1_splits_a_td3_blob_into_two_lines() -> None: + blob = "P None: + assert dg.parse_dg1(encode(0x61, encode(0x5F1F, b"NOT AN MRZ"))) is None + assert dg.parse_dg1(b"") is None + + +def test_dg11_separator_expansion() -> None: + p = dg.parse_dg11( + encode( + 0x6B, + encode(0x5F0E, b"ERIKSSON< None: + d = dg.parse_dg12( + encode( + 0x6C, + encode(0x5F19, b"UTOPIA PASSPORT AGENCY") + encode(0x5F26, b"20200401"), + ) + ) + assert d.issuing_authority == "UTOPIA PASSPORT AGENCY" + assert d.date_of_issue == "20200401" + + +def test_extract_image_finds_jpeg_after_a_cbeff_header() -> None: + from PIL import Image + import io + + buf = io.BytesIO() + Image.new("RGB", (8, 8), (1, 2, 3)).save(buf, "JPEG") + png = dg.extract_image(b"\x7f\x61\x0a" + b"\x00" * 40 + buf.getvalue()) + assert png.startswith(b"\x89PNG") + + +def test_extract_image_on_empty_and_imageless_input() -> None: + assert dg.extract_image(b"") == b"" + assert dg.extract_image(b"\x00" * 64) == b"" + + +# ------------------------------------------------------------ real dumps +def test_full_record_from_sample_dump(record) -> None: + assert record.mrz is not None + assert record.surname == "ERIKSSON" + assert record.given_names == "ANNA MARIA" + assert record.display_name == "ANNA MARIA ERIKSSON" + assert record.mrz.all_checks_ok + assert record.warnings == [] + + +def test_portrait_and_signature_decode(record) -> None: + assert record.portrait_png.startswith(b"\x89PNG") + assert record.signature_png.startswith(b"\x89PNG") + + +def test_dg11_and_dg12_populate_the_page(record) -> None: + assert record.place_of_birth == "STOCKHOLM SWEDEN" + assert record.issuing_authority == "UTOPIA PASSPORT AGENCY" + assert record.date_of_issue == "01 APR 2020" + assert record.full_date_of_birth == "12 AUG 1974" + + +def test_dg14_and_dg15_summarised(record) -> None: + assert any("Active Authentication" in p for p in record.security.protocols) + assert record.security.aa_algorithm.startswith("RSA") + assert record.security.aa_key_size == "1024 bit" + + +def test_sod_hashes_all_match(record) -> None: + assert record.sod.available, record.sod.message + assert record.sod.hash_algorithm == "SHA-256" + assert "Utopia Document Signer 01" in record.sod.signer_subject + assert record.sod.hashes + assert all(h.status == "match" for h in record.sod.hashes) + assert record.sod.mismatches == [] + + +def test_tampered_dg2_is_flagged(td3_tampered: Path) -> None: + tampered = dg.load_dump(td3_tampered) + bad = tampered.sod.mismatches + assert [h.dg for h in bad] == [2] + # everything else still renders + assert tampered.surname == "ERIKSSON" + assert tampered.portrait_png.startswith(b"\x89PNG") + + +def test_eac_groups_are_protected_not_errors(record) -> None: + assert record.file("EF_DG3").state == FileState.PROTECTED + assert record.file("EF_DG4").state == FileState.PROTECTED + assert record.file("EF_DG1").state == FileState.PRESENT + assert record.file("EF_DG5").state == FileState.ABSENT + assert record.has_dg(2) and not record.has_dg(5) + + +def test_td1_dump_without_sod(td1: Path) -> None: + r = dg.load_dump(td1) + assert r.mrz.kind == "TD1" + assert r.portrait_png.startswith(b"\x89PNG") + assert not r.sod.available + assert "not dumped" in r.sod.message + # EF_COM announces DG3 which was not dumped: reported as protected. + assert r.file("EF_DG3").state == FileState.PROTECTED + + +def test_empty_directory_yields_a_warning(tmp_path: Path) -> None: + r = dg.load_dump(tmp_path) + assert r.mrz is None + assert any("EF_DG1 is missing" in w for w in r.warnings) + + +def test_uppercase_bin_suffix_is_accepted(tmp_path: Path, td3: Path) -> None: + (tmp_path / "EF_DG1.BIN").write_bytes((td3 / "EF_DG1.bin").read_bytes()) + r = dg.load_dump(tmp_path) + assert r.mrz is not None and r.surname == "ERIKSSON" + + +# --------------------------------------------- optional data groups absent +def test_missing_dg11_dg12_are_reported_as_not_on_chip( + tmp_path: Path, td3: Path +) -> None: + """Plenty of real passports carry no DG11/DG12 at all. + + The page must say so rather than showing an empty field, which reads as + "the app failed to parse it". + """ + for name in ("EF_COM", "EF_DG1", "EF_DG2"): + (tmp_path / f"{name}.bin").write_bytes((td3 / f"{name}.bin").read_bytes()) + r = dg.load_dump(tmp_path) + assert not r.has_dg(11) and not r.has_dg(12) + assert r.place_of_birth == r.NOT_ON_CHIP + assert r.date_of_issue == r.NOT_ON_CHIP + assert r.issuing_authority == r.NOT_ON_CHIP + assert r.is_missing(r.place_of_birth) + + +def test_personal_number_falls_back_to_the_mrz_optional_field( + tmp_path: Path, td3: Path +) -> None: + """Sweden and others put the national number in MRZ optional data.""" + for name in ("EF_COM", "EF_DG1", "EF_DG2"): + (tmp_path / f"{name}.bin").write_bytes((td3 / f"{name}.bin").read_bytes()) + r = dg.load_dump(tmp_path) + assert r.personal_number == "ZE184226B" # the specimen's optional data + assert r.personal_number_source == "MRZ" + assert not r.is_missing(r.personal_number) + + +def test_dg11_personal_number_wins_over_the_mrz(record) -> None: + assert record.personal_number == "19740812-1234" + assert record.personal_number_source == "DG11" + + +def test_present_optional_groups_are_not_marked_missing(record) -> None: + for value in ( + record.place_of_birth, + record.date_of_issue, + record.issuing_authority, + ): + assert not record.is_missing(value) diff --git a/tools/ePassport/tests/test_dialogs.py b/tools/ePassport/tests/test_dialogs.py new file mode 100644 index 000000000..dc4389183 --- /dev/null +++ b/tools/ePassport/tests/test_dialogs.py @@ -0,0 +1,167 @@ +"""Popup wiring. + +These are plain-Python checks of the parts that do not need a window, because +the bugs worth catching here are wiring mistakes, not pixels. +""" + +from __future__ import annotations + +import inspect +from pathlib import Path + +from epassport.ui import dialogs + + +def test_confirm_callback_is_not_named_with_an_on_prefix() -> None: + """Kivy binds any ``on_*`` constructor keyword as an event observer. + + Naming the callback property ``on_confirm`` meant ``ConfirmPopup( + on_confirm=fn)`` silently bound an observer and left the property None, + so confirming a deletion did nothing at all. + """ + names = [n for n in vars(dialogs.ConfirmPopup) if not n.startswith("__")] + assert "confirm_action" in names + assert not any( + n.startswith("on_") + and n not in ("on_touch_down", "on_touch_move", "on_touch_up") + for n in names + ), "a callback property must not start with on_" + + +def test_confirm_runs_the_action() -> None: + calls: list[int] = [] + popup = dialogs.ConfirmPopup.__new__(dialogs.ConfirmPopup) + popup.confirm_action = lambda: calls.append(1) + popup.dismiss = lambda *a, **k: None + dialogs.ConfirmPopup.confirm(popup) + assert calls == [1] + + +def test_confirm_without_an_action_is_harmless() -> None: + popup = dialogs.ConfirmPopup.__new__(dialogs.ConfirmPopup) + popup.confirm_action = None + popup.dismiss = lambda *a, **k: None + dialogs.ConfirmPopup.confirm(popup) # must not raise + + +def test_dump_rows_expose_both_actions() -> None: + assert "on_open" in dialogs.DumpRow.__events__ + assert "on_delete" in dialogs.DumpRow.__events__ + + +def test_deleting_asks_before_it_removes_anything() -> None: + source = inspect.getsource(dialogs.DumpsPopup.confirm_delete) + assert "ConfirmPopup" in source, "deletion must be confirmed, never immediate" + assert "cannot be undone" in source + + +# ------------------------------------------------------------- quick jumps +def test_shortcuts_offer_the_places_dumps_actually_live(monkeypatch, tmp_path) -> None: + from epassport import config + + monkeypatch.setenv("XDG_DATA_HOME", str(tmp_path)) + monkeypatch.setattr(config, "samples_dir", lambda: None) + labels = [label for label, _path in dialogs.ChooseDirPopup.shortcuts()] + assert "Dumps" in labels + assert "Home" in labels + assert "Samples" not in labels, "not offered until the samples are generated" + + +def test_samples_appear_once_generated(monkeypatch, tmp_path) -> None: + from epassport import config + + monkeypatch.setenv("XDG_DATA_HOME", str(tmp_path)) + generated = tmp_path / "samples" + generated.mkdir() + monkeypatch.setattr(config, "samples_dir", lambda: generated) + entries = dict(dialogs.ChooseDirPopup.shortcuts()) + assert entries["Samples"] == generated.resolve() + + +def test_shortcuts_are_all_real_directories(monkeypatch, tmp_path) -> None: + from epassport import config + + monkeypatch.setenv("XDG_DATA_HOME", str(tmp_path)) + monkeypatch.setattr(config, "samples_dir", lambda: tmp_path / "does-not-exist") + for label, path in dialogs.ChooseDirPopup.shortcuts(): + assert path.is_dir(), f"{label} points at {path}" + + +def test_duplicate_shortcuts_are_collapsed(monkeypatch, tmp_path) -> None: + """Launched from the project root, 'Working dir' and 'Samples' can be the + same place; offering it twice is just noise.""" + from epassport import config + + monkeypatch.setenv("XDG_DATA_HOME", str(tmp_path)) + monkeypatch.setattr(config, "samples_dir", lambda: Path.cwd()) + paths = [path for _label, path in dialogs.ChooseDirPopup.shortcuts()] + assert len(paths) == len(set(paths)) + + +def test_samples_dir_is_none_until_generated(tmp_path, monkeypatch) -> None: + from epassport import config + + monkeypatch.setattr(config, "project_root", lambda: tmp_path) + assert config.samples_dir() is None + (tmp_path / "samples").mkdir() + assert config.samples_dir() == tmp_path / "samples" + + +# --------------------------------------------------- remembering where you were +def test_the_picker_reopens_beside_the_last_dump(tmp_path, monkeypatch) -> None: + """A dump was picked *inside* some folder; offer that folder again. + + Opening the app's own dumps directory every time meant navigating back to + wherever your dumps actually live on every single trip through the picker. + """ + from epassport import config + + monkeypatch.setenv("XDG_DATA_HOME", str(tmp_path / "data")) + elsewhere = tmp_path / "captures" / "20260101T000000Z" + elsewhere.mkdir(parents=True) + assert config.browse_start(str(elsewhere)) == elsewhere.parent + + +def test_no_history_falls_back_to_the_app_dumps(tmp_path, monkeypatch) -> None: + from epassport import config + + monkeypatch.setenv("XDG_DATA_HOME", str(tmp_path)) + assert config.browse_start("") == config.dumps_dir() + + +def test_a_dump_that_has_been_deleted_falls_back(tmp_path, monkeypatch) -> None: + from epassport import config + + monkeypatch.setenv("XDG_DATA_HOME", str(tmp_path)) + gone = tmp_path / "gone" / "also-gone" + assert config.browse_start(str(gone)) == config.dumps_dir() + + +def test_a_deleted_dump_whose_parent_survives_offers_the_parent( + tmp_path, monkeypatch +) -> None: + from epassport import config + + monkeypatch.setenv("XDG_DATA_HOME", str(tmp_path / "data")) + parent = tmp_path / "captures" + parent.mkdir() + assert config.browse_start(str(parent / "removed")) == parent + + +def test_the_start_is_absolute(tmp_path, monkeypatch) -> None: + """The chooser is handed this path directly; a relative one is fragile.""" + from epassport import config + + monkeypatch.setenv("XDG_DATA_HOME", str(tmp_path / "data")) + nested = tmp_path / "rel" / "dump" + nested.mkdir(parents=True) + monkeypatch.chdir(tmp_path) + assert config.browse_start("rel/dump").is_absolute() + + +def test_recent_is_offered_as_a_shortcut() -> None: + import inspect + + source = inspect.getsource(dialogs.ChooseDirPopup.shortcuts) + assert '"Recent"' in source + assert "browse_start" in source diff --git a/tools/ePassport/tests/test_dumps.py b/tools/ePassport/tests/test_dumps.py new file mode 100644 index 000000000..7513444f9 --- /dev/null +++ b/tools/ePassport/tests/test_dumps.py @@ -0,0 +1,157 @@ +"""The dumps directory listing that answers "where did my read go?".""" + +from __future__ import annotations + +from pathlib import Path + +from epassport import config + + +def _dump(root: Path, name: str, files: int) -> Path: + directory = root / "ePassport" / "dumps" / name + directory.mkdir(parents=True) + for index in range(files): + (directory / f"EF_DG{index + 1}.bin").write_bytes(b"\x61\x02\xab\xcd") + return directory + + +def test_listing_is_newest_first(monkeypatch, tmp_path: Path) -> None: + monkeypatch.setenv("XDG_DATA_HOME", str(tmp_path)) + older = _dump(tmp_path, "20260101T000000Z", 2) + newer = _dump(tmp_path, "20260102T000000Z", 3) + import os + + os.utime(older, (1_700_000_000, 1_700_000_000)) + os.utime(newer, (1_800_000_000, 1_800_000_000)) + entries = config.list_dumps() + assert [e.name for e in entries] == [newer.name, older.name] + assert entries[0].files == 3 + + +def test_timestamp_is_rendered_readably(monkeypatch, tmp_path: Path) -> None: + monkeypatch.setenv("XDG_DATA_HOME", str(tmp_path)) + _dump(tmp_path, "20260821T194657Z", 1) + assert config.list_dumps()[0].when == "2026-08-21 19:46:57 UTC" + + +def test_a_directory_with_an_odd_name_still_lists(monkeypatch, tmp_path: Path) -> None: + monkeypatch.setenv("XDG_DATA_HOME", str(tmp_path)) + _dump(tmp_path, "handmade", 1) + assert config.list_dumps()[0].when == "handmade" + + +def test_empty_dumps_are_flagged_and_prunable(monkeypatch, tmp_path: Path) -> None: + monkeypatch.setenv("XDG_DATA_HOME", str(tmp_path)) + _dump(tmp_path, "20260101T000000Z", 0) + kept = _dump(tmp_path, "20260102T000000Z", 2) + entries = config.list_dumps() + assert sum(1 for e in entries if e.is_empty) == 1 + assert "did not complete" in [e.summary for e in entries if e.is_empty][0] + + assert config.prune_empty_dumps() == 1 + remaining = config.list_dumps() + assert [e.name for e in remaining] == [kept.name] + assert config.prune_empty_dumps() == 0 + + +def test_summary_reports_size(monkeypatch, tmp_path: Path) -> None: + monkeypatch.setenv("XDG_DATA_HOME", str(tmp_path)) + _dump(tmp_path, "20260101T000000Z", 2) + assert "2 files" in config.list_dumps()[0].summary + + +def test_no_dumps_yet(monkeypatch, tmp_path: Path) -> None: + monkeypatch.setenv("XDG_DATA_HOME", str(tmp_path)) + assert config.list_dumps() == [] + + +def test_window_size_round_trips(tmp_path: Path) -> None: + path = tmp_path / "settings.json" + settings = config.Settings(window_width=900, window_height=600) + settings.save(path) + assert config.Settings.load(path).window_width == 900 + assert config.Settings.load(path).window_height == 600 + + +# ------------------------------------------------------------ deleting one +def test_deleting_one_dump_leaves_the_others(monkeypatch, tmp_path: Path) -> None: + monkeypatch.setenv("XDG_DATA_HOME", str(tmp_path)) + doomed = _dump(tmp_path, "20260101T000000Z", 3) + kept = _dump(tmp_path, "20260102T000000Z", 2) + + import shutil + + shutil.rmtree(doomed) + assert [e.name for e in config.list_dumps()] == [kept.name] + assert not doomed.exists() + assert kept.exists() + + +def test_a_deleted_dump_takes_its_files_with_it(monkeypatch, tmp_path: Path) -> None: + monkeypatch.setenv("XDG_DATA_HOME", str(tmp_path)) + doomed = _dump(tmp_path, "20260101T000000Z", 3) + assert len(list(doomed.iterdir())) == 3 + + import shutil + + shutil.rmtree(doomed) + assert not doomed.exists() + assert config.list_dumps() == [] + + +# ---------------------------------------------------- surviving the rename +def test_a_legacy_data_directory_is_adopted(monkeypatch, tmp_path: Path) -> None: + """Dumps are not reproducible without the document in hand. + + Renaming the app must carry the old directory across, never quietly start + an empty one and orphan somebody's reads. + """ + monkeypatch.setenv("XDG_DATA_HOME", str(tmp_path)) + legacy = tmp_path / "pm3-passport" / "dumps" / "20260101T000000Z" + legacy.mkdir(parents=True) + (legacy / "EF_DG1.bin").write_bytes(b"\x61\x02\xab\xcd") + + entries = config.list_dumps() + assert [e.name for e in entries] == ["20260101T000000Z"] + assert config.data_dir() == tmp_path / config.APP_NAME + assert not (tmp_path / "pm3-passport").exists() + + +def test_an_existing_new_directory_wins_over_a_legacy_one( + monkeypatch, tmp_path: Path +) -> None: + monkeypatch.setenv("XDG_DATA_HOME", str(tmp_path)) + (tmp_path / config.APP_NAME / "dumps" / "new").mkdir(parents=True) + (tmp_path / "pm3-passport" / "dumps" / "old").mkdir(parents=True) + + assert [e.name for e in config.list_dumps()] == ["new"] + # The legacy directory is left alone rather than merged or deleted. + assert (tmp_path / "pm3-passport" / "dumps" / "old").exists() + + +def test_no_legacy_directory_is_harmless(monkeypatch, tmp_path: Path) -> None: + monkeypatch.setenv("XDG_DATA_HOME", str(tmp_path)) + assert config.list_dumps() == [] + assert config.data_dir().is_dir() + + +def test_every_test_here_redirects_the_data_directory() -> None: + """A test that forgets to redirect XDG_DATA_HOME would operate on the + user's real dumps - which hold a live portrait and MRZ and cannot be + recreated without the document.""" + import inspect + + import tests.test_dumps as module + + for name, func in vars(module).items(): + if ( + not name.startswith("test_") + or name == "test_every_test_here_redirects_the_data_directory" + ): + continue + source = inspect.getsource(func) + if any( + token in source + for token in ("config.list_dumps", "config.data_dir", "prune_empty") + ): + assert "XDG_DATA_HOME" in source, f"{name} must redirect XDG_DATA_HOME" diff --git a/tools/ePassport/tests/test_entry.py b/tools/ePassport/tests/test_entry.py new file mode 100644 index 000000000..a4055fefc --- /dev/null +++ b/tools/ePassport/tests/test_entry.py @@ -0,0 +1,156 @@ +"""Manual-entry sanitising and live validation (no GUI needed).""" + +from __future__ import annotations + +import pytest + +from epassport.ui.entry import ( + date_problem, + sanitize_date, + sanitize_docnum, + sanitize_line2, +) + + +def test_docnum_is_uppercased_filtered_and_capped() -> None: + assert sanitize_docnum("l898902c3") == "L898902C3" + assert sanitize_docnum("L8989 02C3!") == "L898902C3" + assert sanitize_docnum("1234567890123") == "123456789" + assert sanitize_docnum("ab<<") == "AB<<" + + +def test_date_is_digits_only_and_capped() -> None: + assert sanitize_date("74-08-12") == "740812" + assert sanitize_date("74081234") == "740812" + assert sanitize_date("abc") == "" + + +def test_line2_is_capped_at_44() -> None: + assert len(sanitize_line2("X" * 60)) == 44 + assert sanitize_line2("l898902c3<") == "L898902C3<" + + +@pytest.mark.parametrize( + "value,expected", + [ + ("740812", ""), + ("74081", "YYMMDD"), + ("741312", "month must be 01-12"), + ("740012", "month must be 01-12"), + ("740230", "day must be 01-29"), + ("740431", "day must be 01-30"), + ("740229", ""), # leap-safe: MRZ years are ambiguous, so 29 Feb is allowed + ], +) +def test_date_problem_messages(value: str, expected: str) -> None: + assert date_problem(value) == expected + + +# ------------------------------------------------------- the form as a whole +from epassport.pm3.client import AUTH_AUTO, AUTH_BAC, AUTH_PACE # noqa: E402 +from epassport.ui.entry import auth_hint, build_input, validate_form # noqa: E402 + +TRIPLE = dict( + document_number="L898902C3", date_of_birth="740812", date_of_expiry="120415" +) +LINE2 = "L898902C36UTO7408122F1204159ZE184226B<<<<<10" + + +def test_a_can_alone_is_enough_to_read() -> None: + """Regression: entering a CAN left the MRZ markers set, so Read stayed + disabled on a form that was perfectly valid.""" + state = validate_form(can="123456") + assert state.valid + assert state.docnum_error == "" + assert state.dob_error == "" + assert state.expiry_error == "" + assert state.can_error == "" + assert build_input(can="123456").args() == ["--can", "123456"] + + +def test_the_mrz_triple_alone_is_enough() -> None: + state = validate_form(**TRIPLE) + assert state.valid + assert state.can_error == "" + + +def test_line2_alone_is_enough() -> None: + state = validate_form(mrz_line2=LINE2) + assert state.valid + assert build_input(mrz_line2=LINE2).args() == ["-m", LINE2] + + +def test_an_untouched_form_is_invalid_but_says_nothing_alarming() -> None: + state = validate_form() + assert not state.valid + assert state.note == "" + assert state.docnum_error == "required" + + +def test_a_can_plus_mrz_is_refused_with_a_usable_message() -> None: + state = validate_form(can="123456", **TRIPLE) + assert not state.valid + assert "clear the MRZ" in state.can_error + + +def test_a_can_of_the_wrong_length_is_refused() -> None: + assert validate_form(can="1" * 15).can_error == "1-14 digits" + assert not validate_form(can="1" * 15).valid + + +def test_an_unusual_can_length_is_allowed_but_flagged() -> None: + state = validate_form(can="1234") + assert state.valid + assert "usually 6 digits" in state.note + + +def test_an_incomplete_triple_keeps_read_disabled() -> None: + state = validate_form(document_number="L898902C3", date_of_birth="740812") + assert not state.valid + assert state.expiry_error == "YYMMDD" + + +def test_a_bad_date_keeps_read_disabled() -> None: + state = validate_form(**{**TRIPLE, "date_of_birth": "741301"}) + assert not state.valid + assert "month" in state.dob_error + + +def test_a_short_line2_is_flagged() -> None: + state = validate_form(mrz_line2=LINE2[:40], **TRIPLE) + assert not state.valid + assert "40/44" in state.line2_error + + +def test_forcing_bac_with_a_can_is_refused() -> None: + state = validate_form(can="123456", mode=AUTH_BAC) + assert not state.valid + assert "PACE-only" in state.note + + +def test_forcing_pace_with_nothing_is_refused() -> None: + state = validate_form(mode=AUTH_PACE) + assert not state.valid + + +def test_the_hint_describes_the_chosen_mode() -> None: + assert "PACE is tried first" in auth_hint(AUTH_AUTO, "") + assert "Forcing BAC" in auth_hint(AUTH_BAC, "") + assert "no BAC fallback" in auth_hint(AUTH_PACE, "") + assert "Card Access Number" in auth_hint(AUTH_AUTO, "123456") + + +def test_mode_is_carried_into_the_command() -> None: + assert build_input(can="123456", mode=AUTH_PACE).args() == [ + "--can", + "123456", + "--pace", + ] + assert build_input(mode=AUTH_BAC, **TRIPLE).args()[-1] == "--bac" + assert build_input(mode=AUTH_AUTO, **TRIPLE).args()[-1] == "120415" + + +def test_the_note_explains_why_read_is_disabled() -> None: + state = validate_form(can="123456", **TRIPLE) + assert not state.valid + assert "clear the MRZ" in state.note, "the note must name the blocker" diff --git a/tools/ePassport/tests/test_guilloche.py b/tools/ePassport/tests/test_guilloche.py new file mode 100644 index 000000000..830b20dba --- /dev/null +++ b/tools/ePassport/tests/test_guilloche.py @@ -0,0 +1,153 @@ +"""The page's security print stays inside the printed frame.""" + +from __future__ import annotations + +import pytest + +from epassport.ui.widgets import guilloche + + +class _Fake: + """Just enough of a widget for the geometry helpers.""" + + def __init__(self, x: float, y: float, bottom_inset: float = 0.0) -> None: + self.x = x + self.y = y + self.bottom_inset = bottom_inset + + _frame_rect = guilloche.Guilloche._frame_rect + + +def test_frame_is_inset_from_the_paper_edge() -> None: + fx, fy, fw, fh = _Fake(0, 0)._frame_rect(700, 500) + inset = min(700, 500) * 0.022 + assert fx == pytest.approx(inset) + assert fy == pytest.approx(inset) + assert fw == pytest.approx(700 - 2 * inset) + assert fh == pytest.approx(500 - 2 * inset) + + +def test_frame_follows_the_widget_position() -> None: + fx, fy, _w, _h = _Fake(120, 40)._frame_rect(700, 500) + inset = min(700, 500) * 0.022 + assert fx == pytest.approx(120 + inset) + assert fy == pytest.approx(40 + inset) + + +def test_the_mrz_band_raises_the_frame_floor() -> None: + """The band is full-bleed, so the frame must stop above it - otherwise + the rule runs on behind the band and pokes out at the corners.""" + plain = _Fake(0, 0)._frame_rect(700, 500) + banded = _Fake(0, 0, bottom_inset=64)._frame_rect(700, 500) + assert banded[1] == pytest.approx(64) + assert banded[3] == pytest.approx(plain[1] + plain[3] - 64) + assert banded[3] < plain[3] + + +def test_a_tiny_widget_never_yields_a_negative_frame() -> None: + fx, fy, fw, fh = _Fake(0, 0, bottom_inset=500)._frame_rect(700, 500) + assert fh >= 0 + + +def test_rosettes_are_clipped_in_geometry_not_with_a_stencil() -> None: + """A stencil here silently stops working when the widget is nested. + + Kivy's StencilView is itself a stencil, and nested stencils do not + intersect - so an inner stencil around the rosettes clipped nothing at all + once the page was wrapped in one. + """ + import inspect + + source = inspect.getsource(guilloche.Guilloche._draw_rosettes) + assert "clip_polyline" in source + # No stencil *instructions* - the words may still appear in comments + # explaining why they are avoided. + module = inspect.getsource(guilloche) + for instruction in ("StencilPush(", "StencilUse(", "StencilUnUse(", "StencilPop("): + assert instruction not in module + + +def test_the_frame_rule_uses_the_same_rect_as_the_clip() -> None: + import inspect + + source = inspect.getsource(guilloche.Guilloche._redraw) + assert "_frame_rect" in source + assert "_draw_rosettes(w, h, frame)" in source + assert "_draw_border(w, h, frame)" in source + + +# ------------------------------------------------------- the clipper itself +RECT = (0.0, 0.0, 100.0, 100.0) + + +def test_a_segment_wholly_inside_is_untouched() -> None: + assert guilloche._clip_segment(10, 10, 90, 90, RECT) == (10, 10, 90, 90) + + +def test_a_segment_wholly_outside_is_dropped() -> None: + assert guilloche._clip_segment(200, 200, 300, 300, RECT) is None + assert guilloche._clip_segment(-50, -50, -10, -10, RECT) is None + + +def test_a_crossing_segment_ends_exactly_on_the_boundary() -> None: + assert guilloche._clip_segment(-50, 50, 150, 50, RECT) == (0.0, 50.0, 100.0, 50.0) + assert guilloche._clip_segment(50, -50, 50, 150, RECT) == (50.0, 0.0, 50.0, 100.0) + + +def test_a_segment_parallel_to_an_edge_and_outside_is_dropped() -> None: + assert guilloche._clip_segment(-10, 50, -5, 50, RECT) is None + assert guilloche._clip_segment(50, 200, 90, 200, RECT) is None + + +def test_a_polyline_is_split_into_runs_that_stay_inside() -> None: + # Out, in, out again: one run, ending on both boundaries. + runs = guilloche.clip_polyline([-50, 50, 50, 50, 150, 50], RECT) + assert runs == [[0.0, 50.0, 50.0, 50.0, 100.0, 50.0]] + + +def test_a_polyline_that_leaves_and_returns_yields_separate_runs() -> None: + points = [10, 10, 20, 20, 500, 500, 900, 900, 30, 30, 40, 40] + runs = guilloche.clip_polyline(points, RECT) + assert len(runs) == 2 + for run in runs: + for x, y in zip(run[0::2], run[1::2]): + assert -0.001 <= x <= 100.001 + assert -0.001 <= y <= 100.001 + + +def test_every_clipped_point_lies_within_the_rect() -> None: + import math + + points: list[float] = [] + for i in range(400): + t = i * math.tau / 60 + points += [50 + 400 * math.cos(t), 50 + 400 * math.sin(t)] + for run in guilloche.clip_polyline(points, RECT): + for x, y in zip(run[0::2], run[1::2]): + assert -0.001 <= x <= 100.001, x + assert -0.001 <= y <= 100.001, y + + +def test_a_curve_entirely_outside_produces_nothing() -> None: + points = [500, 500, 600, 600, 700, 700] + assert guilloche.clip_polyline(points, RECT) == [] + + +def test_runs_are_long_enough_to_draw() -> None: + """Kivy needs at least two points; a one-point run would raise.""" + for run in guilloche.clip_polyline([-10, 50, 5, 50, -10, 50], RECT): + assert len(run) >= 4 + assert len(run) % 2 == 0 + + +def test_an_empty_ghost_portrait_draws_nothing() -> None: + """A ghost is a faint repeat of the portrait; with no image to repeat, a + placeholder silhouette just reads as a smudge on the page.""" + import inspect + + from epassport.ui.widgets import portrait + + source = inspect.getsource(portrait.Portrait._redraw) + guard = source.index("if self.ghost:") + placeholder = source.index("_draw_placeholder") + assert guard < placeholder, "the ghost must bail out before the placeholder" diff --git a/tools/ePassport/tests/test_hexview.py b/tools/ePassport/tests/test_hexview.py new file mode 100644 index 000000000..f9da015e7 --- /dev/null +++ b/tools/ePassport/tests/test_hexview.py @@ -0,0 +1,70 @@ +"""The hex dump renderer.""" + +from __future__ import annotations + +from epassport.ui.widgets.hexview import hexdump + + +def test_layout_is_offset_hex_ascii() -> None: + line = hexdump(b"ABC").splitlines()[0] + assert line.startswith("00000000 41 42 43") + assert line.endswith("|ABC|") + + +def test_short_final_row_is_padded_so_the_ascii_gutter_lines_up() -> None: + rows = hexdump(bytes(range(20))).splitlines() + assert len(rows) == 2 + assert rows[0].index("|") == rows[1].index("|") + + +def test_non_printable_bytes_become_dots() -> None: + assert hexdump(b"\x00\x1f\x7f\x80").endswith("|....|") + + +def test_empty_input() -> None: + assert hexdump(b"") == "(empty)" + + +def test_large_input_is_truncated_with_a_note() -> None: + out = hexdump(b"\x00" * 100, limit=32) + assert "68 more bytes not shown" in out + + +# ------------------------------------------------ fitting a narrow pane +from epassport.ui.widgets import hexview # noqa: E402 + + +def test_row_width_is_configurable() -> None: + rows = hexdump(bytes(range(16)), width=8).splitlines() + assert len(rows) == 2 + assert rows[0].startswith("00000000 00 01 02 03 04 05 06 07") + assert rows[1].startswith("00000008 08 09 0A 0B 0C 0D 0E 0F") + + +def test_narrow_rows_still_line_up() -> None: + rows = hexdump(bytes(range(12)), width=8).splitlines() + assert rows[0].index("|") == rows[1].index("|") + + +def test_sample_row_is_worst_case() -> None: + row = hexview.sample_row(16) + assert row.count("FF") == 16 + assert row.endswith("|" + "W" * 16 + "|") + assert len(hexview.sample_row(8)) < len(row) + + +def test_fit_row_bytes_picks_the_widest_that_fits(monkeypatch) -> None: + widths = {16: 500.0, 8: 300.0, 4: 180.0} + monkeypatch.setattr(hexview, "measure_row_width", lambda n: widths[n]) + view = hexview.HexView.__new__(hexview.HexView) # no Kivy widget tree needed + assert view.fit_row_bytes(900) == 16 + assert view.fit_row_bytes(500) == 16 + assert view.fit_row_bytes(499) == 8 + assert view.fit_row_bytes(299) == 4 + assert view.fit_row_bytes(10) == 4 + + +def test_fit_row_bytes_before_layout_assumes_the_widest(monkeypatch) -> None: + monkeypatch.setattr(hexview, "measure_row_width", lambda n: 500.0) + view = hexview.HexView.__new__(hexview.HexView) + assert view.fit_row_bytes(0) == 16 diff --git a/tools/ePassport/tests/test_mrz.py b/tools/ePassport/tests/test_mrz.py new file mode 100644 index 000000000..29d26f1b1 --- /dev/null +++ b/tools/ePassport/tests/test_mrz.py @@ -0,0 +1,195 @@ +"""Golden ICAO 9303 vectors, plus deliberately corrupted ones.""" + +from __future__ import annotations + +import datetime as dt + +import pytest + +from epassport.emrtd import mrz + +TODAY = dt.date(2026, 8, 21) + +# ICAO 9303 part 4 specimen (Utopia). +TD3 = [ + "P None: + assert mrz.char_value("<") == 0 + assert mrz.char_value("0") == 0 + assert mrz.char_value("9") == 9 + assert mrz.char_value("A") == 10 + assert mrz.char_value("Z") == 35 + with pytest.raises(mrz.MrzError): + mrz.char_value("a") + + +@pytest.mark.parametrize( + "data,digit", + [ + ("D23145890", "7"), + ("740812", "2"), + ("120415", "9"), + ("L898902C3", "6"), + ], +) +def test_check_digit_vectors(data: str, digit: str) -> None: + assert mrz.check_digit(data) == digit + assert mrz.verify(data, digit) + + +def test_filler_check_digit_only_valid_for_empty_field() -> None: + assert mrz.verify("<<<<<<", "<") + assert not mrz.verify("ABC<<<", "<") + + +def test_td3_specimen() -> None: + m = mrz.parse(TD3, today=TODAY) + assert m.kind == "TD3" + assert m.document_code == "P" + assert m.document_type == "PASSPORT" + assert m.issuing_state == "UTO" + assert m.issuing_state_name == "Utopia" + assert m.surname == "ERIKSSON" + assert m.given_names == "ANNA MARIA" + assert m.document_number.value == "L898902C3" + assert m.nationality == "UTO" + assert m.sex == "F" + assert m.optional_data.value == "ZE184226B" + assert m.all_checks_ok + assert m.failed_checks() == [] + + +def test_td3_dates_use_the_sliding_window() -> None: + m = mrz.parse(TD3, today=TODAY) + assert m.dob == dt.date(1974, 8, 12) # not 2074 + assert m.expiry == dt.date(2012, 4, 15) # expired, but not 1912 + assert m.dob_text == "12 AUG 1974" + assert m.expiry_text == "15 APR 2012" + + +def test_expiry_in_the_near_future_stays_in_this_century() -> None: + line1 = "P None: + m = mrz.parse(TD1, today=TODAY) + assert m.kind == "TD1" + assert m.document_number.value == "D23145890" + assert m.nationality == "UTO" + assert m.surname == "ERIKSSON" + assert m.given_names == "ANNA MARIA" + assert m.dob == dt.date(1974, 8, 12) + assert m.all_checks_ok, m.failed_checks() + + +def test_td2_specimen() -> None: + m = mrz.parse(TD2, today=TODAY) + assert m.kind == "TD2" + assert m.document_number.value == "D23145890" + assert m.surname == "ERIKSSON" + assert m.all_checks_ok, m.failed_checks() + + +def test_document_number_longer_than_nine_chars() -> None: + # Number "ABC123456789" overflows into the optional-data field. + number = "ABC123456789" + head, rest = number[:9], number[9:] + line1 = "P None: + line2 = list(TD3[1]) + line2[pos] = "0" if line2[pos] != "0" else "1" + m = mrz.parse([TD3[0], "".join(line2)], today=TODAY) + assert label in m.failed_checks() + assert not m.all_checks_ok + # ...but the document still renders. + assert m.surname == "ERIKSSON" + + +def test_corrupted_payload_flags_composite_too() -> None: + line2 = TD3[1][:13] + "990101" + TD3[1][19:] + m = mrz.parse([TD3[0], line2], today=TODAY) + assert "date of birth" in m.failed_checks() + assert "composite" in m.failed_checks() + + +def test_ocr_noise_is_cleaned_before_parsing() -> None: + noisy = [ + "P«UTOERIKSSON««ANNA«MARIA«««««««««««««««« «««", + "L898902C36UTO7408122F1204159ZE184226B«««« «10", + ] + m = mrz.parse(noisy, today=TODAY) + assert m.surname == "ERIKSSON" + assert m.all_checks_ok + + +def test_bad_geometry_raises() -> None: + with pytest.raises(mrz.MrzError): + mrz.parse(["TOO SHORT"]) + with pytest.raises(mrz.MrzError): + mrz.parse([]) + + +def test_illegal_characters_raise() -> None: + with pytest.raises(mrz.MrzError): + mrz.parse(["P#UTOERIKSSON< None: + line2 = mrz.build_td3_line2( + "L898902C3", "740812", "120415", nationality="UTO", sex="F" + ) + assert len(line2) == 44 + m = mrz.parse([TD3[0], line2], today=TODAY) + assert m.all_checks_ok, m.failed_checks() + assert m.document_number.value == "L898902C3" + assert m.bac_document_number == "L898902C3" + + +def test_split_names_handles_single_and_missing_given_names() -> None: + assert mrz.split_names("ERIKSSON< None: + """A three-line TD1 used to be sized from its width alone, which made the + glyphs tall enough to overflow the band and cover the fields above.""" + layout = fit_rows(rows, BAND_W, BAND_H, margin=MARGIN) + assert layout.block_height <= BAND_H, label + + +@pytest.mark.parametrize("rows,label", [(TD3, "TD3"), (TD2, "TD2"), (TD1, "TD1")]) +def test_every_format_fits_the_width(rows: list[str], label: str) -> None: + layout = fit_rows(rows, BAND_W, BAND_H, margin=MARGIN) + usable = BAND_W * (1.0 - 2 * MARGIN) + assert layout.char_width * len(rows[0]) <= usable + 0.001, label + + +def test_a_three_line_block_is_set_smaller_than_a_two_line_one() -> None: + assert ( + fit_rows(TD1, BAND_W, BAND_H, margin=MARGIN).font_size + < fit_rows(TD3, BAND_W, BAND_H, margin=MARGIN).font_size + ) + + +def test_the_wide_format_is_limited_by_width_not_height() -> None: + """44 characters across is what constrains a passport's MRZ.""" + layout = fit_rows(TD3, BAND_W, 400.0, margin=MARGIN) + usable = BAND_W * (1.0 - 2 * MARGIN) + assert layout.char_width * 44 == pytest.approx(usable, rel=1e-6) + assert layout.indent == pytest.approx(0.0, abs=0.001) + + +def test_a_height_limited_block_is_centred_rather_than_left_hugging() -> None: + layout = fit_rows(TD1, BAND_W, 40.0, margin=MARGIN) + assert layout.indent > 0 + + +def test_geometry_is_self_consistent() -> None: + layout = fit_rows(TD3, BAND_W, BAND_H, margin=MARGIN) + assert layout.char_width == pytest.approx(layout.font_size * CHAR_ADVANCE) + assert layout.line_height == pytest.approx(layout.font_size * LINE_SPACING) + assert layout.block_height == pytest.approx(layout.line_height * 2) + + +def test_a_tiny_band_still_yields_a_usable_font() -> None: + layout = fit_rows(TD3, 40.0, 6.0, margin=MARGIN) + assert layout.font_size >= 5.0 + assert layout.char_width > 0 + + +def test_no_rows_does_not_divide_by_zero() -> None: + layout = fit_rows([], BAND_W, BAND_H, margin=MARGIN) + assert layout.font_size > 0 + assert layout.block_height > 0 + + +def test_scale_multiplies_the_result() -> None: + plain = fit_rows(TD3, BAND_W, BAND_H, margin=MARGIN) + bigger = fit_rows(TD3, BAND_W, BAND_H, margin=MARGIN, scale=2.0) + assert bigger.font_size == pytest.approx(plain.font_size * 2) + + +# ------------------------------------------------- geometry per MRZ format +from epassport.ui import theme # noqa: E402 + + +def test_a_card_is_not_shaped_like_a_passport() -> None: + """A TD1 is an ID-1 card (85.6 x 54), not a small data page (125 x 88). + + Drawing it at passport aspect with a passport-sized band is what left the + three-line MRZ unsizable in the first place. + """ + assert theme.page_aspect("TD1") > theme.page_aspect("TD3") + assert theme.page_aspect("TD1") == pytest.approx(85.6 / 54.0) + assert theme.page_aspect("TD3") == pytest.approx(125.0 / 88.0) + assert theme.page_aspect("TD2") == theme.page_aspect("TD3") + + +def test_a_three_line_band_takes_a_bigger_share_of_a_smaller_card() -> None: + assert theme.band_fraction("TD1") > 2 * theme.band_fraction("TD3") * 0.9 + assert 0.20 < theme.band_fraction("TD1") < 0.32 + assert 0.10 < theme.band_fraction("TD3") < 0.16 + + +def test_unknown_or_missing_formats_fall_back_to_the_passport() -> None: + for kind in (None, "", "TD9", "nonsense"): + assert theme.page_aspect(kind) == theme.PAGE_ASPECT + assert theme.band_fraction(kind) == theme.band_fraction("TD3") + + +@pytest.mark.parametrize("kind,rows", [("TD3", TD3), ("TD2", TD2), ("TD1", TD1)]) +def test_each_format_is_legible_in_its_own_band(kind: str, rows: list[str]) -> None: + """Lay each format out on its real page shape and band, and check the + characters come out a sensible size relative to the page.""" + page_width = 1000.0 + page_height = page_width / theme.page_aspect(kind) + band_height = page_height * theme.band_fraction(kind) + + layout = fit_rows(rows, page_width, band_height, margin=MARGIN) + assert layout.block_height <= band_height + + # Real MRZ print is roughly 2-3% of the document width per character. + share = layout.char_width / page_width + assert 0.015 < share < 0.035, f"{kind}: {share:.3f} of the width per character" + + +def test_line_spacing_lets_three_lines_span_the_document() -> None: + """Generous spacing shrank a card's MRZ until it no longer reached the + margins; it should fill most of the printable width, like real print.""" + page_width = 1000.0 + for kind, rows in (("TD3", TD3), ("TD1", TD1)): + page_height = page_width / theme.page_aspect(kind) + band = page_height * theme.band_fraction(kind) + layout = fit_rows(rows, page_width, band, margin=MARGIN) + usable = page_width * (1.0 - 2 * MARGIN) + filled = layout.char_width * len(rows[0]) / usable + assert filled > 0.90, f"{kind} fills only {filled:.0%} of the width" + + +def test_the_portrait_is_sized_from_the_width_not_the_page_height() -> None: + """Sizing it as a fraction of page height made it swallow a short card.""" + page_width = 1000.0 + shares = [] + for kind in ("TD3", "TD1"): + page_height = page_width / theme.page_aspect(kind) + content = page_height * theme.content_fraction(kind) + height = min( + page_width * theme.PHOTO_WIDTH_FRACTION / theme.PHOTO_ASPECT, + content * theme.PHOTO_MAX_CONTENT_SHARE, + ) + shares.append(height / content) + assert all(0.5 < share < 0.8 for share in shares), shares + assert abs(shares[0] - shares[1]) < 0.1, "both formats give it a similar share" + + +def test_photo_geometry_matches_a_real_id_photo() -> None: + assert theme.PHOTO_ASPECT == pytest.approx(35.0 / 45.0) + assert 0.22 < theme.PHOTO_WIDTH_FRACTION < 0.30 + + +def test_every_format_gets_the_same_mrz_print_size() -> None: + """OCR-B is a fixed 2.54 mm pitch on a card and on a data page alike. + + Drawing every format to one millimetre scale is what makes that true on + screen too: a card is smaller than a passport page, so it is drawn + smaller, and the MRZ ends up the same size in both - as in the hand. + """ + ref_w, ref_h = theme.REFERENCE_PAGE_MM + area_w, area_h = 1000.0, 700.0 + scale = min(area_w / ref_w, area_h / ref_h) + + sizes = {} + for kind, rows in (("TD3", TD3), ("TD1", TD1)): + doc_w, doc_h = theme.page_size_mm(kind) + page_w, page_h = doc_w * scale, doc_h * scale + band = page_h * theme.band_fraction(kind) + sizes[kind] = fit_rows(rows, page_w, band, margin=MARGIN).font_size + + biggest, smallest = max(sizes.values()), min(sizes.values()) + assert (biggest - smallest) / biggest < 0.05, sizes + + +def test_a_card_is_drawn_smaller_than_a_data_page() -> None: + card_w, _card_h = theme.page_size_mm("TD1") + page_w, _page_h = theme.page_size_mm("TD3") + assert card_w < page_w + assert theme.page_size_mm("TD3") == theme.REFERENCE_PAGE_MM + assert theme.page_size_mm(None) == theme.REFERENCE_PAGE_MM + + +# ------------------------------------------------------------ resize cost +def test_the_page_is_laid_out_once_and_then_scaled() -> None: + """Re-flowing the page on every resize event re-rendered every label and + regenerated the security print, which made dragging a window edge crawl + and the contents jitter. It is drawn on a fixed plate and scaled instead. + """ + import inspect + + from epassport.ui import passport + + assert passport.PX_PER_MM > 0 + plate = inspect.getsource(passport.PagePlate) + assert "Scatter" in inspect.getsource(passport) + for locked in ("do_rotation", "do_scale", "do_translation"): + assert locked in plate, f"{locked} must be pinned - the page is display-only" + + layout = inspect.getsource(passport.AspectBox.do_layout) + assert ".size =" not in layout, "assigning sizes during layout re-triggers it" + assert "scale" in layout + + +def test_the_plate_holds_a_smaller_document_centred() -> None: + """A card is smaller than the reference page, so it sits centred on it.""" + ref_w, ref_h = theme.REFERENCE_PAGE_MM + card_w, card_h = theme.page_size_mm("TD1") + assert card_w < ref_w and card_h < ref_h + from epassport.ui.passport import PX_PER_MM + + offset_x = (ref_w * PX_PER_MM - card_w * PX_PER_MM) / 2.0 + offset_y = (ref_h * PX_PER_MM - card_h * PX_PER_MM) / 2.0 + assert offset_x > 0 and offset_y > 0 diff --git a/tools/ePassport/tests/test_ocr.py b/tools/ePassport/tests/test_ocr.py new file mode 100644 index 000000000..d50f1876e --- /dev/null +++ b/tools/ePassport/tests/test_ocr.py @@ -0,0 +1,344 @@ +"""MRZ OCR post-processing and the two-frame acceptance rule.""" + +from __future__ import annotations + +import pytest + +from epassport.ocr import mrz_ocr + +GOOD = """ +some header noise +P None: + result = mrz_ocr.parse_raw(GOOD) + assert result.mrz is not None + assert result.mrz.surname == "ERIKSSON" + assert result.checks_ok + + +def test_ocr_confusions_are_repaired_before_validation() -> None: + result = mrz_ocr.parse_raw(NOISY) + assert result.checks_ok, result.reason + assert result.mrz.document_number.value == "L898902C3" + + +def test_bad_check_digit_is_reported_and_never_accepted() -> None: + acceptor = mrz_ocr.Acceptor() + for _ in range(5): + result = acceptor.offer(mrz_ocr.parse_raw(BAD_CHECK)) + assert not result.accepted + assert "check digits failed" in result.reason + + +def test_two_consecutive_agreeing_frames_are_required() -> None: + acceptor = mrz_ocr.Acceptor() + first = acceptor.offer(mrz_ocr.parse_raw(GOOD)) + assert not first.accepted + assert "1/2" in first.reason + second = acceptor.offer(mrz_ocr.parse_raw(GOOD)) + assert second.accepted + + +def test_a_disagreeing_frame_resets_the_streak() -> None: + acceptor = mrz_ocr.Acceptor() + acceptor.offer(mrz_ocr.parse_raw(GOOD)) + acceptor.offer(mrz_ocr.parse_raw(BAD_CHECK)) # a junk frame + assert not acceptor.offer(mrz_ocr.parse_raw(GOOD)).accepted # back to 1/2 + + +def test_no_mrz_length_line_is_reported_not_raised() -> None: + result = mrz_ocr.parse_raw("just some words\nand more words") + assert result.mrz is None + assert "no line of MRZ length" in result.reason + + +def test_candidate_lines_only_keeps_mrz_widths() -> None: + lines = mrz_ocr.candidate_lines("A" * 44 + "\n" + "B" * 43 + "\n" + "C" * 30) + assert [len(line) for line in lines] == [44, 30] + + +def test_tesseract_availability_reports_a_remedy() -> None: + available, reason = mrz_ocr.tesseract_available() + assert available or "install" in reason + + +cv2 = pytest.importorskip("cv2") +numpy = pytest.importorskip("numpy") + + +def test_preprocess_returns_a_binary_image() -> None: + frame = numpy.full((120, 480, 3), 220, dtype=numpy.uint8) + cv2.putText( + frame, "P None: + frame = numpy.zeros((100, 200, 3), dtype=numpy.uint8) + cropped = mrz_ocr.crop_to_guide(frame, (0.1, 0.5, 0.8, 0.4), margin=0.0) + assert cropped.shape[0] == 40 and cropped.shape[1] == 160 + + +def test_crop_to_guide_adds_a_margin_so_tilted_pages_keep_their_edges() -> None: + frame = numpy.zeros((100, 200, 3), dtype=numpy.uint8) + exact = mrz_ocr.crop_to_guide(frame, (0.1, 0.5, 0.8, 0.4), margin=0.0) + padded = mrz_ocr.crop_to_guide(frame, (0.1, 0.5, 0.8, 0.4)) + assert padded.shape[0] > exact.shape[0] + assert padded.shape[1] > exact.shape[1] + + +def test_crop_to_guide_clamps_to_the_frame() -> None: + frame = numpy.zeros((100, 200, 3), dtype=numpy.uint8) + whole = mrz_ocr.crop_to_guide(frame, (0.0, 0.0, 1.0, 1.0)) + assert whole.shape == frame.shape + # A degenerate guide falls back to the whole frame rather than crashing. + assert mrz_ocr.crop_to_guide(frame, (0.0, 0.0, 0.005, 0.005)).shape == frame.shape + + +def test_normalize_scale_lifts_a_thin_strip_and_caps_a_huge_one() -> None: + thin = numpy.zeros((40, 800, 3), dtype=numpy.uint8) + assert mrz_ocr.normalize_scale(thin).shape[0] >= mrz_ocr.MIN_STRIP_HEIGHT + huge = numpy.zeros((900, 3000, 3), dtype=numpy.uint8) + assert mrz_ocr.normalize_scale(huge).shape[0] <= mrz_ocr.MAX_STRIP_HEIGHT + ok = numpy.zeros((mrz_ocr.MAX_STRIP_HEIGHT - 20, 1200, 3), dtype=numpy.uint8) + assert mrz_ocr.normalize_scale(ok).shape == ok.shape + + +def test_deskew_leaves_straight_text_alone() -> None: + img = numpy.full((120, 600, 3), 240, dtype=numpy.uint8) + cv2.putText( + img, "P None: + # Tesseract habitually miscounts long runs of '<'. + short = L1[:38] + assert short.endswith("<") + result = mrz_ocr.parse_raw(short + "\n" + L2) + assert result.checks_ok, result.reason + assert result.mrz.surname == "ERIKSSON" + + +def test_an_over_long_filler_run_is_trimmed() -> None: + result = mrz_ocr.parse_raw(L1 + "<<<" + "\n" + L2) + assert result.checks_ok, result.reason + + +def test_a_line_ending_in_a_check_digit_is_never_padded() -> None: + # Losing characters from line 2 must fail, not be silently filled in. + assert mrz_ocr._fit_to_width(L2[:41], 44) is None + assert mrz_ocr._fit_to_width("ABC", 44) is None + + +def test_a_wrong_length_line_can_map_to_more_than_one_format() -> None: + buckets = mrz_ocr.candidates_by_width(L1[:38]) + assert len(buckets[44]) == 1 and len(buckets[36]) == 1 + assert len(buckets[44][0]) == 44 and len(buckets[36][0]) == 36 + + +def test_positional_coercion_repairs_a_country_code() -> None: + # "UTO" misread as "UT0" breaks the composite check until it is repaired. + result = mrz_ocr.parse_raw(L1 + "\n" + L2.replace("UTO", "UT0")) + assert result.checks_ok, result.reason + assert result.mrz.nationality == "UTO" + + +def test_a_lone_line2_is_accepted_because_it_self_validates() -> None: + result = mrz_ocr.parse_raw(L2) + assert result.checks_ok + assert result.line2_only + assert result.mrz.bac_document_number == "L898902C3" + assert result.mrz.date_of_birth.value == "740812" + assert result.mrz.date_of_expiry.value == "120415" + + +def test_a_corrupted_lone_line2_is_rejected() -> None: + corrupted = L2[:-1] + ("9" if L2[-1] != "9" else "8") + assert not mrz_ocr.parse_raw(corrupted).checks_ok + + +def test_a_lone_line1_is_not_enough() -> None: + result = mrz_ocr.parse_raw(L1) + assert not result.checks_ok + + +def test_lone_line2_still_needs_two_agreeing_frames() -> None: + acceptor = mrz_ocr.Acceptor() + assert not acceptor.offer(mrz_ocr.parse_raw(L2)).accepted + assert acceptor.offer(mrz_ocr.parse_raw(L2)).accepted + + +# ------------------------------------------- what check digits cannot catch +def test_check_digits_cannot_see_every_ocr_slip() -> None: + """The 7-3-1 checksum is mod 10, so value differences of 10 are invisible. + + This is not a bug in the implementation - it is a property of the ICAO + scheme, and it is exactly why a scan fills an editable form instead of + starting a read on its own. + """ + from epassport.emrtd import mrz as mrzlib + + for good, blind in (("L", "1"), ("S", "8"), ("G", "6"), ("Z", "5")): + number = f"{good}898902C3" + swapped = f"{blind}898902C3" + assert mrzlib.check_digit(number) == mrzlib.check_digit(swapped) + + +def test_confusions_that_check_digits_do_catch() -> None: + from epassport.emrtd import mrz as mrzlib + + # O(24) vs 0(0) differ by 24, so this one IS detected - which is why the + # positional coercion of country codes is worth doing. + assert mrzlib.check_digit("UTO") != mrzlib.check_digit("UT0") + + +def test_blind_confusions_are_symmetric_and_exclude_identity() -> None: + from epassport.emrtd import mrz as mrzlib + + table = mrzlib.blind_confusions() + for char, others in table.items(): + assert char not in others + for other in others: + assert char in table[other] + + +def test_ambiguous_positions_flags_the_risky_characters() -> None: + from epassport.emrtd import mrz as mrzlib + + assert mrzlib.ambiguous_positions("L1") == [0, 1] + assert mrzlib.ambiguous_positions("XXX") == [] + + +def test_result_reports_unverifiable_document_number_characters() -> None: + result = mrz_ocr.parse_raw(L2) + assert "L" in result.unverifiable_characters + assert mrz_ocr.OcrResult().unverifiable_characters == "" + + +# ------------------------------------------------------- the cheap OCR gate +def test_the_gate_rejects_a_blank_strip() -> None: + blank = numpy.full((180, 1100, 3), 235, dtype=numpy.uint8) + worth, why = mrz_ocr.looks_like_text(blank) + assert not worth + assert "box" in why + + +def test_the_gate_rejects_an_almost_black_strip() -> None: + dark = numpy.full((180, 1100, 3), 4, dtype=numpy.uint8) + dark[40:60, :] = 250 # a sliver of light so Otsu has two classes + worth, why = mrz_ocr.looks_like_text(dark) + assert not worth + + +def test_the_gate_rejects_a_single_blob() -> None: + """A photo or a hand is one mass of ink, not two lines.""" + blob = numpy.full((180, 1100, 3), 240, dtype=numpy.uint8) + cv2.rectangle(blob, (100, 40), (900, 140), (20, 20, 20), -1) + worth, why = mrz_ocr.looks_like_text(blob) + assert not worth + assert "both MRZ lines" in why + + +def test_the_gate_accepts_two_lines_of_text() -> None: + strip = numpy.full((180, 1100, 3), 240, dtype=numpy.uint8) + for row in (55, 125): + cv2.putText( + strip, + "P None: + mask = numpy.zeros((100, 200), dtype=numpy.uint8) + mask[10:20, :] = 255 + mask[50:62, :] = 255 + assert mrz_ocr.ink_bands(mask, floor=0.1) == 2 + mask[80:81, :] = 255 # a single row is noise, not a line + assert mrz_ocr.ink_bands(mask, floor=0.1) == 2 + + +def test_a_gated_frame_costs_no_ocr_call(monkeypatch) -> None: + """The whole point of the gate is to not pay for tesseract.""" + calls: list[int] = [] + monkeypatch.setattr(mrz_ocr, "ocr_text", lambda *a, **k: calls.append(1) or "") + blank = numpy.full((900, 1280, 3), 235, dtype=numpy.uint8) + result = mrz_ocr.read_frame(blank, guide=(0.06, 0.60, 0.88, 0.26)) + assert calls == [] + assert not result.checks_ok + + +def test_variant_escalation_stops_when_nothing_is_recognised(monkeypatch) -> None: + calls: list[int] = [] + + def nothing(*_a, **_k): + calls.append(1) + return "qqq\nqqq" # no line of MRZ length + + monkeypatch.setattr(mrz_ocr, "ocr_text", nothing) + monkeypatch.setattr(mrz_ocr, "looks_like_text", lambda img: (True, "")) + strip = numpy.full((200, 1200, 3), 240, dtype=numpy.uint8) + mrz_ocr.read_frame(strip) + assert len(calls) == 2, "a third pass cannot help when two found nothing" + + +def test_all_variants_run_while_there_is_partial_signal(monkeypatch) -> None: + calls: list[int] = [] + + def partial(*_a, **_k): + calls.append(1) + return L1 + "\n" + L2[:-1] + "9" # right shape, bad composite + + monkeypatch.setattr(mrz_ocr, "ocr_text", partial) + monkeypatch.setattr(mrz_ocr, "looks_like_text", lambda img: (True, "")) + strip = numpy.full((200, 1200, 3), 240, dtype=numpy.uint8) + mrz_ocr.read_frame(strip) + assert len(calls) == len(mrz_ocr.VARIANTS) + + +def test_the_last_winning_variant_is_tried_first_next_time() -> None: + mrz_ocr._last_winner = "adaptive" + try: + assert mrz_ocr.ordered_variants()[0][0] == "adaptive" + finally: + mrz_ocr._last_winner = "" + assert mrz_ocr.ordered_variants() == mrz_ocr.VARIANTS + + +def test_best_language_is_cached() -> None: + """It shells out to tesseract; paying that per frame was measurable.""" + mrz_ocr.best_language.cache_clear() + first = mrz_ocr.best_language() + assert mrz_ocr.best_language() is first + assert mrz_ocr.best_language.cache_info().hits >= 1 diff --git a/tools/ePassport/tests/test_pm3_client.py b/tools/ePassport/tests/test_pm3_client.py new file mode 100644 index 000000000..acc5cfa25 --- /dev/null +++ b/tools/ePassport/tests/test_pm3_client.py @@ -0,0 +1,422 @@ +"""pm3 client: input validation, error classification, cancel, dry-run.""" + +from __future__ import annotations + +import threading +import time +from pathlib import Path + +import pytest + +from epassport.pm3 import errors +from epassport.pm3.client import ( + BacInput, + Pm3Client, + Pm3Result, + strip_ansi, + validate_date, + validate_mrz_field, +) + +#: Recorded pm3 sessions, written to a temp directory by the ``logs`` fixture. +#: They live here rather than in ``samples/`` so the repository carries no +#: throwaway log files - ``--dry-run`` takes any log you have recorded. +RECORDED: dict[str, str] = { + "dump_success.log": """\ +[+] Using UART port /dev/ttyACM0 +[usb] pm3 --> hf emrtd dump -n L898902C3 -d 740812 -e 120415 --dir /tmp/dump +[+] Selected eMRTD application +[=] Attempting Basic Access Control +[+] Basic Access Control successful +[=] Reading EF_COM +[+] Read EF_COM, 27 bytes +[=] Data groups present: [1, 2, 7, 11, 12, 14, 15] +[=] Reading EF_DG1 +[+] Read EF_DG1, 93 bytes +[+] Saved to /tmp/dump/EF_DG1.bin +[=] Reading EF_DG2 +[+] Read EF_DG2, 6678 bytes +[+] Saved to /tmp/dump/EF_DG2.bin +[=] Reading EF_DG7 +[+] Read EF_DG7, 4439 bytes +[+] Saved to /tmp/dump/EF_DG7.bin +[=] Reading EF_DG11 +[+] Read EF_DG11, 128 bytes +[+] Saved to /tmp/dump/EF_DG11.bin +[=] Reading EF_DG12 +[+] Read EF_DG12, 53 bytes +[+] Saved to /tmp/dump/EF_DG12.bin +[=] Reading EF_DG14 +[+] Read EF_DG14, 33 bytes +[+] Saved to /tmp/dump/EF_DG14.bin +[=] Reading EF_DG15 +[+] Read EF_DG15, 165 bytes +[+] Saved to /tmp/dump/EF_DG15.bin +[=] Reading EF_SOD +[+] Read EF_SOD, 1678 bytes +[+] Saved to /tmp/dump/EF_SOD.bin +[+] Dump completed +""", + "dump_bac_failed.log": """\ +[+] Using UART port /dev/ttyACM0 +[usb] pm3 --> hf emrtd dump -n L898902C3 -d 740813 -e 120415 --dir /tmp/dump +[+] Selected eMRTD application +[=] Attempting Basic Access Control +[!] Couldn't do external authentication. Did you supply the correct MRZ info? +""", + "no_device.log": "[=] Waiting for Proxmark3 to appear...\n", + "no_card.log": """\ +[+] Using UART port /dev/ttyACM0 +[usb] pm3 --> hf emrtd info -n L898902C3 -d 740812 -e 120415 +[!] Couldn't select the MRTD application. +""", + "dump_pace_can.log": """\ +[+] Using UART port /dev/ttyACM0 +[usb] pm3 --> hf emrtd dump --can 123456 --dir /tmp/dump +[+] Selected eMRTD application +[=] Trying PACE with the CAN +[+] Authentication with PACE successful ( ECDH, CAN ) +[=] Reading EF_DG1 +[+] Read EF_DG1, 93 bytes +[+] Saved to /tmp/dump/EF_DG1.bin +[+] Dump completed +""", + "pace_wrong_can.log": """\ +[+] Using UART port /dev/ttyACM0 +[usb] pm3 --> hf emrtd dump --can 111111 --pace --dir /tmp/dump +[+] Selected eMRTD application +[=] Trying PACE with the CAN +[!] PACE: wrong password, 2 attempt(s) left before the password is blocked +""", +} + + +@pytest.fixture(scope="session") +def logs(tmp_path_factory) -> Path: + directory = tmp_path_factory.mktemp("pm3-logs") + for name, body in RECORDED.items(): + (directory / name).write_text(body, encoding="utf-8") + return directory + + +# --------------------------------------------------------------- validation +@pytest.mark.parametrize( + "bad", + ["L898902C3; rm -rf /", "L8989 02C3", "L898902c3\n-x", "$(id)", "`id`", "a|b"], +) +def test_shell_metacharacters_are_rejected(bad: str) -> None: + with pytest.raises(Exception): + validate_mrz_field(bad, name="document number", maxlen=9) + + +def test_valid_document_number_is_uppercased() -> None: + assert validate_mrz_field("l898902c3", name="doc", maxlen=9) == "L898902C3" + assert validate_mrz_field("1234<<<<<", name="doc", maxlen=9) == "1234<<<<<" + + +def test_document_number_length_cap() -> None: + with pytest.raises(Exception): + validate_mrz_field("1234567890", name="doc", maxlen=9) + + +@pytest.mark.parametrize( + "bad", ["7408122", "74081", "741332", "740800", "abcdef", "74-08-12", ""] +) +def test_bad_dates_rejected(bad: str) -> None: + with pytest.raises(Exception): + validate_date(bad, name="dob") + + +def test_good_dates_accepted() -> None: + assert validate_date("740812", name="dob") == "740812" + assert validate_date("001231", name="dob") == "001231" + + +def test_partial_triple_is_refused_not_silently_dropped() -> None: + with pytest.raises(Exception) as info: + BacInput("L898902C3", "740812", "").validated() + assert "date of expiry" in str(info.value) + + +def test_mrz_line2_takes_precedence_and_must_be_the_right_length() -> None: + line = "L898902C36UTO7408122F1204159ZE184226B<<<<<10" + got = BacInput(document_number="IGNORED", mrz_line2=line).validated() + assert got.args() == ["-m", line] + with pytest.raises(Exception): + BacInput(mrz_line2="TOOSHORT").validated() + + +# ------------------------------------------------------------ command build +def test_build_command_is_one_string_with_all_three_bac_fields() -> None: + cmd = Pm3Client.build_command( + "dump", BacInput("L898902C3", "740812", "120415"), Path("/tmp/d") + ) + assert cmd == "hf emrtd dump -n L898902C3 -d 740812 -e 120415 --dir /tmp/d" + + +def test_build_command_offline_info_takes_only_a_dir() -> None: + assert ( + Pm3Client.build_command("info", None, Path("/tmp/d")) + == "hf emrtd info --dir /tmp/d" + ) + + +def test_argv_passes_the_command_as_a_single_element(tmp_path: Path) -> None: + fake = tmp_path / "pm3" + fake.write_text("#!/bin/sh\n") + fake.chmod(0o755) + client = Pm3Client(fake) + argv = client.argv_for("hf emrtd info -n X -d 740812 -e 120415") + assert argv[1] == "-c" + assert len(argv) == 3 + assert " " in argv[2] + + +def test_missing_binary_yields_a_typed_error(tmp_path: Path, monkeypatch) -> None: + monkeypatch.delenv("PM3_BIN", raising=False) + monkeypatch.setattr("epassport.pm3.client.find_pm3_binary", lambda _=None: None) + client = Pm3Client() + client.binary = None + result = client.run("hf emrtd info") + assert isinstance(result.error, errors.Pm3NotFound) + assert "PATH" in result.error.remedy + + +# ----------------------------------------------------------- classification +def test_ansi_is_stripped() -> None: + assert strip_ansi("\x1b[32m[+]\x1b[0m ok") == "[+] ok" + + +@pytest.mark.parametrize( + "log,expected", + [ + ("no_device.log", errors.NoDeviceError), + ("no_card.log", errors.NoCardError), + ("dump_bac_failed.log", errors.BacFailedError), + ], +) +def test_recorded_logs_classify(log: str, expected: type, logs: Path) -> None: + lines = (logs / log).read_text().splitlines() + err = errors.classify(lines) + assert isinstance(err, expected) + assert err.remedy + + +def test_successful_log_classifies_as_no_error(logs: Path) -> None: + assert errors.classify((logs / "dump_success.log").read_text().splitlines()) is None + + +def test_bac_remedy_mentions_the_date_format() -> None: + assert "YYMMDD" in errors.BacFailedError().remedy + + +# ------------------------------------------------------------------ dry run +def test_dry_run_replays_a_log_and_reports_progress(logs: Path) -> None: + client = Pm3Client(dry_run_log=logs / "dump_success.log") + seen: list[str] = [] + progress: list[str] = [] + result = client.run( + "hf emrtd dump", + on_line=seen.append, + on_progress=lambda done, total, name: progress.append(name), + ) + assert result.ok + assert result.returncode == 0 + assert any("Basic Access Control successful" in line for line in seen) + assert "EF_DG1" in progress and "EF_SOD" in progress + assert len(progress) == len(set(progress)) # each file counted once + + +def test_dry_run_of_a_failed_log_surfaces_the_typed_error(logs: Path) -> None: + client = Pm3Client(dry_run_log=logs / "dump_bac_failed.log") + result = client.run("hf emrtd dump") + assert isinstance(result.error, errors.BacFailedError) + assert not result.ok + + +def test_cancel_stops_a_dry_run_promptly(logs: Path) -> None: + client = Pm3Client(dry_run_log=logs / "dump_success.log") + holder: list[Pm3Result] = [] + + def work() -> None: + holder.append(client.run("hf emrtd dump")) + + thread = threading.Thread(target=work) + thread.start() + time.sleep(0.05) + client.cancel() + thread.join(timeout=5) + assert not thread.is_alive() + assert isinstance(holder[0].error, errors.CancelledError) + + +# --------------------------------------------------------- real subprocess +def test_cancel_kills_a_real_child_process(tmp_path: Path) -> None: + fake = tmp_path / "pm3" + fake.write_text('#!/bin/sh\necho "[=] starting"\nsleep 60\n') + fake.chmod(0o755) + client = Pm3Client(fake, timeout=30) + holder: list[Pm3Result] = [] + thread = threading.Thread(target=lambda: holder.append(client.run("hf emrtd dump"))) + thread.start() + for _ in range(100): + if client.running: + break + time.sleep(0.02) + client.cancel() + thread.join(timeout=10) + assert not thread.is_alive(), "cancel must not leave the app hanging" + assert isinstance(holder[0].error, errors.CancelledError) + assert not client.running + + +def test_timeout_terminates_the_process(tmp_path: Path) -> None: + fake = tmp_path / "pm3" + fake.write_text('#!/bin/sh\nwhile true; do echo "[=] tick"; sleep 0.05; done\n') + fake.chmod(0o755) + client = Pm3Client(fake, timeout=0.4) + result = client.run("hf emrtd dump") + assert isinstance(result.error, errors.TimeoutError_) + assert not client.running + + +def test_non_executable_binary_is_reported(tmp_path: Path) -> None: + fake = tmp_path / "pm3" + fake.write_text("#!/bin/sh\n") + fake.chmod(0o644) + result = Pm3Client(fake).run("hf emrtd info") + assert isinstance(result.error, errors.Pm3NotExecutable) + assert "chmod" in result.error.remedy + + +# ------------------------------------------------------- PACE and the CAN +from epassport.pm3.client import ( + AUTH_AUTO, + AUTH_BAC, + AUTH_PACE, + validate_can, +) # noqa: E402 + + +def test_can_must_be_digits() -> None: + assert validate_can("123456") == "123456" + for bad in ("12x456", "12 34", "", "1234567890abcd", "-1"): + with pytest.raises(Exception): + validate_can(bad) + + +def test_can_length_bounds() -> None: + assert validate_can("1") == "1" + assert len(validate_can("1" * 14)) == 14 + with pytest.raises(Exception): + validate_can("1" * 15) + + +def test_can_builds_a_pace_command() -> None: + cmd = Pm3Client.build_command("dump", BacInput(can="123456"), Path("/tmp/d")) + assert cmd == "hf emrtd dump --can 123456 --dir /tmp/d" + + +def test_forcing_pace_and_bac_adds_the_right_flag() -> None: + assert Pm3Client.build_command( + "dump", BacInput(can="123456", mode=AUTH_PACE), None + ).endswith("--pace") + triple = BacInput("L898902C3", "740812", "120415", mode=AUTH_BAC) + assert Pm3Client.build_command("dump", triple, None).endswith("--bac") + assert not Pm3Client.build_command( + "dump", triple.__class__(**{**vars(triple), "mode": AUTH_AUTO}), None + ).endswith(("--bac", "--pace")) + + +def test_can_and_mrz_are_mutually_exclusive() -> None: + with pytest.raises(Exception) as info: + BacInput("L898902C3", "740812", "120415", can="123456").validated() + assert "mutually exclusive" in str(info.value) + + +def test_bac_cannot_use_a_can() -> None: + with pytest.raises(Exception) as info: + BacInput(can="123456", mode=AUTH_BAC).validated() + assert "PACE-only" in str(info.value) + + +def test_pace_needs_some_password() -> None: + with pytest.raises(Exception) as info: + BacInput(mode=AUTH_PACE).validated() + assert "PACE needs a password" in str(info.value) + + +def test_unknown_mode_is_rejected() -> None: + with pytest.raises(Exception): + BacInput(can="123456", mode="telepathy").validated() + + +def test_unusual_can_length_warns_but_is_allowed() -> None: + checked = BacInput(can="1234").validated() + assert checked.args() == ["--can", "1234"] + assert "usually 6 digits" in checked.warnings()[0] + assert BacInput(can="123456").validated().warnings() == [] + + +def test_mechanism_describes_what_will_be_attempted() -> None: + assert BacInput(can="123456").mechanism == "PACE (CAN)" + assert BacInput("L898902C3", "740812", "120415").mechanism == "PACE/BAC (MRZ)" + assert BacInput("L898902C3", "740812", "120415", mode=AUTH_BAC).mechanism == "BAC" + assert BacInput(can="123456", mode=AUTH_PACE).mechanism == "PACE (CAN)" + + +@pytest.mark.parametrize( + "line,expected", + [ + ( + "[!] PACE: wrong password, 2 attempt(s) left before the password is blocked", + errors.CanWrongError, + ), + ("[!] PACE: invalid CAN", errors.CanWrongError), + ( + "[!] PACE: the document rejected the algorithm we selected (6A80)", + errors.PaceAlgorithmError, + ), + ( + "[!] PACE: the document's authentication token is wrong, aborting", + errors.PaceFailedError, + ), + ( + "[!] BAC needs MRZ data, the CAN is a PACE only password.", + errors.MissingBacInputError, + ), + ], +) +def test_pace_failures_classify(line: str, expected: type) -> None: + err = errors.classify([line]) + assert isinstance(err, expected) + assert err.remedy + + +def test_wrong_can_remedy_warns_about_blocking() -> None: + assert "block" in errors.CanWrongError().remedy + + +def test_mechanism_is_detected_from_the_log() -> None: + assert ( + errors.detect_mechanism( + ["[+] Authentication with PACE successful ( ECDH, CAN )"] + ) + == "PACE" + ) + assert errors.detect_mechanism(["[+] Basic Access Control successful"]) == "BAC" + assert errors.detect_mechanism(["[=] nothing happened"]) == "" + + +def test_a_recorded_pace_session_reports_success_and_its_mechanism(logs: Path) -> None: + client = Pm3Client(dry_run_log=logs / "dump_pace_can.log") + result = client.run("hf emrtd dump --can 123456") + assert result.ok, result.error + assert errors.detect_mechanism(result.lines) == "PACE" + + +def test_a_recorded_wrong_can_session_classifies_as_a_wrong_can(logs: Path) -> None: + client = Pm3Client(dry_run_log=logs / "pace_wrong_can.log") + result = client.run("hf emrtd dump --can 111111 --pace") + assert isinstance(result.error, errors.CanWrongError) + assert errors.detect_mechanism(result.lines) == "" diff --git a/tools/ePassport/tests/test_scale_modes.py b/tools/ePassport/tests/test_scale_modes.py new file mode 100644 index 000000000..d31c2fdc9 --- /dev/null +++ b/tools/ePassport/tests/test_scale_modes.py @@ -0,0 +1,207 @@ +"""Fitting the page into the window. + +A card's MRZ takes about 2.97% of its width per character; a passport's takes +2.03%. Scale both documents to the same screen width and the card's MRZ comes +out half again as large; make the MRZ match and the card must be drawn smaller. +Both are defensible, so the app offers both - and these tests pin what each +one promises. +""" + +from __future__ import annotations + +import pytest + +from epassport.ui import theme +from epassport.ui.passport import ( + FIT_TO_WINDOW, + PX_PER_MM, + SCALE_MODES, + TRUE_SCALE, + page_scale, +) + +AREA = (1000.0, 700.0) +REF = (theme.REFERENCE_PAGE_MM[0] * PX_PER_MM, theme.REFERENCE_PAGE_MM[1] * PX_PER_MM) + + +def page_px(kind: str) -> tuple[float, float]: + w, h = theme.page_size_mm(kind) + return (w * PX_PER_MM, h * PX_PER_MM) + + +def test_both_modes_exist() -> None: + assert set(SCALE_MODES) == {FIT_TO_WINDOW, TRUE_SCALE} + + +@pytest.mark.parametrize("kind", ["TD3", "TD1"]) +def test_fit_fills_one_dimension_exactly(kind: str) -> None: + """Whatever the format, fitting must use all the space it can.""" + page = page_px(kind) + scale = page_scale(FIT_TO_WINDOW, AREA, page, REF) + shown = (page[0] * scale, page[1] * scale) + fills_width = shown[0] == pytest.approx(AREA[0]) + fills_height = shown[1] == pytest.approx(AREA[1]) + assert fills_width or fills_height, shown + assert shown[0] <= AREA[0] + 0.001 and shown[1] <= AREA[1] + 0.001 + + +def test_fit_makes_a_card_bigger_on_screen_than_true_scale() -> None: + card = page_px("TD1") + assert page_scale(FIT_TO_WINDOW, AREA, card, REF) > page_scale( + TRUE_SCALE, AREA, card, REF + ) + + +def test_true_scale_is_the_same_for_every_format() -> None: + scales = { + kind: page_scale(TRUE_SCALE, AREA, page_px(kind), REF) + for kind in ("TD3", "TD1") + } + assert scales["TD3"] == pytest.approx(scales["TD1"]) + + +def test_the_reference_page_is_identical_in_both_modes() -> None: + """A passport fills the window either way; only smaller formats differ.""" + page = page_px("TD3") + assert page_scale(FIT_TO_WINDOW, AREA, page, REF) == pytest.approx( + page_scale(TRUE_SCALE, AREA, page, REF) + ) + + +def test_true_scale_keeps_mrz_print_matched_across_formats() -> None: + from epassport.ui.widgets.mrzstrip import fit_rows + + on_screen = {} + for kind, rows in (("TD3", ["P" * 44, "L" * 44]), ("TD1", ["I" * 30] * 3)): + page_w, page_h = page_px(kind) + scale = page_scale(TRUE_SCALE, AREA, (page_w, page_h), REF) + band = page_h * theme.band_fraction(kind) + on_screen[kind] = fit_rows(rows, page_w, band, margin=0.055).font_size * scale + biggest, smallest = max(on_screen.values()), min(on_screen.values()) + assert (biggest - smallest) / biggest < 0.05, on_screen + + +def test_fit_deliberately_does_not_match_mrz_print() -> None: + """Documented consequence, asserted so nobody 'fixes' it by accident.""" + from epassport.ui.widgets.mrzstrip import fit_rows + + on_screen = {} + for kind, rows in (("TD3", ["P" * 44, "L" * 44]), ("TD1", ["I" * 30] * 3)): + page_w, page_h = page_px(kind) + scale = page_scale(FIT_TO_WINDOW, AREA, (page_w, page_h), REF) + band = page_h * theme.band_fraction(kind) + on_screen[kind] = fit_rows(rows, page_w, band, margin=0.055).font_size * scale + assert on_screen["TD1"] > on_screen["TD3"] * 1.2 + + +def test_a_degenerate_area_does_not_divide_by_zero() -> None: + for mode in SCALE_MODES: + assert page_scale(mode, (0, 0), page_px("TD3"), REF) == 1.0 + assert page_scale(mode, AREA, (0, 0), REF) > 0 + + +def test_the_mode_is_remembered(tmp_path) -> None: + from epassport.config import Settings + + path = tmp_path / "settings.json" + Settings(page_scale_mode=TRUE_SCALE).save(path) + assert Settings.load(path).page_scale_mode == TRUE_SCALE + assert Settings().page_scale_mode == FIT_TO_WINDOW + + +def test_the_toolbar_toggles_are_labelled_the_same_way() -> None: + """Both buttons must name the ACTION, not the current state. + + Sitting side by side with opposite conventions, the scale button read + "True size" while already in true-size mode - which looks exactly like a + button offering to switch to it. + """ + from pathlib import Path + + kv = (Path(__file__).parent.parent / "epassport" / "ui" / "app.kv").read_text() + + # chrome: shows "Dark chrome" while NOT dark -> names the action + assert 'text: "Dark chrome" if not app.dark else "Light chrome"' in kv + # scale: shows "True size" while fitting -> also names the action + assert 'text: "True size" if app.scale_mode == "fit" else "Fit window"' in kv + + +def test_loading_a_new_format_refits_the_page() -> None: + """The fit depends on the document's size, so a new format must re-fit. + + Without this, opening a card after a passport kept the passport's scale + and the card sat at 59% of the area until something else forced a layout - + which looked like the fit button needing a press after every load. + """ + import inspect + + from epassport.ui import passport + + on_size = inspect.getsource(passport.PassportPage.on_page_size_mm) + assert "self.refit()" in on_size + + refit = inspect.getsource(passport.PassportPage.refit) + # It must walk up to the AspectBox: the plate in between is a Scatter and + # has no layout, so calling _trigger_layout on the immediate parent throws. + assert "AspectBox" in refit + assert "self.parent.parent" not in refit, "walk the chain, do not assume depth" + + +def test_refit_walks_past_a_plate_to_the_layout() -> None: + from epassport.ui.passport import AspectBox, PassportPage + + class Stub: + parent = None + + triggered: list[int] = [] + + class FakeBox(AspectBox): + def _trigger_layout(self, *a, **k): + triggered.append(1) + + box = FakeBox.__new__(FakeBox) + box.parent = None + plate = Stub() + plate.parent = box + page = PassportPage.__new__(PassportPage) + page.parent = plate + + PassportPage.refit(page) + assert triggered == [1] + + +def test_refit_is_harmless_before_the_page_is_parented() -> None: + from epassport.ui.passport import PassportPage + + orphan = PassportPage.__new__(PassportPage) + orphan.parent = None + PassportPage.refit(orphan) # must not raise + + +def test_the_default_window_suits_the_reference_document() -> None: + """Otherwise a passport is letterboxed the moment you open the app.""" + from epassport.config import Settings + + settings = Settings() + pad_w, chrome_h = theme.WINDOW_CHROME_PX + content = ( + settings.window_width - pad_w, + settings.window_height - chrome_h, + ) + assert content[0] / content[1] == pytest.approx(theme.PAGE_ASPECT, rel=0.01) + + +def test_the_suggested_window_matches_the_stored_default() -> None: + from epassport.config import Settings + + settings = Settings() + width, height = theme.window_for_reference(settings.window_width) + assert abs(height - settings.window_height) <= 2, (height, settings.window_height) + + +def test_the_default_window_clears_the_minimum() -> None: + from epassport.config import Settings + + settings = Settings() + assert settings.window_width >= 760 + assert settings.window_height >= 520 diff --git a/tools/ePassport/tests/test_scan_integration.py b/tools/ePassport/tests/test_scan_integration.py new file mode 100644 index 000000000..584c66830 --- /dev/null +++ b/tools/ePassport/tests/test_scan_integration.py @@ -0,0 +1,153 @@ +"""Scan screen end to end: synthetic frames in, auto-filled BAC fields out. + +Uses a fake camera so it runs on a build machine with no webcam, but exercises +the real OCR pipeline and the real acceptance rule. +""" + +from __future__ import annotations + +import glob +import os +import tempfile +import time +from pathlib import Path + +import pytest + +cv2 = pytest.importorskip("cv2") +numpy = pytest.importorskip("numpy") + +from epassport.ocr import mrz_ocr # noqa: E402 + +FONT = ( + Path(__file__).parent.parent + / "epassport" + / "assets" + / "fonts" + / "DejaVuSansMono.ttf" +) +L1 = "P None: + from epassport.ui.scan import GUIDE + + result = mrz_ocr.read_frame(render_page(), guide=GUIDE) + assert result.checks_ok, f"{result.reason} / {result.lines}" + # The dates and their check digits are fully verified. + assert result.mrz.date_of_birth.value == "740812" + assert result.mrz.date_of_expiry.value == "120415" + assert result.mrz.nationality == "UTO" + # The document number's shape is verified; individual characters are not - + # see test_check_digits_cannot_see_every_ocr_slip. + assert len(result.mrz.bac_document_number) == 9 + + +def test_acceptance_needs_two_frames_then_yields_bac_input() -> None: + from epassport.pm3.client import BacInput + from epassport.ui.scan import GUIDE + + frame = render_page() + acceptor = mrz_ocr.Acceptor() + first = acceptor.offer(mrz_ocr.read_frame(frame, guide=GUIDE)) + assert not first.accepted + second = acceptor.offer(mrz_ocr.read_frame(frame, guide=GUIDE)) + assert second.accepted + + parsed = second.mrz + validated = BacInput(mrz_line2=parsed.mrz_line2).validated() + assert validated.args()[0] == "-m" + assert len(validated.args()[1]) == 44 + assert validated.args()[1][13:19] == "740812" + assert validated.args()[1][21:27] == "120415" + + +def test_a_blank_frame_is_never_accepted() -> None: + from epassport.ui.scan import GUIDE + + blank = numpy.full((900, 1280, 3), 235, dtype=numpy.uint8) + acceptor = mrz_ocr.Acceptor() + for _ in range(3): + assert not acceptor.offer(mrz_ocr.read_frame(blank, guide=GUIDE)).accepted + + +def test_ocr_scratch_files_stay_out_of_slash_tmp() -> None: + """A picture of somebody's MRZ must not be written to a shared /tmp.""" + original = tempfile.tempdir + try: + mrz_ocr.use_private_tempdir() + assert tempfile.tempdir is not None + scratch = Path(tempfile.tempdir) + assert scratch.is_dir() + assert scratch.stat().st_mode & 0o077 == 0, "OCR scratch dir must be owner-only" + + before = set(glob.glob("/tmp/tess_*")) + mrz_ocr.read_frame(render_page()) + after = set(glob.glob("/tmp/tess_*")) + assert after == before, "tesseract wrote scratch files into /tmp" + + mrz_ocr.clear_private_tempdir() + assert not any(scratch.iterdir()) + finally: + tempfile.tempdir = original + + +def test_camera_thread_stops_cleanly_without_a_camera(monkeypatch) -> None: + """No camera must mean a clear message, not a hung thread.""" + from epassport.ocr.camera import CameraThread + + class DeadCapture: + def __init__(self, *_a, **_k) -> None: + pass + + def isOpened(self) -> bool: + return False + + def release(self) -> None: + pass + + def set(self, *_a) -> None: + pass + + def read(self): + return False, None + + monkeypatch.setattr(cv2, "VideoCapture", DeadCapture) + errors: list[str] = [] + camera = CameraThread(index=0, on_error=errors.append) + camera.start() + for _ in range(100): + if errors: + break + time.sleep(0.02) + camera.stop() + assert errors, "a missing camera must report an error" + assert "/dev/video" in errors[0] + assert not camera.running diff --git a/tools/ePassport/tests/test_sod.py b/tools/ePassport/tests/test_sod.py new file mode 100644 index 000000000..aa5a2a710 --- /dev/null +++ b/tools/ePassport/tests/test_sod.py @@ -0,0 +1,76 @@ +"""EF_SOD structure decoding, including the shapes real documents use.""" + +from __future__ import annotations + +from pathlib import Path + +import pytest + +from epassport.emrtd import dg +from epassport.emrtd.sod import parse_sod + + +def _raw(directory: Path) -> dict[str, bytes]: + out: dict[str, bytes] = {} + for name, _tag, _note, _eac in dg.DG_FILES: + _path, data = dg.read_dump_file(directory, name) + if data: + out[name] = data + return out + + +def test_data_group_hash_values_is_a_sequence_of_not_a_set_of(td3: Path) -> None: + """ICAO 9303 part 10 says SEQUENCE OF. + + Decoding it as SET OF makes every real EF_SOD fail with "tag should have + been 17, but 16 was found", while a synthetic file encoded the same wrong + way still parses - so this is asserted against the raw DER. + """ + from asn1crypto import cms + + from epassport.emrtd import tlv + + data = (td3 / "EF_SOD.bin").read_bytes() + payload = tlv.parse(data)[0].value + lds_der = cms.ContentInfo.load(payload)["content"]["encap_content_info"][ + "content" + ].native + + # Walk the outer SEQUENCE to the third element and check its tag byte. + assert lds_der[0] == 0x30, "LDSSecurityObject is a SEQUENCE" + offset = 2 if lds_der[1] < 0x80 else 2 + (lds_der[1] & 0x7F) + offset += 3 # version: 02 01 xx + assert lds_der[offset] == 0x30, "hashAlgorithm is a SEQUENCE" + offset += 2 + lds_der[offset + 1] + assert lds_der[offset] == 0x30, "dataGroupHashValues must be tagged SEQUENCE (0x30)" + + +def test_sod_reports_every_data_group_hash(td3: Path) -> None: + raw = _raw(td3) + info = parse_sod(raw["EF_SOD"], raw) + assert info.available, info.message + assert info.message == "" + assert [h.dg for h in info.hashes] == [1, 2, 7, 11, 12, 14, 15] + assert all(h.status == "match" for h in info.hashes) + + +def test_a_data_group_absent_from_the_dump_is_not_checked(td3: Path) -> None: + raw = _raw(td3) + raw.pop("EF_DG7") + info = parse_sod(raw["EF_SOD"], raw) + statuses = {h.dg: h.status for h in info.hashes} + assert statuses[7] == "not checked" + assert statuses[1] == "match" + assert info.mismatches == [] + + +def test_missing_sod_is_reported_not_crashed() -> None: + info = parse_sod(b"", {}) + assert not info.available + assert "not dumped" in info.message + + +def test_garbage_sod_is_reported_not_crashed() -> None: + info = parse_sod(b"\x77\x05\x01\x02\x03\x04\x05", {}) + assert not info.available + assert info.message diff --git a/tools/ePassport/tests/test_tlv.py b/tools/ePassport/tests/test_tlv.py new file mode 100644 index 000000000..29eaad0f9 --- /dev/null +++ b/tools/ePassport/tests/test_tlv.py @@ -0,0 +1,87 @@ +"""BER-TLV reader: nesting, long-form lengths, multi-byte tags, damage.""" + +from __future__ import annotations + +import pytest + +from epassport.emrtd import tlv + + +def test_primitive_short_form() -> None: + node = tlv.parse_one(bytes([0x5F, 0x1F, 0x03]) + b"ABC") + assert node.tag == 0x5F1F + assert node.tag_hex == "5F1F" + assert not node.constructed + assert node.value == b"ABC" + + +def test_constructed_nesting() -> None: + inner = tlv.encode(0x5F1F, b"P None: + payload = b"\xab" * 300 + node = tlv.parse_one(tlv.encode(0x75, payload)) + assert len(node.value) == 300 + + +def test_encode_length_boundaries() -> None: + assert tlv.encode_length(0x7F) == b"\x7f" + assert tlv.encode_length(0x80) == b"\x81\x80" + assert tlv.encode_length(300) == b"\x82\x01\x2c" + + +def test_multiple_top_level_objects() -> None: + buf = tlv.encode(0x5C, b"\x61\x75") + tlv.encode(0x5F01, b"0107") + nodes = tlv.parse(buf) + assert [n.tag for n in nodes] == [0x5C, 0x5F01] + assert tlv.find_value(nodes, 0x5F01) == b"0107" + + +def test_padding_between_objects_is_skipped() -> None: + buf = b"\x00\x00" + tlv.encode(0x5F1F, b"X") + b"\xff\xff" + assert [n.tag for n in tlv.parse(buf)] == [0x5F1F] + + +def test_truncated_value_is_tolerated_by_default() -> None: + buf = bytes([0x61, 0x20]) + b"\x5f\x1f\x03ABC" # claims 32 bytes, has 7 + node = tlv.parse_one(buf) + assert node.tag == 0x61 + assert node.find(0x5F1F).value == b"ABC" + + +def test_truncated_value_raises_in_strict_mode() -> None: + with pytest.raises(tlv.TlvError): + tlv.parse(bytes([0x61, 0x20]) + b"\x5f\x1f\x03ABC", strict=True) + + +def test_indefinite_length_rejected() -> None: + with pytest.raises(tlv.TlvError): + tlv.parse(b"\x61\x80\x00\x00", strict=True) + + +def test_empty_buffer() -> None: + assert tlv.parse(b"") == [] + with pytest.raises(tlv.TlvError): + tlv.parse_one(b"") + + +def test_text_decoding_never_raises() -> None: + assert tlv.text(b"ANNA\x00") == "ANNA" + assert tlv.text(b"\xff\xfe") == "ÿþ" + assert tlv.text(None) == "" + assert tlv.text(b"M\xc3\xbcller") == "Müller" + + +def test_walk_and_dump() -> None: + buf = tlv.encode(0x6B, tlv.encode(0x5C, b"\x5f\x0e") + tlv.encode(0x5F0E, b"ANNA")) + node = tlv.parse_one(buf) + assert [n.tag for n in node.walk()] == [0x6B, 0x5C, 0x5F0E] + assert "5F0E" in node.dump() + assert len(node.find_all(0x5F0E)) == 1 diff --git a/tools/ePassport/tools_gen_countries.py b/tools/ePassport/tools_gen_countries.py new file mode 100644 index 000000000..bda1ce33d --- /dev/null +++ b/tools/ePassport/tools_gen_countries.py @@ -0,0 +1,114 @@ +"""One-shot generator for ``epassport/emrtd/countries.py``. + +Country *names* come from the proxmark3 client's own ISO-3166 table +(``client/src/cmdlffdxb.c``, ``fdxbCountryMapping``), which is keyed by +ISO-3166 numeric. MRZ uses alpha-3, so the numeric -> alpha-3 bridge is +resolved here at generation time via pycountry; the emitted module is a plain +dict with no runtime dependency. + +Run: python3 tools_gen_countries.py ../../client/src/cmdlffdxb.c +""" + +from __future__ import annotations + +import re +import sys +from pathlib import Path + +import pycountry + +# ICAO 9303 codes that are not ISO-3166 country codes. +ICAO_EXTRA: dict[str, str] = { + "D": "Germany", + "GBD": "British Overseas Territories Citizen", + "GBN": "British National (Overseas)", + "GBO": "British Overseas Citizen", + "GBP": "British Protected Person", + "GBS": "British Subject", + "EUE": "European Union", + "RKS": "Kosovo", + "UNO": "United Nations Organization", + "UNA": "United Nations Specialized Agency", + "UNK": "Kosovo (UNMIK)", + "XBA": "African Development Bank", + "XIM": "African Export-Import Bank", + "XCC": "Caribbean Community", + "XCO": "Common Market for Eastern and Southern Africa", + "XEC": "Economic Community of West African States", + "XPO": "International Criminal Police Organization", + "XOM": "Sovereign Military Order of Malta", + "XDC": "Southern African Development Community", + "XXA": "Stateless person", + "XXB": "Refugee", + "XXC": "Refugee (other)", + "XXX": "Unspecified nationality", + "UTO": "Utopia", + "ZZZ": "Unknown", +} + +ROW = re.compile(r"\{\s*(\d+)\s*,\s*\"([^\"]+)\"\s*\}") + + +def main(source: Path, out: Path) -> None: + text = source.read_text(encoding="utf-8", errors="replace") + start = text.index("fdxbCountryMapping[]") + end = text.index("};", start) + table = {int(num): name for num, name in ROW.findall(text[start:end])} + + mapping: dict[str, str] = {} + unmatched: list[tuple[int, str]] = [] + for numeric, name in sorted(table.items()): + try: + entry = pycountry.countries.get(numeric=f"{numeric:03d}") + except (KeyError, LookupError): + entry = None + if entry is None: + unmatched.append((numeric, name)) + continue + mapping[entry.alpha_3] = name + + # ICAO codes win over anything the numeric bridge produced. + mapping.update(ICAO_EXTRA) + + lines = [ + '"""ICAO / ISO-3166 alpha-3 code -> country name.', + "", + "GENERATED FILE - do not edit by hand. Regenerate with::", + "", + " python3 tools_gen_countries.py /client/src/cmdlffdxb.c", + "", + "Names are taken verbatim from the proxmark3 client's own ISO-3166 table", + "(``fdxbCountryMapping`` in ``client/src/cmdlffdxb.c``); the numeric ->", + "alpha-3 bridge and the ICAO-specific non-ISO codes are applied by the", + "generator. No runtime dependencies.", + '"""', + "", + "from __future__ import annotations", + "", + "COUNTRIES: dict[str, str] = {", + ] + for code in sorted(mapping): + lines.append(f' "{code}": "{mapping[code]}",') + lines += [ + "}", + "", + "", + "def country_name(code: str) -> str:", + ' """Full country name for an MRZ alpha-3 code, or the code itself."""', + " if not code:", + ' return ""', + ' key = code.strip().upper().rstrip("<")', + " return COUNTRIES.get(key, key)", + "", + ] + out.write_text("\n".join(lines), encoding="utf-8") + print(f"wrote {out} with {len(mapping)} codes") + if unmatched: + print(f"no alpha-3 for {len(unmatched)} numeric entries: {unmatched}") + + +if __name__ == "__main__": + src = ( + Path(sys.argv[1]) if len(sys.argv) > 1 else Path("../../client/src/cmdlffdxb.c") + ) + main(src, Path("epassport/emrtd/countries.py")) diff --git a/tools/ePassport/tools_make_sample.py b/tools/ePassport/tools_make_sample.py new file mode 100644 index 000000000..74bf66a58 --- /dev/null +++ b/tools/ePassport/tools_make_sample.py @@ -0,0 +1,358 @@ +"""Generate the synthetic dumps under ``samples/``. + +These are entirely fabricated documents for the fictional ICAO specimen state +"Utopia". No real personal data, no real security print, no real key material +of any consequence - the SOD signing key is generated fresh and thrown away. + +Run: python3 tools_make_sample.py +""" + +from __future__ import annotations + +import datetime as dt +import io +from pathlib import Path + +from epassport.emrtd import mrz +from epassport.emrtd.tlv import encode + +#: Default output directory when this file is run as a script. Nothing is +#: checked in: the dumps are generated on demand, and the tests build their own +#: copy into a temporary directory. +SAMPLES = Path(__file__).parent / "samples" + + +def portrait_png(seed: int, width: int = 240, height: int = 320) -> bytes: + """A flat synthetic 'photo' - deliberately not a real face.""" + from PIL import Image, ImageDraw + + img = Image.new("RGB", (width, height), (207, 205, 198)) + d = ImageDraw.Draw(img) + skin = (214, 178 - seed % 30, 150 - seed % 20) + d.ellipse((width * 0.28, height * 0.14, width * 0.72, height * 0.52), fill=skin) + d.ellipse( + (width * 0.12, height * 0.50, width * 0.88, height * 1.10), fill=(48, 60, 92) + ) + d.ellipse((width * 0.32, height * 0.53, width * 0.68, height * 0.78), fill=skin) + out = io.BytesIO() + img.save(out, format="JPEG", quality=88) + return out.getvalue() + + +def signature_png() -> bytes: + from PIL import Image, ImageDraw + + img = Image.new("RGB", (320, 96), (255, 255, 255)) + d = ImageDraw.Draw(img) + pts = [ + (20, 70), + (50, 30), + (70, 72), + (95, 34), + (125, 68), + (160, 40), + (200, 66), + (250, 36), + (300, 60), + ] + d.line(pts, fill=(20, 24, 60), width=3, joint="curve") + out = io.BytesIO() + img.save(out, format="JPEG", quality=85) + return out.getvalue() + + +def cbeff_wrap(image: bytes, biometric_type: int = 0x02) -> bytes: + """Wrap an image the way DG2 does: 7F61 { 02 count, 7F60 { A1 hdr, 5F2E img } }.""" + header = ( + encode(0x81, bytes([biometric_type])) + + encode(0x82, b"\x00") + + encode(0x87, b"\x01\x01") + ) + bit = encode(0xA1, header) + encode(0x5F2E, b"\x00" * 46 + image) + return encode(0x7F61, encode(0x02, b"\x01") + encode(0x7F60, bit)) + + +def build_dg1(line1: str, line2: str) -> bytes: + return encode(0x61, encode(0x5F1F, (line1 + line2).encode("ascii"))) + + +def build_com(dgs: list[int]) -> bytes: + tag_of = { + 1: 0x61, + 2: 0x75, + 3: 0x63, + 5: 0x65, + 7: 0x67, + 11: 0x6B, + 12: 0x6C, + 14: 0x6E, + 15: 0x6F, + } + taglist = bytes(tag_of[n] for n in dgs if n in tag_of) + body = encode(0x5F01, b"0107") + encode(0x5F36, b"040000") + encode(0x5C, taglist) + return encode(0x60, body) + + +def build_dg11(**fields: str) -> bytes: + tags = { + "full_name": 0x5F0E, + "personal_number": 0x5F10, + "place_of_birth": 0x5F11, + "full_date_of_birth": 0x5F2B, + "address": 0x5F42, + "telephone": 0x5F12, + "profession": 0x5F13, + } + present = [tags[k] for k in fields if k in tags] + body = encode(0x5C, b"".join(t.to_bytes(2, "big") for t in present)) + for key, value in fields.items(): + body += encode(tags[key], value.encode("utf-8")) + return encode(0x6B, body) + + +def build_dg12(**fields: str) -> bytes: + tags = { + "issuing_authority": 0x5F19, + "date_of_issue": 0x5F26, + "endorsements": 0x5F1B, + } + present = [tags[k] for k in fields if k in tags] + body = encode(0x5C, b"".join(t.to_bytes(2, "big") for t in present)) + for key, value in fields.items(): + body += encode(tags[key], value.encode("utf-8")) + return encode(0x6C, body) + + +def build_dg15() -> bytes: + """A real (throwaway) RSA public key in SubjectPublicKeyInfo form.""" + from cryptography.hazmat.primitives.asymmetric import rsa + from cryptography.hazmat.primitives.serialization import Encoding, PublicFormat + + key = rsa.generate_private_key(public_exponent=65537, key_size=1024) + spki = key.public_key().public_bytes( + Encoding.DER, PublicFormat.SubjectPublicKeyInfo + ) + return encode(0x6F, spki) + + +def build_dg14() -> bytes: + """SecurityInfos announcing Chip Authentication + Active Authentication.""" + from asn1crypto.core import ObjectIdentifier + + def secinfo(oid: str, version: int) -> bytes: + body = ObjectIdentifier(oid).dump() + encode(0x02, bytes([version])) + return encode(0x30, body) + + infos = secinfo("0.4.0.127.0.7.2.2.1.2", 1) + secinfo("2.23.136.1.1.5", 1) + return encode(0x6E, encode(0x31, infos)) + + +def build_sod(dg_hashes: dict[int, bytes], subject: str) -> bytes: + """A genuine CMS SignedData over a real LDSSecurityObject, self-signed.""" + import hashlib + + from asn1crypto import algos, cms, core, x509 as a_x509 + from cryptography import x509 + from cryptography.hazmat.primitives import hashes, serialization + from cryptography.hazmat.primitives.asymmetric import rsa + from cryptography.x509.oid import NameOID + + class DataGroupHash(core.Sequence): + _fields = [ + ("dataGroupNumber", core.Integer), + ("dataGroupHashValue", core.OctetString), + ] + + class DataGroupHashValues(core.SequenceOf): + # ICAO 9303 part 10: SEQUENCE OF, not SET OF. + _child_spec = DataGroupHash + + class LDSSecurityObject(core.Sequence): + _fields = [ + ("version", core.Integer), + ("hashAlgorithm", algos.DigestAlgorithm), + ("dataGroupHashValues", DataGroupHashValues), + ] + + lds = LDSSecurityObject( + { + "version": 0, + "hashAlgorithm": {"algorithm": "sha256"}, + "dataGroupHashValues": [ + {"dataGroupNumber": n, "dataGroupHashValue": h} + for n, h in sorted(dg_hashes.items()) + ], + } + ) + lds_der = lds.dump() + + key = rsa.generate_private_key(public_exponent=65537, key_size=2048) + name = x509.Name( + [ + x509.NameAttribute(NameOID.COUNTRY_NAME, "UT"), + x509.NameAttribute( + NameOID.ORGANIZATION_NAME, "Utopia Ministry of the Interior" + ), + x509.NameAttribute(NameOID.COMMON_NAME, subject), + ] + ) + now = dt.datetime(2020, 4, 1, tzinfo=dt.timezone.utc) + cert = ( + x509.CertificateBuilder() + .subject_name(name) + .issuer_name(name) + .public_key(key.public_key()) + .serial_number(0x5A17C0DE) + .not_valid_before(now) + .not_valid_after(now + dt.timedelta(days=3650)) + .sign(key, hashes.SHA256()) + ) + cert_der = cert.public_bytes(serialization.Encoding.DER) + + digest = hashlib.sha256(lds_der).digest() + signed_attrs = cms.CMSAttributes( + [ + cms.CMSAttribute( + {"type": "content_type", "values": ["1.2.840.10008.5.1.4.1.1.1"]} + ), + cms.CMSAttribute({"type": "message_digest", "values": [digest]}), + ] + ) + signature = key.sign( + signed_attrs.dump(), + __import__( + "cryptography.hazmat.primitives.asymmetric.padding", fromlist=["PKCS1v15"] + ).PKCS1v15(), + hashes.SHA256(), + ) + + signed_data = cms.SignedData( + { + "version": "v3", + "digest_algorithms": [{"algorithm": "sha256"}], + "encap_content_info": { + "content_type": "1.2.840.10008.5.1.4.1.1.1", + "content": lds_der, + }, + "certificates": [a_x509.Certificate.load(cert_der)], + "signer_infos": [ + { + "version": "v1", + "sid": cms.SignerIdentifier( + { + "issuer_and_serial_number": { + "issuer": a_x509.Certificate.load(cert_der).issuer, + "serial_number": 0x5A17C0DE, + } + } + ), + "digest_algorithm": {"algorithm": "sha256"}, + "signed_attrs": signed_attrs, + "signature_algorithm": {"algorithm": "rsassa_pkcs1v15"}, + "signature": signature, + } + ], + } + ) + content = cms.ContentInfo({"content_type": "signed_data", "content": signed_data}) + return encode(0x77, content.dump()) + + +def write_dump(directory: Path, files: dict[str, bytes]) -> None: + directory.mkdir(parents=True, exist_ok=True) + for name, data in files.items(): + (directory / f"{name}.bin").write_bytes(data) + # pm3 also side-saves the carved portrait next to the .bin files. + if "EF_DG2" in files: + blob = files["EF_DG2"] + idx = blob.find(b"\xff\xd8\xff") + if idx >= 0: + (directory / "EF_DG2.jpg").write_bytes(blob[idx:]) + print(f"wrote {directory} ({len(files)} files)") + + +def sample_td3(root: Path) -> None: + import hashlib + + line1 = "P None: + """Same document, but DG2 is altered after signing - SOD must flag it.""" + import hashlib + import shutil + + src = root / "td3_utopia" + dst = root / "td3_utopia_tampered" + if dst.exists(): + shutil.rmtree(dst) + shutil.copytree(src, dst) + swapped = encode(0x75, cbeff_wrap(portrait_png(21))) + (dst / "EF_DG2.bin").write_bytes(swapped) + idx = swapped.find(b"\xff\xd8\xff") + (dst / "EF_DG2.jpg").write_bytes(swapped[idx:]) + print(f"wrote {dst} (DG2 replaced after signing)") + del hashlib + + +def sample_td1(root: Path) -> None: + """An ID card: TD1 geometry, no DG11/DG12, no SOD.""" + l1 = "I Path: + """Generate every sample dump under ``root``. Returns ``root``.""" + root.mkdir(parents=True, exist_ok=True) + sample_td3(root) + sample_td3_tampered(root) + sample_td1(root) + return root + + +if __name__ == "__main__": + import sys + + build_all(Path(sys.argv[1]) if len(sys.argv) > 1 else SAMPLES) diff --git a/tools/ePassport/tools_render_page.py b/tools/ePassport/tools_render_page.py new file mode 100644 index 000000000..1cf03e73e --- /dev/null +++ b/tools/ePassport/tools_render_page.py @@ -0,0 +1,56 @@ +"""Render the passport data page to a PNG, headless-ish, for eyeballing. + +python3 tools_render_page.py samples/td3_utopia out.png +""" + +from __future__ import annotations + +import os +import sys +from pathlib import Path + +os.environ.setdefault("KIVY_NO_ARGS", "1") +os.environ.setdefault("KIVY_NO_CONSOLELOG", "1") + +from kivy.app import App # noqa: E402 +from kivy.clock import Clock # noqa: E402 +from kivy.config import Config # noqa: E402 + +Config.set("graphics", "width", "1280") +Config.set("graphics", "height", "860") + +from epassport.emrtd.dg import load_dump # noqa: E402 +from epassport.ui import load_kv # noqa: E402 + + +class RenderApp(App): + def __init__(self, dump: Path, out: Path, **kwargs) -> None: + super().__init__(**kwargs) + self.dump = dump + self.out = out + + def build(self): + load_kv() + from epassport.ui.passport import AspectBox, PassportPage + + box = AspectBox() + page = PassportPage() + page.record = load_dump(self.dump) + box.add_widget(page) + return box + + def on_start(self) -> None: + Clock.schedule_once(self._shoot, 1.2) + + def _shoot(self, *_a) -> None: + from kivy.core.window import Window + + Window.screenshot(name=str(self.out)) + self.stop() + + +if __name__ == "__main__": + dump = Path(sys.argv[1] if len(sys.argv) > 1 else "samples/td3_utopia") + out = Path(sys.argv[2] if len(sys.argv) > 2 else "/tmp/page.png") + RenderApp(dump, out).run() + print("wrote", out) diff --git a/tools/ePassport/tools_screenshot.py b/tools/ePassport/tools_screenshot.py new file mode 100644 index 000000000..397b1ff58 --- /dev/null +++ b/tools/ePassport/tools_screenshot.py @@ -0,0 +1,64 @@ +"""Drive the running app and screenshot every tab, for eyeballing a build. + +python3 tools_screenshot.py samples/td3_utopia /tmp/shots +""" + +from __future__ import annotations + +import os +import sys +from pathlib import Path + +os.environ.setdefault("KIVY_NO_ARGS", "1") + +from kivy.clock import Clock # noqa: E402 + +from epassport.__main__ import Pm3PassportApp, parse_args # noqa: E402 + + +def main() -> int: + dump = sys.argv[1] if len(sys.argv) > 1 else "samples/td3_utopia" + outdir = Path(sys.argv[2] if len(sys.argv) > 2 else "/tmp/shots") + outdir.mkdir(parents=True, exist_ok=True) + + args = parse_args(["--dump", dump]) + app = Pm3PassportApp(args) + steps: list[tuple[str, object]] = [] + + def shoot(name: str): + from kivy.core.window import Window + + Window.screenshot(name=str(outdir / f"{name}.png")) + + def script(*_a) -> None: + if not steps: + app.stop() + return + name, action = steps.pop(0) + if callable(action): + action() + Clock.schedule_once( + lambda *_: (shoot(name), Clock.schedule_once(script, 0.6)), 0.8 + ) + + for index, label in enumerate( + ("datapage", "personal", "issuer", "security", "files", "log") + ): + steps.append((f"{index}_{label}", lambda i=index: app.select_tab(i))) + steps.append(("6_entry", app.goto_entry)) + steps.append(("7_dark", app.toggle_dark)) + + original = app.on_start + + def on_start() -> None: + original() + Clock.schedule_once(script, 1.5) + + app.on_start = on_start + app.run() + print("shots in", outdir) + return 0 + + +if __name__ == "__main__": + raise SystemExit(main())