2 .\" Copyright (C) 2004 Red Hat, Inc. All Rights Reserved.
3 .\" Written by David Howells (dhowells@redhat.com)
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.
10 .TH KEYCTL 1 "17 Nov 2005" Linux "Linux Key Management Utilities"
12 keyctl - Key management facility control
16 \fBkeyctl\fR add <type> <desc> <data> <keyring>
18 \fBkeyctl\fR padd <type> <desc> <keyring>
20 \fBkeyctl\fR request <type> <desc> [<dest_keyring>]
22 \fBkeyctl\fR request2 <type> <desc> <info> [<dest_keyring>]
24 \fBkeyctl\fR prequest2 <type> <desc> [<dest_keyring>]
26 \fBkeyctl\fR update <key> <data>
28 \fBkeyctl\fR pupdate <key>
30 \fBkeyctl\fR newring <name> <keyring>
32 \fBkeyctl\fR revoke <key>
34 \fBkeyctl\fR clear <keyring>
36 \fBkeyctl\fR link <key> <keyring>
38 \fBkeyctl\fR unlink <key> <keyring>
40 \fBkeyctl\fR search <keyring> <type> <desc> [<dest_keyring>]
42 \fBkeyctl\fR read <key>
44 \fBkeyctl\fR pipe <key>
46 \fBkeyctl\fR print <key>
48 \fBkeyctl\fR list <keyring>
50 \fBkeyctl\fR rlist <keyring>
52 \fBkeyctl\fR describe <keyring>
54 \fBkeyctl\fR rdescribe <keyring> [sep]
56 \fBkeyctl\fR chown <key> <uid>
58 \fBkeyctl\fR chgrp <key> <gid>
60 \fBkeyctl\fR setperm <key> <mask>
64 \fBkeyctl\fR session - [<prog> <arg1> <arg2> ...]
66 \fBkeyctl\fR session <name> [<prog> <arg1> <arg2> ...]
68 \fBkeyctl\fR instantiate <key> <data> <keyring>
70 \fBkeyctl\fR pinstantiate <key> <keyring>
72 \fBkeyctl\fR negate <key> <timeout> <keyring>
74 \fBkeyctl\fR reject <key> <timeout> <error> <keyring>
76 \fBkeyctl\fR timeout <key> <timeout>
78 \fBkeyctl\fR security <key>
80 \fBkeyctl\fR reap [-v]
82 \fBkeyctl\fR purge <type>
84 \fBkeyctl\fR purge [-i] [-p] <type> <desc>
86 \fBkeyctl\fR purge -s <type> <desc>
88 This program is used to control the key management facility in various ways
89 using a variety of subcommands.
92 The key identifiers passed to or returned from keyctl are, in general, positive
93 integers. There are, however, some special values with special meanings that
94 can be passed as arguments:
98 (*) Thread keyring: \fB@t\fR or \fB-1\fR
100 Each thread may have its own keyring. This is searched first, before all
101 others. The thread keyring is replaced by (v)fork, exec and clone.
103 (*) Process keyring: \fB@p\fR or \fB-2\fR
105 Each process (thread group) may have its own keyring. This is shared between
106 all members of a group and will be searched after the thread keyring. The
107 process keyring is replaced by (v)fork and exec.
109 (*) Session keyring: \fB@s\fR or \fB-3\fR
111 Each process subscribes to a session keyring that is inherited across (v)fork,
112 exec and clone. This is searched after the process keyring. Session keyrings
113 can be named and an extant keyring can be joined in place of a process's
114 current session keyring.
116 (*) User specific keyring: \fB@u\fR or \fB-4\fR
118 This keyring is shared between all the processes owned by a particular user. It
119 isn't searched directly, but is normally linked to from the session keyring.
121 (*) User default session keyring: \fB@us\fR or \fB-5\fR
123 This is the default session keyring for a particular user. Login processes that
124 change to a particular user will bind to this session until another session is
127 (*) Group specific keyring: \fB@g\fR or \fB-6\fR
129 This is a place holder for a group specific keyring, but is not actually
130 implemented yet in the kernel.
132 (*) Assumed request_key authorisation key: \fB@a\fR or \fB-7\fR
134 This selects the authorisation key provided to the request_key() helper to
135 permit it to access the callers keyrings and instantiate the target key.
137 Any non-ambiguous shortening of a command name may be used in lieu of the full
138 command name. This facility should not be used in scripting as new commands may
139 be added in future that then cause ambiguity.
141 (*) \fBShow process keyrings\fR
145 This command recursively shows what keyrings a process is subscribed to and
146 what keys and keyrings they contain.
148 (*) \fBAdd a key to a keyring\fR
150 \fBkeyctl add\fR <type> <desc> <data> <keyring>
152 \fBkeyctl padd\fR <type> <desc> <keyring>
154 This command creates a key of the specified type and description; instantiates
155 it with the given data and attaches it to the specified keyring. It then prints
156 the new key's ID on stdout:
159 testbox>keyctl add user mykey stuff @u
164 The \fBpadd\fR variant of the command reads the data from stdin rather than
165 taking it from the command line:
168 testbox>echo -n stuff | keyctl padd user mykey @u
173 (*) \fBRequest a key\fR
175 \fBkeyctl request\fR <type> <desc> [<dest_keyring>]
177 \fBkeyctl request2\fR <type> <desc> <info> [<dest_keyring>]
179 \fBkeyctl prequest2\fR <type> <desc> [<dest_keyring>]
181 These three commands request the lookup of a key of the given type and
182 description. The process's keyrings will be searched, and if a match is found
183 the matching key's ID will be printed to stdout; and if a destination keyring
184 is given, the key will be added to that keyring also.
186 If there is no key, the first command will simply return the error ENOKEY and
187 fail. The second and third commands will create a partial key with the type and
188 description, and call out to \fB/sbin/request-key\fR with that key and the
189 extra information supplied. This will then attempt to instantiate the key in
190 some manner, such that a valid key is obtained.
192 The third command is like the second, except that the callout information is
193 read from stdin rather than being passed on the command line.
195 If a valid key is obtained, the ID will be printed and the key attached as if
196 the original search had succeeded.
198 If there wasn't a valid key obtained, a temporary negative key will be attached
199 to the destination keyring if given and the error "Requested key not available"
203 testbox>keyctl request2 user debug:hello wibble
207 testbox>echo -n wibble | keyctl prequest2 user debug:hello
211 testbox>keyctl request user debug:hello
216 (*) \fBUpdate a key\fR
218 \fBkeyctl update\fR <key> <data>
220 \fBkeyctl pupdate\fR <key>
222 This command replaces the data attached to a key with a new set of data. If the
223 type of the key doesn't support update then error "Operation not supported"
227 testbox>keyctl update 23 zebra
230 The \fBpupdate\fR variant of the command reads the data from stdin rather than
231 taking it from the command line:
234 testbox>echo -n zebra | keyctl pupdate 23
237 (*) \fBCreate a keyring\fR
239 \fBkeyctl newring\fR <name> <keyring>
241 This command creates a new keyring of the specified name and attaches it to the
242 specified keyring. The ID of the new keyring will be printed to stdout if
246 testbox>keyctl newring squelch @us
251 (*) \fBRevoke a key\fR
253 \fBkeyctl revoke\fR <key>
255 This command marks a key as being revoked. Any further operations on that key
256 (apart from unlinking it) will return error "Key has been revoked".
259 testbox>keyctl revoke 26
261 testbox>keyctl describe 26
263 keyctl_describe: Key has been revoked
266 (*) \fBClear a keyring\fR
268 \fBkeyctl clear\fR <keyring>
270 This command unlinks all the keys attached to the specified keyring. Error
271 "Not a directory" will be returned if the key specified is not a keyring.
274 testbox>keyctl clear 27
277 (*) \fBLink a key to a keyring\fR
279 \fBkeyctl link\fR <key> <keyring>
281 This command makes a link from the key to the keyring if there's enough
282 capacity to do so. Error "Not a directory" will be returned if the destination
283 is not a keyring. Error "Permission denied" will be returned if the key doesn't
284 have link permission or the keyring doesn't have write permission. Error "File
285 table overflow" will be returned if the keyring is full. Error "Resource
286 deadlock avoided" will be returned if an attempt was made to introduce a
290 testbox>keyctl link 23 27
292 testbox>keyctl link 27 27
294 keyctl_link: Resource deadlock avoided
297 (*) \fBUnlink a key from a keyring or the session keyring tree\fR
299 \fBkeyctl unlink\fR <key> [<keyring>]
301 If the keyring is specified, this command removes a link to the key from the
302 keyring. Error "Not a directory" will be returned if the destination is not a
303 keyring. Error "Permission denied" will be returned if the keyring doesn't have
304 write permission. Error "No such file or directory" will be returned if the key
305 is not linked to by the keyring.
307 If the keyring is not specified, this command performs a depth-first search of
308 the session keyring tree and removes all the links to the nominated key that it
309 finds (and that it is permitted to remove). It prints the number of successful
310 unlinks before exiting.
313 testbox>keyctl unlink 23 27
316 (*) \fBSearch a keyring\fR
318 \fBkeyctl search\fR <keyring> <type> <desc> [<dest_keyring>]
320 This command non-recursively searches a keyring for a key of a particular type
321 and description. If found, the ID of the key will be printed on stdout and the
322 key will be attached to the destination keyring if present. Error "Requested
323 key not available" will be returned if the key is not found.
326 testbox>keyctl search @us user debug:hello
330 testbox>keyctl search @us user debug:bye
332 keyctl_search: Requested key not available
337 \fBkeyctl read\fR <key>
339 \fBkeyctl pipe\fR <key>
341 \fBkeyctl print\fR <key>
343 These commands read the payload of a key. "read" prints it on stdout as a hex
344 dump, "pipe" dumps the raw data to stdout and "print" dumps it to stdout
345 directly if it's entirely printable or as a hexdump preceded by ":hex:" if not.
347 If the key type does not support reading of the payload, then error "Operation
348 not supported" will be returned.
351 testbox>keyctl read 26
353 1 bytes of data in key:
357 testbox>keyctl print 26
361 testbox>keyctl pipe 26
366 (*) \fBList a keyring\fR
368 \fBkeyctl list\fR <keyring>
370 \fBkeyctl rlist\fR <keyring>
372 These commands list the contents of a key as a keyring. "list" pretty prints
373 the contents and "rlist" just produces a space-separated list of key IDs.
375 No attempt is made to check that the specified keyring is a keyring.
378 testbox>keyctl list @us
382 22: vrwsl---------- 4043 -1 keyring: _uid.4043
384 23: vrwsl---------- 4043 4043 user: debug:hello
386 testbox>keyctl rlist @us
391 (*) \fBDescribe a key\fR
393 \fBkeyctl describe\fR <keyring>
395 \fBkeyctl rdescribe\fR <keyring> [sep]
397 These commands fetch a description of a keyring. "describe" pretty prints the
398 description in the same fashion as the "list" command; "rdescribe" prints the
399 raw data returned from the kernel.
402 testbox>keyctl describe @us
403 -5: vrwsl---------- 4043 -1 keyring: _uid_ses.4043
404 testbox>keyctl rdescribe @us
405 keyring;4043;-1;3f1f0000;_uid_ses.4043
408 The raw string is "<type>;<uid>;<gid>;<perms>;<description>", where \fIuid\fR
409 and \fIgid\fR are the decimal user and group IDs, \fIperms\fR is the
410 permissions mask in hex, \fItype\fR and \fIdescription\fR are the type name and
411 description strings (neither of which will contain semicolons).
413 (*) \fBChange the access controls on a key\fR
415 \fBkeyctl chown\fR <key> <uid>
417 \fBkeyctl chgrp\fR <key> <gid>
419 These two commands change the UID and GID associated with evaluating a key's
420 permissions mask. The UID also governs which quota a key is taken out of.
422 The chown command is not currently supported; attempting it will earn the error
423 "Operation not supported" at best.
425 For non-superuser users, the GID may only be set to the process's GID or a GID
426 in the process's groups list. The superuser may set any GID it likes.
429 testbox>sudo keyctl chown 27 0
431 keyctl_chown: Operation not supported
433 testbox>sudo keyctl chgrp 27 0
436 (*) \fBSet the permissions mask on a key\fR
438 \fBkeyctl setperm\fR <key> <mask>
440 This command changes the permission control mask on a key. The mask may be
441 specified as a hex number if it begins "0x", an octal number if it begins "0"
442 or a decimal number otherwise.
444 The hex numbers are a combination of:
447 Possessor UID GID Other Permission Granted
449 ======== ======== ======== ======== ==================
451 01000000 00010000 00000100 00000001 View
453 02000000 00020000 00000200 00000002 Read
455 04000000 00040000 00000400 00000004 Write
457 08000000 00080000 00000800 00000008 Search
459 10000000 00100000 00001000 00000010 Link
461 20000000 00200000 00002000 00000020 Set Attribute
463 3f000000 003f0000 00003f00 0000003f All
466 \fIView\fR permits the type, description and other parameters of a key to be
469 \fIRead\fR permits the payload (or keyring list) to be read if supported by the
472 \fIWrite\fR permits the payload (or keyring list) to be modified or updated.
474 \fISearch\fR on a key permits it to be found when a keyring to which it is
477 \fILink\fR permits a key to be linked to a keyring.
479 \fISet Attribute\fR permits a key to have its owner, group membership,
480 permissions mask and timeout changed.
483 testbox>keyctl setperm 27 0x1f1f1f00
486 (*) \fBStart a new session with fresh keyrings\fR
490 \fBkeyctl session\fR - [<prog> <arg1> <arg2> ...]
492 \fBkeyctl session\fR <name> [<prog> <arg1> <arg2> ...]
494 These commands join or create a new keyring and then run a shell or other
495 program with that keyring as the session key.
497 The variation with no arguments just creates an anonymous session keyring and
498 attaches that as the session keyring; it then exec's $SHELL.
500 The variation with a dash in place of a name creates an anonymous session
501 keyring and attaches that as the session keyring; it then exec's the supplied
502 command, or $SHELL if one isn't supplied.
504 The variation with a name supplied creates or joins the named keyring and
505 attaches that as the session keyring; it then exec's the supplied command, or
506 $SHELL if one isn't supplied.
509 testbox>keyctl rdescribe @s
511 keyring;4043;-1;3f1f0000;_uid_ses.4043
513 testbox>keyctl session
515 Joined session keyring: 28
517 testbox>keyctl rdescribe @s
519 keyring;4043;4043;3f1f0000;_ses.24082
521 testbox>keyctl session -
523 Joined session keyring: 29
525 testbox>keyctl rdescribe @s
527 keyring;4043;4043;3f1f0000;_ses.24139
529 testbox>keyctl session - keyctl rdescribe @s
531 Joined session keyring: 30
533 keyring;4043;4043;3f1f0000;_ses.24185
535 testbox>keyctl session fish
537 Joined session keyring: 34
539 testbox>keyctl rdescribe @s
541 keyring;4043;4043;3f1f0000;fish
543 testbox>keyctl session fish keyctl rdesc @s
545 Joined session keyring: 35
547 keyring;4043;4043;3f1f0000;fish
550 (*) \fBInstantiate a key\fR
552 \fBkeyctl instantiate\fR <key> <data> <keyring>
554 \fBkeyctl pinstantiate\fR <key> <keyring>
556 \fBkeyctl negate\fR <key> <timeout> <keyring>
558 \fBkeyctl reject\fR <key> <timeout> <error> <keyring>
560 These commands are used to attach data to a partially set up key (as created by
561 the kernel and passed to /sbin/request-key). "instantiate" marks a key as
562 being valid and attaches the data as the payload. "negate" and "reject" mark a
563 key as invalid and sets a timeout on it so that it'll go away after a while.
564 This prevents a lot of quickly sequential requests from slowing the system down
565 overmuch when they all fail, as all subsequent requests will then fail with
566 error "Requested key not found" (if negated) or the specified error (if
567 rejected) until the negative key has expired.
569 Reject's error argument can either be a UNIX error number or one of
570 .BR "" "'" rejected "', '" expired "' or '" revoked "'."
572 The newly instantiated key will be attached to the specified keyring.
574 These commands may only be run from the program run by request-key - a special
575 authorisation key is set up by the kernel and attached to the request-key's
576 session keyring. This special key is revoked once the key to which it refers
577 has been instantiated one way or another.
580 testbox>keyctl instantiate $1 "Debug $3" $4
582 testbox>keyctl negate $1 30 $4
584 testbox>keyctl reject $1 30 64 $4
587 The \fBpinstantiate\fR variant of the command reads the data from stdin rather
588 than taking it from the command line:
591 testbox>echo -n "Debug $3" | keyctl pinstantiate $1 $4
594 (*) \fBSet the expiry time on a key\fR
596 \fBkeyctl timeout\fR <key> <timeout>
598 This command is used to set the timeout on a key, or clear an existing timeout
599 if the value specified is zero. The timeout is given as a number of seconds
603 testbox>keyctl timeout $1 45
606 (*) \fBRetrieve a key's security context\fR
608 \fBkeyctl security\fR <key>
610 This command is used to retrieve a key's LSM security context. The label is
614 testbox>keyctl security @s
616 unconfined_u:unconfined_r:unconfined_t:s0-s0:c0.c1023
619 (*) \fBGive the parent process a new session keyring\fR
621 \fBkeyctl new_session\fR
623 This command is used to give the invoking process (typically a shell) a new
624 session keyring, discarding its old session keyring.
627 testbox> keyctl session foo
629 Joined session keyring: 723488146
635 -3 --alswrv 0 0 keyring: foo
637 testbox> keyctl new_session
645 -3 --alswrv 0 0 keyring: _ses
648 Note that this affects the \fIparent\fP of the process that invokes the system
649 call, and so may only affect processes with matching credentials.
650 Furthermore, the change does not take effect till the parent process next
651 transitions from kernel space to user space - typically when the \fBwait\fP()
654 (*) \fBRemove dead keys from the session keyring tree\fR
658 This command performs a depth-first search of the caller's session keyring tree
659 and attempts to unlink any key that it finds that is inaccessible due to
660 expiry, revocation, rejection or negation. It does not attempt to remove live
661 keys that are unavailable simply due to a lack of granted permission.
663 A key that is designated reapable will only be removed from a keyring if the
664 caller has Write permission on that keyring, and only keyrings that grant
665 Search permission to the caller will be searched.
667 The command prints the number of keys reaped before it exits. If the \fB-v\fR
668 flag is passed then the reaped keys are listed as they're being reaped,
669 together with the success or failure of the unlink.
671 (*) \fBRemove matching keys from the session keyring tree\fR
673 \fBkeyctl\fR purge <type>
675 \fBkeyctl\fR purge [-i] [-p] <type> <desc>
677 \fBkeyctl\fR purge -s <type> <desc>
679 These commands perform a depth-first search to find matching keys in the
680 caller's session keyring tree and attempts to unlink them. The number of
681 keys successfully unlinked is printed at the end.
683 The keyrings must grant Read and View permission to the caller to be searched,
684 and the keys to be removed must also grant View permission. Keys can only be
685 removed from keyrings that grant Write permission.
687 The first variant purges all keys of the specified type.
689 The second variant purges all keys of the specified type that also match the
690 given description literally. The -i flag allows a case-independent match and
691 the -p flag allows a prefix match.
693 The third variant purges all keys of the specified type and matching
694 description using the key type's comparator in the kernel to match the
695 description. This permits the key type to match a key with a variety of
700 There are a number of common errors returned by this program:
702 "Not a directory" - a key wasn't a keyring.
704 "Requested key not found" - the looked for key isn't available.
706 "Key has been revoked" - a revoked key was accessed.
708 "Key has expired" - an expired key was accessed.
710 "Permission denied" - permission was denied by a UID/GID/mask combination.
713 \fBkeyctl\fR(1), \fBrequest-key.conf\fR(5)
projects / platform / upstream / keyutils.git / blob