Commit | Line | Data |
---|---|---|
805e021f CE |
1 | =head1 NAME |
2 | ||
3 | KeyFileExt - Defines extended AFS server encryption keys | |
4 | ||
5 | =head1 DESCRIPTION | |
6 | ||
7 | The F<KeyFileExt> file defines some of the server encryption keys | |
8 | that the AFS server | |
9 | processes running on the machine use to decrypt the tickets presented by | |
10 | clients during the mutual authentication process. AFS server processes | |
11 | perform privileged actions only for clients that possess a ticket | |
12 | encrypted with one of the keys from the F<KeyFile> or F<KeyFileExt>. | |
13 | The file must reside in the | |
14 | F</usr/afs/etc> directory on every server machine. For more detailed | |
15 | information on mutual authentication and server encryption keys, see the | |
16 | I<OpenAFS Administration Guide>. | |
17 | ||
18 | Each key has a corresponding key version number and encryption | |
19 | type that distinguishes it | |
20 | from the other keys. The tickets that clients present are also marked with | |
21 | a key version number and encryption type | |
22 | to tell the server process which key to use to | |
23 | decrypt it. The F<KeyFileExt> file must always include a key with the same | |
24 | key version number and encryption type | |
25 | and contents as the key currently listed for the | |
26 | C<afs/I<cell>> principal in the associated Kerberos v5 realm. | |
27 | (The principal C<afs> may be used if the cell and | |
28 | realm names are the same, but adding the cell name to the principal is | |
29 | recommended even in this case.) | |
30 | Keys in the F<KeyFile> must be DES keys; keys of stronger | |
31 | encryption types (such as those used by the rxkad-k5 extension) are | |
32 | contained in the F<KeyFileExt>. | |
33 | ||
34 | The F<KeyFileExt> file is in binary format, so always use the | |
35 | B<asetkey> command to administer it: | |
36 | ||
37 | =over 4 | |
38 | ||
39 | =item * | |
40 | ||
41 | The B<asetkey add> command to add a new key. | |
42 | ||
43 | =item * | |
44 | ||
45 | The B<asetkey list> command to display the keys. | |
46 | ||
47 | =item * | |
48 | ||
49 | The B<asetkey delete> command to remove a key from the file. | |
50 | ||
51 | =back | |
52 | ||
53 | The B<asetkey> commands must be run on the same server as the F<KeyFileExt> | |
54 | file to update. Normally, new | |
55 | keys should be added from a Kerberos v5 keytab using B<asetkey add>. | |
56 | ||
57 | The file should be edited on each server machine. | |
58 | ||
59 | =head1 CAUTIONS | |
60 | ||
61 | The most common error caused by changes to F<KeyFileExt> is to add a key that | |
62 | does not match the corresponding key for the Kerberos v5 principal or | |
63 | Authentication Server database entry. Both the key and the key version | |
64 | number must match the key for the corresponding principal, either | |
65 | C<afs/I<cell>> or C<afs>, in the Kerberos v5 realm. Using L<asetkey(8)> | |
66 | to add rxkad-k5 keys to the F<KeyFileExt> also requires specifying a krb5 | |
67 | encryption type number. Since the encryption type must be specified | |
68 | by its number (not a symbolic or string name), care must be taken to | |
69 | determine the correct encryption type to add. | |
70 | ||
71 | =head1 SEE ALSO | |
72 | ||
73 | L<KeyFile(5)>, | |
74 | L<asetkey(8)>, | |
75 | ||
76 | The I<OpenAFS Administration Guide> at | |
77 | L<http://docs.openafs.org/AdminGuide/>. | |
78 | ||
79 | =head1 COPYRIGHT | |
80 | ||
81 | IBM Corporation, 2000. <http://www.ibm.com/> All Rights Reserved. | |
82 | Massachusetts Institute of Technology, 2015. |