man-page-bos-util-20070817

Add a man page for bos_util.

doc/man-pages/README

@@ -197,7 +197,6 @@ Known Problems
 
    * The following installed commands have no man pages:
 
-       bos_util
        copyauth
        flushall (Windows only)
        fs getcalleraccess
@@ -230,6 +229,9 @@ Known Problems
    * bos listkeys and the KeyFile man page assume that you're using the
      kaserver.
 
+   * bos addkey should be marked deprecated in favor of using asetkey with
+     a keytab.
+
    * I'm fairly sure that the fileserver man page no longer documents all
      of the fileserver options.
 

doc/man-pages/pod8/bos_util.pod

@@ -0,0 +1,118 @@
+=head1 NAME
+
+bos_util - Manipulate the AFS server Keyfile
+
+=head1 SYNOPSIS
+
+=for html
+<div class="synopsis">
+
+B<bos_util> add <I<kvno>>
+
+B<bos_util> adddes <I<kvno>>
+
+B<bos_util> delete <I<kvno>>
+
+B<bos_util> list
+
+=for html
+</div>
+
+=head1 DESCRIPTION
+
+The B<bos_util> command manipulates the AFS server B<Keyfile>. It can take
+a password from standard input, convert it to a key, and add it to the
+F<KeyFile>; list the keys in the F<KeyFile>; or remove a key from thet
+F<KeyFile>. It is very similar in function to B<asetkey>, but B<asetkey>
+works with keytab files wheras B<bos_util> works with passwords directly.
+
+B<bos_util> expects one of the following subcommands:
+
+=over 4
+
+=item add <I<kvno>>
+
+Add a key with key version <I<kvno>> to the F<KeyFile> using a password
+from standard input. This command uses the normal AFS password salt
+algorithm to generate the key (equivalent to the des-cbc-crc:afs3 enctype
+in Kerberos v5). This command is basically equivalent to B<bos addkey>.
+
+=item adddes <I<kvno>>
+
+Add a key with key version <I<kvno>> to the B<KeyFile> using a password
+from standard input.  This command does not salt the password when
+generating the key (equivalent to the des-cbc-crc:v4 enctype in Kerberos
+v5).
+
+Since this command applies no salt to the password, it can be used as a
+last resort for generating a DES key with a salt algorithm that other
+utilities don't know how to use by giving this command the pre-salted
+password. This can be useful when, for example, using Microsoft Active
+Directory as the Kerberos KDC, since Active Directory uses a different
+salt algorithm for service principals than most Unix Kerberos
+implementations. The best approach, however, is to find a way to generate
+a keytab and then use B<asetkey>.
+
+=item delete <I<kvno>>
+
+Delete the key with the specified key version from the F<KeyFile>. This
+command is equivalent to B<asetkey delete> or B<bos removekey>.
+
+=item list
+
+List the keys in the F<KeyFile>. This command is equivalent to B<asetkey
+list> or B<bos listkeys>.
+
+=back
+
+The B<bos_util> command does not use the normal AFS option parsing library
+and its subcommands cannot be abbreviated.
+
+=head1 CAUTIONS
+
+B<bos_util> is intended for use with a Kerberos v4 environment and
+therefore is mostly obsolete. Normally, rather than using this command,
+you will want to use B<ktutil> to create a keytab (perhaps with its
+B<add_entry> command) and then use B<asetkey> as normal. B<bos_util> only
+supports the AFS password salt algorithm and no password salt algorithm
+and therefore may not produce the same key from a given password as
+Kerberos v5 utilities unless one is careful to use that same salt
+algorithm when creating the key in the KDC.
+
+Creating an AFS key with a known password and then using B<bos_util> or
+B<bos addkey> to add that key to the F<KeyFile> is not recommended.
+Human-created passwords are usually not as strong as a random key
+generated using a good entropy source, such as with the B<-randkey> option
+to the MIT Kerberos v5 B<kadmin ktadd> command or the equivalent in other
+Kerberos v5 implementations. The security of AFS depends on the strength
+of the AFS service key; it should therefore be as random as possible.
+
+It is imperative that the key version number (kvno) given matches the kvno
+on the Kerberos server. If it doesn't, users won't be able to
+authenticate. The key generated by B<bos_util> must also match the
+internal representation on the Kerberos server including the salt.
+
+=head1 OPTIONS
+
+B<bos_util> takes no options.
+
+=head1 PRIVILEGE REQUIRED
+
+The issuer must be logged onto a file server machine as the local
+superuser C<root>.
+
+=head1 SEE ALSO
+
+L<asetkey(8)>,
+L<bos_addkey(8)>,
+L<bos_listkeys(8)>,
+L<bos_removekey(8)>,
+kadmin(8),
+ktutil(8)
+
+=head1 COPYRIGHT
+
+Copyright 2007 Jason Edgecombe <jason@rampaginggeek.com>
+
+This documentation is covered by the IBM Public License Version 1.0.
+This man page was written by Jason Edgecombe for OpenAFS.