keyrings man page on Archlinux

Printed from

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)

List of man pages available for Archlinux

Copyright (c) for man pages and the logo by the respective OS vendor.

For those who want to learn more, the polarhome community provides shell access and support.

[legal] [privacy] [GNU] [policy] [cookies] [netiquette] [sponsors] [FAQ]
Polarhome, production since 1999.
Member of Polarhome portal.
Based on Fawad Halim's script.
Vote for polarhome
Free Shell Accounts :: the biggest list on the net