/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-07-29 16:35:53 UTC
  • mto: This revision was merged to the branch mainline in revision 384.
  • 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 "2014-06-22">
 
5
<!ENTITY TIMESTAMP "2019-07-18">
6
6
<!ENTITY % common SYSTEM "common.ent">
7
7
%common;
8
8
]>
33
33
    <copyright>
34
34
      <year>2008</year>
35
35
      <year>2009</year>
 
36
      <year>2010</year>
36
37
      <year>2011</year>
37
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>
38
46
      <holder>Teddy Hogeborn</holder>
39
47
      <holder>Björn Påhlsson</holder>
40
48
    </copyright>
120
128
      </group>
121
129
      <sbr/>
122
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>
123
138
        <arg choice="plain"><option>--force</option></arg>
124
139
        <arg choice="plain"><option>-f</option></arg>
125
140
      </group>
173
188
    <title>DESCRIPTION</title>
174
189
    <para>
175
190
      <command>&COMMANDNAME;</command> is a program to generate the
176
 
      OpenPGP key used by
 
191
      TLS and OpenPGP keys used by
177
192
      <citerefentry><refentrytitle>mandos-client</refentrytitle>
178
 
      <manvolnum>8mandos</manvolnum></citerefentry>.  The key is
179
 
      normally written to /etc/mandos for later installation into the
180
 
      initrd image, but this, and most other things, can be changed
181
 
      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.
182
197
    </para>
183
198
    <para>
184
199
      This program can also be used with the
221
236
        <replaceable>DIRECTORY</replaceable></option></term>
222
237
        <listitem>
223
238
          <para>
224
 
            Target directory for key files.  Default is
225
 
            <filename class="directory">/etc/mandos</filename>.
 
239
            Target directory for key files.  Default is <filename
 
240
            class="directory">/etc/keys/mandos</filename>.
226
241
          </para>
227
242
        </listitem>
228
243
      </varlistentry>
234
249
        <replaceable>TYPE</replaceable></option></term>
235
250
        <listitem>
236
251
          <para>
237
 
            Key type.  Default is <quote>RSA</quote>.
 
252
            OpenPGP key type.  Default is <quote>RSA</quote>.
238
253
          </para>
239
254
        </listitem>
240
255
      </varlistentry>
246
261
        <replaceable>BITS</replaceable></option></term>
247
262
        <listitem>
248
263
          <para>
249
 
            Key length in bits.  Default is 4096.
 
264
            OpenPGP key length in bits.  Default is 4096.
250
265
          </para>
251
266
        </listitem>
252
267
      </varlistentry>
258
273
        <replaceable>KEYTYPE</replaceable></option></term>
259
274
        <listitem>
260
275
          <para>
261
 
            Subkey type.  Default is <quote>RSA</quote> (Elgamal
262
 
            encryption-only).
 
276
            OpenPGP subkey type.  Default is <quote>RSA</quote>
263
277
          </para>
264
278
        </listitem>
265
279
      </varlistentry>
271
285
        <replaceable>BITS</replaceable></option></term>
272
286
        <listitem>
273
287
          <para>
274
 
            Subkey length in bits.  Default is 4096.
 
288
            OpenPGP subkey length in bits.  Default is 4096.
275
289
          </para>
276
290
        </listitem>
277
291
      </varlistentry>
315
329
      </varlistentry>
316
330
      
317
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>
318
344
        <term><option>--force</option></term>
319
345
        <term><option>-f</option></term>
320
346
        <listitem>
329
355
        <listitem>
330
356
          <para>
331
357
            Prompt for a password and encrypt it with the key already
332
 
            present in either <filename>/etc/mandos</filename> or the
333
 
            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>
334
360
            option.  Outputs, on standard output, a section suitable
335
361
            for inclusion in <citerefentry><refentrytitle
336
362
            >mandos-clients.conf</refentrytitle><manvolnum
337
363
            >8</manvolnum></citerefentry>.  The host name or the name
338
364
            specified with the <option>--name</option> option is used
339
365
            for the section header.  All other options are ignored,
340
 
            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"/>.
341
369
          </para>
342
370
        </listitem>
343
371
      </varlistentry>
349
377
        <listitem>
350
378
          <para>
351
379
            The same as <option>--password</option>, but read from
352
 
            <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.
353
382
          </para>
354
383
        </listitem>
355
384
      </varlistentry>
376
405
    <title>OVERVIEW</title>
377
406
    <xi:include href="overview.xml"/>
378
407
    <para>
379
 
      This program is a small utility to generate new OpenPGP keys for
380
 
      new Mandos clients, and to generate sections for inclusion in
381
 
      <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.
382
411
    </para>
383
412
  </refsect1>
384
413
  
416
445
    </para>
417
446
    <variablelist>
418
447
      <varlistentry>
419
 
        <term><filename>/etc/mandos/seckey.txt</filename></term>
 
448
        <term><filename>/etc/keys/mandos/seckey.txt</filename></term>
420
449
        <listitem>
421
450
          <para>
422
451
            OpenPGP secret key file which will be created or
425
454
        </listitem>
426
455
      </varlistentry>
427
456
      <varlistentry>
428
 
        <term><filename>/etc/mandos/pubkey.txt</filename></term>
 
457
        <term><filename>/etc/keys/mandos/pubkey.txt</filename></term>
429
458
        <listitem>
430
459
          <para>
431
460
            OpenPGP public key file which will be created or
434
463
        </listitem>
435
464
      </varlistentry>
436
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>
437
482
        <term><filename class="directory">/tmp</filename></term>
438
483
        <listitem>
439
484
          <para>
445
490
    </variablelist>
446
491
  </refsect1>
447
492
  
448
 
<!--   <refsect1 id="bugs"> -->
449
 
<!--     <title>BUGS</title> -->
450
 
<!--     <para> -->
451
 
<!--     </para> -->
452
 
<!--   </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>
453
504
  
454
505
  <refsect1 id="example">
455
506
    <title>EXAMPLE</title>
475
526
    </informalexample>
476
527
    <informalexample>
477
528
      <para>
478
 
        Prompt for a password, encrypt it with the key in <filename
479
 
        class="directory">/etc/mandos</filename> and output a section
480
 
        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>.
481
532
      </para>
482
533
      <para>
483
534
        <userinput>&COMMANDNAME; --password</userinput>
485
536
    </informalexample>
486
537
    <informalexample>
487
538
      <para>
488
 
        Prompt for a password, encrypt it with the key in the
 
539
        Prompt for a password, encrypt it with the keys in the
489
540
        <filename>client-key</filename> directory and output a section
490
541
        suitable for <filename>clients.conf</filename>.
491
542
      </para>