]>
Commit | Line | Data |
---|---|---|
1 | .\" | |
2 | .\" Copyright (C) 2014 Red Hat, Inc. All Rights Reserved. | |
3 | .\" Written by David Howells (dhowells@redhat.com) | |
4 | .\" | |
5 | .\" %%%LICENSE_START(GPLv2+_SW_ONEPARA) | |
6 | .\" This program is free software; you can redistribute it and/or | |
7 | .\" modify it under the terms of the GNU General Public License | |
8 | .\" as published by the Free Software Foundation; either version | |
9 | .\" 2 of the License, or (at your option) any later version. | |
10 | .\" %%%LICENSE_END | |
11 | .\" | |
12 | .TH "USER-SESSION-KEYRING" 7 2017-03-13 Linux "Linux Programmer's Manual" | |
13 | .SH NAME | |
14 | user-session-keyring \- per-user default session keyring | |
15 | .SH DESCRIPTION | |
16 | The user session keyring is a keyring used to anchor keys on behalf of a user. | |
17 | Each UID the kernel deals with has its own user session keyring that | |
18 | is shared by all processes with that UID. | |
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. | |
24 | .PP | |
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.) | |
37 | .PP | |
38 | The user session keyring is created on demand when a thread requests it | |
39 | or when a thread asks for its | |
40 | .BR session-keyring (7) | |
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. | |
45 | .PP | |
46 | The user session keyring is searched by | |
47 | .BR request_key (2) | |
48 | if the actual session keyring does not exist and is ignored otherwise. | |
49 | .PP | |
50 | A special serial number value, | |
51 | .BR KEY_SPEC_USER_SESSION_KEYRING , | |
52 | is defined | |
53 | that can be used in lieu of the actual serial number of | |
54 | the calling process's user session keyring. | |
55 | .PP | |
56 | From the | |
57 | .BR keyctl (1) | |
58 | utility, '\fB@us\fP' can be used instead of a numeric key ID in | |
59 | much the same way. | |
60 | .PP | |
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 | |
67 | .BR _exit (2) | |
68 | excepting that the keyring is destroyed when the UID record is destroyed | |
69 | when the last process pinning it exits. | |
70 | .PP | |
71 | If a user session keyring does not exist when it is accessed, | |
72 | it will be created. | |
73 | .PP | |
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 | |
77 | .BR session-keyring (7) | |
78 | be set explicitly, for example by | |
79 | .BR pam_keyinit (8). | |
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). | |
88 | .SH SEE ALSO | |
89 | .ad l | |
90 | .nh | |
91 | .BR keyctl (1), | |
92 | .BR keyctl (3), | |
93 | .BR keyrings (7), | |
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) |