/mandos/release

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

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