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.
|
|
|
|
|
|
|
|
|
|
`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
|
|
|
|
|
|
packaging, ci: build the apk with the Crafter.Build Flatpak
Crafter.Build's releases carry a Flatpak and nothing else since
2026-10-02 (imsd a625248): the rolling `latest` release's
crafter-build-linux-x86_64-musl-v2.tar.gz that build-package.sh fetched
is gone, so the push of 0.2.6 failed at `fetch crafter-build` (run 10,
2026-10-14, three 404s) and published nothing; the registry still
serves 0.2.5.
The move imsd made on 2026-10-04: install the Flatpak
(net.catcrafts.CrafterBuild//stable from flatpak.catcrafts.net) in the
job container and run it as crafter-build. bubblewrap inside the
container needs a privileged runner, so the job runs on the `flatpak`
label. The host keeps clang and llvm-ar for libqcomtee, which
make-libqcomtee.sh compiles against the sysroot; the daemon's compiler,
lld and libc++ are the Flatpak's, so the host packages that served the
native test-suite run go. The sysroot gains llvm-runtimes, the package
with the std module source of its own libc++ (libc++-dev ships none),
added with --upgrade so a sysroot from before this change comes out
with a matching libc++ and source. The README's Build section carries
the install lines.
Tested: build-package.sh run end to end on this commit in a privileged
alpine:edge container (podman) on the workstation: crafter-build 2.1.0
(clang 23.1.2) from `stable`, the sysroot at libc++ and llvm-runtimes
23.1.3, daemon and agent cross-built, 8 suites passed natively, the
three apks built, the daemon an aarch64 PIE against the sysroot's musl
and libc++ (65 s). The rehearsed copy differs from this commit by the
wrapping of one comment line.
2026-10-14 02:32:30 +02:00
|
|
|
With the [Crafter Build](https://forgejo.catcrafts.net/Catcrafts/Crafter.Build)
|
|
|
|
|
Flatpak, which carries the compiler:
|
|
|
|
|
|
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
|
|
|
```sh
|
packaging, ci: build the apk with the Crafter.Build Flatpak
Crafter.Build's releases carry a Flatpak and nothing else since
2026-10-02 (imsd a625248): the rolling `latest` release's
crafter-build-linux-x86_64-musl-v2.tar.gz that build-package.sh fetched
is gone, so the push of 0.2.6 failed at `fetch crafter-build` (run 10,
2026-10-14, three 404s) and published nothing; the registry still
serves 0.2.5.
The move imsd made on 2026-10-04: install the Flatpak
(net.catcrafts.CrafterBuild//stable from flatpak.catcrafts.net) in the
job container and run it as crafter-build. bubblewrap inside the
container needs a privileged runner, so the job runs on the `flatpak`
label. The host keeps clang and llvm-ar for libqcomtee, which
make-libqcomtee.sh compiles against the sysroot; the daemon's compiler,
lld and libc++ are the Flatpak's, so the host packages that served the
native test-suite run go. The sysroot gains llvm-runtimes, the package
with the std module source of its own libc++ (libc++-dev ships none),
added with --upgrade so a sysroot from before this change comes out
with a matching libc++ and source. The README's Build section carries
the install lines.
Tested: build-package.sh run end to end on this commit in a privileged
alpine:edge container (podman) on the workstation: crafter-build 2.1.0
(clang 23.1.2) from `stable`, the sysroot at libc++ and llvm-runtimes
23.1.3, daemon and agent cross-built, 8 suites passed natively, the
three apks built, the daemon an aarch64 PIE against the sysroot's musl
and libc++ (65 s). The rehearsed copy differs from this commit by the
wrapping of one comment line.
2026-10-14 02:32:30 +02:00
|
|
|
flatpak remote-add --if-not-exists flathub https://dl.flathub.org/repo/flathub.flatpakrepo
|
|
|
|
|
flatpak remote-add --if-not-exists catcrafts https://flatpak.catcrafts.net/catcrafts.flatpakrepo
|
|
|
|
|
flatpak install catcrafts net.catcrafts.CrafterBuild//stable
|
|
|
|
|
alias crafter-build='flatpak run net.catcrafts.CrafterBuild//stable'
|
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 # bin/fingerprintd-<target>-<march>/fingerprintd
|
|
|
|
|
crafter-build test # the unit suites
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
Cross-compiling for the phone:
|
|
|
|
|
|
|
|
|
|
```sh
|
2026-09-05 22:35:23 +02:00
|
|
|
packaging/make-sysroot.sh
|
2026-09-05 23:06:57 +02:00
|
|
|
crafter-build -- --target=aarch64-alpine-linux-musl --sysroot=~/.cache/fingerprintd/sysroot-aarch64-alpine --march=armv8.6-a+fp16fml+aes+sha3+sm4 --mtune=cortex-a720
|
|
|
|
|
crafter-build test --target=aarch64-alpine-linux-musl --sysroot=~/.cache/fingerprintd/sysroot-aarch64-alpine --march=armv8.6-a+fp16fml+aes+sha3+sm4 --mtune=cortex-a720
|
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-05 19:58:35 +02:00
|
|
|
Verified on the device: all five suites pass cross-built and run on the phone
|
|
|
|
|
itself, not only under emulation.
|
2026-09-02 17:34:27 +02:00
|
|
|
|
2026-09-02 22:29:59 +02:00
|
|
|
```
|
|
|
|
|
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
|
|
|
|
|
```
|
|
|
|
|
|
standby unlock: a locked session unlocks by finger without PAM
Phosh's lock screen cannot take a fingerprint: its PAM conversation
answers every prompt with the password. So the daemon follows the seat
session that is locked and in front (logind LockedHint + Active), runs a
verify of its own while the display is on (backlight bl_power), and
answers a match with logind's Session.Unlock.
Only fingers named in that session owner's map unlock. The map is
re-read at every arm and verdict, and a delete cancels a running standby
verify, so a finger deleted while locked stops counting at once. A
verdict from an earlier lock or another session is dropped. no-unlock
rules and FingerMatched apply as for a client match. A client Claim
cancels standby, and its Release, or a claim that fails while pending,
re-arms it. --standby-unlock=off disables it.
Tested on the dev phone before the review fixes (map re-read,
front-session tracking, cancel ordering, pending-claim re-arm): under
Phosh, six unlocks by two fingers and an unnamed template refused; under
Plasma, kscreenlocker's pam_fprintd unlocks while standby yields and
re-arms. With the fixes: suites 8/8, and a daemon restart under a lock
screen picks the locked session up. Not exercised: standby's own
Session.Unlock on kscreenlocker, user switching.
2026-09-23 16:56:06 +02:00
|
|
|
## Lock-screen unlock
|
|
|
|
|
|
|
|
|
|
Two routes, both on by default:
|
|
|
|
|
|
|
|
|
|
- **PAM.** The daemon provides `fprintd`, so a lock screen that runs
|
|
|
|
|
`pam_fprintd` beside its password prompt unlocks by finger the usual way.
|
|
|
|
|
Plasma's does (`kde-fingerprint`; the `fingerprint-auth` and `postlogin`
|
|
|
|
|
services it needs are shipped here). Phosh's cannot: its PAM conversation
|
|
|
|
|
answers every prompt with the password, so a fingerprint module in its stack
|
|
|
|
|
would only stall the password behind the fingerprint timeout.
|
|
|
|
|
- **Standby.** While the session in front on its seat is locked and the
|
|
|
|
|
display is on, the daemon runs a verify of its own and answers a match with
|
|
|
|
|
logind's `Session.Unlock`, which Phosh honours. No verify runs while the
|
|
|
|
|
display is off (an open verify polls the sensor at ~5 Hz; the display state
|
|
|
|
|
comes from the backlight's `bl_power` or the panel's DRM `dpms`, and a
|
|
|
|
|
device with neither is treated as always on). Any fprintd client takes
|
|
|
|
|
precedence: a `Claim` cancels the standby verify, a `Release` re-arms it.
|
|
|
|
|
Only fingers named in that session owner's map unlock, and the map is
|
|
|
|
|
re-read at every arm, so a finger deleted while locked stops counting at
|
|
|
|
|
once. Per-finger `no-unlock` rules apply here too, and every match is
|
|
|
|
|
announced as `FingerMatched` for the session agent. `--standby-unlock=off`
|
|
|
|
|
disables it.
|
|
|
|
|
|
2026-09-06 13:56:44 +00:00
|
|
|
## Runtime dependencies
|
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-05 19:58:35 +02:00
|
|
|
The `focal64` trustlet is proprietary and is not in this repo. It is
|
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
|
|
|
extracted from the device's own stock Android partition on first boot by the
|
2026-09-06 13:56:44 +00:00
|
|
|
`fp6-vendor-blobs` mechanism, the same way other firmware in fp6-img is.
|
2026-09-05 19:58:09 +02:00
|
|
|
|
2026-10-13 22:05:35 +02:00
|
|
|
## Releases
|
|
|
|
|
|
|
|
|
|
Every push to `main` is built and tested by CI, which then publishes the
|
|
|
|
|
apks to the Forgejo Alpine registry that installed phones already point at.
|
|
|
|
|
CI treats the registry's "already published" answer as nothing to do, so a
|
|
|
|
|
push publishes only a package version new to the registry. The package
|
|
|
|
|
version is `pkgver-rpkgrel`: `pkgver` is the `Version` constant in
|
|
|
|
|
`interfaces/Fingerprintd.cppm`, `pkgrel` is the APKBUILD's and stays at 0.
|
|
|
|
|
An installed phone picks a published version up with plain `apk upgrade`.
|
|
|
|
|
|
|
|
|
|
From 0.2.6 on, a release is a range of commits ending in a bump commit
|
|
|
|
|
titled `fingerprintd X.Y.Z` that changes only the version: the constant and
|
|
|
|
|
the APKBUILD's `pkgver`. Each release is tagged `vX.Y.Z` on its bump commit
|
|
|
|
|
(signed, annotated) with the release notes as the tag message, and
|
|
|
|
|
published as a Forgejo release of the same name and text. No version
|
|
|
|
|
before 0.2.6 has a tag or release notes. The notes are written for the
|
|
|
|
|
people whose phones will upgrade:
|
|
|
|
|
|
|
|
|
|
```
|
|
|
|
|
fingerprintd X.Y.Z
|
|
|
|
|
|
|
|
|
|
## New
|
|
|
|
|
|
|
|
|
|
- **What a user can now do.** One bullet per change, the most important
|
|
|
|
|
first, with anything the user has to do inside the bullet.
|
|
|
|
|
|
|
|
|
|
## Fixes
|
|
|
|
|
|
|
|
|
|
- **What went wrong, in the user's terms.** What they saw, what changes,
|
|
|
|
|
what to do.
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
A section with nothing in it is left out, and so is behaviour the release
|
|
|
|
|
does not change. Versioning, from 0.2.6 on, is `MAJOR.MINOR.PATCH`: the
|
|
|
|
|
patch number counts releases, fixes and features alike; the minor number
|
|
|
|
|
moves when a release changes what a user can rely on the daemon for; the
|
|
|
|
|
major number moves when a release changes what an installed phone does
|
|
|
|
|
without being asked.
|
|
|
|
|
|
2026-09-05 19:58:09 +02:00
|
|
|
## License
|
|
|
|
|
|
|
|
|
|
GPL-3.0-only, see LICENSE.
|
|
|
|
|
|
|
|
|
|
## Copyright
|
|
|
|
|
|
|
|
|
|
Copyright (C) 2026 Catcrafts® catcrafts.net
|