Commit | Line | Data |
---|---|---|
b68101a1 KC |
1 | ============================ |
2 | Kernel Key Retention Service | |
3 | ============================ | |
1da177e4 LT |
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 | |
76181c13 | 7 | filesystems and other kernel services. |
1da177e4 LT |
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 | ||
33c2f4ec | 19 | .. contents:: :local: |
1da177e4 LT |
20 | |
21 | ||
b68101a1 | 22 | Key Overview |
1da177e4 LT |
23 | ============ |
24 | ||
25 | In this context, keys represent units of cryptographic data, authentication | |
26 | tokens, keyrings, etc.. These are represented in the kernel by struct key. | |
27 | ||
28 | Each key has a number of attributes: | |
29 | ||
30 | - A serial number. | |
31 | - A type. | |
32 | - A description (for matching a key in a search). | |
33 | - Access control information. | |
34 | - An expiry time. | |
35 | - A payload. | |
36 | - State. | |
37 | ||
38 | ||
b68101a1 | 39 | * Each key is issued a serial number of type key_serial_t that is unique for |
76d8aeab DH |
40 | the lifetime of that key. All serial numbers are positive non-zero 32-bit |
41 | integers. | |
1da177e4 LT |
42 | |
43 | Userspace programs can use a key's serial numbers as a way to gain access | |
44 | to it, subject to permission checking. | |
45 | ||
b68101a1 | 46 | * Each key is of a defined "type". Types must be registered inside the |
76d8aeab DH |
47 | kernel by a kernel service (such as a filesystem) before keys of that type |
48 | can be added or used. Userspace programs cannot define new types directly. | |
1da177e4 | 49 | |
76d8aeab DH |
50 | Key types are represented in the kernel by struct key_type. This defines a |
51 | number of operations that can be performed on a key of that type. | |
1da177e4 LT |
52 | |
53 | Should a type be removed from the system, all the keys of that type will | |
54 | be invalidated. | |
55 | ||
b68101a1 | 56 | * Each key has a description. This should be a printable string. The key |
76d8aeab DH |
57 | type provides an operation to perform a match between the description on a |
58 | key and a criterion string. | |
1da177e4 | 59 | |
b68101a1 | 60 | * Each key has an owner user ID, a group ID and a permissions mask. These |
1da177e4 LT |
61 | are used to control what a process may do to a key from userspace, and |
62 | whether a kernel service will be able to find the key. | |
63 | ||
b68101a1 | 64 | * Each key can be set to expire at a specific time by the key type's |
1da177e4 LT |
65 | instantiation function. Keys can also be immortal. |
66 | ||
b68101a1 | 67 | * Each key can have a payload. This is a quantity of data that represent the |
76d8aeab DH |
68 | actual "key". In the case of a keyring, this is a list of keys to which |
69 | the keyring links; in the case of a user-defined key, it's an arbitrary | |
70 | blob of data. | |
1da177e4 LT |
71 | |
72 | Having a payload is not required; and the payload can, in fact, just be a | |
73 | value stored in the struct key itself. | |
74 | ||
75 | When a key is instantiated, the key type's instantiation function is | |
76 | called with a blob of data, and that then creates the key's payload in | |
77 | some way. | |
78 | ||
79 | Similarly, when userspace wants to read back the contents of the key, if | |
80 | permitted, another key type operation will be called to convert the key's | |
81 | attached payload back into a blob of data. | |
82 | ||
b68101a1 | 83 | * Each key can be in one of a number of basic states: |
1da177e4 | 84 | |
b68101a1 | 85 | * Uninstantiated. The key exists, but does not have any data attached. |
76d8aeab | 86 | Keys being requested from userspace will be in this state. |
1da177e4 | 87 | |
b68101a1 | 88 | * Instantiated. This is the normal state. The key is fully formed, and |
1da177e4 LT |
89 | has data attached. |
90 | ||
b68101a1 | 91 | * Negative. This is a relatively short-lived state. The key acts as a |
1da177e4 LT |
92 | note saying that a previous call out to userspace failed, and acts as |
93 | a throttle on key lookups. A negative key can be updated to a normal | |
94 | state. | |
95 | ||
b68101a1 | 96 | * Expired. Keys can have lifetimes set. If their lifetime is exceeded, |
1da177e4 LT |
97 | they traverse to this state. An expired key can be updated back to a |
98 | normal state. | |
99 | ||
b68101a1 | 100 | * Revoked. A key is put in this state by userspace action. It can't be |
1da177e4 LT |
101 | found or operated upon (apart from by unlinking it). |
102 | ||
b68101a1 | 103 | * Dead. The key's type was unregistered, and so the key is now useless. |
1da177e4 | 104 | |
5d135440 DH |
105 | Keys in the last three states are subject to garbage collection. See the |
106 | section on "Garbage collection". | |
107 | ||
1da177e4 | 108 | |
b68101a1 | 109 | Key Service Overview |
1da177e4 LT |
110 | ==================== |
111 | ||
112 | The key service provides a number of features besides keys: | |
113 | ||
b68101a1 | 114 | * The key service defines three special key types: |
1da177e4 LT |
115 | |
116 | (+) "keyring" | |
117 | ||
118 | Keyrings are special keys that contain a list of other keys. Keyring | |
119 | lists can be modified using various system calls. Keyrings should not | |
120 | be given a payload when created. | |
121 | ||
122 | (+) "user" | |
123 | ||
124 | A key of this type has a description and a payload that are arbitrary | |
125 | blobs of data. These can be created, updated and read by userspace, | |
126 | and aren't intended for use by kernel services. | |
127 | ||
a05a4830 JL |
128 | (+) "logon" |
129 | ||
130 | Like a "user" key, a "logon" key has a payload that is an arbitrary | |
131 | blob of data. It is intended as a place to store secrets which are | |
132 | accessible to the kernel but not to userspace programs. | |
133 | ||
134 | The description can be arbitrary, but must be prefixed with a non-zero | |
135 | length string that describes the key "subclass". The subclass is | |
136 | separated from the rest of the description by a ':'. "logon" keys can | |
137 | be created and updated from userspace, but the payload is only | |
138 | readable from kernel space. | |
139 | ||
b68101a1 | 140 | * Each process subscribes to three keyrings: a thread-specific keyring, a |
1da177e4 LT |
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 | ||
76d8aeab DH |
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. | |
1da177e4 LT |
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 | ||
b68101a1 | 161 | * Each user ID resident in the system holds two special keyrings: a user |
1da177e4 LT |
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 | ||
b68101a1 | 171 | * Each user has two quotas against which the keys they own are tracked. One |
1da177e4 LT |
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 | |
0b77f5bf DH |
176 | files. The root user may also alter the quota limits through sysctl files |
177 | (see the section "New procfs files"). | |
1da177e4 LT |
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 | ||
b68101a1 | 185 | * There's a system call interface by which userspace programs can create and |
76d8aeab | 186 | manipulate keys and keyrings. |
1da177e4 | 187 | |
b68101a1 | 188 | * There's a kernel interface by which services can register types and search |
76d8aeab | 189 | for keys. |
1da177e4 | 190 | |
b68101a1 | 191 | * There's a way for the a search done from the kernel to call back to |
1da177e4 LT |
192 | userspace to request a key that can't be found in a process's keyrings. |
193 | ||
b68101a1 | 194 | * An optional filesystem is available through which the key database can be |
1da177e4 LT |
195 | viewed and manipulated. |
196 | ||
197 | ||
b68101a1 | 198 | Key Access Permissions |
1da177e4 LT |
199 | ====================== |
200 | ||
76d8aeab | 201 | Keys have an owner user ID, a group access ID, and a permissions mask. The mask |
664cceb0 | 202 | has up to eight bits each for possessor, user, group and other access. Only |
29db9190 | 203 | six of each set of eight bits are defined. These permissions granted are: |
1da177e4 | 204 | |
b68101a1 | 205 | * View |
1da177e4 LT |
206 | |
207 | This permits a key or keyring's attributes to be viewed - including key | |
208 | type and description. | |
209 | ||
b68101a1 | 210 | * Read |
1da177e4 LT |
211 | |
212 | This permits a key's payload to be viewed or a keyring's list of linked | |
213 | keys. | |
214 | ||
b68101a1 | 215 | * Write |
1da177e4 | 216 | |
76d8aeab DH |
217 | This permits a key's payload to be instantiated or updated, or it allows a |
218 | link to be added to or removed from a keyring. | |
1da177e4 | 219 | |
b68101a1 | 220 | * Search |
1da177e4 LT |
221 | |
222 | This permits keyrings to be searched and keys to be found. Searches can | |
223 | only recurse into nested keyrings that have search permission set. | |
224 | ||
b68101a1 | 225 | * Link |
1da177e4 LT |
226 | |
227 | This permits a key or keyring to be linked to. To create a link from a | |
228 | keyring to a key, a process must have Write permission on the keyring and | |
229 | Link permission on the key. | |
230 | ||
b68101a1 | 231 | * Set Attribute |
29db9190 DH |
232 | |
233 | This permits a key's UID, GID and permissions mask to be changed. | |
234 | ||
1da177e4 LT |
235 | For changing the ownership, group ID or permissions mask, being the owner of |
236 | the key or having the sysadmin capability is sufficient. | |
237 | ||
238 | ||
b68101a1 | 239 | SELinux Support |
d720024e ML |
240 | =============== |
241 | ||
242 | The security class "key" has been added to SELinux so that mandatory access | |
243 | controls can be applied to keys created within various contexts. This support | |
244 | is preliminary, and is likely to change quite significantly in the near future. | |
245 | Currently, all of the basic permissions explained above are provided in SELinux | |
4eb582cf | 246 | as well; SELinux is simply invoked after all basic permission checks have been |
d720024e ML |
247 | performed. |
248 | ||
4eb582cf ML |
249 | The value of the file /proc/self/attr/keycreate influences the labeling of |
250 | newly-created keys. If the contents of that file correspond to an SELinux | |
251 | security context, then the key will be assigned that context. Otherwise, the | |
252 | key will be assigned the current context of the task that invoked the key | |
253 | creation request. Tasks must be granted explicit permission to assign a | |
254 | particular context to newly-created keys, using the "create" permission in the | |
255 | key security class. | |
d720024e | 256 | |
4eb582cf ML |
257 | The default keyrings associated with users will be labeled with the default |
258 | context of the user if and only if the login programs have been instrumented to | |
259 | properly initialize keycreate during the login process. Otherwise, they will | |
260 | be labeled with the context of the login program itself. | |
d720024e ML |
261 | |
262 | Note, however, that the default keyrings associated with the root user are | |
263 | labeled with the default kernel context, since they are created early in the | |
264 | boot process, before root has a chance to log in. | |
265 | ||
4eb582cf ML |
266 | The keyrings associated with new threads are each labeled with the context of |
267 | their associated thread, and both session and process keyrings are handled | |
268 | similarly. | |
269 | ||
d720024e | 270 | |
b68101a1 | 271 | New ProcFS Files |
1da177e4 LT |
272 | ================ |
273 | ||
274 | Two files have been added to procfs by which an administrator can find out | |
275 | about the status of the key service: | |
276 | ||
b68101a1 | 277 | * /proc/keys |
1da177e4 | 278 | |
06ec7be5 ML |
279 | This lists the keys that are currently viewable by the task reading the |
280 | file, giving information about their type, description and permissions. | |
281 | It is not possible to view the payload of the key this way, though some | |
282 | information about it may be given. | |
283 | ||
284 | The only keys included in the list are those that grant View permission to | |
285 | the reading process whether or not it possesses them. Note that LSM | |
286 | security checks are still performed, and may further filter out keys that | |
287 | the current process is not authorised to view. | |
288 | ||
b68101a1 | 289 | The contents of the file look like this:: |
1da177e4 | 290 | |
664cceb0 | 291 | SERIAL FLAGS USAGE EXPY PERM UID GID TYPE DESCRIPTION: SUMMARY |
29db9190 DH |
292 | 00000001 I----- 39 perm 1f3f0000 0 0 keyring _uid_ses.0: 1/4 |
293 | 00000002 I----- 2 perm 1f3f0000 0 0 keyring _uid.0: empty | |
294 | 00000007 I----- 1 perm 1f3f0000 0 0 keyring _pid.1: empty | |
295 | 0000018d I----- 1 perm 1f3f0000 0 0 keyring _pid.412: empty | |
296 | 000004d2 I--Q-- 1 perm 1f3f0000 32 -1 keyring _uid.32: 1/4 | |
297 | 000004d3 I--Q-- 3 perm 1f3f0000 32 -1 keyring _uid_ses.32: empty | |
664cceb0 | 298 | 00000892 I--QU- 1 perm 1f000000 0 0 user metal:copper: 0 |
29db9190 DH |
299 | 00000893 I--Q-N 1 35s 1f3f0000 0 0 user metal:silver: 0 |
300 | 00000894 I--Q-- 1 10h 003f0000 0 0 user metal:gold: 0 | |
1da177e4 | 301 | |
b68101a1 | 302 | The flags are:: |
1da177e4 LT |
303 | |
304 | I Instantiated | |
305 | R Revoked | |
306 | D Dead | |
307 | Q Contributes to user's quota | |
5d3f083d | 308 | U Under construction by callback to userspace |
1da177e4 LT |
309 | N Negative key |
310 | ||
1da177e4 | 311 | |
b68101a1 | 312 | * /proc/key-users |
1da177e4 LT |
313 | |
314 | This file lists the tracking data for each user that has at least one key | |
b68101a1 | 315 | on the system. Such data includes quota information and statistics:: |
1da177e4 LT |
316 | |
317 | [root@andromeda root]# cat /proc/key-users | |
318 | 0: 46 45/45 1/100 13/10000 | |
319 | 29: 2 2/2 2/100 40/10000 | |
320 | 32: 2 2/2 2/100 40/10000 | |
321 | 38: 2 2/2 2/100 40/10000 | |
322 | ||
b68101a1 KC |
323 | The format of each line is:: |
324 | ||
1da177e4 LT |
325 | <UID>: User ID to which this applies |
326 | <usage> Structure refcount | |
327 | <inst>/<keys> Total number of keys and number instantiated | |
328 | <keys>/<max> Key count quota | |
329 | <bytes>/<max> Key size quota | |
330 | ||
331 | ||
0b77f5bf DH |
332 | Four new sysctl files have been added also for the purpose of controlling the |
333 | quota limits on keys: | |
334 | ||
b68101a1 | 335 | * /proc/sys/kernel/keys/root_maxkeys |
0b77f5bf DH |
336 | /proc/sys/kernel/keys/root_maxbytes |
337 | ||
338 | These files hold the maximum number of keys that root may have and the | |
339 | maximum total number of bytes of data that root may have stored in those | |
340 | keys. | |
341 | ||
b68101a1 | 342 | * /proc/sys/kernel/keys/maxkeys |
0b77f5bf DH |
343 | /proc/sys/kernel/keys/maxbytes |
344 | ||
345 | These files hold the maximum number of keys that each non-root user may | |
346 | have and the maximum total number of bytes of data that each of those | |
347 | users may have stored in their keys. | |
348 | ||
349 | Root may alter these by writing each new limit as a decimal number string to | |
350 | the appropriate file. | |
351 | ||
352 | ||
b68101a1 | 353 | Userspace System Call Interface |
1da177e4 LT |
354 | =============================== |
355 | ||
356 | Userspace can manipulate keys directly through three new syscalls: add_key, | |
357 | request_key and keyctl. The latter provides a number of functions for | |
358 | manipulating keys. | |
359 | ||
360 | When referring to a key directly, userspace programs should use the key's | |
361 | serial number (a positive 32-bit integer). However, there are some special | |
362 | values available for referring to special keys and keyrings that relate to the | |
b68101a1 | 363 | process making the call:: |
1da177e4 LT |
364 | |
365 | CONSTANT VALUE KEY REFERENCED | |
366 | ============================== ====== =========================== | |
367 | KEY_SPEC_THREAD_KEYRING -1 thread-specific keyring | |
368 | KEY_SPEC_PROCESS_KEYRING -2 process-specific keyring | |
369 | KEY_SPEC_SESSION_KEYRING -3 session-specific keyring | |
370 | KEY_SPEC_USER_KEYRING -4 UID-specific keyring | |
371 | KEY_SPEC_USER_SESSION_KEYRING -5 UID-session keyring | |
372 | KEY_SPEC_GROUP_KEYRING -6 GID-specific keyring | |
b5f545c8 DH |
373 | KEY_SPEC_REQKEY_AUTH_KEY -7 assumed request_key() |
374 | authorisation key | |
1da177e4 LT |
375 | |
376 | ||
377 | The main syscalls are: | |
378 | ||
b68101a1 KC |
379 | * Create a new key of given type, description and payload and add it to the |
380 | nominated keyring:: | |
1da177e4 LT |
381 | |
382 | key_serial_t add_key(const char *type, const char *desc, | |
383 | const void *payload, size_t plen, | |
384 | key_serial_t keyring); | |
385 | ||
386 | If a key of the same type and description as that proposed already exists | |
387 | in the keyring, this will try to update it with the given payload, or it | |
388 | will return error EEXIST if that function is not supported by the key | |
76d8aeab DH |
389 | type. The process must also have permission to write to the key to be able |
390 | to update it. The new key will have all user permissions granted and no | |
391 | group or third party permissions. | |
1da177e4 | 392 | |
76d8aeab DH |
393 | Otherwise, this will attempt to create a new key of the specified type and |
394 | description, and to instantiate it with the supplied payload and attach it | |
395 | to the keyring. In this case, an error will be generated if the process | |
396 | does not have permission to write to the keyring. | |
1da177e4 | 397 | |
d4f65b5d DH |
398 | If the key type supports it, if the description is NULL or an empty |
399 | string, the key type will try and generate a description from the content | |
400 | of the payload. | |
401 | ||
1da177e4 LT |
402 | The payload is optional, and the pointer can be NULL if not required by |
403 | the type. The payload is plen in size, and plen can be zero for an empty | |
404 | payload. | |
405 | ||
76d8aeab DH |
406 | A new keyring can be generated by setting type "keyring", the keyring name |
407 | as the description (or NULL) and setting the payload to NULL. | |
1da177e4 LT |
408 | |
409 | User defined keys can be created by specifying type "user". It is | |
410 | recommended that a user defined key's description by prefixed with a type | |
411 | ID and a colon, such as "krb5tgt:" for a Kerberos 5 ticket granting | |
412 | ticket. | |
413 | ||
414 | Any other type must have been registered with the kernel in advance by a | |
415 | kernel service such as a filesystem. | |
416 | ||
417 | The ID of the new or updated key is returned if successful. | |
418 | ||
419 | ||
b68101a1 KC |
420 | * Search the process's keyrings for a key, potentially calling out to |
421 | userspace to create it:: | |
1da177e4 LT |
422 | |
423 | key_serial_t request_key(const char *type, const char *description, | |
424 | const char *callout_info, | |
425 | key_serial_t dest_keyring); | |
426 | ||
427 | This function searches all the process's keyrings in the order thread, | |
428 | process, session for a matching key. This works very much like | |
429 | KEYCTL_SEARCH, including the optional attachment of the discovered key to | |
430 | a keyring. | |
431 | ||
432 | If a key cannot be found, and if callout_info is not NULL, then | |
433 | /sbin/request-key will be invoked in an attempt to obtain a key. The | |
434 | callout_info string will be passed as an argument to the program. | |
435 | ||
adf31eeb | 436 | See also Documentation/security/keys/request-key.rst. |
f1a9badc | 437 | |
1da177e4 LT |
438 | |
439 | The keyctl syscall functions are: | |
440 | ||
b68101a1 | 441 | * Map a special key ID to a real key ID for this process:: |
1da177e4 LT |
442 | |
443 | key_serial_t keyctl(KEYCTL_GET_KEYRING_ID, key_serial_t id, | |
444 | int create); | |
445 | ||
76d8aeab DH |
446 | The special key specified by "id" is looked up (with the key being created |
447 | if necessary) and the ID of the key or keyring thus found is returned if | |
448 | it exists. | |
1da177e4 LT |
449 | |
450 | If the key does not yet exist, the key will be created if "create" is | |
451 | non-zero; and the error ENOKEY will be returned if "create" is zero. | |
452 | ||
453 | ||
b68101a1 | 454 | * Replace the session keyring this process subscribes to with a new one:: |
1da177e4 LT |
455 | |
456 | key_serial_t keyctl(KEYCTL_JOIN_SESSION_KEYRING, const char *name); | |
457 | ||
458 | If name is NULL, an anonymous keyring is created attached to the process | |
459 | as its session keyring, displacing the old session keyring. | |
460 | ||
461 | If name is not NULL, if a keyring of that name exists, the process | |
462 | attempts to attach it as the session keyring, returning an error if that | |
463 | is not permitted; otherwise a new keyring of that name is created and | |
464 | attached as the session keyring. | |
465 | ||
466 | To attach to a named keyring, the keyring must have search permission for | |
467 | the process's ownership. | |
468 | ||
469 | The ID of the new session keyring is returned if successful. | |
470 | ||
471 | ||
b68101a1 | 472 | * Update the specified key:: |
1da177e4 LT |
473 | |
474 | long keyctl(KEYCTL_UPDATE, key_serial_t key, const void *payload, | |
475 | size_t plen); | |
476 | ||
477 | This will try to update the specified key with the given payload, or it | |
478 | will return error EOPNOTSUPP if that function is not supported by the key | |
76d8aeab DH |
479 | type. The process must also have permission to write to the key to be able |
480 | to update it. | |
1da177e4 LT |
481 | |
482 | The payload is of length plen, and may be absent or empty as for | |
483 | add_key(). | |
484 | ||
485 | ||
b68101a1 | 486 | * Revoke a key:: |
1da177e4 LT |
487 | |
488 | long keyctl(KEYCTL_REVOKE, key_serial_t key); | |
489 | ||
490 | This makes a key unavailable for further operations. Further attempts to | |
491 | use the key will be met with error EKEYREVOKED, and the key will no longer | |
492 | be findable. | |
493 | ||
494 | ||
b68101a1 | 495 | * Change the ownership of a key:: |
1da177e4 LT |
496 | |
497 | long keyctl(KEYCTL_CHOWN, key_serial_t key, uid_t uid, gid_t gid); | |
498 | ||
76d8aeab DH |
499 | This function permits a key's owner and group ID to be changed. Either one |
500 | of uid or gid can be set to -1 to suppress that change. | |
1da177e4 LT |
501 | |
502 | Only the superuser can change a key's owner to something other than the | |
503 | key's current owner. Similarly, only the superuser can change a key's | |
504 | group ID to something other than the calling process's group ID or one of | |
505 | its group list members. | |
506 | ||
507 | ||
b68101a1 | 508 | * Change the permissions mask on a key:: |
1da177e4 LT |
509 | |
510 | long keyctl(KEYCTL_SETPERM, key_serial_t key, key_perm_t perm); | |
511 | ||
512 | This function permits the owner of a key or the superuser to change the | |
513 | permissions mask on a key. | |
514 | ||
515 | Only bits the available bits are permitted; if any other bits are set, | |
516 | error EINVAL will be returned. | |
517 | ||
518 | ||
b68101a1 | 519 | * Describe a key:: |
1da177e4 LT |
520 | |
521 | long keyctl(KEYCTL_DESCRIBE, key_serial_t key, char *buffer, | |
522 | size_t buflen); | |
523 | ||
524 | This function returns a summary of the key's attributes (but not its | |
525 | payload data) as a string in the buffer provided. | |
526 | ||
527 | Unless there's an error, it always returns the amount of data it could | |
528 | produce, even if that's too big for the buffer, but it won't copy more | |
529 | than requested to userspace. If the buffer pointer is NULL then no copy | |
530 | will take place. | |
531 | ||
532 | A process must have view permission on the key for this function to be | |
533 | successful. | |
534 | ||
b68101a1 | 535 | If successful, a string is placed in the buffer in the following format:: |
1da177e4 LT |
536 | |
537 | <type>;<uid>;<gid>;<perm>;<description> | |
538 | ||
539 | Where type and description are strings, uid and gid are decimal, and perm | |
540 | is hexadecimal. A NUL character is included at the end of the string if | |
541 | the buffer is sufficiently big. | |
542 | ||
b68101a1 | 543 | This can be parsed with:: |
1da177e4 LT |
544 | |
545 | sscanf(buffer, "%[^;];%d;%d;%o;%s", type, &uid, &gid, &mode, desc); | |
546 | ||
547 | ||
b68101a1 | 548 | * Clear out a keyring:: |
1da177e4 LT |
549 | |
550 | long keyctl(KEYCTL_CLEAR, key_serial_t keyring); | |
551 | ||
552 | This function clears the list of keys attached to a keyring. The calling | |
553 | process must have write permission on the keyring, and it must be a | |
554 | keyring (or else error ENOTDIR will result). | |
555 | ||
700920eb DH |
556 | This function can also be used to clear special kernel keyrings if they |
557 | are appropriately marked if the user has CAP_SYS_ADMIN capability. The | |
558 | DNS resolver cache keyring is an example of this. | |
559 | ||
1da177e4 | 560 | |
b68101a1 | 561 | * Link a key into a keyring:: |
1da177e4 LT |
562 | |
563 | long keyctl(KEYCTL_LINK, key_serial_t keyring, key_serial_t key); | |
564 | ||
76d8aeab DH |
565 | This function creates a link from the keyring to the key. The process must |
566 | have write permission on the keyring and must have link permission on the | |
567 | key. | |
1da177e4 | 568 | |
76d8aeab DH |
569 | Should the keyring not be a keyring, error ENOTDIR will result; and if the |
570 | keyring is full, error ENFILE will result. | |
1da177e4 LT |
571 | |
572 | The link procedure checks the nesting of the keyrings, returning ELOOP if | |
017679c4 | 573 | it appears too deep or EDEADLK if the link would introduce a cycle. |
1da177e4 | 574 | |
cab8eb59 DH |
575 | Any links within the keyring to keys that match the new key in terms of |
576 | type and description will be discarded from the keyring as the new one is | |
577 | added. | |
578 | ||
1da177e4 | 579 | |
b68101a1 | 580 | * Unlink a key or keyring from another keyring:: |
1da177e4 LT |
581 | |
582 | long keyctl(KEYCTL_UNLINK, key_serial_t keyring, key_serial_t key); | |
583 | ||
584 | This function looks through the keyring for the first link to the | |
585 | specified key, and removes it if found. Subsequent links to that key are | |
586 | ignored. The process must have write permission on the keyring. | |
587 | ||
76d8aeab DH |
588 | If the keyring is not a keyring, error ENOTDIR will result; and if the key |
589 | is not present, error ENOENT will be the result. | |
1da177e4 LT |
590 | |
591 | ||
b68101a1 | 592 | * Search a keyring tree for a key:: |
1da177e4 LT |
593 | |
594 | key_serial_t keyctl(KEYCTL_SEARCH, key_serial_t keyring, | |
595 | const char *type, const char *description, | |
596 | key_serial_t dest_keyring); | |
597 | ||
76d8aeab DH |
598 | This searches the keyring tree headed by the specified keyring until a key |
599 | is found that matches the type and description criteria. Each keyring is | |
600 | checked for keys before recursion into its children occurs. | |
1da177e4 LT |
601 | |
602 | The process must have search permission on the top level keyring, or else | |
603 | error EACCES will result. Only keyrings that the process has search | |
604 | permission on will be recursed into, and only keys and keyrings for which | |
605 | a process has search permission can be matched. If the specified keyring | |
606 | is not a keyring, ENOTDIR will result. | |
607 | ||
608 | If the search succeeds, the function will attempt to link the found key | |
609 | into the destination keyring if one is supplied (non-zero ID). All the | |
610 | constraints applicable to KEYCTL_LINK apply in this case too. | |
611 | ||
612 | Error ENOKEY, EKEYREVOKED or EKEYEXPIRED will be returned if the search | |
613 | fails. On success, the resulting key ID will be returned. | |
614 | ||
615 | ||
b68101a1 | 616 | * Read the payload data from a key:: |
1da177e4 | 617 | |
f1a9badc DH |
618 | long keyctl(KEYCTL_READ, key_serial_t keyring, char *buffer, |
619 | size_t buflen); | |
1da177e4 LT |
620 | |
621 | This function attempts to read the payload data from the specified key | |
622 | into the buffer. The process must have read permission on the key to | |
623 | succeed. | |
624 | ||
625 | The returned data will be processed for presentation by the key type. For | |
626 | instance, a keyring will return an array of key_serial_t entries | |
627 | representing the IDs of all the keys to which it is subscribed. The user | |
628 | defined key type will return its data as is. If a key type does not | |
629 | implement this function, error EOPNOTSUPP will result. | |
630 | ||
be543dd6 EB |
631 | If the specified buffer is too small, then the size of the buffer required |
632 | will be returned. Note that in this case, the contents of the buffer may | |
633 | have been overwritten in some undefined way. | |
1da177e4 | 634 | |
be543dd6 EB |
635 | Otherwise, on success, the function will return the amount of data copied |
636 | into the buffer. | |
1da177e4 | 637 | |
b68101a1 | 638 | * Instantiate a partially constructed key:: |
1da177e4 | 639 | |
f1a9badc DH |
640 | long keyctl(KEYCTL_INSTANTIATE, key_serial_t key, |
641 | const void *payload, size_t plen, | |
642 | key_serial_t keyring); | |
ee009e4a DH |
643 | long keyctl(KEYCTL_INSTANTIATE_IOV, key_serial_t key, |
644 | const struct iovec *payload_iov, unsigned ioc, | |
645 | key_serial_t keyring); | |
1da177e4 LT |
646 | |
647 | If the kernel calls back to userspace to complete the instantiation of a | |
648 | key, userspace should use this call to supply data for the key before the | |
649 | invoked process returns, or else the key will be marked negative | |
650 | automatically. | |
651 | ||
652 | The process must have write access on the key to be able to instantiate | |
653 | it, and the key must be uninstantiated. | |
654 | ||
655 | If a keyring is specified (non-zero), the key will also be linked into | |
76d8aeab DH |
656 | that keyring, however all the constraints applying in KEYCTL_LINK apply in |
657 | this case too. | |
1da177e4 LT |
658 | |
659 | The payload and plen arguments describe the payload data as for add_key(). | |
660 | ||
ee009e4a DH |
661 | The payload_iov and ioc arguments describe the payload data in an iovec |
662 | array instead of a single buffer. | |
663 | ||
1da177e4 | 664 | |
b68101a1 | 665 | * Negatively instantiate a partially constructed key:: |
1da177e4 | 666 | |
f1a9badc DH |
667 | long keyctl(KEYCTL_NEGATE, key_serial_t key, |
668 | unsigned timeout, key_serial_t keyring); | |
fdd1b945 DH |
669 | long keyctl(KEYCTL_REJECT, key_serial_t key, |
670 | unsigned timeout, unsigned error, key_serial_t keyring); | |
1da177e4 LT |
671 | |
672 | If the kernel calls back to userspace to complete the instantiation of a | |
673 | key, userspace should use this call mark the key as negative before the | |
40e47125 | 674 | invoked process returns if it is unable to fulfill the request. |
1da177e4 LT |
675 | |
676 | The process must have write access on the key to be able to instantiate | |
677 | it, and the key must be uninstantiated. | |
678 | ||
679 | If a keyring is specified (non-zero), the key will also be linked into | |
76d8aeab DH |
680 | that keyring, however all the constraints applying in KEYCTL_LINK apply in |
681 | this case too. | |
1da177e4 | 682 | |
fdd1b945 DH |
683 | If the key is rejected, future searches for it will return the specified |
684 | error code until the rejected key expires. Negating the key is the same | |
685 | as rejecting the key with ENOKEY as the error code. | |
686 | ||
1da177e4 | 687 | |
b68101a1 | 688 | * Set the default request-key destination keyring:: |
3e30148c DH |
689 | |
690 | long keyctl(KEYCTL_SET_REQKEY_KEYRING, int reqkey_defl); | |
691 | ||
692 | This sets the default keyring to which implicitly requested keys will be | |
b68101a1 | 693 | attached for this thread. reqkey_defl should be one of these constants:: |
3e30148c DH |
694 | |
695 | CONSTANT VALUE NEW DEFAULT KEYRING | |
696 | ====================================== ====== ======================= | |
697 | KEY_REQKEY_DEFL_NO_CHANGE -1 No change | |
698 | KEY_REQKEY_DEFL_DEFAULT 0 Default[1] | |
699 | KEY_REQKEY_DEFL_THREAD_KEYRING 1 Thread keyring | |
700 | KEY_REQKEY_DEFL_PROCESS_KEYRING 2 Process keyring | |
701 | KEY_REQKEY_DEFL_SESSION_KEYRING 3 Session keyring | |
702 | KEY_REQKEY_DEFL_USER_KEYRING 4 User keyring | |
703 | KEY_REQKEY_DEFL_USER_SESSION_KEYRING 5 User session keyring | |
704 | KEY_REQKEY_DEFL_GROUP_KEYRING 6 Group keyring | |
705 | ||
706 | The old default will be returned if successful and error EINVAL will be | |
707 | returned if reqkey_defl is not one of the above values. | |
708 | ||
709 | The default keyring can be overridden by the keyring indicated to the | |
710 | request_key() system call. | |
711 | ||
712 | Note that this setting is inherited across fork/exec. | |
713 | ||
670e9f34 | 714 | [1] The default is: the thread keyring if there is one, otherwise |
3e30148c DH |
715 | the process keyring if there is one, otherwise the session keyring if |
716 | there is one, otherwise the user default session keyring. | |
717 | ||
718 | ||
b68101a1 | 719 | * Set the timeout on a key:: |
017679c4 DH |
720 | |
721 | long keyctl(KEYCTL_SET_TIMEOUT, key_serial_t key, unsigned timeout); | |
722 | ||
723 | This sets or clears the timeout on a key. The timeout can be 0 to clear | |
724 | the timeout or a number of seconds to set the expiry time that far into | |
725 | the future. | |
726 | ||
727 | The process must have attribute modification access on a key to set its | |
728 | timeout. Timeouts may not be set with this function on negative, revoked | |
729 | or expired keys. | |
730 | ||
731 | ||
b68101a1 | 732 | * Assume the authority granted to instantiate a key:: |
b5f545c8 DH |
733 | |
734 | long keyctl(KEYCTL_ASSUME_AUTHORITY, key_serial_t key); | |
735 | ||
736 | This assumes or divests the authority required to instantiate the | |
737 | specified key. Authority can only be assumed if the thread has the | |
738 | authorisation key associated with the specified key in its keyrings | |
739 | somewhere. | |
740 | ||
741 | Once authority is assumed, searches for keys will also search the | |
742 | requester's keyrings using the requester's security label, UID, GID and | |
743 | groups. | |
744 | ||
745 | If the requested authority is unavailable, error EPERM will be returned, | |
746 | likewise if the authority has been revoked because the target key is | |
747 | already instantiated. | |
748 | ||
749 | If the specified key is 0, then any assumed authority will be divested. | |
750 | ||
3f6dee9b | 751 | The assumed authoritative key is inherited across fork and exec. |
b5f545c8 DH |
752 | |
753 | ||
b68101a1 | 754 | * Get the LSM security context attached to a key:: |
70a5bb72 DH |
755 | |
756 | long keyctl(KEYCTL_GET_SECURITY, key_serial_t key, char *buffer, | |
757 | size_t buflen) | |
758 | ||
759 | This function returns a string that represents the LSM security context | |
760 | attached to a key in the buffer provided. | |
761 | ||
762 | Unless there's an error, it always returns the amount of data it could | |
763 | produce, even if that's too big for the buffer, but it won't copy more | |
764 | than requested to userspace. If the buffer pointer is NULL then no copy | |
765 | will take place. | |
766 | ||
767 | A NUL character is included at the end of the string if the buffer is | |
768 | sufficiently big. This is included in the returned count. If no LSM is | |
769 | in force then an empty string will be returned. | |
770 | ||
771 | A process must have view permission on the key for this function to be | |
772 | successful. | |
773 | ||
774 | ||
b68101a1 | 775 | * Install the calling process's session keyring on its parent:: |
ee18d64c DH |
776 | |
777 | long keyctl(KEYCTL_SESSION_TO_PARENT); | |
778 | ||
779 | This functions attempts to install the calling process's session keyring | |
780 | on to the calling process's parent, replacing the parent's current session | |
781 | keyring. | |
782 | ||
783 | The calling process must have the same ownership as its parent, the | |
784 | keyring must have the same ownership as the calling process, the calling | |
785 | process must have LINK permission on the keyring and the active LSM module | |
786 | mustn't deny permission, otherwise error EPERM will be returned. | |
787 | ||
788 | Error ENOMEM will be returned if there was insufficient memory to complete | |
789 | the operation, otherwise 0 will be returned to indicate success. | |
790 | ||
791 | The keyring will be replaced next time the parent process leaves the | |
792 | kernel and resumes executing userspace. | |
793 | ||
794 | ||
b68101a1 | 795 | * Invalidate a key:: |
fd75815f DH |
796 | |
797 | long keyctl(KEYCTL_INVALIDATE, key_serial_t key); | |
798 | ||
799 | This function marks a key as being invalidated and then wakes up the | |
800 | garbage collector. The garbage collector immediately removes invalidated | |
801 | keys from all keyrings and deletes the key when its reference count | |
802 | reaches zero. | |
803 | ||
804 | Keys that are marked invalidated become invisible to normal key operations | |
805 | immediately, though they are still visible in /proc/keys until deleted | |
806 | (they're marked with an 'i' flag). | |
807 | ||
808 | A process must have search permission on the key for this function to be | |
809 | successful. | |
810 | ||
b68101a1 | 811 | * Compute a Diffie-Hellman shared secret or public key:: |
ddbb4114 | 812 | |
b68101a1 KC |
813 | long keyctl(KEYCTL_DH_COMPUTE, struct keyctl_dh_params *params, |
814 | char *buffer, size_t buflen, struct keyctl_kdf_params *kdf); | |
ddbb4114 | 815 | |
b68101a1 | 816 | The params struct contains serial numbers for three keys:: |
ddbb4114 MM |
817 | |
818 | - The prime, p, known to both parties | |
819 | - The local private key | |
820 | - The base integer, which is either a shared generator or the | |
821 | remote public key | |
822 | ||
b68101a1 | 823 | The value computed is:: |
ddbb4114 MM |
824 | |
825 | result = base ^ private (mod prime) | |
826 | ||
827 | If the base is the shared generator, the result is the local | |
828 | public key. If the base is the remote public key, the result is | |
829 | the shared secret. | |
830 | ||
f1c316a3 | 831 | If the parameter kdf is NULL, the following applies: |
4693fc73 | 832 | |
f1c316a3 | 833 | - The buffer length must be at least the length of the prime, or zero. |
ddbb4114 | 834 | |
f1c316a3 SM |
835 | - If the buffer length is nonzero, the length of the result is |
836 | returned when it is successfully calculated and copied in to the | |
837 | buffer. When the buffer length is zero, the minimum required | |
838 | buffer length is returned. | |
839 | ||
840 | The kdf parameter allows the caller to apply a key derivation function | |
841 | (KDF) on the Diffie-Hellman computation where only the result | |
842 | of the KDF is returned to the caller. The KDF is characterized with | |
843 | struct keyctl_kdf_params as follows: | |
844 | ||
b68101a1 | 845 | - ``char *hashname`` specifies the NUL terminated string identifying |
f1c316a3 SM |
846 | the hash used from the kernel crypto API and applied for the KDF |
847 | operation. The KDF implemenation complies with SP800-56A as well | |
848 | as with SP800-108 (the counter KDF). | |
849 | ||
b68101a1 | 850 | - ``char *otherinfo`` specifies the OtherInfo data as documented in |
f1c316a3 SM |
851 | SP800-56A section 5.8.1.2. The length of the buffer is given with |
852 | otherinfolen. The format of OtherInfo is defined by the caller. | |
853 | The otherinfo pointer may be NULL if no OtherInfo shall be used. | |
ddbb4114 MM |
854 | |
855 | This function will return error EOPNOTSUPP if the key type is not | |
856 | supported, error ENOKEY if the key could not be found, or error | |
f1c316a3 SM |
857 | EACCES if the key is not readable by the caller. In addition, the |
858 | function will return EMSGSIZE when the parameter kdf is non-NULL | |
859 | and either the buffer length or the OtherInfo length exceeds the | |
860 | allowed length. | |
fd75815f | 861 | |
b68101a1 | 862 | * Restrict keyring linkage:: |
6563c91f | 863 | |
b68101a1 KC |
864 | long keyctl(KEYCTL_RESTRICT_KEYRING, key_serial_t keyring, |
865 | const char *type, const char *restriction); | |
6563c91f MM |
866 | |
867 | An existing keyring can restrict linkage of additional keys by evaluating | |
868 | the contents of the key according to a restriction scheme. | |
869 | ||
870 | "keyring" is the key ID for an existing keyring to apply a restriction | |
871 | to. It may be empty or may already have keys linked. Existing linked keys | |
872 | will remain in the keyring even if the new restriction would reject them. | |
873 | ||
874 | "type" is a registered key type. | |
875 | ||
876 | "restriction" is a string describing how key linkage is to be restricted. | |
877 | The format varies depending on the key type, and the string is passed to | |
878 | the lookup_restriction() function for the requested type. It may specify | |
879 | a method and relevant data for the restriction such as signature | |
880 | verification or constraints on key payload. If the requested key type is | |
881 | later unregistered, no keys may be added to the keyring after the key type | |
882 | is removed. | |
883 | ||
884 | To apply a keyring restriction the process must have Set Attribute | |
885 | permission and the keyring must not be previously restricted. | |
886 | ||
7228b66a MM |
887 | One application of restricted keyrings is to verify X.509 certificate |
888 | chains or individual certificate signatures using the asymmetric key type. | |
889 | See Documentation/crypto/asymmetric-keys.txt for specific restrictions | |
890 | applicable to the asymmetric key type. | |
891 | ||
892 | ||
b68101a1 | 893 | Kernel Services |
1da177e4 LT |
894 | =============== |
895 | ||
2fe0ae78 | 896 | The kernel services for key management are fairly simple to deal with. They can |
1da177e4 LT |
897 | be broken down into two areas: keys and key types. |
898 | ||
899 | Dealing with keys is fairly straightforward. Firstly, the kernel service | |
900 | registers its type, then it searches for a key of that type. It should retain | |
901 | the key as long as it has need of it, and then it should release it. For a | |
76d8aeab DH |
902 | filesystem or device file, a search would probably be performed during the open |
903 | call, and the key released upon close. How to deal with conflicting keys due to | |
904 | two different users opening the same file is left to the filesystem author to | |
905 | solve. | |
906 | ||
b68101a1 | 907 | To access the key manager, the following header must be #included:: |
76181c13 DH |
908 | |
909 | <linux/key.h> | |
910 | ||
911 | Specific key types should have a header file under include/keys/ that should be | |
b68101a1 | 912 | used to access that type. For keys of type "user", for example, that would be:: |
76181c13 DH |
913 | |
914 | <keys/user-type.h> | |
915 | ||
664cceb0 DH |
916 | Note that there are two different types of pointers to keys that may be |
917 | encountered: | |
918 | ||
b68101a1 | 919 | * struct key * |
664cceb0 DH |
920 | |
921 | This simply points to the key structure itself. Key structures will be at | |
922 | least four-byte aligned. | |
923 | ||
b68101a1 | 924 | * key_ref_t |
664cceb0 | 925 | |
b68101a1 | 926 | This is equivalent to a ``struct key *``, but the least significant bit is set |
664cceb0 DH |
927 | if the caller "possesses" the key. By "possession" it is meant that the |
928 | calling processes has a searchable link to the key from one of its | |
b68101a1 | 929 | keyrings. There are three functions for dealing with these:: |
664cceb0 | 930 | |
a5b4bd28 | 931 | key_ref_t make_key_ref(const struct key *key, bool possession); |
664cceb0 DH |
932 | |
933 | struct key *key_ref_to_ptr(const key_ref_t key_ref); | |
934 | ||
a5b4bd28 | 935 | bool is_key_possessed(const key_ref_t key_ref); |
664cceb0 DH |
936 | |
937 | The first function constructs a key reference from a key pointer and | |
a5b4bd28 | 938 | possession information (which must be true or false). |
664cceb0 DH |
939 | |
940 | The second function retrieves the key pointer from a reference and the | |
941 | third retrieves the possession flag. | |
942 | ||
76d8aeab DH |
943 | When accessing a key's payload contents, certain precautions must be taken to |
944 | prevent access vs modification races. See the section "Notes on accessing | |
945 | payload contents" for more information. | |
1da177e4 | 946 | |
b68101a1 | 947 | * To search for a key, call:: |
1da177e4 LT |
948 | |
949 | struct key *request_key(const struct key_type *type, | |
950 | const char *description, | |
4a38e122 | 951 | const char *callout_info); |
1da177e4 LT |
952 | |
953 | This is used to request a key or keyring with a description that matches | |
f93b3cc7 DH |
954 | the description specified according to the key type's match_preparse() |
955 | method. This permits approximate matching to occur. If callout_string is | |
956 | not NULL, then /sbin/request-key will be invoked in an attempt to obtain | |
957 | the key from userspace. In that case, callout_string will be passed as an | |
958 | argument to the program. | |
1da177e4 LT |
959 | |
960 | Should the function fail error ENOKEY, EKEYEXPIRED or EKEYREVOKED will be | |
961 | returned. | |
962 | ||
3e30148c DH |
963 | If successful, the key will have been attached to the default keyring for |
964 | implicitly obtained request-key keys, as set by KEYCTL_SET_REQKEY_KEYRING. | |
965 | ||
adf31eeb | 966 | See also Documentation/security/keys/request-key.rst. |
f1a9badc | 967 | |
1da177e4 | 968 | |
b68101a1 | 969 | * To search for a key, passing auxiliary data to the upcaller, call:: |
4e54f085 DH |
970 | |
971 | struct key *request_key_with_auxdata(const struct key_type *type, | |
972 | const char *description, | |
4a38e122 DH |
973 | const void *callout_info, |
974 | size_t callout_len, | |
4e54f085 DH |
975 | void *aux); |
976 | ||
977 | This is identical to request_key(), except that the auxiliary data is | |
4a38e122 DH |
978 | passed to the key_type->request_key() op if it exists, and the callout_info |
979 | is a blob of length callout_len, if given (the length may be 0). | |
4e54f085 DH |
980 | |
981 | ||
b68101a1 | 982 | * A key can be requested asynchronously by calling one of:: |
76181c13 DH |
983 | |
984 | struct key *request_key_async(const struct key_type *type, | |
985 | const char *description, | |
4a38e122 DH |
986 | const void *callout_info, |
987 | size_t callout_len); | |
76181c13 | 988 | |
b68101a1 | 989 | or:: |
76181c13 DH |
990 | |
991 | struct key *request_key_async_with_auxdata(const struct key_type *type, | |
992 | const char *description, | |
4a38e122 DH |
993 | const char *callout_info, |
994 | size_t callout_len, | |
76181c13 DH |
995 | void *aux); |
996 | ||
997 | which are asynchronous equivalents of request_key() and | |
998 | request_key_with_auxdata() respectively. | |
999 | ||
1000 | These two functions return with the key potentially still under | |
d9195881 | 1001 | construction. To wait for construction completion, the following should be |
b68101a1 | 1002 | called:: |
76181c13 DH |
1003 | |
1004 | int wait_for_key_construction(struct key *key, bool intr); | |
1005 | ||
1006 | The function will wait for the key to finish being constructed and then | |
1007 | invokes key_validate() to return an appropriate value to indicate the state | |
1008 | of the key (0 indicates the key is usable). | |
1009 | ||
1010 | If intr is true, then the wait can be interrupted by a signal, in which | |
1011 | case error ERESTARTSYS will be returned. | |
1012 | ||
1013 | ||
b68101a1 | 1014 | * When it is no longer required, the key should be released using:: |
1da177e4 LT |
1015 | |
1016 | void key_put(struct key *key); | |
1017 | ||
b68101a1 | 1018 | Or:: |
664cceb0 DH |
1019 | |
1020 | void key_ref_put(key_ref_t key_ref); | |
1021 | ||
1022 | These can be called from interrupt context. If CONFIG_KEYS is not set then | |
1da177e4 LT |
1023 | the argument will not be parsed. |
1024 | ||
1025 | ||
b68101a1 KC |
1026 | * Extra references can be made to a key by calling one of the following |
1027 | functions:: | |
1da177e4 | 1028 | |
ccc3e6d9 | 1029 | struct key *__key_get(struct key *key); |
1da177e4 LT |
1030 | struct key *key_get(struct key *key); |
1031 | ||
ccc3e6d9 DH |
1032 | Keys so references will need to be disposed of by calling key_put() when |
1033 | they've been finished with. The key pointer passed in will be returned. | |
1034 | ||
1035 | In the case of key_get(), if the pointer is NULL or CONFIG_KEYS is not set | |
1036 | then the key will not be dereferenced and no increment will take place. | |
1da177e4 LT |
1037 | |
1038 | ||
b68101a1 | 1039 | * A key's serial number can be obtained by calling:: |
1da177e4 LT |
1040 | |
1041 | key_serial_t key_serial(struct key *key); | |
1042 | ||
1043 | If key is NULL or if CONFIG_KEYS is not set then 0 will be returned (in the | |
1044 | latter case without parsing the argument). | |
1045 | ||
1046 | ||
b68101a1 | 1047 | * If a keyring was found in the search, this can be further searched by:: |
1da177e4 | 1048 | |
664cceb0 DH |
1049 | key_ref_t keyring_search(key_ref_t keyring_ref, |
1050 | const struct key_type *type, | |
1051 | const char *description) | |
1da177e4 LT |
1052 | |
1053 | This searches the keyring tree specified for a matching key. Error ENOKEY | |
664cceb0 DH |
1054 | is returned upon failure (use IS_ERR/PTR_ERR to determine). If successful, |
1055 | the returned key will need to be released. | |
1056 | ||
1057 | The possession attribute from the keyring reference is used to control | |
1058 | access through the permissions mask and is propagated to the returned key | |
1059 | reference pointer if successful. | |
1da177e4 LT |
1060 | |
1061 | ||
b68101a1 | 1062 | * A keyring can be created by:: |
f8aa23a5 DH |
1063 | |
1064 | struct key *keyring_alloc(const char *description, uid_t uid, gid_t gid, | |
1065 | const struct cred *cred, | |
1066 | key_perm_t perm, | |
2b6aa412 | 1067 | struct key_restriction *restrict_link, |
f8aa23a5 DH |
1068 | unsigned long flags, |
1069 | struct key *dest); | |
1070 | ||
1071 | This creates a keyring with the given attributes and returns it. If dest | |
1072 | is not NULL, the new keyring will be linked into the keyring to which it | |
1073 | points. No permission checks are made upon the destination keyring. | |
1074 | ||
1075 | Error EDQUOT can be returned if the keyring would overload the quota (pass | |
1076 | KEY_ALLOC_NOT_IN_QUOTA in flags if the keyring shouldn't be accounted | |
1077 | towards the user's quota). Error ENOMEM can also be returned. | |
1078 | ||
2b6aa412 MM |
1079 | If restrict_link is not NULL, it should point to a structure that contains |
1080 | the function that will be called each time an attempt is made to link a | |
1081 | key into the new keyring. The structure may also contain a key pointer | |
1082 | and an associated key type. The function is called to check whether a key | |
1083 | may be added into the keyring or not. The key type is used by the garbage | |
1084 | collector to clean up function or data pointers in this structure if the | |
1085 | given key type is unregistered. Callers of key_create_or_update() within | |
1086 | the kernel can pass KEY_ALLOC_BYPASS_RESTRICTION to suppress the check. | |
1087 | An example of using this is to manage rings of cryptographic keys that are | |
1088 | set up when the kernel boots where userspace is also permitted to add keys | |
1089 | - provided they can be verified by a key the kernel already has. | |
5ac7eace DH |
1090 | |
1091 | When called, the restriction function will be passed the keyring being | |
aaf66c88 MM |
1092 | added to, the key type, the payload of the key being added, and data to be |
1093 | used in the restriction check. Note that when a new key is being created, | |
1094 | this is called between payload preparsing and actual key creation. The | |
1095 | function should return 0 to allow the link or an error to reject it. | |
5ac7eace DH |
1096 | |
1097 | A convenience function, restrict_link_reject, exists to always return | |
1098 | -EPERM to in this case. | |
1099 | ||
f8aa23a5 | 1100 | |
b68101a1 | 1101 | * To check the validity of a key, this function can be called:: |
1da177e4 LT |
1102 | |
1103 | int validate_key(struct key *key); | |
1104 | ||
1105 | This checks that the key in question hasn't expired or and hasn't been | |
1106 | revoked. Should the key be invalid, error EKEYEXPIRED or EKEYREVOKED will | |
1107 | be returned. If the key is NULL or if CONFIG_KEYS is not set then 0 will be | |
1108 | returned (in the latter case without parsing the argument). | |
1109 | ||
1110 | ||
b68101a1 | 1111 | * To register a key type, the following function should be called:: |
1da177e4 LT |
1112 | |
1113 | int register_key_type(struct key_type *type); | |
1114 | ||
1115 | This will return error EEXIST if a type of the same name is already | |
1116 | present. | |
1117 | ||
1118 | ||
b68101a1 | 1119 | * To unregister a key type, call:: |
1da177e4 LT |
1120 | |
1121 | void unregister_key_type(struct key_type *type); | |
1122 | ||
1123 | ||
7eacbbd3 | 1124 | Under some circumstances, it may be desirable to deal with a bundle of keys. |
b68101a1 | 1125 | The facility provides access to the keyring type for managing such a bundle:: |
7318226e DH |
1126 | |
1127 | struct key_type key_type_keyring; | |
1128 | ||
1129 | This can be used with a function such as request_key() to find a specific | |
1130 | keyring in a process's keyrings. A keyring thus found can then be searched | |
1131 | with keyring_search(). Note that it is not possible to use request_key() to | |
1132 | search a specific keyring, so using keyrings in this way is of limited utility. | |
1133 | ||
1134 | ||
b68101a1 | 1135 | Notes On Accessing Payload Contents |
76d8aeab DH |
1136 | =================================== |
1137 | ||
146aa8b1 DH |
1138 | The simplest payload is just data stored in key->payload directly. In this |
1139 | case, there's no need to indulge in RCU or locking when accessing the payload. | |
76d8aeab | 1140 | |
146aa8b1 DH |
1141 | More complex payload contents must be allocated and pointers to them set in the |
1142 | key->payload.data[] array. One of the following ways must be selected to | |
1143 | access the data: | |
76d8aeab | 1144 | |
b68101a1 | 1145 | 1) Unmodifiable key type. |
76d8aeab DH |
1146 | |
1147 | If the key type does not have a modify method, then the key's payload can | |
1148 | be accessed without any form of locking, provided that it's known to be | |
1149 | instantiated (uninstantiated keys cannot be "found"). | |
1150 | ||
b68101a1 | 1151 | 2) The key's semaphore. |
76d8aeab DH |
1152 | |
1153 | The semaphore could be used to govern access to the payload and to control | |
1154 | the payload pointer. It must be write-locked for modifications and would | |
1155 | have to be read-locked for general access. The disadvantage of doing this | |
1156 | is that the accessor may be required to sleep. | |
1157 | ||
b68101a1 | 1158 | 3) RCU. |
76d8aeab DH |
1159 | |
1160 | RCU must be used when the semaphore isn't already held; if the semaphore | |
1161 | is held then the contents can't change under you unexpectedly as the | |
1162 | semaphore must still be used to serialise modifications to the key. The | |
1163 | key management code takes care of this for the key type. | |
1164 | ||
b68101a1 | 1165 | However, this means using:: |
76d8aeab DH |
1166 | |
1167 | rcu_read_lock() ... rcu_dereference() ... rcu_read_unlock() | |
1168 | ||
b68101a1 | 1169 | to read the pointer, and:: |
76d8aeab DH |
1170 | |
1171 | rcu_dereference() ... rcu_assign_pointer() ... call_rcu() | |
1172 | ||
1173 | to set the pointer and dispose of the old contents after a grace period. | |
1174 | Note that only the key type should ever modify a key's payload. | |
1175 | ||
1176 | Furthermore, an RCU controlled payload must hold a struct rcu_head for the | |
1177 | use of call_rcu() and, if the payload is of variable size, the length of | |
1178 | the payload. key->datalen cannot be relied upon to be consistent with the | |
1179 | payload just dereferenced if the key's semaphore is not held. | |
1180 | ||
146aa8b1 DH |
1181 | Note that key->payload.data[0] has a shadow that is marked for __rcu |
1182 | usage. This is called key->payload.rcu_data0. The following accessors | |
1183 | wrap the RCU calls to this element: | |
1184 | ||
b68101a1 | 1185 | a) Set or change the first payload pointer:: |
0837e49a DH |
1186 | |
1187 | rcu_assign_keypointer(struct key *key, void *data); | |
1188 | ||
b68101a1 | 1189 | b) Read the first payload pointer with the key semaphore held:: |
0837e49a DH |
1190 | |
1191 | [const] void *dereference_key_locked([const] struct key *key); | |
1192 | ||
1193 | Note that the return value will inherit its constness from the key | |
1194 | parameter. Static analysis will give an error if it things the lock | |
1195 | isn't held. | |
1196 | ||
b68101a1 | 1197 | c) Read the first payload pointer with the RCU read lock held:: |
0837e49a DH |
1198 | |
1199 | const void *dereference_key_rcu(const struct key *key); | |
146aa8b1 | 1200 | |
76d8aeab | 1201 | |
b68101a1 | 1202 | Defining a Key Type |
1da177e4 LT |
1203 | =================== |
1204 | ||
1205 | A kernel service may want to define its own key type. For instance, an AFS | |
1206 | filesystem might want to define a Kerberos 5 ticket key type. To do this, it | |
76181c13 DH |
1207 | author fills in a key_type struct and registers it with the system. |
1208 | ||
b68101a1 | 1209 | Source files that implement key types should include the following header file:: |
76181c13 DH |
1210 | |
1211 | <linux/key-type.h> | |
1da177e4 LT |
1212 | |
1213 | The structure has a number of fields, some of which are mandatory: | |
1214 | ||
b68101a1 | 1215 | * ``const char *name`` |
1da177e4 LT |
1216 | |
1217 | The name of the key type. This is used to translate a key type name | |
1218 | supplied by userspace into a pointer to the structure. | |
1219 | ||
1220 | ||
b68101a1 | 1221 | * ``size_t def_datalen`` |
1da177e4 LT |
1222 | |
1223 | This is optional - it supplies the default payload data length as | |
1224 | contributed to the quota. If the key type's payload is always or almost | |
1225 | always the same size, then this is a more efficient way to do things. | |
1226 | ||
1227 | The data length (and quota) on a particular key can always be changed | |
b68101a1 | 1228 | during instantiation or update by calling:: |
1da177e4 LT |
1229 | |
1230 | int key_payload_reserve(struct key *key, size_t datalen); | |
1231 | ||
76d8aeab DH |
1232 | With the revised data length. Error EDQUOT will be returned if this is not |
1233 | viable. | |
1da177e4 LT |
1234 | |
1235 | ||
b68101a1 | 1236 | * ``int (*vet_description)(const char *description);`` |
b9fffa38 DH |
1237 | |
1238 | This optional method is called to vet a key description. If the key type | |
1239 | doesn't approve of the key description, it may return an error, otherwise | |
1240 | it should return 0. | |
1241 | ||
1242 | ||
b68101a1 | 1243 | * ``int (*preparse)(struct key_preparsed_payload *prep);`` |
d4f65b5d DH |
1244 | |
1245 | This optional method permits the key type to attempt to parse payload | |
1246 | before a key is created (add key) or the key semaphore is taken (update or | |
b68101a1 | 1247 | instantiate key). The structure pointed to by prep looks like:: |
d4f65b5d DH |
1248 | |
1249 | struct key_preparsed_payload { | |
1250 | char *description; | |
146aa8b1 | 1251 | union key_payload payload; |
d4f65b5d DH |
1252 | const void *data; |
1253 | size_t datalen; | |
1254 | size_t quotalen; | |
7dfa0ca6 | 1255 | time_t expiry; |
d4f65b5d DH |
1256 | }; |
1257 | ||
1258 | Before calling the method, the caller will fill in data and datalen with | |
1259 | the payload blob parameters; quotalen will be filled in with the default | |
7dfa0ca6 DH |
1260 | quota size from the key type; expiry will be set to TIME_T_MAX and the |
1261 | rest will be cleared. | |
d4f65b5d DH |
1262 | |
1263 | If a description can be proposed from the payload contents, that should be | |
1264 | attached as a string to the description field. This will be used for the | |
1265 | key description if the caller of add_key() passes NULL or "". | |
1266 | ||
146aa8b1 DH |
1267 | The method can attach anything it likes to payload. This is merely passed |
1268 | along to the instantiate() or update() operations. If set, the expiry | |
1269 | time will be applied to the key if it is instantiated from this data. | |
d4f65b5d | 1270 | |
7dfa0ca6 | 1271 | The method should return 0 if successful or a negative error code |
d4f65b5d DH |
1272 | otherwise. |
1273 | ||
f93b3cc7 | 1274 | |
b68101a1 | 1275 | * ``void (*free_preparse)(struct key_preparsed_payload *prep);`` |
d4f65b5d DH |
1276 | |
1277 | This method is only required if the preparse() method is provided, | |
146aa8b1 DH |
1278 | otherwise it is unused. It cleans up anything attached to the description |
1279 | and payload fields of the key_preparsed_payload struct as filled in by the | |
1280 | preparse() method. It will always be called after preparse() returns | |
1281 | successfully, even if instantiate() or update() succeed. | |
d4f65b5d DH |
1282 | |
1283 | ||
b68101a1 | 1284 | * ``int (*instantiate)(struct key *key, struct key_preparsed_payload *prep);`` |
1da177e4 LT |
1285 | |
1286 | This method is called to attach a payload to a key during construction. | |
76d8aeab DH |
1287 | The payload attached need not bear any relation to the data passed to this |
1288 | function. | |
1da177e4 | 1289 | |
d4f65b5d DH |
1290 | The prep->data and prep->datalen fields will define the original payload |
1291 | blob. If preparse() was supplied then other fields may be filled in also. | |
1292 | ||
1da177e4 LT |
1293 | If the amount of data attached to the key differs from the size in |
1294 | keytype->def_datalen, then key_payload_reserve() should be called. | |
1295 | ||
1296 | This method does not have to lock the key in order to attach a payload. | |
1297 | The fact that KEY_FLAG_INSTANTIATED is not set in key->flags prevents | |
1298 | anything else from gaining access to the key. | |
1299 | ||
76d8aeab | 1300 | It is safe to sleep in this method. |
1da177e4 | 1301 | |
146aa8b1 DH |
1302 | generic_key_instantiate() is provided to simply copy the data from |
1303 | prep->payload.data[] to key->payload.data[], with RCU-safe assignment on | |
1304 | the first element. It will then clear prep->payload.data[] so that the | |
1305 | free_preparse method doesn't release the data. | |
1306 | ||
1da177e4 | 1307 | |
b68101a1 | 1308 | * ``int (*update)(struct key *key, const void *data, size_t datalen);`` |
1da177e4 | 1309 | |
76d8aeab DH |
1310 | If this type of key can be updated, then this method should be provided. |
1311 | It is called to update a key's payload from the blob of data provided. | |
1da177e4 | 1312 | |
d4f65b5d DH |
1313 | The prep->data and prep->datalen fields will define the original payload |
1314 | blob. If preparse() was supplied then other fields may be filled in also. | |
1315 | ||
1da177e4 | 1316 | key_payload_reserve() should be called if the data length might change |
76d8aeab DH |
1317 | before any changes are actually made. Note that if this succeeds, the type |
1318 | is committed to changing the key because it's already been altered, so all | |
1319 | memory allocation must be done first. | |
1320 | ||
1321 | The key will have its semaphore write-locked before this method is called, | |
1322 | but this only deters other writers; any changes to the key's payload must | |
1323 | be made under RCU conditions, and call_rcu() must be used to dispose of | |
1324 | the old payload. | |
1da177e4 | 1325 | |
76d8aeab DH |
1326 | key_payload_reserve() should be called before the changes are made, but |
1327 | after all allocations and other potentially failing function calls are | |
1328 | made. | |
1da177e4 | 1329 | |
76d8aeab | 1330 | It is safe to sleep in this method. |
1da177e4 LT |
1331 | |
1332 | ||
b68101a1 | 1333 | * ``int (*match_preparse)(struct key_match_data *match_data);`` |
f93b3cc7 DH |
1334 | |
1335 | This method is optional. It is called when a key search is about to be | |
b68101a1 | 1336 | performed. It is given the following structure:: |
f93b3cc7 DH |
1337 | |
1338 | struct key_match_data { | |
1339 | bool (*cmp)(const struct key *key, | |
1340 | const struct key_match_data *match_data); | |
1341 | const void *raw_data; | |
1342 | void *preparsed; | |
1343 | unsigned lookup_type; | |
1344 | }; | |
1345 | ||
1346 | On entry, raw_data will be pointing to the criteria to be used in matching | |
b68101a1 | 1347 | a key by the caller and should not be modified. ``(*cmp)()`` will be pointing |
f93b3cc7 DH |
1348 | to the default matcher function (which does an exact description match |
1349 | against raw_data) and lookup_type will be set to indicate a direct lookup. | |
1350 | ||
1351 | The following lookup_type values are available: | |
1352 | ||
b68101a1 | 1353 | * KEYRING_SEARCH_LOOKUP_DIRECT - A direct lookup hashes the type and |
f93b3cc7 DH |
1354 | description to narrow down the search to a small number of keys. |
1355 | ||
b68101a1 | 1356 | * KEYRING_SEARCH_LOOKUP_ITERATE - An iterative lookup walks all the |
f93b3cc7 DH |
1357 | keys in the keyring until one is matched. This must be used for any |
1358 | search that's not doing a simple direct match on the key description. | |
1359 | ||
1360 | The method may set cmp to point to a function of its choice that does some | |
1361 | other form of match, may set lookup_type to KEYRING_SEARCH_LOOKUP_ITERATE | |
b68101a1 KC |
1362 | and may attach something to the preparsed pointer for use by ``(*cmp)()``. |
1363 | ``(*cmp)()`` should return true if a key matches and false otherwise. | |
f93b3cc7 DH |
1364 | |
1365 | If preparsed is set, it may be necessary to use the match_free() method to | |
1366 | clean it up. | |
1367 | ||
1368 | The method should return 0 if successful or a negative error code | |
1369 | otherwise. | |
1370 | ||
b68101a1 | 1371 | It is permitted to sleep in this method, but ``(*cmp)()`` may not sleep as |
f93b3cc7 DH |
1372 | locks will be held over it. |
1373 | ||
1374 | If match_preparse() is not provided, keys of this type will be matched | |
1375 | exactly by their description. | |
1da177e4 | 1376 | |
1da177e4 | 1377 | |
b68101a1 | 1378 | * ``void (*match_free)(struct key_match_data *match_data);`` |
1da177e4 | 1379 | |
f93b3cc7 DH |
1380 | This method is optional. If given, it called to clean up |
1381 | match_data->preparsed after a successful call to match_preparse(). | |
1da177e4 LT |
1382 | |
1383 | ||
b68101a1 | 1384 | * ``void (*revoke)(struct key *key);`` |
04c567d9 DH |
1385 | |
1386 | This method is optional. It is called to discard part of the payload | |
1387 | data upon a key being revoked. The caller will have the key semaphore | |
1388 | write-locked. | |
1389 | ||
1390 | It is safe to sleep in this method, though care should be taken to avoid | |
1391 | a deadlock against the key semaphore. | |
1392 | ||
1393 | ||
b68101a1 | 1394 | * ``void (*destroy)(struct key *key);`` |
1da177e4 | 1395 | |
76d8aeab DH |
1396 | This method is optional. It is called to discard the payload data on a key |
1397 | when it is being destroyed. | |
1da177e4 | 1398 | |
76d8aeab DH |
1399 | This method does not need to lock the key to access the payload; it can |
1400 | consider the key as being inaccessible at this time. Note that the key's | |
1401 | type may have been changed before this function is called. | |
1da177e4 LT |
1402 | |
1403 | It is not safe to sleep in this method; the caller may hold spinlocks. | |
1404 | ||
1405 | ||
b68101a1 | 1406 | * ``void (*describe)(const struct key *key, struct seq_file *p);`` |
1da177e4 LT |
1407 | |
1408 | This method is optional. It is called during /proc/keys reading to | |
1409 | summarise a key's description and payload in text form. | |
1410 | ||
76d8aeab DH |
1411 | This method will be called with the RCU read lock held. rcu_dereference() |
1412 | should be used to read the payload pointer if the payload is to be | |
1413 | accessed. key->datalen cannot be trusted to stay consistent with the | |
1414 | contents of the payload. | |
1415 | ||
1416 | The description will not change, though the key's state may. | |
1417 | ||
1418 | It is not safe to sleep in this method; the RCU read lock is held by the | |
1419 | caller. | |
1da177e4 LT |
1420 | |
1421 | ||
b68101a1 | 1422 | * ``long (*read)(const struct key *key, char __user *buffer, size_t buflen);`` |
1da177e4 LT |
1423 | |
1424 | This method is optional. It is called by KEYCTL_READ to translate the | |
76d8aeab DH |
1425 | key's payload into something a blob of data for userspace to deal with. |
1426 | Ideally, the blob should be in the same format as that passed in to the | |
1427 | instantiate and update methods. | |
1da177e4 LT |
1428 | |
1429 | If successful, the blob size that could be produced should be returned | |
1430 | rather than the size copied. | |
1431 | ||
76d8aeab DH |
1432 | This method will be called with the key's semaphore read-locked. This will |
1433 | prevent the key's payload changing. It is not necessary to use RCU locking | |
1434 | when accessing the key's payload. It is safe to sleep in this method, such | |
1435 | as might happen when the userspace buffer is accessed. | |
1da177e4 LT |
1436 | |
1437 | ||
b68101a1 | 1438 | * ``int (*request_key)(struct key_construction *cons, const char *op, void *aux);`` |
4e54f085 | 1439 | |
76181c13 DH |
1440 | This method is optional. If provided, request_key() and friends will |
1441 | invoke this function rather than upcalling to /sbin/request-key to operate | |
1442 | upon a key of this type. | |
1443 | ||
1444 | The aux parameter is as passed to request_key_async_with_auxdata() and | |
1445 | similar or is NULL otherwise. Also passed are the construction record for | |
1446 | the key to be operated upon and the operation type (currently only | |
1447 | "create"). | |
1448 | ||
1449 | This method is permitted to return before the upcall is complete, but the | |
1450 | following function must be called under all circumstances to complete the | |
1451 | instantiation process, whether or not it succeeds, whether or not there's | |
b68101a1 | 1452 | an error:: |
76181c13 DH |
1453 | |
1454 | void complete_request_key(struct key_construction *cons, int error); | |
1455 | ||
1456 | The error parameter should be 0 on success, -ve on error. The | |
1457 | construction record is destroyed by this action and the authorisation key | |
1458 | will be revoked. If an error is indicated, the key under construction | |
1459 | will be negatively instantiated if it wasn't already instantiated. | |
1460 | ||
1461 | If this method returns an error, that error will be returned to the | |
1462 | caller of request_key*(). complete_request_key() must be called prior to | |
1463 | returning. | |
1464 | ||
1465 | The key under construction and the authorisation key can be found in the | |
1466 | key_construction struct pointed to by cons: | |
1467 | ||
b68101a1 | 1468 | * ``struct key *key;`` |
76181c13 DH |
1469 | |
1470 | The key under construction. | |
4e54f085 | 1471 | |
b68101a1 | 1472 | * ``struct key *authkey;`` |
4e54f085 | 1473 | |
76181c13 | 1474 | The authorisation key. |
4e54f085 DH |
1475 | |
1476 | ||
b68101a1 | 1477 | * ``struct key_restriction *(*lookup_restriction)(const char *params);`` |
efba797b MM |
1478 | |
1479 | This optional method is used to enable userspace configuration of keyring | |
1480 | restrictions. The restriction parameter string (not including the key type | |
1481 | name) is passed in, and this method returns a pointer to a key_restriction | |
1482 | structure containing the relevant functions and data to evaluate each | |
1483 | attempted key link operation. If there is no match, -EINVAL is returned. | |
1484 | ||
1485 | ||
b68101a1 | 1486 | Request-Key Callback Service |
1da177e4 LT |
1487 | ============================ |
1488 | ||
1489 | To create a new key, the kernel will attempt to execute the following command | |
b68101a1 | 1490 | line:: |
1da177e4 LT |
1491 | |
1492 | /sbin/request-key create <key> <uid> <gid> \ | |
1493 | <threadring> <processring> <sessionring> <callout_info> | |
1494 | ||
1495 | <key> is the key being constructed, and the three keyrings are the process | |
1496 | keyrings from the process that caused the search to be issued. These are | |
1497 | included for two reasons: | |
1498 | ||
b68101a1 | 1499 | 1 There may be an authentication token in one of the keyrings that is |
1da177e4 LT |
1500 | required to obtain the key, eg: a Kerberos Ticket-Granting Ticket. |
1501 | ||
b68101a1 | 1502 | 2 The new key should probably be cached in one of these rings. |
1da177e4 LT |
1503 | |
1504 | This program should set it UID and GID to those specified before attempting to | |
1505 | access any more keys. It may then look around for a user specific process to | |
1506 | hand the request off to (perhaps a path held in placed in another key by, for | |
1507 | example, the KDE desktop manager). | |
1508 | ||
1509 | The program (or whatever it calls) should finish construction of the key by | |
ee009e4a DH |
1510 | calling KEYCTL_INSTANTIATE or KEYCTL_INSTANTIATE_IOV, which also permits it to |
1511 | cache the key in one of the keyrings (probably the session ring) before | |
1512 | returning. Alternatively, the key can be marked as negative with KEYCTL_NEGATE | |
1513 | or KEYCTL_REJECT; this also permits the key to be cached in one of the | |
1514 | keyrings. | |
1da177e4 LT |
1515 | |
1516 | If it returns with the key remaining in the unconstructed state, the key will | |
1517 | be marked as being negative, it will be added to the session keyring, and an | |
1518 | error will be returned to the key requestor. | |
1519 | ||
76d8aeab DH |
1520 | Supplementary information may be provided from whoever or whatever invoked this |
1521 | service. This will be passed as the <callout_info> parameter. If no such | |
1da177e4 LT |
1522 | information was made available, then "-" will be passed as this parameter |
1523 | instead. | |
1524 | ||
1525 | ||
1526 | Similarly, the kernel may attempt to update an expired or a soon to expire key | |
b68101a1 | 1527 | by executing:: |
1da177e4 LT |
1528 | |
1529 | /sbin/request-key update <key> <uid> <gid> \ | |
1530 | <threadring> <processring> <sessionring> | |
1531 | ||
1532 | In this case, the program isn't required to actually attach the key to a ring; | |
1533 | the rings are provided for reference. | |
5d135440 DH |
1534 | |
1535 | ||
b68101a1 | 1536 | Garbage Collection |
5d135440 DH |
1537 | ================== |
1538 | ||
1539 | Dead keys (for which the type has been removed) will be automatically unlinked | |
1540 | from those keyrings that point to them and deleted as soon as possible by a | |
1541 | background garbage collector. | |
1542 | ||
1543 | Similarly, revoked and expired keys will be garbage collected, but only after a | |
b68101a1 | 1544 | certain amount of time has passed. This time is set as a number of seconds in:: |
5d135440 DH |
1545 | |
1546 | /proc/sys/kernel/keys/gc_delay |