1KEYCTL(1) Linux Key Management Utilities KEYCTL(1)
2
6 keyctl - Key management facility control
7
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
42 This program is used to control the key management facility in various
43 ways using a variety of subcommands.
44
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 (*) No key: 0
51 (*) Thread keyring: @t or -1
53 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 (*) Process keyring: @p or -2
58 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 (*) Session keyring: @s or -3
64 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 (*) User specific keyring: @u or -4
71 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 (*) User default session keyring: @us or -5
77 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 (*) Group specific keyring: @g or -6
83 This is a place holder for a group specific keyring, but is not actu‐
85 ally implemented yet in the kernel.
86 (*) Assumed request_key authorisation key: @a or -7
88 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
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 (*) Show process keyrings
99 keyctl show
101 This command recursively shows what keyrings a process is subscribed to
103 and what keys and keyrings they contain.
104 (*) Add a key to a keyring
106 keyctl add <type> <desc> <data> <keyring>
108 keyctl padd <type> <desc> <keyring>
109 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 testbox>keyctl add user mykey stuff @u
115 26
116 The padd variant of the command reads the data from stdin rather than
118 taking it from the command line:
119 testbox>echo -n stuff | keyctl padd user mykey @u
121 26
122 (*) Request a key
124 keyctl request <type> <desc> [<dest_keyring>]
126 keyctl request2 <type> <desc> <info> [<dest_keyring>]
127 keyctl prequest2 <type> <desc> [<dest_keyring>]
128 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 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 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 If a valid key is obtained, the ID will be printed and the key attached
145 as if the original search had succeeded.
146 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 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 (*) Update a key
159 keyctl update <key> <data>
161 keyctl pupdate <key>
162 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 testbox>keyctl update 23 zebra
168 The pupdate variant of the command reads the data from stdin rather
170 than taking it from the command line:
171 testbox>echo -n zebra | keyctl pupdate 23
173 (*) Create a keyring
175 keyctl newring <name> <keyring>
177 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 testbox>keyctl newring squelch @us
183 27
184 (*) Revoke a key
186 keyctl revoke <key>
188 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 testbox>keyctl revoke 26
194 testbox>keyctl describe 26
195 keyctl_describe: Key has been revoked
196 (*) Clear a keyring
198 keyctl clear <keyring>
200 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 testbox>keyctl clear 27
206 (*) Link a key to a keyring
208 keyctl link <key> <keyring>
210 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 testbox>keyctl link 23 27
220 testbox>keyctl link 27 27
221 keyctl_link: Resource deadlock avoided
222 (*) Unlink a key from a keyring
224 keyctl unlink <key> <keyring>
226 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 Note that this only removes one key link from the keyring; any further
234 links to the same key are not deleted.
235 testbox>keyctl unlink 23 27
237 (*) Search a keyring
239 keyctl search <keyring> <type> <desc> [<dest_keyring>]
241 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 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 (*) Read a key
254 keyctl read <key>
256 keyctl pipe <key>
257 keyctl print <key>
258 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 If the key type does not support reading of the payload, then error
265 "Operation not supported" will be returned.
266 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 (*) List a keyring
276 keyctl list <keyring>
278 keyctl rlist <keyring>
279 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 No attempt is made to check that the specified keyring is a keyring.
285 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 (*) Describe a key
294 keyctl describe <keyring>
296 keyctl rdescribe <keyring> [sep]
297 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 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 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 (*) Change the access controls on a key
313 keyctl chown <key> <uid>
315 keyctl chgrp <key> <gid>
316 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 The chown command is not currently supported; attempting it will earn
322 the error "Operation not supported" at best.
323 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 testbox>sudo keyctl chown 27 0
329 keyctl_chown: Operation not supported
330 testbox>sudo keyctl chgrp 27 0
331 (*) Set the permissions mask on a key
333 keyctl setperm <key> <mask>
335 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 The hex numbers are a combination of:
341 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 View permits the type, description and other parameters of a key to be
353 viewed.
354 Read permits the payload (or keyring list) to be read if supported by
356 the type.
357 Write permits the payload (or keyring list) to be modified or updated.
359 Search on a key permits it to be found when a keyring to which it is
361 linked is searched.
362 Link permits a key to be linked to a keyring.
364 Set Attribute permits a key to have its owner, group membership, per‐
366 missions mask and timeout changed.
367 testbox>keyctl setperm 27 0x1f1f1f00
369 (*) Start a new session with fresh keyrings
371 keyctl session
373 keyctl session - [<prog> <arg1> <arg2> ...]
374 keyctl session <name> [<prog> <arg1> <arg2> ...]
375 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 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 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 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 testbox>keyctl rdescribe @s
392 keyring;4043;-1;3f1f0000;_uid_ses.4043
393 testbox>keyctl session
395 Joined session keyring: 28
396 testbox>keyctl rdescribe @s
397 keyring;4043;4043;3f1f0000;_ses.24082
398 testbox>keyctl session -
400 Joined session keyring: 29
401 testbox>keyctl rdescribe @s
402 keyring;4043;4043;3f1f0000;_ses.24139
403 testbox>keyctl session - keyctl rdescribe @s
405 Joined session keyring: 30
406 keyring;4043;4043;3f1f0000;_ses.24185
407 testbox>keyctl session fish
409 Joined session keyring: 34
410 testbox>keyctl rdescribe @s
411 keyring;4043;4043;3f1f0000;fish
412 testbox>keyctl session fish keyctl rdesc @s
414 Joined session keyring: 35
415 keyring;4043;4043;3f1f0000;fish
416 (*) Instantiate a key
418 keyctl instantiate <key> <data> <keyring>
420 keyctl pinstantiate <key> <keyring>
421 keyctl negate <key> <timeout> <keyring>
422 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 The newly instantiated key will be attached to the specified keyring.
433 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 testbox>keyctl instantiate $1 "Debug $3" $4
440 testbox>keyctl negate $1 30 $4
441 The pinstantiate variant of the command reads the data from stdin
443 rather than taking it from the command line:
444 testbox>echo -n "Debug $3" | keyctl pinstantiate $1 $4
446 (*) Set the expiry time on a key
448 keyctl timeout <key> <timeout>
450 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 testbox>keyctl timeout $1 45
456
458 There are a number of common errors returned by this program:
459 "Not a directory" - a key wasn't a keyring.
461 "Requested key not found" - the looked for key isn't available.
463 "Key has been revoked" - a revoked key was accessed.
465 "Key has expired" - an expired key was accessed.
467 "Permission denied" - permission was denied by a UID/GID/mask combina‐
469 tion.
470
473 keyctl(1), request-key.conf(5)
474Linux 17 Nov 2005 KEYCTL(1)