home *** CD-ROM | disk | FTP | other *** search
/ InfoMagic Source Code 1993 July / THE_SOURCE_CODE_CD_ROM.iso / bsd_srcs / kerberosIV / acl / acl_files.doc < prev    next >
Encoding:
Text File  |  1987-07-14  |  3.2 KB  |  108 lines
  1. PROTOTYPE ACL LIBRARY
  2.  
  3. Introduction
  4.     
  5. An access control list (ACL) is a list of principals, where each
  6. principal is is represented by a text string which cannot contain
  7. whitespace.  The library allows application programs to refer to named
  8. access control lists to test membership and to atomically add and
  9. delete principals using a natural and intuitive interface.  At
  10. present, the names of access control lists are required to be Unix
  11. filenames, and refer to human-readable Unix files; in the future, when
  12. a networked ACL server is implemented, the names may refer to a
  13. different namespace specific to the ACL service.
  14.  
  15.  
  16. Usage
  17.  
  18. cc <files> -lacl -lkrb.
  19.  
  20.  
  21.  
  22. Principal Names
  23.  
  24. Principal names have the form
  25.  
  26. <name>[.<instance>][@<realm>]
  27.  
  28. e.g.
  29.  
  30. asp
  31. asp.root
  32. asp@ATHENA.MIT.EDU
  33. asp.@ATHENA.MIT.EDU
  34. asp.root@ATHENA.MIT.EDU
  35.  
  36. It is possible for principals to be underspecified.  If instance is
  37. missing, it is assumed to be "".  If realm is missing, it is assumed
  38. to be local_realm.  The canonical form contains all of name, instance,
  39. and realm; the acl_add and acl_delete routines will always
  40. leave the file in that form.  Note that the canonical form of
  41. asp@ATHENA.MIT.EDU is actually asp.@ATHENA.MIT.EDU.
  42.  
  43.  
  44. Routines
  45.  
  46. acl_canonicalize_principal(principal, buf)
  47. char *principal;
  48. char *buf;      /*RETVAL*/
  49.  
  50. Store the canonical form of principal in buf.  Buf must contain enough
  51. space to store a principal, given the limits on the sizes of name,
  52. instance, and realm specified in /usr/include/krb.h.
  53.  
  54. acl_check(acl, principal)
  55. char *acl;
  56. char *principal;
  57.  
  58. Returns nonzero if principal appears in acl.  Returns 0 if principal
  59. does not appear in acl, or if an error occurs.  Canonicalizes
  60. principal before checking, and allows the ACL to contain wildcards.
  61.  
  62. acl_exact_match(acl, principal)
  63. char *acl;
  64. char *principal;
  65.  
  66. Like acl_check, but does no canonicalization or wildcarding.
  67.  
  68. acl_add(acl, principal)
  69. char *acl;
  70. char *principal;
  71.  
  72. Atomically adds principal to acl.  Returns 0 if successful, nonzero
  73. otherwise.  It is considered a failure if principal is already in acl.
  74. This routine will canonicalize principal, but will treat wildcards
  75. literally.
  76.  
  77. acl_delete(acl, principal)
  78. char *acl;
  79. char *principal;
  80.  
  81. Atomically deletes principal from acl.  Returns 0 if successful,
  82. nonzero otherwise.  It is consider a failure if principal is not
  83. already in acl.  This routine will canonicalize principal, but will
  84. treat wildcards literally.
  85.  
  86. acl_initialize(acl, mode)
  87. char *acl;
  88. int mode;
  89.  
  90. Initialize acl.  If acl file does not exist, creates it with mode
  91. mode.  If acl exists, removes all members.  Returns 0 if successful,
  92. nonzero otherwise.  WARNING: Mode argument is likely to change with
  93. the eventual introduction of an ACL service.  
  94.  
  95.  
  96. Known problems
  97.  
  98. In the presence of concurrency, there is a very small chance that
  99. acl_add or acl_delete could report success even though it would have
  100. had no effect.  This is a necessary side effect of using lock files
  101. for concurrency control rather than flock(2), which is not supported
  102. by NFS.
  103.  
  104. The current implementation caches ACLs in memory in a hash-table
  105. format for increased efficiency in checking membership; one effect of
  106. the caching scheme is that one file descriptor will be kept open for
  107. each ACL cached, up to a maximum of 8.
  108.