doc/xml/AdminReference/sect8/bos_listkeys.xml

   1 <?xml version="1.0" encoding="UTF-8"?>
   2 <refentry id="bos_listkeys8">
   3   <refmeta>
   4     <refentrytitle>bos listkeys</refentrytitle>
   5     <manvolnum>8</manvolnum>
   6   </refmeta>
   7   <refnamediv>
   8     <refname>bos listkeys</refname>
   9     <refpurpose>Displays the server encryption keys from the KeyFile file</refpurpose>
  10   </refnamediv>
  11   <refsect1>
  12     <title>Synopsis</title>
  13     <para><emphasis role="bold">bos listkeys</emphasis> <emphasis role="bold">-server</emphasis> &lt;<emphasis>machine name</emphasis>&gt; [<emphasis role="bold">-showkey</emphasis>]
  14         [<emphasis role="bold">-cell</emphasis> &lt;<emphasis>cell name</emphasis>&gt;] [<emphasis role="bold">-noauth</emphasis>] [<emphasis role="bold">-localauth</emphasis>] [<emphasis role="bold">-help</emphasis>]</para>
  15
  16     <para><emphasis role="bold">bos listk</emphasis> <emphasis role="bold">-se</emphasis> &lt;<emphasis>machine name</emphasis>&gt; [<emphasis role="bold">-sh</emphasis>] [<emphasis role="bold">-c</emphasis> &lt;<emphasis>cell name</emphasis>&gt;]
  17         [<emphasis role="bold">-n</emphasis>] [<emphasis role="bold">-l</emphasis>] [<emphasis role="bold">-h</emphasis>]</para>
  18
  19   </refsect1>
  20   <refsect1>
  21     <title>Description</title>
  22     <para>The <emphasis role="bold">bos listkeys</emphasis> command formats and displays the list of server
  23     encryption keys from the <replaceable>/usr/afs/etc/KeyFile</replaceable> file on the server
  24     machine named by the <emphasis role="bold">-server</emphasis> argument.</para>
  25
  26     <para>To edit the list of keys, use the <emphasis role="bold">bos addkey</emphasis> and <emphasis role="bold">bos removekey</emphasis>
  27     commands.</para>
  28
  29   </refsect1>
  30   <refsect1>
  31     <title>Cautions</title>
  32     <para>Displaying actual keys on the standard output stream (by including the
  33     <emphasis role="bold">-showkey</emphasis> flag) is a security exposure. Displaying a checksum is
  34     sufficient for most purposes.</para>
  35
  36   </refsect1>
  37   <refsect1>
  38     <title>Options</title>
  39     <variablelist>
  40       <varlistentry>
  41         <term><emphasis role="bold">-server</emphasis> &lt;<emphasis>machine name</emphasis>&gt;</term>
  42         <listitem>
  43           <para>Indicates the server machine from which to display the KeyFile
  44           file. Identify the machine by IP address or its host name (either
  45           fully-qualified or abbreviated unambiguously). For details, see <link linkend="bos8">bos(8)</link>.</para>
  46
  47           <para>For consistent performance in the cell, the output must be the same on
  48           every server machine. The <emphasis role="bold">bos addkey</emphasis> reference page explains how to
  49           keep the machines synchronized.</para>
  50
  51         </listitem>
  52       </varlistentry>
  53       <varlistentry>
  54         <term><emphasis role="bold">-showkey</emphasis></term>
  55         <listitem>
  56           <para>Displays the octal digits that constitute each key.</para>
  57
  58         </listitem>
  59       </varlistentry>
  60       <varlistentry>
  61         <term><emphasis role="bold">-cell</emphasis> &lt;<emphasis>cell name</emphasis>&gt;</term>
  62         <listitem>
  63           <para>Names the cell in which to run the command. Do not combine this argument
  64           with the <emphasis role="bold">-localauth</emphasis> flag. For more details, see <link linkend="bos8">bos(8)</link>.</para>
  65
  66         </listitem>
  67       </varlistentry>
  68       <varlistentry>
  69         <term><emphasis role="bold">-noauth</emphasis></term>
  70         <listitem>
  71           <para>Assigns the unprivileged identity <computeroutput>anonymous</computeroutput> to the issuer. Do not
  72           combine this flag with the <emphasis role="bold">-localauth</emphasis> flag. For more details, see
  73           <link linkend="bos8">bos(8)</link>.</para>
  74
  75         </listitem>
  76       </varlistentry>
  77       <varlistentry>
  78         <term><emphasis role="bold">-localauth</emphasis></term>
  79         <listitem>
  80           <para>Constructs a server ticket using a key from the local
  81           <replaceable>/usr/afs/etc/KeyFile</replaceable> file. The <emphasis role="bold">bos</emphasis> command interpreter presents the
  82           ticket to the BOS Server during mutual authentication. Do not combine this
  83           flag with the <emphasis role="bold">-cell</emphasis> or <emphasis role="bold">-noauth</emphasis> options. For more details, see
  84           <link linkend="bos8">bos(8)</link>.</para>
  85
  86         </listitem>
  87       </varlistentry>
  88       <varlistentry>
  89         <term><emphasis role="bold">-help</emphasis></term>
  90         <listitem>
  91           <para>Prints the online help for this command. All other valid options are
  92           ignored.</para>
  93
  94         </listitem>
  95       </varlistentry>
  96     </variablelist>
  97   </refsect1>
  98   <refsect1>
  99     <title>Output</title>
 100     <para>The output includes one line for each server encryption key listed in the
 101     <replaceable>KeyFile</replaceable> file, identified by its key version number.</para>
 102
 103     <para>If the <emphasis role="bold">-showkey</emphasis> flag is included, the output displays the actual string
 104     of eight octal numbers that constitute the key. Each octal number is a
 105     backslash and three decimal digits.</para>
 106
 107     <para>If the <emphasis role="bold">-showkey</emphasis> flag is not included, the output represents each key as
 108     a checksum, which is a decimal number derived by encrypting a constant
 109     with the key.</para>
 110
 111     <para>Following the list of keys or checksums, the string <computeroutput>Keys last changed</computeroutput>
 112     indicates when a key was last added to the <replaceable>KeyFile</replaceable> file. The words
 113     <computeroutput>All done</computeroutput> indicate the end of the output.</para>
 114
 115     <para>For mutual authentication to work properly, the output from the command
 116     <computeroutput>kas examine afs</computeroutput> must match the key or checksum with the same key
 117     version number in the output from this command.</para>
 118
 119   </refsect1>
 120   <refsect1>
 121     <title>Examples</title>
 122     <para>The following example shows the checksums for the keys stored in the
 123     <replaceable>KeyFile</replaceable> file on the machine <computeroutput>fs3.abc.com</computeroutput>.</para>
 124
 125 <programlisting>
 126    % bos listkeys fs3.abc.com
 127    key 1 has cksum 972037177
 128    key 3 has cksum 2825175022
 129    key 4 has cksum 260617746
 130    key 6 has cksum 4178774593
 131    Keys last changed on Mon Apr 12 11:24:46 1999.
 132    All done.
 133
 134 </programlisting>
 135       <para>The following example shows the actual keys from the <replaceable>KeyFile</replaceable> file on
 136       the machine <computeroutput>fs6.abc.com</computeroutput>.</para>
 137
 138 <programlisting>
 139    % bos listkeys fs6.abc.com -showkey
 140    key 0 is '\040\205\211\241\345\002\023\211'
 141    key 1 is '\343\315\307\227\255\320\135\244'
 142    key 2 is '\310\310\255\253\326\236\261\211'
 143    Keys last changed on Wed Mar 31 11:24:46 1999.
 144    All done.
 145
 146 </programlisting>
 147       </refsect1>
 148       <refsect1>
 149         <title>Privilege Required</title>
 150         <para>The issuer must be listed in the <replaceable>/usr/afs/etc/UserList</replaceable> file on the
 151         machine named by the <emphasis role="bold">-server</emphasis> argument, or must be logged onto a server
 152         machine as the local superuser <computeroutput>root</computeroutput> if the <emphasis role="bold">-localauth</emphasis> flag is
 153         included.</para>
 154
 155       </refsect1>
 156       <refsect1>
 157         <title>See Also</title>
 158         <para><link linkend="KeyFile5">KeyFile(5)</link>,
 159         <link linkend="UserList5">UserList(5)</link>,
 160         <link linkend="bos_addkey8">bos_addkey(8)</link>,
 161         <link linkend="bos_removekey8">bos_removekey(8)</link>,
 162         <link linkend="bos_setauth8">bos_setauth(8)</link>,
 163         <link linkend="kas_examine8">kas_examine(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>