doc/man-pages/pod8/asetkey.pod

   1 =head1 NAME
   2
   3 asetkey - Add a key from a keytab to an AFS KeyFile
   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 is located and it takes the
  30 new key from the command line or 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 (similar
  35 to B<bos listkeys>).
  36
  37 B<asetkey> is used when authentication for an AFS cell is provided by a
  38 Kerberos 5 KDC rather than B<kaserver>.  The key for the C<afs> or
  39 C<afs/I<cell name>> principal in the Kerberos 5 KDC must match the key
  40 stored in the AFS KeyFile on all AFS database servers and file servers.
  41 This is done by creating a keytab containing that key using the standard
  42 Kerberos commands (generally the C<ktadd> function of the B<kadmin>
  43 command) and then, on each AFS database server and file server, adding
  44 that key to the KeyFile with B<asetkey add>.  The I<kvno> chosen should
  45 match the kvno in the Kerberos KDC (checked with B<kvno> or the
  46 C<getprinc> function of B<kadmin>).  I<principal> should be the name of
  47 the AFS principal in the keytab, which must be either C<afs> or
  48 C<afs/I<cell name>>. B<asetkey> can also be used to install a key
  49 from a hex string.
  50
  51 In cells that use the Update Server to distribute the contents of the
  52 F</usr/afs/etc> directory, it is conventional to run B<asetkey add> only
  53 on the control machine and then let the Update Server propagate the new
  54 KeyFile to all other systems.
  55
  56 =head1 CAUTIONS
  57
  58 Historically, AFS only supported des-cbc-crc:v4 Kerberos keys.  In environments
  59 which have not been upgraded to use the rxkad-k5 extension, when
  60 creating the keytab with C<ktadd>, you must pass C<-e des-cbc-crc:v4> to force
  61 the encryption type.  Otherwise, AFS authentication may not work.
  62
  63 As soon as a new keytab is created with C<ktadd>, new AFS service tickets
  64 will use the new key.  However, tokens formed from those service tickets
  65 will only work if the new key is present in the KeyFile on the AFS file
  66 server.  There is therefore an outage window between when the new keytab
  67 is created and when the key had been added to the KeyFile of all AFS
  68 servers with B<asetkey>, during which newly obtained AFS tokens will not
  69 work properly.
  70
  71 All of the KeyFile entries must match the key in the Kerberos KDC, but
  72 each time C<ktadd> is run, it creates a new key.  Either the Update Server
  73 or some other mechanism must be used to distribute the KeyFile to all servers,
  74 or the same keytab must be used with B<asetkey> on each server.
  75
  76 =head1 EXAMPLES
  77
  78 In a cell which is using the rxkad-k5 extension, the following commands
  79 create a new keytab for the principal C<afs/I<cell name>> and then import
  80 its keys into the KeyFileExt.  Note the kvno in the output from C<ktadd>.
  81 The values 18, 17, and 16 are the assigned numbers corresponding to the
  82 kerberos enctypes in the keytab.  These numbers can be determined from your
  83 system's krb5 headers.
  84
  85     % kadmin
  86     Authenticating as principal kaduk/admin@ZONE.MIT.EDU with password.
  87     Password for kaduk/admin@ZONE.MIT.EDU:
  88     kadmin:  ktadd -k /tmp/afs.keytab afs/disarray.mit.edu
  89     Entry for principal afs/disarray.mit.edu with kvno 4, encryption type
  90     aes256-cts-hmac-sha1-96 added to keytab WRFILE:/tmp/afs.keytab.
  91     Entry for principal afs/disarray.mit.edu with kvno 4, encryption type
  92     aes128-cts-hmac-sha1-96 added to keytab WRFILE:/tmp/afs.keytab.
  93     Entry for principal afs/disarray.mit.edu with kvno 4, encryption type
  94     des3-cbc-sha1 added to keytab WRFILE:/tmp/afs.keytab.
  95     kadmin:  exit
  96     % asetkey add rxkad_krb5 4 18 /tmp/afs.keytab afs/disarray.mit.edu
  97     % asetkey add rxkad_krb5 4 17 /tmp/afs.keytab afs/disarray.mit.edu
  98     % asetkey add rxkad_krb5 4 16 /tmp/afs.keytab afs/disarray.mit.edu
  99
 100 In a cell which is <B<not>> using the rxkad-k5 extension, the following
 101 commands create a new keytab for the principal C<afs> and then import the
 102 key into the KeyFile.  Note the kvno in the output from C<ktadd>.
 103
 104     % kadmin
 105     Authenticating as principal rra/admin@stanford.edu with password.
 106     Password for rra/admin@stanford.edu:
 107     kadmin:  ktadd -k /tmp/afs.keytab -e des-cbc-crc:v4 afs
 108     Entry for principal afs with kvno 3, encryption type DES cbc mode
 109     with CRC-32 added to keytab WRFILE:/tmp/afs.keytab.
 110     kadmin:  exit
 111     % asetkey add 3 /tmp/afs.keytab afs
 112
 113 You may want to use C<afs/I<cell name>> instead of C<afs>, particularly if
 114 you may have multiple AFS cells for a single Kerberos realm.
 115
 116 In the event you have been distributed a key by a Kerberos administrator
 117 in the form of a hex string, you may use asetkey to install that.
 118
 119     % asetkey add 3 80b6a7cd7a9dadb6
 120
 121 I<key> should be an 8 byte hex representation.
 122
 123 =head1 PRIVILEGE REQUIRED
 124
 125 The issuer must be able to read (for B<asetkey list>) and write (for
 126 B<asetkey add> and B<asetkey delete>) the KeyFile, normally
 127 F</usr/afs/etc/KeyFile>.  In practice, this means that the issuer must be
 128 the local superuser C<root> on the AFS file server or database server.
 129 For B<asetkey add>, the issuer must also be able to read the specified
 130 keytab file.
 131
 132 =head1 SEE ALSO
 133
 134 L<KeyFile(5)>,
 135 L<bos_addkey(8)>,
 136 L<bos_listkeys(8)>,
 137 L<bos_removekey(8)>,
 138 kadmin(8),
 139 kvno(1)
 140
 141 =head1 COPYRIGHT
 142
 143 Copyright 2006 Russ Allbery <rra@stanford.edu>
 144
 145 This documentation is covered by the IBM Public License Version 1.0.  This
 146 man page was written by Russ Allbery for OpenAFS.