freebsd-dev/eBones/lib/libacl/acl_files.doc

108 lines
3.2 KiB
Plaintext
Raw Normal View History

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
asp@ATHENA.MIT.EDU
asp.@ATHENA.MIT.EDU
asp.root@ATHENA.MIT.EDU
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
asp@ATHENA.MIT.EDU is actually asp.@ATHENA.MIT.EDU.
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.