Add a manual page for the KeyFileExt file.
Add cross-references from all places which currently reference
KeyFile(5), and update their body text accordingly.
Change-Id: Iab56847fcb59dda0c8a344a626ddb0ff35b98b26
Reviewed-on: http://gerrit.openafs.org/11770
Tested-by: BuildBot <buildbot@rampaginggeek.com>
Reviewed-by: Benjamin Kaduk <kaduk@mit.edu>
--- /dev/null
+=head1 NAME
+
+KeyFileExt - Defines extended AFS server encryption keys
+
+=head1 DESCRIPTION
+
+The F<KeyFileExt> file defines some of the server encryption keys
+that the AFS server
+processes running on the machine use to decrypt the tickets presented by
+clients during the mutual authentication process. AFS server processes
+perform privileged actions only for clients that possess a ticket
+encrypted with one of the keys from the F<KeyFile> or F<KeyFileExt>.
+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<OpenAFS Administration Guide>.
+
+Each key has a corresponding key version number and encryption
+type that distinguishes it
+from the other keys. The tickets that clients present are also marked with
+a key version number and encryption type
+to tell the server process which key to use to
+decrypt it. The F<KeyFileExt> file must always include a key with the same
+key version number and encryption type
+and contents as the key currently listed for the
+C<afs/I<cell>> principal in the associated Kerberos v5 realm.
+(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.)
+Keys in the F<KeyFile> must be DES keys; keys of stronger
+encryption types (such as those used by the rxkad-k5 extension) are
+contained in the F<KeyFileExt>.
+
+The F<KeyFileExt> file is in binary format, so always use the
+B<asetkey> command to administer it:
+
+=over 4
+
+=item *
+
+The B<asetkey add> command to add a new key.
+
+=item *
+
+The B<asetkey list> command to display the keys.
+
+=item *
+
+The B<asetkey delete> command to remove a key from the file.
+
+=back
+
+The B<asetkey> commands must be run on the same server as the F<KeyFileExt>
+file to update. Normally, new
+keys should be added from a Kerberos v5 keytab using B<asetkey add>.
+
+The file should be edited on each server machine.
+
+=head1 CAUTIONS
+
+The most common error caused by changes to F<KeyFileExt> 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. Using L<asetkey(8)>
+to add rxkad-k5 keys to the F<KeyFileExt> also requires specifying a krb5
+encryption type number. Since the encryption type must be specified
+by its number (not a symbolic or string name), care must be taken to
+determine the correct encryption type to add.
+
+=head1 SEE ALSO
+
+L<KeyFile(5)>,
+L<asetkey(8)>,
+
+The I<OpenAFS Administration Guide> at
+L<http://docs.openafs.org/AdminGuide/>.
+
+=head1 COPYRIGHT
+
+IBM Corporation, 2000. <http://www.ibm.com/> All Rights Reserved.
+Massachusetts Institute of Technology, 2015.
=item L<KeyFile(5)>
+=item L<KeyFileExt(5)>
+
=item L<UserList(5)>
=back
=head1 NAME
-asetkey - Add a key from a keytab to an AFS KeyFile
+asetkey - Add a key from a keytab to an AFS KeyFile or KeyFileExt
=head1 SYNOPSIS
The B<asetkey> command is used to add a key to an AFS KeyFile or KeyFileExt
from a Kerberos keytab. It is similar to B<bos addkey> except that it must be
-run locally on the system where the KeyFile is located and it takes the
-new key from the command line or a Kerberos 5 keytab rather than prompting
+run locally on the system where the KeyFile or KeyFileExt is located
+and it takes the new key from a Kerberos 5 keytab rather than prompting
for the password.
B<asetkey delete> can be used to delete a key (similar to B<bos
=item B<-localauth>
Constructs a server ticket using the server encryption key with the
-highest key version number in the local F</usr/afs/etc/KeyFile> file. The
+highest key version number in the local F</usr/afs/etc/KeyFile>
+or F</usr/afs/etc/KeyFileExt> file. The
B<backup> command interpreter presents the ticket, which never expires, to
the Backup Server, Volume Server and Volume Location (VL) Server during
mutual authentication.
Use this flag only when issuing a command on a server machine; client
-machines do not usually have a F</usr/afs/etc/KeyFile> file. The issuer
+machines do not usually have a F</usr/afs/etc/KeyFile> or
+F</usr/afs/etc/KeyFileExt> file. The issuer
of a command that includes this flag must be logged on to the server
machine as the local superuser C<root>. The flag is useful for commands
invoked by an unattended application program, such as a process controlled
L<BosConfig(5)>,
L<CellServDB(5)>,
L<KeyFile(5)>,
+L<KeyFileExt(5)>,
L<ThisCell(5)>,
L<UserList(5)>,
L<butc(5)>,
=item *
+The F</usr/afs/etc/KeyFileExt> file lists additional server encryption
+keys that the server processes can use to decrypt tickets presented by
+client processes and one another. These keys are strong encryption
+keys used by the rxkad-k5 extension; use L<asetkey(8)> to manage the
+F<KeyFileExt>.
+
+=item *
+
The F</usr/afs/etc/ThisCell> file defines the cell to which the server
machine belongs for the purposes of server-to-server communication.
Administer it with the B<bos setcellname> command. There is also a
=item B<-localauth>
Constructs a server ticket using the server encryption key with the
-highest key version number in the local F</usr/afs/etc/KeyFile> file. The
+highest key version number in the local F</usr/afs/etc/KeyFile> or
+F</usr/afs/etc/KeyFileExt> file. The
B<bos> command interpreter presents the ticket, which never expires, to
the BOS Server during mutual authentication.
Use this flag only when issuing a command on a server machine; client
-machines do not usually have a F</usr/afs/etc/KeyFile> file. The issuer
+machines do not usually have a F</usr/afs/etc/KeyFile> or
+F</usr/afs/etc/KeyFileExt> file. The issuer
of a command that includes this flag must be logged on to the server
machine as the local superuser C<root>. The flag is useful for commands
invoked by an unattended application program, such as a process controlled
L<BosConfig(5)>,
L<CellServDB(5)>,
L<KeyFile(5)>,
+L<KeyFileExt(5)>,
L<ThisCell(5)>,
L<UserList(5)>,
L<bos_addhost(8)>,
=item B<-localauth>
Constructs a server ticket using a key from the local
-F</usr/afs/etc/KeyFile> file. The B<bos> command interpreter presents the
+F</usr/afs/etc/KeyFile> or F</usr/afs/etc/KeyFileExt> file.
+The B<bos> command interpreter presents the
ticket to the BOS Server during mutual authentication. Do not combine this
flag with the B<-cell> or B<-noauth> options. For more details, see
L<bos(8)>.
L<CellServDB(5)>,
L<KeyFile(5)>,
+L<KeyFileExt(5)>,
L<UserList(5)>,
L<bos(8)>,
L<bos_listhosts(8)>,
key generated by B<bos addkey> will not match the key generated by the
Kerberos v5 KDC.
+This command can only add keys to the F<KeyFile>; these keys must
+be DES keys. The stronger keys used by the rxkad-k5 extension are
+stored in the F<KeyFileExt>, which is not supported by this command.
+
+As such, the use of this command is disrecommended; use
+L<asetkey(8)> instead to benefit from the increased security
+of the rxkad-k5 extension.
+
=head1 OPTIONS
=over 4
=item B<-localauth>
Constructs a server ticket using a key from the local
-F</usr/afs/etc/KeyFile> file. The B<bos> command interpreter presents the
+F</usr/afs/etc/KeyFile> or F</usr/afs/etc/KeyFileExt> file.
+The B<bos> command interpreter presents the
ticket to the BOS Server during mutual authentication. Do not combine this
flag with the B<-cell> or B<-noauth> options. For more details, see
L<bos(8)>.
=head1 SEE ALSO
L<KeyFile(5)>,
+L<KeyFileExt(5)>,
L<UserList(5)>,
L<asetkey(8)>,
L<bos(8)>,
=item B<-localauth>
Constructs a server ticket using a key from the local
-F</usr/afs/etc/KeyFile> file. The B<bos> command interpreter presents the
+F</usr/afs/etc/KeyFile> or F</usr/afs/etc/KeyFileExt> file.
+The B<bos> command interpreter presents the
ticket to the BOS Server during mutual authentication. Do not combine this
flag with the B<-cell> or B<-noauth> options. For more details, see
L<bos(8)>.
=head1 SEE ALSO
L<KeyFile(5)>,
+L<KeyFileExt(5)>,
L<UserList(5)>,
L<bos(8)>,
L<bos_listusers(8)>,
=item B<-localauth>
Constructs a server ticket using a key from the local
-F</usr/afs/etc/KeyFile> file. The B<bos> command interpreter presents the
+F</usr/afs/etc/KeyFile> or F</usr/afs/etc/KeyFileExt> file.
+The B<bos> command interpreter presents the
ticket to the BOS Server during mutual authentication. Do not combine this
flag with the B<-cell> or B<-noauth> options. For more details, see
L<bos(8)>.
L<BosConfig(5)>,
L<KeyFile(5)>,
+L<KeyFileExt(5)>,
L<UserList(5)>,
L<bos(8)>,
L<buserver(8)>,
=item B<-localauth>
Constructs a server ticket using a key from the local
-F</usr/afs/etc/KeyFile> file. The B<bos> command interpreter presents the
+F</usr/afs/etc/KeyFile> or F</usr/afs/etc/KeyFileExt> file.
+The B<bos> command interpreter presents the
ticket to the BOS Server during mutual authentication. Do not combine this
flag with the B<-cell> or B<-noauth> options. For more details, see
L<bos(8)>.
L<BosConfig(5)>,
L<KeyFile(5)>,
+L<KeyFileExt(5)>,
L<UserList(5)>,
L<bos(8)>,
L<bos_create(8)>,
=item B<-localauth>
Constructs a server ticket using a key from the local
-F</usr/afs/etc/KeyFile> file. The B<bos> command interpreter presents the
+F</usr/afs/etc/KeyFile> or F</usr/afs/etc/KeyFileExt> file.
+The B<bos> command interpreter presents the
ticket to the BOS Server during mutual authentication. Do not combine this
flag with the B<-cell> or B<-noauth> options. For more details, see
L<bos(8)>.
=head1 SEE ALSO
L<KeyFile(5)>,
+L<KeyFileExt(5)>,
L<bos(8)>,
L<bos_install(8)>,
L<bos_prune(8)>,
=item B<-localauth>
Constructs a server ticket using a key from the local
-F</usr/afs/etc/KeyFile> file. The B<bos> command interpreter presents the
+F</usr/afs/etc/KeyFile> or F</usr/afs/etc/KeyFileExt> file.
+The B<bos> command interpreter presents the
ticket to the BOS Server during mutual authentication. Do not combine this
flag with the B<-cell> or B<-noauth> options. For more details, see
L<bos(8)>.
L<BosConfig(5)>,
L<KeyFile(5)>,
+L<KeyFileExt(5)>,
L<bos(8)>,
L<bos_getdate(8)>,
L<bos_setrestart(8)>,
=item B<-localauth>
Constructs a server ticket using a key from the local
-F</usr/afs/etc/KeyFile> file. The B<bos> command interpreter presents the
+F</usr/afs/etc/KeyFile> or F</usr/afs/etc/KeyFileExt> file.
+The B<bos> command interpreter presents the
ticket to the BOS Server during mutual authentication. Do not combine this
flag with the B<-cell> or B<-noauth> options. For more details, see
L<bos(8)>.
L<BosConfig(5)>,
L<KeyFile(5)>,
+L<KeyFileExt(5)>,
L<UserList(5)>,
L<bos(8)>,
L<bos_getdate(8)>,
=item B<-localauth>
Constructs a server ticket using a key from the local
-F</usr/afs/etc/KeyFile> file. The B<bos> command interpreter presents the
+F</usr/afs/etc/KeyFile> or F</usr/afs/etc/KeyFileExt> file.
+The B<bos> command interpreter presents the
ticket to the BOS Server during mutual authentication. Do not combine this
flag with the B<-cell> or B<-noauth> options. For more details, see
L<bos(8)>.
L<CellServDB(5)>,
L<KeyFile(5)>,
+L<KeyFileExt(5)>,
L<bos(8)>,
L<bos_addhost(8)>,
L<bos_removehost(8)>
B<-showkey> flag) is a security exposure. Displaying a checksum is
sufficient for most purposes.
+This command will only list keys in the F<KeyFile>; it cannot display
+keys from a F<KeyFileExt>. A server running a modern, secure installation
+using only keys for the rxkad-k5 extension will yield no keys in
+the output of this command.
+
=head1 OPTIONS
=over 4
=item B<-localauth>
Constructs a server ticket using a key from the local
-F</usr/afs/etc/KeyFile> file. The B<bos> command interpreter presents the
+F</usr/afs/etc/KeyFile> or F</usr/afs/etc/KeyFileExt> file.
+The B<bos> command interpreter presents the
ticket to the BOS Server during mutual authentication. Do not combine this
flag with the B<-cell> or B<-noauth> options. For more details, see
L<bos(8)>.
=head1 SEE ALSO
L<KeyFile(5)>,
+L<KeyFileExt(5)>,
L<UserList(5)>,
L<asetkey(8)>,
L<bos_addkey(8)>,
=item B<-localauth>
Constructs a server ticket using a key from the local
-F</usr/afs/etc/KeyFile> file. The B<bos> command interpreter presents the
+F</usr/afs/etc/KeyFile> or F</usr/afs/etc/KeyFileExt> file.
+The B<bos> command interpreter presents the
ticket to the BOS Server during mutual authentication. Do not combine this
flag with the B<-cell> or B<-noauth> options. For more details, see
L<bos(8)>.
=head1 SEE ALSO
L<KeyFile(5)>,
+L<KeyFileExt(5)>,
L<UserList(5)>,
L<bos(8)>,
L<bos_adduser(8)>,
=item B<-localauth>
Constructs a server ticket using a key from the local
-F</usr/afs/etc/KeyFile> file. The B<bos> command interpreter presents the
+F</usr/afs/etc/KeyFile> or F</usr/afs/etc/KeyFileExt> file.
+The B<bos> command interpreter presents the
ticket to the BOS Server during mutual authentication. Do not combine this
flag with the B<-cell> or B<-noauth> options. For more details, see
L<bos(8)>.
=head1 SEE ALSO
L<KeyFile(5)>,
+L<KeyFileExt(5)>,
L<UserList(5)>,
L<bos(8)>,
L<bos_getdate(8)>
=item B<-localauth>
Constructs a server ticket using a key from the local
-F</usr/afs/etc/KeyFile> file. The B<bos> command interpreter presents the
+F</usr/afs/etc/KeyFile> or F</usr/afs/etc/KeyFileExt> file.
+The B<bos> command interpreter presents the
ticket to the BOS Server during mutual authentication. Do not combine this
flag with the B<-cell> or B<-noauth> options. For more details, see
L<bos(8)>.
=head1 SEE ALSO
L<KeyFile(5)>,
+L<KeyFileExt(5)>,
L<UserList(5)>,
L<bos(8)>,
L<bos_addhost(8)>,
setpassword> and B<bos addkey> commands. This ensures that no clients
still possess tickets encrypted with the obsolete key.
+This command can only remove keys from the F</usr/afs/etc/KeyFile> file;
+the F</usr/afs/etc/KeyFileExt> cannot be modified by this command.
+
=head1 OPTIONS
=over 4
=item B<-localauth>
Constructs a server ticket using a key from the local
-F</usr/afs/etc/KeyFile> file. The B<bos> command interpreter presents the
+F</usr/afs/etc/KeyFile> or F</usr/afs/etc/KeyFileExt> file.
+The B<bos> command interpreter presents the
ticket to the BOS Server during mutual authentication. Do not combine this
flag with the B<-cell> or B<-noauth> options. For more details, see
L<bos(8)>.
=head1 SEE ALSO
L<KeyFile(5)>,
+L<KeyFileExt(5)>,
L<UserList(5)>,
L<bos(8)>,
L<bos_addkey(8)>,
=item B<-localauth>
Constructs a server ticket using a key from the local
-F</usr/afs/etc/KeyFile> file. The B<bos> command interpreter presents the
+F</usr/afs/etc/KeyFile> or F</usr/afs/etc/KeyFileExt> file.
+The B<bos> command interpreter presents the
ticket to the BOS Server during mutual authentication. Do not combine this
flag with the B<-cell> or B<-noauth> options. For more details, see
L<bos(8)>.
=head1 SEE ALSO
L<KeyFile(5)>,
+L<KeyFileExt(5)>,
L<UserList(5)>,
L<bos(8)>,
L<bos_addkey(8)>,
=item B<-localauth>
Constructs a server ticket using a key from the local
-F</usr/afs/etc/KeyFile> file. The B<bos> command interpreter presents the
+F</usr/afs/etc/KeyFile> or F</usr/afs/etc/KeyFileExt> file.
+The B<bos> command interpreter presents the
ticket to the BOS Server during mutual authentication. Do not combine this
flag with the B<-cell> or B<-noauth> options. For more details, see
L<bos(8)>.
L<BosConfig(5)>,
L<KeyFile(5)>,
+L<KeyFileExt(5)>,
L<UserList(5)>,
L<bos(8)>,
L<bos_create(8)>,
=item B<-localauth>
Constructs a server ticket using a key from the local
-F</usr/afs/etc/KeyFile> file. The B<bos> command interpreter presents the
+F</usr/afs/etc/KeyFile> or F</usr/afs/etc/KeyFileExt> file.
+The B<bos> command interpreter presents the
ticket to the BOS Server during mutual authentication. Do not combine this
flag with the B<-cell> or B<-noauth> options. For more details, see
L<bos(8)>.
=head1 SEE ALSO
L<KeyFile(5)>,
+L<KeyFileExt(5)>,
L<SalvageLog(5)>,
L<UserList(5)>,
L<bos(8)>,
=item B<-localauth>
Constructs a server ticket using a key from the local
-F</usr/afs/etc/KeyFile> file. The B<bos> command interpreter presents the
+F</usr/afs/etc/KeyFile> or F</usr/afs/etc/KeyFileExt> file.
+The B<bos> command interpreter presents the
ticket to the BOS Server during mutual authentication. Do not combine this
flag with the B<-cell> or B<-noauth> options. For more details, see
L<bos(8)>.
=head1 SEE ALSO
L<KeyFile(5)>,
+L<KeyFileExt(5)>,
L<NoAuth(5)>,
L<UserList(5)>,
L<bos(8)>,
=item B<-localauth>
Constructs a server ticket using a key from the local
-F</usr/afs/etc/KeyFile> file. The B<bos> command interpreter presents the
+F</usr/afs/etc/KeyFile> or F</usr/afs/etc/KeyFileExt> file.
+The B<bos> command interpreter presents the
ticket to the BOS Server during mutual authentication. Do not combine this
flag with the B<-cell> or B<-noauth> options. For more details, see
L<bos(8)>.
L<CellServDB(5)>,
L<KeyFile(5)>,
+L<KeyFileExt(5)>,
L<ThisCell(5)>,
L<UserList(5)>,
L<bos(8)>
=item B<-localauth>
Constructs a server ticket using a key from the local
-F</usr/afs/etc/KeyFile> file. The B<bos> command interpreter presents the
+F</usr/afs/etc/KeyFile> or F</usr/afs/etc/KeyFileExt> file.
+The B<bos> command interpreter presents the
ticket to the BOS Server during mutual authentication. Do not combine this
flag with the B<-cell> or B<-noauth> options. For more details, see
L<bos(8)>.
L<BosConfig(5)>,
L<KeyFile(5)>,
+L<KeyFileExt(5)>,
L<UserList(5)>,
L<bos(8)>,
L<bos_getrestart(8)>,
=item B<-localauth>
Constructs a server ticket using a key from the local
-F</usr/afs/etc/KeyFile> file. The B<bos> command interpreter presents the
+F</usr/afs/etc/KeyFile> or F</usr/afs/etc/KeyFileExt> file.
+The B<bos> command interpreter presents the
ticket to the BOS Server during mutual authentication. Do not combine this
flag with the B<-cell> or B<-noauth> options. For more details, see
L<bos(8)>.
L<BosConfig(5)>,
L<KeyFile(5)>,
+L<KeyFileExt(5)>,
L<UserList(5)>,
L<bos(8)>,
L<bos_create(8)>,
=item B<-localauth>
Constructs a server ticket using a key from the local
-F</usr/afs/etc/KeyFile> file. The B<bos> command interpreter presents the
+F</usr/afs/etc/KeyFile> or F</usr/afs/etc/KeyFileExt> file.
+The B<bos> command interpreter presents the
ticket to the BOS Server during mutual authentication. Do not combine this
flag with the B<-cell> or B<-noauth> options. For more details, see
L<bos(8)>.
L<BosConfig(5)>,
L<KeyFile(5)>,
+L<KeyFileExt(5)>,
L<UserList(5)>,
L<bos(8)>,
L<bos_create(8)>,
=item B<-localauth>
Constructs a server ticket using a key from the local
-F</usr/afs/etc/KeyFile> file. The B<bos> command interpreter presents the
+F</usr/afs/etc/KeyFile> or F</usr/afs/etc/KeyFileExt> file.
+The B<bos> command interpreter presents the
ticket to the BOS Server during mutual authentication. Do not combine this
flag with the B<-cell> or B<-noauth> options. For more details, see
L<bos(8)>.
L<BosConfig(5)>,
L<KeyFile(5)>,
+L<KeyFileExt(5)>,
L<UserList(5)>,
L<bos(8)>,
L<bos_create(8)>,
=item B<-localauth>
Constructs a server ticket using a key from the local
-F</usr/afs/etc/KeyFile> file. The B<bos> command
+F</usr/afs/etc/KeyFile> or F</usr/afs/etc/KeyFileExt> file. The B<bos> command
interpreter presents the ticket to the BOS Server during mutual
authentication. Do not combine this flag with the B<-cell> or
B<-noauth> options. For more details, see L<bos(8)>.
L<BosConfig(5)>,
L<KeyFile(5)>,
+L<KeyFileExt(5)>,
L<bos(8)>,
L<bos_create(8)>,
L<bos_shutdown(8)>,
=item B<-localauth>
Constructs a server ticket using a key from the local
-F</usr/afs/etc/KeyFile> file. The B<bos> command interpreter presents the
+F</usr/afs/etc/KeyFile> or F</usr/afs/etc/KeyFileExt> file.
+The B<bos> command interpreter presents the
ticket to the BOS Server during mutual authentication. Do not combine this
flag with the B<-cell> or B<-noauth> options. For more details, see
L<bos(8)>.
L<BosConfig(5)>,
L<KeyFile(5)>,
+L<KeyFileExt(5)>,
L<UserList(5)>,
L<bos(8)>,
L<bos_create(8)>,
=item B<-localauth>
Constructs a server ticket using a key from the local
-F</usr/afs/etc/KeyFile> file. The B<bos> command interpreter presents the
+F</usr/afs/etc/KeyFile> or F</usr/afs/etc/KeyFileExt> file.
+The B<bos> command interpreter presents the
ticket to the BOS Server during mutual authentication. Do not combine this
flag with the B<-cell> or B<-noauth> options. For more details, see
L<bos(8)>.
L<BosConfig(5)>,
L<KeyFile(5)>,
+L<KeyFileExt(5)>,
L<UserList(5)>,
L<bos(8)>,
L<bos_getrestart(8)>,
=item B<-localauth>
Constructs a server ticket using the server encryption key with the
-highest key version number in the local F</usr/afs/etc/KeyFile>. The
+highest key version number in the local F</usr/afs/etc/KeyFile> or
+F</usr/afs/etc/KeyFileExt>. The
B<butc> command interpreter presents the ticket, which never expires, to
the Volume Server and Volume Location Server to use in mutual
authentication.
Do not combine this argument with the B<-cell> flag, and use it only when
logged on to a server machine as the local superuser C<root>; client
-machines do not have F</usr/afs/etc/KeyFile> file.
+machines do not have F</usr/afs/etc/KeyFile> or F</usr/afs/etc/KeyFileExt>
+files.
=item B<-help>
=head1 SEE ALSO
L<KeyFile(5)>,
+L<KeyFileExt(5)>,
L<ThisCell(5)>,
L<UserList(5)>,
L<butc(5)>,
git://git.openafs.org / openafs.git / commitdiff