Movatterモバイル変換

request_key(2) — Linux manual page

NAME \|LIBRARY \|SYNOPSIS \|DESCRIPTION \|RETURN VALUE \|ERRORS \|STANDARDS \|HISTORY \|EXAMPLES \|SEE ALSO \|COLOPHON

request_key(2)             System Calls Manualrequest_key(2)

NAME top

       request_key - request a key from the kernel's key management       facility

LIBRARY top

       Linux Key Management Utilities (libkeyutils,-lkeyutils)

SYNOPSIS top

#include <keyutils.h>key_serial_t request_key(const char *type, const char *description,const char *_Nullablecallout_info,key_serial_tdest_keyring);

DESCRIPTION top

request_key() attempts to find a key of the giventype with a       description (name) that matches the specifieddescription.  If       such a key could not be found, then the key is optionally created.       If the key is found or created,request_key() attaches it to the       keyring whose ID is specified indest_keyring and returns the       key's serial number.request_key() first recursively searches for a matching key in all       of the keyrings attached to the calling process.  The keyrings are       searched in the order: thread-specific keyring, process-specific       keyring, and then session keyring.       Ifrequest_key() is called from a program invoked byrequest_key()       on behalf of some other process to generate a key, then the       keyrings of that other process will be searched next, using that       other process's user ID, group ID, supplementary group IDs, and       security context to determine access.       The search of the keyring tree is breadth-first: the keys in each       keyring searched are checked for a match before any child keyrings       are recursed into.  Only keys for which the caller hassearch       permission be found, and only keyrings for which the caller hassearch permission may be searched.       If the key is not found andcallout is NULL, then the call fails       with the errorENOKEY.       If the key is not found andcallout is not NULL, then the kernel       attempts to invoke a user-space program to instantiate the key.       The details are given below.       Thedest_keyring serial number may be that of a valid keyring for       which the caller haswrite permission, or it may be one of the       following special keyring IDs:KEY_SPEC_THREAD_KEYRING              This specifies the caller's thread-specific keyring (seethread-keyring(7)).KEY_SPEC_PROCESS_KEYRING              This specifies the caller's process-specific keyring (seeprocess-keyring(7)).KEY_SPEC_SESSION_KEYRING              This specifies the caller's session-specific keyring (seesession-keyring(7)).KEY_SPEC_USER_KEYRING              This specifies the caller's UID-specific keyring (seeuser-keyring(7)).KEY_SPEC_USER_SESSION_KEYRING              This specifies the caller's UID-session keyring (seeuser-session-keyring(7)).       When thedest_keyring is specified as 0 and no key construction       has been performed, then no additional linking is done.       Otherwise, ifdest_keyring is 0 and a new key is constructed, the       new key will be linked to the "default" keyring.  More precisely,       when the kernel tries to determine to which keyring the newly       constructed key should be linked, it tries the following keyrings,       beginning with the keyring set via thekeyctl(2)KEYCTL_SET_REQKEY_KEYRINGoperation and continuing in the order       shown below until it finds the first keyring that exists:       •  The requestor keyring (KEY_REQKEY_DEFL_REQUESTOR_KEYRING, since          Linux 2.6.29).       •  The thread-specific keyring (KEY_REQKEY_DEFL_THREAD_KEYRING;          seethread-keyring(7)).       •  The process-specific keyring (KEY_REQKEY_DEFL_PROCESS_KEYRING;          seeprocess-keyring(7)).       •  The session-specific keyring (KEY_REQKEY_DEFL_SESSION_KEYRING;          seesession-keyring(7)).       •  The session keyring for the process's user ID          (KEY_REQKEY_DEFL_USER_SESSION_KEYRING; seeuser-session-keyring(7)).  This keyring is expected to always          exist.       •  The UID-specific keyring (KEY_REQKEY_DEFL_USER_KEYRING; seeuser-keyring(7)).  This keyring is also expected to always          exist.       If thekeyctl(2)KEYCTL_SET_REQKEY_KEYRINGoperation specifiesKEY_REQKEY_DEFL_DEFAULT(or noKEYCTL_SET_REQKEY_KEYRINGoperation       is performed), then the kernel looks for a keyring starting from       the beginning of the list.Requesting user-space instantiation of a key       If the kernel cannot find a key matchingtype anddescription, andcallout is not NULL, then the kernel attempts to invoke a user-       space program to instantiate a key with the giventype anddescription.  In this case, the following steps are performed:       (1)  The kernel creates an uninstantiated key, U, with the            requestedtype anddescription.       (2)  The kernel creates an authorization key, V, that refers to            the key U and records the facts that the caller ofrequest_key() is:            (2.1)  the context in which the key U should be instantiated                   and secured, and            (2.2)  the context from which associated key requests may be                   satisfied.            The authorization key is constructed as follows:            •  The key type is".request_key_auth".            •  The key's UID and GID are the same as the corresponding               filesystem IDs of the requesting process.            •  The key grantsview,read, andsearch permissions to the               key possessor as well asview permission for the key user.            •  The description (name) of the key is the hexadecimal               string representing the ID of the key that is to be               instantiated in the requesting program.            •  The payload of the key is taken from the data specified incallout_info.            •  Internally, the kernel also records the PID of the process               that calledrequest_key().       (3)  The kernel creates a process that executes a user-space            service such asrequest-key(8) with a new session keyring            that contains a link to the authorization key, V.            This program is supplied with the following command-line            arguments:            [0]  The string"/sbin/request-key".            [1]  The string"create" (indicating that a key is to be                 created).            [2]  The ID of the key that is to be instantiated.            [3]  The filesystem UID of the caller ofrequest_key().            [4]  The filesystem GID of the caller ofrequest_key().            [5]  The ID of the thread keyring of the caller ofrequest_key().  This may be zero if that keyring hasn't                 been created.            [6]  The ID of the process keyring of the caller ofrequest_key().  This may be zero if that keyring hasn't                 been created.            [7]  The ID of the session keyring of the caller ofrequest_key().Note: each of the command-line arguments that is a key ID is            encoded indecimal (unlike the key IDs shown in/proc/keys,            which are shown as hexadecimal values).       (4)  The program spawned in the previous step:            •  Assumes the authority to instantiate the key U using thekeyctl(2)KEYCTL_ASSUME_AUTHORITYoperation (typically via               thekeyctl_assume_authority(3) function).            •  Obtains the callout data from the payload of the               authorization key V (using thekeyctl(2)KEYCTL_READ               operation (or, more commonly, thekeyctl_read(3) function)               with a key ID value ofKEY_SPEC_REQKEY_AUTH_KEY).            •  Instantiates the key (or execs another program that               performs that task), specifying the payload and               destination keyring.  (The destination keyring that the               requestor specified when callingrequest_key() can be               accessed using the special key IDKEY_SPEC_REQUESTOR_KEYRING.)  Instantiation is performed               using thekeyctl(2)KEYCTL_INSTANTIATEoperation (or, more               commonly, thekeyctl_instantiate(3) function).  At this               point, therequest_key() call completes, and the               requesting program can continue execution.       If these steps are unsuccessful, then anENOKEYerror will be       returned to the caller ofrequest_key() and a temporary,       negatively instantiated key will be installed in the keyring       specified bydest_keyring.  This will expire after a few seconds,       but will cause subsequent calls torequest_key() to fail until it       does.  The purpose of this negatively instantiated key is to       prevent (possibly different) processes making repeated requests       (that require expensiverequest-key(8) upcalls) for a key that       can't (at the moment) be positively instantiated.       Once the key has been instantiated, the authorization key       (KEY_SPEC_REQKEY_AUTH_KEY) is revoked, and the destination keyring       (KEY_SPEC_REQUESTOR_KEYRING) is no longer accessible from therequest-key(8) program.       If a key is created, then—regardless of whether it is a valid key       or a negatively instantiated key—it will displace any other key       with the same type and description from the keyring specified indest_keyring.

RETURN VALUE top

       On success,request_key() returns the serial number of the key it       found or caused to be created.  On error, -1 is returned anderrno       is set to indicate the error.

ERRORS top

EACCESThe keyring wasn't available for modification by the user.EDQUOTThe key quota for this user would be exceeded by creating              this key or linking it to the keyring.EFAULTOne oftype,description, orcallout_info points outside              the process's accessible address space.EINTRThe request was interrupted by a signal; seesignal(7).EINVALThe size of the string (including the terminating null              byte) specified intype ordescription exceeded the limit              (32 bytes and 4096 bytes respectively).EINVALThe size of the string (including the terminating null              byte) specified incallout_info exceeded the system page              size.EKEYEXPIRED              An expired key was found, but no replacement could be              obtained.EKEYREJECTED              The attempt to generate a new key was rejected.EKEYREVOKED              A revoked key was found, but no replacement could be              obtained.ENOKEYNo matching key was found.ENOMEMInsufficient memory to create a key.EPERMThetype argument started with a period ('.').

STANDARDS top

       Linux.

HISTORY top

       Linux 2.6.10.       The ability to instantiate keys upon request was added in Linux       2.6.13.

EXAMPLES top

       The program below demonstrates the use ofrequest_key().  Thetype,description, andcallout_info arguments for the system call       are taken from the values supplied in the command-line arguments.       The call specifies the session keyring as the target keyring.       In order to demonstrate this program, we first create a suitable       entry in the file/etc/request-key.conf.           $sudo sh;           #echo 'create user mtk:* *   /bin/keyctl instantiate %k %c %S' \> /etc/request-key.conf;           #exit;       This entry specifies that when a new "user" key with the prefix       "mtk:" must be instantiated, that task should be performed via thekeyctl(1) command'sinstantiateoperation.  The arguments supplied       to theinstantiateoperation are: the ID of the uninstantiated key       (%k); the callout data supplied to therequest_key() call (%c);       and the session keyring (%S) of the requestor (i.e., the caller ofrequest_key()).  Seerequest-key.conf(5) for details of these%       specifiers.       Then we run the program and check the contents of/proc/keys to       verify that the requested key has been instantiated:           $./t_request_key user mtk:key1 "Payload data";           $grep '2dddaf50' /proc/keys;           2dddaf50 I--Q---  1 perm 3f010000  1000  1000 user  mtk:key1: 12       For another example of the use of this program, seekeyctl(2).Program source       /* t_request_key.c */       #include <keyutils.h>       #include <stdint.h>       #include <stdio.h>       #include <stdlib.h>       int       main(int argc, char *argv[])       {           key_serial_t key;           if (argc != 4) {               fprintf(stderr, "Usage: %s type description callout-data\n",                       argv[0]);               exit(EXIT_FAILURE);           }           key = request_key(argv[1], argv[2], argv[3],                             KEY_SPEC_SESSION_KEYRING);           if (key == -1) {               perror("request_key");               exit(EXIT_FAILURE);           }           printf("Key ID is %jx\n", (uintmax_t) key);           exit(EXIT_SUCCESS);       }

COLOPHON top

       This page is part of theman-pages (Linux kernel and C library       user-space interface documentation) project.  Information about       the project can be found at        ⟨https://www.kernel.org/doc/man-pages/⟩.  If you have a bug report       for this manual page, see       ⟨https://git.kernel.org/pub/scm/docs/man-pages/man-pages.git/tree/CONTRIBUTING⟩.       This page was obtained from the tarball man-pages-6.15.tar.gz       fetched from       ⟨https://mirrors.edge.kernel.org/pub/linux/docs/man-pages/⟩ on       2025-08-11.  If you discover any rendering problems in this HTML       version of the page, or you believe there is a better or more up-       to-date source for the page, or you have corrections or       improvements to the information in this COLOPHON (which isnot       part of the original manual page), send a mail to       man-pages@man7.orgLinux man-pages 6.15            2025-05-17request_key(2)

Pages that refer to this page:keyctl(1), add_key(2), keyctl(2), KEYCTL_ASSUME_AUTHORITY(2const), KEYCTL_GET_KEYRING_ID(2const), KEYCTL_INSTANTIATE(2const), KEYCTL_SET_REQKEY_KEYRING(2const), KEYCTL_SET_TIMEOUT(2const), syscalls(2), find_key_by_type_and_name(3), keyctl(3), keyctl_capabilities(3), keyctl_chown(3), keyctl_clear(3), keyctl_describe(3), keyctl_get_keyring_ID(3), keyctl_get_persistent(3), keyctl_get_security(3), keyctl_instantiate(3), keyctl_invalidate(3), keyctl_join_session_keyring(3), keyctl_link(3), keyctl_move(3), keyctl_read(3), keyctl_revoke(3), keyctl_search(3), keyctl_session_to_parent(3), keyctl_setperm(3), keyctl_set_reqkey_keyring(3), keyctl_set_timeout(3), keyctl_update(3), keyctl_watch_key(3), keyrings(7), keyutils(7), persistent-keyring(7), user-keyring(7), user-session-keyring(7)