Merging upstream version 6.8.

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

1 files changed, 0 insertions, 901 deletions

diff --git a/man7/keyrings.7 b/man7/keyrings.7
deleted file mode 100644
index 879d1aa..0000000
--- a/man7/keyrings.7
+++ /dev/null
@@ -1,901 +0,0 @@
-.\" 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-02-25 "Linux man-pages 6.7"
-.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 ).