/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

  • Committer: Teddy Hogeborn
  • Date: 2019-07-29 16:35:53 UTC
  • Revision ID: teddy@recompile.se-20190729163553-1i442i2cbx64c537
Make tests and man page examples match

Make the tests test_manual_page_example[1-5] match exactly what is
written in the manual page, and add comments to manual page as
reminders to keep tests and manual page examples in sync.

* mandos-ctl (Test_commands_from_options.test_manual_page_example_1):
  Remove "--verbose" option, since the manual does not have it as the
  first example, and change assertion to match.
* mandos-ctl.xml (EXAMPLE): Add comments to all examples documenting
  which test function they correspond to.  Also remove unnecessary
  quotes from option arguments in fourth example, and clarify language
  slightly in fifth example.

Show diffs side-by-side

added added

removed removed

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