request_key(2)

1REQUEST_KEY(2)            Linux Key Management Calls            REQUEST_KEY(2)
2
3
4

NAME

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

SYNOPSIS

9       #include <keyutils.h>
10
11       key_serial_t request_key(const char *type, const char *description,
12                                const char *callout_info,
13                                key_serial_t dest_keyring);
14
15       Note: There is no glibc wrapper for this system call; see NOTES.
16

DESCRIPTION

18       request_key()  attempts to find a key of the given type with a descrip‐
19       tion (name) that matches the specified  description.   If  such  a  key
20       could  not be found, then the key is optionally created.  If the key is
21       found or created, request_key() attaches it to the keyring whose ID  is
22       specified in dest_keyring and returns the key's serial number.
23
24       request_key()  first  recursively searches for a matching key in all of
25       the keyrings  attached  to  the  calling  process.   The  keyrings  are
26       searched   in  the  order:  thread-specific  keyring,  process-specific
27       keyring, and then session keyring.
28
29       If request_key() is called from a program invoked by  request_key()  on
30       behalf  of  some  other process to generate a key, then the keyrings of
31       that other process will be searched next, using  that  other  process's
32       user ID, group ID, supplementary group IDs, and security context to de‐
33       termine access.
34
35       The search of the keyring tree  is  breadth-first:  the  keys  in  each
36       keyring  searched are checked for a match before any child keyrings are
37       recursed into.  Only keys for which the caller has search permission be
38       found, and only keyrings for which the caller has search permission may
39       be searched.
40
41       If the key is not found and callout is NULL, then the call  fails  with
42       the error ENOKEY.
43
44       If  the  key  is not found and callout is not NULL, then the kernel at‐
45       tempts to invoke a user-space program to instantiate the key.  The  de‐
46       tails are given below.
47
48       The dest_keyring serial number may be that of a valid keyring for which
49       the caller has write permission, or it may be one of the following spe‐
50       cial keyring IDs:
51
52       KEY_SPEC_THREAD_KEYRING
53              This   specifies   the  caller's  thread-specific  keyring  (see
54              thread-keyring(7)).
55
56       KEY_SPEC_PROCESS_KEYRING
57              This  specifies  the  caller's  process-specific  keyring   (see
58              process-keyring(7)).
59
60       KEY_SPEC_SESSION_KEYRING
61              This  specifies  the caller's session-specific keyring (see ses‐
62              sion-keyring(7)).
63
64       KEY_SPEC_USER_KEYRING
65              This  specifies   the   caller's   UID-specific   keyring   (see
66              user-keyring(7)).
67
68       KEY_SPEC_USER_SESSION_KEYRING
69              This  specifies  the caller's UID-session keyring (see user-ses‐
70              sion-keyring(7)).
71
72       When the dest_keyring is specified as 0 and  no  key  construction  has
73       been performed, then no additional linking is done.
74
75       Otherwise,  if  dest_keyring is 0 and a new key is constructed, the new
76       key will be linked to the "default" keyring.  More precisely, when  the
77       kernel  tries  to  determine to which keyring the newly constructed key
78       should be linked, it tries the following keyrings, beginning  with  the
79       keyring  set  via the keyctl(2) KEYCTL_SET_REQKEY_KEYRING operation and
80       continuing in the order shown below until it finds  the  first  keyring
81       that exists:
82
83       •  The   requestor  keyring  (KEY_REQKEY_DEFL_REQUESTOR_KEYRING,  since
84          Linux 2.6.29).
85
86       •  The  thread-specific  keyring  (KEY_REQKEY_DEFL_THREAD_KEYRING;  see
87          thread-keyring(7)).
88
89       •  The  process-specific  keyring (KEY_REQKEY_DEFL_PROCESS_KEYRING; see
90          process-keyring(7)).
91
92       •  The session-specific keyring  (KEY_REQKEY_DEFL_SESSION_KEYRING;  see
93          session-keyring(7)).
94
95       •  The   session   keyring   for   the   process's   user  ID  (KEY_RE‐
96          QKEY_DEFL_USER_SESSION_KEYRING; see user-session-keyring(7)).   This
97          keyring is expected to always exist.
98
99       •  The    UID-specific   keyring   (KEY_REQKEY_DEFL_USER_KEYRING;   see
100          user-keyring(7)).  This keyring is also expected to always exist.
101
102       If the keyctl(2) KEYCTL_SET_REQKEY_KEYRING operation specifies  KEY_RE‐
103       QKEY_DEFL_DEFAULT  (or  no  KEYCTL_SET_REQKEY_KEYRING operation is per‐
104       formed), then the kernel looks for a keyring starting from  the  begin‐
105       ning of the list.
106
107   Requesting user-space instantiation of a key
108       If  the  kernel  cannot  find  a key matching type and description, and
109       callout is not NULL, then the kernel attempts to  invoke  a  user-space
110       program  to  instantiate a key with the given type and description.  In
111       this case, the following steps are performed:
112
113       a)  The kernel creates an uninstantiated key,  U,  with  the  requested
114           type and description.
115
116       b)  The  kernel creates an authorization key, V, that refers to the key
117           U and records the facts that the caller of request_key() is:
118
119           (1) the context in which the key U should be instantiated  and  se‐
120               cured, and
121
122           (2) the  context  from  which associated key requests may be satis‐
123               fied.
124
125           The authorization key is constructed as follows:
126
127           *  The key type is ".request_key_auth".
128
129           *  The key's UID and GID are the same as the corresponding filesys‐
130              tem IDs of the requesting process.
131
132           *  The  key  grants  view,  read, and search permissions to the key
133              possessor as well as view permission for the key user.
134
135           *  The description (name) of the key is the hexadecimal string rep‐
136              resenting  the  ID  of the key that is to be instantiated in the
137              requesting program.
138
139           *  The payload of the key is taken from the data specified in call‐
140              out_info.
141
142           *  Internally,  the kernel also records the PID of the process that
143              called request_key().
144
145       c)  The kernel creates a process that  executes  a  user-space  service
146           such  as  request-key(8) with a new session keyring that contains a
147           link to the authorization key, V.
148
149           This program is supplied with the following command-line arguments:
150
151           [0] The string "/sbin/request-key".
152
153           [1] The string "create" (indicating that a key is to be created).
154
155           [2] The ID of the key that is to be instantiated.
156
157           [3] The filesystem UID of the caller of request_key().
158
159           [4] The filesystem GID of the caller of request_key().
160
161           [5] The ID of the thread keyring of the  caller  of  request_key().
162               This may be zero if that keyring hasn't been created.
163
164           [6] The  ID  of the process keyring of the caller of request_key().
165               This may be zero if that keyring hasn't been created.
166
167           [7] The ID of the session keyring of the caller of request_key().
168
169           Note: each of the command-line arguments that is a key  ID  is  en‐
170           coded in decimal (unlike the key IDs shown in /proc/keys, which are
171           shown as hexadecimal values).
172
173       d)  The program spawned in the previous step:
174
175           *  Assumes the  authority  to  instantiate  the  key  U  using  the
176              keyctl(2)  KEYCTL_ASSUME_AUTHORITY  operation (typically via the
177              keyctl_assume_authority(3) function).
178
179           *  Obtains the callout data from the payload of  the  authorization
180              key  V (using the keyctl(2) KEYCTL_READ operation (or, more com‐
181              monly, the keyctl_read(3) function)  with  a  key  ID  value  of
182              KEY_SPEC_REQKEY_AUTH_KEY).
183
184           *  Instantiates  the  key  (or  execs another program that performs
185              that task), specifying  the  payload  and  destination  keyring.
186              (The destination keyring that the requestor specified when call‐
187              ing request_key() can be  accessed  using  the  special  key  ID
188              KEY_SPEC_REQUESTOR_KEYRING.)   Instantiation  is performed using
189              the keyctl(2) KEYCTL_INSTANTIATE operation (or,  more  commonly,
190              the  keyctl_instantiate(3)  function).   At  this point, the re‐
191              quest_key() call completes, and the requesting program can  con‐
192              tinue execution.
193
194       If  these steps are unsuccessful, then an ENOKEY error will be returned
195       to the caller of request_key() and a temporary, negatively instantiated
196       key  will  be installed in the keyring specified by dest_keyring.  This
197       will expire after a few seconds, but will cause subsequent calls to re‐
198       quest_key()  to fail until it does.  The purpose of this negatively in‐
199       stantiated key is to prevent (possibly different) processes making  re‐
200       peated  requests  (that require expensive request-key(8) upcalls) for a
201       key that can't (at the moment) be positively instantiated.
202
203       Once the key has been instantiated, the authorization key (KEY_SPEC_RE‐
204       QKEY_AUTH_KEY)  is  revoked,  and the destination keyring (KEY_SPEC_RE‐
205       QUESTOR_KEYRING) is no longer accessible from the  request-key(8)  pro‐
206       gram.
207
208       If  a key is created, then—regardless of whether it is a valid key or a
209       negatively instantiated key—it will displace any  other  key  with  the
210       same type and description from the keyring specified in dest_keyring.
211

RETURN VALUE

213       On success, request_key() returns the serial number of the key it found
214       or caused to be created.  On error, -1 is returned and errno is set  to
215       indicate the error.
216

ERRORS

218       EACCES The keyring wasn't available for modification by the user.
219
220       EDQUOT The  key  quota for this user would be exceeded by creating this
221              key or linking it to the keyring.
222
223       EFAULT One of type, description, or  callout_info  points  outside  the
224              process's accessible address space.
225
226       EINTR  The request was interrupted by a signal; see signal(7).
227
228       EINVAL The  size  of  the  string (including the terminating null byte)
229              specified in type or description exceeded the  limit  (32  bytes
230              and 4096 bytes respectively).
231
232       EINVAL The  size  of  the  string (including the terminating null byte)
233              specified in callout_info exceeded the system page size.
234
235       EKEYEXPIRED
236              An expired key was found, but no replacement could be obtained.
237
238       EKEYREJECTED
239              The attempt to generate a new key was rejected.
240
241       EKEYREVOKED
242              A revoked key was found, but no replacement could be obtained.
243
244       ENOKEY No matching key was found.
245
246       ENOMEM Insufficient memory to create a key.
247
248       EPERM  The type argument started with a period ('.').
249

VERSIONS

251       This system call first appeared in Linux 2.6.10.  The  ability  to  in‐
252       stantiate keys upon request was added in Linux 2.6.13.
253

CONFORMING TO

255       This system call is a nonstandard Linux extension.
256

NOTES

258       Glibc  does  not  provide a wrapper for this system call.  A wrapper is
259       provided in the libkeyutils package.  When  employing  the  wrapper  in
260       that library, link with -lkeyutils.
261

EXAMPLES

263       The program below demonstrates the use of request_key().  The type, de‐
264       scription, and callout_info arguments for the  system  call  are  taken
265       from the values supplied in the command-line arguments.  The call spec‐
266       ifies the session keyring as the target keyring.
267
268       In order to demonstrate this program, we first create a suitable  entry
269       in the file /etc/request-key.conf.
270
271           $ sudo sh
272           # echo 'create user mtk:* *   /bin/keyctl instantiate %k %c %S' \
273                     > /etc/request-key.conf
274           # exit
275
276       This  entry specifies that when a new "user" key with the prefix "mtk:"
277       must be instantiated, that task should be performed via  the  keyctl(1)
278       command's instantiate operation.  The arguments supplied to the instan‐
279       tiate operation are: the ID of the uninstantiated key (%k); the callout
280       data  supplied  to the request_key() call (%c); and the session keyring
281       (%S) of the requestor (i.e., the caller  of  request_key()).   See  re‐
282       quest-key.conf(5) for details of these % specifiers.
283
284       Then  we run the program and check the contents of /proc/keys to verify
285       that the requested key has been instantiated:
286
287           $ ./t_request_key user mtk:key1 "Payload data"
288           $ grep '2dddaf50' /proc/keys
289           2dddaf50 I--Q---  1 perm 3f010000  1000  1000 user  mtk:key1: 12
290
291       For another example of the use of this program, see keyctl(2).
292
293   Program source
294
295       /* t_request_key.c */
296
297       #include <sys/types.h>
298       #include <keyutils.h>
299       #include <stdint.h>
300       #include <stdio.h>
301       #include <stdlib.h>
302       #include <string.h>
303
304       int
305       main(int argc, char *argv[])
306       {
307           key_serial_t key;
308
309           if (argc != 4) {
310               fprintf(stderr, "Usage: %s type description callout-data\n",
311                       argv[0]);
312               exit(EXIT_FAILURE);
313           }
314
315           key = request_key(argv[1], argv[2], argv[3],
316                             KEY_SPEC_SESSION_KEYRING);
317           if (key == -1) {
318               perror("request_key");
319               exit(EXIT_FAILURE);
320           }
321
322           printf("Key ID is %jx\n", (uintmax_t) key);
323
324           exit(EXIT_SUCCESS);
325       }
326

COLOPHON

339       This page is part of release 5.12 of the Linux man-pages project.  A
340       description of the project, information about reporting bugs, and the
341       latest version of this page, can be found at
342       https://www.kernel.org/doc/man-pages/.
343
344
345
346Linux                             2021-03-22                    REQUEST_KEY(2)