- C++ 88.7%
- Shell 11.3%
| Filename | Latest commit message | Latest commit date |
|---|---|---|
Jorijn van der Graaf
e03ce4ae5a
Stock rewrites the stored template on every successful press. Its post-match loop is QUERY_FINGER_STATUS, CAPTURE_IMAGE, 0x1015 UPDATE_TEMPLATE while the finger stays down, with no REPORT_EVENT in it -- so the matcher does not re-run and the verdict cannot change. Forty-six of those against eighty-six captures in one reference session, and the stored body measurably grows: 333278 bytes at enrolment, 360822 at the next session's load, 371734 after one authentication session. This daemon sent none of them. The command shares REPORT_EVENT's event context. The stock wrapper memsets 732 bytes and writes six fields: a zero byte at +0x2a4, the scan-slot count, a zero word, the count of frames folded so far in this press, a flags word of 0x00080000 with bit 6 set on the frame whose event was FingerTouched, and a zero at +0x2d8. Declared length 0x2dc. +0x2d8 is the one that matters, and it matters by staying zero. The dispatcher stub reads it after the handler returns and only if it is non-zero does it read +0x2dc and make that the response length. Every earlier attempt in this project set both fields and varied the declared length across 0x2e0, 0x400 and 0x1000; all of them answered -90, the trustlet gone, and the conclusion recorded was "do not retry until a template is loaded". A loaded template was necessary but not sufficient. The stock HAL sets neither field. Measured on the device with two templates loaded and no finger: both branches answer rc=0 and ENUMERATE still reports 2, so the app did not fault. Those fields are little endian, assembled low-address-first by the handler. An earlier reading called them big endian, off the bfi order, and was wrong. Bit 6 selects which algorithm entry runs: clear takes libfp_template_x_update, set takes the other, which also reads the scan-slot count. |
||
| implementations | ||
| interfaces | ||
| packaging | ||
| tests | ||
| .gitignore | ||
| LICENSE | ||
| lint-rules.h | ||
| project.cpp | ||
| README.md | ||
fingerprintd
Fingerprint daemon for the Fairphone 6 (milos, SM7635) on mainline Linux.
Why a daemon
The sensor is a FocalTech FT9391 on a TrustZone-owned SPI bus. spi@a88000 is
disabled in both the mainline and the stock Android device tree, and the pads
are XPU-protected — touching them from the normal world is an instant SError
reboot. Every pixel the sensor produces stays inside the TEE: capture,
preprocessing, the classifier, enrolment and matching all run in the focal64
trustlet, which reports a matched finger id and nothing else. A libfprint-style
driver cannot exist on this device.
So the normal world's job is narrower than usual, and none of it is per-request work:
- Power the sensor. Rail on gpio29, reset on gpio74, interrupt on gpio75 — the same division of labour the downstream driver uses. One sensor reset buys exactly one trustlet init, so whatever powers the sensor must also hold the session open.
- Be QTEE's filesystem. QTEE cannot reach storage. When the trustlet saves
or loads a template it calls back into the normal world through the
gpfile(0x7000) and RPMB (0x2000) listeners, and expects them served. QTEE does the crypto and the anti-rollback; this side moves opaque bytes and performs the authenticated RPMB transactions against the UFS device. - Speak a biometrics API. The daemon owns
net.reactivated.Fprint, sopam_fprintd, the Plasma fingerprint KCM andfprintd-enroll(1)work against it unmodified.
A listener registration is held for as long as the process lives and QTEE's listener table is global to the boot, so this has to be one long-lived process rather than a tool spawned per request.
Layout
interfaces/ Fingerprintd{,-Sfs}.cppm the core: pure C++ modules
implementations/main.cpp the daemon shell
tests/ one suite per core module
fingerprintd-core is a static library with no GLib, no libqcomtee and no
system headers. Everything in it is a wire format or a state machine that was
recovered by reverse-engineering, so all of it is pinned by tests that run on a
dev box with no phone, no TEE and no sensor. The daemon shell holds everything
that touches hardware.
Build
crafter-build # bin/fingerprintd-<target>-<march>/fingerprintd
crafter-build test # the unit suites
Cross-compiling for the phone:
packaging/make-sysroot.sh # once; no root, no qemu, no device
crafter-build -- --target=aarch64-alpine-linux-musl \
--sysroot=~/.cache/fingerprintd/sysroot-aarch64-alpine \
--march=armv8-a --mtune=generic
crafter-build test --target=aarch64-alpine-linux-musl --sysroot=... \
--march=armv8-a --mtune=generic # runs the suites under qemu-aarch64
The result links dynamically against the phone's own musl and libc++
(libc++, libc++abi, libunwind, libgcc_s, all already present on pmOS).
The research harness this replaces had to be built -static, but only because
it was built with the host's glibc toolchain — that constraint does not apply
to a real Alpine sysroot.
Verified on the device: all five suites pass cross-built and run on the phone itself, not only under emulation.
Status
It works end to end through fprintd's own clients. On the Fairphone 6, as a
systemd unit owning net.reactivated.Fprint:
fprintd-enroll -f right-index-finger user ten stages, enroll-completed
fprintd-list user - #0: right-index-finger
fprintd-verify user (wrong finger) verify-no-match, on the first press
fprintd-verify user (enrolled finger) verify-match, on the first press
Nothing in fprintd was modified; the daemon speaks its interface.
| module | what it holds |
|---|---|
:Sfs |
the gpfile frame — the read/write offset split, the O_TRUNC guard, root mapping, path-traversal rejection |
:Rpmb |
request/reply framing, the bytes-transferred out-parameter, JEDEC result codes, chunking, the one-time-programmable key guard |
:Ta |
command surface, the 740-byte event context, capture flags, save masks, enrol/auth payloads, the error table, the verdict rule |
:Engine |
baseline calibration, touch edges, enrolment progress, the accounting |
:Store |
the finger name map |
:Tee |
QTEE service/op numbers, the listener table, the 13-byte CBOR credentials blob |
:Sensor |
the pins, the timings, and the XPU guard |
Every constant that was recovered by reverse-engineering carries where it came from, and the tests are written to fail if it is undone rather than to restate it. Several replay real captures off the phone.
Two policy decisions live in the daemon and both were forced by measurement.
Verification is judged per press: any matching frame wins, only rejections
is no-match — both correct presses in the acceptance run had rejected frames
before the one that matched, so a first-frame rule would have failed them. And
the shipped config sets max_authentication_rescan_times to 0, because at the
stock budget a wrong finger never yields a terminal frame and a PAM client
waits forever for the verify-no-match it needs.
Known about the loop, from real use. A verify frame is four QTEE round
trips (~200 ms idle); a REPORT_EVENT that runs the matcher is ~300 ms, and
the rising edge pays it twice because events 5 and 7 both reach the matcher.
The first frame of a press is the finger landing and usually rejects; matches
land at frame 3, 5, 8 — so a quick tap is often a miss. Two attempts to fix
that (drop event 5; recapture after 50 ms) went in together and produced zero
matches; both are reverted and recorded. gpio75 is a ~1 ms pulse, not a
level — an IRQ-driven idle needs GPIO edge events. Changes to this loop are
made one variable at a time, on a measured baseline.
Not done: packaging (provides="fprintd=…" so this replaces the fprintd
daemon package while fprintd-pam stays), the shipped storage policy, polkit
(a caller-uid rule stands in), trustlet-side template removal (deletes drop the
name only), and the kernel config change — CONFIG_QCOMTEE, which selects the
SHM bridge — that gates any public image. A claim held by a client that leaves
the bus is dropped.
Runtime dependencies, not carried here
The focal64 trustlet is proprietary and is not in this repo. It is
extracted from the device's own stock Android partition on first boot by the
fp6-vendor-blobs mechanism, the same way the audio firmware is.