ACL_CHECK(3)                                         ACL_CHECK(3)


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



SYNOPSIS
       cc <files> -lacl -lkrb

       #include <kerberosIV/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 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.


   Principal Names
       Principal names have the form
            <name>[.<instance>][@<realm>]
       e.g.:
            asp



MIT Project Athena     Kerberos Version 4.0                     1





ACL_CHECK(3)                                         ACL_CHECK(3)


            asp.root
            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/kerberosIV/ker-
       berosIV/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



MIT Project Athena     Kerberos Version 4.0                     2





ACL_CHECK(3)                                         ACL_CHECK(3)


       even though it would have had no effect.  This is a neces-
       sary side effect of using lock files for concurrency  con-
       trol  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)










































MIT Project Athena     Kerberos Version 4.0                     3