/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 "2009-01-04">
 
5
<!ENTITY TIMESTAMP "2019-02-10">
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
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>
36
46
      <holder>Teddy Hogeborn</holder>
37
47
      <holder>Björn Påhlsson</holder>
38
48
    </copyright>
117
127
        <replaceable>TIME</replaceable></option></arg>
118
128
      </group>
119
129
      <sbr/>
120
 
      <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>
121
141
    </cmdsynopsis>
122
142
    <cmdsynopsis>
123
143
      <command>&COMMANDNAME;</command>
143
163
        <arg choice="plain"><option>-n
144
164
        <replaceable>NAME</replaceable></option></arg>
145
165
      </group>
 
166
      <group>
 
167
        <arg choice="plain"><option>--no-ssh</option></arg>
 
168
        <arg choice="plain"><option>-S</option></arg>
 
169
      </group>
146
170
    </cmdsynopsis>
147
171
    <cmdsynopsis>
148
172
      <command>&COMMANDNAME;</command>
164
188
    <title>DESCRIPTION</title>
165
189
    <para>
166
190
      <command>&COMMANDNAME;</command> is a program to generate the
167
 
      OpenPGP key used by
 
191
      TLS and OpenPGP keys used by
168
192
      <citerefentry><refentrytitle>mandos-client</refentrytitle>
169
 
      <manvolnum>8mandos</manvolnum></citerefentry>.  The key is
170
 
      normally written to /etc/mandos for later installation into the
171
 
      initrd image, but this, and most other things, can be changed
172
 
      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.
173
197
    </para>
174
198
    <para>
175
199
      This program can also be used with the
212
236
        <replaceable>DIRECTORY</replaceable></option></term>
213
237
        <listitem>
214
238
          <para>
215
 
            Target directory for key files.  Default is
216
 
            <filename>/etc/mandos</filename>.
 
239
            Target directory for key files.  Default is <filename
 
240
            class="directory">/etc/keys/mandos</filename>.
217
241
          </para>
218
242
        </listitem>
219
243
      </varlistentry>
225
249
        <replaceable>TYPE</replaceable></option></term>
226
250
        <listitem>
227
251
          <para>
228
 
            Key type.  Default is <quote>DSA</quote>.
 
252
            OpenPGP key type.  Default is <quote>RSA</quote>.
229
253
          </para>
230
254
        </listitem>
231
255
      </varlistentry>
237
261
        <replaceable>BITS</replaceable></option></term>
238
262
        <listitem>
239
263
          <para>
240
 
            Key length in bits.  Default is 2048.
 
264
            OpenPGP key length in bits.  Default is 4096.
241
265
          </para>
242
266
        </listitem>
243
267
      </varlistentry>
249
273
        <replaceable>KEYTYPE</replaceable></option></term>
250
274
        <listitem>
251
275
          <para>
252
 
            Subkey type.  Default is <quote>ELG-E</quote> (Elgamal
253
 
            encryption-only).
 
276
            OpenPGP subkey type.  Default is <quote>RSA</quote>
254
277
          </para>
255
278
        </listitem>
256
279
      </varlistentry>
262
285
        <replaceable>BITS</replaceable></option></term>
263
286
        <listitem>
264
287
          <para>
265
 
            Subkey length in bits.  Default is 2048.
 
288
            OpenPGP subkey length in bits.  Default is 4096.
266
289
          </para>
267
290
        </listitem>
268
291
      </varlistentry>
286
309
        <replaceable>TEXT</replaceable></option></term>
287
310
        <listitem>
288
311
          <para>
289
 
            Comment field for key.  The default value is
290
 
            <quote><literal>Mandos client key</literal></quote>.
 
312
            Comment field for key.  Default is empty.
291
313
          </para>
292
314
        </listitem>
293
315
      </varlistentry>
307
329
      </varlistentry>
308
330
      
309
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>
310
344
        <term><option>--force</option></term>
311
345
        <term><option>-f</option></term>
312
346
        <listitem>
321
355
        <listitem>
322
356
          <para>
323
357
            Prompt for a password and encrypt it with the key already
324
 
            present in either <filename>/etc/mandos</filename> or the
325
 
            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>
326
360
            option.  Outputs, on standard output, a section suitable
327
361
            for inclusion in <citerefentry><refentrytitle
328
362
            >mandos-clients.conf</refentrytitle><manvolnum
345
379
          </para>
346
380
        </listitem>
347
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>
348
398
    </variablelist>
349
399
  </refsect1>
350
400
  
352
402
    <title>OVERVIEW</title>
353
403
    <xi:include href="overview.xml"/>
354
404
    <para>
355
 
      This program is a small utility to generate new OpenPGP keys for
356
 
      new Mandos clients, and to generate sections for inclusion in
357
 
      <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.
358
408
    </para>
359
409
  </refsect1>
360
410
  
392
442
    </para>
393
443
    <variablelist>
394
444
      <varlistentry>
395
 
        <term><filename>/etc/mandos/seckey.txt</filename></term>
 
445
        <term><filename>/etc/keys/mandos/seckey.txt</filename></term>
396
446
        <listitem>
397
447
          <para>
398
448
            OpenPGP secret key file which will be created or
401
451
        </listitem>
402
452
      </varlistentry>
403
453
      <varlistentry>
404
 
        <term><filename>/etc/mandos/pubkey.txt</filename></term>
 
454
        <term><filename>/etc/keys/mandos/pubkey.txt</filename></term>
405
455
        <listitem>
406
456
          <para>
407
457
            OpenPGP public key file which will be created or
410
460
        </listitem>
411
461
      </varlistentry>
412
462
      <varlistentry>
413
 
        <term><filename>/tmp</filename></term>
 
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>
 
479
        <term><filename class="directory">/tmp</filename></term>
414
480
        <listitem>
415
481
          <para>
416
482
            Temporary files will be written here if
421
487
    </variablelist>
422
488
  </refsect1>
423
489
  
424
 
<!--   <refsect1 id="bugs"> -->
425
 
<!--     <title>BUGS</title> -->
426
 
<!--     <para> -->
427
 
<!--     </para> -->
428
 
<!--   </refsect1> -->
 
490
  <refsect1 id="bugs">
 
491
    <title>BUGS</title>
 
492
    <xi:include href="bugs.xml"/>
 
493
  </refsect1>
429
494
  
430
495
  <refsect1 id="example">
431
496
    <title>EXAMPLE</title>
451
516
    </informalexample>
452
517
    <informalexample>
453
518
      <para>
454
 
        Prompt for a password, encrypt it with the key in
455
 
        <filename>/etc/mandos</filename> and output a section suitable
456
 
        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>.
457
522
      </para>
458
523
      <para>
459
524
        <userinput>&COMMANDNAME; --password</userinput>
461
526
    </informalexample>
462
527
    <informalexample>
463
528
      <para>
464
 
        Prompt for a password, encrypt it with the key in the
 
529
        Prompt for a password, encrypt it with the keys in the
465
530
        <filename>client-key</filename> directory and output a section
466
531
        suitable for <filename>clients.conf</filename>.
467
532
      </para>
492
557
  <refsect1 id="see_also">
493
558
    <title>SEE ALSO</title>
494
559
    <para>
 
560
      <citerefentry><refentrytitle>intro</refentrytitle>
 
561
      <manvolnum>8mandos</manvolnum></citerefentry>,
495
562
      <citerefentry><refentrytitle>gpg</refentrytitle>
496
563
      <manvolnum>1</manvolnum></citerefentry>,
497
564
      <citerefentry><refentrytitle>mandos-clients.conf</refentrytitle>
499
566
      <citerefentry><refentrytitle>mandos</refentrytitle>
500
567
      <manvolnum>8</manvolnum></citerefentry>,
501
568
      <citerefentry><refentrytitle>mandos-client</refentrytitle>
502
 
      <manvolnum>8mandos</manvolnum></citerefentry>
 
569
      <manvolnum>8mandos</manvolnum></citerefentry>,
 
570
      <citerefentry><refentrytitle>ssh-keyscan</refentrytitle>
 
571
      <manvolnum>1</manvolnum></citerefentry>
503
572
    </para>
504
573
  </refsect1>
505
574