]>
Commit | Line | Data |
---|---|---|
57ce8d0f MK |
1 | .\" Copyright (C) 2016 Michael Kerrisk <mtk.manpages@gmail.com> |
2 | .\" and Copyright (C) 2016 Eugene Syromyatnikov <evgsyr@gmail.com> | |
3 | .\" A very few fragments remain from an earlier version of this page | |
4 | .\" written by David Howells (dhowells@redhat.com) | |
4509c62e | 5 | .\" |
e56eefd6 MK |
6 | .\" %%%LICENSE_START(VERBATIM) |
7 | .\" Permission is granted to make and distribute verbatim copies of this | |
8 | .\" manual provided the copyright notice and this permission notice are | |
9 | .\" preserved on all copies. | |
10 | .\" | |
11 | .\" Permission is granted to copy and distribute modified versions of this | |
12 | .\" manual under the conditions for verbatim copying, provided that the | |
13 | .\" entire resulting derived work is distributed under the terms of a | |
14 | .\" permission notice identical to this one. | |
15 | .\" | |
16 | .\" Since the Linux kernel and libraries are constantly changing, this | |
17 | .\" manual page may be incorrect or out-of-date. The author(s) assume no | |
18 | .\" responsibility for errors or omissions, or for damages resulting from | |
19 | .\" the use of the information contained herein. The author(s) may not | |
20 | .\" have taken the same level of care in the production of this manual, | |
21 | .\" which is licensed free of charge, as they might when working | |
22 | .\" professionally. | |
23 | .\" | |
24 | .\" Formatted or processed versions of this manual, if unaccompanied by | |
25 | .\" the source, must acknowledge the copyright and authors of this work. | |
722b6788 | 26 | .\" %%%LICENSE_END |
4509c62e | 27 | .\" |
a02cbc78 | 28 | .mso www.tmac |
31a1b45e | 29 | .TH KEYCTL 2 2017-03-13 Linux "Linux Key Management Calls" |
4509c62e | 30 | .SH NAME |
f68512e9 | 31 | keyctl \- manipulate the kernel's key management facility |
4509c62e MK |
32 | .SH SYNOPSIS |
33 | .nf | |
e02acf2f | 34 | .B #include <sys/types.h> |
4509c62e | 35 | .B #include <keyutils.h> |
68e4db0a | 36 | .PP |
53e88c3e | 37 | .BI "long keyctl(int " operation ", ...)" |
f90f031e | 38 | |
60fc9e95 | 39 | .B "/* For direct call via syscall(2): */" |
fa76da80 ES |
40 | .B #include <asm/unistd.h> |
41 | .B #include <linux/keyctl.h> | |
42 | .B #include <unistd.h> | |
68e4db0a | 43 | .PP |
53e88c3e | 44 | .BI "long syscall(__NR_keyctl, int " operation ", __kernel_ulong_t " arg2 , |
9a9febc8 MK |
45 | .BI " __kernel_ulong_t " arg3 ", __kernel_ulong_t " arg4 , |
46 | .BI " __kernel_ulong_t " arg5 ); | |
6030f2d8 | 47 | .fi |
dbfe9c70 | 48 | .PP |
be428596 | 49 | No glibc wrapper is provided for this system call; see NOTES. |
4509c62e MK |
50 | .SH DESCRIPTION |
51 | .BR keyctl () | |
60fc9e95 | 52 | allows user-space programs to perform key manipulation. |
efeece04 | 53 | .PP |
60fc9e95 | 54 | The operation performed by |
fa76da80 | 55 | .BR keyctl () |
60fc9e95 | 56 | is determined by the value of the |
53e88c3e | 57 | .I operation |
60fc9e95 | 58 | argument. |
a76439c9 | 59 | Each of these operations is wrapped by the |
a1269389 | 60 | .I libkeyutils |
a76439c9 MK |
61 | library (provided by the |
62 | .I keyutils | |
63 | package) into individual functions (noted below) | |
60fc9e95 | 64 | to permit the compiler to check types. |
efeece04 | 65 | .PP |
60fc9e95 | 66 | The permitted values for |
53e88c3e | 67 | .I operation |
60fc9e95 | 68 | are: |
4509c62e | 69 | .TP |
5685b18c | 70 | .BR KEYCTL_GET_KEYRING_ID " (since Linux 2.6.10)" |
d6c7244f | 71 | Map a special key ID to a real key ID for this process. |
efeece04 | 72 | .IP |
d6c7244f | 73 | This operation looks up the special key whose ID is provided in |
fa76da80 | 74 | .I arg2 |
fd2d68f9 | 75 | (cast to |
79319a25 MK |
76 | .IR key_serial_t ). |
77 | If the special key is found, | |
78 | the ID of the corresponding real key is returned as the function result. | |
63eab5d8 MK |
79 | The following values may be specified in |
80 | .IR arg2 : | |
81 | .RS | |
82 | .TP | |
83 | .B KEY_SPEC_THREAD_KEYRING | |
303ec07a | 84 | This specifies the calling thread's thread-specific keyring. |
63eab5d8 | 85 | See |
9879bf30 | 86 | .BR thread-keyring (7). |
63eab5d8 MK |
87 | .TP |
88 | .B KEY_SPEC_PROCESS_KEYRING | |
303ec07a | 89 | This specifies the caller's process-specific keyring. |
63eab5d8 | 90 | See |
9879bf30 | 91 | .BR process-keyring (7). |
63eab5d8 MK |
92 | .TP |
93 | .B KEY_SPEC_SESSION_KEYRING | |
303ec07a | 94 | This specifies the caller's session-specific keyring. |
63eab5d8 | 95 | See |
9879bf30 | 96 | .BR session-keyring (7). |
63eab5d8 MK |
97 | .TP |
98 | .B KEY_SPEC_USER_KEYRING | |
303ec07a | 99 | This specifies the caller's UID-specific keyring. |
63eab5d8 | 100 | See |
9879bf30 | 101 | .BR user-keyring (7). |
63eab5d8 MK |
102 | .TP |
103 | .B KEY_SPEC_USER_SESSION_KEYRING | |
303ec07a | 104 | This specifies the caller's UID-session keyring. |
63eab5d8 | 105 | See |
9879bf30 | 106 | .BR user-session-keyring (7). |
303ec07a MK |
107 | .TP |
108 | .BR KEY_SPEC_REQKEY_AUTH_KEY " (since Linux 2.6.16)" | |
109 | .\" commit b5f545c880a2a47947ba2118b2509644ab7a2969 | |
110 | This specifies the authorization key created by | |
111 | .BR request_key (2) | |
112 | and passed to the process it spawns to generate a key. | |
38590ae0 MK |
113 | This key is available only in a |
114 | .BR request-key (8)-style | |
115 | program that was passed an authorization key by the kernel and | |
116 | ceases to be available once the requested key has been instantiated; see | |
117 | .BR request_key (2). | |
303ec07a MK |
118 | .TP |
119 | .BR KEY_SPEC_REQUESTOR_KEYRING " (since Linux 2.6.29)" | |
120 | .\" commit 8bbf4976b59fc9fc2861e79cab7beb3f6d647640 | |
121 | This specifies the key ID for the | |
122 | .BR request_key (2) | |
123 | destination keyring. | |
38590ae0 MK |
124 | This keyring is available only in a |
125 | .BR request-key (8)-style | |
126 | program that was passed an authorization key by the kernel and | |
127 | ceases to be available once the requested key has been instantiated; see | |
128 | .BR request_key (2). | |
63eab5d8 MK |
129 | .RE |
130 | .IP | |
29708373 | 131 | The behavior if the key specified in |
d6c7244f | 132 | .I arg2 |
29708373 | 133 | does not exist depends on the value of |
fa76da80 | 134 | .I arg3 |
29708373 MK |
135 | (cast to |
136 | .IR int ). | |
137 | If | |
138 | .I arg3 | |
139 | contains a non-zero value, then\(emif it is appropriate to do so | |
f0fb21d1 MK |
140 | (e.g., when looking up the user, user-session, or session key)\(ema new key |
141 | is created and its real key ID returned as the function result. | |
b74b20aa MK |
142 | .\" The keyctl_get_keyring_ID.3 page says that a new key |
143 | .\" "will be created *if it is appropriate to do so**. What is the | |
144 | .\" determiner for appropriate? | |
2329c6d0 MK |
145 | .\" David Howells: Some special keys such as KEY_SPEC_REQKEY_AUTH_KEY |
146 | .\" wouldn't get created but user/user-session/session keyring would | |
147 | .\" be created. | |
29708373 MK |
148 | Otherwise, the operation fails with the error |
149 | .BR ENOKEY . | |
efeece04 | 150 | .IP |
29708373 MK |
151 | If a valid key ID is specified in |
152 | .IR arg2 , | |
153 | and the key exists, then this operation simply returns the key ID. | |
154 | If the key does not exist, the call fails with error | |
155 | .BR ENOKEY . | |
efeece04 | 156 | .IP |
60fc9e95 | 157 | The caller must have |
fa76da80 | 158 | .I search |
60fc9e95 | 159 | permission on a keyring in order for it to be found. |
efeece04 | 160 | .IP |
60fc9e95 MK |
161 | The arguments |
162 | .IR arg4 | |
163 | and | |
164 | .IR arg5 | |
fa76da80 | 165 | are ignored. |
efeece04 | 166 | .IP |
d6c7244f MK |
167 | This operation is exposed by |
168 | .I libkeyutils | |
169 | via the function | |
170 | .BR keyctl_get_keyring_ID (3). | |
4509c62e | 171 | .TP |
5685b18c | 172 | .BR KEYCTL_JOIN_SESSION_KEYRING " (since Linux 2.6.10)" |
f9fa5a66 MK |
173 | Replace the session keyring this process subscribes to with |
174 | a new session keyring. | |
2329c6d0 MK |
175 | .\" This may be useful in conjunction with some sort of |
176 | .\" session management framework that is employed by the application. | |
efeece04 | 177 | .IP |
f9fa5a66 | 178 | If |
fa76da80 | 179 | .I arg2 |
f9fa5a66 MK |
180 | is NULL, |
181 | an anonymous keyring with the description "_ses" is created | |
182 | and the process is subscribed to that keyring as its session keyring, | |
183 | displacing the previous session keyring. | |
efeece04 | 184 | .IP |
f9fa5a66 MK |
185 | Otherwise, |
186 | .I arg2 | |
fd2d68f9 | 187 | (cast to |
f9fa5a66 MK |
188 | .IR "char\ *" ) |
189 | is treated as the description (name) of a keyring, | |
190 | and the behavior is as follows: | |
191 | .RS | |
192 | .IP * 3 | |
193 | If a keyring with a matching description exists, | |
4e9afdfc MK |
194 | the process will attempt to subscribe to that keyring |
195 | as its session keyring if possible; | |
f9fa5a66 | 196 | if that is not possible, an error is returned. |
f9fa5a66 MK |
197 | In order to subscribe to the keyring, |
198 | the caller must have | |
fa76da80 | 199 | .I search |
f9fa5a66 MK |
200 | permission on the keyring. |
201 | .IP * | |
202 | If a keyring with a matching description does not exist, | |
4e9afdfc MK |
203 | then a new keyring with the specified description is created, |
204 | and the process is subscribed to that keyring as its session keyring. | |
f9fa5a66 MK |
205 | .RE |
206 | .IP | |
60fc9e95 MK |
207 | The arguments |
208 | .IR arg3 , | |
209 | .IR arg4 , | |
210 | and | |
211 | .IR arg5 | |
fa76da80 | 212 | are ignored. |
efeece04 | 213 | .IP |
f9fa5a66 MK |
214 | This operation is exposed by |
215 | .I libkeyutils | |
216 | via the function | |
217 | .BR keyctl_join_session_keyring (3). | |
4509c62e | 218 | .TP |
5685b18c | 219 | .BR KEYCTL_UPDATE " (since Linux 2.6.10)" |
60fc9e95 | 220 | Update a key's data payload. |
efeece04 | 221 | .IP |
461a8ce5 | 222 | The |
fa76da80 | 223 | .I arg2 |
fd2d68f9 | 224 | argument (cast to |
fa76da80 | 225 | .IR key_serial_t ) |
581f8203 | 226 | specifies the ID of the key to be updated. |
60fc9e95 | 227 | The |
fa76da80 | 228 | .I arg3 |
fd2d68f9 | 229 | argument (cast to |
581f8203 MK |
230 | .IR "void\ *" ) |
231 | points to the new payload and | |
fa76da80 | 232 | .I arg4 |
fd2d68f9 | 233 | (cast to |
fa76da80 | 234 | .IR size_t ) |
581f8203 | 235 | contains the new payload size in bytes. |
efeece04 | 236 | .IP |
60fc9e95 | 237 | The caller must have |
fa76da80 | 238 | .I write |
60fc9e95 | 239 | permission on the key specified and the key type must support updating. |
efeece04 | 240 | .IP |
1ac6bb73 MK |
241 | A negatively instantiated key (see the description of |
242 | .BR KEYCTL_REJECT ) | |
243 | can be positively instantiated with this operation. | |
efeece04 | 244 | .IP |
461a8ce5 | 245 | The |
fa76da80 ES |
246 | .I arg5 |
247 | argument is ignored. | |
efeece04 | 248 | .IP |
581f8203 MK |
249 | This operation is exposed by |
250 | .I libkeyutils | |
251 | via the function | |
252 | .BR keyctl_update (3). | |
4509c62e | 253 | .TP |
5685b18c | 254 | .BR KEYCTL_REVOKE " (since Linux 2.6.10)" |
60fc9e95 | 255 | Revoke the key with the ID provided in |
fa76da80 | 256 | .I arg2 |
fd2d68f9 | 257 | (cast to |
fa76da80 | 258 | .IR key_serial_t ). |
7b4861d9 MK |
259 | The key is scheduled for garbage collection; |
260 | it will no longer be findable, | |
261 | and will be unavailable for further operations. | |
5c1cb825 MK |
262 | Further attempts to use the key will fail with the error |
263 | .BR EKEYREVOKED . | |
efeece04 | 264 | .IP |
60fc9e95 | 265 | The caller must have |
cbf0e35e MK |
266 | .IR write |
267 | or | |
268 | .IR setattr | |
269 | permission on the key. | |
2329c6d0 | 270 | .\" Keys with the KEY_FLAG_KEEP bit set cause an EPERM |
1fe70a67 | 271 | .\" error for KEYCTL_REVOKE. Does this need to be documented? |
2329c6d0 | 272 | .\" David Howells: No significance for user space. |
efeece04 | 273 | .IP |
60fc9e95 MK |
274 | The arguments |
275 | .IR arg3 , | |
276 | .IR arg4 , | |
277 | and | |
278 | .IR arg5 | |
fa76da80 | 279 | are ignored. |
efeece04 | 280 | .IP |
cbf0e35e MK |
281 | This operation is exposed by |
282 | .I libkeyutils | |
283 | via the function | |
284 | .BR keyctl_revoke (3). | |
4509c62e | 285 | .TP |
5685b18c | 286 | .BR KEYCTL_CHOWN " (since Linux 2.6.10)" |
14694cb5 | 287 | Change the ownership (user and group ID) of a key. |
efeece04 | 288 | .IP |
461a8ce5 | 289 | The |
fa76da80 | 290 | .I arg2 |
fd2d68f9 | 291 | argument (cast to |
fa76da80 | 292 | .IR key_serial_t ) |
60fc9e95 MK |
293 | contains the key ID. |
294 | The | |
fa76da80 | 295 | .I arg3 |
fd2d68f9 | 296 | argument (cast to |
fa76da80 | 297 | .IR uid_t ) |
60fc9e95 MK |
298 | contains the new user ID (or \-1 in case the user ID shouldn't be changed). |
299 | The | |
fa76da80 | 300 | .I arg4 |
fd2d68f9 | 301 | argument (cast to |
fa76da80 | 302 | .IR gid_t ) |
60fc9e95 | 303 | contains the new group ID (or \-1 in case the group ID shouldn't be changed). |
efeece04 | 304 | .IP |
fa76da80 ES |
305 | The key must grant the caller |
306 | .I setattr | |
461a8ce5 | 307 | permission. |
efeece04 | 308 | .IP |
461a8ce5 | 309 | For the UID to be changed, or for the GID to be changed to a group |
60fc9e95 MK |
310 | the caller is not a member of, the caller must have the |
311 | .B CAP_SYS_ADMIN | |
fa76da80 | 312 | capability (see |
60fc9e95 | 313 | .BR capabilities (7)). |
efeece04 | 314 | .IP |
461a8ce5 MK |
315 | If the UID is to be changed, the new user must have sufficient |
316 | quota to accept the key. | |
317 | The quota deduction will be removed from the old user | |
14694cb5 | 318 | to the new user should the UID be changed. |
efeece04 | 319 | .IP |
461a8ce5 | 320 | The |
fa76da80 ES |
321 | .I arg5 |
322 | argument is ignored. | |
efeece04 | 323 | .IP |
efd4c0cd MK |
324 | This operation is exposed by |
325 | .I libkeyutils | |
326 | via the function | |
327 | .BR keyctl_chown (3). | |
4509c62e | 328 | .TP |
5685b18c | 329 | .BR KEYCTL_SETPERM " (since Linux 2.6.10)" |
60fc9e95 | 330 | Change the permissions of the key with the ID provided in the |
fa76da80 | 331 | .I arg2 |
fd2d68f9 | 332 | argument (cast to |
fa76da80 | 333 | .IR key_serial_t ) |
60fc9e95 | 334 | to the permissions provided in the |
fa76da80 | 335 | .I arg3 |
fd2d68f9 | 336 | argument (cast to |
3d20acc9 | 337 | .IR key_perm_t ). |
efeece04 | 338 | .IP |
3d20acc9 | 339 | If the caller doesn't have the |
60fc9e95 MK |
340 | .B CAP_SYS_ADMIN |
341 | capability, it can change permissions only for the keys it owns. | |
3d20acc9 | 342 | (More precisely: the caller's filesystem UID must match the UID of the key.) |
efeece04 | 343 | .IP |
6e810113 MK |
344 | The key must grant |
345 | .I setattr | |
346 | permission to the caller | |
347 | .IR regardless | |
348 | of the caller's capabilities. | |
349 | .\" FIXME Above, is it really intended that a privileged process can't | |
350 | .\" override the lack of the 'setattr' permission? | |
efeece04 | 351 | .IP |
3d20acc9 MK |
352 | The permissions in |
353 | .IR arg3 | |
354 | specify masks of available operations | |
355 | for each of the following user categories: | |
356 | .RS | |
357 | .TP | |
358 | .IR possessor " (since Linux 2.6.14)" | |
359 | .\" commit 664cceb0093b755739e56572b836a99104ee8a75 | |
360 | This is the permission granted to a process that possesses the key | |
361 | (has it attached searchably to one of the process's keyrings); | |
362 | see | |
363 | .BR keyrings (7). | |
364 | .TP | |
365 | .IR user | |
366 | This is the permission granted to a process | |
367 | whose filesystem UID matches the UID of the key. | |
368 | .TP | |
369 | .IR group | |
370 | This is the permission granted to a process | |
371 | whose filesystem GID or any of its supplementary GIDs | |
372 | matches the GID of the key. | |
373 | .TP | |
374 | .IR other | |
375 | This is the permission granted to other processes | |
376 | that do not match the | |
377 | .IR user | |
378 | and | |
379 | .IR group | |
380 | categories. | |
381 | .RE | |
382 | .IP | |
383 | The | |
384 | .IR user , | |
385 | .IR group , | |
386 | and | |
387 | .IR other | |
388 | categories are exclusive: if a process matches the | |
389 | .IR user | |
390 | category, it will not receive permissions granted in the | |
391 | .IR group | |
392 | category; if a process matches the | |
393 | .I user | |
394 | or | |
395 | .IR group | |
396 | category, then it will not receive permissions granted in the | |
397 | .IR other | |
398 | category. | |
efeece04 | 399 | .IP |
3d20acc9 | 400 | The |
afa27faa | 401 | .I possessor |
3d20acc9 MK |
402 | category grants permissions that are cumulative with the grants from the |
403 | .IR user , | |
404 | .IR group , | |
405 | or | |
406 | .IR other | |
407 | category. | |
efeece04 | 408 | .IP |
3d20acc9 MK |
409 | Each permission mask is eight bits in size, |
410 | with only six bits currently used. | |
461a8ce5 | 411 | The available permissions are: |
fa76da80 | 412 | .RS |
3d20acc9 MK |
413 | .TP |
414 | .IR view | |
415 | This permission allows reading attributes of a key. | |
efeece04 | 416 | .IP |
3d20acc9 MK |
417 | This permission is required for the |
418 | .BR KEYCTL_DESCRIBE | |
419 | operation. | |
efeece04 | 420 | .IP |
3d20acc9 MK |
421 | The permission bits for each category are |
422 | .BR KEY_POS_VIEW , | |
423 | .BR KEY_USR_VIEW , | |
424 | .BR KEY_GRP_VIEW , | |
425 | and | |
426 | .BR KEY_OTH_VIEW . | |
427 | .TP | |
428 | .IR read | |
429 | This permission allows reading a key's payload. | |
efeece04 | 430 | .IP |
3d20acc9 MK |
431 | This permission is required for the |
432 | .BR KEYCTL_READ | |
433 | operation. | |
efeece04 | 434 | .IP |
3d20acc9 MK |
435 | The permission bits for each category are |
436 | .BR KEY_POS_READ , | |
437 | .BR KEY_USR_READ , | |
438 | .BR KEY_GRP_READ , | |
439 | and | |
440 | .BR KEY_OTH_READ . | |
441 | .TP | |
442 | .IR write | |
443 | This permission allows update or instantiation of a key's payload. | |
444 | For a keyring, it allows keys to be linked and unlinked from the keyring, | |
efeece04 | 445 | .IP |
3d20acc9 | 446 | This permission is required for the |
60fc9e95 MK |
447 | .BR KEYCTL_UPDATE , |
448 | .BR KEYCTL_REVOKE , | |
449 | .BR KEYCTL_CLEAR , | |
450 | .BR KEYCTL_LINK , | |
451 | and | |
3d20acc9 MK |
452 | .BR KEYCTL_UNLINK |
453 | operations. | |
efeece04 | 454 | .IP |
3d20acc9 MK |
455 | The permission bits for each category are |
456 | .BR KEY_POS_WRITE , | |
457 | .BR KEY_USR_WRITE , | |
458 | .BR KEY_GRP_WRITE , | |
459 | and | |
460 | .BR KEY_OTH_WRITE . | |
461 | .TP | |
462 | .IR search | |
463 | This permission allows keyrings to be searched and keys to be found. | |
a76439c9 MK |
464 | Searches can recurse only into nested keyrings that have |
465 | .I search | |
466 | permission set. | |
efeece04 | 467 | .IP |
3d20acc9 | 468 | This permission is required for the |
60fc9e95 MK |
469 | .BR KEYCTL_GET_KEYRING_ID , |
470 | .BR KEYCTL_JOIN_SESSION_KEYRING , | |
471 | .BR KEYCTL_SEARCH , | |
472 | and | |
3d20acc9 MK |
473 | .BR KEYCTL_INVALIDATE |
474 | operations. | |
efeece04 | 475 | .IP |
3d20acc9 MK |
476 | The permission bits for each category are |
477 | .BR KEY_POS_SEARCH , | |
478 | .BR KEY_USR_SEARCH , | |
479 | .BR KEY_GRP_SEARCH , | |
480 | and | |
481 | .BR KEY_OTH_SEARCH . | |
482 | .TP | |
483 | .IR link | |
484 | This permission allows a key or keyring to be linked to. | |
efeece04 | 485 | .IP |
3d20acc9 | 486 | This permission is required for the |
60fc9e95 MK |
487 | .BR KEYCTL_LINK |
488 | and | |
3d20acc9 MK |
489 | .BR KEYCTL_SESSION_TO_PARENT |
490 | operations. | |
efeece04 | 491 | .IP |
3d20acc9 MK |
492 | The permission bits for each category are |
493 | .BR KEY_POS_LINK , | |
494 | .BR KEY_USR_LINK , | |
495 | .BR KEY_GRP_LINK , | |
496 | and | |
497 | .BR KEY_OTH_LINK . | |
498 | .TP | |
499 | .IR setattr " (since Linux 2.6.15)." | |
500 | This permission allows a key's UID, GID, and permissions mask to be changed. | |
efeece04 | 501 | .IP |
3d20acc9 | 502 | This permission is required for the |
60fc9e95 MK |
503 | .BR KEYCTL_REVOKE , |
504 | .BR KEYCTL_CHOWN , | |
505 | and | |
3d20acc9 MK |
506 | .BR KEYCTL_SETPERM |
507 | operations. | |
efeece04 | 508 | .IP |
3d20acc9 MK |
509 | The permission bits for each category are |
510 | .BR KEY_POS_SETATTR , | |
511 | .BR KEY_USR_SETATTR , | |
512 | .BR KEY_GRP_SETATTR , | |
513 | and | |
514 | .BR KEY_OTH_SETATTR . | |
fa76da80 ES |
515 | .RE |
516 | .IP | |
3d20acc9 MK |
517 | As a convenience, the following macros are defined as masks for |
518 | all of the permission bits in each of the user categories: | |
519 | .BR KEY_POS_ALL , | |
520 | .BR KEY_USR_ALL, | |
521 | .BR KEY_GRP_ALL , | |
522 | and | |
523 | .BR KEY_OTH_ALL . | |
efeece04 | 524 | .IP |
fa76da80 ES |
525 | The |
526 | .IR arg4 " and " arg5 | |
527 | arguments are ignored. | |
efeece04 | 528 | .IP |
efd4c0cd MK |
529 | This operation is exposed by |
530 | .I libkeyutils | |
531 | via the function | |
532 | .BR keyctl_setperm (3). | |
4509c62e | 533 | .TP |
5685b18c | 534 | .BR KEYCTL_DESCRIBE " (since Linux 2.6.10)" |
1f6c40f0 | 535 | Obtain a string describing the attributes of a specified key. |
efeece04 | 536 | .IP |
015c82d5 | 537 | The ID of the key to be described is specified in |
fa76da80 | 538 | .I arg2 |
015c82d5 | 539 | (cast to |
60fc9e95 | 540 | .IR key_serial_t ). |
1f6c40f0 | 541 | The descriptive string is returned in the buffer pointed to by |
fa76da80 | 542 | .I arg3 |
015c82d5 | 543 | (cast to |
1f6c40f0 | 544 | .IR "char\ *" ); |
fa76da80 | 545 | .I arg4 |
015c82d5 MK |
546 | (cast to |
547 | .IR size_t ) | |
548 | specifies the size of that buffer in bytes. | |
efeece04 | 549 | .IP |
461a8ce5 | 550 | The key must grant the caller |
fa76da80 | 551 | .I view |
461a8ce5 | 552 | permission. |
efeece04 | 553 | .IP |
1f6c40f0 MK |
554 | The returned string is null-terminated and |
555 | contains the following information about the key: | |
efeece04 | 556 | .IP |
015c82d5 | 557 | .in +4n |
1f6c40f0 | 558 | .IR type ; uid ; gid ; perm ; description |
015c82d5 | 559 | .in |
efeece04 | 560 | .IP |
015c82d5 MK |
561 | In the above, |
562 | .IR type | |
563 | and | |
564 | .IR description | |
565 | are strings, | |
566 | .IR uid | |
567 | and | |
568 | .IR gid | |
569 | are decimal strings, and | |
570 | .I perm | |
571 | is a hexadecimal permissions mask. | |
1f6c40f0 | 572 | The descriptive string is written with the following format: |
efeece04 | 573 | .IP |
015c82d5 | 574 | %s;%d;%d;%08x;%s |
efeece04 | 575 | .IP |
1f6c40f0 | 576 | .BR "Note: the intention is that the descriptive string should" |
015c82d5 MK |
577 | .BR "be extensible in future kernel versions". |
578 | In particular, the | |
579 | .IR description | |
580 | field will not contain semicolons; | |
472f8204 MK |
581 | .\" FIXME But, the kernel does not enforce the requirement |
582 | .\" that the key description contains no semicolons! | |
583 | .\" So, user space has no guarantee here?? | |
584 | .\" Either something more needs to be said here, | |
585 | .\" or a kernel fix is required. | |
015c82d5 MK |
586 | it should be parsed by working backwards from the end of the string |
587 | to find the last semicolon. | |
588 | This allows future semicolon-delimited fields to be inserted | |
1f6c40f0 | 589 | in the descriptive string in the future. |
efeece04 | 590 | .IP |
015c82d5 MK |
591 | Writing to the buffer is attempted only when |
592 | .IR arg3 | |
593 | is non-NULL and the specified buffer size | |
1f6c40f0 | 594 | is large enough to accept the descriptive string |
015c82d5 MK |
595 | (including the terminating null byte). |
596 | '\" Function commentary says it copies up to buflen bytes, but see the | |
fa76da80 ES |
597 | '\" (buffer && buflen >= ret) condition in keyctl_describe_key() in |
598 | '\" security/keyctl.c | |
015c82d5 MK |
599 | In order to determine whether the buffer size was too small, |
600 | check to see if the return value of the operation is greater than | |
601 | .IR arg4 . | |
efeece04 | 602 | .IP |
461a8ce5 | 603 | The |
fa76da80 ES |
604 | .I arg5 |
605 | argument is ignored. | |
efeece04 | 606 | .IP |
efd4c0cd MK |
607 | This operation is exposed by |
608 | .I libkeyutils | |
609 | via the function | |
610 | .BR keyctl_describe (3). | |
4509c62e | 611 | .TP |
a92d3bb4 | 612 | .B KEYCTL_CLEAR |
c97582e5 | 613 | Clear the contents of (i.e., unlink all keys from) a keyring. |
efeece04 | 614 | .IP |
c97582e5 MK |
615 | The ID of the key |
616 | (which must be of keyring type) | |
617 | .\" or the error ENOTDIR results | |
618 | is provided in | |
fa76da80 | 619 | .I arg2 |
c97582e5 | 620 | (cast to |
fa76da80 | 621 | .IR key_serial_t ). |
c97582e5 MK |
622 | .\" According to Documentation/security/keys.txt: |
623 | .\" This function can also be used to clear special kernel keyrings if they | |
624 | .\" are appropriately marked if the user has CAP_SYS_ADMIN capability. The | |
625 | .\" DNS resolver cache keyring is an example of this. | |
efeece04 | 626 | .IP |
60fc9e95 | 627 | The caller must have |
fa76da80 | 628 | .I write |
c97582e5 | 629 | permission on the keyring. |
efeece04 | 630 | .IP |
60fc9e95 MK |
631 | The arguments |
632 | .IR arg3 , | |
633 | .IR arg4 , | |
634 | and | |
635 | .IR arg5 | |
fa76da80 | 636 | are ignored. |
efeece04 | 637 | .IP |
efd4c0cd MK |
638 | This operation is exposed by |
639 | .I libkeyutils | |
640 | via the function | |
641 | .BR keyctl_clear (3). | |
4509c62e | 642 | .TP |
5685b18c | 643 | .BR KEYCTL_LINK " (since Linux 2.6.10)" |
c336c207 | 644 | Create a link from a keyring to a key. |
efeece04 | 645 | .IP |
c336c207 MK |
646 | The key to be linked is specified in |
647 | .IR arg2 | |
648 | (cast to | |
649 | .IR key_serial_t ); | |
650 | the keyring is specified in | |
651 | .IR arg3 | |
652 | (cast to | |
653 | .IR key_serial_t ). | |
efeece04 | 654 | .IP |
c336c207 MK |
655 | If a key with the same type and description is already linked in the keyring, |
656 | then that key is displaced from the keyring. | |
efeece04 | 657 | .IP |
c336c207 MK |
658 | Before creating the link, |
659 | the kernel checks the nesting of the keyrings and returns appropriate errors | |
2329c6d0 | 660 | if the link would produce a cycle |
ab3d151e | 661 | or if the nesting of keyrings would be too deep |
2329c6d0 MK |
662 | (The limit on the nesting of keyrings is determined by the kernel constant |
663 | .BR KEYRING_SEARCH_MAX_DEPTH , | |
664 | defined with the value 6, and is necessary to prevent overflows | |
665 | on the kernel stack when recursively searching keyrings). | |
efeece04 | 666 | .IP |
60fc9e95 | 667 | The caller must have |
fa76da80 ES |
668 | .I link |
669 | permission on the key being added and | |
670 | .I write | |
c336c207 | 671 | permission on the keyring. |
efeece04 | 672 | .IP |
60fc9e95 MK |
673 | The arguments |
674 | .IR arg4 | |
675 | and | |
676 | .IR arg5 | |
fa76da80 | 677 | are ignored. |
efeece04 | 678 | .IP |
efd4c0cd MK |
679 | This operation is exposed by |
680 | .I libkeyutils | |
681 | via the function | |
682 | .BR keyctl_link (3). | |
4509c62e | 683 | .TP |
5685b18c | 684 | .BR KEYCTL_UNLINK " (since Linux 2.6.10)" |
2981a43f | 685 | Unlink a key from a keyring. |
efeece04 | 686 | .IP |
2981a43f | 687 | The ID of the key to be unlinked is specified in |
fa76da80 | 688 | .I arg2 |
2981a43f MK |
689 | (cast to |
690 | .IR key_serial_t ); | |
691 | the ID of the keyring from which it is to be unlinked is specified in | |
fa76da80 | 692 | .I arg3 |
2981a43f MK |
693 | (cast to |
694 | .IR key_serial_t ). | |
efeece04 | 695 | .IP |
2981a43f | 696 | If the key is not currently linked into the keyring, an error results. |
efeece04 | 697 | .IP |
60fc9e95 | 698 | The caller must have |
fa76da80 | 699 | .I write |
60fc9e95 | 700 | permission on the keyring from which the key is being removed. |
efeece04 | 701 | .IP |
2981a43f MK |
702 | If the last link to a key is removed, |
703 | then that key will be scheduled for destruction. | |
efeece04 | 704 | .IP |
60fc9e95 MK |
705 | The arguments |
706 | .IR arg4 | |
707 | and | |
708 | .IR arg5 | |
fa76da80 | 709 | are ignored. |
efeece04 | 710 | .IP |
efd4c0cd MK |
711 | This operation is exposed by |
712 | .I libkeyutils | |
713 | via the function | |
714 | .BR keyctl_unlink (3). | |
4509c62e | 715 | .TP |
5685b18c | 716 | .BR KEYCTL_SEARCH " (since Linux 2.6.10)" |
4f5a5b13 MK |
717 | Search for a key in a keyring tree, |
718 | returning its ID and optionally linking it to a specified keyring. | |
efeece04 | 719 | .IP |
4f5a5b13 MK |
720 | The tree to be searched is specified by passing |
721 | the ID of the head keyring in | |
722 | .IR arg2 | |
723 | (cast to | |
fd2d68f9 | 724 | .IR key_serial_t ). |
4f5a5b13 | 725 | The search is performed breadth-first and recursively. |
efeece04 | 726 | .IP |
461a8ce5 | 727 | The |
fa76da80 | 728 | .I arg3 |
4f5a5b13 | 729 | and |
fa76da80 | 730 | .I arg4 |
4f5a5b13 MK |
731 | arguments specify the key to be searched for: |
732 | .I arg3 | |
733 | (cast as | |
734 | .IR "char\ *" ) | |
735 | contains the key type | |
736 | (a null-terminated character string up to 32 bytes in size, | |
737 | including the terminating null byte), and | |
738 | .I arg4 | |
739 | (cast as | |
740 | .IR "char\ *" ) | |
741 | contains the description of the key | |
742 | (a null-terminated character string up to 4096 bytes in size, | |
743 | including the terminating null byte). | |
efeece04 | 744 | .IP |
4f5a5b13 | 745 | The source keyring must grant |
fa76da80 | 746 | .I search |
4f5a5b13 MK |
747 | permission to the caller. |
748 | When performing the recursive search, only keyrings that grant the caller | |
749 | .I search | |
750 | permission will be searched. | |
751 | Only keys with for which the caller has | |
fa76da80 | 752 | .I search |
461a8ce5 | 753 | permission can be found. |
efeece04 | 754 | .IP |
4f5a5b13 | 755 | If the key is found, its ID is returned as the function result. |
efeece04 | 756 | .IP |
4f5a5b13 | 757 | If the key is found and |
fa76da80 | 758 | .I arg5 |
4f5a5b13 | 759 | (cast to |
fd2d68f9 | 760 | .IR key_serial_t ) |
4f5a5b13 MK |
761 | is nonzero, then, subject to the same constraints and rules as |
762 | .BR KEYCTL_LINK , | |
763 | the key is linked into the keyring whose ID is specified in | |
764 | .IR arg5 . | |
765 | If the destination keyring specified in | |
766 | .I arg5 | |
767 | already contains a link to a key that has the same type and description, | |
768 | then that link will be displaced by a link to | |
769 | the key found by this operation. | |
efeece04 | 770 | .IP |
4f5a5b13 MK |
771 | Instead of valid existing keyring IDs, the source |
772 | .RI ( arg2 ) | |
773 | and destination | |
774 | .RI ( arg5 ) | |
303ec07a MK |
775 | keyrings can be one of the special keyring IDs listed under |
776 | .BR KEYCTL_GET_KEYRING_ID . | |
4f5a5b13 | 777 | .IP |
efd4c0cd MK |
778 | This operation is exposed by |
779 | .I libkeyutils | |
780 | via the function | |
781 | .BR keyctl_search (3). | |
4509c62e | 782 | .TP |
5685b18c | 783 | .BR KEYCTL_READ " (since Linux 2.6.10)" |
8baa4815 | 784 | Read the payload data of a key. |
efeece04 | 785 | .IP |
8baa4815 | 786 | The ID of the key whose payload is to be read is specified in |
fa76da80 | 787 | .I arg2 |
8baa4815 | 788 | (cast to |
fd2d68f9 | 789 | .IR key_serial_t ). |
10c4bf22 MK |
790 | This can be the ID of an existing key, |
791 | or any of the special key IDs listed for | |
303ec07a | 792 | .BR KEYCTL_GET_KEYRING_ID . |
10c4bf22 | 793 | .\" including KEY_SPEC_REQKEY_AUTH_KEY |
efeece04 | 794 | .IP |
8baa4815 | 795 | The payload is placed in the buffer pointed by |
fa76da80 | 796 | .I arg3 |
8baa4815 | 797 | (cast to |
fd2d68f9 | 798 | .IR "char\ *" ); |
8baa4815 | 799 | the size of that buffer must be specified in |
fa76da80 | 800 | .I arg4 |
8baa4815 | 801 | (cast to |
fd2d68f9 | 802 | .IR size_t ). |
efeece04 | 803 | .IP |
10c4bf22 MK |
804 | The returned data will be processed for presentation |
805 | according to the key type. | |
806 | For example, a keyring will return an array of | |
807 | .I key_serial_t | |
808 | entries representing the IDs of all the keys that are linked to it. | |
809 | The | |
810 | .IR "user" | |
811 | key type will return its data as is. | |
812 | If a key type does not implement this function, | |
813 | the operation fails with the error | |
814 | .BR EOPNOTSUPP . | |
efeece04 | 815 | .IP |
10c4bf22 MK |
816 | If |
817 | .I arg3 | |
818 | is not NULL, | |
819 | as much of the payload data as will fit is copied into the buffer. | |
820 | On a successful return, | |
821 | the return value is always the total size of the payload data. | |
822 | To determine whether the buffer was of sufficient size, | |
823 | check to see that the return value is less than or equal to | |
824 | the value supplied in | |
825 | .IR arg4 . | |
efeece04 | 826 | .IP |
461a8ce5 | 827 | The key must either grant the caller |
fa76da80 | 828 | .I read |
8baa4815 | 829 | permission, or grant the caller |
fa76da80 | 830 | .I search |
2329c6d0 | 831 | permission when searched for from the process keyrings |
40aba91d | 832 | (i.e., the key is possessed). |
efeece04 | 833 | .IP |
461a8ce5 | 834 | The |
fa76da80 ES |
835 | .I arg5 |
836 | argument is ignored. | |
efeece04 | 837 | .IP |
efd4c0cd MK |
838 | This operation is exposed by |
839 | .I libkeyutils | |
840 | via the function | |
841 | .BR keyctl_read (3). | |
4509c62e | 842 | .TP |
5685b18c | 843 | .BR KEYCTL_INSTANTIATE " (since Linux 2.6.10)" |
0e4229d9 | 844 | (Positively) instantiate an uninstantiated key with a specified payload. |
efeece04 | 845 | .IP |
9f79744c | 846 | The ID of the key to be instantiated is provided in |
fa76da80 | 847 | .I arg2 |
9f79744c MK |
848 | (cast to |
849 | .IR key_serial_t ). | |
efeece04 | 850 | .IP |
9f79744c | 851 | The key payload is specified in the buffer pointed to by |
fa76da80 | 852 | .I arg3 |
9f79744c MK |
853 | (cast to |
854 | .IR "void\ *"); | |
855 | the size of that buffer is specified in | |
fa76da80 | 856 | .I arg4 |
9f79744c | 857 | (cast to |
fd2d68f9 | 858 | .IR size_t ). |
efeece04 | 859 | .IP |
9f79744c | 860 | The payload may be a NULL pointer and the buffer size may be 0 |
38590ae0 | 861 | if this is supported by the key type (e.g., it is a keyring). |
efeece04 | 862 | .IP |
9f79744c MK |
863 | The operation may be fail if the payload data is in the wrong format |
864 | or is otherwise invalid. | |
efeece04 | 865 | .IP |
9f79744c | 866 | If |
fa76da80 | 867 | .I arg5 |
9f79744c MK |
868 | (cast to |
869 | .IR key_serial_t ) | |
870 | is nonzero, then, subject to the same constraints and rules as | |
871 | .BR KEYCTL_LINK , | |
872 | the instantiated key is linked into the keyring whose ID specified in | |
873 | .IR arg5 . | |
efeece04 | 874 | .IP |
4e23dce3 MK |
875 | The caller must have the appropriate authorization key, |
876 | and once the uninstantiated key has been instantiated, | |
877 | the authorization key is revoked. | |
2329c6d0 MK |
878 | In other words, this operation is available only from a |
879 | .BR request-key (8)-style | |
880 | program. | |
881 | See | |
4e23dce3 MK |
882 | .BR request_key (2) |
883 | for an explanation of uninstantiated keys and key instantiation. | |
efeece04 | 884 | .IP |
efd4c0cd MK |
885 | This operation is exposed by |
886 | .I libkeyutils | |
887 | via the function | |
888 | .BR keyctl_instantiate (3). | |
4509c62e | 889 | .TP |
5685b18c | 890 | .BR KEYCTL_NEGATE " (since Linux 2.6.10)" |
64f2f3e7 | 891 | Negatively instantiate an uninstantiated key. |
efeece04 | 892 | .IP |
39b91a53 | 893 | This operation is equivalent to the call: |
efeece04 | 894 | .IP |
60fc9e95 | 895 | keyctl(KEYCTL_REJECT, arg2, arg3, ENOKEY, arg4); |
efeece04 | 896 | .IP |
fa76da80 ES |
897 | The |
898 | .I arg5 | |
899 | argument is ignored. | |
efeece04 | 900 | .IP |
efd4c0cd MK |
901 | This operation is exposed by |
902 | .I libkeyutils | |
903 | via the function | |
904 | .BR keyctl_negate (3). | |
8ec6a211 | 905 | .TP |
fa76da80 | 906 | .BR KEYCTL_SET_REQKEY_KEYRING " (since Linux 2.6.13)" |
0a45d567 | 907 | Set the default keyring to which implicitly requested keys |
0a45d567 | 908 | will be linked for this thread, and return the previous setting. |
2329c6d0 MK |
909 | Implicit key requests are those made by internal kernel components, |
910 | .\" I.e., calls to the kernel's internal request_key() interface, | |
911 | .\" which is distinct from the request_key(2) system call (which | |
912 | .\" ultimately employs the kernel-internal interface). | |
913 | such as can occur when, for example, opening files | |
0a45d567 | 914 | on an AFS or NFS filesystem. |
60be6628 MK |
915 | Setting the default keyring also has an effect when requesting |
916 | a key from user space; see | |
917 | .BR request_key (2) | |
918 | for details. | |
efeece04 | 919 | .IP |
461a8ce5 | 920 | The |
fa76da80 | 921 | .I arg2 |
fd2d68f9 MK |
922 | argument (cast to |
923 | .IR int ) | |
0a45d567 MK |
924 | should contain one of the following values, |
925 | to specify the new default keyring: | |
d1d5839d | 926 | .RS |
0a45d567 | 927 | .TP |
d1d5839d | 928 | .BR KEY_REQKEY_DEFL_NO_CHANGE |
38590ae0 | 929 | Don't change the default keyring. |
761fd292 | 930 | This can be used to discover the current default keyring |
38590ae0 | 931 | (without changing it). |
d1d5839d MK |
932 | .TP |
933 | .BR KEY_REQKEY_DEFL_DEFAULT | |
0a45d567 MK |
934 | This selects the default behaviour, |
935 | which is to use the thread-specific keyring if there is one, | |
936 | otherwise the process-specific keyring if there is one, | |
937 | otherwise the session keyring if there is one, | |
c69490ae MK |
938 | otherwise the UID-specific session keyring, |
939 | otherwise the user-specific keyring. | |
d1d5839d MK |
940 | .TP |
941 | .BR KEY_REQKEY_DEFL_THREAD_KEYRING | |
0a45d567 | 942 | Use the thread-specific keyring |
9879bf30 | 943 | .RB ( thread-keyring (7)) |
0a45d567 | 944 | as the new default keyring. |
d1d5839d MK |
945 | .TP |
946 | .BR KEY_REQKEY_DEFL_PROCESS_KEYRING | |
0a45d567 | 947 | Use the process-specific keyring |
9879bf30 | 948 | .RB ( process-keyring (7)) |
0a45d567 MK |
949 | as the new default keyring. |
950 | .TP | |
d1d5839d | 951 | .BR KEY_REQKEY_DEFL_SESSION_KEYRING |
0a45d567 | 952 | Use the session-specific keyring |
9879bf30 | 953 | .RB ( session-keyring (7)) |
0a45d567 | 954 | as the new default keyring. |
d1d5839d MK |
955 | .TP |
956 | .BR KEY_REQKEY_DEFL_USER_KEYRING | |
0a45d567 | 957 | Use the UID-specific keyring |
9879bf30 | 958 | .RB ( user-keyring (7)) |
0a45d567 | 959 | as the new default keyring. |
d1d5839d | 960 | .TP |
0a45d567 MK |
961 | .BR KEY_REQKEY_DEFL_USER_SESSION_KEYRING |
962 | Use the UID-specific session keyring | |
ab3d151e | 963 | .RB ( user-session-keyring (7)) |
0a45d567 | 964 | as the new default keyring. |
d1d5839d MK |
965 | .TP |
966 | .BR KEY_REQKEY_DEFL_REQUESTOR_KEYRING " (since Linux 2.6.29)" | |
fa76da80 | 967 | '\" 8bbf4976b59fc9fc2861e79cab7beb3f6d647640 |
0a45d567 | 968 | Use the requestor keyring. |
1fe70a67 | 969 | .\" FIXME The preceding explanation needs to be expanded. |
962dd42d MK |
970 | .\" Is the following correct: |
971 | .\" | |
2329c6d0 MK |
972 | .\" The requestor keyring is the dest_keyring that |
973 | .\" was supplied to a call to request_key(2)? | |
974 | .\" | |
64dd3b71 | 975 | .\" David Howells said: to be checked |
d1d5839d MK |
976 | .RE |
977 | .IP | |
0a45d567 MK |
978 | All other values are invalid. |
979 | .\" (including the still-unsupported KEY_REQKEY_DEFL_GROUP_KEYRING) | |
efeece04 | 980 | .IP |
60fc9e95 MK |
981 | The arguments |
982 | .IR arg3 , | |
983 | .IR arg4 , | |
984 | and | |
985 | .IR arg5 | |
fa76da80 | 986 | are ignored. |
efeece04 | 987 | .IP |
0a45d567 MK |
988 | The setting controlled by this operation is inherited by the child of |
989 | .BR fork (2) | |
990 | and preserved across | |
991 | .BR execve (2). | |
efeece04 | 992 | .IP |
efd4c0cd MK |
993 | This operation is exposed by |
994 | .I libkeyutils | |
995 | via the function | |
996 | .BR keyctl_set_reqkey_keyring (3). | |
8ec6a211 | 997 | .TP |
fa76da80 | 998 | .BR KEYCTL_SET_TIMEOUT " (since Linux 2.6.16)" |
adee7073 | 999 | Set a timeout on a key. |
efeece04 | 1000 | .IP |
adee7073 | 1001 | The ID of the key is specified in |
fa76da80 | 1002 | .I arg2 |
adee7073 MK |
1003 | (cast to |
1004 | .IR key_serial_t ). | |
1005 | The timeout value, in seconds from the current time, | |
1006 | is specified in | |
fa76da80 | 1007 | .I arg3 |
adee7073 | 1008 | (cast to |
fd2d68f9 | 1009 | .IR "unsigned int" ). |
38590ae0 | 1010 | The timeout is measured against the realtime clock. |
efeece04 | 1011 | .IP |
adee7073 | 1012 | Specifying the timeout value as 0 clears any existing timeout on the key. |
efeece04 | 1013 | .IP |
38590ae0 MK |
1014 | The |
1015 | .I /proc/keys | |
1016 | file displays the remaining time until each key will expire. | |
1017 | (This is the only method of discovering the timeout on a key.) | |
efeece04 | 1018 | .IP |
60fc9e95 | 1019 | The caller must either have the |
fa76da80 | 1020 | .I setattr |
adee7073 MK |
1021 | permission on the key |
1022 | or hold an instantiation authorization token for the key (see | |
1023 | .BR request_key (2)). | |
efeece04 | 1024 | .IP |
461a8ce5 MK |
1025 | The key and any links to the key will be |
1026 | automatically garbage collected after the timeout expires. | |
adee7073 MK |
1027 | Subsequent attempts to access the key will then fail with the error |
1028 | .BR EKEYEXPIRED . | |
efeece04 | 1029 | .IP |
4c8ae226 MK |
1030 | This operation cannot be used to set timeouts on revoked, expired, |
1031 | or negatively instantiated keys. | |
efeece04 | 1032 | .IP |
60fc9e95 MK |
1033 | The arguments |
1034 | .IR arg4 | |
1035 | and | |
1036 | .IR arg5 | |
fa76da80 | 1037 | are ignored. |
efeece04 | 1038 | .IP |
efd4c0cd MK |
1039 | This operation is exposed by |
1040 | .I libkeyutils | |
1041 | via the function | |
1042 | .BR keyctl_set_timeout (3). | |
8ec6a211 | 1043 | .TP |
fa76da80 | 1044 | .BR KEYCTL_ASSUME_AUTHORITY " (since Linux 2.6.16)" |
076432af | 1045 | Assume (or divest) the authority for the calling thread |
a6cca1b5 | 1046 | to instantiate a key. |
efeece04 | 1047 | .IP |
076432af | 1048 | The |
fa76da80 | 1049 | .I arg2 |
fd2d68f9 | 1050 | argument (cast to |
076432af MK |
1051 | .IR key_serial_t ) |
1052 | specifies either a nonzero key ID to assume authority, | |
1053 | or the value 0 to divest authority. | |
efeece04 | 1054 | .IP |
076432af MK |
1055 | If |
1056 | .I arg2 | |
1057 | is nonzero, then it specifies the ID of an uninstantiated key for which | |
1058 | authority is to be assumed. | |
a6cca1b5 MK |
1059 | That key can then be instantiated using one of |
1060 | .BR KEYCTL_INSTANTIATE , | |
1061 | .BR KEYCTL_INSTANTIATE_IOV , | |
1062 | .BR KEYCTL_REJECT , | |
1063 | or | |
1064 | .BR KEYCTL_NEGATE . | |
1065 | Once the key has been instantiated, | |
1066 | the thread is automatically divested of authority to instantiate the key. | |
efeece04 | 1067 | .IP |
a6cca1b5 | 1068 | Authority over a key can be assumed only if the calling thread has present |
076432af MK |
1069 | in its keyrings the authorization key that is |
1070 | associated with the specified key. | |
16d9a8f9 MK |
1071 | (In other words, the |
1072 | .BR KEYCTL_ASSUME_AUTHORITY | |
1073 | operation is available only from a | |
2329c6d0 MK |
1074 | .BR request-key (8)-style |
1075 | program; see | |
16d9a8f9 MK |
1076 | .BR request_key (2) |
1077 | for an explanation of how this operation is used.) | |
076432af | 1078 | The caller must have |
fa76da80 | 1079 | .I search |
076432af | 1080 | permission on the authorization key. |
efeece04 | 1081 | .IP |
076432af MK |
1082 | If the specified key has a matching authorization key, |
1083 | then the ID of that key is returned. | |
a6cca1b5 MK |
1084 | The authorization key can be read |
1085 | .RB ( KEYCTL_READ ) | |
1086 | to obtain the callout information passed to | |
076432af | 1087 | .BR request_key (2). |
efeece04 | 1088 | .IP |
076432af | 1089 | If the ID given in |
fa76da80 | 1090 | .I arg2 |
076432af MK |
1091 | is 0, then the currently assumed authority is cleared (divested), |
1092 | and the value 0 is returned. | |
efeece04 | 1093 | .IP |
a6cca1b5 MK |
1094 | The |
1095 | .BR KEYCTL_ASSUME_AUTHORITY | |
1096 | mechanism allows a program such as | |
1097 | .BR request-key (8) | |
1098 | to assume the necessary authority to instantiate a new uninstantiated key | |
1099 | that was created as a consequence of a call to | |
1100 | .BR request_key (2). | |
1101 | For further information, see | |
1102 | .BR request_key (2) | |
1103 | and the kernel source file | |
1104 | .IR Documentation/security/keys-request-key.txt . | |
efeece04 | 1105 | .IP |
60fc9e95 MK |
1106 | The arguments |
1107 | .IR arg3 , | |
1108 | .IR arg4 , | |
1109 | and | |
1110 | .IR arg5 | |
fa76da80 | 1111 | are ignored. |
efeece04 | 1112 | .IP |
efd4c0cd MK |
1113 | This operation is exposed by |
1114 | .I libkeyutils | |
1115 | via the function | |
1116 | .BR keyctl_assume_authority (3). | |
fa76da80 ES |
1117 | .TP |
1118 | .BR KEYCTL_GET_SECURITY " (since Linux 2.6.26)" | |
48874189 MK |
1119 | .\" commit 70a5bb72b55e82fbfbf1e22cae6975fac58a1e2d |
1120 | Get the LSM (Linux Security Module) security label of the specified key. | |
efeece04 | 1121 | .IP |
48874189 | 1122 | The ID of the key whose security label is to be fetched is specified in |
fa76da80 | 1123 | .I arg2 |
48874189 | 1124 | (cast to |
fd2d68f9 | 1125 | .IR key_serial_t ). |
48874189 MK |
1126 | The security label (terminated by a null byte) |
1127 | will be placed in the buffer pointed to by | |
fa76da80 | 1128 | .I arg3 |
fd2d68f9 | 1129 | argument (cast to |
48874189 MK |
1130 | .IR "char\ *" ); |
1131 | the size of the buffer must be provided in | |
fa76da80 | 1132 | .I arg4 |
48874189 | 1133 | (cast to |
fd2d68f9 | 1134 | .IR size_t ). |
efeece04 | 1135 | .IP |
48874189 MK |
1136 | If |
1137 | .I arg3 | |
1138 | is specified as NULL or the buffer size specified in | |
1139 | .IR arg4 | |
1140 | is too small, the full size of the security label string | |
1141 | (including the terminating null byte) | |
1142 | is returned as the function result, | |
1143 | and nothing is copied to the buffer. | |
efeece04 | 1144 | .IP |
48874189 MK |
1145 | The caller must have |
1146 | .I view | |
1147 | permission on the specified key. | |
efeece04 | 1148 | .IP |
48874189 MK |
1149 | The returned security label string will be rendered in a form appropriate |
1150 | to the LSM in force. | |
962dd42d | 1151 | For example, with SELinux, it may look like: |
efeece04 | 1152 | .IP |
48874189 | 1153 | unconfined_u:unconfined_r:unconfined_t:s0-s0:c0.c1023 |
efeece04 | 1154 | .IP |
48874189 MK |
1155 | If no LSM is currently in force, |
1156 | then an empty string is placed in the buffer. | |
efeece04 | 1157 | .IP |
461a8ce5 | 1158 | The |
fa76da80 ES |
1159 | .I arg5 |
1160 | argument is ignored. | |
efeece04 | 1161 | .IP |
efd4c0cd MK |
1162 | This operation is exposed by |
1163 | .I libkeyutils | |
48874189 | 1164 | via the functions |
efd4c0cd MK |
1165 | .BR keyctl_get_security (3) |
1166 | and | |
1167 | .BR keyctl_get_security_alloc (3). | |
fa76da80 ES |
1168 | .TP |
1169 | .BR KEYCTL_SESSION_TO_PARENT " (since Linux 2.6.32)" | |
3234dd5f MK |
1170 | .\" commit ee18d64c1f632043a02e6f5ba5e045bb26a5465f |
1171 | Replace the session keyring to which the | |
1172 | .I parent | |
1173 | of the calling process | |
1174 | subscribes with the session keyring of the calling process. | |
38590ae0 MK |
1175 | .\" What is the use case for KEYCTL_SESSION_TO_PARENT? |
1176 | .\" David Howells: the Process Authentication Groups people requested this, | |
1177 | .\" but then didn't use it; maybe there are no users. | |
efeece04 | 1178 | .IP |
3234dd5f MK |
1179 | The keyring will be replaced in the parent process at the point |
1180 | where the parent next transitions from kernel space to user space. | |
efeece04 | 1181 | .IP |
461a8ce5 | 1182 | The keyring must exist and must grant the caller |
fa76da80 | 1183 | .I link |
3234dd5f MK |
1184 | permission. |
1185 | The parent process must be single-threaded and have | |
60fc9e95 | 1186 | the same effective ownership as this process |
40aba91d | 1187 | and must not be set-user-ID or set-group-ID. |
3234dd5f MK |
1188 | The UID of the parent process's existing session keyring (f it has one), |
1189 | as well as the UID of the caller's session keyring | |
1190 | much match the caller's effective UID. | |
efeece04 | 1191 | .IP |
3234dd5f MK |
1192 | The fact that it is the parent process that is affected by this operation |
1193 | allows a program such as the shell to start a child process that | |
1194 | uses this operation to change the shell's session keyring. | |
1195 | (This is what the | |
1196 | .BR keyctl (1) | |
1197 | .B new_session | |
1198 | command does.) | |
efeece04 | 1199 | .IP |
60fc9e95 MK |
1200 | The arguments |
1201 | .IR arg2 , | |
1202 | .IR arg3 , | |
1203 | .IR arg4 , | |
1204 | and | |
1205 | .IR arg5 | |
fa76da80 | 1206 | are ignored. |
efeece04 | 1207 | .IP |
efd4c0cd MK |
1208 | This operation is exposed by |
1209 | .I libkeyutils | |
1210 | via the function | |
1211 | .BR keyctl_session_to_parent (3). | |
fa76da80 ES |
1212 | .TP |
1213 | .BR KEYCTL_REJECT " (since Linux 2.6.39)" | |
8ab24543 | 1214 | .\" commit fdd1b94581782a2ddf9124414e5b7a5f48ce2f9c |
8ab24543 MK |
1215 | Mark a key as negatively instantiated and set an expiration timer |
1216 | on the key. | |
1217 | This operation provides a superset of the functionality of the earlier | |
1218 | .BR KEYCTL_NEGATE | |
1219 | operation. | |
efeece04 | 1220 | .IP |
8ab24543 | 1221 | The ID of the key that is to be negatively instantiated is specified in |
fa76da80 | 1222 | .I arg2 |
8ab24543 MK |
1223 | (cast to |
1224 | .IR key_serial_t ). | |
1225 | The | |
fa76da80 | 1226 | .I arg3 |
8ab24543 | 1227 | (cast to |
fd2d68f9 | 1228 | .IR "unsigned int" ) |
8ab24543 MK |
1229 | argument specifies the lifetime of the key, in seconds. |
1230 | The | |
fa76da80 | 1231 | .I arg4 |
fd2d68f9 | 1232 | argument (cast to |
8ab24543 MK |
1233 | .IR "unsigned int" ) |
1234 | specifies the error to be returned when a search hits this key; | |
1235 | typically, this is one of | |
1236 | .BR EKEYREJECTED , | |
1237 | .BR EKEYREVOKED , | |
1238 | or | |
1239 | .BR EKEYEXPIRED . | |
efeece04 | 1240 | .IP |
8ab24543 | 1241 | If |
fa76da80 | 1242 | .I arg5 |
8ab24543 MK |
1243 | (cast to |
1244 | .IR key_serial_t ) | |
1245 | is nonzero, then, subject to the same constraints and rules as | |
1246 | .BR KEYCTL_LINK , | |
1247 | the negatively instantiated key is linked into the keyring | |
17de986e | 1248 | whose ID is specified in |
8ab24543 | 1249 | .IR arg5 . |
efeece04 | 1250 | .IP |
2329c6d0 MK |
1251 | The caller must have the appropriate authorization key. |
1252 | In other words, this operation is available only from a | |
1253 | .BR request-key (8)-style | |
1254 | program. | |
1255 | See | |
1256 | .BR request_key (2). | |
efeece04 | 1257 | .IP |
ebf4eb28 MK |
1258 | The caller must have the appropriate authorization key, |
1259 | and once the uninstantiated key has been instantiated, | |
1260 | the authorization key is revoked. | |
1261 | In other words, this operation is available only from a | |
1262 | .BR request-key (8)-style | |
1263 | program. | |
1264 | See | |
60fc9e95 | 1265 | .BR request_key (2) |
ebf4eb28 | 1266 | for an explanation of uninstantiated keys and key instantiation. |
efeece04 | 1267 | .IP |
efd4c0cd MK |
1268 | This operation is exposed by |
1269 | .I libkeyutils | |
1270 | via the function | |
1271 | .BR keyctl_reject (3). | |
fa76da80 ES |
1272 | .TP |
1273 | .BR KEYCTL_INSTANTIATE_IOV " (since Linux 2.6.39)" | |
1f234c53 | 1274 | .\" commit ee009e4a0d4555ed522a631bae9896399674f063 |
64f2f3e7 | 1275 | Instantiate an uninstantiated key with a payload specified |
329c2892 | 1276 | via a vector of buffers. |
efeece04 | 1277 | .IP |
329c2892 MK |
1278 | This operation is the same as |
1279 | .BR KEYCTL_INSTANTIATE , | |
1280 | but the payload data is specified as an array of | |
1281 | .IR iovec | |
1282 | structures: | |
efeece04 | 1283 | .IP |
329c2892 | 1284 | .in +4n |
b8302363 | 1285 | .EX |
329c2892 MK |
1286 | struct iovec { |
1287 | void *iov_base; /* Starting address of buffer */ | |
1288 | size_t iov_len; /* Size of buffer (in bytes) */ | |
1289 | }; | |
b8302363 | 1290 | .EE |
329c2892 | 1291 | .in |
efeece04 | 1292 | .IP |
329c2892 MK |
1293 | The pointer to the payload vector is specified in |
1294 | .IR arg3 | |
1295 | (cast as | |
1296 | .IR "const struct iovec\ *" ). | |
1297 | The number of items in the vector is specified in | |
1298 | .IR arg4 | |
1299 | (cast as | |
1300 | .IR "unsigned int" ). | |
efeece04 | 1301 | .IP |
461a8ce5 | 1302 | The |
329c2892 MK |
1303 | .I arg2 |
1304 | (key ID) | |
1305 | and | |
fa76da80 | 1306 | .I arg5 |
329c2892 MK |
1307 | (keyring ID) |
1308 | are interpreted as for | |
1309 | .BR KEYCTL_INSTANTIATE . | |
efeece04 | 1310 | .IP |
efd4c0cd MK |
1311 | This operation is exposed by |
1312 | .I libkeyutils | |
1313 | via the function | |
1314 | .BR keyctl_instantiate_iov (3). | |
fa76da80 ES |
1315 | .TP |
1316 | .BR KEYCTL_INVALIDATE " (since Linux 3.5)" | |
1f234c53 MK |
1317 | .\" commit fd75815f727f157a05f4c96b5294a4617c0557da |
1318 | Mark a key as invalid. | |
efeece04 | 1319 | .IP |
1f234c53 | 1320 | The ID of the key to be invalidated is specified in |
fa76da80 | 1321 | .I arg2 |
1f234c53 | 1322 | (cast to |
fd2d68f9 | 1323 | .IR key_serial_t ). |
efeece04 | 1324 | .IP |
1f234c53 MK |
1325 | To invalidate a key, |
1326 | the caller must have | |
fa76da80 | 1327 | .I search |
1f234c53 MK |
1328 | permission on the key. |
1329 | .\" CAP_SYS_ADMIN is permitted to invalidate certain special keys | |
efeece04 | 1330 | .IP |
7b4861d9 MK |
1331 | This operation marks the key as invalid |
1332 | and schedules immediate garbage collection. | |
1f234c53 MK |
1333 | The garbage collector removes the invalidated key from all keyrings and |
1334 | deletes the key when its reference count reaches zero. | |
1335 | After this operation, | |
1336 | the key will be ignored by all searches, | |
1337 | even if it is not yet deleted. | |
efeece04 | 1338 | .IP |
1f234c53 MK |
1339 | Keys that are marked invalid become invisible to normal key operations |
1340 | immediately, though they are still visible in | |
1341 | .I /proc/keys | |
1342 | (marked with an 'i' flag) | |
1343 | until they are actually removed. | |
efeece04 | 1344 | .IP |
60fc9e95 MK |
1345 | The arguments |
1346 | .IR arg3 , | |
1347 | .IR arg4 , | |
1348 | and | |
1349 | .IR arg5 | |
fa76da80 | 1350 | are ignored. |
efeece04 | 1351 | .IP |
efd4c0cd MK |
1352 | This operation is exposed by |
1353 | .I libkeyutils | |
1354 | via the function | |
1355 | .BR keyctl_invalidate (3). | |
fa76da80 ES |
1356 | .TP |
1357 | .BR KEYCTL_GET_PERSISTENT " (since Linux 3.13)" | |
f5954733 MK |
1358 | .\" commit f36f8c75ae2e7d4da34f4c908cebdb4aa42c977e |
1359 | Get the persistent keyring | |
9879bf30 | 1360 | .RB ( persistent-keyring (7)) |
f5954733 | 1361 | for a specified user and link it to a specified keyring. |
efeece04 | 1362 | .IP |
f5954733 | 1363 | The user ID is specified in |
fa76da80 | 1364 | .I arg2 |
fd2d68f9 | 1365 | (cast to |
f5954733 MK |
1366 | .IR uid_t ). |
1367 | If the value \-1 is specified, the caller's real user ID is used. | |
1368 | The ID of the destination keyring is specified in | |
fa76da80 | 1369 | .I arg3 |
f5954733 | 1370 | (cast to |
fd2d68f9 | 1371 | .IR key_serial_t ). |
efeece04 | 1372 | .IP |
f5954733 MK |
1373 | The caller must have the |
1374 | .BR CAP_SETUID | |
1375 | capability in its user namespace in order to fetch the persistent keyring | |
1376 | for a user ID that does not match either the real or effective user ID | |
1377 | of the caller. | |
efeece04 | 1378 | .IP |
f5954733 MK |
1379 | If the call is successful, |
1380 | a link to the persistent keyring is added to the keyring | |
1381 | whose ID was specified in | |
1382 | .IR arg3 . | |
efeece04 | 1383 | .IP |
f5954733 MK |
1384 | The caller must have |
1385 | .I write | |
1386 | permission on the keyring. | |
efeece04 | 1387 | .IP |
f5954733 MK |
1388 | The persistent keyring will be created by the kernel |
1389 | if it does not yet exist. | |
efeece04 | 1390 | .IP |
f5954733 MK |
1391 | Each time the |
1392 | .B KEYCTL_GET_PERSISTENT | |
1393 | operation is performed, the persistent keyring will | |
1394 | have its expiration timeout reset to the value in: | |
efeece04 | 1395 | .IP |
f17b3bd8 MK |
1396 | .in +4n |
1397 | .EX | |
1398 | /proc/sys/kernel/keys/persistent_keyring_expiry | |
1399 | .EE | |
1400 | .in | |
efeece04 | 1401 | .IP |
f5954733 MK |
1402 | Should the timeout be reached, |
1403 | the persistent keyring will be removed and | |
1404 | everything it pins can then be garbage collected. | |
efeece04 | 1405 | .IP |
f5954733 | 1406 | Persistent keyrings were added to Linux in kernel version 3.13. |
efeece04 | 1407 | .IP |
60fc9e95 MK |
1408 | The arguments |
1409 | .IR arg4 | |
1410 | and | |
1411 | .IR arg5 | |
fa76da80 | 1412 | are ignored. |
efeece04 | 1413 | .IP |
efd4c0cd MK |
1414 | This operation is exposed by |
1415 | .I libkeyutils | |
1416 | via the function | |
1417 | .BR keyctl_get_persistent (3). | |
fa76da80 ES |
1418 | .TP |
1419 | .BR KEYCTL_DH_COMPUTE " (since Linux 4.7)" | |
b74b20aa | 1420 | .\" commit ddbb41148724367394d0880c516bfaeed127b52e |
a02cbc78 ES |
1421 | Compute a Diffie-Hellman shared secret or public key, |
1422 | optionally applying key derivation function (KDF) to the result. | |
efeece04 | 1423 | .IP |
461a8ce5 | 1424 | The |
fa76da80 | 1425 | .I arg2 |
1deb8c8e | 1426 | argument is a pointer to a set of parameters containing |
152d5aab MK |
1427 | serial numbers for three |
1428 | .IR """user""" | |
1429 | keys used in the Diffie-Hellman calculation, | |
1deb8c8e | 1430 | packaged in a structure of the following form: |
efeece04 | 1431 | .IP |
fa76da80 | 1432 | .in +4n |
b8302363 | 1433 | .EX |
fa76da80 | 1434 | struct keyctl_dh_params { |
1deb8c8e MK |
1435 | int32_t private; /* The local private key */ |
1436 | int32_t prime; /* The prime, known to both parties */ | |
1437 | int32_t base; /* The base integer: either a shared | |
1438 | generator or the remote public key */ | |
fa76da80 | 1439 | }; |
b8302363 | 1440 | .EE |
e646a1ba | 1441 | .in |
efeece04 | 1442 | .IP |
152d5aab MK |
1443 | Each of the three keys specified in this structure must grant the caller |
1444 | .I read | |
1445 | permission. | |
1446 | The payloads of these keys are used to calculate the Diffie-Hellman | |
1447 | result as: | |
efeece04 | 1448 | .IP |
1deb8c8e | 1449 | base ^ private mod prime |
efeece04 | 1450 | .IP |
1deb8c8e MK |
1451 | If the base is the shared generator, the result is the local public key. |
1452 | If the base is the remote public key, the result is the shared secret. | |
efeece04 | 1453 | .IP |
fa76da80 ES |
1454 | The |
1455 | .I arg3 | |
fd2d68f9 MK |
1456 | argument (cast to |
1457 | .IR "char\ *" ) | |
1deb8c8e MK |
1458 | points to a buffer where the result of the calculation is placed. |
1459 | The size of that buffer is specified in | |
fa76da80 | 1460 | .I arg4 |
1deb8c8e | 1461 | (cast to |
fd2d68f9 | 1462 | .IR size_t ). |
efeece04 | 1463 | .IP |
1deb8c8e | 1464 | The buffer must be large enough to accommodate the output data, |
60fc9e95 | 1465 | otherwise an error is returned. |
1deb8c8e MK |
1466 | If |
1467 | .I arg4 | |
1468 | is specified zero, | |
152d5aab | 1469 | in which case the buffer is not used and |
1deb8c8e MK |
1470 | the operation returns the minimum required buffer size |
1471 | (i.e., the length of the prime). | |
efeece04 | 1472 | .IP |
919d8206 MK |
1473 | Diffie-Hellman computations can be performed in user space, |
1474 | but require a multiple-precision integer (MPI) library. | |
1475 | Moving the implementation into the kernel gives access to | |
1476 | the kernel MPI implementation, | |
1477 | and allows access to secure or acceleration hardware. | |
efeece04 | 1478 | .IP |
919d8206 MK |
1479 | Adding support for DH computation to the |
1480 | .BR keyctl() | |
1481 | system call was considered a good fit due to the DH algorithm's use | |
1482 | for deriving shared keys; | |
1483 | it also allows the type of the key to determine | |
1484 | which DH implementation (software or hardware) is appropriate. | |
a02cbc78 | 1485 | .\" commit f1c316a3ab9d24df6022682422fe897492f2c0c8 |
efeece04 | 1486 | .IP |
a02cbc78 | 1487 | If the |
fa76da80 | 1488 | .I arg5 |
a02cbc78 ES |
1489 | argument is |
1490 | .BR NULL , | |
1491 | then the DH result itself is returned. | |
1492 | Otherwise (since Linux 4.12), it is a pointer to a structure which specifies | |
1493 | parameters of the KDF operation to be applied: | |
1494 | .IP | |
1495 | .in +4n | |
1496 | .EX | |
1497 | struct keyctl_kdf_params { | |
1498 | char *hashname; /* Hash algorithm name */ | |
1499 | char *otherinfo; /* SP800-56A OtherInfo */ | |
1500 | __u32 otherinfolen; /* Length of otherinfo data */ | |
1501 | __u32 __spare[8]; /* Reserved */ | |
1502 | }; | |
1503 | .EE | |
1504 | .in | |
1505 | .IP | |
1506 | The | |
1507 | .B hashname | |
1508 | field is a null-terminated string which specifies hash name | |
1509 | (available into the kernel's crypto API; the list of the hashes available | |
1510 | is rather tricky to observe; please refer to the | |
1511 | .URL https://www.kernel.org/doc/html/latest/crypto/architecture.html "Kernel Crypto API Architecture" | |
1512 | for the information regarding how hash names are constructed and | |
1513 | to your kernel's source and configuration regarding what ciphers | |
1514 | and templates with type | |
1515 | .B CRYPTO_ALG_TYPE_SHASH | |
1516 | are available) | |
1517 | to be applied to DH result in KDF operation. | |
1518 | .IP | |
1519 | The | |
1520 | .B otherinfo | |
1521 | field is an | |
1522 | .I OtherInfo | |
1523 | data as described in SP800-56A section 5.8.1.2 and is algorithm-specific. | |
1524 | This data is concatenated with the result of DH operation and is provided as | |
1525 | an input to the KDF operation. | |
1526 | Its size is provided in the | |
1527 | .B otherinfolen | |
1528 | field and is limited by | |
1529 | .B KEYCTL_KDF_MAX_OI_LEN | |
1530 | constant that defined in | |
1531 | .B security/keys/internal.h | |
1532 | to a value of 64. | |
1533 | .IP | |
1534 | The | |
1535 | .B __spare | |
1536 | field is currently unused. | |
1537 | .\" commit 4f9dabfaf8df971f8a3b6aa324f8f817be38d538 | |
1538 | It was ignored until Linux 4.13 (but still should be | |
1539 | user-addressable since it is copied to the kernel), | |
1540 | and should contain zeroes since Linux 4.13. | |
1541 | .IP | |
1542 | The KDF implementation complies with SP800-56A as well | |
1543 | as with SP800-108 (the counter KDF). | |
4509c62e | 1544 | .SH RETURN VALUE |
fa76da80 ES |
1545 | For a successful call, the return value depends on the operation: |
1546 | .TP | |
1547 | .B KEYCTL_GET_KEYRING_ID | |
1548 | The ID of the requested keyring. | |
1549 | .TP | |
1550 | .B KEYCTL_JOIN_SESSION_KEYRING | |
1551 | The ID of the joined session keyring. | |
1552 | .TP | |
1553 | .B KEYCTL_DESCRIBE | |
015c82d5 MK |
1554 | The size of the description (including the terminating null byte), |
1555 | irrespective of the provided buffer size. | |
fa76da80 ES |
1556 | .TP |
1557 | .B KEYCTL_SEARCH | |
d374e850 | 1558 | The ID of the key that was found. |
fa76da80 ES |
1559 | .TP |
1560 | .B KEYCTL_READ | |
8baa4815 MK |
1561 | The amount of data that is available in the key, |
1562 | irrespective of the provided buffer size. | |
fa76da80 ES |
1563 | .TP |
1564 | .B KEYCTL_SET_REQKEY_KEYRING | |
0a45d567 MK |
1565 | The ID of the previous default keyring |
1566 | to which implicitly requested keys were linked | |
1567 | (one of | |
1568 | .BR KEY_REQKEY_DEFL_USER_* ). | |
fa76da80 ES |
1569 | .TP |
1570 | .B KEYCTL_ASSUME_AUTHORITY | |
076432af MK |
1571 | Either 0, if the ID given was 0, |
1572 | or the ID of the authorization key matching the specified key, | |
1573 | if a non-zero key ID was provided. | |
fa76da80 ES |
1574 | .TP |
1575 | .B KEYCTL_GET_SECURITY | |
48874189 MK |
1576 | The size of the LSM security label string |
1577 | (including the terminating null byte), | |
fa76da80 ES |
1578 | irrespective of the provided buffer size. |
1579 | .TP | |
1580 | .B KEYCTL_GET_PERSISTENT | |
d374e850 | 1581 | The ID of the persistent keyring. |
fa76da80 ES |
1582 | .TP |
1583 | .B KEYCTL_DH_COMPUTE | |
1deb8c8e MK |
1584 | The number of bytes copied to the buffer, or, if |
1585 | .I arg4 | |
1586 | is 0, the required buffer size. | |
fa76da80 | 1587 | .TP |
c3161083 | 1588 | All other operations |
fa76da80 ES |
1589 | Zero. |
1590 | .PP | |
1591 | On error, \-1 is returned, and | |
1592 | .I errno | |
1593 | is set appropriately to indicate the error. | |
4509c62e MK |
1594 | .SH ERRORS |
1595 | .TP | |
27807c32 | 1596 | .B EACCES |
60fc9e95 | 1597 | The requested operation wasn't permitted. |
27807c32 | 1598 | .TP |
a02cbc78 ES |
1599 | .B EAGAIN |
1600 | .I operation | |
1601 | was | |
1602 | .B KEYCTL_DH_COMPUTE | |
1603 | and there was an error during crypto module initialisation. | |
1604 | .TP | |
c336c207 | 1605 | .B EDEADLK |
53e88c3e | 1606 | .I operation |
8a156aca | 1607 | was |
c336c207 MK |
1608 | .BR KEYCTL_LINK |
1609 | and the requested link would result in a cycle. | |
1610 | .TP | |
27807c32 MK |
1611 | .B EDQUOT |
1612 | The key quota for the caller's user would be exceeded by creating a key or | |
1613 | linking it to the keyring. | |
4509c62e | 1614 | .TP |
a02cbc78 ES |
1615 | .B EFAULT |
1616 | .I operation | |
1617 | was | |
1618 | .B KEYCTL_DH_COMPUTE | |
1619 | and one of the following has failed: | |
1620 | .RS | |
1621 | .IP \(bu 3 | |
1622 | copying of | |
1623 | .BR "struct keyctl_dh_params" , | |
1624 | provided in | |
1625 | .I arg2 | |
1626 | argument, from the user space; | |
1627 | .IP \(bu | |
1628 | copying of | |
1629 | .BR "struct keyctl_kdf_params" , | |
1630 | provided in non-NULL | |
1631 | .I arg5 | |
1632 | argument, from the user space | |
1633 | (in case kernel supports performing KDF operation on DH operation result); | |
1634 | .IP \(bu | |
1635 | copying of data pointed by | |
1636 | .B hashname | |
1637 | field of | |
1638 | .B "struct keyctl_kdf_params" | |
1639 | from the user space; | |
1640 | .IP \(bu | |
1641 | copying of data pointed by | |
1642 | .B otherinfo | |
1643 | field of | |
1644 | .B struct keyctl_kdf_params | |
1645 | from the user space if | |
1646 | .B otherinfolen | |
1647 | field was non-zero; | |
1648 | .IP \(bu | |
1649 | copying of the result to the user space. | |
1650 | .RE | |
1651 | .TP | |
3d20acc9 | 1652 | .B EINVAL |
53e88c3e | 1653 | .I operation |
3d20acc9 MK |
1654 | was |
1655 | .B KEYCTL_SETPERM | |
1656 | and an invalid permission bit was specified in | |
1657 | .IR arg3 . | |
1658 | .TP | |
3cc58bb8 MK |
1659 | .B EINVAL |
1660 | .I operation | |
29806cc8 | 1661 | was |
ff91beca MK |
1662 | .BR KEYCTL_SEARCH |
1663 | and the size of the description in | |
1664 | .IR arg4 | |
1665 | (including the terminating null byte) exceeded 4096 bytes. | |
1666 | size of the string (including the terminating null byte) specified in | |
1667 | .I arg3 | |
1668 | (the key type) | |
1669 | or | |
1670 | .I arg4 | |
1671 | (the key description) | |
1672 | exceeded the limit (32 bytes and 4096 bytes respectively). | |
a76439c9 | 1673 | .TP |
a02cbc78 ES |
1674 | .BR EINVAL " (Linux kernels before 4.12)" |
1675 | .I operation | |
1676 | was | |
1677 | .BR KEYCTL_DH_COMPUTE , | |
1678 | argument | |
1679 | .I arg5 | |
1680 | was non-NULL. | |
1681 | .TP | |
1682 | .B EINVAL | |
1683 | .I operation | |
1684 | was | |
1685 | .B KEYCTL_DH_COMPUTE | |
1686 | And the digest size of the hashing algorithm supplied is zero. | |
1687 | .TP | |
ff91beca MK |
1688 | .B EINVAL |
1689 | .I operation | |
1690 | was | |
3cc58bb8 MK |
1691 | .B KEYCTL_DH_COMPUTE |
1692 | and the buffer size provided is not enough to hold the result. | |
1693 | Provide 0 as a buffer size in order to obtain the minimum buffer size. | |
1694 | .TP | |
a02cbc78 ES |
1695 | .B EINVAL |
1696 | .I operation | |
1697 | was | |
1698 | .B KEYCTL_DH_COMPUTE | |
1699 | and the hash name provided in the | |
1700 | .B hashname | |
1701 | field of the | |
1702 | .B struct keyctl_kdf_params | |
1703 | pointed by | |
1704 | .I arg5 | |
1705 | argument is too big (the limit is implementation-specific and varies between | |
1706 | kernel versions, but it is deemed big enough for all valid algorithm names). | |
1707 | .TP | |
1708 | .B EINVAL | |
1709 | .\" commit 4f9dabfaf8df971f8a3b6aa324f8f817be38d538 | |
1710 | .I operation | |
1711 | was | |
1712 | .B KEYCTL_DH_COMPUTE | |
1713 | and the | |
1714 | .B __spare | |
1715 | field of the | |
1716 | .B struct keyctl_kdf_params | |
1717 | provided in | |
1718 | .I arg5 | |
1719 | argument | |
1720 | contains non-zero values. | |
1721 | .TP | |
4509c62e MK |
1722 | .B EKEYEXPIRED |
1723 | An expired key was found or specified. | |
1724 | .TP | |
4509c62e MK |
1725 | .B EKEYREJECTED |
1726 | A rejected key was found or specified. | |
1727 | .TP | |
27807c32 MK |
1728 | .B EKEYREVOKED |
1729 | A revoked key was found or specified. | |
4509c62e | 1730 | .TP |
c336c207 | 1731 | .B ELOOP |
53e88c3e | 1732 | .I operation |
8a156aca | 1733 | was |
c336c207 MK |
1734 | .BR KEYCTL_LINK |
1735 | and the requested link would cause the maximum nesting depth | |
1736 | for keyrings to be exceeded. | |
1737 | .TP | |
a02cbc78 ES |
1738 | .B EMSGSIZE |
1739 | .I operation | |
1740 | was | |
1741 | .B KEYCTL_DH_COMPUTE | |
1742 | and the buffer length exceeds | |
1743 | .B KEYCTL_KDF_MAX_OUTPUT_LEN | |
1744 | (which is 1024 currently) | |
1745 | or the | |
1746 | .B otherinfolen | |
1747 | field of | |
1748 | .B struct keyctl_kdf_parms | |
1749 | passed in | |
1750 | .I arg5 | |
1751 | exceeds | |
1752 | .B KEYCTL_KDF_MAX_OI_LEN | |
1753 | (which is 64 currently). | |
1754 | .TP | |
38590ae0 | 1755 | .BR ENFILE " (Linux kernels before 3.13)" |
3cc58bb8 | 1756 | .IR operation |
8a156aca | 1757 | was |
3cc58bb8 MK |
1758 | .BR KEYCTL_LINK |
1759 | and the keyring is full. | |
38590ae0 MK |
1760 | (Before Linux 3.13, |
1761 | .\" commit b2a4df200d570b2c33a57e1ebfa5896e4bc81b69 | |
1762 | the available space for storing keyring links was limited to | |
1763 | a single page of memory; since Linux 3.13, there is no fixed limit.) | |
3cc58bb8 MK |
1764 | .TP |
1765 | .B ENOENT | |
1766 | .I operation | |
8a156aca | 1767 | was |
3cc58bb8 MK |
1768 | .B KEYCTL_UNLINK |
1769 | and the key to be unlinked isn't linked to the keyring. | |
1770 | .TP | |
a02cbc78 ES |
1771 | .B ENOENT |
1772 | .I operation | |
1773 | was | |
1774 | .B KEYCTL_DH_COMPUTE | |
1775 | and the hashing algorithm specified in the | |
1776 | .B hashname | |
1777 | field of the | |
1778 | .B struct keyctl_kdf_params | |
1779 | pointed by | |
1780 | .I arg5 | |
1781 | argument hasn't been found. | |
1782 | .TP | |
27807c32 MK |
1783 | .B ENOKEY |
1784 | No matching key was found or an invalid key was specified. | |
fa76da80 | 1785 | .TP |
d6c7244f MK |
1786 | .B ENOKEY |
1787 | The value | |
1788 | .B KEYCTL_GET_KEYRING_ID | |
1789 | was specified in | |
53e88c3e | 1790 | .IR operation , |
d6c7244f MK |
1791 | the key specified in |
1792 | .I arg2 | |
1793 | did not exist, and | |
1794 | .I arg3 | |
1795 | was zero (meaning don't create the key if it didn't exist). | |
1796 | .TP | |
e937944e ES |
1797 | .B ENOMEM |
1798 | One of kernel memory allocation routines failed during the execution of the | |
1799 | syscall. | |
1800 | .TP | |
fa76da80 | 1801 | .B ENOTDIR |
f8aead6a MK |
1802 | A key of keyring type was expected but the ID of a key with |
1803 | a different type was provided. | |
fa76da80 | 1804 | .TP |
3cc58bb8 | 1805 | .B EOPNOTSUPP |
53e88c3e | 1806 | .I operation |
8a156aca | 1807 | was |
10c4bf22 MK |
1808 | .B KEYCTL_READ |
1809 | and the key type does not support reading | |
1810 | (e.g., the type is | |
1811 | .IR """login""" ). | |
1812 | .TP | |
1813 | .B EOPNOTSUPP | |
1814 | .I operation | |
8a156aca | 1815 | was |
3cc58bb8 MK |
1816 | .B KEYCTL_UPDATE |
1817 | and the key type does not support updating. | |
fa76da80 | 1818 | .TP |
3234dd5f MK |
1819 | .B EPERM |
1820 | .I operation | |
1821 | was | |
737d8596 MK |
1822 | .BR KEYCTL_GET_PERSISTENT , |
1823 | .I arg2 | |
1824 | specified a UID other than the calling thread's real or effective UID, | |
1825 | and the caller did not have the | |
1826 | .B CAP_SETUID | |
1827 | capability. | |
1828 | .TP | |
1829 | .B EPERM | |
1830 | .I operation | |
1831 | was | |
3234dd5f MK |
1832 | .BR KEYCTL_SESSION_TO_PARENT |
1833 | and either: | |
1834 | all of the UIDs (GIDs) of the parent process do not match | |
1835 | the effective UID (GID) of the calling process; | |
1836 | the UID of the parent's existing session keyring or | |
1837 | the UID of the caller's session keyring did not match | |
1838 | the effective UID of the caller; | |
1839 | the parent process is not single-thread; | |
1840 | or the parent process is | |
1841 | .BR init (1) | |
1842 | or a kernel thread. | |
a02cbc78 ES |
1843 | .TP |
1844 | .B ETIMEDOUT | |
1845 | .I operation | |
1846 | was | |
1847 | .B KEYCTL_DH_COMPUTE | |
1848 | and the initialisation of crypto modules has timed out. | |
a5987bfd | 1849 | .SH VERSIONS |
5685b18c | 1850 | This system call first appeared in Linux 2.6.10. |
a5987bfd MK |
1851 | .SH CONFORMING TO |
1852 | This system call is a nonstandard Linux extension. | |
60fc9e95 | 1853 | .SH NOTES |
be428596 MK |
1854 | No wrapper for this system call is provided in glibc. |
1855 | A wrapper is provided in the | |
1856 | .IR libkeyutils | |
a76439c9 | 1857 | library. |
be428596 MK |
1858 | When employing the wrapper in that library, link with |
1859 | .IR \-lkeyutils . | |
1860 | However, rather than using this system call directly, | |
1861 | you probably want to use the various library functions | |
1862 | mentioned in the descriptions of individual operations above. | |
cbf1ad35 MK |
1863 | .SH EXAMPLE |
1864 | The program below provide subset of the functionality of the | |
1865 | .BR request-key (8) | |
1866 | program provided by the | |
1867 | .I keyutils | |
1868 | package. | |
1869 | For informational purposes, | |
1870 | the program records various information in a log file. | |
efeece04 | 1871 | .PP |
cbf1ad35 MK |
1872 | As described in |
1873 | .BR request_key (2), | |
1874 | the | |
1875 | .BR request-key (8) | |
1876 | program is invoked with command-line arguments that | |
1877 | describe a key that is to be instantiated. | |
1878 | The example program fetches and logs these arguments. | |
1879 | The program assumes authority to instantiate the requested key, | |
1880 | and then instantiates that key. | |
efeece04 | 1881 | .PP |
cbf1ad35 MK |
1882 | The following shell session demonstrates the use of this program. |
1883 | In the session, | |
1884 | we compile the program and then use it to temporarily replace the standard | |
1885 | .BR request-key (8) | |
1886 | program. | |
1887 | (Note that temporarily disabling the standard | |
1888 | .BR request-key (8) | |
1889 | program may not be safe on some systems.) | |
1890 | While our example program is installed, | |
1891 | we use the example program shown in | |
1892 | .BR request_key (2) | |
1893 | to request a key. | |
efeece04 | 1894 | .PP |
cbf1ad35 | 1895 | .in +4n |
b8302363 | 1896 | .EX |
cbf1ad35 MK |
1897 | $ \fBcc \-o key_instantiate key_instantiate.c \-lkeyutils\fP |
1898 | $ \fBsudo mv /sbin/request\-key /sbin/request\-key.backup\fP | |
1899 | $ \fBsudo cp key_instantiate /sbin/request\-key\fP | |
1900 | $ \fB./t_request_key user mykey somepayloaddata\fP | |
1901 | Key ID is 20d035bf | |
1902 | $ \fBsudo mv /sbin/request\-key.backup /sbin/request\-key\fP | |
b8302363 | 1903 | .EE |
e646a1ba | 1904 | .in |
efeece04 | 1905 | .PP |
cbf1ad35 MK |
1906 | Looking at the log file created by this program, |
1907 | we can see the command-line arguments supplied to our example program: | |
efeece04 | 1908 | .PP |
cbf1ad35 | 1909 | .in +4n |
b8302363 | 1910 | .EX |
cbf1ad35 MK |
1911 | $ \fBcat /tmp/key_instantiate.log \fP |
1912 | Time: Mon Nov 7 13:06:47 2016 | |
1913 | ||
1914 | Command line arguments: | |
1915 | argv[0]: /sbin/request-key | |
1916 | operation: create | |
1917 | key_to_instantiate: 20d035bf | |
1918 | UID: 1000 | |
1919 | GID: 1000 | |
1920 | thread_keyring: 0 | |
1921 | process_keyring: 0 | |
1922 | session_keyring: 256e6a6 | |
1923 | ||
1924 | Key description: user;1000;1000;3f010000;mykey | |
1925 | Auth key payload: somepayloaddata | |
1926 | Destination keyring: 256e6a6 | |
1927 | Auth key description: .request_key_auth;1000;1000;0b010000;20d035bf | |
b8302363 | 1928 | .EE |
e646a1ba | 1929 | .in |
efeece04 | 1930 | .PP |
cbf1ad35 MK |
1931 | The last few lines of the above output show that the example program |
1932 | was able to fetch: | |
1933 | .IP * 3 | |
1934 | the description of the key to be instantiated, | |
1935 | which included the name of the key | |
1936 | .RI ( mykey ); | |
1937 | .IP * | |
1938 | the payload of the authorization key, which consisted of the data | |
1939 | .RI ( somepayloaddata ) | |
1940 | passed to | |
1941 | .BR request_key (2); | |
1942 | .IP * | |
1943 | the destination keyring that was specified in the call to | |
1944 | .BR request_key (2); | |
1945 | and | |
1946 | .IP * | |
1947 | the description of the authorization key, | |
1948 | where we can see that the name of the authorization key matches | |
1949 | the ID of the key that is to be instantiated | |
1950 | .RI ( 20d035bf ). | |
1951 | .PP | |
1952 | The example program in | |
1953 | .BR request_key (2) | |
1954 | specified the destination keyring as | |
1955 | .BR KEY_SPEC_SESSION_KEYRING . | |
1956 | By examining the contents of | |
1957 | .IR /proc/keys , | |
1958 | we can see that this was translated to the ID of the destination keyring | |
1959 | .RI ( 0256e6a6 ) | |
1960 | shown in the log output above; | |
1961 | we can also see the newly created key with the name | |
1962 | .IR mykey | |
1963 | and ID | |
1964 | .IR 20d035bf . | |
efeece04 | 1965 | .PP |
cbf1ad35 | 1966 | .in +4n |
b8302363 | 1967 | .EX |
cbf1ad35 MK |
1968 | $ \fBcat /proc/keys | egrep \(aqmykey|256e6a6\(aq\fP |
1969 | 0256e6a6 I\-\-Q\-\-\- 194 perm 3f030000 1000 1000 keyring _ses: 3 | |
1970 | 20d035bf I\-\-Q\-\-\- 1 perm 3f010000 1000 1000 user mykey: 16 | |
b8302363 | 1971 | .EE |
e646a1ba | 1972 | .in |
cbf1ad35 MK |
1973 | .SS Program source |
1974 | \& | |
e7d0bb47 | 1975 | .EX |
cbf1ad35 MK |
1976 | /* key_instantiate.c */ |
1977 | ||
1978 | #include <sys/types.h> | |
1979 | #include <keyutils.h> | |
1980 | #include <time.h> | |
1981 | #include <fcntl.h> | |
1982 | #include <stdio.h> | |
1983 | #include <stdlib.h> | |
1984 | #include <unistd.h> | |
1985 | #include <string.h> | |
1986 | #include <errno.h> | |
1987 | ||
1988 | #ifndef KEY_SPEC_REQUESTOR_KEYRING | |
1989 | #define KEY_SPEC_REQUESTOR_KEYRING \-8 | |
1990 | #endif | |
1991 | ||
1992 | int | |
1993 | main(int argc, char *argv[]) | |
1994 | { | |
1995 | FILE *fp; | |
1996 | time_t t; | |
1997 | char *operation; | |
1998 | key_serial_t key_to_instantiate, dest_keyring; | |
1999 | key_serial_t thread_keyring, process_keyring, session_keyring; | |
2000 | uid_t uid; | |
2001 | gid_t gid; | |
2002 | char dbuf[256]; | |
2003 | char auth_key_payload[256]; | |
2004 | int akp_size; /* Size of auth_key_payload */ | |
2005 | ||
2006 | fp = fopen("/tmp/key_instantiate.log", "w"); | |
2007 | if (fp == NULL) | |
2008 | exit(EXIT_FAILURE); | |
2009 | ||
2010 | setbuf(fp, NULL); | |
2011 | ||
2012 | t = time(NULL); | |
2013 | fprintf(fp, "Time: %s\\n", ctime(&t)); | |
2014 | ||
2015 | /* | |
2016 | * The kernel passes a fixed set of arguments to the program | |
2017 | * that it execs; fetch them. | |
2018 | */ | |
2019 | operation = argv[1]; | |
2020 | key_to_instantiate = atoi(argv[2]); | |
2021 | uid = atoi(argv[3]); | |
2022 | gid = atoi(argv[4]); | |
2023 | thread_keyring = atoi(argv[5]); | |
2024 | process_keyring = atoi(argv[6]); | |
2025 | session_keyring = atoi(argv[7]); | |
2026 | ||
2027 | fprintf(fp, "Command line arguments:\\n"); | |
2028 | fprintf(fp, " argv[0]: %s\\n", argv[0]); | |
2029 | fprintf(fp, " operation: %s\\n", operation); | |
2030 | fprintf(fp, " key_to_instantiate: %lx\\n", | |
2031 | (long) key_to_instantiate); | |
2032 | fprintf(fp, " UID: %ld\\n", (long) uid); | |
2033 | fprintf(fp, " GID: %ld\\n", (long) gid); | |
2034 | fprintf(fp, " thread_keyring: %lx\\n", (long) thread_keyring); | |
2035 | fprintf(fp, " process_keyring: %lx\\n", (long) process_keyring); | |
2036 | fprintf(fp, " session_keyring: %lx\\n", (long) session_keyring); | |
2037 | fprintf(fp, "\\n"); | |
2038 | ||
2039 | /* | |
2040 | * Assume the authority to instantiate the key named in argv[2] | |
2041 | */ | |
2042 | if (keyctl(KEYCTL_ASSUME_AUTHORITY, key_to_instantiate) == \-1) { | |
2043 | fprintf(fp, "KEYCTL_ASSUME_AUTHORITY failed: %s\\n", | |
2044 | strerror(errno)); | |
2045 | exit(EXIT_FAILURE); | |
2046 | } | |
2047 | ||
2048 | /* | |
2049 | * Fetch the description of the key that is to be instantiated | |
2050 | */ | |
2051 | if (keyctl(KEYCTL_DESCRIBE, key_to_instantiate, | |
2052 | dbuf, sizeof(dbuf)) == \-1) { | |
2053 | fprintf(fp, "KEYCTL_DESCRIBE failed: %s\\n", strerror(errno)); | |
2054 | exit(EXIT_FAILURE); | |
2055 | } | |
2056 | ||
2057 | fprintf(fp, "Key description: %s\\n", dbuf); | |
2058 | ||
2059 | /* | |
2060 | * Fetch the payload of the authorization key, which is | |
2061 | * actually the callout data given to request_key() | |
2062 | */ | |
2063 | akp_size = keyctl(KEYCTL_READ, KEY_SPEC_REQKEY_AUTH_KEY, | |
2064 | auth_key_payload, sizeof(auth_key_payload)); | |
2065 | if (akp_size == \-1) { | |
2066 | fprintf(fp, "KEYCTL_READ failed: %s\\n", strerror(errno)); | |
2067 | exit(EXIT_FAILURE); | |
2068 | } | |
2069 | ||
2070 | auth_key_payload[akp_size] = \(aq\\0\(aq; | |
2071 | fprintf(fp, "Auth key payload: %s\\n", auth_key_payload); | |
2072 | ||
2073 | /* | |
2074 | * For interest, get the ID of the authorization key and | |
2075 | * display it. | |
2076 | */ | |
2077 | auth_key = keyctl(KEYCTL_GET_KEYRING_ID, | |
2078 | KEY_SPEC_REQKEY_AUTH_KEY); | |
2079 | if (auth_key == \-1) { | |
2080 | fprintf(fp, "KEYCTL_GET_KEYRING_ID failed: %s\\n", | |
2081 | strerror(errno)); | |
2082 | exit(EXIT_FAILURE); | |
2083 | } | |
2084 | ||
2085 | fprintf(fp, "Auth key ID: %lx\\n", (long) auth_key); | |
2086 | ||
2087 | /* | |
2088 | * Fetch key ID for the request_key(2) destination keyring. | |
2089 | */ | |
2090 | dest_keyring = keyctl(KEYCTL_GET_KEYRING_ID, | |
2091 | KEY_SPEC_REQUESTOR_KEYRING); | |
2092 | if (dest_keyring == \-1) { | |
2093 | fprintf(fp, "KEYCTL_GET_KEYRING_ID failed: %s\\n", | |
2094 | strerror(errno)); | |
2095 | exit(EXIT_FAILURE); | |
2096 | } | |
2097 | ||
2098 | fprintf(fp, "Destination keyring: %lx\\n", (long) dest_keyring); | |
2099 | ||
2100 | /* | |
2101 | * Fetch the description of the authorization key. This | |
2102 | * allows us to see the key type, UID, GID, permissions, | |
2103 | * and description (name) of the key. Among other things, | |
2104 | * we will see that the name of the key is a hexadecimal | |
2105 | * string representing the ID of the key to be instantiated. | |
2106 | */ | |
2107 | if (keyctl(KEYCTL_DESCRIBE, KEY_SPEC_REQKEY_AUTH_KEY, | |
2108 | dbuf, sizeof(dbuf)) == \-1) { | |
2109 | fprintf(fp, "KEYCTL_DESCRIBE failed: %s\\n", strerror(errno)); | |
2110 | exit(EXIT_FAILURE); | |
2111 | } | |
2112 | ||
2113 | fprintf(fp, "Auth key description: %s\\n", dbuf); | |
2114 | ||
2115 | /* | |
2116 | * Instantiate the key using the callout data that was supplied | |
2117 | * in the payload of the authorization key. | |
2118 | */ | |
2119 | if (keyctl(KEYCTL_INSTANTIATE, key_to_instantiate, | |
2120 | auth_key_payload, akp_size + 1, dest_keyring) == \-1) { | |
2121 | fprintf(fp, "KEYCTL_INSTANTIATE failed: %s\\n", | |
2122 | strerror(errno)); | |
2123 | exit(EXIT_FAILURE); | |
2124 | } | |
2125 | ||
2126 | exit(EXIT_SUCCESS); | |
2127 | } | |
e7d0bb47 | 2128 | .EE |
4509c62e | 2129 | .SH SEE ALSO |
e264f024 MK |
2130 | .ad l |
2131 | .nh | |
4509c62e | 2132 | .BR keyctl (1), |
4509c62e | 2133 | .BR add_key (2), |
4509c62e | 2134 | .BR request_key (2), |
f011ea55 MK |
2135 | .\" .BR find_key_by_type_and_name (3) |
2136 | .\" There is a man page, but this function seems not to exist | |
2137 | .BR keyctl (3), | |
2138 | .BR keyctl_assume_authority (3), | |
4509c62e | 2139 | .BR keyctl_chown (3), |
4509c62e | 2140 | .BR keyctl_clear (3), |
cf4d4361 DP |
2141 | .BR keyctl_describe (3), |
2142 | .BR keyctl_describe_alloc (3), | |
2143 | .BR keyctl_get_keyring_ID (3), | |
f011ea55 MK |
2144 | .BR keyctl_get_persistent (3), |
2145 | .BR keyctl_get_security (3), | |
2146 | .BR keyctl_get_security_alloc (3), | |
4509c62e | 2147 | .BR keyctl_instantiate (3), |
f011ea55 MK |
2148 | .BR keyctl_instantiate_iov (3), |
2149 | .BR keyctl_invalidate (3), | |
cf4d4361 DP |
2150 | .BR keyctl_join_session_keyring (3), |
2151 | .BR keyctl_link (3), | |
4509c62e | 2152 | .BR keyctl_negate (3), |
d8f1a35c MK |
2153 | .BR keyctl_read (3), |
2154 | .BR keyctl_read_alloc (3), | |
f011ea55 | 2155 | .BR keyctl_reject (3), |
cf4d4361 DP |
2156 | .BR keyctl_revoke (3), |
2157 | .BR keyctl_search (3), | |
f011ea55 | 2158 | .BR keyctl_session_to_parent (3), |
4509c62e | 2159 | .BR keyctl_set_reqkey_keyring (3), |
4509c62e | 2160 | .BR keyctl_set_timeout (3), |
d8f1a35c | 2161 | .BR keyctl_setperm (3), |
cf4d4361 DP |
2162 | .BR keyctl_unlink (3), |
2163 | .BR keyctl_update (3), | |
f011ea55 MK |
2164 | .BR recursive_key_scan (3), |
2165 | .BR recursive_session_key_scan (3), | |
0e5c391f MK |
2166 | .BR capabilities (7), |
2167 | .BR credentials (7), | |
32fc2407 | 2168 | .BR keyrings (7), |
f011ea55 | 2169 | .BR keyutils (7), |
46c0179a MK |
2170 | .BR persistent\-keyring (7), |
2171 | .BR process\-keyring (7), | |
2172 | .BR session\-keyring (7), | |
2173 | .BR thread\-keyring (7), | |
2174 | .BR user\-keyring (7), | |
0e5c391f | 2175 | .BR user\-namespaces (7), |
46c0179a MK |
2176 | .BR user\-session\-keyring (7), |
2177 | .BR request\-key (8) | |
efeece04 | 2178 | .PP |
514c8256 | 2179 | The kernel source files under |
954be1b9 MK |
2180 | .IR Documentation/security/keys/ |
2181 | (or, before Linux 4.13, in the file | |
2182 | .IR Documentation/security/keys.txt ). |