PAM_GNOME_KEYRING(8)

💅 pam_gnome_keyring — ok bestie, let me tell you about the Gnome Keyring PAM module

So this is pam_gnome_keyring, a page from the Gnome Keyring PAM Module Manua (that's the manual name, not a typo, it's just how it's spelled there 🫶). It's a PAM module, it's in section 8, and it's about unlocking your Gnome Keyring automatically so you don't have to type your password a million times. Iconic behavior, honestly.

---

✨ NAME ✨

pam_gnome_keyring — automatic unlocking of Gnome Keyring. That's it, that's the whole vibe. 🔑

---

🎀 SYNOPSIS 🎀

pam_gnome_keyring.so

Yep. That's the whole invocation. You just drop that name into your PAM config and the magic happens. No arguments required at the top level, no flags on the module line itself — the options go after it, and we'll get to those. 💅

---

🌸 DESCRIPTION 🌸

Okay so here's the tea ☕ — the Gnome Keyring service module for PAM is a triple threat. It handles three PAM categories:

• authentication (module-type parameter: auth)
• session management (module-type parameter: session)
• password management (module-type parameter: password)

Three whole personalities, one module. Main character energy fr fr. Let's break each one down. 🦋

🔐 Authentication Module

The Gnome Keyring authentication module snags the password that a previous module already got in the PAM stack, and tucks it away for later use. Cute, right? 🎀

But listen — when no password was obtained, this module literally does nothing and returns success. It will never prompt for a password by itself. Never ever. Not its job, not its problem.

Unless otherwise noted, this module returns success. Say it with me: success is the default. ✨

Here are the options you can pass to the authentication module:

• auto_start — the Gnome Keyring daemon gets started if it's not already running, and the login keyring gets unlocked using the password you provided. But if any of that fails, this module returns an error. No pressure or anything. 😭
• *only_if=service* — a comma separated list of services (like gdm,xdm) that this module will actually handle. If your service isn't on the list, the module returns success without doing anything. Basically a VIP list. 💅

🌈 Session Management Module

The session management module is all about starting and ending sessions — the open and the close, the hello and the bye. 👋

Here's how it goes: if the Gnome Keyring daemon isn't running, or no password was stored by the authentication module, this module returns success and we move on. Otherwise? It'll try to unlock the login keyring, and if the unlocking fails, this module returns an error. 😬

And when the session is terminated, if the daemon was started in either module, then that daemon gets terminated too. Clean exits only, bestie. ✨

Options for the session management module:

• auto_start — same as in authentication. But heads up: either the authentication or the session management module must have the auto_start option for the Gnome Keyring daemon to actually get started. Pick one, pick both, just don't pick neither. 🙈
• *only_if=service* — list of services to handle. Same VIP-list situation as above. 🎟️

🔑 Password Management Module

The password module is the one that lets you change the password for the login keyring. Very glow-up of it. 💖

Rules of the game:

• If no old password was obtained by a previous module in the stack, this module is just ignored. Not today. 💀
• On the flip side, when no new password was obtained, this module will prompt for one. It's gotta have it.

The Gnome Keyring daemon gets started if it's not already running — and it gets stopped after concluding the operation if it wasn't running before. Tidy! 🧹

Options for the password management module:

• auto_start — keep the daemon running even when it was started by this module. You started it, but it stays. Queen behavior. 👑
• *only_if=service* — list of services to handle. Yes, again. Consistency is key. 🗝️
• use_authtok — do not prompt for a new password. And if it's not provided? Return error. That's the deal, no negotiation. 🚨

---

🗂️ FILES 🗂️

• $HOME/.local/share/keyrings/login.keyring — the encrypted login keyring. That's the little vault. 💜

---

🧚 EXAMPLES 🧚

Okay, practical time, because this is where it all clicks. 🤩

Here's the example of the file /etc/pam.d/gdm, which configures the gdm service to use standard UNIX authentication plus start and unlock Gnome Keyring. The rest of the configuration is inherited from the login service configuration. Slay, inheritance.

auth       required     pam_unix.so
auth       optional     pam_gnome_keyring.so
account    include      login
session    include      login
session    optional     pam_gnome_keyring.so auto_start
password   include      login

And here's the example of the file /etc/pam.d/passwd, which configures the passwd program to update the keyring password right along with the user's system password. Two birds, one password change. 🐦🐦

password   required     pam_unix.so
password   optional     pam_gnome_keyring.so

---

⚠️ NOTES ⚠️

Real talk, bestie — Gnome Keyring implements its own SSH agent, so you should not stack it with pam_ssh for session management. Just don't. They would fight. 💀

---

👀 SEE ALSO 👀

pam.conf(5), pam.d(5), pam(8), auditctl(8), auditd(8) — go read those too, expanding your knowledge is always a vibe. 📚✨

---

💌 AUTHOR 💌

pam_gnome_keyring was written by Stef Walter <stef@thewalter.net>. Legend behavior. 👑🌸

---

Okay that's the whole page, you made it!! 🎉 This was the Gnome Keyring PAM Module Manua, PAM_GNOME_KEYRING(8), and it's giving "your keyring unlocks itself now" energy. Go forth and never type that password twice. 💖✨🫶