/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
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
4
<!ENTITY COMMANDNAME "mandos-keygen">
5
 
<!ENTITY TIMESTAMP "2009-01-04">
 
5
<!ENTITY TIMESTAMP "2019-07-18">
6
6
<!ENTITY % common SYSTEM "common.ent">
7
7
%common;
8
8
]>
19
19
        <firstname>Björn</firstname>
20
20
        <surname>Påhlsson</surname>
21
21
        <address>
22
 
          <email>belorn@fukt.bsnet.se</email>
 
22
          <email>belorn@recompile.se</email>
23
23
        </address>
24
24
      </author>
25
25
      <author>
26
26
        <firstname>Teddy</firstname>
27
27
        <surname>Hogeborn</surname>
28
28
        <address>
29
 
          <email>teddy@fukt.bsnet.se</email>
 
29
          <email>teddy@recompile.se</email>
30
30
        </address>
31
31
      </author>
32
32
    </authorgroup>
33
33
    <copyright>
34
34
      <year>2008</year>
35
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>
36
46
      <holder>Teddy Hogeborn</holder>
37
47
      <holder>Björn Påhlsson</holder>
38
48
    </copyright>
117
127
        <replaceable>TIME</replaceable></option></arg>
118
128
      </group>
119
129
      <sbr/>
120
 
      <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>
121
141
    </cmdsynopsis>
122
142
    <cmdsynopsis>
123
143
      <command>&COMMANDNAME;</command>
143
163
        <arg choice="plain"><option>-n
144
164
        <replaceable>NAME</replaceable></option></arg>
145
165
      </group>
 
166
      <group>
 
167
        <arg choice="plain"><option>--no-ssh</option></arg>
 
168
        <arg choice="plain"><option>-S</option></arg>
 
169
      </group>
146
170
    </cmdsynopsis>
147
171
    <cmdsynopsis>
148
172
      <command>&COMMANDNAME;</command>
164
188
    <title>DESCRIPTION</title>
165
189
    <para>
166
190
      <command>&COMMANDNAME;</command> is a program to generate the
167
 
      OpenPGP key used by
 
191
      TLS and OpenPGP keys used by
168
192
      <citerefentry><refentrytitle>mandos-client</refentrytitle>
169
 
      <manvolnum>8mandos</manvolnum></citerefentry>.  The key is
170
 
      normally written to /etc/mandos for later installation into the
171
 
      initrd image, but this, and most other things, can be changed
172
 
      with command line options.
 
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.
173
197
    </para>
174
198
    <para>
175
199
      This program can also be used with the
212
236
        <replaceable>DIRECTORY</replaceable></option></term>
213
237
        <listitem>
214
238
          <para>
215
 
            Target directory for key files.  Default is
216
 
            <filename>/etc/mandos</filename>.
 
239
            Target directory for key files.  Default is <filename
 
240
            class="directory">/etc/keys/mandos</filename>.
217
241
          </para>
218
242
        </listitem>
219
243
      </varlistentry>
225
249
        <replaceable>TYPE</replaceable></option></term>
226
250
        <listitem>
227
251
          <para>
228
 
            Key type.  Default is <quote>DSA</quote>.
 
252
            OpenPGP key type.  Default is <quote>RSA</quote>.
229
253
          </para>
230
254
        </listitem>
231
255
      </varlistentry>
237
261
        <replaceable>BITS</replaceable></option></term>
238
262
        <listitem>
239
263
          <para>
240
 
            Key length in bits.  Default is 2048.
 
264
            OpenPGP key length in bits.  Default is 4096.
241
265
          </para>
242
266
        </listitem>
243
267
      </varlistentry>
249
273
        <replaceable>KEYTYPE</replaceable></option></term>
250
274
        <listitem>
251
275
          <para>
252
 
            Subkey type.  Default is <quote>ELG-E</quote> (Elgamal
253
 
            encryption-only).
 
276
            OpenPGP subkey type.  Default is <quote>RSA</quote>
254
277
          </para>
255
278
        </listitem>
256
279
      </varlistentry>
262
285
        <replaceable>BITS</replaceable></option></term>
263
286
        <listitem>
264
287
          <para>
265
 
            Subkey length in bits.  Default is 2048.
 
288
            OpenPGP subkey length in bits.  Default is 4096.
266
289
          </para>
267
290
        </listitem>
268
291
      </varlistentry>
286
309
        <replaceable>TEXT</replaceable></option></term>
287
310
        <listitem>
288
311
          <para>
289
 
            Comment field for key.  The default value is
290
 
            <quote><literal>Mandos client key</literal></quote>.
 
312
            Comment field for key.  Default is empty.
291
313
          </para>
292
314
        </listitem>
293
315
      </varlistentry>
307
329
      </varlistentry>
308
330
      
309
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>
310
344
        <term><option>--force</option></term>
311
345
        <term><option>-f</option></term>
312
346
        <listitem>
321
355
        <listitem>
322
356
          <para>
323
357
            Prompt for a password and encrypt it with the key already
324
 
            present in either <filename>/etc/mandos</filename> or the
325
 
            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>
326
360
            option.  Outputs, on standard output, a section suitable
327
361
            for inclusion in <citerefentry><refentrytitle
328
362
            >mandos-clients.conf</refentrytitle><manvolnum
329
363
            >8</manvolnum></citerefentry>.  The host name or the name
330
364
            specified with the <option>--name</option> option is used
331
365
            for the section header.  All other options are ignored,
332
 
            and no key is created.
 
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"/>.
333
369
          </para>
334
370
        </listitem>
335
371
      </varlistentry>
341
377
        <listitem>
342
378
          <para>
343
379
            The same as <option>--password</option>, but read from
344
 
            <replaceable>FILE</replaceable>, not the terminal.
 
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.
345
398
          </para>
346
399
        </listitem>
347
400
      </varlistentry>
352
405
    <title>OVERVIEW</title>
353
406
    <xi:include href="overview.xml"/>
354
407
    <para>
355
 
      This program is a small utility to generate new OpenPGP keys for
356
 
      new Mandos clients, and to generate sections for inclusion in
357
 
      <filename>clients.conf</filename> on the server.
 
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.
358
411
    </para>
359
412
  </refsect1>
360
413
  
392
445
    </para>
393
446
    <variablelist>
394
447
      <varlistentry>
395
 
        <term><filename>/etc/mandos/seckey.txt</filename></term>
 
448
        <term><filename>/etc/keys/mandos/seckey.txt</filename></term>
396
449
        <listitem>
397
450
          <para>
398
451
            OpenPGP secret key file which will be created or
401
454
        </listitem>
402
455
      </varlistentry>
403
456
      <varlistentry>
404
 
        <term><filename>/etc/mandos/pubkey.txt</filename></term>
 
457
        <term><filename>/etc/keys/mandos/pubkey.txt</filename></term>
405
458
        <listitem>
406
459
          <para>
407
460
            OpenPGP public key file which will be created or
410
463
        </listitem>
411
464
      </varlistentry>
412
465
      <varlistentry>
413
 
        <term><filename>/tmp</filename></term>
 
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>
414
483
        <listitem>
415
484
          <para>
416
485
            Temporary files will be written here if
421
490
    </variablelist>
422
491
  </refsect1>
423
492
  
424
 
<!--   <refsect1 id="bugs"> -->
425
 
<!--     <title>BUGS</title> -->
426
 
<!--     <para> -->
427
 
<!--     </para> -->
428
 
<!--   </refsect1> -->
 
493
  <refsect1 id="bugs">
 
494
    <title>BUGS</title>
 
495
    <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.
 
501
    </para>
 
502
    <xi:include href="bugs.xml"/>
 
503
  </refsect1>
429
504
  
430
505
  <refsect1 id="example">
431
506
    <title>EXAMPLE</title>
451
526
    </informalexample>
452
527
    <informalexample>
453
528
      <para>
454
 
        Prompt for a password, encrypt it with the key in
455
 
        <filename>/etc/mandos</filename> and output a section suitable
456
 
        for <filename>clients.conf</filename>.
 
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>.
457
532
      </para>
458
533
      <para>
459
534
        <userinput>&COMMANDNAME; --password</userinput>
461
536
    </informalexample>
462
537
    <informalexample>
463
538
      <para>
464
 
        Prompt for a password, encrypt it with the key in the
 
539
        Prompt for a password, encrypt it with the keys in the
465
540
        <filename>client-key</filename> directory and output a section
466
541
        suitable for <filename>clients.conf</filename>.
467
542
      </para>
492
567
  <refsect1 id="see_also">
493
568
    <title>SEE ALSO</title>
494
569
    <para>
 
570
      <citerefentry><refentrytitle>intro</refentrytitle>
 
571
      <manvolnum>8mandos</manvolnum></citerefentry>,
495
572
      <citerefentry><refentrytitle>gpg</refentrytitle>
496
573
      <manvolnum>1</manvolnum></citerefentry>,
497
574
      <citerefentry><refentrytitle>mandos-clients.conf</refentrytitle>
499
576
      <citerefentry><refentrytitle>mandos</refentrytitle>
500
577
      <manvolnum>8</manvolnum></citerefentry>,
501
578
      <citerefentry><refentrytitle>mandos-client</refentrytitle>
502
 
      <manvolnum>8mandos</manvolnum></citerefentry>
 
579
      <manvolnum>8mandos</manvolnum></citerefentry>,
 
580
      <citerefentry><refentrytitle>ssh-keyscan</refentrytitle>
 
581
      <manvolnum>1</manvolnum></citerefentry>
503
582
    </para>
504
583
  </refsect1>
505
584