/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 "2015-07-20">
 
5
<!ENTITY TIMESTAMP "2019-07-18">
6
6
<!ENTITY % common SYSTEM "common.ent">
7
7
%common;
8
8
]>
39
39
      <year>2013</year>
40
40
      <year>2014</year>
41
41
      <year>2015</year>
 
42
      <year>2016</year>
 
43
      <year>2017</year>
 
44
      <year>2018</year>
 
45
      <year>2019</year>
42
46
      <holder>Teddy Hogeborn</holder>
43
47
      <holder>Björn Påhlsson</holder>
44
48
    </copyright>
124
128
      </group>
125
129
      <sbr/>
126
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>
127
138
        <arg choice="plain"><option>--force</option></arg>
128
139
        <arg choice="plain"><option>-f</option></arg>
129
140
      </group>
177
188
    <title>DESCRIPTION</title>
178
189
    <para>
179
190
      <command>&COMMANDNAME;</command> is a program to generate the
180
 
      OpenPGP key used by
 
191
      TLS and OpenPGP keys used by
181
192
      <citerefentry><refentrytitle>mandos-client</refentrytitle>
182
 
      <manvolnum>8mandos</manvolnum></citerefentry>.  The key is
183
 
      normally written to /etc/mandos for later installation into the
184
 
      initrd image, but this, and most other things, can be changed
185
 
      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.
186
197
    </para>
187
198
    <para>
188
199
      This program can also be used with the
225
236
        <replaceable>DIRECTORY</replaceable></option></term>
226
237
        <listitem>
227
238
          <para>
228
 
            Target directory for key files.  Default is
229
 
            <filename class="directory">/etc/mandos</filename>.
 
239
            Target directory for key files.  Default is <filename
 
240
            class="directory">/etc/keys/mandos</filename>.
230
241
          </para>
231
242
        </listitem>
232
243
      </varlistentry>
238
249
        <replaceable>TYPE</replaceable></option></term>
239
250
        <listitem>
240
251
          <para>
241
 
            Key type.  Default is <quote>RSA</quote>.
 
252
            OpenPGP key type.  Default is <quote>RSA</quote>.
242
253
          </para>
243
254
        </listitem>
244
255
      </varlistentry>
250
261
        <replaceable>BITS</replaceable></option></term>
251
262
        <listitem>
252
263
          <para>
253
 
            Key length in bits.  Default is 4096.
 
264
            OpenPGP key length in bits.  Default is 4096.
254
265
          </para>
255
266
        </listitem>
256
267
      </varlistentry>
262
273
        <replaceable>KEYTYPE</replaceable></option></term>
263
274
        <listitem>
264
275
          <para>
265
 
            Subkey type.  Default is <quote>RSA</quote> (Elgamal
266
 
            encryption-only).
 
276
            OpenPGP subkey type.  Default is <quote>RSA</quote>
267
277
          </para>
268
278
        </listitem>
269
279
      </varlistentry>
275
285
        <replaceable>BITS</replaceable></option></term>
276
286
        <listitem>
277
287
          <para>
278
 
            Subkey length in bits.  Default is 4096.
 
288
            OpenPGP subkey length in bits.  Default is 4096.
279
289
          </para>
280
290
        </listitem>
281
291
      </varlistentry>
319
329
      </varlistentry>
320
330
      
321
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>
322
344
        <term><option>--force</option></term>
323
345
        <term><option>-f</option></term>
324
346
        <listitem>
333
355
        <listitem>
334
356
          <para>
335
357
            Prompt for a password and encrypt it with the key already
336
 
            present in either <filename>/etc/mandos</filename> or the
337
 
            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>
338
360
            option.  Outputs, on standard output, a section suitable
339
361
            for inclusion in <citerefentry><refentrytitle
340
362
            >mandos-clients.conf</refentrytitle><manvolnum
341
363
            >8</manvolnum></citerefentry>.  The host name or the name
342
364
            specified with the <option>--name</option> option is used
343
365
            for the section header.  All other options are ignored,
344
 
            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"/>.
345
369
          </para>
346
370
        </listitem>
347
371
      </varlistentry>
353
377
        <listitem>
354
378
          <para>
355
379
            The same as <option>--password</option>, but read from
356
 
            <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.
357
382
          </para>
358
383
        </listitem>
359
384
      </varlistentry>
380
405
    <title>OVERVIEW</title>
381
406
    <xi:include href="overview.xml"/>
382
407
    <para>
383
 
      This program is a small utility to generate new OpenPGP keys for
384
 
      new Mandos clients, and to generate sections for inclusion in
385
 
      <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.
386
411
    </para>
387
412
  </refsect1>
388
413
  
420
445
    </para>
421
446
    <variablelist>
422
447
      <varlistentry>
423
 
        <term><filename>/etc/mandos/seckey.txt</filename></term>
 
448
        <term><filename>/etc/keys/mandos/seckey.txt</filename></term>
424
449
        <listitem>
425
450
          <para>
426
451
            OpenPGP secret key file which will be created or
429
454
        </listitem>
430
455
      </varlistentry>
431
456
      <varlistentry>
432
 
        <term><filename>/etc/mandos/pubkey.txt</filename></term>
 
457
        <term><filename>/etc/keys/mandos/pubkey.txt</filename></term>
433
458
        <listitem>
434
459
          <para>
435
460
            OpenPGP public key file which will be created or
438
463
        </listitem>
439
464
      </varlistentry>
440
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>
441
482
        <term><filename class="directory">/tmp</filename></term>
442
483
        <listitem>
443
484
          <para>
449
490
    </variablelist>
450
491
  </refsect1>
451
492
  
452
 
<!--   <refsect1 id="bugs"> -->
453
 
<!--     <title>BUGS</title> -->
454
 
<!--     <para> -->
455
 
<!--     </para> -->
456
 
<!--   </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>
457
504
  
458
505
  <refsect1 id="example">
459
506
    <title>EXAMPLE</title>
479
526
    </informalexample>
480
527
    <informalexample>
481
528
      <para>
482
 
        Prompt for a password, encrypt it with the key in <filename
483
 
        class="directory">/etc/mandos</filename> and output a section
484
 
        suitable 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>.
485
532
      </para>
486
533
      <para>
487
534
        <userinput>&COMMANDNAME; --password</userinput>
489
536
    </informalexample>
490
537
    <informalexample>
491
538
      <para>
492
 
        Prompt for a password, encrypt it with the key in the
 
539
        Prompt for a password, encrypt it with the keys in the
493
540
        <filename>client-key</filename> directory and output a section
494
541
        suitable for <filename>clients.conf</filename>.
495
542
      </para>