1KEYCTL(1)               Linux Key Management Utilities               KEYCTL(1)
2
3
4

NAME

6       keyctl - key management facility control
7

SYNOPSIS

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

DESCRIPTION

52       This  program is used to control the key management facility in various
53       ways using a variety of subcommands.
54

KEY IDENTIFIERS

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
60       No key: 0
61
62       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
67       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
73       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
80       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
85       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
90       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
94       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
99       Keyring by name: %:<name>
100              A named keyring.  This will be searched  for  in  the  process's
101              keyrings and in /proc/keys.
102
103       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

COMMAND SYNTAX

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
112   Display the package version number
113       keyctl --version
114
115       This command prints the package  version  number  and  build  date  and
116       exits:
117
118              $ keyctl --version
119              keyctl from keyutils-1.5.3 (Built 2011-08-24)
120
121   Show process keyrings
122       keyctl show [-x] [<keyring>]
123
124       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
129   Add a key to a keyring
130       keyctl add <type> <desc> <data> <keyring>
131       keyctl padd <type> <desc> <keyring>
132
133       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
137              $ keyctl add user mykey stuff @u
138              26
139
140       The padd variant of the command reads the data from stdin  rather  than
141       taking it from the command line:
142
143              $ echo -n stuff | keyctl padd user mykey @u 26
144
145   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
150       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
155       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
162       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
165       If a valid key is obtained, the ID will be printed and the key attached
166       as if the original search had succeeded.
167
168       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
172              $ 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
179   Update a key
180       keyctl update <key> <data>
181       keyctl pupdate <key>
182
183       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
187              $ keyctl update 23 zebra
188
189       The  pupdate  variant  of  the command reads the data from stdin rather
190       than taking it from the command line:
191
192              $ echo -n zebra | keyctl pupdate 23
193
194   Create a keyring
195       keyctl newring <name> <keyring>
196
197       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
201              $ keyctl newring squelch @us
202              27
203
204   Revoke a key
205       keyctl revoke <key>
206
207       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
211              $ keyctl revoke 26
212              $ keyctl describe 26
213              keyctl_describe: Key has been revoked
214
215   Clear a keyring
216       keyctl clear <keyring>
217
218       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
222              $ keyctl clear 27
223
224   Link a key to a keyring
225       keyctl link <key> <keyring>
226
227       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
235              $ keyctl link 23 27
236              $ keyctl link 27 27
237              keyctl_link: Resource deadlock avoided
238
239   Unlink a key from a keyring or the session keyring tree
240       keyctl unlink <key> [<keyring>]
241
242       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
248       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
253              $ keyctl unlink 23 27
254
255   Search a keyring
256       keyctl search <keyring> <type> <desc> [<dest_keyring>]
257
258       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
264              $ keyctl search @us user debug:hello
265              23
266              $ keyctl search @us user debug:bye
267              keyctl_search: Requested key not available
268
269   Read a key
270       keyctl read <key>
271       keyctl pipe <key>
272       keyctl print <key>
273
274       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
279       If the key type does not support reading of  the  payload,  then  error
280       "Operation not supported" will be returned.
281
282              $ keyctl read 26
283              1 bytes of data in key:
284              62
285              $ keyctl print 26
286              b
287              $ keyctl pipe 26
288              $
289
290   List a keyring
291       keyctl list <keyring>
292       keyctl rlist <keyring>
293
294       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
298       No attempt is made to check that the specified keyring is a keyring.
299
300              $ 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
307   Describe a key
308       keyctl describe <keyring>
309       keyctl rdescribe <keyring> [sep]
310
311       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
315              $ 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
320       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
325   Change the access controls on a key
326       keyctl chown <key> <uid>
327       keyctl chgrp <key> <gid>
328
329       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
333       The chown command is not currently supported; attempting it  will  earn
334       the error "Operation not supported" at best.
335
336       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
340              $ sudo keyctl chown 27 0
341              keyctl_chown: Operation not supported
342              $ sudo keyctl chgrp 27 0
343
344   Set the permissions mask on a key
345       keyctl setperm <key> <mask>
346
347       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
351       The hex numbers are a combination of:
352
353              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
363       View  permits the type, description and other parameters of a key to be
364       viewed.
365
366       Read permits the payload (or keyring list) to be read if  supported  by
367       the type.
368
369       Write permits the payload (or keyring list) to be modified or updated.
370
371       Search  on  a  key permits it to be found when a keyring to which it is
372       linked is searched.
373
374       Link permits a key to be linked to a keyring.
375
376       Set Attribute permits a key to have its owner, group  membership,  per‐
377       missions mask and timeout changed.
378
379              $ keyctl setperm 27 0x1f1f1f00
380
381   Start a new session with fresh keyrings
382       keyctl session
383       keyctl session - [<prog> <arg1> <arg2> ...]
384       keyctl session <name> [<prog> <arg1> <arg2> ...]
385
386       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
389       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
393       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
397       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
401              $ keyctl rdescribe @s
402              keyring;4043;-1;3f1f0000;_uid_ses.4043
403
404              $ keyctl session
405              Joined session keyring: 28
406
407              $ keyctl rdescribe @s
408              keyring;4043;4043;3f1f0000;_ses.24082
409
410              $ keyctl session -
411              Joined session keyring: 29
412              $ keyctl rdescribe @s
413              keyring;4043;4043;3f1f0000;_ses.24139
414
415              $ keyctl session - keyctl rdescribe @s
416              Joined session keyring: 30
417              keyring;4043;4043;3f1f0000;_ses.24185
418
419              $ keyctl session fish
420              Joined session keyring: 34
421              $ keyctl rdescribe @s
422              keyring;4043;4043;3f1f0000;fish
423
424              $ keyctl session fish keyctl rdesc @s
425              Joined session keyring: 35
426              keyring;4043;4043;3f1f0000;fish
427
428   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
434       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
444       Reject's error argument can either be a UNIX error  number  or  one  of
445       'rejected', 'expired' or 'revoked'.
446
447       The newly instantiated key will be attached to the specified keyring.
448
449       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
454              $ keyctl instantiate $1 "Debug $3" $4
455              $ keyctl negate $1 30 $4
456              $ keyctl reject $1 30 64 $4
457
458       The pinstantiate variant of the  command  reads  the  data  from  stdin
459       rather than taking it from the command line:
460
461              $ echo -n "Debug $3" | keyctl pinstantiate $1 $4
462
463   Set the expiry time on a key
464       keyctl timeout <key> <timeout>
465
466       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
470              $ keyctl timeout $1 45
471
472   Retrieve a key's security context
473       keyctl security <key>
474
475       This  command  is  used  to retrieve a key's LSM security context.  The
476       label is printed on stdout.
477
478              $ keyctl security @s
479              unconfined_u:unconfined_r:unconfined_t:s0-s0:c0.c1023
480
481   Give the parent process a new session keyring
482       keyctl new_session
483
484       This command is used to give the invoking process (typically a shell) a
485       new session keyring, discarding its old session keyring.
486
487              $  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
498       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
504   Remove dead keys from the session keyring tree
505       keyctl reap
506
507       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
513       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
517       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
521   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
526       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
530       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
534       The first variant purges all keys of the specified type.
535
536       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
540       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
545   Get persistent keyring
546       keyctl get_persistent <keyring> [<uid>]
547
548       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
552       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
556              /proc/sys/kernel/keys/persistent_keyring_expiry
557
558       (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
562       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
566   Compute a Diffie-Hellman shared secret or public key
567       keyctl dh_compute <private> <prime> <base>
568
569       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
573              base ^ private (mod prime)
574
575       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
580       The result is printed to stdout as a hex dump.
581
582              $ keyctl dh_compute $1 $2 $3
583              8 bytes of data in result:
584              00010203 04050607
585

ERRORS

587       There are a number of common errors returned by this program:
588
589       "Not a directory" - a key wasn't a keyring.
590
591       "Requested key not found" - the looked for key isn't available.
592
593       "Key has been revoked" - a revoked key was accessed.
594
595       "Key has expired" - an expired key was accessed.
596
597       "Permission  denied" - permission was denied by a UID/GID/mask combina‐
598       tion.
599

SEE ALSO

601       keyctl(1), keyctl(2), request_key(2), keyctl(3), request-key.conf(5),
602       keyrings(7), request-key(8)
603
604
605
606Linux                             20 Feb 2014                        KEYCTL(1)
Impressum