diff options
Diffstat (limited to 'kerberosIV/acl/acl_check.3')
| -rw-r--r-- | kerberosIV/acl/acl_check.3 | 182 |
1 files changed, 182 insertions, 0 deletions
diff --git a/kerberosIV/acl/acl_check.3 b/kerberosIV/acl/acl_check.3 new file mode 100644 index 00000000000..c1e57741cfc --- /dev/null +++ b/kerberosIV/acl/acl_check.3 @@ -0,0 +1,182 @@ +.\" Copyright 1989 by the Massachusetts Institute of Technology. +.\" +.\" For copying and distribution information, +.\" please see the file <mit-copyright.h>. +.\" +.\" $Id: acl_check.3,v 1.1 1995/12/14 06:52:36 tholo Exp $ +.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) |