acl_files.doc

早期freebsd实现

PROTOTYPE ACL LIBRARY

Introduction
	
An access control list (ACL) is a list of principals, where each
principal is is represented by a text string which cannot contain
whitespace.  The library allows application programs to refer to named
access control lists to test membership and to atomically add and
delete principals using a natural and intuitive interface.  At
present, the names of access control lists are required to be Unix
filenames, and refer to human-readable Unix files; in the future, when
a networked ACL server is implemented, the names may refer to a
different namespace specific to the ACL service.


Usage

cc <files> -lacl -lkrb.



Principal Names

Principal names have the form

<name>[.<instance>][@<realm>]

e.g.

asp
asp.root
[e-mail]
[e-mail]
[e-mail]

It is possible for principals to be underspecified.  If instance is
missing, it is assumed to be "".  If realm is missing, it is assumed
to be local_realm.  The canonical form contains all of name, instance,
and realm; the acl_add and acl_delete routines will always
leave the file in that form.  Note that the canonical form of
[e-mail] is actually [e-mail].


Routines

acl_canonicalize_principal(principal, buf)
char *principal;
char *buf;  	/*RETVAL*/

Store the canonical form of principal in buf.  Buf must contain enough
space to store a principal, given the limits on the sizes of name,
instance, and realm specified in /usr/include/krb.h.

acl_check(acl, principal)
char *acl;
char *principal;

Returns nonzero if principal appears in acl.  Returns 0 if principal
does not appear in acl, or if an error occurs.  Canonicalizes
principal before checking, and allows the ACL to contain wildcards.

acl_exact_match(acl, principal)
char *acl;
char *principal;

Like acl_check, but does no canonicalization or wildcarding.

acl_add(acl, principal)
char *acl;
char *principal;

Atomically adds principal to acl.  Returns 0 if successful, nonzero
otherwise.  It is considered a failure if principal is already in acl.
This routine will canonicalize principal, but will treat wildcards
literally.

acl_delete(acl, principal)
char *acl;
char *principal;

Atomically deletes principal from acl.  Returns 0 if successful,
nonzero otherwise.  It is consider a failure if principal is not
already in acl.  This routine will canonicalize principal, but will
treat wildcards literally.

acl_initialize(acl, mode)
char *acl;
int mode;

Initialize acl.  If acl file does not exist, creates it with mode
mode.  If acl exists, removes all members.  Returns 0 if successful,
nonzero otherwise.  WARNING: Mode argument is likely to change with
the eventual introduction of an ACL service.  


Known problems

In the presence of concurrency, there is a very small chance that
acl_add or acl_delete could report success even though it would have
had no effect.  This is a necessary side effect of using lock files
for concurrency control rather than flock(2), which is not supported
by NFS.

The current implementation caches ACLs in memory in a hash-table
format for increased efficiency in checking membership; one effect of
the caching scheme is that one file descriptor will be kept open for
each ACL cached, up to a maximum of 8.