Revised keyrings(7) man page for review

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

 



Hi David,

As part of the process of adopting the *.7 pages from
keyutils into man-pages, I've made some significant
extensions to the keyrings(7) page. Among the more notable 
changes:

* Expanded the detail in "Key types"
* Addition of a section on the various /proc files
* Various other minor reworkings elsewhere in the text

Would you would be willing to review the new page, please?
(The page source file is attached, in case you want to
see all the formatting.)

Cheers,

Michael


====

NAME
       keyrings - in-kernel key management and retention facility

DESCRIPTION
       The  Linux key-management facility is primarily a way for driv‐
       ers 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.

       A  library  and some user-space utilities are provided to allow
       access to the facility.  See keyctl(1),  keyctl(3),  and  keyu‐
       tils(7) for more information.

   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 call arguments.  The serial number
              is  sometimes synonymously referred as the key ID.  Pro‐
              grammatically, 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 drivers.

       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.   (Details  can  be
              found in 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.  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
              unswappable kernel memory and the owning user ID  speci‐
              fies 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 attempts to access the key will  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 facility provides several basic types of key:

       "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 "afs:mykey").

       "keyring"
              Keyrings are special keys whose payload  consists  of  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.

       "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 you do not want  to
              be readable from user space.

       "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 1MiB in size.  The data  may
              be stored in the swap space rather than in kernel memory
              if the data size exceeds the  overhead  of  storing  the
              data in swap space (a tmpfs file is used, which requires
              filesystem structures to be allocated  in  the  kernel).
              This  key  type is useful for tasks such as holding Ker‐
              beros ticket caches.

       There are  more  specialized  key  types  available  also,  but
       they're  not  discussed here as they're not intended for normal
       user-space use.

   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 imme‐
              diately deleted when the system call driver releases its
              last reference to the key.

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

       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  sub‐
              tree  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   keyctl_clear(3),  keyctl_link(3),  keyctl_search(3),  and
       keyctl_unlink(3) for more information.

   Anchoring keys
       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  refer‐
       ence  on  a  key - but whilst keyrings are available to link to
       keys, keyrings themselves are just keys and are also subject to
       the same anchoring necessity.

       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 credentials exists, which is usually as
              long as the process exists.

              There  are  three  keyrings   with   different   inheri‐
              tance/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).

       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.   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 expira‐
              tion 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 out.

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

              These special keyrings  are  usually  closed  to  direct
              alteration by user space.

       See  thread-keyring(7), process-keyring(7), session-keyring(7),
       user-keyring(7),   user-session-keyring(7),   and   persistent-
       keyring(7) for more information.

   Possession
       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 cre‐
           dentials.

       (3) If a keyring is possessed, then any key it links to is also
           possessed.

       (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 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.  It  also  allows
       the  prevention  of access to keys just 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 any‐
       thing 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:

       possessor
              The set specifies the rights granted if a key is  deter‐
              mined 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 possessed.

       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.  For  a  keyring,
              links  may  be added to or removed from the keyring, the
              keyring  may  be  cleared  completely  (all  links   are
              removed), and the key may be revoked.

       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 ini‐
              tial link to a key that is established when the  key  is
              created doesn't require 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.

       If any right is granted to a thread for a key,


       ┌─────────────────────────────────────────────────────┐
       │FIXME                                                │
       ├─────────────────────────────────────────────────────┤
       │This  seems to contradict the text below, which says │
       │that 'view' permission is what is significant.       │
       │Which is correct?                                    │
       └─────────────────────────────────────────────────────┘
       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
       (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
       which can be retrieved.

       See   keyctl_chown(3),   keyctl_describe(3),   keyctl_get_secu‐
       rity(3), keyctl_setperm(3), and selinux(8)  for  more  informa‐
       tion.

   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 three 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  ses‐
           sion-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 that request_key(2) will be searched  as
           well.

       (3) The search of the keyring tree is in preorder: 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
           terminates 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 contin‐
           ues.

       (6) If 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 call‐
       out_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 forking and exec'ing
       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_instan‐
       tiate(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 that are viewable
              by the reading process,  providing  various  information
              about each key.

              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 authorized to view.

              An  example  of the data that one might see in this file
              is the following:

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  fol‐
              lows:

              ID     The  ID  (serial number) of the key, expressed in
                     hexadecimal.

              Flags  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., has been deleted).  (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  This  is  a count of the number of kernel creden‐
                     tial structures that are pinning the key (approx‐
                     imately: the number of threads and open file ref‐
                     erences that refer to this key).

              Timeout
                     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 time‐
                     out).  The string expd means  that  the  key  has
                     already  expired,  but  has  not yet been garbage
                     collected.

              Permissions
                     The key permissions, expressed as four  hexadeci‐
                     mal  bytes  containing,  from  left to right, the
                     possessor, user, group, and other permissions.

              UID    The user ID of the key owner.

              GID    The group ID of the key.  The value -1 here means
                     that  the  key  as no group ID; this can occur in
                     certain circumstances for  keys  created  by  the
                     kernel.

              Type   The key type (user, keyring, etc.)

              Description
                     The key description (name).

              Description
                     This field contains descriptive information about
                     the key.  For most key tpes, it has the form

                          desc[: extra-info]

                     The name subfield is the  the  key's  description
                     (name).   The  optional extra-info field provides
                     some further  information  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 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 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 (authoriza‐
                     tion key; see  request_key(2)),  the  description
                     field  has  the form shown in the following exam‐
                     ple:

                         key:c9a9b19 pid:28880 ci:10

                     The three subfields are as follows:

                     key  The hexadecimal ID of the key being  instan‐
                          tiated 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 authorization 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  follow‐
              ing:

                     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 instanti‐
                     ated.

              qnkeys/maxkeys
                     The number of keys owned by  the  user,  and  the
                     maximum 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  sec‐
              onds,  after  which  revoked  and  expired  keys will be
              garbage collected.  The purpose of having such an inter‐
              val  is  so  that  there  is a window of time where user
              space can see an  error  (respectively  EKEYREVOKED  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
              persistent 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 pro‐
       cesses) 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 non‐
              root 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.

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

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

   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 upcall to user space to do DNS lookups and  then
              to cache the results.

       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  opera‐
              tions on kAFS.

       NFS - User ID mapping
              The  NFS  filesystem uses keys to store mappings of for‐
              eign 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 cryptographi‐
              cally 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 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.

SEE ALSO
       keyutils(7), persistent-keyring(7), process-keyring(7),
       session-keyring(7), thread-keyring(7), user-keyring(7),
       user-session-keyring(7), pam_keyinit(8)



Linux                         2016-11-01                   KEYRINGS(7)

-- 
Michael Kerrisk, man7.org Training and Consulting
mtk@xxxxxxxx, http://man7.org/training/
"The Linux Programming Interface" -- http://man7.org/tlpi/

Attachment: keyrings.7
Description: Unix manual page


[Index of Archives]     [Kernel Documentation]     [Netdev]     [Linux Ethernet Bridging]     [Linux Wireless]     [Kernel Newbies]     [Security]     [Linux for Hams]     [Netfilter]     [Bugtraq]     [Yosemite News]     [MIPS Linux]     [ARM Linux]     [Linux RAID]     [Linux Admin]     [Samba]

  Powered by Linux