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 new_session
35 keyctl session
36 keyctl session - [<prog> <arg1> <arg2> ...]
37 keyctl session <name> [<prog> <arg1> <arg2> ...]
38 keyctl instantiate <key> <data> <keyring>
39 keyctl pinstantiate <key> <keyring>
40 keyctl negate <key> <timeout> <keyring>
41 keyctl reject <key> <timeout> <error> <keyring>
42 keyctl timeout <key> <timeout>
43 keyctl security <key>
44 keyctl reap [-v]
45 keyctl purge <type>
46 keyctl purge [-i] [-p] <type> <desc>
47 keyctl purge -s <type> <desc>
48 keyctl get_persistent <keyring> [<uid>]
49 keyctl dh_compute <private> <prime> <base>
50
52 This program is used to control the key management facility in various
53 ways using a variety of subcommands.
54
56 The key identifiers passed to or returned from keyctl are, in general,
57 positive integers. There are, however, some special values with special
58 meanings that can be passed as arguments:
59 No key: 0
61 Thread keyring: @t or -1
63 Each thread may have its own keyring. This is searched first,
64 before all others. The thread keyring is replaced by (v)fork,
65 exec and clone.
66 Process keyring: @p or -2
68 Each process (thread group) may have its own keyring. This is
69 shared between all members of a group and will be searched after
70 the thread keyring. The process keyring is replaced by (v)fork
71 and exec.
72 Session keyring: @s or -3
74 Each process subscribes to a session keyring that is inherited
75 across (v)fork, exec and clone. This is searched after the
76 process keyring. Session keyrings can be named and an extant
77 keyring can be joined in place of a process's current session
78 keyring.
79 User specific keyring: @u or -4
81 This keyring is shared between all the processes owned by a par‐
82 ticular user. It isn't searched directly, but is normally linked
83 to from the session keyring.
84 User default session keyring: @us or -5
86 This is the default session keyring for a particular user. Login
87 processes that change to a particular user will bind to this
88 session until another session is set.
89 Group specific keyring: @g or -6
91 This is a place holder for a group specific keyring, but is not
92 actually 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()
96 helper to permit it to access the callers keyrings and instanti‐
97 ate the target key.
98 Keyring by name: %:<name>
100 A named keyring. This will be searched for in the process's
101 keyrings and in /proc/keys.
102 Key by name: %<type>:<name>
104 A named key of the given type. This will be searched for in the
105 process's keyrings and in /proc/keys.
106
108 Any non-ambiguous shortening of a command name may be used in lieu of
109 the full command name. This facility should not be used in scripting as
110 new commands may be added in future that then cause ambiguity.
111 Display the package version number
113 keyctl --version
114 This command prints the package version number and build date and
116 exits:
117 $ keyctl --version
119 keyctl from keyutils-1.5.3 (Built 2011-08-24)
120 Show process keyrings
122 keyctl show [-x] [<keyring>]
123 By default this command recursively shows what keyrings a process is
125 subscribed to and what keys and keyrings they contain. If a keyring is
126 specified then that keyring will be dumped instead. If -x is specified
127 then the keyring IDs will be dumped in hex instead of decimal.
128 Add a key to a keyring
130 keyctl add <type> <desc> <data> <keyring>
131 keyctl padd <type> <desc> <keyring>
132 This command creates a key of the specified type and description;
134 instantiates it with the given data and attaches it to the specified
135 keyring. It then prints the new key's ID on stdout:
136 $ keyctl add user mykey stuff @u
138 26
139 The padd variant of the command reads the data from stdin rather than
141 taking it from the command line:
142 $ echo -n stuff | keyctl padd user mykey @u 26
144 Request a key
146 keyctl request <type> <desc> [<dest_keyring>]
147 keyctl request2 <type> <desc> <info> [<dest_keyring>]
148 keyctl prequest2 <type> <desc> [<dest_keyring>]
149 These three commands request the lookup of a key of the given type and
151 description. The process's keyrings will be searched, and if a match is
152 found the matching key's ID will be printed to stdout; and if a desti‐
153 nation keyring is given, the key will be added to that keyring also.
154 If there is no key, the first command will simply return the error
156 ENOKEY and fail. The second and third commands will create a partial
157 key with the type and description, and call out to /sbin/request-key
158 with that key and the extra information supplied. This will then
159 attempt to instantiate the key in some manner, such that a valid key is
160 obtained.
161 The third command is like the second, except that the callout informa‐
163 tion is read from stdin rather than being passed on the command line.
164 If a valid key is obtained, the ID will be printed and the key attached
166 as if the original search had succeeded.
167 If there wasn't a valid key obtained, a temporary negative key will be
169 attached to the destination keyring if given and the error "Requested
170 key not available" will be given.
171 $ keyctl request2 user debug:hello wibble
173 23
174 $ echo -n wibble | keyctl prequest2 user debug:hello
175 23
176 $ keyctl request user debug:hello
177 23
178 Update a key
180 keyctl update <key> <data>
181 keyctl pupdate <key>
182 This command replaces the data attached to a key with a new set of
184 data. If the type of the key doesn't support update then error "Opera‐
185 tion not supported" will be returned.
186 $ keyctl update 23 zebra
188 The pupdate variant of the command reads the data from stdin rather
190 than taking it from the command line:
191 $ echo -n zebra | keyctl pupdate 23
193 Create a keyring
195 keyctl newring <name> <keyring>
196 This command creates a new keyring of the specified name and attaches
198 it to the specified keyring. The ID of the new keyring will be printed
199 to stdout if successful.
200 $ keyctl newring squelch @us
202 27
203 Revoke a key
205 keyctl revoke <key>
206 This command marks a key as being revoked. Any further operations on
208 that key (apart from unlinking it) will return error "Key has been
209 revoked".
210 $ keyctl revoke 26
212 $ keyctl describe 26
213 keyctl_describe: Key has been revoked
214 Clear a keyring
216 keyctl clear <keyring>
217 This command unlinks all the keys attached to the specified keyring.
219 Error "Not a directory" will be returned if the key specified is not a
220 keyring.
221 $ keyctl clear 27
223 Link a key to a keyring
225 keyctl link <key> <keyring>
226 This command makes a link from the key to the keyring if there's enough
228 capacity to do so. Error "Not a directory" will be returned if the des‐
229 tination is not a keyring. Error "Permission denied" will be returned
230 if the key doesn't have link permission or the keyring doesn't have
231 write permission. Error "File table overflow" will be returned if the
232 keyring is full. Error "Resource deadlock avoided" will be returned if
233 an attempt was made to introduce a recursive link.
234 $ keyctl link 23 27
236 $ keyctl link 27 27
237 keyctl_link: Resource deadlock avoided
238 Unlink a key from a keyring or the session keyring tree
240 keyctl unlink <key> [<keyring>]
241 If the keyring is specified, this command removes a link to the key
243 from the keyring. Error "Not a directory" will be returned if the des‐
244 tination is not a keyring. Error "Permission denied" will be returned
245 if the keyring doesn't have write permission. Error "No such file or
246 directory" will be returned if the key is not linked to by the keyring.
247 If the keyring is not specified, this command performs a depth-first
249 search of the session keyring tree and removes all the links to the
250 nominated key that it finds (and that it is permitted to remove). It
251 prints the number of successful unlinks before exiting.
252 $ keyctl unlink 23 27
254 Search a keyring
256 keyctl search <keyring> <type> <desc> [<dest_keyring>]
257 This command non-recursively searches a keyring for a key of a particu‐
259 lar type and description. If found, the ID of the key will be printed
260 on stdout and the key will be attached to the destination keyring if
261 present. Error "Requested key not available" will be returned if the
262 key is not found.
263 $ keyctl search @us user debug:hello
265 23
266 $ keyctl search @us user debug:bye
267 keyctl_search: Requested key not available
268 Read a key
270 keyctl read <key>
271 keyctl pipe <key>
272 keyctl print <key>
273 These commands read the payload of a key. "read" prints it on stdout as
275 a hex dump, "pipe" dumps the raw data to stdout and "print" dumps it to
276 stdout directly if it's entirely printable or as a hexdump preceded by
277 ":hex:" if not.
278 If the key type does not support reading of the payload, then error
280 "Operation not supported" will be returned.
281 $ keyctl read 26
283 1 bytes of data in key:
284 62
285 $ keyctl print 26
286 b
287 $ keyctl pipe 26
288 $
289 List a keyring
291 keyctl list <keyring>
292 keyctl rlist <keyring>
293 These commands list the contents of a key as a keyring. "list" pretty
295 prints the contents and "rlist" just produces a space-separated list of
296 key IDs.
297 No attempt is made to check that the specified keyring is a keyring.
299 $ keyctl list @us
301 2 keys in keyring:
302 22: vrwsl---------- 4043 -1 keyring: _uid.4043
303 23: vrwsl---------- 4043 4043 user: debug:hello
304 $ keyctl rlist @us
305 22 23
306 Describe a key
308 keyctl describe <keyring>
309 keyctl rdescribe <keyring> [sep]
310 These commands fetch a description of a keyring. "describe" pretty
312 prints the description in the same fashion as the "list" command; "rde‐
313 scribe" prints the raw data returned from the kernel.
314 $ keyctl describe @us
316 -5: vrwsl---------- 4043 -1 keyring: _uid_ses.4043
317 $ keyctl rdescribe @us
318 keyring;4043;-1;3f1f0000;_uid_ses.4043
319 The raw string is "<type>;<uid>;<gid>;<perms>;<description>", where uid
321 and gid are the decimal user and group IDs, perms is the permissions
322 mask in hex, type and description are the type name and description
323 strings (neither of which will contain semicolons).
324 Change the access controls on a key
326 keyctl chown <key> <uid>
327 keyctl chgrp <key> <gid>
328 These two commands change the UID and GID associated with evaluating a
330 key's permissions mask. The UID also governs which quota a key is taken
331 out of.
332 The chown command is not currently supported; attempting it will earn
334 the error "Operation not supported" at best.
335 For non-superuser users, the GID may only be set to the process's GID
337 or a GID in the process's groups list. The superuser may set any GID it
338 likes.
339 $ sudo keyctl chown 27 0
341 keyctl_chown: Operation not supported
342 $ sudo keyctl chgrp 27 0
343 Set the permissions mask on a key
345 keyctl setperm <key> <mask>
346 This command changes the permission control mask on a key. The mask may
348 be specified as a hex number if it begins "0x", an octal number if it
349 begins "0" or a decimal number otherwise.
350 The hex numbers are a combination of:
352 Possessor UID GID Other Permission Granted
354 ======== ======== ======== ======== ==================
355 01000000 00010000 00000100 00000001 View
356 02000000 00020000 00000200 00000002 Read
357 04000000 00040000 00000400 00000004 Write
358 08000000 00080000 00000800 00000008 Search
359 10000000 00100000 00001000 00000010 Link
360 20000000 00200000 00002000 00000020 Set Attribute
361 3f000000 003f0000 00003f00 0000003f All
362 View permits the type, description and other parameters of a key to be
364 viewed.
365 Read permits the payload (or keyring list) to be read if supported by
367 the type.
368 Write permits the payload (or keyring list) to be modified or updated.
370 Search on a key permits it to be found when a keyring to which it is
372 linked is searched.
373 Link permits a key to be linked to a keyring.
375 Set Attribute permits a key to have its owner, group membership, per‐
377 missions mask and timeout changed.
378 $ keyctl setperm 27 0x1f1f1f00
380 Start a new session with fresh keyrings
382 keyctl session
383 keyctl session - [<prog> <arg1> <arg2> ...]
384 keyctl session <name> [<prog> <arg1> <arg2> ...]
385 These commands join or create a new keyring and then run a shell or
387 other program with that keyring as the session key.
388 The variation with no arguments just creates an anonymous session
390 keyring and attaches that as the session keyring; it then exec's
391 $SHELL.
392 The variation with a dash in place of a name creates an anonymous ses‐
394 sion keyring and attaches that as the session keyring; it then exec's
395 the supplied command, or $SHELL if one isn't supplied.
396 The variation with a name supplied creates or joins the named keyring
398 and attaches that as the session keyring; it then exec's the supplied
399 command, or $SHELL if one isn't supplied.
400 $ keyctl rdescribe @s
402 keyring;4043;-1;3f1f0000;_uid_ses.4043
403 $ keyctl session
405 Joined session keyring: 28
406 $ keyctl rdescribe @s
408 keyring;4043;4043;3f1f0000;_ses.24082
409 $ keyctl session -
411 Joined session keyring: 29
412 $ keyctl rdescribe @s
413 keyring;4043;4043;3f1f0000;_ses.24139
414 $ keyctl session - keyctl rdescribe @s
416 Joined session keyring: 30
417 keyring;4043;4043;3f1f0000;_ses.24185
418 $ keyctl session fish
420 Joined session keyring: 34
421 $ keyctl rdescribe @s
422 keyring;4043;4043;3f1f0000;fish
423 $ keyctl session fish keyctl rdesc @s
425 Joined session keyring: 35
426 keyring;4043;4043;3f1f0000;fish
427 Instantiate a key
429 keyctl instantiate <key> <data> <keyring>
430 keyctl pinstantiate <key> <keyring>
431 keyctl negate <key> <timeout> <keyring>
432 keyctl reject <key> <timeout> <error> <keyring>
433 These commands are used to attach data to a partially set up key (as
435 created by the kernel and passed to /sbin/request-key). "instantiate"
436 marks a key as being valid and attaches the data as the payload.
437 "negate" and "reject" mark a key as invalid and sets a timeout on it so
438 that it'll go away after a while. This prevents a lot of quickly
439 sequential requests from slowing the system down overmuch when they all
440 fail, as all subsequent requests will then fail with error "Requested
441 key not found" (if negated) or the specified error (if rejected) until
442 the negative key has expired.
443 Reject's error argument can either be a UNIX error number or one of
445 'rejected', 'expired' or 'revoked'.
446 The newly instantiated key will be attached to the specified keyring.
448 These commands may only be run from the program run by request-key - a
450 special authorisation key is set up by the kernel and attached to the
451 request-key's session keyring. This special key is revoked once the key
452 to which it refers has been instantiated one way or another.
453 $ keyctl instantiate $1 "Debug $3" $4
455 $ keyctl negate $1 30 $4
456 $ keyctl reject $1 30 64 $4
457 The pinstantiate variant of the command reads the data from stdin
459 rather than taking it from the command line:
460 $ echo -n "Debug $3" | keyctl pinstantiate $1 $4
462 Set the expiry time on a key
464 keyctl timeout <key> <timeout>
465 This command is used to set the timeout on a key, or clear an existing
467 timeout if the value specified is zero. The timeout is given as a num‐
468 ber of seconds into the future.
469 $ keyctl timeout $1 45
471 Retrieve a key's security context
473 keyctl security <key>
474 This command is used to retrieve a key's LSM security context. The
476 label is printed on stdout.
477 $ keyctl security @s
479 unconfined_u:unconfined_r:unconfined_t:s0-s0:c0.c1023
480 Give the parent process a new session keyring
482 keyctl new_session
483 This command is used to give the invoking process (typically a shell) a
485 new session keyring, discarding its old session keyring.
486 $ keyctl session foo
488 Joined session keyring: 723488146
489 $ keyctl show
490 Session Keyring
491 -3 --alswrv 0 0 keyring: foo
492 $ keyctl new_session
493 490511412
494 $ keyctl show
495 Session Keyring
496 -3 --alswrv 0 0 keyring: _ses
497 Note that this affects the parent of the process that invokes the sys‐
499 tem call, and so may only affect processes with matching credentials.
500 Furthermore, the change does not take effect till the parent process
501 next transitions from kernel space to user space - typically when the
502 wait() system call returns.
503 Remove dead keys from the session keyring tree
505 keyctl reap
506 This command performs a depth-first search of the caller's session
508 keyring tree and attempts to unlink any key that it finds that is inac‐
509 cessible due to expiry, revocation, rejection or negation. It does not
510 attempt to remove live keys that are unavailable simply due to a lack
511 of granted permission.
512 A key that is designated reapable will only be removed from a keyring
514 if the caller has Write permission on that keyring, and only keyrings
515 that grant Search permission to the caller will be searched.
516 The command prints the number of keys reaped before it exits. If the
518 -v flag is passed then the reaped keys are listed as they're being
519 reaped, together with the success or failure of the unlink.
520 Remove matching keys from the session keyring tree
522 keyctl purge <type>
523 keyctl purge [-i] [-p] <type> <desc>
524 keyctl purge -s <type> <desc>
525 These commands perform a depth-first search to find matching keys in
527 the caller's session keyring tree and attempts to unlink them. The
528 number of keys successfully unlinked is printed at the end.
529 The keyrings must grant Read and View permission to the caller to be
531 searched, and the keys to be removed must also grant View permission.
532 Keys can only be removed from keyrings that grant Write permission.
533 The first variant purges all keys of the specified type.
535 The second variant purges all keys of the specified type that also
537 match the given description literally. The -i flag allows a case-inde‐
538 pendent match and the -p flag allows a prefix match.
539 The third variant purges all keys of the specified type and matching
541 description using the key type's comparator in the kernel to match the
542 description. This permits the key type to match a key with a variety
543 of descriptions.
544 Get persistent keyring
546 keyctl get_persistent <keyring> [<uid>]
547 This command gets the persistent keyring for either the current UID or
549 the specified UID and attaches it to the nominated keyring. The per‐
550 sistent keyring's ID will be printed on stdout.
551 The kernel will create the keyring if it doesn't exist and every time
553 this command is called, will reset the expiration timeout on the
554 keyring to the value in:
555 /proc/sys/kernel/keys/persistent_keyring_expiry
557 (by default three days). Should the timeout be reached, the persistent
559 keyring will be removed and everything it pins can then be garbage col‐
560 lected.
561 If a UID other than the process's real or effective UIDs is specified,
563 then an error will be given if the process does not have the CAP_SETUID
564 capability.
565 Compute a Diffie-Hellman shared secret or public key
567 keyctl dh_compute <private> <prime> <base>
568 This command computes either a Diffie-Hellman shared secret or the pub‐
570 lic key corresponding to the provided private key using the payloads of
571 three keys. The computation is:
572 base ^ private (mod prime)
574 The three inputs must be user keys with read permission. If the pro‐
576 vided base key contains the shared generator value, the public key will
577 be computed. If the provided base key contains the remote public key
578 value, the shared secret will be computed.
579 The result is printed to stdout as a hex dump.
581 $ keyctl dh_compute $1 $2 $3
583 8 bytes of data in result:
584 00010203 04050607
585
587 There are a number of common errors returned by this program:
588 "Not a directory" - a key wasn't a keyring.
590 "Requested key not found" - the looked for key isn't available.
592 "Key has been revoked" - a revoked key was accessed.
594 "Key has expired" - an expired key was accessed.
596 "Permission denied" - permission was denied by a UID/GID/mask combina‐
598 tion.
599
601 keyctl(1), keyctl(2), request_key(2), keyctl(3), request-key.conf(5),
602 keyrings(7), request-key(8)
603Linux 20 Feb 2014 KEYCTL(1)