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 23, 2022 29.Dt VACCESS 9 30.Os 31.Sh NAME 32.Nm vaccess 33.Nd generate an access control decision using vnode parameters 34.Sh SYNOPSIS 35.In sys/param.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 "accmode_t accmode" 44.Fa "struct ucred *cred" 45.Fc 46.Sh DESCRIPTION 47This call implements the logic for the 48.Ux 49discretionary file security model 50common to many file systems in 51.Fx . 52It accepts the vnodes type 53.Fa type , 54permissions via 55.Fa file_mode , 56owning UID 57.Fa file_uid , 58owning GID 59.Fa file_gid , 60desired access mode 61.Fa accmode 62and requesting credential 63.Fa cred . 64.Pp 65This call is intended to support implementations of 66.Xr VOP_ACCESS 9 , 67which will use their own access methods to retrieve the vnode properties, 68and then invoke 69.Fn vaccess 70in order to perform the actual check. 71Implementations of 72.Xr VOP_ACCESS 9 73may choose to implement additional security mechanisms whose results will 74be composed with the return value. 75.Pp 76The algorithm used by 77.Fn vaccess 78selects a component of the file permission bits based on comparing the 79passed credential, file owner, and file group. 80If the credential's effective UID matches the file owner, then the 81owner component of the permission bits is selected. 82If the UID does not match, then the credential's effective GID, followed 83by additional groups, are compared with the file group\[em]if there is 84a match, then the group component of the permission bits is selected. 85If neither the credential UID or GIDs match the passed file owner and 86group, then the other component of the permission bits is selected. 87.Pp 88Once appropriate protections are selected for the current credential, 89the requested access mode, in combination with the vnode type, will be 90compared with the discretionary rights available for the credential. 91If the rights granted by discretionary protections are insufficient, 92then super-user privilege, if available for the credential, will also be 93considered. 94.Sh RETURN VALUES 95.Fn vaccess 96will return 0 on success, or a non-zero error value on failure. 97.Sh ERRORS 98.Bl -tag -width Er 99.It Bq Er EACCES 100Permission denied. 101An attempt was made to access a file in a way forbidden by its file access 102permissions. 103.It Bq Er EPERM 104Operation not permitted. 105An attempt was made to perform an operation limited to processes with 106appropriate privileges or to the owner of a file or other resource. 107.El 108.Sh SEE ALSO 109.Xr vaccess_acl_nfs4 9 , 110.Xr vaccess_acl_posix1e 9 , 111.Xr vnode 9 , 112.Xr VOP_ACCESS 9 113.Sh AUTHORS 114This manual page and the current implementation of 115.Fn vaccess 116were written by 117.An Robert Watson . 118