Commit | Line | Data |
---|---|---|
805e021f CE |
1 | =head1 NAME |
2 | ||
3 | bos_listkeys - Displays the server encryption keys from the KeyFile file | |
4 | ||
5 | =head1 SYNOPSIS | |
6 | ||
7 | =for html | |
8 | <div class="synopsis"> | |
9 | ||
10 | B<bos listkeys> S<<< B<-server> <I<machine name>> >>> [B<-showkey>] | |
11 | S<<< [B<-cell> <I<cell name>>] >>> [B<-noauth>] [B<-localauth>] [B<-help>] | |
12 | ||
13 | B<bos listk> S<<< B<-se> <I<machine name>> >>> [B<-sh>] S<<< [B<-c> <I<cell name>>] >>> | |
14 | [B<-n>] [B<-l>] [B<-h>] | |
15 | ||
16 | =for html | |
17 | </div> | |
18 | ||
19 | =head1 DESCRIPTION | |
20 | ||
21 | The B<bos listkeys> command formats and displays the list of server | |
22 | encryption keys from the F</usr/afs/etc/KeyFile> file on the server | |
23 | machine named by the B<-server> argument. It is equivalent to B<asetkey | |
24 | list>, but can be run remotely. | |
25 | ||
26 | To edit the list of keys, use the B<asetkey> command; see L<asetkey(8)> | |
27 | for more information. You can also remove keys remotely using the B<bos | |
28 | removekey> command. If you are using the Authentication Server | |
29 | (B<kaserver>) rather than a Kerberos v5 KDC, use the B<bos addkey> command | |
30 | instead of B<asetkey> to add a new key. | |
31 | ||
32 | =head1 CAUTIONS | |
33 | ||
34 | Displaying actual keys on the standard output stream (by including the | |
35 | B<-showkey> flag) is a security exposure. Displaying a checksum is | |
36 | sufficient for most purposes. | |
37 | ||
38 | This command will only list keys in the F<KeyFile>; it cannot display | |
39 | keys from a F<KeyFileExt>. A server running a modern, secure installation | |
40 | using only keys for the rxkad-k5 extension will yield no keys in | |
41 | the output of this command. | |
42 | ||
43 | =head1 OPTIONS | |
44 | ||
45 | =over 4 | |
46 | ||
47 | =item B<-server> <I<machine name>> | |
48 | ||
49 | Indicates the server machine from which to display the KeyFile | |
50 | file. Identify the machine by IP address or its host name (either | |
51 | fully-qualified or abbreviated unambiguously). For details, see L<bos(8)>. | |
52 | ||
53 | For consistent performance in the cell, the output must be the same on | |
54 | every server machine. L<asetkey(8)> explains how to keep the machines | |
55 | synchronized. | |
56 | ||
57 | =item B<-showkey> | |
58 | ||
59 | Displays the octal digits that constitute each key. Anyone who has access | |
60 | to the resulting output will have complete access to the AFS cell and will | |
61 | be able to impersonate the AFS cell to any client, so be very careful when | |
62 | using this option. | |
63 | ||
64 | =item B<-cell> <I<cell name>> | |
65 | ||
66 | Names the cell in which to run the command. Do not combine this argument | |
67 | with the B<-localauth> flag. For more details, see L<bos(8)>. | |
68 | ||
69 | =item B<-noauth> | |
70 | ||
71 | Assigns the unprivileged identity C<anonymous> to the issuer. Do not | |
72 | combine this flag with the B<-localauth> flag. For more details, see | |
73 | L<bos(8)>. | |
74 | ||
75 | =item B<-localauth> | |
76 | ||
77 | Constructs a server ticket using a key from the local | |
78 | F</usr/afs/etc/KeyFile> or F</usr/afs/etc/KeyFileExt> file. | |
79 | The B<bos> command interpreter presents the | |
80 | ticket to the BOS Server during mutual authentication. Do not combine this | |
81 | flag with the B<-cell> or B<-noauth> options. For more details, see | |
82 | L<bos(8)>. | |
83 | ||
84 | =item B<-help> | |
85 | ||
86 | Prints the online help for this command. All other valid options are | |
87 | ignored. | |
88 | ||
89 | =back | |
90 | ||
91 | =head1 OUTPUT | |
92 | ||
93 | The output includes one line for each server encryption key listed in the | |
94 | F<KeyFile> file, identified by its key version number. | |
95 | ||
96 | If the B<-showkey> flag is included, the output displays the actual string | |
97 | of eight octal numbers that constitute the key. Each octal number is a | |
98 | backslash and three decimal digits. | |
99 | ||
100 | If the B<-showkey> flag is not included, the output represents each key as | |
101 | a checksum, which is a decimal number derived by encrypting a constant | |
102 | with the key. | |
103 | ||
104 | Following the list of keys or checksums, the string C<Keys last changed> | |
105 | indicates when a key was last added to the F<KeyFile> file. The words | |
106 | C<All done> indicate the end of the output. | |
107 | ||
108 | For mutual authentication to work properly, the output from the command | |
109 | C<kas examine afs> must match the key or checksum with the same key | |
110 | version number in the output from this command. | |
111 | ||
112 | =head1 EXAMPLES | |
113 | ||
114 | The following example shows the checksums for the keys stored in the | |
115 | F<KeyFile> file on the machine C<fs3.example.com>. | |
116 | ||
117 | % bos listkeys fs3.example.com | |
118 | key 1 has cksum 972037177 | |
119 | key 3 has cksum 2825175022 | |
120 | key 4 has cksum 260617746 | |
121 | key 6 has cksum 4178774593 | |
122 | Keys last changed on Mon Apr 12 11:24:46 1999. | |
123 | All done. | |
124 | ||
125 | The following example shows the actual keys from the F<KeyFile> file on | |
126 | the machine C<fs6.example.com>. | |
127 | ||
128 | % bos listkeys fs6.example.com -showkey | |
129 | key 0 is '\040\205\211\241\345\002\023\211' | |
130 | key 1 is '\343\315\307\227\255\320\135\244' | |
131 | key 2 is '\310\310\255\253\326\236\261\211' | |
132 | Keys last changed on Wed Mar 31 11:24:46 1999. | |
133 | All done. | |
134 | ||
135 | =head1 PRIVILEGE REQUIRED | |
136 | ||
137 | The issuer must be listed in the F</usr/afs/etc/UserList> file on the | |
138 | machine named by the B<-server> argument, or must be logged onto a server | |
139 | machine as the local superuser C<root> if the B<-localauth> flag is | |
140 | included. | |
141 | ||
142 | =head1 SEE ALSO | |
143 | ||
144 | L<KeyFile(5)>, | |
145 | L<KeyFileExt(5)>, | |
146 | L<UserList(5)>, | |
147 | L<asetkey(8)>, | |
148 | L<bos_addkey(8)>, | |
149 | L<bos_removekey(8)>, | |
150 | L<bos_setauth(8)>, | |
151 | L<kas_examine(8)> | |
152 | ||
153 | =head1 COPYRIGHT | |
154 | ||
155 | IBM Corporation 2000. <http://www.ibm.com/> All Rights Reserved. | |
156 | ||
157 | This documentation is covered by the IBM Public License Version 1.0. It | |
158 | was converted from HTML to POD by software written by Chas Williams and | |
159 | Russ Allbery, based on work by Alf Wachsmann and Elizabeth Cassell. |