1 files changed, 92 insertions, 0 deletions
diff --git a/man/man7/user-session-keyring.7 b/man/man7/user-session-keyring.7
new file mode 100644
index 000000000..d7b633299
--- /dev/null
+++ b/man/man7/user-session-keyring.7
@@ -0,0 +1,92 @@
+.\" Copyright (C) 2014 Red Hat, Inc. All Rights Reserved.
+.\" Written by David Howells (dhowells@redhat.com)
+.\"
+.\" SPDX-License-Identifier: GPL-2.0-or-later
+.\"
+.TH user-session-keyring 7 (date) "Linux man-pages (unreleased)"
+.SH NAME
+user-session-keyring \- per-user default session keyring
+.SH DESCRIPTION
+The user session keyring is a keyring used to anchor keys on behalf of a user.
+Each UID the kernel deals with has its own user session keyring that
+is shared by all processes with that UID.
+The user session keyring has a name (description) of the form
+.I _uid_ses.<UID>
+where
+.I <UID>
+is the user ID of the corresponding user.
+.P
+The user session keyring is associated with the record that
+the kernel maintains for the UID.
+It comes into existence upon the first attempt to access either the
+user session keyring, the
+.BR user\-keyring (7),
+or the
+.BR session\-keyring (7).
+.\" Davis Howells: the user and user-session keyrings are managed as a pair.
+The keyring remains pinned in existence so long as there are processes
+running with that real UID or files opened by those processes remain open.
+(The keyring can also be pinned indefinitely by linking it
+into another keyring.)
+.P
+The user session keyring is created on demand when a thread requests it
+or when a thread asks for its
+.BR session\-keyring (7)
+and that keyring doesn't exist.
+In the latter case, a user session keyring will be created and,
+if the session keyring wasn't to be created,
+the user session keyring will be set as the process's actual session keyring.
+.P
+The user session keyring is searched by
+.BR request_key (2)
+if the actual session keyring does not exist and is ignored otherwise.
+.P
+A special serial number value,
+.BR KEY_SPEC_USER_SESSION_KEYRING ,
+is defined
+that can be used in lieu of the actual serial number of
+the calling process's user session keyring.
+.P
+From the
+.BR keyctl (1)
+utility, '\fB@us\fP' can be used instead of a numeric key ID in
+much the same way.
+.P
+User session keyrings are independent of
+.BR clone (2),
+.BR fork (2),
+.BR vfork (2),
+.BR execve (2),
+and
+.BR _exit (2)
+excepting that the keyring is destroyed when the UID record is destroyed
+when the last process pinning it exits.
+.P
+If a user session keyring does not exist when it is accessed,
+it will be created.
+.P
+Rather than relying on the user session keyring,
+it is strongly recommended\[em]especially if the process
+is running as root\[em]that a
+.BR session\-keyring (7)
+be set explicitly, for example by
+.BR pam_keyinit (8).
+.SH NOTES
+The user session keyring was added to support situations where
+a process doesn't have a session keyring,
+perhaps because it was created via a pathway that didn't involve PAM
+(e.g., perhaps it was a daemon started by
+.BR inetd (8)).
+In such a scenario, the user session keyring acts as a substitute for the
+.BR session\-keyring (7).
+.SH SEE ALSO
+.ad l
+.nh
+.BR keyctl (1),
+.BR keyctl (3),
+.BR keyrings (7),
+.BR persistent\-keyring (7),
+.BR process\-keyring (7),
+.BR session\-keyring (7),
+.BR thread\-keyring (7),
+.BR user\-keyring (7)