request_key(2)

1request_key(2)                System Calls Manual               request_key(2)
2
3
4

NAME

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

LIBRARY

9       Linux Key Management Utilities (libkeyutils, -lkeyutils)
10

SYNOPSIS

12       #include <keyutils.h>
13
14       key_serial_t request_key(const char *type, const char *description,
15                                const char *_Nullable callout_info,
16                                key_serial_t dest_keyring);
17

DESCRIPTION

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

RETURN VALUE

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

ERRORS

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

STANDARDS

253       Linux.
254

HISTORY

256       Linux 2.6.10.
257
258       The ability to instantiate keys upon request was added in Linux 2.6.13.
259

EXAMPLES

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