NAME

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

SYNOPSIS

       asetkey add <kvno> <keyfile> <principal>

       asetkey add <kvno> <key>

       asetkey add <type> <kvno> <subtype> <key>

       asetkey add <type> <kvno> <subtype> <keyfile> <princ>

       asetkey delete <kvno>

       asetkey delete <type> <kvno>

       asetkey delete <type> <kvno> <subtype>

       asetkey list

DESCRIPTION

       The asetkey command is used to add a key to an AFS KeyFile or KeyFileExt from a Kerberos
       keytab.  It is similar to bos addkey except that it must be 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.

       asetkey delete can be used to delete a key (similar to bos removekeys), and asetkey list
       will list the keys in a KeyFile and the keys in a KeyFileExt (similar to bos listkeys, but
       more fully featured, since bos listkeys cannot list the contents of a KeyFileExt).

       asetkey is used when authentication for an AFS cell is provided by a Kerberos 5 KDC rather
       than the deprecated kaserver.  The key for the "afs" or "afs/cell name" principal in the
       Kerberos 5 KDC must match the key stored in the AFS KeyFileExt 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 KeyFileExt 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".

CAUTIONS

       Historically, AFS only supported des-cbc-crc:v4 Kerberos keys.  In environments which have
       not been upgraded to use the rxkad-k5 extension, when creating the keytab with "ktadd",
       you must 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 KeyFileExt 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 KeyFileExt
       of all AFS servers with asetkey, during which newly obtained AFS tokens will not work
       properly.

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

EXAMPLES

       In a cell which is using the rxkad-k5 extension, the following commands create a new
       keytab for the principal "afs/cell name" and then import its keys into the KeyFileExt.
       Note the kvno in the output from "ktadd".  The values 18, 17, and 16 are the assigned
       numbers corresponding to the kerberos enctypes in the keytab.  These numbers can be
       determined from your system's krb5 headers.

           % kadmin
           Authenticating as principal kaduk/admin@ZONE.MIT.EDU with password.
           Password for kaduk/admin@ZONE.MIT.EDU:
           kadmin:  ktadd -k /tmp/afs.keytab afs/disarray.mit.edu
           Entry for principal afs/disarray.mit.edu with kvno 4, encryption type
           aes256-cts-hmac-sha1-96 added to keytab WRFILE:/tmp/afs.keytab.
           Entry for principal afs/disarray.mit.edu with kvno 4, encryption type
           aes128-cts-hmac-sha1-96 added to keytab WRFILE:/tmp/afs.keytab.
           Entry for principal afs/disarray.mit.edu with kvno 4, encryption type
           des3-cbc-sha1 added to keytab WRFILE:/tmp/afs.keytab.
           kadmin:  exit
           % asetkey add rxkad_krb5 4 18 /tmp/afs.keytab afs/disarray.mit.edu
           % asetkey add rxkad_krb5 4 17 /tmp/afs.keytab afs/disarray.mit.edu
           % asetkey add rxkad_krb5 4 16 /tmp/afs.keytab afs/disarray.mit.edu

PRIVILEGE REQUIRED

       The issuer must be able to read (for asetkey list) and write (for asetkey add and asetkey
       delete) the KeyFileExt, normally /etc/openafs/server/KeyFileExt.  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.

HISTORICAL COMPATIBILITY

       A modern AFS cell should be using the rxkad-k5 extension, or risks terribly insecure
       operation (complete cell compromise for $100 in 1 day).  The keys used for rxkad-k5
       operation are stored in the KeyFileExt.  Cells not using the rxkad-k5 extension (i.e.,
       stock rxkad) use keys of the des-cbc-crc encryption type, which are stored in the KeyFile.

       asetkey retains the functionality needed to support stock rxkad operation, but its use is
       disrecommended.  A bare 8-byte hex key can be added with

           % asetkey add I<kvno> I<key>

       key should be an 8 byte hex representation.  An example using a kvno of 3:

           % asetkey add 3 80b6a7cd7a9dadb6

       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.

SEE ALSO

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

COPYRIGHT

       Copyright 2006 Russ Allbery <rra@stanford.edu> Copyright 2013,2015 Massachusetts Institute
       of Technology

       This documentation is covered by the IBM Public License Version 1.0.  This man page was
       written by Russ Allbery for OpenAFS and updated for the rxkad-k5 extension by Benjamin
       Kaduk.