From 505614ad0fd6532a44562a6e4c3b8c92d9fd821b Mon Sep 17 00:00:00 2001 From: Michael Kerrisk Date: Wed, 2 Nov 2016 15:25:57 +0100 Subject: [PATCH] user-session-keyring.7: Various rewordings and additions Signed-off-by: Michael Kerrisk --- man7/user-session-keyring.7 | 59 ++++++++++++++++++------------------- 1 file changed, 28 insertions(+), 31 deletions(-) diff --git a/man7/user-session-keyring.7 b/man7/user-session-keyring.7 index 0d1d65cb6..40f31b449 100644 --- a/man7/user-session-keyring.7 +++ b/man7/user-session-keyring.7 @@ -14,37 +14,35 @@ 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. +Each UID the kernel deals with has its own user session keyring. This keyring is associated with -the record that the kernel maintains for the UID and, once created, is retained -as long as that record persists. -It is shared amongst all processes of that -UID. -.P +the record that the kernel maintains for the UID and, once created, +is retained as long as that record persists. +It is shared amongst all processes of that UID. + 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 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 +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. + The user session keyring is searched by .BR request_key (2) -if the actual -session keyring does not exist and is ignored otherwise. -.P +if the actual session keyring does not exist and is ignored otherwise. + A special serial number value, .BR KEY_SPEC_USER_SESSION_KEYRING , is defined -that can be used in lieu of the calling process's user session keyring's actual -serial number. -.P -From the keyctl utility, '\fB@us\fP' can be used instead of a numeric key ID in +that can be used in lieu of the actual serial number of +the calling process's user session keyring. + +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), @@ -54,17 +52,16 @@ 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 -It is strongly recommended that a + +If a user session keyring does not exist when it is accessed, +it will be created. + +Rather than relying on the user session keyring, +it is strongly recommended\(emespecially if the process +is running as root\(emthat a .BR session-keyring (7) -be set explicitly, for -example by -.BR pam_keyinit (8), -rather than relying on the user session keyring - -particularly if a process is running as root. +be set explicitly, for example by +.BR pam_keyinit (8). .SH SEE ALSO .ad l .nh