share/man/man9/ucred.9

   1 .\"
   2 .\" Copyright (C) 2001 Chad David <davidc@acns.ab.ca>. All rights reserved.
   3 .\"
   4 .\" Redistribution and use in source and binary forms, with or without
   5 .\" modification, are permitted provided that the following conditions
   6 .\" are met:
   7 .\" 1. Redistributions of source code must retain the above copyright
   8 .\"    notice(s), this list of conditions and the following disclaimer as
   9 .\"    the first lines of this file unmodified other than the possible
  10 .\"    addition of one or more copyright notices.
  11 .\" 2. Redistributions in binary form must reproduce the above copyright
  12 .\"    notice(s), this list of conditions and the following disclaimer in the
  13 .\"    documentation and/or other materials provided with the distribution.
  14 .\"
  15 .\" THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDER(S) ``AS IS'' AND ANY
  16 .\" EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
  17 .\" WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
  18 .\" DISCLAIMED.  IN NO EVENT SHALL THE COPYRIGHT HOLDER(S) BE LIABLE FOR ANY
  19 .\" DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
  20 .\" (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
  21 .\" SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
  22 .\" CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  23 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  24 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH
  25 .\" DAMAGE.
  26 .\"
  27 .\" $FreeBSD$
  28 .\"
  29 .Dd September 27, 2017
  30 .Dt UCRED 9
  31 .Os
  32 .Sh NAME
  33 .Nm ucred ,
  34 .Nm crget ,
  35 .Nm crhold ,
  36 .Nm crfree ,
  37 .Nm crcopy ,
  38 .Nm crdup ,
  39 .Nm cru2x ,
  40 .Nm cred_update_thread
  41 .Nd "functions related to user credentials"
  42 .Sh SYNOPSIS
  43 .In sys/param.h
  44 .In sys/ucred.h
  45 .Ft "struct ucred *"
  46 .Fn crget void
  47 .Ft "struct ucred *"
  48 .Fn crhold "struct ucred *cr"
  49 .Ft void
  50 .Fn crfree "struct ucred *cr"
  51 .Ft void
  52 .Fn crcopy "struct ucred *dest" "struct ucred *src"
  53 .Ft "struct ucred *"
  54 .Fn crcopysafe "struct proc *p" "struct ucred *cr"
  55 .Ft "struct ucred *"
  56 .Fn crdup "struct ucred *cr"
  57 .Ft void
  58 .Fn crsetgroups "struct ucred *cr" "int ngrp" "gid_t *groups"
  59 .Ft void
  60 .Fn cru2x "struct ucred *cr" "struct xucred *xcr"
  61 .Ft void
  62 .Fn cred_update_thread "struct thread *td"
  63 .Sh DESCRIPTION
  64 The
  65 .Nm
  66 family of functions is used to manage user credential structures
  67 .Pq Vt "struct ucred"
  68 within the kernel.
  69 .Pp
  70 The
  71 .Fn crget
  72 function allocates memory
  73 for a new structure, sets its reference count to 1, and
  74 initializes its lock.
  75 .Pp
  76 The
  77 .Fn crhold
  78 function increases the reference count on the credential.
  79 .Pp
  80 The
  81 .Fn crfree
  82 function decreases the reference count on the credential.
  83 If the count drops to 0, the storage for the structure is freed.
  84 .Pp
  85 The
  86 .Fn crcopy
  87 function copies the contents of the source (template)
  88 credential into the destination template.
  89 The
  90 .Vt uidinfo
  91 structure within the destination is referenced
  92 by calling
  93 .Xr uihold 9 .
  94 .Pp
  95 The
  96 .Fn crcopysafe
  97 function copies the current credential associated with the process
  98 .Fa p
  99 into the newly allocated credential
 100 .Fa cr .
 101 The process lock on
 102 .Fa p
 103 must be held and will be dropped and reacquired as needed to allocate
 104 group storage space in
 105 .Fa cr .
 106 .Pp
 107 The
 108 .Fn crdup
 109 function allocates memory for a new structure and copies the
 110 contents of
 111 .Fa cr
 112 into it.
 113 The actual copying is performed by
 114 .Fn crcopy .
 115 .Pp
 116 The
 117 .Fn crsetgroups
 118 function sets the
 119 .Va cr_groups
 120 and
 121 .Va cr_ngroups
 122 variables and allocates space as needed.
 123 It also truncates the group list to the current maximum number of
 124 groups.
 125 No other mechanism should be used to modify the
 126 .Va cr_groups
 127 array except for updating the primary group via assignment to
 128 .Va cr_groups[0] .
 129 .Pp
 130 The
 131 .Fn cru2x
 132 function converts a
 133 .Vt ucred
 134 structure to an
 135 .Vt xucred
 136 structure.
 137 That is,
 138 it copies data from
 139 .Fa cr
 140 to
 141 .Fa xcr ;
 142 it ignores fields in the former that are not present in the latter
 143 (e.g.,
 144 .Va cr_uidinfo ) ,
 145 and appropriately sets fields in the latter that are not present in
 146 the former
 147 (e.g.,
 148 .Va cr_version ) .
 149 .Pp
 150 The
 151 .Fn cred_update_thread
 152 function sets the credentials of
 153 .Fa td
 154 to that of its process, freeing its old credential if required.
 155 .Sh RETURN VALUES
 156 .Fn crget ,
 157 .Fn crhold ,
 158 .Fn crdup ,
 159 and
 160 .Fn crcopysafe
 161 all return a pointer to a
 162 .Vt ucred
 163 structure.
 164 .Sh USAGE NOTES
 165 As of
 166 .Fx 5.0 ,
 167 the
 168 .Vt ucred
 169 structure contains extensible fields.
 170 This means that the correct protocol must always be followed to create
 171 a fresh and writable credential structure: new credentials must always
 172 be derived from existing credentials using
 173 .Fn crget ,
 174 .Fn crcopy ,
 175 and
 176 .Fn crcopysafe .
 177 .Pp
 178 In the common case, credentials required for access control decisions are
 179 used in a read-only manner.
 180 In these circumstances, the thread credential
 181 .Va td_ucred
 182 should be used, as it requires no locking to access safely, and remains stable
 183 for the duration of the call even in the face of a multi-threaded
 184 application changing the process credentials from another thread.
 185 .Pp
 186 During a process credential update, the process lock must be held across
 187 check and update, to prevent race conditions.
 188 The process credential,
 189 .Va td->td_proc->p_ucred ,
 190 must be used both for check and update.
 191 If a process credential is updated during a system call and checks against
 192 the thread credential are to be made later during the same system call,
 193 the thread credential must also be refreshed from the process credential
 194 so as to prevent use of a stale value.
 195 To avoid this scenario, it is recommended that system calls updating the
 196 process credential be designed to avoid other authorization functions.
 197 .Pp
 198 If temporarily elevated privileges are required for a thread, the thread
 199 credential can by replaced for the duration of an activity, or for
 200 the remainder of the system call.
 201 However, as a thread credential is often shared, appropriate care should be
 202 taken to make sure modifications are made to a writable credential
 203 through the use of
 204 .Fn crget
 205 and
 206 .Fn crcopy .
 207 .Pp
 208 Caution should be exercised when checking authorization for a thread or
 209 process perform an operation on another thread or process.
 210 As a result of temporary elevation, the target thread credential should
 211 .Em never
 212 be used as the target credential in an access control decision: the process
 213 credential associated with the thread,
 214 .Va td->td_proc->p_ucred ,
 215 should be used instead.
 216 For example,
 217 .Xr p_candebug 9
 218 accepts a target process, not a target thread, for access control purposes.
 219 .Sh SEE ALSO
 220 .Xr uihold 9
 221 .Sh AUTHORS
 222 This manual page was written by
 223 .An Chad David Aq Mt davidc@acns.ab.ca .