| 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. |