acl(5)acl(5)NAMEacl - introduction to HFS access control lists
DESCRIPTION
Access control lists are a key enforcement mechanism of discretionary
access control (see Definitions below), for specifying access to files
by users and groups more selectively than traditional HP-UX mechanisms
allow.
HP-UX already enables nonprivileged users or processes, such as file
owners, to allow or deny other users access to files and other objects
on a "need to know" basis, as determined by their user and/or group
identity (see passwd(4) and group(4)). This level of control is accom‐
plished by setting or manipulating a file's permission bits to grant or
restrict access by owner, group, and others (see chmod(2)).
ACLs offer a greater degree of selectivity than permission bits. ACLs
allow the file owner or superuser to permit or deny access to a list of
users, groups, or combinations thereof.
ACLs are supported as a superset of the UNIX operating system discre‐
tionary access control (DAC) mechanism for files, but not for other
objects such as inter-process communication (IPC) objects.
This manual page describes ACLs as implemented on HFS file systems
only. See aclv(5) for a description of ACLs in JFS file systems.
Definitions
Because control of access to data is a key concern of computer secu‐
rity, we provide the following definitions, based on those of the to
explain further both the concepts of access control and its relevance
to HP-UX security features:
"A specific type of interaction between a subject and an object
that
results in the flow of information from one to
the other." Subjects include "persons, pro‐
cesses, or devices that cause information to flow
among objects or change the system state."
Objects include files (ordinary files, directo‐
ries, special files, FIFOs, etc.) and inter-
process communication (IPC) features (shared mem‐
ory, message queues, semaphores, sockets).
An access control list is a set of (user.group,
mode) entries associated with a file that specify
permissions for all possible user-ID/group-ID
combinations.
An entry in an ACL that specifies access rights for one user and
group ID combination.
The right to alter
DAC information (permission bits or ACL entries).
Change permission is granted to object (file)
owners and to privileged users.
"A means of restricting access to objects based on the identity
of
subjects and/or groups to which they belong. The
controls are discretionary in the sense that a
subject with a certain access permission is capa‐
ble of passing that permission (perhaps indi‐
rectly) to any other subject."
Three bits in each ACL entry which represent read, write, and
execute/search permissions. These bits may exist
in addition to the 16 mode bits associated with
every file in the file system (see glossary(9)).
The ability to ignore access restrictions and change restric‐
tions
imposed by security policy and implemented in an
access control mechanism. In HP-UX, superusers
and members of certain groups (see privgrp(4))
are the only privileged users.
An individual ACL entry is considered restrictive or permissive,
depending on context. Restrictive entries deny a
user and/or group access that would otherwise be
granted by less-specific base or optional ACL
entries (see below). Permissive entries grant a
user and/or group access that would otherwise be
denied by less-specific base or optional ACL
entries.
Access Control List Entries
An access control list (ACL) consists of sets of (user.group, mode)
entries associated with a file that specify permissions. Each entry
specifies for one user-ID/group-ID combination a set of access permis‐
sions, including read, write, and execute/search.
To help understand the relationship between access control lists and
traditional file permissions, consider the following file and its per‐
missions:
In an ACL, user and group IDs can be represented by names or numbers,
found in The following special symbols can also be used:
Symbol representing no specific user or group.
Symbol representing the current file owner or group.
Base ACL Entries
When a file is created, three base access control list entries are
mapped from the file's access permission bits to match a file's owner
and group and its traditional permission bits. Base ACL entries can be
changed by the chmod(2) and setacl(2) system calls.
(uid.%,mode) Base ACL entry for the file's owner
(%.gid,mode) Base ACL entry for the file's group
(%.%,mode) Base entry for other users
(Except where noted, examples are represented in short form notation.
See below.)
Optional ACL entries
Optional access control list entries contain additional access control
information, which the user can set with the setacl(2) system call to
further allow or deny file access. Up to thirteen additional
user/group combinations can be specified.
For example, the following optional access control list entries can be
associated with our file:
(mary.admin, rwx) Grant read, write, and execute access to
user mary in group admin.
(george.%, ---) Deny any access to user george in no spe‐
cific group.
ACL Notation
Supported library calls and commands that manage ACLs recognize three
different symbolic representations:
operator form For input of entire ACLs and modifications to existing
ACLs, in a syntax similar to that used by chmod(1).
short form Easier to read, intended primarily for output. chacl(1)
accepts this form as input so that it can interpret out‐
put from lsacl(1).
long form A multi-line format useful for greater clarity, and sup‐
ported only for output.
For our example file, the base ACL entries could be represented in the
three notations as follows:
operator form james.% = rwx, %.admin = rx, %.% = r
short form (james.%,rwx) (%.admin,r-x) (%.%,r--)
long form rwx james.%
r-x %.admin
r-- %.%
In addition to basic ACL usage, some library calls and commands under‐
stand and use a variation of operator and short forms. See the section
below on
ACL Uniqueness
Entries are unique in each ACL. There can only be one (u.g, mode)
entry for any pair of u and g values; one (u.%, mode) entry for a given
value of u; one (%.g, mode) entry for a given value of g; and one (%.%,
mode) entry for each file. For example, an ACL can have a (23.14,
mode) entry and a (23.%, mode) entry, but not two (23.14, mode) entries
or two (23.%, mode) entries.
Access Check Algorithm
ACL entries can be categorized by four levels of specificity. In
access checking, ACLs are compared to the effective user and group IDs
in this order:
(u.g, rwx) specific user, specific group
(u.%, rwx) specific user, no specific group
(%.g, rwx) no specific user, specific group
(%.%, rwx) no specific user, no specific group
Once an entry for the combination of a process effective user ID and
effective group ID (or any supplementary group ID) is matched, no fur‐
ther (that is, less specific) entries are checked. More specific
entries that match take precedence over any less specific ones that
also match.
If a process has more than one group ID (that is, a non-null supplemen‐
tary groups list), more than one (u.g, mode) or (%.g, mode) entry might
apply for that process. If so, the access modes in all matching
entries (of the same level of specificity, u.g or %.g) are OR'd
together. Access is granted if the resulting mode bits allow it.
Since entries are unique, the order of entries in each entry type is
insignificant.
Because the traditional UNIX permission bits are mapped into base ACL
entries, they are included in access checks.
If a request is made for more than one type of access, such as opening
a file for both reading and writing, access is granted only if the
process is allowed all requested types of access. Note that access can
be granted if the process has two groups in its groups list, one of
which is only allowed read access, and the other of which is only
allowed write access. In other words, even if the requested access is
not granted by any one entry, it may be granted by a combination of
entries due to the process belonging to several groups.
Operator Form of ACLs (input only)
user. group operator mode [ operator mode ]... , ...
Multiple entries are separated by commas, as in chmod(1). Each entry
consists of a user identifier and group identifier followed by one or
more operators and mode characters, as in the mode syntax accepted by
chmod(1).
The entire ACL must be a single argument, and thus should be quoted to
the shell if it contains whitespace or special characters. Whitespace
is ignored except within names. A null ACL is legitimate, and means
either "no access" or "no changes", depending on context.
Each user or group ID may be represented by:
name Valid user or group name.
number Valid numeric ID value.
"No specific user or group," as appropriate.
"Current file owner or group," as appropriate;
useful for referring to a file's u.% and %.g base ACL
entries.
An operator is always required in each entry. Operators are:
Set all bits in the entry to the given mode value.
Set the indicated mode bits in the entry.
Clear the indicated mode bits in the entry.
The mode is represented by an octal value of through or any combination
of and can be given in any order (see below). A null mode denies
access if the operator is or represents "no change" if the operator is
or
Multiple entries and multiple operator-mode parts in an entry are
applied in the order specified. Conflicts do not result in error; the
last specified entry or operator takes effect. Entries need not appear
in any particular order.
Note that chmod(1) allows only or to refer symbolically to the file
owner, group, other, or all users, respectively. Since ACLs work with
arbitrary user and group identifiers, @ is provided as a convenience.
The exact syntax is:
acl ::= [entry[,entry]...]
entry ::= id . id op mode [op mode]...
id ::= name | number | % | @
op ::= = | + | -
mode ::= 0..7 | [char[char]...]
char ::= r | w | x
Short Form of ACLs (input and output)
(user . group, mode) ...
Short form differs from operator form in several ways:
· Entries are surrounded by parentheses rather than being sepa‐
rated by commas.
· Each entry specifies the mode, including all mode bits. It is
not possible to change the mode value with and operators. How‐
ever, the comma functions like the operator in operator form.
· For clarity, hyphens represent unset permission bits in the out‐
put of the mode field and are allowed in input. This resembles
the mode output style used by ls(1).
Multiple entries are concatenated. For consistency with operator form,
a dot (.) is used to separate user and group IDs.
On output, no whitespace is printed except in names (if any). ID num‐
bers are printed if no matching names are known. Either ID can be
printed as for "no specific user or group." The mode is represented as
<r|-><w|-><x|->, that is, it always has three characters, padded with
hyphens for unset mode bits. If the ACL is read from the system,
entries are ordered by specificity, then by numeric values of ID parts.
On input, the entire ACL must be a single argument, and thus should be
quoted to the shell if it contains whitespace or special characters.
Whitespace is ignored except within names. A null ACL is legitimate,
and means either "no access" or "no changes", depending on context.
User and group IDs are represented as in operator form.
The mode is represented by an octal value of through or any combination
of and (ignored) can be given in any order (see below). A null mode
denies access.
Redundancy does not result in error; the last entry for any user-
ID/group-ID combination takes effect. Entries need not appear in any
particular order.
The exact syntax is:
acl ::= [entry[entry]...]
entry ::= (id.id,mode)
id ::= name | number | % | @
mode ::= 0..7 | [char[char]...]
char ::= r | w | x | -
Long Form of ACLs (output only)
mode user . group
Each entry occupies a single line of output. The mode appears first in
a fixed-width field, using hyphens (for unset mode bits) for easy ver‐
tical scanning. Each user and group ID is shown as a name if known, a
number if unknown, or for "no specific user or group." Entries are
ordered from most to least specific, then by numeric values of ID
parts.
Note that every ACL printed has at least three entries, the base ACL
entries (that is, uid.%, %.gid, and %.%).
The exact syntax is:
acl ::= entry[<newline>entry]...
entry ::= mode<space>id.id
mode ::= <r|-><w|-><x|->
id ::= name | number | %
ACL Patterns
Some library calls and commands recognize and use ACL patterns instead
of exact ACLs to allow operations on all entries that match the pat‐
terns. ACL syntax is extended in the following ways:
wildcard user and group IDs
A user or group name of (wildcard) matches the user or
group ID in any entry, including (no specific user or
group).
mode bits on, off, or ignored
For operator-form input, the operators and are applied
as follows:
entry mode value matches this mode value exactly
these bits turned on in entry mode value
these bits turned off in entry mode value
When only and operators are used, commands ignore the
values of unspecified mode bits.
Short-form patterns treat the mode identically to the
operator in operator form.
wildcard mode values
A mode of (wildcard) in operator or short form input
(for example, "ajs.%=*" or "(ajs.%,*)") matches any mode
value, provided no other mode value is given in a opera‐
tor-form entry. Also, the mode part of an entry can be
omitted altogether for the same effect.
entries not combined
Entries with matching user and group ID values are not
combined. Each entry specified is applied separately by
commands that accept patterns.
ACL Operations Supported
The system calls setacl(2) and getacl(2) allow setting or getting the
entire ACL for a file in the form of an array of acl_entry structures.
To check access rights to a file, see access(2) and getaccess(2).
Various library calls are provided to manage ACLs:
acltostr(3C) Convert acl_entry arrays to printable strings.
strtoacl(3C) Parse and convert ACL strings to acl_entry arrays.
strtoaclpat(3C) Parse and convert ACL pattern strings to
acl_entry_patt arrays.
setaclentry(3C)
fsetaclentry Add, modify, or delete a single ACL entry in one
file's ACL.
cpacl(3C)
fcpacl Copy an ACL and file miscellaneous mode bits (see
chmod(2)) from one file to another, transfer owner‐
ship if needed (see below), and handle remote files
correctly.
chownacl(3C) Change the file owner and/or group represented in an
ACL, that is, transfer ownership (see below).
The following commands are available to manage ACLs and permissions:
chacl(1) Add, modify, or delete individual entries or all
optional entries in ACLs on one or more files, remove
all access to files, or incorporate ACLs into permis‐
sion bits.
lsacl(1) List ACLs on files.
chmod(1) Change permission bits and other file miscellaneous
mode bits.
ls(1) In long form, list permission bits and other file
attributes.
find(1) Find files according to their attributes, including
ACLs.
getaccess(1) List access rights to file(s).
ACL Interaction with stat, chmod, and chown
stat The st_mode field summarizes the caller's access rights to the
file. It differs from file permission bits only if the file
has one or more optional entries applicable to the caller. The
st_basemode field provides the file's actual permission bits.
The st_acl field indicates the presence of optional ACL entries
in the file's ACL.
The st_mode field contains a user-dependent summary, so that
programs ignorant of ACLs that use stat(2) and chmod(2) are
more likely to produce expected results, and so that stat(2)
provides reasonable information about remote files over NFS.
The st_basemode and st_acl fields are useful only for local
files.
chmod For conformance with IEEE Standard POSIX 1003.1-1988, chmod(2)
deletes any optional entries in a file's ACL. Unfortunately,
since chmod(2) is used to set file miscellaneous mode bits as
well as permission bits, extra effort is required in some cases
to preserve a file's ACL.
chown If the new owner and/or group of a file does not already have
an optional (u.%, mode) and/or (%.g, mode) entry in the file's
ACL, it inherits the old owner's and/or group's file access
permission bits and base ACL entry:
(id1,mode1) -> (id2,mode1)
This is the traditional behavior. However, if the new owner
and/or group of a file already has an optional (u.%, mode)
and/or (%.g, mode) entry in the file's ACL, the ACL does not
change:
(id1, mode1) -> (id1, mode1)
(id2, mode2) -> (id2, mode2)
Existing access information in the ACL is preserved. However,
because the old optional ACL entry becomes the new base ACL
entry and vice versa, the file's access permission bits change.
Transferring ownership of ACLs by chown(2) allows a file to be
transferred to a different user or group, or copied by a dif‐
ferent user or group than the owner (using cpacl(3C) or chow‐
nacl(3C)), and later returned to the original owner or group
without net changes to its ACL. The extra complexity is neces‐
sary because:
· ACLs are a backward-compatible superset of permission bits
(which are coupled to file owner and group IDs), not a
replacement for them.
· it enables users and programs that deal with ACLs to do so
simply, rather than with a combination of permission bits
and ACL entries. Also, the access check algorithm is sim‐
pler and more symmetrical; permission bits do not
"eclipse" or "mask" ACL entries.
EXAMPLES
Operator Form
The following sets the entry to restrict "other" users to only reading
the file.
The following allows user "bill" in any group to write the file, assum‐
ing that no restrictive entry is more specific than the entry (for
example, a entry that denies writing).
The following ACL specification contains two entries. The first one
deletes write and adds read capability to the entry for user 12, group
4. The second entry denies access for any unspecified user in any
unspecified group.
The following pair of entries sets the u.% entry for the file's owner
to allow both read and execute and results in adding write and execute
capabilities for "other" users (the "%.%" entry). Note that a mode
character is purposely repeated for illustration purposes.
Short Form
Here is a typical ACL as it might be printed. It allows user to read
or execute the file while in group it denies user access to the file
while in group it allows user in any group (except to only read the
file; any other user in group may read or execute the file; and any
other user may only read the file.
The following allows "other" users to only read the file.
The following sets write-only access for user in any group.
The following sets the entry for user 12 in group 4 to allow read and
write.
The following sets the base ACL entry for the file's owner to allow
both read and execute, and sets write and execute capabilities for
"other" users (the "%.%" entry).
Long Form
Here is the same ACL as in an earlier example, printed in long form.
r-x jpc.adm
--- ajs.trux
r-- jpc.%
r-x %.bin
r-- %.%
ACL Patterns
The following command locates files whose ACLs contain an entry that
allows read access and denies write access to some user/group combina‐
tion.
The following matches entries for any user in group and for user in any
group, regardless of the entries' mode values. Matching optional ACL
entries are deleted and mode values in matching base ACL entries are
set to zero:
The following matches all entries, deleting optional entries and set‐
ting mode values of base ACL entries to zero:
HEADERS
Header <sys/acl.h>
The header file defines the following constants to govern the numbers
of entries per ACL:
maximum number of entries per ACL, including base entries
number of base entries
number of optional entries
The ACL entry structure is also defined, and includes the following
members:
aclid_t uid; /* user ID */
aclid_t gid; /* group ID */
aclmode_t mode; /* see <unistd.h> */
The header also defines the types and
Non-specific user and group ID values:
non-specific user ID
non-specific group ID
A special nentries value is used with setacl(2) to delete optional
entries.
Header <sys/getaccess.h>
The header defines constants for use with getaccess(2).
Special parameter values for uid:
use effective user ID
use real user ID
use saved user ID
Special parameter values for ngroups:
process's effective gid
process's real gid
process's saved gid
process's supplementary groups only
process's eff gid plus supp groups
process's real gid plus supp groups
process's saved gid plus supp groups
Header <acllib.h>
The header file defines several constants for use with ACL support
library calls.
Symbolic forms of ACLs for acltostr():
Magic values for various calls:
ACL_FILEOWNER file's owner ID
ACL_FILEGROUP file's group ID
ACL_ANYUSER wildcard user ID
ACL_ANYGROUP wildcard group ID
MODE_DEL delete one ACL entry
Mask for valid mode bits in ACL entries:
The header also defines the ACL pattern entry structure, which includes
the following members:
aclid_t uid; /* user ID */
aclid_t gid; /* group ID */
aclmode_t onmode; /* mode bits that must be on */
aclmode_t offmode; /* mode bits that must be off */
WARNINGS
ACLs are intended for use on ordinary files and directories. Optional
ACL entries are not recommended on files that are manipulated by cer‐
tain system utilities, such as terminal special files and LP scheduler
control files. These utilities might delete optional entries, includ‐
ing those whose intent is restrictive, without warning as a consequence
of calling chmod(2), thereby increasing access unexpectedly.
Most, but not all, supported utilities are able to handle ACLs cor‐
rectly. However, only the fbackup(1M) and frecover(1M) file archive
utilities handle access control lists properly. When using programs
(such as archive programs ar(1), cpio(1), ftio(1), tar(1), and
dump(1M)) unable to handle ACLs on files with optional ACL entries,
note the Access Control List information included on their respective
reference pages, to avoid loss of data.
If a user name is defined in the file or a group name is defined in the
file as or @, or for patterns, ∗, ACL syntax cannot reference that name
as itself because the symbols have other meanings. However, such users
or groups can still be referenced by their ID numbers. User and/or
group names must not include the following characters:
Do not use in user names.
Do not use in group names.
Do not use in group names.
Do not use for operator form input of group names.
Do not use for short form or for operator form patterns.
Do not use for short form patterns.
It is possible to specify an ACL pattern using the @ (file owner or
group) or (wildcard) symbols so that it cannot match certain files,
perhaps depending on their ownership, by giving two entries, one with
specific values and the other using @ or which are equivalent for a
file but contain different mode values. For example:
cannot match a file owned by
DEPENDENCIES
NFS NFS does not support ACLs on remote files. Individual manual
entries specify the behavior of various system calls, library
calls, and commands under these circumstances. Be careful when
transferring a file with optional entries over a network or when
manipulating a remote file because optional entries may be
silently deleted.
AUTHOR
The access control list design described here was developed by HP.
FILES
Header file that supports setacl(2) and getacl(2).
Header file that supports getaccess(2).
Header file that supports ACL library calls.
Defines user names and user and group
ID values.
Defines group names.
SEE ALSOchacl(1), chmod(1), cp(1), find(1), getaccess(1), ln(1), ls(1),
lsacl(1), mv(1), rm(1), fbackup(1M), frecover(1M), fsck(1M), fsdb(1M)access(2), chmod(2), chown(2), creat(2), getaccess(2), getacl(2),
mknod(2), open(2), setacl(2), stat(2), acltostr(3C), chownacl(3C),
cpacl(3C), setaclentry(3C), strtoacl(3C), group(4), passwd(4), priv‐
grp(4), aclv(5).
acl(5)
