[OpenAFS-Doc] new man page: bos_util

[Russ Allbery]

--=-=-=

Jason Edgecombe <jason@rampaginggeek.com> writes:

> Here is the second draft that includes your suggestions.

I've applied this with some changes.  See below for my version, which can
probably be further improved.

I added more information about what's going on with salts.  The salt
description that you had, based on Douglas Engert's message, is actually
the Kerberos v5 salt algorithm, which isn't one of the salt algorithms
that bos_util speaks.  bos_util supports either the traditional (and
weirdly complex) AFS salt (:afs3 in MIT Kerberos parlance) or straight DES
keys with no salt (:v4).  The relevant point from that message is that
since the adddes function applies no salt at all, you can use it as a
mechanism of last resort to generate a DES key by providing a pre-salted
password as input.  Douglas's message doesn't explain exactly how to do
that, just that it's possible, so I tried to incorporate the information
from that message into the man page and removed the link to the message
archive.

I added some more comparisons to the bos commands and to the asetkey
commands as well and reworded the pushing of people towards asetkey.


--=-=-=
Content-Disposition: inline; filename=bos_util.pod

=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.

--=-=-=


-- 
Russ Allbery (rra@stanford.edu)             <http://www.eyrie.org/~eagle/>

--=-=-=--