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


6       keyrings - in-kernel key management and retention facility


9       The Linux key-management facility is primarily a way for various kernel
10       components to retain  or  cache  security  data,  authentication  keys,
11       encryption keys, and other data in the kernel.
13       System  call  interfaces  are  provided so that user-space programs can
14       manage those objects and also use the facility for their own  purposes;
15       see add_key(2), request_key(2), and keyctl(2).
17       A library and some user-space utilities are provided to allow access to
18       the facility.  See  keyctl(1),  keyctl(3),  and  keyutils(7)  for  more
19       information.
21   Keys
22       A key has the following attributes:
24       Serial number (ID)
25              This is a unique integer handle by which a key is referred to in
26              system calls.   The  serial  number  is  sometimes  synonymously
27              referred  as  the  key ID.  Programmatically, key serial numbers
28              are represented using the type key_serial_t.
30       Type   A key's type defines what sort of data can be held in  the  key,
31              how  the proposed content of the key will be parsed, and how the
32              payload will be used.
34              There are a number of general-purpose types available, plus some
35              specialist types defined by specific kernel components.
37       Description (name)
38              The  key  description  is a printable string that is used as the
39              search term for the key (in conjunction with the  key  type)  as
40              well as a display name.  During searches, the description may be
41              partially matched or exactly matched.
43       Payload (data)
44              The payload is the actual content of a key.  This is usually set
45              when  a  key  is  created,  but it is possible for the kernel to
46              upcall to user space to finish the instantiation  of  a  key  if
47              that  key  wasn't  already  known  to  the  kernel  when  it was
48              requested.  For further details, see request_key(2).
50              A key's payload can be read and updated if the key type supports
51              it and if suitable permission is granted to the caller.
53       Access rights
54              Much  as  files  do,  each  key has an owning user ID, an owning
55              group ID, and a security label.  Each key also has a set of per‐
56              missions, though there are more than for a normal UNIX file, and
57              there is an additional category—possessor—beyond the usual user,
58              group, and other (see Possession, below).
60              Note  that keys are quota controlled, since they require unswap‐
61              pable kernel memory.  The owning user ID specifies  whose  quota
62              is to be debited.
64       Expiration time
65              Each  key  can  have  an expiration time set.  When that time is
66              reached, the key is marked as being expired and accesses  to  it
67              fail  with  the  error EKEYEXPIRED.  If not deleted, updated, or
68              replaced, then, after a set amount of time, an  expired  key  is
69              automatically  removed  (garbage collected) along with all links
70              to it, and attempts to  access  the  key  fail  with  the  error
71              ENOKEY.
73       Reference count
74              Each  key  has  a  reference  count.   Keys  are  referenced  by
75              keyrings, by currently active users, and by a process's  creden‐
76              tials.  When the reference count reaches zero, the key is sched‐
77              uled for garbage collection.
79   Key types
80       The kernel provides several basic types of key:
82       "keyring"
83              Keyrings are special keys which store a set of  links  to  other
84              keys  (including other keyrings), analogous to a directory hold‐
85              ing links to files.  The main purpose of a keyring is to prevent
86              other  keys  from being garbage collected because nothing refers
87              to them.
89              Keyrings with descriptions (names)  that  begin  with  a  period
90              ('.') are reserved to the implementation.
92       "user" This  is  a  general-purpose key type.  The key is kept entirely
93              within kernel memory.  The payload may be read  and  updated  by
94              user-space applications.
96              The payload for keys of this type is a blob of arbitrary data of
97              up to 32,767 bytes.
99              The description may be any valid string, though it is  preferred
100              that  it  start  with  a colon-delimited prefix representing the
101              service  to  which  the  key  is  of  interest   (for   instance
102              "afs:mykey").
104       "logon" (since Linux 3.3)
105              This key type is essentially the same as "user", but it does not
106              provide reading (i.e.,  the  keyctl(2)  KEYCTL_READ  operation),
107              meaning  that  the key payload is never visible from user space.
108              This is suitable for storing username-password pairs that should
109              not be readable from user space.
111              The  description  of  a  "logon"  key muststart with a non-empty
112              colon-delimited prefix whose purpose is to identify the  service
113              to  which the key belongs.  (Note that this differs from keys of
114              the "user" type, where the inclusion of a prefix is  recommended
115              but is not enforced.)
117       "big_key" (since Linux 3.13)
118              This key type is similar to the "user" key type, but it may hold
119              a payload of up to 1 MiB in size.  This key type is  useful  for
120              purposes such as holding Kerberos ticket caches.
122              The  payload  data  may  be stored in a tmpfs filesystem, rather
123              than in kernel memory, if the data size exceeds the overhead  of
124              storing  the  data  in  the  filesystem.  (Storing the data in a
125              filesystem requires filesystem structures to be allocated in the
126              kernel.   The  size  of  these  structures  determines  the size
127              threshold above which the tmpfs storage method is used.)   Since
128              Linux  4.8,  the payload data is encrypted when stored in tmpfs,
129              thereby preventing it from being written unencrypted  into  swap
130              space.
132       There  are  more  specialized key types available also, but they aren't
133       discussed here because they aren't intended for normal user-space use.
135       Key type names that begin with a  period  ('.')  are  reserved  to  the
136       implementation.
138   Keyrings
139       As  previously  mentioned, keyrings are a special type of key that con‐
140       tain links to other keys (which may include other keyrings).  Keys  may
141       be linked to by multiple keyrings.  Keyrings may be considered as anal‐
142       ogous to UNIX directories where each directory contains a set  of  hard
143       links to files.
145       Various operations (system calls) may be applied only to keyrings:
147       Adding A  key  may  be  added  to a keyring by system calls that create
148              keys.  This prevents the new key from being immediately  deleted
149              when the system call releases its last reference to the key.
151       Linking
152              A  link  may  be  added  to  a keyring pointing to a key that is
153              already known, provided this does not create a  self-referential
154              cycle.
156       Unlinking
157              A  link  may be removed from a keyring.  When the last link to a
158              key is removed, that key will be scheduled for deletion  by  the
159              garbage collector.
161       Clearing
162              All the links may be removed from a keyring.
164       Searching
165              A  keyring  may  be  considered the root of a tree or subtree in
166              which keyrings form the branches and  non-keyrings  the  leaves.
167              This  tree  may be searched for a key matching a particular type
168              and description.
170       See    keyctl_clear(3),    keyctl_link(3),    keyctl_search(3),     and
171       keyctl_unlink(3) for more information.
173   Anchoring keys
174       To prevent a key from being garbage collected, it must anchored to keep
175       its reference count elevated when it is not in active use by  the  ker‐
176       nel.
178       Keyrings  are  used to anchor other keys: each link is a reference on a
179       key.  Note that keyrings themselves are just keys and are also  subject
180       to  the  same  anchoring requirement to prevent them being garbage col‐
181       lected.
183       The kernel makes available a number of anchor keyrings.  Note that some
184       of these keyrings will be created only when first accessed.
186       Process keyrings
187              Process  credentials themselves reference keyrings with specific
188              semantics.  These keyrings are pinned as long as the set of cre‐
189              dentials exists, which is usually as long as the process exists.
191              There  are  three  keyrings  with  different inheritance/sharing
192              rules: the session-keyring(7) (inherited and shared by all child
193              processes),  the  process-keyring(7) (shared by all threads in a
194              process) and the thread-keyring(7)  (specific  to  a  particular
195              thread).
197              As  an  alternative to using the actual keyring IDs, in calls to
198              add_key(2), keyctl(2), and request_key(2), the  special  keyring
200              KEY_SPEC_THREAD_KEYRING can be used to refer to the caller's own
201              instances of these keyrings.
203       User keyrings
204              Each  UID  known  to  the  kernel has a record that contains two
205              keyrings: the user-keyring(7) and  the  user-session-keyring(7).
206              These exist for as long as the UID record in the kernel exists.
208              As  an  alternative to using the actual keyring IDs, in calls to
209              add_key(2), keyctl(2), and request_key(2), the  special  keyring
211              can be used to refer to the  caller's  own  instances  of  these
212              keyrings.
214              A link to the user keyring is placed in a new session keyring by
215              pam_keyinit(8) when a new login session is initiated.
217       Persistent keyrings
218              There is a persistent-keyring(7) available to each UID known  to
219              the  system.   It  may persist beyond the life of the UID record
220              previously mentioned, but has an expiration time set  such  that
221              it is automatically cleaned up after a set time.  The persistent
222              keyring permits, for example, cron(8) scripts to use credentials
223              that are left in the persistent keyring after the user logs out.
225              Note that the expiration time of the persistent keyring is reset
226              every time the persistent key is requested.
228       Special keyrings
229              There are special keyrings owned by the kernel that  can  anchor
230              keys  for  special  purposes.   An example of this is the system
231              keyring used for holding encryption keys  for  module  signature
232              verification.
234              These  special keyrings  are usually closed to direct alteration
235              by user space.
237       An originally planned "group keyring", for storing keys associated with
238       each GID known to the kernel, is not so far implemented, is unlikely to
239       be implemented.  Nevertheless, the constant KEY_SPEC_GROUP_KEYRING  has
240       been defined for this keyring.
242   Possession
243       The  concept  of  possession is important to understanding the keyrings
244       security model.  Whether a thread possesses a key is determined by  the
245       following rules:
247       (1) Any  key  or  keyring  that does not grant search permission to the
248           caller is ignored in all the following rules.
250       (2) A thread possesses its session-keyring(7), process-keyring(7),  and
251           thread-keyring(7)  directly  because those keyrings are referred to
252           by its credentials.
254       (3) If a keyring is possessed, then any key it links to  is  also  pos‐
255           sessed.
257       (4) If  any  key  a keyring links to is itself a keyring, then rule (3)
258           applies recursively.
260       (5) If a process is upcalled from the kernel to instantiate a key  (see
261           request_key(2)), then it also possesses the requester's keyrings as
262           in rule (1) as if it were the requester.
264       Note that possession is not a fundamental property of a key,  but  must
265       rather be calculated each time the key is needed.
267       Possession  is  designed  to allow set-user-ID programs run from, say a
268       user's shell to access the user's keys.  Granting  permissions  to  the
269       key  possessor while denying them to the key owner and group allows the
270       prevention of access to keys on the basis of UID and GID matches.
272       When it creates the session keyring, pam_keyinit(8) adds a link to  the
273       user-keyring(7),  thus making the user keyring and anything it contains
274       possessed by default.
276   Access rights
277       Each key has the following security-related attributes:
279       *  The owning user ID
281       *  The ID of a group that is permitted to access the key
283       *  A security label
285       *  A permissions mask
287       The permissions mask contains four sets of  rights.   The  first  three
288       sets  are  mutually exclusive.  One and only one will be in force for a
289       particular access check.  In order of descending priority, these  three
290       sets are:
292       user   The  set  specifies  the  rights  granted  if  the key's user ID
293              matches the caller's filesystem user ID.
295       group  The set specifies the rights granted if the user ID didn't match
296              and  the  key's  group ID matches the caller's filesystem GID or
297              one of the caller's supplementary group IDs.
299       other  The set specifies the rights granted if neither the  key's  user
300              ID nor group ID matched.
302       The fourth set of rights is:
304       possessor
305              The  set  specifies the rights granted if a key is determined to
306              be possessed by the caller.
308       The complete set of rights for a key is the union of whichever  of  the
309       first  three  sets is applicable plus the fourth set if the key is pos‐
310       sessed.
312       The set of rights that may be granted in each of the four masks  is  as
313       follows:
315       view   The  attributes of the key may be read.  This includes the type,
316              description, and access rights (excluding the security label).
318       read   For a key: the payload of the key may be read.  For  a  keyring:
319              the list of serial numbers (keys) to which the keyring has links
320              may be read.
322       write  The payload of the key  may  be  updated  and  the  key  may  be
323              revoked.   For  a keyring, links may be added to or removed from
324              the keyring, and the keyring  may  be  cleared  completely  (all
325              links are removed),
327       search For a key (or a keyring): the key may be found by a search.  For
328              a keyring: keys and keyrings that are linked to by  the  keyring
329              may be searched.
331       link   Links may be created from keyrings to the key.  The initial link
332              to a key that is established when the  key  is  created  doesn't
333              require this permission.
335       setattr
336              The  ownership  details  and  security  label  of the key may be
337              changed, the key's expiration time may be set, and the  key  may
338              be revoked.
340       In  addition  to  access rights, any active Linux Security Module (LSM)
341       may prevent access to a key if its policy so dictates.  A  key  may  be
342       given  a  security  label  or other attribute by the LSM; this label is
343       retrievable via keyctl_get_security(3).
345       See   keyctl_chown(3),   keyctl_describe(3),    keyctl_get_security(3),
346       keyctl_setperm(3), and selinux(8) for more information.
348   Searching for keys
349       One  of  the  key  features of the Linux key-management facility is the
350       ability to find a key that a process is retaining.  The  request_key(2)
351       system  call is the primary point of access for user-space applications
352       to find a key.  (Internally, the kernel has something similar available
353       for use by internal components that make use of keys.)
355       The search algorithm works as follows:
357       (1) The  process  keyrings  are  searched  in  the following order: the
358           thread thread-keyring(7) if it exists, the process-keyring(7) if it
359           exists,  and then either the session-keyring(7) if it exists or the
360           user-session-keyring(7) if that exists.
362       (2) If the caller was a process that was invoked by the  request_key(2)
363           upcall  mechanism,  then  the  keyrings  of  the original caller of
364           request_key(2) will be searched as well.
366       (3) The search of a  keyring  tree  is  in  breadth-first  order:  each
367           keyring  is  searched first for a match, then the keyrings referred
368           to by that keyring are searched.
370       (4) If a matching key is found that is valid, then  the  search  termi‐
371           nates and that key is returned.
373       (5) If  a  matching key is found that has an error state attached, that
374           error state is noted and the search continues.
376       (6) If no valid matching key is found, then the first noted error state
377           is returned; otherwise, an ENOKEY error is returned.
379       It  is  also  possible to search a specific keyring, in which case only
380       steps (3) to (6) apply.
382       See request_key(2) and keyctl_search(3) for more information.
384   On-demand key creation
385       If a key cannot be found, request_key(2) will, if given a  callout_info
386       argument, create a new key and then upcall to user space to instantiate
387       the key.  This allows keys to be created on an as-needed basis.
389       Typically, this will involve the kernel creating  a  new  process  that
390       executes the request-key(8) program, which will then execute the appro‐
391       priate handler based on its configuration.
393       The handler is passed a special authorization key that  allows  it  and
394       only  it  to  instantiate  the  new  key.   This is also used to permit
395       searches  performed  by  the  handler  program  to  also   search   the
396       requester's keyrings.
398       See  request_key(2), keyctl_assume_authority(3), keyctl_instantiate(3),
399       keyctl_negate(3),  keyctl_reject(3),   request-key(8),   and   request-
400       key.conf(5) for more information.
402   /proc files
403       The  kernel  provides various /proc files that expose information about
404       keys or define limits on key usage.
406       /proc/keys (since Linux 2.6.10)
407              This file exposes a list of  the  keys  for  which  the  reading
408              thread  has view permission, providing various information about
409              each key.  The thread need not possess the key for it to be vis‐
410              ible in this file.
412              The  only  keys  included  in the list are those that grant view
413              permission to the reading process (regardless of whether or  not
414              it  possesses  them).   LSM security checks are still performed,
415              and may filter out further keys that the process is  not  autho‐
416              rized to view.
418              An example of the data that one might see in this file (with the
419              columns numbered for easy reference below) is the following:
421  (1)     (2)     (3)(4)    (5)     (6)   (7)   (8)        (9)
422009a2028 I--Q---   1 perm 3f010000  1000  1000 user     krb_ccache:primary: 12
4231806c4ba I--Q---   1 perm 3f010000  1000  1000 keyring  _pid: 2
42425d3a08f I--Q---   1 perm 1f3f0000  1000 65534 keyring  _uid_ses.1000: 1
42528576bd8 I--Q---   3 perm 3f010000  1000  1000 keyring  _krb: 1
4262c546d21 I--Q--- 190 perm 3f030000  1000  1000 keyring  _ses: 2
42730a4e0be I------   4   2d 1f030000  1000 65534 keyring  _persistent.1000: 1
42832100fab I--Q---   4 perm 1f3f0000  1000 65534 keyring  _uid.1000: 2
42932a387ea I--Q---   1 perm 3f010000  1000  1000 keyring  _pid: 2
4303ce56aea I--Q---   5 perm 3f030000  1000  1000 keyring  _ses: 1
432              The fields shown in each line of this file are as follows:
434              ID (1) The ID (serial number) of the key, expressed in hexadeci‐
435                     mal.
437              Flags (2)
438                     A set of flags describing the state of the key:
440                     I   The key has been instantiated.
442                     R   The key has been revoked.
444                     D   The key is dead (i.e., the key type has been unregis‐
445                         tered).  (A key may be briefly in this  state  during
446                         garbage collection.)
448                     Q   The key contributes to the user's quota.
450                     U   The  key is under construction via a callback to user
451                         space; see request-key(2).
453                     N   The key is negatively instantiated.
455                     i   The key has been invalidated.
457              Usage (3)
458                     This is a count of the number of kernel credential struc‐
459                     tures that are pinning the key (approximately: the number
460                     of threads and open file references that  refer  to  this
461                     key).
463              Timeout (4)
464                     The  amount  of time until the key will expire, expressed
465                     in human-readable form (weeks, days, hours, minutes,  and
466                     seconds).   The  string  perm  here means that the key is
467                     permanent (no timeout).  The string expd means  that  the
468                     key  has  already  expired,  but has not yet been garbage
469                     collected.
471              Permissions (5)
472                     The key permissions, expressed as four hexadecimal  bytes
473                     containing,  from  left  to  right,  the possessor, user,
474                     group, and other permissions.  Within each byte, the per‐
475                     mission bits are as follows:
477                          0x01   view
478                          Ox02   read
479                          0x04   write
480                          0x08   search
481                          0x10   link
482                          0x20   setattr
484              UID (6)
485                     The user ID of the key owner.
487              GID (7)
488                     The  group  ID  of the key.  The value -1 here means that
489                     the key has no group ID; this can occur in  certain  cir‐
490                     cumstances for keys created by the kernel.
492              Type (8)
493                     The key type (user, keyring, etc.)
495              Description (9)
496                     The key description (name).  This field contains descrip‐
497                     tive information about the key.  For most key  types,  it
498                     has the form
500                          name[: extra-info]
502                     The  name  subfield is the key's description (name).  The
503                     optional extra-info field provides some further  informa‐
504                     tion  about  the  key.  The information that appears here
505                     depends on the key type, as follows:
507                     "user" and "logon"
508                         The size in bytes of the key  payload  (expressed  in
509                         decimal).
511                     "keyring"
512                         The  number  of  keys  linked  to the keyring, or the
513                         string empty if there  are  no  keys  linked  to  the
514                         keyring.
516                     "big_key"
517                         The  payload  size  in  bytes, followed either by the
518                         string [file], if the key payload exceeds the thresh‐
519                         old that means that the payload is stored in a (swap‐
520                         pable) tmpfs(5) filesystem, or otherwise  the  string
521                         [buff],  indicating  that  the key is small enough to
522                         reside in kernel memory.
524                     For the ".request_key_auth" key type (authorization  key;
525                     see  request_key(2)),  the description field has the form
526                     shown in the following example:
528                         key:c9a9b19 pid:28880 ci:10
530                     The three subfields are as follows:
532                     key  The hexadecimal ID of the key being instantiated  in
533                          the requesting program.
535                     pid  The PID of the requesting program.
537                     ci   The  length  of  the  callout  data  with  which the
538                          requested key  should  be  instantiated  (i.e.,  the
539                          length of the payload associated with the authoriza‐
540                          tion key).
542       /proc/key-users (since Linux 2.6.10)
543              This file lists various information for each user ID that has at
544              least  one  key  on the system.  An example of the data that one
545              might see in this file is the following:
547                     0:    10 9/9 2/1000000 22/25000000
548                    42:     9 9/9 8/200 106/20000
549                  1000:    11 11/11 10/200 271/20000
551              The fields shown in each line are as follows:
553              uid    The user ID.
555              usage  This is a kernel-internal  usage  count  for  the  kernel
556                     structure used to record key users.
558              nkeys/nikeys
559                     The  total number of keys owned by the user, and the num‐
560                     ber of those keys that have been instantiated.
562              qnkeys/maxkeys
563                     The number of keys owned by the  user,  and  the  maximum
564                     number of keys that the user may own.
566              qnbytes/maxbytes
567                     The  number  of  bytes  consumed  in payloads of the keys
568                     owned by this user, and the upper limit on the number  of
569                     bytes in key payloads for that user.
571       /proc/sys/kernel/keys/gc_delay (since Linux 2.6.32)
572              The value in this file specifies the interval, in seconds, after
573              which revoked and expired keys will be garbage  collected.   The
574              purpose  of having such an interval is so that there is a window
575              of time where user space can see an error (respectively  EKEYRE‐
576              VOKED and EKEYEXPIRED) that indicates what happened to the key.
578              The default value in this file is 300 (i.e., 5 minutes).
580       /proc/sys/kernel/keys/persistent_keyring_expiry (since Linux 3.13)
581              This  file defines an interval, in seconds, to which the persis‐
582              tent keyring's expiration timer is reset each time  the  keyring
583              is  accessed  (via  keyctl_get_persistent(3)  or  the  keyctl(2)
584              KEYCTL_GET_PERSISTENT operation.)
586              The default value in this file is 259200 (i.e., 3 days).
588       The following files (which are writable by  privileged  processes)  are
589       used  to  enforce  quotas  on the number of keys and number of bytes of
590       data that can be stored in key payloads:
592       /proc/sys/kernel/keys/maxbytes (since Linux 2.6.26)
593              This is the maximum number of bytes of data that a nonroot  user
594              can hold in the payloads of the keys owned by the user.
596              The default value in this file is 20,000.
598       /proc/sys/kernel/keys/maxkeys (since Linux 2.6.26)
599              This is the maximum number of keys that a nonroot user may own.
601              The default value in this file is 200.
603       /proc/sys/kernel/keys/root_maxbytes (since Linux 2.6.26)
604              This  is  the maximum number of bytes of data that the root user
605              (UID 0 in the root user namespace) can hold in the  payloads  of
606              the keys owned by root.
608              The  default  value  in  this  file is 25,000,000 (20,000 before
609              Linux 3.17).
611       /proc/sys/kernel/keys/root_maxkeys (since Linux 2.6.26)
612              This is the maximum number of keys that the root user (UID 0  in
613              the root user namespace) may own.
615              The  default  value  in this file is 1,000,000 (200 before Linux
616              3.17).
618       With respect to keyrings, note that each link in a keyring  consumes  4
619       bytes of the keyring payload.
621   Users
622       The Linux key-management facility has a number of users and usages, but
623       is not limited to those that already exist.
625       In-kernel users of this facility include:
627       Network filesystems - DNS
628              The kernel uses the upcall mechanism provided  by  the  keys  to
629              upcall  to  user  space  to do DNS lookups and then to cache the
630              results.
632       AF_RXRPC and kAFS - Authentication
633              The AF_RXRPC network protocol and the in-kernel  AFS  filesystem
634              use  keys  to store the ticket needed to do secured or encrypted
635              traffic.  These are then looked  up  by  network  operations  on
636              AF_RXRPC and filesystem operations on kAFS.
638       NFS - User ID mapping
639              The  NFS  filesystem uses keys to store mappings of foreign user
640              IDs to local user IDs.
642       CIFS - Password
643              The CIFS filesystem uses keys to store passwords  for  accessing
644              remote shares.
646       Module verification
647              The  kernel  build process can be made to cryptographically sign
648              modules.  That signature  is  then  checked  when  a  module  is
649              loaded.
651       User-space users of this facility include:
653       Kerberos key storage
654              The  MIT  Kerberos  5  facility  (libkrb5) can use keys to store
655              authentication tokens which can  be  made  to  be  automatically
656              cleaned  up  a set time after the user last uses them, but until
657              then permits them to hang around after the user has  logged  out
658              so that cron(8) scripts can use them.


661       keyctl(1), add_key(2), keyctl(2), request_key(2), keyctl(3),
662       keyutils(7), persistent-keyring(7), process-keyring(7),
663       session-keyring(7), thread-keyring(7), user-keyring(7),
664       user-session-keyring(7), pam_keyinit(8), request-key(8)
666       The kernel source files Documentation/crypto/asymmetric-keys.txt and
667       under Documentation/security/keys (or, before Linux 4.13, in the file
668       Documentation/security/keys.txt).


671       This page is part of release 4.15 of the Linux man-pages project.  A
672       description of the project, information about reporting bugs, and the
673       latest version of this page, can be found at
674       https://www.kernel.org/doc/man-pages/.
678Linux                             2017-09-15                       KEYRINGS(7)