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_ACL_POSIX1E 9 31.Sh NAME 32.Nm vaccess_acl_posix1e 33.Nd generate a POSIX.1e ACL access control decision using vnode parameters 34.Sh SYNOPSIS 35.In sys/param.h 36.In sys/vnode.h 37.In sys/acl.h 38.Ft int 39.Fo vaccess_acl_posix1e 40.Fa "enum vtype type" 41.Fa "uid_t file_uid" 42.Fa "gid_t file_gid" 43.Fa "struct acl *acl" 44.Fa "mode_t acc_mode" 45.Fa "struct ucred *cred" 46.Fa "int *privused" 47.Fc 48.Sh DESCRIPTION 49This call implements the logic for the 50.Ux 51discretionary file security model 52with POSIX.1e ACL extensions. 53It accepts the vnodes type 54.Fa type , 55owning UID 56.Fa file_uid , 57owning GID 58.Fa file_gid , 59access ACL for the file 60.Fa acl , 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 access methods to retrieve the vnode properties, 79and then invoke 80.Fn vaccess_acl_posix1e 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_acl_posix1e 89is based on the POSIX.1e ACL evaluation algorithm. 90The algorithm selects a 91.Em matching 92entry from the access ACL, which may 93then be composed with an available ACL mask entry, providing 94.Ux 95security compatibility. 96.Pp 97Once appropriate protections are selected for the current credential, 98the requested access mode, in combination with the vnode type, will be 99compared with the discretionary rights available for the credential. 100If the rights granted by discretionary protections are insufficient, 101then super-user privilege, if available for the credential, will also be 102considered. 103.Sh RETURN VALUES 104.Fn vaccess_acl_posix1e 105will return 0 on success, or a non-zero error value on failure. 106.Sh ERRORS 107.Bl -tag -width Er 108.It Bq Er EACCES 109Permission denied. 110An attempt was made to access a file in a way forbidden by its file access 111permissions. 112.It Bq Er EPERM 113Operation not permitted. 114An attempt was made to perform an operation limited to processes with 115appropriate privileges or to the owner of a file or other resource. 116.El 117.Sh SEE ALSO 118.Xr vaccess 9 , 119.Xr vnode 9 , 120.Xr VOP_ACCESS 9 121.Sh AUTHORS 122This manual page and the current implementation of 123.Fn vaccess_acl_posix1e 124were written by 125.An Robert Watson . 126.Sh BUGS 127This manual page should include a full description of the POSIX.1e ACL 128evaluation algorithm, or cross reference another page that does. 129