]>
Commit | Line | Data |
---|---|---|
9bb46110 MK |
1 | .\" |
2 | .\" Copyright (C) 2014 Red Hat, Inc. All Rights Reserved. | |
3 | .\" Written by David Howells (dhowells@redhat.com) | |
4 | .\" | |
1ba9d9e5 | 5 | .\" %%%LICENSE_START(GPLv2+_SW_ONEPARA) |
9bb46110 | 6 | .\" This program is free software; you can redistribute it and/or |
e22cb0c4 | 7 | .\" modify it under the terms of the GNU General Public License |
9bb46110 | 8 | .\" as published by the Free Software Foundation; either version |
e22cb0c4 | 9 | .\" 2 of the License, or (at your option) any later version. |
1ba9d9e5 | 10 | .\" %%%LICENSE_END |
9bb46110 | 11 | .\" |
31a1b45e | 12 | .TH "USER-SESSION-KEYRING" 7 2017-03-13 Linux "Linux Programmer's Manual" |
9bb46110 | 13 | .SH NAME |
8c5a425a | 14 | user-session-keyring \- per-user default session keyring |
9bb46110 | 15 | .SH DESCRIPTION |
f437df79 | 16 | The user session keyring is a keyring used to anchor keys on behalf of a user. |
6294ad5c MK |
17 | Each UID the kernel deals with has its own user session keyring that |
18 | is shared by all processes with that UID. | |
59d33fb6 MK |
19 | The user session keyring has a name (description) of the form |
20 | .I _uid_ses.<UID> | |
21 | where | |
22 | .I <UID> | |
23 | is the user ID of the corresponding user. | |
a721e8b2 | 24 | .PP |
6294ad5c MK |
25 | The user session keyring is associated with the record that |
26 | the kernel maintains for the UID. | |
27 | It comes into existence upon the first attempt to access either the | |
28 | user session keyring, the | |
29 | .BR user-keyring (7), | |
30 | or the | |
31 | .BR session-keyring (7). | |
32 | .\" Davis Howells: the user and user-session keyrings are managed as a pair. | |
33 | The keyring remains pinned in existence so long as there are processes | |
34 | running with that real UID or files opened by those processes remain open. | |
35 | (The keyring can also be pinned indefinitely by linking it | |
36 | into another keyring.) | |
a721e8b2 | 37 | .PP |
a44454bc | 38 | The user session keyring is created on demand when a thread requests it |
f437df79 MK |
39 | or when a thread asks for its |
40 | .BR session-keyring (7) | |
505614ad MK |
41 | and that keyring doesn't exist. |
42 | In the latter case, a user session keyring will be created and, | |
43 | if the session keyring wasn't to be created, | |
44 | the user session keyring will be set as the process's actual session keyring. | |
a721e8b2 | 45 | .PP |
c26b9d57 MK |
46 | The user session keyring is searched by |
47 | .BR request_key (2) | |
505614ad | 48 | if the actual session keyring does not exist and is ignored otherwise. |
a721e8b2 | 49 | .PP |
f437df79 MK |
50 | A special serial number value, |
51 | .BR KEY_SPEC_USER_SESSION_KEYRING , | |
52 | is defined | |
505614ad MK |
53 | that can be used in lieu of the actual serial number of |
54 | the calling process's user session keyring. | |
a721e8b2 | 55 | .PP |
505614ad MK |
56 | From the |
57 | .BR keyctl (1) | |
58 | utility, '\fB@us\fP' can be used instead of a numeric key ID in | |
9bb46110 | 59 | much the same way. |
a721e8b2 | 60 | .PP |
f437df79 MK |
61 | User session keyrings are independent of |
62 | .BR clone (2), | |
63 | .BR fork (2), | |
64 | .BR vfork (2), | |
65 | .BR execve (2), | |
66 | and | |
da1b8e41 | 67 | .BR _exit (2) |
f437df79 | 68 | excepting that the keyring is destroyed when the UID record is destroyed |
9bb46110 | 69 | when the last process pinning it exits. |
a721e8b2 | 70 | .PP |
505614ad MK |
71 | If a user session keyring does not exist when it is accessed, |
72 | it will be created. | |
a721e8b2 | 73 | .PP |
505614ad MK |
74 | Rather than relying on the user session keyring, |
75 | it is strongly recommended\(emespecially if the process | |
76 | is running as root\(emthat a | |
f437df79 | 77 | .BR session-keyring (7) |
505614ad MK |
78 | be set explicitly, for example by |
79 | .BR pam_keyinit (8). | |
ec5fa8a7 MK |
80 | .SH NOTES |
81 | The user session keyring was added to support situations where | |
82 | a process doesn't have a session keyring, | |
83 | perhaps because it was created via a pathway that didn't involve PAM | |
84 | (e.g., perhaps it was a daemon started by | |
85 | .BR inetd (8)). | |
86 | In such a scenario, the user session keyring acts as a substitute for the | |
87 | .BR session-keyring (7). | |
9bb46110 | 88 | .SH SEE ALSO |
2aa9ab8b MK |
89 | .ad l |
90 | .nh | |
9bb46110 | 91 | .BR keyctl (1), |
9bb46110 | 92 | .BR keyctl (3), |
9bb46110 | 93 | .BR keyrings (7), |
2aa9ab8b MK |
94 | .BR persistent\-keyring (7), |
95 | .BR process\-keyring (7), | |
96 | .BR session\-keyring (7), | |
97 | .BR thread\-keyring (7), | |
98 | .BR user\-keyring (7) |