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.Dd August 29, 2025 28.Dt UCRED 9 29.Os 30.Sh NAME 31.Nm ucred , 32.Nm crget , 33.Nm crhold , 34.Nm crfree , 35.Nm crcopy , 36.Nm crdup , 37.Nm cru2x 38.Nd "functions related to user credentials" 39.Sh SYNOPSIS 40.In sys/param.h 41.In sys/ucred.h 42.Ft "struct ucred *" 43.Fn crget void 44.Ft "struct ucred *" 45.Fn crhold "struct ucred *cr" 46.Ft void 47.Fn crfree "struct ucred *cr" 48.Ft void 49.Fn crcopy "struct ucred *dest" "struct ucred *src" 50.Ft "struct ucred *" 51.Fn crcopysafe "struct proc *p" "struct ucred *cr" 52.Ft "struct ucred *" 53.Fn crdup "struct ucred *cr" 54.Ft void 55.Fn crsetgroups "struct ucred *cr" "int ngrp" "gid_t *groups" 56.Ft void 57.Fn crsetgroups_and_egid "struct ucred *cr" "int ngrp" "gid_t *groups" \ 58 "gid_t default_egid" 59.Ft void 60.Fn cru2x "struct ucred *cr" "struct xucred *xcr" 61.Sh DESCRIPTION 62The 63.Nm 64family of functions is used to manage user credential structures 65.Pq Vt "struct ucred" 66within the kernel. 67.Pp 68The 69.Fn crget 70function allocates memory 71for a new structure, sets its reference count to 1, and 72initializes its lock. 73.Pp 74The 75.Fn crhold 76function increases the reference count on the credential. 77.Pp 78The 79.Fn crfree 80function decreases the reference count on the credential. 81If the count drops to 0, the storage for the structure is freed. 82.Pp 83The 84.Fn crcopy 85function copies the contents of the source (template) 86credential into the destination template. 87The 88.Vt uidinfo 89structure within the destination is referenced 90by calling 91.Xr uihold 9 . 92.Pp 93The 94.Fn crcopysafe 95function copies the current credential associated with the process 96.Fa p 97into the newly allocated credential 98.Fa cr . 99The process lock on 100.Fa p 101must be held and will be dropped and reacquired as needed to allocate 102group storage space in 103.Fa cr . 104.Pp 105The 106.Fn crdup 107function allocates memory for a new structure and copies the 108contents of 109.Fa cr 110into it. 111The actual copying is performed by 112.Fn crcopy . 113.Pp 114The 115.Fn crsetgroups 116function sets the 117.Va cr_groups 118and 119.Va cr_ngroups 120variables representing the supplementary groups, allocating space as needed. 121It also truncates the group list to the current maximum number of groups. 122The 123.Fn crsetgroups_and_egid 124function is similar, but interprets separately the first group of 125.Va groups 126as the effective GID to set, only setting the subsequent groups as supplementary 127ones. 128It will use 129.Va default_egid 130as the new effective GID if 131.Va groups 132is empty. 133No other mechanism should be used to modify the 134.Va cr_groups 135array. 136.Pp 137The 138.Fn cru2x 139function converts a 140.Vt ucred 141structure to an 142.Vt xucred 143structure. 144That is, 145it copies data from 146.Fa cr 147to 148.Fa xcr ; 149it ignores fields in the former that are not present in the latter 150(e.g., 151.Va cr_uidinfo ) , 152and appropriately sets fields in the latter that are not present in 153the former 154(e.g., 155.Va cr_version ) . 156.Sh RETURN VALUES 157.Fn crget , 158.Fn crhold , 159.Fn crdup , 160and 161.Fn crcopysafe 162all return a pointer to a 163.Vt ucred 164structure. 165.Sh USAGE NOTES 166As of 167.Fx 5.0 , 168the 169.Vt ucred 170structure contains extensible fields. 171This means that the correct protocol must always be followed to create 172a fresh and writable credential structure: new credentials must always 173be derived from existing credentials using 174.Fn crget , 175.Fn crcopy , 176and 177.Fn crcopysafe . 178.Pp 179In the common case, credentials required for access control decisions are 180used in a read-only manner. 181In these circumstances, the thread credential 182.Va td_ucred 183should be used, as it requires no locking to access safely, and remains stable 184for the duration of the call even in the face of a multi-threaded 185application changing the process credentials from another thread. 186.Pp 187During a process credential update, the process lock must be held across 188check and update, to prevent race conditions. 189The process credential, 190.Va td->td_proc->p_ucred , 191must be used both for check and update. 192If a process credential is updated during a system call and checks against 193the thread credential are to be made later during the same system call, 194the thread credential must also be refreshed from the process credential 195so as to prevent use of a stale value. 196To avoid this scenario, it is recommended that system calls updating the 197process credential be designed to avoid other authorization functions. 198.Pp 199If temporarily elevated privileges are required for a thread, the thread 200credential can be replaced for the duration of an activity, or for 201the remainder of the system call. 202However, as a thread credential is often shared, appropriate care should be 203taken to make sure modifications are made to a writable credential 204through the use of 205.Fn crget 206and 207.Fn crcopy . 208.Pp 209Caution should be exercised when checking authorization for a thread or 210process perform an operation on another thread or process. 211As a result of temporary elevation, the target thread credential should 212.Em never 213be used as the target credential in an access control decision: the process 214credential associated with the thread, 215.Va td->td_proc->p_ucred , 216should be used instead. 217For example, 218.Xr p_candebug 9 219accepts a target process, not a target thread, for access control purposes. 220.Sh SEE ALSO 221.Xr uihold 9 222.Sh AUTHORS 223This manual page was written by 224.An Chad David Aq Mt davidc@acns.ab.ca . 225