*** UNIX MANUAL PAGE BROWSER ***

acl(4) Kernel Interfaces Manual acl(4) NAME acl - Access control list DESCRIPTION The DIGITAL UNIX ACLs are based on the POSIX P1003.6 Draft 13 standard. ACL functionality and interfaces may change as the P1003.6 standard is finalized. Traditionally, UNIX systems control a user's access to files and directories (filesystem objects) using a method of discre- tionary access control (DAC) normally referred to as the permission bits. By default, DIGITAL UNIX systems are run using this untrusted method of DAC for filesystem objects. This default DAC defines the categories 'owning user', 'owning group', and 'other', as attributes of these objects, and associates a set of access permissions with each of the categories. ACLs provide greater granularity of filesystem object protection than the default DIGITAL UNIX DAC. The level of filesystem object protec- tion provided by ACLs is required by trusted systems, but ACLs can be enabled separately from the other security options. This allows you to tailor your system to use only the security options that you need, in- stead of having to setup a fully trusted system. With ACLs enabled, an access control list (ACL) is associated with a file or directory. The ACL is an extended file attribute stored in the file or directory's property List. The ACL provides the access permis- sion categories normally supplied by the default DAC and also provides discretionary access permissions on individually specified users and groups. Extended in this manner, DAC is compatible with system calls such as chown(), chgrp(), chmod(), stat(), and open(), which use exist- ing interfaces to retrieve and manipulate access permission bits. To be granted the set of permissions associated with one of the ACL user categories above, a process "identifies" itself through its effec- tive user ID (UID) or its set of group IDs (an effective GID with op- tional supplementary GIDs) as belonging to that category. Also, the permissions requested by the process must be a subset of the permis- sions associated with the category. Discretionary access control with ACLs consists of an ACL initializa- tion that accompanies object creation, DAC access checking, functions and system calls for ACL retrieval and manipulation, format conversion, validity checking, and storage management. This extended version of DAC includes the library functions, system calls, and commands for ma- nipulating ACLs. The following functions retrieve and manipulate ACL entries: acl_copy_entry() acl_create_entry() acl_delete_entry() acl_first_entry() acl_get_entry() The following functions re- trieve and manipulate fields in an ACL entry: acl_add_perm() acl_clear_perm() acl_delete_perm() acl_get_permset() acl_get_qualifier() acl_get_tag_type() acl_set_permset() acl_set_qualifier() acl_set_tag_type() The following functions manage working storage for ACL manipulation: acl_free() acl_free_qualifier() acl_free_text() acl_init() acl_copy_ext() acl_copy_int() acl_dup() acl_size() The following functions validate and convert ACLs: acl_valid() acl_delete_def_fd() acl_delete_def_file() acl_get_fd() acl_get_file() acl_set_fd() acl_set_file() The following functions perform format conversion between external and internal representations of an ACL: acl_from_text() acl_to_text() The following commands display and change the contents of an ACL: Changes an ACL on a file or direc- tory. Displays an ACL on a file or directory. Types of ACLs The access ACL can be associated with any filesystem object and con- trols the access permissions to the object. The default access ACL is associated only with directories. It is in- herited as the access ACL by all non-directory objects created within the directory containing the default access ACL. If there is no de- fault directory ACL associated with the directory, directories that are created inherit the default access ACL as both its access and default access ACL. Otherwise, it is inherited as the default access ACL. The default directory ACL is inherited as the access ACL for directo- ries that are created within a directory having the default directory ACL type. ACL Entries A valid ACL entry consists of the following fields: Tag type (defined in the acl.h header file): ACL_USER_OBJ The owning user entry. ACL_GROUP_OBJ The owning group entry. ACL_USER An entry for other users. ACL_GROUP An entry for other groups. ACL_OTHER_OBJ The entry for all users and groups that are not included in another entry. Tag qualifier The qualifier value for a ACL_USER entry is a user ID. The qualifier value for a ACL_GROUP entry is a group ID. The qualifier value for any of the *_OBJ entries is NULL. Permissions field The set of access permissions must include, at min- imum: read, write, execute/search, or a no-access place holder for one or more of the above permis- sions. Users normally specify ACLs with the setacl command. Contents of an ACL A valid ACL must meet the following requirements: Exactly one ACL_USER_OBJ, ACL_GROUP_OBJ, and ACL_OTHER_OBJ, must be present in the ACL. This is the minimum requirement. Entries can be entered in any order with setacl. They need not correspond to the order displayed by getacl. An ACL must be specified as either an access, a default ac- cess, or a default directory ACL. A default ACL is associated with a directory only. A default ACL may be empty or have the minimum three entries; an access ACL must have the minimum three entries. A tag qualifier must be unique for a given tag type. An entry duplicates an- other entry in the same ACL if they match in tag type and tag quali- fier, regardless of permissions. ACL Formats An ACL has two internal and one external representation. The external representation consists of text and is used to enter and display ACLs. Library routines manipulate ACLs in working storage in an internal rep- resentation that is only indirectly accessible to the calling routine. This internal representation can be interpreted with the acl.h header file. The other internal representation is a data (binary) package, which consists of ACL entries only, and is in packed format, without padding. ACL entry contents can be converted to exportable text or contiguous persistent binary. Backward Compatibility The extended DAC affects these commands, system and library calls as follows: The chmod command updates the contents of the ACL to match the new mode being set on the object. If the chgrp command changes the owning group's ID to one that is currently qualifying a ACL_GROUP en- try, the permissions set for both entries remain unchanged. The effec- tive access of either entry, however, results from the union of all permissions from entries of the file group class. The acl_to_text() and acl_from_text() functions convert between the ACL data package rep- resentation and the text representation. ACL Initialization An ACL is initialized by any of the following system calls and commands that create a file or a directory: The creat() system call The open() system call with the O_CREATE flag The mkdir command The mkfifo com- mand, which creates a pipe that is managed as a file When a file or directory is created, the default access ACL of its par- ent directory automatically initializes a new ACL, as summarized in the Default ACLs section. If a default access ACL does not exist, the un- trusted method of initializing an object's DAC attributes automatically applies. Briefly, this method logically ANDs the complement of a process's umask, if one exists, with the mode parameter (the permis- sions parameter, which is supplied by any of the object creation func- tions mentioned above). The result of complementation and ANDing auto- matically initializes permission fields associated with the required entries, as follows: The leftmost three bits set the ACL_USER_OBJ en- try. The middle three bits set the ACL_GROUP_OBJ entry. The remaining three bits set the ACL_OTHER_OBJ entry. No other ACL entries can be initialized without default access ACLs. For a description of a process umask, see the umask(2) reference page. Default ACLs An optional, per-directory default access ACL automatically initializes an access ACL for a newly created non-directory object. If the newly created object is a directory, it inherits its access ACL from its parent directory; otherwise, its access ACL is initialized by the untrusted methods for initializing an access ACL on a file. If the parent directory has a default access ACL, the new directory inherits the parent's default ACL as its default access ACL. A default access ACL has the same minimum required entries as an access ACL. A default access ACL may also be empty of any entries. A default ACL's entries are manipulated by the same commands and functions as ac- cess ACLs. The default access ACL is used only to initialize ACLs and is not used by the DAC access checking mechanism to check the access on an object. Upon object creation, an existing default access ACL is automatically copied to a new object's ACL and sets its contents. Permissions from any of the *_OBJ entries in the the default access ACL automatically interact with the object mode parameter (specified by the object cre- ation system calls referred to earlier) as follows: The permission bits of ACL_USER_OBJ are set to the intersection of this same entry's per- mission bits from the default access ACL with the owner bits from the mode parameter. The permission bits of ACL_OTHER_OBJ are set to the intersection of this same entry's permission bits from the default ac- cess ACL with the other bits from the mode parameter. The permission bits of ACL_GROUP_OBJ are set to the intersection of this same entry's permission bits from the default access ACL with the group bits from the mode parameter. DAC Access Checking The stat structure should not be used to determine accessability of an object. On local filesystems, read-only mounts and ACLs can both mod- ify the access that is allowed. On remote filesystems, in addition to read-only mounts and ACLs, there may also be additional controls that alter the permitted access, such as: ID mapping Mandatory access con- trol Additional authentication requirements The access() call should be used to do DAC access checking on an object. DAC access checking combines untrusted file attribute information with ACLs in checking access to an object. The checking algorithm checks ACL entries in the following order, regardless of how the ACL entries are ordered: 1. ACL_USER_OBJ entry 2. ACL_USER entries 3. ACL_GROUP_OBJ entry 4. ACL_GROUP entries 5. ACL_OTHER_OBJ entry The first occurrence of a match determines which set of permissions governs a process's access to an object. For example, if a process's effective uid and gid both match entries in the ACL, the process's access is governed by the set of permissions associated with the matching UID entry in the ACL. This ordering also means, for example, that if a process's effective UID matches both ACL_USER_OBJ and a ACL_USER entry, the process's access is governed by the permissions associated with the ACL_USER_OBJ entry. The checking algorithm is as follows: Check the process's effective UID against the UID of the owning user. If there is a match, check each of the requested permissions against the permissions of the matching ACL entry. If the requested permissions are a subset of the associated permissions, grant the request. If not, deny the request. If the process's effective UID does not match against the UID of the owning user entry, ACL_USER_OBJ, check the effective UID against the UID of every non-owning user entry, ACL_USER. If the process's effective GID or any of the supplementary GID values does not match against the GID of the owning group entry, ACL_GROUP_OBJ, check the effective GID against the GID of every non-owning group entry, ACL_GROUP. If the re- quested permissions are a subset of this intersection, grant the re- quest. If not, deny the request. Finally, if neither the process's effective GID nor any of the supplementary GID values match to any of the GID values contained in any of the group entries, check each of the requested permissions against the permissions of the other entry, ACL_OTHER_OBJ. If the requested permissions are a subset of the per- missions associated with the matching entry, grant the request. If not, deny the request. NFS Flatten Mode The NFS flatten mode (nfs-flatten-mode) controls the permission bits of a file with ACLS as seen by an NFS V2 client. NFS V2 clients make their own access decisions based on their interpre- tation of a file's mode bits. Based on this decision, they may allow access to data cached on the client from a previous access by another user. A file that is protected by an ACL can not reflect the correct access for all users in the access bits for the file. It may be that access that would be granted by the mode bits is actually denied ex- plicitly by the ACL. It may also be that access that seems to be de- nied by the mode bits is, in fact, granted explicitly by the mode bits. The nfs-flatten-mode parameter can be used to modify the bits that ex- ist on the server before presentation to the client. NFS V3 clients have, in essence, an "open" protocol request that they use to defer the access decision to the server, and grants access only when they have previously made an "open" request for the same user and file. Setting the nfs-flatten-mode parameter to the restrictive setting (1) can cause some users to be denied access to files that they should le- gitimately be granted access to. Setting the parameter to the permis- sive setting (2) can cause some users to be granted access to files that they should not be granted access to, but only for read access to data in the client cache, since any request that is sent to the server (and all write requests are supposed to be sent to the server) results in an access decision on the server denying the request. Setting the parameter to the unmodified setting (0) leaves the mode bits unmodi- fied, possibly resulting in both inadvertent denial and granting of ac- cess, while accurately displaying the bits on the client as they would be displayed on the server. The allowable values are: 0 - unmodified The actual file mode is sent. 1 - restrictive The group and other fields of the file mode are modified such that only access that would be granted to everyone in the ACL is granted by the mode bits. 2 - permissive The group and other bits are modified such that access that is granted to anyone in the ACL is granted in the mode bits. The default value is 0. RELATED INFORMATION Security Commands: setacl(1), chgrp(1), chmod(1), chown(1), getacl(1) Functions: acl_add_perm(3) acl_clear_perm(3) acl_copy_entry(3) acl_copy_ext(3) acl_copy_int(3) acl_create_entry(3) acl_delete_def_fd(3) acl_delete_def_file(3) acl_delete_entry(3) acl_delete_perm(3) acl_dup(3) acl_first_entry(3) acl_free(3) acl_free_qualifier(3) acl_free_text(3) acl_from_text(3) acl_get_entry(3) acl_get_fd(3) acl_get_file(3) acl_get_permset(3) acl_get_qualifier(3) acl_get_tag_type(3) acl_init(3) acl_set_fd(3) acl_set_file(3) acl_set_permset(3) acl_set_qualifier(3) acl_set_tag_type(3) acl_size(3) acl_to_text(3) acl_valid(3) Files: proplist(4) delim off acl(4)