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 July 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 116and 117.Fn crsetgroups_and_egid 118functions set the 119.Va cr_groups 120and 121.Va cr_ngroups 122variables and allocates space as needed. 123They also truncate the group list to the current maximum number of 124groups. 125No other mechanism should be used to modify the 126.Va cr_groups 127array. 128Note that 129.Fn crsetgroups_and_egid 130will interpret the first element of 131.Va groups 132as the new effective GID and the rest of the array as the supplementary groups, 133and 134.Va default_egid 135will be used as the new effective GID only if 136.Va groups 137is empty. 138.Pp 139The 140.Fn cru2x 141function converts a 142.Vt ucred 143structure to an 144.Vt xucred 145structure. 146That is, 147it copies data from 148.Fa cr 149to 150.Fa xcr ; 151it ignores fields in the former that are not present in the latter 152(e.g., 153.Va cr_uidinfo ) , 154and appropriately sets fields in the latter that are not present in 155the former 156(e.g., 157.Va cr_version ) . 158.Sh RETURN VALUES 159.Fn crget , 160.Fn crhold , 161.Fn crdup , 162and 163.Fn crcopysafe 164all return a pointer to a 165.Vt ucred 166structure. 167.Sh USAGE NOTES 168As of 169.Fx 5.0 , 170the 171.Vt ucred 172structure contains extensible fields. 173This means that the correct protocol must always be followed to create 174a fresh and writable credential structure: new credentials must always 175be derived from existing credentials using 176.Fn crget , 177.Fn crcopy , 178and 179.Fn crcopysafe . 180.Pp 181In the common case, credentials required for access control decisions are 182used in a read-only manner. 183In these circumstances, the thread credential 184.Va td_ucred 185should be used, as it requires no locking to access safely, and remains stable 186for the duration of the call even in the face of a multi-threaded 187application changing the process credentials from another thread. 188.Pp 189During a process credential update, the process lock must be held across 190check and update, to prevent race conditions. 191The process credential, 192.Va td->td_proc->p_ucred , 193must be used both for check and update. 194If a process credential is updated during a system call and checks against 195the thread credential are to be made later during the same system call, 196the thread credential must also be refreshed from the process credential 197so as to prevent use of a stale value. 198To avoid this scenario, it is recommended that system calls updating the 199process credential be designed to avoid other authorization functions. 200.Pp 201If temporarily elevated privileges are required for a thread, the thread 202credential can be replaced for the duration of an activity, or for 203the remainder of the system call. 204However, as a thread credential is often shared, appropriate care should be 205taken to make sure modifications are made to a writable credential 206through the use of 207.Fn crget 208and 209.Fn crcopy . 210.Pp 211Caution should be exercised when checking authorization for a thread or 212process perform an operation on another thread or process. 213As a result of temporary elevation, the target thread credential should 214.Em never 215be used as the target credential in an access control decision: the process 216credential associated with the thread, 217.Va td->td_proc->p_ucred , 218should be used instead. 219For example, 220.Xr p_candebug 9 221accepts a target process, not a target thread, for access control purposes. 222.Sh SEE ALSO 223.Xr uihold 9 224.Sh AUTHORS 225This manual page was written by 226.An Chad David Aq Mt davidc@acns.ab.ca . 227