doc/xml/AdminReference/sect8/bos_addkey.xml

   1 <?xml version="1.0" encoding="UTF-8"?>
   2 <refentry id="bos_addkey8">
   3   <refmeta>
   4     <refentrytitle>bos addkey</refentrytitle>
   5     <manvolnum>8</manvolnum>
   6   </refmeta>
   7   <refnamediv>
   8     <refname>bos addkey</refname>
   9     <refpurpose>Adds a new server encryption key to the KeyFile file</refpurpose>
  10   </refnamediv>
  11   <refsect1>
  12     <title>Synopsis</title>
  13     <para><emphasis role="bold">bos addkey</emphasis> <emphasis role="bold">-server</emphasis> &lt;<emphasis>machine name</emphasis>&gt; [<emphasis role="bold">-key</emphasis> &lt;<emphasis>key</emphasis>&gt;]
  14         <emphasis role="bold">-kvno</emphasis> &lt;<emphasis>key version number</emphasis>&gt; [<emphasis role="bold">-cell</emphasis> &lt;<emphasis>cell name</emphasis>&gt;]
  15         [<emphasis role="bold">-noauth</emphasis>] [<emphasis role="bold">-localauth</emphasis>] [<emphasis role="bold">-help</emphasis>]</para>
  16
  17     <para><emphasis role="bold">bos addk</emphasis> <emphasis role="bold">-s</emphasis> &lt;<emphasis>machine name</emphasis>&gt; [<emphasis role="bold">-ke</emphasis> &lt;<emphasis>key</emphasis>&gt;]
  18         <emphasis role="bold">-kv</emphasis> &lt;<emphasis>key version number</emphasis>&gt; [<emphasis role="bold">-ce</emphasis> &lt;<emphasis>cell name</emphasis>&gt;] [<emphasis role="bold">-n</emphasis>]
  19         [<emphasis role="bold">-l</emphasis>] [<emphasis role="bold">-h</emphasis>]</para>
  20
  21   </refsect1>
  22   <refsect1>
  23     <title>Description</title>
  24     <para>The <emphasis role="bold">bos addkey</emphasis> command constructs a server encryption key from the text
  25     string provided, assigns it the key version number specified with the
  26     <emphasis role="bold">-kvno</emphasis> argument, and adds it to the <replaceable>/usr/afs/etc/KeyFile</replaceable> file on the
  27     machine specified with the <emphasis role="bold">-server</emphasis> argument. Be sure to use the <emphasis role="bold">kas
  28     setpassword</emphasis> or <emphasis role="bold">kas setkey</emphasis> command to add the same key to the <computeroutput>afs</computeroutput>
  29     entry in the Authentication Database.</para>
  30
  31     <para>Do not use the <emphasis role="bold">-key</emphasis> argument, which echoes the password string visibly
  32     on the screen. If the argument is omitted, the BOS Server prompts for the
  33     string and does not echo it visibly:</para>
  34
  35 <programlisting>
  36    Input key:
  37    Retype input key:
  38
  39 </programlisting>
  40       <para>The BOS Server prohibits reuse of any key version number already listed in
  41       the <replaceable>/usr/afs/etc/KeyFile</replaceable> file. This ensures that users who still have
  42       tickets sealed with the current key are not prevented from communicating
  43       with a server process because the current key is overwritten with a new
  44       key. Use the <emphasis role="bold">bos listkeys</emphasis> command to display the key version numbers in
  45       the <replaceable>/usr/afs/etc/KeyFile</replaceable> file.</para>
  46
  47     </refsect1>
  48     <refsect1>
  49       <title>Options</title>
  50       <variablelist>
  51         <varlistentry>
  52           <term><emphasis role="bold">-server</emphasis> &lt;<emphasis>machine name</emphasis>&gt;</term>
  53           <listitem>
  54             <para>Indicates the server machine on which to change the
  55             <replaceable>/usr/afs/etc/KeyFile</replaceable> file. Identify the machine by IP address or its
  56             host name (either fully-qualified or abbreviated unambiguously). For
  57             details, see <link linkend="bos8">bos(8)</link>.</para>
  58
  59             <para>In cells that use the Update Server to distribute the contents of the
  60             <replaceable>/usr/afs/etc</replaceable> directory, it is conventional to specify only the system
  61             control machine as a value for the <emphasis role="bold">-server</emphasis> argument. Otherwise, repeat
  62             the command for each file server machine. For further discussion, see
  63             <link linkend="bos8">bos(8)</link>.</para>
  64
  65           </listitem>
  66         </varlistentry>
  67         <varlistentry>
  68           <term><emphasis role="bold">-key</emphasis> &lt;<emphasis>key</emphasis>&gt;</term>
  69           <listitem>
  70             <para>Specifies a character string just like a password; the BOS Server calls a
  71             DES conversion function to encode it into a form appropriate for use as an
  72             encryption key. Omit this argument to have the BOS Server prompt for the
  73             string instead.</para>
  74
  75           </listitem>
  76         </varlistentry>
  77         <varlistentry>
  78           <term><emphasis role="bold">-kvno</emphasis> &lt;<emphasis>key version number</emphasis>&gt;</term>
  79           <listitem>
  80             <para>Defines the new key's key version number. It must be an integer in the
  81             range from <computeroutput>0</computeroutput> (zero) through <computeroutput>255</computeroutput>.  For the sake of simplicity, use
  82             the number one higher than the current highest key version number; use the
  83             <emphasis role="bold">bos listkeys</emphasis> command to display key version numbers.</para>
  84
  85           </listitem>
  86         </varlistentry>
  87         <varlistentry>
  88           <term><emphasis role="bold">-cell</emphasis> &lt;<emphasis>cell name</emphasis>&gt;</term>
  89           <listitem>
  90             <para>Names the cell in which to run the command. Do not combine this argument
  91             with the <emphasis role="bold">-localauth</emphasis> flag. For more details, see <link linkend="bos8">bos(8)</link>.</para>
  92
  93           </listitem>
  94         </varlistentry>
  95         <varlistentry>
  96           <term><emphasis role="bold">-noauth</emphasis></term>
  97           <listitem>
  98             <para>Assigns the unprivileged identity <computeroutput>anonymous</computeroutput> to the issuer. Do not combine
  99             this flag with the <emphasis role="bold">-localauth</emphasis> flag. For more details, see <link linkend="bos8">bos(8)</link>.</para>
 100
 101           </listitem>
 102         </varlistentry>
 103         <varlistentry>
 104           <term><emphasis role="bold">-localauth</emphasis></term>
 105           <listitem>
 106             <para>Constructs a server ticket using a key from the local
 107             <replaceable>/usr/afs/etc/KeyFile</replaceable> file. The <emphasis role="bold">bos</emphasis> command interpreter presents the
 108             ticket to the BOS Server during mutual authentication. Do not combine this
 109             flag with the <emphasis role="bold">-cell</emphasis> or <emphasis role="bold">-noauth</emphasis> options. For more details, see
 110             <link linkend="bos8">bos(8)</link>.</para>
 111
 112           </listitem>
 113         </varlistentry>
 114         <varlistentry>
 115           <term><emphasis role="bold">-help</emphasis></term>
 116           <listitem>
 117             <para>Prints the online help for this command. All other valid options are
 118             ignored.</para>
 119
 120           </listitem>
 121         </varlistentry>
 122       </variablelist>
 123     </refsect1>
 124     <refsect1>
 125       <title>Output</title>
 126       <para>If the strings typed at the <computeroutput>Input key</computeroutput> and <computeroutput>Retype input key</computeroutput> prompts
 127       do not match, the following message appears, and the command exits without
 128       adding a new key:</para>
 129
 130 <programlisting>
 131    Input key mismatch
 132
 133 </programlisting>
 134       </refsect1>
 135       <refsect1>
 136         <title>Examples</title>
 137         <para>The following command adds a new server encryption key with key version
 138         number 14 to the <emphasis role="bold">KeyFile</emphasis> file kept on the machine <computeroutput>fs1.abc.com</computeroutput> (the
 139         system control machine). The issuer omits the <emphasis role="bold">-key</emphasis> argument, as
 140         recommended, and provides the password at the prompts.</para>
 141
 142 <programlisting>
 143    % bos addkey -server fs1.abc.com -kvno 14
 144    Input key:
 145    Retype input key:
 146
 147 </programlisting>
 148         </refsect1>
 149         <refsect1>
 150           <title>Privilege Required</title>
 151           <para>The issuer must be listed in the <replaceable>/usr/afs/etc/UserList</replaceable> file on the
 152           machine named by the <emphasis role="bold">-server</emphasis> argument, or must be logged onto a server
 153           machine as the local superuser <computeroutput>root</computeroutput> if the <emphasis role="bold">-localauth</emphasis> flag is
 154           included.</para>
 155
 156         </refsect1>
 157         <refsect1>
 158           <title>See Also</title>
 159           <para><link linkend="KeyFile5">KeyFile(5)</link>,
 160           <link linkend="UserList5">UserList(5)</link>,
 161           <link linkend="bos8">bos(8)</link>,
 162           <link linkend="bos_listkeys8">bos_listkeys(8)</link>,
 163           <link linkend="bos_removekey8">bos_removekey(8)</link></para>
 164
 165         </refsect1>
 166         <refsect1>
 167           <title>Copyright</title>
 168           <para>IBM Corporation 2000. &lt;http://www.ibm.com/&gt; All Rights Reserved.</para>
 169
 170           <para>This documentation is covered by the IBM Public License Version 1.0.  It was
 171           converted from HTML to POD by software written by Chas Williams and Russ
 172           Allbery, based on work by Alf Wachsmann and Elizabeth Cassell.</para>
 173
 174         </refsect1>
 175       </refentry>