]>
Commit | Line | Data |
---|---|---|
1da177e4 LT |
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 | |
d720024e | 22 | - SELinux support |
1da177e4 LT |
23 | - New procfs files |
24 | - Userspace system call interface | |
25 | - Kernel services | |
76d8aeab | 26 | - Notes on accessing payload contents |
1da177e4 LT |
27 | - Defining a key type |
28 | - Request-key callback service | |
29 | - Key access filesystem | |
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 | ||
76d8aeab DH |
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. | |
1da177e4 LT |
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 | |
76d8aeab DH |
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. | |
1da177e4 | 60 | |
76d8aeab DH |
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. | |
1da177e4 LT |
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 | |
76d8aeab DH |
68 | type provides an operation to perform a match between the description on a |
69 | key and a criterion string. | |
1da177e4 LT |
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 | ||
76d8aeab DH |
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. | |
1da177e4 LT |
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 | ||
76d8aeab DH |
96 | (*) Uninstantiated. The key exists, but does not have any data attached. |
97 | Keys being requested from userspace will be in this state. | |
1da177e4 LT |
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 | ||
117 | ==================== | |
118 | KEY SERVICE OVERVIEW | |
119 | ==================== | |
120 | ||
121 | The key service provides a number of features besides keys: | |
122 | ||
123 | (*) The key service defines two special key types: | |
124 | ||
125 | (+) "keyring" | |
126 | ||
127 | Keyrings are special keys that contain a list of other keys. Keyring | |
128 | lists can be modified using various system calls. Keyrings should not | |
129 | be given a payload when created. | |
130 | ||
131 | (+) "user" | |
132 | ||
133 | A key of this type has a description and a payload that are arbitrary | |
134 | blobs of data. These can be created, updated and read by userspace, | |
135 | and aren't intended for use by kernel services. | |
136 | ||
137 | (*) Each process subscribes to three keyrings: a thread-specific keyring, a | |
138 | process-specific keyring, and a session-specific keyring. | |
139 | ||
140 | The thread-specific keyring is discarded from the child when any sort of | |
141 | clone, fork, vfork or execve occurs. A new keyring is created only when | |
142 | required. | |
143 | ||
76d8aeab DH |
144 | The process-specific keyring is replaced with an empty one in the child on |
145 | clone, fork, vfork unless CLONE_THREAD is supplied, in which case it is | |
146 | shared. execve also discards the process's process keyring and creates a | |
147 | new one. | |
1da177e4 LT |
148 | |
149 | The session-specific keyring is persistent across clone, fork, vfork and | |
150 | execve, even when the latter executes a set-UID or set-GID binary. A | |
151 | process can, however, replace its current session keyring with a new one | |
152 | by using PR_JOIN_SESSION_KEYRING. It is permitted to request an anonymous | |
153 | new one, or to attempt to create or join one of a specific name. | |
154 | ||
155 | The ownership of the thread keyring changes when the real UID and GID of | |
156 | the thread changes. | |
157 | ||
158 | (*) Each user ID resident in the system holds two special keyrings: a user | |
159 | specific keyring and a default user session keyring. The default session | |
160 | keyring is initialised with a link to the user-specific keyring. | |
161 | ||
162 | When a process changes its real UID, if it used to have no session key, it | |
163 | will be subscribed to the default session key for the new UID. | |
164 | ||
165 | If a process attempts to access its session key when it doesn't have one, | |
166 | it will be subscribed to the default for its current UID. | |
167 | ||
168 | (*) Each user has two quotas against which the keys they own are tracked. One | |
169 | limits the total number of keys and keyrings, the other limits the total | |
170 | amount of description and payload space that can be consumed. | |
171 | ||
172 | The user can view information on this and other statistics through procfs | |
173 | files. | |
174 | ||
175 | Process-specific and thread-specific keyrings are not counted towards a | |
176 | user's quota. | |
177 | ||
178 | If a system call that modifies a key or keyring in some way would put the | |
179 | user over quota, the operation is refused and error EDQUOT is returned. | |
180 | ||
76d8aeab DH |
181 | (*) There's a system call interface by which userspace programs can create and |
182 | manipulate keys and keyrings. | |
1da177e4 | 183 | |
76d8aeab DH |
184 | (*) There's a kernel interface by which services can register types and search |
185 | for keys. | |
1da177e4 LT |
186 | |
187 | (*) There's a way for the a search done from the kernel to call back to | |
188 | userspace to request a key that can't be found in a process's keyrings. | |
189 | ||
190 | (*) An optional filesystem is available through which the key database can be | |
191 | viewed and manipulated. | |
192 | ||
193 | ||
194 | ====================== | |
195 | KEY ACCESS PERMISSIONS | |
196 | ====================== | |
197 | ||
76d8aeab | 198 | Keys have an owner user ID, a group access ID, and a permissions mask. The mask |
664cceb0 | 199 | has up to eight bits each for possessor, user, group and other access. Only |
29db9190 | 200 | six of each set of eight bits are defined. These permissions granted are: |
1da177e4 LT |
201 | |
202 | (*) View | |
203 | ||
204 | This permits a key or keyring's attributes to be viewed - including key | |
205 | type and description. | |
206 | ||
207 | (*) Read | |
208 | ||
209 | This permits a key's payload to be viewed or a keyring's list of linked | |
210 | keys. | |
211 | ||
212 | (*) Write | |
213 | ||
76d8aeab DH |
214 | This permits a key's payload to be instantiated or updated, or it allows a |
215 | link to be added to or removed from a keyring. | |
1da177e4 LT |
216 | |
217 | (*) Search | |
218 | ||
219 | This permits keyrings to be searched and keys to be found. Searches can | |
220 | only recurse into nested keyrings that have search permission set. | |
221 | ||
222 | (*) Link | |
223 | ||
224 | This permits a key or keyring to be linked to. To create a link from a | |
225 | keyring to a key, a process must have Write permission on the keyring and | |
226 | Link permission on the key. | |
227 | ||
29db9190 DH |
228 | (*) Set Attribute |
229 | ||
230 | This permits a key's UID, GID and permissions mask to be changed. | |
231 | ||
1da177e4 LT |
232 | For changing the ownership, group ID or permissions mask, being the owner of |
233 | the key or having the sysadmin capability is sufficient. | |
234 | ||
235 | ||
d720024e ML |
236 | =============== |
237 | SELINUX SUPPORT | |
238 | =============== | |
239 | ||
240 | The security class "key" has been added to SELinux so that mandatory access | |
241 | controls can be applied to keys created within various contexts. This support | |
242 | is preliminary, and is likely to change quite significantly in the near future. | |
243 | Currently, all of the basic permissions explained above are provided in SELinux | |
244 | as well; SE Linux is simply invoked after all basic permission checks have been | |
245 | performed. | |
246 | ||
247 | Each key is labeled with the same context as the task to which it belongs. | |
248 | Typically, this is the same task that was running when the key was created. | |
249 | The default keyrings are handled differently, but in a way that is very | |
250 | intuitive: | |
251 | ||
252 | (*) The user and user session keyrings that are created when the user logs in | |
253 | are currently labeled with the context of the login manager. | |
254 | ||
255 | (*) The keyrings associated with new threads are each labeled with the context | |
256 | of their associated thread, and both session and process keyrings are | |
257 | handled similarly. | |
258 | ||
259 | Note, however, that the default keyrings associated with the root user are | |
260 | labeled with the default kernel context, since they are created early in the | |
261 | boot process, before root has a chance to log in. | |
262 | ||
263 | ||
1da177e4 LT |
264 | ================ |
265 | NEW PROCFS FILES | |
266 | ================ | |
267 | ||
268 | Two files have been added to procfs by which an administrator can find out | |
269 | about the status of the key service: | |
270 | ||
271 | (*) /proc/keys | |
272 | ||
06ec7be5 ML |
273 | This lists the keys that are currently viewable by the task reading the |
274 | file, giving information about their type, description and permissions. | |
275 | It is not possible to view the payload of the key this way, though some | |
276 | information about it may be given. | |
277 | ||
278 | The only keys included in the list are those that grant View permission to | |
279 | the reading process whether or not it possesses them. Note that LSM | |
280 | security checks are still performed, and may further filter out keys that | |
281 | the current process is not authorised to view. | |
282 | ||
283 | The contents of the file look like this: | |
1da177e4 | 284 | |
664cceb0 | 285 | SERIAL FLAGS USAGE EXPY PERM UID GID TYPE DESCRIPTION: SUMMARY |
29db9190 DH |
286 | 00000001 I----- 39 perm 1f3f0000 0 0 keyring _uid_ses.0: 1/4 |
287 | 00000002 I----- 2 perm 1f3f0000 0 0 keyring _uid.0: empty | |
288 | 00000007 I----- 1 perm 1f3f0000 0 0 keyring _pid.1: empty | |
289 | 0000018d I----- 1 perm 1f3f0000 0 0 keyring _pid.412: empty | |
290 | 000004d2 I--Q-- 1 perm 1f3f0000 32 -1 keyring _uid.32: 1/4 | |
291 | 000004d3 I--Q-- 3 perm 1f3f0000 32 -1 keyring _uid_ses.32: empty | |
664cceb0 | 292 | 00000892 I--QU- 1 perm 1f000000 0 0 user metal:copper: 0 |
29db9190 DH |
293 | 00000893 I--Q-N 1 35s 1f3f0000 0 0 user metal:silver: 0 |
294 | 00000894 I--Q-- 1 10h 003f0000 0 0 user metal:gold: 0 | |
1da177e4 LT |
295 | |
296 | The flags are: | |
297 | ||
298 | I Instantiated | |
299 | R Revoked | |
300 | D Dead | |
301 | Q Contributes to user's quota | |
302 | U Under contruction by callback to userspace | |
303 | N Negative key | |
304 | ||
305 | This file must be enabled at kernel configuration time as it allows anyone | |
306 | to list the keys database. | |
307 | ||
308 | (*) /proc/key-users | |
309 | ||
310 | This file lists the tracking data for each user that has at least one key | |
06ec7be5 | 311 | on the system. Such data includes quota information and statistics: |
1da177e4 LT |
312 | |
313 | [root@andromeda root]# cat /proc/key-users | |
314 | 0: 46 45/45 1/100 13/10000 | |
315 | 29: 2 2/2 2/100 40/10000 | |
316 | 32: 2 2/2 2/100 40/10000 | |
317 | 38: 2 2/2 2/100 40/10000 | |
318 | ||
319 | The format of each line is | |
320 | <UID>: User ID to which this applies | |
321 | <usage> Structure refcount | |
322 | <inst>/<keys> Total number of keys and number instantiated | |
323 | <keys>/<max> Key count quota | |
324 | <bytes>/<max> Key size quota | |
325 | ||
326 | ||
327 | =============================== | |
328 | USERSPACE SYSTEM CALL INTERFACE | |
329 | =============================== | |
330 | ||
331 | Userspace can manipulate keys directly through three new syscalls: add_key, | |
332 | request_key and keyctl. The latter provides a number of functions for | |
333 | manipulating keys. | |
334 | ||
335 | When referring to a key directly, userspace programs should use the key's | |
336 | serial number (a positive 32-bit integer). However, there are some special | |
337 | values available for referring to special keys and keyrings that relate to the | |
338 | process making the call: | |
339 | ||
340 | CONSTANT VALUE KEY REFERENCED | |
341 | ============================== ====== =========================== | |
342 | KEY_SPEC_THREAD_KEYRING -1 thread-specific keyring | |
343 | KEY_SPEC_PROCESS_KEYRING -2 process-specific keyring | |
344 | KEY_SPEC_SESSION_KEYRING -3 session-specific keyring | |
345 | KEY_SPEC_USER_KEYRING -4 UID-specific keyring | |
346 | KEY_SPEC_USER_SESSION_KEYRING -5 UID-session keyring | |
347 | KEY_SPEC_GROUP_KEYRING -6 GID-specific keyring | |
b5f545c8 DH |
348 | KEY_SPEC_REQKEY_AUTH_KEY -7 assumed request_key() |
349 | authorisation key | |
1da177e4 LT |
350 | |
351 | ||
352 | The main syscalls are: | |
353 | ||
354 | (*) Create a new key of given type, description and payload and add it to the | |
355 | nominated keyring: | |
356 | ||
357 | key_serial_t add_key(const char *type, const char *desc, | |
358 | const void *payload, size_t plen, | |
359 | key_serial_t keyring); | |
360 | ||
361 | If a key of the same type and description as that proposed already exists | |
362 | in the keyring, this will try to update it with the given payload, or it | |
363 | will return error EEXIST if that function is not supported by the key | |
76d8aeab DH |
364 | type. The process must also have permission to write to the key to be able |
365 | to update it. The new key will have all user permissions granted and no | |
366 | group or third party permissions. | |
1da177e4 | 367 | |
76d8aeab DH |
368 | Otherwise, this will attempt to create a new key of the specified type and |
369 | description, and to instantiate it with the supplied payload and attach it | |
370 | to the keyring. In this case, an error will be generated if the process | |
371 | does not have permission to write to the keyring. | |
1da177e4 LT |
372 | |
373 | The payload is optional, and the pointer can be NULL if not required by | |
374 | the type. The payload is plen in size, and plen can be zero for an empty | |
375 | payload. | |
376 | ||
76d8aeab DH |
377 | A new keyring can be generated by setting type "keyring", the keyring name |
378 | as the description (or NULL) and setting the payload to NULL. | |
1da177e4 LT |
379 | |
380 | User defined keys can be created by specifying type "user". It is | |
381 | recommended that a user defined key's description by prefixed with a type | |
382 | ID and a colon, such as "krb5tgt:" for a Kerberos 5 ticket granting | |
383 | ticket. | |
384 | ||
385 | Any other type must have been registered with the kernel in advance by a | |
386 | kernel service such as a filesystem. | |
387 | ||
388 | The ID of the new or updated key is returned if successful. | |
389 | ||
390 | ||
391 | (*) Search the process's keyrings for a key, potentially calling out to | |
392 | userspace to create it. | |
393 | ||
394 | key_serial_t request_key(const char *type, const char *description, | |
395 | const char *callout_info, | |
396 | key_serial_t dest_keyring); | |
397 | ||
398 | This function searches all the process's keyrings in the order thread, | |
399 | process, session for a matching key. This works very much like | |
400 | KEYCTL_SEARCH, including the optional attachment of the discovered key to | |
401 | a keyring. | |
402 | ||
403 | If a key cannot be found, and if callout_info is not NULL, then | |
404 | /sbin/request-key will be invoked in an attempt to obtain a key. The | |
405 | callout_info string will be passed as an argument to the program. | |
406 | ||
f1a9badc DH |
407 | See also Documentation/keys-request-key.txt. |
408 | ||
1da177e4 LT |
409 | |
410 | The keyctl syscall functions are: | |
411 | ||
412 | (*) Map a special key ID to a real key ID for this process: | |
413 | ||
414 | key_serial_t keyctl(KEYCTL_GET_KEYRING_ID, key_serial_t id, | |
415 | int create); | |
416 | ||
76d8aeab DH |
417 | The special key specified by "id" is looked up (with the key being created |
418 | if necessary) and the ID of the key or keyring thus found is returned if | |
419 | it exists. | |
1da177e4 LT |
420 | |
421 | If the key does not yet exist, the key will be created if "create" is | |
422 | non-zero; and the error ENOKEY will be returned if "create" is zero. | |
423 | ||
424 | ||
425 | (*) Replace the session keyring this process subscribes to with a new one: | |
426 | ||
427 | key_serial_t keyctl(KEYCTL_JOIN_SESSION_KEYRING, const char *name); | |
428 | ||
429 | If name is NULL, an anonymous keyring is created attached to the process | |
430 | as its session keyring, displacing the old session keyring. | |
431 | ||
432 | If name is not NULL, if a keyring of that name exists, the process | |
433 | attempts to attach it as the session keyring, returning an error if that | |
434 | is not permitted; otherwise a new keyring of that name is created and | |
435 | attached as the session keyring. | |
436 | ||
437 | To attach to a named keyring, the keyring must have search permission for | |
438 | the process's ownership. | |
439 | ||
440 | The ID of the new session keyring is returned if successful. | |
441 | ||
442 | ||
443 | (*) Update the specified key: | |
444 | ||
445 | long keyctl(KEYCTL_UPDATE, key_serial_t key, const void *payload, | |
446 | size_t plen); | |
447 | ||
448 | This will try to update the specified key with the given payload, or it | |
449 | will return error EOPNOTSUPP if that function is not supported by the key | |
76d8aeab DH |
450 | type. The process must also have permission to write to the key to be able |
451 | to update it. | |
1da177e4 LT |
452 | |
453 | The payload is of length plen, and may be absent or empty as for | |
454 | add_key(). | |
455 | ||
456 | ||
457 | (*) Revoke a key: | |
458 | ||
459 | long keyctl(KEYCTL_REVOKE, key_serial_t key); | |
460 | ||
461 | This makes a key unavailable for further operations. Further attempts to | |
462 | use the key will be met with error EKEYREVOKED, and the key will no longer | |
463 | be findable. | |
464 | ||
465 | ||
466 | (*) Change the ownership of a key: | |
467 | ||
468 | long keyctl(KEYCTL_CHOWN, key_serial_t key, uid_t uid, gid_t gid); | |
469 | ||
76d8aeab DH |
470 | This function permits a key's owner and group ID to be changed. Either one |
471 | of uid or gid can be set to -1 to suppress that change. | |
1da177e4 LT |
472 | |
473 | Only the superuser can change a key's owner to something other than the | |
474 | key's current owner. Similarly, only the superuser can change a key's | |
475 | group ID to something other than the calling process's group ID or one of | |
476 | its group list members. | |
477 | ||
478 | ||
479 | (*) Change the permissions mask on a key: | |
480 | ||
481 | long keyctl(KEYCTL_SETPERM, key_serial_t key, key_perm_t perm); | |
482 | ||
483 | This function permits the owner of a key or the superuser to change the | |
484 | permissions mask on a key. | |
485 | ||
486 | Only bits the available bits are permitted; if any other bits are set, | |
487 | error EINVAL will be returned. | |
488 | ||
489 | ||
490 | (*) Describe a key: | |
491 | ||
492 | long keyctl(KEYCTL_DESCRIBE, key_serial_t key, char *buffer, | |
493 | size_t buflen); | |
494 | ||
495 | This function returns a summary of the key's attributes (but not its | |
496 | payload data) as a string in the buffer provided. | |
497 | ||
498 | Unless there's an error, it always returns the amount of data it could | |
499 | produce, even if that's too big for the buffer, but it won't copy more | |
500 | than requested to userspace. If the buffer pointer is NULL then no copy | |
501 | will take place. | |
502 | ||
503 | A process must have view permission on the key for this function to be | |
504 | successful. | |
505 | ||
506 | If successful, a string is placed in the buffer in the following format: | |
507 | ||
508 | <type>;<uid>;<gid>;<perm>;<description> | |
509 | ||
510 | Where type and description are strings, uid and gid are decimal, and perm | |
511 | is hexadecimal. A NUL character is included at the end of the string if | |
512 | the buffer is sufficiently big. | |
513 | ||
514 | This can be parsed with | |
515 | ||
516 | sscanf(buffer, "%[^;];%d;%d;%o;%s", type, &uid, &gid, &mode, desc); | |
517 | ||
518 | ||
519 | (*) Clear out a keyring: | |
520 | ||
521 | long keyctl(KEYCTL_CLEAR, key_serial_t keyring); | |
522 | ||
523 | This function clears the list of keys attached to a keyring. The calling | |
524 | process must have write permission on the keyring, and it must be a | |
525 | keyring (or else error ENOTDIR will result). | |
526 | ||
527 | ||
528 | (*) Link a key into a keyring: | |
529 | ||
530 | long keyctl(KEYCTL_LINK, key_serial_t keyring, key_serial_t key); | |
531 | ||
76d8aeab DH |
532 | This function creates a link from the keyring to the key. The process must |
533 | have write permission on the keyring and must have link permission on the | |
534 | key. | |
1da177e4 | 535 | |
76d8aeab DH |
536 | Should the keyring not be a keyring, error ENOTDIR will result; and if the |
537 | keyring is full, error ENFILE will result. | |
1da177e4 LT |
538 | |
539 | The link procedure checks the nesting of the keyrings, returning ELOOP if | |
017679c4 | 540 | it appears too deep or EDEADLK if the link would introduce a cycle. |
1da177e4 | 541 | |
cab8eb59 DH |
542 | Any links within the keyring to keys that match the new key in terms of |
543 | type and description will be discarded from the keyring as the new one is | |
544 | added. | |
545 | ||
1da177e4 LT |
546 | |
547 | (*) Unlink a key or keyring from another keyring: | |
548 | ||
549 | long keyctl(KEYCTL_UNLINK, key_serial_t keyring, key_serial_t key); | |
550 | ||
551 | This function looks through the keyring for the first link to the | |
552 | specified key, and removes it if found. Subsequent links to that key are | |
553 | ignored. The process must have write permission on the keyring. | |
554 | ||
76d8aeab DH |
555 | If the keyring is not a keyring, error ENOTDIR will result; and if the key |
556 | is not present, error ENOENT will be the result. | |
1da177e4 LT |
557 | |
558 | ||
559 | (*) Search a keyring tree for a key: | |
560 | ||
561 | key_serial_t keyctl(KEYCTL_SEARCH, key_serial_t keyring, | |
562 | const char *type, const char *description, | |
563 | key_serial_t dest_keyring); | |
564 | ||
76d8aeab DH |
565 | This searches the keyring tree headed by the specified keyring until a key |
566 | is found that matches the type and description criteria. Each keyring is | |
567 | checked for keys before recursion into its children occurs. | |
1da177e4 LT |
568 | |
569 | The process must have search permission on the top level keyring, or else | |
570 | error EACCES will result. Only keyrings that the process has search | |
571 | permission on will be recursed into, and only keys and keyrings for which | |
572 | a process has search permission can be matched. If the specified keyring | |
573 | is not a keyring, ENOTDIR will result. | |
574 | ||
575 | If the search succeeds, the function will attempt to link the found key | |
576 | into the destination keyring if one is supplied (non-zero ID). All the | |
577 | constraints applicable to KEYCTL_LINK apply in this case too. | |
578 | ||
579 | Error ENOKEY, EKEYREVOKED or EKEYEXPIRED will be returned if the search | |
580 | fails. On success, the resulting key ID will be returned. | |
581 | ||
582 | ||
583 | (*) Read the payload data from a key: | |
584 | ||
f1a9badc DH |
585 | long keyctl(KEYCTL_READ, key_serial_t keyring, char *buffer, |
586 | size_t buflen); | |
1da177e4 LT |
587 | |
588 | This function attempts to read the payload data from the specified key | |
589 | into the buffer. The process must have read permission on the key to | |
590 | succeed. | |
591 | ||
592 | The returned data will be processed for presentation by the key type. For | |
593 | instance, a keyring will return an array of key_serial_t entries | |
594 | representing the IDs of all the keys to which it is subscribed. The user | |
595 | defined key type will return its data as is. If a key type does not | |
596 | implement this function, error EOPNOTSUPP will result. | |
597 | ||
598 | As much of the data as can be fitted into the buffer will be copied to | |
599 | userspace if the buffer pointer is not NULL. | |
600 | ||
76d8aeab DH |
601 | On a successful return, the function will always return the amount of data |
602 | available rather than the amount copied. | |
1da177e4 LT |
603 | |
604 | ||
605 | (*) Instantiate a partially constructed key. | |
606 | ||
f1a9badc DH |
607 | long keyctl(KEYCTL_INSTANTIATE, key_serial_t key, |
608 | const void *payload, size_t plen, | |
609 | key_serial_t keyring); | |
1da177e4 LT |
610 | |
611 | If the kernel calls back to userspace to complete the instantiation of a | |
612 | key, userspace should use this call to supply data for the key before the | |
613 | invoked process returns, or else the key will be marked negative | |
614 | automatically. | |
615 | ||
616 | The process must have write access on the key to be able to instantiate | |
617 | it, and the key must be uninstantiated. | |
618 | ||
619 | If a keyring is specified (non-zero), the key will also be linked into | |
76d8aeab DH |
620 | that keyring, however all the constraints applying in KEYCTL_LINK apply in |
621 | this case too. | |
1da177e4 LT |
622 | |
623 | The payload and plen arguments describe the payload data as for add_key(). | |
624 | ||
625 | ||
626 | (*) Negatively instantiate a partially constructed key. | |
627 | ||
f1a9badc DH |
628 | long keyctl(KEYCTL_NEGATE, key_serial_t key, |
629 | unsigned timeout, key_serial_t keyring); | |
1da177e4 LT |
630 | |
631 | If the kernel calls back to userspace to complete the instantiation of a | |
632 | key, userspace should use this call mark the key as negative before the | |
633 | invoked process returns if it is unable to fulfil the request. | |
634 | ||
635 | The process must have write access on the key to be able to instantiate | |
636 | it, and the key must be uninstantiated. | |
637 | ||
638 | If a keyring is specified (non-zero), the key will also be linked into | |
76d8aeab DH |
639 | that keyring, however all the constraints applying in KEYCTL_LINK apply in |
640 | this case too. | |
1da177e4 LT |
641 | |
642 | ||
3e30148c DH |
643 | (*) Set the default request-key destination keyring. |
644 | ||
645 | long keyctl(KEYCTL_SET_REQKEY_KEYRING, int reqkey_defl); | |
646 | ||
647 | This sets the default keyring to which implicitly requested keys will be | |
648 | attached for this thread. reqkey_defl should be one of these constants: | |
649 | ||
650 | CONSTANT VALUE NEW DEFAULT KEYRING | |
651 | ====================================== ====== ======================= | |
652 | KEY_REQKEY_DEFL_NO_CHANGE -1 No change | |
653 | KEY_REQKEY_DEFL_DEFAULT 0 Default[1] | |
654 | KEY_REQKEY_DEFL_THREAD_KEYRING 1 Thread keyring | |
655 | KEY_REQKEY_DEFL_PROCESS_KEYRING 2 Process keyring | |
656 | KEY_REQKEY_DEFL_SESSION_KEYRING 3 Session keyring | |
657 | KEY_REQKEY_DEFL_USER_KEYRING 4 User keyring | |
658 | KEY_REQKEY_DEFL_USER_SESSION_KEYRING 5 User session keyring | |
659 | KEY_REQKEY_DEFL_GROUP_KEYRING 6 Group keyring | |
660 | ||
661 | The old default will be returned if successful and error EINVAL will be | |
662 | returned if reqkey_defl is not one of the above values. | |
663 | ||
664 | The default keyring can be overridden by the keyring indicated to the | |
665 | request_key() system call. | |
666 | ||
667 | Note that this setting is inherited across fork/exec. | |
668 | ||
669 | [1] The default default is: the thread keyring if there is one, otherwise | |
670 | the process keyring if there is one, otherwise the session keyring if | |
671 | there is one, otherwise the user default session keyring. | |
672 | ||
673 | ||
017679c4 DH |
674 | (*) Set the timeout on a key. |
675 | ||
676 | long keyctl(KEYCTL_SET_TIMEOUT, key_serial_t key, unsigned timeout); | |
677 | ||
678 | This sets or clears the timeout on a key. The timeout can be 0 to clear | |
679 | the timeout or a number of seconds to set the expiry time that far into | |
680 | the future. | |
681 | ||
682 | The process must have attribute modification access on a key to set its | |
683 | timeout. Timeouts may not be set with this function on negative, revoked | |
684 | or expired keys. | |
685 | ||
686 | ||
b5f545c8 DH |
687 | (*) Assume the authority granted to instantiate a key |
688 | ||
689 | long keyctl(KEYCTL_ASSUME_AUTHORITY, key_serial_t key); | |
690 | ||
691 | This assumes or divests the authority required to instantiate the | |
692 | specified key. Authority can only be assumed if the thread has the | |
693 | authorisation key associated with the specified key in its keyrings | |
694 | somewhere. | |
695 | ||
696 | Once authority is assumed, searches for keys will also search the | |
697 | requester's keyrings using the requester's security label, UID, GID and | |
698 | groups. | |
699 | ||
700 | If the requested authority is unavailable, error EPERM will be returned, | |
701 | likewise if the authority has been revoked because the target key is | |
702 | already instantiated. | |
703 | ||
704 | If the specified key is 0, then any assumed authority will be divested. | |
705 | ||
706 | The assumed authorititive key is inherited across fork and exec. | |
707 | ||
708 | ||
1da177e4 LT |
709 | =============== |
710 | KERNEL SERVICES | |
711 | =============== | |
712 | ||
713 | The kernel services for key managment are fairly simple to deal with. They can | |
714 | be broken down into two areas: keys and key types. | |
715 | ||
716 | Dealing with keys is fairly straightforward. Firstly, the kernel service | |
717 | registers its type, then it searches for a key of that type. It should retain | |
718 | the key as long as it has need of it, and then it should release it. For a | |
76d8aeab DH |
719 | filesystem or device file, a search would probably be performed during the open |
720 | call, and the key released upon close. How to deal with conflicting keys due to | |
721 | two different users opening the same file is left to the filesystem author to | |
722 | solve. | |
723 | ||
664cceb0 DH |
724 | Note that there are two different types of pointers to keys that may be |
725 | encountered: | |
726 | ||
727 | (*) struct key * | |
728 | ||
729 | This simply points to the key structure itself. Key structures will be at | |
730 | least four-byte aligned. | |
731 | ||
732 | (*) key_ref_t | |
733 | ||
734 | This is equivalent to a struct key *, but the least significant bit is set | |
735 | if the caller "possesses" the key. By "possession" it is meant that the | |
736 | calling processes has a searchable link to the key from one of its | |
737 | keyrings. There are three functions for dealing with these: | |
738 | ||
739 | key_ref_t make_key_ref(const struct key *key, | |
740 | unsigned long possession); | |
741 | ||
742 | struct key *key_ref_to_ptr(const key_ref_t key_ref); | |
743 | ||
744 | unsigned long is_key_possessed(const key_ref_t key_ref); | |
745 | ||
746 | The first function constructs a key reference from a key pointer and | |
747 | possession information (which must be 0 or 1 and not any other value). | |
748 | ||
749 | The second function retrieves the key pointer from a reference and the | |
750 | third retrieves the possession flag. | |
751 | ||
76d8aeab DH |
752 | When accessing a key's payload contents, certain precautions must be taken to |
753 | prevent access vs modification races. See the section "Notes on accessing | |
754 | payload contents" for more information. | |
1da177e4 LT |
755 | |
756 | (*) To search for a key, call: | |
757 | ||
758 | struct key *request_key(const struct key_type *type, | |
759 | const char *description, | |
760 | const char *callout_string); | |
761 | ||
762 | This is used to request a key or keyring with a description that matches | |
763 | the description specified according to the key type's match function. This | |
764 | permits approximate matching to occur. If callout_string is not NULL, then | |
765 | /sbin/request-key will be invoked in an attempt to obtain the key from | |
766 | userspace. In that case, callout_string will be passed as an argument to | |
767 | the program. | |
768 | ||
769 | Should the function fail error ENOKEY, EKEYEXPIRED or EKEYREVOKED will be | |
770 | returned. | |
771 | ||
3e30148c DH |
772 | If successful, the key will have been attached to the default keyring for |
773 | implicitly obtained request-key keys, as set by KEYCTL_SET_REQKEY_KEYRING. | |
774 | ||
f1a9badc DH |
775 | See also Documentation/keys-request-key.txt. |
776 | ||
1da177e4 LT |
777 | |
778 | (*) When it is no longer required, the key should be released using: | |
779 | ||
780 | void key_put(struct key *key); | |
781 | ||
664cceb0 DH |
782 | Or: |
783 | ||
784 | void key_ref_put(key_ref_t key_ref); | |
785 | ||
786 | These can be called from interrupt context. If CONFIG_KEYS is not set then | |
1da177e4 LT |
787 | the argument will not be parsed. |
788 | ||
789 | ||
790 | (*) Extra references can be made to a key by calling the following function: | |
791 | ||
792 | struct key *key_get(struct key *key); | |
793 | ||
794 | These need to be disposed of by calling key_put() when they've been | |
795 | finished with. The key pointer passed in will be returned. If the pointer | |
796 | is NULL or CONFIG_KEYS is not set then the key will not be dereferenced and | |
797 | no increment will take place. | |
798 | ||
799 | ||
800 | (*) A key's serial number can be obtained by calling: | |
801 | ||
802 | key_serial_t key_serial(struct key *key); | |
803 | ||
804 | If key is NULL or if CONFIG_KEYS is not set then 0 will be returned (in the | |
805 | latter case without parsing the argument). | |
806 | ||
807 | ||
808 | (*) If a keyring was found in the search, this can be further searched by: | |
809 | ||
664cceb0 DH |
810 | key_ref_t keyring_search(key_ref_t keyring_ref, |
811 | const struct key_type *type, | |
812 | const char *description) | |
1da177e4 LT |
813 | |
814 | This searches the keyring tree specified for a matching key. Error ENOKEY | |
664cceb0 DH |
815 | is returned upon failure (use IS_ERR/PTR_ERR to determine). If successful, |
816 | the returned key will need to be released. | |
817 | ||
818 | The possession attribute from the keyring reference is used to control | |
819 | access through the permissions mask and is propagated to the returned key | |
820 | reference pointer if successful. | |
1da177e4 LT |
821 | |
822 | ||
823 | (*) To check the validity of a key, this function can be called: | |
824 | ||
825 | int validate_key(struct key *key); | |
826 | ||
827 | This checks that the key in question hasn't expired or and hasn't been | |
828 | revoked. Should the key be invalid, error EKEYEXPIRED or EKEYREVOKED will | |
829 | be returned. If the key is NULL or if CONFIG_KEYS is not set then 0 will be | |
830 | returned (in the latter case without parsing the argument). | |
831 | ||
832 | ||
833 | (*) To register a key type, the following function should be called: | |
834 | ||
835 | int register_key_type(struct key_type *type); | |
836 | ||
837 | This will return error EEXIST if a type of the same name is already | |
838 | present. | |
839 | ||
840 | ||
841 | (*) To unregister a key type, call: | |
842 | ||
843 | void unregister_key_type(struct key_type *type); | |
844 | ||
845 | ||
76d8aeab DH |
846 | =================================== |
847 | NOTES ON ACCESSING PAYLOAD CONTENTS | |
848 | =================================== | |
849 | ||
850 | The simplest payload is just a number in key->payload.value. In this case, | |
851 | there's no need to indulge in RCU or locking when accessing the payload. | |
852 | ||
853 | More complex payload contents must be allocated and a pointer to them set in | |
854 | key->payload.data. One of the following ways must be selected to access the | |
855 | data: | |
856 | ||
664cceb0 | 857 | (1) Unmodifiable key type. |
76d8aeab DH |
858 | |
859 | If the key type does not have a modify method, then the key's payload can | |
860 | be accessed without any form of locking, provided that it's known to be | |
861 | instantiated (uninstantiated keys cannot be "found"). | |
862 | ||
863 | (2) The key's semaphore. | |
864 | ||
865 | The semaphore could be used to govern access to the payload and to control | |
866 | the payload pointer. It must be write-locked for modifications and would | |
867 | have to be read-locked for general access. The disadvantage of doing this | |
868 | is that the accessor may be required to sleep. | |
869 | ||
870 | (3) RCU. | |
871 | ||
872 | RCU must be used when the semaphore isn't already held; if the semaphore | |
873 | is held then the contents can't change under you unexpectedly as the | |
874 | semaphore must still be used to serialise modifications to the key. The | |
875 | key management code takes care of this for the key type. | |
876 | ||
877 | However, this means using: | |
878 | ||
879 | rcu_read_lock() ... rcu_dereference() ... rcu_read_unlock() | |
880 | ||
881 | to read the pointer, and: | |
882 | ||
883 | rcu_dereference() ... rcu_assign_pointer() ... call_rcu() | |
884 | ||
885 | to set the pointer and dispose of the old contents after a grace period. | |
886 | Note that only the key type should ever modify a key's payload. | |
887 | ||
888 | Furthermore, an RCU controlled payload must hold a struct rcu_head for the | |
889 | use of call_rcu() and, if the payload is of variable size, the length of | |
890 | the payload. key->datalen cannot be relied upon to be consistent with the | |
891 | payload just dereferenced if the key's semaphore is not held. | |
892 | ||
893 | ||
1da177e4 LT |
894 | =================== |
895 | DEFINING A KEY TYPE | |
896 | =================== | |
897 | ||
898 | A kernel service may want to define its own key type. For instance, an AFS | |
899 | filesystem might want to define a Kerberos 5 ticket key type. To do this, it | |
900 | author fills in a struct key_type and registers it with the system. | |
901 | ||
902 | The structure has a number of fields, some of which are mandatory: | |
903 | ||
904 | (*) const char *name | |
905 | ||
906 | The name of the key type. This is used to translate a key type name | |
907 | supplied by userspace into a pointer to the structure. | |
908 | ||
909 | ||
910 | (*) size_t def_datalen | |
911 | ||
912 | This is optional - it supplies the default payload data length as | |
913 | contributed to the quota. If the key type's payload is always or almost | |
914 | always the same size, then this is a more efficient way to do things. | |
915 | ||
916 | The data length (and quota) on a particular key can always be changed | |
917 | during instantiation or update by calling: | |
918 | ||
919 | int key_payload_reserve(struct key *key, size_t datalen); | |
920 | ||
76d8aeab DH |
921 | With the revised data length. Error EDQUOT will be returned if this is not |
922 | viable. | |
1da177e4 LT |
923 | |
924 | ||
925 | (*) int (*instantiate)(struct key *key, const void *data, size_t datalen); | |
926 | ||
927 | This method is called to attach a payload to a key during construction. | |
76d8aeab DH |
928 | The payload attached need not bear any relation to the data passed to this |
929 | function. | |
1da177e4 LT |
930 | |
931 | If the amount of data attached to the key differs from the size in | |
932 | keytype->def_datalen, then key_payload_reserve() should be called. | |
933 | ||
934 | This method does not have to lock the key in order to attach a payload. | |
935 | The fact that KEY_FLAG_INSTANTIATED is not set in key->flags prevents | |
936 | anything else from gaining access to the key. | |
937 | ||
76d8aeab | 938 | It is safe to sleep in this method. |
1da177e4 LT |
939 | |
940 | ||
1da177e4 LT |
941 | (*) int (*update)(struct key *key, const void *data, size_t datalen); |
942 | ||
76d8aeab DH |
943 | If this type of key can be updated, then this method should be provided. |
944 | It is called to update a key's payload from the blob of data provided. | |
1da177e4 LT |
945 | |
946 | key_payload_reserve() should be called if the data length might change | |
76d8aeab DH |
947 | before any changes are actually made. Note that if this succeeds, the type |
948 | is committed to changing the key because it's already been altered, so all | |
949 | memory allocation must be done first. | |
950 | ||
951 | The key will have its semaphore write-locked before this method is called, | |
952 | but this only deters other writers; any changes to the key's payload must | |
953 | be made under RCU conditions, and call_rcu() must be used to dispose of | |
954 | the old payload. | |
1da177e4 | 955 | |
76d8aeab DH |
956 | key_payload_reserve() should be called before the changes are made, but |
957 | after all allocations and other potentially failing function calls are | |
958 | made. | |
1da177e4 | 959 | |
76d8aeab | 960 | It is safe to sleep in this method. |
1da177e4 LT |
961 | |
962 | ||
963 | (*) int (*match)(const struct key *key, const void *desc); | |
964 | ||
965 | This method is called to match a key against a description. It should | |
966 | return non-zero if the two match, zero if they don't. | |
967 | ||
968 | This method should not need to lock the key in any way. The type and | |
969 | description can be considered invariant, and the payload should not be | |
970 | accessed (the key may not yet be instantiated). | |
971 | ||
972 | It is not safe to sleep in this method; the caller may hold spinlocks. | |
973 | ||
974 | ||
04c567d9 DH |
975 | (*) void (*revoke)(struct key *key); |
976 | ||
977 | This method is optional. It is called to discard part of the payload | |
978 | data upon a key being revoked. The caller will have the key semaphore | |
979 | write-locked. | |
980 | ||
981 | It is safe to sleep in this method, though care should be taken to avoid | |
982 | a deadlock against the key semaphore. | |
983 | ||
984 | ||
1da177e4 LT |
985 | (*) void (*destroy)(struct key *key); |
986 | ||
76d8aeab DH |
987 | This method is optional. It is called to discard the payload data on a key |
988 | when it is being destroyed. | |
1da177e4 | 989 | |
76d8aeab DH |
990 | This method does not need to lock the key to access the payload; it can |
991 | consider the key as being inaccessible at this time. Note that the key's | |
992 | type may have been changed before this function is called. | |
1da177e4 LT |
993 | |
994 | It is not safe to sleep in this method; the caller may hold spinlocks. | |
995 | ||
996 | ||
997 | (*) void (*describe)(const struct key *key, struct seq_file *p); | |
998 | ||
999 | This method is optional. It is called during /proc/keys reading to | |
1000 | summarise a key's description and payload in text form. | |
1001 | ||
76d8aeab DH |
1002 | This method will be called with the RCU read lock held. rcu_dereference() |
1003 | should be used to read the payload pointer if the payload is to be | |
1004 | accessed. key->datalen cannot be trusted to stay consistent with the | |
1005 | contents of the payload. | |
1006 | ||
1007 | The description will not change, though the key's state may. | |
1008 | ||
1009 | It is not safe to sleep in this method; the RCU read lock is held by the | |
1010 | caller. | |
1da177e4 LT |
1011 | |
1012 | ||
1013 | (*) long (*read)(const struct key *key, char __user *buffer, size_t buflen); | |
1014 | ||
1015 | This method is optional. It is called by KEYCTL_READ to translate the | |
76d8aeab DH |
1016 | key's payload into something a blob of data for userspace to deal with. |
1017 | Ideally, the blob should be in the same format as that passed in to the | |
1018 | instantiate and update methods. | |
1da177e4 LT |
1019 | |
1020 | If successful, the blob size that could be produced should be returned | |
1021 | rather than the size copied. | |
1022 | ||
76d8aeab DH |
1023 | This method will be called with the key's semaphore read-locked. This will |
1024 | prevent the key's payload changing. It is not necessary to use RCU locking | |
1025 | when accessing the key's payload. It is safe to sleep in this method, such | |
1026 | as might happen when the userspace buffer is accessed. | |
1da177e4 LT |
1027 | |
1028 | ||
1029 | ============================ | |
1030 | REQUEST-KEY CALLBACK SERVICE | |
1031 | ============================ | |
1032 | ||
1033 | To create a new key, the kernel will attempt to execute the following command | |
1034 | line: | |
1035 | ||
1036 | /sbin/request-key create <key> <uid> <gid> \ | |
1037 | <threadring> <processring> <sessionring> <callout_info> | |
1038 | ||
1039 | <key> is the key being constructed, and the three keyrings are the process | |
1040 | keyrings from the process that caused the search to be issued. These are | |
1041 | included for two reasons: | |
1042 | ||
1043 | (1) There may be an authentication token in one of the keyrings that is | |
1044 | required to obtain the key, eg: a Kerberos Ticket-Granting Ticket. | |
1045 | ||
1046 | (2) The new key should probably be cached in one of these rings. | |
1047 | ||
1048 | This program should set it UID and GID to those specified before attempting to | |
1049 | access any more keys. It may then look around for a user specific process to | |
1050 | hand the request off to (perhaps a path held in placed in another key by, for | |
1051 | example, the KDE desktop manager). | |
1052 | ||
1053 | The program (or whatever it calls) should finish construction of the key by | |
1054 | calling KEYCTL_INSTANTIATE, which also permits it to cache the key in one of | |
1055 | the keyrings (probably the session ring) before returning. Alternatively, the | |
1056 | key can be marked as negative with KEYCTL_NEGATE; this also permits the key to | |
1057 | be cached in one of the keyrings. | |
1058 | ||
1059 | If it returns with the key remaining in the unconstructed state, the key will | |
1060 | be marked as being negative, it will be added to the session keyring, and an | |
1061 | error will be returned to the key requestor. | |
1062 | ||
76d8aeab DH |
1063 | Supplementary information may be provided from whoever or whatever invoked this |
1064 | service. This will be passed as the <callout_info> parameter. If no such | |
1da177e4 LT |
1065 | information was made available, then "-" will be passed as this parameter |
1066 | instead. | |
1067 | ||
1068 | ||
1069 | Similarly, the kernel may attempt to update an expired or a soon to expire key | |
1070 | by executing: | |
1071 | ||
1072 | /sbin/request-key update <key> <uid> <gid> \ | |
1073 | <threadring> <processring> <sessionring> | |
1074 | ||
1075 | In this case, the program isn't required to actually attach the key to a ring; | |
1076 | the rings are provided for reference. |