Premier IT Outsourcing and Support Services within the UK

User Tools

Site Tools


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


     keyrings - in-kernel key management and retention facility


     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
     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 per-
            missions, 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 unswap-
            pable 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
     Reference count
            Each  key  has  a  reference  count.   Keys  are  referenced  by
            keyrings, by currently active users, and by a process's  creden-
            tials.  When the reference count reaches zero, the key is sched-
            uled for garbage collection.
 Key types
     The kernel provides several basic types of key:
            Keyrings are special keys which store a set of  links  to  other
            keys  (including other keyrings), analogous to a directory hold-
            ing 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
     "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 muststart 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
     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
     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.
     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.
            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 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
     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  col-
     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 cre-
            dentials 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
            As  an  alternative to using the actual keyring IDs, in calls to
            add_key(2), keyctl(2), and request_key(2), the  special  keyring
            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
            can  be  used  to  refer  to the caller's own instances of these
            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
            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.
     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  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  (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:
            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 pos-
     The set of rights that may be granted in each of the four masks  is  as
     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.
            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  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 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 appro-
     priate 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 vis-
            ible 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  autho-
            rized 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 hexadeci-
            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 unregis-
                       tered).  (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 struc-
                   tures that are pinning the key (approximately: the number
                   of threads and open file references that  refer  to  this
            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
            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 per-
                   mission 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  cir-
                   cumstances for keys created by the kernel.
            Type (8)
                   The key type (user, keyring, etc.)
            Description (9)
                   The key description (name).  This field contains descrip-
                   tive 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  informa-
                   tion  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
                       The  number  of  keys  linked  to the keyring, or the
                       string empty if there  are  no  keys  linked  to  the
                       The  payload  size  in  bytes, followed either by the
                       string [file], if the key payload exceeds the thresh-
                       old that means that the payload is stored in a (swap-
                       pable) 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 authoriza-
                        tion 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
            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.
                   The total number of keys owned by the user, and the  num-
                   ber of those keys that have been instantiated.
                   The  number  of  keys  owned by the user, and the maximum
                   number of keys that the user may own.
                   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 EKEYRE-
            VOKED 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 persis-
            tent 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
     With  respect  to keyrings, note that each link in a keyring consumes 4
     bytes of the keyring payload.
     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
     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
     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.


     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


     This page is part of release 4.16 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

Linux 2017-09-15 KEYRINGS(7)

/data/webs/external/dokuwiki/data/pages/man/keyrings.txt · Last modified: 2019/05/17 09:47 by

Was this page helpful?-12+1

Donate Powered by PHP Valid HTML5 Valid CSS Driven by DokuWiki