108 lines
3.2 KiB
Plaintext
108 lines
3.2 KiB
Plaintext
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.
|