crypto/kerberosIV/man/acl_check.3

   1 .\" $Id: acl_check.3,v 1.2 1996/06/12 21:29:08 bg Exp $
   2 .\" Copyright 1989 by the Massachusetts Institute of Technology.
   3 .\"
   4 .\" For copying and distribution information,
   5 .\" please see the file <mit-copyright.h>.
   6 .\"
   7 .TH ACL_CHECK 3 "Kerberos Version 4.0" "MIT Project Athena"
   8 .SH NAME
   9 acl_canonicalize_principal, acl_check, acl_exact_match, acl_add,
  10 acl_delete, acl_initialize \- Access control list routines
  11 .SH SYNOPSIS
  12 .nf
  13 .nj
  14 .ft B
  15 cc <files> \-lacl \-lkrb
  16 .PP
  17 .ft B
  18 #include <krb.h>
  19 .PP
  20 .ft B
  21 acl_canonicalize_principal(principal, buf)
  22 char *principal;
  23 char *buf;
  24 .PP
  25 .ft B
  26 acl_check(acl, principal)
  27 char *acl;
  28 char *principal;
  29 .PP
  30 .ft B
  31 acl_exact_match(acl, principal)
  32 char *acl;
  33 char *principal;
  34 .PP
  35 .ft B
  36 acl_add(acl, principal)
  37 char *acl;
  38 char *principal;
  39 .PP
  40 .ft B
  41 acl_delete(acl, principal)
  42 char *acl;
  43 char *principal;
  44 .PP
  45 .ft B
  46 acl_initialize(acl_file, mode)
  47 char *acl_file;
  48 int mode;
  49 .fi
  50 .ft R
  51 .SH DESCRIPTION
  52 .SS Introduction
  53 .PP
  54 An access control list (ACL) is a list of principals, where each
  55 principal is represented by a text string which cannot contain
  56 whitespace.  The library allows application programs to refer to named
  57 access control lists to test membership and to atomically add and
  58 delete principals using a natural and intuitive interface.  At
  59 present, the names of access control lists are required to be Unix
  60 filenames, and refer to human-readable Unix files; in the future, when
  61 a networked ACL server is implemented, the names may refer to a
  62 different namespace specific to the ACL service.
  63 .PP
  64 .SS Principal Names
  65 .PP
  66 Principal names have the form
  67 .nf
  68 .in +5n
  69 <name>[.<instance>][@<realm>]
  70 .in -5n
  71 e.g.:
  72 .in +5n
  73 asp
  74 asp.root
  75 asp@ATHENA.MIT.EDU
  76 asp.@ATHENA.MIT.EDU
  77 asp.root@ATHENA.MIT.EDU
  78 .in -5n
  79 .fi
  80 It is possible for principals to be underspecified.  If an instance is
  81 missing, it is assumed to be "".  If realm is missing, it is assumed
  82 to be the local realm as determined by
  83 .IR krb_get_lrealm (3).
  84 The canonical form contains all of name, instance,
  85 and realm; the acl_add and acl_delete routines will always
  86 leave the file in that form.  Note that the canonical form of
  87 asp@ATHENA.MIT.EDU is actually asp.@ATHENA.MIT.EDU.
  88 .SS Routines
  89 .PP
  90 .I acl_canonicalize_principal
  91 stores the canonical form of
  92 .I principal
  93 in
  94 .IR buf .
  95 .I Buf
  96 must contain enough
  97 space to store a principal, given the limits on the sizes of name,
  98 instance, and realm specified as ANAME_SZ, INST_SZ, and REALM_SZ,
  99 respectively, in
 100 .IR /usr/include/krb.h .
 101 .PP
 102 .I acl_check
 103 returns nonzero if
 104 .I principal
 105 appears in
 106 .IR acl .
 107 Returns 0 if principal
 108 does not appear in acl, or if an error occurs.  Canonicalizes
 109 principal before checking, and allows the ACL to contain wildcards.  The
 110 only supported wildcards are entries of the form
 111 name.*@realm, *.*@realm, and *.*@*.  An asterisk matches any value for the
 112 its component field.  For example, "jtkohl.*@*" would match principal
 113 jtkohl, with any instance and any realm.
 114 .PP
 115 .I acl_exact_match
 116 performs like
 117 .IR acl_check ,
 118 but does no canonicalization or wildcard matching.
 119 .PP
 120 .I acl_add
 121 atomically adds
 122 .I principal
 123 to
 124 .IR acl .
 125 Returns 0 if successful, nonzero otherwise.  It is considered a failure
 126 if
 127 .I principal
 128 is already in
 129 .IR acl .
 130 This routine will canonicalize
 131 .IR principal ,
 132 but will treat wildcards literally.
 133 .PP
 134 .I acl_delete
 135 atomically deletes
 136 .I principal
 137 from
 138 .IR acl .
 139 Returns 0 if successful,
 140 nonzero otherwise.  It is considered a failure if
 141 .I principal
 142 is not
 143 already in
 144 .IR acl .
 145 This routine will canonicalize
 146 .IR principal ,
 147 but will treat wildcards literally.
 148 .PP
 149 .I acl_initialize
 150 initializes
 151 .IR acl_file .
 152 If the file
 153 .I acl_file
 154 does not exist,
 155 .I acl_initialize
 156 creates it with mode
 157 .IR mode .
 158 If the file
 159 .I acl_file
 160 exists,
 161 .I acl_initialize
 162 removes all members.  Returns 0 if successful,
 163 nonzero otherwise.  WARNING: Mode argument is likely to change with
 164 the eventual introduction of an ACL service.
 165 .SH NOTES
 166 In the presence of concurrency, there is a very small chance that
 167 .I acl_add
 168 or
 169 .I acl_delete
 170 could report success even though it would have
 171 had no effect.  This is a necessary side effect of using lock files
 172 for concurrency control rather than flock(2), which is not supported
 173 by NFS.
 174 .PP
 175 The current implementation caches ACLs in memory in a hash-table
 176 format for increased efficiency in checking membership; one effect of
 177 the caching scheme is that one file descriptor will be kept open for
 178 each ACL cached, up to a maximum of 8.
 179 .SH SEE ALSO
 180 kerberos(3), krb_get_lrealm(3)
 181 .SH AUTHOR
 182 James Aspnes (MIT Project Athena)