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