]>
Commit | Line | Data |
---|---|---|
9d7cbb62 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) |
9d7cbb62 | 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 |
9d7cbb62 | 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 |
9d7cbb62 | 11 | .\" |
c1488329 | 12 | .TH USER-KEYRING 7 2017-03-13 Linux "Linux Programmer's Manual" |
9d7cbb62 | 13 | .SH NAME |
8c5a425a | 14 | user-keyring \- per-user keyring |
9d7cbb62 | 15 | .SH DESCRIPTION |
f437df79 | 16 | The user keyring is a keyring used to anchor keys on behalf of a user. |
2929ba68 MK |
17 | Each UID the kernel deals with has its own user keyring that |
18 | is shared by all processes with that UID. | |
cab39aef MK |
19 | The user keyring has a name (description) of the form |
20 | .I _uid.<UID> | |
21 | where | |
22 | .I <UID> | |
23 | is the user ID of the corresponding user. | |
a721e8b2 | 24 | .PP |
2929ba68 MK |
25 | The user keyring is associated with the record that the kernel maintains |
26 | for the UID. | |
27 | It comes into existence upon the first attempt to access either the | |
28 | user keyring, the | |
29 | .BR user-session-keyring (7), | |
30 | or the | |
31 | .BR session-keyring (7). | |
32 | The keyring remains pinned in existence so long as there are processes | |
33 | running with that real UID or files opened by those processes remain open. | |
34 | (The keyring can also be pinned indefinitely by linking it | |
35 | into another keyring.) | |
a721e8b2 | 36 | .PP |
2929ba68 | 37 | Typically, the user keyring is created by |
f437df79 | 38 | .BR pam_keyinit (8) |
2929ba68 | 39 | when a user logs in. |
a721e8b2 | 40 | .PP |
c26b9d57 MK |
41 | The user keyring is not searched by default by |
42 | .BR request_key (2). | |
f437df79 MK |
43 | When |
44 | .BR pam_keyinit (8) | |
45 | creates a session keyring, it adds to it a link to the user | |
9d7cbb62 | 46 | keyring so that the user keyring will be searched when the session keyring is. |
a721e8b2 | 47 | .PP |
f437df79 MK |
48 | A special serial number value, |
49 | .BR KEY_SPEC_USER_KEYRING , | |
f6993c8c MK |
50 | is defined that can be used in lieu of the actual serial number of |
51 | the calling process's user keyring. | |
a721e8b2 | 52 | .PP |
f6993c8c MK |
53 | From the |
54 | .BR keyctl (1) | |
55 | utility, '\fB@u\fP' can be used instead of a numeric key ID in | |
9d7cbb62 | 56 | much the same way. |
a721e8b2 | 57 | .PP |
f437df79 MK |
58 | User keyrings are independent of |
59 | .BR clone (2), | |
60 | .BR fork (2), | |
61 | .BR vfork (2), | |
62 | .BR execve (2), | |
63 | and | |
da1b8e41 | 64 | .BR _exit (2) |
9d7cbb62 MK |
65 | excepting that the keyring is destroyed when the UID record is destroyed when |
66 | the last process pinning it exits. | |
11ac5b51 | 67 | .PP |
f6993c8c MK |
68 | If it is necessary for a key associated with a user to exist beyond the UID |
69 | record being garbage collected\(emfor example, for use by a | |
70 | .BR cron (8) | |
71 | script\(emthen the | |
f437df79 MK |
72 | .BR persistent-keyring (7) |
73 | should be used instead. | |
11ac5b51 | 74 | .PP |
9d7cbb62 | 75 | If a user keyring does not exist when it is accessed, it will be created. |
9d7cbb62 | 76 | .SH SEE ALSO |
2aa9ab8b MK |
77 | .ad l |
78 | .nh | |
9d7cbb62 | 79 | .BR keyctl (1), |
9d7cbb62 | 80 | .BR keyctl (3), |
9d7cbb62 | 81 | .BR keyrings (7), |
2aa9ab8b MK |
82 | .BR persistent\-keyring (7), |
83 | .BR process\-keyring (7), | |
84 | .BR session\-keyring (7), | |
85 | .BR thread\-keyring (7), | |
86 | .BR user\-session\-keyring (7), | |
87 | .BR pam_keyinit (8) |