SouveraineOS/docs/substrate/pam-souveraine-sessiond.md

PAM config for souveraine-sessiond

The fallback PIN lock surface (src/sessiond/auth.rs) calls pam_start("souveraine-sessiond", ...). This file specifies the PAM service config that MUST exist on any device running souveraine-sessiond.

Expected file: /etc/pam.d/souveraine-sessiond

# Souveraine fallback PIN surface — minimal PAM stack.
#
# This file is shipped as root-owned (0644) system config by the OS
# overlay, never by the souveraine crate itself. The daemon links
# libpam directly (no wrapper crate) and uses the setuid unix_chkpwd
# helper via pam_unix, so it works from an unprivileged session process.
#
# The PIN is numeric-only, 1-32 digits. Complexity enforcement lives
# here in PAM, not in the lock surface code.

# Authentication: pam_unix handles the PIN check via unix_chkpwd.
# The `nullok` flag allows empty passwords (device may have no password
# set during initial setup). Remove `nullok` for production deployments
# that require a PIN.
auth        required    pam_unix.so    nullok

# Account: allow all accounts (the session is already established).
account     required    pam_permit.so

# Password: not used (PIN is set through the main session's PAM stack,
# not through this service).
password    required    pam_deny.so

# Session: not used (no session management needed for auth-only).
session     required    pam_permit.so

Lockout policy

pam_unix provides built-in throttling: it sleeps ~2 seconds after each wrong answer. This is the primary brute-force protection for the fallback surface. There is no additional lockout counter in the lock surface code (lock.rs).

For stronger lockout (e.g. 5 failed attempts → 30s cooldown), add pam_faillock before pam_unix:

auth        required    pam_faillock.so    preauth deny=5 unlock_time=30
auth        required    pam_unix.so        nullok
auth        [default=die]  pam_faillock.so  authfail deny=5 unlock_time=30

The lock surface code does not currently display a remaining-attempt counter. If pam_faillock is configured, the lockout message from PAM is logged but not shown to the user (the conv_fn in auth.rs drops info/error messages — it only carries the PIN prompt). This is a known gap; see task #5 in the security hardening tracker.

What NOT to configure

• No pam_permit.so for auth. This would allow any PIN to unlock, defeating the purpose of the fallback surface entirely.
• No pam_fprintd.so. Fingerprint auth is handled by the shell's lock surface (LockContext.qml) using the default login PAM service with pam/fprintd.conf. The fallback surface is PIN-only by design — it exists for when the shell is dead.
• No pam_systemd.so. The fallback surface does not create a login session; it authenticates within the existing session.

Verification

On-device, verify the config exists and is correct:

ls -la /etc/pam.d/souveraine-sessiond
cat /etc/pam.d/souveraine-sessiond

If the file is missing, pam_start will fail with code 4 (PAM_SYSTEM_ERR) and the lock session will not start. The daemon logs this as "lock session failed" and falls back to Idle phase.