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