]>
Commit | Line | Data |
---|---|---|
6b71fd9a DH |
1 | .\" |
2 | .\" Copyright (C) 2014 Red Hat, Inc. All Rights Reserved. | |
3 | .\" Written by David Howells (dhowells@redhat.com) | |
424fb6a6 | 4 | .\" and Copyright (C) 2016 Michael Kerrisk <mtk.manpages@gmail.com> |
6b71fd9a | 5 | .\" |
1ba9d9e5 | 6 | .\" %%%LICENSE_START(GPLv2+_SW_ONEPARA) |
6b71fd9a | 7 | .\" This program is free software; you can redistribute it and/or |
e22cb0c4 | 8 | .\" modify it under the terms of the GNU General Public License |
6b71fd9a | 9 | .\" as published by the Free Software Foundation; either version |
e22cb0c4 | 10 | .\" 2 of the License, or (at your option) any later version. |
1ba9d9e5 | 11 | .\" %%%LICENSE_END |
6b71fd9a | 12 | .\" |
31a1b45e | 13 | .TH KEYRINGS 7 2017-03-13 Linux "Linux Programmer's Manual" |
6b71fd9a | 14 | .SH NAME |
8c5a425a | 15 | keyrings \- in-kernel key management and retention facility |
fe2d2f79 | 16 | .SH DESCRIPTION |
e650d927 | 17 | The Linux key-management facility |
16dfd5ce MK |
18 | is primarily a way for various kernel components |
19 | to retain or cache security data, | |
c1f7a90f | 20 | authentication keys, encryption keys, and other data in the kernel. |
11ac5b51 | 21 | .PP |
103a3798 | 22 | System call interfaces are provided so that user-space programs can manage |
cf84b5a4 MK |
23 | those objects and also use the facility for their own purposes; see |
24 | .BR add_key (2), | |
25 | .BR request_key (2), | |
26 | and | |
27 | .BR keyctl (2). | |
a721e8b2 | 28 | .PP |
6d6d803e | 29 | A library and some user-space utilities are provided to allow access to the |
a44454bc MK |
30 | facility. |
31 | See | |
e650d927 MK |
32 | .BR keyctl (1), |
33 | .BR keyctl (3), | |
34 | and | |
6b71fd9a | 35 | .BR keyutils (7) |
f437df79 | 36 | for more information. |
103a3798 | 37 | .\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" |
fe2d2f79 | 38 | .SS Keys |
e650d927 MK |
39 | A key has the following attributes: |
40 | .TP | |
25508c01 | 41 | Serial number (ID) |
16dfd5ce | 42 | This is a unique integer handle by which a key is referred to in system calls. |
25508c01 | 43 | The serial number is sometimes synonymously referred as the key ID. |
e650d927 MK |
44 | Programmatically, key serial numbers are represented using the type |
45 | .IR key_serial_t . | |
46 | .TP | |
47 | Type | |
48 | A key's type defines what sort of data can be held in the key, | |
49 | how the proposed content of the key will be parsed, | |
50 | and how the payload will be used. | |
a721e8b2 | 51 | .IP |
62694337 | 52 | There are a number of general-purpose types available, plus some specialist |
16dfd5ce | 53 | types defined by specific kernel components. |
e650d927 MK |
54 | .TP |
55 | Description (name) | |
56 | The key description is a printable string that is used as the search term | |
57 | for the key (in conjunction with the key type) as well as a display name. | |
58 | During searches, the description may be partially matched or exactly matched. | |
59 | .TP | |
25508c01 | 60 | Payload (data) |
e650d927 | 61 | The payload is the actual content of a key. |
a44454bc | 62 | This is usually set when a key is created, |
6d6d803e | 63 | but it is possible for the kernel to upcall to user space to finish the |
a44454bc MK |
64 | instantiation of a key if that key wasn't already known to the kernel |
65 | when it was requested. | |
23e10faf MK |
66 | For further details, see |
67 | .BR request_key (2). | |
a721e8b2 | 68 | .IP |
6b71fd9a DH |
69 | A key's payload can be read and updated if the key type supports it and if |
70 | suitable permission is granted to the caller. | |
e650d927 MK |
71 | .TP |
72 | Access rights | |
630abd84 MK |
73 | Much as files do, |
74 | each key has an owning user ID, an owning group ID, and a security label. | |
62694337 | 75 | Each key also has a set of permissions, |
a44454bc | 76 | though there are more than for a normal UNIX file, |
62694337 | 77 | and there is an additional category\(empossessor\(embeyond the usual user, |
23e10faf MK |
78 | group, and other (see |
79 | .IR Possession , | |
80 | below). | |
a721e8b2 | 81 | .IP |
62694337 | 82 | Note that keys are quota controlled, since they require unswappable kernel |
16dfd5ce | 83 | memory. |
62694337 | 84 | The owning user ID specifies whose quota is to be debited. |
e650d927 MK |
85 | .TP |
86 | Expiration time | |
a44454bc MK |
87 | Each key can have an expiration time set. |
88 | When that time is reached, | |
16dfd5ce | 89 | the key is marked as being expired and accesses to it fail with the error |
f437df79 | 90 | .BR EKEYEXPIRED . |
62694337 MK |
91 | If not deleted, updated, or replaced, then, after a set amount of time, |
92 | an expired key is automatically removed (garbage collected) | |
93 | along with all links to it, | |
e650d927 MK |
94 | and attempts to access the key will fail with the error |
95 | .BR ENOKEY . | |
96 | .TP | |
97 | Reference count | |
a44454bc | 98 | Each key has a reference count. |
e650d927 | 99 | Keys are referenced by keyrings, by currently active users, |
a44454bc MK |
100 | and by a process's credentials. |
101 | When the reference count reaches zero, | |
102 | the key is scheduled for garbage collection. | |
103a3798 | 103 | .\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" |
fe2d2f79 | 104 | .SS Key types |
62694337 | 105 | The kernel provides several basic types of key: |
e650d927 | 106 | .TP |
9fd70ffa MK |
107 | .I """keyring""" |
108 | '\" Note that keyrings use different fields in struct key in order to store | |
109 | '\" their data - index_key instead of type/description and name_link/keys | |
110 | '\" instead of payload. | |
111 | Keyrings are special keys which store a set of links | |
112 | to other keys (including other keyrings), | |
113 | analogous to a directory holding links to files. | |
114 | The main purpose of a keyring is to prevent other keys from | |
115 | being garbage collected because nothing refers to them. | |
a721e8b2 | 116 | .IP |
9fd70ffa MK |
117 | Keyrings with descriptions (names) |
118 | that begin with a period (\(aq.\(aq) are reserved to the implementation. | |
119 | .TP | |
39709e8a | 120 | .I """user""" |
62694337 | 121 | This is a general-purpose key type. |
39709e8a MK |
122 | The key is kept entirely within kernel memory. |
123 | The payload may be read and updated by user-space applications. | |
a721e8b2 | 124 | .IP |
39709e8a MK |
125 | The payload for keys of this type is a blob of arbitrary data |
126 | of up to 32,767 bytes. | |
a721e8b2 | 127 | .IP |
39709e8a MK |
128 | The description may be any valid string, though it is preferred that it |
129 | start with a colon-delimited prefix representing the service | |
130 | to which the key is of interest | |
131 | (for instance | |
132 | .IR """afs:mykey""" ). | |
133 | .TP | |
39709e8a MK |
134 | .IR """logon""" " (since Linux 3.3)" |
135 | .\" commit 9f6ed2ca257fa8650b876377833e6f14e272848b | |
136 | This key type is essentially the same as | |
137 | .IR """user""" , | |
138 | but it does not provide reading (i.e., the | |
139 | .BR keyctl (2) | |
140 | .BR KEYCTL_READ | |
141 | operation), | |
142 | meaning that the key payload is never visible from user space. | |
143 | This is suitable for storing username-password pairs | |
62694337 | 144 | that should not be readable from user space. |
e650d927 | 145 | .TP |
39709e8a MK |
146 | .IR """big_key""" " (since Linux 3.13)" |
147 | .\" commit ab3c3587f8cda9083209a61dbe3a4407d3cada10 | |
148 | This key type is similar to the | |
e650d927 | 149 | .I """user""" |
c4b7e5ac | 150 | key type, but it may hold a payload of up to 1\ MiB in size. |
b51c7752 | 151 | This key type is useful for purposes such as holding Kerberos ticket caches. |
a721e8b2 | 152 | .IP |
b51c7752 MK |
153 | The payload data may be stored in a tmpfs filesystem, |
154 | rather than in kernel memory, | |
155 | if the data size exceeds the overhead of storing the data in the filesystem. | |
156 | (Storing the data in a filesystem requires filesystem structures | |
157 | to be allocated in the kernel. | |
e8722fc5 MK |
158 | The size of these structures determines the size threshold |
159 | above which the tmpfs storage method is used.) | |
7c5c6f2c MK |
160 | Since Linux 4.8, |
161 | .\" commit 13100a72f40f5748a04017e0ab3df4cf27c809ef | |
b51c7752 | 162 | the payload data is encrypted when stored in tmpfs, |
8a141d6b | 163 | thereby preventing it from being written unencrypted into swap space. |
e650d927 | 164 | .PP |
103a3798 | 165 | There are more specialized key types available also, |
62694337 MK |
166 | but they aren't discussed here |
167 | because they aren't intended for normal user-space use. | |
a721e8b2 | 168 | .PP |
8880b194 MK |
169 | Key type names |
170 | that begin with a period (\(aq.\(aq) are reserved to the implementation. | |
103a3798 | 171 | .\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" |
fe2d2f79 | 172 | .SS Keyrings |
103a3798 MK |
173 | As previously mentioned, keyrings are a special type of key that contain |
174 | links to other keys (which may include other keyrings). | |
a44454bc MK |
175 | Keys may be linked to by multiple keyrings. |
176 | Keyrings may be considered as analogous to UNIX directories | |
6b71fd9a | 177 | where each directory contains a set of hard links to files. |
11ac5b51 | 178 | .PP |
c1f7a90f | 179 | Various operations (system calls) may be applied only to keyrings: |
25508c01 | 180 | .IP Adding |
a44454bc MK |
181 | A key may be added to a keyring by system calls that create keys. |
182 | This prevents the new key from being immediately deleted | |
16dfd5ce | 183 | when the system call releases its last reference to the key. |
25508c01 | 184 | .IP Linking |
6b71fd9a DH |
185 | A link may be added to a keyring pointing to a key that is already known, |
186 | provided this does not create a self-referential cycle. | |
25508c01 | 187 | .IP Unlinking |
a44454bc MK |
188 | A link may be removed from a keyring. |
189 | When the last link to a key is removed, | |
6b71fd9a | 190 | that key will be scheduled for deletion by the garbage collector. |
25508c01 | 191 | .IP Clearing |
6b71fd9a | 192 | All the links may be removed from a keyring. |
25508c01 | 193 | .IP Searching |
6b71fd9a | 194 | A keyring may be considered the root of a tree or subtree in which keyrings |
a44454bc | 195 | form the branches and non-keyrings the leaves. |
62694337 | 196 | This tree may be searched for a key matching |
a44454bc | 197 | a particular type and description. |
11ac5b51 | 198 | .PP |
bf0dcc15 | 199 | See |
6b71fd9a DH |
200 | .BR keyctl_clear (3), |
201 | .BR keyctl_link (3), | |
e650d927 | 202 | .BR keyctl_search (3), |
6b71fd9a DH |
203 | and |
204 | .BR keyctl_unlink (3) | |
bf0dcc15 | 205 | for more information. |
103a3798 | 206 | .\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" |
fe2d2f79 | 207 | .SS Anchoring keys |
23e10faf | 208 | To prevent a key from being garbage collected, |
a44454bc MK |
209 | it must anchored to keep its reference count elevated |
210 | when it is not in active use by the kernel. | |
a721e8b2 | 211 | .PP |
62694337 MK |
212 | Keyrings are used to anchor other keys: |
213 | each link is a reference on a key. | |
214 | Note that keyrings themselves are just keys and | |
16dfd5ce MK |
215 | are also subject to the same anchoring requirement to prevent |
216 | them being garbage collected. | |
a721e8b2 | 217 | .PP |
a44454bc | 218 | The kernel makes available a number of anchor keyrings. |
c1f7a90f | 219 | Note that some of these keyrings will be created only when first accessed. |
25508c01 MK |
220 | .TP |
221 | Process keyrings | |
6b71fd9a | 222 | Process credentials themselves reference keyrings with specific semantics. |
630abd84 MK |
223 | These keyrings are pinned as long as the set of credentials exists, |
224 | which is usually as long as the process exists. | |
6b71fd9a | 225 | .IP |
a44454bc | 226 | There are three keyrings with different inheritance/sharing rules: |
62694337 | 227 | the |
f437df79 MK |
228 | .BR session-keyring (7) |
229 | (inherited and shared by all child processes), | |
230 | the | |
231 | .BR process-keyring (7) | |
232 | (shared by all threads in a process) and | |
233 | the | |
234 | .BR thread-keyring (7) | |
235 | (specific to a particular thread). | |
a721e8b2 | 236 | .IP |
dc26e499 MK |
237 | As an alternative to using the actual keyring IDs, |
238 | in calls to | |
239 | .BR add_key (2), | |
240 | .BR keyctl (2), | |
241 | and | |
242 | .BR request_key (2), | |
243 | the special keyring values | |
244 | .BR KEY_SPEC_SESSION_KEYRING , | |
245 | .BR KEY_SPEC_PROCESS_KEYRING , | |
246 | and | |
247 | .BR KEY_SPEC_THREAD_KEYRING | |
248 | can be used to refer to the caller's own instances of these keyrings. | |
25508c01 MK |
249 | .TP |
250 | User keyrings | |
251 | Each UID known to the kernel has a record that contains two keyrings: the | |
f437df79 MK |
252 | .BR user-keyring (7) |
253 | and the | |
254 | .BR user-session-keyring (7). | |
a44454bc | 255 | These exist for as long as the UID record in the kernel exists. |
a721e8b2 | 256 | .IP |
dc26e499 MK |
257 | As an alternative to using the actual keyring IDs, |
258 | in calls to | |
259 | .BR add_key (2), | |
260 | .BR keyctl (2), | |
261 | and | |
262 | .BR request_key (2), | |
263 | the special keyring values | |
264 | .BR KEY_SPEC_USER_KEYRING | |
265 | and | |
266 | .BR KEY_SPEC_USER_SESSION_KEYRING | |
267 | can be used to refer to the caller's own instances of these keyrings. | |
a721e8b2 | 268 | .IP |
a44454bc | 269 | A link to the user keyring is placed in a new session keyring by |
afa27faa | 270 | .BR pam_keyinit (8) |
f437df79 | 271 | when a new login session is initiated. |
25508c01 MK |
272 | .TP |
273 | Persistent keyrings | |
f437df79 MK |
274 | There is a |
275 | .BR persistent-keyring (7) | |
276 | available to each UID known to the system. | |
a44454bc MK |
277 | It may persist beyond the life of the UID record previously mentioned, |
278 | but has an expiration time set such that it is automatically cleaned up | |
279 | after a set time. | |
16dfd5ce | 280 | The persistent keyring permits, for example, |
62694337 MK |
281 | .BR cron (8) |
282 | scripts to use credentials that are left in the persistent keyring after | |
283 | the user logs out. | |
6b71fd9a | 284 | .IP |
62694337 MK |
285 | Note that the expiration time of the persistent keyring |
286 | is reset every time the persistent key is requested. | |
25508c01 MK |
287 | .TP |
288 | Special keyrings | |
a44454bc MK |
289 | There are special keyrings owned by the kernel that can anchor keys |
290 | for special purposes. | |
25508c01 | 291 | An example of this is the \fIsystem keyring\fR used for holding |
6b71fd9a DH |
292 | encryption keys for module signature verification. |
293 | .IP | |
e650d927 MK |
294 | These special keyrings are usually closed to direct alteration |
295 | by user space. | |
6cf27f3f MK |
296 | .PP |
297 | An originally planned "group keyring", | |
298 | for storing keys associated with each GID known to the kernel, | |
299 | is not so far implemented, is unlikely to be implemented. | |
300 | Nevertheless, the constant | |
301 | .BR KEY_SPEC_GROUP_KEYRING | |
302 | has been defined for this keyring. | |
103a3798 | 303 | .\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" |
fe2d2f79 | 304 | .SS Possession |
e650d927 | 305 | The concept of possession is important to understanding the keyrings |
a44454bc MK |
306 | security model. |
307 | Whether a thread possesses a key is determined by the following rules: | |
e650d927 MK |
308 | .IP (1) 4 |
309 | Any key or keyring that does not grant | |
310 | .I search | |
311 | permission to the caller is ignored in all the following rules. | |
6b71fd9a | 312 | .IP (2) |
62694337 MK |
313 | A thread possesses its |
314 | .BR session-keyring (7), | |
315 | .BR process-keyring (7), | |
316 | and | |
317 | .BR thread-keyring (7) | |
318 | directly because those keyrings are referred to by its credentials. | |
6b71fd9a | 319 | .IP (3) |
62694337 | 320 | If a keyring is possessed, then any key it links to is also possessed. |
6b71fd9a DH |
321 | .IP (4) |
322 | If any key a keyring links to is itself a keyring, then rule (3) applies | |
62694337 | 323 | recursively. |
6b71fd9a | 324 | .IP (5) |
62694337 MK |
325 | If a process is upcalled from the kernel to instantiate a key (see |
326 | .BR request_key (2)), | |
327 | then it also possesses the requester's keyrings as in | |
328 | rule (1) as if it were the requester. | |
11ac5b51 | 329 | .PP |
a44454bc | 330 | Note that possession is not a fundamental property of a key, |
e650d927 | 331 | but must rather be calculated each time the key is needed. |
11ac5b51 | 332 | .PP |
e650d927 MK |
333 | Possession is designed to allow set-user-ID programs run from, say |
334 | a user's shell to access the user's keys. | |
62694337 | 335 | Granting permissions to the key possessor while denying them |
16dfd5ce | 336 | to the key owner and group allows the prevention of access to keys |
62694337 | 337 | on the basis of UID and GID matches. |
11ac5b51 | 338 | .PP |
f437df79 MK |
339 | When it creates the session keyring, |
340 | .BR pam_keyinit (8) | |
e650d927 MK |
341 | adds a link to the |
342 | .BR user-keyring (7), | |
f437df79 | 343 | thus making the user keyring and anything it contains possessed by default. |
103a3798 | 344 | .\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" |
fe2d2f79 | 345 | .SS Access rights |
6b71fd9a | 346 | Each key has the following security-related attributes: |
e650d927 MK |
347 | .IP * 3 |
348 | The owning user ID | |
349 | .IP * | |
350 | The ID of a group that is permitted to access the key | |
351 | .IP * | |
352 | A security label | |
353 | .IP * | |
354 | A permissions mask | |
11ac5b51 | 355 | .PP |
a44454bc MK |
356 | The permissions mask contains four sets of rights. |
357 | The first three sets are mutually exclusive. | |
e650d927 MK |
358 | One and only one will be in force for a particular access check. |
359 | In order of descending priority, these three sets are: | |
360 | .IP \fIuser\fR | |
361 | The set specifies the rights granted | |
362 | if the key's user ID matches the caller's filesystem user ID. | |
363 | .IP \fIgroup\fR | |
364 | The set specifies the rights granted | |
365 | if the user ID didn't match and the key's group ID matches the caller's | |
366 | filesystem GID or one of the caller's supplementary group IDs. | |
367 | .IP \fIother\fR | |
368 | The set specifies the rights granted | |
369 | if neither the key's user ID nor group ID matched. | |
11ac5b51 | 370 | .PP |
6b71fd9a | 371 | The fourth set of rights is: |
e650d927 MK |
372 | .IP \fIpossessor\fR |
373 | The set specifies the rights granted | |
374 | if a key is determined to be possessed by the caller. | |
11ac5b51 | 375 | .PP |
e650d927 MK |
376 | The complete set of rights for a key is the union of whichever |
377 | of the first three sets is applicable plus the fourth set | |
a44454bc | 378 | if the key is possessed. |
11ac5b51 | 379 | .PP |
e650d927 MK |
380 | The set of rights that may be granted in each of the four masks |
381 | is as follows: | |
382 | .TP | |
383 | .I view | |
384 | The attributes of the key may be read. | |
385 | This includes the type, | |
386 | description, and access rights (excluding the security label). | |
387 | .TP | |
388 | .I read | |
389 | For a key: the payload of the key may be read. | |
390 | For a keyring: the list of serial numbers (keys) to | |
391 | which the keyring has links may be read. | |
392 | .TP | |
393 | .I write | |
62694337 | 394 | The payload of the key may be updated and the key may be revoked. |
e650d927 | 395 | For a keyring, links may be added to or removed from the keyring, |
62694337 | 396 | and the keyring may be cleared completely (all links are removed), |
e650d927 MK |
397 | .TP |
398 | .I search | |
399 | For a key (or a keyring): the key may be found by a search. | |
400 | For a keyring: keys and keyrings that are linked to by the | |
401 | keyring may be searched. | |
402 | .TP | |
403 | .I link | |
404 | Links may be created from keyrings to the key. | |
405 | The initial link to a key that is established when the key is created | |
406 | doesn't require this permission. | |
407 | .TP | |
408 | .I setattr | |
409 | The ownership details and security label of the key may be changed, | |
410 | the key's expiration time may be set, and the key may be revoked. | |
11ac5b51 | 411 | .PP |
e650d927 | 412 | In addition to access rights, any active Linux Security Module (LSM) may |
a44454bc MK |
413 | prevent access to a key if its policy so dictates. |
414 | A key may be given a | |
62694337 MK |
415 | security label or other attribute by the LSM; |
416 | this label is retrievable via | |
417 | .BR keyctl_get_security (3). | |
11ac5b51 | 418 | .PP |
bf0dcc15 | 419 | See |
6b71fd9a DH |
420 | .BR keyctl_chown (3), |
421 | .BR keyctl_describe (3), | |
422 | .BR keyctl_get_security (3), | |
e650d927 | 423 | .BR keyctl_setperm (3), |
6b71fd9a DH |
424 | and |
425 | .BR selinux (8) | |
bf0dcc15 | 426 | for more information. |
103a3798 | 427 | .\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" |
fe2d2f79 | 428 | .SS Searching for keys |
e650d927 MK |
429 | One of the key features of the Linux key-management facility |
430 | is the ability to find a key that a process is retaining. | |
f437df79 MK |
431 | The |
432 | .BR request_key (2) | |
433 | system call is the primary point of | |
e650d927 | 434 | access for user-space applications to find a key. |
62694337 | 435 | (Internally, the kernel has something similar available |
e650d927 | 436 | for use by internal components that make use of keys.) |
11ac5b51 | 437 | .PP |
6b71fd9a | 438 | The search algorithm works as follows: |
e650d927 | 439 | .IP (1) 4 |
62694337 | 440 | The process keyrings are searched in the following order: the thread |
e650d927 MK |
441 | .BR thread-keyring (7) |
442 | if it exists, the | |
443 | .BR process-keyring (7) | |
444 | if it exists, and then either the | |
f437df79 MK |
445 | .BR session-keyring (7) |
446 | if it exists or the | |
447 | .BR user-session-keyring (7) | |
448 | if that exists. | |
6b71fd9a | 449 | .IP (2) |
c26b9d57 MK |
450 | If the caller was a process that was invoked by the |
451 | .BR request_key (2) | |
62694337 | 452 | upcall mechanism, then the keyrings of the original caller of |
c26b9d57 | 453 | .BR request_key (2) |
6b71fd9a DH |
454 | will be searched as well. |
455 | .IP (3) | |
23e10faf | 456 | The search of a keyring tree is in breadth-first order: |
e650d927 MK |
457 | each keyring is searched first for a match, |
458 | then the keyrings referred to by that keyring are searched. | |
6b71fd9a | 459 | .IP (4) |
e650d927 MK |
460 | If a matching key is found that is valid, |
461 | then the search terminates and that key is returned. | |
6b71fd9a | 462 | .IP (5) |
e650d927 MK |
463 | If a matching key is found that has an error state attached, |
464 | that error state is noted and the search continues. | |
6b71fd9a | 465 | .IP (6) |
eec85a07 | 466 | If no valid matching key is found, |
afa27faa | 467 | then the first noted error state is returned; otherwise, an |
e650d927 MK |
468 | .B ENOKEY |
469 | error is returned. | |
11ac5b51 | 470 | .PP |
103a3798 MK |
471 | It is also possible to search a specific keyring, in which case only steps |
472 | (3) to (6) apply. | |
11ac5b51 | 473 | .PP |
f437df79 | 474 | See |
6b71fd9a DH |
475 | .BR request_key (2) |
476 | and | |
477 | .BR keyctl_search (3) | |
f437df79 | 478 | for more information. |
103a3798 | 479 | .\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" |
fe2d2f79 | 480 | .SS On-demand key creation |
f437df79 MK |
481 | If a key cannot be found, |
482 | .BR request_key (2) | |
483 | will, if given a | |
484 | .I callout_info | |
6d6d803e | 485 | argument, create a new key and then upcall to user space to |
a44454bc MK |
486 | instantiate the key. |
487 | This allows keys to be created on an as-needed basis. | |
11ac5b51 | 488 | .PP |
62694337 MK |
489 | Typically, |
490 | this will involve the kernel creating a new process that executes the | |
f437df79 | 491 | .BR request-key (8) |
6d6d803e | 492 | program, which will then execute the appropriate handler based on its |
6b71fd9a | 493 | configuration. |
11ac5b51 | 494 | .PP |
e650d927 MK |
495 | The handler is passed a special authorization key that allows it |
496 | and only it to instantiate the new key. | |
a44454bc | 497 | This is also used to permit searches performed by the |
6b71fd9a | 498 | handler program to also search the requester's keyrings. |
11ac5b51 | 499 | .PP |
bf0dcc15 | 500 | See |
e650d927 | 501 | .BR request_key (2), |
6b71fd9a DH |
502 | .BR keyctl_assume_authority (3), |
503 | .BR keyctl_instantiate (3), | |
504 | .BR keyctl_negate (3), | |
505 | .BR keyctl_reject (3), | |
261a725e | 506 | .BR request-key (8), |
6b71fd9a DH |
507 | and |
508 | .BR request-key.conf (5) | |
bf0dcc15 | 509 | for more information. |
103a3798 | 510 | .\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" |
424fb6a6 | 511 | .SS /proc files |
abb8dc58 MK |
512 | The kernel provides various |
513 | .I /proc | |
514 | files that expose information about keys or define limits on key usage. | |
c29d99da | 515 | .TP |
ebf039e2 | 516 | .IR /proc/keys " (since Linux 2.6.10)" |
c9630289 MK |
517 | This file exposes a list of the keys for which the reading thread has |
518 | .I view | |
519 | permission, providing various information about each key. | |
51139f08 | 520 | The thread need not possess the key for it to be visible in this file. |
23e10faf MK |
521 | .\" David Howells, Dec 2016 linux-man@: |
522 | .\" This [The thread need not possess the key for it to be visible in | |
523 | .\" this file.] is correct. See proc_keys_show() in security/keys/proc.c: | |
afa27faa | 524 | .\" |
23e10faf MK |
525 | .\" rc = key_task_permission(key_ref, ctx.cred, KEY_NEED_VIEW); |
526 | .\" if (rc < 0) | |
527 | .\" return 0; | |
528 | .\" | |
529 | .\"Possibly it shouldn't be, but for now it is. | |
530 | .\" | |
a721e8b2 | 531 | .IP |
424fb6a6 MK |
532 | The only keys included in the list are those that grant |
533 | .I view | |
23e10faf MK |
534 | permission to the reading process |
535 | (regardless of whether or not it possesses them). | |
424fb6a6 | 536 | LSM security checks are still performed, |
f2161a52 | 537 | and may filter out further keys that the process is not authorized to view. |
a721e8b2 | 538 | .IP |
34795036 MK |
539 | An example of the data that one might see in this file |
540 | (with the columns numbered for easy reference below) | |
541 | is the following: | |
a721e8b2 | 542 | .IP |
424fb6a6 MK |
543 | .nf |
544 | .in 0n | |
34795036 | 545 | (1) (2) (3)(4) (5) (6) (7) (8) (9) |
424fb6a6 MK |
546 | 009a2028 I--Q--- 1 perm 3f010000 1000 1000 user krb_ccache:primary: 12 |
547 | 1806c4ba I--Q--- 1 perm 3f010000 1000 1000 keyring _pid: 2 | |
424fb6a6 MK |
548 | 25d3a08f I--Q--- 1 perm 1f3f0000 1000 65534 keyring _uid_ses.1000: 1 |
549 | 28576bd8 I--Q--- 3 perm 3f010000 1000 1000 keyring _krb: 1 | |
550 | 2c546d21 I--Q--- 190 perm 3f030000 1000 1000 keyring _ses: 2 | |
551 | 30a4e0be I------ 4 2d 1f030000 1000 65534 keyring _persistent.1000: 1 | |
552 | 32100fab I--Q--- 4 perm 1f3f0000 1000 65534 keyring _uid.1000: 2 | |
553 | 32a387ea I--Q--- 1 perm 3f010000 1000 1000 keyring _pid: 2 | |
554 | 3ce56aea I--Q--- 5 perm 3f030000 1000 1000 keyring _ses: 1 | |
555 | .in | |
556 | .fi | |
a721e8b2 | 557 | .IP |
424fb6a6 MK |
558 | The fields shown in each line of this file are as follows: |
559 | .RS | |
560 | .TP | |
34795036 | 561 | ID (1) |
424fb6a6 MK |
562 | The ID (serial number) of the key, expressed in hexadecimal. |
563 | .TP | |
34795036 | 564 | Flags (2) |
424fb6a6 MK |
565 | A set of flags describing the state of the key: |
566 | .RS | |
567 | .IP I 4 | |
17041003 | 568 | .\" KEY_FLAG_INSTANTIATED |
424fb6a6 MK |
569 | The key has been instantiated. |
570 | .IP R | |
17041003 | 571 | .\" KEY_FLAG_REVOKED |
424fb6a6 MK |
572 | The key has been revoked. |
573 | .IP D | |
17041003 | 574 | .\" KEY_FLAG_DEAD |
805aa466 | 575 | The key is dead (i.e., the key type has been unregistered). |
23e10faf | 576 | .\" unregister_key_type() in the kernel source |
424fb6a6 MK |
577 | (A key may be briefly in this state during garbage collection.) |
578 | .IP Q | |
17041003 | 579 | .\" KEY_FLAG_IN_QUOTA |
424fb6a6 MK |
580 | The key contributes to the user's quota. |
581 | .IP U | |
17041003 | 582 | .\" KEY_FLAG_USER_CONSTRUCT |
424fb6a6 MK |
583 | The key is under construction via a callback to user space; |
584 | see | |
585 | .BR request-key (2). | |
586 | .IP N | |
17041003 | 587 | .\" KEY_FLAG_NEGATIVE |
424fb6a6 MK |
588 | The key is negatively instantiated. |
589 | .IP i | |
17041003 | 590 | .\" KEY_FLAG_INVALIDATED |
424fb6a6 MK |
591 | The key has been invalidated. |
592 | .RE | |
593 | .TP | |
34795036 | 594 | Usage (3) |
abb8dc58 MK |
595 | This is a count of the number of kernel credential |
596 | structures that are pinning the key | |
25508c01 | 597 | (approximately: the number of threads and open file references |
abb8dc58 | 598 | that refer to this key). |
424fb6a6 | 599 | .TP |
34795036 | 600 | Timeout (4) |
424fb6a6 MK |
601 | The amount of time until the key will expire, |
602 | expressed in human-readable form (weeks, days, hours, minutes, and seconds). | |
603 | The string | |
604 | .I perm | |
605 | here means that the key is permanent (no timeout). | |
606 | The string | |
607 | .I expd | |
608 | means that the key has already expired, | |
609 | but has not yet been garbage collected. | |
610 | .TP | |
34795036 | 611 | Permissions (5) |
25508c01 MK |
612 | The key permissions, expressed as four hexadecimal bytes containing, |
613 | from left to right, the possessor, user, group, and other permissions. | |
2651b688 | 614 | Within each byte, the permission bits are as follows: |
a721e8b2 | 615 | .IP |
2651b688 MK |
616 | .PD 0 |
617 | .RS 12 | |
618 | .TP | |
619 | 0x01 | |
620 | .I view | |
621 | .TP | |
622 | Ox02 | |
623 | .I read | |
624 | .TP | |
625 | 0x04 | |
626 | .I write | |
627 | .TP | |
628 | 0x08 | |
629 | .I search | |
630 | .TP | |
631 | 0x10 | |
632 | .I link | |
633 | .TP | |
634 | 0x20 | |
635 | .I setattr | |
636 | .RE | |
637 | .PD | |
424fb6a6 | 638 | .TP |
34795036 | 639 | UID (6) |
424fb6a6 MK |
640 | The user ID of the key owner. |
641 | .TP | |
34795036 | 642 | GID (7) |
424fb6a6 | 643 | The group ID of the key. |
62694337 | 644 | The value \-1 here means that the key has no group ID; |
abb8dc58 | 645 | this can occur in certain circumstances for keys created by the kernel. |
424fb6a6 | 646 | .TP |
34795036 | 647 | Type (8) |
424fb6a6 MK |
648 | The key type (user, keyring, etc.) |
649 | .TP | |
34795036 | 650 | Description (9) |
424fb6a6 | 651 | The key description (name). |
f2161a52 MK |
652 | This field contains descriptive information about the key. |
653 | For most key types, it has the form | |
a721e8b2 | 654 | .IP |
260eda92 | 655 | name[: extra\-info] |
a721e8b2 | 656 | .IP |
f2161a52 MK |
657 | The |
658 | .I name | |
82d46d99 | 659 | subfield is the key's description (name). |
f2161a52 MK |
660 | The optional |
661 | .I extra\-info | |
662 | field provides some further information about the key. | |
663 | The information that appears here depends on the key type, as follows: | |
664 | .RS | |
665 | .TP 4 | |
666 | .IR """user""" " and " """logon""" | |
667 | The size in bytes of the key payload (expressed in decimal). | |
668 | .TP | |
669 | .IR """keyring""" | |
670 | The number of keys linked to the keyring, | |
424fb6a6 MK |
671 | or the string |
672 | .IR empty | |
673 | if there are no keys linked to the keyring. | |
f2161a52 MK |
674 | .TP |
675 | .IR """big_key""" | |
676 | The payload size in bytes, followed either by the string | |
677 | .IR [file] , | |
678 | if the key payload exceeds the threshold that means that the | |
62694337 MK |
679 | payload is stored in a (swappable) |
680 | .BR tmpfs (5) | |
681 | filesystem, | |
f2161a52 MK |
682 | or otherwise the string |
683 | .IR [buff] , | |
684 | indicating that the key is small enough to reside in kernel memory. | |
685 | .RE | |
686 | .IP | |
687 | For the | |
688 | .IR """.request_key_auth""" | |
689 | key type | |
690 | (authorization key; see | |
691 | .BR request_key (2)), | |
692 | the description field has the form shown in the following example: | |
a721e8b2 | 693 | .IP |
f2161a52 | 694 | key:c9a9b19 pid:28880 ci:10 |
a721e8b2 | 695 | .IP |
f2161a52 MK |
696 | The three subfields are as follows: |
697 | .RS | |
698 | .TP 5 | |
699 | .I key | |
700 | The hexadecimal ID of the key being instantiated in the requesting program. | |
701 | .TP | |
702 | .I pid | |
703 | The PID of the requesting program. | |
704 | .TP | |
705 | .I ci | |
706 | The length of the callout data with which the requested key should | |
707 | be instantiated | |
708 | (i.e., the length of the payload associated with the authorization key). | |
709 | .RE | |
424fb6a6 | 710 | .RE |
ebf039e2 MK |
711 | .TP |
712 | .IR /proc/key-users " (since Linux 2.6.10)" | |
713 | This file lists various information for each user ID that | |
714 | has at least one key on the system. | |
715 | An example of the data that one might see in this file is the following: | |
a721e8b2 | 716 | .IP |
ebf039e2 MK |
717 | .nf |
718 | .in +4n | |
719 | 0: 10 9/9 2/1000000 22/25000000 | |
720 | 42: 9 9/9 8/200 106/20000 | |
721 | 1000: 11 11/11 10/200 271/20000 | |
722 | .in | |
723 | .fi | |
a721e8b2 | 724 | .IP |
ebf039e2 MK |
725 | The fields shown in each line are as follows: |
726 | .RS | |
727 | .TP | |
728 | .I uid | |
729 | The user ID. | |
730 | .TP | |
731 | .I usage | |
abb8dc58 MK |
732 | This is a kernel-internal usage count for the kernel structure |
733 | used to record key users. | |
ebf039e2 MK |
734 | .TP |
735 | .IR nkeys / nikeys | |
736 | The total number of keys owned by the user, | |
737 | and the number of those keys that have been instantiated. | |
738 | .TP | |
739 | .IR qnkeys / maxkeys | |
740 | The number of keys owned by the user, | |
62694337 | 741 | and the maximum number of keys that the user may own. |
ebf039e2 MK |
742 | .TP |
743 | .IR qnbytes / maxbytes | |
744 | The number of bytes consumed in payloads of the keys owned by this user, | |
745 | and the upper limit on the number of bytes in key payloads for that user. | |
746 | .RE | |
747 | .TP | |
c29d99da MK |
748 | .IR /proc/sys/kernel/keys/gc_delay " (since Linux 2.6.32)" |
749 | .\" commit 5d135440faf7db8d566de0c6fab36b16cf9cfc3b | |
ef805a05 MK |
750 | The value in this file specifies the interval, in seconds, |
751 | after which revoked and expired keys will be garbage collected. | |
abb8dc58 MK |
752 | The purpose of having such an interval is so that there is a window |
753 | of time where user space can see an error (respectively | |
754 | .BR EKEYREVOKED | |
755 | and | |
756 | .BR EKEYEXPIRED ) | |
757 | that indicates what happened to the key. | |
a721e8b2 | 758 | .IP |
c29d99da MK |
759 | The default value in this file is 300 (i.e., 5 minutes). |
760 | .TP | |
761 | .IR /proc/sys/kernel/keys/persistent_keyring_expiry " (since Linux 3.13)" | |
762 | .\" commit f36f8c75ae2e7d4da34f4c908cebdb4aa42c977e | |
763 | This file defines an interval, in seconds, | |
764 | to which the persistent keyring's expiration timer is reset | |
765 | each time the keyring is accessed (via | |
766 | .BR keyctl_get_persistent (3) | |
767 | or the | |
768 | .BR keyctl (2) | |
769 | .B KEYCTL_GET_PERSISTENT | |
770 | operation.) | |
a721e8b2 | 771 | .IP |
c29d99da | 772 | The default value in this file is 259200 (i.e., 3 days). |
5b0a63f6 | 773 | .PP |
25508c01 | 774 | The following files (which are writable by privileged processes) |
5b0a63f6 MK |
775 | are used to enforce quotas on the number of keys |
776 | and number of bytes of data that can be stored in key payloads: | |
777 | .TP | |
778 | .IR /proc/sys/kernel/keys/maxbytes " (since Linux 2.6.26)" | |
779 | .\" commit 0b77f5bfb45c13e1e5142374f9d6ca75292252a4 | |
780 | .\" Previously: KEYQUOTA_MAX_BYTES 10000 | |
781 | This is the maximum number of bytes of data that a nonroot user | |
782 | can hold in the payloads of the keys owned by the user. | |
a721e8b2 | 783 | .IP |
5b0a63f6 MK |
784 | The default value in this file is 20,000. |
785 | .TP | |
786 | .IR /proc/sys/kernel/keys/maxkeys " (since Linux 2.6.26)" | |
787 | .\" commit 0b77f5bfb45c13e1e5142374f9d6ca75292252a4 | |
788 | .\" Previously: KEYQUOTA_MAX_KEYS 100 | |
789 | This is the maximum number of keys that a nonroot user may own. | |
a721e8b2 | 790 | .IP |
5b0a63f6 MK |
791 | The default value in this file is 200. |
792 | .TP | |
793 | .IR /proc/sys/kernel/keys/root_maxbytes " (since Linux 2.6.26)" | |
794 | This is the maximum number of bytes of data that the root user | |
795 | (UID 0 in the root user namespace) | |
796 | can hold in the payloads of the keys owned by root. | |
a721e8b2 | 797 | .IP |
efeccbf6 | 798 | .\"738c5d190f6540539a04baf36ce21d46b5da04bd |
722772aa | 799 | The default value in this file is 25,000,000 (20,000 before Linux 3.17). |
5b0a63f6 MK |
800 | .\" commit 0b77f5bfb45c13e1e5142374f9d6ca75292252a4 |
801 | .TP | |
802 | .IR /proc/sys/kernel/keys/root_maxkeys " (since Linux 2.6.26)" | |
803 | .\" commit 0b77f5bfb45c13e1e5142374f9d6ca75292252a4 | |
804 | This is the maximum number of keys that the root user | |
805 | (UID 0 in the root user namespace) | |
806 | may own. | |
a721e8b2 | 807 | .IP |
efeccbf6 | 808 | .\"738c5d190f6540539a04baf36ce21d46b5da04bd |
722772aa | 809 | The default value in this file is 1,000,000 (200 before Linux 3.17). |
5b0a63f6 MK |
810 | .PP |
811 | With respect to keyrings, | |
812 | note that each link in a keyring consumes 4 bytes of the keyring payload. | |
103a3798 | 813 | .\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" |
fe2d2f79 | 814 | .SS Users |
e650d927 MK |
815 | The Linux key-management facility has a number of users and usages, |
816 | but is not limited to those that already exist. | |
11ac5b51 | 817 | .PP |
6b71fd9a | 818 | In-kernel users of this facility include: |
25508c01 MK |
819 | .TP |
820 | Network filesystems - DNS | |
6b71fd9a | 821 | The kernel uses the upcall mechanism provided by the keys to upcall to |
6d6d803e | 822 | user space to do DNS lookups and then to cache the results. |
25508c01 MK |
823 | .TP |
824 | AF_RXRPC and kAFS - Authentication | |
e650d927 MK |
825 | The AF_RXRPC network protocol and the in-kernel AFS filesystem |
826 | use keys to store the ticket needed to do secured or encrypted traffic. | |
a44454bc | 827 | These are then looked up by |
6b71fd9a | 828 | network operations on AF_RXRPC and filesystem operations on kAFS. |
25508c01 MK |
829 | .TP |
830 | NFS - User ID mapping | |
e650d927 MK |
831 | The NFS filesystem uses keys to store mappings of |
832 | foreign user IDs to local user IDs. | |
25508c01 MK |
833 | .TP |
834 | CIFS - Password | |
6b71fd9a | 835 | The CIFS filesystem uses keys to store passwords for accessing remote shares. |
25508c01 MK |
836 | .TP |
837 | Module verification | |
a44454bc MK |
838 | The kernel build process can be made to cryptographically sign modules. |
839 | That signature is then checked when a module is loaded. | |
11ac5b51 | 840 | .PP |
6d6d803e | 841 | User-space users of this facility include: |
25508c01 MK |
842 | .TP |
843 | Kerberos key storage | |
6b71fd9a | 844 | The MIT Kerberos 5 facility (libkrb5) can use keys to store authentication |
103a3798 MK |
845 | tokens which can be made to be automatically cleaned up a set time after |
846 | the user last uses them, | |
e650d927 | 847 | but until then permits them to hang around after the user |
62694337 MK |
848 | has logged out so that |
849 | .BR cron (8) | |
850 | scripts can use them. | |
103a3798 | 851 | .\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" |
6b71fd9a | 852 | .SH SEE ALSO |
2aa9ab8b MK |
853 | .ad l |
854 | .nh | |
ecf9a3e3 MK |
855 | .BR keyctl (1), |
856 | .BR add_key (2), | |
857 | .BR keyctl (2), | |
858 | .BR request_key (2), | |
859 | .BR keyctl (3), | |
6b71fd9a | 860 | .BR keyutils (7), |
2aa9ab8b MK |
861 | .BR persistent\-keyring (7), |
862 | .BR process\-keyring (7), | |
863 | .BR session\-keyring (7), | |
864 | .BR thread\-keyring (7), | |
865 | .BR user\-keyring (7), | |
866 | .BR user\-session\-keyring (7), | |
ecf9a3e3 MK |
867 | .BR pam_keyinit (8), |
868 | .BR request-key (8) |