]>
Commit | Line | Data |
---|---|---|
6b71fd9a DH |
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) |
6b71fd9a DH |
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 |
6b71fd9a | 11 | .\" |
e7ca6b3c | 12 | .TH KEYRINGS 7 2016-11-01 Linux "Linux Programmer's Manual" |
6b71fd9a | 13 | .SH NAME |
8c5a425a | 14 | keyrings \- in-kernel key management and retention facility |
fe2d2f79 | 15 | .SH DESCRIPTION |
e650d927 MK |
16 | The Linux key-management facility |
17 | is primarily a way for drivers to retain or cache security data, | |
c1f7a90f | 18 | authentication keys, encryption keys, and other data in the kernel. |
6b71fd9a | 19 | .P |
6d6d803e | 20 | System call interfaces are provided so that user-space programs can manage those |
6b71fd9a DH |
21 | objects and also use the facility for their own purposes. |
22 | .P | |
6d6d803e | 23 | A library and some user-space utilities are provided to allow access to the |
a44454bc MK |
24 | facility. |
25 | See | |
e650d927 MK |
26 | .BR keyctl (1), |
27 | .BR keyctl (3), | |
28 | and | |
6b71fd9a | 29 | .BR keyutils (7) |
f437df79 | 30 | for more information. |
6b71fd9a | 31 | .\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" |
fe2d2f79 | 32 | .SS Keys |
e650d927 MK |
33 | A key has the following attributes: |
34 | .TP | |
35 | Serial number | |
6b71fd9a DH |
36 | This is a unique integer handle by which a key is referred to in system call |
37 | arguments. | |
e650d927 MK |
38 | The serial number is sometimes synonymously referred the key ID. |
39 | Programmatically, key serial numbers are represented using the type | |
40 | .IR key_serial_t . | |
41 | .TP | |
42 | Type | |
43 | A key's type defines what sort of data can be held in the key, | |
44 | how the proposed content of the key will be parsed, | |
45 | and how the payload will be used. | |
46 | ||
6b71fd9a DH |
47 | There are a number of general purpose types available, plus some specialist |
48 | types defined by specific drivers. | |
e650d927 MK |
49 | .TP |
50 | Description (name) | |
51 | The key description is a printable string that is used as the search term | |
52 | for the key (in conjunction with the key type) as well as a display name. | |
53 | During searches, the description may be partially matched or exactly matched. | |
54 | .TP | |
55 | Payload | |
56 | The payload is the actual content of a key. | |
a44454bc | 57 | This is usually set when a key is created, |
6d6d803e | 58 | but it is possible for the kernel to upcall to user space to finish the |
a44454bc MK |
59 | instantiation of a key if that key wasn't already known to the kernel |
60 | when it was requested. | |
e650d927 MK |
61 | (Details can be found in |
62 | .BR request_key (2).) | |
63 | ||
6b71fd9a DH |
64 | A key's payload can be read and updated if the key type supports it and if |
65 | suitable permission is granted to the caller. | |
e650d927 MK |
66 | .TP |
67 | Access rights | |
630abd84 MK |
68 | Much as files do, |
69 | each key has an owning user ID, an owning group ID, and a security label. | |
a44454bc MK |
70 | files do. |
71 | They also have a set of permissions, | |
72 | though there are more than for a normal UNIX file, | |
73 | and there is an additional category beyond the usual user, | |
e650d927 MK |
74 | group, and other (see below). |
75 | ||
6b71fd9a DH |
76 | Note that keys are quota controlled since they represent unswappable kernel |
77 | memory and the owning user ID specifies whose quota is to be debited. | |
e650d927 MK |
78 | .TP |
79 | Expiration time | |
a44454bc MK |
80 | Each key can have an expiration time set. |
81 | When that time is reached, | |
82 | the key is marked as being expired and accesses to it fail with | |
f437df79 | 83 | .BR EKEYEXPIRED . |
e650d927 MK |
84 | If not deleted, updated, or replaced, after a set amount of time, |
85 | expired keys are automatically removed along with all links to them, | |
86 | and attempts to access the key will fail with the error | |
87 | .BR ENOKEY . | |
88 | .TP | |
89 | Reference count | |
a44454bc | 90 | Each key has a reference count. |
e650d927 | 91 | Keys are referenced by keyrings, by currently active users, |
a44454bc MK |
92 | and by a process's credentials. |
93 | When the reference count reaches zero, | |
94 | the key is scheduled for garbage collection. | |
6b71fd9a | 95 | .\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" |
fe2d2f79 | 96 | .SS Key types |
6b71fd9a | 97 | The facility provides several basic types of key: |
e650d927 MK |
98 | .TP |
99 | .I """keyring""" | |
a44454bc MK |
100 | Keys of this type are special. |
101 | The payload consists of a set of links to other | |
102 | keys, analogous to a directory holding links to files. | |
103 | The main purpose of a keyring is to prevent other keys from | |
104 | being garbage collected because nothing refers to them. | |
e650d927 MK |
105 | .TP |
106 | .I """user""" | |
a44454bc MK |
107 | This is a general purpose key type. |
108 | It may be instantiated with an arbitrary blob of data of up to about 32KB. | |
109 | It is kept entirely within kernel memory. | |
6d6d803e | 110 | It may be read and updated by user-space applications |
e650d927 MK |
111 | .TP |
112 | .I """big_key""" | |
113 | This is similar to the | |
114 | .I """user""" | |
115 | key type, but it may hold a payload of up to 1MiB in size. | |
a44454bc MK |
116 | The data may be stored in the swap space rather than in kernel memory |
117 | if the size exceeds the overhead of doing so | |
630abd84 | 118 | (a tmpfs file is used, which requires filesystem structures |
a44454bc | 119 | to be allocated in the kernel). |
e650d927 MK |
120 | .TP |
121 | .I """logon""" | |
122 | This is similar to the | |
123 | .I """user""" | |
124 | key type, but the contents may not be read by user-space applications. | |
125 | .PP | |
6d6d803e MK |
126 | There are more specialized key types available also, but they're not discussed |
127 | here as they're not intended for normal user-space use. | |
6b71fd9a | 128 | .\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" |
fe2d2f79 | 129 | .SS Keyrings |
6b71fd9a | 130 | As previously mentioned, keyrings are a special type of key that contain links |
a44454bc MK |
131 | to other keys (which may include other keyrings). |
132 | Keys may be linked to by multiple keyrings. | |
133 | Keyrings may be considered as analogous to UNIX directories | |
6b71fd9a DH |
134 | where each directory contains a set of hard links to files. |
135 | .P | |
c1f7a90f | 136 | Various operations (system calls) may be applied only to keyrings: |
6b71fd9a | 137 | .IP "\fBAdding\fR" |
a44454bc MK |
138 | A key may be added to a keyring by system calls that create keys. |
139 | This prevents the new key from being immediately deleted | |
140 | when the system call driver releases its last reference to the key. | |
6b71fd9a DH |
141 | .IP "\fBLinking\fR" |
142 | A link may be added to a keyring pointing to a key that is already known, | |
143 | provided this does not create a self-referential cycle. | |
144 | .IP "\fBUnlinking\fR" | |
a44454bc MK |
145 | A link may be removed from a keyring. |
146 | When the last link to a key is removed, | |
6b71fd9a DH |
147 | that key will be scheduled for deletion by the garbage collector. |
148 | .IP "\fBClearing\fR" | |
149 | All the links may be removed from a keyring. | |
150 | .IP "\fBSearching\fR" | |
151 | A keyring may be considered the root of a tree or subtree in which keyrings | |
a44454bc MK |
152 | form the branches and non-keyrings the leaves. |
153 | This tree may be searched for a leaf matching | |
154 | a particular type and description. | |
6b71fd9a | 155 | .P |
bf0dcc15 | 156 | See |
6b71fd9a DH |
157 | .BR keyctl_clear (3), |
158 | .BR keyctl_link (3), | |
e650d927 | 159 | .BR keyctl_search (3), |
6b71fd9a DH |
160 | and |
161 | .BR keyctl_unlink (3) | |
bf0dcc15 | 162 | for more information. |
6b71fd9a | 163 | .\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" |
fe2d2f79 | 164 | .SS Anchoring keys |
a44454bc MK |
165 | To prevent a key from being prematurely garbage collected, |
166 | it must anchored to keep its reference count elevated | |
167 | when it is not in active use by the kernel. | |
6b71fd9a DH |
168 | .P |
169 | \fBKeyrings\fR are used to anchor other keys - each link is a reference on a | |
170 | key - but whilst keyrings are available to link to keys, keyrings themselves | |
171 | are just keys and are also subject to the same anchoring necessity. | |
172 | .P | |
a44454bc | 173 | The kernel makes available a number of anchor keyrings. |
c1f7a90f | 174 | Note that some of these keyrings will be created only when first accessed. |
6b71fd9a DH |
175 | .IP "\fBProcess keyrings\fR" |
176 | Process credentials themselves reference keyrings with specific semantics. | |
630abd84 MK |
177 | These keyrings are pinned as long as the set of credentials exists, |
178 | which is usually as long as the process exists. | |
6b71fd9a | 179 | .IP |
a44454bc | 180 | There are three keyrings with different inheritance/sharing rules: |
f437df79 MK |
181 | The |
182 | .BR session-keyring (7) | |
183 | (inherited and shared by all child processes), | |
184 | the | |
185 | .BR process-keyring (7) | |
186 | (shared by all threads in a process) and | |
187 | the | |
188 | .BR thread-keyring (7) | |
189 | (specific to a particular thread). | |
6b71fd9a DH |
190 | .IP "\fBUser keyrings\fR" |
191 | Each UID known to the kernel has a record that contains two keyrings: The | |
f437df79 MK |
192 | .BR user-keyring (7) |
193 | and the | |
194 | .BR user-session-keyring (7). | |
a44454bc MK |
195 | These exist for as long as the UID record in the kernel exists. |
196 | A link to the user keyring is placed in a new session keyring by | |
f437df79 MK |
197 | .BR pam_keyinit (8) |
198 | when a new login session is initiated. | |
6b71fd9a | 199 | .IP "\fBPersistent keyrings\fR" |
f437df79 MK |
200 | There is a |
201 | .BR persistent-keyring (7) | |
202 | available to each UID known to the system. | |
a44454bc MK |
203 | It may persist beyond the life of the UID record previously mentioned, |
204 | but has an expiration time set such that it is automatically cleaned up | |
205 | after a set time. | |
206 | This, for example, permits cron scripts to use credentials left when the | |
6b71fd9a DH |
207 | user logs out. |
208 | .IP | |
209 | Note that the expiration time is reset every time the persistent key is | |
210 | requested. | |
211 | .IP "\fBSpecial keyrings\fR" | |
a44454bc MK |
212 | There are special keyrings owned by the kernel that can anchor keys |
213 | for special purposes. | |
214 | An example of this is the \fBsystem keyring\fR used for holding | |
6b71fd9a DH |
215 | encryption keys for module signature verification. |
216 | .IP | |
e650d927 MK |
217 | These special keyrings are usually closed to direct alteration |
218 | by user space. | |
6b71fd9a | 219 | .P |
bf0dcc15 | 220 | See |
6b71fd9a DH |
221 | .BR thread-keyring (7), |
222 | .BR process-keyring (7), | |
223 | .BR session-keyring (7), | |
224 | .BR user-keyring (7), | |
225 | .BR user-session-keyring (7), | |
226 | and | |
227 | .BR persistent-keyring (7) | |
bf0dcc15 | 228 | for more information. |
6b71fd9a | 229 | .\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" |
fe2d2f79 | 230 | .SS Possession |
e650d927 | 231 | The concept of possession is important to understanding the keyrings |
a44454bc MK |
232 | security model. |
233 | Whether a thread possesses a key is determined by the following rules: | |
e650d927 MK |
234 | .IP (1) 4 |
235 | Any key or keyring that does not grant | |
236 | .I search | |
237 | permission to the caller is ignored in all the following rules. | |
6b71fd9a | 238 | .IP (2) |
c1f7a90f | 239 | A thread \fIpossesses\fR its \fBsession\fR, \fBprocess\fR, and \fBthread\fR |
6b71fd9a DH |
240 | keyrings directly because those are pointed to by its credentials. |
241 | .IP (3) | |
242 | If a keyring is possessed, then any key it links to is \fIalso\fR possessed. | |
243 | .IP (4) | |
244 | If any key a keyring links to is itself a keyring, then rule (3) applies | |
245 | \fIrecursively\fP. | |
246 | .IP (5) | |
247 | If a process is upcalled from the kernel to instantiate a key, then it also | |
e650d927 | 248 | possesses the \fIrequester's\fP keyrings as in rule (1) as if it were the |
6b71fd9a DH |
249 | requester. |
250 | .P | |
a44454bc | 251 | Note that possession is not a fundamental property of a key, |
e650d927 | 252 | but must rather be calculated each time the key is needed. |
6b71fd9a | 253 | .P |
e650d927 MK |
254 | Possession is designed to allow set-user-ID programs run from, say |
255 | a user's shell to access the user's keys. | |
a44454bc | 256 | It also allows the prevention of access to keys |
6b71fd9a DH |
257 | just on the basis of UID and GID matches. |
258 | .P | |
f437df79 MK |
259 | When it creates the session keyring, |
260 | .BR pam_keyinit (8) | |
e650d927 MK |
261 | adds a link to the |
262 | .BR user-keyring (7), | |
f437df79 | 263 | thus making the user keyring and anything it contains possessed by default. |
6b71fd9a | 264 | .\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" |
fe2d2f79 | 265 | .SS Access rights |
6b71fd9a | 266 | Each key has the following security-related attributes: |
e650d927 MK |
267 | .IP * 3 |
268 | The owning user ID | |
269 | .IP * | |
270 | The ID of a group that is permitted to access the key | |
271 | .IP * | |
272 | A security label | |
273 | .IP * | |
274 | A permissions mask | |
6b71fd9a | 275 | .P |
a44454bc MK |
276 | The permissions mask contains four sets of rights. |
277 | The first three sets are mutually exclusive. | |
e650d927 MK |
278 | One and only one will be in force for a particular access check. |
279 | In order of descending priority, these three sets are: | |
280 | .IP \fIuser\fR | |
281 | The set specifies the rights granted | |
282 | if the key's user ID matches the caller's filesystem user ID. | |
283 | .IP \fIgroup\fR | |
284 | The set specifies the rights granted | |
285 | if the user ID didn't match and the key's group ID matches the caller's | |
286 | filesystem GID or one of the caller's supplementary group IDs. | |
287 | .IP \fIother\fR | |
288 | The set specifies the rights granted | |
289 | if neither the key's user ID nor group ID matched. | |
6b71fd9a DH |
290 | .P |
291 | The fourth set of rights is: | |
e650d927 MK |
292 | .IP \fIpossessor\fR |
293 | The set specifies the rights granted | |
294 | if a key is determined to be possessed by the caller. | |
6b71fd9a | 295 | .P |
e650d927 MK |
296 | The complete set of rights for a key is the union of whichever |
297 | of the first three sets is applicable plus the fourth set | |
a44454bc | 298 | if the key is possessed. |
6b71fd9a | 299 | .P |
e650d927 MK |
300 | The set of rights that may be granted in each of the four masks |
301 | is as follows: | |
302 | .TP | |
303 | .I view | |
304 | The attributes of the key may be read. | |
305 | This includes the type, | |
306 | description, and access rights (excluding the security label). | |
307 | .TP | |
308 | .I read | |
309 | For a key: the payload of the key may be read. | |
310 | For a keyring: the list of serial numbers (keys) to | |
311 | which the keyring has links may be read. | |
312 | .TP | |
313 | .I write | |
314 | The payload of the key may be updated. | |
315 | For a keyring, links may be added to or removed from the keyring, | |
316 | the keyring may be cleared completely (all links are removed), | |
317 | and the key may be revoked. | |
318 | .TP | |
319 | .I search | |
320 | For a key (or a keyring): the key may be found by a search. | |
321 | For a keyring: keys and keyrings that are linked to by the | |
322 | keyring may be searched. | |
323 | .TP | |
324 | .I link | |
325 | Links may be created from keyrings to the key. | |
326 | The initial link to a key that is established when the key is created | |
327 | doesn't require this permission. | |
328 | .TP | |
329 | .I setattr | |
330 | The ownership details and security label of the key may be changed, | |
331 | the key's expiration time may be set, and the key may be revoked. | |
332 | .P | |
333 | If any right is granted to a thread for a key, | |
334 | then that thread will see the key listed in | |
335 | .IR /proc/keys . | |
a44454bc | 336 | If no rights at all are granted, then that thread |
6b71fd9a DH |
337 | can't even tell that the key exists. |
338 | .P | |
e650d927 | 339 | In addition to access rights, any active Linux Security Module (LSM) may |
a44454bc MK |
340 | prevent access to a key if its policy so dictates. |
341 | A key may be given a | |
6b71fd9a DH |
342 | security label or other attribute by the LSM which can be retrieved. |
343 | .P | |
bf0dcc15 | 344 | See |
6b71fd9a DH |
345 | .BR keyctl_chown (3), |
346 | .BR keyctl_describe (3), | |
347 | .BR keyctl_get_security (3), | |
e650d927 | 348 | .BR keyctl_setperm (3), |
6b71fd9a DH |
349 | and |
350 | .BR selinux (8) | |
bf0dcc15 | 351 | for more information. |
6b71fd9a | 352 | .\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" |
fe2d2f79 | 353 | .SS Searching for keys |
e650d927 MK |
354 | One of the key features of the Linux key-management facility |
355 | is the ability to find a key that a process is retaining. | |
f437df79 MK |
356 | The |
357 | .BR request_key (2) | |
358 | system call is the primary point of | |
e650d927 MK |
359 | access for user-space applications to find a key. |
360 | (!nternally, the kernel has something similar available | |
361 | for use by internal components that make use of keys.) | |
6b71fd9a DH |
362 | .P |
363 | The search algorithm works as follows: | |
e650d927 | 364 | .IP (1) 4 |
6b71fd9a | 365 | The three process keyrings are searched in the following order: the thread |
e650d927 MK |
366 | .BR thread-keyring (7) |
367 | if it exists, the | |
368 | .BR process-keyring (7) | |
369 | if it exists, and then either the | |
f437df79 MK |
370 | .BR session-keyring (7) |
371 | if it exists or the | |
372 | .BR user-session-keyring (7) | |
373 | if that exists. | |
6b71fd9a | 374 | .IP (2) |
c26b9d57 MK |
375 | If the caller was a process that was invoked by the |
376 | .BR request_key (2) | |
377 | upcall mechanism then the keyrings of the original caller of that | |
378 | .BR request_key (2) | |
6b71fd9a DH |
379 | will be searched as well. |
380 | .IP (3) | |
e650d927 MK |
381 | The search of the keyring tree is in preorder: |
382 | each keyring is searched first for a match, | |
383 | then the keyrings referred to by that keyring are searched. | |
6b71fd9a | 384 | .IP (4) |
e650d927 MK |
385 | If a matching key is found that is valid, |
386 | then the search terminates and that key is returned. | |
6b71fd9a | 387 | .IP (5) |
e650d927 MK |
388 | If a matching key is found that has an error state attached, |
389 | that error state is noted and the search continues. | |
6b71fd9a | 390 | .IP (6) |
a44454bc | 391 | If valid matching key is found, |
e650d927 MK |
392 | then the first noted error state is returned; otherwise, an |
393 | .B ENOKEY | |
394 | error is returned. | |
6b71fd9a DH |
395 | .P |
396 | It is also possible to search a specific keyring, in which case only steps (3) | |
397 | to (6) apply. | |
398 | .P | |
f437df79 | 399 | See |
6b71fd9a DH |
400 | .BR request_key (2) |
401 | and | |
402 | .BR keyctl_search (3) | |
f437df79 | 403 | for more information. |
6b71fd9a | 404 | .\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" |
fe2d2f79 | 405 | .SS On-demand key creation |
f437df79 MK |
406 | If a key cannot be found, |
407 | .BR request_key (2) | |
408 | will, if given a | |
409 | .I callout_info | |
6d6d803e | 410 | argument, create a new key and then upcall to user space to |
a44454bc MK |
411 | instantiate the key. |
412 | This allows keys to be created on an as-needed basis. | |
6b71fd9a | 413 | .P |
e650d927 | 414 | Typically, this will involve the kernel forking and exec'ing the |
f437df79 | 415 | .BR request-key (8) |
6d6d803e | 416 | program, which will then execute the appropriate handler based on its |
6b71fd9a DH |
417 | configuration. |
418 | .P | |
e650d927 MK |
419 | The handler is passed a special authorization key that allows it |
420 | and only it to instantiate the new key. | |
a44454bc | 421 | This is also used to permit searches performed by the |
6b71fd9a DH |
422 | handler program to also search the requester's keyrings. |
423 | .P | |
bf0dcc15 | 424 | See |
e650d927 | 425 | .BR request_key (2), |
6b71fd9a DH |
426 | .BR keyctl_assume_authority (3), |
427 | .BR keyctl_instantiate (3), | |
428 | .BR keyctl_negate (3), | |
429 | .BR keyctl_reject (3), | |
6b71fd9a DH |
430 | .BR request-key (8) |
431 | and | |
432 | .BR request-key.conf (5) | |
bf0dcc15 | 433 | for more information. |
5b0a63f6 | 434 | .SS /proc files |
6b71fd9a | 435 | .\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" |
baf69887 | 436 | .\" FIXME document /proc files |
c29d99da | 437 | .TP |
c29d99da MK |
438 | .IR /proc/sys/kernel/keys/gc_delay " (since Linux 2.6.32)" |
439 | .\" commit 5d135440faf7db8d566de0c6fab36b16cf9cfc3b | |
ef805a05 MK |
440 | The value in this file specifies the interval, in seconds, |
441 | after which revoked and expired keys will be garbage collected. | |
442 | .\" FIXME What is the purpose of the GC delay? | |
c29d99da MK |
443 | |
444 | The default value in this file is 300 (i.e., 5 minutes). | |
445 | .TP | |
446 | .IR /proc/sys/kernel/keys/persistent_keyring_expiry " (since Linux 3.13)" | |
447 | .\" commit f36f8c75ae2e7d4da34f4c908cebdb4aa42c977e | |
448 | This file defines an interval, in seconds, | |
449 | to which the persistent keyring's expiration timer is reset | |
450 | each time the keyring is accessed (via | |
451 | .BR keyctl_get_persistent (3) | |
452 | or the | |
453 | .BR keyctl (2) | |
454 | .B KEYCTL_GET_PERSISTENT | |
455 | operation.) | |
456 | ||
457 | The default value in this file is 259200 (i.e., 3 days). | |
5b0a63f6 MK |
458 | .PP |
459 | The following files (which are writable by privileged processies) | |
460 | are used to enforce quotas on the number of keys | |
461 | and number of bytes of data that can be stored in key payloads: | |
462 | .TP | |
463 | .IR /proc/sys/kernel/keys/maxbytes " (since Linux 2.6.26)" | |
464 | .\" commit 0b77f5bfb45c13e1e5142374f9d6ca75292252a4 | |
465 | .\" Previously: KEYQUOTA_MAX_BYTES 10000 | |
466 | This is the maximum number of bytes of data that a nonroot user | |
467 | can hold in the payloads of the keys owned by the user. | |
468 | ||
469 | The default value in this file is 20,000. | |
470 | .TP | |
471 | .IR /proc/sys/kernel/keys/maxkeys " (since Linux 2.6.26)" | |
472 | .\" commit 0b77f5bfb45c13e1e5142374f9d6ca75292252a4 | |
473 | .\" Previously: KEYQUOTA_MAX_KEYS 100 | |
474 | This is the maximum number of keys that a nonroot user may own. | |
475 | ||
476 | The default value in this file is 200. | |
477 | .TP | |
478 | .IR /proc/sys/kernel/keys/root_maxbytes " (since Linux 2.6.26)" | |
479 | This is the maximum number of bytes of data that the root user | |
480 | (UID 0 in the root user namespace) | |
481 | can hold in the payloads of the keys owned by root. | |
482 | ||
483 | The default value in this file is 25,000,000. | |
484 | .\" commit 0b77f5bfb45c13e1e5142374f9d6ca75292252a4 | |
485 | .TP | |
486 | .IR /proc/sys/kernel/keys/root_maxkeys " (since Linux 2.6.26)" | |
487 | .\" commit 0b77f5bfb45c13e1e5142374f9d6ca75292252a4 | |
488 | This is the maximum number of keys that the root user | |
489 | (UID 0 in the root user namespace) | |
490 | may own. | |
491 | ||
492 | The default value in this file is 1,000,000. | |
493 | .PP | |
494 | With respect to keyrings, | |
495 | note that each link in a keyring consumes 4 bytes of the keyring payload. | |
baf69887 | 496 | .\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" |
fe2d2f79 | 497 | .SS Users |
e650d927 MK |
498 | The Linux key-management facility has a number of users and usages, |
499 | but is not limited to those that already exist. | |
6b71fd9a DH |
500 | .P |
501 | In-kernel users of this facility include: | |
502 | .IP "\fBNetwork filesystems - DNS\fR" | |
503 | The kernel uses the upcall mechanism provided by the keys to upcall to | |
6d6d803e | 504 | user space to do DNS lookups and then to cache the results. |
6b71fd9a | 505 | .IP "\fBAF_RXRPC and kAFS - Authentication\fR" |
e650d927 MK |
506 | The AF_RXRPC network protocol and the in-kernel AFS filesystem |
507 | use keys to store the ticket needed to do secured or encrypted traffic. | |
a44454bc | 508 | These are then looked up by |
6b71fd9a DH |
509 | network operations on AF_RXRPC and filesystem operations on kAFS. |
510 | .IP "\fBNFS - User ID mapping\fR" | |
e650d927 MK |
511 | The NFS filesystem uses keys to store mappings of |
512 | foreign user IDs to local user IDs. | |
6b71fd9a DH |
513 | .IP "\fBCIFS - Password\fR" |
514 | The CIFS filesystem uses keys to store passwords for accessing remote shares. | |
515 | .IP "\fBModule verification\fR" | |
a44454bc MK |
516 | The kernel build process can be made to cryptographically sign modules. |
517 | That signature is then checked when a module is loaded. | |
6b71fd9a | 518 | .P |
6d6d803e | 519 | User-space users of this facility include: |
6b71fd9a DH |
520 | .IP "\fBKerberos key storage\fR" |
521 | The MIT Kerberos 5 facility (libkrb5) can use keys to store authentication | |
522 | tokens which can be made to be automatically cleaned up a set time after the | |
e650d927 MK |
523 | user last uses them, |
524 | but until then permits them to hang around after the user | |
6b71fd9a DH |
525 | has logged out so that cron scripts can use them. |
526 | .\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" | |
527 | .SH SEE ALSO | |
2aa9ab8b MK |
528 | .ad l |
529 | .nh | |
6b71fd9a | 530 | .BR keyutils (7), |
2aa9ab8b MK |
531 | .BR persistent\-keyring (7), |
532 | .BR process\-keyring (7), | |
533 | .BR session\-keyring (7), | |
534 | .BR thread\-keyring (7), | |
535 | .BR user\-keyring (7), | |
536 | .BR user\-session\-keyring (7), | |
537 | .BR pam_keyinit (8) |