Debian Codegraph @

upstream/debian-unstable/man7/keyrings.7

raw
1 .\" Copyright 2014, Red Hat, Inc.
2 .\" Copyright 2016, Michael Kerrisk <[email protected]>
3 .\" Copyright, the authors of the Linux man-pages project
4 .\"
5 .\" SPDX-License-Identifier: GPL-2.0-or-later
6 .\"
7 .TH keyrings 7 2026-02-08 "Linux man-pages 6.18"
8 .SH NAME
9 keyrings \- in-kernel key management and retention facility
10 .SH DESCRIPTION
11 The Linux key-management facility
12 is primarily a way for various kernel components
13 to retain or cache
14 security data,
15 authentication keys,
16 encryption keys,
17 and other data in the kernel.
18 .P
19 System call interfaces are provided
20 so that user-space programs can manage those objects
21 and also use the facility for their own purposes;
22 see
23 .BR add_key (2),
24 .BR request_key (2),
25 and
26 .BR keyctl (2).
27 .P
28 A library and some user-space utilities are provided
29 to allow access to the facility.
30 See
31 .BR keyctl (1),
32 .BR keyctl (3),
33 and
34 .BR keyutils (7)
35 for more information.
36 .\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
37 .SS Keys
38 A key has the following attributes:
39 .TP
40 Serial number (ID)
41 This is a unique integer handle by which a key is referred to in system calls.
42 The serial number is sometimes synonymously referred as the key ID.
43 Programmatically,
44 key serial numbers are represented using the type
45 .IR key_serial_t .
46 .TP
47 Type
48 A key's type defines what sort of data can be held in the key,
49 how the proposed content of the key will be parsed,
50 and how the payload will be used.
51 .IP
52 There are a number of general-purpose types available,
53 plus some specialist types defined by specific kernel components.
54 .TP
55 Description (name)
56 The key description is a printable string
57 that is used as the search term for the key
58 (in conjunction with the key type)
59 as well as a display name.
60 During searches,
61 the description may be partially matched or exactly matched.
62 .TP
63 Payload (data)
64 The payload is the actual content of a key.
65 This is usually set when a key is created,
66 but it is possible for the kernel to upcall to user space to finish the
67 instantiation of a key if that key wasn't already known to the kernel
68 when it was requested.
69 For further details,
70 see
71 .BR request_key (2).
72 .IP
73 A key's payload can be read and updated
74 if the key type supports it
75 and if suitable permission is granted to the caller.
76 .TP
77 Access rights
78 Much as files do,
79 each key has
80 an owning user ID, an owning group ID, and a security label.
81 Each key also has a set of permissions,
82 though there are more than for a normal UNIX file,
83 and there is an additional category (possessor)
84 beyond the usual user, group, and other
85 (see
86 .IR Possession ,
87 below).
88 .IP
89 Note that keys are quota controlled,
90 since they require unswappable kernel memory.
91 The owning user ID specifies whose quota is to be debited.
92 .TP
93 Expiration time
94 Each key can have an expiration time set.
95 When that time is reached,
96 the key is marked as being expired and accesses to it fail with the error
97 .BR EKEYEXPIRED .
98 If not deleted, updated, or replaced, then, after a set amount of time,
99 an expired key is automatically removed (garbage collected)
100 along with all links to it,
101 and attempts to access the key fail with the error
102 .BR ENOKEY .
103 .TP
104 Reference count
105 Each key has a reference count.
106 Keys are referenced
107 by keyrings,
108 by currently active users,
109 and by a process's credentials.
110 When the reference count reaches zero,
111 the key is scheduled for garbage collection.
112 .\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
113 .SS Key types
114 The kernel provides several basic types of key:
115 .TP
116 .I \[dq]keyring\[dq]
117 .\" Note that keyrings use different fields in struct key in order to store
118 .\" their data - index_key instead of type/description and name_link/keys
119 .\" instead of payload.
120 Keyrings are special keys which store a set of links
121 to other keys (including other keyrings),
122 analogous to a directory holding links to files.
123 The main purpose of a keyring is
124 to prevent other keys from being garbage collected
125 because nothing refers to them.
126 .IP
127 Keyrings with descriptions (names)
128 that begin with a period (\[aq].\[aq]) are reserved to the implementation.
129 .TP
130 .I \[dq]user\[dq]
131 This is a general-purpose key type.
132 The key is kept entirely within kernel memory.
133 The payload may be read and updated by user-space applications.
134 .IP
135 The payload for keys of this type is a blob of arbitrary data
136 of up to 32,767 bytes.
137 .IP
138 The description may be any valid string,
139 though it is preferred that it start with a colon-delimited prefix
140 representing the service to which the key is of interest
141 (for instance
142 .IR \[dq]afs:mykey\[dq] ).
143 .TP
144 .IR \[dq]logon\[dq] " (since Linux 3.3)"
145 .\" commit 9f6ed2ca257fa8650b876377833e6f14e272848b
146 This key type is essentially the same as
147 .IR \[dq]user\[dq] ,
148 but it does not provide reading (i.e., the
149 .BR keyctl (2)
150 .B KEYCTL_READ
151 operation),
152 meaning that the key payload is never visible from user space.
153 This is suitable for storing username-password pairs
154 that should not be readable from user space.
155 .IP
156 The description of a
157 .I \[dq]logon\[dq]
158 key
159 .I must
160 start with a non-empty colon-delimited prefix whose purpose is
161 to identify the service to which the key belongs.
162 (Note that this differs from keys of the
163 .I \[dq]user\[dq]
164 type,
165 where the inclusion of a prefix is recommended but is not enforced.)
166 .TP
167 .IR \[dq]big_key\[dq] " (since Linux 3.13)"
168 .\" commit ab3c3587f8cda9083209a61dbe3a4407d3cada10
169 This key type is similar to the
170 .I \[dq]user\[dq]
171 key type, but it may hold a payload of up to 1\ MiB in size.
172 This key type is useful for purposes such as holding Kerberos ticket caches.
173 .IP
174 The payload data may be stored in a tmpfs filesystem,
175 rather than in kernel memory,
176 if the data size exceeds the overhead of storing the data in the filesystem.
177 (Storing the data in a filesystem requires filesystem structures
178 to be allocated in the kernel.
179 The size of these structures determines the size threshold
180 above which the tmpfs storage method is used.)
181 Since Linux 4.8,
182 .\" commit 13100a72f40f5748a04017e0ab3df4cf27c809ef
183 the payload data is encrypted when stored in tmpfs,
184 thereby preventing it from being written unencrypted into swap space.
185 .P
186 There are more specialized key types available also,
187 but they aren't discussed here
188 because they aren't intended for normal user-space use.
189 .P
190 Key type names
191 that begin with a period (\[aq].\[aq]) are reserved to the implementation.
192 .\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
193 .SS Keyrings
194 As previously mentioned, keyrings are a special type of key that contain
195 links to other keys (which may include other keyrings).
196 Keys may be linked to by multiple keyrings.
197 Keyrings may be considered as analogous to UNIX directories
198 where each directory contains a set of hard links to files.
199 .P
200 Various operations (system calls) may be applied only to keyrings:
201 .TP
202 Adding
203 A key may be added to a keyring by system calls that create keys.
204 This prevents the new key from being immediately deleted
205 when the system call releases its last reference to the key.
206 .TP
207 Linking
208 A link may be added to a keyring pointing to a key that is already known,
209 provided this does not create a self-referential cycle.
210 .TP
211 Unlinking
212 A link may be removed from a keyring.
213 When the last link to a key is removed,
214 that key will be scheduled for deletion by the garbage collector.
215 .TP
216 Clearing
217 All the links may be removed from a keyring.
218 .TP
219 Searching
220 A keyring may be considered the root of a tree or subtree in which keyrings
221 form the branches and non-keyrings the leaves.
222 This tree may be searched for a key matching
223 a particular type and description.
224 .P
225 See
226 .BR keyctl_clear (3),
227 .BR keyctl_link (3),
228 .BR keyctl_search (3),
229 and
230 .BR keyctl_unlink (3)
231 for more information.
232 .\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
233 .SS Anchoring keys
234 To prevent a key from being garbage collected,
235 it must be anchored to keep its reference count elevated
236 when it is not in active use by the kernel.
237 .P
238 Keyrings are used to anchor other keys:
239 each link is a reference on a key.
240 Note that keyrings themselves are just keys and
241 are also subject to the same anchoring requirement to prevent
242 them being garbage collected.
243 .P
244 The kernel makes available a number of anchor keyrings.
245 Note that some of these keyrings will be created only when first accessed.
246 .TP
247 Process keyrings
248 Process credentials themselves reference keyrings with specific semantics.
249 These keyrings are pinned as long as the set of credentials exists,
250 which is usually as long as the process exists.
251 .IP
252 There are three keyrings with different inheritance/sharing rules:
253 the
254 .BR session\-keyring (7)
255 (inherited and shared by all child processes),
256 the
257 .BR process\-keyring (7)
258 (shared by all threads in a process) and
259 the
260 .BR thread\-keyring (7)
261 (specific to a particular thread).
262 .IP
263 As an alternative to using the actual keyring IDs,
264 in calls to
265 .BR add_key (2),
266 .BR keyctl (2),
267 and
268 .BR request_key (2),
269 the special keyring values
270 .BR KEY_SPEC_SESSION_KEYRING ,
271 .BR KEY_SPEC_PROCESS_KEYRING ,
272 and
273 .B KEY_SPEC_THREAD_KEYRING
274 can be used to refer to the caller's own instances of these keyrings.
275 .TP
276 User keyrings
277 Each UID known to the kernel has a record that contains two keyrings: the
278 .BR user\-keyring (7)
279 and the
280 .BR user\-session\-keyring (7).
281 These exist for as long as the UID record in the kernel exists.
282 .IP
283 As an alternative to using the actual keyring IDs,
284 in calls to
285 .BR add_key (2),
286 .BR keyctl (2),
287 and
288 .BR request_key (2),
289 the special keyring values
290 .B KEY_SPEC_USER_KEYRING
291 and
292 .B KEY_SPEC_USER_SESSION_KEYRING
293 can be used to refer to the caller's own instances of these keyrings.
294 .IP
295 A link to the user keyring is placed in a new session keyring by
296 .BR pam_keyinit (8)
297 when a new login session is initiated.
298 .TP
299 Persistent keyrings
300 There is a
301 .BR persistent\-keyring (7)
302 available to each UID known to the system.
303 It may persist beyond the life of the UID record previously mentioned,
304 but has an expiration time set such that it is automatically cleaned up
305 after a set time.
306 The persistent keyring permits, for example,
307 .BR cron (8)
308 scripts to use credentials that are left in the persistent keyring after
309 the user logs out.
310 .IP
311 Note that the expiration time of the persistent keyring
312 is reset every time the persistent key is requested.
313 .TP
314 Special keyrings
315 There are special keyrings owned by the kernel that can anchor keys
316 for special purposes.
317 An example of this is the
318 .I system\~keyring
319 used for holding
320 encryption keys for module signature verification.
321 .IP
322 These special keyrings are usually closed to direct alteration
323 by user space.
324 .P
325 An originally planned "group keyring",
326 for storing keys associated with each GID known to the kernel,
327 is not so far implemented, is unlikely to be implemented.
328 Nevertheless, the constant
329 .B KEY_SPEC_GROUP_KEYRING
330 has been defined for this keyring.
331 .\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
332 .SS Possession
333 The concept of possession is important to understanding the keyrings
334 security model.
335 Whether a thread possesses a key is determined by the following rules:
336 .IP (1) 5
337 Any key or keyring that does not grant
338 .I search
339 permission to the caller is ignored in all the following rules.
340 .IP (2)
341 A thread possesses its
342 .BR session\-keyring (7),
343 .BR process\-keyring (7),
344 and
345 .BR thread\-keyring (7)
346 directly because those keyrings are referred to by its credentials.
347 .IP (3)
348 If a keyring is possessed, then any key it links to is also possessed.
349 .IP (4)
350 If any key a keyring links to is itself a keyring, then rule (3) applies
351 recursively.
352 .IP (5)
353 If a process is upcalled from the kernel to instantiate a key (see
354 .BR request_key (2)),
355 then it also possesses the requester's keyrings as in
356 rule (1) as if it were the requester.
357 .P
358 Note that possession is not a fundamental property of a key,
359 but must rather be calculated each time the key is needed.
360 .P
361 Possession is designed to allow set-user-ID programs run from, say
362 a user's shell to access the user's keys.
363 Granting permissions to the key possessor while denying them
364 to the key owner and group allows the prevention of access to keys
365 on the basis of UID and GID matches.
366 .P
367 When it creates the session keyring,
368 .BR pam_keyinit (8)
369 adds a link to the
370 .BR user\-keyring (7),
371 thus making the user keyring and anything it contains possessed by default.
372 .\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
373 .SS Access rights
374 Each key has the following security-related attributes:
375 .IP \[bu] 3
376 The owning user ID
377 .IP \[bu]
378 The ID of a group that is permitted to access the key
379 .IP \[bu]
380 A security label
381 .IP \[bu]
382 A permissions mask
383 .P
384 The permissions mask contains four sets of rights.
385 The first three sets are mutually exclusive.
386 One and only one will be in force for a particular access check.
387 In order of descending priority, these three sets are:
388 .TP
389 .I user
390 The set specifies the rights granted
391 if the key's user ID matches the caller's filesystem user ID.
392 .TP
393 .I group
394 The set specifies the rights granted
395 if the user ID didn't match and the key's group ID matches the caller's
396 filesystem GID or one of the caller's supplementary group IDs.
397 .TP
398 .I other
399 The set specifies the rights granted
400 if neither the key's user ID nor group ID matched.
401 .P
402 The fourth set of rights is:
403 .TP
404 .I possessor
405 The set specifies the rights granted
406 if a key is determined to be possessed by the caller.
407 .P
408 The complete set of rights for a key is the union of whichever
409 of the first three sets is applicable plus the fourth set
410 if the key is possessed.
411 .P
412 The set of rights that may be granted in each of the four masks
413 is as follows:
414 .TP
415 .I view
416 The attributes of the key may be read.
417 This includes the type,
418 description, and access rights (excluding the security label).
419 .TP
420 .I read
421 For a key: the payload of the key may be read.
422 For a keyring: the list of serial numbers (keys) to
423 which the keyring has links may be read.
424 .TP
425 .I write
426 The payload of the key may be updated and the key may be revoked.
427 For a keyring, links may be added to or removed from the keyring,
428 and the keyring may be cleared completely (all links are removed),
429 .TP
430 .I search
431 For a key (or a keyring): the key may be found by a search.
432 For a keyring: keys and keyrings that are linked to by the
433 keyring may be searched.
434 .TP
435 .I link
436 Links may be created from keyrings to the key.
437 The initial link to a key that is established when the key is created
438 doesn't require this permission.
439 .TP
440 .I setattr
441 The ownership details and security label of the key may be changed,
442 the key's expiration time may be set, and the key may be revoked.
443 .P
444 In addition to access rights, any active Linux Security Module (LSM) may
445 prevent access to a key if its policy so dictates.
446 A key may be given a
447 security label or other attribute by the LSM;
448 this label is retrievable via
449 .BR keyctl_get_security (3).
450 .P
451 See
452 .BR keyctl_chown (3),
453 .BR keyctl_describe (3),
454 .BR keyctl_get_security (3),
455 .BR keyctl_setperm (3),
456 and
457 .BR selinux (8)
458 for more information.
459 .\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
460 .SS Searching for keys
461 One of the key features of the Linux key-management facility
462 is the ability to find a key that a process is retaining.
463 The
464 .BR request_key (2)
465 system call is the primary point of
466 access for user-space applications to find a key.
467 (Internally, the kernel has something similar available
468 for use by internal components that make use of keys.)
469 .P
470 The search algorithm works as follows:
471 .IP (1) 5
472 The process keyrings are searched in the following order: the
473 .BR thread\-keyring (7)
474 if it exists, the
475 .BR process\-keyring (7)
476 if it exists, and then either the
477 .BR session\-keyring (7)
478 if it exists or the
479 .BR user\-session\-keyring (7)
480 if that exists.
481 .IP (2)
482 If the caller was a process that was invoked by the
483 .BR request_key (2)
484 upcall mechanism, then the keyrings of the original caller of
485 .BR request_key (2)
486 will be searched as well.
487 .IP (3)
488 The search of a keyring tree is in breadth-first order:
489 each keyring is searched first for a match,
490 then the keyrings referred to by that keyring are searched.
491 .IP (4)
492 If a matching key is found that is valid,
493 then the search terminates and that key is returned.
494 .IP (5)
495 If a matching key is found that has an error state attached,
496 that error state is noted and the search continues.
497 .IP (6)
498 If no valid matching key is found,
499 then the first noted error state is returned;
500 otherwise, an
501 .B ENOKEY
502 error is returned.
503 .P
504 It is also possible to search a specific keyring, in which case only steps
505 (3) to (6) apply.
506 .P
507 See
508 .BR request_key (2)
509 and
510 .BR keyctl_search (3)
511 for more information.
512 .\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
513 .SS On-demand key creation
514 If a key cannot be found,
515 .BR request_key (2)
516 will, if given a
517 .I callout_info
518 argument, create a new key and then upcall to user space to
519 instantiate the key.
520 This allows keys to be created on an as-needed basis.
521 .P
522 Typically,
523 this will involve the kernel creating a new process that executes the
524 .BR request\-key (8)
525 program, which will then execute the appropriate handler based on its
526 configuration.
527 .P
528 The handler is passed a special authorization key that allows it
529 and only it to instantiate the new key.
530 This is also used to permit searches performed by the
531 handler program to also search the requester's keyrings.
532 .P
533 See
534 .BR request_key (2),
535 .BR keyctl_assume_authority (3),
536 .BR keyctl_instantiate (3),
537 .BR keyctl_negate (3),
538 .BR keyctl_reject (3),
539 .BR request\-key (8),
540 and
541 .BR request\-key.conf (5)
542 for more information.
543 .\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
544 .SS Users
545 The Linux key-management facility has a number of users and usages,
546 but is not limited to those that already exist.
547 .P
548 In-kernel users of this facility include:
549 .TP
550 Network filesystems - DNS
551 The kernel uses the upcall mechanism provided by the keys to upcall to
552 user space to do DNS lookups and then to cache the results.
553 .TP
554 AF_RXRPC and kAFS - Authentication
555 The AF_RXRPC network protocol and the in-kernel AFS filesystem
556 use keys to store the ticket needed to do secured or encrypted traffic.
557 These are then looked up by
558 network operations on AF_RXRPC and filesystem operations on kAFS.
559 .TP
560 NFS - User ID mapping
561 The NFS filesystem uses keys to store mappings of
562 foreign user IDs to local user IDs.
563 .TP
564 CIFS - Password
565 The CIFS filesystem uses keys to store passwords for accessing remote shares.
566 .TP
567 Module verification
568 The kernel build process can be made to cryptographically sign modules.
569 That signature is then checked when a module is loaded.
570 .P
571 User-space users of this facility include:
572 .TP
573 Kerberos key storage
574 The MIT Kerberos 5 facility (libkrb5) can use keys to store authentication
575 tokens which can be made to be automatically cleaned up a set time after
576 the user last uses them,
577 but until then permits them to hang around after the user
578 has logged out so that
579 .BR cron (8)
580 scripts can use them.
581 .\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
582 .SH FILES
583 The kernel provides various
584 .I /proc
585 files that expose information about keys or define limits on key usage.
586 .TP
587 .IR /proc/keys " (since Linux 2.6.10)"
588 This file exposes a list of the keys for which the reading thread has
589 .I view
590 permission, providing various information about each key.
591 The thread need not possess the key for it to be visible in this file.
592 .\" David Howells, Dec 2016 linux-man@:
593 .\" This [The thread need not possess the key for it to be visible in
594 .\" this file.] is correct. See proc_keys_show() in security/keys/proc.c:
595 .\"
596 .\" rc = key_task_permission(key_ref, ctx.cred, KEY_NEED_VIEW);
597 .\" if (rc < 0)
598 .\" return 0;
599 .\"
600 .\"Possibly it shouldn't be, but for now it is.
601 .\"
602 .IP
603 The only keys included in the list are those that grant
604 .I view
605 permission to the reading process
606 (regardless of whether or not it possesses them).
607 LSM security checks are still performed,
608 and may filter out further keys that the process is not authorized to view.
609 .IP
610 An example of the data that one might see in this file
611 (with the columns numbered for easy reference below)
612 is the following:
613 .IP
614 .EX
615 (1) (2) (3)(4) (5) (6) (7) (8) (9)
616 009a2028 I\-\-Q\-\-\- 1 perm 3f010000 1000 1000 user krb_ccache:primary: 12
617 1806c4ba I\-\-Q\-\-\- 1 perm 3f010000 1000 1000 keyring _pid: 2
618 25d3a08f I\-\-Q\-\-\- 1 perm 1f3f0000 1000 65534 keyring _uid_ses.1000: 1
619 28576bd8 I\-\-Q\-\-\- 3 perm 3f010000 1000 1000 keyring _krb: 1
620 2c546d21 I\-\-Q\-\-\- 190 perm 3f030000 1000 1000 keyring _ses: 2
621 30a4e0be I\-\-\-\-\-\- 4 2d 1f030000 1000 65534 keyring _persistent.1000: 1
622 32100fab I\-\-Q\-\-\- 4 perm 1f3f0000 1000 65534 keyring _uid.1000: 2
623 32a387ea I\-\-Q\-\-\- 1 perm 3f010000 1000 1000 keyring _pid: 2
624 3ce56aea I\-\-Q\-\-\- 5 perm 3f030000 1000 1000 keyring _ses: 1
625 .EE
626 .IP
627 The fields shown in each line of this file are as follows:
628 .RS
629 .TP
630 ID (1)
631 The ID (serial number) of the key, expressed in hexadecimal.
632 .TP
633 Flags (2)
634 A set of flags describing the state of the key:
635 .RS
636 .TP
637 I
638 .\" KEY_FLAG_INSTANTIATED
639 The key has been instantiated.
640 .TP
641 R
642 .\" KEY_FLAG_REVOKED
643 The key has been revoked.
644 .TP
645 D
646 .\" KEY_FLAG_DEAD
647 The key is dead (i.e., the key type has been unregistered).
648 .\" unregister_key_type() in the kernel source
649 (A key may be briefly in this state during garbage collection.)
650 .TP
651 Q
652 .\" KEY_FLAG_IN_QUOTA
653 The key contributes to the user's quota.
654 .TP
655 U
656 .\" KEY_FLAG_USER_CONSTRUCT
657 The key is under construction via a callback to user space;
658 see
659 .BR request\-key (2).
660 .TP
661 N
662 .\" KEY_FLAG_NEGATIVE
663 The key is negatively instantiated.
664 .TP
665 i
666 .\" KEY_FLAG_INVALIDATED
667 The key has been invalidated.
668 .RE
669 .TP
670 Usage (3)
671 This is a count of the number of kernel credential
672 structures that are pinning the key
673 (approximately: the number of threads and open file references
674 that refer to this key).
675 .TP
676 Timeout (4)
677 The amount of time until the key will expire,
678 expressed in human-readable form (weeks, days, hours, minutes, and seconds).
679 The string
680 .I perm
681 here means that the key is permanent (no timeout).
682 The string
683 .I expd
684 means that the key has already expired,
685 but has not yet been garbage collected.
686 .TP
687 Permissions (5)
688 The key permissions, expressed as four hexadecimal bytes containing,
689 from left to right, the possessor, user, group, and other permissions.
690 Within each byte, the permission bits are as follows:
691 .IP
692 .PD 0
693 .RS 12
694 .TP
695 0x01
696 .I view
697 .TP
698 0x02
699 .I read
700 .TP
701 0x04
702 .I write
703 .TP
704 0x08
705 .I search
706 .TP
707 0x10
708 .I link
709 .TP
710 0x20
711 .I setattr
712 .RE
713 .PD
714 .TP
715 UID (6)
716 The user ID of the key owner.
717 .TP
718 GID (7)
719 The group ID of the key.
720 The value \-1 here means that the key has no group ID;
721 this can occur in certain circumstances for keys created by the kernel.
722 .TP
723 Type (8)
724 The key type (user, keyring, etc.)
725 .TP
726 Description (9)
727 The key description (name).
728 This field contains descriptive information about the key.
729 For most key types, it has the form
730 .IP
731 .in +4n
732 .EX
733 name[: extra\-info]
734 .EE
735 .in
736 .IP
737 The
738 .I name
739 subfield is the key's description (name).
740 The optional
741 .I extra\-info
742 field provides some further information about the key.
743 The information that appears here depends on the key type, as follows:
744 .RS
745 .TP
746 .I \[dq]user\[dq]
747 .TQ
748 .I \[dq]logon\[dq]
749 The size in bytes of the key payload (expressed in decimal).
750 .TP
751 .I \[dq]keyring\[dq]
752 The number of keys linked to the keyring,
753 or the string
754 .I empty
755 if there are no keys linked to the keyring.
756 .TP
757 .I \[dq]big_key\[dq]
758 The payload size in bytes,
759 followed either by the string
760 .IR [file] ,
761 if the key payload exceeds the threshold
762 that means that the payload is stored in a (swappable)
763 .BR tmpfs (5)
764 filesystem,
765 or otherwise the string
766 .IR [buff] ,
767 indicating that the key is small enough to reside in kernel memory.
768 .RE
769 .IP
770 For the
771 .I \[dq].request_key_auth\[dq]
772 key type
773 (authorization key;
774 see
775 .BR request_key (2)),
776 the description field has the form shown in the following example:
777 .IP
778 .in +4n
779 .EX
780 key:c9a9b19 pid:28880 ci:10
781 .EE
782 .in
783 .IP
784 The three subfields are as follows:
785 .RS
786 .TP
787 .I key
788 The hexadecimal ID of the key being instantiated in the requesting program.
789 .TP
790 .I pid
791 The PID of the requesting program.
792 .TP
793 .I ci
794 The length of the callout data with which the requested key should
795 be instantiated
796 (i.e., the length of the payload associated with the authorization key).
797 .RE
798 .RE
799 .TP
800 .IR /proc/key\-users " (since Linux 2.6.10)"
801 This file lists various information for each user ID that
802 has at least one key on the system.
803 An example of the data that one might see in this file is the following:
804 .IP
805 .in +4n
806 .EX
807 0: 10 9/9 2/1000000 22/25000000
808 42: 9 9/9 8/200 106/20000
809 1000: 11 11/11 10/200 271/20000
810 .EE
811 .in
812 .IP
813 The fields shown in each line are as follows:
814 .RS
815 .TP
816 .I uid
817 The user ID.
818 .TP
819 .I usage
820 This is a kernel-internal usage count for the kernel structure
821 used to record key users.
822 .TP
823 .IR nkeys / nikeys
824 The total number of keys owned by the user,
825 and the number of those keys that have been instantiated.
826 .TP
827 .IR qnkeys / maxkeys
828 The number of keys owned by the user,
829 and the maximum number of keys that the user may own.
830 .TP
831 .IR qnbytes / maxbytes
832 The number of bytes consumed in payloads of the keys owned by this user,
833 and the upper limit on the number of bytes in key payloads for that user.
834 .RE
835 .TP
836 .IR /proc/sys/kernel/keys/gc_delay " (since Linux 2.6.32)"
837 .\" commit 5d135440faf7db8d566de0c6fab36b16cf9cfc3b
838 The value in this file specifies the interval, in seconds,
839 after which revoked and expired keys will be garbage collected.
840 The purpose of having such an interval is so that there is a window
841 of time where user space can see an error (respectively
842 .B EKEYREVOKED
843 and
844 .BR EKEYEXPIRED )
845 that indicates what happened to the key.
846 .IP
847 The default value in this file is 300 (i.e., 5 minutes).
848 .TP
849 .IR /proc/sys/kernel/keys/persistent_keyring_expiry " (since Linux 3.13)"
850 .\" commit f36f8c75ae2e7d4da34f4c908cebdb4aa42c977e
851 This file defines an interval, in seconds,
852 to which the persistent keyring's expiration timer is reset
853 each time the keyring is accessed (via
854 .BR keyctl_get_persistent (3)
855 or the
856 .BR keyctl (2)
857 .B KEYCTL_GET_PERSISTENT
858 operation.)
859 .IP
860 The default value in this file is 259200 (i.e., 3 days).
861 .P
862 The following files (which are writable by privileged processes)
863 are used to enforce quotas on the number of keys
864 and number of bytes of data that can be stored in key payloads:
865 .TP
866 .IR /proc/sys/kernel/keys/maxbytes " (since Linux 2.6.26)"
867 .\" commit 0b77f5bfb45c13e1e5142374f9d6ca75292252a4
868 .\" Previously: KEYQUOTA_MAX_BYTES 10000
869 This is the maximum number of bytes of data that a nonroot user
870 can hold in the payloads of the keys owned by the user.
871 .IP
872 The default value in this file is 20,000.
873 .TP
874 .IR /proc/sys/kernel/keys/maxkeys " (since Linux 2.6.26)"
875 .\" commit 0b77f5bfb45c13e1e5142374f9d6ca75292252a4
876 .\" Previously: KEYQUOTA_MAX_KEYS 100
877 This is the maximum number of keys that a nonroot user may own.
878 .IP
879 The default value in this file is 200.
880 .TP
881 .IR /proc/sys/kernel/keys/root_maxbytes " (since Linux 2.6.26)"
882 This is the maximum number of bytes of data that the root user
883 (UID 0 in the root user namespace)
884 can hold in the payloads of the keys owned by root.
885 .IP
886 .\"738c5d190f6540539a04baf36ce21d46b5da04bd
887 The default value in this file is 25,000,000 (20,000 before Linux 3.17).
888 .\" commit 0b77f5bfb45c13e1e5142374f9d6ca75292252a4
889 .TP
890 .IR /proc/sys/kernel/keys/root_maxkeys " (since Linux 2.6.26)"
891 .\" commit 0b77f5bfb45c13e1e5142374f9d6ca75292252a4
892 This is the maximum number of keys that the root user
893 (UID 0 in the root user namespace)
894 may own.
895 .IP
896 .\"738c5d190f6540539a04baf36ce21d46b5da04bd
897 The default value in this file is 1,000,000 (200 before Linux 3.17).
898 .P
899 With respect to keyrings,
900 note that each link in a keyring consumes 4 bytes of the keyring payload.
901 .\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
902 .SH SEE ALSO
903 .ad l
904 .nh
905 .BR keyctl (1),
906 .BR add_key (2),
907 .BR keyctl (2),
908 .BR request_key (2),
909 .BR keyctl (3),
910 .BR keyutils (7),
911 .BR persistent\-keyring (7),
912 .BR process\-keyring (7),
913 .BR session\-keyring (7),
914 .BR thread\-keyring (7),
915 .BR user\-keyring (7),
916 .BR user\-session\-keyring (7),
917 .BR pam_keyinit (8),
918 .BR request\-key (8)
919 .TP
920 .I linux.git/Documentation/crypto/asymmetric\-keys.rst
921 .TQ
922 .I linux.git/\:Documentation/\:security/\:keys/