USER-SESSION-KEYRING(7)

💖 USER-SESSION-KEYRING 💖

okay bestie so the manual name is user-session-keyring(7) and it lives in the Miscellaneous Information Manual, and no cap, it is genuinely one of the most "wait what is my kernel even doing" pages out there. sit down, get cozy 🫶

---

✨ NAME ✨

user-session-keyring — the per-user default session keyring 👑

---

🌸 DESCRIPTION 🌸

so. the user session keyring is a keyring, and its whole job is anchoring keys on behalf of a user. like it's the little home base for your keys, bestie. 🏠

every single UID the kernel deals with gets its own user session keyring, and — this is the important part — it's shared by all processes with that UID. not per-process, not per-thread. one UID, one vibe. 💅

it has a name (description, same thing) that looks like this:

_uid_ses.<UID>

where <UID> is literally just the user ID of the corresponding user. so if you're UID 1000, your keyring is _uid_ses.1000. iconic. 🎀

the user session keyring is associated with the record that the kernel maintains for the UID. and the way it comes into existence? not at boot, not on login — it shows up upon the first attempt to access any of:

• the user session keyring itself
• the user-keyring(7)
• the session-keyring(7)

(three doors, same room. iykyk 🌈)

and then it stays pinned in existence for as long as there are either (a) processes running with that real UID, or (b) files opened by those processes that remain open. also, side note: it can be pinned indefinitely if you link it into another keyring. so it can outlive basically everything if you want it to. main character energy fr fr. 👑

the creation story goes like this: it's created on demand when a thread requests it, OR when a thread asks for its session-keyring(7) and that session keyring doesn't exist. in that second case, a user session keyring gets created, and here's the spicy bit — if the session keyring wasn't to be created, then the user session keyring gets set as the process's actual session keyring. sneaky little substitution, love that for it. 🦋

who talks to it? request_key(2) searches it, but ONLY if the actual session keyring does not exist. if the actual session keyring does exist, then request_key(2) ignores the user session keyring entirely. read that again, it matters. 🙈

there's also a special serial number value for when you don't have the real serial number handy:

KEY_SPEC_USER_SESSION_KEYRING

throw that in in lieu of the actual serial number of the calling process's user session keyring. and if you're in the keyctl(1) utility, you can just use @us instead of a numeric key ID — same idea, way less typing, so slay. ✨

now, the independence era: user session keyrings are independent of clone(2), fork(2), vfork(2), execve(2), and _exit(3) — with the one exception that the keyring gets destroyed when the UID record is destroyed, which happens when the last process pinning it exits. that's the whole exception. everything else just doesn't touch it. periodt. 💜

oh and also, if a user session keyring does not exist when it is accessed? it will be created. yes, again. it's very "if you build it they will come" but in reverse, it builds itself the second you look at it 👀

⚠️ real talk bestie, please read this one: rather than relying on the user session keyring, it is strongly recommended — especially if the process is running as root — that a session-keyring(7) be set explicitly, for example by pam_keyinit(8). this is not a suggestion, this is the "please do not ship root with vibes only" warning. 🙏

---

📝 NOTES 📝

why does this thing even exist, you ask? great question, bestie.

the user session keyring was added to support situations where a process doesn't have a session keyring — perhaaaps because it was created via a pathway that didn't involve PAM (for example, maybe it was a daemon started by inetd(8)). yeah. that kind of process. no PAM, no session keyring, just existential dread and sockets. 💀

in such a scenario, the user session keyring acts as a substitute for the session-keyring(7). it's the understudy who goes on every single night. it's holding it down. 🎭

---

🔗 SEE ALSO 🔗

• keyctl(1)
• keyctl(3)
• keyrings(7)
• persistent-keyring(7)
• process-keyring(7)
• session-keyring(7)
• thread-keyring(7)
• user-keyring(7)

the whole keyring cinematic universe, honestly. go read all of them. 🌈⭐

---

and that's the page!! 💖 thanks for coming to my ted talk, this one shipped as part of Linux man-pages 6.20, dated 2026-06-05 — go forth and keyctl responsibly, bestie 🎀✨🫶