Information on AFS directory and file security.
Reviewed by John Sopko 6/17/2014
This page gives information on AFS tokens, access control lists (ACLs), protection groups, and home directory permissions. AFS does not use Unix/Linux user IDs, since any Linux machine can give a user a particular User ID. Instead, AFS provides its own user ID’s which are managed at the AFS cell level. To get an AFS ID which identifies you to an AFS cell you must log in and have an account on that AFS cell. The Computer Science AFS cell name is cs.unc.edu.
AFS’s authentication is based on Kerberos, a computer network authentication protocol, which allows nodes communicating over a non-secure network to prove their identity to one another in a secure manner. When you log on successfully to an AFS cell, your local machine’s AFS cache manager will hold a “token” for you. Once you have an AFS token, you can access AFS directories that have their permissions set to allow your AFS User ID access. Tokens contain a time stamp and are valid for a pre-set amount of time. The default lifetime of a token at UNC is one week. The AFS Cache Manager will notify you via the console when tokens on your machine expire. You can use the AFS command aklog to extend the life of a token or to get a new token if your original token expires.
Tokens are the mechanism of authentication. Tokens provide security because in order for an application to ask for the token, it must know an encryption key, and in order to understand that a token has been granted, it must also have an encryption key. This makes it very difficult for someone outside the application to intercept the password, or to even ask for a token. All AFS commands and file requests check with the cache manager to see whether or not you’ve been authenticated to AFS. If the cache manager holds a token for you, you are considered authenticated to AFS.
You get a token by logging in. We have set up the login process to authenticate your password within AFS. To see that this has happened, you can type the tokens command:
Tokens held by the Cache Manager:
User’s (AFS ID 3903) tokens for firstname.lastname@example.org [Expires Mar 29 09:03]
This output says that the cache manager holds for you a token for the cell cs.unc.edu as AFS ID 3903. You may hold additional tokens for different cells, but you may not have more than one token for a particular cell. Tokens are specific to a machine, so authenticating on one machine does not give you a token for another workstation.
Tokens expire after some period of time and need to be renewed. The default lifetime at UNC Computer Science is one week. Also, tokens do not automatically go away when you log out, so that when you run programs overnight the background programs can use the tokens to access files. You can remove a token by using the unlog command:
Tokens held by the Cache Manager:
–End of list–
Please see AFS Aklog for information on how to renew your AFS tokens from the command line. The AFS “klog” command is based on kerberos version 4 which is no longer supported.
Access control lists and UNIX/Linux file protections
An access control list (ACL) is a list of permissions attached to an object. An ACL specifies which users or system processes are granted access to objects, as well as what operations are allowed on given objects. In AFS, an access control list is provided for each AFS directory. File protections do not work the same way in AFS as they do in UNIX. The most important point to bear in mind is that only directories have ACLs in AFS, whereas UNIX has controls on both files and directories. Access to files in AFS is controlled by the ACL of the containing directory. As a result, when you move files between directories, you may have changed the permissions. AFS ACLs provide a much broader range of security features than the file permission mechanism in UNIX.
When you create a new subdirectory, it automatically inherits the ACL that the parent had at the time it was created. Changing the parent ACL in the future will not change the child’s ACL.
The Unix/Linux mode bits set on a directory have no effect in AFS and may be safely ignored. However, the first three bits (the user bits) of a file’s mode bits do have a meaning in AFS. The file bits may be used to further restrict access to a file that the ACL allows access to. For example, if the AFS ACL allows write access to a directory, but the Linux file bits look like -r–??????, where “?” means anything, then the user will not be allowed to write to the file.
Remember, however, that the user bits are applied to anyone who has access to the file; the owner of the file is irrelevant. Also, anyone who has write access to the file through the ACL will be allowed to change the protection bits on the file using chmod.
AFS acls can be complicated. If you are not sure your AFS acls are set correctly PLEASE email email@example.com and we will be glad to assist you. This is especially true of directories where you plan to house sensitive information. For example, if you have files in your www.cs.unc.edu web space that you plan to protect with a user login and password, the ACLs must be configured properly! If your AFS ACLs are not configured properly, search engines like Google can find your pages, catalog them, and keep cached copies of them. See the Web Server FAQ for information on how to protect your web pages.
How to decode an ACL
You may use the command “fs la” or “fs listacl” to examine the access control list that applies to a directory. For example:
% fs la /afs/unc/home/user1
Access list for /afs/unc/home/user1 is
Every ACL implicitly contains “system:administrators a”; this entry allows the AFS system administrator to administer the directory, similar to root privileges in UNIX. The system:anyuser is any user with access to the AFS system, whether or not he has been authenticated to your AFS cell. The above ACL says that anyone can list the contents of this directory. The user user1 may read, lookup, insert files into the directory, delete files from the directory, write to a file in the directory, can flock files in the directory, and may change the ACLs for the directory.
Unlike UNIX, which has only three basic rights that may be controlled, AFS has seven different rights which may be individually controlled:
l (lookup) – list files in the directory (but subdirectories are controlled by their own ACLs)
i (insert) – create files in the directory
d (delete) – remove files and subdirectories from the directory
a (administer) – change the ACL for the directory
r (read) – read files in the directory
w (write) – modify files in the directory and modify their UNIX mode bits with the chmod command
k (lock) – run programs that need to “flock” files in the directory
Changing the ACL of a directory
The ACL of a directory may be changed using the “fs setacl” command (which can be abbreviated as “fs sa”). By default, “fs sa” adds to or alters the existing ACL, rather than replacing it entirely. So, for example, if you wish to give user joe the right to insert and delete files in a directory, use the “fs sa” command:
% fs sa /afs/unc/home/user1/foo joe ldi
NOTE: The ‘l’ right is needed for every other right to be effective.
In addition to accepting any combination of the seven valid AFS rights as an argument, “fs sa” also accepts the following shorthand notations:
write – All rights except administer (a) (i.e., rlidwk);
read – Read and lookup rights (rl);
all – All seven rights (rlidwka);
none – No rights, this removes the user’s entry from the ACL entirely.
So, if you wish to remove user1 from an ACL and allow user2 to read files, you could say:
% fs sa /afs/unc/home/user1/foo user1 none user2 read
AFS also provides groups of users. An AFS protection group is a similar concept to a UNIX user group. An AFS group is used exclusively for file protection in access control lists. These groups are managed by the distributed database component of AFS, and may be modified from any AFS client in the cell. There may be some short latency for the permissions to take effect while the database is distributed among the AFS file servers.
AFS allows individual users to create and maintain their own groups, which can then be used by any user on any ACL. This allows users to grant read/write permissions in a more controlled way than UNIX.
There are two types of groups in AFS: user groups and system groups. All user groups must begin with the user’s name, followed by a colon, followed by a lower case name with no colons in it. Only administrators create system groups, such as “somegroup”, which have no true owner.
The command to create a group is:
% pts creategroup user:name owner
where user is your login, name is the name you want to give the group, and owner is the person or group with administration rights over the group. The owner can be your login, the group itself, or another group you own. If the group is to be owned by your login, you can omit it from the “pts creategroup” command. “pts creategroup” can be shortened to “pts cg”. For example:
% pts creategroup -name yourlogin:friends
group yourlogin:friends has id -205
To see which groups you own or belong to, use the command “pts listowned”. For example:
% pts listowned login
Groups owned by login (id: 2857) are:
To add users to a group, you must be an owner of the group, be the system administrator, or have been given permission by the group owner. The command to add users to a group is: “pts adduser user group”. For example:
% pts adduser user2 login:friends
You can use the “pts membership” command to see who belongs to a given group or which groups a user belongs to:
% pts membership login:friends
Members of user1:friends (id: -205) are:
% pts membership user2
Groups user2 (id: 2857) is a member of:
Finally, you can delete users from a group with the command: “pts remove user”.
Two important groups that are always available in AFS are system:anyuser and system:authuser. “system:anyuser” is any person with access to the AFS file system, who may or may not have been authenticated to AFS, so this is basically anyone from anywhere. “system:authuser” is any person who has been authenticated by the local AFS cell.
Using groups in large projects
Each user and research group can create and administer their own groups without mailing to help. If you have a large, active group, it is useful to spread out the administration among several people, so the change can be made quickly. For this situation, you can set up an administrative group to own the research group. For example, the group “jbs:colab” replaced the old UNIX group “textlab”. This group is owned by “jbs:colab-admin”, whose members are people authorized to make changes to the group “jbs:colab”. To set this up, the owner of the group (in this case “jbs”) issues these commands:
% pts creategroup jbs:colab-admin
% pts creategroup -name jbs:colab -owner jbs:colab-admin
Home directory permissions
When you get your AFS home directory, it will be set up to provide you security by default. Your top level directory permissions will be set up like this:
% fs la /afs/unc/home/user1
Access list for /afs/unc/home/user1 is
This means that anyone can do an ls in your directory and see the names of your files, but cannot read any of them. There will also be two special sub-directories in your AFS home directory with the following permissions:
% fs la /afs/unc/home/user1/public
Access list for /afs/unc/home/user1/public is
% fs la /afs/unc/home/user1/private
Access list for /afs/unc/home/user1/private is
These permissions allow anyone with AFS access to read things in ~user1/public, and allows no one except the owner to run ls or read files in ~user1/private.
Note the special group “cs-machines”. This group contains a block of IP addresses allocated to Computer Science. This special group allows machines AFS access to your files without having an AFS token. Using this group means any machine or person logged into a CS machine has cs-machines access to your files. The cs-machines group is more restrictive then the system:anyuser group but needs to be used with caution.
You will also notice that two files have been moved from your main home directory into ~/public and symbolic links left in their original locations. These files, calendar and .plan, must be readable by everyone for the utility that uses them to run. (This is the same in NFS.) The calendar file, for example, must be read by the reminder service program on one of our servers, and this program does not have a token to read your home directory.
All your sub-directories have inherited the ACL of your main directory at the time of creation, except for ~/public and ~/private.
You are free to relax this security, but remember that AFS permissions work on the directory level, not the file level. If you make files in a directory readable, all the files in that directory are readable, regardless of the UNIX “group” and “other” mode bits. If you want to protect some files in a directory, move them into a protected directory and put symbolic links to the original directory.
Resources on AFS
See http://docs.openafs.org/ for the OpenAFS online manuals. The “AFS Users’s Guide”, which is on this page, is an excellent manual for beginners and covers all of the above information and more.