1 CREDENTIALS(9F)          Kernel Functions for Drivers          CREDENTIALS(9F)
   2 
   3 NAME
   4      credentials, CRED, crdup, crfree, crget, crhold, kcred, zone_kcred -
   5      Functions for obtaining credentials in the kernel
   6 
   7 SYNOPSIS
   8      #include <sys/cred.h>
   9 
  10      cred_t *
  11      CRED();
  12 
  13      cred_t *
  14      crdup(cred_t *cr);
  15 
  16      void
  17      crfree(cred_t *cr);
  18 
  19      cred_t *
  20      crget();
  21 
  22      void
  23      crhold(cred_t *cr);
  24 
  25      cred_t *
  26      zone_kcred();
  27 
  28      cred_t *kcred
  29 
  30 INTERFACE LEVEL
  31      Volatile - This interface is still evolving in illumos.  API and ABI
  32      stability is not guaranteed.
  33 
  34 PARAMETERS
  35      cr            pointer to the user credential structure.
  36 
  37 DESCRIPTION
  38      Some kernel interfaces require a credential as an argument.  This page
  39      documents the credentials available in the system, as well as interfaces
  40      for creating new credentials.
  41 
  42      Most users do not need to create new credentials.  Instead, users should
  43      generally use the credentials of the executing context.
  44 
  45      This interface is primarily intended for services that must perform
  46      operations on behalf of multiple remotely authenticated users, whose
  47      authentication context is unrelated to the context of the executing
  48      thread or process.  Drivers MUST NOT create new credentials.  Drivers
  49      should use the provided credential.
  50 
  51      For functions that do not return new credentials, if the credentials will
  52      be used outside of their context (i.e. if the output of zone_kcred() is
  53      referenced outside of the zone), then one should use crdup() or crhold()
  54      to ensure that the credentials remain valid.
  55 
  56    CRED()
  57      The CRED() function returns the credential of the calling thread.  Its
  58      contents depend on the calling context (user, kernel, interrupt).
  59 
  60    crdup()
  61      crdup() returns a newly-allocated copy of cr with reference count of 1.
  62      It sleeps until the allocation succeeds.
  63 
  64    crfree()
  65      crfree() releases a reference to cr.  If this is the last reference, the
  66      credential is destroyed.
  67 
  68    crhold()
  69      crhold() takes a reference to cr.
  70 
  71    kcred
  72      kcred is the root credential of the global zone.  Its UIDs and GIDs are
  73      all 0.  It has the following privilege sets by default:
  74 
  75            E: basic,proc_secflags
  76            I: basic,proc_secflags
  77            P: basic,proc_secflags
  78            L: all
  79 
  80      NET_MAC_AWARE is set in the credential's flags.  It is not marked
  81      privilege-aware.
  82 
  83      kcred will never be freed by the system.
  84 
  85    zone_kcred()
  86      The zone_kcred() function returns the root credential of the zone to
  87      which the calling thread belongs.  This cred is derived from the global
  88      kcred, minus any privileges denied to the zone.
  89 
  90    crget()
  91      The crget() function returns a copy of zone_kcred() suitable for
  92      modification by the caller.  This is useful for obtaining a default,
  93      well-initialized credential in the appropriate zone context, that is free
  94      of privileges or limitations of the originating thread.  It must be freed
  95      with crfree().  It sleeps until the allocation succeeds.
  96 
  97    Considerations
  98      kcred and zone_kcred() are not privilege-aware, and have all IDs set to
  99      0.  This causes their Limit set to be used in place of the Effective and
 100      Permitted sets, which significantly expands their privileges.
 101 
 102      If the output of crget() is not later marked as privilege aware, and its
 103      UID is not set to a non-zero value, then its Limit set will be used in
 104      place of its Effective and Permitted sets, significantly expanding its
 105      privileges.  Callers should either mark the credential as privilege-
 106      aware, reduce the Limit set appropriately, or ensure that they intend for
 107      zero-uid users to have expanded privileges.
 108 
 109      kcred, zone_kcred(), and CRED() are not suitable for modfication by the
 110      caller.  Callers must use crdup() to create a copy of these credentials
 111      that are suitable for modification.
 112 
 113      Callers of zone_kcred() and crget() must take care to ensure that the
 114      calling thread is executing in the context of the appropriate zone.  If
 115      the thread is performing work on behalf of a different zone, or if one is
 116      uncertain of the zone context of the calling thread, then one should find
 117      the appropriate zone by other means, and reference zone->zone_kcred
 118      explicitly.
 119 
 120 CONTEXT
 121      These functions can be called from user and kernel contexts.
 122 
 123 RETURN VALUES
 124      zone_kcred() and CRED() return a pointer to a cred_t that should not be
 125      modified.
 126 
 127      crget() and crdup() return a pointer to a newly allocated cred_t.
 128 
 129      zone_kcred(), CRED(), crdup(), and crget() can never fail, and always
 130      return a valid credential.
 131 
 132 SEE ALSO
 133      ddi_cred(9f)
 134 
 135 illumos                         August 21, 2020                        illumos