]>
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 MK |
6 | .\" This program is free software; you can redistribute it and/or |
7 | .\" modify it under the terms of the GNU General Public Licence | |
8 | .\" as published by the Free Software Foundation; either version | |
9 | .\" 2 of the Licence, or (at your option) any later version. | |
1ba9d9e5 | 10 | .\" %%%LICENSE_END |
9bb46110 | 11 | .\" |
e7ca6b3c | 12 | .TH "USER-SESSION-KEYRING" 7 2016-11-01 Linux "Linux Programmer's Manual" |
9bb46110 MK |
13 | .\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" |
14 | .SH NAME | |
8c5a425a | 15 | user-session-keyring \- per-user default session keyring |
9bb46110 | 16 | .SH DESCRIPTION |
f437df79 | 17 | The user session keyring is a keyring used to anchor keys on behalf of a user. |
a44454bc MK |
18 | Each UID the kernel |
19 | deals with has its own user session keyring. | |
20 | This keyring is associated with | |
9bb46110 | 21 | the record that the kernel maintains for the UID and, once created, is retained |
a44454bc MK |
22 | as long as that record persists. |
23 | It is shared amongst all processes of that | |
9bb46110 MK |
24 | UID. |
25 | .P | |
a44454bc | 26 | The user session keyring is created on demand when a thread requests it |
f437df79 MK |
27 | or when a thread asks for its |
28 | .BR session-keyring (7) | |
29 | and that doesn't exist. | |
a44454bc MK |
30 | In the latter case, |
31 | a user session keyring will be created and, if the session keyring | |
9bb46110 MK |
32 | wasn't to be created, the user session keyring will be set as the process's |
33 | actual session keyring. | |
34 | .P | |
35 | The user session keyring is searched by \fBrequest_key\fP() if the actual | |
36 | session keyring does not exist and is ignored otherwise. | |
37 | .P | |
f437df79 MK |
38 | A special serial number value, |
39 | .BR KEY_SPEC_USER_SESSION_KEYRING , | |
40 | is defined | |
9bb46110 MK |
41 | that can be used in lieu of the calling process's user session keyring's actual |
42 | serial number. | |
43 | .P | |
44 | From the keyctl utility, '\fB@us\fP' can be used instead of a numeric key ID in | |
45 | much the same way. | |
46 | .P | |
f437df79 MK |
47 | User session keyrings are independent of |
48 | .BR clone (2), | |
49 | .BR fork (2), | |
50 | .BR vfork (2), | |
51 | .BR execve (2), | |
52 | and | |
53 | .BR exit (2) | |
54 | excepting that the keyring is destroyed when the UID record is destroyed | |
9bb46110 MK |
55 | when the last process pinning it exits. |
56 | .P | |
57 | If a user session keyring does not exist when it is accessed, it will be | |
58 | created. | |
59 | .P | |
f437df79 MK |
60 | It is strongly recommended that a |
61 | .BR session-keyring (7) | |
62 | be set explicitly, for | |
63 | example by | |
64 | .BR pam_keyinit (8), | |
65 | rather than relying on the user session keyring - | |
9bb46110 MK |
66 | particularly if a process is running as root. |
67 | .\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" | |
68 | .SH SEE ALSO | |
2aa9ab8b MK |
69 | .ad l |
70 | .nh | |
9bb46110 | 71 | .BR keyctl (1), |
9bb46110 | 72 | .BR keyctl (3), |
9bb46110 | 73 | .BR keyrings (7), |
2aa9ab8b MK |
74 | .BR persistent\-keyring (7), |
75 | .BR process\-keyring (7), | |
76 | .BR session\-keyring (7), | |
77 | .BR thread\-keyring (7), | |
78 | .BR user\-keyring (7) |