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 <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 prin‐
cipal is represented by a text string which cannot contain whitespace.
The library allows application programs to refer to named access con‐
trol lists to test membership and to atomically add and delete princi‐
pals 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
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 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 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 supported wildcards are entries of the form name.*@realm,
*.*@realm, and *.*@*. An asterisk matches any value for 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 canonicalize principal, but will treat wild‐
cards literally.
acl_delete atomically deletes principal from acl. Returns 0 if suc‐
cessful, nonzero otherwise. It is considered a failure if principal is
not already in acl. This routine will canonicalize principal, but will
treat wildcards literally.
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
eventual 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 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.
SEE ALSOkerberos(3), krb_get_lrealm(3)AUTHOR
James Aspnes (MIT Project Athena)
MIT Project Athena Kerberos Version 4.0 ACL_CHECK(3)
