1 <?xml version="1.0" encoding="UTF-8"?>
2 <refentry id="bos_listkeys8">
4 <refentrytitle>bos listkeys</refentrytitle>
5 <manvolnum>8</manvolnum>
8 <refname>bos listkeys</refname>
9 <refpurpose>Displays the server encryption keys from the KeyFile file</refpurpose>
12 <title>Synopsis</title>
13 <para><emphasis role="bold">bos listkeys</emphasis> <emphasis role="bold">-server</emphasis> <<emphasis>machine name</emphasis>> [<emphasis role="bold">-showkey</emphasis>]
14 [<emphasis role="bold">-cell</emphasis> <<emphasis>cell name</emphasis>>] [<emphasis role="bold">-noauth</emphasis>] [<emphasis role="bold">-localauth</emphasis>] [<emphasis role="bold">-help</emphasis>]</para>
16 <para><emphasis role="bold">bos listk</emphasis> <emphasis role="bold">-se</emphasis> <<emphasis>machine name</emphasis>> [<emphasis role="bold">-sh</emphasis>] [<emphasis role="bold">-c</emphasis> <<emphasis>cell name</emphasis>>]
17 [<emphasis role="bold">-n</emphasis>] [<emphasis role="bold">-l</emphasis>] [<emphasis role="bold">-h</emphasis>]</para>
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>
26 <para>To edit the list of keys, use the <emphasis role="bold">bos addkey</emphasis> and <emphasis role="bold">bos removekey</emphasis>
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>
38 <title>Options</title>
41 <term><emphasis role="bold">-server</emphasis> <<emphasis>machine name</emphasis>></term>
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>
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>
54 <term><emphasis role="bold">-showkey</emphasis></term>
56 <para>Displays the octal digits that constitute each key.</para>
61 <term><emphasis role="bold">-cell</emphasis> <<emphasis>cell name</emphasis>></term>
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>
69 <term><emphasis role="bold">-noauth</emphasis></term>
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>
78 <term><emphasis role="bold">-localauth</emphasis></term>
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>
89 <term><emphasis role="bold">-help</emphasis></term>
91 <para>Prints the online help for this command. All other valid options are
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>
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>
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
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>
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>
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>
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.
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>
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.
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
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>
167 <title>Copyright</title>
168 <para>IBM Corporation 2000. <http://www.ibm.com/> All Rights Reserved.</para>
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>