Auto-unlock the GNOME login keyring on fingerprint login, without weakening it — the keyring stays password-protected; the password is sealed inside the TPM instead of typed by hand.
git clone https://github.com/dmitriitimoshenko/tpm-keyring-unlock.git
cd tpm-keyring-unlock
./install.shPrints the full plan up front — every package to install, the tss group
change, the exact PAM-file diff(s) it would apply (each backed up
automatically) — and asks for approval exactly once before doing any of it.
The one exception: if you need adding to the tss group (for passwordless
TPM access), that step alone requires a relogin partway through, so the
script stops there and asks you to re-run it once you're back. Your keyring
password itself is typed interactively during sealing — never touches disk
unencrypted, never passed as a command-line argument. See Requirements below
before running it.
GNOME's login keyring is encrypted with your password. Fingerprint auth
(fprintd/libpam-fprintd) only ever answers yes/no — it never produces
the password the keyring needs, so logging in with a fingerprint leaves the
keyring locked. The first app that needs a saved secret (Wi-Fi password,
browser-saved password, a token) triggers a manual "Authentication
required" password prompt.
The two obvious fixes are both bad:
- Blank the keyring password. Removes the prompt, but also removes the only thing protecting saved secrets if your disk isn't encrypted.
- Store the real password in a plain file and feed it in at login. Same problem as above — a plaintext password file gives zero additional protection over no password at all.
Seal the real keyring password inside the TPM, bound to a PCR7 policy (the Secure Boot state). The sealed blob is useless anywhere except this exact machine, in this exact Secure Boot state — pull the disk and it's just ciphertext. On this machine, in its current state, it can be unsealed automatically and fed into the normal keyring-unlock path, whether you logged in with a password or a fingerprint.
This only makes sense if your disk isn't already full-disk-encrypted (if it is, the keyring password mostly duplicates protection you already have from disk encryption, and you may as well just blank it).
Two independent things had to be fixed:
1. A systemd/PAM race that breaks keyring auto-unlock for everyone,
password login included, on distros that pre-start
gnome-keyring-daemon.service via graphical-session-pre.target.
That unit starts the daemon before login/PAM runs. By the time PAM's own
keyring-unlock logic (pam_gnome_keyring.so) tries to create/unlock the
daemon with your password, the systemd-started instance already owns the
D-Bus name and control socket — PAM's attempt just spins up a second,
disconnected daemon instead of unlocking the real one. Masking the unit
(systemctl --user mask gnome-keyring-daemon.socket gnome-keyring-daemon.service) stops the race: PAM's own spawn becomes the
only daemon there ever is. On its own, this already fixes password-login
auto-unlock. If you're hitting the keyring-unlock prompt even with
password logins, this alone might be your whole fix — try it before the
fingerprint-specific pieces below.
2. Fingerprint auth never sets PAM_AUTHTOK, so even with the race
fixed, pam_gnome_keyring.so has nothing to stash.
A small PAM module (pam/pam_tpm_keyring_authtok.c) sits right before
pam_gnome_keyring.so in every login PAM stack that has one. It unseals
the TPM-sealed password (via a root-owned helper script) and sets it as
PAM_AUTHTOK, purely so the next module can use it. It is always auth optional and always returns PAM_IGNORE — it cannot grant or deny login
by itself under any circumstances, including its own failure. If
PAM_AUTHTOK is already set (a real password was typed), it does nothing.
Whatever module actually authenticated you (pam_fprintd.so, pam_unix.so
via a typed password, etc.) remains the sole thing deciding whether login
succeeds.
auth required pam_fprintd.so
auth optional pam_tpm_keyring_authtok.so <- added by this tool
auth optional pam_gnome_keyring.so <- already there by default
This isn't only about a service literally named *fingerprint*. Any
login PAM stack that includes pam_gnome_keyring.so in its auth phase
needs this module if it can ever succeed via something other than a
typed password — including gdm-password itself, the moment you enable
fingerprint system-wide with pam-auth-update --enable fprintd (which
adds pam_fprintd.so to common-auth, included by gdm-password too).
install.sh accounts for this: it patches every /etc/pam.d/ service file
with an auth-phase pam_gnome_keyring.so line, not just ones with
"fingerprint" in the filename.
That's a separate, independent thing — not specific to this tool — and the officially supported way to do it is:
sudo pam-auth-update --enable fprintdThis is a maintainer-shipped profile (/usr/share/pam-configs/fprintd on
Debian/Ubuntu) that adds fingerprint as the first auth method system-wide,
with automatic fallback to your password if it fails or times out. It's
what makes sudo in a terminal, and polkit-gated GUI prompts (installing a
snap from Ubuntu's App Center, GNOME Software, etc.), accept a fingerprint.
If you use this, run (or re-run) install.sh afterward. Enabling
system-wide fingerprint auth means your regular password login screen
(gdm-password) can now also succeed via fingerprint, not just a dedicated
fingerprint option — which reopens the exact PAM_AUTHTOK gap described
above, on a service that isn't named after fingerprints at all.
install.sh looks for every /etc/pam.d/ service with an auth-phase
pam_gnome_keyring.so line and patches all of them for exactly this
reason.
Hard requirements — the tool refuses to proceed without these, they're not optional:
- TPM 2.0 with a resource-manager device (
/dev/tpmrm0) - Secure Boot enabled (PCR7 is meaningless as a lock if Secure Boot is off)
gnome-keyringas your actual secrets backend, with fingerprint login already set up and working (fprintd/libpam-fprintd, enrolled fingerprint) — this tool doesn't set fingerprint auth up, it only fixes what happens to the keyring once fingerprint auth already workstpm2-tools, a C compiler, and PAM development headers —install.shoffers to install these itself on apt/dnf/pacman/zypper systems (see Compatibility below for other package managers)- systemd as your init/session manager (for the
systemctl --user maskstep — see "How it works" part 1)
Everything in this repo was built against, and is directly verified on,
one real machine: Ubuntu, GNOME, GDM, systemd, TPM 2.0, Secure Boot on, no
disk encryption (see JOURNAL.md for the actual test log). Past that,
here's an honest breakdown of what the code does and doesn't account for
— "should work" below means the logic handles it, not that it's been
run there:
Should work, same as the tested setup:
- Any GNOME-based distro using
gnome-keyring+ GDM (Fedora Workstation, Debian, Pop!_OS, etc.) —install.sh's PAM-file detection matches by content (any/etc/pam.d/service with an auth-phasepam_gnome_keyring.soline), not by filename, so it isn't GDM-specific by construction. - Other display managers (LightDM, SDDM, ...) if
gnome-keyringis what actually backs your secrets — same reasoning, detection is content-based. apt,dnf,pacman, andzyppersystems for the dependency-install step.x86_64andaarch64machines for PAM module install-path detection.
Won't work, by design or by architecture mismatch:
- KDE Plasma with KWallet. Different secrets service entirely, not
gnome-keyring— this tool has nothing to attach to. (KDE runninggnome-keyringinstead of KWallet is a different story and should fall under "should work" above.) - No TPM 2.0, or Secure Boot off, or a non-systemd init — hard requirements
above,
install.shchecks and exits cleanly rather than doing something half-working. - Any other package manager (e.g.
apkon Alpine) — dependency auto-install isn't wired up; installtpm2-tools/a C compiler/PAM headers yourself first, the rest ofinstall.shdoesn't care how they got there.
Covered by an automated test suite (see CONTRIBUTING.md), not just code review: apt/
dnf/pacman/zypper dependency install and PAM-directory detection,
each against that distro's real base image; aarch64 PAM-path detection,
cross-built via docker buildx/QEMU; the PAM module's actual
fork/exec/timeout/PAM_AUTHTOK behavior; and — via test/vm/run-vm-test.sh,
a real VM (swtpm + OVMF, real toggleable Secure Boot state) — the actual
require_secure_boot() detection logic in both states, a real bin/seal.sh
tpm-keyring-unseal.shround trip against a real PCR7 policy, that round trip surviving a genuine TPM reset (a real swtpm+qemu process restart, the same trigger as a physical reboot), and two concurrent unseal calls against the same TPM (theflockserialization fix). Still genuinely untested: any TPM implementation other than this one dev machine's fTPM and the software TPM the VM layer uses (real hardware TPMs, especially other vendors' fTPMs, can behave differently under contention — that's exactly what surfaced the concurrent-access bugs inJOURNAL.md), and any non-GDM display manager or real graphical fingerprint login (the VM layer is headless — no GDM, nolibfprint). If you hit something broken on one of these, that's a real bug report, not a "this was never claimed to work" situation — please open an issue.
./uninstall.shReverses each step. Your actual GNOME keyring password is never changed by this tool, so there's nothing to restore there.
What this protects against: someone getting hold of your powered-off laptop and pulling the disk. The sealed secret is worthless off this TPM.
What this does not protect against: anyone with control of your running, logged-in machine (root, or you) can read the sealed secret's decrypted value the same way this tool does — that's inherent to "unlock automatically without asking," not a bug specific to this approach.
If your BIOS Secure Boot settings ever change (enabled/disabled, keys
reset), PCR7 changes and the seal breaks — you'll need to re-run
bin/seal.sh. Routine kernel/driver updates do not affect PCR7 and won't
break it.
- Still prompted after install. Check which PAM service actually
handled your login:
journalctl -b 0 | grep gkr-pam. The service name in brackets (e.g.gdm-password][1234]) tells you which/etc/pam.d/file needs the patch — re-runinstall.sh, it'll find and offer to patch any service it missed. - Worked, then broke after a reboot, and you didn't change anything
PAM-related. Check
journalctl -b 0 | grep -i tpmand trysudo /usr/local/sbin/tpm-keyring-unseal $USER >/dev/null; echo $?— a non-zero exit usually means the TPM's PCR7 changed (a Secure Boot setting changed) and the seal needs redoing:bin/seal.sh. - Worked, then broke after enabling
pam-auth-update --enable fprintd. See "Also want fingerprint for sudo" above — re-runinstall.sh. - Login pauses for several seconds (fingerprint or password) even though
auto-unlock works. The TPM operation this relies on has a fast path and
a slow fallback path; sealed secrets created before that fast path existed
use the slow one until re-sealed. Fix:
bin/seal.sh(choose "Overwrite" when it asks, same password as before). See JOURNAL.md, 2026-08-16, for why this is one-time and safe. install.shrefuses to run, saying it can't determine the Secure Boot state. It checks viamokutil --sb-statefirst, falling back to reading theSecureBootEFI variable directly ifmokutilisn't installed. If neither works (rare — usually means a very locked-down efivarfs or a non-standard firmware setup), installmokutilor confirm Secure Boot is on some other way, then re-run.- Diagnosing anything deeper:
JOURNAL.mdin this repo is the full, warts-and-all investigation log this tool came out of, including two regressions found after this README was first written and exactly how they were root-caused. If you hit something not covered above, it's worth a skim.
MIT — see LICENSE.