acl_canonicalize_principal,   acl_check,  acl_exact_match,
       acl_add, acl_delete, acl_initialize - Access control  list
       routines

SYNOPSIS

       cc <files> -lacl -lkrb

       #include <krb.h>

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

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

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

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

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

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

DESCRIPTION

   Introduction
       An  access  control  list  (ACL)  is a list of principals,
       where each principal 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 file-
       names, and refer to human-readable files; in  the  future,
       when  a networked ACL server is implemented, the names may
       refer to a different namespace specific to  the  ACL  ser-
       vice.

   Principal Names
       Principal names have the form
            <name>[.<instance>][@<realm>]
       e.g.:
            asp@ATHENA.MIT.EDU
            asp.@ATHENA.MIT.EDU
            asp.root@ATHENA.MIT.EDU
       It is possible for principals to be underspecified.  If an
       instance is missing, it is assumed to be "".  If realm  is
       missing, it is assumed to be the local realm as determined
       by krb_get_lrealm(3).  The canonical form contains all  of
       name, instance, and realm; the acl_add and acl_delete rou-
       tines 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 stores 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 as ANAME_SZ, INST_SZ, and
       REALM_SZ, respectively, in /usr/include/krb.h.

       acl_check 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.  The only sup-
       ported wildcards are entries  of  the  form  name.*@realm,
       *.*@realm,  and  *.*@*.  An asterisk matches any value for
       the its component field.  For example, "jtkohl.*@*"  would
       match principal jtkohl, with any instance and any realm.

       acl_exact_match  performs  like  acl_check,  but  does  no
       canonicalization or wildcard matching.

       acl_add 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 canoni-
       calize principal, but will treat wildcards literally.

       acl_delete atomically deletes principal from acl.  Returns
       0 if successful, nonzero otherwise.  It  is  considered  a
       failure  if principal is not already in acl.  This routine
       will canonicalize principal, but will treat wildcards lit-
       erally.

       acl_initialize initializes acl_file.  If the file acl_file
       does not exist, acl_initialize creates it with mode  mode.
       If  the  file  acl_file exists, acl_initialize removes all
       members.  Returns  0  if  successful,  nonzero  otherwise.
       WARNING:  Mode argument is likely to change with the even-
       tual introduction of an ACL service.

NOTES

       In the presence of concurrency,  there  is  a  very  small
       chance  that  acl_add  or  acl_delete could report success
       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.

SEE ALSO

       kerberos(3), krb_get_lrealm(3)

AUTHOR

       James Aspnes (MIT Project Athena)