1 <!DOCTYPE HTML PUBLIC "-//IETF//DTD HTML 4//EN">
3 <TITLE>Administration Guide</TITLE>
4 <!-- Begin Header Records ========================================== -->
5 <!-- /tmp/idwt3570/auagd000.scr converted by idb2h R4.2 (359) ID -->
6 <!-- Workbench Version (AIX) on 2 Oct 2000 at 11:42:14 -->
7 <META HTTP-EQUIV="updated" CONTENT="Mon, 02 Oct 2000 11:42:13">
8 <META HTTP-EQUIV="review" CONTENT="Tue, 02 Oct 2001 11:42:13">
9 <META HTTP-EQUIV="expires" CONTENT="Wed, 02 Oct 2002 11:42:13">
11 <!-- (C) IBM Corporation 2000. All Rights Reserved -->
12 <BODY bgcolor="ffffff">
13 <!-- End Header Records ============================================ -->
14 <A NAME="Top_Of_Page"></A>
15 <H1>Administration Guide</H1>
16 <HR><P ALIGN="center"> <A HREF="../index.htm"><IMG SRC="../books.gif" BORDER="0" ALT="[Return to Library]"></A> <A HREF="auagd002.htm#ToC"><IMG SRC="../toc.gif" BORDER="0" ALT="[Contents]"></A> <A HREF="auagd013.htm"><IMG SRC="../prev.gif" BORDER="0" ALT="[Previous Topic]"></A> <A HREF="#Bot_Of_Page"><IMG SRC="../bot.gif" BORDER="0" ALT="[Bottom of Topic]"></A> <A HREF="auagd015.htm"><IMG SRC="../next.gif" BORDER="0" ALT="[Next Topic]"></A> <A HREF="auagd026.htm#HDRINDEX"><IMG SRC="../index.gif" BORDER="0" ALT="[Index]"></A> <P>
17 <HR><H1><A NAME="HDRWQ355" HREF="auagd002.htm#ToC_409">Managing Server Encryption Keys</A></H1>
18 <P>This chapter explains how to maintain your cell's
19 server encryption keys, which are vital for secure communications in
21 <HR><H2><A NAME="HDRWQ356" HREF="auagd002.htm#ToC_410">Summary of Instructions</A></H2>
22 <P>This chapter explains how to perform the following tasks by
23 using the indicated commands:
27 <TD ALIGN="LEFT" VALIGN="TOP" WIDTH="70%">Add a new server encryption key
28 </TD><TD ALIGN="LEFT" VALIGN="TOP" WIDTH="30%"><B>bos addkey</B> and <B>kas setpassword</B>
30 <TD ALIGN="LEFT" VALIGN="TOP" WIDTH="70%">Inspect key checksums in the Authentication Database
31 </TD><TD ALIGN="LEFT" VALIGN="TOP" WIDTH="30%"><B>kas examine</B>
33 <TD ALIGN="LEFT" VALIGN="TOP" WIDTH="70%">Inspect key checksums in the <B>KeyFile</B>
34 </TD><TD ALIGN="LEFT" VALIGN="TOP" WIDTH="30%"><B>bos listkeys</B>
36 <TD ALIGN="LEFT" VALIGN="TOP" WIDTH="70%">Remove an old server encryption key
37 </TD><TD ALIGN="LEFT" VALIGN="TOP" WIDTH="30%"><B>bos removekey</B>
39 <HR><H2><A NAME="HDRWQ358" HREF="auagd002.htm#ToC_411">About Server Encryption Keys</A></H2>
40 <A NAME="IDX7246"></A>
41 <A NAME="IDX7247"></A>
42 <P>An <I>encryption key</I> is a string of octal numbers used to encrypt
43 and decrypt packets of information. In AFS, a <I>server encryption
44 key</I> is the key used to protect information being transferred between AFS
45 server processes and between them and their clients. A server
46 encryption key is essentially a password for a server process and like a user
47 password is stored in the Authentication Database.
48 <P>Maintaining your cell's server encryption keys properly is the most
49 basic way to protect the information in your AFS filespace from access by
51 <P><H3><A NAME="Header_412" HREF="auagd002.htm#ToC_412">Keys and Mutual Authentication: A Review</A></H3>
52 <A NAME="IDX7248"></A>
53 <A NAME="IDX7249"></A>
54 <A NAME="IDX7250"></A>
55 <A NAME="IDX7251"></A>
56 <A NAME="IDX7252"></A>
57 <A NAME="IDX7253"></A>
58 <P>Server encryption keys play a central role in the mutual authentication
59 between client and server processes in AFS. For a more detailed
60 description of mutual authentication, see <A HREF="auagd007.htm#HDRWQ75">A More Detailed Look at Mutual Authentication</A>.
61 <P>When a client wants to contact an AFS server, it first contacts the
62 <I>Ticket Granting Service</I> (TGS) module of the Authentication
63 Server. After verifying the client's identity (based indirectly on
64 the password of the human user whom the client represents), the TGS gives the
65 client a <I>server ticket</I>. This ticket is encrypted with the
66 server's encryption key. (The TGS also invents a second encryption
67 key, called the <I>session key</I>, to be used only for a single episode
68 of communication between server and client. The server ticket and
69 session key, together with other pieces of information, are collectively
70 referred to as a <I>token</I>.)
71 <P>The client cannot read the server ticket or token because it does not know
72 the server encryption key. However, the client sends it to the AFS
73 server along with service requests, because the ticket proves to the AFS
74 server processes that it has already authenticated with the TGS. AFS
75 servers trust the TGS to grant tickets only to valid clients. The fact
76 that the client possesses a ticket encrypted with the server's encryption
77 key proves to the server that the client is valid. On the other hand,
78 the client assumes that only a genuine AFS server knows the server encryption
79 key needed to decrypt the ticket. The server's ability to decrypt
80 the ticket and understand its contents proves to the client that the server is
82 <P><H3><A NAME="Header_413" HREF="auagd002.htm#ToC_413">Maintaining AFS Server Encryption Keys</A></H3>
83 <P>As you maintain your cell's server encryption keys, keep the
86 <P><LI>Change the key frequently to enhance your cell's security.
87 Changing the key at least once a month is strongly recommended.
88 <A NAME="IDX7254"></A>
89 <P><LI>The AFS server encryption key currently in use is stored in two
90 places. When you add a new key, you must make changes in both places
91 and make them in the correct order, as instructed in <A HREF="#HDRWQ362">Adding Server Encryption Keys</A>. Failure to follow the instructions can seriously
92 impair cell functioning, as clients and servers become unable to
93 communicate. The two storage sites for the current server encryption
94 key are the following:
96 <P><LI>The file <B>/usr/afs/etc/KeyFile</B> on the local disk of every file
97 server machine. The file can list more than one key, each with an
98 associated numerical identifier, the <I>key version number</I> or
99 <I>kvno</I>. A client token records the key version number of the
100 key used to seal it, and the server process retrieves the appropriate key from
101 this file when the client presents the token.
102 <A NAME="IDX7255"></A>
103 <A NAME="IDX7256"></A>
104 <A NAME="IDX7257"></A>
105 <A NAME="IDX7258"></A>
106 <A NAME="IDX7259"></A>
107 <P><LI>The <B>afs</B> entry in the Authentication Database. The
108 current server encryption key is in the entry's password field, just like
109 an individual user's scrambled password. The Authentication
110 Server's Ticket Granting Service (TGS) uses this key to encrypt the
111 tokens it gives to clients. There is only a single key in the entry,
112 because the TGS never needs to read existing tokens, but only to generate new
113 ones by using the current key.
114 <A NAME="IDX7260"></A>
115 <A NAME="IDX7261"></A>
116 <A NAME="IDX7262"></A>
118 <P>For instructions on creating the initial <B>afs</B> entry and
119 <B>KeyFile</B> files as you install your cell's first server machine,
120 see the <I>IBM AFS Quick Beginnings</I>.
121 <P><LI>At any specific time, the tokens that the Authentication Server's
122 Ticket Granting Service gives to clients are sealed with only one of the
123 server encryption keys, namely the one stored in the <B>afs</B> entry in
124 the Authentication Database.
125 <P><LI>When you add a new server encryption key, you cannot immediately remove
126 the former key from the <B>/usr/afs/etc/KeyFile</B> file on the local disk
127 of every AFS server machine. Any time that you add a new key, it is
128 likely that some clients still have valid, unexpired tokens sealed with the
129 previous key. The more frequently you change the server encryption key,
130 the more such tickets there are likely to be. To be able to grant
131 service appropriately to clients with such tokens, an AFS server process must
132 still be able to access the server encryption key used to seal it.
133 <P>You can safely delete an old server encryption key only when it is certain
134 that no clients have tokens sealed with that key. In general, wait a
135 period of time at least as long as the maximum token lifetime in your
136 cell. By default, the maximum token lifetime for users is 25 hours
137 (except for users whose Authentication Database entries were created by using
138 the 3.0 version of AFS, for whom the default is 100 hours). You
139 can use the <B>-lifetime</B> argument to the <B>kas setfields</B>
140 command to change this default.
141 <P>Instructions for removing obsolete keys appear in <A HREF="#HDRWQ368">Removing Server Encryption Keys</A>.
142 <P><LI>You create a new AFS server encryption key in much the same way regular
143 users change their passwords, by providing a character string that is
144 converted into an encryption key automatically. See <A HREF="#HDRWQ362">Adding Server Encryption Keys</A>.
145 <A NAME="IDX7263"></A>
146 <P><LI>In addition to using server encryption keys when communicating with
147 clients, the server processes use them to protect communications with other
148 server processes. Therefore, all server machines in your cell must have
149 the same version of the <B>KeyFile</B> file. The easiest way to
150 maintain consistency (if you run the United States edition of AFS) is to use
151 the Update Server to distribute the contents of the system control
152 machine's <B>/usr/afs/etc</B> directory to all of the other server
153 machines. There are two implications:
155 <P><LI>You must run the <B>upserver</B> process on the system control machine
156 and an <B>upclientetc</B> process on all other server machines that
157 references the system control machine. The <I>IBM AFS Quick
158 Beginnings</I> explains how to install both processes. For
159 instructions on verifying that the Update Server processes are running, see <A HREF="auagd009.htm#HDRWQ158">Displaying Process Status and Information from the BosConfig File</A>.
160 <A NAME="IDX7264"></A>
161 <P><LI>Change the <B>KeyFile</B> file only on the system control machine
162 (except in the types of emergencies discussed in <A HREF="#HDRWQ370">Handling Server Encryption Key Emergencies</A>). Any changes you make on other server machines are
163 overwritten the next time the <B>upclientetc</B> process retrieves the
164 contents of the system control machine's <B>/usr/afs/etc</B>
165 directory. By default, this happens every five minutes.
166 <A NAME="IDX7265"></A>
168 <P>If you run the international edition of AFS, do not use the Update Server
169 to distribute the contents of the <B>/usr/afs/etc</B> directory,
170 particularly the <B>KeyFile</B> file. The data in the file is too
171 sensitive for transfer in unencrypted form, and because of United States
172 government exports regulations the international edition of AFS does not
173 include the necessary encryption routines in a form that the Update Server can
174 use. You must instead modify the file on each server machine
175 individually, taking care to enter the same key on every server
177 <P><LI>Never edit the <B>KeyFile</B> directly with a text editor.
178 Instead, always use the appropriate <B>bos</B> commands as instructed in <A HREF="#HDRWQ362">Adding Server Encryption Keys</A> and <A HREF="#HDRWQ368">Removing Server Encryption Keys</A>.
180 <HR><H2><A NAME="HDRWQ359" HREF="auagd002.htm#ToC_414">Displaying Server Encryption Keys</A></H2>
181 <P>To display the server encryption keys in the
182 <B>/usr/afs/etc/KeyFile</B> file on any file server machine, use the
183 <B>bos listkeys</B> command. Use the <B>kas examine</B> command
184 to display the key in the Authentication Database's <B>afs</B>
186 <P>By default the commands do not display the actual string of octal digits
187 that constitute a key, but rather a <I>checksum</I>, a decimal number
188 derived by encrypting a constant with the key. This prevents
189 unauthorized users from easily accessing the actual key, which they can then
190 use to falsify or eavesdrop on protected communications.
191 <A NAME="IDX7266"></A>
192 <A NAME="IDX7267"></A>
193 The <B>bos listkeys</B> and <B>kas examine</B> commands generate the
194 same checksum for a given key, so displaying checksums rather than actual keys
195 is generally sufficient. If you suspect that the keys differ in a way
196 that the checksums are not revealing, then you are probably experiencing
197 authentication problems throughout your cell. The easiest solution is
198 to create a new server encryption key following the instructions in <A HREF="#HDRWQ362">Adding Server Encryption Keys</A> or <A HREF="#HDRWQ370">Handling Server Encryption Key Emergencies</A>. Another common reason to issue the
199 <B>bos listkeys</B> command is to display the key version numbers
200 currently in use, in preparation for choosing the next one; here, the
201 checksum is sufficient because the key itself is irrelevant.
202 <P>If it is important to display the actual octal digits, include the
203 <B>-showkey</B> argument to both the <B>bos listkeys</B> and <B>kas
204 examine</B> commands.
205 <A NAME="IDX7268"></A>
206 <A NAME="IDX7269"></A>
207 <A NAME="IDX7270"></A>
208 <A NAME="IDX7271"></A>
209 <A NAME="IDX7272"></A>
210 <A NAME="IDX7273"></A>
211 <P><H3><A NAME="HDRWQ360" HREF="auagd002.htm#ToC_415">To display the KeyFile file</A></H3>
213 <P><LI>Verify that you are authenticated as a user listed in the
214 <B>/usr/afs/etc/UserList</B> file. If necessary, issue the <B>bos
215 listusers</B> command, which is fully described in <A HREF="auagd021.htm#HDRWQ593">To display the users in the UserList file</A>.
216 <PRE> % <B>bos listusers</B> <<VAR>machine name</VAR>>
218 <P><LI>Issue the <B>bos listkeys</B> command to display the contents of one
219 machine's <B>/usr/afs/etc/KeyFile</B> file.
220 <PRE> % <B>bos listkeys</B> <<VAR>machine name</VAR>> [<B>-showkey</B>]
225 </B><DD>Is the shortest acceptable abbreviation of <B>listkeys</B>.
226 <P><DT><B><VAR>machine name</VAR>
227 </B><DD>Names a file server machine. In the normal case, it is acceptable
228 to name any machine, because correct cell functioning requires that the
229 <B>KeyFile</B> file be the same on all of them.
230 <P><DT><B><B>-showkey</B>
231 </B><DD>Displays the octal digits that constitute each key.
234 <P>In the following example, the output displays a checksum for each server
235 encryption key rather than the actual octal digits. The penultimate
236 line indicates when an administrator last changed the file, and the final line
237 confirms that the output is complete.
238 <PRE> % <B>bos listkeys fs1.abc.com</B>
239 key 0 has cksum 972037177
240 key 1 has cksum 2825165022
241 Keys last changed on Wed Jan 13 11:20:29 1999.
244 <A NAME="IDX7274"></A>
245 <A NAME="IDX7275"></A>
246 <A NAME="IDX7276"></A>
247 <A NAME="IDX7277"></A>
248 <A NAME="IDX7278"></A>
249 <A NAME="IDX7279"></A>
250 <P><H3><A NAME="HDRWQ361" HREF="auagd002.htm#ToC_416">To display the afs key from the Authentication Database</A></H3>
252 <P><LI>Issue the <B>kas examine</B> command to display the <B>afs</B>
253 entry in the Authentication Database.
254 <P>The Authentication Server performs its own authentication rather than
255 accepting your existing AFS token. By default, it authenticates your
256 local (UNIX) identity, which possibly does not correspond to an AFS-privileged
257 administrator. Include the <B>-admin</B> argument to name an
258 identity that has the <TT>ADMIN</TT> flag on its Authentication Database
259 entry. To verify that an entry has the flag, issue the <B>kas
260 examine</B> command as described in <A HREF="auagd021.htm#HDRWQ590">To check if the ADMIN flag is set</A>.
261 <PRE> % <B>kas examine afs</B> [<B>-showkey</B>] \
262 <B>-admin</B> <<VAR>admin principal to use for authentication</VAR>>
263 Administrator's (<VAR>admin_user</VAR>) password: <VAR>admin_password</VAR>
268 </B><DD>Is the shortest acceptable abbreviation of <B>examine</B>.
270 </B><DD>Designates the <B>afs</B> entry.
271 <P><DT><B><B>-showkey</B>
272 </B><DD>Displays the octal digits that constitute the key.
274 </B><DD>Names an administrative account with the <TT>ADMIN</TT> flag on its
275 Authentication Database entry, such as <B>admin</B>. The password
276 prompt echoes it as <VAR>admin_user</VAR>. Enter the appropriate password
277 as <VAR>admin_password</VAR>.
280 <P>In the following example, the <B>admin</B> user displays the
281 <B>afs</B> entry without using the <B>-showkey</B> flag. The
282 second line shows the key version number in parentheses and the key's
283 checksum. The line that begins with the string <TT>last mod</TT>
284 reports the date on which the indicated administrator changed the key.
285 There is no necessary relationship between this date and the date reported by
286 the <B>bos listkeys</B> command, because the latter date changes for any
287 type of change to the <B>KeyFile</B> file, not just a key addition.
288 For a description of the other lines in the output from the <B>kas
289 examine</B> command, see its reference page in the <I>IBM AFS
290 Administration Reference</I>.
291 <PRE> % <B>kas examine afs -admin admin</B>
292 Administrator's (admin) password: <VAR>admin_password</VAR>
294 key (1) cksum is 2825165022, last cpw: no date
295 password will never expire.
296 An unlimited number of unsuccessful authentications is permitted.
297 entry expires on never. Max ticket lifetime 100.00 hours.
298 last mod on Wed Jan 13 11:21:36 1999 by admin
299 permit password reuse
301 <HR><H2><A NAME="HDRWQ362" HREF="auagd002.htm#ToC_417">Adding Server Encryption Keys</A></H2>
302 <A NAME="IDX7280"></A>
303 <A NAME="IDX7281"></A>
304 <A NAME="IDX7282"></A>
305 <A NAME="IDX7283"></A>
306 <A NAME="IDX7284"></A>
307 <A NAME="IDX7285"></A>
308 <A NAME="IDX7286"></A>
309 <A NAME="IDX7287"></A>
310 <A NAME="IDX7288"></A>
311 <P>As noted, AFS records server encryption keys in two separate places:
313 <P><LI>In the file <B>/usr/afs/etc/KeyFile</B> on the local disk of each
314 server machine, for use by the AFS server processes running on the machine
315 <P><LI>In the <B>afs</B> entry in the Authentication Database, for use by the
316 Ticket Granting Service (TGS) when creating tokens
318 <P>To ensure that server processes and the TGS share the same AFS server
319 encryption key, execute all the steps in this section without
321 <P>The following instructions include a step in which you restart the database
322 server processes (the Authentication, Backup, Protection, and Volume Location
323 Server processes) on all database server machines. As a database server
324 process starts, it reads in the server encryption key that has the highest key
325 version number in the <B>KeyFile</B> file and uses it to protect the
326 messages that it sends for synchronizing the database and maintaining
327 quorum. It uses the same key throughout its lifetime, which can be for
328 an extended period, even if you remove the key from the <B>KeyFile</B>
329 file. However, if one of the peer database server processes restarts
330 and the others do not, quorum and database synchronization break down because
331 the processes are no longer using the same key: the restarted process is
332 using the key that currently has the highest key version number, and the other
333 processes are still using the key they read in when they originally
334 started. To avoid this problem, it is safest to restart all of the
335 database server processes when adding a new key.
336 <P>After adding a new key, you can remove obsolete keys from the
337 <B>KeyFile</B> file to prevent it from becoming cluttered. However,
338 you must take care not to remove keys that client or server processes are
339 still using. For discussion and instructions, see <A HREF="#HDRWQ368">Removing Server Encryption Keys</A>.
340 <P><H3><A NAME="HDRWQ363" HREF="auagd002.htm#ToC_418">To add a new server encryption key</A></H3>
342 <P><LI>Verify that you are authenticated as a user listed in the
343 <B>/usr/afs/etc/UserList</B> file. If necessary, issue the <B>bos
344 listusers</B> command, which is fully described in <A HREF="auagd021.htm#HDRWQ593">To display the users in the UserList file</A>.
345 <PRE> % <B>bos listusers</B> <<VAR>machine name</VAR>>
347 <P><LI><A NAME="LIWQ364"></A>Issue the <B>bos listkeys</B> command to display the key
348 version numbers that are already in use, as a first step in choosing the key
349 version number for the new key.
350 <PRE> % <B>bos listkeys</B> <<VAR>machine name</VAR>>
355 </B><DD>Is the shortest acceptable abbreviation of <B>listkeys</B>.
356 <P><DT><B><VAR>machine name</VAR>
357 </B><DD>Names any file server machine.
359 <P><LI><A NAME="LIWQ365"></A>Choose a key version number for the new key, based on the
360 output from Step <A HREF="#LIWQ364">2</A> and the following requirements:
362 <P><LI>A key version number must be an integer between 0 (zero) and 255 to comply
363 with Kerberos standards. It is simplest if you keep your key version
364 numbers in sequence by choosing a key version number one greater than the
365 largest existing one.
366 <P><LI>Do not reuse a key version number currently found in the
367 <B>KeyFile</B> file, particularly if it is also the one in the
368 Authentication Database <B>afs</B> entry. Client processes possibly
369 still have tickets sealed with the key that originally had that key version
370 number, but the server processes start using the new key marked with that key
371 version number. Because the keys do not match, the server processes
372 refuse requests from clients who hold legitimate tokens.
374 <A NAME="IDX7289"></A>
375 <A NAME="IDX7290"></A>
376 <P><LI><A NAME="LIWQ366"></A>Issue the <B>bos addkey</B> command to create a new AFS
377 server encryption key in the <B>KeyFile</B> file.
378 <P>If you run the United States edition of AFS and use the Update Server to
379 distribute the contents of the system control machine's
380 <B>/usr/afs/etc</B> directory, substitute the system control machine for
381 the <VAR>machine name</VAR> argument. (If you have forgotten which
382 machine is the system control machine, see <A HREF="auagd008.htm#HDRWQ96">To locate the system control machine</A>.)
383 <P>If you run the international edition of AFS or do not use the Update
384 Server, repeat the <B>bos addkey</B> command, substituting each server
385 machine in your cell for the <VAR>machine name</VAR> argument in turn.
386 <P>To avoid visible echoing of the string that corresponds to the new key,
387 omit the <B>-key</B> argument from the command line; instead enter
388 the string at the prompts that appear when you omit it, as shown in the
389 following syntax specification.
390 <PRE> % <B>bos addkey -server</B> <<VAR>machine name</VAR>> <B>-kvno</B> <<VAR>key version number</VAR>>
391 input key: <VAR>afs_password</VAR>
392 Retype input key: <VAR>afs_password</VAR>
396 <P><DT><B><B>addk</B>
397 </B><DD>Is the shortest acceptable abbreviation of <B>addkey</B>.
399 </B><DD>Names the cell's system control machine if you are using the Update
400 Server, or each server machine in turn if you are not.
402 </B><DD>Specifies the new key's key version number as an integer from the
403 range 0 (zero) through 255.
404 <P>Remember the number. You need to use it again in Step <A HREF="#LIWQ367">6</A>. If you are using the international edition of AFS,
405 be sure to type the same number each time you issue this command.
406 <P><DT><B><VAR>afs_password</VAR>
407 </B><DD>Is a character string similar to a user password, of any length from one
408 to about 1,000 characters. To improve security, include nonalphabetic
409 characters and make the string as long as is practical (you need to type it
410 only in this step and in Step <A HREF="#LIWQ367">6</A>). If you are using the international edition of AFS,
411 be sure to type the same string each time you issue this command.
412 <P>Do not enter an octal string directly. The BOS Server scrambles the
413 character string into an octal string appropriate for use as an encryption key
414 before recording it in the <B>KeyFile</B> file.
416 <P><LI>If you are using the Update Server, wait for a few minutes while the
417 Update Server distributes the new <B>KeyFile</B> file to all server
418 machines. The maximum necessary waiting period is the largest value
419 provided for the <B>-t</B> argument to the <B>upclientetc</B>
420 process's initialization command used on any of the server machines;
421 the default time is five minutes.
422 <P>To be certain that all machines have the same <B>KeyFile</B> file,
423 issue the <B>bos listkeys</B> command for every file server machine and
424 verify that the checksum for the new key is the same on all machines.
425 <PRE> % <B>bos listkeys</B> <<VAR>machine name</VAR>>
427 <P>If you are not using the Update Server, try to complete Step <A HREF="#LIWQ366">4</A> within five minutes.
428 <A NAME="IDX7291"></A>
429 <A NAME="IDX7292"></A>
430 <P><LI><A NAME="LIWQ367"></A>Issue the <B>kas setpassword</B> command to enter the same
431 key in the <B>afs</B> entry in the Authentication Database.
432 <P>The Authentication Server performs its own authentication rather than
433 accepting your existing AFS token. By default, it authenticates your
434 local (UNIX) identity, which possibly does not correspond to an AFS-privileged
435 administrator. Include the <B>-admin</B> argument to name an
436 identity that has the <TT>ADMIN</TT> flag on its Authentication Database
437 entry. To verify that an entry has the flag, issue the <B>kas
438 examine</B> command as described in <A HREF="auagd021.htm#HDRWQ590">To check if the ADMIN flag is set</A>.
439 <PRE> % <B>kas setpassword -name afs -kvno</B> <<VAR>kvno</VAR>> \
440 <B>-admin</B> <<VAR>admin principal to use for authentication</VAR>>
441 Administrator's (<VAR>admin_user</VAR>) password: <VAR>admin_password</VAR>
442 new_password: <VAR>afs_password</VAR>
443 Verifying, please re-enter new_password: <VAR>afs_password</VAR>
448 </B><DD>Is an acceptable alias for <B>setpassword</B> (<B>setp</B> is the
449 shortest acceptable abbreviation).
451 </B><DD>Creates the new key in the <B>afs</B> entry.
453 </B><DD>Specifies the same key version number as in Step <A HREF="#LIWQ366">4</A>.
455 </B><DD>Names an administrative account with the <TT>ADMIN</TT> flag on its
456 Authentication Database entry, such as <B>admin</B>. The password
457 prompt echoes it as <VAR>admin_user</VAR>. Enter the appropriate password
458 as <VAR>admin_password</VAR>.
459 <P><DT><B><VAR>afs_password</VAR>
460 </B><DD>Is the same character string you entered in Step <A HREF="#LIWQ366">4</A>.
462 <P><LI><B>(Optional.)</B> If you want to verify that the keys you just
463 created in the <B>KeyFile</B> file and the Authentication Database
464 <B>afs</B> entry are identical and have the same key version number,
465 follow the instructions in <A HREF="#HDRWQ359">Displaying Server Encryption Keys</A>.
466 <P><LI>Issue the <B>bos restart</B> command to restart the database server
467 processes on all database server machines. This forces them to start
468 using the key in the <B>KeyFile</B> file that currently has the highest
470 <P>Repeat this command in quick succession for each database server machine,
471 starting with the machine that has the lowest IP address.
472 <PRE> % <B>bos restart</B> <<VAR>machine name</VAR>> <B>buserver kaserver ptserver vlserver</B>
477 </B><DD>Is the shortest acceptable abbreviation of <B>restart</B>.
478 <P><DT><B><VAR>machine name</VAR>
479 </B><DD>Names each database server machine in turn.
480 <P><DT><B>buserver kaserver ptserver vlserver
481 </B><DD>Designates the Backup Server, Authentication Server, Protection Server,
482 and Volume Location (VL) Server, respectively.
485 <HR><H2><A NAME="HDRWQ368" HREF="auagd002.htm#ToC_419">Removing Server Encryption Keys</A></H2>
486 <A NAME="IDX7293"></A>
487 <A NAME="IDX7294"></A>
488 <A NAME="IDX7295"></A>
489 <P>You can periodically remove old keys from the
490 <B>/usr/afs/etc/KeyFile</B> file to keep it to a reasonable size.
491 To avoid disturbing cell functioning, do not remove an old key until all
492 tokens sealed with the key and held by users or client processes have
493 expired. After adding a new key, wait to remove old keys at least as
494 long as the longest token lifetime you use in your cell. For
495 Authentication Database user entries created under AFS version 3.1 or
496 higher, the default token lifetime is 25 hours; for entries created under
497 AFS version 3.0, it is 100 hours.
498 <P>There is no command for removing the key from the <B>afs</B> entry in
499 the Authentication Database, because the key field in that entry must never be
500 empty. Use the <B>kas setpassword</B> command to replace the
501 <B>afs</B> key, but only as part of the complete procedure detailed in <A HREF="#HDRWQ363">To add a new server encryption key</A>.
502 <P>Never remove from the <B>KeyFile</B> file the key that is currently in
503 the <B>afs</B> entry in the Authentication Database. AFS server
504 processes become unable to decrypt the tickets that clients present to
506 <P><H3><A NAME="HDRWQ369" HREF="auagd002.htm#ToC_420">To remove a key from the KeyFile file</A></H3>
508 <P><LI>Verify that you are authenticated as a user listed in the
509 <B>/usr/afs/etc/UserList</B> file. If necessary, issue the <B>bos
510 listusers</B> command, which is fully described in <A HREF="auagd021.htm#HDRWQ593">To display the users in the UserList file</A>.
511 <PRE> % <B>bos listusers</B> <<VAR>machine name</VAR>>
513 <P><LI>Issue the <B>bos listkeys</B> command to display the key version
514 number of each key you want to remove. The output also reveals whether
515 it has been at least 25 hours since a new key was placed in the
516 <B>KeyFile</B> file. For complete instructions for the <B>bos
517 listkeys</B> command, see <A HREF="#HDRWQ360">To display the KeyFile file</A>.
518 <PRE> % <B>bos listkeys</B> <<VAR>machine name</VAR>>
520 <P><LI>Issue the <B>kas examine</B> command to verify that the key currently
521 in the Authentication Database's <B>afs</B> entry does not have the
522 same key version number as any of the keys you are removing from the
523 <B>KeyFile</B> file. For detailed instructions for the <B>kas
524 examine</B> command, see <A HREF="#HDRWQ361">To display the afs key from the Authentication Database</A>.
525 <PRE> % <B>kas examine afs -admin</B> <<VAR>admin principal to use for authentication</VAR>>
526 Administrator's (<VAR>admin_user</VAR>) password: <VAR>admin_password</VAR>
528 <A NAME="IDX7296"></A>
529 <A NAME="IDX7297"></A>
530 <P><LI>Issue the <B>bos removekey</B> command to remove one or more server
531 encryption keys from the <B>KeyFile</B> file.
532 <P>If you run the United States edition of AFS and use the Update Server to
533 distribute the contents of the system control machine's
534 <B>/usr/afs/etc</B> directory, substitute the system control machine for
535 the <VAR>machine name</VAR> argument. (If you have forgotten which
536 machine is the system control machine, see <A HREF="auagd008.htm#HDRWQ96">To locate the system control machine</A>.)
537 <P>If you run the international edition of AFS or do not use the Update
538 Server, repeat the <B>bos removekey</B> command, substituting each server
539 machine in your cell for the <VAR>machine name</VAR> argument in turn.
540 <PRE> % <B>bos removekey</B> <<VAR>machine name</VAR>> <<VAR>key version number</VAR>>
544 <P><DT><B><B>removek</B>
545 </B><DD>Is the shortest acceptable abbreviation of <B>removekey</B>.
546 <P><DT><B><VAR>machine name</VAR>
547 </B><DD>Names the cell's system control machine if you are using the Update
548 Server, or each server machine in turn if you are not.
549 <P><DT><B><VAR>key version number</VAR>
550 </B><DD>Specifies the key version number of each key to remove.
553 <HR><H2><A NAME="HDRWQ370" HREF="auagd002.htm#ToC_421">Handling Server Encryption Key Emergencies</A></H2>
554 <A NAME="IDX7298"></A>
555 <A NAME="IDX7299"></A>
556 <A NAME="IDX7300"></A>
557 <A NAME="IDX7301"></A>
558 <A NAME="IDX7302"></A>
559 <P>In rare circumstances, the AFS server processes can become unable to
560 decrypt the server tickets that clients or peer server processes are
561 presenting. Activity in your cell can come to a halt, because the
562 server processes believe that the tickets are forged or expired, and refuse to
563 execute any actions. This can happen on one machine or several;
564 the effect is more serious when more machines are involved.
565 <P>One common cause of server encryption key problems is that the
566 client's ticket is encrypted with a key that the server process does not
567 know. Usually this means that the <B>/usr/afs/etc/KeyFile</B> on
568 the server machine does not include the key in the <B>afs</B>
569 Authentication Database entry, which the Authentication Server's Ticket
570 Granting Service (TGS) module is using to encrypt server tickets.
571 <P>Another possibility is that the <B>KeyFile</B> files on different
572 machines do not contain the same keys. In this case, communications
573 among server processes themselves become impossible. For instance,
574 AFS's replicated database mechanism (Ubik) breaks down if the instances
575 of a database server process on the different database server machines are not
577 <P>The appearance of the following error message when you direct a
578 <B>bos</B> command to a file server machine in the local cell is one
579 possible symptom of server encryption key mismatch. (Note, however,
580 that you can also get this message if you forget to include the
581 <B>-cell</B> argument when directing the <B>bos</B> command to a file
582 server machine in a foreign cell.)
583 <PRE> bos: failed to contact host's bosserver (security object was passed a bad ticket).
585 <P>The solution to server encryption key emergencies is to put a new AFS
586 server encryption key in both the Authentication Database and the
587 <B>KeyFile</B> file on every server machine, so that the TGS and all
588 server processes again share the same key.
589 <P>Handling key emergencies requires some unusual actions. The reasons
590 for these actions are explained in the following sections; the actual
591 procedures appear in the subsequent instructions.
592 <P><H3><A NAME="HDRWQ371" HREF="auagd002.htm#ToC_422">Prevent Mutual Authentication</A></H3>
593 <P>It is necessary to prevent the server processes from trying
594 to mutually authenticate with you as you deal with a key emergency, because
595 they possibly cannot decrypt your token. When you do not mutually
596 authenticate, the server processes assign you the identity
597 <B>anonymous</B>. To prevent mutual authentication, use the
598 <B>unlog</B> command to discard your tokens and include the
599 <B>-noauth</B> flag on every command where it is available.
600 <P><H3><A NAME="Header_423" HREF="auagd002.htm#ToC_423">Disable Authorization Checking by Hand</A></H3>
601 <P>Because the server processes recognize you as the user
602 <B>anonymous</B> when you do not mutually authenticate, you must turn off
603 authorization checking. Only with authorization checking disabled do
604 the server processes allow the <B>anonymous</B> user to perform privileged
605 actions such as key creation.
606 <P>In an emergency, disable authorization checking by creating the file
607 <B>/usr/afs/local/NoAuth</B> by hand. In normal circumstances, use
608 the <B>bos setauth</B> command instead.
609 <P><H3><A NAME="Header_424" HREF="auagd002.htm#ToC_424">Work Quickly on Each Machine</A></H3>
610 <P>Disabling authorization checking is a serious security exposure,
611 because server processes on the affected machine perform any action for
612 anyone. Disable authorization checking only for as long as necessary,
613 completing all steps in an uninterrupted session and as quickly as
615 <P><H3><A NAME="Header_425" HREF="auagd002.htm#ToC_425">Work at the Console</A></H3>
616 <P>Working at the console of each server machine on which you disable
617 authorization checking ensures that no one else logs onto the console while
618 you are working there. It does not prevent others from connecting to
619 the machine remotely (using the <B>telnet</B> program, for example), which
620 is why it is important to work quickly. The only way to ensure complete
621 security is to disable network traffic, which is not a viable option in many
622 environments. You can improve security in general by limiting the
623 number of people who can connect remotely to your server machines at any time,
624 as recommended in <A HREF="auagd007.htm#HDRWQ74">Improving Security in Your Cell</A>.
625 <P><H3><A NAME="HDRWQ372" HREF="auagd002.htm#ToC_426">Change Individual KeyFile Files</A></H3>
626 <P>If you use the Update Server to distribute the contents of
627 the <B>/usr/afs/etc</B> directory, an emergency is the only time when it
628 is appropriate to change the <B>KeyFile</B> file on individual machines
629 instead. Updating each machine's file is necessary because
630 mismatched keys can prevent the system control machine's
631 <B>upserver</B> process from mutually authenticating with
632 <B>upclientetc</B> processes on other server machines, in which case the
633 <B>upserver</B> process refuses to distribute its <B>KeyFile</B> file
635 <P>Even if it appears that the Update Server is working correctly, the only
636 way to verify that is to change the key on the system control machine and wait
637 the standard delay period to see if the <B>upclientetc</B> processes
638 retrieve the key. During an emergency, it does not usually make sense
639 to wait the standard delay period. It is more efficient simply to
640 update the file on each server machine separately. Also, even if the
641 Update Server can distribute the file correctly, other processes can have
642 trouble because of mismatched keys. The following instructions add the
643 new key file on the system control machine first. If the Update Server
644 is working, then it is distributing the same change as you are making on each
645 server machine individually.
646 <P>If your cell does not use the Update Server, or uses the international
647 edition of AFS, you always change keys on server machines individually.
648 The following instructions are also appropriate for you.
649 <P><H3><A NAME="Header_427" HREF="auagd002.htm#ToC_427">Two Component Procedures</A></H3>
650 <P>There are two subprocedures used frequently in the following
651 instructions: disabling authorization checking and reenabling it.
652 For the sake of clarity, the procedures are detailed here; the
653 instructions refer to them as necessary.
654 <P><H4><A NAME="HDRWQ373">Disabling Authorization Checking in an Emergency</A></H4>
656 <P><LI>Become the local superuser <B>root</B> on the machine, if you are not
657 already, by issuing the <B>su</B> command.
658 <PRE> % <B>su root</B>
659 Password: <VAR>root_password</VAR>
661 <A NAME="IDX7303"></A>
662 <P><LI><A NAME="LIWQ374"></A>Create the file <B>/usr/afs/local/NoAuth</B> to disable
663 authorization checking.
664 <PRE> # <B>touch /usr/afs/local/NoAuth</B>
666 <A NAME="IDX7304"></A>
667 <P><LI>Discard your tokens, in case they were sealed with an incompatible key,
668 which can prevent some commands from executing.
672 <P><H4><A NAME="HDRWQ375">Reenabling Authorization Checking in an Emergency</A></H4>
674 <P><LI>Become the local superuser <B>root</B> on the machine, if you are not
675 already, by issuing the <B>su</B> command.
676 <PRE> % <B>su root</B>
677 Password: <VAR>root_password</VAR>
679 <P><LI>Remove the <B>/usr/afs/local/NoAuth</B> file.
680 <PRE> # <B>rm /usr/afs/local/NoAuth</B>
682 <A NAME="IDX7305"></A>
683 <P><LI>Authenticate as an administrative identity that belongs to the
684 <B>system:administrators</B> group and is listed in the
685 <B>/usr/afs/etc/UserList</B> file.
686 <PRE> # <B>klog</B> <<VAR>admin_user</VAR>>
687 Password: <<VAR>admin_password</VAR>>
689 <P><LI>If appropriate, log out from the console (or close the remote connection
690 you are using), after issuing the <B>unlog</B> command to destroy your
693 <P><H3><A NAME="Header_430" HREF="auagd002.htm#ToC_430">To create a new server encryption key in emergencies</A></H3>
695 <P><LI><A NAME="LIWQ376"></A><B>On the system control machine</B>, disable authorization
696 checking as instructed in <A HREF="#HDRWQ373">Disabling Authorization Checking in an Emergency</A>.
697 <P><LI><A NAME="LIWQ377"></A>Issue the <B>bos listkeys</B> command to display the key
698 version numbers already in use in the <B>KeyFile</B> file, as a first step
699 in choosing the new key's key version number.
700 <PRE> #<B> bos listkeys</B> <<VAR>machine name</VAR>> <B>-noauth</B>
704 <P><DT><B><B>listk</B>
705 </B><DD>Is the shortest acceptable abbreviation of <B>listkeys</B>.
706 <P><DT><B><VAR>machine name</VAR>
707 </B><DD>Specifies a file server machine.
708 <P><DT><B><B>-noauth</B>
709 </B><DD>Bypasses mutual authentication with the BOS Server. Include it in
710 case the key emergency is preventing successful mutual authentication.
712 <P><LI><A NAME="LIWQ378"></A>Choose a key version number for the new key, based on what you
713 learned in Step <A HREF="#LIWQ377">2</A> plus the following requirements:
715 <P><LI>It is best to keep your key version numbers in sequence by choosing a key
716 version number one greater than the largest existing one.
717 <P><LI>Key version numbers must be integers between 0 and 255 to comply with
719 <P><LI>Do not reuse a key version number currently listed in the
722 <A NAME="IDX7306"></A>
723 <P><LI><A NAME="LIWQ379"></A><B>On the system control machine</B>, issue the <B>bos
724 addkey</B> command to create a new AFS server encryption key in the
726 <PRE> # <B>bos addkey</B> <<VAR>machine name</VAR>> <B>-kvno</B> <<VAR>key version number</VAR>> <B>-noauth</B>
727 input key: <VAR>afs_password</VAR>
728 Retype input key: <VAR>afs_password</VAR>
732 <P><DT><B><B>addk</B>
733 </B><DD>Is the shortest acceptable abbreviation of <B>addkey</B>.
734 <P><DT><B><VAR>machine name</VAR>
735 </B><DD>Names the file server machine on which to define the new key in the
738 </B><DD>Specifies the key version number you chose in Step <A HREF="#LIWQ378">3</A>, an integer in the range 0 (zero) through 255. You
739 must specify the same number in Steps <A HREF="#LIWQ382">7</A>, <A HREF="#LIWQ383">8</A>, and <A HREF="#LIWQ386">13</A>.
740 <P><DT><B><B>-noauth</B>
741 </B><DD>Bypasses mutual authentication with the BOS Server. Include it in
742 case the key emergency is preventing successful mutual authentication.
743 <P><DT><B><VAR>afs_password</VAR>
744 </B><DD>Is a character string similar to a user password, of any length from one
745 to about 1,000 characters. To improve security, make the string as long
746 as is practical, and include nonalphabetic characters.
747 <P>Do not type an octal string directly. The BOS Server scrambles the
748 character string into an octal string appropriate for use as an encryption key
749 before recording it in the <B>KeyFile</B> file.
750 <P>Remember the string. You need to use it again in Steps <A HREF="#LIWQ382">7</A>, <A HREF="#LIWQ383">8</A>, and <A HREF="#LIWQ386">13</A>.
752 <P><LI><A NAME="LIWQ380"></A><B>On every database server machine in your cell</B> (other
753 than the system control machine), disable authorization checking as instructed
754 in <A HREF="#HDRWQ373">Disabling Authorization Checking in an Emergency</A>. Do not repeat the procedure on the system control
755 machine, if it is a database server machine, because you already disabled
756 authorization checking in Step <A HREF="#LIWQ376">1</A>. (If you need to learn which machines are database
757 server machines, use the <B>bos listhosts</B> command as described in <A HREF="auagd008.htm#HDRWQ95">To locate database server machines</A>.)
758 <P><LI><A NAME="LIWQ381"></A>Wait at least 90 seconds after finishing Step <A HREF="#LIWQ380">5</A>, to allow each of the database server processes (the
759 Authentication, Backup, Protection and Volume Location Servers) to finish
760 electing a new sync site. Then issue the <B>udebug</B> command to
761 verify that the election worked properly. Issue the following commands,
762 substituting each database server machine's name for <VAR>server
763 machine</VAR> in turn. Include the system control machine if it is a
764 database server machine.
765 <PRE> # <B>udebug</B> <<VAR>server machine</VAR>> <B>buserver</B>
766 # <B>udebug</B> <<VAR>server machine</VAR>> <B>kaserver</B>
767 # <B>udebug</B> <<VAR>server machine</VAR>> <B>ptserver</B>
768 # <B>udebug</B> <<VAR>server machine</VAR>> <B>vlserver</B>
770 <P>For each process, the output from all of the database server machines must
771 agree on which one is the sync site for the process. It is not,
772 however, necessary that the same machine serves as the sync site for each of
773 the four processes. For each process, the output from only one machine
774 must include the following string:
775 <PRE> I am sync site ...
777 <P>The output on the other machines instead includes the following line
778 <PRE> I am not sync site
780 <P>and a subsequent line that begins with the string <TT>Sync host</TT> and
781 specifies the IP address of the machine claiming to be the sync site.
782 <P>If the output does not meet these requirements or seems abnormal in another
783 way, contact AFS Product Support for assistance.
784 <P><LI><A NAME="LIWQ382"></A><B>On every database server machine in your cell</B> (other
785 than the system control machine), issue the <B>bos addkey</B> command
786 described in Step <A HREF="#LIWQ379">4</A>. Be sure to use the same values for
787 <VAR>afs_password</VAR> and <VAR>kvno</VAR> as you used in that step.
788 <A NAME="IDX7307"></A>
789 <P><LI><A NAME="LIWQ383"></A>Issue the <B>kas setpassword</B> command to define the new
790 key in the Authentication Database's <B>afs</B> entry. It must
791 match the key you created in Step <A HREF="#LIWQ379">4</A> and Step <A HREF="#LIWQ382">7</A>.
792 <PRE> # <B>kas setpassword -name afs</B> <B>-kvno</B> <<VAR>key version number</VAR>> <B>-noauth</B>
793 new_password: <VAR>afs_password</VAR>
794 Verifying, please re-enter new_password: <VAR>afs_password</VAR>
799 </B><DD>Is an acceptable alias for <B>setpassword</B> (<B>setp</B> is the
800 shortest acceptable abbreviation).
802 </B><DD>Is the same key version number you specified in Step <A HREF="#LIWQ379">4</A>.
803 <P><DT><B><VAR>afs_password</VAR>
804 </B><DD>Is the same character string you specified as <VAR>afs_password</VAR> in
805 Step <A HREF="#LIWQ379">4</A>. It does not echo visibly.
807 <P><LI><A NAME="LIWQ384"></A><B>On every database server machine in your cell</B>
808 (including the system control machine if it is a database server machine),
809 reenable authorization checking as instructed in <A HREF="#HDRWQ375">Reenabling Authorization Checking in an Emergency</A>. If the system control machine is not a database
810 server machine, do not perform this procedure until Step <A HREF="#LIWQ385">11</A>.
811 <P><LI>Repeat Step <A HREF="#LIWQ381">6</A> to verify that each database server process has properly
812 elected a sync site after being restarted in Step <A HREF="#LIWQ384">9</A>.
813 <P><LI><A NAME="LIWQ385"></A><B>On the system control machine</B> (if it is not a
814 database server machine), reenable authorization checking as instructed in <A HREF="#HDRWQ375">Reenabling Authorization Checking in an Emergency</A>. If it is a database server machine, you already
815 performed the procedure in Step <A HREF="#LIWQ384">9</A>.
816 <P><LI><B>On all remaining (simple) file server machines</B>, disable
817 authorization checking as instructed in <A HREF="#HDRWQ373">Disabling Authorization Checking in an Emergency</A>.
818 <P><LI><A NAME="LIWQ386"></A><B>On all remaining (simple) file server machines</B>,
819 issue the <B>bos addkey</B> command described in Step <A HREF="#LIWQ379">4</A>. Be sure to use the same values for
820 <VAR>afs_password</VAR> and <VAR>kvno</VAR> as you used in that step.
821 <P><LI><B>On all remaining (simple) file server machines</B>, reenable
822 authorization checking as instructed in <A HREF="#HDRWQ375">Reenabling Authorization Checking in an Emergency</A>.
824 <HR><P ALIGN="center"> <A HREF="../index.htm"><IMG SRC="../books.gif" BORDER="0" ALT="[Return to Library]"></A> <A HREF="auagd002.htm#ToC"><IMG SRC="../toc.gif" BORDER="0" ALT="[Contents]"></A> <A HREF="auagd013.htm"><IMG SRC="../prev.gif" BORDER="0" ALT="[Previous Topic]"></A> <A HREF="#Top_Of_Page"><IMG SRC="../top.gif" BORDER="0" ALT="[Top of Topic]"></A> <A HREF="auagd015.htm"><IMG SRC="../next.gif" BORDER="0" ALT="[Next Topic]"></A> <A HREF="auagd026.htm#HDRINDEX"><IMG SRC="../index.gif" BORDER="0" ALT="[Index]"></A> <P>
825 <!-- Begin Footer Records ========================================== -->
827 <br>© <A HREF="http://www.ibm.com/">IBM Corporation 2000.</A> All Rights Reserved
829 <!-- End Footer Records ============================================ -->
830 <A NAME="Bot_Of_Page"></A>
git://git.openafs.org / openafs.git / blob