jimzah/openafs
1
0
Fork 0
mirror of https://git.openafs.org/openafs.git synced 2025-01-20 07:51:00 +00:00
Code Issues Actions Packages Projects Releases Wiki Activity
81e1d54034
openafs/doc/xml/AdminGuide/c20494.html

3231 lines
63 KiB
HTML
Raw Normal View History

xml-docbook-documentation-first-pass-20060915 needs more massaging to make it fit the tree, but, get it here first
2006-09-16 02:13:22 +01:00
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<HTML
><HEAD
><TITLE
>Managing Server Encryption Keys</TITLE
><META
NAME="GENERATOR"
CONTENT="Modular DocBook HTML Stylesheet Version 1.7"><LINK
REL="HOME"
TITLE="AFS Administration Guide"
HREF="book1.html"><LINK
REL="UP"
TITLE="Managing File Server Machines"
HREF="p3023.html"><LINK
REL="PREVIOUS"
TITLE="Monitoring and Auditing AFS Performance"
HREF="c18360.html"><LINK
REL="NEXT"
TITLE="Managing Client Machines"
HREF="p21471.html"></HEAD
><BODY
CLASS="chapter"
BGCOLOR="#FFFFFF"
TEXT="#000000"
LINK="#0000FF"
VLINK="#840084"
ALINK="#0000FF"
><DIV
CLASS="NAVHEADER"
><TABLE
SUMMARY="Header navigation table"
WIDTH="100%"
BORDER="0"
CELLPADDING="0"
CELLSPACING="0"
><TR
><TH
COLSPAN="3"
ALIGN="center"
>AFS Administration Guide: Version 3.6</TH
></TR
><TR
><TD
WIDTH="10%"
ALIGN="left"
VALIGN="bottom"
><A
HREF="c18360.html"
ACCESSKEY="P"
>Prev</A
></TD
><TD
WIDTH="80%"
ALIGN="center"
VALIGN="bottom"
></TD
><TD
WIDTH="10%"
ALIGN="right"
VALIGN="bottom"
><A
HREF="p21471.html"
ACCESSKEY="N"
>Next</A
></TD
></TR
></TABLE
><HR
ALIGN="LEFT"
WIDTH="100%"></DIV
><DIV
CLASS="chapter"
><H1
><A
NAME="HDRWQ355"
></A
>Chapter 9. Managing Server Encryption Keys</H1
><P
>This chapter explains how to maintain your cell's server encryption keys, which are vital for secure communications in
AFS.</P
><DIV
CLASS="sect1"
><H1
CLASS="sect1"
><A
NAME="HDRWQ356"
>Summary of Instructions</A
></H1
><P
>This chapter explains how to perform the following tasks by using the indicated commands:</P
><DIV
CLASS="informaltable"
><A
NAME="AEN20500"
></A
><TABLE
BORDER="0"
FRAME="void"
CLASS="CALSTABLE"
><COL
WIDTH="70*"><COL
WIDTH="30*"><TBODY
><TR
><TD
>Add a new server encryption key</TD
><TD
><SPAN
CLASS="bold"
><B
CLASS="emphasis"
>bos addkey</B
></SPAN
> and <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>kas setpassword</B
></SPAN
></TD
></TR
><TR
><TD
>Inspect key checksums in the Authentication Database</TD
><TD
><SPAN
CLASS="bold"
><B
CLASS="emphasis"
>kas examine</B
></SPAN
></TD
></TR
><TR
><TD
>Inspect key checksums in the <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>KeyFile</B
></SPAN
></TD
><TD
><SPAN
CLASS="bold"
><B
CLASS="emphasis"
>bos listkeys</B
></SPAN
></TD
></TR
><TR
><TD
>Remove an old server encryption key</TD
><TD
><SPAN
CLASS="bold"
><B
CLASS="emphasis"
>bos removekey</B
></SPAN
></TD
></TR
></TBODY
></TABLE
></DIV
></DIV
><DIV
CLASS="sect1"
><H1
CLASS="sect1"
><A
NAME="HDRWQ358"
>About Server Encryption Keys</A
></H1
><P
>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.</P
><P
>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.</P
><DIV
CLASS="sect2"
><H2
CLASS="sect2"
><A
NAME="Header_412"
>Keys and Mutual Authentication: A Review</A
></H2
><P
>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
HREF="c667.html#HDRWQ75"
>A More Detailed Look at Mutual
Authentication</A
>.</P
><P
>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.)</P
><P
>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.</P
></DIV
><DIV
CLASS="sect2"
><H2
CLASS="sect2"
><A
NAME="Header_413"
>Maintaining AFS Server Encryption Keys</A
></H2
><P
>As you maintain your cell's server encryption keys, keep the following in mind. <UL
><LI
><P
>Change the key frequently to enhance your cell's security. Changing the key at least once a month is strongly
recommended.</P
></LI
><LI
><P
>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 <A
HREF="c20494.html#HDRWQ362"
>Adding Server
Encryption Keys</A
>. 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:
<OL
TYPE="1"
><LI
><P
>The file <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>/usr/afs/etc/KeyFile</B
></SPAN
> 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.</P
></LI
><LI
><P
>The <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>afs</B
></SPAN
> 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.</P
></LI
></OL
></P
><P
>For instructions on creating the initial <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>afs</B
></SPAN
> entry and <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>KeyFile</B
></SPAN
> files as you install your cell's first server machine, see the IBM AFS Quick
Beginnings.</P
></LI
><LI
><P
>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 <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>afs</B
></SPAN
>
entry in the Authentication Database.</P
></LI
><LI
><P
>When you add a new server encryption key, you cannot immediately remove the former key from the <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>/usr/afs/etc/KeyFile</B
></SPAN
> 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.</P
><P
>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 <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>-lifetime</B
></SPAN
> argument to the <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>kas setfields</B
></SPAN
> command to change this
default.</P
><P
>Instructions for removing obsolete keys appear in <A
HREF="c20494.html#HDRWQ368"
>Removing Server Encryption
Keys</A
>.</P
></LI
><LI
><P
>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 <A
HREF="c20494.html#HDRWQ362"
>Adding Server
Encryption Keys</A
>.</P
></LI
><LI
><P
>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 <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>KeyFile</B
></SPAN
> 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
<SPAN
CLASS="bold"
><B
CLASS="emphasis"
>/usr/afs/etc</B
></SPAN
> directory to all of the other server machines. There are two implications:
<UL
><LI
><P
>You must run the <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>upserver</B
></SPAN
> process on the system control machine and an
<SPAN
CLASS="bold"
><B
CLASS="emphasis"
>upclientetc</B
></SPAN
> process on all other server machines that references the system
control machine. The IBM AFS Quick Beginnings explains how to install both processes. For instructions on
verifying that the Update Server processes are running, see <A
HREF="c6449.html#HDRWQ158"
>Displaying Process Status and
Information from the BosConfig File</A
>.</P
></LI
><LI
><P
>Change the <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>KeyFile</B
></SPAN
> file only on the system control machine (except in the
types of emergencies discussed in <A
HREF="c20494.html#HDRWQ370"
>Handling Server Encryption Key Emergencies</A
>). Any
changes you make on other server machines are overwritten the next time the <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>upclientetc</B
></SPAN
> process retrieves the contents of the system control machine's <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>/usr/afs/etc</B
></SPAN
> directory. By default, this happens every five minutes.</P
></LI
></UL
></P
><P
>If you run the international edition of AFS, do not use the Update Server to distribute the contents of the
<SPAN
CLASS="bold"
><B
CLASS="emphasis"
>/usr/afs/etc</B
></SPAN
> directory, particularly the <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>KeyFile</B
></SPAN
> 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.</P
></LI
><LI
><P
>Never edit the <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>KeyFile</B
></SPAN
> directly with a text editor. Instead, always use the
appropriate <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>bos</B
></SPAN
> commands as instructed in <A
HREF="c20494.html#HDRWQ362"
>Adding Server
Encryption Keys</A
> and <A
HREF="c20494.html#HDRWQ368"
>Removing Server Encryption Keys</A
>.</P
></LI
></UL
></P
></DIV
></DIV
><DIV
CLASS="sect1"
><H1
CLASS="sect1"
><A
NAME="HDRWQ359"
>Displaying Server Encryption Keys</A
></H1
><P
>To display the server encryption keys in the <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>/usr/afs/etc/KeyFile</B
></SPAN
> file on any file server
machine, use the <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>bos listkeys</B
></SPAN
> command. Use the <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>kas examine</B
></SPAN
>
command to display the key in the Authentication Database's <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>afs</B
></SPAN
> entry.</P
><P
>By default the commands do not display the actual string of octal digits that constitute a key, but rather a checksum, a
decimal number derived by encrypting a constant with the key. This prevents unauthorized users from easily accessing the actual
key, which they can then use to falsify or eavesdrop on protected communications. The <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>bos
listkeys</B
></SPAN
> and <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>kas examine</B
></SPAN
> commands generate the same checksum for a given key, so
displaying checksums rather than actual keys is generally sufficient. If you suspect that the keys differ in a way that the
checksums are not revealing, then you are probably experiencing authentication problems throughout your cell. The easiest
solution is to create a new server encryption key following the instructions in <A
HREF="c20494.html#HDRWQ362"
>Adding Server
Encryption Keys</A
> or <A
HREF="c20494.html#HDRWQ370"
>Handling Server Encryption Key Emergencies</A
>. Another common reason to
issue the <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>bos listkeys</B
></SPAN
> command is to display the key version numbers currently in use, in
preparation for choosing the next one; here, the checksum is sufficient because the key itself is irrelevant.</P
><P
>If it is important to display the actual octal digits, include the <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>-showkey</B
></SPAN
> argument to
both the <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>bos listkeys</B
></SPAN
> and <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>kas examine</B
></SPAN
> commands.</P
><DIV
CLASS="sect2"
><H2
CLASS="sect2"
><A
NAME="HDRWQ360"
>To display the KeyFile file</A
></H2
><OL
TYPE="1"
><LI
><P
>Verify that you are authenticated as a user listed in the <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>/usr/afs/etc/UserList</B
></SPAN
>
file. If necessary, issue the <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>bos listusers</B
></SPAN
> command, which is fully described in <A
HREF="c32432.html#HDRWQ593"
>To display the users in the UserList file</A
>. <PRE
CLASS="programlisting"
>&#13; % <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>bos listusers</B
></SPAN
> &#60;<VAR
CLASS="replaceable"
>machine name</VAR
>&#62;
</PRE
></P
></LI
><LI
><P
>Issue the <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>bos listkeys</B
></SPAN
> command to display the contents of one machine's <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>/usr/afs/etc/KeyFile</B
></SPAN
> file. <PRE
CLASS="programlisting"
>&#13; % <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>bos listkeys</B
></SPAN
> &#60;<VAR
CLASS="replaceable"
>machine name</VAR
>&#62; [<SPAN
CLASS="bold"
><B
CLASS="emphasis"
>-showkey</B
></SPAN
>]
</PRE
></P
><P
>where <DIV
CLASS="variablelist"
><DL
><DT
><SPAN
CLASS="bold"
><B
CLASS="emphasis"
>listk</B
></SPAN
></DT
><DD
><P
>Is the shortest acceptable abbreviation of <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>listkeys</B
></SPAN
>.</P
></DD
><DT
><SPAN
CLASS="bold"
><B
CLASS="emphasis"
>machine name</B
></SPAN
></DT
><DD
><P
>Names a file server machine. In the normal case, it is acceptable to name any machine, because correct cell
functioning requires that the <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>KeyFile</B
></SPAN
> file be the same on all of them.</P
></DD
><DT
><SPAN
CLASS="bold"
><B
CLASS="emphasis"
>-showkey</B
></SPAN
></DT
><DD
><P
>Displays the octal digits that constitute each key.</P
></DD
></DL
></DIV
></P
></LI
></OL
><P
>In the following example, the output displays a checksum for each server encryption key rather than the actual octal
digits. The penultimate line indicates when an administrator last changed the file, and the final line confirms that the
output is complete.</P
><PRE
CLASS="programlisting"
>&#13; % <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>bos listkeys fs1.abc.com</B
></SPAN
>
key 0 has cksum 972037177
key 1 has cksum 2825165022
Keys last changed on Wed Jan 13 11:20:29 1999.
All done.
</PRE
></DIV
><DIV
CLASS="sect2"
><H2
CLASS="sect2"
><A
NAME="HDRWQ361"
>To display the afs key from the Authentication Database</A
></H2
><OL
TYPE="1"
><LI
><P
>Issue the <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>kas examine</B
></SPAN
> command to display the <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>afs</B
></SPAN
>
entry in the Authentication Database.</P
><P
>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 <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>-admin</B
></SPAN
> argument to name an identity that has the
<SAMP
CLASS="computeroutput"
>ADMIN</SAMP
> flag on its Authentication Database entry. To verify that an entry has the flag,
issue the <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>kas examine</B
></SPAN
> command as described in <A
HREF="c32432.html#HDRWQ590"
>To check if the
ADMIN flag is set</A
>.</P
><PRE
CLASS="programlisting"
>&#13; % <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>kas examine afs</B
></SPAN
> [<SPAN
CLASS="bold"
><B
CLASS="emphasis"
>-showkey</B
></SPAN
>] \
<SPAN
CLASS="bold"
><B
CLASS="emphasis"
>-admin</B
></SPAN
> &#60;<VAR
CLASS="replaceable"
>admin principal to use for authentication</VAR
>&#62;
Administrator's (admin_user) password: &#60;<VAR
CLASS="replaceable"
>admin_password</VAR
>&#62;
</PRE
><P
>where <DIV
CLASS="variablelist"
><DL
><DT
><SPAN
CLASS="bold"
><B
CLASS="emphasis"
>e</B
></SPAN
></DT
><DD
><P
>Is the shortest acceptable abbreviation of <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>examine</B
></SPAN
>.</P
></DD
><DT
><SPAN
CLASS="bold"
><B
CLASS="emphasis"
>afs</B
></SPAN
></DT
><DD
><P
>Designates the <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>afs</B
></SPAN
> entry.</P
></DD
><DT
><SPAN
CLASS="bold"
><B
CLASS="emphasis"
>-showkey</B
></SPAN
></DT
><DD
><P
>Displays the octal digits that constitute the key.</P
></DD
><DT
><SPAN
CLASS="bold"
><B
CLASS="emphasis"
>-admin</B
></SPAN
></DT
><DD
><P
>Names an administrative account with the <SAMP
CLASS="computeroutput"
>ADMIN</SAMP
> flag on its Authentication
Database entry, such as <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>admin</B
></SPAN
>. The password prompt echoes it as admin_user. Enter
the appropriate password as admin_password.</P
></DD
></DL
></DIV
></P
></LI
></OL
><P
>In the following example, the <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>admin</B
></SPAN
> user displays the <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>afs</B
></SPAN
> entry without using the <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>-showkey</B
></SPAN
> flag. The second line shows the
key version number in parentheses and the key's checksum. The line that begins with the string <SAMP
CLASS="computeroutput"
>last
mod</SAMP
> reports the date on which the indicated administrator changed the key. There is no necessary relationship
between this date and the date reported by the <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>bos listkeys</B
></SPAN
> command, because the latter date
changes for any type of change to the <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>KeyFile</B
></SPAN
> file, not just a key addition. For a
description of the other lines in the output from the <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>kas examine</B
></SPAN
> command, see its reference
page in the IBM AFS Administration Reference.</P
><PRE
CLASS="programlisting"
>&#13; % <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>kas examine afs -admin admin</B
></SPAN
>
Administrator's (admin) password: &#60;<VAR
CLASS="replaceable"
>admin_password</VAR
>&#62;
User data for afs
key (1) cksum is 2825165022, last cpw: no date
password will never expire.
An unlimited number of unsuccessful authentications is permitted.
entry expires on never. Max ticket lifetime 100.00 hours.
last mod on Wed Jan 13 11:21:36 1999 by admin
permit password reuse
</PRE
></DIV
></DIV
><DIV
CLASS="sect1"
><H1
CLASS="sect1"
><A
NAME="HDRWQ362"
>Adding Server Encryption Keys</A
></H1
><P
>As noted, AFS records server encryption keys in two separate places: <OL
TYPE="1"
><LI
><P
>In the file <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>/usr/afs/etc/KeyFile</B
></SPAN
> on the local disk of each server machine, for use
by the AFS server processes running on the machine</P
></LI
><LI
><P
>In the <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>afs</B
></SPAN
> entry in the Authentication Database, for use by the Ticket Granting
Service (TGS) when creating tokens</P
></LI
></OL
></P
><P
>To ensure that server processes and the TGS share the same AFS server encryption key, execute all the steps in this
section without interruption.</P
><P
>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 <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>KeyFile</B
></SPAN
> 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 <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>KeyFile</B
></SPAN
> 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.</P
><P
>After adding a new key, you can remove obsolete keys from the <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>KeyFile</B
></SPAN
> 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 <A
HREF="c20494.html#HDRWQ368"
>Removing Server Encryption Keys</A
>.</P
><DIV
CLASS="sect2"
><H2
CLASS="sect2"
><A
NAME="HDRWQ363"
>To add a new server encryption key</A
></H2
><OL
TYPE="1"
><LI
><P
>Verify that you are authenticated as a user listed in the <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>/usr/afs/etc/UserList</B
></SPAN
>
file. If necessary, issue the <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>bos listusers</B
></SPAN
> command, which is fully described in <A
HREF="c32432.html#HDRWQ593"
>To display the users in the UserList file</A
>. <PRE
CLASS="programlisting"
>&#13; % <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>bos listusers</B
></SPAN
> &#60;<VAR
CLASS="replaceable"
>machine name</VAR
>&#62;
</PRE
></P
></LI
><LI
><P
><A
NAME="LIWQ364"
></A
>Issue the <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>bos listkeys</B
></SPAN
> 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. <PRE
CLASS="programlisting"
>&#13; % <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>bos listkeys</B
></SPAN
> &#60;<VAR
CLASS="replaceable"
>machine name</VAR
>&#62;
</PRE
></P
><P
>where <DIV
CLASS="variablelist"
><DL
><DT
><SPAN
CLASS="bold"
><B
CLASS="emphasis"
>listk</B
></SPAN
></DT
><DD
><P
>Is the shortest acceptable abbreviation of <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>listkeys</B
></SPAN
>.</P
></DD
><DT
><SPAN
CLASS="bold"
><B
CLASS="emphasis"
>machine name</B
></SPAN
></DT
><DD
><P
>Names any file server machine.</P
></DD
></DL
></DIV
></P
></LI
><LI
><P
><A
NAME="LIWQ365"
></A
>Choose a key version number for the new key, based on the output from Step <A
HREF="c20494.html#LIWQ364"
>2</A
> and the following requirements: <UL
><LI
><P
>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.</P
></LI
><LI
><P
>Do not reuse a key version number currently found in the <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>KeyFile</B
></SPAN
> file,
particularly if it is also the one in the Authentication Database <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>afs</B
></SPAN
> 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.</P
></LI
></UL
></P
></LI
><LI
><P
><A
NAME="LIWQ366"
></A
>Issue the <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>bos addkey</B
></SPAN
> command to create a new AFS server
encryption key in the <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>KeyFile</B
></SPAN
> file.</P
><P
>If you run the United States edition of AFS and use the Update Server to distribute the contents of the system
control machine's <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>/usr/afs/etc</B
></SPAN
> directory, substitute the system control machine for the
machine name argument. (If you have forgotten which machine is the system control machine, see <A
HREF="c3025.html#HDRWQ96"
>To
locate the system control machine</A
>.)</P
><P
>If you run the international edition of AFS or do not use the Update Server, repeat the <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>bos
addkey</B
></SPAN
> command, substituting each server machine in your cell for the machine name argument in turn.</P
><P
>To avoid visible echoing of the string that corresponds to the new key, omit the <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>-key</B
></SPAN
> 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.</P
><PRE
CLASS="programlisting"
>&#13; % <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>bos addkey -server</B
></SPAN
> &#60;<VAR
CLASS="replaceable"
>machine name</VAR
>&#62; <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>-kvno</B
></SPAN
> &#60;<VAR
CLASS="replaceable"
>key version number</VAR
>&#62;
input key: &#60;<VAR
CLASS="replaceable"
>afs_password</VAR
>&#62;
Retype input key: &#60;<VAR
CLASS="replaceable"
>afs_password</VAR
>&#62;
</PRE
><P
>where <DIV
CLASS="variablelist"
><DL
><DT
><SPAN
CLASS="bold"
><B
CLASS="emphasis"
>addk</B
></SPAN
></DT
><DD
><P
>Is the shortest acceptable abbreviation of <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>addkey</B
></SPAN
>.</P
></DD
><DT
><SPAN
CLASS="bold"
><B
CLASS="emphasis"
>-server</B
></SPAN
></DT
><DD
><P
>Names the cell's system control machine if you are using the Update Server, or each server machine in turn
if you are not.</P
></DD
><DT
><SPAN
CLASS="bold"
><B
CLASS="emphasis"
>-kvno</B
></SPAN
></DT
><DD
><P
>Specifies the new key's key version number as an integer from the range 0 (zero) through 255.</P
><P
>Remember the number. You need to use it again in Step <A
HREF="c20494.html#LIWQ367"
>6</A
>. If you are using the
international edition of AFS, be sure to type the same number each time you issue this command.</P
></DD
><DT
><SPAN
CLASS="bold"
><B
CLASS="emphasis"
>afs_password</B
></SPAN
></DT
><DD
><P
>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 <A
HREF="c20494.html#LIWQ367"
>6</A
>). If you are using the international edition of
AFS, be sure to type the same string each time you issue this command.</P
><P
>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 <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>KeyFile</B
></SPAN
>
file.</P
></DD
></DL
></DIV
></P
></LI
><LI
><P
>If you are using the Update Server, wait for a few minutes while the Update Server distributes the new <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>KeyFile</B
></SPAN
> file to all server machines. The maximum necessary waiting period is the largest value
provided for the <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>-t</B
></SPAN
> argument to the <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>upclientetc</B
></SPAN
>
process's initialization command used on any of the server machines; the default time is five minutes.</P
><P
>To be certain that all machines have the same <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>KeyFile</B
></SPAN
> file, issue the <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>bos listkeys</B
></SPAN
> command for every file server machine and verify that the checksum for the new key is
the same on all machines.</P
><PRE
CLASS="programlisting"
>&#13; % <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>bos listkeys</B
></SPAN
> &#60;<VAR
CLASS="replaceable"
>machine name</VAR
>&#62;
</PRE
><P
>If you are not using the Update Server, try to complete Step <A
HREF="c20494.html#LIWQ366"
>4</A
> within five
minutes.</P
></LI
><LI
><P
><A
NAME="LIWQ367"
></A
>Issue the <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>kas setpassword</B
></SPAN
> command to enter the same key in
the <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>afs</B
></SPAN
> entry in the Authentication Database.</P
><P
>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 <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>-admin</B
></SPAN
> argument to name an identity that has the
<SAMP
CLASS="computeroutput"
>ADMIN</SAMP
> flag on its Authentication Database entry. To verify that an entry has the flag,
issue the <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>kas examine</B
></SPAN
> command as described in <A
HREF="c32432.html#HDRWQ590"
>To check if the
ADMIN flag is set</A
>.</P
><PRE
CLASS="programlisting"
>&#13; % <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>kas setpassword -name afs -kvno</B
></SPAN
> &#60;<VAR
CLASS="replaceable"
>kvno</VAR
>&#62; \
<SPAN
CLASS="bold"
><B
CLASS="emphasis"
>-admin</B
></SPAN
> &#60;<VAR
CLASS="replaceable"
>admin principal to use for authentication</VAR
>&#62;
Administrator's (admin_user) password: &#60;<VAR
CLASS="replaceable"
>admin_password</VAR
>&#62;
new_password: afs_password
Verifying, please re-enter new_password: &#60;<VAR
CLASS="replaceable"
>admin_password</VAR
>&#62;
</PRE
><P
>where <DIV
CLASS="variablelist"
><DL
><DT
><SPAN
CLASS="bold"
><B
CLASS="emphasis"
>sp</B
></SPAN
></DT
><DD
><P
>Is an acceptable alias for <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>setpassword</B
></SPAN
> (<SPAN
CLASS="bold"
><B
CLASS="emphasis"
>setp</B
></SPAN
> is the shortest acceptable abbreviation).</P
></DD
><DT
><SPAN
CLASS="bold"
><B
CLASS="emphasis"
>-name afs</B
></SPAN
></DT
><DD
><P
>Creates the new key in the <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>afs</B
></SPAN
> entry.</P
></DD
><DT
><SPAN
CLASS="bold"
><B
CLASS="emphasis"
>-kvno</B
></SPAN
></DT
><DD
><P
>Specifies the same key version number as in Step <A
HREF="c20494.html#LIWQ366"
>4</A
>.</P
></DD
><DT
><SPAN
CLASS="bold"
><B
CLASS="emphasis"
>-admin</B
></SPAN
></DT
><DD
><P
>Names an administrative account with the <SAMP
CLASS="computeroutput"
>ADMIN</SAMP
> flag on its Authentication
Database entry, such as <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>admin</B
></SPAN
>. The password prompt echoes it as admin_user. Enter
the appropriate password as admin_password.</P
></DD
><DT
><SPAN
CLASS="bold"
><B
CLASS="emphasis"
>afs_password</B
></SPAN
></DT
><DD
><P
>Is the same character string you entered in Step <A
HREF="c20494.html#LIWQ366"
>4</A
>.</P
></DD
></DL
></DIV
></P
></LI
><LI
><P
><SPAN
CLASS="bold"
><B
CLASS="emphasis"
>(Optional.)</B
></SPAN
> If you want to verify that the keys you just created in the <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>KeyFile</B
></SPAN
> file and the Authentication Database <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>afs</B
></SPAN
> entry are
identical and have the same key version number, follow the instructions in <A
HREF="c20494.html#HDRWQ359"
>Displaying Server
Encryption Keys</A
>.</P
></LI
><LI
><P
>Issue the <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>bos restart</B
></SPAN
> command to restart the database server processes on all
database server machines. This forces them to start using the key in the <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>KeyFile</B
></SPAN
> file
that currently has the highest key version number.</P
><P
>Repeat this command in quick succession for each database server machine, starting with the machine that has the
lowest IP address.</P
><PRE
CLASS="programlisting"
>&#13; % <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>bos restart</B
></SPAN
> &#60;<VAR
CLASS="replaceable"
>machine name</VAR
>&#62; <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>buserver kaserver ptserver vlserver</B
></SPAN
>
</PRE
><P
>where <DIV
CLASS="variablelist"
><DL
><DT
><SPAN
CLASS="bold"
><B
CLASS="emphasis"
>res</B
></SPAN
></DT
><DD
><P
>Is the shortest acceptable abbreviation of <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>restart</B
></SPAN
>.</P
></DD
><DT
><SPAN
CLASS="bold"
><B
CLASS="emphasis"
>machine name</B
></SPAN
></DT
><DD
><P
>Names each database server machine in turn.</P
></DD
><DT
><SPAN
CLASS="bold"
><B
CLASS="emphasis"
>buserver kaserver ptserver vlserver</B
></SPAN
></DT
><DD
><P
>Designates the Backup Server, Authentication Server, Protection Server, and Volume Location (VL) Server,
respectively.</P
></DD
></DL
></DIV
></P
></LI
></OL
></DIV
></DIV
><DIV
CLASS="sect1"
><H1
CLASS="sect1"
><A
NAME="HDRWQ368"
>Removing Server Encryption Keys</A
></H1
><P
>You can periodically remove old keys from the <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>/usr/afs/etc/KeyFile</B
></SPAN
> file to keep it to a
reasonable size. To avoid disturbing cell functioning, do not remove an old key until all tokens sealed with the key and held by
users or client processes have expired. After adding a new key, wait to remove old keys at least as long as the longest token
lifetime you use in your cell. For Authentication Database user entries created under AFS version 3.1 or higher, the default
token lifetime is 25 hours; for entries created under AFS version 3.0, it is 100 hours.</P
><P
>There is no command for removing the key from the <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>afs</B
></SPAN
> entry in the Authentication
Database, because the key field in that entry must never be empty. Use the <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>kas setpassword</B
></SPAN
>
command to replace the <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>afs</B
></SPAN
> key, but only as part of the complete procedure detailed in <A
HREF="c20494.html#HDRWQ363"
>To add a new server encryption key</A
>.</P
><P
>Never remove from the <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>KeyFile</B
></SPAN
> file the key that is currently in the <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>afs</B
></SPAN
> entry in the Authentication Database. AFS server processes become unable to decrypt the tickets that
clients present to them.</P
><DIV
CLASS="sect2"
><H2
CLASS="sect2"
><A
NAME="HDRWQ369"
>To remove a key from the KeyFile file</A
></H2
><OL
TYPE="1"
><LI
><P
>Verify that you are authenticated as a user listed in the <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>/usr/afs/etc/UserList</B
></SPAN
>
file. If necessary, issue the <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>bos listusers</B
></SPAN
> command, which is fully described in <A
HREF="c32432.html#HDRWQ593"
>To display the users in the UserList file</A
>. <PRE
CLASS="programlisting"
>&#13; % <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>bos listusers</B
></SPAN
> &#60;<VAR
CLASS="replaceable"
>machine name</VAR
>&#62;
</PRE
></P
></LI
><LI
><P
>Issue the <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>bos listkeys</B
></SPAN
> command to display the key version number of each key you
want to remove. The output also reveals whether it has been at least 25 hours since a new key was placed in the <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>KeyFile</B
></SPAN
> file. For complete instructions for the <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>bos listkeys</B
></SPAN
>
command, see <A
HREF="c20494.html#HDRWQ360"
>To display the KeyFile file</A
>. <PRE
CLASS="programlisting"
>&#13; % <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>bos listkeys</B
></SPAN
> &#60;<VAR
CLASS="replaceable"
>machine name</VAR
>&#62;
</PRE
></P
></LI
><LI
><P
>Issue the <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>kas examine</B
></SPAN
> command to verify that the key currently in the
Authentication Database's <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>afs</B
></SPAN
> entry does not have the same key version number as any of
the keys you are removing from the <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>KeyFile</B
></SPAN
> file. For detailed instructions for the
<SPAN
CLASS="bold"
><B
CLASS="emphasis"
>kas examine</B
></SPAN
> command, see <A
HREF="c20494.html#HDRWQ361"
>To display the afs key from the
Authentication Database</A
>. <PRE
CLASS="programlisting"
>&#13; % <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>kas examine afs -admin</B
></SPAN
> &#60;<VAR
CLASS="replaceable"
>admin principal to use for authentication</VAR
>&#62;
Administrator's (admin_user) password: &#60;<VAR
CLASS="replaceable"
>admin_password</VAR
>&#62;
</PRE
></P
></LI
><LI
><P
>Issue the <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>bos removekey</B
></SPAN
> command to remove one or more server encryption keys from
the <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>KeyFile</B
></SPAN
> file.</P
><P
>If you run the United States edition of AFS and use the Update Server to distribute the contents of the system
control machine's <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>/usr/afs/etc</B
></SPAN
> directory, substitute the system control machine for the
machine name argument. (If you have forgotten which machine is the system control machine, see <A
HREF="c3025.html#HDRWQ96"
>To
locate the system control machine</A
>.)</P
><P
>If you run the international edition of AFS or do not use the Update Server, repeat the <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>bos
removekey</B
></SPAN
> command, substituting each server machine in your cell for the machine name argument in turn.</P
><PRE
CLASS="programlisting"
>&#13; % <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>bos removekey</B
></SPAN
> &#60;<VAR
CLASS="replaceable"
>machine name</VAR
>&#62; &#60;<VAR
CLASS="replaceable"
>key version number</VAR
>&#62;
</PRE
><P
>where <DIV
CLASS="variablelist"
><DL
><DT
><SPAN
CLASS="bold"
><B
CLASS="emphasis"
>removek</B
></SPAN
></DT
><DD
><P
>Is the shortest acceptable abbreviation of <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>removekey</B
></SPAN
>.</P
></DD
><DT
><SPAN
CLASS="bold"
><B
CLASS="emphasis"
>machine name</B
></SPAN
></DT
><DD
><P
>Names the cell's system control machine if you are using the Update Server, or each server machine in turn
if you are not.</P
></DD
><DT
><SPAN
CLASS="bold"
><B
CLASS="emphasis"
>key version number</B
></SPAN
></DT
><DD
><P
>Specifies the key version number of each key to remove.</P
></DD
></DL
></DIV
></P
></LI
></OL
></DIV
></DIV
><DIV
CLASS="sect1"
><H1
CLASS="sect1"
><A
NAME="HDRWQ370"
>Handling Server Encryption Key Emergencies</A
></H1
><P
>In rare circumstances, the AFS server processes can become unable to decrypt the server tickets that clients or peer
server processes are presenting. Activity in your cell can come to a halt, because the server processes believe that the tickets
are forged or expired, and refuse to execute any actions. This can happen on one machine or several; the effect is more serious
when more machines are involved.</P
><P
>One common cause of server encryption key problems is that the client's ticket is encrypted with a key that the server
process does not know. Usually this means that the <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>/usr/afs/etc/KeyFile</B
></SPAN
> on the server machine
does not include the key in the <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>afs</B
></SPAN
> Authentication Database entry, which the Authentication
Server's Ticket Granting Service (TGS) module is using to encrypt server tickets.</P
><P
>Another possibility is that the <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>KeyFile</B
></SPAN
> files on different machines do not contain the
same keys. In this case, communications among server processes themselves become impossible. For instance, AFS's replicated
database mechanism (Ubik) breaks down if the instances of a database server process on the different database server machines
are not using the same key.</P
><P
>The appearance of the following error message when you direct a <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>bos</B
></SPAN
> command to a file
server machine in the local cell is one possible symptom of server encryption key mismatch. (Note, however, that you can also
get this message if you forget to include the <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>-cell</B
></SPAN
> argument when directing the <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>bos</B
></SPAN
> command to a file server machine in a foreign cell.)</P
><PRE
CLASS="programlisting"
>&#13; bos: failed to contact host's bosserver (security object was passed a bad ticket).
</PRE
><P
>The solution to server encryption key emergencies is to put a new AFS server encryption key in both the Authentication
Database and the <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>KeyFile</B
></SPAN
> file on every server machine, so that the TGS and all server processes
again share the same key.</P
><P
>Handling key emergencies requires some unusual actions. The reasons for these actions are explained in the following
sections; the actual procedures appear in the subsequent instructions.</P
><DIV
CLASS="sect2"
><H2
CLASS="sect2"
><A
NAME="HDRWQ371"
>Prevent Mutual Authentication</A
></H2
><P
>It is necessary to prevent the server processes from trying to mutually authenticate with you as you deal with a key
emergency, because they possibly cannot decrypt your token. When you do not mutually authenticate, the server processes assign
you the identity <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>anonymous</B
></SPAN
>. To prevent mutual authentication, use the <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>unlog</B
></SPAN
> command to discard your tokens and include the <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>-noauth</B
></SPAN
> flag on
every command where it is available.</P
></DIV
><DIV
CLASS="sect2"
><H2
CLASS="sect2"
><A
NAME="Header_423"
>Disable Authorization Checking by Hand</A
></H2
><P
>Because the server processes recognize you as the user <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>anonymous</B
></SPAN
> when you do not
mutually authenticate, you must turn off authorization checking. Only with authorization checking disabled do the server
processes allow the <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>anonymous</B
></SPAN
> user to perform privileged actions such as key creation.</P
><P
>In an emergency, disable authorization checking by creating the file <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>/usr/afs/local/NoAuth</B
></SPAN
> by hand. In normal circumstances, use the <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>bos
setauth</B
></SPAN
> command instead.</P
></DIV
><DIV
CLASS="sect2"
><H2
CLASS="sect2"
><A
NAME="Header_424"
>Work Quickly on Each Machine</A
></H2
><P
>Disabling authorization checking is a serious security exposure, because server processes on the affected machine
perform any action for anyone. Disable authorization checking only for as long as necessary, completing all steps in an
uninterrupted session and as quickly as possible.</P
></DIV
><DIV
CLASS="sect2"
><H2
CLASS="sect2"
><A
NAME="Header_425"
>Work at the Console</A
></H2
><P
>Working at the console of each server machine on which you disable authorization checking ensures that no one else logs
onto the console while you are working there. It does not prevent others from connecting to the machine remotely (using the
<SPAN
CLASS="bold"
><B
CLASS="emphasis"
>telnet</B
></SPAN
> program, for example), which is why it is important to work quickly. The only way to
ensure complete security is to disable network traffic, which is not a viable option in many environments. You can improve
security in general by limiting the number of people who can connect remotely to your server machines at any time, as
recommended in <A
HREF="c667.html#HDRWQ74"
>Improving Security in Your Cell</A
>.</P
></DIV
><DIV
CLASS="sect2"
><H2
CLASS="sect2"
><A
NAME="HDRWQ372"
>Change Individual KeyFile Files</A
></H2
><P
>If you use the Update Server to distribute the contents of the <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>/usr/afs/etc</B
></SPAN
> directory,
an emergency is the only time when it is appropriate to change the <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>KeyFile</B
></SPAN
> file on individual
machines instead. Updating each machine's file is necessary because mismatched keys can prevent the system control machine's
<SPAN
CLASS="bold"
><B
CLASS="emphasis"
>upserver</B
></SPAN
> process from mutually authenticating with <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>upclientetc</B
></SPAN
> processes on other server machines, in which case the <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>upserver</B
></SPAN
> process refuses to distribute its <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>KeyFile</B
></SPAN
> file to
them.</P
><P
>Even if it appears that the Update Server is working correctly, the only way to verify that is to change the key on the
system control machine and wait the standard delay period to see if the <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>upclientetc</B
></SPAN
> processes
retrieve the key. During an emergency, it does not usually make sense to wait the standard delay period. It is more efficient
simply to update the file on each server machine separately. Also, even if the Update Server can distribute the file
correctly, other processes can have trouble because of mismatched keys. The following instructions add the new key file on the
system control machine first. If the Update Server is working, then it is distributing the same change as you are making on
each server machine individually.</P
><P
>If your cell does not use the Update Server, or uses the international edition of AFS, you always change keys on server
machines individually. The following instructions are also appropriate for you.</P
></DIV
><DIV
CLASS="sect2"
><H2
CLASS="sect2"
><A
NAME="Header_427"
>Two Component Procedures</A
></H2
><P
>There are two subprocedures used frequently in the following instructions: disabling authorization checking and
reenabling it. For the sake of clarity, the procedures are detailed here; the instructions refer to them as necessary.</P
><DIV
CLASS="sect3"
><H3
CLASS="sect3"
><A
NAME="HDRWQ373"
>Disabling Authorization Checking in an Emergency</A
></H3
><OL
TYPE="1"
><LI
><P
>Become the local superuser <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>root</B
></SPAN
> on the machine, if you are not already, by
issuing the <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>su</B
></SPAN
> command. <PRE
CLASS="programlisting"
>&#13; % <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>su root</B
></SPAN
>
Password: &#60;<VAR
CLASS="replaceable"
>root_password</VAR
>&#62;
</PRE
></P
></LI
><LI
><P
><A
NAME="LIWQ374"
></A
>Create the file <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>/usr/afs/local/NoAuth</B
></SPAN
> to disable
authorization checking. <PRE
CLASS="programlisting"
>&#13; # <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>touch /usr/afs/local/NoAuth</B
></SPAN
>
</PRE
></P
></LI
><LI
><P
>Discard your tokens, in case they were sealed with an incompatible key, which can prevent some commands from
executing. <PRE
CLASS="programlisting"
>&#13; # <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>unlog</B
></SPAN
>
</PRE
></P
></LI
></OL
></DIV
><DIV
CLASS="sect3"
><H3
CLASS="sect3"
><A
NAME="HDRWQ375"
>Reenabling Authorization Checking in an Emergency</A
></H3
><OL
TYPE="1"
><LI
><P
>Become the local superuser <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>root</B
></SPAN
> on the machine, if you are not already, by
issuing the <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>su</B
></SPAN
> command. <PRE
CLASS="programlisting"
>&#13; % <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>su root</B
></SPAN
>
Password: &#60;<VAR
CLASS="replaceable"
>root_password</VAR
>&#62;
</PRE
></P
></LI
><LI
><P
>Remove the <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>/usr/afs/local/NoAuth</B
></SPAN
> file. <PRE
CLASS="programlisting"
>&#13; # <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>rm /usr/afs/local/NoAuth</B
></SPAN
>
</PRE
></P
></LI
><LI
><P
>Authenticate as an administrative identity that belongs to the <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>system:administrators</B
></SPAN
> group and is listed in the <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>/usr/afs/etc/UserList</B
></SPAN
> file. <PRE
CLASS="programlisting"
>&#13; # <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>klog</B
></SPAN
> &#60;<VAR
CLASS="replaceable"
>admin_user</VAR
>&#62;
Password: &#60;<VAR
CLASS="replaceable"
>admin_password</VAR
>&#62;
</PRE
></P
></LI
><LI
><P
>If appropriate, log out from the console (or close the remote connection you are using), after issuing the
<SPAN
CLASS="bold"
><B
CLASS="emphasis"
>unlog</B
></SPAN
> command to destroy your tokens.</P
></LI
></OL
></DIV
></DIV
><DIV
CLASS="sect2"
><H2
CLASS="sect2"
><A
NAME="Header_430"
>To create a new server encryption key in emergencies</A
></H2
><OL
TYPE="1"
><LI
><P
><A
NAME="LIWQ376"
></A
><SPAN
CLASS="bold"
><B
CLASS="emphasis"
>On the system control machine</B
></SPAN
>, disable authorization
checking as instructed in <A
HREF="c20494.html#HDRWQ373"
>Disabling Authorization Checking in an Emergency</A
>.</P
></LI
><LI
><P
><A
NAME="LIWQ377"
></A
>Issue the <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>bos listkeys</B
></SPAN
> command to display the key version
numbers already in use in the <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>KeyFile</B
></SPAN
> file, as a first step in choosing the new key's key
version number. <PRE
CLASS="programlisting"
>&#13; # <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>bos listkeys</B
></SPAN
> &#60;<VAR
CLASS="replaceable"
>machine name</VAR
>&#62; <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>-noauth</B
></SPAN
>
</PRE
></P
><P
>where <DIV
CLASS="variablelist"
><DL
><DT
><SPAN
CLASS="bold"
><B
CLASS="emphasis"
>listk</B
></SPAN
></DT
><DD
><P
>Is the shortest acceptable abbreviation of <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>listkeys</B
></SPAN
>.</P
></DD
><DT
><SPAN
CLASS="bold"
><B
CLASS="emphasis"
>machine name</B
></SPAN
></DT
><DD
><P
>Specifies a file server machine.</P
></DD
><DT
><SPAN
CLASS="bold"
><B
CLASS="emphasis"
>-noauth</B
></SPAN
></DT
><DD
><P
>Bypasses mutual authentication with the BOS Server. Include it in case the key emergency is preventing
successful mutual authentication.</P
></DD
></DL
></DIV
></P
></LI
><LI
><P
><A
NAME="LIWQ378"
></A
>Choose a key version number for the new key, based on what you learned in Step <A
HREF="c20494.html#LIWQ377"
>2</A
> plus the following requirements: <UL
><LI
><P
>It is best to keep your key version numbers in sequence by choosing a key version number one greater than the
largest existing one.</P
></LI
><LI
><P
>Key version numbers must be integers between 0 and 255 to comply with Kerberos standards.</P
></LI
><LI
><P
>Do not reuse a key version number currently listed in the <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>KeyFile</B
></SPAN
>
file.</P
></LI
></UL
></P
></LI
><LI
><P
><A
NAME="LIWQ379"
></A
><SPAN
CLASS="bold"
><B
CLASS="emphasis"
>On the system control machine</B
></SPAN
>, issue the <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>bos addkey</B
></SPAN
> command to create a new AFS server encryption key in the <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>KeyFile</B
></SPAN
> file. <PRE
CLASS="programlisting"
>&#13; # <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>bos addkey</B
></SPAN
> &#60;<VAR
CLASS="replaceable"
>machine name</VAR
>&#62; <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>-kvno</B
></SPAN
> &#60;<VAR
CLASS="replaceable"
>key version number</VAR
>&#62; <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>-noauth</B
></SPAN
>
input key: &#60;<VAR
CLASS="replaceable"
>afs_password</VAR
>&#62;
Retype input key: &#60;<VAR
CLASS="replaceable"
>afs_password</VAR
>&#62;
</PRE
></P
><P
>where <DIV
CLASS="variablelist"
><DL
><DT
><SPAN
CLASS="bold"
><B
CLASS="emphasis"
>addk</B
></SPAN
></DT
><DD
><P
>Is the shortest acceptable abbreviation of <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>addkey</B
></SPAN
>.</P
></DD
><DT
><SPAN
CLASS="bold"
><B
CLASS="emphasis"
>machine name</B
></SPAN
></DT
><DD
><P
>Names the file server machine on which to define the new key in the <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>KeyFile</B
></SPAN
>
file.</P
></DD
><DT
><SPAN
CLASS="bold"
><B
CLASS="emphasis"
>-kvno</B
></SPAN
></DT
><DD
><P
>Specifies the key version number you chose in Step <A
HREF="c20494.html#LIWQ378"
>3</A
>, an integer in the range
0 (zero) through 255. You must specify the same number in Steps <A
HREF="c20494.html#LIWQ382"
>7</A
>, <A
HREF="c20494.html#LIWQ383"
>8</A
>, and <A
HREF="c20494.html#LIWQ386"
>13</A
>.</P
></DD
><DT
><SPAN
CLASS="bold"
><B
CLASS="emphasis"
>-noauth</B
></SPAN
></DT
><DD
><P
>Bypasses mutual authentication with the BOS Server. Include it in case the key emergency is preventing
successful mutual authentication.</P
></DD
><DT
><SPAN
CLASS="bold"
><B
CLASS="emphasis"
>afs_password</B
></SPAN
></DT
><DD
><P
>Is a character string similar to a user password, of any length from one to about 1,000 characters. To
improve security, make the string as long as is practical, and include nonalphabetic characters.</P
><P
>Do not type 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 <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>KeyFile</B
></SPAN
>
file.</P
><P
>Remember the string. You need to use it again in Steps <A
HREF="c20494.html#LIWQ382"
>7</A
>, <A
HREF="c20494.html#LIWQ383"
>8</A
>, and <A
HREF="c20494.html#LIWQ386"
>13</A
>.</P
></DD
></DL
></DIV
></P
></LI
><LI
><P
><A
NAME="LIWQ380"
></A
><SPAN
CLASS="bold"
><B
CLASS="emphasis"
>On every database server machine in your cell</B
></SPAN
> (other than
the system control machine), disable authorization checking as instructed in <A
HREF="c20494.html#HDRWQ373"
>Disabling
Authorization Checking in an Emergency</A
>. Do not repeat the procedure on the system control machine, if it is a
database server machine, because you already disabled authorization checking in Step <A
HREF="c20494.html#LIWQ376"
>1</A
>. (If
you need to learn which machines are database server machines, use the <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>bos listhosts</B
></SPAN
>
command as described in <A
HREF="c3025.html#HDRWQ95"
>To locate database server machines</A
>.)</P
></LI
><LI
><P
><A
NAME="LIWQ381"
></A
>Wait at least 90 seconds after finishing Step <A
HREF="c20494.html#LIWQ380"
>5</A
>, to allow each
of the database server processes (the Authentication, Backup, Protection and Volume Location Servers) to finish electing a
new sync site. Then issue the <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>udebug</B
></SPAN
> command to verify that the election worked properly.
Issue the following commands, substituting each database server machine's name for server machine in turn. Include the
system control machine if it is a database server machine. <PRE
CLASS="programlisting"
>&#13; # <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>udebug</B
></SPAN
> &#60;<VAR
CLASS="replaceable"
>server machine</VAR
>&#62; <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>buserver</B
></SPAN
>
# <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>udebug</B
></SPAN
> &#60;<VAR
CLASS="replaceable"
>server machine</VAR
>&#62; <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>kaserver</B
></SPAN
>
# <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>udebug</B
></SPAN
> &#60;<VAR
CLASS="replaceable"
>server machine</VAR
>&#62; <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>ptserver</B
></SPAN
>
# <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>udebug</B
></SPAN
> &#60;<VAR
CLASS="replaceable"
>server machine</VAR
>&#62; <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>vlserver</B
></SPAN
>
</PRE
></P
><P
>For each process, the output from all of the database server machines must agree on which one is the sync site for
the process. It is not, however, necessary that the same machine serves as the sync site for each of the four processes.
For each process, the output from only one machine must include the following string:</P
><PRE
CLASS="programlisting"
>&#13; I am sync site ...
</PRE
><P
>The output on the other machines instead includes the following line</P
><PRE
CLASS="programlisting"
>&#13; I am not sync site
</PRE
><P
>and a subsequent line that begins with the string <SAMP
CLASS="computeroutput"
>Sync host</SAMP
> and specifies the IP
address of the machine claiming to be the sync site.</P
><P
>If the output does not meet these requirements or seems abnormal in another way, contact AFS Product Support for
assistance.</P
></LI
><LI
><P
><A
NAME="LIWQ382"
></A
><SPAN
CLASS="bold"
><B
CLASS="emphasis"
>On every database server machine in your cell</B
></SPAN
> (other than
the system control machine), issue the <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>bos addkey</B
></SPAN
> command described in Step <A
HREF="c20494.html#LIWQ379"
>4</A
>. Be sure to use the same values for afs_password and kvno as you used in that step.</P
></LI
><LI
><P
><A
NAME="LIWQ383"
></A
>Issue the <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>kas setpassword</B
></SPAN
> command to define the new key in
the Authentication Database's <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>afs</B
></SPAN
> entry. It must match the key you created in Step <A
HREF="c20494.html#LIWQ379"
>4</A
> and Step <A
HREF="c20494.html#LIWQ382"
>7</A
>. <PRE
CLASS="programlisting"
>&#13; # <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>kas setpassword -name afs</B
></SPAN
> <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>-kvno</B
></SPAN
> &#60;<VAR
CLASS="replaceable"
>key version number</VAR
>&#62; <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>-noauth</B
></SPAN
>
new_password: &#60;<VAR
CLASS="replaceable"
>afs_password</VAR
>&#62;
Verifying, please re-enter new_password: &#60;<VAR
CLASS="replaceable"
>afs_password</VAR
>&#62;
</PRE
></P
><P
>where <DIV
CLASS="variablelist"
><DL
><DT
><SPAN
CLASS="bold"
><B
CLASS="emphasis"
>sp</B
></SPAN
></DT
><DD
><P
>Is an acceptable alias for <SPAN
CLASS="bold"
><B
CLASS="emphasis"
>setpassword</B
></SPAN
> (<SPAN
CLASS="bold"
><B
CLASS="emphasis"
>setp</B
></SPAN
> is the shortest acceptable abbreviation).</P
></DD
><DT
><SPAN
CLASS="bold"
><B
CLASS="emphasis"
>-kvno</B
></SPAN
></DT
><DD
><P
>Is the same key version number you specified in Step <A
HREF="c20494.html#LIWQ379"
>4</A
>.</P
></DD
><DT
><SPAN
CLASS="bold"
><B
CLASS="emphasis"
>afs_password</B
></SPAN
></DT
><DD
><P
>Is the same character string you specified as afs_password in Step <A
HREF="c20494.html#LIWQ379"
>4</A
>. It does
not echo visibly.</P
></DD
></DL
></DIV
></P
></LI
><LI
><P
><A
NAME="LIWQ384"
></A
><SPAN
CLASS="bold"
><B
CLASS="emphasis"
>On every database server machine in your cell</B
></SPAN
> (including the
system control machine if it is a database server machine), reenable authorization checking as instructed in <A
HREF="c20494.html#HDRWQ375"
>Reenabling Authorization Checking in an Emergency</A
>. If the system control machine is not a
database server machine, do not perform this procedure until Step <A
HREF="c20494.html#LIWQ385"
>11</A
>.</P
></LI
><LI
><P
>Repeat Step <A
HREF="c20494.html#LIWQ381"
>6</A
> to verify that each database server process has properly elected a sync
site after being restarted in Step <A
HREF="c20494.html#LIWQ384"
>9</A
>.</P
></LI
><LI
><P
><A
NAME="LIWQ385"
></A
><SPAN
CLASS="bold"
><B
CLASS="emphasis"
>On the system control machine</B
></SPAN
> (if it is not a database
server machine), reenable authorization checking as instructed in <A
HREF="c20494.html#HDRWQ375"
>Reenabling Authorization
Checking in an Emergency</A
>. If it is a database server machine, you already performed the procedure in Step <A
HREF="c20494.html#LIWQ384"
>9</A
>.</P
></LI
><LI
><P
><SPAN
CLASS="bold"
><B
CLASS="emphasis"
>On all remaining (simple) file server machines</B
></SPAN
>, disable authorization checking as
instructed in <A
HREF="c20494.html#HDRWQ373"
>Disabling Authorization Checking in an Emergency</A
>.</P
></LI
><LI
><P
><A
NAME="LIWQ386"
></A
><SPAN
CLASS="bold"
><B
CLASS="emphasis"
>On all remaining (simple) file server machines</B
></SPAN
>, issue the
<SPAN
CLASS="bold"
><B
CLASS="emphasis"
>bos addkey</B
></SPAN
> command described in Step <A
HREF="c20494.html#LIWQ379"
>4</A
>. Be sure to use the
same values for afs_password and kvno as you used in that step.</P
></LI
><LI
><P
><SPAN
CLASS="bold"
><B
CLASS="emphasis"
>On all remaining (simple) file server machines</B
></SPAN
>, reenable authorization checking as
instructed in <A
HREF="c20494.html#HDRWQ375"
>Reenabling Authorization Checking in an Emergency</A
>.</P
></LI
></OL
></DIV
></DIV
></DIV
><DIV
CLASS="NAVFOOTER"
><HR
ALIGN="LEFT"
WIDTH="100%"><TABLE
SUMMARY="Footer navigation table"
WIDTH="100%"
BORDER="0"
CELLPADDING="0"
CELLSPACING="0"
><TR
><TD
WIDTH="33%"
ALIGN="left"
VALIGN="top"
><A
HREF="c18360.html"
ACCESSKEY="P"
>Prev</A
></TD
><TD
WIDTH="34%"
ALIGN="center"
VALIGN="top"
><A
HREF="book1.html"
ACCESSKEY="H"
>Home</A
></TD
><TD
WIDTH="33%"
ALIGN="right"
VALIGN="top"
><A
HREF="p21471.html"
ACCESSKEY="N"
>Next</A
></TD
></TR
><TR
><TD
WIDTH="33%"
ALIGN="left"
VALIGN="top"
>Monitoring and Auditing AFS Performance</TD
><TD
WIDTH="34%"
ALIGN="center"
VALIGN="top"
><A
HREF="p3023.html"
ACCESSKEY="U"
>Up</A
></TD
><TD
WIDTH="33%"
ALIGN="right"
VALIGN="top"
>Managing Client Machines</TD
></TR
></TABLE
></DIV
></BODY
></HTML
>
Reference in New Issue Copy Permalink