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