man-page-license-change-20071225
[openafs.git] / 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 wheras 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.