asetkey - Add a key from a keytab to an AFS KeyFileExt
asetkey [-config <configuration file>] add <kvno> <keyfile> <principal>
asetkey [-config <configuration file>] add <kvno> <key>
asetkey [-config <configuration file>] add <type> <kvno> <subtype> <key>
asetkey [-config <configuration file>] add <type> <kvno> <subtype> <keyfile> <princ>
asetkey [-config <configuration file>] add yfs-rxgk <kvno> <subtype> random
asetkey [-config <configuration file>] add-acceptor <type> <kvno> <subtype> <key>
asetkey [-config <configuration file>] add-acceptor <type> <kvno> <subtype> <keyfile> <princ>
asetkey [-config <configuration file>] add-acceptor yfs-rxgk <kvno> <subtype> random
asetkey [-config <configuration file>] delete <kvno>
asetkey [-config <configuration file>] delete <type> <kvno>
asetkey [-config <configuration file>] delete <type> <kvno> <subtype>
asetkey [-config <configuration file>] list
asetkey [-config <configuration file>] listkeys
asetkey [-config <configuration file>] promote-acceptor <kvno>
asetkey [-config <configuration file>] promote-acceptor <type> <kvno>
asetkey [-config <configuration file>] demote-to-acceptor <kvno>
asetkey [-config <configuration file>] demote-to-acceptor <type> <kvno>
The asetkey command is used to add a key to an Auristor KeyFileExt(5) from a Kerberos keytab. It is similar to bos addkey except that it must be run locally on the system where the KeyFileExt(5) 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), asetkey list lists the keys in a KeyFileExt(5) without disclosing their key material, and asetkey listkeys displays the hexadecimal values of all keys in the file (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 KeyFileExt(5) 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(5) 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/yfs/server directory, it is conventional to run asetkey add only on the control machine and then let the Update Server propagate the new KeyFileExt(5) to all other systems.
The asetkey add-acceptor and asetkey promote-acceptor commands may be used to achieve clean propagation of new server keys. A key which is added with asetkey add-acceptor will ony be used by servers to accept connections, and not when initiating new ones. A KeyFileExt(5) containing an acceptor only key can be propagated to all servers without requiring a flag day. Once the key is present on all servers, the key may then be promoted using asetkey promote-acceptor so it can be used for both client and server connections. That KeyFileExt(5) can then be propagated out to complete the key replacement process.
The asetkey demote-to-acceptor command can be used to prevent an existing deployed key from being used when initiating new connections. Demoting a key can be used to prevent the use of a weaker encryption type or as a pre-cursor to removing the key from the KeyFileExt(5).
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(5) 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(5) of all AFS servers with asetkey,
during which newly obtained AFS tokens will not work properly.
All of the KeyFileExt(5) entries must match the key in the Kerberos KDC,
but each time ktadd is run,
it creates a new key.
Either the Update Server or some other mechanism must be used to distribute the KeyFileExt(5) to all servers,
or the same keytab must be used with asetkey on each server.
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(5).
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
In order to import all of the encryption types for a particular principal and kvno, a subtype of "all" may be specified.
% asetkey add rxkad_krb5 4 all /tmp/afs.keytab afs/disarray.mit.edu
In a cell which is <not> using the rxkad-k5 extension, the following commands create a new keytab for the principal afs and then import the key into the KeyFileExt(5). 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.
In a cell that supports yfs-rxgk, the following command creates the KeyFileExt(5) and KeyFileExt(5) files containing a new random key of the specified encryption type and with the specified key version number. It is not possible to specify a key value for yfs-rxgk; random is the only valid value for that parameter. The encryption type can be specified as a string recognized by the krb5 libraries or as a numeric value.
% asetkey add yfs-rxgk 4 aes256-cts-hmac-sha1-96 random
The issuer must be able to read (for asetkey list and asetkey listkeys) and write (for asetkey add and asetkey delete) the KeyFileExt(5), normally /etc/yfs/server/KeyFileExt. On supported platforms, this is the yfsserver account; although it might be the local superuser root account. For asetkey add and asetkey add-acceptor, the issuer must also be able to read the specified keytab file.
KeyFileExt(5), auristorfs_key_rotation(7), bos_addkey(8), bos_listkeys(8), bos_removekey(8), kadmin(8), kvno(1)
Copyright 2006 Russ Allbery <rra@stanford.edu>
Copyright 2018-2021 AuriStor, Inc. https://www.auristor.com/
This documentation is covered by the IBM Public License Version 1.0. This man page was originally written by Russ Allbery for OpenAFS.
"AFS" is a registered mark of International Business Machines Corporation, used under license. (USPTO Registration 1598389)
"OpenAFS" is a registered mark of International Business Machines Corporation. (USPTO Registration 4577045)
The "AuriStor" name, log 'S' brand mark, and icon are registered marks of AuriStor, Inc. (USPTO Registrations 4849419, 4849421, and 4928460) (EUIPO Registration 015539653).
"Your File System" is a registered mark of AuriStor, Inc. (USPTO Registrations 4801402 and 4849418).
"YFS" and "AuriStor File System" are trademarks of AuriStor, Inc.