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