1 .\"
   2 .\" This file and its contents are supplied under the terms of the
   3 .\" Common Development and Distribution License ("CDDL"), version 1.0.
   4 .\" You may only use this file in accordance with the terms of version
   5 .\" 1.0 of the CDDL.
   6 .\"
   7 .\" A full copy of the text of the CDDL should have accompanied this
   8 .\" source.  A copy of the CDDL is also available via the Internet at
   9 .\" http://www.illumos.org/license/CDDL.
  10 .\"
  11 .\"
  12 .\" Copyright 2020 Nexenta by DDN, Inc. All rights reserved.
  13 .\"
  14 .Dd Aug 21, 2020
  15 .Dt CREDENTIALS 9F
  16 .Os
  17 .Sh NAME
  18 .Nm credentials ,
  19 .Nm CRED ,
  20 .Nm crdup ,
  21 .Nm crfree ,
  22 .Nm crget ,
  23 .Nm crhold ,
  24 .Nm kcred ,
  25 .Nm zone_kcred
  26 .Nd Functions for obtaining credentials in the kernel
  27 .Sh SYNOPSIS
  28 .In sys/cred.h
  29 .Ft "cred_t *"
  30 .Fo CRED
  31 .Fc
  32 .Ft "cred_t *"
  33 .Fo crdup
  34 .Fa "cred_t *cr"
  35 .Fc
  36 .Ft "void"
  37 .Fo crfree
  38 .Fa "cred_t *cr"
  39 .Fc
  40 .Ft "cred_t *"
  41 .Fo crget
  42 .Fc
  43 .Ft "void"
  44 .Fo crhold
  45 .Fa "cred_t *cr"
  46 .Fc
  47 .Ft "cred_t *"
  48 .Fo zone_kcred
  49 .Fc
  50 .Vt cred_t *kcred
  51 .Sh INTERFACE LEVEL
  52 .Sy Volatile -
  53 This interface is still evolving in illumos.
  54 API and ABI stability is not guaranteed.
  55 .Sh PARAMETERS
  56 .Bl -tag -width Fa
  57 .It Fa cr
  58 pointer to the user credential structure.
  59 .El
  60 .Sh DESCRIPTION
  61 Some kernel interfaces require a credential as an argument.
  62 This page documents the credentials available in the system,
  63 as well as interfaces for creating new credentials.
  64 .Pp
  65 Most users do not need to create new credentials.
  66 Instead, users should generally use the credentials of the executing context.
  67 .Pp
  68 This interface is primarily intended for services that must perform operations
  69 on behalf of multiple remotely authenticated users, whose authentication context
  70 is unrelated to the context of the executing thread or process.
  71 Drivers MUST NOT create new credentials.
  72 Drivers should use the provided credential.
  73 .Pp
  74 For functions that do not return new credentials,
  75 if the credentials will be used outside of their context
  76 (i.e. if the output of zone_kcred() is referenced outside of the zone),
  77 then one should use
  78 .Fn crdup
  79 or
  80 .Fn crhold
  81 to ensure that the credentials remain valid.
  82 .Ss Fn CRED
  83 The
  84 .Fn CRED
  85 function returns the credential of the calling thread.
  86 Its contents depend on the calling context (user, kernel, interrupt).
  87 .Ss Fn crdup
  88 .Fn crdup
  89 returns a newly-allocated copy of
  90 .Fa cr
  91 with reference count of 1.
  92 It sleeps until the allocation succeeds.
  93 .Ss Fn crfree
  94 .Fn crfree
  95 releases a reference to
  96 .Fa cr .
  97 If this is the last reference, the credential is destroyed.
  98 .Ss Fn crhold
  99 .Fn crhold
 100 takes a reference to
 101 .Fa cr .
 102 .Ss Va kcred
 103 .Va kcred
 104 is the root credential of the global zone.
 105 Its UIDs and GIDs are all 0.
 106 It has the following privilege sets by default:
 107 .Bd -literal -offset indent
 108 E: basic,proc_secflags
 109 I: basic,proc_secflags
 110 P: basic,proc_secflags
 111 L: all
 112 .Ed
 113 .Pp
 114 .Dv NET_MAC_AWARE
 115 is set in the credential's flags.
 116 It is not marked privilege-aware.
 117 .Pp
 118 .Va kcred
 119 will never be freed by the system.
 120 .Ss Fn zone_kcred
 121 The
 122 .Fn zone_kcred
 123 function returns the root credential of the zone to which the calling thread belongs.
 124 This cred is derived from the global kcred, minus any privileges denied to the zone.
 125 .Ss Fn crget
 126 The
 127 .Fn crget
 128 function returns a copy of
 129 .Fn zone_kcred
 130 suitable for modification by the caller.
 131 This is useful for obtaining a default,
 132 well-initialized credential in the appropriate zone context,
 133 that is free of privileges or limitations of the originating thread.
 134 It must be freed with
 135 .Fn crfree .
 136 It sleeps until the allocation succeeds.
 137 .Ss Considerations
 138 .Va kcred
 139 and
 140 .Fn zone_kcred
 141 are not privilege-aware, and have all IDs set to 0.
 142 This causes their Limit set to be used in place of the Effective and Permitted sets,
 143 which significantly expands their privileges.
 144 .Pp
 145 If the output of
 146 .Fn crget
 147 is not later marked as privilege aware, and its UID is not set to a non-zero value,
 148 then its Limit set will be used in place of its Effective and Permitted sets,
 149 significantly expanding its privileges.
 150 Callers should either mark the credential as privilege-aware,
 151 reduce the Limit set appropriately,
 152 or ensure that they intend for zero-uid users to have expanded privileges.
 153 .Pp
 154 .Va kcred ,
 155 .Fn zone_kcred ,
 156 and
 157 .Fn CRED
 158 are not suitable for modfication by the caller.
 159 Callers must use
 160 .Fn crdup
 161 to create a copy of these credentials that are suitable for modification.
 162 .Pp
 163 Callers of
 164 .Fn zone_kcred
 165 and
 166 .Fn crget
 167 must take care to ensure that the calling thread is
 168 executing in the context of the appropriate zone.
 169 If the thread is performing work on behalf of a different zone,
 170 or if one is uncertain of the zone context of the calling thread,
 171 then one should find the appropriate zone by other means, and reference
 172 .Em zone->zone_kcred
 173 explicitly.
 174 .Sh CONTEXT
 175 These functions can be called from
 176 .Sy user
 177 and
 178 .Sy kernel
 179 contexts.
 180 .Sh RETURN VALUES
 181 .Fn zone_kcred
 182 and
 183 .Fn CRED
 184 return a pointer to a
 185 .Vt cred_t
 186 that should not be modified.
 187 .Pp
 188 .Fn crget
 189 and
 190 .Fn crdup
 191 return a pointer to a newly allocated
 192 .Vt cred_t .
 193 .Pp
 194 .Fn zone_kcred ,
 195 .Fn CRED ,
 196 .Fn crdup ,
 197 and
 198 .Fn crget
 199 can never fail, and always return a valid credential.
 200 .Sh SEE ALSO
 201 .Xr ddi_cred 9f