Re: Revised keyrings(7) man page for review
From: Michael Kerrisk (man-pages)
Date: Sat Nov 26 2016 - 07:52:43 EST
Hi David,
Would you have a chance to look at this page?
Cheers
Michael
On 11/04/2016 04:47 PM, Michael Kerrisk wrote:
> Hi David,
>
> As part of the process of adopting the *.7 pages from
> keyutils into man-pages, I've made some significant
> extensions to the keyrings(7) page. Among the more notable
> changes:
>
> * Expanded the detail in "Key types"
> * Addition of a section on the various /proc files
> * Various other minor reworkings elsewhere in the text
>
> Would you would be willing to review the new page, please?
> (The page source file is attached, in case you want to
> see all the formatting.)
>
> Cheers,
>
> Michael
>
>
> ====
>
> NAME
> keyrings - in-kernel key management and retention facility
>
> DESCRIPTION
> The Linux key-management facility is primarily a way for drivâ
> ers to retain or cache security data, authentication keys,
> encryption keys, and other data in the kernel.
>
> System call interfaces are provided so that user-space programs
> can manage those objects and also use the facility for their
> own purposes.
>
> A library and some user-space utilities are provided to allow
> access to the facility. See keyctl(1), keyctl(3), and keyuâ
> tils(7) for more information.
>
> Keys
> A key has the following attributes:
>
> Serial number (ID)
> This is a unique integer handle by which a key is
> referred to in system call arguments. The serial number
> is sometimes synonymously referred as the key ID. Proâ
> grammatically, key serial numbers are represented using
> the type key_serial_t.
>
> 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.
>
> There are a number of general purpose types available,
> plus some specialist types defined by specific drivers.
>
> 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.
>
> 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. (Details can be
> found in request_key(2).)
>
> A key's payload can be read and updated if the key type
> supports it and if suitable permission is granted to the
> caller.
>
> Access rights
> Much as files do, each key has an owning user ID, an
> owning group ID, and a security label. They also have a
> set of permissions, though there are more than for a
> normal UNIX file, and there is an additional category
> beyond the usual user, group, and other (see below).
>
> Note that keys are quota controlled since they represent
> unswappable kernel memory and the owning user ID speciâ
> fies whose quota is to be debited.
>
> 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 EKEYEXPIRED. If not deleted,
> updated, or replaced, after a set amount of time,
> expired keys are automatically removed along with all
> links to them, and attempts to access the key will fail
> with the error ENOKEY.
>
> 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.
>
> Key types
> The facility provides several basic types of key:
>
> "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.
>
> The payload for keys of this type is a blob of arbitrary
> data of up to 32,767 bytes.
>
> 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 "afs:mykey").
>
> "keyring"
> Keyrings are special keys whose payload consists of 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.
>
> "logon" (since Linux 3.3)
> This key type is essentially the same as "user", but it
> does not provide reading (i.e., the keyctl(2)
> KEYCTL_READ operation), meaning that the key payload is
> never visible from user space. This is suitable for
> storing username-password pairs that you do not want to
> be readable from user space.
>
> "big_key" (since Linux 3.13)
> This key type is similar to the "user" key type, but it
> may hold a payload of up to 1MiB in size. The data may
> be stored in the swap space rather than in kernel memory
> if the data size exceeds the overhead of storing the
> data in swap space (a tmpfs file is used, which requires
> filesystem structures to be allocated in the kernel).
> This key type is useful for tasks such as holding Kerâ
> beros ticket caches.
>
> There are more specialized key types available also, but
> they're not discussed here as they're not intended for normal
> user-space use.
>
> 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.
>
> Various operations (system calls) may be applied only to
> keyrings:
>
> Adding A key may be added to a keyring by system calls that
> create keys. This prevents the new key from being immeâ
> diately deleted when the system call driver releases its
> last reference to the key.
>
> 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.
>
> 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.
>
> Clearing
> All the links may be removed from a keyring.
>
> Searching
> A keyring may be considered the root of a tree or subâ
> tree in which keyrings form the branches and non-
> keyrings the leaves. This tree may be searched for a
> leaf matching a particular type and description.
>
> See keyctl_clear(3), keyctl_link(3), keyctl_search(3), and
> keyctl_unlink(3) for more information.
>
> Anchoring keys
> To prevent a key from being prematurely garbage collected, it
> must anchored to keep its reference count elevated when it is
> not in active use by the kernel.
>
> Keyrings are used to anchor other keys - each link is a referâ
> ence on a key - but whilst keyrings are available to link to
> keys, keyrings themselves are just keys and are also subject to
> the same anchoring necessity.
>
> The kernel makes available a number of anchor keyrings. Note
> that some of these keyrings will be created only when first
> accessed.
>
> 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.
>
> There are three keyrings with different inheriâ
> tance/sharing rules: The session-keyring(7) (inherited
> and shared by all child processes), the process-
> keyring(7) (shared by all threads in a process) and the
> thread-keyring(7) (specific to a particular thread).
>
> User keyrings
> Each UID known to the kernel has a record that contains
> two keyrings: the user-keyring(7) and the user-session-
> keyring(7). These exist for as long as the UID record
> in the kernel exists. A link to the user keyring is
> placed in a new session keyring by pam_keyinit(8) when a
> new login session is initiated.
>
> Persistent keyrings
> There is a 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 expiraâ
> tion time set such that it is automatically cleaned up
> after a set time. This, for example, permits cron
> scripts to use credentials left when the user logs out.
>
> Note that the expiration time is reset every time the
> persistent key is requested.
>
> Special keyrings
> There are special keyrings owned by the kernel that can
> anchor keys for special purposes. An example of this is
> the system keyring used for holding encryption keys for
> module signature verification.
>
> These special keyrings are usually closed to direct
> alteration by user space.
>
> See thread-keyring(7), process-keyring(7), session-keyring(7),
> user-keyring(7), user-session-keyring(7), and persistent-
> keyring(7) for more information.
>
> 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:
>
> (1) Any key or keyring that does not grant search permission to
> the caller is ignored in all the following rules.
>
> (2) A thread possesses its session, process, and thread
> keyrings directly because those are pointed to by its creâ
> dentials.
>
> (3) If a keyring is possessed, then any key it links to is also
> possessed.
>
> (4) If any key a keyring links to is itself a keyring, then
> rule (3) applies recursively.
>
> (5) If a process is upcalled from the kernel to instantiate a
> key, then it also possesses the requester's keyrings as in
> rule (1) as if it were the requester.
>
> Note that possession is not a fundamental property of a key,
> but must rather be calculated each time the key is needed.
>
> Possession is designed to allow set-user-ID programs run from,
> say a user's shell to access the user's keys. It also allows
> the prevention of access to keys just on the basis of UID and
> GID matches.
>
> When it creates the session keyring, pam_keyinit(8) adds a link
> to the user-keyring(7), thus making the user keyring and anyâ
> thing it contains possessed by default.
>
> Access rights
> Each key has the following security-related attributes:
>
> * The owning user ID
>
> * The ID of a group that is permitted to access the key
>
> * A security label
>
> * A permissions mask
>
> 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:
>
> user The set specifies the rights granted if the key's user
> ID matches the caller's filesystem user ID.
>
> 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.
>
> other The set specifies the rights granted if neither the
> key's user ID nor group ID matched.
>
> The fourth set of rights is:
>
> possessor
> The set specifies the rights granted if a key is deterâ
> mined to be possessed by the caller.
>
> 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.
>
> The set of rights that may be granted in each of the four masks
> is as follows:
>
> view The attributes of the key may be read. This includes
> the type, description, and access rights (excluding the
> security label).
>
> 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.
>
> write The payload of the key may be updated. For a keyring,
> links may be added to or removed from the keyring, the
> keyring may be cleared completely (all links are
> removed), and the key may be revoked.
>
> 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.
>
> link Links may be created from keyrings to the key. The iniâ
> tial link to a key that is established when the key is
> created doesn't require this permission.
>
> 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.
>
> If any right is granted to a thread for a key,
>
>
> âââââââââââââââââââââââââââââââââââââââââââââââââââââââ
> âFIXME â
> âââââââââââââââââââââââââââââââââââââââââââââââââââââââ
> âThis seems to contradict the text below, which says â
> âthat 'view' permission is what is significant. â
> âWhich is correct? â
> âââââââââââââââââââââââââââââââââââââââââââââââââââââââ
> then that thread will see the key listed in /proc/keys. If no
> rights at all are granted, then that thread can't even tell
> that the key exists.
>
> 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
> which can be retrieved.
>
> See keyctl_chown(3), keyctl_describe(3), keyctl_get_secuâ
> rity(3), keyctl_setperm(3), and selinux(8) for more informaâ
> tion.
>
> 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
> 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.)
>
> The search algorithm works as follows:
>
> (1) The three process keyrings are searched in the following
> order: the thread thread-keyring(7) if it exists, the
> process-keyring(7) if it exists, and then either the sesâ
> sion-keyring(7) if it exists or the user-session-keyring(7)
> if that exists.
>
> (2) If the caller was a process that was invoked by the
> request_key(2) upcall mechanism then the keyrings of the
> original caller of that request_key(2) will be searched as
> well.
>
> (3) The search of the keyring tree is in preorder: each keyring
> is searched first for a match, then the keyrings referred
> to by that keyring are searched.
>
> (4) If a matching key is found that is valid, then the search
> terminates and that key is returned.
>
> (5) If a matching key is found that has an error state
> attached, that error state is noted and the search continâ
> ues.
>
> (6) If valid matching key is found, then the first noted error
> state is returned; otherwise, an ENOKEY error is returned.
>
> It is also possible to search a specific keyring, in which case
> only steps (3) to (6) apply.
>
> See request_key(2) and keyctl_search(3) for more information.
>
> On-demand key creation
> If a key cannot be found, request_key(2) will, if given a callâ
> out_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.
>
> Typically, this will involve the kernel forking and exec'ing
> the request-key(8) program, which will then execute the approâ
> priate handler based on its configuration.
>
> 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.
>
> See request_key(2), keyctl_assume_authority(3), keyctl_instanâ
> tiate(3), keyctl_negate(3), keyctl_reject(3), request-key(8)
> and request-key.conf(5) for more information.
>
> /proc files
> The kernel provides various /proc files that expose information
> about keys or define limits on key usage.
>
> /proc/keys (since Linux 2.6.10)
> This file exposes a list of the keys that are viewable
> by the reading process, providing various information
> about each key.
>
> The only keys included in the list are those that grant
> 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.
>
> An example of the data that one might see in this file
> is the following:
>
> 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
>
> The fields shown in each line of this file are as folâ
> lows:
>
> ID The ID (serial number) of the key, expressed in
> hexadecimal.
>
> Flags A set of flags describing the state of the key:
>
> I The key has been instantiated.
>
> R The key has been revoked.
>
> D The key is dead (i.e., has been deleted). (A
> key may be briefly in this state during
> garbage collection.)
>
> Q The key contributes to the user's quota.
>
> U The key is under construction via a callback
> to user space; see request-key(2).
>
> N The key is negatively instantiated.
>
> i The key has been invalidated.
>
> Usage This is a count of the number of kernel credenâ
> tial structures that are pinning the key (approxâ
> imately: the number of threads and open file refâ
> erences that refer to this key).
>
> Timeout
> The amount of time until the key will expire,
> expressed in human-readable form (weeks, days,
> hours, minutes, and seconds). The string perm
> here means that the key is permanent (no timeâ
> out). The string expd means that the key has
> already expired, but has not yet been garbage
> collected.
>
> Permissions
> The key permissions, expressed as four hexadeciâ
> mal bytes containing, from left to right, the
> possessor, user, group, and other permissions.
>
> UID The user ID of the key owner.
>
> GID The group ID of the key. The value -1 here means
> that the key as no group ID; this can occur in
> certain circumstances for keys created by the
> kernel.
>
> Type The key type (user, keyring, etc.)
>
> Description
> The key description (name).
>
> Description
> This field contains descriptive information about
> the key. For most key tpes, it has the form
>
> desc[: extra-info]
>
> The name subfield is the the key's description
> (name). The optional extra-info field provides
> some further information about the key. The
> information that appears here depends on the key
> type, as follows:
>
> "user" and "logon"
> The size in bytes of the key payload
> (expressed in decimal).
>
> "keyring"
> The number of keys linked to the keyring, or
> the string empty if there are no keys linked
> to the keyring.
>
> "big_key"
> The payload size in bytes, followed either by
> the string [file], if the key payload exceeds
> the threshold that means that the payload is
> stored in a (swappable) tmpfs filesystem, or
> otherwise the string [buff], indicating that
> the key is small enough to reside in kernel
> memory.
>
> For the ".request_key_auth" key type (authorizaâ
> tion key; see request_key(2)), the description
> field has the form shown in the following examâ
> ple:
>
> key:c9a9b19 pid:28880 ci:10
>
> The three subfields are as follows:
>
> key The hexadecimal ID of the key being instanâ
> tiated in the requesting program.
>
> pid The PID of the requesting program.
>
> 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).
>
> /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 followâ
> ing:
>
> 0: 10 9/9 2/1000000 22/25000000
> 42: 9 9/9 8/200 106/20000
> 1000: 11 11/11 10/200 271/20000
>
> The fields shown in each line are as follows:
>
> uid The user ID.
>
> usage This is a kernel-internal usage count for the
> kernel structure used to record key users.
>
> nkeys/nikeys
> The total number of keys owned by the user, and
> the number of those keys that have been instantiâ
> ated.
>
> qnkeys/maxkeys
> The number of keys owned by the user, and the
> maximum keys that the user may own.
>
> 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.
>
> /proc/sys/kernel/keys/gc_delay (since Linux 2.6.32)
> The value in this file specifies the interval, in secâ
> onds, after which revoked and expired keys will be
> garbage collected. The purpose of having such an interâ
> val is so that there is a window of time where user
> space can see an error (respectively EKEYREVOKED and
> EKEYEXPIRED) that indicates what happened to the key.
>
> The default value in this file is 300 (i.e., 5 minutes).
>
> /proc/sys/kernel/keys/persistent_keyring_expiry (since Linux
> 3.13)
> This file defines an interval, in seconds, to which the
> persistent keyring's expiration timer is reset each time
> the keyring is accessed (via keyctl_get_persistent(3) or
> the keyctl(2) KEYCTL_GET_PERSISTENT operation.)
>
> The default value in this file is 259200 (i.e., 3 days).
>
> The following files (which are writable by privileged proâ
> cesses) are used to enforce quotas on the number of keys and
> number of bytes of data that can be stored in key payloads:
>
> /proc/sys/kernel/keys/maxbytes (since Linux 2.6.26)
> This is the maximum number of bytes of data that a nonâ
> root user can hold in the payloads of the keys owned by
> the user.
>
> The default value in this file is 20,000.
>
> /proc/sys/kernel/keys/maxkeys (since Linux 2.6.26)
> This is the maximum number of keys that a nonroot user
> may own.
>
> The default value in this file is 200.
>
> /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.
>
> The default value in this file is 25,000,000.
>
> /proc/sys/kernel/keys/root_maxkeys (since Linux 2.6.26)
> This is the maximum number of keys that the root user
> (UID 0 in the root user namespace) may own.
>
> The default value in this file is 1,000,000.
>
> With respect to keyrings, note that each link in a keyring conâ
> sumes 4 bytes of the keyring payload.
>
> Users
> The Linux key-management facility has a number of users and
> usages, but is not limited to those that already exist.
>
> In-kernel users of this facility include:
>
> 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.
>
> 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 operaâ
> tions on kAFS.
>
> NFS - User ID mapping
> The NFS filesystem uses keys to store mappings of forâ
> eign user IDs to local user IDs.
>
> CIFS - Password
> The CIFS filesystem uses keys to store passwords for
> accessing remote shares.
>
> Module verification
> The kernel build process can be made to cryptographiâ
> cally sign modules. That signature is then checked when
> a module is loaded.
>
> User-space users of this facility include:
>
> 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 cron scripts can
> use them.
>
> SEE ALSO
> keyutils(7), persistent-keyring(7), process-keyring(7),
> session-keyring(7), thread-keyring(7), user-keyring(7),
> user-session-keyring(7), pam_keyinit(8)
>
>
>
> Linux 2016-11-01 KEYRINGS(7)
>
--
Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
Linux/UNIX System Programming Training: http://man7.org/training/