From 9bb46110dc715500ff8cfa201c8a180ed83c0f3a Mon Sep 17 00:00:00 2001 From: Michael Kerrisk Date: Tue, 1 Nov 2016 16:45:33 +0100 Subject: [PATCH] user-session-keyring.7: New page adopted from keyutils Since this page documents kernel-user-space interfaces, it makes sense to have it as part of man-pages, rather than the keyutils package. Signed-off-by: David Howells Signed-off-by: Michael Kerrisk --- man7/user-session-keyring.7 | 65 +++++++++++++++++++++++++++++++++++++ 1 file changed, 65 insertions(+) create mode 100644 man7/user-session-keyring.7 diff --git a/man7/user-session-keyring.7 b/man7/user-session-keyring.7 new file mode 100644 index 000000000..825355750 --- /dev/null +++ b/man7/user-session-keyring.7 @@ -0,0 +1,65 @@ +.\" +.\" Copyright (C) 2014 Red Hat, Inc. All Rights Reserved. +.\" Written by David Howells (dhowells@redhat.com) +.\" +.\" This program is free software; you can redistribute it and/or +.\" modify it under the terms of the GNU General Public Licence +.\" as published by the Free Software Foundation; either version +.\" 2 of the Licence, or (at your option) any later version. +.\" +.TH "USER-SESSION KEYRING" 7 "20 Feb 2014" Linux "Kernel key management" +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.SH NAME +user_session_keyring \- Per-user default session keyring +.SH DESCRIPTION +The +.B 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. 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 user session keyring is created on demand when a thread requests it or when +a thread asks for its \fBsession keyring\fP 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 +The user session keyring is searched by \fBrequest_key\fP() if the actual +session keyring does not exist and is ignored otherwise. +.P +A special serial number value, \fBKEY_SPEC_USER_SESSION_KEYRING\fP, 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 +much the same way. +.P +User session keyrings are independent of clone(), fork(), vfork(), execve() and +exit() 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 \fBsession keyring\fP be set explicitly, for +example by \fBpam_keyinit\fP, rather than relying on the user session keyring - +particularly if a process is running as root. +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.SH SEE ALSO +.BR keyctl (1), +.br +.BR keyctl (3), +.br +.BR keyrings (7), +.br +.BR process-keyring (7), +.br +.BR session-keyring (7), +.br +.BR thread-keyring (7), +.br +.BR user-keyring (7), +.br +.BR persistent-keyring (7)