man2/request_key.2

   1 .\" Copyright (C) 2006 Red Hat, Inc. All Rights Reserved.
   2 .\"     Written by David Howells (dhowells@redhat.com)
   3 .\" and Copyright (C) 2016 Michael Kerrisk <mtk.man-pages@gmail.com>
   4 .\"
   5 .\" SPDX-License-Identifier: GPL-2.0-or-later
   6 .\"
   7 .TH REQUEST_KEY 2 2021-08-27 "Linux man-pages (unreleased)" "Linux Key Management Calls"
   8 .SH NAME
   9 request_key \- request a key from the kernel's key management facility
  10 .SH LIBRARY
  11 Linux Key Management Utilities
  12 .RI ( libkeyutils ", " \-lkeyutils )
  13 .SH SYNOPSIS
  14 .nf
  15 .B #include <keyutils.h>
  16 .PP
  17 .BI "key_serial_t request_key(const char *" type ", const char *" description ,
  18 .BI "                         const char *" callout_info ,
  19 .BI "                         key_serial_t " dest_keyring );
  20 .fi
  21 .SH DESCRIPTION
  22 .BR request_key ()
  23 attempts to find a key of the given
  24 .I type
  25 with a description (name) that matches the specified
  26 .IR description .
  27 If such a key could not be found, then the key is optionally created.
  28 If the key is found or created,
  29 .BR request_key ()
  30 attaches it to the keyring whose ID is specified in
  31 .I dest_keyring
  32 and returns the key's serial number.
  33 .PP
  34 .BR request_key ()
  35 first recursively searches for a matching key in all of the keyrings
  36 attached to the calling process.
  37 The keyrings are searched in the order: thread-specific keyring,
  38 process-specific keyring, and then session keyring.
  39 .PP
  40 If
  41 .BR request_key ()
  42 is called from a program invoked by
  43 .BR request_key ()
  44 on behalf of some other process to generate a key, then the keyrings of that
  45 other process will be searched next,
  46 using that other process's user ID, group ID,
  47 supplementary group IDs, and security context to determine access.
  48 .\" David Howells: we can then have an arbitrarily long sequence
  49 .\" of "recursive" request-key upcalls. There is no limit, other
  50 .\" than number of PIDs, etc.
  51 .PP
  52 The search of the keyring tree is breadth-first:
  53 the keys in each keyring searched are checked for a match before any child
  54 keyrings are recursed into.
  55 Only keys for which the caller has
  56 .I search
  57 permission be found, and only keyrings for which the caller has
  58 .I search
  59 permission may be searched.
  60 .PP
  61 If the key is not found and
  62 .I callout
  63 is NULL, then the call fails with the error
  64 .BR ENOKEY .
  65 .PP
  66 If the key is not found and
  67 .I callout
  68 is not NULL, then the kernel attempts to invoke a user-space
  69 program to instantiate the key.
  70 The details are given below.
  71 .PP
  72 The
  73 .I dest_keyring
  74 serial number may be that of a valid keyring for which the caller has
  75 .I write
  76 permission, or it may be one of the following special keyring IDs:
  77 .TP
  78 .B KEY_SPEC_THREAD_KEYRING
  79 This specifies the caller's thread-specific keyring (see
  80 .BR thread\-keyring (7)).
  81 .TP
  82 .B KEY_SPEC_PROCESS_KEYRING
  83 This specifies the caller's process-specific keyring (see
  84 .BR process\-keyring (7)).
  85 .TP
  86 .B KEY_SPEC_SESSION_KEYRING
  87 This specifies the caller's session-specific keyring (see
  88 .BR session\-keyring (7)).
  89 .TP
  90 .B KEY_SPEC_USER_KEYRING
  91 This specifies the caller's UID-specific keyring (see
  92 .BR user\-keyring (7)).
  93 .TP
  94 .B KEY_SPEC_USER_SESSION_KEYRING
  95 This specifies the caller's UID-session keyring (see
  96 .BR user\-session\-keyring (7)).
  97 .PP
  98 When the
  99 .I dest_keyring
 100 is specified as 0
 101 and no key construction has been performed,
 102 then no additional linking is done.
 103 .PP
 104 Otherwise, if
 105 .I dest_keyring
 106 is 0 and a new key is constructed, the new key will be linked
 107 to the "default" keyring.
 108 More precisely, when the kernel tries to determine to which keyring the
 109 newly constructed key should be linked,
 110 it tries the following keyrings,
 111 beginning with the keyring set via the
 112 .BR keyctl (2)
 113 .B KEYCTL_SET_REQKEY_KEYRING
 114 operation and continuing in the order shown below
 115 until it finds the first keyring that exists:
 116 .IP \(bu 3
 117 .\" 8bbf4976b59fc9fc2861e79cab7beb3f6d647640
 118 The requestor keyring
 119 .RB ( KEY_REQKEY_DEFL_REQUESTOR_KEYRING ,
 120 since Linux 2.6.29).
 121 .\" FIXME
 122 .\" Actually, is the preceding point correct?
 123 .\" If I understand correctly, we'll only get here if
 124 .\" 'dest_keyring' is zero, in which case KEY_REQKEY_DEFL_REQUESTOR_KEYRING
 125 .\" won't refer to a keyring. Have I misunderstood?
 126 .IP \(bu
 127 The thread-specific keyring
 128 .RB ( KEY_REQKEY_DEFL_THREAD_KEYRING ;
 129 see
 130 .BR thread\-keyring (7)).
 131 .IP \(bu
 132 The process-specific keyring
 133 .RB ( KEY_REQKEY_DEFL_PROCESS_KEYRING ;
 134 see
 135 .BR process\-keyring (7)).
 136 .IP \(bu
 137 The session-specific keyring
 138 .RB ( KEY_REQKEY_DEFL_SESSION_KEYRING ;
 139 see
 140 .BR session\-keyring (7)).
 141 .IP \(bu
 142 The session keyring for the process's user ID
 143 .RB ( KEY_REQKEY_DEFL_USER_SESSION_KEYRING ;
 144 see
 145 .BR user\-session\-keyring (7)).
 146 This keyring is expected to always exist.
 147 .IP \(bu
 148 The UID-specific keyring
 149 .RB ( KEY_REQKEY_DEFL_USER_KEYRING ;
 150 see
 151 .BR user\-keyring (7)).
 152 This keyring is also expected to always exist.
 153 .\" mtk: Are there circumstances where the user sessions and UID-specific
 154 .\" keyrings do not exist?
 155 .\"
 156 .\" David Howells:
 157 .\"     The uid keyrings don't exist until someone tries to access them -
 158 .\"     at which point they're both created.  When you log in, pam_keyinit
 159 .\"     creates a link to your user keyring in the session keyring it just
 160 .\"     created, thereby creating the user and user-session keyrings.
 161 .\"
 162 .\" and David elaborated that "access" means:
 163 .\"
 164 .\"     It means lookup_user_key() was passed KEY_LOOKUP_CREATE.  So:
 165 .\"
 166 .\"         add_key() - destination keyring
 167 .\"         request_key() - destination keyring
 168 .\"         KEYCTL_GET_KEYRING_ID - if create arg is true
 169 .\"         KEYCTL_CLEAR
 170 .\"         KEYCTL_LINK - both args
 171 .\"         KEYCTL_SEARCH - destination keyring
 172 .\"         KEYCTL_CHOWN
 173 .\"         KEYCTL_SETPERM
 174 .\"         KEYCTL_SET_TIMEOUT
 175 .\"         KEYCTL_INSTANTIATE - destination keyring
 176 .\"         KEYCTL_INSTANTIATE_IOV - destination keyring
 177 .\"         KEYCTL_NEGATE - destination keyring
 178 .\"         KEYCTL_REJECT - destination keyring
 179 .\"         KEYCTL_GET_PERSISTENT - destination keyring
 180 .\"
 181 .\"     will all create a keyring under some circumstances.  Whereas the rest,
 182 .\"     such as KEYCTL_GET_SECURITY, KEYCTL_READ and KEYCTL_REVOKE, won't.
 183 .PP
 184 If the
 185 .BR keyctl (2)
 186 .B KEYCTL_SET_REQKEY_KEYRING
 187 operation specifies
 188 .B KEY_REQKEY_DEFL_DEFAULT
 189 (or no
 190 .B KEYCTL_SET_REQKEY_KEYRING
 191 operation is performed),
 192 then the kernel looks for a keyring
 193 starting from the beginning of the list.
 194 .\"
 195 .SS Requesting user-space instantiation of a key
 196 If the kernel cannot find a key matching
 197 .I type
 198 and
 199 .IR description ,
 200 and
 201 .I callout
 202 is not NULL, then the kernel attempts to invoke a user-space
 203 program to instantiate a key with the given
 204 .I type
 205 and
 206 .IR description .
 207 In this case, the following steps are performed:
 208 .IP a) 4
 209 The kernel creates an uninstantiated key, U, with the requested
 210 .I type
 211 and
 212 .IR description .
 213 .IP b)
 214 The kernel creates an authorization key, V,
 215 .\" struct request_key_auth, defined in security/keys/internal.h
 216 that refers to the key U and records the facts that the caller of
 217 .BR request_key ()
 218 is:
 219 .RS
 220 .IP (1) 4
 221 the context in which the key U should be instantiated and secured, and
 222 .IP (2)
 223 the context from which associated key requests may be satisfied.
 224 .RE
 225 .IP
 226 The authorization key is constructed as follows:
 227 .RS
 228 .IP * 3
 229 The key type is
 230 .IR """.request_key_auth""" .
 231 .IP *
 232 The key's UID and GID are the same as the corresponding filesystem IDs
 233 of the requesting process.
 234 .IP *
 235 The key grants
 236 .IR view ,
 237 .IR read ,
 238 and
 239 .I search
 240 permissions to the key possessor as well as
 241 .I view
 242 permission for the key user.
 243 .IP *
 244 The description (name) of the key is the hexadecimal
 245 string representing the ID of the key that is to be instantiated
 246 in the requesting program.
 247 .IP *
 248 The payload of the key is taken from the data specified in
 249 .IR callout_info .
 250 .IP *
 251 Internally, the kernel also records the PID of the process that called
 252 .BR request_key ().
 253 .RE
 254 .IP c)
 255 The kernel creates a process that executes a user-space service such as
 256 .BR request\-key (8)
 257 with a new session keyring that contains a link to the authorization key, V.
 258 .\" The request\-key(8) program can be invoked in circumstances *other* than
 259 .\" when triggered by request_key(2). For example, upcalls from places such
 260 .\" as the DNS resolver.
 261 .IP
 262 This program is supplied with the following command-line arguments:
 263 .RS
 264 .IP [0] 4
 265 The string
 266 .IR """/sbin/request\-key""" .
 267 .IP [1]
 268 The string
 269 .I """create"""
 270 (indicating that a key is to be created).
 271 .IP [2]
 272 The ID of the key that is to be instantiated.
 273 .IP [3]
 274 The filesystem UID of the caller of
 275 .BR request_key ().
 276 .IP [4]
 277 The filesystem GID of the caller of
 278 .BR request_key ().
 279 .IP [5]
 280 The ID of the thread keyring of the caller of
 281 .BR request_key ().
 282 This may be zero if that keyring hasn't been created.
 283 .IP [6]
 284 The ID of the process keyring of the caller of
 285 .BR request_key ().
 286 This may be zero if that keyring hasn't been created.
 287 .IP [7]
 288 The ID of the session keyring of the caller of
 289 .BR request_key ().
 290 .RE
 291 .IP
 292 .IR Note :
 293 each of the command-line arguments that is a key ID is encoded in
 294 .I decimal
 295 (unlike the key IDs shown in
 296 .IR /proc/keys ,
 297 which are shown as hexadecimal values).
 298 .IP d)
 299 The program spawned in the previous step:
 300 .RS
 301 .IP * 3
 302 Assumes the authority to instantiate the key U using the
 303 .BR keyctl (2)
 304 .B KEYCTL_ASSUME_AUTHORITY
 305 operation (typically via the
 306 .BR keyctl_assume_authority (3)
 307 function).
 308 .IP *
 309 Obtains the callout data from the payload of the authorization key V
 310 (using the
 311 .BR keyctl (2)
 312 .B KEYCTL_READ
 313 operation (or, more commonly, the
 314 .BR keyctl_read (3)
 315 function) with a key ID value of
 316 .BR KEY_SPEC_REQKEY_AUTH_KEY ).
 317 .IP *
 318 Instantiates the key
 319 (or execs another program that performs that task),
 320 specifying the payload and destination keyring.
 321 (The destination keyring that the requestor specified when calling
 322 .BR request_key ()
 323 can be accessed using the special key ID
 324 .BR KEY_SPEC_REQUESTOR_KEYRING .)
 325 .\" Should an instantiating program be using KEY_SPEC_REQUESTOR_KEYRING?
 326 .\" I couldn't find a use in the keyutils git repo.
 327 .\" According to David Howells:
 328 .\" * This feature is provided, but not used at the moment.
 329 .\" * A key added to that ring is then owned by the requester
 330 Instantiation is performed using the
 331 .BR keyctl (2)
 332 .B KEYCTL_INSTANTIATE
 333 operation (or, more commonly, the
 334 .BR keyctl_instantiate (3)
 335 function).
 336 At this point, the
 337 .BR request_key ()
 338 call completes, and the requesting program can continue execution.
 339 .RE
 340 .PP
 341 If these steps are unsuccessful, then an
 342 .B ENOKEY
 343 error will be returned to the caller of
 344 .BR request_key ()
 345 and a temporary, negatively instantiated key will be installed
 346 in the keyring specified by
 347 .IR dest_keyring .
 348 This will expire after a few seconds, but will cause subsequent calls to
 349 .BR request_key ()
 350 to fail until it does.
 351 The purpose of this negatively instantiated key is to prevent
 352 (possibly different) processes making repeated requests
 353 (that require expensive
 354 .BR request\-key (8)
 355 upcalls) for a key that can't (at the moment) be positively instantiated.
 356 .PP
 357 Once the key has been instantiated, the authorization key
 358 .RB ( KEY_SPEC_REQKEY_AUTH_KEY )
 359 is revoked, and the destination keyring
 360 .RB ( KEY_SPEC_REQUESTOR_KEYRING )
 361 is no longer accessible from the
 362 .BR request\-key (8)
 363 program.
 364 .PP
 365 If a key is created, then\(emregardless of whether it is a valid key or
 366 a negatively instantiated key\(emit will displace any other key with
 367 the same type and description from the keyring specified in
 368 .IR dest_keyring .
 369 .SH RETURN VALUE
 370 On success,
 371 .BR request_key ()
 372 returns the serial number of the key it found or caused to be created.
 373 On error, \-1 is returned and
 374 .I errno
 375 is set to indicate the error.
 376 .SH ERRORS
 377 .TP
 378 .B EACCES
 379 The keyring wasn't available for modification by the user.
 380 .TP
 381 .B EDQUOT
 382 The key quota for this user would be exceeded by creating this key or linking
 383 it to the keyring.
 384 .TP
 385 .B EFAULT
 386 One of
 387 .IR type ,
 388 .IR description ,
 389 or
 390 .I callout_info
 391 points outside the process's accessible address space.
 392 .TP
 393 .B EINTR
 394 The request was interrupted by a signal; see
 395 .BR signal (7).
 396 .TP
 397 .B EINVAL
 398 The size of the string (including the terminating null byte) specified in
 399 .I type
 400 or
 401 .I description
 402 exceeded the limit (32 bytes and 4096 bytes respectively).
 403 .TP
 404 .B EINVAL
 405 The size of the string (including the terminating null byte) specified in
 406 .I callout_info
 407 exceeded the system page size.
 408 .TP
 409 .B EKEYEXPIRED
 410 An expired key was found, but no replacement could be obtained.
 411 .TP
 412 .B EKEYREJECTED
 413 The attempt to generate a new key was rejected.
 414 .TP
 415 .B EKEYREVOKED
 416 A revoked key was found, but no replacement could be obtained.
 417 .TP
 418 .B ENOKEY
 419 No matching key was found.
 420 .TP
 421 .B ENOMEM
 422 Insufficient memory to create a key.
 423 .TP
 424 .B EPERM
 425 The
 426 .I type
 427 argument started with a period (\(aq.\(aq).
 428 .SH VERSIONS
 429 This system call first appeared in Linux 2.6.10.
 430 The ability to instantiate keys upon request was added
 431 .\" commit 3e30148c3d524a9c1c63ca28261bc24c457eb07a
 432 in Linux 2.6.13.
 433 .SH STANDARDS
 434 This system call is a nonstandard Linux extension.
 435 .SH EXAMPLES
 436 The program below demonstrates the use of
 437 .BR request_key ().
 438 The
 439 .IR type ,
 440 .IR description ,
 441 and
 442 .I callout_info
 443 arguments for the system call are taken from the values
 444 supplied in the command-line arguments.
 445 The call specifies the session keyring as the target keyring.
 446 .PP
 447 In order to demonstrate this program,
 448 we first create a suitable entry in the file
 449 .IR /etc/request\-key.conf .
 450 .PP
 451 .in +4n
 452 .EX
 453 $ sudo sh
 454 # \fBecho \(aqcreate user mtk:* *   /bin/keyctl instantiate %k %c %S\(aq \e\fP
 455           \fB> /etc/request\-key.conf\fP
 456 # \fBexit\fP
 457 .EE
 458 .in
 459 .PP
 460 This entry specifies that when a new "user" key with the prefix
 461 "mtk:" must be instantiated, that task should be performed via the
 462 .BR keyctl (1)
 463 command's
 464 .B instantiate
 465 operation.
 466 The arguments supplied to the
 467 .B instantiate
 468 operation are:
 469 the ID of the uninstantiated key
 470 .RI ( %k );
 471 the callout data supplied to the
 472 .BR request_key ()
 473 call
 474 .RI ( %c );
 475 and the session keyring
 476 .RI ( %S )
 477 of the requestor (i.e., the caller of
 478 .BR request_key ()).
 479 See
 480 .BR request\-key.conf (5)
 481 for details of these
 482 .I %
 483 specifiers.
 484 .PP
 485 Then we run the program and check the contents of
 486 .I /proc/keys
 487 to verify that the requested key has been instantiated:
 488 .PP
 489 .in +4n
 490 .EX
 491 $ \fB./t_request_key user mtk:key1 "Payload data"\fP
 492 $ \fBgrep \(aq2dddaf50\(aq /proc/keys\fP
 493 2dddaf50 I\-\-Q\-\-\-  1 perm 3f010000  1000  1000 user  mtk:key1: 12
 494 .EE
 495 .in
 496 .PP
 497 For another example of the use of this program, see
 498 .BR keyctl (2).
 499 .SS Program source
 500 \&
 501 .\" SRC BEGIN (t_request_key.c)
 502 .EX
 503 /* t_request_key.c */
 504
 505 #include <keyutils.h>
 506 #include <stdint.h>
 507 #include <stdio.h>
 508 #include <stdlib.h>
 509
 510 int
 511 main(int argc, char *argv[])
 512 {
 513     key_serial_t key;
 514
 515     if (argc != 4) {
 516         fprintf(stderr, "Usage: %s type description callout\-data\en",
 517                 argv[0]);
 518         exit(EXIT_FAILURE);
 519     }
 520
 521     key = request_key(argv[1], argv[2], argv[3],
 522                       KEY_SPEC_SESSION_KEYRING);
 523     if (key == \-1) {
 524         perror("request_key");
 525         exit(EXIT_FAILURE);
 526     }
 527
 528     printf("Key ID is %jx\en", (uintmax_t) key);
 529
 530     exit(EXIT_SUCCESS);
 531 }
 532 .EE
 533 .\" SRC END
 534 .SH SEE ALSO
 535 .ad l
 536 .nh
 537 .BR keyctl (1),
 538 .BR add_key (2),
 539 .BR keyctl (2),
 540 .BR keyctl (3),
 541 .BR capabilities (7),
 542 .BR keyrings (7),
 543 .BR keyutils (7),
 544 .BR persistent\-keyring (7),
 545 .BR process\-keyring (7),
 546 .BR session\-keyring (7),
 547 .BR thread\-keyring (7),
 548 .BR user\-keyring (7),
 549 .BR user\-session\-keyring (7),
 550 .BR request\-key (8)
 551 .PP
 552 The kernel source files
 553 .I Documentation/security/keys/core.rst
 554 and
 555 .I Documentation/keys/request\-key.rst
 556 (or, before Linux 4.13, in the files
 557 .\" commit b68101a1e8f0263dbc7b8375d2a7c57c6216fb76
 558 .I Documentation/security/keys.txt
 559 and
 560 .\" commit 3db38ed76890565772fcca3279cc8d454ea6176b
 561 .IR Documentation/security/keys\-request\-key.txt ).