1 files changed, 107 insertions, 0 deletions
diff --git a/crypto/kerberosIV/lib/acl/acl_files.doc b/crypto/kerberosIV/lib/acl/acl_files.doc
new file mode 100644
index 0000000..78c448a
--- /dev/null
+++ b/crypto/kerberosIV/lib/acl/acl_files.doc
@@ -0,0 +1,107 @@
+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.