1 .\" Copyright (C) 2016 Michael Kerrisk <mtk.manpages@gmail.com>
2 .\" and Copyright (C) 2016 Eugene Syromyatnikov <evgsyr@gmail.com>
3 .\" A very few fragments remain from an earlier version of this page
4 .\" written by David Howells (dhowells@redhat.com)
6 .\" %%%LICENSE_START(VERBATIM)
7 .\" Permission is granted to make and distribute verbatim copies of this
8 .\" manual provided the copyright notice and this permission notice are
9 .\" preserved on all copies.
11 .\" Permission is granted to copy and distribute modified versions of this
12 .\" manual under the conditions for verbatim copying, provided that the
13 .\" entire resulting derived work is distributed under the terms of a
14 .\" permission notice identical to this one.
16 .\" Since the Linux kernel and libraries are constantly changing, this
17 .\" manual page may be incorrect or out-of-date. The author(s) assume no
18 .\" responsibility for errors or omissions, or for damages resulting from
19 .\" the use of the information contained herein. The author(s) may not
20 .\" have taken the same level of care in the production of this manual,
21 .\" which is licensed free of charge, as they might when working
24 .\" Formatted or processed versions of this manual, if unaccompanied by
25 .\" the source, must acknowledge the copyright and authors of this work.
28 .TH KEYCTL 2 2017-03-13 Linux "Linux Key Management Calls"
30 keyctl \- manipulate the kernel's key management facility
33 .B #include <sys/types.h>
34 .B #include <keyutils.h>
36 .BI "long keyctl(int " operation ", ...)"
38 .B "/* For direct call via syscall(2): */"
39 .B #include <asm/unistd.h>
40 .B #include <linux/keyctl.h>
41 .B #include <unistd.h>
43 .BI "long syscall(__NR_keyctl, int " operation ", __kernel_ulong_t " arg2 ,
44 .BI " __kernel_ulong_t " arg3 ", __kernel_ulong_t " arg4 ,
45 .BI " __kernel_ulong_t " arg5 );
48 No glibc wrapper is provided for this system call; see NOTES.
51 allows user-space programs to perform key manipulation.
53 The operation performed by
55 is determined by the value of the
58 Each of these operations is wrapped by the
60 library (provided by the
62 package) into individual functions (noted below)
63 to permit the compiler to check types.
65 The permitted values for
69 .BR KEYCTL_GET_KEYRING_ID " (since Linux 2.6.10)"
70 Map a special key ID to a real key ID for this process.
72 This operation looks up the special key whose ID is provided in
76 If the special key is found,
77 the ID of the corresponding real key is returned as the function result.
78 The following values may be specified in
82 .B KEY_SPEC_THREAD_KEYRING
83 This specifies the calling thread's thread-specific keyring.
85 .BR thread-keyring (7).
87 .B KEY_SPEC_PROCESS_KEYRING
88 This specifies the caller's process-specific keyring.
90 .BR process-keyring (7).
92 .B KEY_SPEC_SESSION_KEYRING
93 This specifies the caller's session-specific keyring.
95 .BR session-keyring (7).
97 .B KEY_SPEC_USER_KEYRING
98 This specifies the caller's UID-specific keyring.
100 .BR user-keyring (7).
102 .B KEY_SPEC_USER_SESSION_KEYRING
103 This specifies the caller's UID-session keyring.
105 .BR user-session-keyring (7).
107 .BR KEY_SPEC_REQKEY_AUTH_KEY " (since Linux 2.6.16)"
108 .\" commit b5f545c880a2a47947ba2118b2509644ab7a2969
109 This specifies the authorization key created by
111 and passed to the process it spawns to generate a key.
112 This key is available only in a
113 .BR request-key (8)-style
114 program that was passed an authorization key by the kernel and
115 ceases to be available once the requested key has been instantiated; see
118 .BR KEY_SPEC_REQUESTOR_KEYRING " (since Linux 2.6.29)"
119 .\" commit 8bbf4976b59fc9fc2861e79cab7beb3f6d647640
120 This specifies the key ID for the
123 This keyring is available only in a
124 .BR request-key (8)-style
125 program that was passed an authorization key by the kernel and
126 ceases to be available once the requested key has been instantiated; see
130 The behavior if the key specified in
132 does not exist depends on the value of
138 contains a non-zero value, then\(emif it is appropriate to do so
139 (e.g., when looking up the user, user-session, or session key)\(ema new key
140 is created and its real key ID returned as the function result.
141 .\" The keyctl_get_keyring_ID.3 page says that a new key
142 .\" "will be created *if it is appropriate to do so**. What is the
143 .\" determiner for appropriate?
144 .\" David Howells: Some special keys such as KEY_SPEC_REQKEY_AUTH_KEY
145 .\" wouldn't get created but user/user-session/session keyring would
147 Otherwise, the operation fails with the error
150 If a valid key ID is specified in
152 and the key exists, then this operation simply returns the key ID.
153 If the key does not exist, the call fails with error
158 permission on a keyring in order for it to be found.
166 This operation is exposed by
169 .BR keyctl_get_keyring_ID (3).
171 .BR KEYCTL_JOIN_SESSION_KEYRING " (since Linux 2.6.10)"
172 Replace the session keyring this process subscribes to with
173 a new session keyring.
174 .\" This may be useful in conjunction with some sort of
175 .\" session management framework that is employed by the application.
180 an anonymous keyring with the description "_ses" is created
181 and the process is subscribed to that keyring as its session keyring,
182 displacing the previous session keyring.
188 is treated as the description (name) of a keyring,
189 and the behavior is as follows:
192 If a keyring with a matching description exists,
193 the process will attempt to subscribe to that keyring
194 as its session keyring if possible;
195 if that is not possible, an error is returned.
196 In order to subscribe to the keyring,
199 permission on the keyring.
201 If a keyring with a matching description does not exist,
202 then a new keyring with the specified description is created,
203 and the process is subscribed to that keyring as its session keyring.
213 This operation is exposed by
216 .BR keyctl_join_session_keyring (3).
218 .BR KEYCTL_UPDATE " (since Linux 2.6.10)"
219 Update a key's data payload.
225 specifies the ID of the key to be updated.
230 points to the new payload and
234 contains the new payload size in bytes.
238 permission on the key specified and the key type must support updating.
240 A negatively instantiated key (see the description of
242 can be positively instantiated with this operation.
248 This operation is exposed by
251 .BR keyctl_update (3).
253 .BR KEYCTL_REVOKE " (since Linux 2.6.10)"
254 Revoke the key with the ID provided in
258 The key is scheduled for garbage collection;
259 it will no longer be findable,
260 and will be unavailable for further operations.
261 Further attempts to use the key will fail with the error
268 permission on the key.
269 .\" Keys with the KEY_FLAG_KEEP bit set cause an EPERM
270 .\" error for KEYCTL_REVOKE. Does this need to be documented?
271 .\" David Howells: No significance for user space.
280 This operation is exposed by
283 .BR keyctl_revoke (3).
285 .BR KEYCTL_CHOWN " (since Linux 2.6.10)"
286 Change the ownership (user and group ID) of a key.
297 contains the new user ID (or \-1 in case the user ID shouldn't be changed).
302 contains the new group ID (or \-1 in case the group ID shouldn't be changed).
304 The key must grant the caller
308 For the UID to be changed, or for the GID to be changed to a group
309 the caller is not a member of, the caller must have the
312 .BR capabilities (7)).
314 If the UID is to be changed, the new user must have sufficient
315 quota to accept the key.
316 The quota deduction will be removed from the old user
317 to the new user should the UID be changed.
323 This operation is exposed by
326 .BR keyctl_chown (3).
328 .BR KEYCTL_SETPERM " (since Linux 2.6.10)"
329 Change the permissions of the key with the ID provided in the
333 to the permissions provided in the
338 If the caller doesn't have the
340 capability, it can change permissions only for the keys it owns.
341 (More precisely: the caller's filesystem UID must match the UID of the key.)
345 permission to the caller
347 of the caller's capabilities.
348 .\" FIXME Above, is it really intended that a privileged process can't
349 .\" override the lack of the 'setattr' permission?
353 specify masks of available operations
354 for each of the following user categories:
357 .IR possessor " (since Linux 2.6.14)"
358 .\" commit 664cceb0093b755739e56572b836a99104ee8a75
359 This is the permission granted to a process that possesses the key
360 (has it attached searchably to one of the process's keyrings);
365 This is the permission granted to a process
366 whose filesystem UID matches the UID of the key.
369 This is the permission granted to a process
370 whose filesystem GID or any of its supplementary GIDs
371 matches the GID of the key.
374 This is the permission granted to other processes
375 that do not match the
387 categories are exclusive: if a process matches the
389 category, it will not receive permissions granted in the
391 category; if a process matches the
395 category, then it will not receive permissions granted in the
401 category grants permissions that are cumulative with the grants from the
408 Each permission mask is eight bits in size,
409 with only six bits currently used.
410 The available permissions are:
414 This permission allows reading attributes of a key.
416 This permission is required for the
420 The permission bits for each category are
428 This permission allows reading a key's payload.
430 This permission is required for the
434 The permission bits for each category are
442 This permission allows update or instantiation of a key's payload.
443 For a keyring, it allows keys to be linked and unlinked from the keyring,
445 This permission is required for the
454 The permission bits for each category are
462 This permission allows keyrings to be searched and keys to be found.
463 Searches can recurse only into nested keyrings that have
467 This permission is required for the
468 .BR KEYCTL_GET_KEYRING_ID ,
469 .BR KEYCTL_JOIN_SESSION_KEYRING ,
472 .BR KEYCTL_INVALIDATE
475 The permission bits for each category are
483 This permission allows a key or keyring to be linked to.
485 This permission is required for the
488 .BR KEYCTL_SESSION_TO_PARENT
491 The permission bits for each category are
498 .IR setattr " (since Linux 2.6.15)."
499 This permission allows a key's UID, GID, and permissions mask to be changed.
501 This permission is required for the
508 The permission bits for each category are
509 .BR KEY_POS_SETATTR ,
510 .BR KEY_USR_SETATTR ,
511 .BR KEY_GRP_SETATTR ,
513 .BR KEY_OTH_SETATTR .
516 As a convenience, the following macros are defined as masks for
517 all of the permission bits in each of the user categories:
525 .IR arg4 " and " arg5
526 arguments are ignored.
528 This operation is exposed by
531 .BR keyctl_setperm (3).
533 .BR KEYCTL_DESCRIBE " (since Linux 2.6.10)"
534 Obtain a string describing the attributes of a specified key.
536 The ID of the key to be described is specified in
540 The descriptive string is returned in the buffer pointed to by
547 specifies the size of that buffer in bytes.
549 The key must grant the caller
553 The returned string is null-terminated and
554 contains the following information about the key:
557 .IR type ; uid ; gid ; perm ; description
568 are decimal strings, and
570 is a hexadecimal permissions mask.
571 The descriptive string is written with the following format:
575 .BR "Note: the intention is that the descriptive string should"
576 .BR "be extensible in future kernel versions".
579 field will not contain semicolons;
580 .\" FIXME But, the kernel does not enforce the requirement
581 .\" that the key description contains no semicolons!
582 .\" So, user space has no guarantee here??
583 .\" Either something more needs to be said here,
584 .\" or a kernel fix is required.
585 it should be parsed by working backwards from the end of the string
586 to find the last semicolon.
587 This allows future semicolon-delimited fields to be inserted
588 in the descriptive string in the future.
590 Writing to the buffer is attempted only when
592 is non-NULL and the specified buffer size
593 is large enough to accept the descriptive string
594 (including the terminating null byte).
595 '\" Function commentary says it copies up to buflen bytes, but see the
596 '\" (buffer && buflen >= ret) condition in keyctl_describe_key() in
597 '\" security/keyctl.c
598 In order to determine whether the buffer size was too small,
599 check to see if the return value of the operation is greater than
606 This operation is exposed by
609 .BR keyctl_describe (3).
612 Clear the contents of (i.e., unlink all keys from) a keyring.
615 (which must be of keyring type)
616 .\" or the error ENOTDIR results
621 .\" According to Documentation/security/keys.txt:
622 .\" This function can also be used to clear special kernel keyrings if they
623 .\" are appropriately marked if the user has CAP_SYS_ADMIN capability. The
624 .\" DNS resolver cache keyring is an example of this.
628 permission on the keyring.
637 This operation is exposed by
640 .BR keyctl_clear (3).
642 .BR KEYCTL_LINK " (since Linux 2.6.10)"
643 Create a link from a keyring to a key.
645 The key to be linked is specified in
649 the keyring is specified in
654 If a key with the same type and description is already linked in the keyring,
655 then that key is displaced from the keyring.
657 Before creating the link,
658 the kernel checks the nesting of the keyrings and returns appropriate errors
659 if the link would produce a cycle
660 or if the nesting of keyrings would be too deep
661 (The limit on the nesting of keyrings is determined by the kernel constant
662 .BR KEYRING_SEARCH_MAX_DEPTH ,
663 defined with the value 6, and is necessary to prevent overflows
664 on the kernel stack when recursively searching keyrings).
668 permission on the key being added and
670 permission on the keyring.
678 This operation is exposed by
683 .BR KEYCTL_UNLINK " (since Linux 2.6.10)"
684 Unlink a key from a keyring.
686 The ID of the key to be unlinked is specified in
690 the ID of the keyring from which it is to be unlinked is specified in
695 If the key is not currently linked into the keyring, an error results.
699 permission on the keyring from which the key is being removed.
701 If the last link to a key is removed,
702 then that key will be scheduled for destruction.
710 This operation is exposed by
713 .BR keyctl_unlink (3).
715 .BR KEYCTL_SEARCH " (since Linux 2.6.10)"
716 Search for a key in a keyring tree,
717 returning its ID and optionally linking it to a specified keyring.
719 The tree to be searched is specified by passing
720 the ID of the head keyring in
724 The search is performed breadth-first and recursively.
730 arguments specify the key to be searched for:
734 contains the key type
735 (a null-terminated character string up to 32 bytes in size,
736 including the terminating null byte), and
740 contains the description of the key
741 (a null-terminated character string up to 4096 bytes in size,
742 including the terminating null byte).
744 The source keyring must grant
746 permission to the caller.
747 When performing the recursive search, only keyrings that grant the caller
749 permission will be searched.
750 Only keys with for which the caller has
752 permission can be found.
754 If the key is found, its ID is returned as the function result.
756 If the key is found and
760 is nonzero, then, subject to the same constraints and rules as
762 the key is linked into the keyring whose ID is specified in
764 If the destination keyring specified in
766 already contains a link to a key that has the same type and description,
767 then that link will be displaced by a link to
768 the key found by this operation.
770 Instead of valid existing keyring IDs, the source
774 keyrings can be one of the special keyring IDs listed under
775 .BR KEYCTL_GET_KEYRING_ID .
777 This operation is exposed by
780 .BR keyctl_search (3).
782 .BR KEYCTL_READ " (since Linux 2.6.10)"
783 Read the payload data of a key.
785 The ID of the key whose payload is to be read is specified in
789 This can be the ID of an existing key,
790 or any of the special key IDs listed for
791 .BR KEYCTL_GET_KEYRING_ID .
792 .\" including KEY_SPEC_REQKEY_AUTH_KEY
794 The payload is placed in the buffer pointed by
798 the size of that buffer must be specified in
803 The returned data will be processed for presentation
804 according to the key type.
805 For example, a keyring will return an array of
807 entries representing the IDs of all the keys that are linked to it.
810 key type will return its data as is.
811 If a key type does not implement this function,
812 the operation fails with the error
818 as much of the payload data as will fit is copied into the buffer.
819 On a successful return,
820 the return value is always the total size of the payload data.
821 To determine whether the buffer was of sufficient size,
822 check to see that the return value is less than or equal to
823 the value supplied in
826 The key must either grant the caller
828 permission, or grant the caller
830 permission when searched for from the process keyrings
831 (i.e., the key is possessed).
837 This operation is exposed by
842 .BR KEYCTL_INSTANTIATE " (since Linux 2.6.10)"
843 (Positively) instantiate an uninstantiated key with a specified payload.
845 The ID of the key to be instantiated is provided in
850 The key payload is specified in the buffer pointed to by
854 the size of that buffer is specified in
859 The payload may be a NULL pointer and the buffer size may be 0
860 if this is supported by the key type (e.g., it is a keyring).
862 The operation may be fail if the payload data is in the wrong format
863 or is otherwise invalid.
869 is nonzero, then, subject to the same constraints and rules as
871 the instantiated key is linked into the keyring whose ID specified in
874 The caller must have the appropriate authorization key,
875 and once the uninstantiated key has been instantiated,
876 the authorization key is revoked.
877 In other words, this operation is available only from a
878 .BR request-key (8)-style
882 for an explanation of uninstantiated keys and key instantiation.
884 This operation is exposed by
887 .BR keyctl_instantiate (3).
889 .BR KEYCTL_NEGATE " (since Linux 2.6.10)"
890 Negatively instantiate an uninstantiated key.
892 This operation is equivalent to the call:
894 keyctl(KEYCTL_REJECT, arg2, arg3, ENOKEY, arg4);
900 This operation is exposed by
903 .BR keyctl_negate (3).
905 .BR KEYCTL_SET_REQKEY_KEYRING " (since Linux 2.6.13)"
906 Set the default keyring to which implicitly requested keys
907 will be linked for this thread, and return the previous setting.
908 Implicit key requests are those made by internal kernel components,
909 .\" I.e., calls to the kernel's internal request_key() interface,
910 .\" which is distinct from the request_key(2) system call (which
911 .\" ultimately employs the kernel-internal interface).
912 such as can occur when, for example, opening files
913 on an AFS or NFS filesystem.
914 Setting the default keyring also has an effect when requesting
915 a key from user space; see
923 should contain one of the following values,
924 to specify the new default keyring:
927 .BR KEY_REQKEY_DEFL_NO_CHANGE
928 Don't change the default keyring.
929 This can be used to discover the current default keyring
930 (without changing it).
932 .BR KEY_REQKEY_DEFL_DEFAULT
933 This selects the default behaviour,
934 which is to use the thread-specific keyring if there is one,
935 otherwise the process-specific keyring if there is one,
936 otherwise the session keyring if there is one,
937 otherwise the UID-specific session keyring,
938 otherwise the user-specific keyring.
940 .BR KEY_REQKEY_DEFL_THREAD_KEYRING
941 Use the thread-specific keyring
942 .RB ( thread-keyring (7))
943 as the new default keyring.
945 .BR KEY_REQKEY_DEFL_PROCESS_KEYRING
946 Use the process-specific keyring
947 .RB ( process-keyring (7))
948 as the new default keyring.
950 .BR KEY_REQKEY_DEFL_SESSION_KEYRING
951 Use the session-specific keyring
952 .RB ( session-keyring (7))
953 as the new default keyring.
955 .BR KEY_REQKEY_DEFL_USER_KEYRING
956 Use the UID-specific keyring
957 .RB ( user-keyring (7))
958 as the new default keyring.
960 .BR KEY_REQKEY_DEFL_USER_SESSION_KEYRING
961 Use the UID-specific session keyring
962 .RB ( user-session-keyring (7))
963 as the new default keyring.
965 .BR KEY_REQKEY_DEFL_REQUESTOR_KEYRING " (since Linux 2.6.29)"
966 '\" 8bbf4976b59fc9fc2861e79cab7beb3f6d647640
967 Use the requestor keyring.
968 .\" FIXME The preceding explanation needs to be expanded.
969 .\" Is the following correct:
971 .\" The requestor keyring is the dest_keyring that
972 .\" was supplied to a call to request_key(2)?
974 .\" David Howells said: to be checked
977 All other values are invalid.
978 .\" (including the still-unsupported KEY_REQKEY_DEFL_GROUP_KEYRING)
987 The setting controlled by this operation is inherited by the child of
992 This operation is exposed by
995 .BR keyctl_set_reqkey_keyring (3).
997 .BR KEYCTL_SET_TIMEOUT " (since Linux 2.6.16)"
998 Set a timeout on a key.
1000 The ID of the key is specified in
1004 The timeout value, in seconds from the current time,
1008 .IR "unsigned int" ).
1009 The timeout is measured against the realtime clock.
1011 Specifying the timeout value as 0 clears any existing timeout on the key.
1015 file displays the remaining time until each key will expire.
1016 (This is the only method of discovering the timeout on a key.)
1018 The caller must either have the
1020 permission on the key
1021 or hold an instantiation authorization token for the key (see
1022 .BR request_key (2)).
1024 The key and any links to the key will be
1025 automatically garbage collected after the timeout expires.
1026 Subsequent attempts to access the key will then fail with the error
1029 This operation cannot be used to set timeouts on revoked, expired,
1030 or negatively instantiated keys.
1038 This operation is exposed by
1041 .BR keyctl_set_timeout (3).
1043 .BR KEYCTL_ASSUME_AUTHORITY " (since Linux 2.6.16)"
1044 Assume (or divest) the authority for the calling thread
1045 to instantiate a key.
1051 specifies either a nonzero key ID to assume authority,
1052 or the value 0 to divest authority.
1056 is nonzero, then it specifies the ID of an uninstantiated key for which
1057 authority is to be assumed.
1058 That key can then be instantiated using one of
1059 .BR KEYCTL_INSTANTIATE ,
1060 .BR KEYCTL_INSTANTIATE_IOV ,
1064 Once the key has been instantiated,
1065 the thread is automatically divested of authority to instantiate the key.
1067 Authority over a key can be assumed only if the calling thread has present
1068 in its keyrings the authorization key that is
1069 associated with the specified key.
1070 (In other words, the
1071 .BR KEYCTL_ASSUME_AUTHORITY
1072 operation is available only from a
1073 .BR request-key (8)-style
1076 for an explanation of how this operation is used.)
1077 The caller must have
1079 permission on the authorization key.
1081 If the specified key has a matching authorization key,
1082 then the ID of that key is returned.
1083 The authorization key can be read
1085 to obtain the callout information passed to
1086 .BR request_key (2).
1090 is 0, then the currently assumed authority is cleared (divested),
1091 and the value 0 is returned.
1094 .BR KEYCTL_ASSUME_AUTHORITY
1095 mechanism allows a program such as
1097 to assume the necessary authority to instantiate a new uninstantiated key
1098 that was created as a consequence of a call to
1099 .BR request_key (2).
1100 For further information, see
1102 and the kernel source file
1103 .IR Documentation/security/keys-request-key.txt .
1112 This operation is exposed by
1115 .BR keyctl_assume_authority (3).
1117 .BR KEYCTL_GET_SECURITY " (since Linux 2.6.26)"
1118 .\" commit 70a5bb72b55e82fbfbf1e22cae6975fac58a1e2d
1119 Get the LSM (Linux Security Module) security label of the specified key.
1121 The ID of the key whose security label is to be fetched is specified in
1125 The security label (terminated by a null byte)
1126 will be placed in the buffer pointed to by
1130 the size of the buffer must be provided in
1137 is specified as NULL or the buffer size specified in
1139 is too small, the full size of the security label string
1140 (including the terminating null byte)
1141 is returned as the function result,
1142 and nothing is copied to the buffer.
1144 The caller must have
1146 permission on the specified key.
1148 The returned security label string will be rendered in a form appropriate
1149 to the LSM in force.
1150 For example, with SELinux, it may look like:
1152 unconfined_u:unconfined_r:unconfined_t:s0-s0:c0.c1023
1154 If no LSM is currently in force,
1155 then an empty string is placed in the buffer.
1159 argument is ignored.
1161 This operation is exposed by
1164 .BR keyctl_get_security (3)
1166 .BR keyctl_get_security_alloc (3).
1168 .BR KEYCTL_SESSION_TO_PARENT " (since Linux 2.6.32)"
1169 .\" commit ee18d64c1f632043a02e6f5ba5e045bb26a5465f
1170 Replace the session keyring to which the
1172 of the calling process
1173 subscribes with the session keyring of the calling process.
1174 .\" What is the use case for KEYCTL_SESSION_TO_PARENT?
1175 .\" David Howells: the Process Authentication Groups people requested this,
1176 .\" but then didn't use it; maybe there are no users.
1178 The keyring will be replaced in the parent process at the point
1179 where the parent next transitions from kernel space to user space.
1181 The keyring must exist and must grant the caller
1184 The parent process must be single-threaded and have
1185 the same effective ownership as this process
1186 and must not be set-user-ID or set-group-ID.
1187 The UID of the parent process's existing session keyring (f it has one),
1188 as well as the UID of the caller's session keyring
1189 much match the caller's effective UID.
1191 The fact that it is the parent process that is affected by this operation
1192 allows a program such as the shell to start a child process that
1193 uses this operation to change the shell's session keyring.
1207 This operation is exposed by
1210 .BR keyctl_session_to_parent (3).
1212 .BR KEYCTL_REJECT " (since Linux 2.6.39)"
1213 .\" commit fdd1b94581782a2ddf9124414e5b7a5f48ce2f9c
1214 Mark a key as negatively instantiated and set an expiration timer
1216 This operation provides a superset of the functionality of the earlier
1220 The ID of the key that is to be negatively instantiated is specified in
1227 .IR "unsigned int" )
1228 argument specifies the lifetime of the key, in seconds.
1232 .IR "unsigned int" )
1233 specifies the error to be returned when a search hits this key;
1234 typically, this is one of
1244 is nonzero, then, subject to the same constraints and rules as
1246 the negatively instantiated key is linked into the keyring
1247 whose ID is specified in
1250 The caller must have the appropriate authorization key.
1251 In other words, this operation is available only from a
1252 .BR request-key (8)-style
1255 .BR request_key (2).
1257 The caller must have the appropriate authorization key,
1258 and once the uninstantiated key has been instantiated,
1259 the authorization key is revoked.
1260 In other words, this operation is available only from a
1261 .BR request-key (8)-style
1265 for an explanation of uninstantiated keys and key instantiation.
1267 This operation is exposed by
1270 .BR keyctl_reject (3).
1272 .BR KEYCTL_INSTANTIATE_IOV " (since Linux 2.6.39)"
1273 .\" commit ee009e4a0d4555ed522a631bae9896399674f063
1274 Instantiate an uninstantiated key with a payload specified
1275 via a vector of buffers.
1277 This operation is the same as
1278 .BR KEYCTL_INSTANTIATE ,
1279 but the payload data is specified as an array of
1286 void *iov_base; /* Starting address of buffer */
1287 size_t iov_len; /* Size of buffer (in bytes) */
1292 The pointer to the payload vector is specified in
1295 .IR "const struct iovec\ *" ).
1296 The number of items in the vector is specified in
1299 .IR "unsigned int" ).
1307 are interpreted as for
1308 .BR KEYCTL_INSTANTIATE .
1310 This operation is exposed by
1313 .BR keyctl_instantiate_iov (3).
1315 .BR KEYCTL_INVALIDATE " (since Linux 3.5)"
1316 .\" commit fd75815f727f157a05f4c96b5294a4617c0557da
1317 Mark a key as invalid.
1319 The ID of the key to be invalidated is specified in
1324 To invalidate a key,
1325 the caller must have
1327 permission on the key.
1328 .\" CAP_SYS_ADMIN is permitted to invalidate certain special keys
1330 This operation marks the key as invalid
1331 and schedules immediate garbage collection.
1332 The garbage collector removes the invalidated key from all keyrings and
1333 deletes the key when its reference count reaches zero.
1334 After this operation,
1335 the key will be ignored by all searches,
1336 even if it is not yet deleted.
1338 Keys that are marked invalid become invisible to normal key operations
1339 immediately, though they are still visible in
1341 (marked with an 'i' flag)
1342 until they are actually removed.
1351 This operation is exposed by
1354 .BR keyctl_invalidate (3).
1356 .BR KEYCTL_GET_PERSISTENT " (since Linux 3.13)"
1357 .\" commit f36f8c75ae2e7d4da34f4c908cebdb4aa42c977e
1358 Get the persistent keyring
1359 .RB ( persistent-keyring (7))
1360 for a specified user and link it to a specified keyring.
1362 The user ID is specified in
1366 If the value \-1 is specified, the caller's real user ID is used.
1367 The ID of the destination keyring is specified in
1372 The caller must have the
1374 capability in its user namespace in order to fetch the persistent keyring
1375 for a user ID that does not match either the real or effective user ID
1378 If the call is successful,
1379 a link to the persistent keyring is added to the keyring
1380 whose ID was specified in
1383 The caller must have
1385 permission on the keyring.
1387 The persistent keyring will be created by the kernel
1388 if it does not yet exist.
1391 .B KEYCTL_GET_PERSISTENT
1392 operation is performed, the persistent keyring will
1393 have its expiration timeout reset to the value in:
1395 /proc/sys/kernel/keys/persistent_keyring_expiry
1397 Should the timeout be reached,
1398 the persistent keyring will be removed and
1399 everything it pins can then be garbage collected.
1401 Persistent keyrings were added to Linux in kernel version 3.13.
1409 This operation is exposed by
1412 .BR keyctl_get_persistent (3).
1414 .BR KEYCTL_DH_COMPUTE " (since Linux 4.7)"
1415 .\" commit ddbb41148724367394d0880c516bfaeed127b52e
1416 Compute a Diffie-Hellman shared secret or public key.
1420 argument is a pointer to a set of parameters containing
1421 serial numbers for three
1423 keys used in the Diffie-Hellman calculation,
1424 packaged in a structure of the following form:
1428 struct keyctl_dh_params {
1429 int32_t private; /* The local private key */
1430 int32_t prime; /* The prime, known to both parties */
1431 int32_t base; /* The base integer: either a shared
1432 generator or the remote public key */
1437 Each of the three keys specified in this structure must grant the caller
1440 The payloads of these keys are used to calculate the Diffie-Hellman
1443 base ^ private mod prime
1445 If the base is the shared generator, the result is the local public key.
1446 If the base is the remote public key, the result is the shared secret.
1452 points to a buffer where the result of the calculation is placed.
1453 The size of that buffer is specified in
1458 The buffer must be large enough to accommodate the output data,
1459 otherwise an error is returned.
1463 in which case the buffer is not used and
1464 the operation returns the minimum required buffer size
1465 (i.e., the length of the prime).
1467 Diffie-Hellman computations can be performed in user space,
1468 but require a multiple-precision integer (MPI) library.
1469 Moving the implementation into the kernel gives access to
1470 the kernel MPI implementation,
1471 and allows access to secure or acceleration hardware.
1473 Adding support for DH computation to the
1475 system call was considered a good fit due to the DH algorithm's use
1476 for deriving shared keys;
1477 it also allows the type of the key to determine
1478 which DH implementation (software or hardware) is appropriate.
1482 argument is reserved and must be 0.
1484 For a successful call, the return value depends on the operation:
1486 .B KEYCTL_GET_KEYRING_ID
1487 The ID of the requested keyring.
1489 .B KEYCTL_JOIN_SESSION_KEYRING
1490 The ID of the joined session keyring.
1493 The size of the description (including the terminating null byte),
1494 irrespective of the provided buffer size.
1497 The ID of the key that was found.
1500 The amount of data that is available in the key,
1501 irrespective of the provided buffer size.
1503 .B KEYCTL_SET_REQKEY_KEYRING
1504 The ID of the previous default keyring
1505 to which implicitly requested keys were linked
1507 .BR KEY_REQKEY_DEFL_USER_* ).
1509 .B KEYCTL_ASSUME_AUTHORITY
1510 Either 0, if the ID given was 0,
1511 or the ID of the authorization key matching the specified key,
1512 if a non-zero key ID was provided.
1514 .B KEYCTL_GET_SECURITY
1515 The size of the LSM security label string
1516 (including the terminating null byte),
1517 irrespective of the provided buffer size.
1519 .B KEYCTL_GET_PERSISTENT
1520 The ID of the persistent keyring.
1522 .B KEYCTL_DH_COMPUTE
1523 The number of bytes copied to the buffer, or, if
1525 is 0, the required buffer size.
1527 All other operations
1530 On error, \-1 is returned, and
1532 is set appropriately to indicate the error.
1536 The requested operation wasn't permitted.
1542 and the requested link would result in a cycle.
1545 The key quota for the caller's user would be exceeded by creating a key or
1546 linking it to the keyring.
1552 and an invalid permission bit was specified in
1559 and the size of the description in
1561 (including the terminating null byte) exceeded 4096 bytes.
1562 size of the string (including the terminating null byte) specified in
1567 (the key description)
1568 exceeded the limit (32 bytes and 4096 bytes respectively).
1573 .B KEYCTL_DH_COMPUTE
1574 and the buffer size provided is not enough to hold the result.
1575 Provide 0 as a buffer size in order to obtain the minimum buffer size.
1578 An expired key was found or specified.
1581 A rejected key was found or specified.
1584 A revoked key was found or specified.
1590 and the requested link would cause the maximum nesting depth
1591 for keyrings to be exceeded.
1593 .BR ENFILE " (Linux kernels before 3.13)"
1597 and the keyring is full.
1599 .\" commit b2a4df200d570b2c33a57e1ebfa5896e4bc81b69
1600 the available space for storing keyring links was limited to
1601 a single page of memory; since Linux 3.13, there is no fixed limit.)
1607 and the key to be unlinked isn't linked to the keyring.
1610 No matching key was found or an invalid key was specified.
1614 .B KEYCTL_GET_KEYRING_ID
1617 the key specified in
1621 was zero (meaning don't create the key if it didn't exist).
1624 A key of keyring type was expected but the ID of a key with
1625 a different type was provided.
1631 and the key type does not support reading
1639 and the key type does not support updating.
1644 .BR KEYCTL_GET_PERSISTENT ,
1646 specified a UID other than the calling thread's real or effective UID,
1647 and the caller did not have the
1654 .BR KEYCTL_SESSION_TO_PARENT
1656 all of the UIDs (GIDs) of the parent process do not match
1657 the effective UID (GID) of the calling process;
1658 the UID of the parent's existing session keyring or
1659 the UID of the caller's session keyring did not match
1660 the effective UID of the caller;
1661 the parent process is not single-thread;
1662 or the parent process is
1666 This system call first appeared in Linux 2.6.10.
1668 This system call is a nonstandard Linux extension.
1670 No wrapper for this system call is provided in glibc.
1671 A wrapper is provided in the
1674 When employing the wrapper in that library, link with
1676 However, rather than using this system call directly,
1677 you probably want to use the various library functions
1678 mentioned in the descriptions of individual operations above.
1680 The program below provide subset of the functionality of the
1682 program provided by the
1685 For informational purposes,
1686 the program records various information in a log file.
1689 .BR request_key (2),
1692 program is invoked with command-line arguments that
1693 describe a key that is to be instantiated.
1694 The example program fetches and logs these arguments.
1695 The program assumes authority to instantiate the requested key,
1696 and then instantiates that key.
1698 The following shell session demonstrates the use of this program.
1700 we compile the program and then use it to temporarily replace the standard
1703 (Note that temporarily disabling the standard
1705 program may not be safe on some systems.)
1706 While our example program is installed,
1707 we use the example program shown in
1713 $ \fBcc \-o key_instantiate key_instantiate.c \-lkeyutils\fP
1714 $ \fBsudo mv /sbin/request\-key /sbin/request\-key.backup\fP
1715 $ \fBsudo cp key_instantiate /sbin/request\-key\fP
1716 $ \fB./t_request_key user mykey somepayloaddata\fP
1718 $ \fBsudo mv /sbin/request\-key.backup /sbin/request\-key\fP
1722 Looking at the log file created by this program,
1723 we can see the command-line arguments supplied to our example program:
1727 $ \fBcat /tmp/key_instantiate.log \fP
1728 Time: Mon Nov 7 13:06:47 2016
1730 Command line arguments:
1731 argv[0]: /sbin/request-key
1733 key_to_instantiate: 20d035bf
1738 session_keyring: 256e6a6
1740 Key description: user;1000;1000;3f010000;mykey
1741 Auth key payload: somepayloaddata
1742 Destination keyring: 256e6a6
1743 Auth key description: .request_key_auth;1000;1000;0b010000;20d035bf
1747 The last few lines of the above output show that the example program
1750 the description of the key to be instantiated,
1751 which included the name of the key
1754 the payload of the authorization key, which consisted of the data
1755 .RI ( somepayloaddata )
1757 .BR request_key (2);
1759 the destination keyring that was specified in the call to
1760 .BR request_key (2);
1763 the description of the authorization key,
1764 where we can see that the name of the authorization key matches
1765 the ID of the key that is to be instantiated
1768 The example program in
1770 specified the destination keyring as
1771 .BR KEY_SPEC_SESSION_KEYRING .
1772 By examining the contents of
1774 we can see that this was translated to the ID of the destination keyring
1776 shown in the log output above;
1777 we can also see the newly created key with the name
1784 $ \fBcat /proc/keys | egrep \(aqmykey|256e6a6\(aq\fP
1785 0256e6a6 I\-\-Q\-\-\- 194 perm 3f030000 1000 1000 keyring _ses: 3
1786 20d035bf I\-\-Q\-\-\- 1 perm 3f010000 1000 1000 user mykey: 16
1792 /* key_instantiate.c */
1794 #include <sys/types.h>
1795 #include <keyutils.h>
1804 #ifndef KEY_SPEC_REQUESTOR_KEYRING
1805 #define KEY_SPEC_REQUESTOR_KEYRING \-8
1809 main(int argc, char *argv[])
1814 key_serial_t key_to_instantiate, dest_keyring;
1815 key_serial_t thread_keyring, process_keyring, session_keyring;
1819 char auth_key_payload[256];
1820 int akp_size; /* Size of auth_key_payload */
1822 fp = fopen("/tmp/key_instantiate.log", "w");
1829 fprintf(fp, "Time: %s\\n", ctime(&t));
1832 * The kernel passes a fixed set of arguments to the program
1833 * that it execs; fetch them.
1835 operation = argv[1];
1836 key_to_instantiate = atoi(argv[2]);
1837 uid = atoi(argv[3]);
1838 gid = atoi(argv[4]);
1839 thread_keyring = atoi(argv[5]);
1840 process_keyring = atoi(argv[6]);
1841 session_keyring = atoi(argv[7]);
1843 fprintf(fp, "Command line arguments:\\n");
1844 fprintf(fp, " argv[0]: %s\\n", argv[0]);
1845 fprintf(fp, " operation: %s\\n", operation);
1846 fprintf(fp, " key_to_instantiate: %lx\\n",
1847 (long) key_to_instantiate);
1848 fprintf(fp, " UID: %ld\\n", (long) uid);
1849 fprintf(fp, " GID: %ld\\n", (long) gid);
1850 fprintf(fp, " thread_keyring: %lx\\n", (long) thread_keyring);
1851 fprintf(fp, " process_keyring: %lx\\n", (long) process_keyring);
1852 fprintf(fp, " session_keyring: %lx\\n", (long) session_keyring);
1856 * Assume the authority to instantiate the key named in argv[2]
1858 if (keyctl(KEYCTL_ASSUME_AUTHORITY, key_to_instantiate) == \-1) {
1859 fprintf(fp, "KEYCTL_ASSUME_AUTHORITY failed: %s\\n",
1865 * Fetch the description of the key that is to be instantiated
1867 if (keyctl(KEYCTL_DESCRIBE, key_to_instantiate,
1868 dbuf, sizeof(dbuf)) == \-1) {
1869 fprintf(fp, "KEYCTL_DESCRIBE failed: %s\\n", strerror(errno));
1873 fprintf(fp, "Key description: %s\\n", dbuf);
1876 * Fetch the payload of the authorization key, which is
1877 * actually the callout data given to request_key()
1879 akp_size = keyctl(KEYCTL_READ, KEY_SPEC_REQKEY_AUTH_KEY,
1880 auth_key_payload, sizeof(auth_key_payload));
1881 if (akp_size == \-1) {
1882 fprintf(fp, "KEYCTL_READ failed: %s\\n", strerror(errno));
1886 auth_key_payload[akp_size] = \(aq\\0\(aq;
1887 fprintf(fp, "Auth key payload: %s\\n", auth_key_payload);
1890 * For interest, get the ID of the authorization key and
1893 auth_key = keyctl(KEYCTL_GET_KEYRING_ID,
1894 KEY_SPEC_REQKEY_AUTH_KEY);
1895 if (auth_key == \-1) {
1896 fprintf(fp, "KEYCTL_GET_KEYRING_ID failed: %s\\n",
1901 fprintf(fp, "Auth key ID: %lx\\n", (long) auth_key);
1904 * Fetch key ID for the request_key(2) destination keyring.
1906 dest_keyring = keyctl(KEYCTL_GET_KEYRING_ID,
1907 KEY_SPEC_REQUESTOR_KEYRING);
1908 if (dest_keyring == \-1) {
1909 fprintf(fp, "KEYCTL_GET_KEYRING_ID failed: %s\\n",
1914 fprintf(fp, "Destination keyring: %lx\\n", (long) dest_keyring);
1917 * Fetch the description of the authorization key. This
1918 * allows us to see the key type, UID, GID, permissions,
1919 * and description (name) of the key. Among other things,
1920 * we will see that the name of the key is a hexadecimal
1921 * string representing the ID of the key to be instantiated.
1923 if (keyctl(KEYCTL_DESCRIBE, KEY_SPEC_REQKEY_AUTH_KEY,
1924 dbuf, sizeof(dbuf)) == \-1) {
1925 fprintf(fp, "KEYCTL_DESCRIBE failed: %s\\n", strerror(errno));
1929 fprintf(fp, "Auth key description: %s\\n", dbuf);
1932 * Instantiate the key using the callout data that was supplied
1933 * in the payload of the authorization key.
1935 if (keyctl(KEYCTL_INSTANTIATE, key_to_instantiate,
1936 auth_key_payload, akp_size + 1, dest_keyring) == \-1) {
1937 fprintf(fp, "KEYCTL_INSTANTIATE failed: %s\\n",
1950 .BR request_key (2),
1951 .\" .BR find_key_by_type_and_name (3)
1952 .\" There is a man page, but this function seems not to exist
1954 .BR keyctl_assume_authority (3),
1955 .BR keyctl_chown (3),
1956 .BR keyctl_clear (3),
1957 .BR keyctl_describe (3),
1958 .BR keyctl_describe_alloc (3),
1959 .BR keyctl_get_keyring_ID (3),
1960 .BR keyctl_get_persistent (3),
1961 .BR keyctl_get_security (3),
1962 .BR keyctl_get_security_alloc (3),
1963 .BR keyctl_instantiate (3),
1964 .BR keyctl_instantiate_iov (3),
1965 .BR keyctl_invalidate (3),
1966 .BR keyctl_join_session_keyring (3),
1967 .BR keyctl_link (3),
1968 .BR keyctl_negate (3),
1969 .BR keyctl_read (3),
1970 .BR keyctl_read_alloc (3),
1971 .BR keyctl_reject (3),
1972 .BR keyctl_revoke (3),
1973 .BR keyctl_search (3),
1974 .BR keyctl_session_to_parent (3),
1975 .BR keyctl_set_reqkey_keyring (3),
1976 .BR keyctl_set_timeout (3),
1977 .BR keyctl_setperm (3),
1978 .BR keyctl_unlink (3),
1979 .BR keyctl_update (3),
1980 .BR recursive_key_scan (3),
1981 .BR recursive_session_key_scan (3),
1982 .BR capabilities (7),
1983 .BR credentials (7),
1986 .BR persistent\-keyring (7),
1987 .BR process\-keyring (7),
1988 .BR session\-keyring (7),
1989 .BR thread\-keyring (7),
1990 .BR user\-keyring (7),
1991 .BR user\-namespaces (7),
1992 .BR user\-session\-keyring (7),
1993 .BR request\-key (8)
1995 The kernel source files
1996 .IR Documentation/security/keys.txt
1998 .IR Documentation/security/keys\-request\-key.txt .
projects / thirdparty / man-pages.git / blob