Debian Codegraph @

upstream/debian-unstable/man2/keyctl.2

raw
1 .\" Copyright 2016, Michael Kerrisk <[email protected]>
2 .\" Copyright 2016, Eugene Syromyatnikov <[email protected]>
3 .\" Copyright, the authors of the Linux man-pages project
4 .\"
5 .\" SPDX-License-Identifier: Linux-man-pages-copyleft
6 .\"
7 .TH keyctl 2 2026-02-08 "Linux man-pages 6.18"
8 .SH NAME
9 keyctl \- manipulate the kernel's key management facility
10 .SH LIBRARY
11 Standard C library
12 .RI ( libc ,\~ \-lc )
13 .SH SYNOPSIS
14 .nf
15 .BR "#include <linux/keyctl.h>" " /* Definition of " KEY* " constants */"
16 .BR "#include <sys/syscall.h>" " /* Definition of " SYS_* " constants */"
17 .B #include <unistd.h>
18 .P
19 .BI "long syscall(SYS_keyctl, int " op ", ...);"
20 .fi
21 .SH DESCRIPTION
22 .BR keyctl ()
23 allows user-space programs to perform key manipulation.
24 .P
25 The operation performed by
26 .BR keyctl ()
27 is determined by the value of the
28 .I op
29 argument.
30 Each of these operations is wrapped by the
31 .I libkeyutils
32 library (provided by the
33 .I keyutils
34 package) into individual functions (see
35 .BR keyctl (3))
36 to permit the compiler to check types.
37 .P
38 The permitted values for
39 .I op
40 are:
41 .TP
42 .BR KEYCTL_GET_KEYRING_ID (2const)
43 .TQ
44 .BR KEYCTL_JOIN_SESSION_KEYRING (2const)
45 .TQ
46 .BR KEYCTL_UPDATE (2const)
47 .TQ
48 .BR KEYCTL_REVOKE (2const)
49 .TQ
50 .BR KEYCTL_CHOWN (2const)
51 .TQ
52 .BR KEYCTL_SETPERM (2const)
53 .TQ
54 .BR KEYCTL_DESCRIBE (2const)
55 .TQ
56 .BR KEYCTL_CLEAR (2const)
57 .TQ
58 .BR KEYCTL_LINK (2const)
59 .TQ
60 .BR KEYCTL_UNLINK (2const)
61 .TQ
62 .BR KEYCTL_SEARCH (2const)
63 .TQ
64 .BR KEYCTL_READ (2const)
65 .TQ
66 .BR KEYCTL_INSTANTIATE (2const)
67 .TQ
68 .BR KEYCTL_INSTANTIATE_IOV (2const)
69 .TQ
70 .BR KEYCTL_NEGATE (2const)
71 .TQ
72 .BR KEYCTL_REJECT (2const)
73 .TQ
74 .BR KEYCTL_SET_REQKEY_KEYRING (2const)
75 .TQ
76 .BR KEYCTL_SET_TIMEOUT (2const)
77 .TQ
78 .BR KEYCTL_ASSUME_AUTHORITY (2const)
79 .TQ
80 .BR KEYCTL_GET_SECURITY (2const)
81 .TQ
82 .BR KEYCTL_SESSION_TO_PARENT (2const)
83 .TQ
84 .BR KEYCTL_INVALIDATE (2const)
85 .TQ
86 .BR KEYCTL_GET_PERSISTENT (2const)
87 .TQ
88 .BR KEYCTL_DH_COMPUTE (2const)
89 .TQ
90 .BR KEYCTL_RESTRICT_KEYRING (2const)
91 .SH RETURN VALUE
92 For a successful call, the return value depends on the operation.
93 .P
94 On error, \-1 is returned, and
95 .I errno
96 is set to indicate the error.
97 .SH ERRORS
98 .TP
99 .B EACCES
100 The requested operation wasn't permitted.
101 .TP
102 .B EDQUOT
103 The key quota for the caller's user would be exceeded by creating a key or
104 linking it to the keyring.
105 .TP
106 .B EINVAL
107 size of the string (including the terminating null byte) specified in
108 .I arg3
109 (the key type)
110 or
111 .I arg4
112 (the key description)
113 exceeded the limit (32 bytes and 4096 bytes respectively).
114 .TP
115 .B EKEYEXPIRED
116 An expired key was found or specified.
117 .TP
118 .B EKEYREJECTED
119 A rejected key was found or specified.
120 .TP
121 .B EKEYREVOKED
122 A revoked key was found or specified.
123 .TP
124 .B ENOKEY
125 No matching key was found or an invalid key was specified.
126 .TP
127 .B ENOMEM
128 One of kernel memory allocation routines failed during the execution of the
129 syscall.
130 .TP
131 .B ENOTDIR
132 A key of keyring type was expected but the ID of a key with
133 a different type was provided.
134 .SH VERSIONS
135 A wrapper is provided in the
136 .I libkeyutils
137 library.
138 (The accompanying package provides the
139 .I <keyutils.h>
140 header file.)
141 However, rather than using this system call directly,
142 you probably want to use the various library functions
143 mentioned in the descriptions of individual operations above.
144 .SH STANDARDS
145 Linux.
146 .SH HISTORY
147 Linux 2.6.10.
148 .SH EXAMPLES
149 The program below provide subset of the functionality of the
150 .BR request\-key (8)
151 program provided by the
152 .I keyutils
153 package.
154 For informational purposes,
155 the program records various information in a log file.
156 .P
157 As described in
158 .BR request_key (2),
159 the
160 .BR request\-key (8)
161 program is invoked with command-line arguments that
162 describe a key that is to be instantiated.
163 The example program fetches and logs these arguments.
164 The program assumes authority to instantiate the requested key,
165 and then instantiates that key.
166 .P
167 The following shell session demonstrates the use of this program.
168 In the session,
169 we compile the program and then use it to temporarily replace the standard
170 .BR request\-key (8)
171 program.
172 (Note that temporarily disabling the standard
173 .BR request\-key (8)
174 program may not be safe on some systems.)
175 While our example program is installed,
176 we use the example program shown in
177 .BR request_key (2)
178 to request a key.
179 .P
180 .in +4n
181 .EX
182 .RB $ " cc \-o key_instantiate key_instantiate.c \-lkeyutils" ;
183 .RB $ " sudo mv /sbin/request\-key /sbin/request\-key.backup" ;
184 .RB $ " sudo cp key_instantiate /sbin/request\-key" ;
185 .RB $ " ./t_request_key user mykey somepayloaddata" ;
186 Key ID is 20d035bf
187 .RB $ " sudo mv /sbin/request\-key.backup /sbin/request\-key" ;
188 .EE
189 .in
190 .P
191 Looking at the log file created by this program,
192 we can see the command-line arguments supplied to our example program:
193 .P
194 .in +4n
195 .EX
196 .RB $ " cat /tmp/key_instantiate.log" ;
197 Time: Mon Nov 7 13:06:47 2016
198 \&
199 Command line arguments:
200 argv[0]: /sbin/request\-key
201 operation: create
202 key_to_instantiate: 20d035bf
203 UID: 1000
204 GID: 1000
205 thread_keyring: 0
206 process_keyring: 0
207 session_keyring: 256e6a6
208 \&
209 Key description: user;1000;1000;3f010000;mykey
210 Auth key payload: somepayloaddata
211 Destination keyring: 256e6a6
212 Auth key description: .request_key_auth;1000;1000;0b010000;20d035bf
213 .EE
214 .in
215 .P
216 The last few lines of the above output show that the example program
217 was able to fetch:
218 .IP \[bu] 3
219 the description of the key to be instantiated,
220 which included the name of the key
221 .RI ( mykey );
222 .IP \[bu]
223 the payload of the authorization key, which consisted of the data
224 .RI ( somepayloaddata )
225 passed to
226 .BR request_key (2);
227 .IP \[bu]
228 the destination keyring that was specified in the call to
229 .BR request_key (2);
230 and
231 .IP \[bu]
232 the description of the authorization key,
233 where we can see that the name of the authorization key matches
234 the ID of the key that is to be instantiated
235 .RI ( 20d035bf ).
236 .P
237 The example program in
238 .BR request_key (2)
239 specified the destination keyring as
240 .BR KEY_SPEC_SESSION_KEYRING .
241 By examining the contents of
242 .IR /proc/keys ,
243 we can see that this was translated to the ID of the destination keyring
244 .RI ( 0256e6a6 )
245 shown in the log output above;
246 we can also see the newly created key with the name
247 .I mykey
248 and ID
249 .IR 20d035bf .
250 .P
251 .in +4n
252 .EX
253 .RB $ " cat /proc/keys | egrep \[aq]mykey|256e6a6\[aq]" ;
254 0256e6a6 I\-\-Q\-\-\- 194 perm 3f030000 1000 1000 keyring _ses: 3
255 20d035bf I\-\-Q\-\-\- 1 perm 3f010000 1000 1000 user mykey: 16
256 .EE
257 .in
258 .SS Program source
259 \&
260 .\" SRC BEGIN (key_instantiate.c)
261 .EX
262 /* key_instantiate.c */
263 \&
264 #include <errno.h>
265 #include <keyutils.h>
266 #include <stdint.h>
267 #include <stdio.h>
268 #include <stdlib.h>
269 #include <string.h>
270 #include <sys/types.h>
271 #include <time.h>
272 \&
273 #ifndef KEY_SPEC_REQUESTOR_KEYRING
274 #define KEY_SPEC_REQUESTOR_KEYRING (\-8)
275 #endif
276 \&
277 int
278 main(int argc, char *argv[])
279 {
280 int akp_size; /* Size of auth_key_payload */
281 int auth_key;
282 char dbuf[256];
283 char auth_key_payload[256];
284 char *operation;
285 FILE *fp;
286 gid_t gid;
287 uid_t uid;
288 time_t t;
289 key_serial_t key_to_instantiate, dest_keyring;
290 key_serial_t thread_keyring, process_keyring, session_keyring;
291 \&
292 if (argc != 8) {
293 fprintf(stderr, "Usage: %s op key uid gid thread_keyring "
294 "process_keyring session_keyring\[rs]n", argv[0]);
295 exit(EXIT_FAILURE);
296 }
297 \&
298 fp = fopen("/tmp/key_instantiate.log", "w");
299 if (fp == NULL)
300 exit(EXIT_FAILURE);
301 \&
302 setbuf(fp, NULL);
303 \&
304 t = time(NULL);
305 fprintf(fp, "Time: %s\[rs]n", ctime(&t));
306 \&
307 /*
308 * The kernel passes a fixed set of arguments to the program
309 * that it execs; fetch them.
310 */
311 operation = argv[1];
312 key_to_instantiate = atoi(argv[2]);
313 uid = atoi(argv[3]);
314 gid = atoi(argv[4]);
315 thread_keyring = atoi(argv[5]);
316 process_keyring = atoi(argv[6]);
317 session_keyring = atoi(argv[7]);
318 \&
319 fprintf(fp, "Command line arguments:\[rs]n");
320 fprintf(fp, " argv[0]: %s\[rs]n", argv[0]);
321 fprintf(fp, " operation: %s\[rs]n", operation);
322 fprintf(fp, " key_to_instantiate: %jx\[rs]n",
323 (uintmax_t) key_to_instantiate);
324 fprintf(fp, " UID: %jd\[rs]n", (intmax_t) uid);
325 fprintf(fp, " GID: %jd\[rs]n", (intmax_t) gid);
326 fprintf(fp, " thread_keyring: %jx\[rs]n",
327 (uintmax_t) thread_keyring);
328 fprintf(fp, " process_keyring: %jx\[rs]n",
329 (uintmax_t) process_keyring);
330 fprintf(fp, " session_keyring: %jx\[rs]n",
331 (uintmax_t) session_keyring);
332 fprintf(fp, "\[rs]n");
333 \&
334 /*
335 * Assume the authority to instantiate the key named in argv[2].
336 */
337 if (keyctl(KEYCTL_ASSUME_AUTHORITY, key_to_instantiate) == \-1) {
338 fprintf(fp, "KEYCTL_ASSUME_AUTHORITY failed: %s\[rs]n",
339 strerror(errno));
340 exit(EXIT_FAILURE);
341 }
342 \&
343 /*
344 * Fetch the description of the key that is to be instantiated.
345 */
346 if (keyctl(KEYCTL_DESCRIBE, key_to_instantiate,
347 dbuf, sizeof(dbuf)) == \-1) {
348 fprintf(fp, "KEYCTL_DESCRIBE failed: %s\[rs]n", strerror(errno));
349 exit(EXIT_FAILURE);
350 }
351 \&
352 fprintf(fp, "Key description: %s\[rs]n", dbuf);
353 \&
354 /*
355 * Fetch the payload of the authorization key, which is
356 * actually the callout data given to request_key().
357 */
358 akp_size = keyctl(KEYCTL_READ, KEY_SPEC_REQKEY_AUTH_KEY,
359 auth_key_payload, sizeof(auth_key_payload));
360 if (akp_size == \-1) {
361 fprintf(fp, "KEYCTL_READ failed: %s\[rs]n", strerror(errno));
362 exit(EXIT_FAILURE);
363 }
364 \&
365 auth_key_payload[akp_size] = \[aq]\[rs]0\[aq];
366 fprintf(fp, "Auth key payload: %s\[rs]n", auth_key_payload);
367 \&
368 /*
369 * For interest, get the ID of the authorization key and
370 * display it.
371 */
372 auth_key = keyctl(KEYCTL_GET_KEYRING_ID,
373 KEY_SPEC_REQKEY_AUTH_KEY);
374 if (auth_key == \-1) {
375 fprintf(fp, "KEYCTL_GET_KEYRING_ID failed: %s\[rs]n",
376 strerror(errno));
377 exit(EXIT_FAILURE);
378 }
379 \&
380 fprintf(fp, "Auth key ID: %jx\[rs]n", (uintmax_t) auth_key);
381 \&
382 /*
383 * Fetch key ID for the request_key(2) destination keyring.
384 */
385 dest_keyring = keyctl(KEYCTL_GET_KEYRING_ID,
386 KEY_SPEC_REQUESTOR_KEYRING);
387 if (dest_keyring == \-1) {
388 fprintf(fp, "KEYCTL_GET_KEYRING_ID failed: %s\[rs]n",
389 strerror(errno));
390 exit(EXIT_FAILURE);
391 }
392 \&
393 fprintf(fp, "Destination keyring: %jx\[rs]n", (uintmax_t) dest_keyring);
394 \&
395 /*
396 * Fetch the description of the authorization key. This
397 * allows us to see the key type, UID, GID, permissions,
398 * and description (name) of the key. Among other things,
399 * we will see that the name of the key is a hexadecimal
400 * string representing the ID of the key to be instantiated.
401 */
402 if (keyctl(KEYCTL_DESCRIBE, KEY_SPEC_REQKEY_AUTH_KEY,
403 dbuf, sizeof(dbuf)) == \-1)
404 {
405 fprintf(fp, "KEYCTL_DESCRIBE failed: %s\[rs]n", strerror(errno));
406 exit(EXIT_FAILURE);
407 }
408 \&
409 fprintf(fp, "Auth key description: %s\[rs]n", dbuf);
410 \&
411 /*
412 * Instantiate the key using the callout data that was supplied
413 * in the payload of the authorization key.
414 */
415 if (keyctl(KEYCTL_INSTANTIATE, key_to_instantiate,
416 auth_key_payload, akp_size + 1, dest_keyring) == \-1)
417 {
418 fprintf(fp, "KEYCTL_INSTANTIATE failed: %s\[rs]n",
419 strerror(errno));
420 exit(EXIT_FAILURE);
421 }
422 \&
423 exit(EXIT_SUCCESS);
424 }
425 .EE
426 .\" SRC END
427 .SH SEE ALSO
428 .ad l
429 .nh
430 .BR keyctl (1),
431 .BR add_key (2),
432 .BR request_key (2),
433 .\" .BR find_key_by_type_and_name (3)
434 .\" There is a man page, but this function seems not to exist
435 .BR keyctl (3),
436 .BR recursive_key_scan (3),
437 .BR recursive_session_key_scan (3),
438 .BR capabilities (7),
439 .BR credentials (7),
440 .BR keyrings (7),
441 .BR keyutils (7),
442 .BR persistent\-keyring (7),
443 .BR process\-keyring (7),
444 .BR session\-keyring (7),
445 .BR thread\-keyring (7),
446 .BR user\-keyring (7),
447 .BR user_namespaces (7),
448 .BR user\-session\-keyring (7),
449 .BR request\-key (8)
450 .P
451 The kernel source files under
452 .IR Documentation/security/keys/ .