/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 "2018-02-08">
 
5
<!ENTITY TIMESTAMP "2019-07-18">
6
6
<!ENTITY % common SYSTEM "common.ent">
7
7
%common;
8
8
]>
42
42
      <year>2016</year>
43
43
      <year>2017</year>
44
44
      <year>2018</year>
 
45
      <year>2019</year>
45
46
      <holder>Teddy Hogeborn</holder>
46
47
      <holder>Björn Påhlsson</holder>
47
48
    </copyright>
127
128
      </group>
128
129
      <sbr/>
129
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>
130
138
        <arg choice="plain"><option>--force</option></arg>
131
139
        <arg choice="plain"><option>-f</option></arg>
132
140
      </group>
180
188
    <title>DESCRIPTION</title>
181
189
    <para>
182
190
      <command>&COMMANDNAME;</command> is a program to generate the
183
 
      OpenPGP key used by
 
191
      TLS and OpenPGP keys used by
184
192
      <citerefentry><refentrytitle>mandos-client</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.
 
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
228
236
        <replaceable>DIRECTORY</replaceable></option></term>
229
237
        <listitem>
230
238
          <para>
231
 
            Target directory for key files.  Default is
232
 
            <filename class="directory">/etc/mandos</filename>.
 
239
            Target directory for key files.  Default is <filename
 
240
            class="directory">/etc/keys/mandos</filename>.
233
241
          </para>
234
242
        </listitem>
235
243
      </varlistentry>
241
249
        <replaceable>TYPE</replaceable></option></term>
242
250
        <listitem>
243
251
          <para>
244
 
            Key type.  Default is <quote>RSA</quote>.
 
252
            OpenPGP key type.  Default is <quote>RSA</quote>.
245
253
          </para>
246
254
        </listitem>
247
255
      </varlistentry>
253
261
        <replaceable>BITS</replaceable></option></term>
254
262
        <listitem>
255
263
          <para>
256
 
            Key length in bits.  Default is 4096.
 
264
            OpenPGP key length in bits.  Default is 4096.
257
265
          </para>
258
266
        </listitem>
259
267
      </varlistentry>
265
273
        <replaceable>KEYTYPE</replaceable></option></term>
266
274
        <listitem>
267
275
          <para>
268
 
            Subkey type.  Default is <quote>RSA</quote> (Elgamal
269
 
            encryption-only).
 
276
            OpenPGP subkey type.  Default is <quote>RSA</quote>
270
277
          </para>
271
278
        </listitem>
272
279
      </varlistentry>
278
285
        <replaceable>BITS</replaceable></option></term>
279
286
        <listitem>
280
287
          <para>
281
 
            Subkey length in bits.  Default is 4096.
 
288
            OpenPGP subkey length in bits.  Default is 4096.
282
289
          </para>
283
290
        </listitem>
284
291
      </varlistentry>
322
329
      </varlistentry>
323
330
      
324
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>
325
344
        <term><option>--force</option></term>
326
345
        <term><option>-f</option></term>
327
346
        <listitem>
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
344
363
            >8</manvolnum></citerefentry>.  The host name or the name
345
364
            specified with the <option>--name</option> option is used
346
365
            for the section header.  All other options are ignored,
347
 
            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"/>.
348
369
          </para>
349
370
        </listitem>
350
371
      </varlistentry>
356
377
        <listitem>
357
378
          <para>
358
379
            The same as <option>--password</option>, but read from
359
 
            <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.
360
382
          </para>
361
383
        </listitem>
362
384
      </varlistentry>
383
405
    <title>OVERVIEW</title>
384
406
    <xi:include href="overview.xml"/>
385
407
    <para>
386
 
      This program is a small utility to generate new OpenPGP keys for
387
 
      new Mandos clients, and to generate sections for inclusion in
388
 
      <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.
389
411
    </para>
390
412
  </refsect1>
391
413
  
423
445
    </para>
424
446
    <variablelist>
425
447
      <varlistentry>
426
 
        <term><filename>/etc/mandos/seckey.txt</filename></term>
 
448
        <term><filename>/etc/keys/mandos/seckey.txt</filename></term>
427
449
        <listitem>
428
450
          <para>
429
451
            OpenPGP secret key file which will be created or
432
454
        </listitem>
433
455
      </varlistentry>
434
456
      <varlistentry>
435
 
        <term><filename>/etc/mandos/pubkey.txt</filename></term>
 
457
        <term><filename>/etc/keys/mandos/pubkey.txt</filename></term>
436
458
        <listitem>
437
459
          <para>
438
460
            OpenPGP public key file which will be created or
441
463
        </listitem>
442
464
      </varlistentry>
443
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>
444
482
        <term><filename class="directory">/tmp</filename></term>
445
483
        <listitem>
446
484
          <para>
454
492
  
455
493
  <refsect1 id="bugs">
456
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>
457
502
    <xi:include href="bugs.xml"/>
458
503
  </refsect1>
459
504
  
481
526
    </informalexample>
482
527
    <informalexample>
483
528
      <para>
484
 
        Prompt for a password, encrypt it with the key in <filename
485
 
        class="directory">/etc/mandos</filename> and output a section
486
 
        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>.
487
532
      </para>
488
533
      <para>
489
534
        <userinput>&COMMANDNAME; --password</userinput>
491
536
    </informalexample>
492
537
    <informalexample>
493
538
      <para>
494
 
        Prompt for a password, encrypt it with the key in the
 
539
        Prompt for a password, encrypt it with the keys in the
495
540
        <filename>client-key</filename> directory and output a section
496
541
        suitable for <filename>clients.conf</filename>.
497
542
      </para>