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