About Server Encryption Keys

An encryption key is a string of octal numbers used to encrypt and decrypt packets of information. In AFS, a server encryption key is the key used to protect information being transferred between AFS server processes and between them and their clients. A server encryption key is essentially a password for a server process and like a user password is stored in the Authentication Database.

Maintaining your cell's server encryption keys properly is the most basic way to protect the information in your AFS filespace from access by unauthorized users.

Keys and Mutual Authentication: A Review

Server encryption keys play a central role in the mutual authentication between client and server processes in AFS. For a more detailed description of mutual authentication, see A More Detailed Look at Mutual Authentication.

When a client wants to contact an AFS server, it first contacts the Ticket Granting Service (TGS) module of the Authentication Server. After verifying the client's identity (based indirectly on the password of the human user whom the client represents), the TGS gives the client a server ticket. This ticket is encrypted with the server's encryption key. (The TGS also invents a second encryption key, called the session key, to be used only for a single episode of communication between server and client. The server ticket and session key, together with other pieces of information, are collectively referred to as a token.)

The client cannot read the server ticket or token because it does not know the server encryption key. However, the client sends it to the AFS server along with service requests, because the ticket proves to the AFS server processes that it has already authenticated with the TGS. AFS servers trust the TGS to grant tickets only to valid clients. The fact that the client possesses a ticket encrypted with the server's encryption key proves to the server that the client is valid. On the other hand, the client assumes that only a genuine AFS server knows the server encryption key needed to decrypt the ticket. The server's ability to decrypt the ticket and understand its contents proves to the client that the server is legitimate.

Maintaining AFS Server Encryption Keys

As you maintain your cell's server encryption keys, keep the following in mind.

  • Change the key frequently to enhance your cell's security. Changing the key at least once a month is strongly recommended.

  • The AFS server encryption key currently in use is stored in two places. When you add a new key, you must make changes in both places and make them in the correct order, as instructed in Adding Server Encryption Keys. Failure to follow the instructions can seriously impair cell functioning, as clients and servers become unable to communicate. The two storage sites for the current server encryption key are the following:

    1. The file /usr/afs/etc/KeyFile on the local disk of every file server machine. The file can list more than one key, each with an associated numerical identifier, the key version number or kvno. A client token records the key version number of the key used to seal it, and the server process retrieves the appropriate key from this file when the client presents the token.

    2. The afs entry in the Authentication Database. The current server encryption key is in the entry's password field, just like an individual user's scrambled password. The Authentication Server's Ticket Granting Service (TGS) uses this key to encrypt the tokens it gives to clients. There is only a single key in the entry, because the TGS never needs to read existing tokens, but only to generate new ones by using the current key.

    For instructions on creating the initial afs entry and KeyFile files as you install your cell's first server machine, see the OpenAFS Quick Beginnings.

  • At any specific time, the tokens that the Authentication Server's Ticket Granting Service gives to clients are sealed with only one of the server encryption keys, namely the one stored in the afs entry in the Authentication Database.

  • When you add a new server encryption key, you cannot immediately remove the former key from the /usr/afs/etc/KeyFile file on the local disk of every AFS server machine. Any time that you add a new key, it is likely that some clients still have valid, unexpired tokens sealed with the previous key. The more frequently you change the server encryption key, the more such tickets there are likely to be. To be able to grant service appropriately to clients with such tokens, an AFS server process must still be able to access the server encryption key used to seal it.

    You can safely delete an old server encryption key only when it is certain that no clients have tokens sealed with that key. In general, wait a period of time at least as long as the maximum token lifetime in your cell. By default, the maximum token lifetime for users is 25 hours (except for users whose Authentication Database entries were created by using the 3.0 version of AFS, for whom the default is 100 hours). You can use the -lifetime argument to the kas setfields command to change this default.

    Instructions for removing obsolete keys appear in Removing Server Encryption Keys.

  • You create a new AFS server encryption key in much the same way regular users change their passwords, by providing a character string that is converted into an encryption key automatically. See Adding Server Encryption Keys.

  • In addition to using server encryption keys when communicating with clients, the server processes use them to protect communications with other server processes. Therefore, all server machines in your cell must have the same version of the KeyFile file. The easiest way to maintain consistency (if you run the United States edition of AFS) is to use the Update Server to distribute the contents of the system control machine's /usr/afs/etc directory to all of the other server machines. There are two implications:

    • You must run the upserver process on the system control machine and an upclientetc process on all other server machines that references the system control machine. The OpenAFS Quick Beginnings explains how to install both processes. For instructions on verifying that the Update Server processes are running, see Displaying Process Status and Information from the BosConfig File.

    • Change the KeyFile file only on the system control machine (except in the types of emergencies discussed in Handling Server Encryption Key Emergencies). Any changes you make on other server machines are overwritten the next time the upclientetc process retrieves the contents of the system control machine's /usr/afs/etc directory. By default, this happens every five minutes.

    If you run the international edition of AFS, do not use the Update Server to distribute the contents of the /usr/afs/etc directory, particularly the KeyFile file. The data in the file is too sensitive for transfer in unencrypted form, and because of United States government exports regulations the international edition of AFS does not include the necessary encryption routines in a form that the Update Server can use. You must instead modify the file on each server machine individually, taking care to enter the same key on every server machine.

  • Never edit the KeyFile directly with a text editor. Instead, always use the appropriate bos commands as instructed in Adding Server Encryption Keys and Removing Server Encryption Keys.