Jorijn van der Graaf
59f1ac8bc0
The repository had no written release procedure: four versions were published through CI with no tag and no notes, and the next one was about to go the same way. This is imsd's shape, in the README because there is no AGENTS.md here: a push releases when the version changes, the range ends in a bump commit, the bump commit carries a signed tag with the release notes, and the notes are a Forgejo release.
110 lines
No EOL
4.6 KiB
Markdown
110 lines
No EOL
4.6 KiB
Markdown
# 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
|
|
|
|
```sh
|
|
crafter-build # bin/fingerprintd-<target>-<march>/fingerprintd
|
|
crafter-build test # the unit suites
|
|
```
|
|
|
|
Cross-compiling for the phone:
|
|
|
|
```sh
|
|
packaging/make-sysroot.sh
|
|
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
|
|
```
|
|
|
|
Verified on the device: all five suites pass cross-built and run on the phone
|
|
itself, not only under emulation.
|
|
|
|
```
|
|
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
|
|
```
|
|
|
|
## 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.
|
|
|
|
## Runtime dependencies
|
|
|
|
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 other firmware in fp6-img is.
|
|
|
|
## 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.
|
|
|
|
## License
|
|
|
|
GPL-3.0-only, see LICENSE.
|
|
|
|
## Copyright
|
|
|
|
Copyright (C) 2026 Catcrafts® catcrafts.net |