doc/man-pages/pod8/bos_util.pod

   1 =head1 NAME
   2
   3 bos_util - Manipulate the AFS server Keyfile
   4
   5 =head1 SYNOPSIS
   6
   7 =for html
   8 <div class="synopsis">
   9
  10 B<bos_util> add <I<kvno>>
  11
  12 B<bos_util> adddes <I<kvno>>
  13
  14 B<bos_util> delete <I<kvno>>
  15
  16 B<bos_util> list
  17
  18 =for html
  19 </div>
  20
  21 =head1 DESCRIPTION
  22
  23 The B<bos_util> command manipulates the AFS server B<Keyfile>. It can take
  24 a password from standard input, convert it to a key, and add it to the
  25 F<KeyFile>; list the keys in the F<KeyFile>; or remove a key from thet
  26 F<KeyFile>. It is very similar in function to B<asetkey>, but B<asetkey>
  27 works with keytab files whereas B<bos_util> works with passwords directly.
  28
  29 B<bos_util> expects one of the following subcommands:
  30
  31 =over 4
  32
  33 =item add <I<kvno>>
  34
  35 Add a key with key version <I<kvno>> to the F<KeyFile> using a password
  36 from standard input. This command uses the normal AFS password salt
  37 algorithm to generate the key (equivalent to the des-cbc-crc:afs3 enctype
  38 in Kerberos v5). This command is basically equivalent to B<bos addkey>.
  39
  40 =item adddes <I<kvno>>
  41
  42 Add a key with key version <I<kvno>> to the B<KeyFile> using a password
  43 from standard input.  This command does not salt the password when
  44 generating the key (equivalent to the des-cbc-crc:v4 enctype in Kerberos
  45 v5).
  46
  47 Since this command applies no salt to the password, it can be used as a
  48 last resort for generating a DES key with a salt algorithm that other
  49 utilities don't know how to use by giving this command the pre-salted
  50 password. This can be useful when, for example, using Microsoft Active
  51 Directory as the Kerberos KDC, since Active Directory uses a different
  52 salt algorithm for service principals than most Unix Kerberos
  53 implementations. The best approach, however, is to find a way to generate
  54 a keytab and then use B<asetkey>.
  55
  56 =item delete <I<kvno>>
  57
  58 Delete the key with the specified key version from the F<KeyFile>. This
  59 command is equivalent to B<asetkey delete> or B<bos removekey>.
  60
  61 =item list
  62
  63 List the keys in the F<KeyFile>. This command is equivalent to B<asetkey
  64 list> or B<bos listkeys>.
  65
  66 =back
  67
  68 The B<bos_util> command does not use the normal AFS option parsing library
  69 and its subcommands cannot be abbreviated.
  70
  71 =head1 CAUTIONS
  72
  73 B<bos_util> is intended for use with a Kerberos v4 environment and
  74 therefore is mostly obsolete. Normally, rather than using this command,
  75 you will want to use B<ktutil> to create a keytab (perhaps with its
  76 B<add_entry> command) and then use B<asetkey> as normal. B<bos_util> only
  77 supports the AFS password salt algorithm and no password salt algorithm
  78 and therefore may not produce the same key from a given password as
  79 Kerberos v5 utilities unless one is careful to use that same salt
  80 algorithm when creating the key in the KDC.
  81
  82 Creating an AFS key with a known password and then using B<bos_util> or
  83 B<bos addkey> to add that key to the F<KeyFile> is not recommended.
  84 Human-created passwords are usually not as strong as a random key
  85 generated using a good entropy source, such as with the B<-randkey> option
  86 to the MIT Kerberos v5 B<kadmin ktadd> command or the equivalent in other
  87 Kerberos v5 implementations. The security of AFS depends on the strength
  88 of the AFS service key; it should therefore be as random as possible.
  89
  90 It is imperative that the key version number (kvno) given matches the kvno
  91 on the Kerberos server. If it doesn't, users won't be able to
  92 authenticate. The key generated by B<bos_util> must also match the
  93 internal representation on the Kerberos server including the salt.
  94
  95 =head1 OPTIONS
  96
  97 B<bos_util> takes no options.
  98
  99 =head1 PRIVILEGE REQUIRED
 100
 101 The issuer must be logged onto a file server machine as the local
 102 superuser C<root>.
 103
 104 =head1 SEE ALSO
 105
 106 L<asetkey(8)>,
 107 L<bos_addkey(8)>,
 108 L<bos_listkeys(8)>,
 109 L<bos_removekey(8)>,
 110 kadmin(8),
 111 ktutil(8)
 112
 113 =head1 COPYRIGHT
 114
 115 Copyright 2007 Jason Edgecombe <jason@rampaginggeek.com>
 116
 117 This documentation is covered by the BSD License as written in the
 118 doc/LICENSE file. This man page was written by Jason Edgecombe for
 119 OpenAFS.