49ca7a97aae694eafae8651c4de8ca8cd88a9e2d
[openafs.git] / doc / xml / AdminGuide / auagd014.xml
1 <?xml version="1.0" encoding="UTF-8"?>
2 <chapter id="HDRWQ355">
3   <title>Managing Server Encryption Keys</title>
4
5   <para>This chapter explains how to maintain your cell's server encryption keys, which are vital for secure communications in
6   AFS.</para>
7
8   <sect1 id="HDRWQ356">
9     <title>Summary of Instructions</title>
10
11     <para>This chapter explains how to perform the following tasks by using the indicated commands:</para>
12
13     <informaltable frame="none">
14       <tgroup cols="2">
15         <colspec colwidth="70*" />
16
17         <colspec colwidth="30*" />
18
19         <tbody>
20           <row>
21             <entry>Add a new server encryption key</entry>
22
23             <entry><emphasis role="bold">bos addkey</emphasis> and <emphasis role="bold">kas setpassword</emphasis></entry>
24           </row>
25
26           <row>
27             <entry>Inspect key checksums in the Authentication Database</entry>
28
29             <entry><emphasis role="bold">kas examine</emphasis></entry>
30           </row>
31
32           <row>
33             <entry>Inspect key checksums in the <emphasis role="bold">KeyFile</emphasis></entry>
34
35             <entry><emphasis role="bold">bos listkeys</emphasis></entry>
36           </row>
37
38           <row>
39             <entry>Remove an old server encryption key</entry>
40
41             <entry><emphasis role="bold">bos removekey</emphasis></entry>
42           </row>
43         </tbody>
44       </tgroup>
45     </informaltable>
46   </sect1>
47
48   <sect1 id="HDRWQ358">
49     <title>About Server Encryption Keys</title>
50
51     <indexterm>
52       <primary>server encryption key</primary>
53
54       <secondary>defined</secondary>
55     </indexterm>
56
57     <indexterm>
58       <primary>AFS</primary>
59
60       <secondary>server encryption key</secondary>
61
62       <see>server encryption key</see>
63     </indexterm>
64
65     <para>An encryption key is a string of octal numbers used to encrypt and decrypt packets of information. In AFS, a server
66     encryption key is the key used to protect information being transferred between AFS server processes and between them and their
67     clients. A server encryption key is essentially a password for a server process and like a user password is stored in the
68     Authentication Database.</para>
69
70     <para>Maintaining your cell's server encryption keys properly is the most basic way to protect the information in your AFS
71     filespace from access by unauthorized users.</para>
72
73     <sect2 id="Header_412">
74       <title>Keys and Mutual Authentication: A Review</title>
75
76       <indexterm>
77         <primary>mutual authentication</primary>
78
79         <secondary>server encryption key's role</secondary>
80       </indexterm>
81
82       <indexterm>
83         <primary>server encryption key</primary>
84
85         <secondary>role in mutual authentication</secondary>
86       </indexterm>
87
88       <indexterm>
89         <primary>Ticket Granting Service</primary>
90       </indexterm>
91
92       <indexterm>
93         <primary>TGS</primary>
94       </indexterm>
95
96       <indexterm>
97         <primary>server ticket</primary>
98       </indexterm>
99
100       <indexterm>
101         <primary>session key</primary>
102       </indexterm>
103
104       <para>Server encryption keys play a central role in the mutual authentication between client and server processes in AFS. For
105       a more detailed description of mutual authentication, see <link linkend="HDRWQ75">A More Detailed Look at Mutual
106       Authentication</link>.</para>
107
108       <para>When a client wants to contact an AFS server, it first contacts the Ticket Granting Service (TGS) module of the
109       Authentication Server. After verifying the client's identity (based indirectly on the password of the human user whom the
110       client represents), the TGS gives the client a server ticket. This ticket is encrypted with the server's encryption key. (The
111       TGS also invents a second encryption key, called the session key, to be used only for a single episode of communication
112       between server and client. The server ticket and session key, together with other pieces of information, are collectively
113       referred to as a token.)</para>
114
115       <para>The client cannot read the server ticket or token because it does not know the server encryption key. However, the
116       client sends it to the AFS server along with service requests, because the ticket proves to the AFS server processes that it
117       has already authenticated with the TGS. AFS servers trust the TGS to grant tickets only to valid clients. The fact that the
118       client possesses a ticket encrypted with the server's encryption key proves to the server that the client is valid. On the
119       other hand, the client assumes that only a genuine AFS server knows the server encryption key needed to decrypt the ticket.
120       The server's ability to decrypt the ticket and understand its contents proves to the client that the server is
121       legitimate.</para>
122     </sect2>
123
124     <sect2 id="Header_413">
125       <title>Maintaining AFS Server Encryption Keys</title>
126
127       <para>As you maintain your cell's server encryption keys, keep the following in mind. <itemizedlist>
128           <listitem>
129             <para>Change the key frequently to enhance your cell's security. Changing the key at least once a month is strongly
130             recommended.</para>
131
132             <indexterm>
133               <primary>server encryption key</primary>
134
135               <secondary>changing frequently</secondary>
136             </indexterm>
137           </listitem>
138
139           <listitem>
140             <para>The AFS server encryption key currently in use is stored in two places. When you add a new key, you must make
141             changes in both places and make them in the correct order, as instructed in <link linkend="HDRWQ362">Adding Server
142             Encryption Keys</link>. Failure to follow the instructions can seriously impair cell functioning, as clients and servers
143             become unable to communicate. The two storage sites for the current server encryption key are the following:
144             <orderedlist>
145                 <listitem>
146                   <para>The file <emphasis role="bold">/usr/afs/etc/KeyFile</emphasis> on the local disk of every file server
147                   machine. The file can list more than one key, each with an associated numerical identifier, the key version number
148                   or kvno. A client token records the key version number of the key used to seal it, and the server process
149                   retrieves the appropriate key from this file when the client presents the token.</para>
150
151                   <indexterm>
152                     <primary>key version number</primary>
153
154                     <secondary>defined</secondary>
155                   </indexterm>
156
157                   <indexterm>
158                     <primary>kvno</primary>
159
160                     <secondary></secondary>
161
162                     <see>key version number</see>
163                   </indexterm>
164
165                   <indexterm>
166                     <primary>KeyFile file</primary>
167
168                     <secondary>storage site for server encryption keys</secondary>
169                   </indexterm>
170
171                   <indexterm>
172                     <primary>files</primary>
173
174                     <secondary>/usr/afs/etc/KeyFile</secondary>
175                   </indexterm>
176
177                   <indexterm>
178                     <primary>server encryption key</primary>
179
180                     <secondary>KeyFile file</secondary>
181                   </indexterm>
182                 </listitem>
183
184                 <listitem>
185                   <para>The <emphasis role="bold">afs</emphasis> entry in the Authentication Database. The current server encryption
186                   key is in the entry's password field, just like an individual user's scrambled password. The Authentication
187                   Server's Ticket Granting Service (TGS) uses this key to encrypt the tokens it gives to clients. There is only a
188                   single key in the entry, because the TGS never needs to read existing tokens, but only to generate new ones by
189                   using the current key.</para>
190
191                   <indexterm>
192                     <primary>server encryption key</primary>
193
194                     <secondary>Authentication Database</secondary>
195                   </indexterm>
196
197                   <indexterm>
198                     <primary>Authentication Database</primary>
199
200                     <secondary>site for AFS server encryption key</secondary>
201                   </indexterm>
202
203                   <indexterm>
204                     <primary>Authentication Database</primary>
205
206                     <secondary>afs entry</secondary>
207                   </indexterm>
208                 </listitem>
209               </orderedlist></para>
210
211             <para>For instructions on creating the initial <emphasis role="bold">afs</emphasis> entry and <emphasis
212             role="bold">KeyFile</emphasis> files as you install your cell's first server machine, see the OpenAFS Quick
213             Beginnings.</para>
214           </listitem>
215
216           <listitem>
217             <para>At any specific time, the tokens that the Authentication Server's Ticket Granting Service gives to clients are
218             sealed with only one of the server encryption keys, namely the one stored in the <emphasis role="bold">afs</emphasis>
219             entry in the Authentication Database.</para>
220           </listitem>
221
222           <listitem>
223             <para>When you add a new server encryption key, you cannot immediately remove the former key from the <emphasis
224             role="bold">/usr/afs/etc/KeyFile</emphasis> file on the local disk of every AFS server machine. Any time that you add a
225             new key, it is likely that some clients still have valid, unexpired tokens sealed with the previous key. The more
226             frequently you change the server encryption key, the more such tickets there are likely to be. To be able to grant
227             service appropriately to clients with such tokens, an AFS server process must still be able to access the server
228             encryption key used to seal it.</para>
229
230             <para>You can safely delete an old server encryption key only when it is certain that no clients have tokens sealed with
231             that key. In general, wait a period of time at least as long as the maximum token lifetime in your cell. By default, the
232             maximum token lifetime for users is 25 hours (except for users whose Authentication Database entries were created by
233             using the 3.0 version of AFS, for whom the default is 100 hours). You can use the <emphasis
234             role="bold">-lifetime</emphasis> argument to the <emphasis role="bold">kas setfields</emphasis> command to change this
235             default.</para>
236
237             <para>Instructions for removing obsolete keys appear in <link linkend="HDRWQ368">Removing Server Encryption
238             Keys</link>.</para>
239           </listitem>
240
241           <listitem>
242             <para>You create a new AFS server encryption key in much the same way regular users change their passwords, by providing
243             a character string that is converted into an encryption key automatically. See <link linkend="HDRWQ362">Adding Server
244             Encryption Keys</link>.</para>
245
246             <indexterm>
247               <primary>server encryption key</primary>
248
249               <secondary>password-like nature</secondary>
250             </indexterm>
251           </listitem>
252
253           <listitem>
254             <para>In addition to using server encryption keys when communicating with clients, the server processes use them to
255             protect communications with other server processes. Therefore, all server machines in your cell must have the same
256             version of the <emphasis role="bold">KeyFile</emphasis> file. The easiest way to maintain consistency (if you run the
257             United States edition of AFS) is to use the Update Server to distribute the contents of the system control machine's
258             <emphasis role="bold">/usr/afs/etc</emphasis> directory to all of the other server machines. There are two implications:
259             <itemizedlist>
260                 <listitem>
261                   <para>You must run the <emphasis role="bold">upserver</emphasis> process on the system control machine and an
262                   <emphasis role="bold">upclientetc</emphasis> process on all other server machines that references the system
263                   control machine. The OpenAFS Quick Beginnings explains how to install both processes. For instructions on
264                   verifying that the Update Server processes are running, see <link linkend="HDRWQ158">Displaying Process Status and
265                   Information from the BosConfig File</link>.</para>
266
267                   <indexterm>
268                     <primary>Update Server</primary>
269
270                     <secondary>distributor of KeyFile file</secondary>
271                   </indexterm>
272                 </listitem>
273
274                 <listitem>
275                   <para>Change the <emphasis role="bold">KeyFile</emphasis> file only on the system control machine (except in the
276                   types of emergencies discussed in <link linkend="HDRWQ370">Handling Server Encryption Key Emergencies</link>). Any
277                   changes you make on other server machines are overwritten the next time the <emphasis
278                   role="bold">upclientetc</emphasis> process retrieves the contents of the system control machine's <emphasis
279                   role="bold">/usr/afs/etc</emphasis> directory. By default, this happens every five minutes.</para>
280
281                   <indexterm>
282                     <primary>system control machine</primary>
283
284                     <secondary>source for common KeyFile file</secondary>
285                   </indexterm>
286                 </listitem>
287               </itemizedlist></para>
288
289             <para>If you run the international edition of AFS, do not use the Update Server to distribute the contents of the
290             <emphasis role="bold">/usr/afs/etc</emphasis> directory, particularly the <emphasis role="bold">KeyFile</emphasis> file.
291             The data in the file is too sensitive for transfer in unencrypted form, and because of United States government exports
292             regulations the international edition of AFS does not include the necessary encryption routines in a form that the
293             Update Server can use. You must instead modify the file on each server machine individually, taking care to enter the
294             same key on every server machine.</para>
295           </listitem>
296
297           <listitem>
298             <para>Never edit the <emphasis role="bold">KeyFile</emphasis> directly with a text editor. Instead, always use the
299             appropriate <emphasis role="bold">bos</emphasis> commands as instructed in <link linkend="HDRWQ362">Adding Server
300             Encryption Keys</link> and <link linkend="HDRWQ368">Removing Server Encryption Keys</link>.</para>
301           </listitem>
302         </itemizedlist></para>
303     </sect2>
304   </sect1>
305
306   <sect1 id="HDRWQ359">
307     <title>Displaying Server Encryption Keys</title>
308
309     <para>To display the server encryption keys in the <emphasis role="bold">/usr/afs/etc/KeyFile</emphasis> file on any file server
310     machine, use the <emphasis role="bold">bos listkeys</emphasis> command. Use the <emphasis role="bold">kas examine</emphasis>
311     command to display the key in the Authentication Database's <emphasis role="bold">afs</emphasis> entry.</para>
312
313     <indexterm>
314       <primary>checksum</primary>
315     </indexterm>
316
317     <indexterm>
318       <primary>server encryption key</primary>
319
320       <secondary>checksum displayed</secondary>
321     </indexterm>
322
323     <para>By default the commands do not display the actual string of octal digits that constitute a key, but rather a checksum, a
324     decimal number derived by encrypting a constant with the key. This prevents unauthorized users from easily accessing the actual
325     key, which they can then use to falsify or eavesdrop on protected communications. The <emphasis role="bold">bos
326     listkeys</emphasis> and <emphasis role="bold">kas examine</emphasis> commands generate the same checksum for a given key, so
327     displaying checksums rather than actual keys is generally sufficient. If you suspect that the keys differ in a way that the
328     checksums are not revealing, then you are probably experiencing authentication problems throughout your cell. The easiest
329     solution is to create a new server encryption key following the instructions in <link linkend="HDRWQ362">Adding Server
330     Encryption Keys</link> or <link linkend="HDRWQ370">Handling Server Encryption Key Emergencies</link>. Another common reason to
331     issue the <emphasis role="bold">bos listkeys</emphasis> command is to display the key version numbers currently in use, in
332     preparation for choosing the next one; here, the checksum is sufficient because the key itself is irrelevant.</para>
333
334     <para>If it is important to display the actual octal digits, include the <emphasis role="bold">-showkey</emphasis> argument to
335     both the <emphasis role="bold">bos listkeys</emphasis> and <emphasis role="bold">kas examine</emphasis> commands.</para>
336
337     <indexterm>
338       <primary>KeyFile file</primary>
339
340       <secondary>displaying</secondary>
341     </indexterm>
342
343     <indexterm>
344       <primary>displaying</primary>
345
346       <secondary>KeyFile file</secondary>
347     </indexterm>
348
349     <indexterm>
350       <primary>server encryption key</primary>
351
352       <secondary>displaying from KeyFile file</secondary>
353     </indexterm>
354
355     <indexterm>
356       <primary>displaying</primary>
357
358       <secondary>server encryption keys in KeyFile file</secondary>
359     </indexterm>
360
361     <indexterm>
362       <primary>commands</primary>
363
364       <secondary>bos listkeys</secondary>
365     </indexterm>
366
367     <indexterm>
368       <primary>bos commands</primary>
369
370       <secondary>listkeys</secondary>
371     </indexterm>
372
373     <sect2 id="HDRWQ360">
374       <title>To display the KeyFile file</title>
375
376       <orderedlist>
377         <listitem>
378           <para>Verify that you are authenticated as a user listed in the <emphasis role="bold">/usr/afs/etc/UserList</emphasis>
379           file. If necessary, issue the <emphasis role="bold">bos listusers</emphasis> command, which is fully described in <link
380           linkend="HDRWQ593">To display the users in the UserList file</link>. <programlisting>
381    % <emphasis role="bold">bos listusers</emphasis> &lt;<replaceable>machine name</replaceable>&gt;
382 </programlisting></para>
383         </listitem>
384
385         <listitem>
386           <para>Issue the <emphasis role="bold">bos listkeys</emphasis> command to display the contents of one machine's <emphasis
387           role="bold">/usr/afs/etc/KeyFile</emphasis> file. <programlisting>
388    % <emphasis role="bold">bos listkeys</emphasis> &lt;<replaceable>machine name</replaceable>&gt; [<emphasis role="bold">-showkey</emphasis>]
389 </programlisting></para>
390
391           <para>where <variablelist>
392               <varlistentry>
393                 <term><emphasis role="bold">listk</emphasis></term>
394
395                 <listitem>
396                   <para>Is the shortest acceptable abbreviation of <emphasis role="bold">listkeys</emphasis>.</para>
397                 </listitem>
398               </varlistentry>
399
400               <varlistentry>
401                 <term><emphasis role="bold">machine name</emphasis></term>
402
403                 <listitem>
404                   <para>Names a file server machine. In the normal case, it is acceptable to name any machine, because correct cell
405                   functioning requires that the <emphasis role="bold">KeyFile</emphasis> file be the same on all of them.</para>
406                 </listitem>
407               </varlistentry>
408
409               <varlistentry>
410                 <term><emphasis role="bold">-showkey</emphasis></term>
411
412                 <listitem>
413                   <para>Displays the octal digits that constitute each key.</para>
414                 </listitem>
415               </varlistentry>
416             </variablelist></para>
417         </listitem>
418       </orderedlist>
419
420       <para>In the following example, the output displays a checksum for each server encryption key rather than the actual octal
421       digits. The penultimate line indicates when an administrator last changed the file, and the final line confirms that the
422       output is complete.</para>
423
424       <programlisting>
425    % <emphasis role="bold">bos listkeys fs1.abc.com</emphasis>
426    key 0 has cksum 972037177
427    key 1 has cksum 2825165022
428    Keys last changed on Wed Jan 13 11:20:29 1999. 
429    All done.
430 </programlisting>
431
432       <indexterm>
433         <primary>Authentication Database</primary>
434
435         <secondary>server encryption key</secondary>
436
437         <tertiary>displaying</tertiary>
438       </indexterm>
439
440       <indexterm>
441         <primary>displaying</primary>
442
443         <secondary>server encryption key from Authentication Database</secondary>
444       </indexterm>
445
446       <indexterm>
447         <primary>afs entry in Authentication Database</primary>
448
449         <secondary>displaying</secondary>
450       </indexterm>
451
452       <indexterm>
453         <primary>server encryption key</primary>
454
455         <secondary>displaying from Authentication Database</secondary>
456       </indexterm>
457
458       <indexterm>
459         <primary>commands</primary>
460
461         <secondary>kas examine</secondary>
462       </indexterm>
463
464       <indexterm>
465         <primary>kas commands</primary>
466
467         <secondary>examine, to inspect afs key</secondary>
468       </indexterm>
469     </sect2>
470
471     <sect2 id="HDRWQ361">
472       <title>To display the afs key from the Authentication Database</title>
473
474       <orderedlist>
475         <listitem>
476           <para>Issue the <emphasis role="bold">kas examine</emphasis> command to display the <emphasis role="bold">afs</emphasis>
477           entry in the Authentication Database.</para>
478
479           <para>The Authentication Server performs its own authentication rather than accepting your existing AFS token. By default,
480           it authenticates your local (UNIX) identity, which possibly does not correspond to an AFS-privileged administrator.
481           Include the <emphasis role="bold">-admin</emphasis> argument to name an identity that has the
482           <computeroutput>ADMIN</computeroutput> flag on its Authentication Database entry. To verify that an entry has the flag,
483           issue the <emphasis role="bold">kas examine</emphasis> command as described in <link linkend="HDRWQ590">To check if the
484           ADMIN flag is set</link>.</para>
485
486           <programlisting>
487    % <emphasis role="bold">kas examine afs</emphasis> [<emphasis role="bold">-showkey</emphasis>]  \
488                  <emphasis role="bold">-admin</emphasis>  &lt;<replaceable>admin principal to use for authentication</replaceable>&gt;  
489    Administrator's (admin_user) password: &lt;<replaceable>admin_password</replaceable>&gt;
490 </programlisting>
491
492           <para>where <variablelist>
493               <varlistentry>
494                 <term><emphasis role="bold">e</emphasis></term>
495
496                 <listitem>
497                   <para>Is the shortest acceptable abbreviation of <emphasis role="bold">examine</emphasis>.</para>
498                 </listitem>
499               </varlistentry>
500
501               <varlistentry>
502                 <term><emphasis role="bold">afs</emphasis></term>
503
504                 <listitem>
505                   <para>Designates the <emphasis role="bold">afs</emphasis> entry.</para>
506                 </listitem>
507               </varlistentry>
508
509               <varlistentry>
510                 <term><emphasis role="bold">-showkey</emphasis></term>
511
512                 <listitem>
513                   <para>Displays the octal digits that constitute the key.</para>
514                 </listitem>
515               </varlistentry>
516
517               <varlistentry>
518                 <term><emphasis role="bold">-admin</emphasis></term>
519
520                 <listitem>
521                   <para>Names an administrative account with the <computeroutput>ADMIN</computeroutput> flag on its Authentication
522                   Database entry, such as <emphasis role="bold">admin</emphasis>. The password prompt echoes it as admin_user. Enter
523                   the appropriate password as admin_password.</para>
524                 </listitem>
525               </varlistentry>
526             </variablelist></para>
527         </listitem>
528       </orderedlist>
529
530       <para>In the following example, the <emphasis role="bold">admin</emphasis> user displays the <emphasis
531       role="bold">afs</emphasis> entry without using the <emphasis role="bold">-showkey</emphasis> flag. The second line shows the
532       key version number in parentheses and the key's checksum. The line that begins with the string <computeroutput>last
533       mod</computeroutput> reports the date on which the indicated administrator changed the key. There is no necessary relationship
534       between this date and the date reported by the <emphasis role="bold">bos listkeys</emphasis> command, because the latter date
535       changes for any type of change to the <emphasis role="bold">KeyFile</emphasis> file, not just a key addition. For a
536       description of the other lines in the output from the <emphasis role="bold">kas examine</emphasis> command, see its reference
537       page in the OpenAFS Administration Reference.</para>
538
539       <programlisting>
540    % <emphasis role="bold">kas examine afs  -admin admin</emphasis>
541    Administrator's (admin) password: &lt;<replaceable>admin_password</replaceable>&gt;
542    User data for afs
543     key (1) cksum is 2825165022, last cpw: no date
544     password will never expire.
545     An unlimited number of unsuccessful authentications is permitted.
546     entry expires on never. Max ticket lifetime 100.00 hours.
547     last mod on Wed Jan 13 11:21:36 1999 by admin
548     permit password reuse
549 </programlisting>
550     </sect2>
551   </sect1>
552
553   <sect1 id="HDRWQ362">
554     <title>Adding Server Encryption Keys</title>
555
556     <indexterm>
557       <primary>adding</primary>
558
559       <secondary>server encryption key to KeyFile file</secondary>
560     </indexterm>
561
562     <indexterm>
563       <primary>defining</primary>
564
565       <secondary>server encryption key</secondary>
566     </indexterm>
567
568     <indexterm>
569       <primary>creating</primary>
570
571       <secondary>server encryption key</secondary>
572     </indexterm>
573
574     <indexterm>
575       <primary>server encryption key</primary>
576
577       <secondary>adding to KeyFile file</secondary>
578     </indexterm>
579
580     <indexterm>
581       <primary>KeyFile file</primary>
582
583       <secondary>adding server encryption key</secondary>
584     </indexterm>
585
586     <indexterm>
587       <primary>Authentication Database</primary>
588
589       <secondary>server encryption key</secondary>
590
591       <tertiary>setting</tertiary>
592     </indexterm>
593
594     <indexterm>
595       <primary>defining</primary>
596
597       <secondary>server encryption key in Authentication Database</secondary>
598     </indexterm>
599
600     <indexterm>
601       <primary>afs entry in Authentication Database</primary>
602
603       <secondary>setting server encryption key</secondary>
604     </indexterm>
605
606     <indexterm>
607       <primary>server encryption key</primary>
608
609       <secondary>setting in Authentication Database</secondary>
610     </indexterm>
611
612     <para>As noted, AFS records server encryption keys in two separate places: <orderedlist>
613         <listitem>
614           <para>In the file <emphasis role="bold">/usr/afs/etc/KeyFile</emphasis> on the local disk of each server machine, for use
615           by the AFS server processes running on the machine</para>
616         </listitem>
617
618         <listitem>
619           <para>In the <emphasis role="bold">afs</emphasis> entry in the Authentication Database, for use by the Ticket Granting
620           Service (TGS) when creating tokens</para>
621         </listitem>
622       </orderedlist></para>
623
624     <para>To ensure that server processes and the TGS share the same AFS server encryption key, execute all the steps in this
625     section without interruption.</para>
626
627     <para>The following instructions include a step in which you restart the database server processes (the Authentication, Backup,
628     Protection, and Volume Location Server processes) on all database server machines. As a database server process starts, it reads
629     in the server encryption key that has the highest key version number in the <emphasis role="bold">KeyFile</emphasis> file and
630     uses it to protect the messages that it sends for synchronizing the database and maintaining quorum. It uses the same key
631     throughout its lifetime, which can be for an extended period, even if you remove the key from the <emphasis
632     role="bold">KeyFile</emphasis> file. However, if one of the peer database server processes restarts and the others do not,
633     quorum and database synchronization break down because the processes are no longer using the same key: the restarted process is
634     using the key that currently has the highest key version number, and the other processes are still using the key they read in
635     when they originally started. To avoid this problem, it is safest to restart all of the database server processes when adding a
636     new key.</para>
637
638     <para>After adding a new key, you can remove obsolete keys from the <emphasis role="bold">KeyFile</emphasis> file to prevent it
639     from becoming cluttered. However, you must take care not to remove keys that client or server processes are still using. For
640     discussion and instructions, see <link linkend="HDRWQ368">Removing Server Encryption Keys</link>.</para>
641
642     <sect2 id="HDRWQ363">
643       <title>To add a new server encryption key</title>
644
645       <orderedlist>
646         <listitem>
647           <para>Verify that you are authenticated as a user listed in the <emphasis role="bold">/usr/afs/etc/UserList</emphasis>
648           file. If necessary, issue the <emphasis role="bold">bos listusers</emphasis> command, which is fully described in <link
649           linkend="HDRWQ593">To display the users in the UserList file</link>. <programlisting>
650    % <emphasis role="bold">bos listusers</emphasis> &lt;<replaceable>machine name</replaceable>&gt;
651 </programlisting></para>
652         </listitem>
653
654         <listitem>
655           <para><anchor id="LIWQ364" />Issue the <emphasis role="bold">bos listkeys</emphasis> command to display the key version
656           numbers that are already in use, as a first step in choosing the key version number for the new key. <programlisting>
657    % <emphasis role="bold">bos listkeys</emphasis> &lt;<replaceable>machine name</replaceable>&gt;
658 </programlisting></para>
659
660           <para>where <variablelist>
661               <varlistentry>
662                 <term><emphasis role="bold">listk</emphasis></term>
663
664                 <listitem>
665                   <para>Is the shortest acceptable abbreviation of <emphasis role="bold">listkeys</emphasis>.</para>
666                 </listitem>
667               </varlistentry>
668
669               <varlistentry>
670                 <term><emphasis role="bold">machine name</emphasis></term>
671
672                 <listitem>
673                   <para>Names any file server machine.</para>
674                 </listitem>
675               </varlistentry>
676             </variablelist></para>
677         </listitem>
678
679         <listitem>
680           <para><anchor id="LIWQ365" />Choose a key version number for the new key, based on the output from Step <link
681           linkend="LIWQ364">2</link> and the following requirements: <itemizedlist>
682               <listitem>
683                 <para>A key version number must be an integer between 0 (zero) and 255 to comply with Kerberos standards. It is
684                 simplest if you keep your key version numbers in sequence by choosing a key version number one greater than the
685                 largest existing one.</para>
686               </listitem>
687
688               <listitem>
689                 <para>Do not reuse a key version number currently found in the <emphasis role="bold">KeyFile</emphasis> file,
690                 particularly if it is also the one in the Authentication Database <emphasis role="bold">afs</emphasis> entry. Client
691                 processes possibly still have tickets sealed with the key that originally had that key version number, but the
692                 server processes start using the new key marked with that key version number. Because the keys do not match, the
693                 server processes refuse requests from clients who hold legitimate tokens.</para>
694               </listitem>
695             </itemizedlist></para>
696
697           <indexterm>
698             <primary>bos commands</primary>
699
700             <secondary>addkey</secondary>
701
702             <tertiary>basic instructions</tertiary>
703           </indexterm>
704
705           <indexterm>
706             <primary>commands</primary>
707
708             <secondary>bos addkey</secondary>
709           </indexterm>
710         </listitem>
711
712         <listitem>
713           <para><anchor id="LIWQ366" />Issue the <emphasis role="bold">bos addkey</emphasis> command to create a new AFS server
714           encryption key in the <emphasis role="bold">KeyFile</emphasis> file.</para>
715
716           <para>If you run the United States edition of AFS and use the Update Server to distribute the contents of the system
717           control machine's <emphasis role="bold">/usr/afs/etc</emphasis> directory, substitute the system control machine for the
718           machine name argument. (If you have forgotten which machine is the system control machine, see <link linkend="HDRWQ96">To
719           locate the system control machine</link>.)</para>
720
721           <para>If you run the international edition of AFS or do not use the Update Server, repeat the <emphasis role="bold">bos
722           addkey</emphasis> command, substituting each server machine in your cell for the machine name argument in turn.</para>
723
724           <para>To avoid visible echoing of the string that corresponds to the new key, omit the <emphasis
725           role="bold">-key</emphasis> argument from the command line; instead enter the string at the prompts that appear when you
726           omit it, as shown in the following syntax specification.</para>
727
728           <programlisting>
729    % <emphasis role="bold">bos addkey  -server</emphasis> &lt;<replaceable>machine name</replaceable>&gt; <emphasis role="bold">-kvno</emphasis> &lt;<replaceable>key version number</replaceable>&gt;
730    input key: &lt;<replaceable>afs_password</replaceable>&gt;
731    Retype input key: &lt;<replaceable>afs_password</replaceable>&gt;
732 </programlisting>
733
734           <para>where <variablelist>
735               <varlistentry>
736                 <term><emphasis role="bold">addk</emphasis></term>
737
738                 <listitem>
739                   <para>Is the shortest acceptable abbreviation of <emphasis role="bold">addkey</emphasis>.</para>
740                 </listitem>
741               </varlistentry>
742
743               <varlistentry>
744                 <term><emphasis role="bold">-server</emphasis></term>
745
746                 <listitem>
747                   <para>Names the cell's system control machine if you are using the Update Server, or each server machine in turn
748                   if you are not.</para>
749                 </listitem>
750               </varlistentry>
751
752               <varlistentry>
753                 <term><emphasis role="bold">-kvno</emphasis></term>
754
755                 <listitem>
756                   <para>Specifies the new key's key version number as an integer from the range 0 (zero) through 255.</para>
757
758                   <para>Remember the number. You need to use it again in Step <link linkend="LIWQ367">6</link>. If you are using the
759                   international edition of AFS, be sure to type the same number each time you issue this command.</para>
760                 </listitem>
761               </varlistentry>
762
763               <varlistentry>
764                 <term><emphasis role="bold">afs_password</emphasis></term>
765
766                 <listitem>
767                   <para>Is a character string similar to a user password, of any length from one to about 1,000 characters. To
768                   improve security, include nonalphabetic characters and make the string as long as is practical (you need to type
769                   it only in this step and in Step <link linkend="LIWQ367">6</link>). If you are using the international edition of
770                   AFS, be sure to type the same string each time you issue this command.</para>
771
772                   <para>Do not enter an octal string directly. The BOS Server scrambles the character string into an octal string
773                   appropriate for use as an encryption key before recording it in the <emphasis role="bold">KeyFile</emphasis>
774                   file.</para>
775                 </listitem>
776               </varlistentry>
777             </variablelist></para>
778         </listitem>
779
780         <listitem>
781           <para>If you are using the Update Server, wait for a few minutes while the Update Server distributes the new <emphasis
782           role="bold">KeyFile</emphasis> file to all server machines. The maximum necessary waiting period is the largest value
783           provided for the <emphasis role="bold">-t</emphasis> argument to the <emphasis role="bold">upclientetc</emphasis>
784           process's initialization command used on any of the server machines; the default time is five minutes.</para>
785
786           <para>To be certain that all machines have the same <emphasis role="bold">KeyFile</emphasis> file, issue the <emphasis
787           role="bold">bos listkeys</emphasis> command for every file server machine and verify that the checksum for the new key is
788           the same on all machines.</para>
789
790           <programlisting>
791    % <emphasis role="bold">bos listkeys</emphasis> &lt;<replaceable>machine name</replaceable>&gt;
792 </programlisting>
793
794           <para>If you are not using the Update Server, try to complete Step <link linkend="LIWQ366">4</link> within five
795           minutes.</para>
796
797           <indexterm>
798             <primary>kas commands</primary>
799
800             <secondary>setpassword</secondary>
801           </indexterm>
802
803           <indexterm>
804             <primary>commands</primary>
805
806             <secondary>kas setpassword</secondary>
807           </indexterm>
808         </listitem>
809
810         <listitem>
811           <para><anchor id="LIWQ367" />Issue the <emphasis role="bold">kas setpassword</emphasis> command to enter the same key in
812           the <emphasis role="bold">afs</emphasis> entry in the Authentication Database.</para>
813
814           <para>The Authentication Server performs its own authentication rather than accepting your existing AFS token. By default,
815           it authenticates your local (UNIX) identity, which possibly does not correspond to an AFS-privileged administrator.
816           Include the <emphasis role="bold">-admin</emphasis> argument to name an identity that has the
817           <computeroutput>ADMIN</computeroutput> flag on its Authentication Database entry. To verify that an entry has the flag,
818           issue the <emphasis role="bold">kas examine</emphasis> command as described in <link linkend="HDRWQ590">To check if the
819           ADMIN flag is set</link>.</para>
820
821           <programlisting>
822    % <emphasis role="bold">kas setpassword -name afs -kvno</emphasis> &lt;<replaceable>kvno</replaceable>&gt;  \
823                      <emphasis role="bold">-admin</emphasis>  &lt;<replaceable>admin principal to use for authentication</replaceable>&gt;  
824    Administrator's (admin_user) password: &lt;<replaceable>admin_password</replaceable>&gt;
825    new_password: afs_password
826    Verifying, please re-enter new_password: &lt;<replaceable>admin_password</replaceable>&gt;
827 </programlisting>
828
829           <para>where <variablelist>
830               <varlistentry>
831                 <term><emphasis role="bold">sp</emphasis></term>
832
833                 <listitem>
834                   <para>Is an acceptable alias for <emphasis role="bold">setpassword</emphasis> (<emphasis
835                   role="bold">setp</emphasis> is the shortest acceptable abbreviation).</para>
836                 </listitem>
837               </varlistentry>
838
839               <varlistentry>
840                 <term><emphasis role="bold">-name afs</emphasis></term>
841
842                 <listitem>
843                   <para>Creates the new key in the <emphasis role="bold">afs</emphasis> entry.</para>
844                 </listitem>
845               </varlistentry>
846
847               <varlistentry>
848                 <term><emphasis role="bold">-kvno</emphasis></term>
849
850                 <listitem>
851                   <para>Specifies the same key version number as in Step <link linkend="LIWQ366">4</link>.</para>
852                 </listitem>
853               </varlistentry>
854
855               <varlistentry>
856                 <term><emphasis role="bold">-admin</emphasis></term>
857
858                 <listitem>
859                   <para>Names an administrative account with the <computeroutput>ADMIN</computeroutput> flag on its Authentication
860                   Database entry, such as <emphasis role="bold">admin</emphasis>. The password prompt echoes it as admin_user. Enter
861                   the appropriate password as admin_password.</para>
862                 </listitem>
863               </varlistentry>
864
865               <varlistentry>
866                 <term><emphasis role="bold">afs_password</emphasis></term>
867
868                 <listitem>
869                   <para>Is the same character string you entered in Step <link linkend="LIWQ366">4</link>.</para>
870                 </listitem>
871               </varlistentry>
872             </variablelist></para>
873         </listitem>
874
875         <listitem>
876           <para><emphasis role="bold">(Optional.)</emphasis> If you want to verify that the keys you just created in the <emphasis
877           role="bold">KeyFile</emphasis> file and the Authentication Database <emphasis role="bold">afs</emphasis> entry are
878           identical and have the same key version number, follow the instructions in <link linkend="HDRWQ359">Displaying Server
879           Encryption Keys</link>.</para>
880         </listitem>
881
882         <listitem>
883           <para>Issue the <emphasis role="bold">bos restart</emphasis> command to restart the database server processes on all
884           database server machines. This forces them to start using the key in the <emphasis role="bold">KeyFile</emphasis> file
885           that currently has the highest key version number.</para>
886
887           <para>Repeat this command in quick succession for each database server machine, starting with the machine that has the
888           lowest IP address.</para>
889
890           <programlisting>
891    % <emphasis role="bold">bos restart</emphasis>  &lt;<replaceable>machine name</replaceable>&gt; <emphasis role="bold">buserver kaserver ptserver vlserver</emphasis>
892 </programlisting>
893
894           <para>where <variablelist>
895               <varlistentry>
896                 <term><emphasis role="bold">res</emphasis></term>
897
898                 <listitem>
899                   <para>Is the shortest acceptable abbreviation of <emphasis role="bold">restart</emphasis>.</para>
900                 </listitem>
901               </varlistentry>
902
903               <varlistentry>
904                 <term><emphasis role="bold">machine name</emphasis></term>
905
906                 <listitem>
907                   <para>Names each database server machine in turn.</para>
908                 </listitem>
909               </varlistentry>
910
911               <varlistentry>
912                 <term><emphasis role="bold">buserver kaserver ptserver vlserver</emphasis></term>
913
914                 <listitem>
915                   <para>Designates the Backup Server, Authentication Server, Protection Server, and Volume Location (VL) Server,
916                   respectively.</para>
917                 </listitem>
918               </varlistentry>
919             </variablelist></para>
920         </listitem>
921       </orderedlist>
922     </sect2>
923   </sect1>
924
925   <sect1 id="HDRWQ368">
926     <title>Removing Server Encryption Keys</title>
927
928     <indexterm>
929       <primary>removing</primary>
930
931       <secondary>server encryption key from KeyFile file</secondary>
932     </indexterm>
933
934     <indexterm>
935       <primary>server encryption key</primary>
936
937       <secondary>removing from KeyFile file</secondary>
938     </indexterm>
939
940     <indexterm>
941       <primary>KeyFile file</primary>
942
943       <secondary>removing server encryption key</secondary>
944     </indexterm>
945
946     <para>You can periodically remove old keys from the <emphasis role="bold">/usr/afs/etc/KeyFile</emphasis> file to keep it to a
947     reasonable size. To avoid disturbing cell functioning, do not remove an old key until all tokens sealed with the key and held by
948     users or client processes have expired. After adding a new key, wait to remove old keys at least as long as the longest token
949     lifetime you use in your cell. For Authentication Database user entries created under AFS version 3.1 or higher, the default
950     token lifetime is 25 hours; for entries created under AFS version 3.0, it is 100 hours.</para>
951
952     <para>There is no command for removing the key from the <emphasis role="bold">afs</emphasis> entry in the Authentication
953     Database, because the key field in that entry must never be empty. Use the <emphasis role="bold">kas setpassword</emphasis>
954     command to replace the <emphasis role="bold">afs</emphasis> key, but only as part of the complete procedure detailed in <link
955     linkend="HDRWQ363">To add a new server encryption key</link>.</para>
956
957     <para>Never remove from the <emphasis role="bold">KeyFile</emphasis> file the key that is currently in the <emphasis
958     role="bold">afs</emphasis> entry in the Authentication Database. AFS server processes become unable to decrypt the tickets that
959     clients present to them.</para>
960
961     <sect2 id="HDRWQ369">
962       <title>To remove a key from the KeyFile file</title>
963
964       <orderedlist>
965         <listitem>
966           <para>Verify that you are authenticated as a user listed in the <emphasis role="bold">/usr/afs/etc/UserList</emphasis>
967           file. If necessary, issue the <emphasis role="bold">bos listusers</emphasis> command, which is fully described in <link
968           linkend="HDRWQ593">To display the users in the UserList file</link>. <programlisting>
969    % <emphasis role="bold">bos listusers</emphasis> &lt;<replaceable>machine name</replaceable>&gt;
970 </programlisting></para>
971         </listitem>
972
973         <listitem>
974           <para>Issue the <emphasis role="bold">bos listkeys</emphasis> command to display the key version number of each key you
975           want to remove. The output also reveals whether it has been at least 25 hours since a new key was placed in the <emphasis
976           role="bold">KeyFile</emphasis> file. For complete instructions for the <emphasis role="bold">bos listkeys</emphasis>
977           command, see <link linkend="HDRWQ360">To display the KeyFile file</link>. <programlisting>
978    % <emphasis role="bold">bos listkeys</emphasis> &lt;<replaceable>machine name</replaceable>&gt;
979 </programlisting></para>
980         </listitem>
981
982         <listitem>
983           <para>Issue the <emphasis role="bold">kas examine</emphasis> command to verify that the key currently in the
984           Authentication Database's <emphasis role="bold">afs</emphasis> entry does not have the same key version number as any of
985           the keys you are removing from the <emphasis role="bold">KeyFile</emphasis> file. For detailed instructions for the
986           <emphasis role="bold">kas examine</emphasis> command, see <link linkend="HDRWQ361">To display the afs key from the
987           Authentication Database</link>. <programlisting>
988    % <emphasis role="bold">kas examine afs  -admin</emphasis> &lt;<replaceable>admin principal to use for authentication</replaceable>&gt;  
989    Administrator's (admin_user) password: &lt;<replaceable>admin_password</replaceable>&gt;
990 </programlisting></para>
991
992           <indexterm>
993             <primary>commands</primary>
994
995             <secondary>bos removekey</secondary>
996           </indexterm>
997
998           <indexterm>
999             <primary>bos commands</primary>
1000
1001             <secondary>removekey</secondary>
1002           </indexterm>
1003         </listitem>
1004
1005         <listitem>
1006           <para>Issue the <emphasis role="bold">bos removekey</emphasis> command to remove one or more server encryption keys from
1007           the <emphasis role="bold">KeyFile</emphasis> file.</para>
1008
1009           <para>If you run the United States edition of AFS and use the Update Server to distribute the contents of the system
1010           control machine's <emphasis role="bold">/usr/afs/etc</emphasis> directory, substitute the system control machine for the
1011           machine name argument. (If you have forgotten which machine is the system control machine, see <link linkend="HDRWQ96">To
1012           locate the system control machine</link>.)</para>
1013
1014           <para>If you run the international edition of AFS or do not use the Update Server, repeat the <emphasis role="bold">bos
1015           removekey</emphasis> command, substituting each server machine in your cell for the machine name argument in turn.</para>
1016
1017           <programlisting>
1018    % <emphasis role="bold">bos removekey</emphasis> &lt;<replaceable>machine name</replaceable>&gt; &lt;<replaceable>key version number</replaceable>&gt;
1019 </programlisting>
1020
1021           <para>where <variablelist>
1022               <varlistentry>
1023                 <term><emphasis role="bold">removek</emphasis></term>
1024
1025                 <listitem>
1026                   <para>Is the shortest acceptable abbreviation of <emphasis role="bold">removekey</emphasis>.</para>
1027                 </listitem>
1028               </varlistentry>
1029
1030               <varlistentry>
1031                 <term><emphasis role="bold">machine name</emphasis></term>
1032
1033                 <listitem>
1034                   <para>Names the cell's system control machine if you are using the Update Server, or each server machine in turn
1035                   if you are not.</para>
1036                 </listitem>
1037               </varlistentry>
1038
1039               <varlistentry>
1040                 <term><emphasis role="bold">key version number</emphasis></term>
1041
1042                 <listitem>
1043                   <para>Specifies the key version number of each key to remove.</para>
1044                 </listitem>
1045               </varlistentry>
1046             </variablelist></para>
1047         </listitem>
1048       </orderedlist>
1049     </sect2>
1050   </sect1>
1051
1052   <sect1 id="HDRWQ370">
1053     <title>Handling Server Encryption Key Emergencies</title>
1054
1055     <indexterm>
1056       <primary>emergency</primary>
1057
1058       <secondary>server encryption keys mismatched</secondary>
1059     </indexterm>
1060
1061     <indexterm>
1062       <primary>server encryption key</primary>
1063
1064       <secondary>emergency need to replace</secondary>
1065     </indexterm>
1066
1067     <indexterm>
1068       <primary>mutual authentication</primary>
1069
1070       <secondary>failure due to mismatched keys</secondary>
1071     </indexterm>
1072
1073     <indexterm>
1074       <primary>Ubik</primary>
1075
1076       <secondary>failure due to mismatched server encryption keys</secondary>
1077     </indexterm>
1078
1079     <indexterm>
1080       <primary>handling</primary>
1081
1082       <secondary>server encryption key emergency</secondary>
1083     </indexterm>
1084
1085     <para>In rare circumstances, the AFS server processes can become unable to decrypt the server tickets that clients or peer
1086     server processes are presenting. Activity in your cell can come to a halt, because the server processes believe that the tickets
1087     are forged or expired, and refuse to execute any actions. This can happen on one machine or several; the effect is more serious
1088     when more machines are involved.</para>
1089
1090     <para>One common cause of server encryption key problems is that the client's ticket is encrypted with a key that the server
1091     process does not know. Usually this means that the <emphasis role="bold">/usr/afs/etc/KeyFile</emphasis> on the server machine
1092     does not include the key in the <emphasis role="bold">afs</emphasis> Authentication Database entry, which the Authentication
1093     Server's Ticket Granting Service (TGS) module is using to encrypt server tickets.</para>
1094
1095     <para>Another possibility is that the <emphasis role="bold">KeyFile</emphasis> files on different machines do not contain the
1096     same keys. In this case, communications among server processes themselves become impossible. For instance, AFS's replicated
1097     database mechanism (Ubik) breaks down if the instances of a database server process on the different database server machines
1098     are not using the same key.</para>
1099
1100     <para>The appearance of the following error message when you direct a <emphasis role="bold">bos</emphasis> command to a file
1101     server machine in the local cell is one possible symptom of server encryption key mismatch. (Note, however, that you can also
1102     get this message if you forget to include the <emphasis role="bold">-cell</emphasis> argument when directing the <emphasis
1103     role="bold">bos</emphasis> command to a file server machine in a foreign cell.)</para>
1104
1105     <programlisting>
1106    bos: failed to contact host's bosserver (security object was passed a bad ticket).
1107 </programlisting>
1108
1109     <para>The solution to server encryption key emergencies is to put a new AFS server encryption key in both the Authentication
1110     Database and the <emphasis role="bold">KeyFile</emphasis> file on every server machine, so that the TGS and all server processes
1111     again share the same key.</para>
1112
1113     <para>Handling key emergencies requires some unusual actions. The reasons for these actions are explained in the following
1114     sections; the actual procedures appear in the subsequent instructions.</para>
1115
1116     <sect2 id="HDRWQ371">
1117       <title>Prevent Mutual Authentication</title>
1118
1119       <para>It is necessary to prevent the server processes from trying to mutually authenticate with you as you deal with a key
1120       emergency, because they possibly cannot decrypt your token. When you do not mutually authenticate, the server processes assign
1121       you the identity <emphasis role="bold">anonymous</emphasis>. To prevent mutual authentication, use the <emphasis
1122       role="bold">unlog</emphasis> command to discard your tokens and include the <emphasis role="bold">-noauth</emphasis> flag on
1123       every command where it is available.</para>
1124     </sect2>
1125
1126     <sect2 id="Header_423">
1127       <title>Disable Authorization Checking by Hand</title>
1128
1129       <para>Because the server processes recognize you as the user <emphasis role="bold">anonymous</emphasis> when you do not
1130       mutually authenticate, you must turn off authorization checking. Only with authorization checking disabled do the server
1131       processes allow the <emphasis role="bold">anonymous</emphasis> user to perform privileged actions such as key creation.</para>
1132
1133       <para>In an emergency, disable authorization checking by creating the file <emphasis
1134       role="bold">/usr/afs/local/NoAuth</emphasis> by hand. In normal circumstances, use the <emphasis role="bold">bos
1135       setauth</emphasis> command instead.</para>
1136     </sect2>
1137
1138     <sect2 id="Header_424">
1139       <title>Work Quickly on Each Machine</title>
1140
1141       <para>Disabling authorization checking is a serious security exposure, because server processes on the affected machine
1142       perform any action for anyone. Disable authorization checking only for as long as necessary, completing all steps in an
1143       uninterrupted session and as quickly as possible.</para>
1144     </sect2>
1145
1146     <sect2 id="Header_425">
1147       <title>Work at the Console</title>
1148
1149       <para>Working at the console of each server machine on which you disable authorization checking ensures that no one else logs
1150       onto the console while you are working there. It does not prevent others from connecting to the machine remotely (using the
1151       <emphasis role="bold">telnet</emphasis> program, for example), which is why it is important to work quickly. The only way to
1152       ensure complete security is to disable network traffic, which is not a viable option in many environments. You can improve
1153       security in general by limiting the number of people who can connect remotely to your server machines at any time, as
1154       recommended in <link linkend="HDRWQ74">Improving Security in Your Cell</link>.</para>
1155     </sect2>
1156
1157     <sect2 id="HDRWQ372">
1158       <title>Change Individual KeyFile Files</title>
1159
1160       <para>If you use the Update Server to distribute the contents of the <emphasis role="bold">/usr/afs/etc</emphasis> directory,
1161       an emergency is the only time when it is appropriate to change the <emphasis role="bold">KeyFile</emphasis> file on individual
1162       machines instead. Updating each machine's file is necessary because mismatched keys can prevent the system control machine's
1163       <emphasis role="bold">upserver</emphasis> process from mutually authenticating with <emphasis
1164       role="bold">upclientetc</emphasis> processes on other server machines, in which case the <emphasis
1165       role="bold">upserver</emphasis> process refuses to distribute its <emphasis role="bold">KeyFile</emphasis> file to
1166       them.</para>
1167
1168       <para>Even if it appears that the Update Server is working correctly, the only way to verify that is to change the key on the
1169       system control machine and wait the standard delay period to see if the <emphasis role="bold">upclientetc</emphasis> processes
1170       retrieve the key. During an emergency, it does not usually make sense to wait the standard delay period. It is more efficient
1171       simply to update the file on each server machine separately. Also, even if the Update Server can distribute the file
1172       correctly, other processes can have trouble because of mismatched keys. The following instructions add the new key file on the
1173       system control machine first. If the Update Server is working, then it is distributing the same change as you are making on
1174       each server machine individually.</para>
1175
1176       <para>If your cell does not use the Update Server, or uses the international edition of AFS, you always change keys on server
1177       machines individually. The following instructions are also appropriate for you.</para>
1178     </sect2>
1179
1180     <sect2 id="Header_427">
1181       <title>Two Component Procedures</title>
1182
1183       <para>There are two subprocedures used frequently in the following instructions: disabling authorization checking and
1184       reenabling it. For the sake of clarity, the procedures are detailed here; the instructions refer to them as necessary.</para>
1185
1186       <sect3 id="HDRWQ373">
1187         <title>Disabling Authorization Checking in an Emergency</title>
1188
1189         <orderedlist>
1190           <listitem>
1191             <para>Become the local superuser <emphasis role="bold">root</emphasis> on the machine, if you are not already, by
1192             issuing the <emphasis role="bold">su</emphasis> command. <programlisting>
1193    % <emphasis role="bold">su root</emphasis>
1194    Password: &lt;<replaceable>root_password</replaceable>&gt;
1195 </programlisting></para>
1196
1197             <indexterm>
1198               <primary>NoAuth file</primary>
1199
1200               <secondary>creating in emergencies</secondary>
1201             </indexterm>
1202           </listitem>
1203
1204           <listitem>
1205             <para><anchor id="LIWQ374" />Create the file <emphasis role="bold">/usr/afs/local/NoAuth</emphasis> to disable
1206             authorization checking. <programlisting>
1207    # <emphasis role="bold">touch /usr/afs/local/NoAuth</emphasis>
1208 </programlisting></para>
1209
1210             <indexterm>
1211               <primary>unlog command</primary>
1212
1213               <secondary>when handling key emergency</secondary>
1214             </indexterm>
1215           </listitem>
1216
1217           <listitem>
1218             <para>Discard your tokens, in case they were sealed with an incompatible key, which can prevent some commands from
1219             executing. <programlisting>
1220    # <emphasis role="bold">unlog</emphasis>
1221 </programlisting></para>
1222           </listitem>
1223         </orderedlist>
1224       </sect3>
1225
1226       <sect3 id="HDRWQ375">
1227         <title>Reenabling Authorization Checking in an Emergency</title>
1228
1229         <orderedlist>
1230           <listitem>
1231             <para>Become the local superuser <emphasis role="bold">root</emphasis> on the machine, if you are not already, by
1232             issuing the <emphasis role="bold">su</emphasis> command. <programlisting>
1233    % <emphasis role="bold">su root</emphasis>
1234    Password: &lt;<replaceable>root_password</replaceable>&gt;
1235 </programlisting></para>
1236           </listitem>
1237
1238           <listitem>
1239             <para>Remove the <emphasis role="bold">/usr/afs/local/NoAuth</emphasis> file. <programlisting>
1240    # <emphasis role="bold">rm /usr/afs/local/NoAuth</emphasis>
1241 </programlisting></para>
1242
1243             <indexterm>
1244               <primary>klog command</primary>
1245
1246               <secondary>when handling key emergency</secondary>
1247             </indexterm>
1248           </listitem>
1249
1250           <listitem>
1251             <para>Authenticate as an administrative identity that belongs to the <emphasis
1252             role="bold">system:administrators</emphasis> group and is listed in the <emphasis
1253             role="bold">/usr/afs/etc/UserList</emphasis> file. <programlisting>
1254    # <emphasis role="bold">klog</emphasis> &lt;<replaceable>admin_user</replaceable>&gt;
1255    Password: &lt;<replaceable>admin_password</replaceable>&gt;
1256 </programlisting></para>
1257           </listitem>
1258
1259           <listitem>
1260             <para>If appropriate, log out from the console (or close the remote connection you are using), after issuing the
1261             <emphasis role="bold">unlog</emphasis> command to destroy your tokens.</para>
1262           </listitem>
1263         </orderedlist>
1264       </sect3>
1265     </sect2>
1266
1267     <sect2 id="Header_430">
1268       <title>To create a new server encryption key in emergencies</title>
1269
1270       <orderedlist>
1271         <listitem>
1272           <para><anchor id="LIWQ376" /><emphasis role="bold">On the system control machine</emphasis>, disable authorization
1273           checking as instructed in <link linkend="HDRWQ373">Disabling Authorization Checking in an Emergency</link>.</para>
1274         </listitem>
1275
1276         <listitem>
1277           <para><anchor id="LIWQ377" />Issue the <emphasis role="bold">bos listkeys</emphasis> command to display the key version
1278           numbers already in use in the <emphasis role="bold">KeyFile</emphasis> file, as a first step in choosing the new key's key
1279           version number. <programlisting>
1280    # <emphasis role="bold">bos listkeys</emphasis> &lt;<replaceable>machine name</replaceable>&gt; <emphasis role="bold">-noauth</emphasis>
1281 </programlisting></para>
1282
1283           <para>where <variablelist>
1284               <varlistentry>
1285                 <term><emphasis role="bold">listk</emphasis></term>
1286
1287                 <listitem>
1288                   <para>Is the shortest acceptable abbreviation of <emphasis role="bold">listkeys</emphasis>.</para>
1289                 </listitem>
1290               </varlistentry>
1291
1292               <varlistentry>
1293                 <term><emphasis role="bold">machine name</emphasis></term>
1294
1295                 <listitem>
1296                   <para>Specifies a file server machine.</para>
1297                 </listitem>
1298               </varlistentry>
1299
1300               <varlistentry>
1301                 <term><emphasis role="bold">-noauth</emphasis></term>
1302
1303                 <listitem>
1304                   <para>Bypasses mutual authentication with the BOS Server. Include it in case the key emergency is preventing
1305                   successful mutual authentication.</para>
1306                 </listitem>
1307               </varlistentry>
1308             </variablelist></para>
1309         </listitem>
1310
1311         <listitem>
1312           <para><anchor id="LIWQ378" />Choose a key version number for the new key, based on what you learned in Step <link
1313           linkend="LIWQ377">2</link> plus the following requirements: <itemizedlist>
1314               <listitem>
1315                 <para>It is best to keep your key version numbers in sequence by choosing a key version number one greater than the
1316                 largest existing one.</para>
1317               </listitem>
1318
1319               <listitem>
1320                 <para>Key version numbers must be integers between 0 and 255 to comply with Kerberos standards.</para>
1321               </listitem>
1322
1323               <listitem>
1324                 <para>Do not reuse a key version number currently listed in the <emphasis role="bold">KeyFile</emphasis>
1325                 file.</para>
1326               </listitem>
1327             </itemizedlist></para>
1328
1329           <indexterm>
1330             <primary>bos commands</primary>
1331
1332             <secondary>addkey</secondary>
1333
1334             <tertiary>when handling key emergency</tertiary>
1335           </indexterm>
1336         </listitem>
1337
1338         <listitem>
1339           <para><anchor id="LIWQ379" /><emphasis role="bold">On the system control machine</emphasis>, issue the <emphasis
1340           role="bold">bos addkey</emphasis> command to create a new AFS server encryption key in the <emphasis
1341           role="bold">KeyFile</emphasis> file. <programlisting>
1342    # <emphasis role="bold">bos addkey</emphasis> &lt;<replaceable>machine name</replaceable>&gt; <emphasis role="bold">-kvno</emphasis> &lt;<replaceable>key version number</replaceable>&gt; <emphasis
1343                 role="bold">-noauth</emphasis>
1344    input key: &lt;<replaceable>afs_password</replaceable>&gt;
1345    Retype input key: &lt;<replaceable>afs_password</replaceable>&gt;
1346 </programlisting></para>
1347
1348           <para>where <variablelist>
1349               <varlistentry>
1350                 <term><emphasis role="bold">addk</emphasis></term>
1351
1352                 <listitem>
1353                   <para>Is the shortest acceptable abbreviation of <emphasis role="bold">addkey</emphasis>.</para>
1354                 </listitem>
1355               </varlistentry>
1356
1357               <varlistentry>
1358                 <term><emphasis role="bold">machine name</emphasis></term>
1359
1360                 <listitem>
1361                   <para>Names the file server machine on which to define the new key in the <emphasis role="bold">KeyFile</emphasis>
1362                   file.</para>
1363                 </listitem>
1364               </varlistentry>
1365
1366               <varlistentry>
1367                 <term><emphasis role="bold">-kvno</emphasis></term>
1368
1369                 <listitem>
1370                   <para>Specifies the key version number you chose in Step <link linkend="LIWQ378">3</link>, an integer in the range
1371                   0 (zero) through 255. You must specify the same number in Steps <link linkend="LIWQ382">7</link>, <link
1372                   linkend="LIWQ383">8</link>, and <link linkend="LIWQ386">13</link>.</para>
1373                 </listitem>
1374               </varlistentry>
1375
1376               <varlistentry>
1377                 <term><emphasis role="bold">-noauth</emphasis></term>
1378
1379                 <listitem>
1380                   <para>Bypasses mutual authentication with the BOS Server. Include it in case the key emergency is preventing
1381                   successful mutual authentication.</para>
1382                 </listitem>
1383               </varlistentry>
1384
1385               <varlistentry>
1386                 <term><emphasis role="bold">afs_password</emphasis></term>
1387
1388                 <listitem>
1389                   <para>Is a character string similar to a user password, of any length from one to about 1,000 characters. To
1390                   improve security, make the string as long as is practical, and include nonalphabetic characters.</para>
1391
1392                   <para>Do not type an octal string directly. The BOS Server scrambles the character string into an octal string
1393                   appropriate for use as an encryption key before recording it in the <emphasis role="bold">KeyFile</emphasis>
1394                   file.</para>
1395
1396                   <para>Remember the string. You need to use it again in Steps <link linkend="LIWQ382">7</link>, <link
1397                   linkend="LIWQ383">8</link>, and <link linkend="LIWQ386">13</link>.</para>
1398                 </listitem>
1399               </varlistentry>
1400             </variablelist></para>
1401         </listitem>
1402
1403         <listitem>
1404           <para><anchor id="LIWQ380" /><emphasis role="bold">On every database server machine in your cell</emphasis> (other than
1405           the system control machine), disable authorization checking as instructed in <link linkend="HDRWQ373">Disabling
1406           Authorization Checking in an Emergency</link>. Do not repeat the procedure on the system control machine, if it is a
1407           database server machine, because you already disabled authorization checking in Step <link linkend="LIWQ376">1</link>. (If
1408           you need to learn which machines are database server machines, use the <emphasis role="bold">bos listhosts</emphasis>
1409           command as described in <link linkend="HDRWQ95">To locate database server machines</link>.)</para>
1410         </listitem>
1411
1412         <listitem>
1413           <para><anchor id="LIWQ381" />Wait at least 90 seconds after finishing Step <link linkend="LIWQ380">5</link>, to allow each
1414           of the database server processes (the Authentication, Backup, Protection and Volume Location Servers) to finish electing a
1415           new sync site. Then issue the <emphasis role="bold">udebug</emphasis> command to verify that the election worked properly.
1416           Issue the following commands, substituting each database server machine's name for server machine in turn. Include the
1417           system control machine if it is a database server machine. <programlisting>
1418    # <emphasis role="bold">udebug</emphasis> &lt;<replaceable>server machine</replaceable>&gt; <emphasis role="bold">buserver</emphasis>
1419    # <emphasis role="bold">udebug</emphasis> &lt;<replaceable>server machine</replaceable>&gt; <emphasis role="bold">kaserver</emphasis>
1420    # <emphasis role="bold">udebug</emphasis> &lt;<replaceable>server machine</replaceable>&gt; <emphasis role="bold">ptserver</emphasis>
1421    # <emphasis role="bold">udebug</emphasis> &lt;<replaceable>server machine</replaceable>&gt; <emphasis role="bold">vlserver</emphasis>
1422 </programlisting></para>
1423
1424           <para>For each process, the output from all of the database server machines must agree on which one is the sync site for
1425           the process. It is not, however, necessary that the same machine serves as the sync site for each of the four processes.
1426           For each process, the output from only one machine must include the following string:</para>
1427
1428           <programlisting>
1429    I am sync site ...
1430 </programlisting>
1431
1432           <para>The output on the other machines instead includes the following line</para>
1433
1434           <programlisting>
1435    I am not sync site
1436 </programlisting>
1437
1438           <para>and a subsequent line that begins with the string <computeroutput>Sync host</computeroutput> and specifies the IP
1439           address of the machine claiming to be the sync site.</para>
1440
1441           <para>If the output does not meet these requirements or seems abnormal in another way, contact AFS Product Support for
1442           assistance.</para>
1443         </listitem>
1444
1445         <listitem>
1446           <para><anchor id="LIWQ382" /><emphasis role="bold">On every database server machine in your cell</emphasis> (other than
1447           the system control machine), issue the <emphasis role="bold">bos addkey</emphasis> command described in Step <link
1448           linkend="LIWQ379">4</link>. Be sure to use the same values for afs_password and kvno as you used in that step.</para>
1449
1450           <indexterm>
1451             <primary>kas commands</primary>
1452
1453             <secondary>setpassword , when handling key emergency</secondary>
1454           </indexterm>
1455         </listitem>
1456
1457         <listitem>
1458           <para><anchor id="LIWQ383" />Issue the <emphasis role="bold">kas setpassword</emphasis> command to define the new key in
1459           the Authentication Database's <emphasis role="bold">afs</emphasis> entry. It must match the key you created in Step <link
1460           linkend="LIWQ379">4</link> and Step <link linkend="LIWQ382">7</link>. <programlisting>
1461    # <emphasis role="bold">kas setpassword  -name afs</emphasis>  <emphasis role="bold">-kvno</emphasis> &lt;<replaceable>key version number</replaceable>&gt; <emphasis
1462                 role="bold">-noauth</emphasis>
1463    new_password: &lt;<replaceable>afs_password</replaceable>&gt;
1464    Verifying, please re-enter new_password: &lt;<replaceable>afs_password</replaceable>&gt;
1465 </programlisting></para>
1466
1467           <para>where <variablelist>
1468               <varlistentry>
1469                 <term><emphasis role="bold">sp</emphasis></term>
1470
1471                 <listitem>
1472                   <para>Is an acceptable alias for <emphasis role="bold">setpassword</emphasis> (<emphasis
1473                   role="bold">setp</emphasis> is the shortest acceptable abbreviation).</para>
1474                 </listitem>
1475               </varlistentry>
1476
1477               <varlistentry>
1478                 <term><emphasis role="bold">-kvno</emphasis></term>
1479
1480                 <listitem>
1481                   <para>Is the same key version number you specified in Step <link linkend="LIWQ379">4</link>.</para>
1482                 </listitem>
1483               </varlistentry>
1484
1485               <varlistentry>
1486                 <term><emphasis role="bold">afs_password</emphasis></term>
1487
1488                 <listitem>
1489                   <para>Is the same character string you specified as afs_password in Step <link linkend="LIWQ379">4</link>. It does
1490                   not echo visibly.</para>
1491                 </listitem>
1492               </varlistentry>
1493             </variablelist></para>
1494         </listitem>
1495
1496         <listitem>
1497           <para><anchor id="LIWQ384" /><emphasis role="bold">On every database server machine in your cell</emphasis> (including the
1498           system control machine if it is a database server machine), reenable authorization checking as instructed in <link
1499           linkend="HDRWQ375">Reenabling Authorization Checking in an Emergency</link>. If the system control machine is not a
1500           database server machine, do not perform this procedure until Step <link linkend="LIWQ385">11</link>.</para>
1501         </listitem>
1502
1503         <listitem>
1504           <para>Repeat Step <link linkend="LIWQ381">6</link> to verify that each database server process has properly elected a sync
1505           site after being restarted in Step <link linkend="LIWQ384">9</link>.</para>
1506         </listitem>
1507
1508         <listitem>
1509           <para><anchor id="LIWQ385" /><emphasis role="bold">On the system control machine</emphasis> (if it is not a database
1510           server machine), reenable authorization checking as instructed in <link linkend="HDRWQ375">Reenabling Authorization
1511           Checking in an Emergency</link>. If it is a database server machine, you already performed the procedure in Step <link
1512           linkend="LIWQ384">9</link>.</para>
1513         </listitem>
1514
1515         <listitem>
1516           <para><emphasis role="bold">On all remaining (simple) file server machines</emphasis>, disable authorization checking as
1517           instructed in <link linkend="HDRWQ373">Disabling Authorization Checking in an Emergency</link>.</para>
1518         </listitem>
1519
1520         <listitem>
1521           <para><anchor id="LIWQ386" /><emphasis role="bold">On all remaining (simple) file server machines</emphasis>, issue the
1522           <emphasis role="bold">bos addkey</emphasis> command described in Step <link linkend="LIWQ379">4</link>. Be sure to use the
1523           same values for afs_password and kvno as you used in that step.</para>
1524         </listitem>
1525
1526         <listitem>
1527           <para><emphasis role="bold">On all remaining (simple) file server machines</emphasis>, reenable authorization checking as
1528           instructed in <link linkend="HDRWQ375">Reenabling Authorization Checking in an Emergency</link>.</para>
1529         </listitem>
1530       </orderedlist>
1531     </sect2>
1532   </sect1>
1533 </chapter>