session-keyring.7: Various reworking and additions

Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>

man7/session-keyring.7

@@ -16,64 +16,83 @@ session-keyring \- session shared process keyring
 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
+when a user logs in and a link will be added that refers to the
-added that refers to the
 .BR user-keyring (7).
-.P
+
-A special serial number value, \fBKEY_SPEC_SESSION_KEYRING\fP, is defined that
+A special serial number value,
-can be used in lieu of the calling process's session keyring's actual serial
+.BR KEY_SPEC_SESSION_KEYRING ,
-number.
+is defined that can be used in lieu of the actual serial number of
-.P
+the calling process's session keyring.
-From the keyctl utility, '\fB@s\fP' can be used instead of a numeric key ID in
+
+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)
+.BR vfork (2).
-and
+The session keyring
-is retained across
+is preserved across
-.BR execve (2)
+.BR execve (2),
-- even when the target executable is setuid or
+even when the executable is set-user-ID or set-group-ID or has capabilities.
-setgid.
+The session keyring is destroyed when the last process that
-The session keyring will be 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
+If a process doesn't have a session keyring when it is accessed, then,
-certain circumstances, the \fBuser session keyring\fR will be attached as the
+under certain circumstances, the
-session keyring and under others a new session keyring will be created.
+.BR user-session-keyring (7)
+will be attached as the session keyring
+and under others a new session keyring will be created.
 .SS Special operations
-The keyutils library provides a number of special operations for manipulating
+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 their session keyring.
+This operation allows the caller to change the session keyring
-The caller can join an existing keyring by name,
+that it subscribes to.
-create a new keyring of the name given or
+The caller can join an existing keyring with a specified name (description),
-ask the kernel to create a new session keyring with the name "_ses".
+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 set the parent process's session keyring to
+This operation allows the caller to make the parent process's
-the same as their own.
+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.
-.P
+(This function is an interface to the
-These operations are also exposed through the keyctl utility as:
+.BR keyctl (2)
-.P
+.B KEYCTL_SESSION_TO_PARENT
-.RS
+operation.)
-\fBkeyctl\fP session
+.PP
-.br
+These operations are also exposed through the
-\fBkeyctl\fP session - [<prog> <arg1> <arg2> ...]
+.BR keyctl (1)
-.br
+utility as:
-\fBkeyctl\fP session <name> [<prog> <arg1> <arg2> ...]
+
-.RE
+.nf
-.P
+.in +4n
+keyctl session
+keyctl session - [<prog> <arg1> <arg2> ...]
+keyctl session <name> [<prog> <arg1> <arg2> ...]
+.in
+.fi
+
 and:
-.P
+
-.RS
+.nf
-\fBkeyctl\fP new_session
+.in +4n
-.RE
+keyctl new_session
+.in
+.fi
 .SH SEE ALSO
 .ad l
 .nh