]>
Commit | Line | Data |
---|---|---|
4509c62e MK |
1 | .\" Copyright (C) 2006 Red Hat, Inc. All Rights Reserved. |
2 | .\" Written by David Howells (dhowells@redhat.com) | |
3 | .\" | |
23dbdcbe | 4 | .\" %%%LICENSE_START(GPLv2+_SW_ONEPARA) |
4509c62e MK |
5 | .\" This program is free software; you can redistribute it and/or |
6 | .\" modify it under the terms of the GNU General Public License | |
7 | .\" as published by the Free Software Foundation; either version | |
8 | .\" 2 of the License, or (at your option) any later version. | |
722b6788 | 9 | .\" %%%LICENSE_END |
4509c62e | 10 | .\" |
67d2c687 | 11 | .TH KEYCTL 2 2015-05-07 Linux "Linux Key Management Calls" |
4509c62e | 12 | .SH NAME |
f68512e9 | 13 | keyctl \- manipulate the kernel's key management facility |
4509c62e MK |
14 | .SH SYNOPSIS |
15 | .nf | |
16 | .B #include <keyutils.h> | |
17 | .sp | |
fa76da80 ES |
18 | .BI "long keyctl(int " cmd ", ...)" |
19 | .sp | |
60fc9e95 | 20 | .B "/* For direct call via syscall(2): */" |
fa76da80 ES |
21 | .B #include <asm/unistd.h> |
22 | .B #include <linux/keyctl.h> | |
23 | .B #include <unistd.h> | |
24 | .sp | |
9a9febc8 MK |
25 | .BI "long syscall(__NR_keyctl, int " option ", __kernel_ulong_t " arg2 , |
26 | .BI " __kernel_ulong_t " arg3 ", __kernel_ulong_t " arg4 , | |
27 | .BI " __kernel_ulong_t " arg5 ); | |
6030f2d8 | 28 | .fi |
4509c62e MK |
29 | .SH DESCRIPTION |
30 | .BR keyctl () | |
60fc9e95 MK |
31 | allows user-space programs to perform key manipulation. |
32 | ||
33 | The operation performed by | |
fa76da80 | 34 | .BR keyctl () |
60fc9e95 MK |
35 | is determined by the value of the |
36 | .I option | |
37 | argument. | |
38 | Each of these operations is wrapped by | |
39 | .B libkeyutils | |
40 | into individual functions (listed under SEE ALSO) | |
41 | to permit the compiler to check types. | |
42 | ||
43 | The permitted values for | |
fa76da80 | 44 | .I option |
60fc9e95 | 45 | are: |
4509c62e | 46 | .TP |
a92d3bb4 | 47 | .B KEYCTL_GET_KEYRING_ID |
60fc9e95 | 48 | Ask for a keyring whose ID is provided in |
fa76da80 ES |
49 | .I arg2 |
50 | (converted to | |
51 | .IR key_serial_t ). | |
52 | If the | |
53 | .I arg3 | |
60fc9e95 MK |
54 | argument contains a non-zero value, a new keyring is created. |
55 | ||
56 | The caller must have | |
fa76da80 | 57 | .I search |
60fc9e95 MK |
58 | permission on a keyring in order for it to be found. |
59 | ||
60 | The arguments | |
61 | .IR arg4 | |
62 | and | |
63 | .IR arg5 | |
fa76da80 | 64 | are ignored. |
4509c62e | 65 | .TP |
a92d3bb4 | 66 | .B KEYCTL_JOIN_SESSION_KEYRING |
60fc9e95 | 67 | Create a new anonymous session keyring (in case |
fa76da80 ES |
68 | .I arg2 |
69 | is | |
70 | .BR NULL ) | |
60fc9e95 | 71 | or join an existing named session keyring |
fa76da80 | 72 | .RI ( arg2 |
60fc9e95 MK |
73 | should be a pointer to a string containing session name in this case). |
74 | ||
75 | The caller must have | |
fa76da80 | 76 | .I search |
60fc9e95 | 77 | permission on the keyring name which is provided in order |
461a8ce5 | 78 | to successfully join. |
60fc9e95 MK |
79 | |
80 | The arguments | |
81 | .IR arg3 , | |
82 | .IR arg4 , | |
83 | and | |
84 | .IR arg5 | |
fa76da80 | 85 | are ignored. |
4509c62e | 86 | .TP |
a92d3bb4 | 87 | .B KEYCTL_UPDATE |
60fc9e95 | 88 | Update a key's data payload. |
461a8ce5 | 89 | The |
fa76da80 ES |
90 | .I arg2 |
91 | argument (converted to | |
92 | .IR key_serial_t ) | |
60fc9e95 MK |
93 | should contain the key ID. |
94 | The | |
fa76da80 ES |
95 | .I arg3 |
96 | argument is interpreted as a pointer to the new payload and | |
97 | .I arg4 | |
98 | (converted to | |
99 | .IR size_t ) | |
60fc9e95 MK |
100 | should contain the payload size in bytes. |
101 | ||
102 | The caller must have | |
fa76da80 | 103 | .I write |
60fc9e95 MK |
104 | permission on the key specified and the key type must support updating. |
105 | A negative key can be positively instantiated with this call. | |
106 | ||
461a8ce5 | 107 | The |
fa76da80 ES |
108 | .I arg5 |
109 | argument is ignored. | |
4509c62e | 110 | .TP |
a92d3bb4 | 111 | .B KEYCTL_REVOKE |
60fc9e95 | 112 | Revoke the key with the ID provided in |
fa76da80 ES |
113 | .I arg2 |
114 | (converted to | |
115 | .IR key_serial_t ). | |
60fc9e95 MK |
116 | |
117 | The caller must have | |
fa76da80 | 118 | .IR write " or " setattr |
60fc9e95 MK |
119 | permission on they key. |
120 | ||
121 | The arguments | |
122 | .IR arg3 , | |
123 | .IR arg4 , | |
124 | and | |
125 | .IR arg5 | |
fa76da80 | 126 | are ignored. |
4509c62e | 127 | .TP |
a92d3bb4 | 128 | .B KEYCTL_CHOWN |
60fc9e95 | 129 | Set the ownership of a key. |
461a8ce5 | 130 | The |
fa76da80 ES |
131 | .I arg2 |
132 | argument (converted to | |
133 | .IR key_serial_t ) | |
60fc9e95 MK |
134 | contains the key ID. |
135 | The | |
fa76da80 ES |
136 | .I arg3 |
137 | argument (converted to | |
138 | .IR uid_t ) | |
60fc9e95 MK |
139 | contains the new user ID (or \-1 in case the user ID shouldn't be changed). |
140 | The | |
fa76da80 ES |
141 | .I arg4 |
142 | argument (converted to | |
143 | .IR gid_t ) | |
60fc9e95 | 144 | contains the new group ID (or \-1 in case the group ID shouldn't be changed). |
fa76da80 ES |
145 | The key must grant the caller |
146 | .I setattr | |
461a8ce5 MK |
147 | permission. |
148 | For the UID to be changed, or for the GID to be changed to a group | |
60fc9e95 MK |
149 | the caller is not a member of, the caller must have the |
150 | .B CAP_SYS_ADMIN | |
fa76da80 | 151 | capability (see |
60fc9e95 | 152 | .BR capabilities (7)). |
461a8ce5 MK |
153 | If the UID is to be changed, the new user must have sufficient |
154 | quota to accept the key. | |
155 | The quota deduction will be removed from the old user | |
156 | to the new user should the attribute be changed. | |
60fc9e95 | 157 | |
461a8ce5 | 158 | The |
fa76da80 ES |
159 | .I arg5 |
160 | argument is ignored. | |
4509c62e | 161 | .TP |
a92d3bb4 | 162 | .B KEYCTL_SETPERM |
60fc9e95 | 163 | Change the permissions of the key with the ID provided in the |
fa76da80 ES |
164 | .I arg2 |
165 | argument (converted to | |
166 | .IR key_serial_t ) | |
60fc9e95 | 167 | to the permissions provided in the |
fa76da80 ES |
168 | .I arg3 |
169 | argument (converted to | |
170 | .IR key_perms_t ). | |
171 | The key must grant | |
172 | .I setattr | |
461a8ce5 MK |
173 | permission to the caller. |
174 | If the caller doesn't have | |
60fc9e95 MK |
175 | .B CAP_SYS_ADMIN |
176 | capability, it can change permissions only for the keys it owns. | |
177 | Permissions contains a mask of available operations for possessor | |
461a8ce5 | 178 | (since Linux 2.6.14), user, group, other. |
60fc9e95 | 179 | Each mask is eight bits in size, with only six bits currently used. |
461a8ce5 | 180 | The available permissions are: |
fa76da80 ES |
181 | .RS |
182 | .IP \(bu 3 | |
183 | .BR View . | |
461a8ce5 MK |
184 | Allows reading attributes of a key. |
185 | Needed for | |
60fc9e95 | 186 | .BR KEYCTL_DESCRIBE . |
fa76da80 ES |
187 | .IP \(bu |
188 | .BR Read . | |
60fc9e95 | 189 | Allows reading a key's payload. |
461a8ce5 | 190 | Needed for |
60fc9e95 | 191 | .BR KEYCTL_READ . |
fa76da80 ES |
192 | .IP \(bu |
193 | .BR Write . | |
60fc9e95 MK |
194 | Allows update or instantiation of a key's payload. |
195 | For a keyring, it enables addition and removal of keys to a keyring. | |
461a8ce5 | 196 | Needed for |
60fc9e95 MK |
197 | .BR KEYCTL_UPDATE , |
198 | .BR KEYCTL_REVOKE , | |
199 | .BR KEYCTL_CLEAR , | |
200 | .BR KEYCTL_LINK , | |
201 | and | |
202 | .BR KEYCTL_UNLINK . | |
fa76da80 ES |
203 | .IP \(bu |
204 | .BR Search . | |
461a8ce5 MK |
205 | This permits keyrings to be searched and keys to be found. |
206 | Searches can only recurse into nested keyrings | |
207 | that have search permission set. | |
208 | Needed for | |
60fc9e95 MK |
209 | .BR KEYCTL_GET_KEYRING_ID , |
210 | .BR KEYCTL_JOIN_SESSION_KEYRING , | |
211 | .BR KEYCTL_SEARCH , | |
212 | and | |
213 | .BR KEYCTL_INVALIDATE . | |
fa76da80 ES |
214 | .IP \(bu |
215 | .BR Link . | |
461a8ce5 MK |
216 | This permits a key or keyring to be linked to. |
217 | Needed for | |
60fc9e95 MK |
218 | .BR KEYCTL_LINK |
219 | and | |
220 | .BR KEYCTL_SESSION_TO_PARENT . | |
fa76da80 | 221 | .IP \(bu |
60fc9e95 MK |
222 | .BR "Set attribute" " (since Linux 2.6.15)." |
223 | This permits a key's UID, GID, and permissions mask to be changed. | |
461a8ce5 | 224 | Needed for |
60fc9e95 MK |
225 | .BR KEYCTL_REVOKE , |
226 | .BR KEYCTL_CHOWN , | |
227 | and | |
228 | .BR KEYCTL_SETPERM . | |
fa76da80 ES |
229 | .RE |
230 | .IP | |
231 | The | |
232 | .IR arg4 " and " arg5 | |
233 | arguments are ignored. | |
4509c62e | 234 | .TP |
a92d3bb4 | 235 | .B KEYCTL_DESCRIBE |
461a8ce5 | 236 | Describe a key. |
60fc9e95 | 237 | The ID of the key to be described should be provided in the |
fa76da80 ES |
238 | .I arg2 |
239 | argument (converted to | |
60fc9e95 MK |
240 | .IR key_serial_t ). |
241 | The | |
fa76da80 | 242 | .I arg3 |
60fc9e95 | 243 | argument should point to the destination buffer (of type |
fa76da80 ES |
244 | .IR "char *" ), |
245 | and the | |
246 | .I arg4 | |
247 | argument should contain size of the buffer (of kernel's | |
248 | .I size_t | |
461a8ce5 MK |
249 | type). |
250 | The key must grant the caller | |
fa76da80 | 251 | .I view |
461a8ce5 | 252 | permission. |
60fc9e95 | 253 | Writing to the buffer is attempted only when the buffer is non-NULL and |
fa76da80 ES |
254 | has enough space to accept the description. |
255 | '\" Function commentary says it copies up to buflen bytes, bu see the | |
256 | '\" (buffer && buflen >= ret) condition in keyctl_describe_key() in | |
257 | '\" security/keyctl.c | |
60fc9e95 | 258 | The description itself is provided in the format: |
fa76da80 ES |
259 | .RS |
260 | .IP | |
261 | .IR type ; uid ; gid ; perm ; description "<NUL>" | |
262 | .RE | |
263 | .IP | |
461a8ce5 | 264 | The |
fa76da80 ES |
265 | .I arg5 |
266 | argument is ignored. | |
4509c62e | 267 | .TP |
a92d3bb4 | 268 | .B KEYCTL_CLEAR |
60fc9e95 | 269 | Clear the contents of the keyring with the ID provided in the |
fa76da80 ES |
270 | .I arg2 |
271 | argument (converted to | |
272 | .IR key_serial_t ). | |
60fc9e95 MK |
273 | |
274 | The caller must have | |
fa76da80 | 275 | .I write |
461a8ce5 | 276 | permission. |
60fc9e95 MK |
277 | |
278 | The arguments | |
279 | .IR arg3 , | |
280 | .IR arg4 , | |
281 | and | |
282 | .IR arg5 | |
fa76da80 | 283 | are ignored. |
4509c62e | 284 | .TP |
a92d3bb4 | 285 | .B KEYCTL_LINK |
fa76da80 ES |
286 | Link a key (provided in the |
287 | .I arg2 | |
288 | argument converted to | |
289 | .I key_serial_t | |
290 | type) to a keyring (provided in the | |
291 | .I arg3 | |
292 | argument converted to | |
293 | .I key_serial_t | |
294 | type) of there is no matching key in the keyring, or replace the link | |
461a8ce5 | 295 | to the matching key with a link to the new key. |
60fc9e95 MK |
296 | |
297 | The caller must have | |
fa76da80 ES |
298 | .I link |
299 | permission on the key being added and | |
300 | .I write | |
461a8ce5 | 301 | permission on the keyring to which key being added to. |
60fc9e95 MK |
302 | |
303 | The arguments | |
304 | .IR arg4 | |
305 | and | |
306 | .IR arg5 | |
fa76da80 | 307 | are ignored. |
4509c62e | 308 | .TP |
a92d3bb4 | 309 | .B KEYCTL_UNLINK |
fa76da80 ES |
310 | Unlink a key (provided in the |
311 | .I arg2 | |
312 | argument converted to | |
313 | .I key_serial_t | |
314 | type) from a keyring (provided in the | |
315 | .I arg3 | |
316 | argument converted to | |
317 | .I key_serial_t | |
461a8ce5 | 318 | type). |
60fc9e95 MK |
319 | |
320 | The caller must have | |
fa76da80 | 321 | .I write |
60fc9e95 MK |
322 | permission on the keyring from which the key is being removed. |
323 | ||
461a8ce5 | 324 | If the last link |
60fc9e95 MK |
325 | to a key is removed, then that key will be scheduled for destruction. |
326 | ||
327 | The arguments | |
328 | .IR arg4 | |
329 | and | |
330 | .IR arg5 | |
fa76da80 | 331 | are ignored. |
4509c62e | 332 | .TP |
a92d3bb4 | 333 | .B KEYCTL_SEARCH |
60fc9e95 | 334 | Search for a key in a keyring with the ID provided in the |
fa76da80 ES |
335 | .I arg2 |
336 | argument (converted to | |
337 | .I key_serial_t | |
461a8ce5 MK |
338 | type). |
339 | The | |
fa76da80 ES |
340 | .I arg3 |
341 | argument should be a | |
342 | .I char * | |
60fc9e95 MK |
343 | pointing to the name of the type of the key being searched for |
344 | (NUL-terminated character string up to 32 bytes in size), and the | |
fa76da80 ES |
345 | .I arg4 |
346 | argument should be a | |
347 | .I char * | |
60fc9e95 MK |
348 | pointing to a NUL-terminated character string (up to 4096 bytes in size) |
349 | with the description of the key being searched for. | |
461a8ce5 | 350 | The search is performed recursively |
60fc9e95 | 351 | starting from the keyring with the ID provided in |
fa76da80 ES |
352 | .IR arg2 . |
353 | Only keyrings that grant the caller | |
354 | .I search | |
355 | permission will be searched (this includes the starting keyring). | |
356 | Only keys with | |
357 | .I search | |
461a8ce5 | 358 | permission can be found. |
60fc9e95 | 359 | |
461a8ce5 | 360 | If the |
fa76da80 ES |
361 | .I arg5 |
362 | argument (converted to | |
363 | .I key_serial_t | |
60fc9e95 | 364 | type) contains a non-zero value, it is interpreted as a keyring ID to which |
fa76da80 | 365 | the found key should be linked. |
4509c62e | 366 | .TP |
a92d3bb4 | 367 | .B KEYCTL_READ |
60fc9e95 | 368 | Read the payload of the key whose ID is provided in the |
fa76da80 ES |
369 | .I arg2 |
370 | argument (converted to | |
371 | .I key_serial_t | |
60fc9e95 MK |
372 | type). |
373 | The payload is placed in the buffer pointed by the | |
fa76da80 ES |
374 | .I arg3 |
375 | argument (converted to | |
376 | .I char * | |
60fc9e95 MK |
377 | type); |
378 | the size of that buffer must be provided in the | |
fa76da80 ES |
379 | .I arg4 |
380 | argument (converted to kernel's | |
381 | .I size_t | |
461a8ce5 MK |
382 | type). |
383 | The key must either grant the caller | |
fa76da80 ES |
384 | .I read |
385 | permission, or it must grant the caller | |
386 | .I search | |
461a8ce5 | 387 | permission when searched for from the process keyrings. |
60fc9e95 | 388 | |
461a8ce5 | 389 | The |
fa76da80 ES |
390 | .I arg5 |
391 | argument is ignored. | |
4509c62e | 392 | .TP |
a92d3bb4 | 393 | .B KEYCTL_INSTANTIATE |
60fc9e95 | 394 | Instantiate a partially constructed key whose ID is provided in the |
fa76da80 ES |
395 | .I arg2 |
396 | argument (converted to | |
397 | .I key_serial_t | |
398 | type) with a payload pointed by the | |
399 | .I arg3 | |
400 | argument (converted to | |
401 | .I char * | |
402 | type) of size provided in the | |
403 | .I arg4 | |
404 | argument (converted to kernel's | |
405 | .I size_t | |
461a8ce5 | 406 | type). |
60fc9e95 | 407 | The instantiated key will be linked to the keyring ID which is provided in the |
fa76da80 ES |
408 | .I arg5 |
409 | argument (converted to | |
410 | .I key_serial_t | |
461a8ce5 MK |
411 | type). |
412 | The caller must have the appropriate instantiation permit set (auth key). | |
60fc9e95 | 413 | |
4509c62e | 414 | .TP |
a92d3bb4 | 415 | .B KEYCTL_NEGATE |
60fc9e95 | 416 | Negatively instantiate a partially constructed key with the ID provided in the |
fa76da80 ES |
417 | .I arg2 |
418 | argument (converted to | |
419 | .I key_serial_t | |
60fc9e95 | 420 | type), setting the timeout (in seconds) to the value provided in the |
fa76da80 ES |
421 | .I arg3 |
422 | argument (converted to | |
423 | .I unsigned int | |
461a8ce5 | 424 | type). |
60fc9e95 | 425 | The instantiated key will be linked to the keyring ID which is provided in the |
fa76da80 ES |
426 | .I arg4 |
427 | argument (converted to | |
428 | .I key_serial_t | |
461a8ce5 | 429 | type). |
60fc9e95 | 430 | |
461a8ce5 | 431 | The caller must have the appropriate instantiation permit set |
60fc9e95 MK |
432 | (authorization key, see |
433 | .B KEYCTL_ASSUME_AUTHORITY | |
461a8ce5 | 434 | command). |
60fc9e95 | 435 | |
461a8ce5 | 436 | Negative keys are used to rate limit repeated |
60fc9e95 MK |
437 | .BR request_key (2) |
438 | calls by causing them to fail with the error | |
439 | .B ENOKEY | |
461a8ce5 | 440 | until the negative key expires. |
60fc9e95 MK |
441 | |
442 | This is equivalent to the call | |
443 | ||
444 | keyctl(KEYCTL_REJECT, arg2, arg3, ENOKEY, arg4); | |
445 | ||
fa76da80 ES |
446 | The |
447 | .I arg5 | |
448 | argument is ignored. | |
8ec6a211 | 449 | .TP |
fa76da80 | 450 | .BR KEYCTL_SET_REQKEY_KEYRING " (since Linux 2.6.13)" |
60fc9e95 MK |
451 | Read or set the default keyring in which |
452 | .BR request_key (2) | |
461a8ce5 MK |
453 | will cache keys. |
454 | The | |
fa76da80 ES |
455 | .I arg2 |
456 | argument (converted to | |
457 | .I int | |
458 | type) should contain one of the following values, defined in | |
459 | .IR <linux/keyring.h> : | |
d1d5839d MK |
460 | .RS |
461 | .TP 33 | |
462 | .BR KEY_REQKEY_DEFL_NO_CHANGE | |
463 | No change. | |
464 | .TP | |
465 | .BR KEY_REQKEY_DEFL_DEFAULT | |
466 | Default keyring. | |
467 | .TP | |
468 | .BR KEY_REQKEY_DEFL_THREAD_KEYRING | |
469 | Thread-specific keyring. | |
470 | .TP | |
471 | .BR KEY_REQKEY_DEFL_PROCESS_KEYRING | |
472 | Process-specific keyring. | |
473 | .TP | |
474 | .BR KEY_REQKEY_DEFL_SESSION_KEYRING | |
475 | Session-specific keyring. | |
476 | .TP | |
477 | .BR KEY_REQKEY_DEFL_USER_KEYRING | |
478 | UID-specific keyring. | |
479 | .TP | |
480 | .BR KEY_REQKEY_DEFL_USER_SESSION_KEYRING 5 | |
481 | Session keyring of UID. | |
482 | .TP | |
483 | .BR KEY_REQKEY_DEFL_REQUESTOR_KEYRING " (since Linux 2.6.29)" | |
fa76da80 | 484 | '\" 8bbf4976b59fc9fc2861e79cab7beb3f6d647640 |
d1d5839d MK |
485 | Requestor keyring. |
486 | .RE | |
487 | .IP | |
60fc9e95 MK |
488 | All other values are invalid (including the as-yet-unsupported |
489 | .BR KEY_REQKEY_DEFL_GROUP_KEYRING ). | |
490 | ||
491 | The arguments | |
492 | .IR arg3 , | |
493 | .IR arg4 , | |
494 | and | |
495 | .IR arg5 | |
fa76da80 | 496 | are ignored. |
8ec6a211 | 497 | .TP |
fa76da80 | 498 | .BR KEYCTL_SET_TIMEOUT " (since Linux 2.6.16)" |
461a8ce5 MK |
499 | Set timeout on a key. |
500 | ID of a key provided in the | |
fa76da80 ES |
501 | .I arg2 |
502 | argument (converted to | |
503 | .I key_serial_t | |
504 | type), timeout value (in seconds from current time) provided in the | |
505 | .I arg3 | |
506 | argument (converted to | |
507 | .I unsigned int | |
461a8ce5 | 508 | type). |
60fc9e95 MK |
509 | |
510 | The caller must either have the | |
fa76da80 | 511 | .I setattr |
60fc9e95 MK |
512 | permission or hold an instantiation authorization token for the key. |
513 | ||
514 | A timeout value of 0 clears the timeout. | |
461a8ce5 MK |
515 | The key and any links to the key will be |
516 | automatically garbage collected after the timeout expires. | |
60fc9e95 MK |
517 | |
518 | The arguments | |
519 | .IR arg4 | |
520 | and | |
521 | .IR arg5 | |
fa76da80 | 522 | are ignored. |
8ec6a211 | 523 | .TP |
fa76da80 | 524 | .BR KEYCTL_ASSUME_AUTHORITY " (since Linux 2.6.16)" |
461a8ce5 | 525 | Assume (or clear) the authority for the key instantiation. |
60fc9e95 | 526 | The ID of the authorization key provided in the |
fa76da80 ES |
527 | .I arg2 |
528 | argument (converted to | |
529 | .I key_serial_t | |
461a8ce5 | 530 | type). |
60fc9e95 | 531 | |
461a8ce5 | 532 | The caller must have the instantiation key in their process keyrings |
fa76da80 ES |
533 | with a |
534 | .I search | |
461a8ce5 | 535 | permission grant available to the caller. |
60fc9e95 | 536 | |
461a8ce5 | 537 | If the ID given in the |
fa76da80 | 538 | .I arg2 |
461a8ce5 | 539 | argument is 0, then the setting will be cleared. |
60fc9e95 MK |
540 | |
541 | The arguments | |
542 | .IR arg3 , | |
543 | .IR arg4 , | |
544 | and | |
545 | .IR arg5 | |
fa76da80 ES |
546 | are ignored. |
547 | .TP | |
548 | .BR KEYCTL_GET_SECURITY " (since Linux 2.6.26)" | |
60fc9e95 | 549 | Get the LSM security label of the specified key. |
461a8ce5 | 550 | The ID of the key should be provided in the |
fa76da80 ES |
551 | .I arg2 |
552 | argument (converted to | |
553 | .I key_serial_t | |
461a8ce5 | 554 | type). |
60fc9e95 | 555 | The buffer where the security label should be stored is provided in the |
fa76da80 ES |
556 | .I arg3 |
557 | argument (converted to | |
558 | .I char * | |
559 | type) with its size provided in the | |
560 | .I arg4 | |
561 | argument (converted to kernel's | |
562 | .I size_t | |
461a8ce5 | 563 | type). |
60fc9e95 | 564 | |
461a8ce5 | 565 | The |
fa76da80 ES |
566 | .I arg5 |
567 | argument is ignored. | |
568 | .TP | |
569 | .BR KEYCTL_SESSION_TO_PARENT " (since Linux 2.6.32)" | |
570 | Apply session keyring to parent process. | |
571 | .IP | |
461a8ce5 MK |
572 | Attempt to install the calling process's session keyring |
573 | on the process's parent process. | |
574 | The keyring must exist and must grant the caller | |
fa76da80 | 575 | .I link |
60fc9e95 MK |
576 | permission, and the parent process must be single-threaded and have |
577 | the same effective ownership as this process | |
578 | and must not be be set-user-ID or set-group-ID. | |
fa76da80 ES |
579 | .IP |
580 | The keyring will be emplaced on the parent when it next resumes userspace. | |
60fc9e95 MK |
581 | |
582 | The arguments | |
583 | .IR arg2 , | |
584 | .IR arg3 , | |
585 | .IR arg4 , | |
586 | and | |
587 | .IR arg5 | |
fa76da80 ES |
588 | are ignored. |
589 | .TP | |
590 | .BR KEYCTL_REJECT " (since Linux 2.6.39)" | |
60fc9e95 | 591 | Negatively instantiate a partially constructed key with the ID provided in the |
fa76da80 ES |
592 | .I arg2 |
593 | argument (converted to | |
594 | .I key_serial_t | |
595 | type), setting timeout (in seconds) to the value provided in the | |
596 | .I arg3 | |
597 | argument (converted to | |
598 | .I unsigned int | |
599 | type) and instantiation error to the value provided in the | |
600 | .I arg4 | |
601 | argument (converted to | |
602 | .I unsigned int | |
461a8ce5 | 603 | type). |
60fc9e95 | 604 | The instantiated key will be linked to the keyring ID which is provided in the |
fa76da80 ES |
605 | .I arg5 |
606 | argument (converted to | |
607 | .I key_serial_t | |
461a8ce5 | 608 | type). |
60fc9e95 | 609 | |
461a8ce5 | 610 | The caller must have the appropriate instantiation permit set |
60fc9e95 MK |
611 | (authorization key, see |
612 | .B KEYCTL_ASSUME_AUTHORITY | |
461a8ce5 MK |
613 | command). |
614 | Negative keys are used to rate limit repeated | |
60fc9e95 | 615 | .BR request_key (2) |
fa76da80 ES |
616 | calls by causing them to return the error specified until the negative key |
617 | expires. | |
618 | .TP | |
619 | .BR KEYCTL_INSTANTIATE_IOV " (since Linux 2.6.39)" | |
60fc9e95 | 620 | Instantiate a key (with the ID specified in the |
fa76da80 ES |
621 | .I arg2 |
622 | argument of type | |
623 | .IR key_serial_t ) | |
624 | with the specified (in the | |
625 | .I arg3 | |
626 | argument of type | |
627 | .IR "const struct iovec *" ) | |
628 | multipart payload and link the key into | |
60fc9e95 | 629 | the destination keyring (whose ID is provided in the |
fa76da80 ES |
630 | .I arg4 |
631 | argument of type | |
632 | .IR key_serial_t ) | |
461a8ce5 | 633 | if non-zero one is given. |
60fc9e95 | 634 | |
461a8ce5 | 635 | The caller must have the appropriate instantiation |
60fc9e95 MK |
636 | permit (authorization key, see |
637 | .B KEYCTL_ASSUME_AUTHORITY | |
461a8ce5 MK |
638 | command) set for this to work. |
639 | No other permissions are required. | |
60fc9e95 | 640 | |
461a8ce5 | 641 | The |
fa76da80 ES |
642 | .I arg5 |
643 | argument is ignored. | |
644 | .TP | |
645 | .BR KEYCTL_INVALIDATE " (since Linux 3.5)" | |
60fc9e95 | 646 | Invalidate a key with the ID provided in the |
fa76da80 ES |
647 | .I arg2 |
648 | argument (converted to | |
649 | .I key_serial_t | |
461a8ce5 | 650 | type). |
60fc9e95 | 651 | |
461a8ce5 | 652 | The caller must have |
fa76da80 | 653 | .I search |
461a8ce5 | 654 | permission in order to perform invalidation. |
60fc9e95 | 655 | |
461a8ce5 MK |
656 | The key and any links to the key |
657 | will be automatically garbage collected immediately. | |
60fc9e95 MK |
658 | |
659 | The arguments | |
660 | .IR arg3 , | |
661 | .IR arg4 , | |
662 | and | |
663 | .IR arg5 | |
fa76da80 ES |
664 | are ignored. |
665 | .TP | |
666 | .BR KEYCTL_GET_PERSISTENT " (since Linux 3.13)" | |
667 | Get the persistent keyring of the user specified in the | |
668 | .I arg2 | |
669 | (converted to | |
670 | .I uid_t | |
60fc9e95 | 671 | type) and link it to the keyring with the ID provided in the |
fa76da80 ES |
672 | .I arg3 |
673 | argument (converted to | |
674 | .I key_serial_t | |
461a8ce5 | 675 | type). |
60fc9e95 MK |
676 | If \-1 is provided as UID, current user's ID is used. |
677 | ||
678 | The arguments | |
679 | .IR arg4 | |
680 | and | |
681 | .IR arg5 | |
fa76da80 ES |
682 | are ignored. |
683 | .TP | |
684 | .BR KEYCTL_DH_COMPUTE " (since Linux 4.7)" | |
461a8ce5 MK |
685 | Compute Diffie-Hellman values. |
686 | The | |
fa76da80 ES |
687 | .I arg2 |
688 | argument is a pointer to | |
60fc9e95 | 689 | .I struct keyctl_dh_params |
fa76da80 ES |
690 | which is defined in |
691 | .I <linux/keyctl.h> | |
692 | as follows: | |
693 | ||
694 | .nf | |
695 | .in +4n | |
696 | struct keyctl_dh_params { | |
697 | int32_t private; | |
698 | int32_t prime; | |
699 | int32_t base; | |
700 | }; | |
701 | .in | |
702 | .fi | |
703 | ||
60fc9e95 | 704 | The |
fa76da80 | 705 | .IR private ", " prime " and " base |
60fc9e95 | 706 | fields are IDs of the keys, payload of which would be used for DH values |
461a8ce5 | 707 | calculation. |
60fc9e95 | 708 | The result is calculated as |
fa76da80 | 709 | .IR "base^private mod prime" . |
60fc9e95 | 710 | |
fa76da80 ES |
711 | The |
712 | .I arg3 | |
713 | argument (converted to | |
714 | .I char * | |
60fc9e95 | 715 | type) should point to an output buffer whose size is passed in the |
fa76da80 ES |
716 | .I arg4 |
717 | argument (converted to kernel's | |
718 | .I size_t | |
461a8ce5 | 719 | type). |
60fc9e95 MK |
720 | The buffer should be big enough in order to accommodate the output data, |
721 | otherwise an error is returned. | |
722 | A NULL pointer can be provided as buffer in order | |
723 | to obtain the required buffer size. | |
724 | ||
461a8ce5 | 725 | The |
fa76da80 | 726 | .I arg5 |
60fc9e95 | 727 | argument is reserved and must be 0. |
4509c62e | 728 | .SH RETURN VALUE |
fa76da80 ES |
729 | For a successful call, the return value depends on the operation: |
730 | .TP | |
731 | .B KEYCTL_GET_KEYRING_ID | |
732 | The ID of the requested keyring. | |
733 | .TP | |
734 | .B KEYCTL_JOIN_SESSION_KEYRING | |
735 | The ID of the joined session keyring. | |
736 | .TP | |
737 | .B KEYCTL_DESCRIBE | |
60fc9e95 | 738 | The size of description (including the terminating null byte), irrespective |
fa76da80 ES |
739 | of the provided buffer size. |
740 | .TP | |
741 | .B KEYCTL_SEARCH | |
742 | The found key ID. | |
743 | .TP | |
744 | .B KEYCTL_READ | |
745 | The amount of data that is available in the key, irrespective of the provided | |
746 | buffer size. | |
747 | .TP | |
748 | .B KEYCTL_SET_REQKEY_KEYRING | |
749 | Old setting (one of | |
60fc9e95 | 750 | .BR KEY_REQKEY_DEFL_USER_* ) |
fa76da80 ES |
751 | .TP |
752 | .B KEYCTL_ASSUME_AUTHORITY | |
461a8ce5 | 753 | 0, if the ID given is 0. |
60fc9e95 | 754 | ID of the authorization key matching key with the given |
fa76da80 ES |
755 | ID if non-zero key ID provided. |
756 | .TP | |
757 | .B KEYCTL_GET_SECURITY | |
60fc9e95 | 758 | The amount of information available (including the terminating null byte), |
fa76da80 ES |
759 | irrespective of the provided buffer size. |
760 | .TP | |
761 | .B KEYCTL_GET_PERSISTENT | |
762 | ID of the persistent keyring. | |
763 | .TP | |
764 | .B KEYCTL_DH_COMPUTE | |
765 | Amount of bytes being copied. | |
766 | .TP | |
767 | All other commands | |
768 | Zero. | |
769 | .PP | |
770 | On error, \-1 is returned, and | |
771 | .I errno | |
772 | is set appropriately to indicate the error. | |
4509c62e MK |
773 | .SH ERRORS |
774 | .TP | |
27807c32 | 775 | .B EACCES |
60fc9e95 | 776 | The requested operation wasn't permitted. |
27807c32 MK |
777 | .TP |
778 | .B EDQUOT | |
779 | The key quota for the caller's user would be exceeded by creating a key or | |
780 | linking it to the keyring. | |
4509c62e MK |
781 | .TP |
782 | .B EKEYEXPIRED | |
783 | An expired key was found or specified. | |
784 | .TP | |
4509c62e MK |
785 | .B EKEYREJECTED |
786 | A rejected key was found or specified. | |
787 | .TP | |
27807c32 MK |
788 | .B EKEYREVOKED |
789 | A revoked key was found or specified. | |
4509c62e | 790 | .TP |
27807c32 MK |
791 | .B ENOKEY |
792 | No matching key was found or an invalid key was specified. | |
fa76da80 ES |
793 | .TP |
794 | .B ENOTSUPP | |
795 | .I option | |
796 | is | |
797 | .B KEYCTL_UPDATE | |
60fc9e95 | 798 | and the key type does not support updating. |
fa76da80 ES |
799 | .TP |
800 | .B ENOTDIR | |
801 | Key of keyring type is expected but ID of a key with a different type provided. | |
802 | .TP | |
803 | .B ENFILE | |
804 | Keyring is full. | |
805 | .TP | |
806 | .B ENOENT | |
807 | .I option | |
808 | is | |
809 | .B KEYCTL_UNLINK | |
810 | and the key requested for unlinking isn't linked to the keyring. | |
811 | .TP | |
812 | .B EINVAL | |
813 | .I option | |
814 | is | |
815 | .B KEYCTL_DH_COMPUTE | |
60fc9e95 | 816 | and the buffer size provided is not enough for the result to fit in. |
461a8ce5 | 817 | Provide 0 as |
fa76da80 | 818 | a buffer size in order to obtain minimum buffer size first. |
60fc9e95 | 819 | .SH NOTES |
4509c62e MK |
820 | Although this is a Linux system call, it is not present in |
821 | .I libc | |
822 | but can be found rather in | |
823 | .IR libkeyutils . | |
824 | When linking, | |
60fc9e95 | 825 | .B \-lkeyutils |
4509c62e | 826 | should be specified to the linker. |
4509c62e | 827 | .SH SEE ALSO |
e264f024 MK |
828 | .ad l |
829 | .nh | |
4509c62e | 830 | .BR keyctl (1), |
4509c62e | 831 | .BR add_key (2), |
4509c62e | 832 | .BR request_key (2), |
4509c62e | 833 | .BR keyctl_chown (3), |
4509c62e | 834 | .BR keyctl_clear (3), |
cf4d4361 DP |
835 | .BR keyctl_describe (3), |
836 | .BR keyctl_describe_alloc (3), | |
837 | .BR keyctl_get_keyring_ID (3), | |
4509c62e | 838 | .BR keyctl_instantiate (3), |
cf4d4361 DP |
839 | .BR keyctl_join_session_keyring (3), |
840 | .BR keyctl_link (3), | |
4509c62e | 841 | .BR keyctl_negate (3), |
d8f1a35c MK |
842 | .BR keyctl_read (3), |
843 | .BR keyctl_read_alloc (3), | |
cf4d4361 DP |
844 | .BR keyctl_revoke (3), |
845 | .BR keyctl_search (3), | |
4509c62e | 846 | .BR keyctl_set_reqkey_keyring (3), |
4509c62e | 847 | .BR keyctl_set_timeout (3), |
d8f1a35c | 848 | .BR keyctl_setperm (3), |
cf4d4361 DP |
849 | .BR keyctl_unlink (3), |
850 | .BR keyctl_update (3), | |
32fc2407 | 851 | .BR keyrings (7), |
4509c62e | 852 | .BR request-key (8) |
7e7454ef MK |
853 | |
854 | The kernel source file | |
855 | .IR Documentation/security/keys.txt . |