3 asetkey - Add a key from a keytab to an AFS KeyFile or KeyFileExt
10 B<asetkey> add <I<kvno>> <I<keyfile>> <I<principal>>
12 B<asetkey> add <I<kvno>> <I<key>>
14 B<asetkey> add <I<type>> <I<kvno>> <I<subtype>> <I<key>>
16 B<asetkey> add <I<type>> <I<kvno>> <I<subtype>> <I<keyfile>> <I<princ>>
18 B<asetkey> delete <I<kvno>>
20 B<asetkey> delete <I<type>> <I<kvno>>
22 B<asetkey> delete <I<type>> <I<kvno>> <I<subtype>>
31 The B<asetkey> command is used to add a key to an AFS KeyFile or KeyFileExt
32 from a Kerberos keytab. It is similar to B<bos addkey> except that it must be
33 run locally on the system where the KeyFile or KeyFileExt is located
34 and it takes the new key from a Kerberos 5 keytab rather than prompting
37 B<asetkey delete> can be used to delete a key (similar to B<bos
38 removekeys>), and B<asetkey list> will list the keys in a KeyFile
39 and the keys in a KeyFileExt (similar to B<bos listkeys>, but more
40 fully featured, since B<bos listkeys> cannot list the contents of
43 B<asetkey> is used when authentication for an AFS cell is provided by a
44 Kerberos 5 KDC rather than the deprecated B<kaserver>.
45 The key for the C<afs> or
46 C<afs/I<cell name>> principal in the Kerberos 5 KDC must match the key
47 stored in the AFS KeyFileExt on all AFS database servers and file servers.
48 This is done by creating a keytab containing that key using the standard
49 Kerberos commands (generally the C<ktadd> function of the B<kadmin>
50 command) and then, on each AFS database server and file server, adding
51 that key to the KeyFileExt with B<asetkey add>. The I<kvno> chosen should
52 match the kvno in the Kerberos KDC (checked with B<kvno> or the
53 C<getprinc> function of B<kadmin>). I<principal> should be the name of
54 the AFS principal in the keytab, which must be either C<afs> or
59 Historically, AFS only supported des-cbc-crc:v4 Kerberos keys. In environments
60 which have not been upgraded to use the rxkad-k5 extension, when
61 creating the keytab with C<ktadd>, you must pass C<-e des-cbc-crc:v4> to force
62 the encryption type. Otherwise, AFS authentication may not work.
64 As soon as a new keytab is created with C<ktadd>, new AFS service tickets
65 will use the new key. However, tokens formed from those service tickets
66 will only work if the new key is present in the KeyFileExt on the AFS file
67 server. There is therefore an outage window between when the new keytab
68 is created and when the key had been added to the KeyFileExt of all AFS
69 servers with B<asetkey>, during which newly obtained AFS tokens will not
72 All of the KeyFileExt entries must match the key in the Kerberos KDC, but
73 each time C<ktadd> is run, it creates a new key. Some secure mechanism
74 must be used to distribute the KeyFileExt to all servers,
75 or the same keytab must be used with B<asetkey> on each server.
79 In a cell which is using the rxkad-k5 extension, the following commands
80 create a new keytab for the principal C<afs/I<cell name>> and then import
81 its keys into the KeyFileExt. Note the kvno in the output from C<ktadd>.
82 The values 18, 17, and 16 are the assigned numbers corresponding to the
83 kerberos enctypes in the keytab. These numbers can be determined from your
84 system's krb5 headers.
87 Authenticating as principal kaduk/admin@ZONE.MIT.EDU with password.
88 Password for kaduk/admin@ZONE.MIT.EDU:
89 kadmin: ktadd -k /tmp/afs.keytab afs/disarray.mit.edu
90 Entry for principal afs/disarray.mit.edu with kvno 4, encryption type
91 aes256-cts-hmac-sha1-96 added to keytab WRFILE:/tmp/afs.keytab.
92 Entry for principal afs/disarray.mit.edu with kvno 4, encryption type
93 aes128-cts-hmac-sha1-96 added to keytab WRFILE:/tmp/afs.keytab.
94 Entry for principal afs/disarray.mit.edu with kvno 4, encryption type
95 des3-cbc-sha1 added to keytab WRFILE:/tmp/afs.keytab.
97 % asetkey add rxkad_krb5 4 18 /tmp/afs.keytab afs/disarray.mit.edu
98 % asetkey add rxkad_krb5 4 17 /tmp/afs.keytab afs/disarray.mit.edu
99 % asetkey add rxkad_krb5 4 16 /tmp/afs.keytab afs/disarray.mit.edu
101 =head1 PRIVILEGE REQUIRED
103 The issuer must be able to read (for B<asetkey list>) and write (for
104 B<asetkey add> and B<asetkey delete>) the KeyFileExt, normally
105 F</usr/afs/etc/KeyFileExt>. In practice, this means that the issuer must be
106 the local superuser C<root> on the AFS file server or database server.
107 For B<asetkey add>, the issuer must also be able to read the specified
110 =head1 HISTORICAL COMPATIBILITY
112 A modern AFS cell should be using the rxkad-k5 extension, or risks
113 terribly insecure operation (complete cell compromise for $100 in
114 1 day). The keys used for rxkad-k5 operation are stored in the
115 KeyFileExt. Cells not using the rxkad-k5 extension (i.e., stock
116 rxkad) use keys of the des-cbc-crc encryption type, which are stored
119 B<asetkey> retains the functionality needed to support stock rxkad
120 operation, but its use is disrecommended. A bare 8-byte hex key
123 % asetkey add I<kvno> I<key>
125 I<key> should be an 8 byte hex representation. An example using
128 % asetkey add 3 80b6a7cd7a9dadb6
130 The following commands create a new keytab for the principal C<afs>
131 and then import the key into the KeyFile. Note the kvno in the
132 output from C<ktadd>.
135 Authenticating as principal rra/admin@stanford.edu with password.
136 Password for rra/admin@stanford.edu:
137 kadmin: ktadd -k /tmp/afs.keytab -e des-cbc-crc:v4 afs
138 Entry for principal afs with kvno 3, encryption type DES cbc mode
139 with CRC-32 added to keytab WRFILE:/tmp/afs.keytab.
141 % asetkey add 3 /tmp/afs.keytab afs
143 You may want to use C<afs/I<cell name>> instead of C<afs>, particularly if
144 you may have multiple AFS cells for a single Kerberos realm.
158 Copyright 2006 Russ Allbery <rra@stanford.edu>
159 Copyright 2013,2015 Massachusetts Institute of Technology
161 This documentation is covered by the IBM Public License Version 1.0. This
162 man page was written by Russ Allbery for OpenAFS and updated for the
163 rxkad-k5 extension by Benjamin Kaduk.