472351e13d
.In header.h instead of .Fd #include \*[Lt]header.h\*[Gt] Much easier to read and write, and supported by groff for ages. Okayed by ross.
144 lines
4.5 KiB
Groff
144 lines
4.5 KiB
Groff
.\" $NetBSD: cred.9,v 1.5 2003/04/16 13:35:27 wiz Exp $
|
|
.\"
|
|
.\" Copyright (c) 2002 The NetBSD Foundation, Inc.
|
|
.\" All rights reserved.
|
|
.\"
|
|
.\" This code is derived from software contributed to The NetBSD Foundation
|
|
.\" by Gregory McGarry.
|
|
.\"
|
|
.\" 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, this list of conditions and the following disclaimer.
|
|
.\" 2. Redistributions in binary form must reproduce the above copyright
|
|
.\" notice, this list of conditions and the following disclaimer in the
|
|
.\" documentation and/or other materials provided with the distribution.
|
|
.\" 3. All advertising materials mentioning features or use of this software
|
|
.\" must display the following acknowledgement:
|
|
.\" This product includes software developed by the NetBSD
|
|
.\" Foundation, Inc. and its contributors.
|
|
.\" 4. Neither the name of The NetBSD Foundation nor the names of its
|
|
.\" contributors may be used to endorse or promote products derived
|
|
.\" from this software without specific prior written permission.
|
|
.\"
|
|
.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS
|
|
.\" ``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 FOUNDATION OR CONTRIBUTORS
|
|
.\" 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.
|
|
.\"
|
|
.Dd January 25, 2003
|
|
.Dt CRED 9
|
|
.Os
|
|
.Sh NAME
|
|
.Nm cred ,
|
|
.Nm crcopy ,
|
|
.Nm crcvt
|
|
.Nm crdup ,
|
|
.Nm crfree ,
|
|
.Nm crget ,
|
|
.Nm crhold ,
|
|
.Nd operations on user credentials
|
|
.Sh SYNOPSIS
|
|
.In sys/param.h
|
|
.In sys/ucred.h
|
|
.Ft struct ucred *
|
|
.Fn crcopy "struct ucred *cr"
|
|
.Ft void
|
|
.Fn crcvt "struct ucred *cr" "const struct uucred *ucr"
|
|
.Ft struct ucred *
|
|
.Fn crdup "struct ucred *cr"
|
|
.Ft void
|
|
.Fn crfree "struct ucred *cr"
|
|
.Ft struct ucred *
|
|
.Fn crget "void"
|
|
.Ft void
|
|
.Fn crhold "struct ucred *cr"
|
|
.Sh DESCRIPTION
|
|
A process must have the appropriate user credentials for the kernel to
|
|
perform an operation on its behalf.
|
|
The user credentials are stored along with the process in the following
|
|
structure:
|
|
.Pp
|
|
.Bd -literal
|
|
struct ucred {
|
|
u_int32_t cr_ref; /* reference count */
|
|
uid_t cr_uid; /* effective user id */
|
|
gid_t cr_gid; /* effective group id */
|
|
u_int32_t cr_ngroups; /* number of groups */
|
|
gid_t cr_groups[NGROUPS]; /* groups */
|
|
};
|
|
.Ed
|
|
.Pp
|
|
User credentials are controlled by the
|
|
.Xr group 5
|
|
and
|
|
.Xr passwd 5
|
|
files and manipulated using the
|
|
.Xr setregid 2 ,
|
|
.Xr setgid 2 ,
|
|
.Xr setegid 2 ,
|
|
.Xr setgroups 2 ,
|
|
and
|
|
.Xr getgroups 2
|
|
system calls.
|
|
.Pp
|
|
References to user credentials are maintained from many different data
|
|
structures, including processes, file descriptors and vnodes.
|
|
The ucred member
|
|
.Em cr_ref
|
|
reflects the number of references to the credentials.
|
|
.Sh FUNCTIONS
|
|
The following functions operate on user credentials:
|
|
.Pp
|
|
.Bl -tag -width compact
|
|
.It Fn crcopy "cr"
|
|
Allocate a new credentials structure and copy the contents from
|
|
credentials
|
|
.Fa cr
|
|
to the new one.
|
|
The old credentials
|
|
.Fa cr
|
|
are freed.
|
|
The reference count on the returned credentials is guaranteed to be one.
|
|
.It Fn crcvt "cr" "ucr"
|
|
Convert from userland credentials
|
|
.Fa ucr
|
|
to kernel credentials
|
|
.Fa cr .
|
|
.It Fn crdup "cr"
|
|
Allocate a new credentials structure and copy the contents from
|
|
credentials
|
|
.Fa cr
|
|
to the new one.
|
|
The old credentials
|
|
.Fa cr
|
|
remain unchanged.
|
|
The reference count on the returned credentials is guaranteed to be one.
|
|
.It Fn crfree "cr"
|
|
Decrement the reference count on credentials
|
|
.Fa cr .
|
|
If the reference count drops to zero, then the credentials are freed.
|
|
.It Fn crget "void"
|
|
Allocate and return zeroed credentials.
|
|
.It Fn crhold "cr"
|
|
Increment the reference count on credentials
|
|
.Fa cr .
|
|
.El
|
|
.Sh SEE ALSO
|
|
.Xr suser 9
|
|
.Sh BUGS
|
|
User credentials are sometimes allocated using
|
|
.Xr MALLOC 9
|
|
and sometimes using the
|
|
.Xr pool 9
|
|
facility.
|
|
This cannot be right.
|