doc/man-pages/pod8/akeyconvert.pod

   1 =head1 NAME
   2
   3 akeyconvert - Import keys from rxkad.keytab to an AFS KeyFileExt
   4
   5 =head1 SYNOPSIS
   6
   7 =for html
   8 <div class="synopsis">
   9
  10 B<akeyconvert> I<-all>
  11
  12 =for html
  13 </div>
  14
  15 =head1 DESCRIPTION
  16
  17 The B<akeyconvert> command is used when upgrading an AFS cell from
  18 the 1.6.x release series to the 1.8.x release series.
  19 When using the rxkad-k5 security extension, the 1.6.x release series
  20 stored the AFS long-term Kerberos keys in a krb5 keytab file named
  21 F<rxkad.keytab>.  The 1.8.x series releases avoid widespread linking
  22 against libkrb5, and instead store the AFS long-term Kerberos keys
  23 in an OpenAFS-specific file format, the L<KeyFileExt(5)>.
  24
  25 B<akeyconvert> provides an easy way to convert the AFS long-term
  26 Kerberos keys from the krb5 keytab format to the KeyFileExt format.
  27 The same functionality is possible via repeated use of L<asetkey(8)>,
  28 but B<akeyconvert> is provided to simplify the process.
  29
  30 By default, B<akeyconvert> will only migrate the newest key (highest kvno)
  31 for each Kerberos principal with a key in the rxkad.keytab.  The ability
  32 to convert all keys, regardless of kvno, is provided as B<akeyconvert -all>.
  33
  34 =head1 CAUTIONS
  35
  36 The F<KeyFileExt> format is slightly less flexible than the krb5
  37 keytab format -- the F<KeyFileExt> identifies keys only by the
  38 type (rxkad-k5), kvno, and enctype ("subtype"), whereas the krb5 keytab
  39 also stores the principal name associated with each key.  This means
  40 that a krb5 keytab which contained keys of identical kvno and enctype,
  41 but for different principals, would not be representable as a
  42 F<KeyFileExt>.  B<akeyconvert> detects such a situation and does
  43 not perform any key conversions until the conflict is removed.
  44
  45 Many of the concerns given in L<asetkey(8)> regarding extracting
  46 new Kerberos keys with C<ktadd> are also applicable to changes
  47 involving the F<rxkad.keytab>.
  48
  49 =head1 EXAMPLES
  50
  51 In a cell which is using the rxkad-k5 extension, the following command
  52 will read the newest keys from the F<rxkad.keytab> and write them to the
  53 F<KeyFileExt> in the appropriate format.
  54
  55     % akeyconvert
  56
  57 In a cell which has a key of kvno 2 and enctype aes128-cts-hmac-sha1-96
  58 for both afs/example.com@EXAMPLE.COM and a different key with
  59 the same kvno and enctype but for the principal afs@EXAMPLE.COM,
  60 B<akeyconvert> will detect the kvno/enctype collision and refuse to
  61 continue.  The appropriate Kerberos keytab-manipulation tools should
  62 be used to generate a new key (of higher kvno) for one of the colliding
  63 principals and remove the old (colliding) key for that principal before
  64 B<akeyconvert> is used.
  65
  66     % akeyconvert -all
  67     Duplicate kvno/enctype 2/17
  68     FATAL: duplicate key identifiers found.
  69
  70 =head1 PRIVILEGE REQUIRED
  71
  72 The issuer must be able to read the F<rxkad.keytab> and write the
  73 F<KeyFile> and F<KeyFileExt>, normally F</usr/afs/etc/KeyFile> and
  74 F</usr/afs/etc/KeyFileExt>.  In practice, this means that the issuer must be
  75 the local superuser C<root> on the AFS file server or database server.
  76
  77 =head1 SEE ALSO
  78
  79 L<KeyFile(5)>,
  80 L<KeyFileExt(5)>,
  81 L<asetkey(8)>,
  82
  83 =head1 COPYRIGHT
  84
  85 Copyright 2015 Massachusetts Institute of Technology.
  86
  87 This documentation is covered by the IBM Public License Version 1.0.  This
  88 man page was written by Benjamin Kaduk for OpenAFS.