5f51b2e2312a26f8f8e6bb07d0d797e72cf85071
[openafs.git] / doc / man-pages / pod8 / bos_addkey.pod
1 =head1 NAME
2
3 bos_addkey - Adds a new server encryption key to the KeyFile file
4
5 =head1 SYNOPSIS
6
7 =for html
8 <div class="synopsis">
9
10 B<bos addkey> S<<< B<-server> <I<machine name>> >>> S<<< [B<-key> <I<key>>] >>>
11     S<<< B<-kvno> <I<key version number>> >>> S<<< [B<-cell> <I<cell name>>] >>>
12     [B<-noauth>] [B<-localauth>] [B<-help>]
13
14 B<bos addk> S<<< B<-s> <I<machine name>> >>> S<<< [B<-ke> <I<key>>] >>>
15     S<<< B<-kv> <I<key version number>> >>> S<<< [B<-ce> <I<cell name>>] >>> [B<-n>]
16     [B<-l>] [B<-h>]
17
18 =for html
19 </div>
20
21 =head1 DESCRIPTION
22
23 The B<bos addkey> command constructs a server encryption key from the text
24 string provided, assigns it the key version number specified with the
25 B<-kvno> argument, and adds it to the F</usr/afs/etc/KeyFile> file on the
26 machine specified with the B<-server> argument. Be sure to use the B<kas
27 setpassword> or B<kas setkey> command to add the same key to the C<afs>
28 entry in the Authentication Database.
29
30 Do not use the B<-key> argument, which echoes the password string visibly
31 on the screen. If the argument is omitted, the BOS Server prompts for the
32 string and does not echo it visibly:
33
34    Input key:
35    Retype input key:
36
37 The BOS Server prohibits reuse of any key version number already listed in
38 the F</usr/afs/etc/KeyFile> file. This ensures that users who still have
39 tickets sealed with the current key are not prevented from communicating
40 with a server process because the current key is overwritten with a new
41 key. Use the B<bos listkeys> command to display the key version numbers in
42 the F</usr/afs/etc/KeyFile> file.
43
44 =head1 OPTIONS
45
46 =over 4
47
48 =item B<-server> <I<machine name>>
49
50 Indicates the server machine on which to change the
51 F</usr/afs/etc/KeyFile> file. Identify the machine by IP address or its
52 host name (either fully-qualified or abbreviated unambiguously). For
53 details, see L<bos(8)>.
54
55 In cells that use the Update Server to distribute the contents of the
56 F</usr/afs/etc> directory, it is conventional to specify only the system
57 control machine as a value for the B<-server> argument. Otherwise, repeat
58 the command for each file server machine. For further discussion, see
59 L<bos(8)>.
60
61 =item B<-key> <I<key>>
62
63 Specifies a character string just like a password; the BOS Server calls a
64 DES conversion function to encode it into a form appropriate for use as an
65 encryption key. Omit this argument to have the BOS Server prompt for the
66 string instead.
67
68 =item B<-kvno> <I<key version number>>
69
70 Defines the new key's key version number. It must be an integer in the
71 range from C<0> (zero) through C<255>.  For the sake of simplicity, use
72 the number one higher than the current highest key version number; use the
73 B<bos listkeys> command to display key version numbers.
74
75 =item B<-cell> <I<cell name>>
76
77 Names the cell in which to run the command. Do not combine this argument
78 with the B<-localauth> flag. For more details, see L<bos(8)>.
79
80 =item B<-noauth>
81
82 Assigns the unprivileged identity C<anonymous> to the issuer. Do not combine
83 this flag with the B<-localauth> flag. For more details, see L<bos(8)>.
84
85 =item B<-localauth>
86
87 Constructs a server ticket using a key from the local
88 F</usr/afs/etc/KeyFile> file. The B<bos> command interpreter presents the
89 ticket to the BOS Server during mutual authentication. Do not combine this
90 flag with the B<-cell> or B<-noauth> options. For more details, see
91 L<bos(8)>.
92
93 =item B<-help>
94
95 Prints the online help for this command. All other valid options are
96 ignored.
97
98 =back
99
100 =head1 OUTPUT
101
102 If the strings typed at the C<Input key> and C<Retype input key> prompts
103 do not match, the following message appears, and the command exits without
104 adding a new key:
105
106    Input key mismatch
107
108 =head1 EXAMPLES
109
110 The following command adds a new server encryption key with key version
111 number 14 to the B<KeyFile> file kept on the machine C<fs1.abc.com> (the
112 system control machine). The issuer omits the B<-key> argument, as
113 recommended, and provides the password at the prompts.
114
115    % bos addkey -server fs1.abc.com -kvno 14
116    Input key:
117    Retype input key:
118
119 =head1 PRIVILEGE REQUIRED
120
121 The issuer must be listed in the F</usr/afs/etc/UserList> file on the
122 machine named by the B<-server> argument, or must be logged onto a server
123 machine as the local superuser C<root> if the B<-localauth> flag is
124 included.
125
126 =head1 SEE ALSO
127
128 L<KeyFile(5)>,
129 L<UserList(5)>,
130 L<bos(8)>,
131 L<bos_listkeys(8)>,
132 L<bos_removekey(8)>
133
134 =head1 COPYRIGHT
135
136 IBM Corporation 2000. <http://www.ibm.com/> All Rights Reserved.
137
138 This documentation is covered by the IBM Public License Version 1.0.  It was
139 converted from HTML to POD by software written by Chas Williams and Russ
140 Allbery, based on work by Alf Wachsmann and Elizabeth Cassell.