Debian Codegraph @

upstream/fedora-44/man2/keyctl.2

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