Merging upstream version 6.8.

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

1 files changed, 901 insertions, 0 deletions

diff --git a/man/man7/keyrings.7 b/man/man7/keyrings.7
new file mode 100644
index 0000000..492bfca
--- /dev/null
+++ b/man/man7/keyrings.7
@@ -0,0 +1,901 @@
+.\" Copyright (C) 2014 Red Hat, Inc. All Rights Reserved.
+.\" Written by David Howells (dhowells@redhat.com)
+.\" and Copyright (C) 2016 Michael Kerrisk <mtk.manpages@gmail.com>
+.\"
+.\" SPDX-License-Identifier: GPL-2.0-or-later
+.\"
+.TH keyrings 7 2024-05-02 "Linux man-pages (unreleased)"
+.SH NAME
+keyrings \- in-kernel key management and retention facility
+.SH DESCRIPTION
+The Linux key-management facility
+is primarily a way for various kernel components
+to retain or cache security data,
+authentication keys, encryption keys, and other data in the kernel.
+.P
+System call interfaces are provided so that user-space programs can manage
+those objects and also use the facility for their own purposes; see
+.BR add_key (2),
+.BR request_key (2),
+and
+.BR keyctl (2).
+.P
+A library and some user-space utilities are provided to allow access to the
+facility.
+See
+.BR keyctl (1),
+.BR keyctl (3),
+and
+.BR keyutils (7)
+for more information.
+.\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
+.SS Keys
+A key has the following attributes:
+.TP
+Serial number (ID)
+This is a unique integer handle by which a key is referred to in system calls.
+The serial number is sometimes synonymously referred as the key ID.
+Programmatically, key serial numbers are represented using the type
+.IR key_serial_t .
+.TP
+Type
+A key's type defines what sort of data can be held in the key,
+how the proposed content of the key will be parsed,
+and how the payload will be used.
+.IP
+There are a number of general-purpose types available, plus some specialist
+types defined by specific kernel components.
+.TP
+Description (name)
+The key description is a printable string that is used as the search term
+for the key (in conjunction with the key type) as well as a display name.
+During searches, the description may be partially matched or exactly matched.
+.TP
+Payload (data)
+The payload is the actual content of a key.
+This is usually set when a key is created,
+but it is possible for the kernel to upcall to user space to finish the
+instantiation of a key if that key wasn't already known to the kernel
+when it was requested.
+For further details, see
+.BR request_key (2).
+.IP
+A key's payload can be read and updated if the key type supports it and if
+suitable permission is granted to the caller.
+.TP
+Access rights
+Much as files do,
+each key has an owning user ID, an owning group ID, and a security label.
+Each key also has a set of permissions,
+though there are more than for a normal UNIX file,
+and there is an additional category\[em]possessor\[em]beyond the usual user,
+group, and other (see
+.IR Possession ,
+below).
+.IP
+Note that keys are quota controlled, since they require unswappable kernel
+memory.
+The owning user ID specifies whose quota is to be debited.
+.TP
+Expiration time
+Each key can have an expiration time set.
+When that time is reached,
+the key is marked as being expired and accesses to it fail with the error
+.BR EKEYEXPIRED .
+If not deleted, updated, or replaced, then, after a set amount of time,
+an expired key is automatically removed (garbage collected)
+along with all links to it,
+and attempts to access the key fail with the error
+.BR ENOKEY .
+.TP
+Reference count
+Each key has a reference count.
+Keys are referenced by keyrings, by currently active users,
+and by a process's credentials.
+When the reference count reaches zero,
+the key is scheduled for garbage collection.
+.\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
+.SS Key types
+The kernel provides several basic types of key:
+.TP
+.I \[dq]keyring\[dq]
+.\" Note that keyrings use different fields in struct key in order to store
+.\" their data - index_key instead of type/description and name_link/keys
+.\" instead of payload.
+Keyrings are special keys which store a set of links
+to other keys (including other keyrings),
+analogous to a directory holding links to files.
+The main purpose of a keyring is to prevent other keys from
+being garbage collected because nothing refers to them.
+.IP
+Keyrings with descriptions (names)
+that begin with a period (\[aq].\[aq]) are reserved to the implementation.
+.TP
+.I \[dq]user\[dq]
+This is a general-purpose key type.
+The key is kept entirely within kernel memory.
+The payload may be read and updated by user-space applications.
+.IP
+The payload for keys of this type is a blob of arbitrary data
+of up to 32,767 bytes.
+.IP
+The description may be any valid string, though it is preferred that it
+start with a colon-delimited prefix representing the service
+to which the key is of interest
+(for instance
+.IR \[dq]afs:mykey\[dq] ).
+.TP
+.IR \[dq]logon\[dq] " (since Linux 3.3)"
+.\" commit 9f6ed2ca257fa8650b876377833e6f14e272848b
+This key type is essentially the same as
+.IR \[dq]user\[dq] ,
+but it does not provide reading (i.e., the
+.BR keyctl (2)
+.B KEYCTL_READ
+operation),
+meaning that the key payload is never visible from user space.
+This is suitable for storing username-password pairs
+that should not be readable from user space.
+.IP
+The description of a
+.I \[dq]logon\[dq]
+key
+.I must
+start with a non-empty colon-delimited prefix whose purpose
+is to identify the service to which the key belongs.
+(Note that this differs from keys of the
+.I \[dq]user\[dq]
+type, where the inclusion of a prefix is recommended but is not enforced.)
+.TP
+.IR \[dq]big_key\[dq] " (since Linux 3.13)"
+.\" commit ab3c3587f8cda9083209a61dbe3a4407d3cada10
+This key type is similar to the
+.I \[dq]user\[dq]
+key type, but it may hold a payload of up to 1\ MiB in size.
+This key type is useful for purposes such as holding Kerberos ticket caches.
+.IP
+The payload data may be stored in a tmpfs filesystem,
+rather than in kernel memory,
+if the data size exceeds the overhead of storing the data in the filesystem.
+(Storing the data in a filesystem requires filesystem structures
+to be allocated in the kernel.
+The size of these structures determines the size threshold
+above which the tmpfs storage method is used.)
+Since Linux 4.8,
+.\" commit 13100a72f40f5748a04017e0ab3df4cf27c809ef
+the payload data is encrypted when stored in tmpfs,
+thereby preventing it from being written unencrypted into swap space.
+.P
+There are more specialized key types available also,
+but they aren't discussed here
+because they aren't intended for normal user-space use.
+.P
+Key type names
+that begin with a period (\[aq].\[aq]) are reserved to the implementation.
+.\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
+.SS Keyrings
+As previously mentioned, keyrings are a special type of key that contain
+links to other keys (which may include other keyrings).
+Keys may be linked to by multiple keyrings.
+Keyrings may be considered as analogous to UNIX directories
+where each directory contains a set of hard links to files.
+.P
+Various operations (system calls) may be applied only to keyrings:
+.TP
+Adding
+A key may be added to a keyring by system calls that create keys.
+This prevents the new key from being immediately deleted
+when the system call releases its last reference to the key.
+.TP
+Linking
+A link may be added to a keyring pointing to a key that is already known,
+provided this does not create a self-referential cycle.
+.TP
+Unlinking
+A link may be removed from a keyring.
+When the last link to a key is removed,
+that key will be scheduled for deletion by the garbage collector.
+.TP
+Clearing
+All the links may be removed from a keyring.
+.TP
+Searching
+A keyring may be considered the root of a tree or subtree in which keyrings
+form the branches and non-keyrings the leaves.
+This tree may be searched for a key matching
+a particular type and description.
+.P
+See
+.BR keyctl_clear (3),
+.BR keyctl_link (3),
+.BR keyctl_search (3),
+and
+.BR keyctl_unlink (3)
+for more information.
+.\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
+.SS Anchoring keys
+To prevent a key from being garbage collected,
+it must be anchored to keep its reference count elevated
+when it is not in active use by the kernel.
+.P
+Keyrings are used to anchor other keys:
+each link is a reference on a key.
+Note that keyrings themselves are just keys and
+are also subject to the same anchoring requirement to prevent
+them being garbage collected.
+.P
+The kernel makes available a number of anchor keyrings.
+Note that some of these keyrings will be created only when first accessed.
+.TP
+Process keyrings
+Process credentials themselves reference keyrings with specific semantics.
+These keyrings are pinned as long as the set of credentials exists,
+which is usually as long as the process exists.
+.IP
+There are three keyrings with different inheritance/sharing rules:
+the
+.BR session\-keyring (7)
+(inherited and shared by all child processes),
+the
+.BR process\-keyring (7)
+(shared by all threads in a process) and
+the
+.BR thread\-keyring (7)
+(specific to a particular thread).
+.IP
+As an alternative to using the actual keyring IDs,
+in calls to
+.BR add_key (2),
+.BR keyctl (2),
+and
+.BR request_key (2),
+the special keyring values
+.BR KEY_SPEC_SESSION_KEYRING ,
+.BR KEY_SPEC_PROCESS_KEYRING ,
+and
+.B KEY_SPEC_THREAD_KEYRING
+can be used to refer to the caller's own instances of these keyrings.
+.TP
+User keyrings
+Each UID known to the kernel has a record that contains two keyrings: the
+.BR user\-keyring (7)
+and the
+.BR user\-session\-keyring (7).
+These exist for as long as the UID record in the kernel exists.
+.IP
+As an alternative to using the actual keyring IDs,
+in calls to
+.BR add_key (2),
+.BR keyctl (2),
+and
+.BR request_key (2),
+the special keyring values
+.B KEY_SPEC_USER_KEYRING
+and
+.B KEY_SPEC_USER_SESSION_KEYRING
+can be used to refer to the caller's own instances of these keyrings.
+.IP
+A link to the user keyring is placed in a new session keyring by
+.BR pam_keyinit (8)
+when a new login session is initiated.
+.TP
+Persistent keyrings
+There is a
+.BR persistent\-keyring (7)
+available to each UID known to the system.
+It may persist beyond the life of the UID record previously mentioned,
+but has an expiration time set such that it is automatically cleaned up
+after a set time.
+The persistent keyring permits, for example,
+.BR cron (8)
+scripts to use credentials that are left in the persistent keyring after
+the user logs out.
+.IP
+Note that the expiration time of the persistent keyring
+is reset every time the persistent key is requested.
+.TP
+Special keyrings
+There are special keyrings owned by the kernel that can anchor keys
+for special purposes.
+An example of this is the \fIsystem keyring\fR used for holding
+encryption keys for module signature verification.
+.IP
+These special keyrings  are usually closed to direct alteration
+by user space.
+.P
+An originally planned "group keyring",
+for storing keys associated with each GID known to the kernel,
+is not so far implemented, is unlikely to be implemented.
+Nevertheless, the constant
+.B KEY_SPEC_GROUP_KEYRING
+has been defined for this keyring.
+.\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
+.SS Possession
+The concept of possession is important to understanding the keyrings
+security model.
+Whether a thread possesses a key is determined by the following rules:
+.IP (1) 5
+Any key or keyring that does not grant
+.I search
+permission to the caller is ignored in all the following rules.
+.IP (2)
+A thread possesses its
+.BR session\-keyring (7),
+.BR process\-keyring (7),
+and
+.BR thread\-keyring (7)
+directly because those keyrings are referred to by its credentials.
+.IP (3)
+If a keyring is possessed, then any key it links to is also possessed.
+.IP (4)
+If any key a keyring links to is itself a keyring, then rule (3) applies
+recursively.
+.IP (5)
+If a process is upcalled from the kernel to instantiate a key (see
+.BR request_key (2)),
+then it also possesses the requester's keyrings as in
+rule (1) as if it were the requester.
+.P
+Note that possession is not a fundamental property of a key,
+but must rather be calculated each time the key is needed.
+.P
+Possession is designed to allow set-user-ID programs run from, say
+a user's shell to access the user's keys.
+Granting permissions to the key possessor while denying them
+to the key owner and group allows the prevention of access to keys
+on the basis of UID and GID matches.
+.P
+When it creates the session keyring,
+.BR pam_keyinit (8)
+adds a link to the
+.BR user\-keyring (7),
+thus making the user keyring and anything it contains possessed by default.
+.\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
+.SS Access rights
+Each key has the following security-related attributes:
+.IP \[bu] 3
+The owning user ID
+.IP \[bu]
+The ID of a group that is permitted to access the key
+.IP \[bu]
+A security label
+.IP \[bu]
+A permissions mask
+.P
+The permissions mask contains four sets of rights.
+The first three sets are mutually exclusive.
+One and only one will be in force for a particular access check.
+In order of descending priority, these three sets are:
+.TP
+.I user
+The set specifies the rights granted
+if the key's user ID matches the caller's filesystem user ID.
+.TP
+.I group
+The set specifies the rights granted
+if the user ID didn't match and the key's group ID matches the caller's
+filesystem GID or one of the caller's supplementary group IDs.
+.TP
+.I other
+The set specifies the rights granted
+if neither the key's user ID nor group ID matched.
+.P
+The fourth set of rights is:
+.TP
+.I possessor
+The set specifies the rights granted
+if a key is determined to be possessed by the caller.
+.P
+The complete set of rights for a key is the union of whichever
+of the first three sets is applicable plus the fourth set
+if the key is possessed.
+.P
+The set of rights that may be granted in each of the four masks
+is as follows:
+.TP
+.I view
+The attributes of the key may be read.
+This includes the type,
+description, and access rights (excluding the security label).
+.TP
+.I read
+For a key: the payload of the key may be read.
+For a keyring: the list of serial numbers (keys) to
+which the keyring has links may be read.
+.TP
+.I write
+The payload of the key may be updated and the key may be revoked.
+For a keyring, links may be added to or removed from the keyring,
+and the keyring may be cleared completely (all links are removed),
+.TP
+.I search
+For a key (or a keyring): the key may be found by a search.
+For a keyring: keys and keyrings that are linked to by the
+keyring may be searched.
+.TP
+.I link
+Links may be created from keyrings to the key.
+The initial link to a key that is established when the key is created
+doesn't require this permission.
+.TP
+.I setattr
+The ownership details and security label of the key may be changed,
+the key's expiration time may be set, and the key may be revoked.
+.P
+In addition to access rights, any active Linux Security Module (LSM) may
+prevent access to a key if its policy so dictates.
+A key may be given a
+security label or other attribute by the LSM;
+this label is retrievable via
+.BR keyctl_get_security (3).
+.P
+See
+.BR keyctl_chown (3),
+.BR keyctl_describe (3),
+.BR keyctl_get_security (3),
+.BR keyctl_setperm (3),
+and
+.BR selinux (8)
+for more information.
+.\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
+.SS Searching for keys
+One of the key features of the Linux key-management facility
+is the ability to find a key that a process is retaining.
+The
+.BR request_key (2)
+system call is the primary point of
+access for user-space applications to find a key.
+(Internally, the kernel has something similar available
+for use by internal components that make use of keys.)
+.P
+The search algorithm works as follows:
+.IP (1) 5
+The process keyrings are searched in the following order: the
+.BR thread\-keyring (7)
+if it exists, the
+.BR process\-keyring (7)
+if it exists, and then either the
+.BR session\-keyring (7)
+if it exists or the
+.BR user\-session\-keyring (7)
+if that exists.
+.IP (2)
+If the caller was a process that was invoked by the
+.BR request_key (2)
+upcall mechanism, then the keyrings of the original caller of
+.BR request_key (2)
+will be searched as well.
+.IP (3)
+The search of a keyring tree is in breadth-first order:
+each keyring is searched first for a match,
+then the keyrings referred to by that keyring are searched.
+.IP (4)
+If a matching key is found that is valid,
+then the search terminates and that key is returned.
+.IP (5)
+If a matching key is found that has an error state attached,
+that error state is noted and the search continues.
+.IP (6)
+If no valid matching key is found,
+then the first noted error state is returned; otherwise, an
+.B ENOKEY
+error is returned.
+.P
+It is also possible to search a specific keyring, in which case only steps
+(3) to (6) apply.
+.P
+See
+.BR request_key (2)
+and
+.BR keyctl_search (3)
+for more information.
+.\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
+.SS On-demand key creation
+If a key cannot be found,
+.BR request_key (2)
+will, if given a
+.I callout_info
+argument, create a new key and then upcall to user space to
+instantiate the key.
+This allows keys to be created on an as-needed basis.
+.P
+Typically,
+this will involve the kernel creating a new process that executes the
+.BR request\-key (8)
+program, which will then execute the appropriate handler based on its
+configuration.
+.P
+The handler is passed a special authorization key that allows it
+and only it to instantiate the new key.
+This is also used to permit searches performed by the
+handler program to also search the requester's keyrings.
+.P
+See
+.BR request_key (2),
+.BR keyctl_assume_authority (3),
+.BR keyctl_instantiate (3),
+.BR keyctl_negate (3),
+.BR keyctl_reject (3),
+.BR request\-key (8),
+and
+.BR request\-key.conf (5)
+for more information.
+.\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
+.SS /proc files
+The kernel provides various
+.I /proc
+files that expose information about keys or define limits on key usage.
+.TP
+.IR /proc/keys " (since Linux 2.6.10)"
+This file exposes a list of the keys for which the reading thread has
+.I view
+permission, providing various information about each key.
+The thread need not possess the key for it to be visible in this file.
+.\" David Howells, Dec 2016 linux-man@:
+.\" This [The thread need not possess the key for it to be visible in
+.\" this file.] is correct.  See proc_keys_show() in security/keys/proc.c:
+.\"
+.\"	rc = key_task_permission(key_ref, ctx.cred, KEY_NEED_VIEW);
+.\"	if (rc < 0)
+.\"		return 0;
+.\"
+.\"Possibly it shouldn't be, but for now it is.
+.\"
+.IP
+The only keys included in the list are those that grant
+.I view
+permission to the reading process
+(regardless of whether or not it possesses them).
+LSM security checks are still performed,
+and may filter out further keys that the process is not authorized to view.
+.IP
+An example of the data that one might see in this file
+(with the columns numbered for easy reference below)
+is the following:
+.IP
+.EX
+  (1)     (2)     (3)(4)    (5)     (6)   (7)   (8)        (9)
+009a2028 I\-\-Q\-\-\-   1 perm 3f010000  1000  1000 user     krb_ccache:primary: 12
+1806c4ba I\-\-Q\-\-\-   1 perm 3f010000  1000  1000 keyring  _pid: 2
+25d3a08f I\-\-Q\-\-\-   1 perm 1f3f0000  1000 65534 keyring  _uid_ses.1000: 1
+28576bd8 I\-\-Q\-\-\-   3 perm 3f010000  1000  1000 keyring  _krb: 1
+2c546d21 I\-\-Q\-\-\- 190 perm 3f030000  1000  1000 keyring  _ses: 2
+30a4e0be I\-\-\-\-\-\-   4   2d 1f030000  1000 65534 keyring  _persistent.1000: 1
+32100fab I\-\-Q\-\-\-   4 perm 1f3f0000  1000 65534 keyring  _uid.1000: 2
+32a387ea I\-\-Q\-\-\-   1 perm 3f010000  1000  1000 keyring  _pid: 2
+3ce56aea I\-\-Q\-\-\-   5 perm 3f030000  1000  1000 keyring  _ses: 1
+.EE
+.IP
+The fields shown in each line of this file are as follows:
+.RS
+.TP
+ID (1)
+The ID (serial number) of the key, expressed in hexadecimal.
+.TP
+Flags (2)
+A set of flags describing the state of the key:
+.RS
+.TP
+I
+.\" KEY_FLAG_INSTANTIATED
+The key has been instantiated.
+.TP
+R
+.\" KEY_FLAG_REVOKED
+The key has been revoked.
+.TP
+D
+.\" KEY_FLAG_DEAD
+The key is dead (i.e., the key type has been unregistered).
+.\" unregister_key_type() in the kernel source
+(A key may be briefly in this state during garbage collection.)
+.TP
+Q
+.\" KEY_FLAG_IN_QUOTA
+The key contributes to the user's quota.
+.TP
+U
+.\" KEY_FLAG_USER_CONSTRUCT
+The key is under construction via a callback to user space;
+see
+.BR request\-key (2).
+.TP
+N
+.\" KEY_FLAG_NEGATIVE
+The key is negatively instantiated.
+.TP
+i
+.\" KEY_FLAG_INVALIDATED
+The key has been invalidated.
+.RE
+.TP
+Usage (3)
+This is a count of the number of kernel credential
+structures that are pinning the key
+(approximately: the number of threads and open file references
+that refer to this key).
+.TP
+Timeout (4)
+The amount of time until the key will expire,
+expressed in human-readable form (weeks, days, hours, minutes, and seconds).
+The string
+.I perm
+here means that the key is permanent (no timeout).
+The string
+.I expd
+means that the key has already expired,
+but has not yet been garbage collected.
+.TP
+Permissions (5)
+The key permissions, expressed as four hexadecimal bytes containing,
+from left to right, the possessor, user, group, and other permissions.
+Within each byte, the permission bits are as follows:
+.IP
+.PD 0
+.RS 12
+.TP
+0x01
+.I view
+.TP
+0x02
+.I read
+.TP
+0x04
+.I write
+.TP
+0x08
+.I search
+.TP
+0x10
+.I link
+.TP
+0x20
+.I setattr
+.RE
+.PD
+.TP
+UID (6)
+The user ID of the key owner.
+.TP
+GID (7)
+The group ID of the key.
+The value \-1 here means that the key has no group ID;
+this can occur in certain circumstances for keys created by the kernel.
+.TP
+Type (8)
+The key type (user, keyring, etc.)
+.TP
+Description (9)
+The key description (name).
+This field contains descriptive information about the key.
+For most key types, it has the form
+.IP
+.in +4n
+.EX
+name[: extra\-info]
+.EE
+.in
+.IP
+The
+.I name
+subfield is the key's description (name).
+The optional
+.I extra\-info
+field provides some further information about the key.
+The information that appears here depends on the key type, as follows:
+.RS
+.TP
+.IR \[dq]user\[dq] " and " \[dq]logon\[dq]
+The size in bytes of the key payload (expressed in decimal).
+.TP
+.I \[dq]keyring\[dq]
+The number of keys linked to the keyring,
+or the string
+.I empty
+if there are no keys linked to the keyring.
+.TP
+.I \[dq]big_key\[dq]
+The payload size in bytes, followed either by the string
+.IR [file] ,
+if the key payload exceeds the threshold that means that the
+payload is stored in a (swappable)
+.BR tmpfs (5)
+filesystem,
+or otherwise the string
+.IR [buff] ,
+indicating that the key is small enough to reside in kernel memory.
+.RE
+.IP
+For the
+.I \[dq].request_key_auth\[dq]
+key type
+(authorization key; see
+.BR request_key (2)),
+the description field has the form shown in the following example:
+.IP
+.in +4n
+.EX
+key:c9a9b19 pid:28880 ci:10
+.EE
+.in
+.IP
+The three subfields are as follows:
+.RS
+.TP
+.I key
+The hexadecimal ID of the key being instantiated in the requesting program.
+.TP
+.I pid
+The PID of the requesting program.
+.TP
+.I ci
+The length of the callout data with which the requested key should
+be instantiated
+(i.e., the length of the payload associated with the authorization key).
+.RE
+.RE
+.TP
+.IR /proc/key\-users " (since Linux 2.6.10)"
+This file lists various information for each user ID that
+has at least one key on the system.
+An example of the data that one might see in this file is the following:
+.IP
+.in +4n
+.EX
+   0:    10 9/9 2/1000000 22/25000000
+  42:     9 9/9 8/200 106/20000
+1000:    11 11/11 10/200 271/20000
+.EE
+.in
+.IP
+The fields shown in each line are as follows:
+.RS
+.TP
+.I uid
+The user ID.
+.TP
+.I usage
+This is a kernel-internal usage count for the kernel structure
+used to record key users.
+.TP
+.IR nkeys / nikeys
+The total number of keys owned by the user,
+and the number of those keys that have been instantiated.
+.TP
+.IR qnkeys / maxkeys
+The number of keys owned by the user,
+and the maximum number of keys that the user may own.
+.TP
+.IR qnbytes / maxbytes
+The number of bytes consumed in payloads of the keys owned by this user,
+and the upper limit on the number of bytes in key payloads for that user.
+.RE
+.TP
+.IR /proc/sys/kernel/keys/gc_delay " (since Linux 2.6.32)"
+.\" commit 5d135440faf7db8d566de0c6fab36b16cf9cfc3b
+The value in this file specifies the interval, in seconds,
+after which revoked and expired keys will be garbage collected.
+The purpose of having such an interval is so that there is a window
+of time where user space can see an error (respectively
+.B EKEYREVOKED
+and
+.BR EKEYEXPIRED )
+that indicates what happened to the key.
+.IP
+The default value in this file is 300 (i.e., 5 minutes).
+.TP
+.IR /proc/sys/kernel/keys/persistent_keyring_expiry " (since Linux 3.13)"
+.\" commit f36f8c75ae2e7d4da34f4c908cebdb4aa42c977e
+This file defines an interval, in seconds,
+to which the persistent keyring's expiration timer is reset
+each time the keyring is accessed (via
+.BR keyctl_get_persistent (3)
+or the
+.BR keyctl (2)
+.B KEYCTL_GET_PERSISTENT
+operation.)
+.IP
+The default value in this file is 259200 (i.e., 3 days).
+.P
+The following files (which are writable by privileged processes)
+are used to enforce quotas on the number of keys
+and number of bytes of data that can be stored in key payloads:
+.TP
+.IR /proc/sys/kernel/keys/maxbytes " (since Linux 2.6.26)"
+.\" commit 0b77f5bfb45c13e1e5142374f9d6ca75292252a4
+.\" Previously: KEYQUOTA_MAX_BYTES      10000
+This is the maximum number of bytes of data that a nonroot user
+can hold in the payloads of the keys owned by the user.
+.IP
+The default value in this file is 20,000.
+.TP
+.IR /proc/sys/kernel/keys/maxkeys " (since Linux 2.6.26)"
+.\" commit 0b77f5bfb45c13e1e5142374f9d6ca75292252a4
+.\" Previously: KEYQUOTA_MAX_KEYS       100
+This is the maximum number of keys that a nonroot user may own.
+.IP
+The default value in this file is 200.
+.TP
+.IR /proc/sys/kernel/keys/root_maxbytes " (since Linux 2.6.26)"
+This is the maximum number of bytes of data that the root user
+(UID 0 in the root user namespace)
+can hold in the payloads of the keys owned by root.
+.IP
+.\"738c5d190f6540539a04baf36ce21d46b5da04bd
+The default value in this file is 25,000,000 (20,000 before Linux 3.17).
+.\" commit 0b77f5bfb45c13e1e5142374f9d6ca75292252a4
+.TP
+.IR /proc/sys/kernel/keys/root_maxkeys " (since Linux 2.6.26)"
+.\" commit 0b77f5bfb45c13e1e5142374f9d6ca75292252a4
+This is the maximum number of keys that the root user
+(UID 0 in the root user namespace)
+may own.
+.IP
+.\"738c5d190f6540539a04baf36ce21d46b5da04bd
+The default value in this file is 1,000,000 (200 before Linux 3.17).
+.P
+With respect to keyrings,
+note that each link in a keyring consumes 4 bytes of the keyring payload.
+.\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
+.SS Users
+The Linux key-management facility has a number of users and usages,
+but is not limited to those that already exist.
+.P
+In-kernel users of this facility include:
+.TP
+Network filesystems - DNS
+The kernel uses the upcall mechanism provided by the keys to upcall to
+user space to do DNS lookups and then to cache the results.
+.TP
+AF_RXRPC and kAFS - Authentication
+The AF_RXRPC network protocol and the in-kernel AFS filesystem
+use keys to store the ticket needed to do secured or encrypted traffic.
+These are then looked up by
+network operations on AF_RXRPC and filesystem operations on kAFS.
+.TP
+NFS - User ID mapping
+The NFS filesystem uses keys to store mappings of
+foreign user IDs to local user IDs.
+.TP
+CIFS - Password
+The CIFS filesystem uses keys to store passwords for accessing remote shares.
+.TP
+Module verification
+The kernel build process can be made to cryptographically sign modules.
+That signature is then checked when a module is loaded.
+.P
+User-space users of this facility include:
+.TP
+Kerberos key storage
+The MIT Kerberos 5 facility (libkrb5) can use keys to store authentication
+tokens which can be made to be automatically cleaned up a set time after
+the user last uses them,
+but until then permits them to hang around after the user
+has logged out so that
+.BR cron (8)
+scripts can use them.
+.\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
+.SH SEE ALSO
+.ad l
+.nh
+.BR keyctl (1),
+.BR add_key (2),
+.BR keyctl (2),
+.BR request_key (2),
+.BR keyctl (3),
+.BR keyutils (7),
+.BR persistent\-keyring (7),
+.BR process\-keyring (7),
+.BR session\-keyring (7),
+.BR thread\-keyring (7),
+.BR user\-keyring (7),
+.BR user\-session\-keyring (7),
+.BR pam_keyinit (8),
+.BR request\-key (8)
+.P
+The kernel source files
+.I Documentation/crypto/asymmetric\-keys.txt
+and under
+.I Documentation/security/keys
+(or, before Linux 4.13, in the file
+.IR Documentation/security/keys.txt ).