doc/man-pages/pod8/asetkey.pod

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