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