freebsd-dev/crypto/kerberosIV/lib/acl/acl_files.doc
Mark Murray 03656ac1b0 Initial import of KTH eBones. This has been cleaned up to only include
the "core" Kerberos functionality. The rest of the userland will get their
own changes later.
1997-09-04 06:04:33 +00:00

108 lines
3.2 KiB
Plaintext

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.