.\" .\" This source code is no longer held under any constraint of USA .\" `cryptographic laws' since it was exported legally. The cryptographic .\" functions were removed from the code and a "Bones" distribution was .\" made. A Commodity Jurisdiction Request #012-94 was filed with the .\" USA State Department, who handed it to the Commerce department. The .\" code was determined to fall under General License GTDA under ECCN 5D96G, .\" and hence exportable. The cryptographic interfaces were re-added by Eric .\" Young, and then KTH proceeded to maintain the code in the free world. .\" .\"Copyright (C) 1989 by the Massachusetts Institute of Technology .\" .\"Export of this software from the United States of America is assumed .\"to require a specific license from the United States Government. .\"It is the responsibility of any person or organization contemplating .\"export to obtain such a license before exporting. .\" .\"WITHIN THAT CONSTRAINT, permission to use, copy, modify, and .\"distribute this software and its documentation for any purpose and .\"without fee is hereby granted, provided that the above copyright .\"notice appear in all copies and that both that copyright notice and .\"this permission notice appear in supporting documentation, and that .\"the name of M.I.T. not be used in advertising or publicity pertaining .\"to distribution of the software without specific, written prior .\"permission. M.I.T. makes no representations about the suitability of .\"this software for any purpose. It is provided "as is" without express .\"or implied warranty. .\" .\" $OpenBSD: acl_check.3,v 1.4 1998/02/25 15:50:28 art 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 \-lacl \-lkrb .PP .ft B #include .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 [.][@] .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/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)