]>
Commit | Line | Data |
---|---|---|
33af8657 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) |
33af8657 | 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 |
33af8657 | 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 |
33af8657 | 11 | .\" |
c1488329 | 12 | .TH PERSISTENT-KEYRING 7 2017-03-13 Linux "Linux Programmer's Manual" |
33af8657 | 13 | .SH NAME |
8c5a425a | 14 | persistent-keyring \- per-user persistent keyring |
33af8657 | 15 | .SH DESCRIPTION |
f437df79 | 16 | The persistent keyring is a keyring used to anchor keys on behalf of a user. |
a44454bc MK |
17 | Each UID the kernel deals with has its own persistent keyring that |
18 | is shared between all threads owned by that UID. | |
49301cc8 MK |
19 | The persistent keyring has a name (description) of the form |
20 | .I _persistent.<UID> | |
21 | where | |
22 | .I <UID> | |
23 | is the user ID of the corresponding user. | |
a721e8b2 | 24 | .PP |
655b410b MK |
25 | The persistent keyring may not be accessed directly, |
26 | even by processes with the appropriate UID. | |
27 | .\" FIXME The meaning of the preceding sentence isn't clear. What is meant? | |
28 | Instead, it must first be linked to one of a process's keyrings, | |
29 | before that keyring can access the persistent keyring | |
30 | by virtue of its possessor permits. | |
31 | This linking is done with the | |
32 | .BR keyctl_get_persistent (3) | |
33 | function. | |
a721e8b2 | 34 | .PP |
655b410b MK |
35 | If a persistent keyring does not exist when it is accessed by the |
36 | .BR keyctl_get_persistent (3) | |
37 | operation, it will be automatically created. | |
a721e8b2 | 38 | .PP |
655b410b MK |
39 | Each time the |
40 | .BR keyctl_get_persistent (3) | |
41 | operation is performed, | |
42 | the persistent key's expiration timer is reset to the value in: | |
a721e8b2 | 43 | .PP |
655b410b | 44 | /proc/sys/kernel/keys/persistent_keyring_expiry |
a721e8b2 | 45 | .PP |
655b410b MK |
46 | Should the timeout be reached, |
47 | the persistent keyring will be removed and | |
48 | everything it pins can then be garbage collected. | |
49 | The key will then be re-created on a subsequent call to | |
c26b9d57 | 50 | .BR keyctl_get_persistent (3). |
a721e8b2 | 51 | .PP |
655b410b MK |
52 | The persistent keyring is not directly searched by |
53 | .BR request_key (2); | |
54 | it is searched only if it is linked into one of the keyrings | |
55 | that is searched by | |
56 | .BR request_key (2). | |
a721e8b2 | 57 | .PP |
655b410b | 58 | The persistent keyring is independent of |
f437df79 MK |
59 | .BR clone (2), |
60 | .BR fork (2), | |
61 | .BR vfork (2), | |
62 | .BR execve (2), | |
63 | and | |
da1b8e41 | 64 | .BR _exit (2). |
655b410b MK |
65 | It persists until its expiration timer triggers, |
66 | at which point it is garbage collected. | |
67 | This allows the persistent keyring to carry keys beyond the life of | |
68 | the kernel's record of the corresponding UID | |
69 | (the destruction of which results in the destruction of the | |
70 | .BR user-keyring (7) | |
71 | and the | |
72 | .BR user-session-keyring (7)). | |
73 | The persistent keyring can thus be used to | |
74 | hold authentication tokens for processes that run without user interaction, | |
75 | such as programs started by | |
76 | .BR cron (8). | |
a721e8b2 | 77 | .PP |
655b410b MK |
78 | The persistent keyring is used to store UID-specific objects that |
79 | themselves have limited lifetimes (e.g., kerberos tokens). | |
80 | If those tokens cease to be used | |
81 | (i.e., the persistent keyring is not accessed), | |
82 | then the timeout of the persistent keyring ensures that | |
83 | the corresponding objects are automatically discarded. | |
84 | .\" | |
fe2d2f79 | 85 | .SS Special operations |
655b410b MK |
86 | The |
87 | .I keyutils | |
88 | library provides the | |
89 | .BR keyctl_get_persistent (3) | |
90 | function for manipulating persistent keyrings. | |
91 | (This function is an interface to the | |
92 | .BR keyctl (2) | |
93 | .B KEYCTL_GET_PERSISTENT | |
94 | operation.) | |
95 | This operation allows the calling thread to get the persistent keyring | |
96 | corresponding to its own UID or, if the thread has the | |
97 | .BR CAP_SETUID | |
98 | capability, the persistent keyring corresponding to some other UID | |
99 | in the same user namespace. | |
100 | .SH NOTES | |
101 | Each user namespace owns a keyring called | |
102 | .IR .persistent_register | |
103 | that contains links to all of the persistent keys in that namespace. | |
104 | (The | |
105 | .IR .persistent_register | |
106 | keyring can be seen when reading the contents of the | |
107 | .IR /proc/keys | |
108 | file for the UID 0 in the namespace.) | |
109 | The | |
c26b9d57 | 110 | .BR keyctl_get_persistent (3) |
655b410b MK |
111 | operation looks for a key with a name of the form |
112 | .IR _persistent.<UID> | |
113 | in that keyring, | |
114 | creates the key if it does not exist, and links it into the keyring. | |
33af8657 | 115 | .SH SEE ALSO |
2aa9ab8b MK |
116 | .ad l |
117 | .nh | |
33af8657 | 118 | .BR keyctl (1), |
33af8657 | 119 | .BR keyctl (3), |
33af8657 | 120 | .BR keyctl_get_persistent (3), |
33af8657 | 121 | .BR keyrings (7), |
2aa9ab8b MK |
122 | .BR process\-keyring (7), |
123 | .BR session\-keyring (7), | |
124 | .BR thread\-keyring (7), | |
125 | .BR user\-keyring (7), | |
126 | .BR user\-session\-keyring (7) |