Date: Sat, 5 May 2001 20:22:22 -0400 (EDT) From: Robert Watson <rwatson@freebsd.org> To: Dima Dorfman <dima@unixfreak.org> Cc: hackers@freebsd.org Subject: Re: Man page for struct ucred/xucred Message-ID: <Pine.NEB.3.96L.1010505202005.25041D-100000@fledge.watson.org> In-Reply-To: <20010506001207.3A4903E0B@bazooka.unixfreak.org>
next in thread | previous in thread | raw e-mail | index | archive | help
One of the things still under some amount of consideration is the locking and reference counting behavior of the ucred-related code. I have a fairly significant revision of the ucred code in the works, which combines pcred and ucred, as well as cleaning up all the change_*() calls. There are also a number of races in code such as exec(), set*id(), ptrace(), et al, that have substantial races that need to be correct. The pcred->ucred changes are implemented, and build, but I have not booted test boxes yet. Once we have established the desired semantics, we'll probably want to be careful to document their behavior. One thing you should note in the man page is that that function requires that the passed ucred reference be a shared or exclusive reference for the duration of the call. I hope to post the pcred patches to -arch in the near future. Robert N M Watson FreeBSD Core Team, TrustedBSD Project robert@fledge.watson.org NAI Labs, Safeport Network Services On Sat, 5 May 2001, Dima Dorfman wrote: > I wrote a rather short manual page about struct ucred, struct xucred, > and the routines used to manipulate the former. There really isn't > all that much to write about, but I thought it'd be useful to have > something that describes the cr* functions even though the code isn't > hard to find or particularly difficult to understand. In addition it > mentions that struct ucred shouldn't be exported to the userland; it > may seem obvious, but implicit traditions are rarely a good thing. > > While writing this I also noticed that there's no routine to make a > struct xucred from a struct ucred. Should there be one? I think so. > Perhaps something with an API of > > void crxucred(struct ucred *cr, struct xucred *xcr); > > would be useful. > > Diff against /dev/null for the man page attached. Comments? Suggestions? > > Thanks, > > Dima Dorfman > dima@unixfreak.org > > > --- /dev/null Sat May 5 16:12:17 2001 > +++ ucred.9 Sat May 5 16:49:03 2001 > @@ -0,0 +1,108 @@ > +.\" > +.\" Copyright (c) 2001 Dima Dorfman <dima@unixfreak.org> > +.\" 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, 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. > +.\" > +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR 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 AUTHOR 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. > +.\" > +.\" $FreeBSD$ > +.\" > +.Dd May 5, 2001 > +.Dt UCRED 9 > +.Os > +.Sh NAME > +.Nm ucred , > +.Nm xucred > +.Nd structures to describe user credentials in the kernel and userland > +.Sh SYNOPSIS > +.Fd #include <sys/types.h> > +.Fd #include <sys/ucred.h> > +.Ft struct ucred * > +.Fn crget "void" > +.Ft void > +.Fn crhold "struct ucred *cr" > +.Ft void > +.Fn crfree "struct ucred *cr" > +.Ft struct ucred * > +.Fn crcopy "struct ucred *cr" > +.Ft struct ucred * > +.Fn crdup "struct ucred *cr" > +.Sh DESCRIPTION > +The > +.Ft ucred > +structure describes the user credentials within the kernel. > +The > +.Ft xucred > +structure describes the same user credentials in the userland. > +A > +.Ft struct ucred > +should never be exported to the userland; > +instead, it should be converted into a > +.Ft struct xucred . > +.Pp > +The following kernel functions exist to facilitate the maintenance of > +user credentials structures within the kernel. > +.Pp > +.Bl -tag -width crcopy > +.It Fn crget > +Allocate the memory for and return a zeroed structure. > +The reference count is set to 1. > +.It Fn crhold > +Increment the reference count of > +.Fa cr . > +.It Fn crfree > +Decrement the reference count of > +.Fa cr . > +If the reference count drops to 0, > +the memory for the structure is deallocated. > +.It Fn crcopy > +Make a copy and subsequently free > +.Fa cr . > +If the reference count was 1, > +this is equivilent to just assigning the address of > +.Fa cr > +to the new variable. > +Otherwise, it is equivilent to calling > +.Fn crdup > +and > +.Fn crfree . > +.It Fn crdup > +Allocate memory for a new structure and populate its contents with > +those from > +.Fa cr . > +The reference count of the new structure is set to 1. > +.El > +.Sh NOTES > +The > +.Dv cr_uid > +member of > +.Ft struct ucred > +should never be inspected directly to determine whether the user > +associated with this credentials structure should have superuser > +privileges. > +Instead, one of the > +.Xr suser 9 > +functions should be used. > +.Sh BUGS > +There is no routine to convert a > +.Ft struct ucred > +into a > +.Ft struct xucred . > > > To Unsubscribe: send mail to majordomo@FreeBSD.org > with "unsubscribe freebsd-hackers" in the body of the message > To Unsubscribe: send mail to majordomo@FreeBSD.org with "unsubscribe freebsd-hackers" in the body of the message
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?Pine.NEB.3.96L.1010505202005.25041D-100000>