xenial (7) keyrings.7.gz

Provided by: keyutils_1.5.9-8ubuntu1_amd64 bug

NAME

       keyrings - In-kernel key management and retention facility

OVERVIEW

       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

       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

       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

       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

       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

       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

       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

       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

       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

       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

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