60643d379b
(Including all changes for FreeBSD - importing the original eBones distribution would be too complex at this stage, since I don't have access to Piero's CVS.) (If you want to include eBones in your system, don't forget to include MAKE_EBONES in /etc/make.conf.) (This stuff is now also suppable from braae.ru.ac.za.) Bones originally from MIT SIPB. Original port to FreeBSD 1.x by Piero Serini. Moved to FreeBSD 2.0 by Doug Rabson and Geoff Rehmet. Nice bug fixes from Doug Rabson.
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.
|