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 $
|
||
|
|
.\" $Id: acl_check.3,v 1.2 1994/07/19 19:27:17 g89r4222 Exp $
|
||
|
|
.\" 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 <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/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)
|