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