- C++ 88.6%
- Shell 11.4%
| Filename | Latest commit message | Latest commit date |
|---|---|---|
Jorijn van der Graaf
c785aad653
A three-tap enrolment declared itself complete. The transcript says why:
frame 2: metric=308 FINGER ev5 rem=10
frame 3: metric=187 ev6 rem=0
samples: 10 of 10 accepted
The release event never enters do_enroll, so its response leaves
samples-remaining untouched at 0 -- which is indistinguishable from "none
remaining, you are finished". The session believed it, stopped after one press,
and called SAVE_DATA on an algorithm holding no template. That answered -1 and
wrote nothing, so the store was undamaged, but only by luck: the guard meant to
prevent a partial save was itself satisfied by the bogus count.
A reading is only meaningful when it came from the event that runs the enrol
path, and nothing about the value says so -- the caller has to. Observe now
takes that as an argument. Two further guards: a FIRST reading of 0 is an
unpopulated field rather than a finished enrolment, and the count only ever
falls, so an increase is noise.
Verified by mutation: trusting the release event's count, and accepting a
leading zero, each fail the suite.
|
||
| 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
The core is complete; the daemon does not run yet. Everything was ported
out of the research harness that first made the sensor work (utilities/fpta.c
in the fp6 repo), one module at a time, each landing with its tests before the
next started.
| 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_DATA masks, enrol/auth payloads, the error table, the verdict rule |
:Engine |
baseline calibration, touch edges, enrolment progress, and the accounting |
:Store |
the finger name map |
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: two SFS containers off the phone, and three recorded authentication runs.
Next is the I/O shell — the TEE session, the sensor rail, the RPMB device and the bus — which is the first part that cannot be validated without hardware.
The working reference enrols a finger, keeps it across a reboot, and matches it with zero false accepts; the port exists to turn that into a service rather than to rediscover it.
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.