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 keyctl security <key>
41
43 This program is used to control the key management facility in various
44 ways using a variety of subcommands.
45
47 The key identifiers passed to or returned from keyctl are, in general,
48 positive integers. There are, however, some special values with special
49 meanings that can be passed as arguments:
50 (*) No key: 0
52 (*) Thread keyring: @t or -1
54 Each thread may have its own keyring. This is searched first, before
56 all others. The thread keyring is replaced by (v)fork, exec and clone.
57 (*) Process keyring: @p or -2
59 Each process (thread group) may have its own keyring. This is shared
61 between all members of a group and will be searched after the thread
62 keyring. The process keyring is replaced by (v)fork and exec.
63 (*) Session keyring: @s or -3
65 Each process subscribes to a session keyring that is inherited across
67 (v)fork, exec and clone. This is searched after the process keyring.
68 Session keyrings can be named and an extant keyring can be joined in
69 place of a process's current session keyring.
70 (*) User specific keyring: @u or -4
72 This keyring is shared between all the processes owned by a particular
74 user. It isn't searched directly, but is normally linked to from the
75 session keyring.
76 (*) User default session keyring: @us or -5
78 This is the default session keyring for a particular user. Login pro‐
80 cesses that change to a particular user will bind to this session until
81 another session is set.
82 (*) Group specific keyring: @g or -6
84 This is a place holder for a group specific keyring, but is not actu‐
86 ally implemented yet in the kernel.
87 (*) Assumed request_key authorisation key: @a or -7
89 This selects the authorisation key provided to the request_key() helper
91 to permit it to access the callers keyrings and instantiate the target
92 key.
93
95 Any non-ambiguous shortening of a command name may be used in lieu of
96 the full command name. This facility should not be used in scripting as
97 new commands may be added in future that then cause ambiguity.
98 (*) Show process keyrings
100 keyctl show
102 This command recursively shows what keyrings a process is subscribed to
104 and what keys and keyrings they contain.
105 (*) Add a key to a keyring
107 keyctl add <type> <desc> <data> <keyring>
109 keyctl padd <type> <desc> <keyring>
110 This command creates a key of the specified type and description;
112 instantiates it with the given data and attaches it to the specified
113 keyring. It then prints the new key's ID on stdout:
114 testbox>keyctl add user mykey stuff @u
116 26
117 The padd variant of the command reads the data from stdin rather than
119 taking it from the command line:
120 testbox>echo -n stuff | keyctl padd user mykey @u
122 26
123 (*) Request a key
125 keyctl request <type> <desc> [<dest_keyring>]
127 keyctl request2 <type> <desc> <info> [<dest_keyring>]
128 keyctl prequest2 <type> <desc> [<dest_keyring>]
129 These three commands request the lookup of a key of the given type and
131 description. The process's keyrings will be searched, and if a match is
132 found the matching key's ID will be printed to stdout; and if a desti‐
133 nation keyring is given, the key will be added to that keyring also.
134 If there is no key, the first command will simply return the error
136 ENOKEY and fail. The second and third commands will create a partial
137 key with the type and description, and call out to /sbin/request-key
138 with that key and the extra information supplied. This will then
139 attempt to instantiate the key in some manner, such that a valid key is
140 obtained.
141 The third command is like the second, except that the callout informa‐
143 tion is read from stdin rather than being passed on the command line.
144 If a valid key is obtained, the ID will be printed and the key attached
146 as if the original search had succeeded.
147 If there wasn't a valid key obtained, a temporary negative key will be
149 attached to the destination keyring if given and the error "Requested
150 key not available" will be given.
151 testbox>keyctl request2 user debug:hello wibble
153 23
154 testbox>echo -n wibble | keyctl prequest2 user debug:hello
155 23
156 testbox>keyctl request user debug:hello
157 23
158 (*) Update a key
160 keyctl update <key> <data>
162 keyctl pupdate <key>
163 This command replaces the data attached to a key with a new set of
165 data. If the type of the key doesn't support update then error "Opera‐
166 tion not supported" will be returned.
167 testbox>keyctl update 23 zebra
169 The pupdate variant of the command reads the data from stdin rather
171 than taking it from the command line:
172 testbox>echo -n zebra | keyctl pupdate 23
174 (*) Create a keyring
176 keyctl newring <name> <keyring>
178 This command creates a new keyring of the specified name and attaches
180 it to the specified keyring. The ID of the new keyring will be printed
181 to stdout if successful.
182 testbox>keyctl newring squelch @us
184 27
185 (*) Revoke a key
187 keyctl revoke <key>
189 This command marks a key as being revoked. Any further operations on
191 that key (apart from unlinking it) will return error "Key has been
192 revoked".
193 testbox>keyctl revoke 26
195 testbox>keyctl describe 26
196 keyctl_describe: Key has been revoked
197 (*) Clear a keyring
199 keyctl clear <keyring>
201 This command unlinks all the keys attached to the specified keyring.
203 Error "Not a directory" will be returned if the key specified is not a
204 keyring.
205 testbox>keyctl clear 27
207 (*) Link a key to a keyring
209 keyctl link <key> <keyring>
211 This command makes a link from the key to the keyring if there's enough
213 capacity to do so. Error "Not a directory" will be returned if the des‐
214 tination is not a keyring. Error "Permission denied" will be returned
215 if the key doesn't have link permission or the keyring doesn't have
216 write permission. Error "File table overflow" will be returned if the
217 keyring is full. Error "Resource deadlock avoided" will be returned if
218 an attempt was made to introduce a recursive link.
219 testbox>keyctl link 23 27
221 testbox>keyctl link 27 27
222 keyctl_link: Resource deadlock avoided
223 (*) Unlink a key from a keyring
225 keyctl unlink <key> <keyring>
227 This command removes a link to the key from the keyring. Error "Not a
229 directory" will be returned if the destination is not a keyring. Error
230 "Permission denied" will be returned if the keyring doesn't have write
231 permission. Error "No such file or directory" will be returned if the
232 key is not linked to by the keyring.
233 Note that this only removes one key link from the keyring; any further
235 links to the same key are not deleted.
236 testbox>keyctl unlink 23 27
238 (*) Search a keyring
240 keyctl search <keyring> <type> <desc> [<dest_keyring>]
242 This command non-recursively searches a keyring for a key of a particu‐
244 lar type and description. If found, the ID of the key will be printed
245 on stdout and the key will be attached to the destination keyring if
246 present. Error "Requested key not available" will be returned if the
247 key is not found.
248 testbox>keyctl search @us user debug:hello
250 23
251 testbox>keyctl search @us user debug:bye
252 keyctl_search: Requested key not available
253 (*) Read a key
255 keyctl read <key>
257 keyctl pipe <key>
258 keyctl print <key>
259 These commands read the payload of a key. "read" prints it on stdout as
261 a hex dump, "pipe" dumps the raw data to stdout and "print" dumps it to
262 stdout directly if it's entirely printable or as a hexdump preceded by
263 ":hex:" if not.
264 If the key type does not support reading of the payload, then error
266 "Operation not supported" will be returned.
267 testbox>keyctl read 26
269 1 bytes of data in key:
270 62
271 testbox>keyctl print 26
272 b
273 testbox>keyctl pipe 26
274 btestbox>
275 (*) List a keyring
277 keyctl list <keyring>
279 keyctl rlist <keyring>
280 These commands list the contents of a key as a keyring. "list" pretty
282 prints the contents and "rlist" just produces a space-separated list of
283 key IDs.
284 No attempt is made to check that the specified keyring is a keyring.
286 testbox>keyctl list @us
288 2 keys in keyring:
289 22: vrwsl---------- 4043 -1 keyring: _uid.4043
290 23: vrwsl---------- 4043 4043 user: debug:hello
291 testbox>keyctl rlist @us
292 22 23
293 (*) Describe a key
295 keyctl describe <keyring>
297 keyctl rdescribe <keyring> [sep]
298 These commands fetch a description of a keyring. "describe" pretty
300 prints the description in the same fashion as the "list" command; "rde‐
301 scribe" prints the raw data returned from the kernel.
302 testbox>keyctl describe @us
304 -5: vrwsl---------- 4043 -1 keyring: _uid_ses.4043
305 testbox>keyctl rdescribe @us
306 keyring;4043;-1;3f1f0000;_uid_ses.4043
307 The raw string is "<type>;<uid>;<gid>;<perms>;<description>", where uid
309 and gid are the decimal user and group IDs, perms is the permissions
310 mask in hex, type and description are the type name and description
311 strings (neither of which will contain semicolons).
312 (*) Change the access controls on a key
314 keyctl chown <key> <uid>
316 keyctl chgrp <key> <gid>
317 These two commands change the UID and GID associated with evaluating a
319 key's permissions mask. The UID also governs which quota a key is taken
320 out of.
321 The chown command is not currently supported; attempting it will earn
323 the error "Operation not supported" at best.
324 For non-superuser users, the GID may only be set to the process's GID
326 or a GID in the process's groups list. The superuser may set any GID it
327 likes.
328 testbox>sudo keyctl chown 27 0
330 keyctl_chown: Operation not supported
331 testbox>sudo keyctl chgrp 27 0
332 (*) Set the permissions mask on a key
334 keyctl setperm <key> <mask>
336 This command changes the permission control mask on a key. The mask may
338 be specified as a hex number if it begins "0x", an octal number if it
339 begins "0" or a decimal number otherwise.
340 The hex numbers are a combination of:
342 Possessor UID GID Other Permission Granted
344 ======== ======== ======== ======== ==================
345 01000000 00010000 00000100 00000001 View
346 02000000 00020000 00000200 00000002 Read
347 04000000 00040000 00000400 00000004 Write
348 08000000 00080000 00000800 00000008 Search
349 10000000 00100000 00001000 00000010 Link
350 20000000 00200000 00002000 00000020 Set Attribute
351 3f000000 003f0000 00003f00 0000003f All
352 View permits the type, description and other parameters of a key to be
354 viewed.
355 Read permits the payload (or keyring list) to be read if supported by
357 the type.
358 Write permits the payload (or keyring list) to be modified or updated.
360 Search on a key permits it to be found when a keyring to which it is
362 linked is searched.
363 Link permits a key to be linked to a keyring.
365 Set Attribute permits a key to have its owner, group membership, per‐
367 missions mask and timeout changed.
368 testbox>keyctl setperm 27 0x1f1f1f00
370 (*) Start a new session with fresh keyrings
372 keyctl session
374 keyctl session - [<prog> <arg1> <arg2> ...]
375 keyctl session <name> [<prog> <arg1> <arg2> ...]
376 These commands join or create a new keyring and then run a shell or
378 other program with that keyring as the session key.
379 The variation with no arguments just creates an anonymous session
381 keyring and attaches that as the session keyring; it then exec's
382 $SHELL.
383 The variation with a dash in place of a name creates an anonymous ses‐
385 sion keyring and attaches that as the session keyring; it then exec's
386 the supplied command, or $SHELL if one isn't supplied.
387 The variation with a name supplied creates or joins the named keyring
389 and attaches that as the session keyring; it then exec's the supplied
390 command, or $SHELL if one isn't supplied.
391 testbox>keyctl rdescribe @s
393 keyring;4043;-1;3f1f0000;_uid_ses.4043
394 testbox>keyctl session
396 Joined session keyring: 28
397 testbox>keyctl rdescribe @s
398 keyring;4043;4043;3f1f0000;_ses.24082
399 testbox>keyctl session -
401 Joined session keyring: 29
402 testbox>keyctl rdescribe @s
403 keyring;4043;4043;3f1f0000;_ses.24139
404 testbox>keyctl session - keyctl rdescribe @s
406 Joined session keyring: 30
407 keyring;4043;4043;3f1f0000;_ses.24185
408 testbox>keyctl session fish
410 Joined session keyring: 34
411 testbox>keyctl rdescribe @s
412 keyring;4043;4043;3f1f0000;fish
413 testbox>keyctl session fish keyctl rdesc @s
415 Joined session keyring: 35
416 keyring;4043;4043;3f1f0000;fish
417 (*) Instantiate a key
419 keyctl instantiate <key> <data> <keyring>
421 keyctl pinstantiate <key> <keyring>
422 keyctl negate <key> <timeout> <keyring>
423 These commands are used to attach data to a partially set up key (as
425 created by the kernel and passed to /sbin/request-key). "instantiate"
426 marks a key as being valid and attaches the data as the payload.
427 "negate" marks a key as invalid and sets a timeout on it so that it'll
428 go away after a while. This prevents a lot of quickly sequential
429 requests from slowing the system down overmuch when they all fail, as
430 all subsequent requests will then fail with error "Requested key not
431 found" until the negative key has expired.
432 The newly instantiated key will be attached to the specified keyring.
434 These commands may only be run from the program run by request-key - a
436 special authorisation key is set up by the kernel and attached to the
437 request-key's session keyring. This special key is revoked once the key
438 to which it refers has been instantiated one way or another.
439 testbox>keyctl instantiate $1 "Debug $3" $4
441 testbox>keyctl negate $1 30 $4
442 The pinstantiate variant of the command reads the data from stdin
444 rather than taking it from the command line:
445 testbox>echo -n "Debug $3" | keyctl pinstantiate $1 $4
447 (*) Set the expiry time on a key
449 keyctl timeout <key> <timeout>
451 This command is used to set the timeout on a key, or clear an existing
453 timeout if the value specified is zero. The timeout is given as a num‐
454 ber of seconds into the future.
455 testbox>keyctl timeout $1 45
457 (*) Retrieve a key's security context
459 keyctl security <key>
461 This command is used to retrieve a key's LSM security context. The
463 label is printed on stdout.
464 testbox>keyctl security @s
466 unconfined_u:unconfined_r:unconfined_t:s0-s0:c0.c1023
467 (*) Give the parent process a new session keyring
469 keyctl new_session
471 This command is used to give the invoking process (typically a shell) a
473 new session keyring, discarding its old session keyring.
474 testbox> keyctl session foo
476 Joined session keyring: 723488146
477 testbox> keyctl show
478 Session Keyring
479 -3 --alswrv 0 0 keyring: foo
480 testbox> keyctl new_session
481 490511412
482 testbox> keyctl show
483 Session Keyring
484 -3 --alswrv 0 0 keyring: _ses
485 Note that this affects the parent of the process that invokes the sys‐
487 tem call, and so may only affect processes with matching credentials.
488 Furthermore, the change does not take effect till the parent process
489 next transitions from kernel space to user space - typically when the
490 wait() system call returns.
491
493 There are a number of common errors returned by this program:
494 "Not a directory" - a key wasn't a keyring.
496 "Requested key not found" - the looked for key isn't available.
498 "Key has been revoked" - a revoked key was accessed.
500 "Key has expired" - an expired key was accessed.
502 "Permission denied" - permission was denied by a UID/GID/mask combina‐
504 tion.
505
508 keyctl(1), request-key.conf(5)
509Linux 17 Nov 2005 KEYCTL(1)