1 .\" Copyright (C) 2006 Red Hat, Inc. All Rights Reserved.
2 .\" Written by David Howells (dhowells@redhat.com)
3 .\" and Copyright (C) 2016 Michael Kerrisk <mtk.man-pages@gmail.com>
5 .\" %%%LICENSE_START(GPLv2+_SW_ONEPARA)
6 .\" This program is free software; you can redistribute it and/or
7 .\" modify it under the terms of the GNU General Public License
8 .\" as published by the Free Software Foundation; either version
9 .\" 2 of the License, or (at your option) any later version.
12 .TH REQUEST_KEY 2 2020-11-01 Linux "Linux Key Management Calls"
14 request_key \- request a key from the kernel's key management facility
17 .B #include <keyutils.h>
19 .BI "key_serial_t request_key(const char *" type ", const char *" description ,
20 .BI " const char *" callout_info ,
21 .BI " key_serial_t " dest_keyring ");"
25 There is no glibc wrapper for this system call; see NOTES.
28 attempts to find a key of the given
30 with a description (name) that matches the specified
32 If such a key could not be found, then the key is optionally created.
33 If the key is found or created,
35 attaches it to the keyring whose ID is specified in
37 and returns the key's serial number.
40 first recursively searches for a matching key in all of the keyrings
41 attached to the calling process.
42 The keyrings are searched in the order: thread-specific keyring,
43 process-specific keyring, and then session keyring.
47 is called from a program invoked by
49 on behalf of some other process to generate a key, then the keyrings of that
50 other process will be searched next,
51 using that other process's user ID, group ID,
52 supplementary group IDs, and security context to determine access.
53 .\" David Howells: we can then have an arbitrarily long sequence
54 .\" of "recursive" request-key upcalls. There is no limit, other
55 .\" than number of PIDs, etc.
57 The search of the keyring tree is breadth-first:
58 the keys in each keyring searched are checked for a match before any child
59 keyrings are recursed into.
60 Only keys for which the caller has
62 permission be found, and only keyrings for which the caller has
64 permission may be searched.
66 If the key is not found and
68 is NULL, then the call fails with the error
71 If the key is not found and
73 is not NULL, then the kernel attempts to invoke a user-space
74 program to instantiate the key.
75 The details are given below.
79 serial number may be that of a valid keyring for which the caller has
81 permission, or it may be one of the following special keyring IDs:
83 .B KEY_SPEC_THREAD_KEYRING
84 This specifies the caller's thread-specific keyring (see
85 .BR thread\-keyring (7)).
87 .B KEY_SPEC_PROCESS_KEYRING
88 This specifies the caller's process-specific keyring (see
89 .BR process\-keyring (7)).
91 .B KEY_SPEC_SESSION_KEYRING
92 This specifies the caller's session-specific keyring (see
93 .BR session\-keyring (7)).
95 .B KEY_SPEC_USER_KEYRING
96 This specifies the caller's UID-specific keyring (see
97 .BR user\-keyring (7)).
99 .B KEY_SPEC_USER_SESSION_KEYRING
100 This specifies the caller's UID-session keyring (see
101 .BR user\-session\-keyring (7)).
106 and no key construction has been performed,
107 then no additional linking is done.
111 is 0 and a new key is constructed, the new key will be linked
112 to the "default" keyring.
113 More precisely, when the kernel tries to determine to which keyring the
114 newly constructed key should be linked,
115 it tries the following keyrings,
116 beginning with the keyring set via the
118 .BR KEYCTL_SET_REQKEY_KEYRING
119 operation and continuing in the order shown below
120 until it finds the first keyring that exists:
122 .\" 8bbf4976b59fc9fc2861e79cab7beb3f6d647640
123 The requestor keyring
124 .RB ( KEY_REQKEY_DEFL_REQUESTOR_KEYRING ,
127 .\" Actually, is the preceding point correct?
128 .\" If I understand correctly, we'll only get here if
129 .\" 'dest_keyring' is zero, in which case KEY_REQKEY_DEFL_REQUESTOR_KEYRING
130 .\" won't refer to a keyring. Have I misunderstood?
132 The thread-specific keyring
133 .RB ( KEY_REQKEY_DEFL_THREAD_KEYRING ;
135 .BR thread\-keyring (7)).
137 The process-specific keyring
138 .RB ( KEY_REQKEY_DEFL_PROCESS_KEYRING ;
140 .BR process\-keyring (7)).
142 The session-specific keyring
143 .RB ( KEY_REQKEY_DEFL_SESSION_KEYRING ;
145 .BR session\-keyring (7)).
147 The session keyring for the process's user ID
148 .RB ( KEY_REQKEY_DEFL_USER_SESSION_KEYRING ;
150 .BR user\-session\-keyring (7)).
151 This keyring is expected to always exist.
153 The UID-specific keyring
154 .RB ( KEY_REQKEY_DEFL_USER_KEYRING ;
156 .BR user\-keyring (7)).
157 This keyring is also expected to always exist.
158 .\" mtk: Are there circumstances where the user sessions and UID-specific
159 .\" keyrings do not exist?
162 .\" The uid keyrings don't exist until someone tries to access them -
163 .\" at which point they're both created. When you log in, pam_keyinit
164 .\" creates a link to your user keyring in the session keyring it just
165 .\" created, thereby creating the user and user-session keyrings.
167 .\" and David elaborated that "access" means:
169 .\" It means lookup_user_key() was passed KEY_LOOKUP_CREATE. So:
171 .\" add_key() - destination keyring
172 .\" request_key() - destination keyring
173 .\" KEYCTL_GET_KEYRING_ID - if create arg is true
175 .\" KEYCTL_LINK - both args
176 .\" KEYCTL_SEARCH - destination keyring
179 .\" KEYCTL_SET_TIMEOUT
180 .\" KEYCTL_INSTANTIATE - destination keyring
181 .\" KEYCTL_INSTANTIATE_IOV - destination keyring
182 .\" KEYCTL_NEGATE - destination keyring
183 .\" KEYCTL_REJECT - destination keyring
184 .\" KEYCTL_GET_PERSISTENT - destination keyring
186 .\" will all create a keyring under some circumstances. Whereas the rest,
187 .\" such as KEYCTL_GET_SECURITY, KEYCTL_READ and KEYCTL_REVOKE, won't.
191 .BR KEYCTL_SET_REQKEY_KEYRING
193 .BR KEY_REQKEY_DEFL_DEFAULT
195 .BR KEYCTL_SET_REQKEY_KEYRING
196 operation is performed),
197 then the kernel looks for a keyring
198 starting from the beginning of the list.
200 .SS Requesting user-space instantiation of a key
201 If the kernel cannot find a key matching
207 is not NULL, then the kernel attempts to invoke a user-space
208 program to instantiate a key with the given
212 In this case, the following steps are performed:
214 The kernel creates an uninstantiated key, U, with the requested
219 The kernel creates an authorization key, V,
220 .\" struct request_key_auth, defined in security/keys/internal.h
221 that refers to the key U and records the facts that the caller of
226 the context in which the key U should be instantiated and secured, and
228 the context from which associated key requests may be satisfied.
231 The authorization key is constructed as follows:
235 .IR """.request_key_auth""" .
237 The key's UID and GID are the same as the corresponding filesystem IDs
238 of the requesting process.
245 permissions to the key possessor as well as
247 permission for the key user.
249 The description (name) of the key is the hexadecimal
250 string representing the ID of the key that is to be instantiated
251 in the requesting program.
253 The payload of the key is taken from the data specified in
256 Internally, the kernel also records the PID of the process that called
260 The kernel creates a process that executes a user-space service such as
262 with a new session keyring that contains a link to the authorization key, V.
263 .\" The request\-key(8) program can be invoked in circumstances *other* than
264 .\" when triggered by request_key(2). For example, upcalls from places such
265 .\" as the DNS resolver.
267 This program is supplied with the following command-line arguments:
271 .IR """/sbin/request\-key""" .
275 (indicating that a key is to be created).
277 The ID of the key that is to be instantiated.
279 The filesystem UID of the caller of
282 The filesystem GID of the caller of
285 The ID of the thread keyring of the caller of
287 This may be zero if that keyring hasn't been created.
289 The ID of the process keyring of the caller of
291 This may be zero if that keyring hasn't been created.
293 The ID of the session keyring of the caller of
298 each of the command-line arguments that is a key ID is encoded in
300 (unlike the key IDs shown in
302 which are shown as hexadecimal values).
304 The program spawned in the previous step:
307 Assumes the authority to instantiate the key U using the
309 .BR KEYCTL_ASSUME_AUTHORITY
310 operation (typically via the
311 .BR keyctl_assume_authority (3)
314 Obtains the callout data from the payload of the authorization key V
318 operation (or, more commonly, the
320 function) with a key ID value of
321 .BR KEY_SPEC_REQKEY_AUTH_KEY ).
324 (or execs another program that performs that task),
325 specifying the payload and destination keyring.
326 (The destination keyring that the requestor specified when calling
328 can be accessed using the special key ID
329 .BR KEY_SPEC_REQUESTOR_KEYRING .)
330 .\" Should an instantiating program be using KEY_SPEC_REQUESTOR_KEYRING?
331 .\" I couldn't find a use in the keyutils git repo.
332 .\" According to David Howells:
333 .\" * This feature is provided, but not used at the moment.
334 .\" * A key added to that ring is then owned by the requester
335 Instantiation is performed using the
337 .BR KEYCTL_INSTANTIATE
338 operation (or, more commonly, the
339 .BR keyctl_instantiate (3)
343 call completes, and the requesting program can continue execution.
346 If these steps are unsuccessful, then an
348 error will be returned to the caller of
350 and a temporary, negatively instantiated key will be installed
351 in the keyring specified by
353 This will expire after a few seconds, but will cause subsequent calls to
355 to fail until it does.
356 The purpose of this negatively instantiated key is to prevent
357 (possibly different) processes making repeated requests
358 (that require expensive
360 upcalls) for a key that can't (at the moment) be positively instantiated.
362 Once the key has been instantiated, the authorization key
363 .RB ( KEY_SPEC_REQKEY_AUTH_KEY )
364 is revoked, and the destination keyring
365 .RB ( KEY_SPEC_REQUESTOR_KEYRING )
366 is no longer accessible from the
370 If a key is created, then\(emregardless of whether it is a valid key or
371 a negatively instantiated key\(emit will displace any other key with
372 the same type and description from the keyring specified in
377 returns the serial number of the key it found or caused to be created.
378 On error, \-1 is returned and
380 is set to indicate the error.
384 The keyring wasn't available for modification by the user.
387 The key quota for this user would be exceeded by creating this key or linking
396 points outside the process's accessible address space.
399 The request was interrupted by a signal; see
403 The size of the string (including the terminating null byte) specified in
407 exceeded the limit (32 bytes and 4096 bytes respectively).
410 The size of the string (including the terminating null byte) specified in
412 exceeded the system page size.
415 An expired key was found, but no replacement could be obtained.
418 The attempt to generate a new key was rejected.
421 A revoked key was found, but no replacement could be obtained.
424 No matching key was found.
427 Insufficient memory to create a key.
432 argument started with a period (\(aq.\(aq).
434 This system call first appeared in Linux 2.6.10.
435 The ability to instantiate keys upon request was added
436 .\" commit 3e30148c3d524a9c1c63ca28261bc24c457eb07a
439 This system call is a nonstandard Linux extension.
441 Glibc does not provide a wrapper for this system call.
442 A wrapper is provided in the
445 When employing the wrapper in that library, link with
448 The program below demonstrates the use of
455 arguments for the system call are taken from the values
456 supplied in the command-line arguments.
457 The call specifies the session keyring as the target keyring.
459 In order to demonstrate this program,
460 we first create a suitable entry in the file
461 .IR /etc/request\-key.conf .
466 # \fBecho \(aqcreate user mtk:* * /bin/keyctl instantiate %k %c %S\(aq \e\fP
467 \fB> /etc/request\-key.conf\fP
472 This entry specifies that when a new "user" key with the prefix
473 "mtk:" must be instantiated, that task should be performed via the
478 The arguments supplied to the
481 the ID of the uninstantiated key
483 the callout data supplied to the
487 and the session keyring
489 of the requestor (i.e., the caller of
492 .BR request\-key.conf (5)
497 Then we run the program and check the contents of
499 to verify that the requested key has been instantiated:
503 $ \fB./t_request_key user mtk:key1 "Payload data"\fP
504 $ \fBgrep \(aq2dddaf50\(aq /proc/keys\fP
505 2dddaf50 I\-\-Q\-\-\- 1 perm 3f010000 1000 1000 user mtk:key1: 12
509 For another example of the use of this program, see
514 /* t_request_key.c */
516 #include <sys/types.h>
517 #include <keyutils.h>
524 main(int argc, char *argv[])
529 fprintf(stderr, "Usage: %s type description callout\-data\en",
534 key = request_key(argv[1], argv[2], argv[3],
535 KEY_SPEC_SESSION_KEYRING);
537 perror("request_key");
541 printf("Key ID is %jx\en", (uintmax_t) key);
553 .BR capabilities (7),
556 .BR persistent\-keyring (7),
557 .BR process\-keyring (7),
558 .BR session\-keyring (7),
559 .BR thread\-keyring (7),
560 .BR user\-keyring (7),
561 .BR user\-session\-keyring (7),
564 The kernel source files
565 .IR Documentation/security/keys/core.rst
567 .IR Documentation/keys/request\-key.rst
568 (or, before Linux 4.13, in the files
569 .\" commit b68101a1e8f0263dbc7b8375d2a7c57c6216fb76
570 .IR Documentation/security/keys.txt
572 .\" commit 3db38ed76890565772fcca3279cc8d454ea6176b
573 .IR Documentation/security/keys\-request\-key.txt ).