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