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 restrict_keyring <keyring> [<type> [<restriction>]]
25 keyctl read <key>
26 keyctl pipe <key>
27 keyctl print <key>
28 keyctl list <keyring>
29 keyctl rlist <keyring>
30 keyctl describe <keyring>
31 keyctl rdescribe <keyring> [sep]
32 keyctl chown <key> <uid>
33 keyctl chgrp <key> <gid>
34 keyctl setperm <key> <mask>
35 keyctl new_session
36 keyctl session
37 keyctl session - [<prog> <arg1> <arg2> ...]
38 keyctl session <name> [<prog> <arg1> <arg2> ...]
39 keyctl instantiate <key> <data> <keyring>
40 keyctl pinstantiate <key> <keyring>
41 keyctl negate <key> <timeout> <keyring>
42 keyctl reject <key> <timeout> <error> <keyring>
43 keyctl timeout <key> <timeout>
44 keyctl security <key>
45 keyctl reap [-v]
46 keyctl purge <type>
47 keyctl purge [-i] [-p] <type> <desc>
48 keyctl purge -s <type> <desc>
49 keyctl get_persistent <keyring> [<uid>]
50 keyctl dh_compute <private> <prime> <base>
51 keyctl dh_compute_kdf <private> <prime> <base> <output_length>
52 <hash_type>
53 keyctl dh_compute_kdf_oi <private> <prime> <base> <output_length>
54 <hash_type>
55 keyctl pkey_query <key> <pass> [k=v]*
56 keyctl pkey_encrypt <key> <pass> <datafile> [k=v]* ><encfile>
57 keyctl pkey_decrypt <key> <pass> <encfile> [k=v]* ><datafile>
58 keyctl pkey_sign <key> <pass> <datafile> [k=v]* ><sigfile>
59 keyctl pkey_decrypt <key> <pass> <datafile> <sigfile> [k=v]*
60
62 This program is used to control the key management facility in various
63 ways using a variety of subcommands.
64
66 The key identifiers passed to or returned from keyctl are, in general,
67 positive integers. There are, however, some special values with special
68 meanings that can be passed as arguments:
69 No key: 0
71 Thread keyring: @t or -1
73 Each thread may have its own keyring. This is searched first,
74 before all others. The thread keyring is replaced by (v)fork,
75 exec and clone.
76 Process keyring: @p or -2
78 Each process (thread group) may have its own keyring. This is
79 shared between all members of a group and will be searched after
80 the thread keyring. The process keyring is replaced by (v)fork
81 and exec.
82 Session keyring: @s or -3
84 Each process subscribes to a session keyring that is inherited
85 across (v)fork, exec and clone. This is searched after the
86 process keyring. Session keyrings can be named and an extant
87 keyring can be joined in place of a process's current session
88 keyring.
89 User specific keyring: @u or -4
91 This keyring is shared between all the processes owned by a par‐
92 ticular user. It isn't searched directly, but is normally linked
93 to from the session keyring.
94 User default session keyring: @us or -5
96 This is the default session keyring for a particular user. Login
97 processes that change to a particular user will bind to this
98 session until another session is set.
99 Group specific keyring: @g or -6
101 This is a place holder for a group specific keyring, but is not
102 actually implemented yet in the kernel.
103 Assumed request_key authorisation key: @a or -7
105 This selects the authorisation key provided to the request_key()
106 helper to permit it to access the callers keyrings and instanti‐
107 ate the target key.
108 Keyring by name: %:<name>
110 A named keyring. This will be searched for in the process's
111 keyrings and in /proc/keys.
112 Key by name: %<type>:<name>
114 A named key of the given type. This will be searched for in the
115 process's keyrings and in /proc/keys.
116
118 Any non-ambiguous shortening of a command name may be used in lieu of
119 the full command name. This facility should not be used in scripting as
120 new commands may be added in future that then cause ambiguity.
121 Display the package version number
123 keyctl --version
124 This command prints the package version number and build date and
126 exits:
127 $ keyctl --version
129 keyctl from keyutils-1.5.3 (Built 2011-08-24)
130 Show process keyrings
132 keyctl show [-x] [<keyring>]
133 By default this command recursively shows what keyrings a process is
135 subscribed to and what keys and keyrings they contain. If a keyring is
136 specified then that keyring will be dumped instead. If -x is specified
137 then the keyring IDs will be dumped in hex instead of decimal.
138 Add a key to a keyring
140 keyctl add <type> <desc> <data> <keyring>
141 keyctl padd <type> <desc> <keyring>
142 This command creates a key of the specified type and description;
144 instantiates it with the given data and attaches it to the specified
145 keyring. It then prints the new key's ID on stdout:
146 $ keyctl add user mykey stuff @u
148 26
149 The padd variant of the command reads the data from stdin rather than
151 taking it from the command line:
152 $ echo -n stuff | keyctl padd user mykey @u 26
154 Request a key
156 keyctl request <type> <desc> [<dest_keyring>]
157 keyctl request2 <type> <desc> <info> [<dest_keyring>]
158 keyctl prequest2 <type> <desc> [<dest_keyring>]
159 These three commands request the lookup of a key of the given type and
161 description. The process's keyrings will be searched, and if a match is
162 found the matching key's ID will be printed to stdout; and if a desti‐
163 nation keyring is given, the key will be added to that keyring also.
164 If there is no key, the first command will simply return the error
166 ENOKEY and fail. The second and third commands will create a partial
167 key with the type and description, and call out to /sbin/request-key
168 with that key and the extra information supplied. This will then
169 attempt to instantiate the key in some manner, such that a valid key is
170 obtained.
171 The third command is like the second, except that the callout informa‐
173 tion is read from stdin rather than being passed on the command line.
174 If a valid key is obtained, the ID will be printed and the key attached
176 as if the original search had succeeded.
177 If there wasn't a valid key obtained, a temporary negative key will be
179 attached to the destination keyring if given and the error "Requested
180 key not available" will be given.
181 $ keyctl request2 user debug:hello wibble
183 23
184 $ echo -n wibble | keyctl prequest2 user debug:hello
185 23
186 $ keyctl request user debug:hello
187 23
188 Update a key
190 keyctl update <key> <data>
191 keyctl pupdate <key>
192 This command replaces the data attached to a key with a new set of
194 data. If the type of the key doesn't support update then error "Opera‐
195 tion not supported" will be returned.
196 $ keyctl update 23 zebra
198 The pupdate variant of the command reads the data from stdin rather
200 than taking it from the command line:
201 $ echo -n zebra | keyctl pupdate 23
203 Create a keyring
205 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 $ keyctl newring squelch @us
212 27
213 Revoke a key
215 keyctl revoke <key>
216 This command marks a key as being revoked. Any further operations on
218 that key (apart from unlinking it) will return error "Key has been
219 revoked".
220 $ keyctl revoke 26
222 $ keyctl describe 26
223 keyctl_describe: Key has been revoked
224 Clear a keyring
226 keyctl clear <keyring>
227 This command unlinks all the keys attached to the specified keyring.
229 Error "Not a directory" will be returned if the key specified is not a
230 keyring.
231 $ keyctl clear 27
233 Link a key to a keyring
235 keyctl link <key> <keyring>
236 This command makes a link from the key to the keyring if there's enough
238 capacity to do so. Error "Not a directory" will be returned if the des‐
239 tination is not a keyring. Error "Permission denied" will be returned
240 if the key doesn't have link permission or the keyring doesn't have
241 write permission. Error "File table overflow" will be returned if the
242 keyring is full. Error "Resource deadlock avoided" will be returned if
243 an attempt was made to introduce a recursive link.
244 $ keyctl link 23 27
246 $ keyctl link 27 27
247 keyctl_link: Resource deadlock avoided
248 Unlink a key from a keyring or the session keyring tree
250 keyctl unlink <key> [<keyring>]
251 If the keyring is specified, this command removes a link to the key
253 from the keyring. Error "Not a directory" will be returned if the des‐
254 tination is not a keyring. Error "Permission denied" will be returned
255 if the keyring doesn't have write permission. Error "No such file or
256 directory" will be returned if the key is not linked to by the keyring.
257 If the keyring is not specified, this command performs a depth-first
259 search of the session keyring tree and removes all the links to the
260 nominated key that it finds (and that it is permitted to remove). It
261 prints the number of successful unlinks before exiting.
262 $ keyctl unlink 23 27
264 Search a keyring
266 keyctl search <keyring> <type> <desc> [<dest_keyring>]
267 This command non-recursively searches a keyring for a key of a particu‐
269 lar type and description. If found, the ID of the key will be printed
270 on stdout and the key will be attached to the destination keyring if
271 present. Error "Requested key not available" will be returned if the
272 key is not found.
273 $ keyctl search @us user debug:hello
275 23
276 $ keyctl search @us user debug:bye
277 keyctl_search: Requested key not available
278 Restrict a keyring
280 keyctl restrict_keyring <keyring> [<type> [<restriction>]]
281 This command limits the linkage of keys to the given keyring using a
283 provided restriction scheme. The scheme is associated with a given key
284 type, with further details provided in the restriction option string.
285 Options typically contain a restriction name possibly followed by key
286 ids or other data relevant to the restriction. If no restriction scheme
287 is provided, the keyring will reject all links.
288 $ keyctl restrict_keyring $1 asymmetric builtin_trusted
290 Read a key
292 keyctl read <key>
293 keyctl pipe <key>
294 keyctl print <key>
295 These commands read the payload of a key. "read" prints it on stdout as
297 a hex dump, "pipe" dumps the raw data to stdout and "print" dumps it to
298 stdout directly if it's entirely printable or as a hexdump preceded by
299 ":hex:" if not.
300 If the key type does not support reading of the payload, then error
302 "Operation not supported" will be returned.
303 $ keyctl read 26
305 1 bytes of data in key:
306 62
307 $ keyctl print 26
308 b
309 $ keyctl pipe 26
310 $
311 List a keyring
313 keyctl list <keyring>
314 keyctl rlist <keyring>
315 These commands list the contents of a key as a keyring. "list" pretty
317 prints the contents and "rlist" just produces a space-separated list of
318 key IDs.
319 No attempt is made to check that the specified keyring is a keyring.
321 $ keyctl list @us
323 2 keys in keyring:
324 22: vrwsl---------- 4043 -1 keyring: _uid.4043
325 23: vrwsl---------- 4043 4043 user: debug:hello
326 $ keyctl rlist @us
327 22 23
328 Describe a key
330 keyctl describe <keyring>
331 keyctl rdescribe <keyring> [sep]
332 These commands fetch a description of a keyring. "describe" pretty
334 prints the description in the same fashion as the "list" command; "rde‐
335 scribe" prints the raw data returned from the kernel.
336 $ keyctl describe @us
338 -5: vrwsl---------- 4043 -1 keyring: _uid_ses.4043
339 $ keyctl rdescribe @us
340 keyring;4043;-1;3f1f0000;_uid_ses.4043
341 The raw string is "<type>;<uid>;<gid>;<perms>;<description>", where uid
343 and gid are the decimal user and group IDs, perms is the permissions
344 mask in hex, type and description are the type name and description
345 strings (neither of which will contain semicolons).
346 Change the access controls on a key
348 keyctl chown <key> <uid>
349 keyctl chgrp <key> <gid>
350 These two commands change the UID and GID associated with evaluating a
352 key's permissions mask. The UID also governs which quota a key is taken
353 out of.
354 The chown command is not currently supported; attempting it will earn
356 the error "Operation not supported" at best.
357 For non-superuser users, the GID may only be set to the process's GID
359 or a GID in the process's groups list. The superuser may set any GID it
360 likes.
361 $ sudo keyctl chown 27 0
363 keyctl_chown: Operation not supported
364 $ sudo keyctl chgrp 27 0
365 Set the permissions mask on a key
367 keyctl setperm <key> <mask>
368 This command changes the permission control mask on a key. The mask may
370 be specified as a hex number if it begins "0x", an octal number if it
371 begins "0" or a decimal number otherwise.
372 The hex numbers are a combination of:
374 Possessor UID GID Other Permission Granted
376 ======== ======== ======== ======== ==================
377 01000000 00010000 00000100 00000001 View
378 02000000 00020000 00000200 00000002 Read
379 04000000 00040000 00000400 00000004 Write
380 08000000 00080000 00000800 00000008 Search
381 10000000 00100000 00001000 00000010 Link
382 20000000 00200000 00002000 00000020 Set Attribute
383 3f000000 003f0000 00003f00 0000003f All
384 View permits the type, description and other parameters of a key to be
386 viewed.
387 Read permits the payload (or keyring list) to be read if supported by
389 the type.
390 Write permits the payload (or keyring list) to be modified or updated.
392 Search on a key permits it to be found when a keyring to which it is
394 linked is searched.
395 Link permits a key to be linked to a keyring.
397 Set Attribute permits a key to have its owner, group membership, per‐
399 missions mask and timeout changed.
400 $ keyctl setperm 27 0x1f1f1f00
402 Start a new session with fresh keyrings
404 keyctl session
405 keyctl session - [<prog> <arg1> <arg2> ...]
406 keyctl session <name> [<prog> <arg1> <arg2> ...]
407 These commands join or create a new keyring and then run a shell or
409 other program with that keyring as the session key.
410 The variation with no arguments just creates an anonymous session
412 keyring and attaches that as the session keyring; it then exec's
413 $SHELL.
414 The variation with a dash in place of a name creates an anonymous ses‐
416 sion keyring and attaches that as the session keyring; it then exec's
417 the supplied command, or $SHELL if one isn't supplied.
418 The variation with a name supplied creates or joins the named keyring
420 and attaches that as the session keyring; it then exec's the supplied
421 command, or $SHELL if one isn't supplied.
422 $ keyctl rdescribe @s
424 keyring;4043;-1;3f1f0000;_uid_ses.4043
425 $ keyctl session
427 Joined session keyring: 28
428 $ keyctl rdescribe @s
430 keyring;4043;4043;3f1f0000;_ses.24082
431 $ keyctl session -
433 Joined session keyring: 29
434 $ keyctl rdescribe @s
435 keyring;4043;4043;3f1f0000;_ses.24139
436 $ keyctl session - keyctl rdescribe @s
438 Joined session keyring: 30
439 keyring;4043;4043;3f1f0000;_ses.24185
440 $ keyctl session fish
442 Joined session keyring: 34
443 $ keyctl rdescribe @s
444 keyring;4043;4043;3f1f0000;fish
445 $ keyctl session fish keyctl rdesc @s
447 Joined session keyring: 35
448 keyring;4043;4043;3f1f0000;fish
449 Instantiate a key
451 keyctl instantiate <key> <data> <keyring>
452 keyctl pinstantiate <key> <keyring>
453 keyctl negate <key> <timeout> <keyring>
454 keyctl reject <key> <timeout> <error> <keyring>
455 These commands are used to attach data to a partially set up key (as
457 created by the kernel and passed to /sbin/request-key). "instantiate"
458 marks a key as being valid and attaches the data as the payload.
459 "negate" and "reject" mark a key as invalid and sets a timeout on it so
460 that it'll go away after a while. This prevents a lot of quickly
461 sequential requests from slowing the system down overmuch when they all
462 fail, as all subsequent requests will then fail with error "Requested
463 key not found" (if negated) or the specified error (if rejected) until
464 the negative key has expired.
465 Reject's error argument can either be a UNIX error number or one of
467 'rejected', 'expired' or 'revoked'.
468 The newly instantiated key will be attached to the specified keyring.
470 These commands may only be run from the program run by request-key - a
472 special authorisation key is set up by the kernel and attached to the
473 request-key's session keyring. This special key is revoked once the key
474 to which it refers has been instantiated one way or another.
475 $ keyctl instantiate $1 "Debug $3" $4
477 $ keyctl negate $1 30 $4
478 $ keyctl reject $1 30 64 $4
479 The pinstantiate variant of the command reads the data from stdin
481 rather than taking it from the command line:
482 $ echo -n "Debug $3" | keyctl pinstantiate $1 $4
484 Set the expiry time on a key
486 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 $ keyctl timeout $1 45
493 Retrieve a key's security context
495 keyctl security <key>
496 This command is used to retrieve a key's LSM security context. The
498 label is printed on stdout.
499 $ keyctl security @s
501 unconfined_u:unconfined_r:unconfined_t:s0-s0:c0.c1023
502 Give the parent process a new session keyring
504 keyctl new_session
505 This command is used to give the invoking process (typically a shell) a
507 new session keyring, discarding its old session keyring.
508 $ keyctl session foo
510 Joined session keyring: 723488146
511 $ keyctl show
512 Session Keyring
513 -3 --alswrv 0 0 keyring: foo
514 $ keyctl new_session
515 490511412
516 $ keyctl show
517 Session Keyring
518 -3 --alswrv 0 0 keyring: _ses
519 Note that this affects the parent of the process that invokes the sys‐
521 tem call, and so may only affect processes with matching credentials.
522 Furthermore, the change does not take effect till the parent process
523 next transitions from kernel space to user space - typically when the
524 wait() system call returns.
525 Remove dead keys from the session keyring tree
527 keyctl reap
528 This command performs a depth-first search of the caller's session
530 keyring tree and attempts to unlink any key that it finds that is inac‐
531 cessible due to expiry, revocation, rejection or negation. It does not
532 attempt to remove live keys that are unavailable simply due to a lack
533 of granted permission.
534 A key that is designated reapable will only be removed from a keyring
536 if the caller has Write permission on that keyring, and only keyrings
537 that grant Search permission to the caller will be searched.
538 The command prints the number of keys reaped before it exits. If the
540 -v flag is passed then the reaped keys are listed as they're being
541 reaped, together with the success or failure of the unlink.
542 Remove matching keys from the session keyring tree
544 keyctl purge <type>
545 keyctl purge [-i] [-p] <type> <desc>
546 keyctl purge -s <type> <desc>
547 These commands perform a depth-first search to find matching keys in
549 the caller's session keyring tree and attempts to unlink them. The
550 number of keys successfully unlinked is printed at the end.
551 The keyrings must grant Read and View permission to the caller to be
553 searched, and the keys to be removed must also grant View permission.
554 Keys can only be removed from keyrings that grant Write permission.
555 The first variant purges all keys of the specified type.
557 The second variant purges all keys of the specified type that also
559 match the given description literally. The -i flag allows a case-inde‐
560 pendent match and the -p flag allows a prefix match.
561 The third variant purges all keys of the specified type and matching
563 description using the key type's comparator in the kernel to match the
564 description. This permits the key type to match a key with a variety
565 of descriptions.
566 Get persistent keyring
568 keyctl get_persistent <keyring> [<uid>]
569 This command gets the persistent keyring for either the current UID or
571 the specified UID and attaches it to the nominated keyring. The per‐
572 sistent keyring's ID will be printed on stdout.
573 The kernel will create the keyring if it doesn't exist and every time
575 this command is called, will reset the expiration timeout on the
576 keyring to the value in:
577 /proc/sys/kernel/keys/persistent_keyring_expiry
579 (by default three days). Should the timeout be reached, the persistent
581 keyring will be removed and everything it pins can then be garbage col‐
582 lected.
583 If a UID other than the process's real or effective UIDs is specified,
585 then an error will be given if the process does not have the CAP_SETUID
586 capability.
587 Compute a Diffie-Hellman shared secret or public key
589 keyctl dh_compute <private> <prime> <base>
590 This command computes either a Diffie-Hellman shared secret or the pub‐
592 lic key corresponding to the provided private key using the payloads of
593 three keys. The computation is:
594 base ^ private (mod prime)
596 The three inputs must be user keys with read permission. If the pro‐
598 vided base key contains the shared generator value, the public key will
599 be computed. If the provided base key contains the remote public key
600 value, the shared secret will be computed.
601 The result is printed to stdout as a hex dump.
603 $ keyctl dh_compute $1 $2 $3
605 8 bytes of data in result:
606 00010203 04050607
607 Compute a Diffie-Hellman shared secret and derive key material
609 keyctl dh_compute_kdf <private> <prime> <base> <output_length>
610 <hash_type>
611 This command computes a Diffie-Hellman shared secret and derives key
613 material from the shared secret using a key derivation function (KDF).
614 The shared secret is derived as outlined above and is input to the KDF
615 using the specified hash type. The hash type must point to a hash name
616 known to the kernel crypto API.
617 The operation derives key material of the length specified by the call‐
619 er.
620 The operation is compliant to the specification of SP800-56A.
622 The result is printed to stdout as hex dump.
624 Compute a Diffie-Hellman shared secret and apply KDF with other input
626 keyctl dh_compute_kdf_oi <private> <prime> <base> <output_length>
627 <hash_type>
628 This command is identical to the command dh_compute_kdf to generate a
630 Diffie-Hellman shared secret followed by a key derivation operation.
631 This command allows the caller to provide the other input data (OI
632 data) compliant to SP800-56A via stdin.
633 Perform public-key operations with an asymmetric key
635 keyctl pkey_query <key> <pass> [k=v]*
636 keyctl pkey_encrypt <key> <pass> <datafile> [k=v]* > <encfile>
637 keyctl pkey_decrypt <key> <pass> <encfile> [k=v]* > <datafile>
638 keyctl pkey_sign <key> <pass> <datafile> [k=v]* > <sigfile>
639 keyctl pkey_verify <key> <pass> <datafile> <sigfile> [k=v]*
640 These commands query an asymmetric key, encrypt data with it, decrypt
642 the encrypted data, generate a signature over some data and verify that
643 signature. For encrypt, decrypt and sign, the resulting data is writ‐
644 ten to stdout; verify reads the data and the signature files and com‐
645 pares them.
646 [!] NOTE that the data is of very limited capacity, with no more bits
648 than the size of the key. For signatures, the caller is expected to
649 digest the actual data and pass in the result of the digest as the
650 datafile. The name of the digest should be specified on the end of the
651 command line as "hash=<name>".
652 The key ID indicates the key to use; pass is a placeholder for future
654 password provision and should be "0" for the moment; datafile is the
655 unencrypted data to be encrypted, signed or to have its signature
656 checked; encfile is a file containing encrypted data; and sigfile is a
657 file containing a signature.
658 A list of parameters in "key[=val]" form can be included on the end of
660 the command line. These specify things like the digest algorithm used
661 ("hash=<name>") or the encoding form ("enc=<type>").
662 k=`keyctl padd asymmetric "" @s <key.pkcs8.der`
664 keyctl pkey_query $k 0 enc=pkcs1 hash=sha256
665 keyctl pkey_encrypt $k 0 foo.hash enc=pkcs1 >foo.enc
666 keyctl pkey_decrypt $k 0 foo.enc enc=pkcs1 >foo.hash
667 keyctl pkey_sign $k 0 foo.hash enc=pkcs1 hash=sha256 >foo.sig
668 keyctl pkey_verify $k 0 foo.hash foo.sig enc=pkcs1 hash=sha256
669 See asymmetric-key(7) for more information.
671
674 There are a number of common errors returned by this program:
675 "Not a directory" - a key wasn't a keyring.
677 "Requested key not found" - the looked for key isn't available.
679 "Key has been revoked" - a revoked key was accessed.
681 "Key has expired" - an expired key was accessed.
683 "Permission denied" - permission was denied by a UID/GID/mask combina‐
685 tion.
686
688 keyctl(1), keyctl(2), request_key(2), keyctl(3), request-key.conf(5),
689 keyrings(7), request-key(8)
690Linux 20 Feb 2014 KEYCTL(1)