keyrings(7) — Linux manual page

NAME | DESCRIPTION | SEE ALSO | COLOPHON

KEYRINGS(7)             Linux Programmer's Manual            KEYRINGS(7)

NAME         top

       keyrings - in-kernel key management and retention facility

DESCRIPTION         top

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

   /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 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
                          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
                     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" 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(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.

   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.

SEE ALSO         top

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

COLOPHON         top

       This page is part of release 5.13 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/.

Linux                          2021-03-22                    KEYRINGS(7)

Pages that refer to this page: keyctl(1)add_key(2)keyctl(2)request_key(2)find_key_by_type_and_name(3)keyctl(3)keyctl_capabilities(3)keyctl_chown(3)keyctl_clear(3)keyctl_describe(3)keyctl_get_keyring_ID(3)keyctl_get_persistent(3)keyctl_get_security(3)keyctl_instantiate(3)keyctl_invalidate(3)keyctl_join_session_keyring(3)keyctl_link(3)keyctl_move(3)keyctl_pkey_encrypt(3)keyctl_pkey_query(3)keyctl_pkey_sign(3)keyctl_read(3)keyctl_revoke(3)keyctl_search(3)keyctl_session_to_parent(3)keyctl_setperm(3)keyctl_set_reqkey_keyring(3)keyctl_set_timeout(3)keyctl_update(3)keyctl_watch_key(3)recursive_key_scan(3)proc(5)asymmetric-key(7)keyutils(7)persistent-keyring(7)process-keyring(7)session-keyring(7)thread-keyring(7)user-keyring(7)user_namespaces(7)user-session-keyring(7)key.dns_resolver(8)request-key(8)