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