NAME | OVERVIEW | KEYS | KEY TYPES | KEYRINGS | ANCHORING KEYS | POSSESSION | ACCESS RIGHTS | SEARCHING FOR KEYS | ON-DEMAND KEY CREATION | USERS | SEE ALSO | COLOPHON

KEYRINGS(7)                 Kernel key management                KEYRINGS(7)

NAME         top

       keyrings - In-kernel key management and retention facility

OVERVIEW         top

       The keyrings facility is primarily a way for drivers to retain or
       cache security data, authentication keys, encryption keys and other
       data in the kernel.

       System call interfaces are provided so that userspace programs can
       manage those objects and also use the facility for their own
       purposes.

       A library and some userspace utilities are provided to allow access
       to the facility.  See keyutils(7) manual page for more information.

       This document contains the following sections:

              - Keys.
              - Key types.
              - Keyrings.
              - Anchoring keys.
              - Possession.
              - Access rights.
              - Searching for keys.
              - On-demand key creation.
              - Users.

KEYS         top

       The facility provides the concept of a 'key', where all of the above
       examples are encapsulated within objects of this type.

       A 'key' contains the following elements:

       Serial number
              This is a unique integer handle by which a key is referred to
              in system call arguments.

       Type   This defines what sort of data can be held in the key, how the
              proposed content of the key will be parsed and how the payload
              will be used.

              There are a number of general purpose types available, plus
              some specialist types defined by specific drivers.

       Description
              This is a printable string that is used as the search term for
              the key (in conjunction with the type) as well as a display
              name.  The description may be partially matched or exactly
              matched.

       Payload
              This 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 userspace to finish the instantiation of a key if that key
              wasn't already known to the kernel when it was requested.

              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
              Each key has an owning user ID, an owning group and a security
              label - much as files do.  They also have a set of
              permissions, though there are more than for a normal UNIX
              file, and there is an additional category beyond the usual
              user, group and other (see below).

              Note that keys are quota controlled since they represent
              unswappable kernel memory and the owning user ID 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 EKEYEXPIRED.  If not deleted, updated or replaced,
              after a set amount of time, expired keys are automatically
              removed along with all links to them and ENOKEY will be
              reported.

       Reference count
              Each key has a reference count.  Keys are referenced by
              keyrings, by current active users and by a process's
              credentials.  When the reference count reaches zero, the key
              is scheduled for garbage collection.

       See the keyctl_describe(3) manual page for more information.

KEY TYPES         top

       The facility provides several basic types of key:

       keyring
              Keys of this type are special.  The payload consists of a set
              of links to other keys, 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.

       user   This is a general purpose key type.  It may be instantiated
              with an arbitrary blob of data of up to about 32KB.  It is
              kept entirely within kernel memory.  It may be read and
              updated by userspace.

       big_key
              This is similar to user but it may hold data up to 1MB in
              size.  The data may be stored in the swap space rather than in
              kernel memory if the size exceeds the overhead of doing so (a
              tmpfs file is used - which requires filesystem structures to
              be allocated in the kernel).

       logon  This is similar to user but the contents may not be read by
              userspace.

       There are more specialised key types available also, but they're not
       discussed here as they're not intended for normal userspace use.

KEYRINGS         top

       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.

       Several of the syscall functions available may only be applied 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 driver releases its last
              reference to the key.

       Linking
              A link may be added to a keyring pointing to a key that is
              already known, provided this does not create a self-
              referential cycle.

       Unlinking
              A link may be removed from a keyring.  When the last link to a
              key is removed, that key will be scheduled for deletion by the
              garbage collector.

       Clearing
              All the links may be removed from a keyring.

       Searching
              A keyring may be considered the root of a tree or subtree in
              which keyrings form the branches and non-keyrings the leaves.
              This tree may be searched for a leaf matching a particular
              type and description.

       See the keyctl_clear(3), keyctl_link(3), keyctl_search(3) and
       keyctl_unlink(3) manual pages for more information.

ANCHORING KEYS         top

       To prevent a key from being prematurely garbage collected, it must
       anchored to keep its reference count elevated when it is not in
       active use by the kernel.

       Keyrings are used to anchor other keys - each link is a reference on
       a key - but whilst keyrings are available to link to keys, keyrings
       themselves are just keys and are also subject to the same anchoring
       necessity.

       The kernel makes available a number of anchor keyrings.  Note that
       some of these keyrings will only be created 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 does.

              There are three keyrings with different inheritance/sharing
              rules:  The session keyring (inherited and shared by all child
              processes), the process keyring (shared by all threads in a
              process) and the thread keyring (specific to a particular
              thread).

       User keyrings
              Each UID known to the kernel has a record that contains two
              keyrings: The user keyring and the user session keyring.
              These exist for as long as the UID record in the kernel
              exists.  A link to the user keyring is placed in a new session
              keyring by pam_keyinit when a new login session is initiated.

       Persistent keyrings
              There is a persistent keyring 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.  This, for
              example, permits cron scripts to use credentials left when the
              user logs out.

              Note that the expiration time is reset every time the
              persistent key is requested.

       Special keyrings
              There are special keyrings owned by the kernel that can anchor
              keys for special purposes.  An example of this is the system
              keyring used for holding encryption keys for module signature
              verification.

              These are usually closed to direct alteration by userspace.

       See the thread-keyring(7), process-keyring(7), session-keyring(7),
       user-keyring(7), user-session-keyring(7), and persistent-keyring(7)
       manual pages for more information.

POSSESSION         top

       The concept of 'possession' is important to understanding the
       keyrings security model.  Whether a thread possesses a key is
       determined by the following rules:

       (1)    Any key or keyring that does not grant Search permission to
              the caller is ignored in all the following rules.

       (2)    A thread possesses its session, process and thread keyrings
              directly because those are pointed to by its 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,
              then it also possess's 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 it is needed.

       Possession is designed to allow setuid programs run from, say, a
       user's shell to access the user's keys.  It also allows the
       prevention of access to keys just on the basis of UID and GID
       matches.

       When it creates the session keyring, the pam_keyinit module adds a
       link to the user keyring, thus making the user keyring and anything
       it contains possessed by default.

ACCESS RIGHTS         top

       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 is used to govern the following rights:

       View   If set, the attributes of a key may be read.  This includes
              the type, description and access rights (excluding the
              security label).

       Read   If set, the payload of a key may be read and a list of the
              serial numbers to which a keyring has links may be read.

       Write  If set, the payload of a key may be updated, links may be
              added to or removed from a keyring, a keyring may be cleared
              completely and a key may be revoked.

       Search If set, keyrings and subkeyrings may be searched and keys and
              keyrings may be found by that search.

       Link   If set, an additional link may be made to a key from a
              keyring.  The initial link to a key when it is created doesn't
              require this permit.

       Setattr
              If set, the ownership details on a key and its security label
              may be changed, its expiration time may be set and it may be
              revoked.

       The permissions mask contains four sets of rights.  The first three
       sets are mutually exclusive.  One and only one will be in force at
       any one time.  In order of descending priority:

       User   Used if the key's user ID matches the caller's fsuid.

       Group  Used if the user ID didn't match and the key's group ID
              matches the caller's fsgid or one of the caller's
              supplementary group list.

       Other  Used if neither the key's user ID nor group ID matched.

       The fourth set of rights is:

       Possessor
              Used if a key is determined to be possessed by the caller.

       The complete set of rights for a key is the set union of whichever of
       the first three sets is selected plus the fourth if the key is
       possessed.

       If any right is granted to a thread for a key, then that thread will
       see the key listed in /proc/keys.  If no rights at all are granted,
       then that thread can't even tell that the key exists.

       In addition to access rights, any active Linux Security Module may
       prevent access to a key if its policy so dictates.  A key may be
       given a security label or other attribute by the LSM which can be
       retrieved.

       See the keyctl_chown(3), keyctl_describe(3), keyctl_get_security(3),
       keyctl_setperm(3) and selinux(8) manual pages for more information.

SEARCHING FOR KEYS         top

       One of the key features of this facility is the ability to find a key
       that it is retaining.  The request_key() system call is the primary
       point of access for userspace to find a key to use (the kernel has
       something similar available).

       The search algorithm works as follows:

       (1)    The three process keyrings are searched in the following
              order: the thread keyring if it exists, the process keyring if
              it exists and then either the session keyring if it exists or
              the user session keyring if that exists.

       (2)    If the caller was a process that was invoked by the
              request_key() upcall mechanism then the keyrings of the
              original caller of that request_key() will be searched as
              well.

       (3)    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 valid matching key is found, then the first noted error
              state is returned or else ENOKEY is returned.

       It is also possible to search a specific keyring, in which case only
       steps (3) to (6) apply.

       See the request_key(2) and keyctl_search(3) manual pages for more
       information.

ON-DEMAND KEY CREATION         top

       If a key cannot be found, the request_key() system call will, if
       given a callout_info argument, create a new key and then upcall to
       userspace to instantiate the key.  This allows keys to be created on
       an as-needed basis.

       Typically, this will involve the kernel forking and exec'ing request-
       key program, which will then execute the appopriate handler based on
       its configuration.

       The handler is passed a special authorisation 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 the keyctl_assume_authority(3), keyctl_instantiate(3),
       keyctl_negate(3), keyctl_reject(3), request_key(2), request-key(8)
       and request-key.conf(5) manual pages for more information.

USERS         top

       The 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 userspace 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
              store the ticket needed to do secured or encrypted traffic in
              keys.  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 foreign user ID to local
              user ID mapping.

       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.

       Userspace users of this facility include:

       Kerberos key storage
              The MIT Kerberos 5 facility (libkrb5) can use keys to store
              authentication tokens which can be made to be automatically
              cleaned up a set time after the user last uses them, but until
              then permits them to hang around after the user has logged out
              so that cron scripts can use them.

SEE ALSO         top

       keyutils(7),
       pam_keyinit(8),
       thread-keyring(7),
       process-keyring(7),
       session-keyring(7),
       user-keyring(7),
       user-session-keyring(7),
       persistent-keyring(7)

COLOPHON         top

       This page is part of the keyutils (key management utilities) project.
       Information about the project can be found at [unknown -- if you
       know, please contact man-pages@man7.org] If you have a bug report for
       this manual page, send it to keyrings@linux-nfs.org.  This page was
       obtained from the project's upstream Git repository 
       ⟨http://git.kernel.org/pub/scm/linux/kernel/git/dhowells/keyutils.git⟩
       on 2016-05-10.  If you discover any rendering problems in this HTML
       version of the page, or you believe there is a better or more up-to-
       date source for the page, or you have corrections or improvements to
       the information in this COLOPHON (which is not part of the original
       manual page), send a mail to man-pages@man7.org

Linux                            21 Feb 2014                     KEYRINGS(7)