Root/
1 | ============================ |
2 | KERNEL KEY RETENTION SERVICE |
3 | ============================ |
4 | |
5 | This service allows cryptographic keys, authentication tokens, cross-domain |
6 | user mappings, and similar to be cached in the kernel for the use of |
7 | filesystems and other kernel services. |
8 | |
9 | Keyrings are permitted; these are a special type of key that can hold links to |
10 | other keys. Processes each have three standard keyring subscriptions that a |
11 | kernel service can search for relevant keys. |
12 | |
13 | The key service can be configured on by enabling: |
14 | |
15 | "Security options"/"Enable access key retention support" (CONFIG_KEYS) |
16 | |
17 | This document has the following sections: |
18 | |
19 | - Key overview |
20 | - Key service overview |
21 | - Key access permissions |
22 | - SELinux support |
23 | - New procfs files |
24 | - Userspace system call interface |
25 | - Kernel services |
26 | - Notes on accessing payload contents |
27 | - Defining a key type |
28 | - Request-key callback service |
29 | - Garbage collection |
30 | |
31 | |
32 | ============ |
33 | KEY OVERVIEW |
34 | ============ |
35 | |
36 | In this context, keys represent units of cryptographic data, authentication |
37 | tokens, keyrings, etc.. These are represented in the kernel by struct key. |
38 | |
39 | Each key has a number of attributes: |
40 | |
41 | - A serial number. |
42 | - A type. |
43 | - A description (for matching a key in a search). |
44 | - Access control information. |
45 | - An expiry time. |
46 | - A payload. |
47 | - State. |
48 | |
49 | |
50 | (*) Each key is issued a serial number of type key_serial_t that is unique for |
51 | the lifetime of that key. All serial numbers are positive non-zero 32-bit |
52 | integers. |
53 | |
54 | Userspace programs can use a key's serial numbers as a way to gain access |
55 | to it, subject to permission checking. |
56 | |
57 | (*) Each key is of a defined "type". Types must be registered inside the |
58 | kernel by a kernel service (such as a filesystem) before keys of that type |
59 | can be added or used. Userspace programs cannot define new types directly. |
60 | |
61 | Key types are represented in the kernel by struct key_type. This defines a |
62 | number of operations that can be performed on a key of that type. |
63 | |
64 | Should a type be removed from the system, all the keys of that type will |
65 | be invalidated. |
66 | |
67 | (*) Each key has a description. This should be a printable string. The key |
68 | type provides an operation to perform a match between the description on a |
69 | key and a criterion string. |
70 | |
71 | (*) Each key has an owner user ID, a group ID and a permissions mask. These |
72 | are used to control what a process may do to a key from userspace, and |
73 | whether a kernel service will be able to find the key. |
74 | |
75 | (*) Each key can be set to expire at a specific time by the key type's |
76 | instantiation function. Keys can also be immortal. |
77 | |
78 | (*) Each key can have a payload. This is a quantity of data that represent the |
79 | actual "key". In the case of a keyring, this is a list of keys to which |
80 | the keyring links; in the case of a user-defined key, it's an arbitrary |
81 | blob of data. |
82 | |
83 | Having a payload is not required; and the payload can, in fact, just be a |
84 | value stored in the struct key itself. |
85 | |
86 | When a key is instantiated, the key type's instantiation function is |
87 | called with a blob of data, and that then creates the key's payload in |
88 | some way. |
89 | |
90 | Similarly, when userspace wants to read back the contents of the key, if |
91 | permitted, another key type operation will be called to convert the key's |
92 | attached payload back into a blob of data. |
93 | |
94 | (*) Each key can be in one of a number of basic states: |
95 | |
96 | (*) Uninstantiated. The key exists, but does not have any data attached. |
97 | Keys being requested from userspace will be in this state. |
98 | |
99 | (*) Instantiated. This is the normal state. The key is fully formed, and |
100 | has data attached. |
101 | |
102 | (*) Negative. This is a relatively short-lived state. The key acts as a |
103 | note saying that a previous call out to userspace failed, and acts as |
104 | a throttle on key lookups. A negative key can be updated to a normal |
105 | state. |
106 | |
107 | (*) Expired. Keys can have lifetimes set. If their lifetime is exceeded, |
108 | they traverse to this state. An expired key can be updated back to a |
109 | normal state. |
110 | |
111 | (*) Revoked. A key is put in this state by userspace action. It can't be |
112 | found or operated upon (apart from by unlinking it). |
113 | |
114 | (*) Dead. The key's type was unregistered, and so the key is now useless. |
115 | |
116 | Keys in the last three states are subject to garbage collection. See the |
117 | section on "Garbage collection". |
118 | |
119 | |
120 | ==================== |
121 | KEY SERVICE OVERVIEW |
122 | ==================== |
123 | |
124 | The key service provides a number of features besides keys: |
125 | |
126 | (*) The key service defines two special key types: |
127 | |
128 | (+) "keyring" |
129 | |
130 | Keyrings are special keys that contain a list of other keys. Keyring |
131 | lists can be modified using various system calls. Keyrings should not |
132 | be given a payload when created. |
133 | |
134 | (+) "user" |
135 | |
136 | A key of this type has a description and a payload that are arbitrary |
137 | blobs of data. These can be created, updated and read by userspace, |
138 | and aren't intended for use by kernel services. |
139 | |
140 | (*) Each process subscribes to three keyrings: a thread-specific keyring, a |
141 | process-specific keyring, and a session-specific keyring. |
142 | |
143 | The thread-specific keyring is discarded from the child when any sort of |
144 | clone, fork, vfork or execve occurs. A new keyring is created only when |
145 | required. |
146 | |
147 | The process-specific keyring is replaced with an empty one in the child on |
148 | clone, fork, vfork unless CLONE_THREAD is supplied, in which case it is |
149 | shared. execve also discards the process's process keyring and creates a |
150 | new one. |
151 | |
152 | The session-specific keyring is persistent across clone, fork, vfork and |
153 | execve, even when the latter executes a set-UID or set-GID binary. A |
154 | process can, however, replace its current session keyring with a new one |
155 | by using PR_JOIN_SESSION_KEYRING. It is permitted to request an anonymous |
156 | new one, or to attempt to create or join one of a specific name. |
157 | |
158 | The ownership of the thread keyring changes when the real UID and GID of |
159 | the thread changes. |
160 | |
161 | (*) Each user ID resident in the system holds two special keyrings: a user |
162 | specific keyring and a default user session keyring. The default session |
163 | keyring is initialised with a link to the user-specific keyring. |
164 | |
165 | When a process changes its real UID, if it used to have no session key, it |
166 | will be subscribed to the default session key for the new UID. |
167 | |
168 | If a process attempts to access its session key when it doesn't have one, |
169 | it will be subscribed to the default for its current UID. |
170 | |
171 | (*) Each user has two quotas against which the keys they own are tracked. One |
172 | limits the total number of keys and keyrings, the other limits the total |
173 | amount of description and payload space that can be consumed. |
174 | |
175 | The user can view information on this and other statistics through procfs |
176 | files. The root user may also alter the quota limits through sysctl files |
177 | (see the section "New procfs files"). |
178 | |
179 | Process-specific and thread-specific keyrings are not counted towards a |
180 | user's quota. |
181 | |
182 | If a system call that modifies a key or keyring in some way would put the |
183 | user over quota, the operation is refused and error EDQUOT is returned. |
184 | |
185 | (*) There's a system call interface by which userspace programs can create and |
186 | manipulate keys and keyrings. |
187 | |
188 | (*) There's a kernel interface by which services can register types and search |
189 | for keys. |
190 | |
191 | (*) There's a way for the a search done from the kernel to call back to |
192 | userspace to request a key that can't be found in a process's keyrings. |
193 | |
194 | (*) An optional filesystem is available through which the key database can be |
195 | viewed and manipulated. |
196 | |
197 | |
198 | ====================== |
199 | KEY ACCESS PERMISSIONS |
200 | ====================== |
201 | |
202 | Keys have an owner user ID, a group access ID, and a permissions mask. The mask |
203 | has up to eight bits each for possessor, user, group and other access. Only |
204 | six of each set of eight bits are defined. These permissions granted are: |
205 | |
206 | (*) View |
207 | |
208 | This permits a key or keyring's attributes to be viewed - including key |
209 | type and description. |
210 | |
211 | (*) Read |
212 | |
213 | This permits a key's payload to be viewed or a keyring's list of linked |
214 | keys. |
215 | |
216 | (*) Write |
217 | |
218 | This permits a key's payload to be instantiated or updated, or it allows a |
219 | link to be added to or removed from a keyring. |
220 | |
221 | (*) Search |
222 | |
223 | This permits keyrings to be searched and keys to be found. Searches can |
224 | only recurse into nested keyrings that have search permission set. |
225 | |
226 | (*) Link |
227 | |
228 | This permits a key or keyring to be linked to. To create a link from a |
229 | keyring to a key, a process must have Write permission on the keyring and |
230 | Link permission on the key. |
231 | |
232 | (*) Set Attribute |
233 | |
234 | This permits a key's UID, GID and permissions mask to be changed. |
235 | |
236 | For changing the ownership, group ID or permissions mask, being the owner of |
237 | the key or having the sysadmin capability is sufficient. |
238 | |
239 | |
240 | =============== |
241 | SELINUX SUPPORT |
242 | =============== |
243 | |
244 | The security class "key" has been added to SELinux so that mandatory access |
245 | controls can be applied to keys created within various contexts. This support |
246 | is preliminary, and is likely to change quite significantly in the near future. |
247 | Currently, all of the basic permissions explained above are provided in SELinux |
248 | as well; SELinux is simply invoked after all basic permission checks have been |
249 | performed. |
250 | |
251 | The value of the file /proc/self/attr/keycreate influences the labeling of |
252 | newly-created keys. If the contents of that file correspond to an SELinux |
253 | security context, then the key will be assigned that context. Otherwise, the |
254 | key will be assigned the current context of the task that invoked the key |
255 | creation request. Tasks must be granted explicit permission to assign a |
256 | particular context to newly-created keys, using the "create" permission in the |
257 | key security class. |
258 | |
259 | The default keyrings associated with users will be labeled with the default |
260 | context of the user if and only if the login programs have been instrumented to |
261 | properly initialize keycreate during the login process. Otherwise, they will |
262 | be labeled with the context of the login program itself. |
263 | |
264 | Note, however, that the default keyrings associated with the root user are |
265 | labeled with the default kernel context, since they are created early in the |
266 | boot process, before root has a chance to log in. |
267 | |
268 | The keyrings associated with new threads are each labeled with the context of |
269 | their associated thread, and both session and process keyrings are handled |
270 | similarly. |
271 | |
272 | |
273 | ================ |
274 | NEW PROCFS FILES |
275 | ================ |
276 | |
277 | Two files have been added to procfs by which an administrator can find out |
278 | about the status of the key service: |
279 | |
280 | (*) /proc/keys |
281 | |
282 | This lists the keys that are currently viewable by the task reading the |
283 | file, giving information about their type, description and permissions. |
284 | It is not possible to view the payload of the key this way, though some |
285 | information about it may be given. |
286 | |
287 | The only keys included in the list are those that grant View permission to |
288 | the reading process whether or not it possesses them. Note that LSM |
289 | security checks are still performed, and may further filter out keys that |
290 | the current process is not authorised to view. |
291 | |
292 | The contents of the file look like this: |
293 | |
294 | SERIAL FLAGS USAGE EXPY PERM UID GID TYPE DESCRIPTION: SUMMARY |
295 | 00000001 I----- 39 perm 1f3f0000 0 0 keyring _uid_ses.0: 1/4 |
296 | 00000002 I----- 2 perm 1f3f0000 0 0 keyring _uid.0: empty |
297 | 00000007 I----- 1 perm 1f3f0000 0 0 keyring _pid.1: empty |
298 | 0000018d I----- 1 perm 1f3f0000 0 0 keyring _pid.412: empty |
299 | 000004d2 I--Q-- 1 perm 1f3f0000 32 -1 keyring _uid.32: 1/4 |
300 | 000004d3 I--Q-- 3 perm 1f3f0000 32 -1 keyring _uid_ses.32: empty |
301 | 00000892 I--QU- 1 perm 1f000000 0 0 user metal:copper: 0 |
302 | 00000893 I--Q-N 1 35s 1f3f0000 0 0 user metal:silver: 0 |
303 | 00000894 I--Q-- 1 10h 003f0000 0 0 user metal:gold: 0 |
304 | |
305 | The flags are: |
306 | |
307 | I Instantiated |
308 | R Revoked |
309 | D Dead |
310 | Q Contributes to user's quota |
311 | U Under construction by callback to userspace |
312 | N Negative key |
313 | |
314 | This file must be enabled at kernel configuration time as it allows anyone |
315 | to list the keys database. |
316 | |
317 | (*) /proc/key-users |
318 | |
319 | This file lists the tracking data for each user that has at least one key |
320 | on the system. Such data includes quota information and statistics: |
321 | |
322 | [root@andromeda root]# cat /proc/key-users |
323 | 0: 46 45/45 1/100 13/10000 |
324 | 29: 2 2/2 2/100 40/10000 |
325 | 32: 2 2/2 2/100 40/10000 |
326 | 38: 2 2/2 2/100 40/10000 |
327 | |
328 | The format of each line is |
329 | <UID>: User ID to which this applies |
330 | <usage> Structure refcount |
331 | <inst>/<keys> Total number of keys and number instantiated |
332 | <keys>/<max> Key count quota |
333 | <bytes>/<max> Key size quota |
334 | |
335 | |
336 | Four new sysctl files have been added also for the purpose of controlling the |
337 | quota limits on keys: |
338 | |
339 | (*) /proc/sys/kernel/keys/root_maxkeys |
340 | /proc/sys/kernel/keys/root_maxbytes |
341 | |
342 | These files hold the maximum number of keys that root may have and the |
343 | maximum total number of bytes of data that root may have stored in those |
344 | keys. |
345 | |
346 | (*) /proc/sys/kernel/keys/maxkeys |
347 | /proc/sys/kernel/keys/maxbytes |
348 | |
349 | These files hold the maximum number of keys that each non-root user may |
350 | have and the maximum total number of bytes of data that each of those |
351 | users may have stored in their keys. |
352 | |
353 | Root may alter these by writing each new limit as a decimal number string to |
354 | the appropriate file. |
355 | |
356 | |
357 | =============================== |
358 | USERSPACE SYSTEM CALL INTERFACE |
359 | =============================== |
360 | |
361 | Userspace can manipulate keys directly through three new syscalls: add_key, |
362 | request_key and keyctl. The latter provides a number of functions for |
363 | manipulating keys. |
364 | |
365 | When referring to a key directly, userspace programs should use the key's |
366 | serial number (a positive 32-bit integer). However, there are some special |
367 | values available for referring to special keys and keyrings that relate to the |
368 | process making the call: |
369 | |
370 | CONSTANT VALUE KEY REFERENCED |
371 | ============================== ====== =========================== |
372 | KEY_SPEC_THREAD_KEYRING -1 thread-specific keyring |
373 | KEY_SPEC_PROCESS_KEYRING -2 process-specific keyring |
374 | KEY_SPEC_SESSION_KEYRING -3 session-specific keyring |
375 | KEY_SPEC_USER_KEYRING -4 UID-specific keyring |
376 | KEY_SPEC_USER_SESSION_KEYRING -5 UID-session keyring |
377 | KEY_SPEC_GROUP_KEYRING -6 GID-specific keyring |
378 | KEY_SPEC_REQKEY_AUTH_KEY -7 assumed request_key() |
379 | authorisation key |
380 | |
381 | |
382 | The main syscalls are: |
383 | |
384 | (*) Create a new key of given type, description and payload and add it to the |
385 | nominated keyring: |
386 | |
387 | key_serial_t add_key(const char *type, const char *desc, |
388 | const void *payload, size_t plen, |
389 | key_serial_t keyring); |
390 | |
391 | If a key of the same type and description as that proposed already exists |
392 | in the keyring, this will try to update it with the given payload, or it |
393 | will return error EEXIST if that function is not supported by the key |
394 | type. The process must also have permission to write to the key to be able |
395 | to update it. The new key will have all user permissions granted and no |
396 | group or third party permissions. |
397 | |
398 | Otherwise, this will attempt to create a new key of the specified type and |
399 | description, and to instantiate it with the supplied payload and attach it |
400 | to the keyring. In this case, an error will be generated if the process |
401 | does not have permission to write to the keyring. |
402 | |
403 | The payload is optional, and the pointer can be NULL if not required by |
404 | the type. The payload is plen in size, and plen can be zero for an empty |
405 | payload. |
406 | |
407 | A new keyring can be generated by setting type "keyring", the keyring name |
408 | as the description (or NULL) and setting the payload to NULL. |
409 | |
410 | User defined keys can be created by specifying type "user". It is |
411 | recommended that a user defined key's description by prefixed with a type |
412 | ID and a colon, such as "krb5tgt:" for a Kerberos 5 ticket granting |
413 | ticket. |
414 | |
415 | Any other type must have been registered with the kernel in advance by a |
416 | kernel service such as a filesystem. |
417 | |
418 | The ID of the new or updated key is returned if successful. |
419 | |
420 | |
421 | (*) Search the process's keyrings for a key, potentially calling out to |
422 | userspace to create it. |
423 | |
424 | key_serial_t request_key(const char *type, const char *description, |
425 | const char *callout_info, |
426 | key_serial_t dest_keyring); |
427 | |
428 | This function searches all the process's keyrings in the order thread, |
429 | process, session for a matching key. This works very much like |
430 | KEYCTL_SEARCH, including the optional attachment of the discovered key to |
431 | a keyring. |
432 | |
433 | If a key cannot be found, and if callout_info is not NULL, then |
434 | /sbin/request-key will be invoked in an attempt to obtain a key. The |
435 | callout_info string will be passed as an argument to the program. |
436 | |
437 | See also Documentation/keys-request-key.txt. |
438 | |
439 | |
440 | The keyctl syscall functions are: |
441 | |
442 | (*) Map a special key ID to a real key ID for this process: |
443 | |
444 | key_serial_t keyctl(KEYCTL_GET_KEYRING_ID, key_serial_t id, |
445 | int create); |
446 | |
447 | The special key specified by "id" is looked up (with the key being created |
448 | if necessary) and the ID of the key or keyring thus found is returned if |
449 | it exists. |
450 | |
451 | If the key does not yet exist, the key will be created if "create" is |
452 | non-zero; and the error ENOKEY will be returned if "create" is zero. |
453 | |
454 | |
455 | (*) Replace the session keyring this process subscribes to with a new one: |
456 | |
457 | key_serial_t keyctl(KEYCTL_JOIN_SESSION_KEYRING, const char *name); |
458 | |
459 | If name is NULL, an anonymous keyring is created attached to the process |
460 | as its session keyring, displacing the old session keyring. |
461 | |
462 | If name is not NULL, if a keyring of that name exists, the process |
463 | attempts to attach it as the session keyring, returning an error if that |
464 | is not permitted; otherwise a new keyring of that name is created and |
465 | attached as the session keyring. |
466 | |
467 | To attach to a named keyring, the keyring must have search permission for |
468 | the process's ownership. |
469 | |
470 | The ID of the new session keyring is returned if successful. |
471 | |
472 | |
473 | (*) Update the specified key: |
474 | |
475 | long keyctl(KEYCTL_UPDATE, key_serial_t key, const void *payload, |
476 | size_t plen); |
477 | |
478 | This will try to update the specified key with the given payload, or it |
479 | will return error EOPNOTSUPP if that function is not supported by the key |
480 | type. The process must also have permission to write to the key to be able |
481 | to update it. |
482 | |
483 | The payload is of length plen, and may be absent or empty as for |
484 | add_key(). |
485 | |
486 | |
487 | (*) Revoke a key: |
488 | |
489 | long keyctl(KEYCTL_REVOKE, key_serial_t key); |
490 | |
491 | This makes a key unavailable for further operations. Further attempts to |
492 | use the key will be met with error EKEYREVOKED, and the key will no longer |
493 | be findable. |
494 | |
495 | |
496 | (*) Change the ownership of a key: |
497 | |
498 | long keyctl(KEYCTL_CHOWN, key_serial_t key, uid_t uid, gid_t gid); |
499 | |
500 | This function permits a key's owner and group ID to be changed. Either one |
501 | of uid or gid can be set to -1 to suppress that change. |
502 | |
503 | Only the superuser can change a key's owner to something other than the |
504 | key's current owner. Similarly, only the superuser can change a key's |
505 | group ID to something other than the calling process's group ID or one of |
506 | its group list members. |
507 | |
508 | |
509 | (*) Change the permissions mask on a key: |
510 | |
511 | long keyctl(KEYCTL_SETPERM, key_serial_t key, key_perm_t perm); |
512 | |
513 | This function permits the owner of a key or the superuser to change the |
514 | permissions mask on a key. |
515 | |
516 | Only bits the available bits are permitted; if any other bits are set, |
517 | error EINVAL will be returned. |
518 | |
519 | |
520 | (*) Describe a key: |
521 | |
522 | long keyctl(KEYCTL_DESCRIBE, key_serial_t key, char *buffer, |
523 | size_t buflen); |
524 | |
525 | This function returns a summary of the key's attributes (but not its |
526 | payload data) as a string in the buffer provided. |
527 | |
528 | Unless there's an error, it always returns the amount of data it could |
529 | produce, even if that's too big for the buffer, but it won't copy more |
530 | than requested to userspace. If the buffer pointer is NULL then no copy |
531 | will take place. |
532 | |
533 | A process must have view permission on the key for this function to be |
534 | successful. |
535 | |
536 | If successful, a string is placed in the buffer in the following format: |
537 | |
538 | <type>;<uid>;<gid>;<perm>;<description> |
539 | |
540 | Where type and description are strings, uid and gid are decimal, and perm |
541 | is hexadecimal. A NUL character is included at the end of the string if |
542 | the buffer is sufficiently big. |
543 | |
544 | This can be parsed with |
545 | |
546 | sscanf(buffer, "%[^;];%d;%d;%o;%s", type, &uid, &gid, &mode, desc); |
547 | |
548 | |
549 | (*) Clear out a keyring: |
550 | |
551 | long keyctl(KEYCTL_CLEAR, key_serial_t keyring); |
552 | |
553 | This function clears the list of keys attached to a keyring. The calling |
554 | process must have write permission on the keyring, and it must be a |
555 | keyring (or else error ENOTDIR will result). |
556 | |
557 | |
558 | (*) Link a key into a keyring: |
559 | |
560 | long keyctl(KEYCTL_LINK, key_serial_t keyring, key_serial_t key); |
561 | |
562 | This function creates a link from the keyring to the key. The process must |
563 | have write permission on the keyring and must have link permission on the |
564 | key. |
565 | |
566 | Should the keyring not be a keyring, error ENOTDIR will result; and if the |
567 | keyring is full, error ENFILE will result. |
568 | |
569 | The link procedure checks the nesting of the keyrings, returning ELOOP if |
570 | it appears too deep or EDEADLK if the link would introduce a cycle. |
571 | |
572 | Any links within the keyring to keys that match the new key in terms of |
573 | type and description will be discarded from the keyring as the new one is |
574 | added. |
575 | |
576 | |
577 | (*) Unlink a key or keyring from another keyring: |
578 | |
579 | long keyctl(KEYCTL_UNLINK, key_serial_t keyring, key_serial_t key); |
580 | |
581 | This function looks through the keyring for the first link to the |
582 | specified key, and removes it if found. Subsequent links to that key are |
583 | ignored. The process must have write permission on the keyring. |
584 | |
585 | If the keyring is not a keyring, error ENOTDIR will result; and if the key |
586 | is not present, error ENOENT will be the result. |
587 | |
588 | |
589 | (*) Search a keyring tree for a key: |
590 | |
591 | key_serial_t keyctl(KEYCTL_SEARCH, key_serial_t keyring, |
592 | const char *type, const char *description, |
593 | key_serial_t dest_keyring); |
594 | |
595 | This searches the keyring tree headed by the specified keyring until a key |
596 | is found that matches the type and description criteria. Each keyring is |
597 | checked for keys before recursion into its children occurs. |
598 | |
599 | The process must have search permission on the top level keyring, or else |
600 | error EACCES will result. Only keyrings that the process has search |
601 | permission on will be recursed into, and only keys and keyrings for which |
602 | a process has search permission can be matched. If the specified keyring |
603 | is not a keyring, ENOTDIR will result. |
604 | |
605 | If the search succeeds, the function will attempt to link the found key |
606 | into the destination keyring if one is supplied (non-zero ID). All the |
607 | constraints applicable to KEYCTL_LINK apply in this case too. |
608 | |
609 | Error ENOKEY, EKEYREVOKED or EKEYEXPIRED will be returned if the search |
610 | fails. On success, the resulting key ID will be returned. |
611 | |
612 | |
613 | (*) Read the payload data from a key: |
614 | |
615 | long keyctl(KEYCTL_READ, key_serial_t keyring, char *buffer, |
616 | size_t buflen); |
617 | |
618 | This function attempts to read the payload data from the specified key |
619 | into the buffer. The process must have read permission on the key to |
620 | succeed. |
621 | |
622 | The returned data will be processed for presentation by the key type. For |
623 | instance, a keyring will return an array of key_serial_t entries |
624 | representing the IDs of all the keys to which it is subscribed. The user |
625 | defined key type will return its data as is. If a key type does not |
626 | implement this function, error EOPNOTSUPP will result. |
627 | |
628 | As much of the data as can be fitted into the buffer will be copied to |
629 | userspace if the buffer pointer is not NULL. |
630 | |
631 | On a successful return, the function will always return the amount of data |
632 | available rather than the amount copied. |
633 | |
634 | |
635 | (*) Instantiate a partially constructed key. |
636 | |
637 | long keyctl(KEYCTL_INSTANTIATE, key_serial_t key, |
638 | const void *payload, size_t plen, |
639 | key_serial_t keyring); |
640 | |
641 | If the kernel calls back to userspace to complete the instantiation of a |
642 | key, userspace should use this call to supply data for the key before the |
643 | invoked process returns, or else the key will be marked negative |
644 | automatically. |
645 | |
646 | The process must have write access on the key to be able to instantiate |
647 | it, and the key must be uninstantiated. |
648 | |
649 | If a keyring is specified (non-zero), the key will also be linked into |
650 | that keyring, however all the constraints applying in KEYCTL_LINK apply in |
651 | this case too. |
652 | |
653 | The payload and plen arguments describe the payload data as for add_key(). |
654 | |
655 | |
656 | (*) Negatively instantiate a partially constructed key. |
657 | |
658 | long keyctl(KEYCTL_NEGATE, key_serial_t key, |
659 | unsigned timeout, key_serial_t keyring); |
660 | |
661 | If the kernel calls back to userspace to complete the instantiation of a |
662 | key, userspace should use this call mark the key as negative before the |
663 | invoked process returns if it is unable to fulfil the request. |
664 | |
665 | The process must have write access on the key to be able to instantiate |
666 | it, and the key must be uninstantiated. |
667 | |
668 | If a keyring is specified (non-zero), the key will also be linked into |
669 | that keyring, however all the constraints applying in KEYCTL_LINK apply in |
670 | this case too. |
671 | |
672 | |
673 | (*) Set the default request-key destination keyring. |
674 | |
675 | long keyctl(KEYCTL_SET_REQKEY_KEYRING, int reqkey_defl); |
676 | |
677 | This sets the default keyring to which implicitly requested keys will be |
678 | attached for this thread. reqkey_defl should be one of these constants: |
679 | |
680 | CONSTANT VALUE NEW DEFAULT KEYRING |
681 | ====================================== ====== ======================= |
682 | KEY_REQKEY_DEFL_NO_CHANGE -1 No change |
683 | KEY_REQKEY_DEFL_DEFAULT 0 Default[1] |
684 | KEY_REQKEY_DEFL_THREAD_KEYRING 1 Thread keyring |
685 | KEY_REQKEY_DEFL_PROCESS_KEYRING 2 Process keyring |
686 | KEY_REQKEY_DEFL_SESSION_KEYRING 3 Session keyring |
687 | KEY_REQKEY_DEFL_USER_KEYRING 4 User keyring |
688 | KEY_REQKEY_DEFL_USER_SESSION_KEYRING 5 User session keyring |
689 | KEY_REQKEY_DEFL_GROUP_KEYRING 6 Group keyring |
690 | |
691 | The old default will be returned if successful and error EINVAL will be |
692 | returned if reqkey_defl is not one of the above values. |
693 | |
694 | The default keyring can be overridden by the keyring indicated to the |
695 | request_key() system call. |
696 | |
697 | Note that this setting is inherited across fork/exec. |
698 | |
699 | [1] The default is: the thread keyring if there is one, otherwise |
700 | the process keyring if there is one, otherwise the session keyring if |
701 | there is one, otherwise the user default session keyring. |
702 | |
703 | |
704 | (*) Set the timeout on a key. |
705 | |
706 | long keyctl(KEYCTL_SET_TIMEOUT, key_serial_t key, unsigned timeout); |
707 | |
708 | This sets or clears the timeout on a key. The timeout can be 0 to clear |
709 | the timeout or a number of seconds to set the expiry time that far into |
710 | the future. |
711 | |
712 | The process must have attribute modification access on a key to set its |
713 | timeout. Timeouts may not be set with this function on negative, revoked |
714 | or expired keys. |
715 | |
716 | |
717 | (*) Assume the authority granted to instantiate a key |
718 | |
719 | long keyctl(KEYCTL_ASSUME_AUTHORITY, key_serial_t key); |
720 | |
721 | This assumes or divests the authority required to instantiate the |
722 | specified key. Authority can only be assumed if the thread has the |
723 | authorisation key associated with the specified key in its keyrings |
724 | somewhere. |
725 | |
726 | Once authority is assumed, searches for keys will also search the |
727 | requester's keyrings using the requester's security label, UID, GID and |
728 | groups. |
729 | |
730 | If the requested authority is unavailable, error EPERM will be returned, |
731 | likewise if the authority has been revoked because the target key is |
732 | already instantiated. |
733 | |
734 | If the specified key is 0, then any assumed authority will be divested. |
735 | |
736 | The assumed authoritative key is inherited across fork and exec. |
737 | |
738 | |
739 | (*) Get the LSM security context attached to a key. |
740 | |
741 | long keyctl(KEYCTL_GET_SECURITY, key_serial_t key, char *buffer, |
742 | size_t buflen) |
743 | |
744 | This function returns a string that represents the LSM security context |
745 | attached to a key in the buffer provided. |
746 | |
747 | Unless there's an error, it always returns the amount of data it could |
748 | produce, even if that's too big for the buffer, but it won't copy more |
749 | than requested to userspace. If the buffer pointer is NULL then no copy |
750 | will take place. |
751 | |
752 | A NUL character is included at the end of the string if the buffer is |
753 | sufficiently big. This is included in the returned count. If no LSM is |
754 | in force then an empty string will be returned. |
755 | |
756 | A process must have view permission on the key for this function to be |
757 | successful. |
758 | |
759 | |
760 | (*) Install the calling process's session keyring on its parent. |
761 | |
762 | long keyctl(KEYCTL_SESSION_TO_PARENT); |
763 | |
764 | This functions attempts to install the calling process's session keyring |
765 | on to the calling process's parent, replacing the parent's current session |
766 | keyring. |
767 | |
768 | The calling process must have the same ownership as its parent, the |
769 | keyring must have the same ownership as the calling process, the calling |
770 | process must have LINK permission on the keyring and the active LSM module |
771 | mustn't deny permission, otherwise error EPERM will be returned. |
772 | |
773 | Error ENOMEM will be returned if there was insufficient memory to complete |
774 | the operation, otherwise 0 will be returned to indicate success. |
775 | |
776 | The keyring will be replaced next time the parent process leaves the |
777 | kernel and resumes executing userspace. |
778 | |
779 | |
780 | =============== |
781 | KERNEL SERVICES |
782 | =============== |
783 | |
784 | The kernel services for key management are fairly simple to deal with. They can |
785 | be broken down into two areas: keys and key types. |
786 | |
787 | Dealing with keys is fairly straightforward. Firstly, the kernel service |
788 | registers its type, then it searches for a key of that type. It should retain |
789 | the key as long as it has need of it, and then it should release it. For a |
790 | filesystem or device file, a search would probably be performed during the open |
791 | call, and the key released upon close. How to deal with conflicting keys due to |
792 | two different users opening the same file is left to the filesystem author to |
793 | solve. |
794 | |
795 | To access the key manager, the following header must be #included: |
796 | |
797 | <linux/key.h> |
798 | |
799 | Specific key types should have a header file under include/keys/ that should be |
800 | used to access that type. For keys of type "user", for example, that would be: |
801 | |
802 | <keys/user-type.h> |
803 | |
804 | Note that there are two different types of pointers to keys that may be |
805 | encountered: |
806 | |
807 | (*) struct key * |
808 | |
809 | This simply points to the key structure itself. Key structures will be at |
810 | least four-byte aligned. |
811 | |
812 | (*) key_ref_t |
813 | |
814 | This is equivalent to a struct key *, but the least significant bit is set |
815 | if the caller "possesses" the key. By "possession" it is meant that the |
816 | calling processes has a searchable link to the key from one of its |
817 | keyrings. There are three functions for dealing with these: |
818 | |
819 | key_ref_t make_key_ref(const struct key *key, |
820 | unsigned long possession); |
821 | |
822 | struct key *key_ref_to_ptr(const key_ref_t key_ref); |
823 | |
824 | unsigned long is_key_possessed(const key_ref_t key_ref); |
825 | |
826 | The first function constructs a key reference from a key pointer and |
827 | possession information (which must be 0 or 1 and not any other value). |
828 | |
829 | The second function retrieves the key pointer from a reference and the |
830 | third retrieves the possession flag. |
831 | |
832 | When accessing a key's payload contents, certain precautions must be taken to |
833 | prevent access vs modification races. See the section "Notes on accessing |
834 | payload contents" for more information. |
835 | |
836 | (*) To search for a key, call: |
837 | |
838 | struct key *request_key(const struct key_type *type, |
839 | const char *description, |
840 | const char *callout_info); |
841 | |
842 | This is used to request a key or keyring with a description that matches |
843 | the description specified according to the key type's match function. This |
844 | permits approximate matching to occur. If callout_string is not NULL, then |
845 | /sbin/request-key will be invoked in an attempt to obtain the key from |
846 | userspace. In that case, callout_string will be passed as an argument to |
847 | the program. |
848 | |
849 | Should the function fail error ENOKEY, EKEYEXPIRED or EKEYREVOKED will be |
850 | returned. |
851 | |
852 | If successful, the key will have been attached to the default keyring for |
853 | implicitly obtained request-key keys, as set by KEYCTL_SET_REQKEY_KEYRING. |
854 | |
855 | See also Documentation/keys-request-key.txt. |
856 | |
857 | |
858 | (*) To search for a key, passing auxiliary data to the upcaller, call: |
859 | |
860 | struct key *request_key_with_auxdata(const struct key_type *type, |
861 | const char *description, |
862 | const void *callout_info, |
863 | size_t callout_len, |
864 | void *aux); |
865 | |
866 | This is identical to request_key(), except that the auxiliary data is |
867 | passed to the key_type->request_key() op if it exists, and the callout_info |
868 | is a blob of length callout_len, if given (the length may be 0). |
869 | |
870 | |
871 | (*) A key can be requested asynchronously by calling one of: |
872 | |
873 | struct key *request_key_async(const struct key_type *type, |
874 | const char *description, |
875 | const void *callout_info, |
876 | size_t callout_len); |
877 | |
878 | or: |
879 | |
880 | struct key *request_key_async_with_auxdata(const struct key_type *type, |
881 | const char *description, |
882 | const char *callout_info, |
883 | size_t callout_len, |
884 | void *aux); |
885 | |
886 | which are asynchronous equivalents of request_key() and |
887 | request_key_with_auxdata() respectively. |
888 | |
889 | These two functions return with the key potentially still under |
890 | construction. To wait for construction completion, the following should be |
891 | called: |
892 | |
893 | int wait_for_key_construction(struct key *key, bool intr); |
894 | |
895 | The function will wait for the key to finish being constructed and then |
896 | invokes key_validate() to return an appropriate value to indicate the state |
897 | of the key (0 indicates the key is usable). |
898 | |
899 | If intr is true, then the wait can be interrupted by a signal, in which |
900 | case error ERESTARTSYS will be returned. |
901 | |
902 | |
903 | (*) When it is no longer required, the key should be released using: |
904 | |
905 | void key_put(struct key *key); |
906 | |
907 | Or: |
908 | |
909 | void key_ref_put(key_ref_t key_ref); |
910 | |
911 | These can be called from interrupt context. If CONFIG_KEYS is not set then |
912 | the argument will not be parsed. |
913 | |
914 | |
915 | (*) Extra references can be made to a key by calling the following function: |
916 | |
917 | struct key *key_get(struct key *key); |
918 | |
919 | These need to be disposed of by calling key_put() when they've been |
920 | finished with. The key pointer passed in will be returned. If the pointer |
921 | is NULL or CONFIG_KEYS is not set then the key will not be dereferenced and |
922 | no increment will take place. |
923 | |
924 | |
925 | (*) A key's serial number can be obtained by calling: |
926 | |
927 | key_serial_t key_serial(struct key *key); |
928 | |
929 | If key is NULL or if CONFIG_KEYS is not set then 0 will be returned (in the |
930 | latter case without parsing the argument). |
931 | |
932 | |
933 | (*) If a keyring was found in the search, this can be further searched by: |
934 | |
935 | key_ref_t keyring_search(key_ref_t keyring_ref, |
936 | const struct key_type *type, |
937 | const char *description) |
938 | |
939 | This searches the keyring tree specified for a matching key. Error ENOKEY |
940 | is returned upon failure (use IS_ERR/PTR_ERR to determine). If successful, |
941 | the returned key will need to be released. |
942 | |
943 | The possession attribute from the keyring reference is used to control |
944 | access through the permissions mask and is propagated to the returned key |
945 | reference pointer if successful. |
946 | |
947 | |
948 | (*) To check the validity of a key, this function can be called: |
949 | |
950 | int validate_key(struct key *key); |
951 | |
952 | This checks that the key in question hasn't expired or and hasn't been |
953 | revoked. Should the key be invalid, error EKEYEXPIRED or EKEYREVOKED will |
954 | be returned. If the key is NULL or if CONFIG_KEYS is not set then 0 will be |
955 | returned (in the latter case without parsing the argument). |
956 | |
957 | |
958 | (*) To register a key type, the following function should be called: |
959 | |
960 | int register_key_type(struct key_type *type); |
961 | |
962 | This will return error EEXIST if a type of the same name is already |
963 | present. |
964 | |
965 | |
966 | (*) To unregister a key type, call: |
967 | |
968 | void unregister_key_type(struct key_type *type); |
969 | |
970 | |
971 | Under some circumstances, it may be desirable to deal with a bundle of keys. |
972 | The facility provides access to the keyring type for managing such a bundle: |
973 | |
974 | struct key_type key_type_keyring; |
975 | |
976 | This can be used with a function such as request_key() to find a specific |
977 | keyring in a process's keyrings. A keyring thus found can then be searched |
978 | with keyring_search(). Note that it is not possible to use request_key() to |
979 | search a specific keyring, so using keyrings in this way is of limited utility. |
980 | |
981 | |
982 | =================================== |
983 | NOTES ON ACCESSING PAYLOAD CONTENTS |
984 | =================================== |
985 | |
986 | The simplest payload is just a number in key->payload.value. In this case, |
987 | there's no need to indulge in RCU or locking when accessing the payload. |
988 | |
989 | More complex payload contents must be allocated and a pointer to them set in |
990 | key->payload.data. One of the following ways must be selected to access the |
991 | data: |
992 | |
993 | (1) Unmodifiable key type. |
994 | |
995 | If the key type does not have a modify method, then the key's payload can |
996 | be accessed without any form of locking, provided that it's known to be |
997 | instantiated (uninstantiated keys cannot be "found"). |
998 | |
999 | (2) The key's semaphore. |
1000 | |
1001 | The semaphore could be used to govern access to the payload and to control |
1002 | the payload pointer. It must be write-locked for modifications and would |
1003 | have to be read-locked for general access. The disadvantage of doing this |
1004 | is that the accessor may be required to sleep. |
1005 | |
1006 | (3) RCU. |
1007 | |
1008 | RCU must be used when the semaphore isn't already held; if the semaphore |
1009 | is held then the contents can't change under you unexpectedly as the |
1010 | semaphore must still be used to serialise modifications to the key. The |
1011 | key management code takes care of this for the key type. |
1012 | |
1013 | However, this means using: |
1014 | |
1015 | rcu_read_lock() ... rcu_dereference() ... rcu_read_unlock() |
1016 | |
1017 | to read the pointer, and: |
1018 | |
1019 | rcu_dereference() ... rcu_assign_pointer() ... call_rcu() |
1020 | |
1021 | to set the pointer and dispose of the old contents after a grace period. |
1022 | Note that only the key type should ever modify a key's payload. |
1023 | |
1024 | Furthermore, an RCU controlled payload must hold a struct rcu_head for the |
1025 | use of call_rcu() and, if the payload is of variable size, the length of |
1026 | the payload. key->datalen cannot be relied upon to be consistent with the |
1027 | payload just dereferenced if the key's semaphore is not held. |
1028 | |
1029 | |
1030 | =================== |
1031 | DEFINING A KEY TYPE |
1032 | =================== |
1033 | |
1034 | A kernel service may want to define its own key type. For instance, an AFS |
1035 | filesystem might want to define a Kerberos 5 ticket key type. To do this, it |
1036 | author fills in a key_type struct and registers it with the system. |
1037 | |
1038 | Source files that implement key types should include the following header file: |
1039 | |
1040 | <linux/key-type.h> |
1041 | |
1042 | The structure has a number of fields, some of which are mandatory: |
1043 | |
1044 | (*) const char *name |
1045 | |
1046 | The name of the key type. This is used to translate a key type name |
1047 | supplied by userspace into a pointer to the structure. |
1048 | |
1049 | |
1050 | (*) size_t def_datalen |
1051 | |
1052 | This is optional - it supplies the default payload data length as |
1053 | contributed to the quota. If the key type's payload is always or almost |
1054 | always the same size, then this is a more efficient way to do things. |
1055 | |
1056 | The data length (and quota) on a particular key can always be changed |
1057 | during instantiation or update by calling: |
1058 | |
1059 | int key_payload_reserve(struct key *key, size_t datalen); |
1060 | |
1061 | With the revised data length. Error EDQUOT will be returned if this is not |
1062 | viable. |
1063 | |
1064 | |
1065 | (*) int (*instantiate)(struct key *key, const void *data, size_t datalen); |
1066 | |
1067 | This method is called to attach a payload to a key during construction. |
1068 | The payload attached need not bear any relation to the data passed to this |
1069 | function. |
1070 | |
1071 | If the amount of data attached to the key differs from the size in |
1072 | keytype->def_datalen, then key_payload_reserve() should be called. |
1073 | |
1074 | This method does not have to lock the key in order to attach a payload. |
1075 | The fact that KEY_FLAG_INSTANTIATED is not set in key->flags prevents |
1076 | anything else from gaining access to the key. |
1077 | |
1078 | It is safe to sleep in this method. |
1079 | |
1080 | |
1081 | (*) int (*update)(struct key *key, const void *data, size_t datalen); |
1082 | |
1083 | If this type of key can be updated, then this method should be provided. |
1084 | It is called to update a key's payload from the blob of data provided. |
1085 | |
1086 | key_payload_reserve() should be called if the data length might change |
1087 | before any changes are actually made. Note that if this succeeds, the type |
1088 | is committed to changing the key because it's already been altered, so all |
1089 | memory allocation must be done first. |
1090 | |
1091 | The key will have its semaphore write-locked before this method is called, |
1092 | but this only deters other writers; any changes to the key's payload must |
1093 | be made under RCU conditions, and call_rcu() must be used to dispose of |
1094 | the old payload. |
1095 | |
1096 | key_payload_reserve() should be called before the changes are made, but |
1097 | after all allocations and other potentially failing function calls are |
1098 | made. |
1099 | |
1100 | It is safe to sleep in this method. |
1101 | |
1102 | |
1103 | (*) int (*match)(const struct key *key, const void *desc); |
1104 | |
1105 | This method is called to match a key against a description. It should |
1106 | return non-zero if the two match, zero if they don't. |
1107 | |
1108 | This method should not need to lock the key in any way. The type and |
1109 | description can be considered invariant, and the payload should not be |
1110 | accessed (the key may not yet be instantiated). |
1111 | |
1112 | It is not safe to sleep in this method; the caller may hold spinlocks. |
1113 | |
1114 | |
1115 | (*) void (*revoke)(struct key *key); |
1116 | |
1117 | This method is optional. It is called to discard part of the payload |
1118 | data upon a key being revoked. The caller will have the key semaphore |
1119 | write-locked. |
1120 | |
1121 | It is safe to sleep in this method, though care should be taken to avoid |
1122 | a deadlock against the key semaphore. |
1123 | |
1124 | |
1125 | (*) void (*destroy)(struct key *key); |
1126 | |
1127 | This method is optional. It is called to discard the payload data on a key |
1128 | when it is being destroyed. |
1129 | |
1130 | This method does not need to lock the key to access the payload; it can |
1131 | consider the key as being inaccessible at this time. Note that the key's |
1132 | type may have been changed before this function is called. |
1133 | |
1134 | It is not safe to sleep in this method; the caller may hold spinlocks. |
1135 | |
1136 | |
1137 | (*) void (*describe)(const struct key *key, struct seq_file *p); |
1138 | |
1139 | This method is optional. It is called during /proc/keys reading to |
1140 | summarise a key's description and payload in text form. |
1141 | |
1142 | This method will be called with the RCU read lock held. rcu_dereference() |
1143 | should be used to read the payload pointer if the payload is to be |
1144 | accessed. key->datalen cannot be trusted to stay consistent with the |
1145 | contents of the payload. |
1146 | |
1147 | The description will not change, though the key's state may. |
1148 | |
1149 | It is not safe to sleep in this method; the RCU read lock is held by the |
1150 | caller. |
1151 | |
1152 | |
1153 | (*) long (*read)(const struct key *key, char __user *buffer, size_t buflen); |
1154 | |
1155 | This method is optional. It is called by KEYCTL_READ to translate the |
1156 | key's payload into something a blob of data for userspace to deal with. |
1157 | Ideally, the blob should be in the same format as that passed in to the |
1158 | instantiate and update methods. |
1159 | |
1160 | If successful, the blob size that could be produced should be returned |
1161 | rather than the size copied. |
1162 | |
1163 | This method will be called with the key's semaphore read-locked. This will |
1164 | prevent the key's payload changing. It is not necessary to use RCU locking |
1165 | when accessing the key's payload. It is safe to sleep in this method, such |
1166 | as might happen when the userspace buffer is accessed. |
1167 | |
1168 | |
1169 | (*) int (*request_key)(struct key_construction *cons, const char *op, |
1170 | void *aux); |
1171 | |
1172 | This method is optional. If provided, request_key() and friends will |
1173 | invoke this function rather than upcalling to /sbin/request-key to operate |
1174 | upon a key of this type. |
1175 | |
1176 | The aux parameter is as passed to request_key_async_with_auxdata() and |
1177 | similar or is NULL otherwise. Also passed are the construction record for |
1178 | the key to be operated upon and the operation type (currently only |
1179 | "create"). |
1180 | |
1181 | This method is permitted to return before the upcall is complete, but the |
1182 | following function must be called under all circumstances to complete the |
1183 | instantiation process, whether or not it succeeds, whether or not there's |
1184 | an error: |
1185 | |
1186 | void complete_request_key(struct key_construction *cons, int error); |
1187 | |
1188 | The error parameter should be 0 on success, -ve on error. The |
1189 | construction record is destroyed by this action and the authorisation key |
1190 | will be revoked. If an error is indicated, the key under construction |
1191 | will be negatively instantiated if it wasn't already instantiated. |
1192 | |
1193 | If this method returns an error, that error will be returned to the |
1194 | caller of request_key*(). complete_request_key() must be called prior to |
1195 | returning. |
1196 | |
1197 | The key under construction and the authorisation key can be found in the |
1198 | key_construction struct pointed to by cons: |
1199 | |
1200 | (*) struct key *key; |
1201 | |
1202 | The key under construction. |
1203 | |
1204 | (*) struct key *authkey; |
1205 | |
1206 | The authorisation key. |
1207 | |
1208 | |
1209 | ============================ |
1210 | REQUEST-KEY CALLBACK SERVICE |
1211 | ============================ |
1212 | |
1213 | To create a new key, the kernel will attempt to execute the following command |
1214 | line: |
1215 | |
1216 | /sbin/request-key create <key> <uid> <gid> \ |
1217 | <threadring> <processring> <sessionring> <callout_info> |
1218 | |
1219 | <key> is the key being constructed, and the three keyrings are the process |
1220 | keyrings from the process that caused the search to be issued. These are |
1221 | included for two reasons: |
1222 | |
1223 | (1) There may be an authentication token in one of the keyrings that is |
1224 | required to obtain the key, eg: a Kerberos Ticket-Granting Ticket. |
1225 | |
1226 | (2) The new key should probably be cached in one of these rings. |
1227 | |
1228 | This program should set it UID and GID to those specified before attempting to |
1229 | access any more keys. It may then look around for a user specific process to |
1230 | hand the request off to (perhaps a path held in placed in another key by, for |
1231 | example, the KDE desktop manager). |
1232 | |
1233 | The program (or whatever it calls) should finish construction of the key by |
1234 | calling KEYCTL_INSTANTIATE, which also permits it to cache the key in one of |
1235 | the keyrings (probably the session ring) before returning. Alternatively, the |
1236 | key can be marked as negative with KEYCTL_NEGATE; this also permits the key to |
1237 | be cached in one of the keyrings. |
1238 | |
1239 | If it returns with the key remaining in the unconstructed state, the key will |
1240 | be marked as being negative, it will be added to the session keyring, and an |
1241 | error will be returned to the key requestor. |
1242 | |
1243 | Supplementary information may be provided from whoever or whatever invoked this |
1244 | service. This will be passed as the <callout_info> parameter. If no such |
1245 | information was made available, then "-" will be passed as this parameter |
1246 | instead. |
1247 | |
1248 | |
1249 | Similarly, the kernel may attempt to update an expired or a soon to expire key |
1250 | by executing: |
1251 | |
1252 | /sbin/request-key update <key> <uid> <gid> \ |
1253 | <threadring> <processring> <sessionring> |
1254 | |
1255 | In this case, the program isn't required to actually attach the key to a ring; |
1256 | the rings are provided for reference. |
1257 | |
1258 | |
1259 | ================== |
1260 | GARBAGE COLLECTION |
1261 | ================== |
1262 | |
1263 | Dead keys (for which the type has been removed) will be automatically unlinked |
1264 | from those keyrings that point to them and deleted as soon as possible by a |
1265 | background garbage collector. |
1266 | |
1267 | Similarly, revoked and expired keys will be garbage collected, but only after a |
1268 | certain amount of time has passed. This time is set as a number of seconds in: |
1269 | |
1270 | /proc/sys/kernel/keys/gc_delay |
1271 |
Branches:
ben-wpan
ben-wpan-stefan
javiroman/ks7010
jz-2.6.34
jz-2.6.34-rc5
jz-2.6.34-rc6
jz-2.6.34-rc7
jz-2.6.35
jz-2.6.36
jz-2.6.37
jz-2.6.38
jz-2.6.39
jz-3.0
jz-3.1
jz-3.11
jz-3.12
jz-3.13
jz-3.15
jz-3.16
jz-3.18-dt
jz-3.2
jz-3.3
jz-3.4
jz-3.5
jz-3.6
jz-3.6-rc2-pwm
jz-3.9
jz-3.9-clk
jz-3.9-rc8
jz47xx
jz47xx-2.6.38
master
Tags:
od-2011-09-04
od-2011-09-18
v2.6.34-rc5
v2.6.34-rc6
v2.6.34-rc7
v3.9