NAME

       asetkey - Add a key from a keytab to an AFS KeyFile

SYNOPSIS

       asetkey add <kvno> <keyfile> <principal>

       asetkey add <kvno> <key>

       asetkey delete <kvno>

       asetkey list

DESCRIPTION

       The asetkey command is used to add a key to an AFS KeyFile from a Kerberos keytab.  It is
       similar to 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 for the password.

       asetkey delete can be used to delete a key (similar to bos removekeys), and asetkey list
       will list the keys in a KeyFile (similar to bos listkeys).

       asetkey is used when authentication for an AFS cell is provided by a Kerberos 5 KDC rather
       than kaserver.  The key for the "afs" or "afs/cell name" principal in the Kerberos 5 KDC
       must match the key stored in the AFS KeyFile on all AFS database servers and file servers.
       This is done by creating a keytab containing that key using the standard Kerberos commands
       (generally the "ktadd" function of the kadmin command) and then, on each AFS database
       server and file server, adding that key to the KeyFile with asetkey add.  The kvno chosen
       should match the kvno in the Kerberos KDC (checked with kvno or the "getprinc" function of
       kadmin).  principal should be the name of the AFS principal in the keytab, which must be
       either "afs" or "afs/cell name". asetkey can also be used to install a key from a hex
       string.

       In cells that use the Update Server to distribute the contents of the /etc/openafs/server
       directory, it is conventional to run asetkey add only on the control machine and then let
       the Update Server propagate the new KeyFile to all other systems.

CAUTIONS

       AFS currently only supports des-cbc-crc:v4 Kerberos keys.  Make sure, when creating the
       keytab with "ktadd", you pass "-e des-cbc-crc:v4" to force the encryption type.
       Otherwise, AFS authentication may not work.

       As soon as a new keytab is created with "ktadd", new AFS service tickets will use the new
       key.  However, tokens formed from those service tickets will only work if the new key is
       present in the KeyFile on the AFS file server.  There is therefore an outage window
       between when the new keytab is created and when the key had been added to the KeyFile of
       all AFS servers with asetkey, during which newly obtained AFS tokens will not work
       properly.

       All of the KeyFile entries must match the key in the Kerberos KDC, but each time "ktadd"
       is run, it creates a new key.  Either the Update Server must be used to distribute the
       KeyFile to all servers or the same keytab must be used with asetkey on each server.

EXAMPLES

       The following commands create a new keytab for the principal "afs" and then import the key
       into the KeyFile.  Note the kvno in the output from "ktadd".

           % kadmin
           Authenticating as principal rra/admin@stanford.edu with password.
           Password for rra/admin@stanford.edu:
           kadmin:  ktadd -k /tmp/afs.keytab -e des-cbc-crc:v4 afs
           Entry for principal afs with kvno 3, encryption type DES cbc mode
           with CRC-32 added to keytab WRFILE:/tmp/afs.keytab.
           kadmin:  exit
           % asetkey add 3 /tmp/afs.keytab afs

       You may want to use "afs/cell name" instead of "afs", particularly if you may have
       multiple AFS cells for a single Kerberos realm.

       In the event you have been distributed a key by a Kerberos administrator in the form of a
       hex string, you may use asetkey to install that.

           % asetkey add 3 80b6a7cd7a9dadb6

       key should be an 8 byte hex representation.

PRIVILEGE REQUIRED

       The issuer must be able to read (for asetkey list) and write (for asetkey add and asetkey
       delete) the KeyFile, normally /etc/openafs/server/KeyFile.  In practice, this means that
       the issuer must be the local superuser "root" on the AFS file server or database server.
       For asetkey add, the issuer must also be able to read the specified keytab file.

SEE ALSO

       KeyFile(5), bos_addkey(8), bos_listkeys(8), bos_removekey(8), kadmin(8), kvno(1)

COPYRIGHT

       Copyright 2006 Russ Allbery <rra@stanford.edu>

       This documentation is covered by the IBM Public License Version 1.0.  This man page was
       written by Russ Allbery for OpenAFS.