search..
No manual entry for -- in section 7
keyrings(7)		Miscellaneous Information Manual	    keyrings(7)

NAME
       keyrings - in-kernel key management and retention facility

DESCRIPTION
       The  Linux key-management facility is primarily a way for various kernel
       components to retain or cache security data,  authentication  keys,  en-
       cryption keys, and other data in the kernel.

       System call interfaces are provided so that user-space programs can man-
       age  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 infor-
       mation.

   Keys
       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  re-
	      ferred  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 up-
	      call 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 permis-
	      sions, 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 re-
	      placed, then, after a set amount of time, an expired key is auto-
	      matically removed (garbage collected) along with all links to it,
	      and attempts to access the key fail with the error ENOKEY.

       Reference count
	      Each key has a reference count.  Keys are referenced by keyrings,
	      by  currently active users, and by a process's credentials.  When
	      the reference count  reaches  zero,  the	key  is	 scheduled  for
	      garbage collection.

   Key types
       The kernel provides several basic types of key:

       "keyring"
	      Keyrings	are  special  keys  which store a set of links to other
	      keys (including other keyrings), 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.

	      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 ser-
	      vice to which the key is of interest (for instance "afs:mykey").

       "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 must start 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 stor-
	      ing the data in the filesystem.  (Storing the data in a  filesys-
	      tem 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 prevent-
	      ing it from being written unencrypted into swap space.

       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 imple-
       mentation.

   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.

       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.

       Linking
	      A link may be added to a keyring pointing to a key  that	is  al-
	      ready known, provided this does not create a self-referential cy-
	      cle.

       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 key matching a particular type
	      and description.

       See keyctl_clear(3), keyctl_link(3),  keyctl_search(3),	and  keyctl_un-
       link(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
       kernel.

       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-
       lected.

       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
	      thread).

	      As  an  alternative  to using the actual keyring IDs, in calls to
	      add_key(2), keyctl(2), and request_key(2),  the  special	keyring
	      values  KEY_SPEC_SESSION_KEYRING,	 KEY_SPEC_PROCESS_KEYRING,  and
	      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
	      values  KEY_SPEC_USER_KEYRING  and  KEY_SPEC_USER_SESSION_KEYRING
	      can be used to refer to  the  caller's  own  instances  of  these
	      keyrings.

	      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
	      verification.

	      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.

   Possession
       The concept of possession is important to understanding the keyrings se-
       curity 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-
	    sessed.

       (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 pre-
       vention 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:

       o  The owning user ID

       o  The ID of a group that is permitted to access the key

       o  A security label

       o  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 partic-
       ular 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:

       possessor
	      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-
       sessed.

       The set of rights that may be granted in each of the four  masks	 is  as
       follows:

       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  re-
	      moved),

       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  re-
	      quire this permission.

       setattr
	      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-keyring(7)  if  it  exists, the process-keyring(7) if it ex-
	    ists, 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  re-
	    quest_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 exe-
       cutes the request-key(8) program, which will then execute the  appropri-
       ate 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	    re-
       quest-key.conf(5) for more information.

   Users
       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  up-
	      call  to	user  space to do DNS lookups and then to cache the re-
	      sults.

       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 loaded.

       User-space users of this facility include:

       Kerberos key storage
	      The MIT Kerberos 5 facility (libkrb5) can use keys to  store  au-
	      thentication tokens which can be made to be automatically cleaned
	      up  a set time after the user last uses them, but until then per-
	      mits them to hang around after the user has logged  out  so  that
	      cron(8) scripts can use them.

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 visible in
	      this file.

	      The only keys included in the list are those that grant view per-
	      mission  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 authorized 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-
		     mal.

	      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 unreg-
			    istered).  (A key may be briefly in this state dur-
			    ing 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
		     key).

	      Timeout (4)
		     The amount of time until the key will expire, expressed in
		     human-readable form (weeks, days, hours, minutes, and sec-
		     onds).   The string perm here means that the key is perma-
		     nent (no timeout).	 The string expd means that the key has
		     already expired, but has not yet been garbage collected.

	      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
			  0x02	 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 circum-
		     stances 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 de-
		     pends on the key type, as follows:

		     "user" and "logon"
			    The size in bytes of the key payload (expressed  in
			    decimal).

		     "keyring"
			    The	 number	 of  keys linked to the keyring, or the
			    string empty if there are no  keys	linked	to  the
			    keyring.

		     "big_key"
			    The	 payload  size in bytes, followed either by the
			    string [file],  if	the  key  payload  exceeds  the
			    threshold  that means that the payload is stored in
			    a (swappable) 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 re-
			    quested  key  should  be  instantiated  (i.e.,  the
			    length  of	the  payload associated with the autho-
			    rization 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 271/20000

	      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.

	      nkeys/nikeys
		     The total number of keys owned by the user, and the number
		     of those keys that have been instantiated.

	      qnkeys/maxkeys
		     The number of keys owned by the user, and the maximum num-
		     ber of keys that the user may own.

	      qnbytes/maxbytes
		     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
	      3.17).

       With respect to keyrings, note that each link in a  keyring  consumes  4
       bytes of the keyring payload.

SEE ALSO
       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)

       linux.git/Documentation/crypto/asymmetric-keys.txt

       linux.git/Documentation/security/keys/

Linux man-pages 6.9.1		   2024-06-16			    keyrings(7)