Adding Server Encryption Keys

Adding Server Encryption Keys
	Chapter 9. Managing Server Encryption Keys

As noted, AFS records server encryption keys in two separate places:

In the file /usr/afs/etc/KeyFile on the local disk of each server machine, for use by the AFS server processes running on the machine
In the afs entry in the Authentication Database, for use by the Ticket Granting Service (TGS) when creating tokens

To ensure that server processes and the TGS share the same AFS server encryption key, execute all the steps in this section without interruption.

The following instructions include a step in which you restart the database server processes (the Authentication, Backup, Protection, and Volume Location Server processes) on all database server machines. As a database server process starts, it reads in the server encryption key that has the highest key version number in the KeyFile file and uses it to protect the messages that it sends for synchronizing the database and maintaining quorum. It uses the same key throughout its lifetime, which can be for an extended period, even if you remove the key from the KeyFile file. However, if one of the peer database server processes restarts and the others do not, quorum and database synchronization break down because the processes are no longer using the same key: the restarted process is using the key that currently has the highest key version number, and the other processes are still using the key they read in when they originally started. To avoid this problem, it is safest to restart all of the database server processes when adding a new key.

After adding a new key, you can remove obsolete keys from the KeyFile file to prevent it from becoming cluttered. However, you must take care not to remove keys that client or server processes are still using. For discussion and instructions, see Removing Server Encryption Keys.

To add a new server encryption key

Verify that you are authenticated as a user listed in the /usr/afs/etc/UserList file. If necessary, issue the bos listusers command, which is fully described in To display the users in the UserList file.
```
   % bos listusers <machine name>
```
Issue the bos listkeys command to display the key version numbers that are already in use, as a first step in choosing the key version number for the new key.
```
   % bos listkeys <machine name>
```
where
listk
Is the shortest acceptable abbreviation of listkeys.
machine name
Names any file server machine.
Choose a key version number for the new key, based on the output from Step 2 and the following requirements:
- A key version number must be an integer between 0 (zero) and 255 to comply with Kerberos standards. It is simplest if you keep your key version numbers in sequence by choosing a key version number one greater than the largest existing one.
- Do not reuse a key version number currently found in the KeyFile file, particularly if it is also the one in the Authentication Database afs entry. Client processes possibly still have tickets sealed with the key that originally had that key version number, but the server processes start using the new key marked with that key version number. Because the keys do not match, the server processes refuse requests from clients who hold legitimate tokens.
Issue the bos addkey command to create a new AFS server encryption key in the KeyFile file.
If you use the Update Server to distribute the contents of the system control machine's /usr/afs/etc directory, substitute the system control machine for the machine name argument. (If you have forgotten which machine is the system control machine, see To locate the system control machine.)
To avoid visible echoing of the string that corresponds to the new key, omit the -key argument from the command line; instead enter the string at the prompts that appear when you omit it, as shown in the following syntax specification.
```
   % bos addkey  -server <machine name> -kvno <key version number>
   input key: <afs_password>
   Retype input key: <afs_password>
```
where
addk
Is the shortest acceptable abbreviation of addkey.
-server
Names the cell's system control machine if you are using the Update Server, or each server machine in turn if you are not.
-kvno
Specifies the new key's key version number as an integer from the range 0 (zero) through 255.
Remember the number. You need to use it again in Step 6.
afs_password
Is a character string similar to a user password, of any length from one to about 1,000 characters. To improve security, include nonalphabetic characters and make the string as long as is practical (you need to type it only in this step and in Step 6).
Do not enter an octal string directly. The BOS Server scrambles the character string into an octal string appropriate for use as an encryption key before recording it in the KeyFile file.
If you are using the Update Server, wait for a few minutes while the Update Server distributes the new KeyFile file to all server machines. The maximum necessary waiting period is the largest value provided for the -t argument to the upclientetc process's initialization command used on any of the server machines; the default time is five minutes.
To be certain that all machines have the same KeyFile file, issue the bos listkeys command for every file server machine and verify that the checksum for the new key is the same on all machines.
```
   % bos listkeys <machine name>
```
If you are not using the Update Server, try to complete Step 4 within five minutes.
Issue the kas setpassword command to enter the same key in the afs entry in the Authentication Database.
The Authentication Server performs its own authentication rather than accepting your existing AFS token. By default, it authenticates your local (UNIX) identity, which possibly does not correspond to an AFS-privileged administrator. Include the -admin argument to name an identity that has the ADMIN flag on its Authentication Database entry. To verify that an entry has the flag, issue the kas examine command as described in To check if the ADMIN flag is set.
```
   % kas setpassword -name afs -kvno <kvno>  \
                     -admin  <admin principal to use for authentication>  
   Administrator's (admin_user) password: <admin_password>
   new_password: afs_password
   Verifying, please re-enter new_password: <admin_password>
```
where
sp
Is an acceptable alias for setpassword (setp is the shortest acceptable abbreviation).
-name afs
Creates the new key in the afs entry.
-kvno
Specifies the same key version number as in Step 4.
-admin
Names an administrative account with the ADMIN flag on its Authentication Database entry, such as admin. The password prompt echoes it as admin_user. Enter the appropriate password as admin_password.
afs_password
Is the same character string you entered in Step 4.
(Optional.) If you want to verify that the keys you just created in the KeyFile file and the Authentication Database afs entry are identical and have the same key version number, follow the instructions in Displaying Server Encryption Keys.
Issue the bos restart command to restart the database server processes on all database server machines. This forces them to start using the key in the KeyFile file that currently has the highest key version number.
Repeat this command in quick succession for each database server machine, starting with the machine that has the lowest IP address.
```
   % bos restart  <machine name> buserver kaserver ptserver vlserver
```
where
res
Is the shortest acceptable abbreviation of restart.
machine name
Names each database server machine in turn.
buserver kaserver ptserver vlserver
Designates the Backup Server, Authentication Server, Protection Server, and Volume Location (VL) Server, respectively.


Displaying Server Encryption Keys		Removing Server Encryption Keys