/*-
 * Copyright (c) 1999 Robert N. M. Watson
 * All rights reserved.
 *
 * Redistribution and use in source and binary forms, with or without
 * modification, are permitted provided that the following conditions
 * are met:
 * 1. Redistributions of source code must retain the above copyright
 *    notice, this list of conditions and the following disclaimer.
 * 2. Redistributions in binary form must reproduce the above copyright
 *    notice, this list of conditions and the following disclaimer in the
 *    documentation and/or other materials provided with the distribution.
 *
 * THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
 * ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
 * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
 * ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
 * FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
 * DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
 * OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
 * HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
 * LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
 * OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
 * SUCH DAMAGE.
 *
 *	$Id $
 */

POSIX.1e Access Control Lists for FreeBSD, Version 0.1.1
http://www.watson.org/fbsd-hardening/posix1e/acl/
Robert Watson <robert@fledge.watson.org>

This is the README file for 0.1.1 of POSIX.1e ACLs for FreeBSD.

  Introduction

Access Control Lists provide a means by which more detailed permissions may
be associated with file system objects, allowing the granting of rights
in a discretionary way by the file owner.  POSIX.1e ACLs extend the basic
UNIX permission set allowing the granting of rights to additional users
and groups beyond the file owner and group.  These mechanisms can be used
to reduce the need for centralized file permission administration by system
administrators in the case of collaborative work (files and directories can
now give rights to sets of users without the system administrator needing
to define a group describing the set), and can also be used to more finely
tune permissions for system use.

This is a still-experimental implementation, and not all components to
make it useful are present at this time.  However, it is a framework that
can be worked with and extended to become useful.  In general, the POSIX.1e
draft standard is adhered to for interfaces, except in specific documented
cases.  Internally, ACLs are handled in a format the is compatible with POSIX,
but is optimized for faster evaluation due to record ordering and fixed
size limitations.

  Configuration

This code is a forward port from the original code based on 3.3-RELEASE,
and was ported with the assistance of Assar Westerlund.  It is now based on
4.0-CURRENT as of around Dec 1, 1999.  This code should be easily portable
back to 3.x, or even 2.2.x.  

To install the ACL code, first apply the kernel patch, which will modify
the vnode interface, modify a couple of includes, and add new source files.

You'll want to rebuild your kernel, and install the system includes
(specifically, you also want src/sys/sys/acl.h in /usr/include/sys for
the building of the libraries, as well as syscall-associated libraries
for libc syscall stubs).

When building a kernel, add "options POSIX1E_ACL" to your kernel config
file.

You'll also need to rebuild libc to take into account the new ACL
syscalls -- cd to /usr/lib/libc and do a make + make install -- this relies
on the new syscall files appearing in /usr/include/sys.

Next you'll want to build libposix1e_acl by cd'ing to src/lib/libposix1e_acl,
and doing a make followed by make install.  You won't be able to link
programs against this libary without an updated libc as above, although it
will build.

Finally, you'll want to build and try out the test programs, and similarly
build and install src/usr.bin/getfacl.  setfacl is not currently implemented.

Man pages are not yet available.

  Interfaces

Several new interfaces are introduced to support ACLs.  This includes a
new library that provides access to the POSIX.1e interface, new syscalls
wrapped by that library to provide ACL information to user processes, and
allow the setting of ACLs, two new vnode calls to allow the setting and
retrieval of ACLs on files and directories, and a number of support calls
in kern_acl.c so that file systems using the POSIX.1e ACL semantics can
make use of common code for access control checks.  Also provided are the
starting framework for userland utilities for inspecting and modifying
ACLs.

  Implementation Status

Userland utilities: getfacl is finished, setfacl is not

Libraries: The basis ACL set/get/text/etc is complete, but the detailed ACL
           editing support (inconvenient and unwieldy) is not.

Syscalls: All syscalls are fully implemented

Vnode calls: A vnode framework is provided, but individual file systems
             must provide their own ACL storage and management.  Generic
             ACL support code is provided in kern_acl.c to make this consistent
             across filesystems.

Documentation: Not yet started, other than README and some implementation
               notes.

  Documentation

The man pages are not yet started.  In the mean time, the POSIX.1e
draft accurately documents the interface.

Some implementation notes exist in the notes/ subdirectory of the
distribution.

This README makes a good introduction.

  Mailing Lists

FreeBSD Security: freebsd-security@freebsd.org, majordomo@freebsd.org
POSIX.1e: posix1e@cyrus.watson.org, majordomo@cyrus.watson.org

  Web Pages

POSIX.1e for FreeBSD: http://www.watson.org/fbsd-hardening/posix1e/
POSIX.1e ACLs: http://www.watson.org/fbsd-hardening/posix1e/acl/

  License

Standard 2-clause BSD-style license (see top of this file), designed to
encourage wide-spread integration of the code in open-source and commercial
products.  This license encourages interoperability through the use of
compatible and consistent code across platforms--which is consistent with
the desire to produce a more portable and secure environment.  Please
feel free to contact me if you're interested in alternative licenses that
better suit your needs, or if you want to send me money.

  Contact Information

General: Robert Watson <robert@fledge.watson.org>
FreeBSD-related: Robert Watson <robert+freebsd@cyrus.watson.org>


