]>
Commit | Line | Data |
---|---|---|
6dd17d23 MK |
1 | .\" Copyright (C) 2006 Red Hat, Inc. All Rights Reserved. |
2 | .\" Written by David Howells (dhowells@redhat.com) | |
3 | .\" | |
23dbdcbe | 4 | .\" %%%LICENSE_START(GPLv2+_SW_ONEPARA) |
6dd17d23 MK |
5 | .\" This program is free software; you can redistribute it and/or |
6 | .\" modify it under the terms of the GNU General Public License | |
7 | .\" as published by the Free Software Foundation; either version | |
8 | .\" 2 of the License, or (at your option) any later version. | |
722b6788 | 9 | .\" %%%LICENSE_END |
6dd17d23 | 10 | .\" |
97986708 | 11 | .TH REQUEST_KEY 2 2016-03-15 Linux "Linux Key Management Calls" |
6dd17d23 | 12 | .SH NAME |
f68512e9 | 13 | request_key \- request a key from the kernel's key management facility |
6dd17d23 MK |
14 | .SH SYNOPSIS |
15 | .nf | |
16 | .B #include <keyutils.h> | |
17 | .sp | |
18 | .BI "key_serial_t request_key(const char *" type ", const char *" description , | |
74819bb2 MK |
19 | .BI " const char *" callout_info , |
20 | .BI " key_serial_t " keyring ");" | |
6030f2d8 | 21 | .fi |
6dd17d23 MK |
22 | .SH DESCRIPTION |
23 | .BR request_key () | |
24 | asks the kernel to find a key of the given | |
25 | .I type | |
26 | that matches the specified | |
27 | .I description | |
28 | and, if successful, to attach it to the nominated | |
29 | .I keyring | |
30 | and to return its serial number. | |
31 | .P | |
32 | .BR request_key () | |
33 | first recursively searches all the keyrings attached to the calling process in | |
34 | the order thread-specific keyring, process-specific keyring and then session | |
35 | keyring for a matching key. | |
36 | .P | |
37 | If | |
38 | .BR request_key () | |
39 | is called from a program invoked by | |
40 | .BR request_key () | |
41 | on behalf of some other process to generate a key, then the keyrings of that | |
42 | other process will be searched next, using that other process's UID, GID, | |
a797afac | 43 | groups, and security context to control access. |
6dd17d23 MK |
44 | .P |
45 | The keys in each keyring searched are checked for a match before any child | |
4175f999 MK |
46 | keyrings are recursed into. |
47 | Only keys that are | |
6dd17d23 MK |
48 | .B searchable |
49 | for the caller may be found, and only | |
50 | .B searchable | |
51 | keyrings may be searched. | |
52 | .P | |
f14ae16e | 53 | If the key is not found, then, if |
6dd17d23 | 54 | .I callout_info |
4175f999 MK |
55 | is set, this function will attempt to look further afield. |
56 | In such a case, the | |
6dd17d23 | 57 | .I callout_info |
7fac88a9 | 58 | is passed to a user-space service such as |
6dd17d23 MK |
59 | .B /sbin/request\-key |
60 | to generate the key. | |
61 | .P | |
62 | If that is unsuccessful also, then an error will be returned, and a temporary | |
63 | negative key will be installed in the nominated | |
64 | .IR keyring . | |
65 | This will expire after a few seconds, but will cause subsequent | |
66 | calls to | |
67 | .BR request_key () | |
68 | to fail until it does. | |
69 | .P | |
70 | The | |
71 | .I keyring | |
72 | serial number may be that of a valid keyring to which the caller has write | |
73 | permission, or it may be a special keyring ID: | |
74 | .TP | |
75 | .B KEY_SPEC_THREAD_KEYRING | |
76 | This specifies the caller's thread-specific keyring. | |
77 | .TP | |
78 | .B KEY_SPEC_PROCESS_KEYRING | |
79 | This specifies the caller's process-specific keyring. | |
80 | .TP | |
81 | .B KEY_SPEC_SESSION_KEYRING | |
82 | This specifies the caller's session-specific keyring. | |
83 | .TP | |
84 | .B KEY_SPEC_USER_KEYRING | |
85 | This specifies the caller's UID-specific keyring. | |
86 | .TP | |
87 | .B KEY_SPEC_USER_SESSION_KEYRING | |
88 | This specifies the caller's UID-session keyring. | |
89 | .P | |
90 | If a key is created, no matter whether it's a valid key or a negative key, it | |
91 | will displace any other key of the same type and description from the | |
92 | destination | |
93 | .IR keyring . | |
6dd17d23 MK |
94 | .SH RETURN VALUE |
95 | On success | |
96 | .BR request_key () | |
97 | returns the serial number of the key it found. | |
5618d632 | 98 | On error, the value \-1 |
6dd17d23 | 99 | will be returned and errno will have been set to an appropriate error. |
6dd17d23 MK |
100 | .SH ERRORS |
101 | .TP | |
27807c32 MK |
102 | .B EACCES |
103 | The keyring wasn't available for modification by the user. | |
104 | .TP | |
105 | .B EINTR | |
bb14af39 MK |
106 | The request was interrupted by a signal; see |
107 | .BR signal (7). | |
27807c32 MK |
108 | .TP |
109 | .B EDQUOT | |
110 | The key quota for this user would be exceeded by creating this key or linking | |
111 | it to the keyring. | |
6dd17d23 MK |
112 | .TP |
113 | .B EKEYEXPIRED | |
114 | An expired key was found, but no replacement could be obtained. | |
115 | .TP | |
6dd17d23 MK |
116 | .B EKEYREJECTED |
117 | The attempt to generate a new key was rejected. | |
118 | .TP | |
27807c32 MK |
119 | .B EKEYREVOKED |
120 | A revoked key was found, but no replacement could be obtained. | |
121 | .TP | |
6dd17d23 MK |
122 | .B ENOMEM |
123 | Insufficient memory to create a key. | |
124 | .TP | |
27807c32 MK |
125 | .B ENOKEY |
126 | No matching key was found. | |
6dd17d23 MK |
127 | .SH LINKING |
128 | Although this is a Linux system call, it is not present in | |
129 | .I libc | |
130 | but can be found rather in | |
131 | .IR libkeyutils . | |
132 | When linking, | |
133 | .B -lkeyutils | |
134 | should be specified to the linker. | |
6dd17d23 MK |
135 | .SH SEE ALSO |
136 | .BR keyctl (1), | |
137 | .BR add_key (2), | |
138 | .BR keyctl (2), | |
86cfb3ca | 139 | .BR keyctl (3), |
32fc2407 | 140 | .BR keyrings (7), |
6dd17d23 | 141 | .BR request-key (8) |