1keyctl(2) System Calls Manual keyctl(2)
2
6 keyctl - manipulate the kernel's key management facility
7
9 Standard C library (libc, -lc)
10 Alternatively, Linux Key Management Utilities (libkeyutils, -lkeyu‐
12 tils); see VERSIONS.
13
15 #include <linux/keyctl.h> /* Definition of KEY* constants */
16 #include <sys/syscall.h> /* Definition of SYS_* constants */
17 #include <unistd.h>
18 long syscall(SYS_keyctl, int operation, unsigned long arg2,
20 unsigned long arg3, unsigned long arg4,
21 unsigned long arg5);
22 Note: glibc provides no wrapper for keyctl(), necessitating the use of
24 syscall(2).
25
27 keyctl() allows user-space programs to perform key manipulation.
28 The operation performed by keyctl() is determined by the value of the
30 operation argument. Each of these operations is wrapped by the
31 libkeyutils library (provided by the keyutils package) into individual
32 functions (noted below) to permit the compiler to check types.
33 The permitted values for operation are:
35 KEYCTL_GET_KEYRING_ID (since Linux 2.6.10)
37 Map a special key ID to a real key ID for this process.
38 This operation looks up the special key whose ID is provided in
40 arg2 (cast to key_serial_t). If the special key is found, the
41 ID of the corresponding real key is returned as the function re‐
42 sult. The following values may be specified in arg2:
43 KEY_SPEC_THREAD_KEYRING
45 This specifies the calling thread's thread-specific
46 keyring. See thread-keyring(7).
47 KEY_SPEC_PROCESS_KEYRING
49 This specifies the caller's process-specific keyring.
50 See process-keyring(7).
51 KEY_SPEC_SESSION_KEYRING
53 This specifies the caller's session-specific keyring.
54 See session-keyring(7).
55 KEY_SPEC_USER_KEYRING
57 This specifies the caller's UID-specific keyring. See
58 user-keyring(7).
59 KEY_SPEC_USER_SESSION_KEYRING
61 This specifies the caller's UID-session keyring. See
62 user-session-keyring(7).
63 KEY_SPEC_REQKEY_AUTH_KEY (since Linux 2.6.16)
65 This specifies the authorization key created by re‐
66 quest_key(2) and passed to the process it spawns to gen‐
67 erate a key. This key is available only in a re‐
68 quest-key(8)-style program that was passed an authoriza‐
69 tion key by the kernel and ceases to be available once
70 the requested key has been instantiated; see re‐
71 quest_key(2).
72 KEY_SPEC_REQUESTOR_KEYRING (since Linux 2.6.29)
74 This specifies the key ID for the request_key(2) destina‐
75 tion keyring. This keyring is available only in a re‐
76 quest-key(8)-style program that was passed an authoriza‐
77 tion key by the kernel and ceases to be available once
78 the requested key has been instantiated; see re‐
79 quest_key(2).
80 The behavior if the key specified in arg2 does not exist depends
82 on the value of arg3 (cast to int). If arg3 contains a nonzero
83 value, then—if it is appropriate to do so (e.g., when looking up
84 the user, user-session, or session key)—a new key is created and
85 its real key ID returned as the function result. Otherwise, the
86 operation fails with the error ENOKEY.
87 If a valid key ID is specified in arg2, and the key exists, then
89 this operation simply returns the key ID. If the key does not
90 exist, the call fails with error ENOKEY.
91 The caller must have search permission on a keyring in order for
93 it to be found.
94 The arguments arg4 and arg5 are ignored.
96 This operation is exposed by libkeyutils via the function
98 keyctl_get_keyring_ID(3).
99 KEYCTL_JOIN_SESSION_KEYRING (since Linux 2.6.10)
101 Replace the session keyring this process subscribes to with a
102 new session keyring.
103 If arg2 is NULL, an anonymous keyring with the description
105 "_ses" is created and the process is subscribed to that keyring
106 as its session keyring, displacing the previous session keyring.
107 Otherwise, arg2 (cast to char *) is treated as the description
109 (name) of a keyring, and the behavior is as follows:
110 • If a keyring with a matching description exists, the process
112 will attempt to subscribe to that keyring as its session
113 keyring if possible; if that is not possible, an error is re‐
114 turned. In order to subscribe to the keyring, the caller
115 must have search permission on the keyring.
116 • If a keyring with a matching description does not exist, then
118 a new keyring with the specified description is created, and
119 the process is subscribed to that keyring as its session
120 keyring.
121 The arguments arg3, arg4, and arg5 are ignored.
123 This operation is exposed by libkeyutils via the function
125 keyctl_join_session_keyring(3).
126 KEYCTL_UPDATE (since Linux 2.6.10)
128 Update a key's data payload.
129 The arg2 argument (cast to key_serial_t) specifies the ID of the
131 key to be updated. The arg3 argument (cast to void *) points to
132 the new payload and arg4 (cast to size_t) contains the new pay‐
133 load size in bytes.
134 The caller must have write permission on the key specified and
136 the key type must support updating.
137 A negatively instantiated key (see the description of KEYCTL_RE‐
139 JECT) can be positively instantiated with this operation.
140 The arg5 argument is ignored.
142 This operation is exposed by libkeyutils via the function
144 keyctl_update(3).
145 KEYCTL_REVOKE (since Linux 2.6.10)
147 Revoke the key with the ID provided in arg2 (cast to key_se‐
148 rial_t). The key is scheduled for garbage collection; it will
149 no longer be findable, and will be unavailable for further oper‐
150 ations. Further attempts to use the key will fail with the er‐
151 ror EKEYREVOKED.
152 The caller must have write or setattr permission on the key.
154 The arguments arg3, arg4, and arg5 are ignored.
156 This operation is exposed by libkeyutils via the function
158 keyctl_revoke(3).
159 KEYCTL_CHOWN (since Linux 2.6.10)
161 Change the ownership (user and group ID) of a key.
162 The arg2 argument (cast to key_serial_t) contains the key ID.
164 The arg3 argument (cast to uid_t) contains the new user ID (or
165 -1 in case the user ID shouldn't be changed). The arg4 argument
166 (cast to gid_t) contains the new group ID (or -1 in case the
167 group ID shouldn't be changed).
168 The key must grant the caller setattr permission.
170 For the UID to be changed, or for the GID to be changed to a
172 group the caller is not a member of, the caller must have the
173 CAP_SYS_ADMIN capability (see capabilities(7)).
174 If the UID is to be changed, the new user must have sufficient
176 quota to accept the key. The quota deduction will be removed
177 from the old user to the new user should the UID be changed.
178 The arg5 argument is ignored.
180 This operation is exposed by libkeyutils via the function
182 keyctl_chown(3).
183 KEYCTL_SETPERM (since Linux 2.6.10)
185 Change the permissions of the key with the ID provided in the
186 arg2 argument (cast to key_serial_t) to the permissions provided
187 in the arg3 argument (cast to key_perm_t).
188 If the caller doesn't have the CAP_SYS_ADMIN capability, it can
190 change permissions only for the keys it owns. (More precisely:
191 the caller's filesystem UID must match the UID of the key.)
192 The key must grant setattr permission to the caller regardless
194 of the caller's capabilities.
195 The permissions in arg3 specify masks of available operations
197 for each of the following user categories:
198 possessor (since Linux 2.6.14)
200 This is the permission granted to a process that pos‐
201 sesses the key (has it attached searchably to one of the
202 process's keyrings); see keyrings(7).
203 user This is the permission granted to a process whose
205 filesystem UID matches the UID of the key.
206 group This is the permission granted to a process whose
208 filesystem GID or any of its supplementary GIDs matches
209 the GID of the key.
210 other This is the permission granted to other processes that do
212 not match the user and group categories.
213 The user, group, and other categories are exclusive: if a
215 process matches the user category, it will not receive permis‐
216 sions granted in the group category; if a process matches the
217 user or group category, then it will not receive permissions
218 granted in the other category.
219 The possessor category grants permissions that are cumulative
221 with the grants from the user, group, or other category.
222 Each permission mask is eight bits in size, with only six bits
224 currently used. The available permissions are:
225 view This permission allows reading attributes of a key.
227 This permission is required for the KEYCTL_DESCRIBE oper‐
229 ation.
230 The permission bits for each category are KEY_POS_VIEW,
232 KEY_USR_VIEW, KEY_GRP_VIEW, and KEY_OTH_VIEW.
233 read This permission allows reading a key's payload.
235 This permission is required for the KEYCTL_READ opera‐
237 tion.
238 The permission bits for each category are KEY_POS_READ,
240 KEY_USR_READ, KEY_GRP_READ, and KEY_OTH_READ.
241 write This permission allows update or instantiation of a key's
243 payload. For a keyring, it allows keys to be linked and
244 unlinked from the keyring,
245 This permission is required for the KEYCTL_UPDATE,
247 KEYCTL_REVOKE, KEYCTL_CLEAR, KEYCTL_LINK, and KEYCTL_UN‐
248 LINK operations.
249 The permission bits for each category are KEY_POS_WRITE,
251 KEY_USR_WRITE, KEY_GRP_WRITE, and KEY_OTH_WRITE.
252 search This permission allows keyrings to be searched and keys
254 to be found. Searches can recurse only into nested
255 keyrings that have search permission set.
256 This permission is required for the
258 KEYCTL_GET_KEYRING_ID, KEYCTL_JOIN_SESSION_KEYRING,
259 KEYCTL_SEARCH, and KEYCTL_INVALIDATE operations.
260 The permission bits for each category are KEY_POS_SEARCH,
262 KEY_USR_SEARCH, KEY_GRP_SEARCH, and KEY_OTH_SEARCH.
263 link This permission allows a key or keyring to be linked to.
265 This permission is required for the KEYCTL_LINK and
267 KEYCTL_SESSION_TO_PARENT operations.
268 The permission bits for each category are KEY_POS_LINK,
270 KEY_USR_LINK, KEY_GRP_LINK, and KEY_OTH_LINK.
271 setattr (since Linux 2.6.15).
273 This permission allows a key's UID, GID, and permissions
274 mask to be changed.
275 This permission is required for the KEYCTL_REVOKE,
277 KEYCTL_CHOWN, and KEYCTL_SETPERM operations.
278 The permission bits for each category are KEY_POS_SE‐
280 TATTR, KEY_USR_SETATTR, KEY_GRP_SETATTR, and KEY_OTH_SE‐
281 TATTR.
282 As a convenience, the following macros are defined as masks for
284 all of the permission bits in each of the user categories:
285 KEY_POS_ALL, KEY_USR_ALL, KEY_GRP_ALL, and KEY_OTH_ALL.
286 The arg4 and arg5 arguments are ignored.
288 This operation is exposed by libkeyutils via the function
290 keyctl_setperm(3).
291 KEYCTL_DESCRIBE (since Linux 2.6.10)
293 Obtain a string describing the attributes of a specified key.
294 The ID of the key to be described is specified in arg2 (cast to
296 key_serial_t). The descriptive string is returned in the buffer
297 pointed to by arg3 (cast to char *); arg4 (cast to size_t) spec‐
298 ifies the size of that buffer in bytes.
299 The key must grant the caller view permission.
301 The returned string is null-terminated and contains the follow‐
303 ing information about the key:
304 type;uid;gid;perm;description
306 In the above, type and description are strings, uid and gid are
308 decimal strings, and perm is a hexadecimal permissions mask.
309 The descriptive string is written with the following format:
310 %s;%d;%d;%08x;%s
312 Note: the intention is that the descriptive string should be ex‐
314 tensible in future kernel versions. In particular, the descrip‐
315 tion field will not contain semicolons; it should be parsed by
316 working backwards from the end of the string to find the last
317 semicolon. This allows future semicolon-delimited fields to be
318 inserted in the descriptive string in the future.
319 Writing to the buffer is attempted only when arg3 is non-NULL
321 and the specified buffer size is large enough to accept the de‐
322 scriptive string (including the terminating null byte). In or‐
323 der to determine whether the buffer size was too small, check to
324 see if the return value of the operation is greater than arg4.
325 The arg5 argument is ignored.
327 This operation is exposed by libkeyutils via the function
329 keyctl_describe(3).
330 KEYCTL_CLEAR
332 Clear the contents of (i.e., unlink all keys from) a keyring.
333 The ID of the key (which must be of keyring type) is provided in
335 arg2 (cast to key_serial_t).
336 The caller must have write permission on the keyring.
338 The arguments arg3, arg4, and arg5 are ignored.
340 This operation is exposed by libkeyutils via the function
342 keyctl_clear(3).
343 KEYCTL_LINK (since Linux 2.6.10)
345 Create a link from a keyring to a key.
346 The key to be linked is specified in arg2 (cast to key_se‐
348 rial_t); the keyring is specified in arg3 (cast to key_se‐
349 rial_t).
350 If a key with the same type and description is already linked in
352 the keyring, then that key is displaced from the keyring.
353 Before creating the link, the kernel checks the nesting of the
355 keyrings and returns appropriate errors if the link would pro‐
356 duce a cycle or if the nesting of keyrings would be too deep
357 (The limit on the nesting of keyrings is determined by the ker‐
358 nel constant KEYRING_SEARCH_MAX_DEPTH, defined with the value 6,
359 and is necessary to prevent overflows on the kernel stack when
360 recursively searching keyrings).
361 The caller must have link permission on the key being added and
363 write permission on the keyring.
364 The arguments arg4 and arg5 are ignored.
366 This operation is exposed by libkeyutils via the function
368 keyctl_link(3).
369 KEYCTL_UNLINK (since Linux 2.6.10)
371 Unlink a key from a keyring.
372 The ID of the key to be unlinked is specified in arg2 (cast to
374 key_serial_t); the ID of the keyring from which it is to be un‐
375 linked is specified in arg3 (cast to key_serial_t).
376 If the key is not currently linked into the keyring, an error
378 results.
379 The caller must have write permission on the keyring from which
381 the key is being removed.
382 If the last link to a key is removed, then that key will be
384 scheduled for destruction.
385 The arguments arg4 and arg5 are ignored.
387 This operation is exposed by libkeyutils via the function
389 keyctl_unlink(3).
390 KEYCTL_SEARCH (since Linux 2.6.10)
392 Search for a key in a keyring tree, returning its ID and option‐
393 ally linking it to a specified keyring.
394 The tree to be searched is specified by passing the ID of the
396 head keyring in arg2 (cast to key_serial_t). The search is per‐
397 formed breadth-first and recursively.
398 The arg3 and arg4 arguments specify the key to be searched for:
400 arg3 (cast as char *) contains the key type (a null-terminated
401 character string up to 32 bytes in size, including the terminat‐
402 ing null byte), and arg4 (cast as char *) contains the descrip‐
403 tion of the key (a null-terminated character string up to 4096
404 bytes in size, including the terminating null byte).
405 The source keyring must grant search permission to the caller.
407 When performing the recursive search, only keyrings that grant
408 the caller search permission will be searched. Only keys with
409 for which the caller has search permission can be found.
410 If the key is found, its ID is returned as the function result.
412 If the key is found and arg5 (cast to key_serial_t) is nonzero,
414 then, subject to the same constraints and rules as KEYCTL_LINK,
415 the key is linked into the keyring whose ID is specified in
416 arg5. If the destination keyring specified in arg5 already con‐
417 tains a link to a key that has the same type and description,
418 then that link will be displaced by a link to the key found by
419 this operation.
420 Instead of valid existing keyring IDs, the source (arg2) and
422 destination (arg5) keyrings can be one of the special keyring
423 IDs listed under KEYCTL_GET_KEYRING_ID.
424 This operation is exposed by libkeyutils via the function
426 keyctl_search(3).
427 KEYCTL_READ (since Linux 2.6.10)
429 Read the payload data of a key.
430 The ID of the key whose payload is to be read is specified in
432 arg2 (cast to key_serial_t). This can be the ID of an existing
433 key, or any of the special key IDs listed for
434 KEYCTL_GET_KEYRING_ID.
435 The payload is placed in the buffer pointed by arg3 (cast to
437 char *); the size of that buffer must be specified in arg4 (cast
438 to size_t).
439 The returned data will be processed for presentation according
441 to the key type. For example, a keyring will return an array of
442 key_serial_t entries representing the IDs of all the keys that
443 are linked to it. The user key type will return its data as is.
444 If a key type does not implement this function, the operation
445 fails with the error EOPNOTSUPP.
446 If arg3 is not NULL, as much of the payload data as will fit is
448 copied into the buffer. On a successful return, the return
449 value is always the total size of the payload data. To deter‐
450 mine whether the buffer was of sufficient size, check to see
451 that the return value is less than or equal to the value sup‐
452 plied in arg4.
453 The key must either grant the caller read permission, or grant
455 the caller search permission when searched for from the process
456 keyrings (i.e., the key is possessed).
457 The arg5 argument is ignored.
459 This operation is exposed by libkeyutils via the function
461 keyctl_read(3).
462 KEYCTL_INSTANTIATE (since Linux 2.6.10)
464 (Positively) instantiate an uninstantiated key with a specified
465 payload.
466 The ID of the key to be instantiated is provided in arg2 (cast
468 to key_serial_t).
469 The key payload is specified in the buffer pointed to by arg3
471 (cast to void *); the size of that buffer is specified in arg4
472 (cast to size_t).
473 The payload may be a NULL pointer and the buffer size may be 0
475 if this is supported by the key type (e.g., it is a keyring).
476 The operation may be fail if the payload data is in the wrong
478 format or is otherwise invalid.
479 If arg5 (cast to key_serial_t) is nonzero, then, subject to the
481 same constraints and rules as KEYCTL_LINK, the instantiated key
482 is linked into the keyring whose ID specified in arg5.
483 The caller must have the appropriate authorization key, and once
485 the uninstantiated key has been instantiated, the authorization
486 key is revoked. In other words, this operation is available
487 only from a request-key(8)-style program. See request_key(2)
488 for an explanation of uninstantiated keys and key instantiation.
489 This operation is exposed by libkeyutils via the function
491 keyctl_instantiate(3).
492 KEYCTL_NEGATE (since Linux 2.6.10)
494 Negatively instantiate an uninstantiated key.
495 This operation is equivalent to the call:
497 keyctl(KEYCTL_REJECT, arg2, arg3, ENOKEY, arg4);
499 The arg5 argument is ignored.
501 This operation is exposed by libkeyutils via the function
503 keyctl_negate(3).
504 KEYCTL_SET_REQKEY_KEYRING (since Linux 2.6.13)
506 Set the default keyring to which implicitly requested keys will
507 be linked for this thread, and return the previous setting. Im‐
508 plicit key requests are those made by internal kernel compo‐
509 nents, such as can occur when, for example, opening files on an
510 AFS or NFS filesystem. Setting the default keyring also has an
511 effect when requesting a key from user space; see request_key(2)
512 for details.
513 The arg2 argument (cast to int) should contain one of the fol‐
515 lowing values, to specify the new default keyring:
516 KEY_REQKEY_DEFL_NO_CHANGE
518 Don't change the default keyring. This can be used to
519 discover the current default keyring (without changing
520 it).
521 KEY_REQKEY_DEFL_DEFAULT
523 This selects the default behaviour, which is to use the
524 thread-specific keyring if there is one, otherwise the
525 process-specific keyring if there is one, otherwise the
526 session keyring if there is one, otherwise the UID-spe‐
527 cific session keyring, otherwise the user-specific
528 keyring.
529 KEY_REQKEY_DEFL_THREAD_KEYRING
531 Use the thread-specific keyring (thread-keyring(7)) as
532 the new default keyring.
533 KEY_REQKEY_DEFL_PROCESS_KEYRING
535 Use the process-specific keyring (process-keyring(7)) as
536 the new default keyring.
537 KEY_REQKEY_DEFL_SESSION_KEYRING
539 Use the session-specific keyring (session-keyring(7)) as
540 the new default keyring.
541 KEY_REQKEY_DEFL_USER_KEYRING
543 Use the UID-specific keyring (user-keyring(7)) as the new
544 default keyring.
545 KEY_REQKEY_DEFL_USER_SESSION_KEYRING
547 Use the UID-specific session keyring (user-ses‐
548 sion-keyring(7)) as the new default keyring.
549 KEY_REQKEY_DEFL_REQUESTOR_KEYRING (since Linux 2.6.29)
551 Use the requestor keyring.
552 All other values are invalid.
554 The arguments arg3, arg4, and arg5 are ignored.
556 The setting controlled by this operation is inherited by the
558 child of fork(2) and preserved across execve(2).
559 This operation is exposed by libkeyutils via the function
561 keyctl_set_reqkey_keyring(3).
562 KEYCTL_SET_TIMEOUT (since Linux 2.6.16)
564 Set a timeout on a key.
565 The ID of the key is specified in arg2 (cast to key_serial_t).
567 The timeout value, in seconds from the current time, is speci‐
568 fied in arg3 (cast to unsigned int). The timeout is measured
569 against the realtime clock.
570 Specifying the timeout value as 0 clears any existing timeout on
572 the key.
573 The /proc/keys file displays the remaining time until each key
575 will expire. (This is the only method of discovering the time‐
576 out on a key.)
577 The caller must either have the setattr permission on the key or
579 hold an instantiation authorization token for the key (see re‐
580 quest_key(2)).
581 The key and any links to the key will be automatically garbage
583 collected after the timeout expires. Subsequent attempts to ac‐
584 cess the key will then fail with the error EKEYEXPIRED.
585 This operation cannot be used to set timeouts on revoked, ex‐
587 pired, or negatively instantiated keys.
588 The arguments arg4 and arg5 are ignored.
590 This operation is exposed by libkeyutils via the function
592 keyctl_set_timeout(3).
593 KEYCTL_ASSUME_AUTHORITY (since Linux 2.6.16)
595 Assume (or divest) the authority for the calling thread to in‐
596 stantiate a key.
597 The arg2 argument (cast to key_serial_t) specifies either a non‐
599 zero key ID to assume authority, or the value 0 to divest au‐
600 thority.
601 If arg2 is nonzero, then it specifies the ID of an uninstanti‐
603 ated key for which authority is to be assumed. That key can
604 then be instantiated using one of KEYCTL_INSTANTIATE, KEYCTL_IN‐
605 STANTIATE_IOV, KEYCTL_REJECT, or KEYCTL_NEGATE. Once the key
606 has been instantiated, the thread is automatically divested of
607 authority to instantiate the key.
608 Authority over a key can be assumed only if the calling thread
610 has present in its keyrings the authorization key that is asso‐
611 ciated with the specified key. (In other words, the KEYCTL_AS‐
612 SUME_AUTHORITY operation is available only from a re‐
613 quest-key(8)-style program; see request_key(2) for an explana‐
614 tion of how this operation is used.) The caller must have
615 search permission on the authorization key.
616 If the specified key has a matching authorization key, then the
618 ID of that key is returned. The authorization key can be read
619 (KEYCTL_READ) to obtain the callout information passed to re‐
620 quest_key(2).
621 If the ID given in arg2 is 0, then the currently assumed author‐
623 ity is cleared (divested), and the value 0 is returned.
624 The KEYCTL_ASSUME_AUTHORITY mechanism allows a program such as
626 request-key(8) to assume the necessary authority to instantiate
627 a new uninstantiated key that was created as a consequence of a
628 call to request_key(2). For further information, see re‐
629 quest_key(2) and the kernel source file Documentation/secu‐
630 rity/keys-request-key.txt.
631 The arguments arg3, arg4, and arg5 are ignored.
633 This operation is exposed by libkeyutils via the function
635 keyctl_assume_authority(3).
636 KEYCTL_GET_SECURITY (since Linux 2.6.26)
638 Get the LSM (Linux Security Module) security label of the speci‐
639 fied key.
640 The ID of the key whose security label is to be fetched is spec‐
642 ified in arg2 (cast to key_serial_t). The security label (ter‐
643 minated by a null byte) will be placed in the buffer pointed to
644 by arg3 argument (cast to char *); the size of the buffer must
645 be provided in arg4 (cast to size_t).
646 If arg3 is specified as NULL or the buffer size specified in
648 arg4 is too small, the full size of the security label string
649 (including the terminating null byte) is returned as the func‐
650 tion result, and nothing is copied to the buffer.
651 The caller must have view permission on the specified key.
653 The returned security label string will be rendered in a form
655 appropriate to the LSM in force. For example, with SELinux, it
656 may look like:
657 unconfined_u:unconfined_r:unconfined_t:s0-s0:c0.c1023
659 If no LSM is currently in force, then an empty string is placed
661 in the buffer.
662 The arg5 argument is ignored.
664 This operation is exposed by libkeyutils via the functions
666 keyctl_get_security(3) and keyctl_get_security_alloc(3).
667 KEYCTL_SESSION_TO_PARENT (since Linux 2.6.32)
669 Replace the session keyring to which the parent of the calling
670 process subscribes with the session keyring of the calling
671 process.
672 The keyring will be replaced in the parent process at the point
674 where the parent next transitions from kernel space to user
675 space.
676 The keyring must exist and must grant the caller link permis‐
678 sion. The parent process must be single-threaded and have the
679 same effective ownership as this process and must not be set-
680 user-ID or set-group-ID. The UID of the parent process's exist‐
681 ing session keyring (f it has one), as well as the UID of the
682 caller's session keyring much match the caller's effective UID.
683 The fact that it is the parent process that is affected by this
685 operation allows a program such as the shell to start a child
686 process that uses this operation to change the shell's session
687 keyring. (This is what the keyctl(1) new_session command does.)
688 The arguments arg2, arg3, arg4, and arg5 are ignored.
690 This operation is exposed by libkeyutils via the function
692 keyctl_session_to_parent(3).
693 KEYCTL_REJECT (since Linux 2.6.39)
695 Mark a key as negatively instantiated and set an expiration
696 timer on the key. This operation provides a superset of the
697 functionality of the earlier KEYCTL_NEGATE operation.
698 The ID of the key that is to be negatively instantiated is spec‐
700 ified in arg2 (cast to key_serial_t). The arg3 (cast to un‐
701 signed int) argument specifies the lifetime of the key, in sec‐
702 onds. The arg4 argument (cast to unsigned int) specifies the
703 error to be returned when a search hits this key; typically,
704 this is one of EKEYREJECTED, EKEYREVOKED, or EKEYEXPIRED.
705 If arg5 (cast to key_serial_t) is nonzero, then, subject to the
707 same constraints and rules as KEYCTL_LINK, the negatively in‐
708 stantiated key is linked into the keyring whose ID is specified
709 in arg5.
710 The caller must have the appropriate authorization key. In
712 other words, this operation is available only from a re‐
713 quest-key(8)-style program. See request_key(2).
714 The caller must have the appropriate authorization key, and once
716 the uninstantiated key has been instantiated, the authorization
717 key is revoked. In other words, this operation is available
718 only from a request-key(8)-style program. See request_key(2)
719 for an explanation of uninstantiated keys and key instantiation.
720 This operation is exposed by libkeyutils via the function
722 keyctl_reject(3).
723 KEYCTL_INSTANTIATE_IOV (since Linux 2.6.39)
725 Instantiate an uninstantiated key with a payload specified via a
726 vector of buffers.
727 This operation is the same as KEYCTL_INSTANTIATE, but the pay‐
729 load data is specified as an array of iovec structures (see
730 iovec(3type)).
731 The pointer to the payload vector is specified in arg3 (cast as
733 const struct iovec *). The number of items in the vector is
734 specified in arg4 (cast as unsigned int).
735 The arg2 (key ID) and arg5 (keyring ID) are interpreted as for
737 KEYCTL_INSTANTIATE.
738 This operation is exposed by libkeyutils via the function
740 keyctl_instantiate_iov(3).
741 KEYCTL_INVALIDATE (since Linux 3.5)
743 Mark a key as invalid.
744 The ID of the key to be invalidated is specified in arg2 (cast
746 to key_serial_t).
747 To invalidate a key, the caller must have search permission on
749 the key.
750 This operation marks the key as invalid and schedules immediate
752 garbage collection. The garbage collector removes the invali‐
753 dated key from all keyrings and deletes the key when its refer‐
754 ence count reaches zero. After this operation, the key will be
755 ignored by all searches, even if it is not yet deleted.
756 Keys that are marked invalid become invisible to normal key op‐
758 erations immediately, though they are still visible in
759 /proc/keys (marked with an 'i' flag) until they are actually re‐
760 moved.
761 The arguments arg3, arg4, and arg5 are ignored.
763 This operation is exposed by libkeyutils via the function
765 keyctl_invalidate(3).
766 KEYCTL_GET_PERSISTENT (since Linux 3.13)
768 Get the persistent keyring (persistent-keyring(7)) for a speci‐
769 fied user and link it to a specified keyring.
770 The user ID is specified in arg2 (cast to uid_t). If the value
772 -1 is specified, the caller's real user ID is used. The ID of
773 the destination keyring is specified in arg3 (cast to key_se‐
774 rial_t).
775 The caller must have the CAP_SETUID capability in its user name‐
777 space in order to fetch the persistent keyring for a user ID
778 that does not match either the real or effective user ID of the
779 caller.
780 If the call is successful, a link to the persistent keyring is
782 added to the keyring whose ID was specified in arg3.
783 The caller must have write permission on the keyring.
785 The persistent keyring will be created by the kernel if it does
787 not yet exist.
788 Each time the KEYCTL_GET_PERSISTENT operation is performed, the
790 persistent keyring will have its expiration timeout reset to the
791 value in:
792 /proc/sys/kernel/keys/persistent_keyring_expiry
794 Should the timeout be reached, the persistent keyring will be
796 removed and everything it pins can then be garbage collected.
797 Persistent keyrings were added in Linux 3.13.
799 The arguments arg4 and arg5 are ignored.
801 This operation is exposed by libkeyutils via the function
803 keyctl_get_persistent(3).
804 KEYCTL_DH_COMPUTE (since Linux 4.7)
806 Compute a Diffie-Hellman shared secret or public key, optionally
807 applying key derivation function (KDF) to the result.
808 The arg2 argument is a pointer to a set of parameters containing
810 serial numbers for three "user" keys used in the Diffie-Hellman
811 calculation, packaged in a structure of the following form:
812 struct keyctl_dh_params {
814 int32_t private; /* The local private key */
815 int32_t prime; /* The prime, known to both parties */
816 int32_t base; /* The base integer: either a shared
817 generator or the remote public key */
818 };
819 Each of the three keys specified in this structure must grant
821 the caller read permission. The payloads of these keys are used
822 to calculate the Diffie-Hellman result as:
823 base ^ private mod prime
825 If the base is the shared generator, the result is the local
827 public key. If the base is the remote public key, the result is
828 the shared secret.
829 The arg3 argument (cast to char *) points to a buffer where the
831 result of the calculation is placed. The size of that buffer is
832 specified in arg4 (cast to size_t).
833 The buffer must be large enough to accommodate the output data,
835 otherwise an error is returned. If arg4 is specified zero, in
836 which case the buffer is not used and the operation returns the
837 minimum required buffer size (i.e., the length of the prime).
838 Diffie-Hellman computations can be performed in user space, but
840 require a multiple-precision integer (MPI) library. Moving the
841 implementation into the kernel gives access to the kernel MPI
842 implementation, and allows access to secure or acceleration
843 hardware.
844 Adding support for DH computation to the keyctl() system call
846 was considered a good fit due to the DH algorithm's use for de‐
847 riving shared keys; it also allows the type of the key to deter‐
848 mine which DH implementation (software or hardware) is appropri‐
849 ate.
850 If the arg5 argument is NULL, then the DH result itself is re‐
852 turned. Otherwise (since Linux 4.12), it is a pointer to a
853 structure which specifies parameters of the KDF operation to be
854 applied:
855 struct keyctl_kdf_params {
857 char *hashname; /* Hash algorithm name */
858 char *otherinfo; /* SP800-56A OtherInfo */
859 __u32 otherinfolen; /* Length of otherinfo data */
860 __u32 __spare[8]; /* Reserved */
861 };
862 The hashname field is a null-terminated string which specifies a
864 hash name (available in the kernel's crypto API; the list of the
865 hashes available is rather tricky to observe; please refer to
866 the "Kernel Crypto API Architecture" ⟨https://www.kernel.org/doc
867 /html/latest/crypto/architecture.html⟩ documentation for the in‐
868 formation regarding how hash names are constructed and your ker‐
869 nel's source and configuration regarding what ciphers and tem‐
870 plates with type CRYPTO_ALG_TYPE_SHASH are available) to be ap‐
871 plied to DH result in KDF operation.
872 The otherinfo field is an OtherInfo data as described in
874 SP800-56A section 5.8.1.2 and is algorithm-specific. This data
875 is concatenated with the result of DH operation and is provided
876 as an input to the KDF operation. Its size is provided in the
877 otherinfolen field and is limited by KEYCTL_KDF_MAX_OI_LEN con‐
878 stant that defined in security/keys/internal.h to a value of 64.
879 The __spare field is currently unused. It was ignored until
881 Linux 4.13 (but still should be user-addressable since it is
882 copied to the kernel), and should contain zeros since Linux
883 4.13.
884 The KDF implementation complies with SP800-56A as well as with
886 SP800-108 (the counter KDF).
887 This operation is exposed by libkeyutils (from libkeyutils
889 1.5.10 onwards) via the functions keyctl_dh_compute(3) and
890 keyctl_dh_compute_alloc(3).
891 KEYCTL_RESTRICT_KEYRING (since Linux 4.12)
893 Apply a key-linking restriction to the keyring with the ID pro‐
894 vided in arg2 (cast to key_serial_t). The caller must have se‐
895 tattr permission on the key. If arg3 is NULL, any attempt to
896 add a key to the keyring is blocked; otherwise it contains a
897 pointer to a string with a key type name and arg4 contains a
898 pointer to string that describes the type-specific restriction.
899 As of Linux 4.12, only the type "asymmetric" has restrictions
900 defined:
901 builtin_trusted
903 Allows only keys that are signed by a key linked to the
904 built-in keyring (".builtin_trusted_keys").
905 builtin_and_secondary_trusted
907 Allows only keys that are signed by a key linked to the
908 secondary keyring (".secondary_trusted_keys") or, by ex‐
909 tension, a key in a built-in keyring, as the latter is
910 linked to the former.
911 key_or_keyring:key
913 key_or_keyring:key:chain
914 If key specifies the ID of a key of type "asymmetric",
915 then only keys that are signed by this key are allowed.
916 If key specifies the ID of a keyring, then only keys that
918 are signed by a key linked to this keyring are allowed.
919 If ":chain" is specified, keys that are signed by a keys
921 linked to the destination keyring (that is, the keyring
922 with the ID specified in the arg2 argument) are also al‐
923 lowed.
924 Note that a restriction can be configured only once for the
926 specified keyring; once a restriction is set, it can't be over‐
927 ridden.
928 The argument arg5 is ignored.
930
932 For a successful call, the return value depends on the operation:
933 KEYCTL_GET_KEYRING_ID
935 The ID of the requested keyring.
936 KEYCTL_JOIN_SESSION_KEYRING
938 The ID of the joined session keyring.
939 KEYCTL_DESCRIBE
941 The size of the description (including the terminating null
942 byte), irrespective of the provided buffer size.
943 KEYCTL_SEARCH
945 The ID of the key that was found.
946 KEYCTL_READ
948 The amount of data that is available in the key, irrespective of
949 the provided buffer size.
950 KEYCTL_SET_REQKEY_KEYRING
952 The ID of the previous default keyring to which implicitly re‐
953 quested keys were linked (one of KEY_REQKEY_DEFL_USER_*).
954 KEYCTL_ASSUME_AUTHORITY
956 Either 0, if the ID given was 0, or the ID of the authorization
957 key matching the specified key, if a nonzero key ID was pro‐
958 vided.
959 KEYCTL_GET_SECURITY
961 The size of the LSM security label string (including the termi‐
962 nating null byte), irrespective of the provided buffer size.
963 KEYCTL_GET_PERSISTENT
965 The ID of the persistent keyring.
966 KEYCTL_DH_COMPUTE
968 The number of bytes copied to the buffer, or, if arg4 is 0, the
969 required buffer size.
970 All other operations
972 Zero.
973 On error, -1 is returned, and errno is set to indicate the error.
975
977 EACCES The requested operation wasn't permitted.
978 EAGAIN operation was KEYCTL_DH_COMPUTE and there was an error during
980 crypto module initialization.
981 EDEADLK
983 operation was KEYCTL_LINK and the requested link would result in
984 a cycle.
985 EDEADLK
987 operation was KEYCTL_RESTRICT_KEYRING and the requested keyring
988 restriction would result in a cycle.
989 EDQUOT The key quota for the caller's user would be exceeded by creat‐
991 ing a key or linking it to the keyring.
992 EEXIST operation was KEYCTL_RESTRICT_KEYRING and keyring provided in
994 arg2 argument already has a restriction set.
995 EFAULT operation was KEYCTL_DH_COMPUTE and one of the following has
997 failed:
998 • copying of the struct keyctl_dh_params, provided in the arg2
1000 argument, from user space;
1001 • copying of the struct keyctl_kdf_params, provided in the non-
1003 NULL arg5 argument, from user space (in case kernel supports
1004 performing KDF operation on DH operation result);
1005 • copying of data pointed by the hashname field of the struct
1007 keyctl_kdf_params from user space;
1008 • copying of data pointed by the otherinfo field of the struct
1010 keyctl_kdf_params from user space if the otherinfolen field
1011 was nonzero;
1012 • copying of the result to user space.
1014 EINVAL operation was KEYCTL_SETPERM and an invalid permission bit was
1016 specified in arg3.
1017 EINVAL operation was KEYCTL_SEARCH and the size of the description in
1019 arg4 (including the terminating null byte) exceeded 4096 bytes.
1020 EINVAL size of the string (including the terminating null byte) speci‐
1022 fied in arg3 (the key type) or arg4 (the key description) ex‐
1023 ceeded the limit (32 bytes and 4096 bytes respectively).
1024 EINVAL (before Linux 4.12)
1026 operation was KEYCTL_DH_COMPUTE, argument arg5 was non-NULL.
1027 EINVAL operation was KEYCTL_DH_COMPUTE And the digest size of the hash‐
1029 ing algorithm supplied is zero.
1030 EINVAL operation was KEYCTL_DH_COMPUTE and the buffer size provided is
1032 not enough to hold the result. Provide 0 as a buffer size in
1033 order to obtain the minimum buffer size.
1034 EINVAL operation was KEYCTL_DH_COMPUTE and the hash name provided in
1036 the hashname field of the struct keyctl_kdf_params pointed by
1037 arg5 argument is too big (the limit is implementation-specific
1038 and varies between kernel versions, but it is deemed big enough
1039 for all valid algorithm names).
1040 EINVAL operation was KEYCTL_DH_COMPUTE and the __spare field of the
1042 struct keyctl_kdf_params provided in the arg5 argument contains
1043 nonzero values.
1044 EKEYEXPIRED
1046 An expired key was found or specified.
1047 EKEYREJECTED
1049 A rejected key was found or specified.
1050 EKEYREVOKED
1052 A revoked key was found or specified.
1053 ELOOP operation was KEYCTL_LINK and the requested link would cause the
1055 maximum nesting depth for keyrings to be exceeded.
1056 EMSGSIZE
1058 operation was KEYCTL_DH_COMPUTE and the buffer length exceeds
1059 KEYCTL_KDF_MAX_OUTPUT_LEN (which is 1024 currently) or the oth‐
1060 erinfolen field of the struct keyctl_kdf_parms passed in arg5
1061 exceeds KEYCTL_KDF_MAX_OI_LEN (which is 64 currently).
1062 ENFILE (before Linux 3.13)
1064 operation was KEYCTL_LINK and the keyring is full. (Before
1065 Linux 3.13, the available space for storing keyring links was
1066 limited to a single page of memory; since Linux 3.13, there is
1067 no fixed limit.)
1068 ENOENT operation was KEYCTL_UNLINK and the key to be unlinked isn't
1070 linked to the keyring.
1071 ENOENT operation was KEYCTL_DH_COMPUTE and the hashing algorithm speci‐
1073 fied in the hashname field of the struct keyctl_kdf_params
1074 pointed by arg5 argument hasn't been found.
1075 ENOENT operation was KEYCTL_RESTRICT_KEYRING and the type provided in
1077 arg3 argument doesn't support setting key linking restrictions.
1078 ENOKEY No matching key was found or an invalid key was specified.
1080 ENOKEY The value KEYCTL_GET_KEYRING_ID was specified in operation, the
1082 key specified in arg2 did not exist, and arg3 was zero (meaning
1083 don't create the key if it didn't exist).
1084 ENOMEM One of kernel memory allocation routines failed during the exe‐
1086 cution of the syscall.
1087 ENOTDIR
1089 A key of keyring type was expected but the ID of a key with a
1090 different type was provided.
1091 EOPNOTSUPP
1093 operation was KEYCTL_READ and the key type does not support
1094 reading (e.g., the type is "login").
1095 EOPNOTSUPP
1097 operation was KEYCTL_UPDATE and the key type does not support
1098 updating.
1099 EOPNOTSUPP
1101 operation was KEYCTL_RESTRICT_KEYRING, the type provided in arg3
1102 argument was "asymmetric", and the key specified in the restric‐
1103 tion specification provided in arg4 has type other than "asym‐
1104 metric" or "keyring".
1105 EPERM operation was KEYCTL_GET_PERSISTENT, arg2 specified a UID other
1107 than the calling thread's real or effective UID, and the caller
1108 did not have the CAP_SETUID capability.
1109 EPERM operation was KEYCTL_SESSION_TO_PARENT and either: all of the
1111 UIDs (GIDs) of the parent process do not match the effective UID
1112 (GID) of the calling process; the UID of the parent's existing
1113 session keyring or the UID of the caller's session keyring did
1114 not match the effective UID of the caller; the parent process is
1115 not single-thread; or the parent process is init(1) or a kernel
1116 thread.
1117 ETIMEDOUT
1119 operation was KEYCTL_DH_COMPUTE and the initialization of crypto
1120 modules has timed out.
1121
1123 A wrapper is provided in the libkeyutils library. (The accompanying
1124 package provides the <keyutils.h> header file.) However, rather than
1125 using this system call directly, you probably want to use the various
1126 library functions mentioned in the descriptions of individual opera‐
1127 tions above.
1128
1130 Linux.
1131
1133 Linux 2.6.10.
1134
1136 The program below provide subset of the functionality of the re‐
1137 quest-key(8) program provided by the keyutils package. For informa‐
1138 tional purposes, the program records various information in a log file.
1139 As described in request_key(2), the request-key(8) program is invoked
1141 with command-line arguments that describe a key that is to be instanti‐
1142 ated. The example program fetches and logs these arguments. The pro‐
1143 gram assumes authority to instantiate the requested key, and then in‐
1144 stantiates that key.
1145 The following shell session demonstrates the use of this program. In
1147 the session, we compile the program and then use it to temporarily re‐
1148 place the standard request-key(8) program. (Note that temporarily dis‐
1149 abling the standard request-key(8) program may not be safe on some sys‐
1150 tems.) While our example program is installed, we use the example pro‐
1151 gram shown in request_key(2) to request a key.
1152 $ cc -o key_instantiate key_instantiate.c -lkeyutils
1154 $ sudo mv /sbin/request-key /sbin/request-key.backup
1155 $ sudo cp key_instantiate /sbin/request-key
1156 $ ./t_request_key user mykey somepayloaddata
1157 Key ID is 20d035bf
1158 $ sudo mv /sbin/request-key.backup /sbin/request-key
1159 Looking at the log file created by this program, we can see the com‐
1161 mand-line arguments supplied to our example program:
1162 $ cat /tmp/key_instantiate.log
1164 Time: Mon Nov 7 13:06:47 2016
1165 Command line arguments:
1167 argv[0]: /sbin/request-key
1168 operation: create
1169 key_to_instantiate: 20d035bf
1170 UID: 1000
1171 GID: 1000
1172 thread_keyring: 0
1173 process_keyring: 0
1174 session_keyring: 256e6a6
1175 Key description: user;1000;1000;3f010000;mykey
1177 Auth key payload: somepayloaddata
1178 Destination keyring: 256e6a6
1179 Auth key description: .request_key_auth;1000;1000;0b010000;20d035bf
1180 The last few lines of the above output show that the example program
1182 was able to fetch:
1183 • the description of the key to be instantiated, which included the
1185 name of the key (mykey);
1186 • the payload of the authorization key, which consisted of the data
1188 (somepayloaddata) passed to request_key(2);
1189 • the destination keyring that was specified in the call to re‐
1191 quest_key(2); and
1192 • the description of the authorization key, where we can see that the
1194 name of the authorization key matches the ID of the key that is to
1195 be instantiated (20d035bf).
1196 The example program in request_key(2) specified the destination keyring
1198 as KEY_SPEC_SESSION_KEYRING. By examining the contents of /proc/keys,
1199 we can see that this was translated to the ID of the destination
1200 keyring (0256e6a6) shown in the log output above; we can also see the
1201 newly created key with the name mykey and ID 20d035bf.
1202 $ cat /proc/keys | egrep 'mykey|256e6a6'
1204 0256e6a6 I--Q--- 194 perm 3f030000 1000 1000 keyring _ses: 3
1205 20d035bf I--Q--- 1 perm 3f010000 1000 1000 user mykey: 16
1206 Program source
1208 /* key_instantiate.c */
1210 #include <errno.h>
1212 #include <keyutils.h>
1213 #include <stdint.h>
1214 #include <stdio.h>
1215 #include <stdlib.h>
1216 #include <string.h>
1217 #include <sys/types.h>
1218 #include <time.h>
1219 #ifndef KEY_SPEC_REQUESTOR_KEYRING
1221 #define KEY_SPEC_REQUESTOR_KEYRING (-8)
1222 #endif
1223 int
1225 main(int argc, char *argv[])
1226 {
1227 int akp_size; /* Size of auth_key_payload */
1228 int auth_key;
1229 char dbuf[256];
1230 char auth_key_payload[256];
1231 char *operation;
1232 FILE *fp;
1233 gid_t gid;
1234 uid_t uid;
1235 time_t t;
1236 key_serial_t key_to_instantiate, dest_keyring;
1237 key_serial_t thread_keyring, process_keyring, session_keyring;
1238 if (argc != 8) {
1240 fprintf(stderr, "Usage: %s op key uid gid thread_keyring "
1241 "process_keyring session_keyring\n", argv[0]);
1242 exit(EXIT_FAILURE);
1243 }
1244 fp = fopen("/tmp/key_instantiate.log", "w");
1246 if (fp == NULL)
1247 exit(EXIT_FAILURE);
1248 setbuf(fp, NULL);
1250 t = time(NULL);
1252 fprintf(fp, "Time: %s\n", ctime(&t));
1253 /*
1255 * The kernel passes a fixed set of arguments to the program
1256 * that it execs; fetch them.
1257 */
1258 operation = argv[1];
1259 key_to_instantiate = atoi(argv[2]);
1260 uid = atoi(argv[3]);
1261 gid = atoi(argv[4]);
1262 thread_keyring = atoi(argv[5]);
1263 process_keyring = atoi(argv[6]);
1264 session_keyring = atoi(argv[7]);
1265 fprintf(fp, "Command line arguments:\n");
1267 fprintf(fp, " argv[0]: %s\n", argv[0]);
1268 fprintf(fp, " operation: %s\n", operation);
1269 fprintf(fp, " key_to_instantiate: %jx\n",
1270 (uintmax_t) key_to_instantiate);
1271 fprintf(fp, " UID: %jd\n", (intmax_t) uid);
1272 fprintf(fp, " GID: %jd\n", (intmax_t) gid);
1273 fprintf(fp, " thread_keyring: %jx\n",
1274 (uintmax_t) thread_keyring);
1275 fprintf(fp, " process_keyring: %jx\n",
1276 (uintmax_t) process_keyring);
1277 fprintf(fp, " session_keyring: %jx\n",
1278 (uintmax_t) session_keyring);
1279 fprintf(fp, "\n");
1280 /*
1282 * Assume the authority to instantiate the key named in argv[2].
1283 */
1284 if (keyctl(KEYCTL_ASSUME_AUTHORITY, key_to_instantiate) == -1) {
1285 fprintf(fp, "KEYCTL_ASSUME_AUTHORITY failed: %s\n",
1286 strerror(errno));
1287 exit(EXIT_FAILURE);
1288 }
1289 /*
1291 * Fetch the description of the key that is to be instantiated.
1292 */
1293 if (keyctl(KEYCTL_DESCRIBE, key_to_instantiate,
1294 dbuf, sizeof(dbuf)) == -1) {
1295 fprintf(fp, "KEYCTL_DESCRIBE failed: %s\n", strerror(errno));
1296 exit(EXIT_FAILURE);
1297 }
1298 fprintf(fp, "Key description: %s\n", dbuf);
1300 /*
1302 * Fetch the payload of the authorization key, which is
1303 * actually the callout data given to request_key().
1304 */
1305 akp_size = keyctl(KEYCTL_READ, KEY_SPEC_REQKEY_AUTH_KEY,
1306 auth_key_payload, sizeof(auth_key_payload));
1307 if (akp_size == -1) {
1308 fprintf(fp, "KEYCTL_READ failed: %s\n", strerror(errno));
1309 exit(EXIT_FAILURE);
1310 }
1311 auth_key_payload[akp_size] = '\0';
1313 fprintf(fp, "Auth key payload: %s\n", auth_key_payload);
1314 /*
1316 * For interest, get the ID of the authorization key and
1317 * display it.
1318 */
1319 auth_key = keyctl(KEYCTL_GET_KEYRING_ID,
1320 KEY_SPEC_REQKEY_AUTH_KEY);
1321 if (auth_key == -1) {
1322 fprintf(fp, "KEYCTL_GET_KEYRING_ID failed: %s\n",
1323 strerror(errno));
1324 exit(EXIT_FAILURE);
1325 }
1326 fprintf(fp, "Auth key ID: %jx\n", (uintmax_t) auth_key);
1328 /*
1330 * Fetch key ID for the request_key(2) destination keyring.
1331 */
1332 dest_keyring = keyctl(KEYCTL_GET_KEYRING_ID,
1333 KEY_SPEC_REQUESTOR_KEYRING);
1334 if (dest_keyring == -1) {
1335 fprintf(fp, "KEYCTL_GET_KEYRING_ID failed: %s\n",
1336 strerror(errno));
1337 exit(EXIT_FAILURE);
1338 }
1339 fprintf(fp, "Destination keyring: %jx\n", (uintmax_t) dest_keyring);
1341 /*
1343 * Fetch the description of the authorization key. This
1344 * allows us to see the key type, UID, GID, permissions,
1345 * and description (name) of the key. Among other things,
1346 * we will see that the name of the key is a hexadecimal
1347 * string representing the ID of the key to be instantiated.
1348 */
1349 if (keyctl(KEYCTL_DESCRIBE, KEY_SPEC_REQKEY_AUTH_KEY,
1350 dbuf, sizeof(dbuf)) == -1)
1351 {
1352 fprintf(fp, "KEYCTL_DESCRIBE failed: %s\n", strerror(errno));
1353 exit(EXIT_FAILURE);
1354 }
1355 fprintf(fp, "Auth key description: %s\n", dbuf);
1357 /*
1359 * Instantiate the key using the callout data that was supplied
1360 * in the payload of the authorization key.
1361 */
1362 if (keyctl(KEYCTL_INSTANTIATE, key_to_instantiate,
1363 auth_key_payload, akp_size + 1, dest_keyring) == -1)
1364 {
1365 fprintf(fp, "KEYCTL_INSTANTIATE failed: %s\n",
1366 strerror(errno));
1367 exit(EXIT_FAILURE);
1368 }
1369 exit(EXIT_SUCCESS);
1371 }
1372
1374 keyctl(1), add_key(2), request_key(2), keyctl(3),
1375 keyctl_assume_authority(3), keyctl_chown(3), keyctl_clear(3),
1376 keyctl_describe(3), keyctl_describe_alloc(3), keyctl_dh_compute(3),
1377 keyctl_dh_compute_alloc(3), keyctl_get_keyring_ID(3),
1378 keyctl_get_persistent(3), keyctl_get_security(3),
1379 keyctl_get_security_alloc(3), keyctl_instantiate(3),
1380 keyctl_instantiate_iov(3), keyctl_invalidate(3),
1381 keyctl_join_session_keyring(3), keyctl_link(3), keyctl_negate(3),
1382 keyctl_read(3), keyctl_read_alloc(3), keyctl_reject(3),
1383 keyctl_revoke(3), keyctl_search(3), keyctl_session_to_parent(3),
1384 keyctl_set_reqkey_keyring(3), keyctl_set_timeout(3), keyctl_setperm(3),
1385 keyctl_unlink(3), keyctl_update(3), recursive_key_scan(3),
1386 recursive_session_key_scan(3), capabilities(7), credentials(7),
1387 keyrings(7), keyutils(7), persistent-keyring(7), process-keyring(7),
1388 session-keyring(7), thread-keyring(7), user-keyring(7),
1389 user_namespaces(7), user-session-keyring(7), request-key(8)
1390 The kernel source files under Documentation/security/keys/ (or, before
1392 Linux 4.13, in the file Documentation/security/keys.txt).
1393Linux man-pages 6.04 2023-03-30 keyctl(2)