]>
Commit | Line | Data |
---|---|---|
2e2f82fc | 1 | .\" Copyright (C) 2006 Red Hat, Inc. All Rights Reserved. |
7b791539 MK |
2 | .\" Written by David Howells (dhowells@redhat.com) |
3 | .\" and Copyright (C) 2016 Michael Kerrisk <mtk.man-pages@gmail.com> | |
2e2f82fc | 4 | .\" |
e4a74ca8 | 5 | .\" SPDX-License-Identifier: GPL-2.0-or-later |
2e2f82fc | 6 | .\" |
45186a5d | 7 | .TH ADD_KEY 2 2021-08-27 "Linux man-pages (unreleased)" |
2e2f82fc | 8 | .SH NAME |
f68512e9 | 9 | add_key \- add a key to the kernel's key management facility |
1cd19964 AC |
10 | .SH LIBRARY |
11 | Standard C library | |
8fc3b2cf | 12 | .RI ( libc ", " \-lc ) |
2e2f82fc MK |
13 | .SH SYNOPSIS |
14 | .nf | |
15 | .B #include <keyutils.h> | |
46661ad9 | 16 | .PP |
2e2f82fc | 17 | .BI "key_serial_t add_key(const char *" type ", const char *" description , |
be464b55 MK |
18 | .BI " const void *" payload ", size_t " plen , |
19 | .BI " key_serial_t " keyring ");" | |
6030f2d8 | 20 | .fi |
46661ad9 | 21 | .PP |
632d1152 GC |
22 | .IR Note : |
23 | There is no glibc wrapper for this system call; see NOTES. | |
2e2f82fc MK |
24 | .SH DESCRIPTION |
25 | .BR add_key () | |
6430ef0a | 26 | creates or updates a key of the given |
2e2f82fc MK |
27 | .I type |
28 | and | |
29 | .IR description , | |
6430ef0a | 30 | instantiates it with the |
2e2f82fc MK |
31 | .I payload |
32 | of length | |
33 | .IR plen , | |
6430ef0a MK |
34 | attaches it to the nominated |
35 | .IR keyring , | |
d38d7053 | 36 | and returns the key's serial number. |
11ac5b51 | 37 | .PP |
89bcd517 ES |
38 | The key may be rejected if the provided data is in the wrong format or |
39 | it is invalid in some other way. | |
11ac5b51 | 40 | .PP |
2e2f82fc MK |
41 | If the destination |
42 | .I keyring | |
43 | already contains a key that matches the specified | |
1ae6b2c7 | 44 | .I type |
6430ef0a MK |
45 | and |
46 | .IR description , | |
fbed92d3 | 47 | then, if the key type supports it, |
0978f706 MK |
48 | .\" FIXME The aforementioned phrases begs the question: |
49 | .\" which key types support this? | |
fbed92d3 MK |
50 | that key will be updated rather than a new key being created; |
51 | if not, a new key (with a different ID) will be created | |
52 | and it will displace the link to the extant key from the keyring. | |
57850834 | 53 | .\" FIXME Perhaps elaborate the implications here? Namely, the new |
f5e0c167 | 54 | .\" key will have a new ID, and if the old key was a keyring that |
cf759ef9 | 55 | .\" is consequently unlinked, then keys that it was anchoring |
0978f706 MK |
56 | .\" will have their reference count decreased by one (and may |
57 | .\" consequently be garbage collected). Is this all correct? | |
11ac5b51 | 58 | .PP |
2e2f82fc MK |
59 | The destination |
60 | .I keyring | |
6430ef0a MK |
61 | serial number may be that of a valid keyring for which the caller has |
62 | .I write | |
1d452eec MK |
63 | permission. |
64 | Alternatively, it may be one of the following special keyring IDs: | |
0978f706 | 65 | .\" FIXME . Perhaps have a separate page describing special keyring IDs? |
2e2f82fc MK |
66 | .TP |
67 | .B KEY_SPEC_THREAD_KEYRING | |
632acae1 | 68 | This specifies the caller's thread-specific keyring |
cd415e73 | 69 | .RB ( thread\-keyring (7)). |
2e2f82fc MK |
70 | .TP |
71 | .B KEY_SPEC_PROCESS_KEYRING | |
632acae1 | 72 | This specifies the caller's process-specific keyring |
cd415e73 | 73 | .RB ( process\-keyring (7)). |
2e2f82fc MK |
74 | .TP |
75 | .B KEY_SPEC_SESSION_KEYRING | |
632acae1 | 76 | This specifies the caller's session-specific keyring |
cd415e73 | 77 | .RB ( session\-keyring (7)). |
2e2f82fc MK |
78 | .TP |
79 | .B KEY_SPEC_USER_KEYRING | |
632acae1 | 80 | This specifies the caller's UID-specific keyring |
cd415e73 | 81 | .RB ( user\-keyring (7)). |
2e2f82fc MK |
82 | .TP |
83 | .B KEY_SPEC_USER_SESSION_KEYRING | |
632acae1 | 84 | This specifies the caller's UID-session keyring |
cd415e73 | 85 | .RB ( user\-session\-keyring (7)). |
6430ef0a | 86 | .SS Key types |
047d68b7 MK |
87 | The key |
88 | .I type | |
89 | is a string that specifies the key's type. | |
90 | Internally, the kernel defines a number of key types that are | |
91 | available in the core key management code. | |
39709e8a | 92 | Among the types that are available for user-space use |
047d68b7 MK |
93 | and can be specified as the |
94 | .I type | |
95 | argument to | |
39709e8a MK |
96 | .BR add_key () |
97 | are the following: | |
2e2f82fc | 98 | .TP |
59c3c2df | 99 | .I """keyring""" |
2e2f82fc | 100 | Keyrings are special key types that may contain links to sequences of other |
4175f999 | 101 | keys of any type. |
1d452eec | 102 | If this interface is used to create a keyring, then |
2e2f82fc | 103 | .I payload |
1d452eec | 104 | should be NULL and |
2e2f82fc MK |
105 | .I plen |
106 | should be zero. | |
2c0a219b | 107 | .TP |
1ae6b2c7 | 108 | .I """user""" |
eebdcb80 MK |
109 | This is a general purpose key type whose payload may be read and updated |
110 | by user-space applications. | |
111 | The key is kept entirely within kernel memory. | |
112 | The payload for keys of this type is a blob of arbitrary data | |
113 | of up to 32,767 bytes. | |
114 | .TP | |
2c0a219b MK |
115 | .IR """logon""" " (since Linux 3.3)" |
116 | .\" commit 9f6ed2ca257fa8650b876377833e6f14e272848b | |
117 | This key type is essentially the same as | |
118 | .IR """user""" , | |
1d452eec | 119 | but it does not permit the key to read. |
39709e8a | 120 | This is suitable for storing payloads |
2c0a219b | 121 | that you do not want to be readable from user space. |
46661ad9 | 122 | .PP |
39709e8a | 123 | This key type vets the |
2c0a219b MK |
124 | .I description |
125 | to ensure that it is qualified by a "service" prefix, | |
126 | by checking to ensure that the | |
127 | .I description | |
128 | contains a ':' that is preceded by other characters. | |
bcf73370 MK |
129 | .TP |
130 | .IR """big_key""" " (since Linux 3.13)" | |
131 | .\" commit ab3c3587f8cda9083209a61dbe3a4407d3cada10 | |
132 | This key type is similar to | |
133 | .IR """user""" , | |
c4b7e5ac | 134 | but may hold a payload of up to 1\ MiB. |
94dd02f4 | 135 | If the key payload is large enough, |
1d452eec MK |
136 | then it may be stored encrypted in tmpfs |
137 | (which can be swapped out) rather than kernel memory. | |
39709e8a MK |
138 | .PP |
139 | For further details on these key types, see | |
140 | .BR keyrings (7). | |
2e2f82fc | 141 | .SH RETURN VALUE |
6430ef0a | 142 | On success, |
2e2f82fc MK |
143 | .BR add_key () |
144 | returns the serial number of the key it created or updated. | |
6430ef0a MK |
145 | On error, \-1 is returned and |
146 | .I errno | |
855d489a | 147 | is set to indicate the error. |
2e2f82fc MK |
148 | .SH ERRORS |
149 | .TP | |
b801426a MK |
150 | .B EACCES |
151 | The keyring wasn't available for modification by the user. | |
152 | .TP | |
d5e2b2c9 MK |
153 | .B EDQUOT |
154 | The key quota for this user would be exceeded by creating this key or linking | |
155 | it to the keyring. | |
156 | .TP | |
c99809b9 | 157 | .B EFAULT |
924ebcde MK |
158 | One or more of |
159 | .IR type , | |
160 | .IR description , | |
161 | and | |
162 | .I payload | |
163 | points outside process's accessible address space. | |
c99809b9 | 164 | .TP |
b801426a | 165 | .B EINVAL |
71d4559c MK |
166 | The size of the string (including the terminating null byte) specified in |
167 | .I type | |
168 | or | |
169 | .I description | |
170 | exceeded the limit (32 bytes and 4096 bytes respectively). | |
171 | .TP | |
172 | .B EINVAL | |
b801426a | 173 | The payload data was invalid. |
2e2f82fc | 174 | .TP |
2c0a219b | 175 | .B EINVAL |
1ae6b2c7 | 176 | .I type |
2c0a219b | 177 | was |
1ae6b2c7 | 178 | .I """logon""" |
2c0a219b MK |
179 | and the |
180 | .I description | |
181 | was not qualified with a prefix string of the form | |
182 | .IR """service:""" . | |
183 | .TP | |
2e2f82fc MK |
184 | .B EKEYEXPIRED |
185 | The keyring has expired. | |
186 | .TP | |
187 | .B EKEYREVOKED | |
188 | The keyring has been revoked. | |
189 | .TP | |
b801426a MK |
190 | .B ENOKEY |
191 | The keyring doesn't exist. | |
2e2f82fc MK |
192 | .TP |
193 | .B ENOMEM | |
194 | Insufficient memory to create a key. | |
62975dc2 ES |
195 | .TP |
196 | .B EPERM | |
197 | The | |
198 | .I type | |
924ebcde | 199 | started with a period (\(aq.\(aq). |
b67331f9 | 200 | Key types that begin with a period are reserved to the implementation. |
62975dc2 ES |
201 | .TP |
202 | .B EPERM | |
203 | .I type | |
204 | was | |
205 | .I """keyring""" | |
206 | and the | |
207 | .I description | |
924ebcde | 208 | started with a period (\(aq.\(aq). |
b67331f9 MK |
209 | Keyrings with descriptions (names) |
210 | that begin with a period are reserved to the implementation. | |
92624b07 | 211 | .SH VERSIONS |
5685b18c | 212 | This system call first appeared in Linux 2.6.10. |
3113c7f3 | 213 | .SH STANDARDS |
92624b07 | 214 | This system call is a nonstandard Linux extension. |
be2d8882 | 215 | .SH NOTES |
16cc03ca | 216 | Glibc does not provide a wrapper for this system call. |
59d15a1c | 217 | A wrapper is provided in the |
1ae6b2c7 | 218 | .I libkeyutils |
7127973e MK |
219 | library. |
220 | (The accompanying package provides the | |
221 | .I <keyutils.h> | |
222 | header file.) | |
59d15a1c MK |
223 | When employing the wrapper in that library, link with |
224 | .IR \-lkeyutils . | |
a14af333 | 225 | .SH EXAMPLES |
7b791539 MK |
226 | The program below creates a key with the type, description, and payload |
227 | specified in its command-line arguments, | |
228 | and links that key into the session keyring. | |
229 | The following shell session demonstrates the use of the program: | |
46661ad9 | 230 | .PP |
7b791539 | 231 | .in +4n |
46661ad9 | 232 | .EX |
7b791539 MK |
233 | $ \fB./a.out user mykey "Some payload"\fP |
234 | Key ID is 64a4dca | |
235 | $ \fBgrep \(aq64a4dca\(aq /proc/keys\fP | |
d064d41a | 236 | 064a4dca I\-\-Q\-\-\- 1 perm 3f010000 1000 1000 user mykey: 12 |
46661ad9 | 237 | .EE |
7b791539 MK |
238 | .in |
239 | .SS Program source | |
240 | \& | |
33857069 | 241 | .\" SRC BEGIN (add_key.c) |
46661ad9 | 242 | .EX |
7b791539 | 243 | #include <keyutils.h> |
8eb90116 | 244 | #include <stdint.h> |
7b791539 MK |
245 | #include <stdio.h> |
246 | #include <stdlib.h> | |
247 | #include <string.h> | |
248 | ||
7b791539 MK |
249 | int |
250 | main(int argc, char *argv[]) | |
251 | { | |
252 | key_serial_t key; | |
253 | ||
254 | if (argc != 4) { | |
d1a71985 | 255 | fprintf(stderr, "Usage: %s type description payload\en", |
7b791539 MK |
256 | argv[0]); |
257 | exit(EXIT_FAILURE); | |
258 | } | |
259 | ||
260 | key = add_key(argv[1], argv[2], argv[3], strlen(argv[3]), | |
4687ab0e | 261 | KEY_SPEC_SESSION_KEYRING); |
6052344b MK |
262 | if (key == \-1) { |
263 | perror("add_key"); | |
264 | exit(EXIT_FAILURE); | |
265 | } | |
7b791539 | 266 | |
8eb90116 | 267 | printf("Key ID is %jx\en", (uintmax_t) key); |
7b791539 MK |
268 | |
269 | exit(EXIT_SUCCESS); | |
270 | } | |
46661ad9 | 271 | .EE |
33857069 | 272 | .\" SRC END |
2e2f82fc | 273 | .SH SEE ALSO |
46c0179a MK |
274 | .ad l |
275 | .nh | |
2e2f82fc MK |
276 | .BR keyctl (1), |
277 | .BR keyctl (2), | |
32fc2407 | 278 | .BR request_key (2), |
86cfb3ca | 279 | .BR keyctl (3), |
bd73f2bf | 280 | .BR keyrings (7), |
d64b3725 | 281 | .BR keyutils (7), |
46c0179a MK |
282 | .BR persistent\-keyring (7), |
283 | .BR process\-keyring (7), | |
284 | .BR session\-keyring (7), | |
285 | .BR thread\-keyring (7), | |
286 | .BR user\-keyring (7), | |
287 | .BR user\-session\-keyring (7) | |
46661ad9 | 288 | .PP |
22961867 | 289 | The kernel source files |
1ae6b2c7 | 290 | .I Documentation/security/keys/core.rst |
db8074da | 291 | and |
1ae6b2c7 | 292 | .I Documentation/keys/request\-key.rst |
db8074da ES |
293 | (or, before Linux 4.13, in the files |
294 | .\" commit b68101a1e8f0263dbc7b8375d2a7c57c6216fb76 | |
1ae6b2c7 | 295 | .I Documentation/security/keys.txt |
22961867 | 296 | and |
db8074da ES |
297 | .\" commit 3db38ed76890565772fcca3279cc8d454ea6176b |
298 | .IR Documentation/security/keys\-request\-key.txt ). |