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