NAME

       KeyFile - Defines AFS server encryption keys

DESCRIPTION

       The KeyFile file defines 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 file. The file must reside in the /etc/openafs/server directory on every server machine.
       For more detailed information on mutual authentication and server encryption keys, see the 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 KeyFile file must always include a key with the same key version number and
       contents as the key currently listed for the "afs/cell" principal in the associated Kerberos v5 realm or
       Authentication Database. (The principal "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. "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 KeyFile file is in binary format, so always use either the asetkey command or the appropriate
       commands from the bos command suite to administer it:

       •   The asetkey add or bos addkey command to add a new key.

       •   The asetkey list or bos listkeys command to display the keys.

       •   The asetkey delete or bos removekey command to remove a key from the file.

       The  asetkey  commands must be run on the same server as the KeyFile file to update. The bos commands may
       be run remotely. Normally, new keys should be added from a Kerberos v5 keytab  using  asetkey  add.   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 /etc/openafs/server 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.

CAUTIONS

       The  most common error caused by changes to 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 "afs/cell" or "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 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 "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 asetkey.

SEE ALSO

       asetkey(8),    bos_addkey(8),   bos_listkeys(8),   bos_removekey(8),   kas_setpassword(8),   upclient(8),
       upserver(8)

       The OpenAFS Administration Guide at <http://docs.openafs.org/AdminGuide/>.

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.

OpenAFS                                            2024-08-27                                         KEYFILE(5)