auristorfs_acls - AuriStor File System Access Control Lists (ACLs)
The AuriStor File System is an AFS3-compatible distributed file system also known as the /afs file namespace.
The /afs file namespace is protected by
access control lists (ACLs).
ACLs can be applied to directories,
symlinks and volumes.
AuriStorFS File access control model defines seven access permissions:
This document describes the permissions and the access that is granted when they are included in an access control entry (ACE) on each of the file system object types.
The l (lookup) permission
This permission can be applied to directories, symlinks and mount points.
When applied to a directory the l (lookup) permission grants the following capabilities:
This permission does not grant the ability to read the contents of a file in the directory, to access the status information on files stored in the directory, or to examine the ACL of a file stored in the directory.
Similarly, this permission does not grant any rights to subdirectories of the directory. Those operations require the l (lookup) permission on the ACL of the subdirectory itself.
The i (insert) permission
This permission enables the addition of new files to the directory, either by creating or copying, and the creation of new subdirectories. It does not extend into any subdirectories, which are protected by their own ACLs.
When applied to files, this permission grants to the file owner the rights normally granted by the w (write) permission.
The d (delete) permission
This permission enables the deletion of files and subdirectories from the directory or moving them into other directories (assuming that the user has the i (insert) permission on the ACL of the other directories).
The a (administer) permission
This permission enables changing the ACL associated with a directory, file, symlink or mount point. Members of the system:administrators group and the owner of the volume root directory implicitly have this permission on every file system object.
The r (read) permission
This permission enables reading the contents and status information for files. When the permission is granted on a directory it applies to all files in the directory that are not assigned their own ACL.
This permission does not grant the ability to obtain a shared file lock. That ability is granted by the k (lock) permission.
The w (write) permission
This permission enables modifying the contents and status information for files. When the permission is granted on a directory it applies to all files in the directory that are not assigned their own ACL.
This permission enables the ability to obtain shared and exclusive file locks.
The status information that can be modified include:
UNIX mode bits
Setting the UNIX suid and sgid bits requires membership in the system:administrators group.
The k (lock) permission
This permission grants the ability to obtain a shared file lock. When the permission is granted on a directory it applies to all files in the directory that are not assigned their own ACL.
The eight auxiliary permissions
AuriStorFS provides eight additional permissions that do not have a defined meaning, denoted by the uppercase letters A, B, C, D, E, F, G, and H.
Application programs can be written that assign a meaning to one or more of the permissions, and then place them on ACLs to control file access by those programs. For example, you can modify a print program to recognize and interpret the permissions, and then place them on directories that house files that the program accesses. Use the fs_listacl(1) and fs_setacl(1) commands to display and set the auxiliary permissions on ACLs just like the standard seven.
You can combine the seven permissions in any way in an ACL entry, but certain combinations are more useful than others. Four of the more common combinations have corresponding shorthand forms. When using the fs setacl command to define ACL entries, you can provide either one or more of the individual letters that represent the permissions, or one of the following shorthand forms:
Represents all seven standard permissions (rlidwka).
Represents the l (lookup), i (insert) and k (lock) permissions.
Removes the entry from the ACL, leaving the user or group with no permissions.
Represents the r (read) and l (lookup) permissions.
Represents all permissions except a (administer): rlidwk.
ACLs enable you to both grant and deny access to file system objects. To grant access, use the fs_setacl(1) command to create an access control entry (ACE) that associates a set of permissions with a set of users or groups. When the fs_listacl(1) command displays an ACL, such entries appear underneath the Normal rights header.
There are two ways to deny access:
The recommended method is simply to omit an entry for the user or group from the ACL, or to omit the appropriate permissions from the entry. Use the fs_setacl(1) command to remove or edit an existing entry. In most circumstances, this method is enough to prevent access of certain kinds or by certain users. You must take care, however, not to grant the undesired permissions to any groups to which such users belong.
The more explicit method for denying access is to use the -negative flag to the fs_setacl(1) command to create an entry that associates negative permissions with the user or group. The output from the fs_setacl(1) command lists negative entries underneath the Negative rights header.
When determining what type of access to grant to a user, the File Server first compiles a set of permissions by examining all of the entries in the Normal rights section of the ACL. It then subtracts any permissions associated with the user (or with groups to which the user belongs) on the Negative rights section of the ACL. Therefore, negative permissions always cancel out normal permissions.
Using negative permissions reverses the usual semantics of the fs_setacl(1) command, introducing the potential for confusion. In particular, combining the none shorthand and the -negative flag constitutes a double negative: by removing an entry from the Negative rights section of the ACL, you enable a user once again to obtain permissions via entries in the Normal rights section. Combining the all shorthand with the -negative flag explicitly denies all permissions.
Note also that it is pointless to create an entry in the Negative rights section if an entry in the Normal rights section grants the denied permissions to the system:anyuser group. In this case, users might obtain the permissions simply by using the unlog(1) command to discard their tokens. When they do so, the File Server recognizes them as the anonymous user, who belongs to the system:anyuser group but does not match the entries on the Negative rights section of the ACL. Further note that a negative entry for the anonymous user can be added to the ACL.
As previously mentioned, placing a group entry on an ACL enables you to control access for many users at once. You can grant a new user access to many files and directories simply by adding the user to a group that appears on the relevant ACLs. On directories where they have the a (admin) permission on the ACL, users can define their own groups and can create ACL entries for any groups, not just groups that they create or own themselves using the pts_creategroup(1) command.
AuriStorFS also defines the following two system groups, which can be very useful on ACLs because they potentially represent a large group of people.
This group includes anyone who can access the cell's file tree,
including users who have logged in as the local superuser root,
have connected to a local machine from somewhere outside the cell,
and AFS users who belong to a foreign cell.
This group includes users who do not have tokens that are valid for the local AFS servers; the servers recognize them as the user
This group includes all users who have a valid AFS token for the local cell. It does not include Protection Service entries that are disabled or afsonly. See pts_setaccess(1) for more information.
It is particularly useful to grant the l (lookup) permission to the system:anyuser group on the ACL of most directories in the file system, especially at the upper levels. This permission enables users only to learn the names of files and subdirectories in a directory, but without it they cannot traverse their way through the directories in the path to a target file.
A slightly more restrictive alternative is to grant the l (lookup) permission to the system:authuser group. If that is still not restrictive enough, you can grant the l (lookup) to specific users or groups.
Another reason to grant certain permissions to the system:anyuser group is to enable the correct operation of processes that provide services such as printing and mail delivery. For example, in addition to the l (lookup) permission, a print process possibly needs the r (read) permission in order to access the contents of files, and a mail delivery process possibly requires the i (insert) permission to deliver new pieces of mail.
The ACL on the root directory of every newly created volume grants all permissions to the system:administrators group. You can remove this entry if you wish, but members of the system:administrators group always implicitly have the a (administer), and by default also the l (lookup), permission on every directory's ACL. The a (admin) permission enables them to grant themselves other permissions explicitly when necessary.
Access Control Lists are optional for files, symlinks and mount points. When an ACL is unassigned, the parent directory's ACL is inherited by the object. The (riwka) permissions apply to files and the (lwka) permissions apply to symlinks and mount points. For symlinks and mount points the l (lookup) permission permits reading the target and status information.
When a cross-directory hard link is created to a file that inherits the directory ACL, the directory ACL will be cloned and assigned to the file. This ensures that identical access permissions will be used when accessing the file regardless of which directory is used.
Non-directory ACLs can be removed using the fs_removeacl(1) provided there are no hard links present. After removal the directory ACL is inherited.
The AuriStorFS Volume is a policy container for the directory tree that exists within it. The Volume Maximum ACL (MaxACL) is a policy attribute that restricts the rights that can be effectively granted by ACLs assigned to individual objects (directories, files, symlinks and mount points). Instead the MaxACL contrains the rights that can be granted by ACLs assigned to file objects. All file object access must be permitted by both the MaxACL and the ACL that applies to the request file object.
Effective rights := ACL(Normal & ~Negative) & MaxACL(Normal & ~Negative)
The MaxACL can only be set using the vos_setmaxacl(1) by a user listed in the /etc/yfs/server/UserListExt file or by an account capable of reading the /etc/yfs/server/KeyFileExt file. Normal users and members of the system:administrators group cannot alter the MaxACL. The maximum rights granted on a Volume with no MaxACL assignment are equivalent to the MaxACL with the ACE:
which results in the Effective Rights to be equal to those granted by the file object ACL.
AuriStorFS implements a User-centric, Constrained Elevation Authorization Model that leverages Combined Identity Authentication and Multi-factor Access Control Lists. This model combined with Volume Security Policies can be used to create Volumes that enforce data classification policies as defined by the deploying organization.
AuriStorFS authentication tokens are used to securely authenticate a user, process or machine to any AuriStorFS service. An AuriStorFS authentication token is similar to a Kerberos v5 service ticket that uses a shared secret to prove mutual authentication between two peers. This token traditionally authenticates a single entity which can be a user, process, service, container, or machine. When a user acquires a token using the aklog(1) command, that token contains an identity sequence of length one.
For example, if a Kerberos v5 realm
"YOUR-CELL-NAME.COM" is used to authenticate a cell
"your-cell-name.com" and the user's name is
"user", the the acquired token will contain an identity sequence of length one.
The AuriStor File System supports a concept referred to as Combined Identity authentication. A Combined Identity is sequence of entity names which can represent users, services, machines, and other objects that can authenticate to the AuriStor File System by name.
When the yfs-rxgk security class is enabled the Cache Manager can request a Combined Identity Token which securely combines the identity of the user with the identity of the Cache Manager. The Cache Manager identity is typically the identity of the machine. A Combined Identity Token is an authentication token that asserts authentication of an identity sequence.
When an AuriStorFS Cache Manager is installed on a Windows domain joined computer a Combined Identity Token will be acquired. If the domain name is
"AD.YOUR-CELL-NAME.COM", the computer's name is
"desktop", and the domain user's name is
"user", then the token's identity sequence will be.
One benefit of the use of a Combined Identity Token is that the Cache Manager is protected against cache poisoning attacks. In addition, the AuriStorFS services can log all of the authenticated identities.
When the user has not acquired a token, the Cache Manager will acquire a Combined Identity Token for the
anonymous user and the cache manager identity. This token permits the cache manager to obtain integrity protection and wire privacy for the otherwise anonymous communication. Using the prior Windows domain as an example, the resulting identity sequence would be:
"WELLKNOWN/ANONYMOUS@WELLKNOWN:ANONYMOUS" identity is recognized by the Protection Service as the local cell user
"anonymous" that is assigned the AuriStorFS User Number (AUN) 37266.
The first identity in the sequence is the identity used by an AuriStorFS service when evaluating membership in the UserListExt(5) and ReaderList(5) or super user status or file object ownership.
AuriStorFS cache managers installed on UNIX hosts can be assigned an authenticated identity using the keytab option of afsd(8).
Combined Identity Tokens can contain an identity sequence longer than two. As an example, many organizations deploy HTTP or SFTP proxy access to the /afs file namespace. Some organizations might wish to distinguish access via the proxy service which requires the transmission of the user's name and password over a TLS protected channel from access where the user obtains an authentication token directly. A web service such as Filedrawers might be assigned the Kerberos service name
"HTTP/filedrawers.your-cell-name.com" and the service might be running on a machine with a host service principal of
"host/web-1.your-cell-name.com" which is used by the cache manager. The Filedrawers service uses an Apache module mod_waklog to acquire tokens for the requesting user. The acquired token can be combined with the Filedrawers service identity before handing the token off to the Cache Manager. The resulting identity sequence could be:
Each of these identities would be written to the audit logs.
As the concept of Container Identity evolves the use of Combined Identity Tokens can be extended to support container deployment and execution.
A simple or single-factor Access Control Entry (ACE) consists of a single name representing a single entity or a group and a granted set of access permissions.
john rlw system:anyuser l
The AuriStor File System leverages the Combined Identity authentication to produce a richer set of access control semantics; a user centric, constrained elevation access control model. Each additional identity appended to a Combined Identity sequence can:
grant more rights, not fewer, when used to evaluate an ACL's Normal entries.
revoke more rights, not fewer, when used to evaluate an ACL's Negative entries.
An AuriStor File System ACE is specified as an unordered list of user or group names rather than a single name.
anonymous,machine-identity l system:authuser,machine-identity lrk group-of-users,group-of-machines lrw
The a user centric, constrained elevation access control model's ACL evaluation rules are as follows:
The rights granted by an ACL are the sum of the rights granted by the Normal ACEs minus the sum of the rights revoked by the Negative ACEs.
If an ACE matches the Combined Identity sequence then the rights it grants or revokes are added to the appropriate summation.
An ACE matches a Combined Identity sequence when each of the following rules are satisfied by a prefix substring of the Combined Identity sequence:
user in the ACE must be present in the prefix substring and every
group in the ACE must have a member in the prefix substring.
All of the identities within the prefix substring must contribute to the match. That is, each identity in the prefix substring must match (either by user, or by group) an element of the ACE.
An ACE match is evaluated for each prefix substring of the Combined Identity sequence. That is, start with the prefix substring that is just the primary identity. Then evaluate the prefix substring consisting of the primary and secondary identities. Then the prefix substring consisting of the primary, secondary and tertiary identities, and so on. If an prefix substring matches the ACE, its rights are added to the Normal or Negative summation and the evaluation of the next ACE begins.
What follows are examples of how the user centric, constrained elevation access control model can be used to grant and constrain rights for combined identities.
Groups: anyuser authuser admin hr devices networks Identities and their memberships: anonymous anyuser george anyuser authuser jane anyuser authuser john anyuser authuser admin hr pc anyuser devices ipad anyuser devices ny-net anyuser networks tn-net anyuser networks uk-net anyuser networks ca-net anyuser networks ACL: Normal entries: authuser l george lrkwid george,pc lrkwida jane lr jane,pc lrka jane,ipad lrk pc lrk anyuser,devices l Negative entries: anyuser,ca-net lrkwida Rights granted to Combined Identity sequences: anonymous none george lrkwid jane lr john l pc lrk ipad none anonymous,pc l george,pc lrkwida jane,pc lrka john,pc l anonymous,ipad l george,ipad lrkwid jane,ipad lrk john,ipad l
The user centric, constrained elevation model ACL evaluation rules compute the rights for the Combined Identity sequence
<jane pc ny-net> by determining the rights granted to each prefix substring and adding them to the appropriate summation.
Normal entries ------------------------------- jane (primary) lr jane,pc lrka jane,pc ny-net none ------------------------------- Total Positive rights lrka Negative entries ------------------------------- jane (primary) none jane,pc none jane,pc ny-net none ------------------------------- Total Negative rights none Total rights (lrka & ~none) = "lrka"
If a new Normal ACE is added to the ACL:
Then the rights granted to each prefix substring become:
Normal entries ------------------------------- jane (primary) lr jane,pc lrka jane,pc,ny-net wida ------------------------------- Total Positive rights lrkwida Total Negative rights none Total rights = "lrkwida".
For the Combined Identity seqence
<jane ca-net>, the granted rights will be:
Normal entries ------------------------------- jane (primary) lr jane,ca-net none ------------------------------- Total positive rights lr Total egative rights none Total rights = "lr"
In the user centric, constrained elevation model the Combined Identities are a sequence; not an unordered set. Therefore, the position of each identity in the sequence matters. If an organization wishes to provide a group of users enhanced rights when accessing data from the
uk-net group of networks as long as the access was from an authenticated device, then it could add the ACE:
Granting rights to authenticated users on
uk-net from an unauthenticated device is:
An ACE can also represent a set of groups. For example, the ACE
when specifed grants
john the full set of permissions because he is a member of both the
Negative ACEs in general are discouraged because they can add confusion especially when the group memberships of the primary identity are hard to determine. That being said, negative ACEs are a good fit for the user centric, constrained elevation model when used to deny rights based upon the supplemental identities and their memberships.
For example, a Negative ACE can be added to deny all users connecting through a web service the delete right.
Negative entries --------------------------- anyuser,web-servers d
If an accessing user has the
l (lookup) and
i (insert) permissions on a directory, but not the
w (write) and/or
r (read) permissions, the user is implicitly granted the ability to write and/or read any file they create in that directory, until they close the file. This is to allow "dropbox"-style directories to exist, where users can deposit files, but cannot modify them later nor can they modify or read any files deposited in the directory by other users.
Note, however, that the dropbox functionality is not perfect. The fileserver does not have knowledge of when a file is opened or closed on the client, and so the fileserver always allows an accessing user to read or write to a file in a "dropbox" directory if they own the file. While the client prevents the user from reading or modifying their deposited file later, this is not enforced on the fileserver, and so should not be relied on for security.
Additionally, if "dropbox" permissions are granted to
system:anyuser, unauthenticated users may deposit files in the directory. If an unauthenticated user deposits a file in the directory, the new file will be owned by the unauthenticated Auristor User Number (AUN), and is thus potentially modifiable by anyone.
In an effort to try and reduce accidentally publicizing private data, the fileserver may refuse read requests for "dropbox" files from unauthenticated users. As a result, depositing files as an unauthenticated user may arbitrarily fail if
system:anyuser has been granted dropbox permissions. While this should be rare, it is not completely preventable, and so for this reason relying on unauthenticated users to be able to deposit files in a dropbox is NOT RECOMMENDED.
IBM AFS and OpenAFS clients and servers are unable to perform Combined Identity authentication. When IBM AFS or OpenAFS clients authenticate to an AuriStor File System server only the primary identity can be asserted.
IBM AFS and OpenAFS servers are unable to store volumes that contain Access Control Lists that cannot be stored as an AFS3 ACL. The AFS3 ACL restrictions are:
Each ACE can associate rights with a single
Each ACL can contain no more than twenty (20) ACEs.
IBM AFS and OpenAFS servers are unable to store volumes that have Volume Maximum ACLs assigned to them.
The IBM AFS and OpenAFS vos(1) command do not support Volume Maximum ACL operations.
The IBM AFS and OpenAFS fs(1) command do not support multi-component ACEs nor do they support the assignment of rights to the
The issuer of the fs_setacl(1) command must have the
a (administer) permission on the file object's ACL, be a member of the
system:administrators group, or, as a special case, must be the UID owner of the top-level directory of the volume containing the file object. The last provision allows the UID owner of a volume to repair accidental ACL errors without requiring intervention by a member of
The issuer of the vos_setmaxacl(1) command must be listed in the /etc/yfs/server/UserListExt file on the File Server in order to set, modify or remove a Volume Maximum ACL.
The issuer of the vos_listmaxacl(1) command must be listed in the /etc/yfs/server/UserListExt file or the /etc/yfs/server/ReaderList file on the File Server in order to examine a Volume Maximum ACL.
KeyFileExt(5), ReaderList(5), UserListExt(5), afsd(8), fs_getcalleraccess(1), fs_cleanacl(1), fs_copyacl(1), fs_listacl(1), fs_lsmount(1), fs_removeacl(1), fs_setacl(1), pts_creategroup(1), unlog(1), vos_listmaxacl(1), vos_setmaxacl(1)
Copyright AuriStor, Inc. 2014-2021. https://www.auristor.com/ All Rights Reserved.
"AFS" is a registered mark of International Business Machines Corporation, used under license. (USPTO Registration 1598389)
"OpenAFS" is a registered mark of International Business Machines Corporation. (USPTO Registration 4577045)
The "AuriStor" name, log 'S' brand mark, and icon are registered marks of AuriStor, Inc. (USPTO Registrations 4849419, 4849421, and 4928460) (EUIPO Registration 015539653).
"Your File System" is a registered mark of AuriStor, Inc. (USPTO Registrations 4801402 and 4849418).
"YFS" and "AuriStor File System" are trademarks of AuriStor, Inc.