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