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