acl_check(3krb)
Name
acl_check − Access control list (ACL) library routines.
Syntax
cc <files> -lacl -l krb
#include <krb.h>
acl_canonicalize_principal (principal, buf)
char*principal;
char*buf;
acl_check (acl_file, principal)
char *acl_file;
char *principal;
acl_exact_match (acl_file, principal)
char *acl_file;
char *principal;
acl_add (acl_file, principal)
char *acl_file;
char *principal;
acl_delete (acl_file, principal)
char *acl_file;
char *principal;
acl_initialize (acl_file, mode)
char *acl_file;
int mode;
kname_parse (primary_name, instance_name,
realm_name, principal)
char*primary_name;
char*instance_name;
char*realm_name;
char*principal;
Arguments
principal The name of a principal. Principal names consist of from one to three fields. The first field must be included because it stores the primary name of the principal. The second field is not always required. It begins with a period (.), and stores the instance name of the principal. The third field is not always requred. It begins with an "at" sign (@), and stores the realm name of the principal. The principal name format can be expressed as:
name[.instance][@realm]
For example, all of the names below are legitimate principal names:
venus
venus.root
venus@dec.com
venus.@dec.com
venus.root@dec.com
buf Pointer to the buffer that stores the canonical form of a principal name. The canonical form is derived from the form of a principal name. Like a principal name, it includes a primary name in its first field. Unlike a principal name, it must include an instance name as its next field even if the instance name is blank. Also, unlike a principal name, it must contain a realm field. If a canonical name is derived from a principal name that has no realm field, the local realm returned by krb_get_lrealm(3krb) is used as the realm field in the canonical name. Of the above examples, only the last two are in canonical form.
acl_file The path name of the file in which the access control list (ACL) is stored.
mode If the ACL file, acl_file, does not currently exist when acl_initialize is called, the file acl_file, is created with read, write, and access mode bits set equal to mode.
primary_name
The primary name portion of principal, returned by kname_parse. ANAME_SZ bytes of storage space must be allocated for primary_name.
instance_name
The instance name of principal, returned by kname_parse. INST_SZ bytes of storage space must be allocated for instance_name.
realm_name
The realm name of principal, returned by kname_parse. REALM_SZ bytes of storage space must be allocated for realm_name.
Description
The routines of the acl_check library allow you to perform various administrative functions on an access control list (ACL). An ACL is a list of Kerberos principals in which each principal is represented by a text string. The routines of this library allow application programs to refer to named ACLs to test whether a principal is a member of an ACL, and to add or delete principals from the ACL file.
The routines of the acl_check library are:
acl_canonicalize_principal
Stores the canonical form of the principal name pointed to by principal in the buffer pointed to by buf. This buffer must contain enough space to store a full canonical principal name (MAX_PRINCIPAL_SIZE characters). No meaningful value is returned by acl_canonicalize_principal.
acl_check
Verifies that the principal name, principal, appears in the ACL file, acl_file. This routine returns a zero (0) if the principal does not appear in the ACL, or if there is an error condition. If the principal is a member of the ACL, a one (1) is returned. The acl_check routine always canonicalizes a principal before trying to find it in the ACL. acl_check will determine if there is an ACL entry in the acl_file which exactly matches principal, principal, or if principal matches an ACL entry which contains a wildcard. A wildcard appears in place of a field name in an ACL entry and is represented as an asterisk (*). A wildcard in a field name of an ACL entry allows the ACL entry to match a principal name that contains anything in that particular field. For example, if there is an entry, venus.*@dec.com in the ACL, the principals, venus.root@dec.com, venus.@dec.com, and venus.planet@dec.com would be included in the ACL. The use of wildcards is limited, for they may be used in only the three following configurations in an ACL file:
name.*@realm
*.*@realm
*.*@*
acl_exact_match
Verifies that principal name, principal, appears in the ACL file, acl_file. This routine returns a zero (0) if the principal does not appear in the ACL, or if any error occurs. If the principal is a member of the ACL, acl_exact_match returns a non-zero. The acl_exact_match routine does not canonicalize a principal before the ACL checks are made, and it does not support wildcards. Only an exact match is acceptable. So, for example, if there is an entry, venus.*@dec.com in the ACL, only the principal venus.*@dec.com would match the ACL entry. This routine makes it easy to find ACL entries with wildcards.
acl_add
Adds the principal name, principal, to the ACL file, acl_file. This routine returns a zero (0) if it successfully adds the principal to the ACL. Otherwise, if there was an internal error, or if the principal is already in the ACL, the acl_add routine returns a non-zero value. The acl_add routine canonicalizes a principal, but treats wildcards literally.
acl_delete
Deletes the principal, principal, from the ACL file, acl_file. The routine returns a zero (0) if it successfully deletes the principal from the ACL. Otherwise, if there was an internal error or if the principal is not in the ACL, the acl_delete routine returns a non-zero value. The acl_delete routine canonicalizes a principal, but treats wildcards literally.
acl_initialize
Initializes the ACL file, acl_file. If the named acl_file does not exist, acl_initialize creates one with the permissions specified by the mode argument. If the ACL exists, acl_initialize removes all previously stored principal members of the list. This routine returns a zero (0) if successful or a nonzero if it fails.
kname_parse
parses the principal name, principal, and stores the primary name of the principal in principal_name, the instance name of the principal in instance_name, and the realm name of the principal in realm_name. kname_parse returns KNAME_FMT if the principal name is incorrectly formatted or if it is too long to be a principal name. It returns KSUCCESS if the parsing of the principal name succeeded.