]>
Commit | Line | Data |
---|---|---|
6dd17d23 | 1 | .\" Copyright (C) 2006 Red Hat, Inc. All Rights Reserved. |
a7c31ed8 MK |
2 | .\" Written by David Howells (dhowells@redhat.com) |
3 | .\" and Copyright (C) 2016 Michael Kerrisk <mtk.man-pages@gmail.com> | |
6dd17d23 | 4 | .\" |
23dbdcbe | 5 | .\" %%%LICENSE_START(GPLv2+_SW_ONEPARA) |
6dd17d23 MK |
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. | |
722b6788 | 10 | .\" %%%LICENSE_END |
6dd17d23 | 11 | .\" |
31a1b45e | 12 | .TH REQUEST_KEY 2 2017-03-13 Linux "Linux Key Management Calls" |
6dd17d23 | 13 | .SH NAME |
f68512e9 | 14 | request_key \- request a key from the kernel's key management facility |
6dd17d23 MK |
15 | .SH SYNOPSIS |
16 | .nf | |
6011de34 | 17 | .B #include <sys/types.h> |
6dd17d23 | 18 | .B #include <keyutils.h> |
68e4db0a | 19 | .PP |
6dd17d23 | 20 | .BI "key_serial_t request_key(const char *" type ", const char *" description , |
74819bb2 | 21 | .BI " const char *" callout_info , |
f3ff1d07 | 22 | .BI " key_serial_t " dest_keyring ");" |
6030f2d8 | 23 | .fi |
dbfe9c70 | 24 | .PP |
d2f1788e | 25 | No glibc wrapper is provided for this system call; see NOTES. |
6dd17d23 MK |
26 | .SH DESCRIPTION |
27 | .BR request_key () | |
e2eab914 | 28 | attempts to find a key of the given |
6dd17d23 | 29 | .I type |
e2eab914 | 30 | with a description (name) that matches the specified |
2e3b9c2a | 31 | .IR description . |
53705ead MK |
32 | If such a key could not be found, then the key is optionally created. |
33 | If the key is found or created, | |
2e3b9c2a | 34 | .BR request_key () |
f3ff1d07 MK |
35 | attaches it to the keyring whose ID is specified in |
36 | .I dest_keyring | |
2e3b9c2a | 37 | and returns the key's serial number. |
efeece04 | 38 | .PP |
6dd17d23 | 39 | .BR request_key () |
e2eab914 MK |
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. | |
11ac5b51 | 44 | .PP |
6dd17d23 MK |
45 | If |
46 | .BR request_key () | |
47 | is called from a program invoked by | |
48 | .BR request_key () | |
49 | on behalf of some other process to generate a key, then the keyrings of that | |
e2eab914 MK |
50 | other process will be searched next, |
51 | using that other process's user ID, group ID, | |
7ea452dc | 52 | supplementary group IDs, and security context to determine access. |
466c3cd8 MK |
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. | |
11ac5b51 | 56 | .PP |
3d4f67dd MK |
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 | |
4175f999 | 59 | keyrings are recursed into. |
2e3b9c2a MK |
60 | Only keys for which the caller has |
61 | .I search | |
62 | permission be found, and only keyrings for which the caller has | |
63 | .I search | |
64 | permission may be searched. | |
11ac5b51 | 65 | .PP |
53705ead MK |
66 | If the key is not found and |
67 | .I callout | |
68 | is NULL, then the call fails with the error | |
69 | .BR ENOKEY . | |
efeece04 | 70 | .PP |
53705ead MK |
71 | If the key is not found and |
72 | .I callout | |
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. | |
efeece04 | 76 | .PP |
53705ead | 77 | The |
f3ff1d07 | 78 | .I dest_keyring |
53705ead MK |
79 | serial number may be that of a valid keyring for which the caller has |
80 | .I write | |
81 | permission, or it may be one of the following special keyring IDs: | |
82 | .TP | |
83 | .B KEY_SPEC_THREAD_KEYRING | |
3b7f994e MK |
84 | This specifies the caller's thread-specific keyring (see |
85 | .BR thread-keyring (7)). | |
53705ead MK |
86 | .TP |
87 | .B KEY_SPEC_PROCESS_KEYRING | |
3b7f994e MK |
88 | This specifies the caller's process-specific keyring (see |
89 | .BR process-keyring (7)). | |
53705ead MK |
90 | .TP |
91 | .B KEY_SPEC_SESSION_KEYRING | |
3b7f994e MK |
92 | This specifies the caller's session-specific keyring (see |
93 | .BR session-keyring (7)). | |
53705ead MK |
94 | .TP |
95 | .B KEY_SPEC_USER_KEYRING | |
3b7f994e MK |
96 | This specifies the caller's UID-specific keyring (see |
97 | .BR user-keyring (7)). | |
53705ead MK |
98 | .TP |
99 | .B KEY_SPEC_USER_SESSION_KEYRING | |
3b7f994e MK |
100 | This specifies the caller's UID-session keyring (see |
101 | .BR user-session-keyring (7)). | |
2bcf8580 ES |
102 | .PP |
103 | When the | |
104 | .I dest_keyring | |
1d7f3c5e | 105 | is specified as 0 |
bfedb010 | 106 | and no key construction has been performed, |
6dfb4dda | 107 | then no additional linking is done. |
efeece04 | 108 | .PP |
5e0d5def MK |
109 | Otherwise, if |
110 | .I dest_keyring | |
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 | |
2bcf8580 | 117 | .BR keyctl (2) |
5e0d5def | 118 | .BR KEYCTL_SET_REQKEY_KEYRING |
82918334 | 119 | operation and continuing in the order shown below |
5e0d5def | 120 | until it finds the first keyring that exists: |
2bcf8580 ES |
121 | .IP \(bu 3 |
122 | .\" 8bbf4976b59fc9fc2861e79cab7beb3f6d647640 | |
5e0d5def MK |
123 | The requestor keyring |
124 | .RB ( KEY_REQKEY_DEFL_REQUESTOR_KEYRING , | |
125 | since Linux 2.6.29). | |
5834768e MK |
126 | .\" FIXME |
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? | |
2bcf8580 | 131 | .IP \(bu |
5e0d5def | 132 | The thread-specific keyring |
7f1f4bad MK |
133 | .RB ( KEY_REQKEY_DEFL_THREAD_KEYRING ; |
134 | see | |
135 | .BR thread-keyring (7)). | |
2bcf8580 | 136 | .IP \(bu |
5e0d5def | 137 | The process-specific keyring |
7f1f4bad MK |
138 | .RB ( KEY_REQKEY_DEFL_PROCESS_KEYRING ; |
139 | see | |
140 | .BR process-keyring (7)). | |
2bcf8580 | 141 | .IP \(bu |
5e0d5def | 142 | The session-specific keyring |
7f1f4bad MK |
143 | .RB ( KEY_REQKEY_DEFL_SESSION_KEYRING ; |
144 | see | |
145 | .BR session-keyring (7)). | |
2bcf8580 | 146 | .IP \(bu |
afa27faa | 147 | The session keyring for the process's user ID |
7f1f4bad MK |
148 | .RB ( KEY_REQKEY_DEFL_USER_SESSION_KEYRING ; |
149 | see | |
150 | .BR user-session-keyring (7)). | |
2bcf8580 ES |
151 | This keyring is expected to always exist. |
152 | .IP \(bu | |
5e0d5def | 153 | The UID-specific keyring |
7f1f4bad MK |
154 | .RB ( KEY_REQKEY_DEFL_USER_KEYRING ; |
155 | see | |
156 | .BR user-keyring (7)). | |
2bcf8580 | 157 | This keyring is also expected to always exist. |
2db8e1cc MK |
158 | .\" mtk: Are there circumstances where the user sessions and UID-specific |
159 | .\" keyrings do not exist? | |
160 | .\" | |
161 | .\" David Howells: | |
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. | |
166 | .\" | |
167 | .\" and David elaborated that "access" means: | |
168 | .\" | |
169 | .\" It means lookup_user_key() was passed KEY_LOOKUP_CREATE. So: | |
170 | .\" | |
171 | .\" add_key() - destination keyring | |
172 | .\" request_key() - destination keyring | |
173 | .\" KEYCTL_GET_KEYRING_ID - if create arg is true | |
174 | .\" KEYCTL_CLEAR | |
175 | .\" KEYCTL_LINK - both args | |
176 | .\" KEYCTL_SEARCH - destination keyring | |
177 | .\" KEYCTL_CHOWN | |
178 | .\" KEYCTL_SETPERM | |
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 | |
185 | .\" | |
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. | |
2bcf8580 | 188 | .PP |
5e0d5def MK |
189 | If the |
190 | .BR keyctl (2) | |
191 | .BR KEYCTL_SET_REQKEY_KEYRING | |
82918334 | 192 | operation specifies |
5e0d5def MK |
193 | .BR KEY_REQKEY_DEFL_DEFAULT |
194 | (or no | |
195 | .BR KEYCTL_SET_REQKEY_KEYRING | |
82918334 | 196 | operation is performed), |
5e0d5def MK |
197 | then the kernel looks for a keyring |
198 | starting from the beginning of the list. | |
53705ead MK |
199 | .\" |
200 | .SS Requesting user-space instantiation of a key | |
201 | If the kernel cannot find a key matching | |
202 | .IR type | |
203 | and | |
204 | .IR description , | |
205 | and | |
206 | .I callout | |
207 | is not NULL, then the kernel attempts to invoke a user-space | |
208 | program to instantiate a key with the given | |
209 | .IR type | |
210 | and | |
211 | .IR description . | |
120ea0c8 | 212 | In this case, the following steps are performed: |
53705ead | 213 | .IP a) 4 |
120ea0c8 MK |
214 | The kernel creates an uninstantiated key, U, with the requested |
215 | .I type | |
216 | and | |
217 | .IR description . | |
53705ead | 218 | .IP b) |
442a3aeb MK |
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 | |
4084e9b9 | 222 | .BR request_key () |
7ea452dc MK |
223 | is: |
224 | .RS | |
225 | .IP (1) 4 | |
226 | the context in which the key U should be instantiated and secured, and | |
1bf661a0 | 227 | .IP (2) |
7ea452dc MK |
228 | the context from which associated key requests may be satisfied. |
229 | .RE | |
230 | .IP | |
53705ead MK |
231 | The authorization key is constructed as follows: |
232 | .RS | |
233 | .IP * 3 | |
234 | The key type is | |
235 | .IR """.request_key_auth""" . | |
236 | .IP * | |
237 | The key's UID and GID are the same as the corresponding filesystem IDs | |
238 | of the requesting process. | |
239 | .IP * | |
240 | The key grants | |
241 | .IR view , | |
242 | .IR read , | |
243 | and | |
244 | .IR search | |
245 | permissions to the key possessor as well as | |
246 | .IR view | |
247 | permission for the key user. | |
248 | .IP * | |
249 | The description (name) of the key is the hexadecimal | |
442a3aeb MK |
250 | string representing the ID of the key that is to be instantiated |
251 | in the requesting program. | |
53705ead MK |
252 | .IP * |
253 | The payload of the key is taken from the data specified in | |
120ea0c8 | 254 | .IR callout_info . |
442a3aeb | 255 | .IP * |
9b0ac3ef | 256 | Internally, the kernel also records the PID of the process that called |
4084e9b9 | 257 | .BR request_key (). |
53705ead MK |
258 | .RE |
259 | .IP c) | |
120ea0c8 | 260 | The kernel creates a process that executes a user-space service such as |
2e3b9c2a | 261 | .BR request-key (8) |
120ea0c8 | 262 | with a new session keyring that contains a link to the authorization key, V. |
7ea452dc MK |
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. | |
efeece04 | 266 | .IP |
53705ead MK |
267 | This program is supplied with the following command-line arguments: |
268 | .RS | |
269 | .IP [0] 4 | |
270 | The string | |
271 | .IR """/sbin/request-key""" . | |
272 | .IP [1] | |
273 | The string | |
274 | .I """create""" | |
275 | (indicating that a key is to be created). | |
276 | .IP [2] | |
277 | The ID of the key that is to be instantiated. | |
278 | .IP [3] | |
279 | The filesystem UID of the caller of | |
280 | .BR request_key (). | |
281 | .IP [4] | |
282 | The filesystem GID of the caller of | |
283 | .BR request_key (). | |
284 | .IP [5] | |
285 | The ID of the thread keyring of the caller of | |
286 | .BR request_key (). | |
287 | This may be zero if that keyring hasn't been created. | |
288 | .IP [6] | |
289 | The ID of the process keyring of the caller of | |
290 | .BR request_key (). | |
291 | This may be zero if that keyring hasn't been created. | |
292 | .IP [7] | |
293 | The ID of the session keyring of the caller of | |
294 | .BR request_key (). | |
295 | .RE | |
296 | .IP | |
297 | .IR Note : | |
7ea452dc | 298 | each of the command-line arguments that is a key ID is encoded in |
53705ead MK |
299 | .IR decimal |
300 | (unlike the key IDs shown in | |
301 | .IR /proc/keys , | |
302 | which are shown as hexadecimal values). | |
303 | .IP d) | |
120ea0c8 MK |
304 | The program spawned in the previous step: |
305 | .RS | |
306 | .IP * 3 | |
307 | Assumes the authority to instantiate the key U using the | |
308 | .BR keyctl (2) | |
309 | .BR KEYCTL_ASSUME_AUTHORITY | |
7ea452dc MK |
310 | operation (typically via the |
311 | .BR keyctl_assume_authority (3) | |
312 | function). | |
120ea0c8 | 313 | .IP * |
7ea452dc MK |
314 | Obtains the callout data from the payload of the authorization key V |
315 | (using the | |
120ea0c8 MK |
316 | .BR keyctl (2) |
317 | .BR KEYCTL_READ | |
7ea452dc MK |
318 | operation (or, more commonly, the |
319 | .BR keyctl_read (3) | |
320 | function) with a key ID value of | |
120ea0c8 MK |
321 | .BR KEY_SPEC_REQKEY_AUTH_KEY ). |
322 | .IP * | |
323 | Instantiates the key | |
53705ead MK |
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 | |
327 | .BR request_key () | |
328 | can be accessed using the special key ID | |
329 | .BR KEY_SPEC_REQUESTOR_KEYRING .) | |
7ea452dc | 330 | .\" Should an instantiating program be using KEY_SPEC_REQUESTOR_KEYRING? |
51b9f6c0 | 331 | .\" I couldn't find a use in the keyutils git repo. |
7ea452dc MK |
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 | |
336 | .BR keyctl (2) | |
337 | .BR KEYCTL_INSTANTIATE | |
338 | operation (or, more commonly, the | |
339 | .BR keyctl_instantiate (3) | |
340 | function). | |
341 | At this point, the | |
4084e9b9 | 342 | .BR request_key () |
7ea452dc | 343 | call completes, and the requesting program can continue execution. |
120ea0c8 | 344 | .RE |
11ac5b51 | 345 | .PP |
53705ead MK |
346 | If these steps are unsuccessful, then an |
347 | .BR ENOKEY | |
348 | error will be returned to the caller of | |
349 | .BR request_key () | |
4c8ae226 MK |
350 | and a temporary, negatively instantiated key will be installed |
351 | in the keyring specified by | |
f3ff1d07 | 352 | .IR dest_keyring . |
53705ead | 353 | This will expire after a few seconds, but will cause subsequent calls to |
6dd17d23 MK |
354 | .BR request_key () |
355 | to fail until it does. | |
7ea452dc MK |
356 | The purpose of this negatively instantiated key is to prevent |
357 | (possibly different) processes making repeated requests | |
358 | (that require expensive | |
359 | .BR request-key (8) | |
360 | upcalls) for a key that can't (at the moment) be positively instantiated. | |
efeece04 | 361 | .PP |
7ea452dc MK |
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 | |
367 | .BR request-key (8) | |
368 | program. | |
efeece04 | 369 | .PP |
2e3b9c2a | 370 | If a key is created, then\(emregardless of whether it is a valid key or |
4c8ae226 | 371 | a negatively instantiated key\(emit will displace any other key with |
f3ff1d07 MK |
372 | the same type and description from the keyring specified in |
373 | .IR dest_keyring . | |
6dd17d23 | 374 | .SH RETURN VALUE |
e2eab914 | 375 | On success, |
6dd17d23 | 376 | .BR request_key () |
2e3b9c2a | 377 | returns the serial number of the key it found or caused to be created. |
e2eab914 MK |
378 | On error, \-1 is returned and |
379 | .I errno | |
380 | is set to indicate the cause of the error. | |
6dd17d23 MK |
381 | .SH ERRORS |
382 | .TP | |
27807c32 MK |
383 | .B EACCES |
384 | The keyring wasn't available for modification by the user. | |
385 | .TP | |
27807c32 MK |
386 | .B EDQUOT |
387 | The key quota for this user would be exceeded by creating this key or linking | |
388 | it to the keyring. | |
6dd17d23 | 389 | .TP |
f70b502d | 390 | .B EFAULT |
24fcf1d3 MK |
391 | One of |
392 | .IR type , | |
393 | .IR description , | |
394 | or | |
395 | .IR callout_info | |
396 | points outside the process's accessible address space. | |
f70b502d | 397 | .TP |
3a0d6510 MK |
398 | .B EINTR |
399 | The request was interrupted by a signal; see | |
400 | .BR signal (7). | |
401 | .TP | |
61baf869 MK |
402 | .B EINVAL |
403 | The size of the string (including the terminating null byte) specified in | |
404 | .I type | |
405 | or | |
406 | .I description | |
407 | exceeded the limit (32 bytes and 4096 bytes respectively). | |
408 | .TP | |
409 | .B EINVAL | |
410 | The size of the string (including the terminating null byte) specified in | |
411 | .I callout_info | |
412 | exceeded the system page size. | |
413 | .TP | |
6dd17d23 MK |
414 | .B EKEYEXPIRED |
415 | An expired key was found, but no replacement could be obtained. | |
416 | .TP | |
6dd17d23 MK |
417 | .B EKEYREJECTED |
418 | The attempt to generate a new key was rejected. | |
419 | .TP | |
27807c32 MK |
420 | .B EKEYREVOKED |
421 | A revoked key was found, but no replacement could be obtained. | |
422 | .TP | |
27807c32 MK |
423 | .B ENOKEY |
424 | No matching key was found. | |
3a0d6510 MK |
425 | .TP |
426 | .B ENOMEM | |
427 | Insufficient memory to create a key. | |
f70b502d ES |
428 | .TP |
429 | .B EPERM | |
430 | The | |
431 | .I type | |
24fcf1d3 | 432 | argument started with a period (\(aq.\(aq). |
a2b148c3 | 433 | .SH VERSIONS |
5685b18c | 434 | This system call first appeared in Linux 2.6.10. |
24fcf1d3 MK |
435 | The ability to instantiate keys upon request was added |
436 | .\" commit 3e30148c3d524a9c1c63ca28261bc24c457eb07a | |
437 | in Linux 2.6.13. | |
a2b148c3 MK |
438 | .SH CONFORMING TO |
439 | This system call is a nonstandard Linux extension. | |
2b8d7f44 | 440 | .SH NOTES |
d2f1788e MK |
441 | No wrapper for this system call is provided in glibc. |
442 | A wrapper is provided in the | |
443 | .IR libkeyutils | |
444 | package. | |
445 | When employing the wrapper in that library, link with | |
446 | .IR \-lkeyutils . | |
a7c31ed8 MK |
447 | .SH EXAMPLE |
448 | The program below demonstrates the use of | |
449 | .BR request_key (). | |
450 | The | |
451 | .IR type , | |
452 | .IR description , | |
453 | and | |
1f39876b | 454 | .IR callout_info |
a7c31ed8 | 455 | arguments for the system call are taken from the values |
1f39876b | 456 | supplied in the command-line arguments. |
a7c31ed8 | 457 | The call specifies the session keyring as the target keyring. |
efeece04 | 458 | .PP |
a7c31ed8 MK |
459 | In order to demonstrate this program, |
460 | we first create a suitable entry in the file | |
461 | .IR /etc/request-key.conf . | |
efeece04 | 462 | .PP |
a7c31ed8 MK |
463 | .in +4n |
464 | .nf | |
465 | $ sudo sh | |
466 | # \fBecho 'create user mtk:* * /bin/keyctl instantiate %k %c %S' \\\fP | |
467 | \fB> /etc/request-keys.conf\fP | |
468 | # \fBexit\fP | |
469 | .fi | |
470 | .in | |
efeece04 | 471 | .PP |
a7c31ed8 MK |
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 | |
474 | .BR keyctl (1) | |
475 | command's | |
476 | .B instantiate | |
477 | operation. | |
a7c31ed8 MK |
478 | The arguments supplied to the |
479 | .B instantiate | |
480 | operation are: | |
481 | the ID of the uninstantiated key | |
482 | .RI ( %k ); | |
483 | the callout data supplied to the | |
484 | .BR request_key () | |
485 | call | |
486 | .RI ( %c ); | |
487 | and the session keyring | |
488 | .RI ( %S ) | |
489 | of the requestor (i.e., the caller of | |
1f39876b | 490 | .BR request_key ()). |
0b617a3a | 491 | See |
a7c31ed8 MK |
492 | .BR request-key.conf (5) |
493 | for details of these | |
494 | .I % | |
0b617a3a | 495 | specifiers. |
efeece04 | 496 | .PP |
a7c31ed8 MK |
497 | Then we run the program and check the contents of |
498 | .IR /proc/keys | |
e38f3925 | 499 | to verify that the requested key has been instantiated: |
efeece04 | 500 | .PP |
a7c31ed8 MK |
501 | .in +4n |
502 | .nf | |
388adc3c | 503 | $ \fB./t_request_key user mtk:key1 "Payload data"\fP |
a7c31ed8 | 504 | $ \fBgrep \(aq2dddaf50\(aq /proc/keys\fP |
1f39876b | 505 | 2dddaf50 I--Q--- 1 perm 3f010000 1000 1000 user mtk:key1: 12 |
a7c31ed8 MK |
506 | .fi |
507 | .in | |
efeece04 | 508 | .PP |
0bbcf59d MK |
509 | For another example of the use of this program, see |
510 | .BR keyctl (2). | |
a7c31ed8 MK |
511 | .SS Program source |
512 | \& | |
e7d0bb47 | 513 | .EX |
388adc3c MK |
514 | /* t_request_key.c */ |
515 | ||
a7c31ed8 MK |
516 | #include <sys/types.h> |
517 | #include <keyutils.h> | |
518 | #include <stdio.h> | |
519 | #include <stdlib.h> | |
520 | #include <string.h> | |
521 | ||
a7c31ed8 MK |
522 | int |
523 | main(int argc, char *argv[]) | |
524 | { | |
525 | key_serial_t key; | |
526 | ||
527 | if (argc != 4) { | |
528 | fprintf(stderr, "Usage: %s type description callout\-data\\n", | |
529 | argv[0]); | |
530 | exit(EXIT_FAILURE); | |
531 | } | |
532 | ||
533 | key = request_key(argv[1], argv[2], argv[3], | |
534 | KEY_SPEC_SESSION_KEYRING); | |
4051799c MK |
535 | if (key == \-1) { |
536 | perror("request_key"); | |
537 | exit(EXIT_FAILURE); | |
538 | } | |
a7c31ed8 MK |
539 | |
540 | printf("Key ID is %lx\\n", (long) key); | |
541 | ||
542 | exit(EXIT_SUCCESS); | |
543 | } | |
e7d0bb47 | 544 | .EE |
6dd17d23 | 545 | .SH SEE ALSO |
46c0179a MK |
546 | .ad l |
547 | .nh | |
6dd17d23 MK |
548 | .BR keyctl (1), |
549 | .BR add_key (2), | |
550 | .BR keyctl (2), | |
86cfb3ca | 551 | .BR keyctl (3), |
32fc2407 | 552 | .BR keyrings (7), |
f6270868 | 553 | .BR keyutils (7), |
05705bba | 554 | .BR capabilities (7), |
46c0179a MK |
555 | .BR persistent\-keyring (7), |
556 | .BR process\-keyring (7), | |
557 | .BR session\-keyring (7), | |
558 | .BR thread\-keyring (7), | |
559 | .BR user\-keyring (7), | |
560 | .BR user\-session\-keyring (7), | |
561 | .BR request\-key (8) | |
efeece04 | 562 | .PP |
fbc46ac4 MK |
563 | The kernel source files |
564 | .IR Documentation/security/keys.txt | |
565 | and | |
46c0179a | 566 | .IR Documentation/security/keys\-request\-key.txt . |