5 Using ACLs

This chapter describes the access control list (ACL) features of the system and explains how to use them effectively. It also describes the structure of ACLs and the methods used to create and maintain them.

The Digital UNIX ACLs are based on the POSIX P1003.6 Draft 13 standard. The ACL API (Application Programming Interface) may change as the P1003.6 standard is finalized.

5.1 Traditional Discretionary Access Control

Discretionary access control (DAC) is a means of restricting access to objects based on the access permissions attached to the objects. The controls are discretionary in the sense that a subject with a certain access permission is capable of passing that permission (perhaps indirectly) on to any other subject. If you own a file, for example, you can allow other users to read it or write to it by changing its access permissions.

The untrusted Digital UNIX file protection model, although simple and effective, does not meet the DAC requirements for trusted systems. Many environments require more granular control over file access than that provided by the Digital UNIX discretionary protection.

See the Command and Shell User's Guide for a complete description of discretionary access control.

5.2 An Overview of ACLs

To provide access granularity down to a single user, Digital UNIX objects can be configured with an optional attribute called the Access Control List (ACL). An ACL can be associated with any file or directory on systems with file systems that support property lists. An ACL allows users to specify exactly how they want their files protected.

To allow maximum protection of files, an ACL extends the traditional protection scheme in three ways:

With separate access control specifications for each user and group. Each entry in an ACL identifies an individual user or group and associates permissions with the user or group identified.
By limiting the permissions that can be granted to individually specified users and groups.
By allowing all user and group permissions to be automatically specified upon object creation. If directory hierarchies are maintained on a per-project basis, it can be useful to establish different access controls at the directory level. You can define a default ACL for a directory, and it is inherited by files and subdirectories when they are created.

The following commands display and modify ACLs:

setacl: Changes the ACLs on files and directories.

getacl: Lists the ACLs on files and directories.

These commands are used in examples later in this chapter. Refer to the setacl(1) and getacl(1) reference pages for more detailed information. The acl(4) reference page also contains useful information about ACLs.

5.3 States of the ACL System

The system administrator can enable and disable the ACL subsystem on your machine. When the ACL subsystem is enabled, the full functionality of ACLs is available and ACL access checking is enforced (where appropriate).

If ACLs are disabled, you can still set and retrieve ACLs on file system objects and the library interfaces are still present. However, the following five ACL features are only available when ACLs are enabled:

Inheritance
Access checking
Validation of ACLs being set
Caching of ACL attributes
ACL and chmod interactions

See your system administrator to determine if ACLs are enabled on your system.

5.4 Setting an ACL

Setting an ACL is accomplished using the setacl command. The file must reside on a file system that supports the property list.

5.5 Default ACLs

Files only have a single ACL associated with them. A directory can have three ACLs associated with it. The access ACL is used similarly to the ACL on a file. But the default ACL, if it exists, determines the ACLs created for descendents of the directory.

The default directory ACL allows the owner or a privileged user to associate an ACL with a directory that is to be inherited as an access ACL when a subdirectory is created. The default directory ACL will also be inherited as the default directory ACL by the new directory.

The default access ACL allows the owner or a privileged user to associate an ACL with a directory that is to be inherited as an access ACL when an object is created within the directory. If the object being created is a directory and a default directory ACL exists on the parent directory, it is inherited as the access ACL and not the default access ACL. The default access ACL is inherited as the default access ACL for any subdirectory created

5.6 Viewing an ACL

An ACL is viewed by using the getacl command. If there is no ACL associated with the object, the standard UNIX permission bits are shown in the ACL format.

5.7 Access Decision Process

Access decisions for objects are made as follows:

If the process has the superuser privilege, access to the object is granted.
If ACLs are not enabled, or they are enabled but there is not an ACL associated with the object, the traditional UNIX permission checks are used.
The ACL is checked as follows:
1. If the process is the owner of the object, the permissions in the owning user:: entry are granted.
2. If the UID of the process matches a UID listed in a user: entry or resolves to a username listed in a user: entry, the permissions in the entry are granted.
3. If the GID of the process matches the GID of the file, or if one of the supplementary groups of the process matches the GID of the file, the permissions of the group:: entry are granted.
4. If the GID or supplementary groups of the process match any of the group: entries, the union of the permissions of all matching entries is granted.
5. The permissions in the other: entry are granted.

Note that the permissions on the object are the permissions allowed by the first matching user or group entry or the other entry.

5.8 ACL Structure

An access control list consists of a number of ACL entries, each of which contains three fields, as follows:

A keyword identifying the entry type
A group or user ID or name
A permission specification

In the external representation of an ACL, the fields are separated by colons (:). Entries in the qualifier field are separated by commas (,). The following example shows typical ACL entries:

user::rwx
user:juanita:r-w
user:sam:r-x
group::rwx
other::---

The keywords and qualifiers are as follows:

user: A user entry with a NULL qualifier field defines the permissions of the user who owns the file. This entry (called an owning-user entry) corresponds to the user permission bits. The qualifiers for a user entry can be user names or numeric UIDs; such an entry defines the permissions of these users. An ACL must contain an owning user entry and can contain any number of qualified user entries.

group: A group entry with a NULL qualifier field defines the permissions of members of the group that owns the file. This entry (called an owning-group entry) corresponds to the group permission bits. The qualifiers for a group entry can be group names or numeric GIDs; such an entry defines the permissions of members of these groups. An ACL must contain an owning group entry and can contain any number of qualified group entries.

other: The other entry defines the permission of all users who are not identified in a user or group entry. This entry corresponds to the other permission bits. An ACL has only one other entry.

The characters in the permissions field are the same as the characters the ls command displays for the traditional permission bits and are in the same order: r for read access, w for write access, and x for execute or search access. When a hyphen (-) character is used in place of one of the other characters, it indicates denial of that access.

Because the discretionary check against the ACL requires a match against one of the ACL entries in order for access to succeed, an object with an ACL having no entries that match the process's access request denies all accesses unless the requesting process has the ability to override discretionary access control checks.

Table 5-1 illustrates and explains typical ACL entries.

Table 5-1: Example ACL Entries

Entry	Matching Criteria
`group:acct:r--`	Matches all users in group `acct` and grants read permission.
`user:joe:rw-`	Matches user `joe` and grants read and write permission.
`user::rwx`	Matches owner of object, even if owner changes after the file is created, and grants read, write, and execute permission.
`group::r--`	Matches owning group of object, even if owning group changes after the file is created, and grants read permission.
`other::r--`	Matches all users and all groups except the owning user and group and any other users and groups listed in ACL entries. Grants read permission.

5.9 ACL Initialization

When a file or directory is created, the owner and group are set in the same manner as without ACLs. The owner is set to the owner of the process creating the file. The group is set to the group of the parent directory if the moun option grpid is set on the file system. If the directory is set setgid, then the directory's gid is always used. If the directory is not setgid and the nogrpid option is set, then the egid of the process is used. In addition, the file or directory inherits ACLs from its parent directory. A file only has one ACL associated with it, an access ACL. A directory can have three, an access ACL, a default access ACL, and a default directory ACL. The default ACLs determine what ACLs are inherited by the descendents of the directory, as follows:

If the parent directory does not have a default access ACL, the access ACL on new files in that directory is initialized from the traditional permission bits.
If the parent directory does not have any default ACLs, the access ACL on new subdirectories in that directory is initialized from the traditional permission bits. No default ACLs is set.
If the parent directory has a default access ACL, the access ACL on new files in that directory is the same as the default access ACL of the parent.
If the parent directory has a default access ACL and does not have a default directory ACL, the access ACL and default access ACL on new subdirectories in that directory are both set to the default access ACL of the parent. No default directory ACL is set.
If the parent directory does not have a default access ACL, but it does have a default directory ACL, the access ACL and default directory ACL on new subdirectories in that directory are set to the default directory ACL of the parent. No Default Access ACL is set.
If the parent directory has both a default access ACL and a default directory ACL, the access ACL and default directory ACL on new subdirectories in that directory is set to the default directory ACL of the parent. The default access ACL on new subdirectories in that directory is set to the default access ACL of the parent.

Some examples of ACL initialization follow:

Assume that the directory foo contains no default ACLs, and the following command is issued:
% setacl -d -u user:jdoe:rw- foo

Any file or directory that is created within the directory foo now inherits the following ACL as the access ACL:
```
#
# file: foo
# owner: smith
# group: system
#
user::rw-
user:jdoe:rw-
group::r--
other::r--
```
Assume that the directory foo contains no default ACLs, and the following command is issued:
% setacl -D -u user:jdoe:rwx foo

Any directory that is created within the directory foo now inherits the following ACL as the access ACL, as well as its default directory ACL:
```
#
# file: foo
# owner: smith
# group: system
#
user::rwx
user:jdoe:rwx
group::r--
other::r--
```
Assume that the directory foo contains no default ACLs, and the following commands are issued:
% setacl -D -u user:jdoe:rw- foo % setacl -d -u user:wilson:rwx foo

Any directory that is created within the directory foo now inherits the following ACL as the access ACL as well as the default directory ACL:
```
#
# file: foo
# owner: smith
# group: system
#
user::rw-
user:jdoe:rw-
group::r--
other::r--
```
The following ACL would be inherited as the default access ACL:
```
#
# file: foo
# owner: smith
# group: system
#
user::rw-
user:wilson:rwx
group::r--
other::r--
```
Any file created in directory foo now inherits the ACL as the access ACL:
```
#
# file: foo
# owner: smith
# group: system
#
user::rw-
user:wilson:rwx
group::r--
other::r--
```

At a minimum, each ACL contains three entries:

One for the owning-user
One for the owning-group
One for the other entry

These entries correspond to the traditional permission bits for the file or directory. If ACLs are enabled and you use the chmod command to change the traditional permission bits of a file or a directory, chmod also makes the appropriate changes to the ACLs for the owning user, the owning group, and the other entry.

To change the group, use the chgrp command. If you do not own the file or if you do not belong to the new group, you must become superuser to change the group name or group ID. To change the owner, use the chown command. To change the ownership of a file, you must be superuser.

5.10 Protecting Objects with ACLs

An ACL is created and initialized when an object is created. You can change the ACLs on objects that you own by using the setacl command for files and directories. These commands take as an argument ACL entries that modify the ACL on the object.

5.10.1 ACLs and the ls Command

In trusted Digital UNIX, as in traditional systems, the ls -l command displays the access allowed for the owning-user, the owning-group, and others. For the owning-user and for others, the permission displayed by ls -l and the permissions displayed by the getacl command are identical. The group permissions displayed by ls -l are the maximum permissions allowed for the owning group and for any user or group identified in a qualified user or group ACL entry. A given user or member of a group can have more restrictive permissions.

For example, assume that the following group and user entries are set in an ACL:

user::rwx
group::r-x
user:fred:r--
user:chen:rw-
group:nosy:---
other::---

The owning group has read and execute permission, and the user chen has read and write permission. The ls -l command displays the following permissions for a file with this ACL:

-rwxr-x---

5.10.2 Using the setacl Command

The setacl command is used to modify, add, and remove entries from existing ACLs.

Follow these rules for using setacl:

Specify the new attribute (that is, the ACL entries to be applied to the existing ACL, preceded by the appropriate command option, if any), followed by a list of objects to change.
Specify ACL entries between commas, if entered directly on the command line, or on separate lines if listed in an ACL input file.

The examples that follow show the setacl command line with the options, input arguments, and results of applying setacl in text format.

To set an ACL entry denying all access to the object private for user john, enter the following:
% setacl -u user:john:--- private
To set ACL entries allowing read and write access to the object private for members of the finance and marketing groups, enter the following:
% setacl -u group:finance:rw-,group:marketing:rw- private
Suppose the current ACL on the ffff file contains these entries:
```
user::r--
user:jean:r--
group::r--
other::---
```
You can update the ACL with the following command:
$ setacl -u \ group:proj1:r--,user:jean:rw-,group:finance:r-- ffff

The resulting entries are as follows:
```
user::r--
user:jean:rw-
group::r--
group:proj1:r--
group:finance:r--
other::---
```
The user:jean permissions overwrite the existing permissions for the matching user entry. Both input group entries that do not match any of the existing entries in the existing ACL are added to the ACL.

Suppose an ACL is as follows:

user::r--
group::r--
user:jean:rw-
group:proj1:r--
group:finance:r--
other::---

Use the following command to add a new permission:

$ setacl -u user:jean:rw- ffff

The resulting ACL entries are:

user::r--
group::r--
user:jean:rw-
group:proj1:r--
group:finance:r--
other::---

You can set the ACL of a file only if you own the file or you are superuser. See the setacl(1) reference page for more information.

5.10.3 Using the getacl Command

The getacl command lists the ACL on a file in a manner similar to the ls command. For all regular file name arguments, getacl lists the ACLs of the files. The -d flag lists the default ACLs. The following is an example of getacl usage:

$ getacl share_file

# # file: shared_file # owner: mary # group: marketing # user::rw- group::r-- other::---

The first user and group entries refer to the owning user and owning group, respectively.

`5.11 Maintaining ACLs on Your Objects`

The ACL programs are an extension to untrusted Digital UNIX systems and are defined by POSIX and System V compatible UNIX programs. All users should take extra precautions to ensure that ACL-protected objects remain protected (or are reprotected) after manipulation by a UNIX program. When a program manipulates an object by creating a new version, removing the existing version, and then renaming the new version, the object's ACL is lost or replaced with the access ACL of the directory where the new version is created. When an object is renamed it retains the ACL (or lack of ACL) with which it was created. When a program modifies an object in place (that is, rewrites, appends, or updates the object without actually deleting it), the ACL protection is retained. ACLs are preserved as long as the object is not removed or the ACL is not explicitly deleted. Until UNIX variants conform to a standard representation for ACLs, and the base utilities are converted to preserve ACLs from object to object, it is the user's responsibility to keep files protected. The permission bits on all newly created objects can be set by using umask or default ACLs. As with traditional UNIX discretionary file attributes, the burden of protecting files is on the user. Note Digital recommends that you use restrictive traditional permissions, such as other::--- and group::---, and then grant access to individual users with user entries. Using this approach, if an ACL is lost, unintended access is not allowed. 5.12 ACLs and the emacs Editor After editing a file with the emacs editor, the new emacs copy of the file does not have the original ACL, but rather the default directory ACL. The problem is that the emacs editor renames the old file prior to writing out the new text. This causes the following to happen: The ACL is associated with the backup file The default directory ACL is associated with the new text (existing file name) Any hard link is associated with the backup file You can work around this situation in either of the two following ways: Copying the data to the backup file, and then writing to the original file. Getting the ACL (its best to get the whole property list) using getproplist() from the original file and applying it to the new file using setproplist().