[OpenAFS-Doc] new man page: bos_util

[Jason Edgecombe]

This is a multi-part message in MIME format.
--------------080409040802070505030905
Content-Type: text/plain; charset=ISO-8859-1; format=flowed
Content-Transfer-Encoding: 7bit

Jeffrey Altman wrote:
> Jason Edgecombe wrote:
>   
>> Hi,
>>
>> Here is a new man page for pod8/bos_util.pod.
>>
>> It's quite sparse because I can't find much info about the command,
>> aside that it works like asetkey for kerberos 4 and that it's deprecated.
>>
>> I welcome any comments or insights. I figure this sparse page is better
>> than nothing.
>>
>> Sincerely,
>> Jason
>>     
>
> You wrote:
>
> The B<bos_util> command uses Kerberos 4 password types like
> B<kaserver> and should not be used because of this. B<asetkey> should
> be used instead of B<bos_util>.
>
> ---
>
> This isn't really accurate.  The key is a DES key regardless of how the
> key is generated.  asetkey copies the key from the Kerberos v5 keytab
> and inserts it into the AFS KeyFile.  bos_util generates the key from a
> known password.  There is no difference in the strength of the key
> except in the fact that Kerberos v5 service keys are typically generated
> using sources of true randomness whereas passwords are typically
> generated by human beings and are therefore more likely to be
> brute-forced via a dictionary attack.
>
> That said, if the Kerberos v5 key was generated via a password, then the
> bos_util command can be used to generate the equivalent key with the
> same password.
>
>   
Thanks Jeff!

Here is the second draft that includes your suggestions.

Sincerely,
Jason

--------------080409040802070505030905
Content-Type: text/plain; x-mac-type="0"; x-mac-creator="0";
 name="bos_util.pod"
Content-Transfer-Encoding: 7bit
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> S<<< [B<add>] <I<kvno>> >>> S<<< [B<adddes>] <I<kvno>> >>>
   S<<< [B<delete>] <I<kvno>> >>> [B<list>]

=for html
</div>

=head1 DESCRIPTION

The B<bos_util> command can manipulate the AFS server B<Keyfile>. It
can take a password from standard input and convert it into a keytab
and add it to the B<KeyFile>. It's very similar in function to
B<asetkey>, but B<asetkey> works with keytab files wheras B<bos_util>
works with passwords directly. This is useful with some Kerberos
servers where dealing with a password is more practical than dealing
with a keytab. This is sometimes the case with Microsoft's Active
Directory Kerberos implementation.

This command can generate both Kerberos 4 and Kerberos 5 keyfiles if
the proper format and salt is used.

=head1 CAUTIONS

Since B<bos_util> creates a key from a human-generated password, the
key is usually not as strong as a random key that is generated using a
good entropy source, which is the case with a server-generated random
key.

It is imperative that the key version number (kvno) given matches the
kvno on the Kerberos server. If it doesn't then users won't be able to
authenticate. In addition, the password specified to B<bos_util> must
match the internal representation on the Kerberos server including the
salt.

For most Kerberos server implementations except Microsoft's Active
Directory, the salt is normally derived from the principal by
concatenating the realm and the components of the name without the "/" or
"@". Thus if the principal name was "afs/test.example.com@EXAMPLE.COM" and
the password was "newpasswd" the DES key would be generated from the
string "newpasswordEXAMPLE.COMafstest.example.com".

=head1 OPTIONS

=over 4

=item B<add> <I<kvno>>

Add a key to the B<KeyFile> using a password from standard input.

=item B<adddes> <I<kvno>>

Add a DES key to the B<KeyFile> using a password from standard input.

=item B<delete> <I<kvno>>

Delete the key with the specified kvno from the B<KeyFile>.

=item B<list>

List the keys in the B<KeyFile>.

=back

=head1 OUTPUT


=head1 EXAMPLES


=head1 PRIVILEGE REQUIRED

The issuer must be logged in as the local superuser root.

=head1 SEE ALSO

L<asetkey(8)>

L<http://www.openafs.org/pipermail/openafs-info/2007-January/024940.html>

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

--------------080409040802070505030905--