| 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/ . |