Jorijn van der Graaf
c5fc3afc77
Learning rewrites the template on every matched press, so run two is not a
repeat of run one and an A/B against a moving template is not an A/B. The order
is the measurement:
enrol a fresh template at 20 samples with no position prompts, which is also
the outstanding replication of the best result this lane has seen
base learning off: the clean number for that template, and the only figure
comparable to every rate already recorded
trend learning on, three times: the rate should climb, with the container
size as an independent witness that it is the template moving
A rate that climbs while the body grows is learning. A rate that moves while the
body does not is noise, and the daemon's own learn: lines say which. Run one of
the trend is not evidence that learning helped; it starts on the template the
baseline ended on.
One limit the script states rather than letting someone discover it: learning
only fires on a press that matched, so a template that never matches never
improves. That is why the protocol re-enrols instead of building on a template
already measured at 0 of 10.
158 lines
8.1 KiB
Markdown
158 lines
8.1 KiB
Markdown
# 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`, so
|
|
`pam_fprintd`, the Plasma fingerprint KCM and `fprintd-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
|
|
|
|
```sh
|
|
crafter-build # bin/fingerprintd-<target>-<march>/fingerprintd
|
|
crafter-build test # the unit suites
|
|
```
|
|
|
|
Cross-compiling for the phone:
|
|
|
|
```sh
|
|
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.
|
|
|
|
**Template learning.** Stock rewrites the stored template on every successful
|
|
press — `0x1015 UPDATE_TEMPLATE` while the finger is still down, then a deferred
|
|
`SAVE_DATA` — and the stored body measurably grows over a template's life
|
|
(333278 bytes at enrolment to 371734 after one authentication session on the
|
|
reference device). This daemon does the same as of 0.1.0. It matters more than
|
|
any tuning knob: before it, every match rate measured against this device was
|
|
measured against a day-zero template that no stock user lives with.
|
|
|
|
The harvest sends no event, so the matcher does not re-run and a verdict cannot
|
|
be revised by it. A quick tap pays almost nothing, because the finger is gone by
|
|
the time a verdict lands; a held press contributes the frames it was held for —
|
|
which means the frames learned from are, by construction, frames from real
|
|
unlock presses. The save is deferred until after the verdict reaches the client,
|
|
because ~350 ms of RPMB traffic does not belong on an unlock path; stock defers
|
|
it the same way. `--learn=0` turns the whole thing off so the comparison can be
|
|
made on one binary, which is the only way it is single-variable.
|
|
|
|
**Reading the trustlet.** There is no `tzdbg` on mainline, but focal64 writes
|
|
its log into the response buffer, so `--ta-log` surfaces the matcher's own
|
|
verdicts (`auth success score`, `identify fail! FtVerifyByTemplate() = -2`, the
|
|
per-frame `image quality / coverage / humidity`). The log ring is ~150 lines per
|
|
session and is never reset, so the config dump alone can overflow it: the
|
|
shipped verbose config leaves the framework log off to reserve the ring for the
|
|
algorithm. Lower levels are more verbose and 6 is off.
|
|
|
|
**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.
|