1 files changed, 113 insertions, 0 deletions
diff --git a/man/man7/session-keyring.7 b/man/man7/session-keyring.7
new file mode 100644
index 000000000..d54007ee1
--- /dev/null
+++ b/man/man7/session-keyring.7
@@ -0,0 +1,113 @@
+.\" 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 session-keyring 7 (date) "Linux man-pages (unreleased)"
+.SH NAME
+session-keyring \- session shared process keyring
+.SH DESCRIPTION
+The session keyring is a keyring used to anchor keys on behalf of a process.
+It is typically created by
+.BR pam_keyinit (8)
+when a user logs in and a link will be added that refers to the
+.BR user\-keyring (7).
+Optionally,
+.BR PAM (7)
+may revoke the session keyring on logout.
+(In typical configurations, PAM does do this revocation.)
+The session keyring has the name (description)
+.IR _ses .
+.P
+A special serial number value,
+.BR KEY_SPEC_SESSION_KEYRING ,
+is defined that can be used in lieu of the actual serial number of
+the calling process's session keyring.
+.P
+From the
+.BR keyctl (1)
+utility, '\fB@s\fP' can be used instead of a numeric key ID in
+much the same way.
+.P
+A process's session keyring is inherited across
+.BR clone (2),
+.BR fork (2),
+and
+.BR vfork (2).
+The session keyring
+is preserved across
+.BR execve (2),
+even when the executable is set-user-ID or set-group-ID or has capabilities.
+The session keyring is destroyed when the last process that
+refers to it exits.
+.P
+If a process doesn't have a session keyring when it is accessed, then,
+under certain circumstances, the
+.BR user\-session\-keyring (7)
+will be attached as the session keyring
+and under others a new session keyring will be created.
+(See
+.BR user\-session\-keyring (7)
+for further details.)
+.SS Special operations
+The
+.I keyutils
+library provides the following special operations for manipulating
+session keyrings:
+.TP
+.BR keyctl_join_session_keyring (3)
+This operation allows the caller to change the session keyring
+that it subscribes to.
+The caller can join an existing keyring with a specified name (description),
+create a new keyring with a given name,
+or ask the kernel to create a new "anonymous"
+session keyring with the name "_ses".
+(This function is an interface to the
+.BR keyctl (2)
+.B KEYCTL_JOIN_SESSION_KEYRING
+operation.)
+.TP
+.BR keyctl_session_to_parent (3)
+This operation allows the caller to make the parent process's
+session keyring to the same as its own.
+For this to succeed, the parent process must have
+identical security attributes and must be single threaded.
+(This function is an interface to the
+.BR keyctl (2)
+.B KEYCTL_SESSION_TO_PARENT
+operation.)
+.P
+These operations are also exposed through the
+.BR keyctl (1)
+utility as:
+.P
+.in +4n
+.EX
+keyctl session
+keyctl session \- [<prog> <arg1> <arg2> ...]
+keyctl session <name> [<prog> <arg1> <arg2> ...]
+.EE
+.in
+.P
+and:
+.P
+.in +4n
+.EX
+keyctl new_session
+.EE
+.in
+.SH SEE ALSO
+.ad l
+.nh
+.BR keyctl (1),
+.BR keyctl (3),
+.BR keyctl_join_session_keyring (3),
+.BR keyctl_session_to_parent (3),
+.BR keyrings (7),
+.BR PAM (7),
+.BR persistent\-keyring (7),
+.BR process\-keyring (7),
+.BR thread\-keyring (7),
+.BR user\-keyring (7),
+.BR user\-session\-keyring (7),
+.BR pam_keyinit (8)