/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

  • Committer: Teddy Hogeborn
  • Date: 2019-04-22 20:19:28 UTC
  • mto: This revision was merged to the branch mainline in revision 384.
  • Revision ID: teddy@recompile.se-20190422201928-7vmdtipp0ddsr86r
mandos-ctl: Add tests for all examples in the manual page

* mandos-ctl (Test_commands_from_options.assert_command_from_args):
  Add "length" and "clients" arguments; use them.
  (Test_commands_from_options.assert_commands_from_args): New.
  (Test_commands_from_options.test_manual_page_example_1): - '' -
  (Test_commands_from_options.test_manual_page_example_2): - '' -
  (Test_commands_from_options.test_manual_page_example_3): - '' -
  (Test_commands_from_options.test_manual_page_example_4): - '' -
  (Test_commands_from_options.test_manual_page_example_5): - '' -

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">
5
4
<!ENTITY COMMANDNAME "mandos-keygen">
6
 
<!ENTITY TIMESTAMP "2008-08-31">
 
5
<!ENTITY TIMESTAMP "2019-02-10">
 
6
<!ENTITY % common SYSTEM "common.ent">
 
7
%common;
7
8
]>
8
9
 
9
10
<refentry xmlns:xi="http://www.w3.org/2001/XInclude">
11
12
    <title>Mandos Manual</title>
12
13
    <!-- NWalsh’s docbook scripts use this to generate the footer: -->
13
14
    <productname>Mandos</productname>
14
 
    <productnumber>&VERSION;</productnumber>
 
15
    <productnumber>&version;</productnumber>
15
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>
 
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>
34
46
      <holder>Teddy Hogeborn</holder>
35
47
      <holder>Björn Påhlsson</holder>
36
48
    </copyright>
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>
 
49
    <xi:include href="legalnotice.xml"/>
60
50
  </refentryinfo>
61
 
 
 
51
  
62
52
  <refmeta>
63
53
    <refentrytitle>&COMMANDNAME;</refentrytitle>
64
54
    <manvolnum>8</manvolnum>
70
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>
137
127
        <replaceable>TIME</replaceable></option></arg>
138
128
      </group>
139
129
      <sbr/>
140
 
      <arg><option>--force</option></arg>
 
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>
 
138
        <arg choice="plain"><option>--force</option></arg>
 
139
        <arg choice="plain"><option>-f</option></arg>
 
140
      </group>
141
141
    </cmdsynopsis>
142
142
    <cmdsynopsis>
143
143
      <command>&COMMANDNAME;</command>
144
144
      <group choice="req">
145
145
        <arg choice="plain"><option>--password</option></arg>
146
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>
147
151
      </group>
148
152
      <sbr/>
149
153
      <group>
159
163
        <arg choice="plain"><option>-n
160
164
        <replaceable>NAME</replaceable></option></arg>
161
165
      </group>
 
166
      <group>
 
167
        <arg choice="plain"><option>--no-ssh</option></arg>
 
168
        <arg choice="plain"><option>-S</option></arg>
 
169
      </group>
162
170
    </cmdsynopsis>
163
171
    <cmdsynopsis>
164
172
      <command>&COMMANDNAME;</command>
180
188
    <title>DESCRIPTION</title>
181
189
    <para>
182
190
      <command>&COMMANDNAME;</command> is a program to generate the
183
 
      OpenPGP key used by
184
 
      <citerefentry><refentrytitle>password-request</refentrytitle>
185
 
      <manvolnum>8mandos</manvolnum></citerefentry>.  The key is
186
 
      normally written to /etc/mandos for later installation into the
187
 
      initrd image, but this, and most other things, can be changed
188
 
      with command line options.
 
191
      TLS and OpenPGP keys used by
 
192
      <citerefentry><refentrytitle>mandos-client</refentrytitle>
 
193
      <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.
189
197
    </para>
190
198
    <para>
191
199
      This program can also be used with the
192
 
      <option>--password</option> option to generate a ready-made
193
 
      section for <filename>clients.conf</filename> (see
 
200
      <option>--password</option> or <option>--passfile</option>
 
201
      options to generate a ready-made section for
 
202
      <filename>clients.conf</filename> (see
194
203
      <citerefentry><refentrytitle>mandos-clients.conf</refentrytitle>
195
204
      <manvolnum>5</manvolnum></citerefentry>).
196
205
    </para>
219
228
          </para>
220
229
        </listitem>
221
230
      </varlistentry>
222
 
 
 
231
      
223
232
      <varlistentry>
224
233
        <term><option>--dir
225
234
        <replaceable>DIRECTORY</replaceable></option></term>
227
236
        <replaceable>DIRECTORY</replaceable></option></term>
228
237
        <listitem>
229
238
          <para>
230
 
            Target directory for key files.  Default is
231
 
            <filename>/etc/mandos</filename>.
 
239
            Target directory for key files.  Default is <filename
 
240
            class="directory">/etc/keys/mandos</filename>.
232
241
          </para>
233
242
        </listitem>
234
243
      </varlistentry>
235
 
 
 
244
      
236
245
      <varlistentry>
237
246
        <term><option>--type
238
247
        <replaceable>TYPE</replaceable></option></term>
240
249
        <replaceable>TYPE</replaceable></option></term>
241
250
        <listitem>
242
251
          <para>
243
 
            Key type.  Default is <quote>DSA</quote>.
 
252
            OpenPGP key type.  Default is <quote>RSA</quote>.
244
253
          </para>
245
254
        </listitem>
246
255
      </varlistentry>
247
 
 
 
256
      
248
257
      <varlistentry>
249
258
        <term><option>--length
250
259
        <replaceable>BITS</replaceable></option></term>
252
261
        <replaceable>BITS</replaceable></option></term>
253
262
        <listitem>
254
263
          <para>
255
 
            Key length in bits.  Default is 2048.
 
264
            OpenPGP key length in bits.  Default is 4096.
256
265
          </para>
257
266
        </listitem>
258
267
      </varlistentry>
259
 
 
 
268
      
260
269
      <varlistentry>
261
270
        <term><option>--subtype
262
271
        <replaceable>KEYTYPE</replaceable></option></term>
264
273
        <replaceable>KEYTYPE</replaceable></option></term>
265
274
        <listitem>
266
275
          <para>
267
 
            Subkey type.  Default is <quote>ELG-E</quote> (Elgamal
268
 
            encryption-only).
 
276
            OpenPGP subkey type.  Default is <quote>RSA</quote>
269
277
          </para>
270
278
        </listitem>
271
279
      </varlistentry>
272
 
 
 
280
      
273
281
      <varlistentry>
274
282
        <term><option>--sublength
275
283
        <replaceable>BITS</replaceable></option></term>
277
285
        <replaceable>BITS</replaceable></option></term>
278
286
        <listitem>
279
287
          <para>
280
 
            Subkey length in bits.  Default is 2048.
 
288
            OpenPGP subkey length in bits.  Default is 4096.
281
289
          </para>
282
290
        </listitem>
283
291
      </varlistentry>
284
 
 
 
292
      
285
293
      <varlistentry>
286
294
        <term><option>--email
287
295
        <replaceable>ADDRESS</replaceable></option></term>
293
301
          </para>
294
302
        </listitem>
295
303
      </varlistentry>
296
 
 
 
304
      
297
305
      <varlistentry>
298
306
        <term><option>--comment
299
307
        <replaceable>TEXT</replaceable></option></term>
301
309
        <replaceable>TEXT</replaceable></option></term>
302
310
        <listitem>
303
311
          <para>
304
 
            Comment field for key.  The default value is
305
 
            <quote><literal>Mandos client key</literal></quote>.
 
312
            Comment field for key.  Default is empty.
306
313
          </para>
307
314
        </listitem>
308
315
      </varlistentry>
309
 
 
 
316
      
310
317
      <varlistentry>
311
318
        <term><option>--expire
312
319
        <replaceable>TIME</replaceable></option></term>
320
327
          </para>
321
328
        </listitem>
322
329
      </varlistentry>
323
 
 
 
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
      
324
343
      <varlistentry>
325
344
        <term><option>--force</option></term>
326
345
        <term><option>-f</option></term>
336
355
        <listitem>
337
356
          <para>
338
357
            Prompt for a password and encrypt it with the key already
339
 
            present in either <filename>/etc/mandos</filename> or the
340
 
            directory specified with the <option>--dir</option>
 
358
            present in either <filename>/etc/keys/mandos</filename> or
 
359
            the directory specified with the <option>--dir</option>
341
360
            option.  Outputs, on standard output, a section suitable
342
361
            for inclusion in <citerefentry><refentrytitle
343
362
            >mandos-clients.conf</refentrytitle><manvolnum
348
367
          </para>
349
368
        </listitem>
350
369
      </varlistentry>
 
370
      <varlistentry>
 
371
        <term><option>--passfile
 
372
        <replaceable>FILE</replaceable></option></term>
 
373
        <term><option>-F
 
374
        <replaceable>FILE</replaceable></option></term>
 
375
        <listitem>
 
376
          <para>
 
377
            The same as <option>--password</option>, but read from
 
378
            <replaceable>FILE</replaceable>, not the terminal.
 
379
          </para>
 
380
        </listitem>
 
381
      </varlistentry>
 
382
      <varlistentry>
 
383
        <term><option>--no-ssh</option></term>
 
384
        <term><option>-S</option></term>
 
385
        <listitem>
 
386
          <para>
 
387
            When <option>--password</option> or
 
388
            <option>--passfile</option> is given, this option will
 
389
            prevent <command>&COMMANDNAME;</command> from calling
 
390
            <command>ssh-keyscan</command> to get an SSH fingerprint
 
391
            for this host and, if successful, output suitable config
 
392
            options to use this fingerprint as a
 
393
            <option>checker</option> option in the output.  This is
 
394
            otherwise the default behavior.
 
395
          </para>
 
396
        </listitem>
 
397
      </varlistentry>
351
398
    </variablelist>
352
399
  </refsect1>
353
 
 
 
400
  
354
401
  <refsect1 id="overview">
355
402
    <title>OVERVIEW</title>
356
403
    <xi:include href="overview.xml"/>
357
404
    <para>
358
 
      This program is a small utility to generate new OpenPGP keys for
359
 
      new Mandos clients, and to generate sections for inclusion in
360
 
      <filename>clients.conf</filename> on the server.
 
405
      This program is a small utility to generate new TLS and OpenPGP
 
406
      keys for new Mandos clients, and to generate sections for
 
407
      inclusion in <filename>clients.conf</filename> on the server.
361
408
    </para>
362
409
  </refsect1>
363
 
 
 
410
  
364
411
  <refsect1 id="exit_status">
365
412
    <title>EXIT STATUS</title>
366
413
    <para>
386
433
    </variablelist>
387
434
  </refsect1>
388
435
  
389
 
  <refsect1 id="file">
 
436
  <refsect1 id="files">
390
437
    <title>FILES</title>
391
438
    <para>
392
439
      Use the <option>--dir</option> option to change where
395
442
    </para>
396
443
    <variablelist>
397
444
      <varlistentry>
398
 
        <term><filename>/etc/mandos/seckey.txt</filename></term>
 
445
        <term><filename>/etc/keys/mandos/seckey.txt</filename></term>
399
446
        <listitem>
400
447
          <para>
401
448
            OpenPGP secret key file which will be created or
404
451
        </listitem>
405
452
      </varlistentry>
406
453
      <varlistentry>
407
 
        <term><filename>/etc/mandos/pubkey.txt</filename></term>
 
454
        <term><filename>/etc/keys/mandos/pubkey.txt</filename></term>
408
455
        <listitem>
409
456
          <para>
410
457
            OpenPGP public key file which will be created or
413
460
        </listitem>
414
461
      </varlistentry>
415
462
      <varlistentry>
416
 
        <term><filename>/tmp</filename></term>
 
463
        <term><filename>/etc/keys/mandos/tls-privkey.pem</filename></term>
 
464
        <listitem>
 
465
          <para>
 
466
            Private key file which will be created or overwritten.
 
467
          </para>
 
468
        </listitem>
 
469
      </varlistentry>
 
470
      <varlistentry>
 
471
        <term><filename>/etc/keys/mandos/tls-pubkey.pem</filename></term>
 
472
        <listitem>
 
473
          <para>
 
474
            Public key file which will be created or overwritten.
 
475
          </para>
 
476
        </listitem>
 
477
      </varlistentry>
 
478
      <varlistentry>
 
479
        <term><filename class="directory">/tmp</filename></term>
417
480
        <listitem>
418
481
          <para>
419
482
            Temporary files will be written here if
423
486
      </varlistentry>
424
487
    </variablelist>
425
488
  </refsect1>
426
 
 
 
489
  
427
490
  <refsect1 id="bugs">
428
491
    <title>BUGS</title>
429
 
    <para>
430
 
      None are known at this time.
431
 
    </para>
 
492
    <xi:include href="bugs.xml"/>
432
493
  </refsect1>
433
 
 
 
494
  
434
495
  <refsect1 id="example">
435
496
    <title>EXAMPLE</title>
436
497
    <informalexample>
455
516
    </informalexample>
456
517
    <informalexample>
457
518
      <para>
458
 
        Prompt for a password, encrypt it with the key in
459
 
        <filename>/etc/mandos</filename> and output a section suitable
460
 
        for <filename>clients.conf</filename>.
 
519
        Prompt for a password, encrypt it with the keys in <filename
 
520
        class="directory">/etc/keys/mandos</filename> and output a
 
521
        section suitable for <filename>clients.conf</filename>.
461
522
      </para>
462
523
      <para>
463
524
        <userinput>&COMMANDNAME; --password</userinput>
465
526
    </informalexample>
466
527
    <informalexample>
467
528
      <para>
468
 
        Prompt for a password, encrypt it with the key in the
 
529
        Prompt for a password, encrypt it with the keys in the
469
530
        <filename>client-key</filename> directory and output a section
470
531
        suitable for <filename>clients.conf</filename>.
471
532
      </para>
477
538
      </para>
478
539
    </informalexample>
479
540
  </refsect1>
480
 
 
 
541
  
481
542
  <refsect1 id="security">
482
543
    <title>SECURITY</title>
483
544
    <para>
492
553
      <manvolnum>8</manvolnum></citerefentry>.
493
554
    </para>
494
555
  </refsect1>
495
 
 
 
556
  
496
557
  <refsect1 id="see_also">
497
558
    <title>SEE ALSO</title>
498
559
    <para>
 
560
      <citerefentry><refentrytitle>intro</refentrytitle>
 
561
      <manvolnum>8mandos</manvolnum></citerefentry>,
499
562
      <citerefentry><refentrytitle>gpg</refentrytitle>
500
563
      <manvolnum>1</manvolnum></citerefentry>,
501
564
      <citerefentry><refentrytitle>mandos-clients.conf</refentrytitle>
502
565
      <manvolnum>5</manvolnum></citerefentry>,
503
566
      <citerefentry><refentrytitle>mandos</refentrytitle>
504
567
      <manvolnum>8</manvolnum></citerefentry>,
505
 
      <citerefentry><refentrytitle>password-request</refentrytitle>
506
 
      <manvolnum>8mandos</manvolnum></citerefentry>
 
568
      <citerefentry><refentrytitle>mandos-client</refentrytitle>
 
569
      <manvolnum>8mandos</manvolnum></citerefentry>,
 
570
      <citerefentry><refentrytitle>ssh-keyscan</refentrytitle>
 
571
      <manvolnum>1</manvolnum></citerefentry>
507
572
    </para>
508
573
  </refsect1>
509
574