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