Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help 
UCRED(9)		    Kernel Developer's Manual			UCRED(9)

NAME
     ucred,  crget, crhold, crfree, crcopy, crdup, cru2x -- functions related to
     user credentials

SYNOPSIS
     #include <sys/param.h>
     #include <sys/ucred.h>

     struct ucred *
     crget(void);

     struct ucred *
     crhold(struct ucred *cr);

     void
     crfree(struct ucred *cr);

     void
     crcopy(struct ucred *dest, struct ucred *src);

     struct ucred *
     crcopysafe(struct proc *p, struct ucred *cr);

     struct ucred *
     crdup(struct ucred *cr);

     void
     crsetgroups(struct ucred *cr, int ngrp, gid_t *groups);

     void
     crsetgroups_and_egid(struct ucred *cr, int ngrp, gid_t *groups,
	 gid_t default_egid);

     void
     cru2x(struct ucred *cr, struct xucred *xcr);

DESCRIPTION
     The ucred family of functions is used to manage user credential  structures
     (struct ucred) within the kernel.

     The  crget() function allocates memory for a new structure, sets its refer-
     ence count to 1, and initializes its lock.

     The crhold() function increases the reference count on the credential.

     The crfree() function decreases the reference count on the credential.   If
     the count drops to 0, the storage for the structure is freed.

     The  crcopy() function copies the contents of the source (template) creden-
     tial into the destination template.  The uidinfo structure within the  des-
     tination is referenced by calling uihold(9).

     The crcopysafe() function copies the current credential associated with the
     process  p  into  the newly allocated credential cr.  The process lock on p
     must be held and will be dropped and reacquired as needed to allocate group
     storage space in cr.

     The crdup() function allocates memory for a new structure	and  copies  the
     contents of cr into it.  The actual copying is performed by crcopy().

     The crsetgroups() function sets the cr_groups and cr_ngroups variables rep-
     resenting	the  supplementary  groups, allocating space as needed.  It also
     truncates the group list to the current  maximum  number  of  groups.   The
     crsetgroups_and_egid()  function  is similar, but interprets separately the
     first group of groups as the effective GID to set, only setting the  subse-
     quent  groups  as	supplementary ones.  It will use default_egid as the new
     effective GID if groups is empty.	No other mechanism  should  be	used  to
     modify the cr_groups array.

     The  cru2x()  function  converts  a ucred structure to an xucred structure.
     That is, it copies data from cr to xcr; it ignores  fields  in  the  former
     that  are	not  present in the latter (e.g., cr_uidinfo), and appropriately
     sets fields in the latter	that  are  not	present  in  the  former  (e.g.,
     cr_version).

RETURN VALUES
     crget(),  crhold(),  crdup(),  and  crcopysafe()  all return a pointer to a
     ucred structure.

USAGE NOTES
     As of FreeBSD 5.0, the ucred structure contains  extensible  fields.   This
     means  that  the correct protocol must always be followed to create a fresh
     and writable credential structure: new credentials must always  be  derived
     from existing credentials using crget(), crcopy(), and crcopysafe().

     In  the  common case, credentials required for access control decisions are
     used in a read-only manner.  In these circumstances, the thread  credential
     td_ucred  should  be  used, as it requires no locking to access safely, and
     remains stable for the duration of the call even in the face  of  a  multi-
     threaded application changing the process credentials from another thread.

     During  a	process  credential update, the process lock must be held across
     check and update, to prevent  race  conditions.   The  process  credential,
     td->td_proc->p_ucred, must be used both for check and update.  If a process
     credential  is  updated  during a system call and checks against the thread
     credential are to be made later during the same  system  call,  the  thread
     credential must also be refreshed from the process credential so as to pre-
     vent  use of a stale value.  To avoid this scenario, it is recommended that
     system calls updating the process credential be designed to avoid other au-
     thorization functions.

     If temporarily elevated privileges are required for a  thread,  the  thread
     credential  can be replaced for the duration of an activity, or for the re-
     mainder of the system call.  However,  as	a  thread  credential  is  often
     shared,  appropriate  care  should  be taken to make sure modifications are
     made to a writable credential through the use of crget() and crcopy().

     Caution should be exercised when checking authorization  for  a  thread  or
     process  perform an operation on another thread or process.  As a result of
     temporary elevation, the target thread credential should never be	used  as
     the target credential in an access control decision: the process credential
     associated  with  the thread, td->td_proc->p_ucred, should be used instead.
     For example, p_candebug(9) accepts a target process, not a  target  thread,
     for access control purposes.

SEE ALSO
     uihold(9)

AUTHORS
     This manual page was written by Chad David <davidc@acns.ab.ca>.

FreeBSD ports 15.quarterly	 August 29, 2025			UCRED(9)

Want to link to this manual page? Use this URL:
<https://man.freebsd.org/cgi/man.cgi?query=crcopy&sektion=9&manpath=FreeBSD+15.1-RELEASE+and+Ports.quarterly>

home | help