KEYRINGS(7)                  Kernel key management                 KEYRINGS(7)

       keyrings - In-kernel key management and retention facility

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

       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.

              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

              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 unswap-
              pable 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

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

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

       The facility provides several basic types of key:

              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

              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  allo-
              cated in the kernel).

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

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

       As  previously  mentioned, keyrings are a special type of key that con-
       tain links to other keys (which may include other keyrings).  Keys  may
       be linked to by multiple keyrings.  Keyrings may be considered as anal-
       ogous 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

       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

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

              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.

              All the links may be removed from a keyring.

              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.

       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 them-
       selves  are just keys and are also subject to the same anchoring neces-

       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 cre-
              dentials 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

       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 previ-
              ously  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

              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

              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.

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

       (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  con-
       tains possessed by default.

       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

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

              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

       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

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

       The fourth set of rights is:

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

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

       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 termi-
              nates 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

       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

       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.

       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

       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

       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.


Linux                             21 Feb 2014                      KEYRINGS(7)
Man Pages Copyright Respective Owners. Site Copyright (C) 1994 - 2021 Hurricane Electric. All Rights Reserved.