Return to acl_files.doc CVS log

Up to [CSRG BSD Unix] / 43BSDReno / kerberosIV / acl

Annotation of 43BSDReno/kerberosIV/acl/acl_files.doc, revision 1.1

1.1     ! root        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: [email protected]
        !            33: [email protected]
        !            34: [email protected]
        !            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: [email protected] is actually [email protected].
        !            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.

This archive runs on limited infrastructure. Preserving old code on modern bandwidth. Automated agents are requested to crawl responsibly.