diff options
Diffstat (limited to 'man7/keyrings.7')
| -rw-r--r-- | man7/keyrings.7 | 901 |
1 files changed, 901 insertions, 0 deletions
diff --git a/man7/keyrings.7 b/man7/keyrings.7 new file mode 100644 index 0000000..1ebd25f --- /dev/null +++ b/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 2023-02-05 "Linux man-pages 6.05.01" +.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. +.PP +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). +.PP +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 """keyring""" +.\" 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 """user""" +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 """afs:mykey""" ). +.TP +.IR """logon""" " (since Linux 3.3)" +.\" commit 9f6ed2ca257fa8650b876377833e6f14e272848b +This key type is essentially the same as +.IR """user""" , +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 """logon""" +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 """user""" +type, where the inclusion of a prefix is recommended but is not enforced.) +.TP +.IR """big_key""" " (since Linux 3.13)" +.\" commit ab3c3587f8cda9083209a61dbe3a4407d3cada10 +This key type is similar to the +.I """user""" +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. +.PP +There are more specialized key types available also, +but they aren't discussed here +because they aren't intended for normal user-space use. +.PP +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. +.PP +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. +.PP +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. +.PP +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. +.PP +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. +.PP +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. +.PP +Note that possession is not a fundamental property of a key, +but must rather be calculated each time the key is needed. +.PP +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. +.PP +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 +.PP +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. +.PP +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. +.PP +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. +.PP +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. +.PP +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). +.PP +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.) +.PP +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. +.PP +It is also possible to search a specific keyring, in which case only steps +(3) to (6) apply. +.PP +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. +.PP +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. +.PP +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. +.PP +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 """user""" " and " """logon""" +The size in bytes of the key payload (expressed in decimal). +.TP +.I """keyring""" +The number of keys linked to the keyring, +or the string +.I empty +if there are no keys linked to the keyring. +.TP +.I """big_key""" +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 """.request_key_auth""" +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). +.PP +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). +.PP +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. +.PP +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. +.PP +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) +.PP +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 ). |