Contents of /alx-src/tags/kernel26-2.6.12-alx-r9/Documentation/keys.txt
Parent Directory | Revision Log
Revision 630 -
(show annotations)
(download)
Wed Mar 4 11:03:09 2009 UTC (15 years, 6 months ago) by niro
File MIME type: text/plain
File size: 33253 byte(s)
Wed Mar 4 11:03:09 2009 UTC (15 years, 6 months ago) by niro
File MIME type: text/plain
File size: 33253 byte(s)
Tag kernel26-2.6.12-alx-r9
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 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 | - New procfs files |
23 | - Userspace system call interface |
24 | - Kernel services |
25 | - Defining a key type |
26 | - Request-key callback service |
27 | - Key access filesystem |
28 | |
29 | |
30 | ============ |
31 | KEY OVERVIEW |
32 | ============ |
33 | |
34 | In this context, keys represent units of cryptographic data, authentication |
35 | tokens, keyrings, etc.. These are represented in the kernel by struct key. |
36 | |
37 | Each key has a number of attributes: |
38 | |
39 | - A serial number. |
40 | - A type. |
41 | - A description (for matching a key in a search). |
42 | - Access control information. |
43 | - An expiry time. |
44 | - A payload. |
45 | - State. |
46 | |
47 | |
48 | (*) Each key is issued a serial number of type key_serial_t that is unique |
49 | for the lifetime of that key. All serial numbers are positive non-zero |
50 | 32-bit integers. |
51 | |
52 | Userspace programs can use a key's serial numbers as a way to gain access |
53 | to it, subject to permission checking. |
54 | |
55 | (*) Each key is of a defined "type". Types must be registered inside the |
56 | kernel by a kernel service (such as a filesystem) before keys of that |
57 | type can be added or used. Userspace programs cannot define new types |
58 | directly. |
59 | |
60 | Key types are represented in the kernel by struct key_type. This defines |
61 | a number of operations that can be performed on a key of that type. |
62 | |
63 | Should a type be removed from the system, all the keys of that type will |
64 | be invalidated. |
65 | |
66 | (*) Each key has a description. This should be a printable string. The key |
67 | type provides an operation to perform a match between the description on |
68 | a key and a criterion string. |
69 | |
70 | (*) Each key has an owner user ID, a group ID and a permissions mask. These |
71 | are used to control what a process may do to a key from userspace, and |
72 | whether a kernel service will be able to find the key. |
73 | |
74 | (*) Each key can be set to expire at a specific time by the key type's |
75 | instantiation function. Keys can also be immortal. |
76 | |
77 | (*) Each key can have a payload. This is a quantity of data that represent |
78 | the actual "key". In the case of a keyring, this is a list of keys to |
79 | which the keyring links; in the case of a user-defined key, it's an |
80 | arbitrary blob of data. |
81 | |
82 | Having a payload is not required; and the payload can, in fact, just be a |
83 | value stored in the struct key itself. |
84 | |
85 | When a key is instantiated, the key type's instantiation function is |
86 | called with a blob of data, and that then creates the key's payload in |
87 | some way. |
88 | |
89 | Similarly, when userspace wants to read back the contents of the key, if |
90 | permitted, another key type operation will be called to convert the key's |
91 | attached payload back into a blob of data. |
92 | |
93 | (*) Each key can be in one of a number of basic states: |
94 | |
95 | (*) Uninstantiated. The key exists, but does not have any data |
96 | attached. Keys being requested from userspace will be in this state. |
97 | |
98 | (*) Instantiated. This is the normal state. The key is fully formed, and |
99 | has data attached. |
100 | |
101 | (*) Negative. This is a relatively short-lived state. The key acts as a |
102 | note saying that a previous call out to userspace failed, and acts as |
103 | a throttle on key lookups. A negative key can be updated to a normal |
104 | state. |
105 | |
106 | (*) Expired. Keys can have lifetimes set. If their lifetime is exceeded, |
107 | they traverse to this state. An expired key can be updated back to a |
108 | normal state. |
109 | |
110 | (*) Revoked. A key is put in this state by userspace action. It can't be |
111 | found or operated upon (apart from by unlinking it). |
112 | |
113 | (*) Dead. The key's type was unregistered, and so the key is now useless. |
114 | |
115 | |
116 | ==================== |
117 | KEY SERVICE OVERVIEW |
118 | ==================== |
119 | |
120 | The key service provides a number of features besides keys: |
121 | |
122 | (*) The key service defines two special key types: |
123 | |
124 | (+) "keyring" |
125 | |
126 | Keyrings are special keys that contain a list of other keys. Keyring |
127 | lists can be modified using various system calls. Keyrings should not |
128 | be given a payload when created. |
129 | |
130 | (+) "user" |
131 | |
132 | A key of this type has a description and a payload that are arbitrary |
133 | blobs of data. These can be created, updated and read by userspace, |
134 | and aren't intended for use by kernel services. |
135 | |
136 | (*) Each process subscribes to three keyrings: a thread-specific keyring, a |
137 | process-specific keyring, and a session-specific keyring. |
138 | |
139 | The thread-specific keyring is discarded from the child when any sort of |
140 | clone, fork, vfork or execve occurs. A new keyring is created only when |
141 | required. |
142 | |
143 | The process-specific keyring is replaced with an empty one in the child |
144 | on clone, fork, vfork unless CLONE_THREAD is supplied, in which case it |
145 | is shared. execve also discards the process's process keyring and creates |
146 | a new one. |
147 | |
148 | The session-specific keyring is persistent across clone, fork, vfork and |
149 | execve, even when the latter executes a set-UID or set-GID binary. A |
150 | process can, however, replace its current session keyring with a new one |
151 | by using PR_JOIN_SESSION_KEYRING. It is permitted to request an anonymous |
152 | new one, or to attempt to create or join one of a specific name. |
153 | |
154 | The ownership of the thread keyring changes when the real UID and GID of |
155 | the thread changes. |
156 | |
157 | (*) Each user ID resident in the system holds two special keyrings: a user |
158 | specific keyring and a default user session keyring. The default session |
159 | keyring is initialised with a link to the user-specific keyring. |
160 | |
161 | When a process changes its real UID, if it used to have no session key, it |
162 | will be subscribed to the default session key for the new UID. |
163 | |
164 | If a process attempts to access its session key when it doesn't have one, |
165 | it will be subscribed to the default for its current UID. |
166 | |
167 | (*) Each user has two quotas against which the keys they own are tracked. One |
168 | limits the total number of keys and keyrings, the other limits the total |
169 | amount of description and payload space that can be consumed. |
170 | |
171 | The user can view information on this and other statistics through procfs |
172 | files. |
173 | |
174 | Process-specific and thread-specific keyrings are not counted towards a |
175 | user's quota. |
176 | |
177 | If a system call that modifies a key or keyring in some way would put the |
178 | user over quota, the operation is refused and error EDQUOT is returned. |
179 | |
180 | (*) There's a system call interface by which userspace programs can create |
181 | and manipulate keys and keyrings. |
182 | |
183 | (*) There's a kernel interface by which services can register types and |
184 | search for keys. |
185 | |
186 | (*) There's a way for the a search done from the kernel to call back to |
187 | userspace to request a key that can't be found in a process's keyrings. |
188 | |
189 | (*) An optional filesystem is available through which the key database can be |
190 | viewed and manipulated. |
191 | |
192 | |
193 | ====================== |
194 | KEY ACCESS PERMISSIONS |
195 | ====================== |
196 | |
197 | Keys have an owner user ID, a group access ID, and a permissions mask. The |
198 | mask has up to eight bits each for user, group and other access. Only five of |
199 | each set of eight bits are defined. These permissions granted are: |
200 | |
201 | (*) View |
202 | |
203 | This permits a key or keyring's attributes to be viewed - including key |
204 | type and description. |
205 | |
206 | (*) Read |
207 | |
208 | This permits a key's payload to be viewed or a keyring's list of linked |
209 | keys. |
210 | |
211 | (*) Write |
212 | |
213 | This permits a key's payload to be instantiated or updated, or it allows |
214 | a link to be added to or removed from a keyring. |
215 | |
216 | (*) Search |
217 | |
218 | This permits keyrings to be searched and keys to be found. Searches can |
219 | only recurse into nested keyrings that have search permission set. |
220 | |
221 | (*) Link |
222 | |
223 | This permits a key or keyring to be linked to. To create a link from a |
224 | keyring to a key, a process must have Write permission on the keyring and |
225 | Link permission on the key. |
226 | |
227 | For changing the ownership, group ID or permissions mask, being the owner of |
228 | the key or having the sysadmin capability is sufficient. |
229 | |
230 | |
231 | ================ |
232 | NEW PROCFS FILES |
233 | ================ |
234 | |
235 | Two files have been added to procfs by which an administrator can find out |
236 | about the status of the key service: |
237 | |
238 | (*) /proc/keys |
239 | |
240 | This lists all the keys on the system, giving information about their |
241 | type, description and permissions. The payload of the key is not |
242 | available this way: |
243 | |
244 | SERIAL FLAGS USAGE EXPY PERM UID GID TYPE DESCRIPTION: SUMMARY |
245 | 00000001 I----- 39 perm 1f0000 0 0 keyring _uid_ses.0: 1/4 |
246 | 00000002 I----- 2 perm 1f0000 0 0 keyring _uid.0: empty |
247 | 00000007 I----- 1 perm 1f0000 0 0 keyring _pid.1: empty |
248 | 0000018d I----- 1 perm 1f0000 0 0 keyring _pid.412: empty |
249 | 000004d2 I--Q-- 1 perm 1f0000 32 -1 keyring _uid.32: 1/4 |
250 | 000004d3 I--Q-- 3 perm 1f0000 32 -1 keyring _uid_ses.32: empty |
251 | 00000892 I--QU- 1 perm 1f0000 0 0 user metal:copper: 0 |
252 | 00000893 I--Q-N 1 35s 1f0000 0 0 user metal:silver: 0 |
253 | 00000894 I--Q-- 1 10h 1f0000 0 0 user metal:gold: 0 |
254 | |
255 | The flags are: |
256 | |
257 | I Instantiated |
258 | R Revoked |
259 | D Dead |
260 | Q Contributes to user's quota |
261 | U Under contruction by callback to userspace |
262 | N Negative key |
263 | |
264 | This file must be enabled at kernel configuration time as it allows anyone |
265 | to list the keys database. |
266 | |
267 | (*) /proc/key-users |
268 | |
269 | This file lists the tracking data for each user that has at least one key |
270 | on the system. Such data includes quota information and statistics: |
271 | |
272 | [root@andromeda root]# cat /proc/key-users |
273 | 0: 46 45/45 1/100 13/10000 |
274 | 29: 2 2/2 2/100 40/10000 |
275 | 32: 2 2/2 2/100 40/10000 |
276 | 38: 2 2/2 2/100 40/10000 |
277 | |
278 | The format of each line is |
279 | <UID>: User ID to which this applies |
280 | <usage> Structure refcount |
281 | <inst>/<keys> Total number of keys and number instantiated |
282 | <keys>/<max> Key count quota |
283 | <bytes>/<max> Key size quota |
284 | |
285 | |
286 | =============================== |
287 | USERSPACE SYSTEM CALL INTERFACE |
288 | =============================== |
289 | |
290 | Userspace can manipulate keys directly through three new syscalls: add_key, |
291 | request_key and keyctl. The latter provides a number of functions for |
292 | manipulating keys. |
293 | |
294 | When referring to a key directly, userspace programs should use the key's |
295 | serial number (a positive 32-bit integer). However, there are some special |
296 | values available for referring to special keys and keyrings that relate to the |
297 | process making the call: |
298 | |
299 | CONSTANT VALUE KEY REFERENCED |
300 | ============================== ====== =========================== |
301 | KEY_SPEC_THREAD_KEYRING -1 thread-specific keyring |
302 | KEY_SPEC_PROCESS_KEYRING -2 process-specific keyring |
303 | KEY_SPEC_SESSION_KEYRING -3 session-specific keyring |
304 | KEY_SPEC_USER_KEYRING -4 UID-specific keyring |
305 | KEY_SPEC_USER_SESSION_KEYRING -5 UID-session keyring |
306 | KEY_SPEC_GROUP_KEYRING -6 GID-specific keyring |
307 | |
308 | |
309 | The main syscalls are: |
310 | |
311 | (*) Create a new key of given type, description and payload and add it to the |
312 | nominated keyring: |
313 | |
314 | key_serial_t add_key(const char *type, const char *desc, |
315 | const void *payload, size_t plen, |
316 | key_serial_t keyring); |
317 | |
318 | If a key of the same type and description as that proposed already exists |
319 | in the keyring, this will try to update it with the given payload, or it |
320 | will return error EEXIST if that function is not supported by the key |
321 | type. The process must also have permission to write to the key to be |
322 | able to update it. The new key will have all user permissions granted and |
323 | no group or third party permissions. |
324 | |
325 | Otherwise, this will attempt to create a new key of the specified type |
326 | and description, and to instantiate it with the supplied payload and |
327 | attach it to the keyring. In this case, an error will be generated if the |
328 | process does not have permission to write to the keyring. |
329 | |
330 | The payload is optional, and the pointer can be NULL if not required by |
331 | the type. The payload is plen in size, and plen can be zero for an empty |
332 | payload. |
333 | |
334 | A new keyring can be generated by setting type "keyring", the keyring |
335 | name as the description (or NULL) and setting the payload to NULL. |
336 | |
337 | User defined keys can be created by specifying type "user". It is |
338 | recommended that a user defined key's description by prefixed with a type |
339 | ID and a colon, such as "krb5tgt:" for a Kerberos 5 ticket granting |
340 | ticket. |
341 | |
342 | Any other type must have been registered with the kernel in advance by a |
343 | kernel service such as a filesystem. |
344 | |
345 | The ID of the new or updated key is returned if successful. |
346 | |
347 | |
348 | (*) Search the process's keyrings for a key, potentially calling out to |
349 | userspace to create it. |
350 | |
351 | key_serial_t request_key(const char *type, const char *description, |
352 | const char *callout_info, |
353 | key_serial_t dest_keyring); |
354 | |
355 | This function searches all the process's keyrings in the order thread, |
356 | process, session for a matching key. This works very much like |
357 | KEYCTL_SEARCH, including the optional attachment of the discovered key to |
358 | a keyring. |
359 | |
360 | If a key cannot be found, and if callout_info is not NULL, then |
361 | /sbin/request-key will be invoked in an attempt to obtain a key. The |
362 | callout_info string will be passed as an argument to the program. |
363 | |
364 | |
365 | The keyctl syscall functions are: |
366 | |
367 | (*) Map a special key ID to a real key ID for this process: |
368 | |
369 | key_serial_t keyctl(KEYCTL_GET_KEYRING_ID, key_serial_t id, |
370 | int create); |
371 | |
372 | The special key specified by "id" is looked up (with the key being |
373 | created if necessary) and the ID of the key or keyring thus found is |
374 | returned if it exists. |
375 | |
376 | If the key does not yet exist, the key will be created if "create" is |
377 | non-zero; and the error ENOKEY will be returned if "create" is zero. |
378 | |
379 | |
380 | (*) Replace the session keyring this process subscribes to with a new one: |
381 | |
382 | key_serial_t keyctl(KEYCTL_JOIN_SESSION_KEYRING, const char *name); |
383 | |
384 | If name is NULL, an anonymous keyring is created attached to the process |
385 | as its session keyring, displacing the old session keyring. |
386 | |
387 | If name is not NULL, if a keyring of that name exists, the process |
388 | attempts to attach it as the session keyring, returning an error if that |
389 | is not permitted; otherwise a new keyring of that name is created and |
390 | attached as the session keyring. |
391 | |
392 | To attach to a named keyring, the keyring must have search permission for |
393 | the process's ownership. |
394 | |
395 | The ID of the new session keyring is returned if successful. |
396 | |
397 | |
398 | (*) Update the specified key: |
399 | |
400 | long keyctl(KEYCTL_UPDATE, key_serial_t key, const void *payload, |
401 | size_t plen); |
402 | |
403 | This will try to update the specified key with the given payload, or it |
404 | will return error EOPNOTSUPP if that function is not supported by the key |
405 | type. The process must also have permission to write to the key to be |
406 | able to update it. |
407 | |
408 | The payload is of length plen, and may be absent or empty as for |
409 | add_key(). |
410 | |
411 | |
412 | (*) Revoke a key: |
413 | |
414 | long keyctl(KEYCTL_REVOKE, key_serial_t key); |
415 | |
416 | This makes a key unavailable for further operations. Further attempts to |
417 | use the key will be met with error EKEYREVOKED, and the key will no longer |
418 | be findable. |
419 | |
420 | |
421 | (*) Change the ownership of a key: |
422 | |
423 | long keyctl(KEYCTL_CHOWN, key_serial_t key, uid_t uid, gid_t gid); |
424 | |
425 | This function permits a key's owner and group ID to be changed. Either |
426 | one of uid or gid can be set to -1 to suppress that change. |
427 | |
428 | Only the superuser can change a key's owner to something other than the |
429 | key's current owner. Similarly, only the superuser can change a key's |
430 | group ID to something other than the calling process's group ID or one of |
431 | its group list members. |
432 | |
433 | |
434 | (*) Change the permissions mask on a key: |
435 | |
436 | long keyctl(KEYCTL_SETPERM, key_serial_t key, key_perm_t perm); |
437 | |
438 | This function permits the owner of a key or the superuser to change the |
439 | permissions mask on a key. |
440 | |
441 | Only bits the available bits are permitted; if any other bits are set, |
442 | error EINVAL will be returned. |
443 | |
444 | |
445 | (*) Describe a key: |
446 | |
447 | long keyctl(KEYCTL_DESCRIBE, key_serial_t key, char *buffer, |
448 | size_t buflen); |
449 | |
450 | This function returns a summary of the key's attributes (but not its |
451 | payload data) as a string in the buffer provided. |
452 | |
453 | Unless there's an error, it always returns the amount of data it could |
454 | produce, even if that's too big for the buffer, but it won't copy more |
455 | than requested to userspace. If the buffer pointer is NULL then no copy |
456 | will take place. |
457 | |
458 | A process must have view permission on the key for this function to be |
459 | successful. |
460 | |
461 | If successful, a string is placed in the buffer in the following format: |
462 | |
463 | <type>;<uid>;<gid>;<perm>;<description> |
464 | |
465 | Where type and description are strings, uid and gid are decimal, and perm |
466 | is hexadecimal. A NUL character is included at the end of the string if |
467 | the buffer is sufficiently big. |
468 | |
469 | This can be parsed with |
470 | |
471 | sscanf(buffer, "%[^;];%d;%d;%o;%s", type, &uid, &gid, &mode, desc); |
472 | |
473 | |
474 | (*) Clear out a keyring: |
475 | |
476 | long keyctl(KEYCTL_CLEAR, key_serial_t keyring); |
477 | |
478 | This function clears the list of keys attached to a keyring. The calling |
479 | process must have write permission on the keyring, and it must be a |
480 | keyring (or else error ENOTDIR will result). |
481 | |
482 | |
483 | (*) Link a key into a keyring: |
484 | |
485 | long keyctl(KEYCTL_LINK, key_serial_t keyring, key_serial_t key); |
486 | |
487 | This function creates a link from the keyring to the key. The process |
488 | must have write permission on the keyring and must have link permission |
489 | on the key. |
490 | |
491 | Should the keyring not be a keyring, error ENOTDIR will result; and if |
492 | the keyring is full, error ENFILE will result. |
493 | |
494 | The link procedure checks the nesting of the keyrings, returning ELOOP if |
495 | it appears to deep or EDEADLK if the link would introduce a cycle. |
496 | |
497 | |
498 | (*) Unlink a key or keyring from another keyring: |
499 | |
500 | long keyctl(KEYCTL_UNLINK, key_serial_t keyring, key_serial_t key); |
501 | |
502 | This function looks through the keyring for the first link to the |
503 | specified key, and removes it if found. Subsequent links to that key are |
504 | ignored. The process must have write permission on the keyring. |
505 | |
506 | If the keyring is not a keyring, error ENOTDIR will result; and if the |
507 | key is not present, error ENOENT will be the result. |
508 | |
509 | |
510 | (*) Search a keyring tree for a key: |
511 | |
512 | key_serial_t keyctl(KEYCTL_SEARCH, key_serial_t keyring, |
513 | const char *type, const char *description, |
514 | key_serial_t dest_keyring); |
515 | |
516 | This searches the keyring tree headed by the specified keyring until a |
517 | key is found that matches the type and description criteria. Each keyring |
518 | is checked for keys before recursion into its children occurs. |
519 | |
520 | The process must have search permission on the top level keyring, or else |
521 | error EACCES will result. Only keyrings that the process has search |
522 | permission on will be recursed into, and only keys and keyrings for which |
523 | a process has search permission can be matched. If the specified keyring |
524 | is not a keyring, ENOTDIR will result. |
525 | |
526 | If the search succeeds, the function will attempt to link the found key |
527 | into the destination keyring if one is supplied (non-zero ID). All the |
528 | constraints applicable to KEYCTL_LINK apply in this case too. |
529 | |
530 | Error ENOKEY, EKEYREVOKED or EKEYEXPIRED will be returned if the search |
531 | fails. On success, the resulting key ID will be returned. |
532 | |
533 | |
534 | (*) Read the payload data from a key: |
535 | |
536 | key_serial_t keyctl(KEYCTL_READ, key_serial_t keyring, char *buffer, |
537 | size_t buflen); |
538 | |
539 | This function attempts to read the payload data from the specified key |
540 | into the buffer. The process must have read permission on the key to |
541 | succeed. |
542 | |
543 | The returned data will be processed for presentation by the key type. For |
544 | instance, a keyring will return an array of key_serial_t entries |
545 | representing the IDs of all the keys to which it is subscribed. The user |
546 | defined key type will return its data as is. If a key type does not |
547 | implement this function, error EOPNOTSUPP will result. |
548 | |
549 | As much of the data as can be fitted into the buffer will be copied to |
550 | userspace if the buffer pointer is not NULL. |
551 | |
552 | On a successful return, the function will always return the amount of |
553 | data available rather than the amount copied. |
554 | |
555 | |
556 | (*) Instantiate a partially constructed key. |
557 | |
558 | key_serial_t keyctl(KEYCTL_INSTANTIATE, key_serial_t key, |
559 | const void *payload, size_t plen, |
560 | key_serial_t keyring); |
561 | |
562 | If the kernel calls back to userspace to complete the instantiation of a |
563 | key, userspace should use this call to supply data for the key before the |
564 | invoked process returns, or else the key will be marked negative |
565 | automatically. |
566 | |
567 | The process must have write access on the key to be able to instantiate |
568 | it, and the key must be uninstantiated. |
569 | |
570 | If a keyring is specified (non-zero), the key will also be linked into |
571 | that keyring, however all the constraints applying in KEYCTL_LINK apply |
572 | in this case too. |
573 | |
574 | The payload and plen arguments describe the payload data as for add_key(). |
575 | |
576 | |
577 | (*) Negatively instantiate a partially constructed key. |
578 | |
579 | key_serial_t keyctl(KEYCTL_NEGATE, key_serial_t key, |
580 | unsigned timeout, key_serial_t keyring); |
581 | |
582 | If the kernel calls back to userspace to complete the instantiation of a |
583 | key, userspace should use this call mark the key as negative before the |
584 | invoked process returns if it is unable to fulfil the request. |
585 | |
586 | The process must have write access on the key to be able to instantiate |
587 | it, and the key must be uninstantiated. |
588 | |
589 | If a keyring is specified (non-zero), the key will also be linked into |
590 | that keyring, however all the constraints applying in KEYCTL_LINK apply |
591 | in this case too. |
592 | |
593 | |
594 | =============== |
595 | KERNEL SERVICES |
596 | =============== |
597 | |
598 | The kernel services for key managment are fairly simple to deal with. They can |
599 | be broken down into two areas: keys and key types. |
600 | |
601 | Dealing with keys is fairly straightforward. Firstly, the kernel service |
602 | registers its type, then it searches for a key of that type. It should retain |
603 | the key as long as it has need of it, and then it should release it. For a |
604 | filesystem or device file, a search would probably be performed during the |
605 | open call, and the key released upon close. How to deal with conflicting keys |
606 | due to two different users opening the same file is left to the filesystem |
607 | author to solve. |
608 | |
609 | When accessing a key's payload data, key->lock should be at least read locked, |
610 | or else the data may be changed by an update being performed from userspace |
611 | whilst the driver or filesystem is trying to access it. If no update method is |
612 | supplied, then the key's payload may be accessed without holding a lock as |
613 | there is no way to change it, provided it can be guaranteed that the key's |
614 | type definition won't go away. |
615 | |
616 | (*) To search for a key, call: |
617 | |
618 | struct key *request_key(const struct key_type *type, |
619 | const char *description, |
620 | const char *callout_string); |
621 | |
622 | This is used to request a key or keyring with a description that matches |
623 | the description specified according to the key type's match function. This |
624 | permits approximate matching to occur. If callout_string is not NULL, then |
625 | /sbin/request-key will be invoked in an attempt to obtain the key from |
626 | userspace. In that case, callout_string will be passed as an argument to |
627 | the program. |
628 | |
629 | Should the function fail error ENOKEY, EKEYEXPIRED or EKEYREVOKED will be |
630 | returned. |
631 | |
632 | |
633 | (*) When it is no longer required, the key should be released using: |
634 | |
635 | void key_put(struct key *key); |
636 | |
637 | This can be called from interrupt context. If CONFIG_KEYS is not set then |
638 | the argument will not be parsed. |
639 | |
640 | |
641 | (*) Extra references can be made to a key by calling the following function: |
642 | |
643 | struct key *key_get(struct key *key); |
644 | |
645 | These need to be disposed of by calling key_put() when they've been |
646 | finished with. The key pointer passed in will be returned. If the pointer |
647 | is NULL or CONFIG_KEYS is not set then the key will not be dereferenced and |
648 | no increment will take place. |
649 | |
650 | |
651 | (*) A key's serial number can be obtained by calling: |
652 | |
653 | key_serial_t key_serial(struct key *key); |
654 | |
655 | If key is NULL or if CONFIG_KEYS is not set then 0 will be returned (in the |
656 | latter case without parsing the argument). |
657 | |
658 | |
659 | (*) If a keyring was found in the search, this can be further searched by: |
660 | |
661 | struct key *keyring_search(struct key *keyring, |
662 | const struct key_type *type, |
663 | const char *description) |
664 | |
665 | This searches the keyring tree specified for a matching key. Error ENOKEY |
666 | is returned upon failure. If successful, the returned key will need to be |
667 | released. |
668 | |
669 | |
670 | (*) To check the validity of a key, this function can be called: |
671 | |
672 | int validate_key(struct key *key); |
673 | |
674 | This checks that the key in question hasn't expired or and hasn't been |
675 | revoked. Should the key be invalid, error EKEYEXPIRED or EKEYREVOKED will |
676 | be returned. If the key is NULL or if CONFIG_KEYS is not set then 0 will be |
677 | returned (in the latter case without parsing the argument). |
678 | |
679 | |
680 | (*) To register a key type, the following function should be called: |
681 | |
682 | int register_key_type(struct key_type *type); |
683 | |
684 | This will return error EEXIST if a type of the same name is already |
685 | present. |
686 | |
687 | |
688 | (*) To unregister a key type, call: |
689 | |
690 | void unregister_key_type(struct key_type *type); |
691 | |
692 | |
693 | =================== |
694 | DEFINING A KEY TYPE |
695 | =================== |
696 | |
697 | A kernel service may want to define its own key type. For instance, an AFS |
698 | filesystem might want to define a Kerberos 5 ticket key type. To do this, it |
699 | author fills in a struct key_type and registers it with the system. |
700 | |
701 | The structure has a number of fields, some of which are mandatory: |
702 | |
703 | (*) const char *name |
704 | |
705 | The name of the key type. This is used to translate a key type name |
706 | supplied by userspace into a pointer to the structure. |
707 | |
708 | |
709 | (*) size_t def_datalen |
710 | |
711 | This is optional - it supplies the default payload data length as |
712 | contributed to the quota. If the key type's payload is always or almost |
713 | always the same size, then this is a more efficient way to do things. |
714 | |
715 | The data length (and quota) on a particular key can always be changed |
716 | during instantiation or update by calling: |
717 | |
718 | int key_payload_reserve(struct key *key, size_t datalen); |
719 | |
720 | With the revised data length. Error EDQUOT will be returned if this is |
721 | not viable. |
722 | |
723 | |
724 | (*) int (*instantiate)(struct key *key, const void *data, size_t datalen); |
725 | |
726 | This method is called to attach a payload to a key during construction. |
727 | The payload attached need not bear any relation to the data passed to |
728 | this function. |
729 | |
730 | If the amount of data attached to the key differs from the size in |
731 | keytype->def_datalen, then key_payload_reserve() should be called. |
732 | |
733 | This method does not have to lock the key in order to attach a payload. |
734 | The fact that KEY_FLAG_INSTANTIATED is not set in key->flags prevents |
735 | anything else from gaining access to the key. |
736 | |
737 | This method may sleep if it wishes. |
738 | |
739 | |
740 | (*) int (*duplicate)(struct key *key, const struct key *source); |
741 | |
742 | If this type of key can be duplicated, then this method should be |
743 | provided. It is called to copy the payload attached to the source into |
744 | the new key. The data length on the new key will have been updated and |
745 | the quota adjusted already. |
746 | |
747 | This method will be called with the source key's semaphore read-locked to |
748 | prevent its payload from being changed. It is safe to sleep here. |
749 | |
750 | |
751 | (*) int (*update)(struct key *key, const void *data, size_t datalen); |
752 | |
753 | If this type of key can be updated, then this method should be |
754 | provided. It is called to update a key's payload from the blob of data |
755 | provided. |
756 | |
757 | key_payload_reserve() should be called if the data length might change |
758 | before any changes are actually made. Note that if this succeeds, the |
759 | type is committed to changing the key because it's already been altered, |
760 | so all memory allocation must be done first. |
761 | |
762 | key_payload_reserve() should be called with the key->lock write locked, |
763 | and the changes to the key's attached payload should be made before the |
764 | key is locked. |
765 | |
766 | The key will have its semaphore write-locked before this method is |
767 | called. Any changes to the key should be made with the key's rwlock |
768 | write-locked also. It is safe to sleep here. |
769 | |
770 | |
771 | (*) int (*match)(const struct key *key, const void *desc); |
772 | |
773 | This method is called to match a key against a description. It should |
774 | return non-zero if the two match, zero if they don't. |
775 | |
776 | This method should not need to lock the key in any way. The type and |
777 | description can be considered invariant, and the payload should not be |
778 | accessed (the key may not yet be instantiated). |
779 | |
780 | It is not safe to sleep in this method; the caller may hold spinlocks. |
781 | |
782 | |
783 | (*) void (*destroy)(struct key *key); |
784 | |
785 | This method is optional. It is called to discard the payload data on a |
786 | key when it is being destroyed. |
787 | |
788 | This method does not need to lock the key; it can consider the key as |
789 | being inaccessible. Note that the key's type may have changed before this |
790 | function is called. |
791 | |
792 | It is not safe to sleep in this method; the caller may hold spinlocks. |
793 | |
794 | |
795 | (*) void (*describe)(const struct key *key, struct seq_file *p); |
796 | |
797 | This method is optional. It is called during /proc/keys reading to |
798 | summarise a key's description and payload in text form. |
799 | |
800 | This method will be called with the key's rwlock read-locked. This will |
801 | prevent the key's payload and state changing; also the description should |
802 | not change. This also means it is not safe to sleep in this method. |
803 | |
804 | |
805 | (*) long (*read)(const struct key *key, char __user *buffer, size_t buflen); |
806 | |
807 | This method is optional. It is called by KEYCTL_READ to translate the |
808 | key's payload into something a blob of data for userspace to deal |
809 | with. Ideally, the blob should be in the same format as that passed in to |
810 | the instantiate and update methods. |
811 | |
812 | If successful, the blob size that could be produced should be returned |
813 | rather than the size copied. |
814 | |
815 | This method will be called with the key's semaphore read-locked. This |
816 | will prevent the key's payload changing. It is not necessary to also |
817 | read-lock key->lock when accessing the key's payload. It is safe to sleep |
818 | in this method, such as might happen when the userspace buffer is |
819 | accessed. |
820 | |
821 | |
822 | ============================ |
823 | REQUEST-KEY CALLBACK SERVICE |
824 | ============================ |
825 | |
826 | To create a new key, the kernel will attempt to execute the following command |
827 | line: |
828 | |
829 | /sbin/request-key create <key> <uid> <gid> \ |
830 | <threadring> <processring> <sessionring> <callout_info> |
831 | |
832 | <key> is the key being constructed, and the three keyrings are the process |
833 | keyrings from the process that caused the search to be issued. These are |
834 | included for two reasons: |
835 | |
836 | (1) There may be an authentication token in one of the keyrings that is |
837 | required to obtain the key, eg: a Kerberos Ticket-Granting Ticket. |
838 | |
839 | (2) The new key should probably be cached in one of these rings. |
840 | |
841 | This program should set it UID and GID to those specified before attempting to |
842 | access any more keys. It may then look around for a user specific process to |
843 | hand the request off to (perhaps a path held in placed in another key by, for |
844 | example, the KDE desktop manager). |
845 | |
846 | The program (or whatever it calls) should finish construction of the key by |
847 | calling KEYCTL_INSTANTIATE, which also permits it to cache the key in one of |
848 | the keyrings (probably the session ring) before returning. Alternatively, the |
849 | key can be marked as negative with KEYCTL_NEGATE; this also permits the key to |
850 | be cached in one of the keyrings. |
851 | |
852 | If it returns with the key remaining in the unconstructed state, the key will |
853 | be marked as being negative, it will be added to the session keyring, and an |
854 | error will be returned to the key requestor. |
855 | |
856 | Supplementary information may be provided from whoever or whatever invoked |
857 | this service. This will be passed as the <callout_info> parameter. If no such |
858 | information was made available, then "-" will be passed as this parameter |
859 | instead. |
860 | |
861 | |
862 | Similarly, the kernel may attempt to update an expired or a soon to expire key |
863 | by executing: |
864 | |
865 | /sbin/request-key update <key> <uid> <gid> \ |
866 | <threadring> <processring> <sessionring> |
867 | |
868 | In this case, the program isn't required to actually attach the key to a ring; |
869 | the rings are provided for reference. |