man2/keyctl.2

   1 .\" Copyright (C) 2016 Michael Kerrisk <mtk.manpages@gmail.com>
   2 .\" and Copyright (C) 2016 Eugene Syromyatnikov <evgsyr@gmail.com>
   3 .\" A very few fragments remain from an earlier version of this page
   4 .\" written by David Howells (dhowells@redhat.com)
   5 .\"
   6 .\" %%%LICENSE_START(VERBATIM)
   7 .\" Permission is granted to make and distribute verbatim copies of this
   8 .\" manual provided the copyright notice and this permission notice are
   9 .\" preserved on all copies.
  10 .\"
  11 .\" Permission is granted to copy and distribute modified versions of this
  12 .\" manual under the conditions for verbatim copying, provided that the
  13 .\" entire resulting derived work is distributed under the terms of a
  14 .\" permission notice identical to this one.
  15 .\"
  16 .\" Since the Linux kernel and libraries are constantly changing, this
  17 .\" manual page may be incorrect or out-of-date.  The author(s) assume no
  18 .\" responsibility for errors or omissions, or for damages resulting from
  19 .\" the use of the information contained herein.  The author(s) may not
  20 .\" have taken the same level of care in the production of this manual,
  21 .\" which is licensed free of charge, as they might when working
  22 .\" professionally.
  23 .\"
  24 .\" Formatted or processed versions of this manual, if unaccompanied by
  25 .\" the source, must acknowledge the copyright and authors of this work.
  26 .\" %%%LICENSE_END
  27 .\"
  28 .TH KEYCTL 2 2021-03-22 Linux "Linux Key Management Calls"
  29 .SH NAME
  30 keyctl \- manipulate the kernel's key management facility
  31 .SH SYNOPSIS
  32 .nf
  33 .BR "#include <linux/keyctl.h>" "     /* Definition of " KEY* " constants */"
  34 .BR "#include <sys/syscall.h>" "      /* Definition of " SYS_* " constants */"
  35 .B #include <unistd.h>
  36 .PP
  37 .BI "long syscall(SYS_keyctl, int " operation ", unsigned long " arg2 ,
  38 .BI "             unsigned long " arg3 ", unsigned long " arg4 ,
  39 .BI "             unsigned long " arg5 );
  40 .fi
  41 .PP
  42 .IR Note :
  43 glibc provides no wrapper for
  44 .BR keyctl (),
  45 necessitating the use of
  46 .BR syscall (2).
  47 .SH DESCRIPTION
  48 .BR keyctl ()
  49 allows user-space programs to perform key manipulation.
  50 .PP
  51 The operation performed by
  52 .BR keyctl ()
  53 is determined by the value of the
  54 .I operation
  55 argument.
  56 Each of these operations is wrapped by the
  57 .I libkeyutils
  58 library (provided by the
  59 .I keyutils
  60 package) into individual functions (noted below)
  61 to permit the compiler to check types.
  62 .PP
  63 The permitted values for
  64 .I operation
  65 are:
  66 .TP
  67 .BR KEYCTL_GET_KEYRING_ID " (since Linux 2.6.10)"
  68 Map a special key ID to a real key ID for this process.
  69 .IP
  70 This operation looks up the special key whose ID is provided in
  71 .I arg2
  72 (cast to
  73 .IR key_serial_t ).
  74 If the special key is found,
  75 the ID of the corresponding real key is returned as the function result.
  76 The following values may be specified in
  77 .IR arg2 :
  78 .RS
  79 .TP
  80 .B KEY_SPEC_THREAD_KEYRING
  81 This specifies the calling thread's thread-specific keyring.
  82 See
  83 .BR thread\-keyring (7).
  84 .TP
  85 .B KEY_SPEC_PROCESS_KEYRING
  86 This specifies the caller's process-specific keyring.
  87 See
  88 .BR process\-keyring (7).
  89 .TP
  90 .B KEY_SPEC_SESSION_KEYRING
  91 This specifies the caller's session-specific keyring.
  92 See
  93 .BR session\-keyring (7).
  94 .TP
  95 .B KEY_SPEC_USER_KEYRING
  96 This specifies the caller's UID-specific keyring.
  97 See
  98 .BR user\-keyring (7).
  99 .TP
 100 .B KEY_SPEC_USER_SESSION_KEYRING
 101 This specifies the caller's UID-session keyring.
 102 See
 103 .BR user\-session\-keyring (7).
 104 .TP
 105 .BR KEY_SPEC_REQKEY_AUTH_KEY " (since Linux 2.6.16)"
 106 .\"            commit b5f545c880a2a47947ba2118b2509644ab7a2969
 107 This specifies the authorization key created by
 108 .BR request_key (2)
 109 and passed to the process it spawns to generate a key.
 110 This key is available only in a
 111 .BR request\-key (8)-style
 112 program that was passed an authorization key by the kernel and
 113 ceases to be available once the requested key has been instantiated; see
 114 .BR request_key (2).
 115 .TP
 116 .BR KEY_SPEC_REQUESTOR_KEYRING " (since Linux 2.6.29)"
 117 .\"            commit 8bbf4976b59fc9fc2861e79cab7beb3f6d647640
 118 This specifies the key ID for the
 119 .BR request_key (2)
 120 destination keyring.
 121 This keyring is available only in a
 122 .BR request\-key (8)-style
 123 program that was passed an authorization key by the kernel and
 124 ceases to be available once the requested key has been instantiated; see
 125 .BR request_key (2).
 126 .RE
 127 .IP
 128 The behavior if the key specified in
 129 .I arg2
 130 does not exist depends on the value of
 131 .I arg3
 132 (cast to
 133 .IR int ).
 134 If
 135 .I arg3
 136 contains a nonzero value, then\(emif it is appropriate to do so
 137 (e.g., when looking up the user, user-session, or session key)\(ema new key
 138 is created and its real key ID returned as the function result.
 139 .\" The keyctl_get_keyring_ID.3 page says that a new key
 140 .\" "will be created *if it is appropriate to do so**. What is the
 141 .\" determiner for appropriate?
 142 .\" David Howells: Some special keys such as KEY_SPEC_REQKEY_AUTH_KEY
 143 .\" wouldn't get created but user/user-session/session keyring would
 144 .\" be created.
 145 Otherwise, the operation fails with the error
 146 .BR ENOKEY .
 147 .IP
 148 If a valid key ID is specified in
 149 .IR arg2 ,
 150 and the key exists, then this operation simply returns the key ID.
 151 If the key does not exist, the call fails with error
 152 .BR ENOKEY .
 153 .IP
 154 The caller must have
 155 .I search
 156 permission on a keyring in order for it to be found.
 157 .IP
 158 The arguments
 159 .IR arg4
 160 and
 161 .IR arg5
 162 are ignored.
 163 .IP
 164 This operation is exposed by
 165 .I libkeyutils
 166 via the function
 167 .BR keyctl_get_keyring_ID (3).
 168 .TP
 169 .BR KEYCTL_JOIN_SESSION_KEYRING " (since Linux 2.6.10)"
 170 Replace the session keyring this process subscribes to with
 171 a new session keyring.
 172 .\" This may be useful in conjunction with some sort of
 173 .\" session management framework that is employed by the application.
 174 .IP
 175 If
 176 .I arg2
 177 is NULL,
 178 an anonymous keyring with the description "_ses" is created
 179 and the process is subscribed to that keyring as its session keyring,
 180 displacing the previous session keyring.
 181 .IP
 182 Otherwise,
 183 .I arg2
 184 (cast to
 185 .IR "char\ *" )
 186 is treated as the description (name) of a keyring,
 187 and the behavior is as follows:
 188 .RS
 189 .IP * 3
 190 If a keyring with a matching description exists,
 191 the process will attempt to subscribe to that keyring
 192 as its session keyring if possible;
 193 if that is not possible, an error is returned.
 194 In order to subscribe to the keyring,
 195 the caller must have
 196 .I search
 197 permission on the keyring.
 198 .IP *
 199 If a keyring with a matching description does not exist,
 200 then a new keyring with the specified description is created,
 201 and the process is subscribed to that keyring as its session keyring.
 202 .RE
 203 .IP
 204 The arguments
 205 .IR arg3 ,
 206 .IR arg4 ,
 207 and
 208 .IR arg5
 209 are ignored.
 210 .IP
 211 This operation is exposed by
 212 .I libkeyutils
 213 via the function
 214 .BR keyctl_join_session_keyring (3).
 215 .TP
 216 .BR KEYCTL_UPDATE " (since Linux 2.6.10)"
 217 Update a key's data payload.
 218 .IP
 219 The
 220 .I arg2
 221 argument (cast to
 222 .IR key_serial_t )
 223 specifies the ID of the key to be updated.
 224 The
 225 .I arg3
 226 argument (cast to
 227 .IR "void\ *" )
 228 points to the new payload and
 229 .I arg4
 230 (cast to
 231 .IR size_t )
 232 contains the new payload size in bytes.
 233 .IP
 234 The caller must have
 235 .I write
 236 permission on the key specified and the key type must support updating.
 237 .IP
 238 A negatively instantiated key (see the description of
 239 .BR KEYCTL_REJECT )
 240 can be positively instantiated with this operation.
 241 .IP
 242 The
 243 .I arg5
 244 argument is ignored.
 245 .IP
 246 This operation is exposed by
 247 .I libkeyutils
 248 via the function
 249 .BR keyctl_update (3).
 250 .TP
 251 .BR KEYCTL_REVOKE " (since Linux 2.6.10)"
 252 Revoke the key with the ID provided in
 253 .I arg2
 254 (cast to
 255 .IR key_serial_t ).
 256 The key is scheduled for garbage collection;
 257 it will no longer be findable,
 258 and will be unavailable for further operations.
 259 Further attempts to use the key will fail with the error
 260 .BR EKEYREVOKED .
 261 .IP
 262 The caller must have
 263 .IR write
 264 or
 265 .IR setattr
 266 permission on the key.
 267 .\" Keys with the KEY_FLAG_KEEP bit set cause an EPERM
 268 .\" error for KEYCTL_REVOKE. Does this need to be documented?
 269 .\" David Howells: No significance for user space.
 270 .IP
 271 The arguments
 272 .IR arg3 ,
 273 .IR arg4 ,
 274 and
 275 .IR arg5
 276 are ignored.
 277 .IP
 278 This operation is exposed by
 279 .I libkeyutils
 280 via the function
 281 .BR keyctl_revoke (3).
 282 .TP
 283 .BR KEYCTL_CHOWN " (since Linux 2.6.10)"
 284 Change the ownership (user and group ID) of a key.
 285 .IP
 286 The
 287 .I arg2
 288 argument (cast to
 289 .IR key_serial_t )
 290 contains the key ID.
 291 The
 292 .I arg3
 293 argument (cast to
 294 .IR uid_t )
 295 contains the new user ID (or \-1 in case the user ID shouldn't be changed).
 296 The
 297 .I arg4
 298 argument (cast to
 299 .IR gid_t )
 300 contains the new group ID (or \-1 in case the group ID shouldn't be changed).
 301 .IP
 302 The key must grant the caller
 303 .I setattr
 304 permission.
 305 .IP
 306 For the UID to be changed, or for the GID to be changed to a group
 307 the caller is not a member of, the caller must have the
 308 .B CAP_SYS_ADMIN
 309 capability (see
 310 .BR capabilities (7)).
 311 .IP
 312 If the UID is to be changed, the new user must have sufficient
 313 quota to accept the key.
 314 The quota deduction will be removed from the old user
 315 to the new user should the UID be changed.
 316 .IP
 317 The
 318 .I arg5
 319 argument is ignored.
 320 .IP
 321 This operation is exposed by
 322 .I libkeyutils
 323 via the function
 324 .BR keyctl_chown (3).
 325 .TP
 326 .BR KEYCTL_SETPERM " (since Linux 2.6.10)"
 327 Change the permissions of the key with the ID provided in the
 328 .I arg2
 329 argument (cast to
 330 .IR key_serial_t )
 331 to the permissions provided in the
 332 .I arg3
 333 argument (cast to
 334 .IR key_perm_t ).
 335 .IP
 336 If the caller doesn't have the
 337 .B CAP_SYS_ADMIN
 338 capability, it can change permissions only for the keys it owns.
 339 (More precisely: the caller's filesystem UID must match the UID of the key.)
 340 .IP
 341 The key must grant
 342 .I setattr
 343 permission to the caller
 344 .IR regardless
 345 of the caller's capabilities.
 346 .\" FIXME Above, is it really intended that a privileged process can't
 347 .\" override the lack of the 'setattr' permission?
 348 .IP
 349 The permissions in
 350 .IR arg3
 351 specify masks of available operations
 352 for each of the following user categories:
 353 .RS
 354 .TP
 355 .IR possessor " (since Linux 2.6.14)"
 356 .\" commit 664cceb0093b755739e56572b836a99104ee8a75
 357 This is the permission granted to a process that possesses the key
 358 (has it attached searchably to one of the process's keyrings);
 359 see
 360 .BR keyrings (7).
 361 .TP
 362 .IR user
 363 This is the permission granted to a process
 364 whose filesystem UID matches the UID of the key.
 365 .TP
 366 .IR group
 367 This is the permission granted to a process
 368 whose filesystem GID or any of its supplementary GIDs
 369 matches the GID of the key.
 370 .TP
 371 .IR other
 372 This is the permission granted to other processes
 373 that do not match the
 374 .IR user
 375 and
 376 .IR group
 377 categories.
 378 .RE
 379 .IP
 380 The
 381 .IR user ,
 382 .IR group ,
 383 and
 384 .IR other
 385 categories are exclusive: if a process matches the
 386 .IR user
 387 category, it will not receive permissions granted in the
 388 .IR group
 389 category; if a process matches the
 390 .I user
 391 or
 392 .IR group
 393 category, then it will not receive permissions granted in the
 394 .IR other
 395 category.
 396 .IP
 397 The
 398 .I possessor
 399 category grants permissions that are cumulative with the grants from the
 400 .IR user ,
 401 .IR group ,
 402 or
 403 .IR other
 404 category.
 405 .IP
 406 Each permission mask is eight bits in size,
 407 with only six bits currently used.
 408 The available permissions are:
 409 .RS
 410 .TP
 411 .IR view
 412 This permission allows reading attributes of a key.
 413 .IP
 414 This permission is required for the
 415 .BR KEYCTL_DESCRIBE
 416 operation.
 417 .IP
 418 The permission bits for each category are
 419 .BR KEY_POS_VIEW ,
 420 .BR KEY_USR_VIEW ,
 421 .BR KEY_GRP_VIEW ,
 422 and
 423 .BR KEY_OTH_VIEW .
 424 .TP
 425 .IR read
 426 This permission allows reading a key's payload.
 427 .IP
 428 This permission is required for the
 429 .BR KEYCTL_READ
 430 operation.
 431 .IP
 432 The permission bits for each category are
 433 .BR KEY_POS_READ ,
 434 .BR KEY_USR_READ ,
 435 .BR KEY_GRP_READ ,
 436 and
 437 .BR KEY_OTH_READ .
 438 .TP
 439 .IR write
 440 This permission allows update or instantiation of a key's payload.
 441 For a keyring, it allows keys to be linked and unlinked from the keyring,
 442 .IP
 443 This permission is required for the
 444 .BR KEYCTL_UPDATE ,
 445 .BR KEYCTL_REVOKE ,
 446 .BR KEYCTL_CLEAR ,
 447 .BR KEYCTL_LINK ,
 448 and
 449 .BR KEYCTL_UNLINK
 450 operations.
 451 .IP
 452 The permission bits for each category are
 453 .BR KEY_POS_WRITE ,
 454 .BR KEY_USR_WRITE ,
 455 .BR KEY_GRP_WRITE ,
 456 and
 457 .BR KEY_OTH_WRITE .
 458 .TP
 459 .IR search
 460 This permission allows keyrings to be searched and keys to be found.
 461 Searches can recurse only into nested keyrings that have
 462 .I search
 463 permission set.
 464 .IP
 465 This permission is required for the
 466 .BR KEYCTL_GET_KEYRING_ID ,
 467 .BR KEYCTL_JOIN_SESSION_KEYRING ,
 468 .BR KEYCTL_SEARCH ,
 469 and
 470 .BR KEYCTL_INVALIDATE
 471 operations.
 472 .IP
 473 The permission bits for each category are
 474 .BR KEY_POS_SEARCH ,
 475 .BR KEY_USR_SEARCH ,
 476 .BR KEY_GRP_SEARCH ,
 477 and
 478 .BR KEY_OTH_SEARCH .
 479 .TP
 480 .IR link
 481 This permission allows a key or keyring to be linked to.
 482 .IP
 483 This permission is required for the
 484 .BR KEYCTL_LINK
 485 and
 486 .BR KEYCTL_SESSION_TO_PARENT
 487 operations.
 488 .IP
 489 The permission bits for each category are
 490 .BR KEY_POS_LINK ,
 491 .BR KEY_USR_LINK ,
 492 .BR KEY_GRP_LINK ,
 493 and
 494 .BR KEY_OTH_LINK .
 495 .TP
 496 .IR setattr " (since Linux 2.6.15)."
 497 This permission allows a key's UID, GID, and permissions mask to be changed.
 498 .IP
 499 This permission is required for the
 500 .BR KEYCTL_REVOKE ,
 501 .BR KEYCTL_CHOWN ,
 502 and
 503 .BR KEYCTL_SETPERM
 504 operations.
 505 .IP
 506 The permission bits for each category are
 507 .BR KEY_POS_SETATTR ,
 508 .BR KEY_USR_SETATTR ,
 509 .BR KEY_GRP_SETATTR ,
 510 and
 511 .BR KEY_OTH_SETATTR .
 512 .RE
 513 .IP
 514 As a convenience, the following macros are defined as masks for
 515 all of the permission bits in each of the user categories:
 516 .BR KEY_POS_ALL ,
 517 .BR KEY_USR_ALL ,
 518 .BR KEY_GRP_ALL ,
 519 and
 520 .BR KEY_OTH_ALL .
 521 .IP
 522 The
 523 .IR arg4 " and " arg5
 524 arguments are ignored.
 525 .IP
 526 This operation is exposed by
 527 .I libkeyutils
 528 via the function
 529 .BR keyctl_setperm (3).
 530 .TP
 531 .BR KEYCTL_DESCRIBE " (since Linux 2.6.10)"
 532 Obtain a string describing the attributes of a specified key.
 533 .IP
 534 The ID of the key to be described is specified in
 535 .I arg2
 536 (cast to
 537 .IR key_serial_t ).
 538 The descriptive string is returned in the buffer pointed to by
 539 .I arg3
 540 (cast to
 541 .IR "char\ *" );
 542 .I arg4
 543 (cast to
 544 .IR size_t )
 545 specifies the size of that buffer in bytes.
 546 .IP
 547 The key must grant the caller
 548 .I view
 549 permission.
 550 .IP
 551 The returned string is null-terminated and
 552 contains the following information about the key:
 553 .IP
 554 .in +4n
 555 .IR type ; uid ; gid ; perm ; description
 556 .in
 557 .IP
 558 In the above,
 559 .IR type
 560 and
 561 .IR description
 562 are strings,
 563 .IR uid
 564 and
 565 .IR gid
 566 are decimal strings, and
 567 .I perm
 568 is a hexadecimal permissions mask.
 569 The descriptive string is written with the following format:
 570 .IP
 571     %s;%d;%d;%08x;%s
 572 .IP
 573 .BR "Note: the intention is that the descriptive string should"
 574 .BR "be extensible in future kernel versions".
 575 In particular, the
 576 .IR description
 577 field will not contain semicolons;
 578 .\" FIXME But, the kernel does not enforce the requirement
 579 .\" that the key description contains no semicolons!
 580 .\" So, user space has no guarantee here??
 581 .\" Either something more needs to be said here,
 582 .\" or a kernel fix is required.
 583 it should be parsed by working backwards from the end of the string
 584 to find the last semicolon.
 585 This allows future semicolon-delimited fields to be inserted
 586 in the descriptive string in the future.
 587 .IP
 588 Writing to the buffer is attempted only when
 589 .IR arg3
 590 is non-NULL and the specified buffer size
 591 is large enough to accept the descriptive string
 592 (including the terminating null byte).
 593 .\" Function commentary says it copies up to buflen bytes, but see the
 594 .\" (buffer && buflen >= ret) condition in keyctl_describe_key() in
 595 .\" security/keyctl.c
 596 In order to determine whether the buffer size was too small,
 597 check to see if the return value of the operation is greater than
 598 .IR arg4 .
 599 .IP
 600 The
 601 .I arg5
 602 argument is ignored.
 603 .IP
 604 This operation is exposed by
 605 .I libkeyutils
 606 via the function
 607 .BR keyctl_describe (3).
 608 .TP
 609 .B KEYCTL_CLEAR
 610 Clear the contents of (i.e., unlink all keys from) a keyring.
 611 .IP
 612 The ID of the key
 613 (which must be of keyring type)
 614 .\" or the error ENOTDIR results
 615 is provided in
 616 .I arg2
 617 (cast to
 618 .IR key_serial_t ).
 619 .\" According to Documentation/security/keys.txt:
 620 .\"     This function can also be used to clear special kernel keyrings if they
 621 .\"     are appropriately marked if the user has CAP_SYS_ADMIN capability.  The
 622 .\"     DNS resolver cache keyring is an example of this.
 623 .IP
 624 The caller must have
 625 .I write
 626 permission on the keyring.
 627 .IP
 628 The arguments
 629 .IR arg3 ,
 630 .IR arg4 ,
 631 and
 632 .IR arg5
 633 are ignored.
 634 .IP
 635 This operation is exposed by
 636 .I libkeyutils
 637 via the function
 638 .BR keyctl_clear (3).
 639 .TP
 640 .BR KEYCTL_LINK " (since Linux 2.6.10)"
 641 Create a link from a keyring to a key.
 642 .IP
 643 The key to be linked is specified in
 644 .IR arg2
 645 (cast to
 646 .IR key_serial_t );
 647 the keyring is specified in
 648 .IR arg3
 649 (cast to
 650 .IR key_serial_t ).
 651 .IP
 652 If a key with the same type and description is already linked in the keyring,
 653 then that key is displaced from the keyring.
 654 .IP
 655 Before creating the link,
 656 the kernel checks the nesting of the keyrings and returns appropriate errors
 657 if the link would produce a cycle
 658 or if the nesting of keyrings would be too deep
 659 (The limit on the nesting of keyrings is determined by the kernel constant
 660 .BR KEYRING_SEARCH_MAX_DEPTH ,
 661 defined with the value 6, and is necessary to prevent overflows
 662 on the kernel stack when recursively searching keyrings).
 663 .IP
 664 The caller must have
 665 .I link
 666 permission on the key being added and
 667 .I write
 668 permission on the keyring.
 669 .IP
 670 The arguments
 671 .IR arg4
 672 and
 673 .IR arg5
 674 are ignored.
 675 .IP
 676 This operation is exposed by
 677 .I libkeyutils
 678 via the function
 679 .BR keyctl_link (3).
 680 .TP
 681 .BR KEYCTL_UNLINK " (since Linux 2.6.10)"
 682 Unlink a key from a keyring.
 683 .IP
 684 The ID of the key to be unlinked is specified in
 685 .I arg2
 686 (cast to
 687 .IR key_serial_t );
 688 the ID of the keyring from which it is to be unlinked is specified in
 689 .I arg3
 690 (cast to
 691 .IR key_serial_t ).
 692 .IP
 693 If the key is not currently linked into the keyring, an error results.
 694 .IP
 695 The caller must have
 696 .I write
 697 permission on the keyring from which the key is being removed.
 698 .IP
 699 If the last link to a key is removed,
 700 then that key will be scheduled for destruction.
 701 .IP
 702 The arguments
 703 .IR arg4
 704 and
 705 .IR arg5
 706 are ignored.
 707 .IP
 708 This operation is exposed by
 709 .I libkeyutils
 710 via the function
 711 .BR keyctl_unlink (3).
 712 .TP
 713 .BR KEYCTL_SEARCH " (since Linux 2.6.10)"
 714 Search for a key in a keyring tree,
 715 returning its ID and optionally linking it to a specified keyring.
 716 .IP
 717 The tree to be searched is specified by passing
 718 the ID of the head keyring in
 719 .IR arg2
 720 (cast to
 721 .IR key_serial_t ).
 722 The search is performed breadth-first and recursively.
 723 .IP
 724 The
 725 .I arg3
 726 and
 727 .I arg4
 728 arguments specify the key to be searched for:
 729 .I arg3
 730 (cast as
 731 .IR "char\ *" )
 732 contains the key type
 733 (a null-terminated character string up to 32 bytes in size,
 734 including the terminating null byte), and
 735 .I arg4
 736 (cast as
 737 .IR "char\ *" )
 738 contains the description of the key
 739 (a null-terminated character string up to 4096 bytes in size,
 740 including the terminating null byte).
 741 .IP
 742 The source keyring must grant
 743 .I search
 744 permission to the caller.
 745 When performing the recursive search, only keyrings that grant the caller
 746 .I search
 747 permission will be searched.
 748 Only keys with for which the caller has
 749 .I search
 750 permission can be found.
 751 .IP
 752 If the key is found, its ID is returned as the function result.
 753 .IP
 754 If the key is found and
 755 .I arg5
 756 (cast to
 757 .IR key_serial_t )
 758 is nonzero, then, subject to the same constraints and rules as
 759 .BR KEYCTL_LINK ,
 760 the key is linked into the keyring whose ID is specified in
 761 .IR arg5 .
 762 If the destination keyring specified in
 763 .I arg5
 764 already contains a link to a key that has the same type and description,
 765 then that link will be displaced by a link to
 766 the key found by this operation.
 767 .IP
 768 Instead of valid existing keyring IDs, the source
 769 .RI ( arg2 )
 770 and destination
 771 .RI ( arg5 )
 772 keyrings can be one of the special keyring IDs listed under
 773 .BR KEYCTL_GET_KEYRING_ID .
 774 .IP
 775 This operation is exposed by
 776 .I libkeyutils
 777 via the function
 778 .BR keyctl_search (3).
 779 .TP
 780 .BR KEYCTL_READ " (since Linux 2.6.10)"
 781 Read the payload data of a key.
 782 .IP
 783 The ID of the key whose payload is to be read is specified in
 784 .I arg2
 785 (cast to
 786 .IR key_serial_t ).
 787 This can be the ID of an existing key,
 788 or any of the special key IDs listed for
 789 .BR KEYCTL_GET_KEYRING_ID .
 790 .\" including KEY_SPEC_REQKEY_AUTH_KEY
 791 .IP
 792 The payload is placed in the buffer pointed by
 793 .I arg3
 794 (cast to
 795 .IR "char\ *" );
 796 the size of that buffer must be specified in
 797 .I arg4
 798 (cast to
 799 .IR size_t ).
 800 .IP
 801 The returned data will be processed for presentation
 802 according to the key type.
 803 For example, a keyring will return an array of
 804 .I key_serial_t
 805 entries representing the IDs of all the keys that are linked to it.
 806 The
 807 .IR "user"
 808 key type will return its data as is.
 809 If a key type does not implement this function,
 810 the operation fails with the error
 811 .BR EOPNOTSUPP .
 812 .IP
 813 If
 814 .I arg3
 815 is not NULL,
 816 as much of the payload data as will fit is copied into the buffer.
 817 On a successful return,
 818 the return value is always the total size of the payload data.
 819 To determine whether the buffer was of sufficient size,
 820 check to see that the return value is less than or equal to
 821 the value supplied in
 822 .IR arg4 .
 823 .IP
 824 The key must either grant the caller
 825 .I read
 826 permission, or grant the caller
 827 .I search
 828 permission when searched for from the process keyrings
 829 (i.e., the key is possessed).
 830 .IP
 831 The
 832 .I arg5
 833 argument is ignored.
 834 .IP
 835 This operation is exposed by
 836 .I libkeyutils
 837 via the function
 838 .BR keyctl_read (3).
 839 .TP
 840 .BR KEYCTL_INSTANTIATE " (since Linux 2.6.10)"
 841 (Positively) instantiate an uninstantiated key with a specified payload.
 842 .IP
 843 The ID of the key to be instantiated is provided in
 844 .I arg2
 845 (cast to
 846 .IR key_serial_t ).
 847 .IP
 848 The key payload is specified in the buffer pointed to by
 849 .I arg3
 850 (cast to
 851 .IR "void\ *");
 852 the size of that buffer is specified in
 853 .I arg4
 854 (cast to
 855 .IR size_t ).
 856 .IP
 857 The payload may be a NULL pointer and the buffer size may be 0
 858 if this is supported by the key type (e.g., it is a keyring).
 859 .IP
 860 The operation may be fail if the payload data is in the wrong format
 861 or is otherwise invalid.
 862 .IP
 863 If
 864 .I arg5
 865 (cast to
 866 .IR key_serial_t )
 867 is nonzero, then, subject to the same constraints and rules as
 868 .BR KEYCTL_LINK ,
 869 the instantiated key is linked into the keyring whose ID specified in
 870 .IR arg5 .
 871 .IP
 872 The caller must have the appropriate authorization key,
 873 and once the uninstantiated key has been instantiated,
 874 the authorization key is revoked.
 875 In other words, this operation is available only from a
 876 .BR request\-key (8)-style
 877 program.
 878 See
 879 .BR request_key (2)
 880 for an explanation of uninstantiated keys and key instantiation.
 881 .IP
 882 This operation is exposed by
 883 .I libkeyutils
 884 via the function
 885 .BR keyctl_instantiate (3).
 886 .TP
 887 .BR KEYCTL_NEGATE " (since Linux 2.6.10)"
 888 Negatively instantiate an uninstantiated key.
 889 .IP
 890 This operation is equivalent to the call:
 891 .IP
 892     keyctl(KEYCTL_REJECT, arg2, arg3, ENOKEY, arg4);
 893 .IP
 894 The
 895 .I arg5
 896 argument is ignored.
 897 .IP
 898 This operation is exposed by
 899 .I libkeyutils
 900 via the function
 901 .BR keyctl_negate (3).
 902 .TP
 903 .BR KEYCTL_SET_REQKEY_KEYRING " (since Linux 2.6.13)"
 904 Set the default keyring to which implicitly requested keys
 905 will be linked for this thread, and return the previous setting.
 906 Implicit key requests are those made by internal kernel components,
 907 .\" I.e., calls to the kernel's internal request_key() interface,
 908 .\" which is distinct from the request_key(2) system call (which
 909 .\" ultimately employs the kernel-internal interface).
 910 such as can occur when, for example, opening files
 911 on an AFS or NFS filesystem.
 912 Setting the default keyring also has an effect when requesting
 913 a key from user space; see
 914 .BR request_key (2)
 915 for details.
 916 .IP
 917 The
 918 .I arg2
 919 argument (cast to
 920 .IR int )
 921 should contain one of the following values,
 922 to specify the new default keyring:
 923 .RS
 924 .TP
 925 .BR KEY_REQKEY_DEFL_NO_CHANGE
 926 Don't change the default keyring.
 927 This can be used to discover the current default keyring
 928 (without changing it).
 929 .TP
 930 .BR KEY_REQKEY_DEFL_DEFAULT
 931 This selects the default behaviour,
 932 which is to use the thread-specific keyring if there is one,
 933 otherwise the process-specific keyring if there is one,
 934 otherwise the session keyring if there is one,
 935 otherwise the UID-specific session keyring,
 936 otherwise the user-specific keyring.
 937 .TP
 938 .BR KEY_REQKEY_DEFL_THREAD_KEYRING
 939 Use the thread-specific keyring
 940 .RB ( thread\-keyring (7))
 941 as the new default keyring.
 942 .TP
 943 .BR KEY_REQKEY_DEFL_PROCESS_KEYRING
 944 Use the process-specific keyring
 945 .RB ( process\-keyring (7))
 946 as the new default keyring.
 947 .TP
 948 .BR KEY_REQKEY_DEFL_SESSION_KEYRING
 949 Use the session-specific keyring
 950 .RB ( session\-keyring (7))
 951 as the new default keyring.
 952 .TP
 953 .BR KEY_REQKEY_DEFL_USER_KEYRING
 954 Use the UID-specific keyring
 955 .RB ( user\-keyring (7))
 956 as the new default keyring.
 957 .TP
 958 .BR KEY_REQKEY_DEFL_USER_SESSION_KEYRING
 959 Use the UID-specific session keyring
 960 .RB ( user\-session\-keyring (7))
 961 as the new default keyring.
 962 .TP
 963 .BR KEY_REQKEY_DEFL_REQUESTOR_KEYRING " (since Linux 2.6.29)"
 964 .\" 8bbf4976b59fc9fc2861e79cab7beb3f6d647640
 965 Use the requestor keyring.
 966 .\" FIXME The preceding explanation needs to be expanded.
 967 .\" Is the following correct:
 968 .\"
 969 .\"     The requestor keyring is the dest_keyring that
 970 .\"     was supplied to a call to request_key(2)?
 971 .\"
 972 .\" David Howells said: to be checked
 973 .RE
 974 .IP
 975 All other values are invalid.
 976 .\" (including the still-unsupported KEY_REQKEY_DEFL_GROUP_KEYRING)
 977 .IP
 978 The arguments
 979 .IR arg3 ,
 980 .IR arg4 ,
 981 and
 982 .IR arg5
 983 are ignored.
 984 .IP
 985 The setting controlled by this operation is inherited by the child of
 986 .BR fork (2)
 987 and preserved across
 988 .BR  execve (2).
 989 .IP
 990 This operation is exposed by
 991 .I libkeyutils
 992 via the function
 993 .BR keyctl_set_reqkey_keyring (3).
 994 .TP
 995 .BR KEYCTL_SET_TIMEOUT " (since Linux 2.6.16)"
 996 Set a timeout on a key.
 997 .IP
 998 The ID of the key is specified in
 999 .I arg2
1000 (cast to
1001 .IR key_serial_t ).
1002 The timeout value, in seconds from the current time,
1003 is specified in
1004 .I arg3
1005 (cast to
1006 .IR "unsigned int" ).
1007 The timeout is measured against the realtime clock.
1008 .IP
1009 Specifying the timeout value as 0 clears any existing timeout on the key.
1010 .IP
1011 The
1012 .I /proc/keys
1013 file displays the remaining time until each key will expire.
1014 (This is the only method of discovering the timeout on a key.)
1015 .IP
1016 The caller must either have the
1017 .I setattr
1018 permission on the key
1019 or hold an instantiation authorization token for the key (see
1020 .BR request_key (2)).
1021 .IP
1022 The key and any links to the key will be
1023 automatically garbage collected after the timeout expires.
1024 Subsequent attempts to access the key will then fail with the error
1025 .BR EKEYEXPIRED .
1026 .IP
1027 This operation cannot be used to set timeouts on revoked, expired,
1028 or negatively instantiated keys.
1029 .IP
1030 The arguments
1031 .IR arg4
1032 and
1033 .IR arg5
1034 are ignored.
1035 .IP
1036 This operation is exposed by
1037 .I libkeyutils
1038 via the function
1039 .BR keyctl_set_timeout (3).
1040 .TP
1041 .BR KEYCTL_ASSUME_AUTHORITY " (since Linux 2.6.16)"
1042 Assume (or divest) the authority for the calling thread
1043 to instantiate a key.
1044 .IP
1045 The
1046 .I arg2
1047 argument (cast to
1048 .IR key_serial_t )
1049 specifies either a nonzero key ID to assume authority,
1050 or the value 0 to divest authority.
1051 .IP
1052 If
1053 .I arg2
1054 is nonzero, then it specifies the ID of an uninstantiated key for which
1055 authority is to be assumed.
1056 That key can then be instantiated using one of
1057 .BR KEYCTL_INSTANTIATE ,
1058 .BR KEYCTL_INSTANTIATE_IOV ,
1059 .BR KEYCTL_REJECT ,
1060 or
1061 .BR KEYCTL_NEGATE .
1062 Once the key has been instantiated,
1063 the thread is automatically divested of authority to instantiate the key.
1064 .IP
1065 Authority over a key can be assumed only if the calling thread has present
1066 in its keyrings the authorization key that is
1067 associated with the specified key.
1068 (In other words, the
1069 .BR KEYCTL_ASSUME_AUTHORITY
1070 operation is available only from a
1071 .BR request\-key (8)-style
1072 program; see
1073 .BR request_key (2)
1074 for an explanation of how this operation is used.)
1075 The caller must have
1076 .I search
1077 permission on the authorization key.
1078 .IP
1079 If the specified key has a matching authorization key,
1080 then the ID of that key is returned.
1081 The authorization key can be read
1082 .RB ( KEYCTL_READ )
1083 to obtain the callout information passed to
1084 .BR request_key (2).
1085 .IP
1086 If the ID given in
1087 .I arg2
1088 is 0, then the currently assumed authority is cleared (divested),
1089 and the value 0 is returned.
1090 .IP
1091 The
1092 .BR KEYCTL_ASSUME_AUTHORITY
1093 mechanism allows a program such as
1094 .BR request\-key (8)
1095 to assume the necessary authority to instantiate a new uninstantiated key
1096 that was created as a consequence of a call to
1097 .BR request_key (2).
1098 For further information, see
1099 .BR request_key (2)
1100 and the kernel source file
1101 .IR Documentation/security/keys\-request\-key.txt .
1102 .IP
1103 The arguments
1104 .IR arg3 ,
1105 .IR arg4 ,
1106 and
1107 .IR arg5
1108 are ignored.
1109 .IP
1110 This operation is exposed by
1111 .I libkeyutils
1112 via the function
1113 .BR keyctl_assume_authority (3).
1114 .TP
1115 .BR KEYCTL_GET_SECURITY " (since Linux 2.6.26)"
1116 .\" commit 70a5bb72b55e82fbfbf1e22cae6975fac58a1e2d
1117 Get the LSM (Linux Security Module) security label of the specified key.
1118 .IP
1119 The ID of the key whose security label is to be fetched is specified in
1120 .I arg2
1121 (cast to
1122 .IR key_serial_t ).
1123 The security label (terminated by a null byte)
1124 will be placed in the buffer pointed to by
1125 .I arg3
1126 argument (cast to
1127 .IR "char\ *" );
1128 the size of the buffer must be provided in
1129 .I arg4
1130 (cast to
1131 .IR size_t ).
1132 .IP
1133 If
1134 .I arg3
1135 is specified as NULL or the buffer size specified in
1136 .IR arg4
1137 is too small, the full size of the security label string
1138 (including the terminating null byte)
1139 is returned as the function result,
1140 and nothing is copied to the buffer.
1141 .IP
1142 The caller must have
1143 .I view
1144 permission on the specified key.
1145 .IP
1146 The returned security label string will be rendered in a form appropriate
1147 to the LSM in force.
1148 For example, with SELinux, it may look like:
1149 .IP
1150     unconfined_u:unconfined_r:unconfined_t:s0-s0:c0.c1023
1151 .IP
1152 If no LSM is currently in force,
1153 then an empty string is placed in the buffer.
1154 .IP
1155 The
1156 .I arg5
1157 argument is ignored.
1158 .IP
1159 This operation is exposed by
1160 .I libkeyutils
1161 via the functions
1162 .BR keyctl_get_security (3)
1163 and
1164 .BR keyctl_get_security_alloc (3).
1165 .TP
1166 .BR KEYCTL_SESSION_TO_PARENT " (since Linux 2.6.32)"
1167 .\" commit ee18d64c1f632043a02e6f5ba5e045bb26a5465f
1168 Replace the session keyring to which the
1169 .I parent
1170 of the calling process
1171 subscribes with the session keyring of the calling process.
1172 .\" What is the use case for KEYCTL_SESSION_TO_PARENT?
1173 .\" David Howells: the Process Authentication Groups people requested this,
1174 .\" but then didn't use it; maybe there are no users.
1175 .IP
1176 The keyring will be replaced in the parent process at the point
1177 where the parent next transitions from kernel space to user space.
1178 .IP
1179 The keyring must exist and must grant the caller
1180 .I link
1181 permission.
1182 The parent process must be single-threaded and have
1183 the same effective ownership as this process
1184 and must not be set-user-ID or set-group-ID.
1185 The UID of the parent process's existing session keyring (f it has one),
1186 as well as the UID of the caller's session keyring
1187 much match the caller's effective UID.
1188 .IP
1189 The fact that it is the parent process that is affected by this operation
1190 allows a program such as the shell to start a child process that
1191 uses this operation to change the shell's session keyring.
1192 (This is what the
1193 .BR keyctl (1)
1194 .B new_session
1195 command does.)
1196 .IP
1197 The arguments
1198 .IR arg2 ,
1199 .IR arg3 ,
1200 .IR arg4 ,
1201 and
1202 .IR arg5
1203 are ignored.
1204 .IP
1205 This operation is exposed by
1206 .I libkeyutils
1207 via the function
1208 .BR keyctl_session_to_parent (3).
1209 .TP
1210 .BR KEYCTL_REJECT " (since Linux 2.6.39)"
1211 .\" commit fdd1b94581782a2ddf9124414e5b7a5f48ce2f9c
1212 Mark a key as negatively instantiated and set an expiration timer
1213 on the key.
1214 This operation provides a superset of the functionality of the earlier
1215 .BR KEYCTL_NEGATE
1216 operation.
1217 .IP
1218 The ID of the key that is to be negatively instantiated is specified in
1219 .I arg2
1220 (cast to
1221 .IR key_serial_t ).
1222 The
1223 .I arg3
1224 (cast to
1225 .IR "unsigned int" )
1226 argument specifies the lifetime of the key, in seconds.
1227 The
1228 .I arg4
1229 argument (cast to
1230 .IR "unsigned int" )
1231 specifies the error to be returned when a search hits this key;
1232 typically, this is one of
1233 .BR EKEYREJECTED ,
1234 .BR EKEYREVOKED ,
1235 or
1236 .BR EKEYEXPIRED .
1237 .IP
1238 If
1239 .I arg5
1240 (cast to
1241 .IR key_serial_t )
1242 is nonzero, then, subject to the same constraints and rules as
1243 .BR KEYCTL_LINK ,
1244 the negatively instantiated key is linked into the keyring
1245 whose ID is specified in
1246 .IR arg5 .
1247 .IP
1248 The caller must have the appropriate authorization key.
1249 In other words, this operation is available only from a
1250 .BR request\-key (8)-style
1251 program.
1252 See
1253 .BR request_key (2).
1254 .IP
1255 The caller must have the appropriate authorization key,
1256 and once the uninstantiated key has been instantiated,
1257 the authorization key is revoked.
1258 In other words, this operation is available only from a
1259 .BR request\-key (8)-style
1260 program.
1261 See
1262 .BR request_key (2)
1263 for an explanation of uninstantiated keys and key instantiation.
1264 .IP
1265 This operation is exposed by
1266 .I libkeyutils
1267 via the function
1268 .BR keyctl_reject (3).
1269 .TP
1270 .BR KEYCTL_INSTANTIATE_IOV " (since Linux 2.6.39)"
1271 .\" commit ee009e4a0d4555ed522a631bae9896399674f063
1272 Instantiate an uninstantiated key with a payload specified
1273 via a vector of buffers.
1274 .IP
1275 This operation is the same as
1276 .BR KEYCTL_INSTANTIATE ,
1277 but the payload data is specified as an array of
1278 .IR iovec
1279 structures:
1280 .IP
1281 .in +4n
1282 .EX
1283 struct iovec {
1284     void  *iov_base;    /* Starting address of buffer */
1285     size_t iov_len;     /* Size of buffer (in bytes) */
1286 };
1287 .EE
1288 .in
1289 .IP
1290 The pointer to the payload vector is specified in
1291 .IR arg3
1292 (cast as
1293 .IR "const struct iovec\ *" ).
1294 The number of items in the vector is specified in
1295 .IR arg4
1296 (cast as
1297 .IR "unsigned int" ).
1298 .IP
1299 The
1300 .I arg2
1301 (key ID)
1302 and
1303 .I arg5
1304 (keyring ID)
1305 are interpreted as for
1306 .BR KEYCTL_INSTANTIATE .
1307 .IP
1308 This operation is exposed by
1309 .I libkeyutils
1310 via the function
1311 .BR keyctl_instantiate_iov (3).
1312 .TP
1313 .BR KEYCTL_INVALIDATE " (since Linux 3.5)"
1314 .\" commit fd75815f727f157a05f4c96b5294a4617c0557da
1315 Mark a key as invalid.
1316 .IP
1317 The ID of the key to be invalidated is specified in
1318 .I arg2
1319 (cast to
1320 .IR key_serial_t ).
1321 .IP
1322 To invalidate a key,
1323 the caller must have
1324 .I search
1325 permission on the key.
1326 .\" CAP_SYS_ADMIN is permitted to invalidate certain special keys
1327 .IP
1328 This operation marks the key as invalid
1329 and schedules immediate garbage collection.
1330 The garbage collector removes the invalidated key from all keyrings and
1331 deletes the key when its reference count reaches zero.
1332 After this operation,
1333 the key will be ignored by all searches,
1334 even if it is not yet deleted.
1335 .IP
1336 Keys that are marked invalid become invisible to normal key operations
1337 immediately, though they are still visible in
1338 .I /proc/keys
1339 (marked with an 'i' flag)
1340 until they are actually removed.
1341 .IP
1342 The arguments
1343 .IR arg3 ,
1344 .IR arg4 ,
1345 and
1346 .IR arg5
1347 are ignored.
1348 .IP
1349 This operation is exposed by
1350 .I libkeyutils
1351 via the function
1352 .BR keyctl_invalidate (3).
1353 .TP
1354 .BR KEYCTL_GET_PERSISTENT " (since Linux 3.13)"
1355 .\" commit f36f8c75ae2e7d4da34f4c908cebdb4aa42c977e
1356 Get the persistent keyring
1357 .RB ( persistent\-keyring (7))
1358 for a specified user and link it to a specified keyring.
1359 .IP
1360 The user ID is specified in
1361 .I arg2
1362 (cast to
1363 .IR uid_t ).
1364 If the value \-1 is specified, the caller's real user ID is used.
1365 The ID of the destination keyring is specified in
1366 .I arg3
1367 (cast to
1368 .IR key_serial_t ).
1369 .IP
1370 The caller must have the
1371 .BR CAP_SETUID
1372 capability in its user namespace in order to fetch the persistent keyring
1373 for a user ID that does not match either the real or effective user ID
1374 of the caller.
1375 .IP
1376 If the call is successful,
1377 a link to the persistent keyring is added to the keyring
1378 whose ID was specified in
1379 .IR arg3 .
1380 .IP
1381 The caller must have
1382 .I write
1383 permission on the keyring.
1384 .IP
1385 The persistent keyring will be created by the kernel
1386 if it does not yet exist.
1387 .IP
1388 Each time the
1389 .B KEYCTL_GET_PERSISTENT
1390 operation is performed, the persistent keyring will
1391 have its expiration timeout reset to the value in:
1392 .IP
1393 .in +4n
1394 .EX
1395 /proc/sys/kernel/keys/persistent_keyring_expiry
1396 .EE
1397 .in
1398 .IP
1399 Should the timeout be reached,
1400 the persistent keyring will be removed and
1401 everything it pins can then be garbage collected.
1402 .IP
1403 Persistent keyrings were added to Linux in kernel version 3.13.
1404 .IP
1405 The arguments
1406 .IR arg4
1407 and
1408 .IR arg5
1409 are ignored.
1410 .IP
1411 This operation is exposed by
1412 .I libkeyutils
1413 via the function
1414 .BR keyctl_get_persistent (3).
1415 .TP
1416 .BR KEYCTL_DH_COMPUTE " (since Linux 4.7)"
1417 .\" commit ddbb41148724367394d0880c516bfaeed127b52e
1418 Compute a Diffie-Hellman shared secret or public key,
1419 optionally applying key derivation function (KDF) to the result.
1420 .IP
1421 The
1422 .I arg2
1423 argument is a pointer to a set of parameters containing
1424 serial numbers for three
1425 .IR """user"""
1426 keys used in the Diffie-Hellman calculation,
1427 packaged in a structure of the following form:
1428 .IP
1429 .in +4n
1430 .EX
1431 struct keyctl_dh_params {
1432     int32_t private; /* The local private key */
1433     int32_t prime; /* The prime, known to both parties */
1434     int32_t base;  /* The base integer: either a shared
1435                       generator or the remote public key */
1436 };
1437 .EE
1438 .in
1439 .IP
1440 Each of the three keys specified in this structure must grant the caller
1441 .I read
1442 permission.
1443 The payloads of these keys are used to calculate the Diffie-Hellman
1444 result as:
1445 .IP
1446     base \(ha private mod prime
1447 .IP
1448 If the base is the shared generator, the result is the local public key.
1449 If the base is the remote public key, the result is the shared secret.
1450 .IP
1451 The
1452 .I arg3
1453 argument (cast to
1454 .IR "char\ *" )
1455 points to a buffer where the result of the calculation is placed.
1456 The size of that buffer is specified in
1457 .I arg4
1458 (cast to
1459 .IR size_t ).
1460 .IP
1461 The buffer must be large enough to accommodate the output data,
1462 otherwise an error is returned.
1463 If
1464 .I arg4
1465 is specified zero,
1466 in which case the buffer is not used and
1467 the operation returns the minimum required buffer size
1468 (i.e., the length of the prime).
1469 .IP
1470 Diffie-Hellman computations can be performed in user space,
1471 but require a multiple-precision integer (MPI) library.
1472 Moving the implementation into the kernel gives access to
1473 the kernel MPI implementation,
1474 and allows access to secure or acceleration hardware.
1475 .IP
1476 Adding support for DH computation to the
1477 .BR keyctl ()
1478 system call was considered a good fit due to the DH algorithm's use
1479 for deriving shared keys;
1480 it also allows the type of the key to determine
1481 which DH implementation (software or hardware) is appropriate.
1482 .\" commit f1c316a3ab9d24df6022682422fe897492f2c0c8
1483 .IP
1484 If the
1485 .I arg5
1486 argument is
1487 .BR NULL ,
1488 then the DH result itself is returned.
1489 Otherwise (since Linux 4.12), it is a pointer to a structure which specifies
1490 parameters of the KDF operation to be applied:
1491 .IP
1492 .in +4n
1493 .EX
1494 struct keyctl_kdf_params {
1495     char *hashname;     /* Hash algorithm name */
1496     char *otherinfo;    /* SP800\-56A OtherInfo */
1497     __u32 otherinfolen; /* Length of otherinfo data */
1498     __u32 __spare[8];   /* Reserved */
1499 };
1500 .EE
1501 .in
1502 .IP
1503 The
1504 .I hashname
1505 field is a null-terminated string which specifies a hash name
1506 (available in the kernel's crypto API; the list of the hashes available
1507 is rather tricky to observe; please refer to the
1508 .UR https://www.kernel.org\:/doc\:/html\:/latest\:/crypto\:/architecture.html
1509 "Kernel Crypto API Architecture"
1510 .UE
1511 documentation for the information regarding how hash names are constructed and
1512 your kernel's source and configuration regarding what ciphers
1513 and templates with type
1514 .B CRYPTO_ALG_TYPE_SHASH
1515 are available)
1516 to be applied to DH result in KDF operation.
1517 .IP
1518 The
1519 .I otherinfo
1520 field is an
1521 .I OtherInfo
1522 data as described in SP800-56A section 5.8.1.2 and is algorithm-specific.
1523 This data is concatenated with the result of DH operation and is provided as
1524 an input to the KDF operation.
1525 Its size is provided in the
1526 .I otherinfolen
1527 field and is limited by
1528 .B KEYCTL_KDF_MAX_OI_LEN
1529 constant that defined in
1530 .I security/keys/internal.h
1531 to a value of 64.
1532 .IP
1533 The
1534 .B __spare
1535 field is currently unused.
1536 .\" commit 4f9dabfaf8df971f8a3b6aa324f8f817be38d538
1537 It was ignored until Linux 4.13 (but still should be
1538 user-addressable since it is copied to the kernel),
1539 and should contain zeros since Linux 4.13.
1540 .IP
1541 The KDF implementation complies with SP800-56A as well
1542 as with SP800-108 (the counter KDF).
1543 .IP
1544 .\" keyutils commit 742c9d7b94051d3b21f9f61a73ed6b5f3544cb82
1545 .\" keyutils commit d68a981e5db41d059ac782071c35d1e8f3aaf61c
1546 This operation is exposed by
1547 .I libkeyutils
1548 (from version 1.5.10 onwards) via the functions
1549 .BR keyctl_dh_compute (3)
1550 and
1551 .BR keyctl_dh_compute_alloc (3).
1552 .TP
1553 .BR KEYCTL_RESTRICT_KEYRING " (since Linux 4.12)"
1554 .\" commit 6563c91fd645556c7801748f15bc727c77fcd311
1555 .\" commit 7228b66aaf723a623e578aa4db7d083bb39546c9
1556 Apply a key-linking restriction to the keyring with the ID provided in
1557 .IR arg2
1558 (cast to
1559 .IR key_serial_t ).
1560 The caller must have
1561 .IR setattr
1562 permission on the key.
1563 If
1564 .I arg3
1565 is NULL, any attempt to add a key to the keyring is blocked;
1566 otherwise it contains a pointer to a string with a key type name and
1567 .I arg4
1568 contains a pointer to string that describes the type-specific restriction.
1569 As of Linux 4.12, only the type "asymmetric" has restrictions defined:
1570 .RS
1571 .TP
1572 .B builtin_trusted
1573 Allows only keys that are signed by a key linked to the built-in keyring
1574 (".builtin_trusted_keys").
1575 .TP
1576 .B builtin_and_secondary_trusted
1577 Allows only keys that are signed by a key linked to the secondary keyring
1578 (".secondary_trusted_keys") or, by extension, a key in a built-in keyring,
1579 as the latter is linked to the former.
1580 .TP
1581 .BI key_or_keyring: key
1582 .TQ
1583 .BI key_or_keyring: key :chain
1584 If
1585 .I key
1586 specifies the ID of a key of type "asymmetric",
1587 then only keys that are signed by this key are allowed.
1588 .IP
1589 If
1590 .I key
1591 specifies the ID of a keyring,
1592 then only keys that are signed by a key linked
1593 to this keyring are allowed.
1594 .IP
1595 If ":chain" is specified, keys that are signed by a keys linked to the
1596 destination keyring (that is, the keyring with the ID specified in the
1597 .I arg2
1598 argument) are also allowed.
1599 .RE
1600 .IP
1601 Note that a restriction can be configured only once for the specified keyring;
1602 once a restriction is set, it can't be overridden.
1603 .IP
1604 The argument
1605 .I arg5
1606 is ignored.
1607 .\" FIXME Document KEYCTL_RESTRICT_KEYRING, added in Linux 4.12
1608 .\"     commit 6563c91fd645556c7801748f15bc727c77fcd311
1609 .\"     Author: Mat Martineau <mathew.j.martineau@linux.intel.com>
1610 .\" See Documentation/security/keys.txt
1611 .SH RETURN VALUE
1612 For a successful call, the return value depends on the operation:
1613 .TP
1614 .B KEYCTL_GET_KEYRING_ID
1615 The ID of the requested keyring.
1616 .TP
1617 .B KEYCTL_JOIN_SESSION_KEYRING
1618 The ID of the joined session keyring.
1619 .TP
1620 .B KEYCTL_DESCRIBE
1621 The size of the description (including the terminating null byte),
1622 irrespective of the provided buffer size.
1623 .TP
1624 .B KEYCTL_SEARCH
1625 The ID of the key that was found.
1626 .TP
1627 .B KEYCTL_READ
1628 The amount of data that is available in the key,
1629 irrespective of the provided buffer size.
1630 .TP
1631 .B KEYCTL_SET_REQKEY_KEYRING
1632 The ID of the previous default keyring
1633 to which implicitly requested keys were linked
1634 (one of
1635 .BR KEY_REQKEY_DEFL_USER_* ).
1636 .TP
1637 .B KEYCTL_ASSUME_AUTHORITY
1638 Either 0, if the ID given was 0,
1639 or the ID of the authorization key matching the specified key,
1640 if a nonzero key ID was provided.
1641 .TP
1642 .B KEYCTL_GET_SECURITY
1643 The size of the LSM security label string
1644 (including the terminating null byte),
1645 irrespective of the provided buffer size.
1646 .TP
1647 .B KEYCTL_GET_PERSISTENT
1648 The ID of the persistent keyring.
1649 .TP
1650 .B KEYCTL_DH_COMPUTE
1651 The number of bytes copied to the buffer, or, if
1652 .I arg4
1653 is 0, the required buffer size.
1654 .TP
1655 All other operations
1656 Zero.
1657 .PP
1658 On error, \-1 is returned, and
1659 .I errno
1660 is set to indicate the error.
1661 .SH ERRORS
1662 .TP
1663 .B EACCES
1664 The requested operation wasn't permitted.
1665 .TP
1666 .B EAGAIN
1667 .I operation
1668 was
1669 .B KEYCTL_DH_COMPUTE
1670 and there was an error during crypto module initialization.
1671 .TP
1672 .B EDEADLK
1673 .I operation
1674 was
1675 .BR KEYCTL_LINK
1676 and the requested link would result in a cycle.
1677 .TP
1678 .B EDEADLK
1679 .I operation
1680 was
1681 .BR KEYCTL_RESTRICT_KEYRING
1682 and the requested keyring restriction would result in a cycle.
1683 .TP
1684 .B EDQUOT
1685 The key quota for the caller's user would be exceeded by creating a key or
1686 linking it to the keyring.
1687 .TP
1688 .B EEXIST
1689 .I operation
1690 was
1691 .BR KEYCTL_RESTRICT_KEYRING
1692 and keyring provided in
1693 .I arg2
1694 argument already has a restriction set.
1695 .TP
1696 .B EFAULT
1697 .I operation
1698 was
1699 .B KEYCTL_DH_COMPUTE
1700 and one of the following has failed:
1701 .RS
1702 .IP \(bu 3
1703 copying of the
1704 .IR "struct keyctl_dh_params" ,
1705 provided in the
1706 .I arg2
1707 argument, from user space;
1708 .IP \(bu
1709 copying of the
1710 .IR "struct keyctl_kdf_params" ,
1711 provided in the non-NULL
1712 .I arg5
1713 argument, from user space
1714 (in case kernel supports performing KDF operation on DH operation result);
1715 .IP \(bu
1716 copying of data pointed by the
1717 .I hashname
1718 field of the
1719 .I "struct keyctl_kdf_params"
1720 from user space;
1721 .IP \(bu
1722 copying of data pointed by the
1723 .I otherinfo
1724 field of the
1725 .I struct keyctl_kdf_params
1726 from user space if the
1727 .I otherinfolen
1728 field was nonzero;
1729 .IP \(bu
1730 copying of the result to user space.
1731 .RE
1732 .TP
1733 .B EINVAL
1734 .I operation
1735 was
1736 .B KEYCTL_SETPERM
1737 and an invalid permission bit was specified in
1738 .IR arg3 .
1739 .TP
1740 .B EINVAL
1741 .I operation
1742 was
1743 .BR KEYCTL_SEARCH
1744 and the size of the description in
1745 .IR arg4
1746 (including the terminating null byte) exceeded 4096 bytes.
1747 .TP
1748 .B EINVAL
1749 size of the string (including the terminating null byte) specified in
1750 .I arg3
1751 (the key type)
1752 or
1753 .I arg4
1754 (the key description)
1755 exceeded the limit (32 bytes and 4096 bytes respectively).
1756 .TP
1757 .BR EINVAL " (Linux kernels before 4.12)"
1758 .I operation
1759 was
1760 .BR KEYCTL_DH_COMPUTE ,
1761 argument
1762 .I arg5
1763 was non-NULL.
1764 .TP
1765 .B EINVAL
1766 .I operation
1767 was
1768 .B KEYCTL_DH_COMPUTE
1769 And the digest size of the hashing algorithm supplied is zero.
1770 .TP
1771 .B EINVAL
1772 .I operation
1773 was
1774 .B KEYCTL_DH_COMPUTE
1775 and the buffer size provided is not enough to hold the result.
1776 Provide 0 as a buffer size in order to obtain the minimum buffer size.
1777 .TP
1778 .B EINVAL
1779 .I operation
1780 was
1781 .B KEYCTL_DH_COMPUTE
1782 and the hash name provided in the
1783 .I hashname
1784 field of the
1785 .I struct keyctl_kdf_params
1786 pointed by
1787 .I arg5
1788 argument is too big (the limit is implementation-specific and varies between
1789 kernel versions, but it is deemed big enough for all valid algorithm names).
1790 .TP
1791 .B EINVAL
1792 .\" commit 4f9dabfaf8df971f8a3b6aa324f8f817be38d538
1793 .I operation
1794 was
1795 .B KEYCTL_DH_COMPUTE
1796 and the
1797 .I __spare
1798 field of the
1799 .I struct keyctl_kdf_params
1800 provided in the
1801 .I arg5
1802 argument contains nonzero values.
1803 .TP
1804 .B EKEYEXPIRED
1805 An expired key was found or specified.
1806 .TP
1807 .B EKEYREJECTED
1808 A rejected key was found or specified.
1809 .TP
1810 .B EKEYREVOKED
1811 A revoked key was found or specified.
1812 .TP
1813 .B ELOOP
1814 .I operation
1815 was
1816 .BR KEYCTL_LINK
1817 and the requested link would cause the maximum nesting depth
1818 for keyrings to be exceeded.
1819 .TP
1820 .B EMSGSIZE
1821 .I operation
1822 was
1823 .B KEYCTL_DH_COMPUTE
1824 and the buffer length exceeds
1825 .B KEYCTL_KDF_MAX_OUTPUT_LEN
1826 (which is 1024 currently)
1827 or the
1828 .I otherinfolen
1829 field of the
1830 .I struct keyctl_kdf_parms
1831 passed in
1832 .I arg5
1833 exceeds
1834 .B KEYCTL_KDF_MAX_OI_LEN
1835 (which is 64 currently).
1836 .TP
1837 .BR ENFILE " (Linux kernels before 3.13)"
1838 .IR operation
1839 was
1840 .BR KEYCTL_LINK
1841 and the keyring is full.
1842 (Before Linux 3.13,
1843 .\" commit b2a4df200d570b2c33a57e1ebfa5896e4bc81b69
1844 the available space for storing keyring links was limited to
1845 a single page of memory; since Linux 3.13, there is no fixed limit.)
1846 .TP
1847 .B ENOENT
1848 .I operation
1849 was
1850 .B KEYCTL_UNLINK
1851 and the key to be unlinked isn't linked to the keyring.
1852 .TP
1853 .B ENOENT
1854 .I operation
1855 was
1856 .B KEYCTL_DH_COMPUTE
1857 and the hashing algorithm specified in the
1858 .I hashname
1859 field of the
1860 .I struct keyctl_kdf_params
1861 pointed by
1862 .I arg5
1863 argument hasn't been found.
1864 .TP
1865 .B ENOENT
1866 .I operation
1867 was
1868 .B KEYCTL_RESTRICT_KEYRING
1869 and the type provided in
1870 .I arg3
1871 argument doesn't support setting key linking restrictions.
1872 .TP
1873 .B ENOKEY
1874 No matching key was found or an invalid key was specified.
1875 .TP
1876 .B ENOKEY
1877 The value
1878 .B KEYCTL_GET_KEYRING_ID
1879 was specified in
1880 .IR operation ,
1881 the key specified in
1882 .I arg2
1883 did not exist, and
1884 .I arg3
1885 was zero (meaning don't create the key if it didn't exist).
1886 .TP
1887 .B ENOMEM
1888 One of kernel memory allocation routines failed during the execution of the
1889 syscall.
1890 .TP
1891 .B ENOTDIR
1892 A key of keyring type was expected but the ID of a key with
1893 a different type was provided.
1894 .TP
1895 .B EOPNOTSUPP
1896 .I operation
1897 was
1898 .B KEYCTL_READ
1899 and the key type does not support reading
1900 (e.g., the type is
1901 .IR """login""" ).
1902 .TP
1903 .B EOPNOTSUPP
1904 .I operation
1905 was
1906 .B KEYCTL_UPDATE
1907 and the key type does not support updating.
1908 .TP
1909 .B EOPNOTSUPP
1910 .I operation
1911 was
1912 .BR KEYCTL_RESTRICT_KEYRING ,
1913 the type provided in
1914 .I arg3
1915 argument was "asymmetric", and the key specified in the restriction specification
1916 provided in
1917 .I arg4
1918 has type other than "asymmetric" or "keyring".
1919 .TP
1920 .B EPERM
1921 .I operation
1922 was
1923 .BR KEYCTL_GET_PERSISTENT ,
1924 .I arg2
1925 specified a UID other than the calling thread's real or effective UID,
1926 and the caller did not have the
1927 .B CAP_SETUID
1928 capability.
1929 .TP
1930 .B EPERM
1931 .I operation
1932 was
1933 .BR KEYCTL_SESSION_TO_PARENT
1934 and either:
1935 all of the UIDs (GIDs) of the parent process do not match
1936 the effective UID (GID) of the calling process;
1937 the UID of the parent's existing session keyring or
1938 the UID of the caller's session keyring did not match
1939 the effective UID of the caller;
1940 the parent process is not single-thread;
1941 or the parent process is
1942 .BR init (1)
1943 or a kernel thread.
1944 .TP
1945 .B ETIMEDOUT
1946 .I operation
1947 was
1948 .B KEYCTL_DH_COMPUTE
1949 and the initialization of crypto modules has timed out.
1950 .SH VERSIONS
1951 This system call first appeared in Linux 2.6.10.
1952 .SH CONFORMING TO
1953 This system call is a nonstandard Linux extension.
1954 .SH NOTES
1955 A wrapper is provided in the
1956 .IR libkeyutils
1957 library.
1958 When employing the wrapper in that library, link with
1959 .IR \-lkeyutils .
1960 However, rather than using this system call directly,
1961 you probably want to use the various library functions
1962 mentioned in the descriptions of individual operations above.
1963 .SH EXAMPLES
1964 The program below provide subset of the functionality of the
1965 .BR request\-key (8)
1966 program provided by the
1967 .I keyutils
1968 package.
1969 For informational purposes,
1970 the program records various information in a log file.
1971 .PP
1972 As described in
1973 .BR request_key (2),
1974 the
1975 .BR request\-key (8)
1976 program is invoked with command-line arguments that
1977 describe a key that is to be instantiated.
1978 The example program fetches and logs these arguments.
1979 The program assumes authority to instantiate the requested key,
1980 and then instantiates that key.
1981 .PP
1982 The following shell session demonstrates the use of this program.
1983 In the session,
1984 we compile the program and then use it to temporarily replace the standard
1985 .BR request\-key (8)
1986 program.
1987 (Note that temporarily disabling the standard
1988 .BR request\-key (8)
1989 program may not be safe on some systems.)
1990 While our example program is installed,
1991 we use the example program shown in
1992 .BR request_key (2)
1993 to request a key.
1994 .PP
1995 .in +4n
1996 .EX
1997 $ \fBcc \-o key_instantiate key_instantiate.c \-lkeyutils\fP
1998 $ \fBsudo mv /sbin/request\-key /sbin/request\-key.backup\fP
1999 $ \fBsudo cp key_instantiate /sbin/request\-key\fP
2000 $ \fB./t_request_key user mykey somepayloaddata\fP
2001 Key ID is 20d035bf
2002 $ \fBsudo mv /sbin/request\-key.backup /sbin/request\-key\fP
2003 .EE
2004 .in
2005 .PP
2006 Looking at the log file created by this program,
2007 we can see the command-line arguments supplied to our example program:
2008 .PP
2009 .in +4n
2010 .EX
2011 $ \fBcat /tmp/key_instantiate.log\fP
2012 Time: Mon Nov  7 13:06:47 2016
2013
2014 Command line arguments:
2015   argv[0]:            /sbin/request\-key
2016   operation:          create
2017   key_to_instantiate: 20d035bf
2018   UID:                1000
2019   GID:                1000
2020   thread_keyring:     0
2021   process_keyring:    0
2022   session_keyring:    256e6a6
2023
2024 Key description:      user;1000;1000;3f010000;mykey
2025 Auth key payload:     somepayloaddata
2026 Destination keyring:  256e6a6
2027 Auth key description: .request_key_auth;1000;1000;0b010000;20d035bf
2028 .EE
2029 .in
2030 .PP
2031 The last few lines of the above output show that the example program
2032 was able to fetch:
2033 .IP * 3
2034 the description of the key to be instantiated,
2035 which included the name of the key
2036 .RI ( mykey );
2037 .IP *
2038 the payload of the authorization key, which consisted of the data
2039 .RI ( somepayloaddata )
2040 passed to
2041 .BR request_key (2);
2042 .IP *
2043 the destination keyring that was specified in the call to
2044 .BR request_key (2);
2045 and
2046 .IP *
2047 the description of the authorization key,
2048 where we can see that the name of the authorization key matches
2049 the ID of the key that is to be instantiated
2050 .RI ( 20d035bf ).
2051 .PP
2052 The example program in
2053 .BR request_key (2)
2054 specified the destination keyring as
2055 .BR KEY_SPEC_SESSION_KEYRING .
2056 By examining the contents of
2057 .IR /proc/keys ,
2058 we can see that this was translated to the ID of the destination keyring
2059 .RI ( 0256e6a6 )
2060 shown in the log output above;
2061 we can also see the newly created key with the name
2062 .IR mykey
2063 and ID
2064 .IR 20d035bf .
2065 .PP
2066 .in +4n
2067 .EX
2068 $ \fBcat /proc/keys | egrep \(aqmykey|256e6a6\(aq\fP
2069 0256e6a6 I\-\-Q\-\-\-  194 perm 3f030000  1000  1000 keyring  _ses: 3
2070 20d035bf I\-\-Q\-\-\-    1 perm 3f010000  1000  1000 user     mykey: 16
2071 .EE
2072 .in
2073 .SS Program source
2074 \&
2075 .EX
2076 /* key_instantiate.c */
2077
2078 #include <sys/types.h>
2079 #include <keyutils.h>
2080 #include <time.h>
2081 #include <fcntl.h>
2082 #include <stdint.h>
2083 #include <stdio.h>
2084 #include <stdlib.h>
2085 #include <unistd.h>
2086 #include <string.h>
2087 #include <errno.h>
2088
2089 #ifndef KEY_SPEC_REQUESTOR_KEYRING
2090 #define KEY_SPEC_REQUESTOR_KEYRING      \-8
2091 #endif
2092
2093 int
2094 main(int argc, char *argv[])
2095 {
2096     FILE *fp;
2097     time_t t;
2098     char *operation;
2099     key_serial_t key_to_instantiate, dest_keyring;
2100     key_serial_t thread_keyring, process_keyring, session_keyring;
2101     uid_t uid;
2102     gid_t gid;
2103     char dbuf[256];
2104     char auth_key_payload[256];
2105     int akp_size;       /* Size of auth_key_payload */
2106     int auth_key;
2107
2108     fp = fopen("/tmp/key_instantiate.log", "w");
2109     if (fp == NULL)
2110         exit(EXIT_FAILURE);
2111
2112     setbuf(fp, NULL);
2113
2114     t = time(NULL);
2115     fprintf(fp, "Time: %s\en", ctime(&t));
2116
2117     /*
2118      * The kernel passes a fixed set of arguments to the program
2119      * that it execs; fetch them.
2120      */
2121     operation = argv[1];
2122     key_to_instantiate = atoi(argv[2]);
2123     uid = atoi(argv[3]);
2124     gid = atoi(argv[4]);
2125     thread_keyring = atoi(argv[5]);
2126     process_keyring = atoi(argv[6]);
2127     session_keyring = atoi(argv[7]);
2128
2129     fprintf(fp, "Command line arguments:\en");
2130     fprintf(fp, "  argv[0]:            %s\en", argv[0]);
2131     fprintf(fp, "  operation:          %s\en", operation);
2132     fprintf(fp, "  key_to_instantiate: %jx\en",
2133             (uintmax_t) key_to_instantiate);
2134     fprintf(fp, "  UID:                %jd\en", (intmax_t) uid);
2135     fprintf(fp, "  GID:                %jd\en", (intmax_t) gid);
2136     fprintf(fp, "  thread_keyring:     %jx\en",
2137             (uintmax_t) thread_keyring);
2138     fprintf(fp, "  process_keyring:    %jx\en",
2139             (uintmax_t) process_keyring);
2140     fprintf(fp, "  session_keyring:    %jx\en",
2141             (uintmax_t) session_keyring);
2142     fprintf(fp, "\en");
2143
2144     /*
2145      * Assume the authority to instantiate the key named in argv[2].
2146      */
2147     if (keyctl(KEYCTL_ASSUME_AUTHORITY, key_to_instantiate) == \-1) {
2148         fprintf(fp, "KEYCTL_ASSUME_AUTHORITY failed: %s\en",
2149                 strerror(errno));
2150         exit(EXIT_FAILURE);
2151     }
2152
2153     /*
2154      * Fetch the description of the key that is to be instantiated.
2155      */
2156     if (keyctl(KEYCTL_DESCRIBE, key_to_instantiate,
2157                 dbuf, sizeof(dbuf)) == \-1) {
2158         fprintf(fp, "KEYCTL_DESCRIBE failed: %s\en", strerror(errno));
2159         exit(EXIT_FAILURE);
2160     }
2161
2162     fprintf(fp, "Key description:      %s\en", dbuf);
2163
2164     /*
2165      * Fetch the payload of the authorization key, which is
2166      * actually the callout data given to request_key().
2167      */
2168     akp_size = keyctl(KEYCTL_READ, KEY_SPEC_REQKEY_AUTH_KEY,
2169                       auth_key_payload, sizeof(auth_key_payload));
2170     if (akp_size == \-1) {
2171         fprintf(fp, "KEYCTL_READ failed: %s\en", strerror(errno));
2172         exit(EXIT_FAILURE);
2173     }
2174
2175     auth_key_payload[akp_size] = \(aq\e0\(aq;
2176     fprintf(fp, "Auth key payload:     %s\en", auth_key_payload);
2177
2178     /*
2179      * For interest, get the ID of the authorization key and
2180      * display it.
2181      */
2182     auth_key = keyctl(KEYCTL_GET_KEYRING_ID,
2183             KEY_SPEC_REQKEY_AUTH_KEY);
2184     if (auth_key == \-1) {
2185         fprintf(fp, "KEYCTL_GET_KEYRING_ID failed: %s\en",
2186                 strerror(errno));
2187         exit(EXIT_FAILURE);
2188     }
2189
2190     fprintf(fp, "Auth key ID:          %jx\en", (uintmax_t) auth_key);
2191
2192     /*
2193      * Fetch key ID for the request_key(2) destination keyring.
2194      */
2195     dest_keyring = keyctl(KEYCTL_GET_KEYRING_ID,
2196                           KEY_SPEC_REQUESTOR_KEYRING);
2197     if (dest_keyring == \-1) {
2198         fprintf(fp, "KEYCTL_GET_KEYRING_ID failed: %s\en",
2199                 strerror(errno));
2200         exit(EXIT_FAILURE);
2201     }
2202
2203     fprintf(fp, "Destination keyring:  %jx\en", (uintmax_t) dest_keyring);
2204
2205     /*
2206      * Fetch the description of the authorization key. This
2207      * allows us to see the key type, UID, GID, permissions,
2208      * and description (name) of the key. Among other things,
2209      * we will see that the name of the key is a hexadecimal
2210      * string representing the ID of the key to be instantiated.
2211      */
2212     if (keyctl(KEYCTL_DESCRIBE, KEY_SPEC_REQKEY_AUTH_KEY,
2213                 dbuf, sizeof(dbuf)) == \-1) {
2214         fprintf(fp, "KEYCTL_DESCRIBE failed: %s\en", strerror(errno));
2215         exit(EXIT_FAILURE);
2216     }
2217
2218     fprintf(fp, "Auth key description: %s\en", dbuf);
2219
2220     /*
2221      * Instantiate the key using the callout data that was supplied
2222      * in the payload of the authorization key.
2223      */
2224     if (keyctl(KEYCTL_INSTANTIATE, key_to_instantiate,
2225                auth_key_payload, akp_size + 1, dest_keyring) == \-1) {
2226         fprintf(fp, "KEYCTL_INSTANTIATE failed: %s\en",
2227                 strerror(errno));
2228         exit(EXIT_FAILURE);
2229     }
2230
2231     exit(EXIT_SUCCESS);
2232 }
2233 .EE
2234 .SH SEE ALSO
2235 .ad l
2236 .nh
2237 .BR keyctl (1),
2238 .BR add_key (2),
2239 .BR request_key (2),
2240 .\"     .BR find_key_by_type_and_name (3)
2241 .\"     There is a man page, but this function seems not to exist
2242 .BR keyctl (3),
2243 .BR keyctl_assume_authority (3),
2244 .BR keyctl_chown (3),
2245 .BR keyctl_clear (3),
2246 .BR keyctl_describe (3),
2247 .BR keyctl_describe_alloc (3),
2248 .BR keyctl_dh_compute (3),
2249 .BR keyctl_dh_compute_alloc (3),
2250 .BR keyctl_get_keyring_ID (3),
2251 .BR keyctl_get_persistent (3),
2252 .BR keyctl_get_security (3),
2253 .BR keyctl_get_security_alloc (3),
2254 .BR keyctl_instantiate (3),
2255 .BR keyctl_instantiate_iov (3),
2256 .BR keyctl_invalidate (3),
2257 .BR keyctl_join_session_keyring (3),
2258 .BR keyctl_link (3),
2259 .BR keyctl_negate (3),
2260 .BR keyctl_read (3),
2261 .BR keyctl_read_alloc (3),
2262 .BR keyctl_reject (3),
2263 .BR keyctl_revoke (3),
2264 .BR keyctl_search (3),
2265 .BR keyctl_session_to_parent (3),
2266 .BR keyctl_set_reqkey_keyring (3),
2267 .BR keyctl_set_timeout (3),
2268 .BR keyctl_setperm (3),
2269 .BR keyctl_unlink (3),
2270 .BR keyctl_update (3),
2271 .BR recursive_key_scan (3),
2272 .BR recursive_session_key_scan (3),
2273 .BR capabilities (7),
2274 .BR credentials (7),
2275 .BR keyrings (7),
2276 .BR keyutils (7),
2277 .BR persistent\-keyring (7),
2278 .BR process\-keyring (7),
2279 .BR session\-keyring (7),
2280 .BR thread\-keyring (7),
2281 .BR user\-keyring (7),
2282 .BR user_namespaces (7),
2283 .BR user\-session\-keyring (7),
2284 .BR request\-key (8)
2285 .PP
2286 The kernel source files under
2287 .IR Documentation/security/keys/
2288 (or, before Linux 4.13, in the file
2289 .IR Documentation/security/keys.txt ).