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

NAME

6       keyctl - Key management facility control
7

SYNOPSIS

9       keyctl show
10       keyctl add <type> <desc> <data> <keyring>
11       keyctl padd <type> <desc> <keyring>
12       keyctl request <type> <desc> [<dest_keyring>]
13       keyctl request2 <type> <desc> <info> [<dest_keyring>]
14       keyctl prequest2 <type> <desc> [<dest_keyring>]
15       keyctl update <key> <data>
16       keyctl pupdate <key>
17       keyctl newring <name> <keyring>
18       keyctl revoke <key>
19       keyctl clear <keyring>
20       keyctl link <key> <keyring>
21       keyctl unlink <key> <keyring>
22       keyctl search <keyring> <type> <desc> [<dest_keyring>]
23       keyctl read <key>
24       keyctl pipe <key>
25       keyctl print <key>
26       keyctl list <keyring>
27       keyctl rlist <keyring>
28       keyctl describe <keyring>
29       keyctl rdescribe <keyring> [sep]
30       keyctl chown <key> <uid>
31       keyctl chgrp <key> <gid>
32       keyctl setperm <key> <mask>
33       keyctl session
34       keyctl session - [<prog> <arg1> <arg2> ...]
35       keyctl session <name> [<prog> <arg1> <arg2> ...]
36       keyctl instantiate <key> <data> <keyring>
37       keyctl pinstantiate <key> <keyring>
38       keyctl negate <key> <timeout> <keyring>
39       keyctl timeout <key> <timeout>
40

DESCRIPTION

42       This  program is used to control the key management facility in various
43       ways using a variety of subcommands.
44

KEY IDENTIFIERS

46       The key identifiers passed to or returned from keyctl are, in  general,
47       positive integers. There are, however, some special values with special
48       meanings that can be passed as arguments:
49
50       (*) No key: 0
51
52       (*) Thread keyring: @t or -1
53
54       Each thread may have its own keyring. This is  searched  first,  before
55       all others. The thread keyring is replaced by (v)fork, exec and clone.
56
57       (*) Process keyring: @p or -2
58
59       Each  process  (thread  group) may have its own keyring. This is shared
60       between all members of a group and will be searched  after  the  thread
61       keyring. The process keyring is replaced by (v)fork and exec.
62
63       (*) Session keyring: @s or -3
64
65       Each  process  subscribes to a session keyring that is inherited across
66       (v)fork, exec and clone. This is searched after  the  process  keyring.
67       Session  keyrings  can  be named and an extant keyring can be joined in
68       place of a process's current session keyring.
69
70       (*) User specific keyring: @u or -4
71
72       This keyring is shared between all the processes owned by a  particular
73       user.  It  isn't  searched directly, but is normally linked to from the
74       session keyring.
75
76       (*) User default session keyring: @us or -5
77
78       This is the default session keyring for a particular user.  Login  pro‐
79       cesses that change to a particular user will bind to this session until
80       another session is set.
81
82       (*) Group specific keyring: @g or -6
83
84       This is a place holder for a group specific keyring, but is  not  actu‐
85       ally implemented yet in the kernel.
86
87       (*) Assumed request_key authorisation key: @a or -7
88
89       This selects the authorisation key provided to the request_key() helper
90       to permit it to access the callers keyrings and instantiate the  target
91       key.
92

COMMAND SYNTAX

94       Any  non-ambiguous  shortening of a command name may be used in lieu of
95       the full command name. This facility should not be used in scripting as
96       new commands may be added in future that then cause ambiguity.
97
98       (*) Show process keyrings
99
100       keyctl show
101
102       This command recursively shows what keyrings a process is subscribed to
103       and what keys and keyrings they contain.
104
105       (*) Add a key to a keyring
106
107       keyctl add <type> <desc> <data> <keyring>
108       keyctl padd <type> <desc> <keyring>
109
110       This command creates a key  of  the  specified  type  and  description;
111       instantiates  it  with  the given data and attaches it to the specified
112       keyring. It then prints the new key's ID on stdout:
113
114              testbox>keyctl add user mykey stuff @u
115              26
116
117       The padd variant of the command reads the data from stdin  rather  than
118       taking it from the command line:
119
120              testbox>echo -n stuff | keyctl padd user mykey @u
121              26
122
123       (*) Request a key
124
125       keyctl request <type> <desc> [<dest_keyring>]
126       keyctl request2 <type> <desc> <info> [<dest_keyring>]
127       keyctl prequest2 <type> <desc> [<dest_keyring>]
128
129       These  three commands request the lookup of a key of the given type and
130       description. The process's keyrings will be searched, and if a match is
131       found  the matching key's ID will be printed to stdout; and if a desti‐
132       nation keyring is given, the key will be added to that keyring also.
133
134       If there is no key, the first command  will  simply  return  the  error
135       ENOKEY  and  fail.  The second and third commands will create a partial
136       key with the type and description, and call  out  to  /sbin/request-key
137       with  that  key  and  the  extra  information  supplied. This will then
138       attempt to instantiate the key in some manner, such that a valid key is
139       obtained.
140
141       The  third command is like the second, except that the callout informa‐
142       tion is read from stdin rather than being passed on the command line.
143
144       If a valid key is obtained, the ID will be printed and the key attached
145       as if the original search had succeeded.
146
147       If  there wasn't a valid key obtained, a temporary negative key will be
148       attached to the destination keyring if given and the  error  "Requested
149       key not available" will be given.
150
151              testbox>keyctl request2 user debug:hello wibble
152              23
153              testbox>echo -n wibble | keyctl prequest2 user debug:hello
154              23
155              testbox>keyctl request user debug:hello
156              23
157
158       (*) Update a key
159
160       keyctl update <key> <data>
161       keyctl pupdate <key>
162
163       This  command  replaces  the  data  attached to a key with a new set of
164       data. If the type of the key doesn't support update then error  "Opera‐
165       tion not supported" will be returned.
166
167              testbox>keyctl update 23 zebra
168
169       The  pupdate  variant  of  the command reads the data from stdin rather
170       than taking it from the command line:
171
172              testbox>echo -n zebra | keyctl pupdate 23
173
174       (*) Create a keyring
175
176       keyctl newring <name> <keyring>
177
178       This command creates a new keyring of the specified name  and  attaches
179       it  to the specified keyring. The ID of the new keyring will be printed
180       to stdout if successful.
181
182              testbox>keyctl newring squelch @us
183              27
184
185       (*) Revoke a key
186
187       keyctl revoke <key>
188
189       This command marks a key as being revoked. Any  further  operations  on
190       that  key  (apart  from  unlinking  it) will return error "Key has been
191       revoked".
192
193              testbox>keyctl revoke 26
194              testbox>keyctl describe 26
195              keyctl_describe: Key has been revoked
196
197       (*) Clear a keyring
198
199       keyctl clear <keyring>
200
201       This command unlinks all the keys attached to  the  specified  keyring.
202       Error  "Not a directory" will be returned if the key specified is not a
203       keyring.
204
205              testbox>keyctl clear 27
206
207       (*) Link a key to a keyring
208
209       keyctl link <key> <keyring>
210
211       This command makes a link from the key to the keyring if there's enough
212       capacity to do so. Error "Not a directory" will be returned if the des‐
213       tination is not a keyring. Error "Permission denied" will  be  returned
214       if  the  key  doesn't  have link permission or the keyring doesn't have
215       write permission. Error "File table overflow" will be returned  if  the
216       keyring  is full. Error "Resource deadlock avoided" will be returned if
217       an attempt was made to introduce a recursive link.
218
219              testbox>keyctl link 23 27
220              testbox>keyctl link 27 27
221              keyctl_link: Resource deadlock avoided
222
223       (*) Unlink a key from a keyring
224
225       keyctl unlink <key> <keyring>
226
227       This command removes a link to the key from the keyring. Error  "Not  a
228       directory"  will be returned if the destination is not a keyring. Error
229       "Permission denied" will be returned if the keyring doesn't have  write
230       permission.  Error  "No such file or directory" will be returned if the
231       key is not linked to by the keyring.
232
233       Note that this only removes one key link from the keyring; any  further
234       links to the same key are not deleted.
235
236              testbox>keyctl unlink 23 27
237
238       (*) Search a keyring
239
240       keyctl search <keyring> <type> <desc> [<dest_keyring>]
241
242       This command non-recursively searches a keyring for a key of a particu‐
243       lar type and description. If found, the ID of the key will  be  printed
244       on  stdout  and  the key will be attached to the destination keyring if
245       present. Error "Requested key not available" will be  returned  if  the
246       key is not found.
247
248              testbox>keyctl search @us user debug:hello
249              23
250              testbox>keyctl search @us user debug:bye
251              keyctl_search: Requested key not available
252
253       (*) Read a key
254
255       keyctl read <key>
256       keyctl pipe <key>
257       keyctl print <key>
258
259       These commands read the payload of a key. "read" prints it on stdout as
260       a hex dump, "pipe" dumps the raw data to stdout and "print" dumps it to
261       stdout  directly if it's entirely printable or as a hexdump preceded by
262       ":hex:" if not.
263
264       If the key type does not support reading of  the  payload,  then  error
265       "Operation not supported" will be returned.
266
267              testbox>keyctl read 26
268              1 bytes of data in key:
269              62
270              testbox>keyctl print 26
271              b
272              testbox>keyctl pipe 26
273              btestbox>
274
275       (*) List a keyring
276
277       keyctl list <keyring>
278       keyctl rlist <keyring>
279
280       These  commands  list the contents of a key as a keyring. "list" pretty
281       prints the contents and "rlist" just produces a space-separated list of
282       key IDs.
283
284       No attempt is made to check that the specified keyring is a keyring.
285
286              testbox>keyctl list @us
287              2 keys in keyring:
288                     22: vrwsl----------  4043    -1 keyring: _uid.4043
289                     23: vrwsl----------  4043  4043 user: debug:hello
290              testbox>keyctl rlist @us
291              22 23
292
293       (*) Describe a key
294
295       keyctl describe <keyring>
296       keyctl rdescribe <keyring> [sep]
297
298       These  commands  fetch  a  description  of a keyring. "describe" pretty
299       prints the description in the same fashion as the "list" command; "rde‐
300       scribe" prints the raw data returned from the kernel.
301
302              testbox>keyctl describe @us
303                     -5:  vrwsl----------   4043     -1 keyring: _uid_ses.4043
304              testbox>keyctl                   rdescribe                   @us
305              keyring;4043;-1;3f1f0000;_uid_ses.4043
306
307       The raw string is "<type>;<uid>;<gid>;<perms>;<description>", where uid
308       and gid are the decimal user and group IDs, perms  is  the  permissions
309       mask  in  hex,  type  and description are the type name and description
310       strings (neither of which will contain semicolons).
311
312       (*) Change the access controls on a key
313
314       keyctl chown <key> <uid>
315       keyctl chgrp <key> <gid>
316
317       These two commands change the UID and GID associated with evaluating  a
318       key's permissions mask. The UID also governs which quota a key is taken
319       out of.
320
321       The chown command is not currently supported; attempting it  will  earn
322       the error "Operation not supported" at best.
323
324       For  non-superuser  users, the GID may only be set to the process's GID
325       or a GID in the process's groups list. The superuser may set any GID it
326       likes.
327
328              testbox>sudo keyctl chown 27 0
329              keyctl_chown: Operation not supported
330              testbox>sudo keyctl chgrp 27 0
331
332       (*) Set the permissions mask on a key
333
334       keyctl setperm <key> <mask>
335
336       This command changes the permission control mask on a key. The mask may
337       be specified as a hex number if it begins "0x", an octal number  if  it
338       begins "0" or a decimal number otherwise.
339
340       The hex numbers are a combination of:
341
342              Possessor UID       GID       Other     Permission Granted
343              ========  ========  ========  ========  ==================
344              01000000  00010000  00000100  00000001  View
345              02000000  00020000  00000200  00000002  Read
346              04000000  00040000  00000400  00000004  Write
347              08000000  00080000  00000800  00000008  Search
348              10000000  00100000  00001000  00000010  Link
349              20000000  00200000  00002000  00000020  Set Attribute
350              3f000000  003f0000  00003f00  0000003f  All
351
352       View  permits the type, description and other parameters of a key to be
353       viewed.
354
355       Read permits the payload (or keyring list) to be read if  supported  by
356       the type.
357
358       Write permits the payload (or keyring list) to be modified or updated.
359
360       Search  on  a  key permits it to be found when a keyring to which it is
361       linked is searched.
362
363       Link permits a key to be linked to a keyring.
364
365       Set Attribute permits a key to have its owner, group  membership,  per‐
366       missions mask and timeout changed.
367
368              testbox>keyctl setperm 27 0x1f1f1f00
369
370       (*) Start a new session with fresh keyrings
371
372       keyctl session
373       keyctl session - [<prog> <arg1> <arg2> ...]
374       keyctl session <name> [<prog> <arg1> <arg2> ...]
375
376       These  commands  join  or  create a new keyring and then run a shell or
377       other program with that keyring as the session key.
378
379       The variation with no  arguments  just  creates  an  anonymous  session
380       keyring  and  attaches  that  as  the  session  keyring; it then exec's
381       $SHELL.
382
383       The variation with a dash in place of a name creates an anonymous  ses‐
384       sion  keyring  and attaches that as the session keyring; it then exec's
385       the supplied command, or $SHELL if one isn't supplied.
386
387       The variation with a name supplied creates or joins the  named  keyring
388       and  attaches  that as the session keyring; it then exec's the supplied
389       command, or $SHELL if one isn't supplied.
390
391              testbox>keyctl rdescribe @s
392              keyring;4043;-1;3f1f0000;_uid_ses.4043
393
394              testbox>keyctl session
395              Joined session keyring: 28
396              testbox>keyctl rdescribe @s
397              keyring;4043;4043;3f1f0000;_ses.24082
398
399              testbox>keyctl session -
400              Joined session keyring: 29
401              testbox>keyctl rdescribe @s
402              keyring;4043;4043;3f1f0000;_ses.24139
403
404              testbox>keyctl session - keyctl rdescribe @s
405              Joined session keyring: 30
406              keyring;4043;4043;3f1f0000;_ses.24185
407
408              testbox>keyctl session fish
409              Joined session keyring: 34
410              testbox>keyctl rdescribe @s
411              keyring;4043;4043;3f1f0000;fish
412
413              testbox>keyctl session fish keyctl rdesc @s
414              Joined session keyring: 35
415              keyring;4043;4043;3f1f0000;fish
416
417       (*) Instantiate a key
418
419       keyctl instantiate <key> <data> <keyring>
420       keyctl pinstantiate <key> <keyring>
421       keyctl negate <key> <timeout> <keyring>
422
423       These commands are used to attach data to a partially set  up  key  (as
424       created  by  the kernel and passed to /sbin/request-key). "instantiate"
425       marks a key as being valid  and  attaches  the  data  as  the  payload.
426       "negate"  marks a key as invalid and sets a timeout on it so that it'll
427       go away after a while.  This  prevents  a  lot  of  quickly  sequential
428       requests  from  slowing the system down overmuch when they all fail, as
429       all subsequent requests will then fail with error  "Requested  key  not
430       found" until the negative key has expired.
431
432       The newly instantiated key will be attached to the specified keyring.
433
434       These  commands may only be run from the program run by request-key - a
435       special authorisation key is set up by the kernel and attached  to  the
436       request-key's session keyring. This special key is revoked once the key
437       to which it refers has been instantiated one way or another.
438
439              testbox>keyctl instantiate $1 "Debug $3" $4
440              testbox>keyctl negate $1 30 $4
441
442       The pinstantiate variant of the  command  reads  the  data  from  stdin
443       rather than taking it from the command line:
444
445              testbox>echo -n "Debug $3" | keyctl pinstantiate $1 $4
446
447       (*) Set the expiry time on a key
448
449       keyctl timeout <key> <timeout>
450
451       This  command is used to set the timeout on a key, or clear an existing
452       timeout if the value specified is zero. The timeout is given as a  num‐
453       ber of seconds into the future.
454
455              testbox>keyctl timeout $1 45
456

ERRORS

458       There are a number of common errors returned by this program:
459
460       "Not a directory" - a key wasn't a keyring.
461
462       "Requested key not found" - the looked for key isn't available.
463
464       "Key has been revoked" - a revoked key was accessed.
465
466       "Key has expired" - an expired key was accessed.
467
468       "Permission  denied" - permission was denied by a UID/GID/mask combina‐
469       tion.
470
471

SEE ALSO

473       keyctl(1), request-key.conf(5)
474
475
476
477Linux                             17 Nov 2005                        KEYCTL(1)
Impressum