.\" Copyright 1989 by the Massachusetts Institute of Technology.
.\"
.\" For copying and distribution information,
.\" please see the file <mit-copyright.h>.
.\"
.\"	$OpenBSD: acl_check.3,v 1.2 1997/05/30 03:11:15 gene Exp $
.TH ACL_CHECK 3 "Kerberos Version 4.0" "MIT Project Athena"
.SH NAME
acl_canonicalize_principal, acl_check, acl_exact_match, acl_add,
acl_delete, acl_initialize \- Access control list routines
.SH SYNOPSIS
.nf
.nj
.ft B
cc <files> \-lacl \-lkrb
.PP
.ft B
#include <kerberosIV/kerberosIV/krb.h>
.PP
.ft B
acl_canonicalize_principal(principal, buf)
char *principal;
char *buf;
.PP
.ft B
acl_check(acl, principal)
char *acl;
char *principal;
.PP
.ft B
acl_exact_match(acl, principal)
char *acl;
char *principal;
.PP
.ft B
acl_add(acl, principal)
char *acl;
char *principal;
.PP
.ft B
acl_delete(acl, principal)
char *acl;
char *principal;
.PP
.ft B
acl_initialize(acl_file, mode)
char *acl_file;
int mode;
.fi
.ft R
.SH DESCRIPTION
.SS Introduction
.PP
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.
.PP
.SS Principal Names
.PP
Principal names have the form
.nf
.in +5n
<name>[.<instance>][@<realm>]
.in -5n
e.g.:
.in +5n
asp
asp.root
asp@ATHENA.MIT.EDU
asp.@ATHENA.MIT.EDU
asp.root@ATHENA.MIT.EDU
.in -5n
.fi
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
.IR krb_get_lrealm (3).
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.
.SS Routines
.PP
.I acl_canonicalize_principal
stores the canonical form of 
.I principal
in 
.IR buf .
.I 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
.IR /usr/include/kerberosIV/kerberosIV/krb.h .
.PP
.I acl_check
returns nonzero if
.I principal
appears in 
.IR 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 supported 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.
.PP
.I acl_exact_match
performs like 
.IR acl_check ,
but does no canonicalization or wildcard matching.
.PP
.I acl_add
atomically adds 
.I principal
to 
.IR acl .
Returns 0 if successful, nonzero otherwise.  It is considered a failure
if
.I principal
is already in 
.IR acl .
This routine will canonicalize
.IR principal ,
but will treat wildcards literally.
.PP
.I acl_delete
atomically deletes 
.I principal
from 
.IR acl .
Returns 0 if successful,
nonzero otherwise.  It is considered a failure if 
.I principal
is not
already in 
.IR acl .
This routine will canonicalize 
.IR principal ,
but will treat wildcards literally.
.PP
.I acl_initialize
initializes
.IR acl_file .
If the file 
.I acl_file
does not exist,
.I acl_initialize
creates it with mode
.IR mode .
If the file
.I acl_file
exists,
.I acl_initialize
removes all members.  Returns 0 if successful,
nonzero otherwise.  WARNING: Mode argument is likely to change with
the eventual introduction of an ACL service.  
.SH NOTES
In the presence of concurrency, there is a very small chance that
.I acl_add
or
.I 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.
.PP
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.
.SH SEE ALSO
kerberos(3), krb_get_lrealm(3)
.SH AUTHOR
James Aspnes (MIT Project Athena)