doc/man-pages/pod/bos_addkey.pod

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