=head1 NAME

bos addkey - Adds a new server encryption key to the B</usr/afs/etc/KeyFile> file

=head1 SYNOPSIS

bos addkey B<-server> I<machine name>  [B<-key> I<key>]
B<-kvno> I<key version number>  [B<-cell> I<cell name>]
[B<-noauth>]  [B<-localauth>]  [B<-help>]

bos addk B<-s> I<machine name>  [B<-ke> I<key>]  B<-kv> I<key version number>
[B<-ce> I<cell name>]  [B<-n>]  [B<-l>]  [B<-h>]

=head1 DESCRIPTION

The C<bos addkey> command constructs a server encryption key from the
text string provided, assigns it the key version number specified with
the B<-kvno> argument, and adds it to the B</usr/afs/etc/KeyFile> file on
the machine specified with the B<-server> argument. Be sure to use the
C<kas setpassword> or C<kas setkey> command to add the same key to the B<afs>
entry in the Authentication Database.

Do not use the B<-key> argument, which echoes the password string visibly
on the screen. If the argument is omitted, the BOS Server prompts for
the string and does not echo it visibly:

   Input key:
   Retype input key:

The BOS Server prohibits reuse of any key version number already
listed in the B</usr/afs/etc/KeyFile> file. This ensures that users who
still have tickets sealed with the current key are not prevented from
communicating with a server process because the current key is
overwritten with a new key. Use the C<bos listkeys> command to display
the key version numbers in the B</usr/afs/etc/KeyFile> file.

=head1 OPTIONS

=over 4

=item B<-server> I<machine name>

Indicates the server machine on which to change the
B</usr/afs/etc/KeyFile> file. Identify the machine by IP address
or its host name (either fully-qualified or abbreviated
unambiguously). For details, see the introductory reference
page for the C<bos> command suite.

In cells that run the United States edition of AFS and use the
Update Server to distribute the contents of the B</usr/afs/etc>
directory, it is conventional to specify only the system
control machine as a value for the B<-server> argument. In cells
that run the international version of AFS, repeat the command
for each file server machine. For further discussion, see the
introductory reference page for the C<bos> command suite.

=item B<-key> I<key>

Specifies a character string just like a password; the BOS
Server calls a DES conversion function to encode it into a form
appropriate for use as an encryption key. Omit this argument to
have the BOS Server prompt for the string instead.

=item B<-kvno> I<key version number>

Defines the new key's key version number. It must be an integer
in the range from B<0> (zero) through B<255>. For the sake of
simplicity, use the number one higher than the current highest
key version number; use the C<bos listkeys> command to display key
version numbers.

=item B<-cell> I<cell name>

Names the cell in which to run the command. Do not combine this
argument with the B<-localauth> flag. For more details, see the
introductory L<bos(1)> reference page.

=item B<-noauth>

Assigns the unprivileged identity B<anonymous> to the issuer. Do
not combine this flag with the B<-localauth> flag. For more
details, see the introductory L<bos(1)> reference page.

=item B<-localauth>

Constructs a server ticket using a key from the local
B</usr/afs/etc/KeyFile> file. The C<bos> command interpreter presents
the ticket to the BOS Server during mutual authentication. Do
not combine this flag with the B<-cell> or B<-noauth> options. For
more details, see the introductory L<bos(1)> reference page.

=item B<-help>

Prints the online help for this command. All other valid
options are ignored.

=back

=head1 OUTPUT

If the strings typed at the C<Input key> and C<Retype input key> prompts do
not match, the following message appears, and the command exits
without adding a new key:

   Input key mismatch

=head1 EXAMPLES

The following command adds a new server encryption key with key
version number 14 to the B<KeyFile> file kept on the machine B<fs1.abc.com>
(the system control machine). The issuer omits the B<-key> argument, as
recommended, and provides the password at the prompts.

    bos addkey -server fs1.abc.com -kvno 14
   Input key:
   Retype input key:

=head1 PRIVILEGE REQUIRED

The issuer must be listed in the B</usr/afs/etc/UserList> file on the
machine named by the B<-server> argument, or must be logged onto a server
machine as the local superuser B<root> if the B<-localauth> flag is
included.

=head1 COPYRIGHT

IBM Corporation 2000. <http://www.ibm.com/> All Rights Reserved.

Converted from html to pod by Alf Wachsmann <alfw@slac.stanford.edu>, 2003,
and Elizabeth Cassell <e_a_c@mailsnare.net>, 2004,
Stanford Linear Accelerator Center, a department of Stanford University.

=head1 SEE ALSO

L<KeyFile(1)>,
L<UserList(1)>,
L<bos(1)>,
L<bos_listkeys(1)>,
L<bos_removekey(1)>

=cut
