# keyrings

## NAME



           keyrings - in-kernel key management and retention facility
    


## 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.
    
           System call interfaces are provided so that user-space programs
           can manage those objects and also use the facility for their own
           purposes; see add_key(2), request_key(2), and keyctl(2).
    
           A library and some user-space utilities are provided to allow
           access to the facility.  See keyctl(1), keyctl(3), and keyutils(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 calls.  The serial number is sometimes
                  synonymously referred as the key ID.  Programmatically, 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 kernel
                  components.
    
           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.  For further details, see
                  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.  Each key also has a set of
                  permissions, though there are more than for a normal UNIX
                  file, and there is an additional category—possessor—beyond
                  the usual user, group, and other (see _Possession_ , below).
    
                  Note that keys are quota controlled, since they require
                  unswappable kernel memory.  The owning user ID specifies
                  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 the error **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 **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 kernel provides several basic types of key:
    
           _"keyring"_
                  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.
    
                  Keyrings with descriptions (names) that begin with a period
                  ('.') are reserved to the implementation.
    
           _"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"_).
    
           _"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 should not be readable from user space.
    
                  The description of a _"logon"_ key _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 _"user"_ type, where the inclusion
                  of a prefix is recommended but is not enforced.)
    
           _"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 1 MiB in size.  This key type is
                  useful for purposes such as holding Kerberos ticket caches.
    
                  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, the payload data is
                  encrypted when stored in tmpfs, thereby preventing it from
                  being written unencrypted into swap space.
    
           There are more specialized key types available also, but they
           aren't discussed here because they aren't intended for normal
           user-space use.
    
           Key type names that begin with a period ('.') are reserved to the
           implementation.
    
       **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 immediately
                  deleted when the system call 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 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.
    
           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 garbage collected, it must be 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 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.
    
           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 inheritance/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).
    
                  As an alternative to using the actual keyring IDs, in calls
                  to add_key(2), keyctl(2), and request_key(2), the special
                  keyring values **KEY_SPEC_SESSION_KEYRING** ,
                  **KEY_SPEC_PROCESS_KEYRING** , and **KEY_SPEC_THREAD_KEYRING** can
                  be used to refer to the caller's own instances of these
                  keyrings.
    
           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.
    
                  As an alternative to using the actual keyring IDs, in calls
                  to add_key(2), keyctl(2), and request_key(2), the special
                  keyring values **KEY_SPEC_USER_KEYRING** and
                  **KEY_SPEC_USER_SESSION_KEYRING** can be used to refer to the
                  caller's own instances of these keyrings.
    
                  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 expiration time
                  set such that it is automatically cleaned up after a set
                  time.  The persistent keyring permits, for example, cron(8)
                  scripts to use credentials that are left in the persistent
                  keyring after the user logs out.
    
                  Note that the expiration time of the persistent keyring 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.
    
           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
           **KEY_SPEC_GROUP_KEYRING** has been defined for this keyring.
    
       **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-keyring(7),
                process-keyring(7), and thread-keyring(7) directly because
                those keyrings are referred to by its credentials.
    
           (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
                (see request_key(2)), 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.  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.
    
           When it creates the session keyring, pam_keyinit(8) adds a link to
           the user-keyring(7), thus making the user keyring and anything 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 determined
                  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 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),
    
           _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 initial
                  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.
    
           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 keyctl_get_security(3).
    
           See keyctl_chown(3), keyctl_describe(3), keyctl_get_security(3),
           keyctl_setperm(3), and selinux(8) for more information.
    
       **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 process keyrings are searched in the following order: the
                thread-keyring(7) if it exists, the process-keyring(7) if it
                exists, and then either the session-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 request_key(2) will be searched as well.
    
           (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.
    
           (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 continues.
    
           (6)  If no 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
           _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.
    
           Typically, this will involve the kernel creating a new process
           that executes the request-key(8) program, which will then execute
           the appropriate 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_instantiate(3), keyctl_negate(3), keyctl_reject(3),
           request-key(8), and request-key.conf(5) for more information.
    
       **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 operations on
                  kAFS.
    
           NFS - User ID mapping
                  The NFS filesystem uses keys to store mappings of foreign
                  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 cryptographically
                  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(8) scripts can use them.
    


## 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 for which the reading
                  thread has _view_ permission, providing various information
                  about each key.  The thread need not possess the key for it
                  to be visible in this file.
    
                  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
                  (with the columns numbered for easy reference below) is the
                  following:
    
                    (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
    
                  The fields shown in each line of this file are as follows:
    
                  ID (1) The ID (serial number) of the key, expressed in
                         hexadecimal.
    
                  Flags (2)
                         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., the key type has been
                                unregistered).  (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 (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).
    
                  Timeout (4)
                         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 timeout).  The
                         string _expd_ means that the key has already expired,
                         but has not yet been garbage collected.
    
                  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:
    
                              0x01   _view_
                              0x02   _read_
                              0x04   _write_
                              0x08   _search_
                              0x10   _link_
                              0x20   _setattr_
    
                  UID (6)
                         The user ID of the key owner.
    
                  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.
    
                  Type (8)
                         The key type (user, keyring, etc.)
    
                  Description (9)
                         The key description (name).  This field contains
                         descriptive information about the key.  For most key
                         types, it has the form
    
                             name[: extra-info]
    
                         The _name_ subfield is 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"_
                         _"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(5) 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 (authorization
                         key; see request_key(2)), the description field has
                         the form shown in the following example:
    
                             key:c9a9b19 pid:28880 ci:10
    
                         The three subfields are as follows:
    
                         _key_    The hexadecimal ID of the key being
                                instantiated 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 following:
    
                         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 instantiated.
    
                  _qnkeys_ /_maxkeys_
                         The number of keys owned by the user, and the
                         maximum number of 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 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 **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 processes)
           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 nonroot
                  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 (20,000 before
                  Linux 3.17).
    
           _/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 (200 before
                  Linux 3.17).
    
           With respect to keyrings, note that each link in a keyring
           consumes 4 bytes of the keyring payload.
    


* * *