/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-10-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>
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>
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>
 
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>
414
482
        <term><filename class="directory">/tmp</filename></term>
415
483
        <listitem>
416
484
          <para>
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 <filename
456
 
        class="directory">/etc/mandos</filename> and output a section
457
 
        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>.
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