diff options
Diffstat (limited to 'Documentation/security/keys.txt')
-rw-r--r-- | Documentation/security/keys.txt | 1290 |
1 files changed, 1290 insertions, 0 deletions
diff --git a/Documentation/security/keys.txt b/Documentation/security/keys.txt new file mode 100644 index 000000000000..4d75931d2d79 --- /dev/null +++ b/Documentation/security/keys.txt | |||
@@ -0,0 +1,1290 @@ | |||
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/security/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 | long keyctl(KEYCTL_INSTANTIATE_IOV, key_serial_t key, | ||
641 | const struct iovec *payload_iov, unsigned ioc, | ||
642 | key_serial_t keyring); | ||
643 | |||
644 | If the kernel calls back to userspace to complete the instantiation of a | ||
645 | key, userspace should use this call to supply data for the key before the | ||
646 | invoked process returns, or else the key will be marked negative | ||
647 | automatically. | ||
648 | |||
649 | The process must have write access on the key to be able to instantiate | ||
650 | it, and the key must be uninstantiated. | ||
651 | |||
652 | If a keyring is specified (non-zero), the key will also be linked into | ||
653 | that keyring, however all the constraints applying in KEYCTL_LINK apply in | ||
654 | this case too. | ||
655 | |||
656 | The payload and plen arguments describe the payload data as for add_key(). | ||
657 | |||
658 | The payload_iov and ioc arguments describe the payload data in an iovec | ||
659 | array instead of a single buffer. | ||
660 | |||
661 | |||
662 | (*) Negatively instantiate a partially constructed key. | ||
663 | |||
664 | long keyctl(KEYCTL_NEGATE, key_serial_t key, | ||
665 | unsigned timeout, key_serial_t keyring); | ||
666 | long keyctl(KEYCTL_REJECT, key_serial_t key, | ||
667 | unsigned timeout, unsigned error, key_serial_t keyring); | ||
668 | |||
669 | If the kernel calls back to userspace to complete the instantiation of a | ||
670 | key, userspace should use this call mark the key as negative before the | ||
671 | invoked process returns if it is unable to fulfil the request. | ||
672 | |||
673 | The process must have write access on the key to be able to instantiate | ||
674 | it, and the key must be uninstantiated. | ||
675 | |||
676 | If a keyring is specified (non-zero), the key will also be linked into | ||
677 | that keyring, however all the constraints applying in KEYCTL_LINK apply in | ||
678 | this case too. | ||
679 | |||
680 | If the key is rejected, future searches for it will return the specified | ||
681 | error code until the rejected key expires. Negating the key is the same | ||
682 | as rejecting the key with ENOKEY as the error code. | ||
683 | |||
684 | |||
685 | (*) Set the default request-key destination keyring. | ||
686 | |||
687 | long keyctl(KEYCTL_SET_REQKEY_KEYRING, int reqkey_defl); | ||
688 | |||
689 | This sets the default keyring to which implicitly requested keys will be | ||
690 | attached for this thread. reqkey_defl should be one of these constants: | ||
691 | |||
692 | CONSTANT VALUE NEW DEFAULT KEYRING | ||
693 | ====================================== ====== ======================= | ||
694 | KEY_REQKEY_DEFL_NO_CHANGE -1 No change | ||
695 | KEY_REQKEY_DEFL_DEFAULT 0 Default[1] | ||
696 | KEY_REQKEY_DEFL_THREAD_KEYRING 1 Thread keyring | ||
697 | KEY_REQKEY_DEFL_PROCESS_KEYRING 2 Process keyring | ||
698 | KEY_REQKEY_DEFL_SESSION_KEYRING 3 Session keyring | ||
699 | KEY_REQKEY_DEFL_USER_KEYRING 4 User keyring | ||
700 | KEY_REQKEY_DEFL_USER_SESSION_KEYRING 5 User session keyring | ||
701 | KEY_REQKEY_DEFL_GROUP_KEYRING 6 Group keyring | ||
702 | |||
703 | The old default will be returned if successful and error EINVAL will be | ||
704 | returned if reqkey_defl is not one of the above values. | ||
705 | |||
706 | The default keyring can be overridden by the keyring indicated to the | ||
707 | request_key() system call. | ||
708 | |||
709 | Note that this setting is inherited across fork/exec. | ||
710 | |||
711 | [1] The default is: the thread keyring if there is one, otherwise | ||
712 | the process keyring if there is one, otherwise the session keyring if | ||
713 | there is one, otherwise the user default session keyring. | ||
714 | |||
715 | |||
716 | (*) Set the timeout on a key. | ||
717 | |||
718 | long keyctl(KEYCTL_SET_TIMEOUT, key_serial_t key, unsigned timeout); | ||
719 | |||
720 | This sets or clears the timeout on a key. The timeout can be 0 to clear | ||
721 | the timeout or a number of seconds to set the expiry time that far into | ||
722 | the future. | ||
723 | |||
724 | The process must have attribute modification access on a key to set its | ||
725 | timeout. Timeouts may not be set with this function on negative, revoked | ||
726 | or expired keys. | ||
727 | |||
728 | |||
729 | (*) Assume the authority granted to instantiate a key | ||
730 | |||
731 | long keyctl(KEYCTL_ASSUME_AUTHORITY, key_serial_t key); | ||
732 | |||
733 | This assumes or divests the authority required to instantiate the | ||
734 | specified key. Authority can only be assumed if the thread has the | ||
735 | authorisation key associated with the specified key in its keyrings | ||
736 | somewhere. | ||
737 | |||
738 | Once authority is assumed, searches for keys will also search the | ||
739 | requester's keyrings using the requester's security label, UID, GID and | ||
740 | groups. | ||
741 | |||
742 | If the requested authority is unavailable, error EPERM will be returned, | ||
743 | likewise if the authority has been revoked because the target key is | ||
744 | already instantiated. | ||
745 | |||
746 | If the specified key is 0, then any assumed authority will be divested. | ||
747 | |||
748 | The assumed authoritative key is inherited across fork and exec. | ||
749 | |||
750 | |||
751 | (*) Get the LSM security context attached to a key. | ||
752 | |||
753 | long keyctl(KEYCTL_GET_SECURITY, key_serial_t key, char *buffer, | ||
754 | size_t buflen) | ||
755 | |||
756 | This function returns a string that represents the LSM security context | ||
757 | attached to a key in the buffer provided. | ||
758 | |||
759 | Unless there's an error, it always returns the amount of data it could | ||
760 | produce, even if that's too big for the buffer, but it won't copy more | ||
761 | than requested to userspace. If the buffer pointer is NULL then no copy | ||
762 | will take place. | ||
763 | |||
764 | A NUL character is included at the end of the string if the buffer is | ||
765 | sufficiently big. This is included in the returned count. If no LSM is | ||
766 | in force then an empty string will be returned. | ||
767 | |||
768 | A process must have view permission on the key for this function to be | ||
769 | successful. | ||
770 | |||
771 | |||
772 | (*) Install the calling process's session keyring on its parent. | ||
773 | |||
774 | long keyctl(KEYCTL_SESSION_TO_PARENT); | ||
775 | |||
776 | This functions attempts to install the calling process's session keyring | ||
777 | on to the calling process's parent, replacing the parent's current session | ||
778 | keyring. | ||
779 | |||
780 | The calling process must have the same ownership as its parent, the | ||
781 | keyring must have the same ownership as the calling process, the calling | ||
782 | process must have LINK permission on the keyring and the active LSM module | ||
783 | mustn't deny permission, otherwise error EPERM will be returned. | ||
784 | |||
785 | Error ENOMEM will be returned if there was insufficient memory to complete | ||
786 | the operation, otherwise 0 will be returned to indicate success. | ||
787 | |||
788 | The keyring will be replaced next time the parent process leaves the | ||
789 | kernel and resumes executing userspace. | ||
790 | |||
791 | |||
792 | =============== | ||
793 | KERNEL SERVICES | ||
794 | =============== | ||
795 | |||
796 | The kernel services for key management are fairly simple to deal with. They can | ||
797 | be broken down into two areas: keys and key types. | ||
798 | |||
799 | Dealing with keys is fairly straightforward. Firstly, the kernel service | ||
800 | registers its type, then it searches for a key of that type. It should retain | ||
801 | the key as long as it has need of it, and then it should release it. For a | ||
802 | filesystem or device file, a search would probably be performed during the open | ||
803 | call, and the key released upon close. How to deal with conflicting keys due to | ||
804 | two different users opening the same file is left to the filesystem author to | ||
805 | solve. | ||
806 | |||
807 | To access the key manager, the following header must be #included: | ||
808 | |||
809 | <linux/key.h> | ||
810 | |||
811 | Specific key types should have a header file under include/keys/ that should be | ||
812 | used to access that type. For keys of type "user", for example, that would be: | ||
813 | |||
814 | <keys/user-type.h> | ||
815 | |||
816 | Note that there are two different types of pointers to keys that may be | ||
817 | encountered: | ||
818 | |||
819 | (*) struct key * | ||
820 | |||
821 | This simply points to the key structure itself. Key structures will be at | ||
822 | least four-byte aligned. | ||
823 | |||
824 | (*) key_ref_t | ||
825 | |||
826 | This is equivalent to a struct key *, but the least significant bit is set | ||
827 | if the caller "possesses" the key. By "possession" it is meant that the | ||
828 | calling processes has a searchable link to the key from one of its | ||
829 | keyrings. There are three functions for dealing with these: | ||
830 | |||
831 | key_ref_t make_key_ref(const struct key *key, | ||
832 | unsigned long possession); | ||
833 | |||
834 | struct key *key_ref_to_ptr(const key_ref_t key_ref); | ||
835 | |||
836 | unsigned long is_key_possessed(const key_ref_t key_ref); | ||
837 | |||
838 | The first function constructs a key reference from a key pointer and | ||
839 | possession information (which must be 0 or 1 and not any other value). | ||
840 | |||
841 | The second function retrieves the key pointer from a reference and the | ||
842 | third retrieves the possession flag. | ||
843 | |||
844 | When accessing a key's payload contents, certain precautions must be taken to | ||
845 | prevent access vs modification races. See the section "Notes on accessing | ||
846 | payload contents" for more information. | ||
847 | |||
848 | (*) To search for a key, call: | ||
849 | |||
850 | struct key *request_key(const struct key_type *type, | ||
851 | const char *description, | ||
852 | const char *callout_info); | ||
853 | |||
854 | This is used to request a key or keyring with a description that matches | ||
855 | the description specified according to the key type's match function. This | ||
856 | permits approximate matching to occur. If callout_string is not NULL, then | ||
857 | /sbin/request-key will be invoked in an attempt to obtain the key from | ||
858 | userspace. In that case, callout_string will be passed as an argument to | ||
859 | the program. | ||
860 | |||
861 | Should the function fail error ENOKEY, EKEYEXPIRED or EKEYREVOKED will be | ||
862 | returned. | ||
863 | |||
864 | If successful, the key will have been attached to the default keyring for | ||
865 | implicitly obtained request-key keys, as set by KEYCTL_SET_REQKEY_KEYRING. | ||
866 | |||
867 | See also Documentation/security/keys-request-key.txt. | ||
868 | |||
869 | |||
870 | (*) To search for a key, passing auxiliary data to the upcaller, call: | ||
871 | |||
872 | struct key *request_key_with_auxdata(const struct key_type *type, | ||
873 | const char *description, | ||
874 | const void *callout_info, | ||
875 | size_t callout_len, | ||
876 | void *aux); | ||
877 | |||
878 | This is identical to request_key(), except that the auxiliary data is | ||
879 | passed to the key_type->request_key() op if it exists, and the callout_info | ||
880 | is a blob of length callout_len, if given (the length may be 0). | ||
881 | |||
882 | |||
883 | (*) A key can be requested asynchronously by calling one of: | ||
884 | |||
885 | struct key *request_key_async(const struct key_type *type, | ||
886 | const char *description, | ||
887 | const void *callout_info, | ||
888 | size_t callout_len); | ||
889 | |||
890 | or: | ||
891 | |||
892 | struct key *request_key_async_with_auxdata(const struct key_type *type, | ||
893 | const char *description, | ||
894 | const char *callout_info, | ||
895 | size_t callout_len, | ||
896 | void *aux); | ||
897 | |||
898 | which are asynchronous equivalents of request_key() and | ||
899 | request_key_with_auxdata() respectively. | ||
900 | |||
901 | These two functions return with the key potentially still under | ||
902 | construction. To wait for construction completion, the following should be | ||
903 | called: | ||
904 | |||
905 | int wait_for_key_construction(struct key *key, bool intr); | ||
906 | |||
907 | The function will wait for the key to finish being constructed and then | ||
908 | invokes key_validate() to return an appropriate value to indicate the state | ||
909 | of the key (0 indicates the key is usable). | ||
910 | |||
911 | If intr is true, then the wait can be interrupted by a signal, in which | ||
912 | case error ERESTARTSYS will be returned. | ||
913 | |||
914 | |||
915 | (*) When it is no longer required, the key should be released using: | ||
916 | |||
917 | void key_put(struct key *key); | ||
918 | |||
919 | Or: | ||
920 | |||
921 | void key_ref_put(key_ref_t key_ref); | ||
922 | |||
923 | These can be called from interrupt context. If CONFIG_KEYS is not set then | ||
924 | the argument will not be parsed. | ||
925 | |||
926 | |||
927 | (*) Extra references can be made to a key by calling the following function: | ||
928 | |||
929 | struct key *key_get(struct key *key); | ||
930 | |||
931 | These need to be disposed of by calling key_put() when they've been | ||
932 | finished with. The key pointer passed in will be returned. If the pointer | ||
933 | is NULL or CONFIG_KEYS is not set then the key will not be dereferenced and | ||
934 | no increment will take place. | ||
935 | |||
936 | |||
937 | (*) A key's serial number can be obtained by calling: | ||
938 | |||
939 | key_serial_t key_serial(struct key *key); | ||
940 | |||
941 | If key is NULL or if CONFIG_KEYS is not set then 0 will be returned (in the | ||
942 | latter case without parsing the argument). | ||
943 | |||
944 | |||
945 | (*) If a keyring was found in the search, this can be further searched by: | ||
946 | |||
947 | key_ref_t keyring_search(key_ref_t keyring_ref, | ||
948 | const struct key_type *type, | ||
949 | const char *description) | ||
950 | |||
951 | This searches the keyring tree specified for a matching key. Error ENOKEY | ||
952 | is returned upon failure (use IS_ERR/PTR_ERR to determine). If successful, | ||
953 | the returned key will need to be released. | ||
954 | |||
955 | The possession attribute from the keyring reference is used to control | ||
956 | access through the permissions mask and is propagated to the returned key | ||
957 | reference pointer if successful. | ||
958 | |||
959 | |||
960 | (*) To check the validity of a key, this function can be called: | ||
961 | |||
962 | int validate_key(struct key *key); | ||
963 | |||
964 | This checks that the key in question hasn't expired or and hasn't been | ||
965 | revoked. Should the key be invalid, error EKEYEXPIRED or EKEYREVOKED will | ||
966 | be returned. If the key is NULL or if CONFIG_KEYS is not set then 0 will be | ||
967 | returned (in the latter case without parsing the argument). | ||
968 | |||
969 | |||
970 | (*) To register a key type, the following function should be called: | ||
971 | |||
972 | int register_key_type(struct key_type *type); | ||
973 | |||
974 | This will return error EEXIST if a type of the same name is already | ||
975 | present. | ||
976 | |||
977 | |||
978 | (*) To unregister a key type, call: | ||
979 | |||
980 | void unregister_key_type(struct key_type *type); | ||
981 | |||
982 | |||
983 | Under some circumstances, it may be desirable to deal with a bundle of keys. | ||
984 | The facility provides access to the keyring type for managing such a bundle: | ||
985 | |||
986 | struct key_type key_type_keyring; | ||
987 | |||
988 | This can be used with a function such as request_key() to find a specific | ||
989 | keyring in a process's keyrings. A keyring thus found can then be searched | ||
990 | with keyring_search(). Note that it is not possible to use request_key() to | ||
991 | search a specific keyring, so using keyrings in this way is of limited utility. | ||
992 | |||
993 | |||
994 | =================================== | ||
995 | NOTES ON ACCESSING PAYLOAD CONTENTS | ||
996 | =================================== | ||
997 | |||
998 | The simplest payload is just a number in key->payload.value. In this case, | ||
999 | there's no need to indulge in RCU or locking when accessing the payload. | ||
1000 | |||
1001 | More complex payload contents must be allocated and a pointer to them set in | ||
1002 | key->payload.data. One of the following ways must be selected to access the | ||
1003 | data: | ||
1004 | |||
1005 | (1) Unmodifiable key type. | ||
1006 | |||
1007 | If the key type does not have a modify method, then the key's payload can | ||
1008 | be accessed without any form of locking, provided that it's known to be | ||
1009 | instantiated (uninstantiated keys cannot be "found"). | ||
1010 | |||
1011 | (2) The key's semaphore. | ||
1012 | |||
1013 | The semaphore could be used to govern access to the payload and to control | ||
1014 | the payload pointer. It must be write-locked for modifications and would | ||
1015 | have to be read-locked for general access. The disadvantage of doing this | ||
1016 | is that the accessor may be required to sleep. | ||
1017 | |||
1018 | (3) RCU. | ||
1019 | |||
1020 | RCU must be used when the semaphore isn't already held; if the semaphore | ||
1021 | is held then the contents can't change under you unexpectedly as the | ||
1022 | semaphore must still be used to serialise modifications to the key. The | ||
1023 | key management code takes care of this for the key type. | ||
1024 | |||
1025 | However, this means using: | ||
1026 | |||
1027 | rcu_read_lock() ... rcu_dereference() ... rcu_read_unlock() | ||
1028 | |||
1029 | to read the pointer, and: | ||
1030 | |||
1031 | rcu_dereference() ... rcu_assign_pointer() ... call_rcu() | ||
1032 | |||
1033 | to set the pointer and dispose of the old contents after a grace period. | ||
1034 | Note that only the key type should ever modify a key's payload. | ||
1035 | |||
1036 | Furthermore, an RCU controlled payload must hold a struct rcu_head for the | ||
1037 | use of call_rcu() and, if the payload is of variable size, the length of | ||
1038 | the payload. key->datalen cannot be relied upon to be consistent with the | ||
1039 | payload just dereferenced if the key's semaphore is not held. | ||
1040 | |||
1041 | |||
1042 | =================== | ||
1043 | DEFINING A KEY TYPE | ||
1044 | =================== | ||
1045 | |||
1046 | A kernel service may want to define its own key type. For instance, an AFS | ||
1047 | filesystem might want to define a Kerberos 5 ticket key type. To do this, it | ||
1048 | author fills in a key_type struct and registers it with the system. | ||
1049 | |||
1050 | Source files that implement key types should include the following header file: | ||
1051 | |||
1052 | <linux/key-type.h> | ||
1053 | |||
1054 | The structure has a number of fields, some of which are mandatory: | ||
1055 | |||
1056 | (*) const char *name | ||
1057 | |||
1058 | The name of the key type. This is used to translate a key type name | ||
1059 | supplied by userspace into a pointer to the structure. | ||
1060 | |||
1061 | |||
1062 | (*) size_t def_datalen | ||
1063 | |||
1064 | This is optional - it supplies the default payload data length as | ||
1065 | contributed to the quota. If the key type's payload is always or almost | ||
1066 | always the same size, then this is a more efficient way to do things. | ||
1067 | |||
1068 | The data length (and quota) on a particular key can always be changed | ||
1069 | during instantiation or update by calling: | ||
1070 | |||
1071 | int key_payload_reserve(struct key *key, size_t datalen); | ||
1072 | |||
1073 | With the revised data length. Error EDQUOT will be returned if this is not | ||
1074 | viable. | ||
1075 | |||
1076 | |||
1077 | (*) int (*vet_description)(const char *description); | ||
1078 | |||
1079 | This optional method is called to vet a key description. If the key type | ||
1080 | doesn't approve of the key description, it may return an error, otherwise | ||
1081 | it should return 0. | ||
1082 | |||
1083 | |||
1084 | (*) int (*instantiate)(struct key *key, const void *data, size_t datalen); | ||
1085 | |||
1086 | This method is called to attach a payload to a key during construction. | ||
1087 | The payload attached need not bear any relation to the data passed to this | ||
1088 | function. | ||
1089 | |||
1090 | If the amount of data attached to the key differs from the size in | ||
1091 | keytype->def_datalen, then key_payload_reserve() should be called. | ||
1092 | |||
1093 | This method does not have to lock the key in order to attach a payload. | ||
1094 | The fact that KEY_FLAG_INSTANTIATED is not set in key->flags prevents | ||
1095 | anything else from gaining access to the key. | ||
1096 | |||
1097 | It is safe to sleep in this method. | ||
1098 | |||
1099 | |||
1100 | (*) int (*update)(struct key *key, const void *data, size_t datalen); | ||
1101 | |||
1102 | If this type of key can be updated, then this method should be provided. | ||
1103 | It is called to update a key's payload from the blob of data provided. | ||
1104 | |||
1105 | key_payload_reserve() should be called if the data length might change | ||
1106 | before any changes are actually made. Note that if this succeeds, the type | ||
1107 | is committed to changing the key because it's already been altered, so all | ||
1108 | memory allocation must be done first. | ||
1109 | |||
1110 | The key will have its semaphore write-locked before this method is called, | ||
1111 | but this only deters other writers; any changes to the key's payload must | ||
1112 | be made under RCU conditions, and call_rcu() must be used to dispose of | ||
1113 | the old payload. | ||
1114 | |||
1115 | key_payload_reserve() should be called before the changes are made, but | ||
1116 | after all allocations and other potentially failing function calls are | ||
1117 | made. | ||
1118 | |||
1119 | It is safe to sleep in this method. | ||
1120 | |||
1121 | |||
1122 | (*) int (*match)(const struct key *key, const void *desc); | ||
1123 | |||
1124 | This method is called to match a key against a description. It should | ||
1125 | return non-zero if the two match, zero if they don't. | ||
1126 | |||
1127 | This method should not need to lock the key in any way. The type and | ||
1128 | description can be considered invariant, and the payload should not be | ||
1129 | accessed (the key may not yet be instantiated). | ||
1130 | |||
1131 | It is not safe to sleep in this method; the caller may hold spinlocks. | ||
1132 | |||
1133 | |||
1134 | (*) void (*revoke)(struct key *key); | ||
1135 | |||
1136 | This method is optional. It is called to discard part of the payload | ||
1137 | data upon a key being revoked. The caller will have the key semaphore | ||
1138 | write-locked. | ||
1139 | |||
1140 | It is safe to sleep in this method, though care should be taken to avoid | ||
1141 | a deadlock against the key semaphore. | ||
1142 | |||
1143 | |||
1144 | (*) void (*destroy)(struct key *key); | ||
1145 | |||
1146 | This method is optional. It is called to discard the payload data on a key | ||
1147 | when it is being destroyed. | ||
1148 | |||
1149 | This method does not need to lock the key to access the payload; it can | ||
1150 | consider the key as being inaccessible at this time. Note that the key's | ||
1151 | type may have been changed before this function is called. | ||
1152 | |||
1153 | It is not safe to sleep in this method; the caller may hold spinlocks. | ||
1154 | |||
1155 | |||
1156 | (*) void (*describe)(const struct key *key, struct seq_file *p); | ||
1157 | |||
1158 | This method is optional. It is called during /proc/keys reading to | ||
1159 | summarise a key's description and payload in text form. | ||
1160 | |||
1161 | This method will be called with the RCU read lock held. rcu_dereference() | ||
1162 | should be used to read the payload pointer if the payload is to be | ||
1163 | accessed. key->datalen cannot be trusted to stay consistent with the | ||
1164 | contents of the payload. | ||
1165 | |||
1166 | The description will not change, though the key's state may. | ||
1167 | |||
1168 | It is not safe to sleep in this method; the RCU read lock is held by the | ||
1169 | caller. | ||
1170 | |||
1171 | |||
1172 | (*) long (*read)(const struct key *key, char __user *buffer, size_t buflen); | ||
1173 | |||
1174 | This method is optional. It is called by KEYCTL_READ to translate the | ||
1175 | key's payload into something a blob of data for userspace to deal with. | ||
1176 | Ideally, the blob should be in the same format as that passed in to the | ||
1177 | instantiate and update methods. | ||
1178 | |||
1179 | If successful, the blob size that could be produced should be returned | ||
1180 | rather than the size copied. | ||
1181 | |||
1182 | This method will be called with the key's semaphore read-locked. This will | ||
1183 | prevent the key's payload changing. It is not necessary to use RCU locking | ||
1184 | when accessing the key's payload. It is safe to sleep in this method, such | ||
1185 | as might happen when the userspace buffer is accessed. | ||
1186 | |||
1187 | |||
1188 | (*) int (*request_key)(struct key_construction *cons, const char *op, | ||
1189 | void *aux); | ||
1190 | |||
1191 | This method is optional. If provided, request_key() and friends will | ||
1192 | invoke this function rather than upcalling to /sbin/request-key to operate | ||
1193 | upon a key of this type. | ||
1194 | |||
1195 | The aux parameter is as passed to request_key_async_with_auxdata() and | ||
1196 | similar or is NULL otherwise. Also passed are the construction record for | ||
1197 | the key to be operated upon and the operation type (currently only | ||
1198 | "create"). | ||
1199 | |||
1200 | This method is permitted to return before the upcall is complete, but the | ||
1201 | following function must be called under all circumstances to complete the | ||
1202 | instantiation process, whether or not it succeeds, whether or not there's | ||
1203 | an error: | ||
1204 | |||
1205 | void complete_request_key(struct key_construction *cons, int error); | ||
1206 | |||
1207 | The error parameter should be 0 on success, -ve on error. The | ||
1208 | construction record is destroyed by this action and the authorisation key | ||
1209 | will be revoked. If an error is indicated, the key under construction | ||
1210 | will be negatively instantiated if it wasn't already instantiated. | ||
1211 | |||
1212 | If this method returns an error, that error will be returned to the | ||
1213 | caller of request_key*(). complete_request_key() must be called prior to | ||
1214 | returning. | ||
1215 | |||
1216 | The key under construction and the authorisation key can be found in the | ||
1217 | key_construction struct pointed to by cons: | ||
1218 | |||
1219 | (*) struct key *key; | ||
1220 | |||
1221 | The key under construction. | ||
1222 | |||
1223 | (*) struct key *authkey; | ||
1224 | |||
1225 | The authorisation key. | ||
1226 | |||
1227 | |||
1228 | ============================ | ||
1229 | REQUEST-KEY CALLBACK SERVICE | ||
1230 | ============================ | ||
1231 | |||
1232 | To create a new key, the kernel will attempt to execute the following command | ||
1233 | line: | ||
1234 | |||
1235 | /sbin/request-key create <key> <uid> <gid> \ | ||
1236 | <threadring> <processring> <sessionring> <callout_info> | ||
1237 | |||
1238 | <key> is the key being constructed, and the three keyrings are the process | ||
1239 | keyrings from the process that caused the search to be issued. These are | ||
1240 | included for two reasons: | ||
1241 | |||
1242 | (1) There may be an authentication token in one of the keyrings that is | ||
1243 | required to obtain the key, eg: a Kerberos Ticket-Granting Ticket. | ||
1244 | |||
1245 | (2) The new key should probably be cached in one of these rings. | ||
1246 | |||
1247 | This program should set it UID and GID to those specified before attempting to | ||
1248 | access any more keys. It may then look around for a user specific process to | ||
1249 | hand the request off to (perhaps a path held in placed in another key by, for | ||
1250 | example, the KDE desktop manager). | ||
1251 | |||
1252 | The program (or whatever it calls) should finish construction of the key by | ||
1253 | calling KEYCTL_INSTANTIATE or KEYCTL_INSTANTIATE_IOV, which also permits it to | ||
1254 | cache the key in one of the keyrings (probably the session ring) before | ||
1255 | returning. Alternatively, the key can be marked as negative with KEYCTL_NEGATE | ||
1256 | or KEYCTL_REJECT; this also permits the key to be cached in one of the | ||
1257 | keyrings. | ||
1258 | |||
1259 | If it returns with the key remaining in the unconstructed state, the key will | ||
1260 | be marked as being negative, it will be added to the session keyring, and an | ||
1261 | error will be returned to the key requestor. | ||
1262 | |||
1263 | Supplementary information may be provided from whoever or whatever invoked this | ||
1264 | service. This will be passed as the <callout_info> parameter. If no such | ||
1265 | information was made available, then "-" will be passed as this parameter | ||
1266 | instead. | ||
1267 | |||
1268 | |||
1269 | Similarly, the kernel may attempt to update an expired or a soon to expire key | ||
1270 | by executing: | ||
1271 | |||
1272 | /sbin/request-key update <key> <uid> <gid> \ | ||
1273 | <threadring> <processring> <sessionring> | ||
1274 | |||
1275 | In this case, the program isn't required to actually attach the key to a ring; | ||
1276 | the rings are provided for reference. | ||
1277 | |||
1278 | |||
1279 | ================== | ||
1280 | GARBAGE COLLECTION | ||
1281 | ================== | ||
1282 | |||
1283 | Dead keys (for which the type has been removed) will be automatically unlinked | ||
1284 | from those keyrings that point to them and deleted as soon as possible by a | ||
1285 | background garbage collector. | ||
1286 | |||
1287 | Similarly, revoked and expired keys will be garbage collected, but only after a | ||
1288 | certain amount of time has passed. This time is set as a number of seconds in: | ||
1289 | |||
1290 | /proc/sys/kernel/keys/gc_delay | ||