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