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> delete <I<kvno>>
  15
  16 B<asetkey> list
  17
  18 =for html
  19 </div>
  20
  21 =head1 DESCRIPTION
  22
  23 The B<asetkey> command is used to add a key to an AFS KeyFile from a
  24 Kerberos keytab.  It is similar to B<bos addkey> except that it must be
  25 run locally on the system where the KeyFile is located and it takes the
  26 new key from the command line or a Kerberos 5 keytab rather than prompting
  27 for the password.
  28
  29 B<asetkey delete> can be used to delete a key (similar to B<bos
  30 removekeys>), and B<asetkey list> will list the keys in a KeyFile (similar
  31 to B<bos listkeys>).
  32
  33 B<asetkey> is used when authentication for an AFS cell is provided by a
  34 Kerberos 5 KDC rather than B<kaserver>.  The key for the C<afs> or
  35 C<afs/I<cell name>> principal in the Kerberos 5 KDC must match the key
  36 stored in the AFS KeyFile on all AFS database servers and file servers.
  37 This is done by creating a keytab containing that key using the standard
  38 Kerberos commands (generally the C<ktadd> function of the B<kadmin>
  39 command) and then, on each AFS database server and file server, adding
  40 that key to the KeyFile with B<asetkey add>.  The I<kvno> chosen should
  41 match the kvno in the Kerberos KDC (checked with B<kvno> or the
  42 C<getprinc> function of B<kadmin>).  I<principal> should be the name of
  43 the AFS principal in the keytab, which must be either C<afs> or
  44 C<afs/I<cell name>>. B<asetkey> can also be used to install a key
  45 from a hex string.
  46
  47 In cells that use the Update Server to distribute the contents of the
  48 F</usr/afs/etc> directory, it is conventional to run B<asetkey add> only
  49 on the control machine and then let the Update Server propagate the new
  50 KeyFile to all other systems.
  51
  52 =head1 CAUTIONS
  53
  54 AFS currently only supports des-cbc-crc:v4 Kerberos keys.  Make sure, when
  55 creating the keytab with C<ktadd>, you pass C<-e des-cbc-crc:v4> to force
  56 the encryption type.  Otherwise, AFS authentication may not work.
  57
  58 As soon as a new keytab is created with C<ktadd>, new AFS service tickets
  59 will use the new key.  However, tokens formed from those service tickets
  60 will only work if the new key is present in the KeyFile on the AFS file
  61 server.  There is therefore an outage window between when the new keytab
  62 is created and when the key had been added to the KeyFile of all AFS
  63 servers with B<asetkey>, during which newly obtained AFS tokens will not
  64 work properly.
  65
  66 All of the KeyFile entries must match the key in the Kerberos KDC, but
  67 each time C<ktadd> is run, it creates a new key.  Either the Update Server
  68 must be used to distribute the KeyFile to all servers or the same keytab
  69 must be used with B<asetkey> on each server.
  70
  71 =head1 EXAMPLES
  72
  73 The following commands create a new keytab for the principal C<afs> and
  74 then import the key into the KeyFile.  Note the kvno in the output from
  75 C<ktadd>.
  76
  77     % kadmin
  78     Authenticating as principal rra/admin@stanford.edu with password.
  79     Password for rra/admin@stanford.edu:
  80     kadmin:  ktadd -k /tmp/afs.keytab -e des-cbc-crc:v4 afs
  81     Entry for principal afs with kvno 3, encryption type DES cbc mode
  82     with CRC-32 added to keytab WRFILE:/tmp/afs.keytab.
  83     kadmin:  exit
  84     % asetkey add 3 /tmp/afs.keytab afs
  85
  86 You may want to use C<afs/I<cell name>> instead of C<afs>, particularly if
  87 you may have multiple AFS cells for a single Kerberos realm.
  88
  89 In the event you have been distributed a key by a Kerberos administrator
  90 in the form of a hex string, you may use asetkey to install that.
  91
  92     % asetkey add 3 80b6a7cd7a9dadb6
  93
  94 I<key> should be an 8 byte hex representation.
  95
  96 =head1 PRIVILEGE REQUIRED
  97
  98 The issuer must be able to read (for B<asetkey list>) and write (for
  99 B<asetkey add> and B<asetkey delete>) the KeyFile, normally
 100 F</usr/afs/etc/KeyFile>.  In practice, this means that the issuer must be
 101 the local superuser C<root> on the AFS file server or database server.
 102 For B<asetkey add>, the issuer must also be able to read the specified
 103 keytab file.
 104
 105 =head1 SEE ALSO
 106
 107 L<KeyFile(5)>,
 108 L<bos_addkey(8)>,
 109 L<bos_listkeys(8)>,
 110 L<bos_removekey(8)>,
 111 kadmin(8),
 112 kvno(1)
 113
 114 =head1 COPYRIGHT
 115
 116 Copyright 2006 Russ Allbery <rra@stanford.edu>
 117
 118 This documentation is covered by the IBM Public License Version 1.0.  This
 119 man page was written by Russ Allbery for OpenAFS.