Commit | Line | Data |
---|---|---|
805e021f CE |
1 | =head1 NAME |
2 | ||
3 | bos_addkey - Adds a new server encryption key to the KeyFile file | |
4 | ||
5 | =head1 SYNOPSIS | |
6 | ||
7 | =for html | |
8 | <div class="synopsis"> | |
9 | ||
10 | B<bos addkey> S<<< B<-server> <I<machine name>> >>> S<<< [B<-key> <I<key>>] >>> | |
11 | S<<< B<-kvno> <I<key version number>> >>> S<<< [B<-cell> <I<cell name>>] >>> | |
12 | [B<-noauth>] [B<-localauth>] [B<-help>] | |
13 | ||
14 | B<bos addk> S<<< B<-s> <I<machine name>> >>> S<<< [B<-ke> <I<key>>] >>> | |
15 | S<<< B<-kv> <I<key version number>> >>> S<<< [B<-ce> <I<cell name>>] >>> [B<-n>] | |
16 | [B<-l>] [B<-h>] | |
17 | ||
18 | =for html | |
19 | </div> | |
20 | ||
21 | =head1 DESCRIPTION | |
22 | ||
23 | The B<bos addkey> command constructs a server encryption key from the text | |
24 | string provided, assigns it the key version number specified with the | |
25 | B<-kvno> argument, and adds it to the F</usr/afs/etc/KeyFile> file on the | |
26 | machine specified with the B<-server> argument. | |
27 | ||
28 | Normally, B<asetkey add> should be used instead of this command; see | |
29 | L<asetkey(8)> for more details. The primary use of B<bos addkey> is for | |
30 | cells that are still using the Authentication Server instead of a Kerberos | |
31 | v5 KDC. It may, however, also be useful in unusual circumstances where a | |
32 | key needs to be added based on a known password rather than via a Kerberos | |
33 | v5 keytab. | |
34 | ||
35 | When using B<bos addkey> with an AFS cell that uses the Authentication | |
36 | Server, be sure to use the B<kas setpassword> or B<kas setkey> command to | |
37 | add the same key to the C<afs> entry in the Authentication Database. | |
38 | ||
39 | Do not use the B<-key> argument, which echoes the password string visibly | |
40 | on the screen. If the argument is omitted, the BOS Server prompts for the | |
41 | string and does not echo it visibly: | |
42 | ||
43 | Input key: | |
44 | Retype input key: | |
45 | ||
46 | The BOS Server prohibits reuse of any key version number already listed in | |
47 | the F</usr/afs/etc/KeyFile> file. This ensures that users who still have | |
48 | tickets sealed with the current key are not prevented from communicating | |
49 | with a server process because the current key is overwritten with a new | |
50 | key. Use the B<bos listkeys> command to display the key version numbers in | |
51 | the F</usr/afs/etc/KeyFile> file. | |
52 | ||
53 | =head1 CAUTIONS | |
54 | ||
55 | In the unusual case of using B<bos addkey> to add a key with a known | |
56 | password matching a password used to generate Kerberos v5 keys, the key in | |
57 | the Kerberos v5 KDC database must have only the DES encryption type and | |
58 | must use C<afs3> salt, not the default Kerberos v5 salt. Otherwise, the | |
59 | key generated by B<bos addkey> will not match the key generated by the | |
60 | Kerberos v5 KDC. | |
61 | ||
62 | This command can only add keys to the F<KeyFile>; these keys must | |
63 | be DES keys. The stronger keys used by the rxkad-k5 extension are | |
64 | stored in the F<KeyFileExt>, which is not supported by this command. | |
65 | ||
66 | As such, the use of this command is disrecommended; use | |
67 | L<asetkey(8)> instead to benefit from the increased security | |
68 | of the rxkad-k5 extension. | |
69 | ||
70 | =head1 OPTIONS | |
71 | ||
72 | =over 4 | |
73 | ||
74 | =item B<-server> <I<machine name>> | |
75 | ||
76 | Indicates the server machine on which to change the | |
77 | F</usr/afs/etc/KeyFile> file. Identify the machine by IP address or its | |
78 | host name (either fully-qualified or abbreviated unambiguously). For | |
79 | details, see L<bos(8)>. | |
80 | ||
81 | In cells that use the Update Server to distribute the contents of the | |
82 | F</usr/afs/etc> directory, it is conventional to specify only the system | |
83 | control machine as a value for the B<-server> argument. Otherwise, repeat | |
84 | the command for each file server machine. For further discussion, see | |
85 | L<bos(8)>. | |
86 | ||
87 | =item B<-key> <I<key>> | |
88 | ||
89 | Specifies a character string just like a password; the BOS Server calls a | |
90 | DES conversion function to encode it into a form appropriate for use as an | |
91 | encryption key. Omit this argument to have the BOS Server prompt for the | |
92 | string instead. | |
93 | ||
94 | =item B<-kvno> <I<key version number>> | |
95 | ||
96 | Defines the new key's key version number. It must be an integer in the | |
97 | range from C<0> (zero) through C<255>. For the sake of simplicity, use | |
98 | the number one higher than the current highest key version number; use the | |
99 | B<bos listkeys> command to display key version numbers. | |
100 | ||
101 | =item B<-cell> <I<cell name>> | |
102 | ||
103 | Names the cell in which to run the command. Do not combine this argument | |
104 | with the B<-localauth> flag. For more details, see L<bos(8)>. | |
105 | ||
106 | =item B<-noauth> | |
107 | ||
108 | Assigns the unprivileged identity C<anonymous> to the issuer. Do not combine | |
109 | this flag with the B<-localauth> flag. For more details, see L<bos(8)>. | |
110 | ||
111 | =item B<-localauth> | |
112 | ||
113 | Constructs a server ticket using a key from the local | |
114 | F</usr/afs/etc/KeyFile> or F</usr/afs/etc/KeyFileExt> file. | |
115 | The B<bos> command interpreter presents the | |
116 | ticket to the BOS Server during mutual authentication. Do not combine this | |
117 | flag with the B<-cell> or B<-noauth> options. For more details, see | |
118 | L<bos(8)>. | |
119 | ||
120 | =item B<-help> | |
121 | ||
122 | Prints the online help for this command. All other valid options are | |
123 | ignored. | |
124 | ||
125 | =back | |
126 | ||
127 | =head1 OUTPUT | |
128 | ||
129 | If the strings typed at the C<Input key> and C<Retype input key> prompts | |
130 | do not match, the following message appears, and the command exits without | |
131 | adding a new key: | |
132 | ||
133 | Input key mismatch | |
134 | ||
135 | =head1 EXAMPLES | |
136 | ||
137 | The following command adds a new server encryption key with key version | |
138 | number 14 to the B<KeyFile> file kept on the machine C<fs1.example.com> (the | |
139 | system control machine). The issuer omits the B<-key> argument, as | |
140 | recommended, and provides the password at the prompts. | |
141 | ||
142 | % bos addkey -server fs1.example.com -kvno 14 | |
143 | Input key: | |
144 | Retype input key: | |
145 | ||
146 | =head1 PRIVILEGE REQUIRED | |
147 | ||
148 | The issuer must be listed in the F</usr/afs/etc/UserList> file on the | |
149 | machine named by the B<-server> argument, or must be logged onto a server | |
150 | machine as the local superuser C<root> if the B<-localauth> flag is | |
151 | included. | |
152 | ||
153 | =head1 SEE ALSO | |
154 | ||
155 | L<KeyFile(5)>, | |
156 | L<KeyFileExt(5)>, | |
157 | L<UserList(5)>, | |
158 | L<asetkey(8)>, | |
159 | L<bos(8)>, | |
160 | L<bos_listkeys(8)>, | |
161 | L<bos_removekey(8)> | |
162 | ||
163 | =head1 COPYRIGHT | |
164 | ||
165 | IBM Corporation 2000. <http://www.ibm.com/> All Rights Reserved. | |
166 | ||
167 | This documentation is covered by the IBM Public License Version 1.0. It | |
168 | was converted from HTML to POD by software written by Chas Williams and | |
169 | Russ Allbery, based on work by Alf Wachsmann and Elizabeth Cassell. |