1.\"- 2.\" Copyright (c) 2001 Robert N. M. Watson 3.\" All rights reserved. 4.\" 5.\" Redistribution and use in source and binary forms, with or without 6.\" modification, are permitted provided that the following conditions 7.\" are met: 8.\" 1. Redistributions of source code must retain the above copyright 9.\" notice, this list of conditions and the following disclaimer. 10.\" 2. Redistributions in binary form must reproduce the above copyright 11.\" notice, this list of conditions and the following disclaimer in the 12.\" documentation and/or other materials provided with the distribution. 13.\" 14.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND 15.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 16.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 17.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE 18.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 19.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 20.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 21.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 22.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 23.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 24.\" SUCH DAMAGE. 25.\" 26.\" $FreeBSD$ 27.\" 28.Dd August 22, 2001 29.Os 30.Dt VACCESS 9 31.Sh NAME 32.Nm vaccess 33.Nd generate an access control decision using vnode parameters 34.Sh SYNOPSIS 35.In sys/types.h 36.In sys/vnode.h 37.Ft int 38.Fo vaccess 39.Fa "enum vtype type" 40.Fa "mode_t file_mode" 41.Fa "uid_t file_uid" 42.Fa "gid_t file_gid" 43.Fa "mode_t acc_mode" 44.Fa "struct ucred *cred" 45.Fa "int *privused" 46.Fc 47.Sh DESCRIPTION 48This call implements the logic for the 49.Ux 50discretionary file security model 51common to many file systems in 52.Fx . 53It accepts the vnodes type 54.Fa type , 55permissions via 56.Fa file_mode , 57owning UID 58.Fa file_uid , 59owning GID 60.Fa file_gid , 61desired access mode 62.Fa acc_mode , 63requesting credential 64.Fa cred , 65and an optional call-by-reference 66.Vt int 67pointer returning whether or not 68privilege was required for successful evaluation of the call; the 69.Fa privused 70pointer may be set to 71.Dv NULL 72by the caller in order not to be informed of 73privilege information, or it may point to an integer that will be set to 741 if privilege is used, and 0 otherwise. 75.Pp 76This call is intended to support implementations of 77.Xr VOP_ACCESS 9 , 78which will use their own accessor methods to retrieve the vnode properties, 79and then invoke 80.Fn vaccess 81in order to perform the actual check. 82Implementations of 83.Xr VOP_ACCESS 9 84may choose to implement additional security mechanisms whose results will 85be composed with the return value. 86.Pp 87The algorithm used by 88.Fn vaccess 89selects a component of the file permission bits based on comparing the 90passed credential, file owner, and file group. 91If the credential's effective UID matches the file owner, then the 92owner component of the permission bits is selected. 93If the UID does not match, then the credential's effective GID, followed 94by additional groups, are compared with the file group\[em]if there is 95a match, then the group component of the permission bits is selected. 96If neither the credential UID or GIDs match the passed file owner and 97group, then the other component of the permission bits is selected. 98.Pp 99Once appropriate protections are selected for the current credential, 100the requested access mode, in combination with the vnode type, will be 101compared with the discretionary rights available for the credential. 102If the rights granted by discretionary protections are insufficient, 103then super-user privilege, if available for the credential, will also be 104considered. 105.Sh RETURN VALUES 106.Fn vaccess 107will return 0 on success, or a non-zero error value on failure. 108.Sh ERRORS 109.Bl -tag -width Er 110.It Bq Er EACCES 111Permission denied. 112An attempt was made to access a file in a way forbidden by its file access 113permissions. 114.It Bq Er EPERM 115Operation not permitted. 116An attempt was made to perform an operation limited to processes with 117appropriate privileges or to the owner of a file or other resource. 118.El 119.Sh SEE ALSO 120.Xr vaccess_acl_posix1e 9 , 121.Xr vnode 9 , 122.Xr VOP_ACCESS 9 123.Sh AUTHORS 124This man page and the current implementation of 125.Fn vaccess 126were written by 127.An Robert Watson . 128