Update bos addkey/listkeys and KeyFile man pages for asetkey
[openafs.git] / doc / man-pages / pod5 / KeyFile.pod
index df35f80..875be0e 100644 (file)
@@ -11,41 +11,72 @@ perform privileged actions only for clients that possess a ticket
 encrypted with one of the keys from the file. The file must reside in the
 F</usr/afs/etc> directory on every server machine. For more detailed
 information on mutual authentication and server encryption keys, see the
-I<IBM AFS Administration Guide>.
+I<OpenAFS Administration Guide>.
 
 Each key has a corresponding a key version number that distinguishes it
 from the other keys. The tickets that clients present are also marked with
 a key version number to tell the server process which key to use to
 decrypt it. The F<KeyFile> file must always include a key with the same
-key version number and contents as the key currently listed for the C<afs>
-entry in the Authentication Database.
-
-The F<KeyFile> file is in binary format, so always use the appropriate
-commands from the B<bos> command suite to administer it:
+key version number and contents as the key currently listed for the
+C<afs/I<cell>> principal in the associated Kerberos v5 realm or
+Authentication Database. (The principal C<afs> may be used if the cell and
+realm names are the same, but adding the cell name to the principal is
+recommended even in this case. C<afs> must be used as the principal name
+if the cell uses the Authentication Server rather than a Kerberos v5
+realm.) The key must be a DES key; no stronger encryption type is
+supported.
+
+The F<KeyFile> file is in binary format, so always use either the
+B<asetkey> command or the appropriate commands from the B<bos> command
+suite to administer it:
 
 =over 4
 
 =item *
 
-The B<bos addkey> command to define a new key.
+The B<asetkey add> or B<bos addkey> command to add a new key.
 
 =item *
 
-The B<bos listkeys> command to display the keys.
+The B<asetkey list> or B<bos listkeys> command to display the keys.
 
 =item *
 
-The B<bos removekey> command to remove a key from the file.
+The B<asetkey delete> or B<bos removekey> command to remove a key from the
+file.
 
 =back
 
+The B<asetkey> commands must be run on the same server as the F<KeyFile>
+file to update. The B<bos> commands may be run remotely. Normally, new
+keys should be added from a Kerberos v5 keytab using B<asetkey add>.
+B<bos addkey> is normally only used if the Authentication Server is in use
+instead of a Kerberos v5 realm.
+
 In cells that use the Update Server to distribute the contents of the
 F</usr/afs/etc> directory, it is customary to edit only the copy of the
 file stored on the system control machine. Otherwise, edit the file on
 each server machine individually.
 
+=head1 CAUTIONS
+
+The most common error caused by changes to F<KeyFile> is to add a key that
+does not match the corresponding key for the Kerberos v5 principal or
+Authentication Server database entry. Both the key and the key version
+number must match the key for the corresponding principal, either
+C<afs/I<cell>> or C<afs>, in the Kerberos v5 realm or Authentication
+Database. For a Kerberos v5 realm, that principal must only have DES
+encryption types in the Kerberos KDC.
+
+In the unusual case of using B<bos addkey> to add a key with a known
+password matching a password used to generate Kerberos v5 keys, the keys
+in the Kerberos v5 KDC database must use C<afs3> salt, not the default
+Kerberos v5 salt. The salt doesn't matter for the more normal procedure of
+extracting a keytab and then adding the key using B<asetkey>.
+
 =head1 SEE ALSO
 
+L<asetkey(8)>,
 L<bos_addkey(8)>,
 L<bos_listkeys(8)>,
 L<bos_removekey(8)>,
@@ -53,12 +84,13 @@ L<kas_setpassword(8)>,
 L<upclient(8)>,
 L<upserver(8)>
 
-I<IBM AFS Administration Guide>
+The I<OpenAFS Administration Guide> at
+L<http://docs.openafs.org/AdminGuide/index.html>.
 
 =head1 COPYRIGHT
 
 IBM Corporation 2000. <http://www.ibm.com/> All Rights Reserved.
 
-This documentation is covered by the IBM Public License Version 1.0.  It was
-converted from HTML to POD by software written by Chas Williams and Russ
-Allbery, based on work by Alf Wachsmann and Elizabeth Cassell.
+This documentation is covered by the IBM Public License Version 1.0.  It
+was converted from HTML to POD by software written by Chas Williams and
+Russ Allbery, based on work by Alf Wachsmann and Elizabeth Cassell.