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)