KEYRINGS(7)               (2020-08-13)                KEYRINGS(7)

     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.  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 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).

     Page 1                        Linux             (printed 5/24/22)

     KEYRINGS(7)               (2020-08-13)                KEYRINGS(7)

               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 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 the error EKEYEXPIRED.  If not
               deleted, updated, or replaced, then, after a set amount
               of time, an expired key is automatically removed (gar-
               bage 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 (aq.aq) 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 arbi-
               trary data of up to 32,767 bytes.

     Page 2                        Linux             (printed 5/24/22)

     KEYRINGS(7)               (2020-08-13)                KEYRINGS(7)

               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 inter-
               est (for instance

     htmlmanrefend"
               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 unen-
               crypted 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 (aq.aq) 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.

     Page 3                        Linux             (printed 5/24/22)

     KEYRINGS(7)               (2020-08-13)                KEYRINGS(7)

          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 sub-
               tree 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 ref-
          erence 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

     Page 4                        Linux             (printed 5/24/22)

     KEYRINGS(7)               (2020-08-13)                KEYRINGS(7)

               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 expira-
               tion 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.

     Page 5                        Linux             (printed 5/24/22)

     KEYRINGS(7)               (2020-08-13)                KEYRINGS(7)

          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 creden-
              tials.

          (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.  Grant-
          ing 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

     Page 6                        Linux             (printed 5/24/22)

     KEYRINGS(7)               (2020-08-13)                KEYRINGS(7)

          *  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 supple-
               mentary 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 which-
          ever 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.

     Page 7                        Linux             (printed 5/24/22)

     KEYRINGS(7)               (2020-08-13)                KEYRINGS(7)

          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 Mod-
          ule (LSM) may prevent access to a key if its policy so dic-
          tates.  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.  (Inter-
          nally, 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 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 con-
              tinues.

          (6) If no valid matching key is found, then the first noted

     Page 8                        Linux             (printed 5/24/22)

     KEYRINGS(7)               (2020-08-13)                KEYRINGS(7)

              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 informa-
          tion.

        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 pro-
          cess that executes the request-key(8) program, which will
          then execute the appropriate handler based on its configura-
          tion.

          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 pro-
          gram 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 informa-
          tion.

        /proc files
          The kernel provides various /proc files that expose informa-
          tion about keys or define limits on key usage.

               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 pos-
               sess 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

     Page 9                        Linux             (printed 5/24/22)

     KEYRINGS(7)               (2020-08-13)                KEYRINGS(7)

               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 (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 (approxi-
                    mately: the number of threads and open file refer-
                    ences 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

     Page 10                       Linux             (printed 5/24/22)

     KEYRINGS(7)               (2020-08-13)                KEYRINGS(7)

                    bytes containing, from left to right, the posses-
                    sor, user, group, and other permissions.  Within
                    each byte, the permission bits are as follows:

                           0x01 view
                           Ox02 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 ker-
                    nel.

               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 fur-
                    ther information about the key.  The information
                    that appears here depends on the key type, as fol-
                    lows:

                         The size in bytes of the key payload (expressed in dec-
                         imal).

                         The number of keys linked to the keyring,
                         or the string empty if there are no keys
                         linked to the keyring.

                         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.

     Page 11                       Linux             (printed 5/24/22)

     KEYRINGS(7)               (2020-08-13)                KEYRINGS(7)

                    For the

                    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 instanti-
                         ated 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).

               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 ker-
                    nel structure used to record key users.

               nikeys
                    The total number of keys owned by the user, and
                    the number of those keys that have been instanti-
                    ated.

               maxkeys
                    The number of keys owned by the user, and the max-
                    imum number of keys that the user may own.

               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.

     Page 12                       Linux             (printed 5/24/22)

     KEYRINGS(7)               (2020-08-13)                KEYRINGS(7)

               htmlmanrefend/proc/sys/kernel/keys/gc_delay(sinceLinu

          htmlmanrefstart/proc/sys/kernel/keys/persistent_keyring_expiry(sinceLinux3.13)    .}f 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:

               htmlmanrefend/proc/sys/kernel/keys/maxbytes(sinceLinu

          htmlmanrefstart/proc/sys/kernel/keys/maxkeys(sinceLinux2.6.26)    .}f This is the maximum number of keys that a nonroot
               user may own.

               The default value in this file is 200.

               htmlmanrefend/proc/sys/kernel/keys/root_maxbyt

          htmlmanrefstart/proc/sys/kernel/keys/root_maxkeys(sinceLinux2.6.26)    .}f 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

     Page 13                       Linux             (printed 5/24/22)

     KEYRINGS(7)               (2020-08-13)                KEYRINGS(7)

          consumes 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(8) scripts
               can use them.

     SEE ALSO
          keyctl(1), add_key(2), keyctl(2), request_key(2), keyctl(3),
          keyutils(7), persistent-keyring(7), process-keyring(7),
          session-keyring(7), thread-keyring(7), user-keyring(7),
          user-session-keyring(7), pam_keyinit(8), request-key(8)

          The kernel source files Documentation/crypto/asymmetric-
          keys.txt and under Documentation/security/keys (or, before
          Linux 4.13, in the file Documentation/security/keys.txt).

     Page 14                       Linux             (printed 5/24/22)

     KEYRINGS(7)               (2020-08-13)                KEYRINGS(7)

     COLOPHON
          This page is part of release 5.10 of the Linux man-pages
          project.  A description of the project, information about
          reporting bugs, and the latest version of this page, can be
          found at https://www.kernel.org/doc/man-pages/.

     Page 15                       Linux             (printed 5/24/22)