/share/man/man9/ucred.9
https://bitbucket.org/freebsd/freebsd-head/ · Unknown · 236 lines · 236 code · 0 blank · 0 comment · 0 complexity · 83f8552efbe26d6756d2334dc52dc1c1 MD5 · raw file
- .\"
- .\" Copyright (C) 2001 Chad David <davidc@acns.ab.ca>. All rights reserved.
- .\"
- .\" Redistribution and use in source and binary forms, with or without
- .\" modification, are permitted provided that the following conditions
- .\" are met:
- .\" 1. Redistributions of source code must retain the above copyright
- .\" notice(s), this list of conditions and the following disclaimer as
- .\" the first lines of this file unmodified other than the possible
- .\" addition of one or more copyright notices.
- .\" 2. Redistributions in binary form must reproduce the above copyright
- .\" notice(s), this list of conditions and the following disclaimer in the
- .\" documentation and/or other materials provided with the distribution.
- .\"
- .\" THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDER(S) ``AS IS'' AND ANY
- .\" EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
- .\" WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
- .\" DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER(S) BE LIABLE FOR ANY
- .\" DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
- .\" (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
- .\" SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
- .\" CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
- .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
- .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH
- .\" DAMAGE.
- .\"
- .\" $FreeBSD$
- .\"
- .Dd June 19, 2009
- .Dt UCRED 9
- .Os
- .Sh NAME
- .Nm ucred ,
- .Nm crget ,
- .Nm crhold ,
- .Nm crfree ,
- .Nm crshared ,
- .Nm crcopy ,
- .Nm crdup ,
- .Nm cru2x ,
- .Nm cred_update_thread
- .Nd "functions related to user credentials"
- .Sh SYNOPSIS
- .In sys/param.h
- .In sys/ucred.h
- .Ft "struct ucred *"
- .Fn crget void
- .Ft "struct ucred *"
- .Fn crhold "struct ucred *cr"
- .Ft void
- .Fn crfree "struct ucred *cr"
- .Ft int
- .Fn crshared "struct ucred *cr"
- .Ft void
- .Fn crcopy "struct ucred *dest" "struct ucred *src"
- .Ft "struct ucred *"
- .Fn crcopysafe "struct proc *p" "struct ucred *cr"
- .Ft "struct ucred *"
- .Fn crdup "struct ucred *cr"
- .Ft void
- .Fn crsetgroups "struct ucred *cr" "int ngrp" "gid_t *groups"
- .Ft void
- .Fn cru2x "struct ucred *cr" "struct xucred *xcr"
- .Ft void
- .Fn cred_update_thread "struct thread *td"
- .Sh DESCRIPTION
- The
- .Nm
- family of functions is used to manage user credential structures
- .Pq Vt "struct ucred"
- within the kernel.
- .Pp
- The
- .Fn crget
- function allocates memory
- for a new structure, sets its reference count to 1, and
- initializes its lock.
- .Pp
- The
- .Fn crhold
- function increases the reference count on the credential.
- .Pp
- The
- .Fn crfree
- function decreases the reference count on the credential.
- If the count drops to 0, the storage for the structure is freed.
- .Pp
- The
- .Fn crshared
- function returns true if the credential is shared.
- A credential is considered to be shared if its reference
- count is greater than one.
- .Pp
- The
- .Fn crcopy
- function copies the contents of the source (template)
- credential into the destination template.
- The
- .Vt uidinfo
- structure within the destination is referenced
- by calling
- .Xr uihold 9 .
- .Pp
- The
- .Fn crcopysafe
- function copies the current credential associated with the process
- .Fa p
- into the newly allocated credential
- .Fa cr .
- The process lock on
- .Fa p
- must be held and will be dropped and reacquired as needed to allocate
- group storage space in
- .Fa cr .
- .Pp
- The
- .Fn crdup
- function allocates memory for a new structure and copies the
- contents of
- .Fa cr
- into it.
- The actual copying is performed by
- .Fn crcopy .
- .Pp
- The
- .Fn crsetgroups
- function sets the
- .Va cr_groups
- and
- .Va cr_ngroups
- variables and allocates space as needed.
- It also truncates the group list to the current maximum number of
- groups.
- No other mechanism should be used to modify the
- .Va cr_groups
- array except for updating the primary group via assignment to
- .Va cr_groups[0] .
- .Pp
- The
- .Fn cru2x
- function converts a
- .Vt ucred
- structure to an
- .Vt xucred
- structure.
- That is,
- it copies data from
- .Fa cr
- to
- .Fa xcr ;
- it ignores fields in the former that are not present in the latter
- (e.g.,
- .Va cr_uidinfo ) ,
- and appropriately sets fields in the latter that are not present in
- the former
- (e.g.,
- .Va cr_version ) .
- .Pp
- The
- .Fn cred_update_thread
- function sets the credentials of
- .Fa td
- to that of its process, freeing its old credential if required.
- .Sh RETURN VALUES
- .Fn crget ,
- .Fn crhold ,
- .Fn crdup ,
- and
- .Fn crcopysafe
- all return a pointer to a
- .Vt ucred
- structure.
- .Pp
- .Fn crshared
- returns 0 if the credential has a reference count greater than 1;
- otherwise, 1 is returned.
- .Sh USAGE NOTES
- As of
- .Fx 5.0 ,
- the
- .Vt 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
- .Fn crget ,
- .Fn crcopy ,
- and
- .Fn crcopysafe .
- .Pp
- In the common case, credentials required for access control decisions are
- used in a read-only manner.
- In these circumstances, the thread credential
- .Va 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.
- .Pp
- During a process credential update, the process lock must be held across
- check and update, to prevent race conditions.
- The process credential,
- .Va 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 prevent use of a stale value.
- To avoid this scenario, it is recommended that system calls updating the
- process credential be designed to avoid other authorization functions.
- .Pp
- If temporarily elevated privileges are required for a thread, the thread
- credential can by replaced for the duration of an activity, or for
- the remainder 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
- .Fn crget
- and
- .Fn crcopy .
- .Pp
- 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
- .Em never
- be used as the target credential in an access control decision: the process
- credential associated with the thread,
- .Va td->td_proc->p_ucred ,
- should be used instead.
- For example,
- .Xr p_candebug 9
- accepts a target process, not a target thread, for access control purposes.
- .Sh SEE ALSO
- .Xr uihold 9
- .Sh AUTHORS
- This manual page was written by
- .An Chad David Aq davidc@acns.ab.ca .