# 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.

```
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.

## Per-finger macros

The trustlet reports *which* finger matched, so a finger can mean more than
"it was you". Two files, in two trust domains:

- **`~/.config/fingerprintd/fingers.conf`** runs a command as you, in your
  session. This is how a finger opens an application.
- **`/etc/fingerprintd/actions.conf`** runs a command as root, and can mark a
  finger as one that never unlocks.

### In your session: `fingers.conf`

```
# ~/.config/fingerprintd/fingers.conf
right-ring-finger    kde-open camera
left-index-finger    plasma-settings
left-thumb           sh -c 'notify-send "hello from a finger"'
```

- using these requires the fingerprintd-agent service to be running.

### As root: `actions.conf`

```
# /etc/fingerprintd/actions.conf
# <finger>  [no-unlock]  [absolute command...]
right-ring-finger    /usr/local/bin/toggle-something
left-little-finger   no-unlock  /etc/fingerprintd/panic.sh
left-thumb           no-unlock
```

- `no-unlock`: the finger matches and the client is told it did not. PAM
  sees `verify-no-match`, the standby unlock stays locked. The command, if
  there is one, runs regardless.
- the command: an absolute path, run by root through `/bin/sh -c` with a
  fixed `PATH` and `FINGERPRINTD_FINGER` set to the finger's name, detached
  from the daemon with its stdio on `/dev/null`, so it may block or reboot
  the phone without stalling the sensor.
- a line needs at least one of the two, and a finger gets at most one line.
- editing this file requires a restart of the fingerprintd service before changes take effect.


## 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.


## License

GPL-3.0-only, see LICENSE.

## Copyright

Copyright (C) 2026 Catcrafts® catcrafts.net