1130b656e5
This will make a number of things easier in the future, as well as (finally!) avoiding the Id-smashing problem which has plagued developers for so long. Boy, I'm glad we're not using sup anymore. This update would have been insane otherwise.
184 lines
4.5 KiB
Groff
184 lines
4.5 KiB
Groff
.\" from: acl_check.3,v 4.1 89/01/23 11:06:54 jtkohl Exp $
|
|
.\" $FreeBSD$
|
|
.\" Copyright 1989 by the Massachusetts Institute of Technology.
|
|
.\"
|
|
.\" For copying and distribution information,
|
|
.\" please see the file <Copyright.MIT>.
|
|
.\"
|
|
.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/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/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)
|