Catcrafts/fingerprintd
Watch
2
0
Fork
You've already forked fingerprintd
 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
fingerprintd/README.md

123 lines
5.8 KiB
Markdown
Raw Normal View History

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
Add the cross-build sysroot recipe, verified on the device packaging/make-sysroot.sh populates a minimal Alpine aarch64 rootfs with apk-tools-static, so a cross build needs no root, no qemu and no phone. Adapted from imsd's, plus glib-dev for the bus layer that is coming. Building against a real Alpine sysroot means the binary links dynamically against the phone's own musl and libc++ -- libc++, libc++abi, libunwind and libgcc_s are all already on pmOS. The harness this daemon replaces had to be built -static, but only because it was built with the host's glibc toolchain; that constraint was never about the target. The pipeline is proven end to end rather than assumed: the cross-built binary runs on the phone, and all five core suites pass there too -- on the real hardware, not just under qemu-aarch64. That matters for modules that are almost entirely little-endian field packing and offset arithmetic.
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 \
Add the cross-build sysroot recipe, verified on the device packaging/make-sysroot.sh populates a minimal Alpine aarch64 rootfs with apk-tools-static, so a cross build needs no root, no qemu and no phone. Adapted from imsd's, plus glib-dev for the bus layer that is coming. Building against a real Alpine sysroot means the binary links dynamically against the phone's own musl and libc++ -- libc++, libc++abi, libunwind and libgcc_s are all already on pmOS. The harness this daemon replaces had to be built -static, but only because it was built with the host's glibc toolchain; that constraint was never about the target. The pipeline is proven end to end rather than assumed: the cross-built binary runs on the phone, and all five core suites pass there too -- on the real hardware, not just under qemu-aarch64. That matters for modules that are almost entirely little-endian field packing and offset arithmetic.
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
```
Add the cross-build sysroot recipe, verified on the device packaging/make-sysroot.sh populates a minimal Alpine aarch64 rootfs with apk-tools-static, so a cross build needs no root, no qemu and no phone. Adapted from imsd's, plus glib-dev for the bus layer that is coming. Building against a real Alpine sysroot means the binary links dynamically against the phone's own musl and libc++ -- libc++, libc++abi, libunwind and libgcc_s are all already on pmOS. The harness this daemon replaces had to be built -static, but only because it was built with the host's glibc toolchain; that constraint was never about the target. The pipeline is proven end to end rather than assumed: the cross-built binary runs on the phone, and all five core suites pass there too -- on the real hardware, not just under qemu-aarch64. That matters for modules that are almost entirely little-endian field packing and offset arithmetic.
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
README: it works end to end through fprintd's own clients
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.
README: the core is complete
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 |
README: it works end to end through fprintd's own clients
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 |
README: the core is complete
2026-09-02 17:22:51 +02:00
| `:Store` | the finger name map |
README: it works end to end through fprintd's own clients
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 |
README: the core is complete
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
README: it works end to end through fprintd's own clients
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.
**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), cleanup when a claiming client vanishes from the bus, and the
kernel config change — `CONFIG_QCOMTEE`, which selects the SHM bridge — that
gates any public image.
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.
Reference in a new issue Copy permalink