/mandos/trunk

To get this branch, use:
bzr branch http://bzr.recompile.se/loggerhead/mandos/trunk

« back to all changes in this revision

Viewing changes to mandos-keygen.xml

merge

Show diffs side-by-side

added added

removed removed

Lines of Context:
1
1
<?xml version="1.0" encoding="UTF-8"?>
2
2
<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
3
3
        "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
 
4
<!ENTITY VERSION "1.0">
4
5
<!ENTITY COMMANDNAME "mandos-keygen">
5
 
<!ENTITY TIMESTAMP "2019-07-18">
6
 
<!ENTITY % common SYSTEM "common.ent">
7
 
%common;
 
6
<!ENTITY TIMESTAMP "2008-08-29">
8
7
]>
9
8
 
10
9
<refentry xmlns:xi="http://www.w3.org/2001/XInclude">
12
11
    <title>Mandos Manual</title>
13
12
    <!-- NWalsh’s docbook scripts use this to generate the footer: -->
14
13
    <productname>Mandos</productname>
15
 
    <productnumber>&version;</productnumber>
 
14
    <productnumber>&VERSION;</productnumber>
16
15
    <date>&TIMESTAMP;</date>
17
16
    <authorgroup>
18
17
      <author>
19
18
        <firstname>Björn</firstname>
20
19
        <surname>Påhlsson</surname>
21
20
        <address>
22
 
          <email>belorn@recompile.se</email>
 
21
          <email>belorn@fukt.bsnet.se</email>
23
22
        </address>
24
23
      </author>
25
24
      <author>
26
25
        <firstname>Teddy</firstname>
27
26
        <surname>Hogeborn</surname>
28
27
        <address>
29
 
          <email>teddy@recompile.se</email>
 
28
          <email>teddy@fukt.bsnet.se</email>
30
29
        </address>
31
30
      </author>
32
31
    </authorgroup>
33
32
    <copyright>
34
33
      <year>2008</year>
35
 
      <year>2009</year>
36
 
      <year>2010</year>
37
 
      <year>2011</year>
38
 
      <year>2012</year>
39
 
      <year>2013</year>
40
 
      <year>2014</year>
41
 
      <year>2015</year>
42
 
      <year>2016</year>
43
 
      <year>2017</year>
44
 
      <year>2018</year>
45
 
      <year>2019</year>
46
34
      <holder>Teddy Hogeborn</holder>
47
35
      <holder>Björn Påhlsson</holder>
48
36
    </copyright>
49
 
    <xi:include href="legalnotice.xml"/>
 
37
    <legalnotice>
 
38
      <para>
 
39
        This manual page is free software: you can redistribute it
 
40
        and/or modify it under the terms of the GNU General Public
 
41
        License as published by the Free Software Foundation,
 
42
        either version 3 of the License, or (at your option) any
 
43
        later version.
 
44
      </para>
 
45
 
 
46
      <para>
 
47
        This manual page is distributed in the hope that it will
 
48
        be useful, but WITHOUT ANY WARRANTY; without even the
 
49
        implied warranty of MERCHANTABILITY or FITNESS FOR A
 
50
        PARTICULAR PURPOSE.  See the GNU General Public License
 
51
        for more details.
 
52
      </para>
 
53
 
 
54
      <para>
 
55
        You should have received a copy of the GNU General Public
 
56
        License along with this program; If not, see
 
57
        <ulink url="http://www.gnu.org/licenses/"/>.
 
58
      </para>
 
59
    </legalnotice>
50
60
  </refentryinfo>
51
 
  
 
61
 
52
62
  <refmeta>
53
63
    <refentrytitle>&COMMANDNAME;</refentrytitle>
54
64
    <manvolnum>8</manvolnum>
57
67
  <refnamediv>
58
68
    <refname><command>&COMMANDNAME;</command></refname>
59
69
    <refpurpose>
60
 
      Generate key and password for Mandos client and server.
 
70
      Generate keys for <citerefentry><refentrytitle>password-request
 
71
      </refentrytitle><manvolnum>8mandos</manvolnum></citerefentry>
61
72
    </refpurpose>
62
73
  </refnamediv>
63
 
  
 
74
 
64
75
  <refsynopsisdiv>
65
76
    <cmdsynopsis>
66
77
      <command>&COMMANDNAME;</command>
67
 
      <group>
68
 
        <arg choice="plain"><option>--dir
69
 
        <replaceable>DIRECTORY</replaceable></option></arg>
70
 
        <arg choice="plain"><option>-d
71
 
        <replaceable>DIRECTORY</replaceable></option></arg>
72
 
      </group>
73
 
      <sbr/>
74
 
      <group>
75
 
        <arg choice="plain"><option>--type
76
 
        <replaceable>KEYTYPE</replaceable></option></arg>
77
 
        <arg choice="plain"><option>-t
78
 
        <replaceable>KEYTYPE</replaceable></option></arg>
79
 
      </group>
80
 
      <sbr/>
81
 
      <group>
82
 
        <arg choice="plain"><option>--length
83
 
        <replaceable>BITS</replaceable></option></arg>
84
 
        <arg choice="plain"><option>-l
85
 
        <replaceable>BITS</replaceable></option></arg>
86
 
      </group>
87
 
      <sbr/>
88
 
      <group>
89
 
        <arg choice="plain"><option>--subtype
90
 
        <replaceable>KEYTYPE</replaceable></option></arg>
91
 
        <arg choice="plain"><option>-s
92
 
        <replaceable>KEYTYPE</replaceable></option></arg>
93
 
      </group>
94
 
      <sbr/>
95
 
      <group>
96
 
        <arg choice="plain"><option>--sublength
97
 
        <replaceable>BITS</replaceable></option></arg>
98
 
        <arg choice="plain"><option>-L
99
 
        <replaceable>BITS</replaceable></option></arg>
100
 
      </group>
101
 
      <sbr/>
102
 
      <group>
103
 
        <arg choice="plain"><option>--name
104
 
        <replaceable>NAME</replaceable></option></arg>
105
 
        <arg choice="plain"><option>-n
106
 
        <replaceable>NAME</replaceable></option></arg>
107
 
      </group>
108
 
      <sbr/>
109
 
      <group>
110
 
        <arg choice="plain"><option>--email
111
 
        <replaceable>ADDRESS</replaceable></option></arg>
112
 
        <arg choice="plain"><option>-e
113
 
        <replaceable>ADDRESS</replaceable></option></arg>
114
 
      </group>
115
 
      <sbr/>
116
 
      <group>
117
 
        <arg choice="plain"><option>--comment
118
 
        <replaceable>TEXT</replaceable></option></arg>
119
 
        <arg choice="plain"><option>-c
120
 
        <replaceable>TEXT</replaceable></option></arg>
121
 
      </group>
122
 
      <sbr/>
123
 
      <group>
124
 
        <arg choice="plain"><option>--expire
125
 
        <replaceable>TIME</replaceable></option></arg>
126
 
        <arg choice="plain"><option>-x
127
 
        <replaceable>TIME</replaceable></option></arg>
128
 
      </group>
129
 
      <sbr/>
130
 
      <group>
131
 
        <arg choice="plain"><option>--tls-keytype
132
 
        <replaceable>KEYTYPE</replaceable></option></arg>
133
 
        <arg choice="plain"><option>-T
134
 
        <replaceable>KEYTYPE</replaceable></option></arg>
135
 
      </group>
136
 
      <sbr/>
137
 
      <group>
 
78
      <group choice="opt">
 
79
        <arg choice="plain"><option>--dir</option>
 
80
        <replaceable>directory</replaceable></arg>
 
81
      </group>
 
82
      <group choice="opt">
 
83
        <arg choice="plain"><option>--type</option>
 
84
        <replaceable>type</replaceable></arg>
 
85
      </group>
 
86
      <group choice="opt">
 
87
        <arg choice="plain"><option>--length</option>
 
88
        <replaceable>bits</replaceable></arg>
 
89
      </group>
 
90
      <group choice="opt">
 
91
        <arg choice="plain"><option>--subtype</option>
 
92
        <replaceable>type</replaceable></arg>
 
93
      </group>
 
94
      <group choice="opt">
 
95
        <arg choice="plain"><option>--sublength</option>
 
96
        <replaceable>bits</replaceable></arg>
 
97
      </group>
 
98
      <group choice="opt">
 
99
        <arg choice="plain"><option>--name</option>
 
100
        <replaceable>NAME</replaceable></arg>
 
101
      </group>
 
102
      <group choice="opt">
 
103
        <arg choice="plain"><option>--email</option>
 
104
        <replaceable>EMAIL</replaceable></arg>
 
105
      </group>
 
106
      <group choice="opt">
 
107
        <arg choice="plain"><option>--comment</option>
 
108
        <replaceable>COMMENT</replaceable></arg>
 
109
      </group>
 
110
      <group choice="opt">
 
111
        <arg choice="plain"><option>--expire</option>
 
112
        <replaceable>TIME</replaceable></arg>
 
113
      </group>
 
114
      <group choice="opt">
138
115
        <arg choice="plain"><option>--force</option></arg>
 
116
      </group>
 
117
    </cmdsynopsis>
 
118
    <cmdsynopsis>
 
119
      <command>&COMMANDNAME;</command>
 
120
      <group choice="opt">
 
121
        <arg choice="plain"><option>-d</option>
 
122
        <replaceable>directory</replaceable></arg>
 
123
      </group>
 
124
      <group choice="opt">
 
125
        <arg choice="plain"><option>-t</option>
 
126
        <replaceable>type</replaceable></arg>
 
127
      </group>
 
128
      <group choice="opt">
 
129
        <arg choice="plain"><option>-l</option>
 
130
        <replaceable>bits</replaceable></arg>
 
131
      </group>
 
132
      <group choice="opt">
 
133
        <arg choice="plain"><option>-s</option>
 
134
        <replaceable>type</replaceable></arg>
 
135
      </group>
 
136
      <group choice="opt">
 
137
        <arg choice="plain"><option>-L</option>
 
138
        <replaceable>bits</replaceable></arg>
 
139
      </group>
 
140
      <group choice="opt">
 
141
        <arg choice="plain"><option>-n</option>
 
142
        <replaceable>NAME</replaceable></arg>
 
143
      </group>
 
144
      <group choice="opt">
 
145
        <arg choice="plain"><option>-e</option>
 
146
        <replaceable>EMAIL</replaceable></arg>
 
147
      </group>
 
148
      <group choice="opt">
 
149
        <arg choice="plain"><option>-c</option>
 
150
        <replaceable>COMMENT</replaceable></arg>
 
151
      </group>
 
152
      <group choice="opt">
 
153
        <arg choice="plain"><option>-x</option>
 
154
        <replaceable>TIME</replaceable></arg>
 
155
      </group>
 
156
      <group choice="opt">
139
157
        <arg choice="plain"><option>-f</option></arg>
140
158
      </group>
141
159
    </cmdsynopsis>
142
160
    <cmdsynopsis>
143
161
      <command>&COMMANDNAME;</command>
144
162
      <group choice="req">
 
163
        <arg choice="plain"><option>-p</option></arg>
145
164
        <arg choice="plain"><option>--password</option></arg>
146
 
        <arg choice="plain"><option>-p</option></arg>
147
 
        <arg choice="plain"><option>--passfile
148
 
        <replaceable>FILE</replaceable></option></arg>
149
 
        <arg choice="plain"><option>-F</option>
150
 
        <replaceable>FILE</replaceable></arg>
151
 
      </group>
152
 
      <sbr/>
153
 
      <group>
154
 
        <arg choice="plain"><option>--dir
155
 
        <replaceable>DIRECTORY</replaceable></option></arg>
156
 
        <arg choice="plain"><option>-d
157
 
        <replaceable>DIRECTORY</replaceable></option></arg>
158
 
      </group>
159
 
      <sbr/>
160
 
      <group>
161
 
        <arg choice="plain"><option>--name
162
 
        <replaceable>NAME</replaceable></option></arg>
163
 
        <arg choice="plain"><option>-n
164
 
        <replaceable>NAME</replaceable></option></arg>
165
 
      </group>
166
 
      <group>
167
 
        <arg choice="plain"><option>--no-ssh</option></arg>
168
 
        <arg choice="plain"><option>-S</option></arg>
 
165
      </group>
 
166
      <group choice="opt">
 
167
        <arg choice="plain"><option>--dir</option>
 
168
        <replaceable>directory</replaceable></arg>
 
169
      </group>
 
170
      <group choice="opt">
 
171
        <arg choice="plain"><option>--name</option>
 
172
        <replaceable>NAME</replaceable></arg>
169
173
      </group>
170
174
    </cmdsynopsis>
171
175
    <cmdsynopsis>
172
176
      <command>&COMMANDNAME;</command>
173
177
      <group choice="req">
 
178
        <arg choice="plain"><option>-h</option></arg>
174
179
        <arg choice="plain"><option>--help</option></arg>
175
 
        <arg choice="plain"><option>-h</option></arg>
176
180
      </group>
177
181
    </cmdsynopsis>
178
182
    <cmdsynopsis>
179
183
      <command>&COMMANDNAME;</command>
180
184
      <group choice="req">
 
185
        <arg choice="plain"><option>-v</option></arg>
181
186
        <arg choice="plain"><option>--version</option></arg>
182
 
        <arg choice="plain"><option>-v</option></arg>
183
187
      </group>
184
188
    </cmdsynopsis>
185
189
  </refsynopsisdiv>
186
 
  
 
190
 
187
191
  <refsect1 id="description">
188
192
    <title>DESCRIPTION</title>
189
193
    <para>
190
194
      <command>&COMMANDNAME;</command> is a program to generate the
191
 
      TLS and OpenPGP keys used by
192
 
      <citerefentry><refentrytitle>mandos-client</refentrytitle>
 
195
      OpenPGP keys used by
 
196
      <citerefentry><refentrytitle>password-request</refentrytitle>
193
197
      <manvolnum>8mandos</manvolnum></citerefentry>.  The keys are
194
 
      normally written to /etc/keys/mandos for later installation into
195
 
      the initrd image, but this, and most other things, can be
196
 
      changed with command line options.
 
198
      normally written to /etc/mandos for later installation into the
 
199
      initrd image, but this, like most things, can be changed with
 
200
      command line options.
197
201
    </para>
198
202
    <para>
199
 
      This program can also be used with the
200
 
      <option>--password</option> or <option>--passfile</option>
201
 
      options to generate a ready-made section for
202
 
      <filename>clients.conf</filename> (see
 
203
      It can also be used to generate ready-made sections for
203
204
      <citerefentry><refentrytitle>mandos-clients.conf</refentrytitle>
204
 
      <manvolnum>5</manvolnum></citerefentry>).
 
205
      <manvolnum>5</manvolnum></citerefentry> using the
 
206
      <option>--password</option> option.
205
207
    </para>
206
208
  </refsect1>
207
209
  
208
210
  <refsect1 id="purpose">
209
211
    <title>PURPOSE</title>
 
212
 
210
213
    <para>
211
214
      The purpose of this is to enable <emphasis>remote and unattended
212
215
      rebooting</emphasis> of client host computer with an
213
216
      <emphasis>encrypted root file system</emphasis>.  See <xref
214
217
      linkend="overview"/> for details.
215
218
    </para>
 
219
 
216
220
  </refsect1>
217
221
  
218
222
  <refsect1 id="options">
219
223
    <title>OPTIONS</title>
220
 
    
 
224
 
221
225
    <variablelist>
222
226
      <varlistentry>
223
 
        <term><option>--help</option></term>
224
 
        <term><option>-h</option></term>
 
227
        <term><literal>-h</literal>, <literal>--help</literal></term>
225
228
        <listitem>
226
229
          <para>
227
230
            Show a help message and exit
228
231
          </para>
229
232
        </listitem>
230
233
      </varlistentry>
231
 
      
232
 
      <varlistentry>
233
 
        <term><option>--dir
234
 
        <replaceable>DIRECTORY</replaceable></option></term>
235
 
        <term><option>-d
236
 
        <replaceable>DIRECTORY</replaceable></option></term>
237
 
        <listitem>
238
 
          <para>
239
 
            Target directory for key files.  Default is <filename
240
 
            class="directory">/etc/keys/mandos</filename>.
241
 
          </para>
242
 
        </listitem>
243
 
      </varlistentry>
244
 
      
245
 
      <varlistentry>
246
 
        <term><option>--type
247
 
        <replaceable>TYPE</replaceable></option></term>
248
 
        <term><option>-t
249
 
        <replaceable>TYPE</replaceable></option></term>
250
 
        <listitem>
251
 
          <para>
252
 
            OpenPGP key type.  Default is <quote>RSA</quote>.
253
 
          </para>
254
 
        </listitem>
255
 
      </varlistentry>
256
 
      
257
 
      <varlistentry>
258
 
        <term><option>--length
259
 
        <replaceable>BITS</replaceable></option></term>
260
 
        <term><option>-l
261
 
        <replaceable>BITS</replaceable></option></term>
262
 
        <listitem>
263
 
          <para>
264
 
            OpenPGP key length in bits.  Default is 4096.
265
 
          </para>
266
 
        </listitem>
267
 
      </varlistentry>
268
 
      
269
 
      <varlistentry>
270
 
        <term><option>--subtype
271
 
        <replaceable>KEYTYPE</replaceable></option></term>
272
 
        <term><option>-s
273
 
        <replaceable>KEYTYPE</replaceable></option></term>
274
 
        <listitem>
275
 
          <para>
276
 
            OpenPGP subkey type.  Default is <quote>RSA</quote>
277
 
          </para>
278
 
        </listitem>
279
 
      </varlistentry>
280
 
      
281
 
      <varlistentry>
282
 
        <term><option>--sublength
283
 
        <replaceable>BITS</replaceable></option></term>
284
 
        <term><option>-L
285
 
        <replaceable>BITS</replaceable></option></term>
286
 
        <listitem>
287
 
          <para>
288
 
            OpenPGP subkey length in bits.  Default is 4096.
289
 
          </para>
290
 
        </listitem>
291
 
      </varlistentry>
292
 
      
293
 
      <varlistentry>
294
 
        <term><option>--email
295
 
        <replaceable>ADDRESS</replaceable></option></term>
296
 
        <term><option>-e
297
 
        <replaceable>ADDRESS</replaceable></option></term>
 
234
 
 
235
      <varlistentry>
 
236
        <term><literal>-d</literal>, <literal>--dir
 
237
        <replaceable>directory</replaceable></literal></term>
 
238
        <listitem>
 
239
          <para>
 
240
            Target directory for key files.  Default is
 
241
            <filename>/etc/mandos</filename>.
 
242
          </para>
 
243
        </listitem>
 
244
      </varlistentry>
 
245
 
 
246
      <varlistentry>
 
247
        <term><literal>-t</literal>, <literal>--type
 
248
        <replaceable>type</replaceable></literal></term>
 
249
        <listitem>
 
250
          <para>
 
251
            Key type.  Default is <quote>DSA</quote>.
 
252
          </para>
 
253
        </listitem>
 
254
      </varlistentry>
 
255
 
 
256
      <varlistentry>
 
257
        <term><literal>-l</literal>, <literal>--length
 
258
        <replaceable>bits</replaceable></literal></term>
 
259
        <listitem>
 
260
          <para>
 
261
            Key length in bits.  Default is 2048.
 
262
          </para>
 
263
        </listitem>
 
264
      </varlistentry>
 
265
 
 
266
      <varlistentry>
 
267
        <term><literal>-s</literal>, <literal>--subtype
 
268
        <replaceable>type</replaceable></literal></term>
 
269
        <listitem>
 
270
          <para>
 
271
            Subkey type.  Default is <quote>ELG-E</quote> (Elgamal
 
272
            encryption-only).
 
273
          </para>
 
274
        </listitem>
 
275
      </varlistentry>
 
276
 
 
277
      <varlistentry>
 
278
        <term><literal>-L</literal>, <literal>--sublength
 
279
        <replaceable>bits</replaceable></literal></term>
 
280
        <listitem>
 
281
          <para>
 
282
            Subkey length in bits.  Default is 2048.
 
283
          </para>
 
284
        </listitem>
 
285
      </varlistentry>
 
286
 
 
287
      <varlistentry>
 
288
        <term><literal>-e</literal>, <literal>--email</literal>
 
289
        <replaceable>address</replaceable></term>
298
290
        <listitem>
299
291
          <para>
300
292
            Email address of key.  Default is empty.
301
293
          </para>
302
294
        </listitem>
303
295
      </varlistentry>
304
 
      
 
296
 
305
297
      <varlistentry>
306
 
        <term><option>--comment
307
 
        <replaceable>TEXT</replaceable></option></term>
308
 
        <term><option>-c
309
 
        <replaceable>TEXT</replaceable></option></term>
 
298
        <term><literal>-c</literal>, <literal>--comment</literal>
 
299
        <replaceable>comment</replaceable></term>
310
300
        <listitem>
311
301
          <para>
312
 
            Comment field for key.  Default is empty.
 
302
            Comment field for key.  The default value is
 
303
            <quote><literal>Mandos client key</literal></quote>.
313
304
          </para>
314
305
        </listitem>
315
306
      </varlistentry>
316
 
      
 
307
 
317
308
      <varlistentry>
318
 
        <term><option>--expire
319
 
        <replaceable>TIME</replaceable></option></term>
320
 
        <term><option>-x
321
 
        <replaceable>TIME</replaceable></option></term>
 
309
        <term><literal>-x</literal>, <literal>--expire</literal>
 
310
        <replaceable>time</replaceable></term>
322
311
        <listitem>
323
312
          <para>
324
313
            Key expire time.  Default is no expiration.  See
327
316
          </para>
328
317
        </listitem>
329
318
      </varlistentry>
330
 
      
331
 
      <varlistentry>
332
 
        <term><option>--tls-keytype
333
 
        <replaceable>KEYTYPE</replaceable></option></term>
334
 
        <term><option>-T
335
 
        <replaceable>KEYTYPE</replaceable></option></term>
336
 
        <listitem>
337
 
          <para>
338
 
            TLS key type.  Default is <quote>ed25519</quote>
339
 
          </para>
340
 
        </listitem>
341
 
      </varlistentry>
342
 
      
343
 
      <varlistentry>
344
 
        <term><option>--force</option></term>
345
 
        <term><option>-f</option></term>
346
 
        <listitem>
347
 
          <para>
348
 
            Force overwriting old key.
349
 
          </para>
350
 
        </listitem>
351
 
      </varlistentry>
352
 
      <varlistentry>
353
 
        <term><option>--password</option></term>
354
 
        <term><option>-p</option></term>
 
319
 
 
320
      <varlistentry>
 
321
        <term><literal>-f</literal>, <literal>--force</literal></term>
 
322
        <listitem>
 
323
          <para>
 
324
            Force overwriting old keys.
 
325
          </para>
 
326
        </listitem>
 
327
      </varlistentry>
 
328
      <varlistentry>
 
329
        <term><literal>-p</literal>, <literal>--password</literal
 
330
        ></term>
355
331
        <listitem>
356
332
          <para>
357
333
            Prompt for a password and encrypt it with the key already
358
 
            present in either <filename>/etc/keys/mandos</filename> or
359
 
            the directory specified with the <option>--dir</option>
 
334
            present in either <filename>/etc/mandos</filename> or the
 
335
            directory specified with the <option>--dir</option>
360
336
            option.  Outputs, on standard output, a section suitable
361
337
            for inclusion in <citerefentry><refentrytitle
362
338
            >mandos-clients.conf</refentrytitle><manvolnum
363
339
            >8</manvolnum></citerefentry>.  The host name or the name
364
340
            specified with the <option>--name</option> option is used
365
341
            for the section header.  All other options are ignored,
366
 
            and no key is created.  Note: white space is stripped from
367
 
            the beginning and from the end of the password; See <xref
368
 
            linkend="bugs"/>.
369
 
          </para>
370
 
        </listitem>
371
 
      </varlistentry>
372
 
      <varlistentry>
373
 
        <term><option>--passfile
374
 
        <replaceable>FILE</replaceable></option></term>
375
 
        <term><option>-F
376
 
        <replaceable>FILE</replaceable></option></term>
377
 
        <listitem>
378
 
          <para>
379
 
            The same as <option>--password</option>, but read from
380
 
            <replaceable>FILE</replaceable>, not the terminal, and
381
 
            white space is not stripped from the password in any way.
382
 
          </para>
383
 
        </listitem>
384
 
      </varlistentry>
385
 
      <varlistentry>
386
 
        <term><option>--no-ssh</option></term>
387
 
        <term><option>-S</option></term>
388
 
        <listitem>
389
 
          <para>
390
 
            When <option>--password</option> or
391
 
            <option>--passfile</option> is given, this option will
392
 
            prevent <command>&COMMANDNAME;</command> from calling
393
 
            <command>ssh-keyscan</command> to get an SSH fingerprint
394
 
            for this host and, if successful, output suitable config
395
 
            options to use this fingerprint as a
396
 
            <option>checker</option> option in the output.  This is
397
 
            otherwise the default behavior.
 
342
            and no keys are created.
398
343
          </para>
399
344
        </listitem>
400
345
      </varlistentry>
401
346
    </variablelist>
402
347
  </refsect1>
403
 
  
 
348
 
404
349
  <refsect1 id="overview">
405
350
    <title>OVERVIEW</title>
406
351
    <xi:include href="overview.xml"/>
407
352
    <para>
408
 
      This program is a small utility to generate new TLS and OpenPGP
409
 
      keys for new Mandos clients, and to generate sections for
410
 
      inclusion in <filename>clients.conf</filename> on the server.
 
353
      This program is a small utility to generate new OpenPGP keys for
 
354
      new Mandos clients.
411
355
    </para>
412
356
  </refsect1>
413
 
  
 
357
 
414
358
  <refsect1 id="exit_status">
415
359
    <title>EXIT STATUS</title>
416
360
    <para>
417
 
      The exit status will be 0 if a new key (or password, if the
418
 
      <option>--password</option> option was used) was successfully
419
 
      created, otherwise not.
 
361
      The exit status will be 0 if new keys were successfully created,
 
362
      otherwise not.
420
363
    </para>
421
364
  </refsect1>
422
365
  
424
367
    <title>ENVIRONMENT</title>
425
368
    <variablelist>
426
369
      <varlistentry>
427
 
        <term><envar>TMPDIR</envar></term>
 
370
        <term><varname>TMPDIR</varname></term>
428
371
        <listitem>
429
372
          <para>
430
373
            If set, temporary files will be created here. See
436
379
    </variablelist>
437
380
  </refsect1>
438
381
  
439
 
  <refsect1 id="files">
 
382
  <refsect1 id="file">
440
383
    <title>FILES</title>
441
384
    <para>
442
385
      Use the <option>--dir</option> option to change where
445
388
    </para>
446
389
    <variablelist>
447
390
      <varlistentry>
448
 
        <term><filename>/etc/keys/mandos/seckey.txt</filename></term>
 
391
        <term><filename>/etc/mandos/seckey.txt</filename></term>
449
392
        <listitem>
450
393
          <para>
451
394
            OpenPGP secret key file which will be created or
454
397
        </listitem>
455
398
      </varlistentry>
456
399
      <varlistentry>
457
 
        <term><filename>/etc/keys/mandos/pubkey.txt</filename></term>
 
400
        <term><filename>/etc/mandos/pubkey.txt</filename></term>
458
401
        <listitem>
459
402
          <para>
460
403
            OpenPGP public key file which will be created or
463
406
        </listitem>
464
407
      </varlistentry>
465
408
      <varlistentry>
466
 
        <term><filename>/etc/keys/mandos/tls-privkey.pem</filename></term>
467
 
        <listitem>
468
 
          <para>
469
 
            Private key file which will be created or overwritten.
470
 
          </para>
471
 
        </listitem>
472
 
      </varlistentry>
473
 
      <varlistentry>
474
 
        <term><filename>/etc/keys/mandos/tls-pubkey.pem</filename></term>
475
 
        <listitem>
476
 
          <para>
477
 
            Public key file which will be created or overwritten.
478
 
          </para>
479
 
        </listitem>
480
 
      </varlistentry>
481
 
      <varlistentry>
482
 
        <term><filename class="directory">/tmp</filename></term>
 
409
        <term><filename>/tmp</filename></term>
483
410
        <listitem>
484
411
          <para>
485
412
            Temporary files will be written here if
489
416
      </varlistentry>
490
417
    </variablelist>
491
418
  </refsect1>
492
 
  
 
419
 
493
420
  <refsect1 id="bugs">
494
421
    <title>BUGS</title>
495
422
    <para>
496
 
      The <option>--password</option>/<option>-p</option> option
497
 
      strips white space from the start and from the end of the
498
 
      password before using it.  If this is a problem, use the
499
 
      <option>--passfile</option> option instead, which does not do
500
 
      this.
 
423
      None are known at this time.
501
424
    </para>
502
 
    <xi:include href="bugs.xml"/>
503
425
  </refsect1>
504
 
  
 
426
 
505
427
  <refsect1 id="example">
506
428
    <title>EXAMPLE</title>
507
429
    <informalexample>
514
436
    </informalexample>
515
437
    <informalexample>
516
438
      <para>
517
 
        Create key in another directory and of another type.  Force
 
439
        Create keys in another directory and of another type.  Force
518
440
        overwriting old key files:
519
441
      </para>
520
442
      <para>
524
446
 
525
447
      </para>
526
448
    </informalexample>
527
 
    <informalexample>
528
 
      <para>
529
 
        Prompt for a password, encrypt it with the keys in <filename
530
 
        class="directory">/etc/keys/mandos</filename> and output a
531
 
        section suitable for <filename>clients.conf</filename>.
532
 
      </para>
533
 
      <para>
534
 
        <userinput>&COMMANDNAME; --password</userinput>
535
 
      </para>
536
 
    </informalexample>
537
 
    <informalexample>
538
 
      <para>
539
 
        Prompt for a password, encrypt it with the keys in the
540
 
        <filename>client-key</filename> directory and output a section
541
 
        suitable for <filename>clients.conf</filename>.
542
 
      </para>
543
 
      <para>
544
 
 
545
 
<!-- do not wrap this line -->
546
 
<userinput>&COMMANDNAME; --password --dir client-key</userinput>
547
 
 
548
 
      </para>
549
 
    </informalexample>
550
449
  </refsect1>
551
 
  
 
450
 
552
451
  <refsect1 id="security">
553
452
    <title>SECURITY</title>
554
453
    <para>
555
454
      The <option>--type</option>, <option>--length</option>,
556
455
      <option>--subtype</option>, and <option>--sublength</option>
557
 
      options can be used to create keys of low security.  If in
558
 
      doubt, leave them to the default values.
 
456
      options can be used to create keys of insufficient security.  If
 
457
      in doubt, leave them to the default values.
559
458
    </para>
560
459
    <para>
561
 
      The key expire time is <emphasis>not</emphasis> guaranteed to be
562
 
      honored by <citerefentry><refentrytitle>mandos</refentrytitle>
 
460
      The key expire time is not guaranteed to be honored by
 
461
      <citerefentry><refentrytitle>mandos</refentrytitle>
563
462
      <manvolnum>8</manvolnum></citerefentry>.
564
463
    </para>
565
464
  </refsect1>
566
 
  
 
465
 
567
466
  <refsect1 id="see_also">
568
467
    <title>SEE ALSO</title>
569
468
    <para>
570
 
      <citerefentry><refentrytitle>intro</refentrytitle>
571
 
      <manvolnum>8mandos</manvolnum></citerefentry>,
572
469
      <citerefentry><refentrytitle>gpg</refentrytitle>
573
470
      <manvolnum>1</manvolnum></citerefentry>,
574
 
      <citerefentry><refentrytitle>mandos-clients.conf</refentrytitle>
575
 
      <manvolnum>5</manvolnum></citerefentry>,
576
471
      <citerefentry><refentrytitle>mandos</refentrytitle>
577
472
      <manvolnum>8</manvolnum></citerefentry>,
578
 
      <citerefentry><refentrytitle>mandos-client</refentrytitle>
579
 
      <manvolnum>8mandos</manvolnum></citerefentry>,
580
 
      <citerefentry><refentrytitle>ssh-keyscan</refentrytitle>
581
 
      <manvolnum>1</manvolnum></citerefentry>
 
473
      <citerefentry><refentrytitle>password-request</refentrytitle>
 
474
      <manvolnum>8mandos</manvolnum></citerefentry>
582
475
    </para>
583
476
  </refsect1>
584
477