/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-03-18 22:29:25 UTC
  • Revision ID: teddy@recompile.se-20190318222925-jvhek84dgcfgj6g3
mandos-ctl: Refactor tests

* mandos-ctl: Where the clients names "foo" and "barbar" do not refer
              to the actual mock clients in the TestCommand class,
              change all occurrences of these names to "client1" and
              "client2" (or just "client" when only one is used) .
              Also change all test doubles to use correct terminology;
              some things called mocks are actually stubs or spies,
              and rename all true mocks to have "mock" in their names.
              Also eliminate duplicate values in tests; derive values
              from previously defined values whenever possible.

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 "2012-01-01">
 
5
<!ENTITY TIMESTAMP "2019-02-10">
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>DSA</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 2048.
 
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>ELG-E</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 2048.
 
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
347
379
          </para>
348
380
        </listitem>
349
381
      </varlistentry>
 
382
      <varlistentry>
 
383
        <term><option>--no-ssh</option></term>
 
384
        <term><option>-S</option></term>
 
385
        <listitem>
 
386
          <para>
 
387
            When <option>--password</option> or
 
388
            <option>--passfile</option> is given, this option will
 
389
            prevent <command>&COMMANDNAME;</command> from calling
 
390
            <command>ssh-keyscan</command> to get an SSH fingerprint
 
391
            for this host and, if successful, output suitable config
 
392
            options to use this fingerprint as a
 
393
            <option>checker</option> option in the output.  This is
 
394
            otherwise the default behavior.
 
395
          </para>
 
396
        </listitem>
 
397
      </varlistentry>
350
398
    </variablelist>
351
399
  </refsect1>
352
400
  
354
402
    <title>OVERVIEW</title>
355
403
    <xi:include href="overview.xml"/>
356
404
    <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.
 
405
      This program is a small utility to generate new TLS and OpenPGP
 
406
      keys for new Mandos clients, and to generate sections for
 
407
      inclusion in <filename>clients.conf</filename> on the server.
360
408
    </para>
361
409
  </refsect1>
362
410
  
394
442
    </para>
395
443
    <variablelist>
396
444
      <varlistentry>
397
 
        <term><filename>/etc/mandos/seckey.txt</filename></term>
 
445
        <term><filename>/etc/keys/mandos/seckey.txt</filename></term>
398
446
        <listitem>
399
447
          <para>
400
448
            OpenPGP secret key file which will be created or
403
451
        </listitem>
404
452
      </varlistentry>
405
453
      <varlistentry>
406
 
        <term><filename>/etc/mandos/pubkey.txt</filename></term>
 
454
        <term><filename>/etc/keys/mandos/pubkey.txt</filename></term>
407
455
        <listitem>
408
456
          <para>
409
457
            OpenPGP public key file which will be created or
412
460
        </listitem>
413
461
      </varlistentry>
414
462
      <varlistentry>
 
463
        <term><filename>/etc/keys/mandos/tls-privkey.pem</filename></term>
 
464
        <listitem>
 
465
          <para>
 
466
            Private key file which will be created or overwritten.
 
467
          </para>
 
468
        </listitem>
 
469
      </varlistentry>
 
470
      <varlistentry>
 
471
        <term><filename>/etc/keys/mandos/tls-pubkey.pem</filename></term>
 
472
        <listitem>
 
473
          <para>
 
474
            Public key file which will be created or overwritten.
 
475
          </para>
 
476
        </listitem>
 
477
      </varlistentry>
 
478
      <varlistentry>
415
479
        <term><filename class="directory">/tmp</filename></term>
416
480
        <listitem>
417
481
          <para>
423
487
    </variablelist>
424
488
  </refsect1>
425
489
  
426
 
<!--   <refsect1 id="bugs"> -->
427
 
<!--     <title>BUGS</title> -->
428
 
<!--     <para> -->
429
 
<!--     </para> -->
430
 
<!--   </refsect1> -->
 
490
  <refsect1 id="bugs">
 
491
    <title>BUGS</title>
 
492
    <xi:include href="bugs.xml"/>
 
493
  </refsect1>
431
494
  
432
495
  <refsect1 id="example">
433
496
    <title>EXAMPLE</title>
453
516
    </informalexample>
454
517
    <informalexample>
455
518
      <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>.
 
519
        Prompt for a password, encrypt it with the keys in <filename
 
520
        class="directory">/etc/keys/mandos</filename> and output a
 
521
        section suitable for <filename>clients.conf</filename>.
459
522
      </para>
460
523
      <para>
461
524
        <userinput>&COMMANDNAME; --password</userinput>
463
526
    </informalexample>
464
527
    <informalexample>
465
528
      <para>
466
 
        Prompt for a password, encrypt it with the key in the
 
529
        Prompt for a password, encrypt it with the keys in the
467
530
        <filename>client-key</filename> directory and output a section
468
531
        suitable for <filename>clients.conf</filename>.
469
532
      </para>
503
566
      <citerefentry><refentrytitle>mandos</refentrytitle>
504
567
      <manvolnum>8</manvolnum></citerefentry>,
505
568
      <citerefentry><refentrytitle>mandos-client</refentrytitle>
506
 
      <manvolnum>8mandos</manvolnum></citerefentry>
 
569
      <manvolnum>8mandos</manvolnum></citerefentry>,
 
570
      <citerefentry><refentrytitle>ssh-keyscan</refentrytitle>
 
571
      <manvolnum>1</manvolnum></citerefentry>
507
572
    </para>
508
573
  </refsect1>
509
574