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