The University of North Carolina at Chapel Hill
College of Arts and Sciences
Department of Computer Science

AFS Security			Reviewed 2/22/2009 by John Sopko


This is one of several AFS howto pages. Their titles are listed below
in the recommended reading order:

 1)afs-intro -> basic concepts on AFS and AFS command structure
+2)afs-security -> overview of permissions and groups in AFS
 3)afs-volumes -> discussion of how AFS volumes and backups work
 4)afs-tips -> common questions and advanced techniques with AFS
 5) afs-aklog -> Obtaining AFS tokens using Kerberos 5

Resources on AFS
----------------

See the following web page for info on how to get to the Transarc
online html manual. The "AFS Users's Guide" is an excellent manual for
beginners.

http://www.cs.unc.edu/help/afs_info


INTRO
-----

One of the many motivations during the development of AFS at CMU was the 
need for stronger and more flexible security on files in a distributed 
system than is provided by UNIX. The security in AFS is based on two 
major concepts:  tokens and Access Control Lists (ACL).

AFS does not trust UNIX user IDs, since any UNIX machine can give a 
user a particular User ID. AFS provides its own 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 at that AFS cell. AFS uses an 
authentication scheme which improves security by using encryption to 
exchange password information between the AFS Authentication Server and 
the Cache Manager.

AFS's authentication is based on Kerberos. 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 which 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
------

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, you are considered 
authenticated to AFS.


How to become authenticated (get a token):

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

Tokens held by the Cache Manager:

User's (AFS ID 3903) tokens for afs@cs.unc.edu [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 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.

    % unlog 
    % tokens

    Tokens held by the Cache Manager:

	 --End of list--

Please see "howto afs-aklog" on how to renew your AFS tokens from the
command line. The AFS "klog" command is bassed on kerberos version 4
which is no longer being supported.



Access Control Lists and UNIX File Protections:
----------------------------------------------

IMPORTANT! AFS acls can be complicated. If you are not sure your AFS
acls are set correctly PlEASE email help@cs.unc.edu and we will be
glad to assis you. This is especially true of directories you plan to
house sensitive information in. For example if you have files in your
www.cs.unc.edu web space that you plan on protecting 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 following URL for information on how to protect your
web pages:

http://www.cs.unc.edu/help/www_server_faq.html#question11

Access Control Lists have been used by various operating systems to
provide security. Access control lists can provide a much broader range
of security features than the file permission mechanism in UNIX. 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. Access to files is controlled by the ACL of the containing
directory. In other words, when you move files between directories,
you may have changed the permissions.

Another important point is that 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 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 file bits look like -r--??????, 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.

Examining the ACL for a Directory

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 
    Normal rights:   
      system:anyuser l   
      user1 rlidwka

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.


How to decode an ACL
--------------------

Unlike UNIX, which has only three basic rights that may be controlled,
AFS has seven different rights which may be individually controlled.
These rights are subdivided into two groups:  four directory-access
rights and three file-access rights.


Directory Access Rights

The four rights in this group apply to the directory itself. They are:

l -> The lookup right allows the possessor:

To issue ls to list the names of the files and subdirectories in the 
directory. It does not allow the possessor to list the contents of 
subdirectories unless he or she also has the lookup right in the 
subdirectory's ACL.

To "ls -l" of the directory itself and examine the ACL for the directory.

To access the directory's subdirectories, subject to their own ACLs.

i -> The insert right allows the possessor:

To add new files and subdirectories to the directory.

d -> The delete right allows the possessor:

To remove files and subdirectories from the directory.

a -> The administer right allows the possessor:

To change the ACL for the directory. Note that once given this right, 
someone can change the ACL to give themselves all other rights. They 
can even remove you from the ACL.

The owner of a directory has implicit administer rights on the 
directory, regardless of the actual ACL.


File Access Rights

The three rights in this group only apply to files in the directory. 
They are:

r -> The read right allows the possessor:

To look at the contents of the directory (i.e., "ls -l"). For files in 
the directory, the possessor can read the actual data in the file.

w -> The write right allows the possessor:

To modify the contents of files in the directory and to modify their UNIX 
mode bits with the chmod command. This contrasts with the "administer" 
rights:  Mode bits on directories are ignored, so you need to have 
"administer" rights on a directory to change the ACL. You need "write" 
to change mode bits of files within the directory.

k -> The lock right allows the possessor:

To 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" ("fs sa") 
command. 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.
----

As well as 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

It is also possible to set negative access rights on a directory, 
denying access.


Protection Groups

AFS also provides groups of users. Two important groups 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.

AFS also allows individual users to create and maintain their own 
groups. This allows users to grant read/write permissions in a more 
controlled way than UNIX.

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.

Users may create or manage their own AFS protection groups, which can 
then be used by any user on any ACL. 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 "ftphax", 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".

Some examples: 

    % pts creategroup -name user1:friends 
    group user1:friends has id -205

    % pts creategroup user2:document user2 
    group user2:document has id -206

    % pts creategroup user1:enemies user1:friends 
    group user1:enemies has id -207    

To see which groups you own or belong to, use the command "pts listowned":

    % pts listowned [group | user]

For example:

    % pts listowned user1 
    Groups owned by user1 (id: 2857) are:   
      user1:friends

    % pts listowned user1:friends 
    Groups owned by user1:friends (id: -205) are:   
      user1:enemies

To add users to a group, you must be an owner of the group, or the system 
administrator, or been given permission by the group owner. The command 
to add users to a group is:

    % pts adduser user group

For example:
    
    % pts adduser user1 user1:enemies
    
    % pts adduser dsadmin user1:enemies
    
    % pts adduser user2 user1: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 user1:friends 
    Members of user1:friends (id: -205) are:   
      user2  
      user1

    % pts membership user1 
    Groups user1 (id: 2857) is a member of:   
      user1:enemies   
      user1:friends

Finally, you can delete users from a group with the command:

    % pts remove user


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 
    Normal rights:   
      user1 rlidwka
      system:anyuser l   
      system:administrators rlidwka

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 2 new 
subdirectories 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 
    Normal rights:   
      user1 rlidwka
      cs-machines rl   
      system:administrators rlidwka

    % fs la /afs/unc/home/user1/private 
    Access list for /afs/unc/home/user1/private is 
    Normal rights:   
      user1 rlidwka

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 specail 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
accesss 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 several files have been moved from your main 
home directory into ~/public and symbolic links left in their original 
locations. These files, such as .forward, calendar, and .plan, must 
be readable by everyone for the utility that uses them to run. (This 
is the same in NFS.)   The .forward file, for example, must be read by 
the mail process on our mail server, which does not have a token to 
read your home directory.

All your subdirectories 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.

To make a directory generally available to people in this department, 
add "system:authuser rl" to the ACL. System:authuser includes all users 
authenticated to our cell, and is much more protective than 
system:anyuser. The latter group includes anyone with AFS access 
anywhere in the world.