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