1KEYCTL(1) Linux Key Management Utilities KEYCTL(1)
2
6 keyctl - Key management facility control
7
9 keyctl --version
10 keyctl show [-x] [<keyring>]
11 keyctl add <type> <desc> <data> <keyring>
12 keyctl padd <type> <desc> <keyring>
13 keyctl request <type> <desc> [<dest_keyring>]
14 keyctl request2 <type> <desc> <info> [<dest_keyring>]
15 keyctl prequest2 <type> <desc> [<dest_keyring>]
16 keyctl update <key> <data>
17 keyctl pupdate <key>
18 keyctl newring <name> <keyring>
19 keyctl revoke <key>
20 keyctl clear <keyring>
21 keyctl link <key> <keyring>
22 keyctl unlink <key> [<keyring>]
23 keyctl search <keyring> <type> <desc> [<dest_keyring>]
24 keyctl read <key>
25 keyctl pipe <key>
26 keyctl print <key>
27 keyctl list <keyring>
28 keyctl rlist <keyring>
29 keyctl describe <keyring>
30 keyctl rdescribe <keyring> [sep]
31 keyctl chown <key> <uid>
32 keyctl chgrp <key> <gid>
33 keyctl setperm <key> <mask>
34 keyctl session
35 keyctl session - [<prog> <arg1> <arg2> ...]
36 keyctl session <name> [<prog> <arg1> <arg2> ...]
37 keyctl instantiate <key> <data> <keyring>
38 keyctl pinstantiate <key> <keyring>
39 keyctl negate <key> <timeout> <keyring>
40 keyctl reject <key> <timeout> <error> <keyring>
41 keyctl timeout <key> <timeout>
42 keyctl security <key>
43 keyctl reap [-v]
44 keyctl purge <type>
45 keyctl purge [-i] [-p] <type> <desc>
46 keyctl purge -s <type> <desc>
47
49 This program is used to control the key management facility in various
50 ways using a variety of subcommands.
51
53 The key identifiers passed to or returned from keyctl are, in general,
54 positive integers. There are, however, some special values with special
55 meanings that can be passed as arguments:
56 (*) No key: 0
58 (*) Thread keyring: @t or -1
60 Each thread may have its own keyring. This is searched first, before
62 all others. The thread keyring is replaced by (v)fork, exec and clone.
63 (*) Process keyring: @p or -2
65 Each process (thread group) may have its own keyring. This is shared
67 between all members of a group and will be searched after the thread
68 keyring. The process keyring is replaced by (v)fork and exec.
69 (*) Session keyring: @s or -3
71 Each process subscribes to a session keyring that is inherited across
73 (v)fork, exec and clone. This is searched after the process keyring.
74 Session keyrings can be named and an extant keyring can be joined in
75 place of a process's current session keyring.
76 (*) User specific keyring: @u or -4
78 This keyring is shared between all the processes owned by a particular
80 user. It isn't searched directly, but is normally linked to from the
81 session keyring.
82 (*) User default session keyring: @us or -5
84 This is the default session keyring for a particular user. Login pro‐
86 cesses that change to a particular user will bind to this session until
87 another session is set.
88 (*) Group specific keyring: @g or -6
90 This is a place holder for a group specific keyring, but is not actu‐
92 ally implemented yet in the kernel.
93 (*) Assumed request_key authorisation key: @a or -7
95 This selects the authorisation key provided to the request_key() helper
97 to permit it to access the callers keyrings and instantiate the target
98 key.
99 (*) Keyring by name: %:<name>
101 A named keyring. This will be searched for in the process's keyrings
103 and in /proc/keys.
104 (*) Key by name: %<type>:<name>
106 A named key of the given type. This will be searched for in the
108 process's keyrings and in /proc/keys.
109
111 Any non-ambiguous shortening of a command name may be used in lieu of
112 the full command name. This facility should not be used in scripting as
113 new commands may be added in future that then cause ambiguity.
114 (*) Display the package version number
116 keyctl --version
118 This command prints the package version number and build date and
120 exits:
121 testbox>keyctl --version
123 keyctl from keyutils-1.5.3 (Built 2011-08-24)
124 (*) Show process keyrings
126 keyctl show [-x] [<keyring>]
128 By default this command recursively shows what keyrings a process is
130 subscribed to and what keys and keyrings they contain. If a keyring is
131 specified then that keyring will be dumped instead. If -x is specified
132 then the keyring IDs will be dumped in hex instead of decimal.
133 (*) Add a key to a keyring
135 keyctl add <type> <desc> <data> <keyring>
137 keyctl padd <type> <desc> <keyring>
138 This command creates a key of the specified type and description;
140 instantiates it with the given data and attaches it to the specified
141 keyring. It then prints the new key's ID on stdout:
142 testbox>keyctl add user mykey stuff @u
144 26
145 The padd variant of the command reads the data from stdin rather than
147 taking it from the command line:
148 testbox>echo -n stuff | keyctl padd user mykey @u
150 26
151 (*) Request a key
153 keyctl request <type> <desc> [<dest_keyring>]
155 keyctl request2 <type> <desc> <info> [<dest_keyring>]
156 keyctl prequest2 <type> <desc> [<dest_keyring>]
157 These three commands request the lookup of a key of the given type and
159 description. The process's keyrings will be searched, and if a match is
160 found the matching key's ID will be printed to stdout; and if a desti‐
161 nation keyring is given, the key will be added to that keyring also.
162 If there is no key, the first command will simply return the error
164 ENOKEY and fail. The second and third commands will create a partial
165 key with the type and description, and call out to /sbin/request-key
166 with that key and the extra information supplied. This will then
167 attempt to instantiate the key in some manner, such that a valid key is
168 obtained.
169 The third command is like the second, except that the callout informa‐
171 tion is read from stdin rather than being passed on the command line.
172 If a valid key is obtained, the ID will be printed and the key attached
174 as if the original search had succeeded.
175 If there wasn't a valid key obtained, a temporary negative key will be
177 attached to the destination keyring if given and the error "Requested
178 key not available" will be given.
179 testbox>keyctl request2 user debug:hello wibble
181 23
182 testbox>echo -n wibble | keyctl prequest2 user debug:hello
183 23
184 testbox>keyctl request user debug:hello
185 23
186 (*) Update a key
188 keyctl update <key> <data>
190 keyctl pupdate <key>
191 This command replaces the data attached to a key with a new set of
193 data. If the type of the key doesn't support update then error "Opera‐
194 tion not supported" will be returned.
195 testbox>keyctl update 23 zebra
197 The pupdate variant of the command reads the data from stdin rather
199 than taking it from the command line:
200 testbox>echo -n zebra | keyctl pupdate 23
202 (*) Create a keyring
204 keyctl newring <name> <keyring>
206 This command creates a new keyring of the specified name and attaches
208 it to the specified keyring. The ID of the new keyring will be printed
209 to stdout if successful.
210 testbox>keyctl newring squelch @us
212 27
213 (*) Revoke a key
215 keyctl revoke <key>
217 This command marks a key as being revoked. Any further operations on
219 that key (apart from unlinking it) will return error "Key has been
220 revoked".
221 testbox>keyctl revoke 26
223 testbox>keyctl describe 26
224 keyctl_describe: Key has been revoked
225 (*) Clear a keyring
227 keyctl clear <keyring>
229 This command unlinks all the keys attached to the specified keyring.
231 Error "Not a directory" will be returned if the key specified is not a
232 keyring.
233 testbox>keyctl clear 27
235 (*) Link a key to a keyring
237 keyctl link <key> <keyring>
239 This command makes a link from the key to the keyring if there's enough
241 capacity to do so. Error "Not a directory" will be returned if the des‐
242 tination is not a keyring. Error "Permission denied" will be returned
243 if the key doesn't have link permission or the keyring doesn't have
244 write permission. Error "File table overflow" will be returned if the
245 keyring is full. Error "Resource deadlock avoided" will be returned if
246 an attempt was made to introduce a recursive link.
247 testbox>keyctl link 23 27
249 testbox>keyctl link 27 27
250 keyctl_link: Resource deadlock avoided
251 (*) Unlink a key from a keyring or the session keyring tree
253 keyctl unlink <key> [<keyring>]
255 If the keyring is specified, this command removes a link to the key
257 from the keyring. Error "Not a directory" will be returned if the des‐
258 tination is not a keyring. Error "Permission denied" will be returned
259 if the keyring doesn't have write permission. Error "No such file or
260 directory" will be returned if the key is not linked to by the keyring.
261 If the keyring is not specified, this command performs a depth-first
263 search of the session keyring tree and removes all the links to the
264 nominated key that it finds (and that it is permitted to remove). It
265 prints the number of successful unlinks before exiting.
266 testbox>keyctl unlink 23 27
268 (*) Search a keyring
270 keyctl search <keyring> <type> <desc> [<dest_keyring>]
272 This command non-recursively searches a keyring for a key of a particu‐
274 lar type and description. If found, the ID of the key will be printed
275 on stdout and the key will be attached to the destination keyring if
276 present. Error "Requested key not available" will be returned if the
277 key is not found.
278 testbox>keyctl search @us user debug:hello
280 23
281 testbox>keyctl search @us user debug:bye
282 keyctl_search: Requested key not available
283 (*) Read a key
285 keyctl read <key>
287 keyctl pipe <key>
288 keyctl print <key>
289 These commands read the payload of a key. "read" prints it on stdout as
291 a hex dump, "pipe" dumps the raw data to stdout and "print" dumps it to
292 stdout directly if it's entirely printable or as a hexdump preceded by
293 ":hex:" if not.
294 If the key type does not support reading of the payload, then error
296 "Operation not supported" will be returned.
297 testbox>keyctl read 26
299 1 bytes of data in key:
300 62
301 testbox>keyctl print 26
302 b
303 testbox>keyctl pipe 26
304 btestbox>
305 (*) List a keyring
307 keyctl list <keyring>
309 keyctl rlist <keyring>
310 These commands list the contents of a key as a keyring. "list" pretty
312 prints the contents and "rlist" just produces a space-separated list of
313 key IDs.
314 No attempt is made to check that the specified keyring is a keyring.
316 testbox>keyctl list @us
318 2 keys in keyring:
319 22: vrwsl---------- 4043 -1 keyring: _uid.4043
320 23: vrwsl---------- 4043 4043 user: debug:hello
321 testbox>keyctl rlist @us
322 22 23
323 (*) Describe a key
325 keyctl describe <keyring>
327 keyctl rdescribe <keyring> [sep]
328 These commands fetch a description of a keyring. "describe" pretty
330 prints the description in the same fashion as the "list" command; "rde‐
331 scribe" prints the raw data returned from the kernel.
332 testbox>keyctl describe @us
334 -5: vrwsl---------- 4043 -1 keyring: _uid_ses.4043
335 testbox>keyctl rdescribe @us
336 keyring;4043;-1;3f1f0000;_uid_ses.4043
337 The raw string is "<type>;<uid>;<gid>;<perms>;<description>", where uid
339 and gid are the decimal user and group IDs, perms is the permissions
340 mask in hex, type and description are the type name and description
341 strings (neither of which will contain semicolons).
342 (*) Change the access controls on a key
344 keyctl chown <key> <uid>
346 keyctl chgrp <key> <gid>
347 These two commands change the UID and GID associated with evaluating a
349 key's permissions mask. The UID also governs which quota a key is taken
350 out of.
351 The chown command is not currently supported; attempting it will earn
353 the error "Operation not supported" at best.
354 For non-superuser users, the GID may only be set to the process's GID
356 or a GID in the process's groups list. The superuser may set any GID it
357 likes.
358 testbox>sudo keyctl chown 27 0
360 keyctl_chown: Operation not supported
361 testbox>sudo keyctl chgrp 27 0
362 (*) Set the permissions mask on a key
364 keyctl setperm <key> <mask>
366 This command changes the permission control mask on a key. The mask may
368 be specified as a hex number if it begins "0x", an octal number if it
369 begins "0" or a decimal number otherwise.
370 The hex numbers are a combination of:
372 Possessor UID GID Other Permission Granted
374 ======== ======== ======== ======== ==================
375 01000000 00010000 00000100 00000001 View
376 02000000 00020000 00000200 00000002 Read
377 04000000 00040000 00000400 00000004 Write
378 08000000 00080000 00000800 00000008 Search
379 10000000 00100000 00001000 00000010 Link
380 20000000 00200000 00002000 00000020 Set Attribute
381 3f000000 003f0000 00003f00 0000003f All
382 View permits the type, description and other parameters of a key to be
384 viewed.
385 Read permits the payload (or keyring list) to be read if supported by
387 the type.
388 Write permits the payload (or keyring list) to be modified or updated.
390 Search on a key permits it to be found when a keyring to which it is
392 linked is searched.
393 Link permits a key to be linked to a keyring.
395 Set Attribute permits a key to have its owner, group membership, per‐
397 missions mask and timeout changed.
398 testbox>keyctl setperm 27 0x1f1f1f00
400 (*) Start a new session with fresh keyrings
402 keyctl session
404 keyctl session - [<prog> <arg1> <arg2> ...]
405 keyctl session <name> [<prog> <arg1> <arg2> ...]
406 These commands join or create a new keyring and then run a shell or
408 other program with that keyring as the session key.
409 The variation with no arguments just creates an anonymous session
411 keyring and attaches that as the session keyring; it then exec's
412 $SHELL.
413 The variation with a dash in place of a name creates an anonymous ses‐
415 sion keyring and attaches that as the session keyring; it then exec's
416 the supplied command, or $SHELL if one isn't supplied.
417 The variation with a name supplied creates or joins the named keyring
419 and attaches that as the session keyring; it then exec's the supplied
420 command, or $SHELL if one isn't supplied.
421 testbox>keyctl rdescribe @s
423 keyring;4043;-1;3f1f0000;_uid_ses.4043
424 testbox>keyctl session
426 Joined session keyring: 28
427 testbox>keyctl rdescribe @s
428 keyring;4043;4043;3f1f0000;_ses.24082
429 testbox>keyctl session -
431 Joined session keyring: 29
432 testbox>keyctl rdescribe @s
433 keyring;4043;4043;3f1f0000;_ses.24139
434 testbox>keyctl session - keyctl rdescribe @s
436 Joined session keyring: 30
437 keyring;4043;4043;3f1f0000;_ses.24185
438 testbox>keyctl session fish
440 Joined session keyring: 34
441 testbox>keyctl rdescribe @s
442 keyring;4043;4043;3f1f0000;fish
443 testbox>keyctl session fish keyctl rdesc @s
445 Joined session keyring: 35
446 keyring;4043;4043;3f1f0000;fish
447 (*) Instantiate a key
449 keyctl instantiate <key> <data> <keyring>
451 keyctl pinstantiate <key> <keyring>
452 keyctl negate <key> <timeout> <keyring>
453 keyctl reject <key> <timeout> <error> <keyring>
454 These commands are used to attach data to a partially set up key (as
456 created by the kernel and passed to /sbin/request-key). "instantiate"
457 marks a key as being valid and attaches the data as the payload.
458 "negate" and "reject" mark a key as invalid and sets a timeout on it so
459 that it'll go away after a while. This prevents a lot of quickly
460 sequential requests from slowing the system down overmuch when they all
461 fail, as all subsequent requests will then fail with error "Requested
462 key not found" (if negated) or the specified error (if rejected) until
463 the negative key has expired.
464 Reject's error argument can either be a UNIX error number or one of
466 'rejected', 'expired' or 'revoked'.
467 The newly instantiated key will be attached to the specified keyring.
469 These commands may only be run from the program run by request-key - a
471 special authorisation key is set up by the kernel and attached to the
472 request-key's session keyring. This special key is revoked once the key
473 to which it refers has been instantiated one way or another.
474 testbox>keyctl instantiate $1 "Debug $3" $4
476 testbox>keyctl negate $1 30 $4
477 testbox>keyctl reject $1 30 64 $4
478 The pinstantiate variant of the command reads the data from stdin
480 rather than taking it from the command line:
481 testbox>echo -n "Debug $3" | keyctl pinstantiate $1 $4
483 (*) Set the expiry time on a key
485 keyctl timeout <key> <timeout>
487 This command is used to set the timeout on a key, or clear an existing
489 timeout if the value specified is zero. The timeout is given as a num‐
490 ber of seconds into the future.
491 testbox>keyctl timeout $1 45
493 (*) Retrieve a key's security context
495 keyctl security <key>
497 This command is used to retrieve a key's LSM security context. The
499 label is printed on stdout.
500 testbox>keyctl security @s
502 unconfined_u:unconfined_r:unconfined_t:s0-s0:c0.c1023
503 (*) Give the parent process a new session keyring
505 keyctl new_session
507 This command is used to give the invoking process (typically a shell) a
509 new session keyring, discarding its old session keyring.
510 testbox> keyctl session foo
512 Joined session keyring: 723488146
513 testbox> keyctl show
514 Session Keyring
515 -3 --alswrv 0 0 keyring: foo
516 testbox> keyctl new_session
517 490511412
518 testbox> keyctl show
519 Session Keyring
520 -3 --alswrv 0 0 keyring: _ses
521 Note that this affects the parent of the process that invokes the sys‐
523 tem call, and so may only affect processes with matching credentials.
524 Furthermore, the change does not take effect till the parent process
525 next transitions from kernel space to user space - typically when the
526 wait() system call returns.
527 (*) Remove dead keys from the session keyring tree
529 keyctl reap
531 This command performs a depth-first search of the caller's session
533 keyring tree and attempts to unlink any key that it finds that is inac‐
534 cessible due to expiry, revocation, rejection or negation. It does not
535 attempt to remove live keys that are unavailable simply due to a lack
536 of granted permission.
537 A key that is designated reapable will only be removed from a keyring
539 if the caller has Write permission on that keyring, and only keyrings
540 that grant Search permission to the caller will be searched.
541 The command prints the number of keys reaped before it exits. If the
543 -v flag is passed then the reaped keys are listed as they're being
544 reaped, together with the success or failure of the unlink.
545 (*) Remove matching keys from the session keyring tree
547 keyctl purge <type>
549 keyctl purge [-i] [-p] <type> <desc>
550 keyctl purge -s <type> <desc>
551 These commands perform a depth-first search to find matching keys in
553 the caller's session keyring tree and attempts to unlink them. The
554 number of keys successfully unlinked is printed at the end.
555 The keyrings must grant Read and View permission to the caller to be
557 searched, and the keys to be removed must also grant View permission.
558 Keys can only be removed from keyrings that grant Write permission.
559 The first variant purges all keys of the specified type.
561 The second variant purges all keys of the specified type that also
563 match the given description literally. The -i flag allows a case-inde‐
564 pendent match and the -p flag allows a prefix match.
565 The third variant purges all keys of the specified type and matching
567 description using the key type's comparator in the kernel to match the
568 description. This permits the key type to match a key with a variety
569 of descriptions.
570
572 There are a number of common errors returned by this program:
573 "Not a directory" - a key wasn't a keyring.
575 "Requested key not found" - the looked for key isn't available.
577 "Key has been revoked" - a revoked key was accessed.
579 "Key has expired" - an expired key was accessed.
581 "Permission denied" - permission was denied by a UID/GID/mask combina‐
583 tion.
584
587 keyctl(1), request-key.conf(5)
588Linux 10 Sep 2013 KEYCTL(1)