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.

4 files changed, 784 insertions, 0 deletions

diff --git a/crypto/kerberosIV/lib/acl/Makefile.in b/crypto/kerberosIV/lib/acl/Makefile.in
new file mode 100644
index 0000000..59894e4
--- /dev/null
+++ b/crypto/kerberosIV/lib/acl/Makefile.in
@@ -0,0 +1,84 @@
+#
+# $Id: Makefile.in,v 1.21 1997/05/06 03:46:37 assar Exp $
+#
+
+SHELL = /bin/sh
+
+srcdir = @srcdir@
+VPATH = @srcdir@
+
+CC = @CC@
+AR = ar
+RANLIB = @RANLIB@
+DEFS = @DEFS@
+CFLAGS = @CFLAGS@
+
+INSTALL = @INSTALL@
+INSTALL_DATA	= @INSTALL_DATA@
+MKINSTALLDIRS = @top_srcdir@/mkinstalldirs
+
+prefix = @prefix@
+exec_prefix = @exec_prefix@
+libdir = @libdir@
+
+PICFLAGS = # @PICFLAGS@
+
+LIBNAME = $(LIBPREFIX)acl
+#LIBEXT = @LIBEXT@ Always build archive library!
+LIBEXT = a
+LIBPREFIX = @LIBPREFIX@
+SHLIBEXT = @SHLIBEXT@
+LDSHARED = @LDSHARED@
+LIB = $(LIBNAME).$(LIBEXT)
+
+SOURCES = acl_files.c
+
+OBJECTS = acl_files.o
+
+all: $(LIB)
+
+Wall:
+	make CFLAGS="-g -Wall -Wno-comment -Wmissing-prototypes -Wmissing-declarations -D__USE_FIXED_PROTOTYPES__"
+
+.c.o:
+	$(CC) -c $(CPPFLAGS) $(DEFS) -I../../include -I$(srcdir) $(CFLAGS) $(PICFLAGS) $<
+
+install: all
+	$(MKINSTALLDIRS) $(libdir)
+	$(INSTALL_DATA) -m 0555 $(LIB) $(libdir)
+
+uninstall:
+	rm -f $(libdir)/$(LIB)
+
+TAGS: $(SOURCES)
+	etags $(SOURCES)
+
+check:
+
+clean:
+	rm -f $(LIB) *.o *.a
+
+mostlyclean: clean
+
+distclean: clean
+	rm -f Makefile *.tab.c *~
+
+realclean: distclean
+	rm -f TAGS
+
+dist: $(DISTFILES)
+	for file in $(DISTFILES); do \
+	  ln $$file ../`cat ../.fname`/lib \
+	    || cp -p $$file ../`cat ../.fname`/lib; \
+	done
+
+$(LIBNAME).a: $(OBJECTS)
+	rm -f $@
+	$(AR) cr $@ $(OBJECTS)
+	-$(RANLIB) $@
+
+$(LIBNAME).$(SHLIBEXT): $(OBJECTS)
+	rm -f $@
+	$(LDSHARED) -o $@ $(OBJECTS)
+
+$(OBJECTS): ../../include/config.h
diff --git a/crypto/kerberosIV/lib/acl/acl.h b/crypto/kerberosIV/lib/acl/acl.h
new file mode 100644
index 0000000..305b66c
--- /dev/null
+++ b/crypto/kerberosIV/lib/acl/acl.h
@@ -0,0 +1,53 @@
+/*
+ * Copyright (c) 1995, 1996, 1997 Kungliga Tekniska Högskolan
+ * (Royal Institute of Technology, Stockholm, Sweden).
+ * 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.
+ * 
+ * 3. All advertising materials mentioning features or use of this software
+ *    must display the following acknowledgement:
+ *      This product includes software developed by the Kungliga Tekniska
+ *      Högskolan and its contributors.
+ * 
+ * 4. Neither the name of the Institute nor the names of its contributors
+ *    may be used to endorse or promote products derived from this software
+ *    without specific prior written permission.
+ * 
+ * THIS SOFTWARE IS PROVIDED BY THE INSTITUTE 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 INSTITUTE 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: acl.h,v 1.5 1997/04/01 08:17:52 joda Exp $ */
+
+#ifndef __ACL_H
+#define __ACL_H
+
+#include <sys/cdefs.h>
+
+void acl_canonicalize_principal __P((char *principal, char *canon));
+int acl_initialize __P((char *acl_file, int perm));
+int acl_exact_match __P((char *acl, char *principal));
+int acl_check __P((char *acl, char *principal));
+int acl_add __P((char *acl, char *principal));
+int acl_delete __P((char *acl, char *principal));
+
+#endif /* __ACL_H */
diff --git a/crypto/kerberosIV/lib/acl/acl_files.c b/crypto/kerberosIV/lib/acl/acl_files.c
new file mode 100644
index 0000000..fc00b80
--- /dev/null
+++ b/crypto/kerberosIV/lib/acl/acl_files.c
@@ -0,0 +1,540 @@
+/* 
+  Copyright (C) 1989 by the Massachusetts Institute of Technology
+
+   Export of this software from the United States of America is assumed
+   to require a specific license from the United States Government.
+   It is the responsibility of any person or organization contemplating
+   export to obtain such a license before exporting.
+
+WITHIN THAT CONSTRAINT, permission to use, copy, modify, and
+distribute this software and its documentation for any purpose and
+without fee is hereby granted, provided that the above copyright
+notice appear in all copies and that both that copyright notice and
+this permission notice appear in supporting documentation, and that
+the name of M.I.T. not be used in advertising or publicity pertaining
+to distribution of the software without specific, written prior
+permission.  M.I.T. makes no representations about the suitability of
+this software for any purpose.  It is provided "as is" without express
+or implied warranty.
+
+  */
+
+#include "config.h"
+#include "protos.h"
+
+RCSID("$Id: acl_files.c,v 1.10 1997/05/02 14:28:56 assar Exp $");
+
+#include <stdio.h>
+#include <stdlib.h>
+#include <string.h>
+
+#ifdef HAVE_UNISTD_H
+#include <unistd.h>
+#endif
+#ifdef HAVE_SYS_TYPES_H
+#include <sys/types.h>
+#endif
+#include <time.h>
+#ifdef HAVE_FCNTL_H
+#include <fcntl.h>
+#endif
+#ifdef HAVE_SYS_FILE_H
+#include <sys/file.h>
+#endif
+#ifdef HAVE_SYS_STAT_H
+#include <sys/stat.h>
+#endif
+
+#include <errno.h>
+#include <ctype.h>
+
+#include <roken.h>
+
+#include <krb.h>
+#include <acl.h>
+
+/*** Routines for manipulating access control list files ***/
+
+/* "aname.inst@realm" */
+#define MAX_PRINCIPAL_SIZE  (ANAME_SZ + INST_SZ + REALM_SZ + 3)
+#define INST_SEP '.'
+#define REALM_SEP '@'
+
+#define LINESIZE 2048		/* Maximum line length in an acl file */
+
+#define NEW_FILE "%s.~NEWACL~"	/* Format for name of altered acl file */
+#define WAIT_TIME 300		/* Maximum time allowed write acl file */
+
+#define CACHED_ACLS 8		/* How many acls to cache */
+				/* Each acl costs 1 open file descriptor */
+#define ACL_LEN 16		/* Twice a reasonable acl length */
+
+#define COR(a,b) ((a!=NULL)?(a):(b))
+
+/* Canonicalize a principal name */
+/* If instance is missing, it becomes "" */
+/* If realm is missing, it becomes the local realm */
+/* Canonicalized form is put in canon, which must be big enough to hold
+   MAX_PRINCIPAL_SIZE characters */
+void
+acl_canonicalize_principal(char *principal, char *canon)
+{
+    char *dot, *atsign, *end;
+    int len;
+
+    dot = strchr(principal, INST_SEP);
+    atsign = strchr(principal, REALM_SEP);
+
+    /* Maybe we're done already */
+    if(dot != NULL && atsign != NULL) {
+	if(dot < atsign) {
+	    /* It's for real */
+	    /* Copy into canon */
+	    strncpy(canon, principal, MAX_PRINCIPAL_SIZE);
+	    canon[MAX_PRINCIPAL_SIZE-1] = '\0';
+	    return;
+	} else {
+	    /* Nope, it's part of the realm */
+	    dot = NULL;
+	}
+    }
+    
+    /* No such luck */
+    end = principal + strlen(principal);
+
+    /* Get the principal name */
+    len = min(ANAME_SZ, COR(dot, COR(atsign, end)) - principal);
+    strncpy(canon, principal, len);
+    canon += len;
+
+    /* Add INST_SEP */
+    *canon++ = INST_SEP;
+
+    /* Get the instance, if it exists */
+    if(dot != NULL) {
+	++dot;
+	len = min(INST_SZ, COR(atsign, end) - dot);
+	strncpy(canon, dot, len);
+	canon += len;
+    }
+
+    /* Add REALM_SEP */
+    *canon++ = REALM_SEP;
+
+    /* Get the realm, if it exists */
+    /* Otherwise, default to local realm */
+    if(atsign != NULL) {
+	++atsign;
+	len = min(REALM_SZ, end - atsign);
+	strncpy(canon, atsign, len);
+	canon += len;
+	*canon++ = '\0';
+    } else if(krb_get_lrealm(canon, 1) != KSUCCESS) {
+	strcpy(canon, KRB_REALM);
+    }
+}
+	    
+/* Get a lock to modify acl_file */
+/* Return new FILE pointer */
+/* or NULL if file cannot be modified */
+/* REQUIRES WRITE PERMISSION TO CONTAINING DIRECTORY */
+static
+FILE *acl_lock_file(char *acl_file)
+{
+    struct stat s;
+    char new[LINESIZE];
+    int nfd;
+    FILE *nf;
+    int mode;
+
+    if(stat(acl_file, &s) < 0) return(NULL);
+    mode = s.st_mode;
+    snprintf(new, sizeof(new), NEW_FILE, acl_file);
+    for(;;) {
+	/* Open the new file */
+	if((nfd = open(new, O_WRONLY|O_CREAT|O_EXCL, mode)) < 0) {
+	    if(errno == EEXIST) {
+		/* Maybe somebody got here already, maybe it's just old */
+		if(stat(new, &s) < 0) return(NULL);
+		if(time(0) - s.st_ctime > WAIT_TIME) {
+		    /* File is stale, kill it */
+		    unlink(new);
+		    continue;
+		} else {
+		    /* Wait and try again */
+		    sleep(1);
+		    continue;
+		}
+	    } else {
+		/* Some other error, we lose */
+		return(NULL);
+	    }
+	}
+
+	/* If we got to here, the lock file is ours and ok */
+	/* Reopen it under stdio */
+	if((nf = fdopen(nfd, "w")) == NULL) {
+	    /* Oops, clean up */
+	    unlink(new);
+	}
+	return(nf);
+    }
+}
+
+/* Abort changes to acl_file written onto FILE *f */
+/* Returns 0 if successful, < 0 otherwise */
+/* Closes f */
+static int
+acl_abort(char *acl_file, FILE *f)
+{
+    char new[LINESIZE];
+    int ret;
+    struct stat s;
+
+    /* make sure we aren't nuking someone else's file */
+    if(fstat(fileno(f), &s) < 0
+       || s.st_nlink == 0) {
+	   fclose(f);
+	   return(-1);
+       } else {
+	   snprintf(new, sizeof(new), NEW_FILE, acl_file);
+	   ret = unlink(new);
+	   fclose(f);
+	   return(ret);
+       }
+}
+
+/* Commit changes to acl_file written onto FILE *f */
+/* Returns zero if successful */
+/* Returns > 0 if lock was broken */
+/* Returns < 0 if some other error occurs */
+/* Closes f */
+static int
+acl_commit(char *acl_file, FILE *f)
+{
+    char new[LINESIZE];
+    int ret;
+    struct stat s;
+
+    snprintf(new, sizeof(new), NEW_FILE, acl_file);
+    if(fflush(f) < 0
+       || fstat(fileno(f), &s) < 0
+       || s.st_nlink == 0) {
+	acl_abort(acl_file, f);
+	return(-1);
+    }
+
+    ret = rename(new, acl_file);
+    fclose(f);
+    return(ret);
+}
+
+/* Initialize an acl_file */
+/* Creates the file with permissions perm if it does not exist */
+/* Erases it if it does */
+/* Returns return value of acl_commit */
+int
+acl_initialize(char *acl_file, int perm)
+{
+    FILE *new;
+    int fd;
+
+    /* Check if the file exists already */
+    if((new = acl_lock_file(acl_file)) != NULL) {
+	return(acl_commit(acl_file, new));
+    } else {
+	/* File must be readable and writable by owner */
+	if((fd = open(acl_file, O_CREAT|O_EXCL, perm|0600)) < 0) {
+	    return(-1);
+	} else {
+	    close(fd);
+	    return(0);
+	}
+    }
+}
+
+/* Eliminate all whitespace character in buf */
+/* Modifies its argument */
+static void
+ nuke_whitespace(char *buf)
+{
+    char *pin, *pout;
+
+    for(pin = pout = buf; *pin != '\0'; pin++)
+	if(!isspace(*pin)) *pout++ = *pin;
+    *pout = '\0';		/* Terminate the string */
+}
+
+/* Hash table stuff */
+
+struct hashtbl {
+    int size;			/* Max number of entries */
+    int entries;		/* Actual number of entries */
+    char **tbl;			/* Pointer to start of table */
+};
+
+/* Make an empty hash table of size s */
+static struct hashtbl *
+make_hash(int size)
+{
+    struct hashtbl *h;
+
+    if(size < 1) size = 1;
+    h = (struct hashtbl *) malloc(sizeof(struct hashtbl));
+    h->size = size;
+    h->entries = 0;
+    h->tbl = (char **) calloc(size, sizeof(char *));
+    return(h);
+}
+
+/* Destroy a hash table */
+static void
+destroy_hash(struct hashtbl *h)
+{
+    int i;
+
+    for(i = 0; i < h->size; i++) {
+	if(h->tbl[i] != NULL) free(h->tbl[i]);
+    }
+    free(h->tbl);
+    free(h);
+}
+
+/* Compute hash value for a string */
+static unsigned int
+hashval(char *s)
+{
+    unsigned hv;
+
+    for(hv = 0; *s != '\0'; s++) {
+	hv ^= ((hv << 3) ^ *s);
+    }
+    return(hv);
+}
+
+/* Add an element to a hash table */
+static void
+add_hash(struct hashtbl *h, char *el)
+{
+    unsigned hv;
+    char *s;
+    char **old;
+    int i;
+
+    /* Make space if it isn't there already */
+    if(h->entries + 1 > (h->size >> 1)) {
+	old = h->tbl;
+	h->tbl = (char **) calloc(h->size << 1, sizeof(char *));
+	for(i = 0; i < h->size; i++) {
+	    if(old[i] != NULL) {
+		hv = hashval(old[i]) % (h->size << 1);
+		while(h->tbl[hv] != NULL) hv = (hv+1) % (h->size << 1);
+		h->tbl[hv] = old[i];
+	    }
+	}
+	h->size = h->size << 1;
+	free(old);
+    }
+
+    hv = hashval(el) % h->size;
+    while(h->tbl[hv] != NULL && strcmp(h->tbl[hv], el)) hv = (hv+1) % h->size;
+    s = strdup(el);
+    h->tbl[hv] = s;
+    h->entries++;
+}
+
+/* Returns nonzero if el is in h */
+static int
+check_hash(struct hashtbl *h, char *el)
+{
+    unsigned hv;
+
+    for(hv = hashval(el) % h->size;
+	h->tbl[hv] != NULL;
+	hv = (hv + 1) % h->size) {
+	    if(!strcmp(h->tbl[hv], el)) return(1);
+	}
+    return(0);
+}
+
+struct acl {
+    char filename[LINESIZE];	/* Name of acl file */
+    int fd;			/* File descriptor for acl file */
+    struct stat status;		/* File status at last read */
+    struct hashtbl *acl;	/* Acl entries */
+};
+
+static struct acl acl_cache[CACHED_ACLS];
+
+static int acl_cache_count = 0;
+static int acl_cache_next = 0;
+
+/* Returns < 0 if unsuccessful in loading acl */
+/* Returns index into acl_cache otherwise */
+/* Note that if acl is already loaded, this is just a lookup */
+static int
+acl_load(char *name)
+{
+    int i;
+    FILE *f;
+    struct stat s;
+    char buf[MAX_PRINCIPAL_SIZE];
+    char canon[MAX_PRINCIPAL_SIZE];
+
+    /* See if it's there already */
+    for(i = 0; i < acl_cache_count; i++) {
+	if(!strcmp(acl_cache[i].filename, name)
+	   && acl_cache[i].fd >= 0) goto got_it;
+    }
+
+    /* It isn't, load it in */
+    /* maybe there's still room */
+    if(acl_cache_count < CACHED_ACLS) {
+	i = acl_cache_count++;
+    } else {
+	/* No room, clean one out */
+	i = acl_cache_next;
+	acl_cache_next = (acl_cache_next + 1) % CACHED_ACLS;
+	close(acl_cache[i].fd);
+	if(acl_cache[i].acl) {
+	    destroy_hash(acl_cache[i].acl);
+	    acl_cache[i].acl = (struct hashtbl *) 0;
+	}
+    }
+
+    /* Set up the acl */
+    strcpy(acl_cache[i].filename, name);
+    if((acl_cache[i].fd = open(name, O_RDONLY, 0)) < 0) return(-1);
+    /* Force reload */
+    acl_cache[i].acl = (struct hashtbl *) 0;
+
+ got_it:
+    /*
+     * See if the stat matches
+     *
+     * Use stat(), not fstat(), as the file may have been re-created by
+     * acl_add or acl_delete.  If this happens, the old inode will have
+     * no changes in the mod-time and the following test will fail.
+     */
+    if(stat(acl_cache[i].filename, &s) < 0) return(-1);
+    if(acl_cache[i].acl == (struct hashtbl *) 0
+       || s.st_nlink != acl_cache[i].status.st_nlink
+       || s.st_mtime != acl_cache[i].status.st_mtime
+       || s.st_ctime != acl_cache[i].status.st_ctime) {
+	   /* Gotta reload */
+	   if(acl_cache[i].fd >= 0) close(acl_cache[i].fd);
+	   if((acl_cache[i].fd = open(name, O_RDONLY, 0)) < 0) return(-1);
+	   if((f = fdopen(acl_cache[i].fd, "r")) == NULL) return(-1);
+	   if(acl_cache[i].acl) destroy_hash(acl_cache[i].acl);
+	   acl_cache[i].acl = make_hash(ACL_LEN);
+	   while(fgets(buf, sizeof(buf), f) != NULL) {
+	       nuke_whitespace(buf);
+	       acl_canonicalize_principal(buf, canon);
+	       add_hash(acl_cache[i].acl, canon);
+	   }
+	   fclose(f);
+	   acl_cache[i].status = s;
+       }
+    return(i);
+}
+
+/* Returns nonzero if it can be determined that acl contains principal */
+/* Principal is not canonicalized, and no wildcarding is done */
+int
+acl_exact_match(char *acl, char *principal)
+{
+    int idx;
+
+    return((idx = acl_load(acl)) >= 0
+	   && check_hash(acl_cache[idx].acl, principal));
+}
+
+/* Returns nonzero if it can be determined that acl contains principal */
+/* Recognizes wildcards in acl of the form
+   name.*@realm, *.*@realm, and *.*@* */
+int
+acl_check(char *acl, char *principal)
+{
+    char buf[MAX_PRINCIPAL_SIZE];
+    char canon[MAX_PRINCIPAL_SIZE];
+    char *realm;
+
+    acl_canonicalize_principal(principal, canon);
+
+    /* Is it there? */
+    if(acl_exact_match(acl, canon)) return(1);
+
+    /* Try the wildcards */
+    realm = strchr(canon, REALM_SEP);
+    *strchr(canon, INST_SEP) = '\0';	/* Chuck the instance */
+
+    snprintf(buf, sizeof(buf), "%s.*%s", canon, realm);
+    if(acl_exact_match(acl, buf)) return(1);
+
+    snprintf(buf, sizeof(buf), "*.*%s", realm);
+    if(acl_exact_match(acl, buf) || acl_exact_match(acl, "*.*@*")) return(1);
+       
+    return(0);
+}
+
+/* Adds principal to acl */
+/* Wildcards are interpreted literally */
+int
+acl_add(char *acl, char *principal)
+{
+    int idx;
+    int i;
+    FILE *new;
+    char canon[MAX_PRINCIPAL_SIZE];
+
+    acl_canonicalize_principal(principal, canon);
+
+    if((new = acl_lock_file(acl)) == NULL) return(-1);
+    if((acl_exact_match(acl, canon))
+       || (idx = acl_load(acl)) < 0) {
+	   acl_abort(acl, new);
+	   return(-1);
+       }
+    /* It isn't there yet, copy the file and put it in */
+    for(i = 0; i < acl_cache[idx].acl->size; i++) {
+	if(acl_cache[idx].acl->tbl[i] != NULL) {
+	    if(fputs(acl_cache[idx].acl->tbl[i], new) == EOF
+	       || putc('\n', new) != '\n') {
+		   acl_abort(acl, new);
+		   return(-1);
+	       }
+	}
+    }
+    fputs(canon, new);
+    putc('\n', new);
+    return(acl_commit(acl, new));
+}
+
+/* Removes principal from acl */
+/* Wildcards are interpreted literally */
+int
+acl_delete(char *acl, char *principal)
+{
+    int idx;
+    int i;
+    FILE *new;
+    char canon[MAX_PRINCIPAL_SIZE];
+
+    acl_canonicalize_principal(principal, canon);
+
+    if((new = acl_lock_file(acl)) == NULL) return(-1);
+    if((!acl_exact_match(acl, canon))
+       || (idx = acl_load(acl)) < 0) {
+	   acl_abort(acl, new);
+	   return(-1);
+       }
+    /* It isn't there yet, copy the file and put it in */
+    for(i = 0; i < acl_cache[idx].acl->size; i++) {
+	if(acl_cache[idx].acl->tbl[i] != NULL
+	   && strcmp(acl_cache[idx].acl->tbl[i], canon)) {
+	       fputs(acl_cache[idx].acl->tbl[i], new);
+	       putc('\n', new);
+	}
+    }
+    return(acl_commit(acl, new));
+}
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.