Commit | Line | Data |
---|---|---|
805e021f CE |
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. |