Initial commit: the gpfile wire format, pinned by two real containers
fingerprintd will own the FP6's fingerprint sensor: the rail, the QTEE session,
the storage callbacks QTEE makes back into the normal world, and
net.reactivated.Fprint so pam_fprintd and the desktop need no changes. None of
that runs yet. What is here is the first core module and the machinery around
it.
Fingerprintd:Sfs is the gpfile listener's frame -- the callback that carries
47 of 66 storage requests during an enrolment. It is parse, reply and root
mapping only: no file I/O, no TEE, no allocation of the shared buffer. The
daemon shell supplies those, which is what lets every byte-level decision be
tested on a dev box with no phone.
The module exists mainly to hold one fact. READ answers at req+0x00c and WRITE
reads its payload from req+0x110, because the frame is a union: a WRITE still
needs its path while the payload is copied out, so it sits past the 256-byte
path field, while a READ has consumed the path and packs its reply over it.
Conflating them is wrong in both directions with the same symptom -- the
container does not round-trip, QTEE's HMAC check fails, and the file is
unlinked as tampered on the next session.
So the tests do not assert the constants against themselves. They load two real
containers off the phone -- one written correctly, one written with the offsets
conflated -- and re-derive the bug: the broken one opens with ASCII path text
rather than a binary HMAC, that text is the group name from character 8 because
the read offset is 8 bytes into the path field, and the real container sits
exactly 0x104 further in. Then a write-store-read round trip must be the
identity, and the same round trip through a single offset must not be.
O_TRUNC gets a static_assert of its own. QTEE writes a container as
write(0,4096), write(4096,N), write(0,4096), so truncating on open leaves 4096
bytes where a 258850-byte template belongs; it unlinks a file it means to
shorten rather than relying on the opener.
Verified by mutation: conflating the offsets, making DataOffset return the read
offset for writes, and setting O_TRUNC each fail the suite.
2026-09-02 16:02:46 +02:00
|
|
|
# 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
|
2026-09-02 17:34:27 +02:00
|
|
|
packaging/make-sysroot.sh # once; no root, no qemu, no device
|
Initial commit: the gpfile wire format, pinned by two real containers
fingerprintd will own the FP6's fingerprint sensor: the rail, the QTEE session,
the storage callbacks QTEE makes back into the normal world, and
net.reactivated.Fprint so pam_fprintd and the desktop need no changes. None of
that runs yet. What is here is the first core module and the machinery around
it.
Fingerprintd:Sfs is the gpfile listener's frame -- the callback that carries
47 of 66 storage requests during an enrolment. It is parse, reply and root
mapping only: no file I/O, no TEE, no allocation of the shared buffer. The
daemon shell supplies those, which is what lets every byte-level decision be
tested on a dev box with no phone.
The module exists mainly to hold one fact. READ answers at req+0x00c and WRITE
reads its payload from req+0x110, because the frame is a union: a WRITE still
needs its path while the payload is copied out, so it sits past the 256-byte
path field, while a READ has consumed the path and packs its reply over it.
Conflating them is wrong in both directions with the same symptom -- the
container does not round-trip, QTEE's HMAC check fails, and the file is
unlinked as tampered on the next session.
So the tests do not assert the constants against themselves. They load two real
containers off the phone -- one written correctly, one written with the offsets
conflated -- and re-derive the bug: the broken one opens with ASCII path text
rather than a binary HMAC, that text is the group name from character 8 because
the read offset is 8 bytes into the path field, and the real container sits
exactly 0x104 further in. Then a write-store-read round trip must be the
identity, and the same round trip through a single offset must not be.
O_TRUNC gets a static_assert of its own. QTEE writes a container as
write(0,4096), write(4096,N), write(0,4096), so truncating on open leaves 4096
bytes where a 258850-byte template belongs; it unlinks a file it means to
shorten rather than relying on the opener.
Verified by mutation: conflating the offsets, making DataOffset return the read
offset for writes, and setting O_TRUNC each fail the suite.
2026-09-02 16:02:46 +02:00
|
|
|
crafter-build -- --target=aarch64-alpine-linux-musl \
|
2026-09-02 17:34:27 +02:00
|
|
|
--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
|
Initial commit: the gpfile wire format, pinned by two real containers
fingerprintd will own the FP6's fingerprint sensor: the rail, the QTEE session,
the storage callbacks QTEE makes back into the normal world, and
net.reactivated.Fprint so pam_fprintd and the desktop need no changes. None of
that runs yet. What is here is the first core module and the machinery around
it.
Fingerprintd:Sfs is the gpfile listener's frame -- the callback that carries
47 of 66 storage requests during an enrolment. It is parse, reply and root
mapping only: no file I/O, no TEE, no allocation of the shared buffer. The
daemon shell supplies those, which is what lets every byte-level decision be
tested on a dev box with no phone.
The module exists mainly to hold one fact. READ answers at req+0x00c and WRITE
reads its payload from req+0x110, because the frame is a union: a WRITE still
needs its path while the payload is copied out, so it sits past the 256-byte
path field, while a READ has consumed the path and packs its reply over it.
Conflating them is wrong in both directions with the same symptom -- the
container does not round-trip, QTEE's HMAC check fails, and the file is
unlinked as tampered on the next session.
So the tests do not assert the constants against themselves. They load two real
containers off the phone -- one written correctly, one written with the offsets
conflated -- and re-derive the bug: the broken one opens with ASCII path text
rather than a binary HMAC, that text is the group name from character 8 because
the read offset is 8 bytes into the path field, and the real container sits
exactly 0x104 further in. Then a write-store-read round trip must be the
identity, and the same round trip through a single offset must not be.
O_TRUNC gets a static_assert of its own. QTEE writes a container as
write(0,4096), write(4096,N), write(0,4096), so truncating on open leaves 4096
bytes where a 258850-byte template belongs; it unlinks a file it means to
shorten rather than relying on the opener.
Verified by mutation: conflating the offsets, making DataOffset return the read
offset for writes, and setting O_TRUNC each fail the suite.
2026-09-02 16:02:46 +02:00
|
|
|
```
|
|
|
|
|
|
2026-09-02 17:34:27 +02:00
|
|
|
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.
|
|
|
|
|
|
Initial commit: the gpfile wire format, pinned by two real containers
fingerprintd will own the FP6's fingerprint sensor: the rail, the QTEE session,
the storage callbacks QTEE makes back into the normal world, and
net.reactivated.Fprint so pam_fprintd and the desktop need no changes. None of
that runs yet. What is here is the first core module and the machinery around
it.
Fingerprintd:Sfs is the gpfile listener's frame -- the callback that carries
47 of 66 storage requests during an enrolment. It is parse, reply and root
mapping only: no file I/O, no TEE, no allocation of the shared buffer. The
daemon shell supplies those, which is what lets every byte-level decision be
tested on a dev box with no phone.
The module exists mainly to hold one fact. READ answers at req+0x00c and WRITE
reads its payload from req+0x110, because the frame is a union: a WRITE still
needs its path while the payload is copied out, so it sits past the 256-byte
path field, while a READ has consumed the path and packs its reply over it.
Conflating them is wrong in both directions with the same symptom -- the
container does not round-trip, QTEE's HMAC check fails, and the file is
unlinked as tampered on the next session.
So the tests do not assert the constants against themselves. They load two real
containers off the phone -- one written correctly, one written with the offsets
conflated -- and re-derive the bug: the broken one opens with ASCII path text
rather than a binary HMAC, that text is the group name from character 8 because
the read offset is 8 bytes into the path field, and the real container sits
exactly 0x104 further in. Then a write-store-read round trip must be the
identity, and the same round trip through a single offset must not be.
O_TRUNC gets a static_assert of its own. QTEE writes a container as
write(0,4096), write(4096,N), write(0,4096), so truncating on open leaves 4096
bytes where a 258850-byte template belongs; it unlinks a file it means to
shorten rather than relying on the opener.
Verified by mutation: conflating the offsets, making DataOffset return the read
offset for writes, and setting O_TRUNC each fail the suite.
2026-09-02 16:02:46 +02:00
|
|
|
## Status
|
|
|
|
|
|
2026-09-02 22:29:59 +02:00
|
|
|
**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.
|
2026-09-02 17:22:51 +02:00
|
|
|
|
|
|
|
|
| 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 |
|
2026-09-02 22:29:59 +02:00
|
|
|
| `: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 |
|
2026-09-02 17:22:51 +02:00
|
|
|
| `:Store` | the finger name map |
|
2026-09-02 22:29:59 +02:00
|
|
|
| `:Tee` | QTEE service/op numbers, the listener table, the 13-byte CBOR credentials blob |
|
|
|
|
|
| `:Sensor` | the pins, the timings, and the XPU guard |
|
2026-09-02 17:22:51 +02:00
|
|
|
|
|
|
|
|
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
|
2026-09-02 22:29:59 +02:00
|
|
|
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.
|
|
|
|
|
|
2026-09-03 17:46:33 +02:00
|
|
|
**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.
|
|
|
|
|
|
2026-09-02 23:19:24 +02:00
|
|
|
**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.
|
|
|
|
|
|
2026-09-02 22:29:59 +02:00
|
|
|
**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
|
2026-09-02 23:19:24 +02:00
|
|
|
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.
|
Initial commit: the gpfile wire format, pinned by two real containers
fingerprintd will own the FP6's fingerprint sensor: the rail, the QTEE session,
the storage callbacks QTEE makes back into the normal world, and
net.reactivated.Fprint so pam_fprintd and the desktop need no changes. None of
that runs yet. What is here is the first core module and the machinery around
it.
Fingerprintd:Sfs is the gpfile listener's frame -- the callback that carries
47 of 66 storage requests during an enrolment. It is parse, reply and root
mapping only: no file I/O, no TEE, no allocation of the shared buffer. The
daemon shell supplies those, which is what lets every byte-level decision be
tested on a dev box with no phone.
The module exists mainly to hold one fact. READ answers at req+0x00c and WRITE
reads its payload from req+0x110, because the frame is a union: a WRITE still
needs its path while the payload is copied out, so it sits past the 256-byte
path field, while a READ has consumed the path and packs its reply over it.
Conflating them is wrong in both directions with the same symptom -- the
container does not round-trip, QTEE's HMAC check fails, and the file is
unlinked as tampered on the next session.
So the tests do not assert the constants against themselves. They load two real
containers off the phone -- one written correctly, one written with the offsets
conflated -- and re-derive the bug: the broken one opens with ASCII path text
rather than a binary HMAC, that text is the group name from character 8 because
the read offset is 8 bytes into the path field, and the real container sits
exactly 0x104 further in. Then a write-store-read round trip must be the
identity, and the same round trip through a single offset must not be.
O_TRUNC gets a static_assert of its own. QTEE writes a container as
write(0,4096), write(4096,N), write(0,4096), so truncating on open leaves 4096
bytes where a 258850-byte template belongs; it unlinks a file it means to
shorten rather than relying on the opener.
Verified by mutation: conflating the offsets, making DataOffset return the read
offset for writes, and setting O_TRUNC each fail the suite.
2026-09-02 16:02:46 +02:00
|
|
|
|
|
|
|
|
## 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.
|