1KEYCTL(2) Linux Key Management Calls KEYCTL(2)
2
6 keyctl - manipulate the kernel's key management facility
7
9 #include <linux/keyctl.h> /* Definition of KEY* constants */
10 #include <sys/syscall.h> /* Definition of SYS_* constants */
11 #include <unistd.h>
12 long syscall(SYS_keyctl, int operation, unsigned long arg2,
14 unsigned long arg3, unsigned long arg4,
15 unsigned long arg5);
16 Note: glibc provides no wrapper for keyctl(), necessitating the use of
18 syscall(2).
19
21 keyctl() allows user-space programs to perform key manipulation.
22 The operation performed by keyctl() is determined by the value of the
24 operation argument. Each of these operations is wrapped by the
25 libkeyutils library (provided by the keyutils package) into individual
26 functions (noted below) to permit the compiler to check types.
27 The permitted values for operation are:
29 KEYCTL_GET_KEYRING_ID (since Linux 2.6.10)
31 Map a special key ID to a real key ID for this process.
32 This operation looks up the special key whose ID is provided in
34 arg2 (cast to key_serial_t). If the special key is found, the
35 ID of the corresponding real key is returned as the function re‐
36 sult. The following values may be specified in arg2:
37 KEY_SPEC_THREAD_KEYRING
39 This specifies the calling thread's thread-specific
40 keyring. See thread-keyring(7).
41 KEY_SPEC_PROCESS_KEYRING
43 This specifies the caller's process-specific keyring.
44 See process-keyring(7).
45 KEY_SPEC_SESSION_KEYRING
47 This specifies the caller's session-specific keyring.
48 See session-keyring(7).
49 KEY_SPEC_USER_KEYRING
51 This specifies the caller's UID-specific keyring. See
52 user-keyring(7).
53 KEY_SPEC_USER_SESSION_KEYRING
55 This specifies the caller's UID-session keyring. See
56 user-session-keyring(7).
57 KEY_SPEC_REQKEY_AUTH_KEY (since Linux 2.6.16)
59 This specifies the authorization key created by re‐
60 quest_key(2) and passed to the process it spawns to gen‐
61 erate a key. This key is available only in a re‐
62 quest-key(8)-style program that was passed an authoriza‐
63 tion key by the kernel and ceases to be available once
64 the requested key has been instantiated; see re‐
65 quest_key(2).
66 KEY_SPEC_REQUESTOR_KEYRING (since Linux 2.6.29)
68 This specifies the key ID for the request_key(2) destina‐
69 tion keyring. This keyring is available only in a re‐
70 quest-key(8)-style program that was passed an authoriza‐
71 tion key by the kernel and ceases to be available once
72 the requested key has been instantiated; see re‐
73 quest_key(2).
74 The behavior if the key specified in arg2 does not exist depends
76 on the value of arg3 (cast to int). If arg3 contains a nonzero
77 value, then—if it is appropriate to do so (e.g., when looking up
78 the user, user-session, or session key)—a new key is created and
79 its real key ID returned as the function result. Otherwise, the
80 operation fails with the error ENOKEY.
81 If a valid key ID is specified in arg2, and the key exists, then
83 this operation simply returns the key ID. If the key does not
84 exist, the call fails with error ENOKEY.
85 The caller must have search permission on a keyring in order for
87 it to be found.
88 The arguments arg4 and arg5 are ignored.
90 This operation is exposed by libkeyutils via the function
92 keyctl_get_keyring_ID(3).
93 KEYCTL_JOIN_SESSION_KEYRING (since Linux 2.6.10)
95 Replace the session keyring this process subscribes to with a
96 new session keyring.
97 If arg2 is NULL, an anonymous keyring with the description
99 "_ses" is created and the process is subscribed to that keyring
100 as its session keyring, displacing the previous session keyring.
101 Otherwise, arg2 (cast to char *) is treated as the description
103 (name) of a keyring, and the behavior is as follows:
104 * If a keyring with a matching description exists, the process
106 will attempt to subscribe to that keyring as its session
107 keyring if possible; if that is not possible, an error is re‐
108 turned. In order to subscribe to the keyring, the caller
109 must have search permission on the keyring.
110 * If a keyring with a matching description does not exist, then
112 a new keyring with the specified description is created, and
113 the process is subscribed to that keyring as its session
114 keyring.
115 The arguments arg3, arg4, and arg5 are ignored.
117 This operation is exposed by libkeyutils via the function
119 keyctl_join_session_keyring(3).
120 KEYCTL_UPDATE (since Linux 2.6.10)
122 Update a key's data payload.
123 The arg2 argument (cast to key_serial_t) specifies the ID of the
125 key to be updated. The arg3 argument (cast to void *) points to
126 the new payload and arg4 (cast to size_t) contains the new pay‐
127 load size in bytes.
128 The caller must have write permission on the key specified and
130 the key type must support updating.
131 A negatively instantiated key (see the description of KEYCTL_RE‐
133 JECT) can be positively instantiated with this operation.
134 The arg5 argument is ignored.
136 This operation is exposed by libkeyutils via the function
138 keyctl_update(3).
139 KEYCTL_REVOKE (since Linux 2.6.10)
141 Revoke the key with the ID provided in arg2 (cast to key_se‐
142 rial_t). The key is scheduled for garbage collection; it will
143 no longer be findable, and will be unavailable for further oper‐
144 ations. Further attempts to use the key will fail with the er‐
145 ror EKEYREVOKED.
146 The caller must have write or setattr permission on the key.
148 The arguments arg3, arg4, and arg5 are ignored.
150 This operation is exposed by libkeyutils via the function
152 keyctl_revoke(3).
153 KEYCTL_CHOWN (since Linux 2.6.10)
155 Change the ownership (user and group ID) of a key.
156 The arg2 argument (cast to key_serial_t) contains the key ID.
158 The arg3 argument (cast to uid_t) contains the new user ID (or
159 -1 in case the user ID shouldn't be changed). The arg4 argument
160 (cast to gid_t) contains the new group ID (or -1 in case the
161 group ID shouldn't be changed).
162 The key must grant the caller setattr permission.
164 For the UID to be changed, or for the GID to be changed to a
166 group the caller is not a member of, the caller must have the
167 CAP_SYS_ADMIN capability (see capabilities(7)).
168 If the UID is to be changed, the new user must have sufficient
170 quota to accept the key. The quota deduction will be removed
171 from the old user to the new user should the UID be changed.
172 The arg5 argument is ignored.
174 This operation is exposed by libkeyutils via the function
176 keyctl_chown(3).
177 KEYCTL_SETPERM (since Linux 2.6.10)
179 Change the permissions of the key with the ID provided in the
180 arg2 argument (cast to key_serial_t) to the permissions provided
181 in the arg3 argument (cast to key_perm_t).
182 If the caller doesn't have the CAP_SYS_ADMIN capability, it can
184 change permissions only for the keys it owns. (More precisely:
185 the caller's filesystem UID must match the UID of the key.)
186 The key must grant setattr permission to the caller regardless
188 of the caller's capabilities.
189 The permissions in arg3 specify masks of available operations
191 for each of the following user categories:
192 possessor (since Linux 2.6.14)
194 This is the permission granted to a process that pos‐
195 sesses the key (has it attached searchably to one of the
196 process's keyrings); see keyrings(7).
197 user This is the permission granted to a process whose
199 filesystem UID matches the UID of the key.
200 group This is the permission granted to a process whose
202 filesystem GID or any of its supplementary GIDs matches
203 the GID of the key.
204 other This is the permission granted to other processes that do
206 not match the user and group categories.
207 The user, group, and other categories are exclusive: if a
209 process matches the user category, it will not receive permis‐
210 sions granted in the group category; if a process matches the
211 user or group category, then it will not receive permissions
212 granted in the other category.
213 The possessor category grants permissions that are cumulative
215 with the grants from the user, group, or other category.
216 Each permission mask is eight bits in size, with only six bits
218 currently used. The available permissions are:
219 view This permission allows reading attributes of a key.
221 This permission is required for the KEYCTL_DESCRIBE oper‐
223 ation.
224 The permission bits for each category are KEY_POS_VIEW,
226 KEY_USR_VIEW, KEY_GRP_VIEW, and KEY_OTH_VIEW.
227 read This permission allows reading a key's payload.
229 This permission is required for the KEYCTL_READ opera‐
231 tion.
232 The permission bits for each category are KEY_POS_READ,
234 KEY_USR_READ, KEY_GRP_READ, and KEY_OTH_READ.
235 write This permission allows update or instantiation of a key's
237 payload. For a keyring, it allows keys to be linked and
238 unlinked from the keyring,
239 This permission is required for the KEYCTL_UPDATE,
241 KEYCTL_REVOKE, KEYCTL_CLEAR, KEYCTL_LINK, and KEYCTL_UN‐
242 LINK operations.
243 The permission bits for each category are KEY_POS_WRITE,
245 KEY_USR_WRITE, KEY_GRP_WRITE, and KEY_OTH_WRITE.
246 search This permission allows keyrings to be searched and keys
248 to be found. Searches can recurse only into nested
249 keyrings that have search permission set.
250 This permission is required for the
252 KEYCTL_GET_KEYRING_ID, KEYCTL_JOIN_SESSION_KEYRING,
253 KEYCTL_SEARCH, and KEYCTL_INVALIDATE operations.
254 The permission bits for each category are KEY_POS_SEARCH,
256 KEY_USR_SEARCH, KEY_GRP_SEARCH, and KEY_OTH_SEARCH.
257 link This permission allows a key or keyring to be linked to.
259 This permission is required for the KEYCTL_LINK and
261 KEYCTL_SESSION_TO_PARENT operations.
262 The permission bits for each category are KEY_POS_LINK,
264 KEY_USR_LINK, KEY_GRP_LINK, and KEY_OTH_LINK.
265 setattr (since Linux 2.6.15).
267 This permission allows a key's UID, GID, and permissions
268 mask to be changed.
269 This permission is required for the KEYCTL_REVOKE,
271 KEYCTL_CHOWN, and KEYCTL_SETPERM operations.
272 The permission bits for each category are KEY_POS_SE‐
274 TATTR, KEY_USR_SETATTR, KEY_GRP_SETATTR, and KEY_OTH_SE‐
275 TATTR.
276 As a convenience, the following macros are defined as masks for
278 all of the permission bits in each of the user categories:
279 KEY_POS_ALL, KEY_USR_ALL, KEY_GRP_ALL, and KEY_OTH_ALL.
280 The arg4 and arg5 arguments are ignored.
282 This operation is exposed by libkeyutils via the function
284 keyctl_setperm(3).
285 KEYCTL_DESCRIBE (since Linux 2.6.10)
287 Obtain a string describing the attributes of a specified key.
288 The ID of the key to be described is specified in arg2 (cast to
290 key_serial_t). The descriptive string is returned in the buffer
291 pointed to by arg3 (cast to char *); arg4 (cast to size_t) spec‐
292 ifies the size of that buffer in bytes.
293 The key must grant the caller view permission.
295 The returned string is null-terminated and contains the follow‐
297 ing information about the key:
298 type;uid;gid;perm;description
300 In the above, type and description are strings, uid and gid are
302 decimal strings, and perm is a hexadecimal permissions mask.
303 The descriptive string is written with the following format:
304 %s;%d;%d;%08x;%s
306 Note: the intention is that the descriptive string should be ex‐
308 tensible in future kernel versions. In particular, the descrip‐
309 tion field will not contain semicolons; it should be parsed by
310 working backwards from the end of the string to find the last
311 semicolon. This allows future semicolon-delimited fields to be
312 inserted in the descriptive string in the future.
313 Writing to the buffer is attempted only when arg3 is non-NULL
315 and the specified buffer size is large enough to accept the de‐
316 scriptive string (including the terminating null byte). In or‐
317 der to determine whether the buffer size was too small, check to
318 see if the return value of the operation is greater than arg4.
319 The arg5 argument is ignored.
321 This operation is exposed by libkeyutils via the function
323 keyctl_describe(3).
324 KEYCTL_CLEAR
326 Clear the contents of (i.e., unlink all keys from) a keyring.
327 The ID of the key (which must be of keyring type) is provided in
329 arg2 (cast to key_serial_t).
330 The caller must have write permission on the keyring.
332 The arguments arg3, arg4, and arg5 are ignored.
334 This operation is exposed by libkeyutils via the function
336 keyctl_clear(3).
337 KEYCTL_LINK (since Linux 2.6.10)
339 Create a link from a keyring to a key.
340 The key to be linked is specified in arg2 (cast to key_se‐
342 rial_t); the keyring is specified in arg3 (cast to key_se‐
343 rial_t).
344 If a key with the same type and description is already linked in
346 the keyring, then that key is displaced from the keyring.
347 Before creating the link, the kernel checks the nesting of the
349 keyrings and returns appropriate errors if the link would pro‐
350 duce a cycle or if the nesting of keyrings would be too deep
351 (The limit on the nesting of keyrings is determined by the ker‐
352 nel constant KEYRING_SEARCH_MAX_DEPTH, defined with the value 6,
353 and is necessary to prevent overflows on the kernel stack when
354 recursively searching keyrings).
355 The caller must have link permission on the key being added and
357 write permission on the keyring.
358 The arguments arg4 and arg5 are ignored.
360 This operation is exposed by libkeyutils via the function
362 keyctl_link(3).
363 KEYCTL_UNLINK (since Linux 2.6.10)
365 Unlink a key from a keyring.
366 The ID of the key to be unlinked is specified in arg2 (cast to
368 key_serial_t); the ID of the keyring from which it is to be un‐
369 linked is specified in arg3 (cast to key_serial_t).
370 If the key is not currently linked into the keyring, an error
372 results.
373 The caller must have write permission on the keyring from which
375 the key is being removed.
376 If the last link to a key is removed, then that key will be
378 scheduled for destruction.
379 The arguments arg4 and arg5 are ignored.
381 This operation is exposed by libkeyutils via the function
383 keyctl_unlink(3).
384 KEYCTL_SEARCH (since Linux 2.6.10)
386 Search for a key in a keyring tree, returning its ID and option‐
387 ally linking it to a specified keyring.
388 The tree to be searched is specified by passing the ID of the
390 head keyring in arg2 (cast to key_serial_t). The search is per‐
391 formed breadth-first and recursively.
392 The arg3 and arg4 arguments specify the key to be searched for:
394 arg3 (cast as char *) contains the key type (a null-terminated
395 character string up to 32 bytes in size, including the terminat‐
396 ing null byte), and arg4 (cast as char *) contains the descrip‐
397 tion of the key (a null-terminated character string up to 4096
398 bytes in size, including the terminating null byte).
399 The source keyring must grant search permission to the caller.
401 When performing the recursive search, only keyrings that grant
402 the caller search permission will be searched. Only keys with
403 for which the caller has search permission can be found.
404 If the key is found, its ID is returned as the function result.
406 If the key is found and arg5 (cast to key_serial_t) is nonzero,
408 then, subject to the same constraints and rules as KEYCTL_LINK,
409 the key is linked into the keyring whose ID is specified in
410 arg5. If the destination keyring specified in arg5 already con‐
411 tains a link to a key that has the same type and description,
412 then that link will be displaced by a link to the key found by
413 this operation.
414 Instead of valid existing keyring IDs, the source (arg2) and
416 destination (arg5) keyrings can be one of the special keyring
417 IDs listed under KEYCTL_GET_KEYRING_ID.
418 This operation is exposed by libkeyutils via the function
420 keyctl_search(3).
421 KEYCTL_READ (since Linux 2.6.10)
423 Read the payload data of a key.
424 The ID of the key whose payload is to be read is specified in
426 arg2 (cast to key_serial_t). This can be the ID of an existing
427 key, or any of the special key IDs listed for
428 KEYCTL_GET_KEYRING_ID.
429 The payload is placed in the buffer pointed by arg3 (cast to
431 char *); the size of that buffer must be specified in arg4 (cast
432 to size_t).
433 The returned data will be processed for presentation according
435 to the key type. For example, a keyring will return an array of
436 key_serial_t entries representing the IDs of all the keys that
437 are linked to it. The user key type will return its data as is.
438 If a key type does not implement this function, the operation
439 fails with the error EOPNOTSUPP.
440 If arg3 is not NULL, as much of the payload data as will fit is
442 copied into the buffer. On a successful return, the return
443 value is always the total size of the payload data. To deter‐
444 mine whether the buffer was of sufficient size, check to see
445 that the return value is less than or equal to the value sup‐
446 plied in arg4.
447 The key must either grant the caller read permission, or grant
449 the caller search permission when searched for from the process
450 keyrings (i.e., the key is possessed).
451 The arg5 argument is ignored.
453 This operation is exposed by libkeyutils via the function
455 keyctl_read(3).
456 KEYCTL_INSTANTIATE (since Linux 2.6.10)
458 (Positively) instantiate an uninstantiated key with a specified
459 payload.
460 The ID of the key to be instantiated is provided in arg2 (cast
462 to key_serial_t).
463 The key payload is specified in the buffer pointed to by arg3
465 (cast to void *); the size of that buffer is specified in arg4
466 (cast to size_t).
467 The payload may be a NULL pointer and the buffer size may be 0
469 if this is supported by the key type (e.g., it is a keyring).
470 The operation may be fail if the payload data is in the wrong
472 format or is otherwise invalid.
473 If arg5 (cast to key_serial_t) is nonzero, then, subject to the
475 same constraints and rules as KEYCTL_LINK, the instantiated key
476 is linked into the keyring whose ID specified in arg5.
477 The caller must have the appropriate authorization key, and once
479 the uninstantiated key has been instantiated, the authorization
480 key is revoked. In other words, this operation is available
481 only from a request-key(8)-style program. See request_key(2)
482 for an explanation of uninstantiated keys and key instantiation.
483 This operation is exposed by libkeyutils via the function
485 keyctl_instantiate(3).
486 KEYCTL_NEGATE (since Linux 2.6.10)
488 Negatively instantiate an uninstantiated key.
489 This operation is equivalent to the call:
491 keyctl(KEYCTL_REJECT, arg2, arg3, ENOKEY, arg4);
493 The arg5 argument is ignored.
495 This operation is exposed by libkeyutils via the function
497 keyctl_negate(3).
498 KEYCTL_SET_REQKEY_KEYRING (since Linux 2.6.13)
500 Set the default keyring to which implicitly requested keys will
501 be linked for this thread, and return the previous setting. Im‐
502 plicit key requests are those made by internal kernel compo‐
503 nents, such as can occur when, for example, opening files on an
504 AFS or NFS filesystem. Setting the default keyring also has an
505 effect when requesting a key from user space; see request_key(2)
506 for details.
507 The arg2 argument (cast to int) should contain one of the fol‐
509 lowing values, to specify the new default keyring:
510 KEY_REQKEY_DEFL_NO_CHANGE
512 Don't change the default keyring. This can be used to
513 discover the current default keyring (without changing
514 it).
515 KEY_REQKEY_DEFL_DEFAULT
517 This selects the default behaviour, which is to use the
518 thread-specific keyring if there is one, otherwise the
519 process-specific keyring if there is one, otherwise the
520 session keyring if there is one, otherwise the UID-spe‐
521 cific session keyring, otherwise the user-specific
522 keyring.
523 KEY_REQKEY_DEFL_THREAD_KEYRING
525 Use the thread-specific keyring (thread-keyring(7)) as
526 the new default keyring.
527 KEY_REQKEY_DEFL_PROCESS_KEYRING
529 Use the process-specific keyring (process-keyring(7)) as
530 the new default keyring.
531 KEY_REQKEY_DEFL_SESSION_KEYRING
533 Use the session-specific keyring (session-keyring(7)) as
534 the new default keyring.
535 KEY_REQKEY_DEFL_USER_KEYRING
537 Use the UID-specific keyring (user-keyring(7)) as the new
538 default keyring.
539 KEY_REQKEY_DEFL_USER_SESSION_KEYRING
541 Use the UID-specific session keyring (user-ses‐
542 sion-keyring(7)) as the new default keyring.
543 KEY_REQKEY_DEFL_REQUESTOR_KEYRING (since Linux 2.6.29)
545 Use the requestor keyring.
546 All other values are invalid.
548 The arguments arg3, arg4, and arg5 are ignored.
550 The setting controlled by this operation is inherited by the
552 child of fork(2) and preserved across execve(2).
553 This operation is exposed by libkeyutils via the function
555 keyctl_set_reqkey_keyring(3).
556 KEYCTL_SET_TIMEOUT (since Linux 2.6.16)
558 Set a timeout on a key.
559 The ID of the key is specified in arg2 (cast to key_serial_t).
561 The timeout value, in seconds from the current time, is speci‐
562 fied in arg3 (cast to unsigned int). The timeout is measured
563 against the realtime clock.
564 Specifying the timeout value as 0 clears any existing timeout on
566 the key.
567 The /proc/keys file displays the remaining time until each key
569 will expire. (This is the only method of discovering the time‐
570 out on a key.)
571 The caller must either have the setattr permission on the key or
573 hold an instantiation authorization token for the key (see re‐
574 quest_key(2)).
575 The key and any links to the key will be automatically garbage
577 collected after the timeout expires. Subsequent attempts to ac‐
578 cess the key will then fail with the error EKEYEXPIRED.
579 This operation cannot be used to set timeouts on revoked, ex‐
581 pired, or negatively instantiated keys.
582 The arguments arg4 and arg5 are ignored.
584 This operation is exposed by libkeyutils via the function
586 keyctl_set_timeout(3).
587 KEYCTL_ASSUME_AUTHORITY (since Linux 2.6.16)
589 Assume (or divest) the authority for the calling thread to in‐
590 stantiate a key.
591 The arg2 argument (cast to key_serial_t) specifies either a non‐
593 zero key ID to assume authority, or the value 0 to divest au‐
594 thority.
595 If arg2 is nonzero, then it specifies the ID of an uninstanti‐
597 ated key for which authority is to be assumed. That key can
598 then be instantiated using one of KEYCTL_INSTANTIATE, KEYCTL_IN‐
599 STANTIATE_IOV, KEYCTL_REJECT, or KEYCTL_NEGATE. Once the key
600 has been instantiated, the thread is automatically divested of
601 authority to instantiate the key.
602 Authority over a key can be assumed only if the calling thread
604 has present in its keyrings the authorization key that is asso‐
605 ciated with the specified key. (In other words, the KEYCTL_AS‐
606 SUME_AUTHORITY operation is available only from a re‐
607 quest-key(8)-style program; see request_key(2) for an explana‐
608 tion of how this operation is used.) The caller must have
609 search permission on the authorization key.
610 If the specified key has a matching authorization key, then the
612 ID of that key is returned. The authorization key can be read
613 (KEYCTL_READ) to obtain the callout information passed to re‐
614 quest_key(2).
615 If the ID given in arg2 is 0, then the currently assumed author‐
617 ity is cleared (divested), and the value 0 is returned.
618 The KEYCTL_ASSUME_AUTHORITY mechanism allows a program such as
620 request-key(8) to assume the necessary authority to instantiate
621 a new uninstantiated key that was created as a consequence of a
622 call to request_key(2). For further information, see re‐
623 quest_key(2) and the kernel source file Documentation/secu‐
624 rity/keys-request-key.txt.
625 The arguments arg3, arg4, and arg5 are ignored.
627 This operation is exposed by libkeyutils via the function
629 keyctl_assume_authority(3).
630 KEYCTL_GET_SECURITY (since Linux 2.6.26)
632 Get the LSM (Linux Security Module) security label of the speci‐
633 fied key.
634 The ID of the key whose security label is to be fetched is spec‐
636 ified in arg2 (cast to key_serial_t). The security label (ter‐
637 minated by a null byte) will be placed in the buffer pointed to
638 by arg3 argument (cast to char *); the size of the buffer must
639 be provided in arg4 (cast to size_t).
640 If arg3 is specified as NULL or the buffer size specified in
642 arg4 is too small, the full size of the security label string
643 (including the terminating null byte) is returned as the func‐
644 tion result, and nothing is copied to the buffer.
645 The caller must have view permission on the specified key.
647 The returned security label string will be rendered in a form
649 appropriate to the LSM in force. For example, with SELinux, it
650 may look like:
651 unconfined_u:unconfined_r:unconfined_t:s0-s0:c0.c1023
653 If no LSM is currently in force, then an empty string is placed
655 in the buffer.
656 The arg5 argument is ignored.
658 This operation is exposed by libkeyutils via the functions
660 keyctl_get_security(3) and keyctl_get_security_alloc(3).
661 KEYCTL_SESSION_TO_PARENT (since Linux 2.6.32)
663 Replace the session keyring to which the parent of the calling
664 process subscribes with the session keyring of the calling
665 process.
666 The keyring will be replaced in the parent process at the point
668 where the parent next transitions from kernel space to user
669 space.
670 The keyring must exist and must grant the caller link permis‐
672 sion. The parent process must be single-threaded and have the
673 same effective ownership as this process and must not be set-
674 user-ID or set-group-ID. The UID of the parent process's exist‐
675 ing session keyring (f it has one), as well as the UID of the
676 caller's session keyring much match the caller's effective UID.
677 The fact that it is the parent process that is affected by this
679 operation allows a program such as the shell to start a child
680 process that uses this operation to change the shell's session
681 keyring. (This is what the keyctl(1) new_session command does.)
682 The arguments arg2, arg3, arg4, and arg5 are ignored.
684 This operation is exposed by libkeyutils via the function
686 keyctl_session_to_parent(3).
687 KEYCTL_REJECT (since Linux 2.6.39)
689 Mark a key as negatively instantiated and set an expiration
690 timer on the key. This operation provides a superset of the
691 functionality of the earlier KEYCTL_NEGATE operation.
692 The ID of the key that is to be negatively instantiated is spec‐
694 ified in arg2 (cast to key_serial_t). The arg3 (cast to un‐
695 signed int) argument specifies the lifetime of the key, in sec‐
696 onds. The arg4 argument (cast to unsigned int) specifies the
697 error to be returned when a search hits this key; typically,
698 this is one of EKEYREJECTED, EKEYREVOKED, or EKEYEXPIRED.
699 If arg5 (cast to key_serial_t) is nonzero, then, subject to the
701 same constraints and rules as KEYCTL_LINK, the negatively in‐
702 stantiated key is linked into the keyring whose ID is specified
703 in arg5.
704 The caller must have the appropriate authorization key. In
706 other words, this operation is available only from a re‐
707 quest-key(8)-style program. See request_key(2).
708 The caller must have the appropriate authorization key, and once
710 the uninstantiated key has been instantiated, the authorization
711 key is revoked. In other words, this operation is available
712 only from a request-key(8)-style program. See request_key(2)
713 for an explanation of uninstantiated keys and key instantiation.
714 This operation is exposed by libkeyutils via the function
716 keyctl_reject(3).
717 KEYCTL_INSTANTIATE_IOV (since Linux 2.6.39)
719 Instantiate an uninstantiated key with a payload specified via a
720 vector of buffers.
721 This operation is the same as KEYCTL_INSTANTIATE, but the pay‐
723 load data is specified as an array of iovec structures:
724 struct iovec {
726 void *iov_base; /* Starting address of buffer */
727 size_t iov_len; /* Size of buffer (in bytes) */
728 };
729 The pointer to the payload vector is specified in arg3 (cast as
731 const struct iovec *). The number of items in the vector is
732 specified in arg4 (cast as unsigned int).
733 The arg2 (key ID) and arg5 (keyring ID) are interpreted as for
735 KEYCTL_INSTANTIATE.
736 This operation is exposed by libkeyutils via the function
738 keyctl_instantiate_iov(3).
739 KEYCTL_INVALIDATE (since Linux 3.5)
741 Mark a key as invalid.
742 The ID of the key to be invalidated is specified in arg2 (cast
744 to key_serial_t).
745 To invalidate a key, the caller must have search permission on
747 the key.
748 This operation marks the key as invalid and schedules immediate
750 garbage collection. The garbage collector removes the invali‐
751 dated key from all keyrings and deletes the key when its refer‐
752 ence count reaches zero. After this operation, the key will be
753 ignored by all searches, even if it is not yet deleted.
754 Keys that are marked invalid become invisible to normal key op‐
756 erations immediately, though they are still visible in
757 /proc/keys (marked with an 'i' flag) until they are actually re‐
758 moved.
759 The arguments arg3, arg4, and arg5 are ignored.
761 This operation is exposed by libkeyutils via the function
763 keyctl_invalidate(3).
764 KEYCTL_GET_PERSISTENT (since Linux 3.13)
766 Get the persistent keyring (persistent-keyring(7)) for a speci‐
767 fied user and link it to a specified keyring.
768 The user ID is specified in arg2 (cast to uid_t). If the value
770 -1 is specified, the caller's real user ID is used. The ID of
771 the destination keyring is specified in arg3 (cast to key_se‐
772 rial_t).
773 The caller must have the CAP_SETUID capability in its user name‐
775 space in order to fetch the persistent keyring for a user ID
776 that does not match either the real or effective user ID of the
777 caller.
778 If the call is successful, a link to the persistent keyring is
780 added to the keyring whose ID was specified in arg3.
781 The caller must have write permission on the keyring.
783 The persistent keyring will be created by the kernel if it does
785 not yet exist.
786 Each time the KEYCTL_GET_PERSISTENT operation is performed, the
788 persistent keyring will have its expiration timeout reset to the
789 value in:
790 /proc/sys/kernel/keys/persistent_keyring_expiry
792 Should the timeout be reached, the persistent keyring will be
794 removed and everything it pins can then be garbage collected.
795 Persistent keyrings were added to Linux in kernel version 3.13.
797 The arguments arg4 and arg5 are ignored.
799 This operation is exposed by libkeyutils via the function
801 keyctl_get_persistent(3).
802 KEYCTL_DH_COMPUTE (since Linux 4.7)
804 Compute a Diffie-Hellman shared secret or public key, optionally
805 applying key derivation function (KDF) to the result.
806 The arg2 argument is a pointer to a set of parameters containing
808 serial numbers for three "user" keys used in the Diffie-Hellman
809 calculation, packaged in a structure of the following form:
810 struct keyctl_dh_params {
812 int32_t private; /* The local private key */
813 int32_t prime; /* The prime, known to both parties */
814 int32_t base; /* The base integer: either a shared
815 generator or the remote public key */
816 };
817 Each of the three keys specified in this structure must grant
819 the caller read permission. The payloads of these keys are used
820 to calculate the Diffie-Hellman result as:
821 base ^ private mod prime
823 If the base is the shared generator, the result is the local
825 public key. If the base is the remote public key, the result is
826 the shared secret.
827 The arg3 argument (cast to char *) points to a buffer where the
829 result of the calculation is placed. The size of that buffer is
830 specified in arg4 (cast to size_t).
831 The buffer must be large enough to accommodate the output data,
833 otherwise an error is returned. If arg4 is specified zero, in
834 which case the buffer is not used and the operation returns the
835 minimum required buffer size (i.e., the length of the prime).
836 Diffie-Hellman computations can be performed in user space, but
838 require a multiple-precision integer (MPI) library. Moving the
839 implementation into the kernel gives access to the kernel MPI
840 implementation, and allows access to secure or acceleration
841 hardware.
842 Adding support for DH computation to the keyctl() system call
844 was considered a good fit due to the DH algorithm's use for de‐
845 riving shared keys; it also allows the type of the key to deter‐
846 mine which DH implementation (software or hardware) is appropri‐
847 ate.
848 If the arg5 argument is NULL, then the DH result itself is re‐
850 turned. Otherwise (since Linux 4.12), it is a pointer to a
851 structure which specifies parameters of the KDF operation to be
852 applied:
853 struct keyctl_kdf_params {
855 char *hashname; /* Hash algorithm name */
856 char *otherinfo; /* SP800-56A OtherInfo */
857 __u32 otherinfolen; /* Length of otherinfo data */
858 __u32 __spare[8]; /* Reserved */
859 };
860 The hashname field is a null-terminated string which specifies a
862 hash name (available in the kernel's crypto API; the list of the
863 hashes available is rather tricky to observe; please refer to
864 the "Kernel Crypto API Architecture" ⟨https://www.kernel.org/doc
865 /html/latest/crypto/architecture.html⟩ documentation for the in‐
866 formation regarding how hash names are constructed and your ker‐
867 nel's source and configuration regarding what ciphers and tem‐
868 plates with type CRYPTO_ALG_TYPE_SHASH are available) to be ap‐
869 plied to DH result in KDF operation.
870 The otherinfo field is an OtherInfo data as described in
872 SP800-56A section 5.8.1.2 and is algorithm-specific. This data
873 is concatenated with the result of DH operation and is provided
874 as an input to the KDF operation. Its size is provided in the
875 otherinfolen field and is limited by KEYCTL_KDF_MAX_OI_LEN con‐
876 stant that defined in security/keys/internal.h to a value of 64.
877 The __spare field is currently unused. It was ignored until
879 Linux 4.13 (but still should be user-addressable since it is
880 copied to the kernel), and should contain zeros since Linux
881 4.13.
882 The KDF implementation complies with SP800-56A as well as with
884 SP800-108 (the counter KDF).
885 This operation is exposed by libkeyutils (from version 1.5.10
887 onwards) via the functions keyctl_dh_compute(3) and
888 keyctl_dh_compute_alloc(3).
889 KEYCTL_RESTRICT_KEYRING (since Linux 4.12)
891 Apply a key-linking restriction to the keyring with the ID pro‐
892 vided in arg2 (cast to key_serial_t). The caller must have se‐
893 tattr permission on the key. If arg3 is NULL, any attempt to
894 add a key to the keyring is blocked; otherwise it contains a
895 pointer to a string with a key type name and arg4 contains a
896 pointer to string that describes the type-specific restriction.
897 As of Linux 4.12, only the type "asymmetric" has restrictions
898 defined:
899 builtin_trusted
901 Allows only keys that are signed by a key linked to the
902 built-in keyring (".builtin_trusted_keys").
903 builtin_and_secondary_trusted
905 Allows only keys that are signed by a key linked to the
906 secondary keyring (".secondary_trusted_keys") or, by ex‐
907 tension, a key in a built-in keyring, as the latter is
908 linked to the former.
909 key_or_keyring:key
911 key_or_keyring:key:chain
912 If key specifies the ID of a key of type "asymmetric",
913 then only keys that are signed by this key are allowed.
914 If key specifies the ID of a keyring, then only keys that
916 are signed by a key linked to this keyring are allowed.
917 If ":chain" is specified, keys that are signed by a keys
919 linked to the destination keyring (that is, the keyring
920 with the ID specified in the arg2 argument) are also al‐
921 lowed.
922 Note that a restriction can be configured only once for the
924 specified keyring; once a restriction is set, it can't be over‐
925 ridden.
926 The argument arg5 is ignored.
928
930 For a successful call, the return value depends on the operation:
931 KEYCTL_GET_KEYRING_ID
933 The ID of the requested keyring.
934 KEYCTL_JOIN_SESSION_KEYRING
936 The ID of the joined session keyring.
937 KEYCTL_DESCRIBE
939 The size of the description (including the terminating null
940 byte), irrespective of the provided buffer size.
941 KEYCTL_SEARCH
943 The ID of the key that was found.
944 KEYCTL_READ
946 The amount of data that is available in the key, irrespective of
947 the provided buffer size.
948 KEYCTL_SET_REQKEY_KEYRING
950 The ID of the previous default keyring to which implicitly re‐
951 quested keys were linked (one of KEY_REQKEY_DEFL_USER_*).
952 KEYCTL_ASSUME_AUTHORITY
954 Either 0, if the ID given was 0, or the ID of the authorization
955 key matching the specified key, if a nonzero key ID was pro‐
956 vided.
957 KEYCTL_GET_SECURITY
959 The size of the LSM security label string (including the termi‐
960 nating null byte), irrespective of the provided buffer size.
961 KEYCTL_GET_PERSISTENT
963 The ID of the persistent keyring.
964 KEYCTL_DH_COMPUTE
966 The number of bytes copied to the buffer, or, if arg4 is 0, the
967 required buffer size.
968 All other operations
970 Zero.
971 On error, -1 is returned, and errno is set to indicate the error.
973
975 EACCES The requested operation wasn't permitted.
976 EAGAIN operation was KEYCTL_DH_COMPUTE and there was an error during
978 crypto module initialization.
979 EDEADLK
981 operation was KEYCTL_LINK and the requested link would result in
982 a cycle.
983 EDEADLK
985 operation was KEYCTL_RESTRICT_KEYRING and the requested keyring
986 restriction would result in a cycle.
987 EDQUOT The key quota for the caller's user would be exceeded by creat‐
989 ing a key or linking it to the keyring.
990 EEXIST operation was KEYCTL_RESTRICT_KEYRING and keyring provided in
992 arg2 argument already has a restriction set.
993 EFAULT operation was KEYCTL_DH_COMPUTE and one of the following has
995 failed:
996 • copying of the struct keyctl_dh_params, provided in the arg2
998 argument, from user space;
999 • copying of the struct keyctl_kdf_params, provided in the non-
1001 NULL arg5 argument, from user space (in case kernel supports
1002 performing KDF operation on DH operation result);
1003 • copying of data pointed by the hashname field of the struct
1005 keyctl_kdf_params from user space;
1006 • copying of data pointed by the otherinfo field of the struct
1008 keyctl_kdf_params from user space if the otherinfolen field
1009 was nonzero;
1010 • copying of the result to user space.
1012 EINVAL operation was KEYCTL_SETPERM and an invalid permission bit was
1014 specified in arg3.
1015 EINVAL operation was KEYCTL_SEARCH and the size of the description in
1017 arg4 (including the terminating null byte) exceeded 4096 bytes.
1018 EINVAL size of the string (including the terminating null byte) speci‐
1020 fied in arg3 (the key type) or arg4 (the key description) ex‐
1021 ceeded the limit (32 bytes and 4096 bytes respectively).
1022 EINVAL (Linux kernels before 4.12)
1024 operation was KEYCTL_DH_COMPUTE, argument arg5 was non-NULL.
1025 EINVAL operation was KEYCTL_DH_COMPUTE And the digest size of the hash‐
1027 ing algorithm supplied is zero.
1028 EINVAL operation was KEYCTL_DH_COMPUTE and the buffer size provided is
1030 not enough to hold the result. Provide 0 as a buffer size in
1031 order to obtain the minimum buffer size.
1032 EINVAL operation was KEYCTL_DH_COMPUTE and the hash name provided in
1034 the hashname field of the struct keyctl_kdf_params pointed by
1035 arg5 argument is too big (the limit is implementation-specific
1036 and varies between kernel versions, but it is deemed big enough
1037 for all valid algorithm names).
1038 EINVAL operation was KEYCTL_DH_COMPUTE and the __spare field of the
1040 struct keyctl_kdf_params provided in the arg5 argument contains
1041 nonzero values.
1042 EKEYEXPIRED
1044 An expired key was found or specified.
1045 EKEYREJECTED
1047 A rejected key was found or specified.
1048 EKEYREVOKED
1050 A revoked key was found or specified.
1051 ELOOP operation was KEYCTL_LINK and the requested link would cause the
1053 maximum nesting depth for keyrings to be exceeded.
1054 EMSGSIZE
1056 operation was KEYCTL_DH_COMPUTE and the buffer length exceeds
1057 KEYCTL_KDF_MAX_OUTPUT_LEN (which is 1024 currently) or the oth‐
1058 erinfolen field of the struct keyctl_kdf_parms passed in arg5
1059 exceeds KEYCTL_KDF_MAX_OI_LEN (which is 64 currently).
1060 ENFILE (Linux kernels before 3.13)
1062 operation was KEYCTL_LINK and the keyring is full. (Before
1063 Linux 3.13, the available space for storing keyring links was
1064 limited to a single page of memory; since Linux 3.13, there is
1065 no fixed limit.)
1066 ENOENT operation was KEYCTL_UNLINK and the key to be unlinked isn't
1068 linked to the keyring.
1069 ENOENT operation was KEYCTL_DH_COMPUTE and the hashing algorithm speci‐
1071 fied in the hashname field of the struct keyctl_kdf_params
1072 pointed by arg5 argument hasn't been found.
1073 ENOENT operation was KEYCTL_RESTRICT_KEYRING and the type provided in
1075 arg3 argument doesn't support setting key linking restrictions.
1076 ENOKEY No matching key was found or an invalid key was specified.
1078 ENOKEY The value KEYCTL_GET_KEYRING_ID was specified in operation, the
1080 key specified in arg2 did not exist, and arg3 was zero (meaning
1081 don't create the key if it didn't exist).
1082 ENOMEM One of kernel memory allocation routines failed during the exe‐
1084 cution of the syscall.
1085 ENOTDIR
1087 A key of keyring type was expected but the ID of a key with a
1088 different type was provided.
1089 EOPNOTSUPP
1091 operation was KEYCTL_READ and the key type does not support
1092 reading (e.g., the type is "login").
1093 EOPNOTSUPP
1095 operation was KEYCTL_UPDATE and the key type does not support
1096 updating.
1097 EOPNOTSUPP
1099 operation was KEYCTL_RESTRICT_KEYRING, the type provided in arg3
1100 argument was "asymmetric", and the key specified in the restric‐
1101 tion specification provided in arg4 has type other than "asym‐
1102 metric" or "keyring".
1103 EPERM operation was KEYCTL_GET_PERSISTENT, arg2 specified a UID other
1105 than the calling thread's real or effective UID, and the caller
1106 did not have the CAP_SETUID capability.
1107 EPERM operation was KEYCTL_SESSION_TO_PARENT and either: all of the
1109 UIDs (GIDs) of the parent process do not match the effective UID
1110 (GID) of the calling process; the UID of the parent's existing
1111 session keyring or the UID of the caller's session keyring did
1112 not match the effective UID of the caller; the parent process is
1113 not single-thread; or the parent process is init(1) or a kernel
1114 thread.
1115 ETIMEDOUT
1117 operation was KEYCTL_DH_COMPUTE and the initialization of crypto
1118 modules has timed out.
1119
1121 This system call first appeared in Linux 2.6.10.
1122
1124 This system call is a nonstandard Linux extension.
1125
1127 A wrapper is provided in the libkeyutils library. (The accompanying
1128 package provides the <keyutils.h> header file.) When employing the
1129 wrapper in that library, link with -lkeyutils. However, rather than
1130 using this system call directly, you probably want to use the various
1131 library functions mentioned in the descriptions of individual opera‐
1132 tions above.
1133
1135 The program below provide subset of the functionality of the re‐
1136 quest-key(8) program provided by the keyutils package. For informa‐
1137 tional purposes, the program records various information in a log file.
1138 As described in request_key(2), the request-key(8) program is invoked
1140 with command-line arguments that describe a key that is to be instanti‐
1141 ated. The example program fetches and logs these arguments. The pro‐
1142 gram assumes authority to instantiate the requested key, and then in‐
1143 stantiates that key.
1144 The following shell session demonstrates the use of this program. In
1146 the session, we compile the program and then use it to temporarily re‐
1147 place the standard request-key(8) program. (Note that temporarily dis‐
1148 abling the standard request-key(8) program may not be safe on some sys‐
1149 tems.) While our example program is installed, we use the example pro‐
1150 gram shown in request_key(2) to request a key.
1151 $ cc -o key_instantiate key_instantiate.c -lkeyutils
1153 $ sudo mv /sbin/request-key /sbin/request-key.backup
1154 $ sudo cp key_instantiate /sbin/request-key
1155 $ ./t_request_key user mykey somepayloaddata
1156 Key ID is 20d035bf
1157 $ sudo mv /sbin/request-key.backup /sbin/request-key
1158 Looking at the log file created by this program, we can see the com‐
1160 mand-line arguments supplied to our example program:
1161 $ cat /tmp/key_instantiate.log
1163 Time: Mon Nov 7 13:06:47 2016
1164 Command line arguments:
1166 argv[0]: /sbin/request-key
1167 operation: create
1168 key_to_instantiate: 20d035bf
1169 UID: 1000
1170 GID: 1000
1171 thread_keyring: 0
1172 process_keyring: 0
1173 session_keyring: 256e6a6
1174 Key description: user;1000;1000;3f010000;mykey
1176 Auth key payload: somepayloaddata
1177 Destination keyring: 256e6a6
1178 Auth key description: .request_key_auth;1000;1000;0b010000;20d035bf
1179 The last few lines of the above output show that the example program
1181 was able to fetch:
1182 * the description of the key to be instantiated, which included the
1184 name of the key (mykey);
1185 * the payload of the authorization key, which consisted of the data
1187 (somepayloaddata) passed to request_key(2);
1188 * the destination keyring that was specified in the call to re‐
1190 quest_key(2); and
1191 * the description of the authorization key, where we can see that the
1193 name of the authorization key matches the ID of the key that is to
1194 be instantiated (20d035bf).
1195 The example program in request_key(2) specified the destination keyring
1197 as KEY_SPEC_SESSION_KEYRING. By examining the contents of /proc/keys,
1198 we can see that this was translated to the ID of the destination
1199 keyring (0256e6a6) shown in the log output above; we can also see the
1200 newly created key with the name mykey and ID 20d035bf.
1201 $ cat /proc/keys | egrep 'mykey|256e6a6'
1203 0256e6a6 I--Q--- 194 perm 3f030000 1000 1000 keyring _ses: 3
1204 20d035bf I--Q--- 1 perm 3f010000 1000 1000 user mykey: 16
1205 Program source
1207 /* key_instantiate.c */
1209 #include <sys/types.h>
1211 #include <keyutils.h>
1212 #include <time.h>
1213 #include <fcntl.h>
1214 #include <stdint.h>
1215 #include <stdio.h>
1216 #include <stdlib.h>
1217 #include <unistd.h>
1218 #include <string.h>
1219 #include <errno.h>
1220 #ifndef KEY_SPEC_REQUESTOR_KEYRING
1222 #define KEY_SPEC_REQUESTOR_KEYRING -8
1223 #endif
1224 int
1226 main(int argc, char *argv[])
1227 {
1228 FILE *fp;
1229 time_t t;
1230 char *operation;
1231 key_serial_t key_to_instantiate, dest_keyring;
1232 key_serial_t thread_keyring, process_keyring, session_keyring;
1233 uid_t uid;
1234 gid_t gid;
1235 char dbuf[256];
1236 char auth_key_payload[256];
1237 int akp_size; /* Size of auth_key_payload */
1238 int auth_key;
1239 fp = fopen("/tmp/key_instantiate.log", "w");
1241 if (fp == NULL)
1242 exit(EXIT_FAILURE);
1243 setbuf(fp, NULL);
1245 t = time(NULL);
1247 fprintf(fp, "Time: %s\n", ctime(&t));
1248 /*
1250 * The kernel passes a fixed set of arguments to the program
1251 * that it execs; fetch them.
1252 */
1253 operation = argv[1];
1254 key_to_instantiate = atoi(argv[2]);
1255 uid = atoi(argv[3]);
1256 gid = atoi(argv[4]);
1257 thread_keyring = atoi(argv[5]);
1258 process_keyring = atoi(argv[6]);
1259 session_keyring = atoi(argv[7]);
1260 fprintf(fp, "Command line arguments:\n");
1262 fprintf(fp, " argv[0]: %s\n", argv[0]);
1263 fprintf(fp, " operation: %s\n", operation);
1264 fprintf(fp, " key_to_instantiate: %jx\n",
1265 (uintmax_t) key_to_instantiate);
1266 fprintf(fp, " UID: %jd\n", (intmax_t) uid);
1267 fprintf(fp, " GID: %jd\n", (intmax_t) gid);
1268 fprintf(fp, " thread_keyring: %jx\n",
1269 (uintmax_t) thread_keyring);
1270 fprintf(fp, " process_keyring: %jx\n",
1271 (uintmax_t) process_keyring);
1272 fprintf(fp, " session_keyring: %jx\n",
1273 (uintmax_t) session_keyring);
1274 fprintf(fp, "\n");
1275 /*
1277 * Assume the authority to instantiate the key named in argv[2].
1278 */
1279 if (keyctl(KEYCTL_ASSUME_AUTHORITY, key_to_instantiate) == -1) {
1280 fprintf(fp, "KEYCTL_ASSUME_AUTHORITY failed: %s\n",
1281 strerror(errno));
1282 exit(EXIT_FAILURE);
1283 }
1284 /*
1286 * Fetch the description of the key that is to be instantiated.
1287 */
1288 if (keyctl(KEYCTL_DESCRIBE, key_to_instantiate,
1289 dbuf, sizeof(dbuf)) == -1) {
1290 fprintf(fp, "KEYCTL_DESCRIBE failed: %s\n", strerror(errno));
1291 exit(EXIT_FAILURE);
1292 }
1293 fprintf(fp, "Key description: %s\n", dbuf);
1295 /*
1297 * Fetch the payload of the authorization key, which is
1298 * actually the callout data given to request_key().
1299 */
1300 akp_size = keyctl(KEYCTL_READ, KEY_SPEC_REQKEY_AUTH_KEY,
1301 auth_key_payload, sizeof(auth_key_payload));
1302 if (akp_size == -1) {
1303 fprintf(fp, "KEYCTL_READ failed: %s\n", strerror(errno));
1304 exit(EXIT_FAILURE);
1305 }
1306 auth_key_payload[akp_size] = '\0';
1308 fprintf(fp, "Auth key payload: %s\n", auth_key_payload);
1309 /*
1311 * For interest, get the ID of the authorization key and
1312 * display it.
1313 */
1314 auth_key = keyctl(KEYCTL_GET_KEYRING_ID,
1315 KEY_SPEC_REQKEY_AUTH_KEY);
1316 if (auth_key == -1) {
1317 fprintf(fp, "KEYCTL_GET_KEYRING_ID failed: %s\n",
1318 strerror(errno));
1319 exit(EXIT_FAILURE);
1320 }
1321 fprintf(fp, "Auth key ID: %jx\n", (uintmax_t) auth_key);
1323 /*
1325 * Fetch key ID for the request_key(2) destination keyring.
1326 */
1327 dest_keyring = keyctl(KEYCTL_GET_KEYRING_ID,
1328 KEY_SPEC_REQUESTOR_KEYRING);
1329 if (dest_keyring == -1) {
1330 fprintf(fp, "KEYCTL_GET_KEYRING_ID failed: %s\n",
1331 strerror(errno));
1332 exit(EXIT_FAILURE);
1333 }
1334 fprintf(fp, "Destination keyring: %jx\n", (uintmax_t) dest_keyring);
1336 /*
1338 * Fetch the description of the authorization key. This
1339 * allows us to see the key type, UID, GID, permissions,
1340 * and description (name) of the key. Among other things,
1341 * we will see that the name of the key is a hexadecimal
1342 * string representing the ID of the key to be instantiated.
1343 */
1344 if (keyctl(KEYCTL_DESCRIBE, KEY_SPEC_REQKEY_AUTH_KEY,
1345 dbuf, sizeof(dbuf)) == -1) {
1346 fprintf(fp, "KEYCTL_DESCRIBE failed: %s\n", strerror(errno));
1347 exit(EXIT_FAILURE);
1348 }
1349 fprintf(fp, "Auth key description: %s\n", dbuf);
1351 /*
1353 * Instantiate the key using the callout data that was supplied
1354 * in the payload of the authorization key.
1355 */
1356 if (keyctl(KEYCTL_INSTANTIATE, key_to_instantiate,
1357 auth_key_payload, akp_size + 1, dest_keyring) == -1) {
1358 fprintf(fp, "KEYCTL_INSTANTIATE failed: %s\n",
1359 strerror(errno));
1360 exit(EXIT_FAILURE);
1361 }
1362 exit(EXIT_SUCCESS);
1364 }
1365
1367 keyctl(1), add_key(2), request_key(2), keyctl(3),
1368 keyctl_assume_authority(3), keyctl_chown(3), keyctl_clear(3),
1369 keyctl_describe(3), keyctl_describe_alloc(3), keyctl_dh_compute(3),
1370 keyctl_dh_compute_alloc(3), keyctl_get_keyring_ID(3),
1371 keyctl_get_persistent(3), keyctl_get_security(3),
1372 keyctl_get_security_alloc(3), keyctl_instantiate(3),
1373 keyctl_instantiate_iov(3), keyctl_invalidate(3),
1374 keyctl_join_session_keyring(3), keyctl_link(3), keyctl_negate(3),
1375 keyctl_read(3), keyctl_read_alloc(3), keyctl_reject(3),
1376 keyctl_revoke(3), keyctl_search(3), keyctl_session_to_parent(3),
1377 keyctl_set_reqkey_keyring(3), keyctl_set_timeout(3), keyctl_setperm(3),
1378 keyctl_unlink(3), keyctl_update(3), recursive_key_scan(3),
1379 recursive_session_key_scan(3), capabilities(7), credentials(7),
1380 keyrings(7), keyutils(7), persistent-keyring(7), process-keyring(7),
1381 session-keyring(7), thread-keyring(7), user-keyring(7),
1382 user_namespaces(7), user-session-keyring(7), request-key(8)
1383 The kernel source files under Documentation/security/keys/ (or, before
1385 Linux 4.13, in the file Documentation/security/keys.txt).
1386
1388 This page is part of release 5.13 of the Linux man-pages project. A
1389 description of the project, information about reporting bugs, and the
1390 latest version of this page, can be found at
1391 https://www.kernel.org/doc/man-pages/.
1392Linux 2021-08-27 KEYCTL(2)