/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
1
1
<?xml version="1.0" encoding="UTF-8"?>
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
 
<!ENTITY VERSION "1.0">
5
4
<!ENTITY COMMANDNAME "mandos-keygen">
6
 
<!ENTITY TIMESTAMP "2008-09-20">
 
5
<!ENTITY TIMESTAMP "2019-02-10">
 
6
<!ENTITY % common SYSTEM "common.ent">
 
7
%common;
7
8
]>
8
9
 
9
10
<refentry xmlns:xi="http://www.w3.org/2001/XInclude">
11
12
    <title>Mandos Manual</title>
12
13
    <!-- NWalsh’s docbook scripts use this to generate the footer: -->
13
14
    <productname>Mandos</productname>
14
 
    <productnumber>&VERSION;</productnumber>
 
15
    <productnumber>&version;</productnumber>
15
16
    <date>&TIMESTAMP;</date>
16
17
    <authorgroup>
17
18
      <author>
18
19
        <firstname>Björn</firstname>
19
20
        <surname>Påhlsson</surname>
20
21
        <address>
21
 
          <email>belorn@fukt.bsnet.se</email>
 
22
          <email>belorn@recompile.se</email>
22
23
        </address>
23
24
      </author>
24
25
      <author>
25
26
        <firstname>Teddy</firstname>
26
27
        <surname>Hogeborn</surname>
27
28
        <address>
28
 
          <email>teddy@fukt.bsnet.se</email>
 
29
          <email>teddy@recompile.se</email>
29
30
        </address>
30
31
      </author>
31
32
    </authorgroup>
32
33
    <copyright>
33
34
      <year>2008</year>
 
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>
34
46
      <holder>Teddy Hogeborn</holder>
35
47
      <holder>Björn Påhlsson</holder>
36
48
    </copyright>
115
127
        <replaceable>TIME</replaceable></option></arg>
116
128
      </group>
117
129
      <sbr/>
118
 
      <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>
119
141
    </cmdsynopsis>
120
142
    <cmdsynopsis>
121
143
      <command>&COMMANDNAME;</command>
141
163
        <arg choice="plain"><option>-n
142
164
        <replaceable>NAME</replaceable></option></arg>
143
165
      </group>
 
166
      <group>
 
167
        <arg choice="plain"><option>--no-ssh</option></arg>
 
168
        <arg choice="plain"><option>-S</option></arg>
 
169
      </group>
144
170
    </cmdsynopsis>
145
171
    <cmdsynopsis>
146
172
      <command>&COMMANDNAME;</command>
162
188
    <title>DESCRIPTION</title>
163
189
    <para>
164
190
      <command>&COMMANDNAME;</command> is a program to generate the
165
 
      OpenPGP key used by
 
191
      TLS and OpenPGP keys used by
166
192
      <citerefentry><refentrytitle>mandos-client</refentrytitle>
167
 
      <manvolnum>8mandos</manvolnum></citerefentry>.  The key is
168
 
      normally written to /etc/mandos for later installation into the
169
 
      initrd image, but this, and most other things, can be changed
170
 
      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.
171
197
    </para>
172
198
    <para>
173
199
      This program can also be used with the
210
236
        <replaceable>DIRECTORY</replaceable></option></term>
211
237
        <listitem>
212
238
          <para>
213
 
            Target directory for key files.  Default is
214
 
            <filename>/etc/mandos</filename>.
 
239
            Target directory for key files.  Default is <filename
 
240
            class="directory">/etc/keys/mandos</filename>.
215
241
          </para>
216
242
        </listitem>
217
243
      </varlistentry>
223
249
        <replaceable>TYPE</replaceable></option></term>
224
250
        <listitem>
225
251
          <para>
226
 
            Key type.  Default is <quote>DSA</quote>.
 
252
            OpenPGP key type.  Default is <quote>RSA</quote>.
227
253
          </para>
228
254
        </listitem>
229
255
      </varlistentry>
235
261
        <replaceable>BITS</replaceable></option></term>
236
262
        <listitem>
237
263
          <para>
238
 
            Key length in bits.  Default is 2048.
 
264
            OpenPGP key length in bits.  Default is 4096.
239
265
          </para>
240
266
        </listitem>
241
267
      </varlistentry>
247
273
        <replaceable>KEYTYPE</replaceable></option></term>
248
274
        <listitem>
249
275
          <para>
250
 
            Subkey type.  Default is <quote>ELG-E</quote> (Elgamal
251
 
            encryption-only).
 
276
            OpenPGP subkey type.  Default is <quote>RSA</quote>
252
277
          </para>
253
278
        </listitem>
254
279
      </varlistentry>
260
285
        <replaceable>BITS</replaceable></option></term>
261
286
        <listitem>
262
287
          <para>
263
 
            Subkey length in bits.  Default is 2048.
 
288
            OpenPGP subkey length in bits.  Default is 4096.
264
289
          </para>
265
290
        </listitem>
266
291
      </varlistentry>
284
309
        <replaceable>TEXT</replaceable></option></term>
285
310
        <listitem>
286
311
          <para>
287
 
            Comment field for key.  The default value is
288
 
            <quote><literal>Mandos client key</literal></quote>.
 
312
            Comment field for key.  Default is empty.
289
313
          </para>
290
314
        </listitem>
291
315
      </varlistentry>
305
329
      </varlistentry>
306
330
      
307
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>
308
344
        <term><option>--force</option></term>
309
345
        <term><option>-f</option></term>
310
346
        <listitem>
319
355
        <listitem>
320
356
          <para>
321
357
            Prompt for a password and encrypt it with the key already
322
 
            present in either <filename>/etc/mandos</filename> or the
323
 
            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>
324
360
            option.  Outputs, on standard output, a section suitable
325
361
            for inclusion in <citerefentry><refentrytitle
326
362
            >mandos-clients.conf</refentrytitle><manvolnum
343
379
          </para>
344
380
        </listitem>
345
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>
346
398
    </variablelist>
347
399
  </refsect1>
348
400
  
350
402
    <title>OVERVIEW</title>
351
403
    <xi:include href="overview.xml"/>
352
404
    <para>
353
 
      This program is a small utility to generate new OpenPGP keys for
354
 
      new Mandos clients, and to generate sections for inclusion in
355
 
      <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.
356
408
    </para>
357
409
  </refsect1>
358
410
  
381
433
    </variablelist>
382
434
  </refsect1>
383
435
  
384
 
  <refsect1 id="file">
 
436
  <refsect1 id="files">
385
437
    <title>FILES</title>
386
438
    <para>
387
439
      Use the <option>--dir</option> option to change where
390
442
    </para>
391
443
    <variablelist>
392
444
      <varlistentry>
393
 
        <term><filename>/etc/mandos/seckey.txt</filename></term>
 
445
        <term><filename>/etc/keys/mandos/seckey.txt</filename></term>
394
446
        <listitem>
395
447
          <para>
396
448
            OpenPGP secret key file which will be created or
399
451
        </listitem>
400
452
      </varlistentry>
401
453
      <varlistentry>
402
 
        <term><filename>/etc/mandos/pubkey.txt</filename></term>
 
454
        <term><filename>/etc/keys/mandos/pubkey.txt</filename></term>
403
455
        <listitem>
404
456
          <para>
405
457
            OpenPGP public key file which will be created or
408
460
        </listitem>
409
461
      </varlistentry>
410
462
      <varlistentry>
411
 
        <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>
412
480
        <listitem>
413
481
          <para>
414
482
            Temporary files will be written here if
419
487
    </variablelist>
420
488
  </refsect1>
421
489
  
422
 
<!--   <refsect1 id="bugs"> -->
423
 
<!--     <title>BUGS</title> -->
424
 
<!--     <para> -->
425
 
<!--     </para> -->
426
 
<!--   </refsect1> -->
 
490
  <refsect1 id="bugs">
 
491
    <title>BUGS</title>
 
492
    <xi:include href="bugs.xml"/>
 
493
  </refsect1>
427
494
  
428
495
  <refsect1 id="example">
429
496
    <title>EXAMPLE</title>
449
516
    </informalexample>
450
517
    <informalexample>
451
518
      <para>
452
 
        Prompt for a password, encrypt it with the key in
453
 
        <filename>/etc/mandos</filename> and output a section suitable
454
 
        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>.
455
522
      </para>
456
523
      <para>
457
524
        <userinput>&COMMANDNAME; --password</userinput>
459
526
    </informalexample>
460
527
    <informalexample>
461
528
      <para>
462
 
        Prompt for a password, encrypt it with the key in the
 
529
        Prompt for a password, encrypt it with the keys in the
463
530
        <filename>client-key</filename> directory and output a section
464
531
        suitable for <filename>clients.conf</filename>.
465
532
      </para>
490
557
  <refsect1 id="see_also">
491
558
    <title>SEE ALSO</title>
492
559
    <para>
 
560
      <citerefentry><refentrytitle>intro</refentrytitle>
 
561
      <manvolnum>8mandos</manvolnum></citerefentry>,
493
562
      <citerefentry><refentrytitle>gpg</refentrytitle>
494
563
      <manvolnum>1</manvolnum></citerefentry>,
495
564
      <citerefentry><refentrytitle>mandos-clients.conf</refentrytitle>
497
566
      <citerefentry><refentrytitle>mandos</refentrytitle>
498
567
      <manvolnum>8</manvolnum></citerefentry>,
499
568
      <citerefentry><refentrytitle>mandos-client</refentrytitle>
500
 
      <manvolnum>8mandos</manvolnum></citerefentry>
 
569
      <manvolnum>8mandos</manvolnum></citerefentry>,
 
570
      <citerefentry><refentrytitle>ssh-keyscan</refentrytitle>
 
571
      <manvolnum>1</manvolnum></citerefentry>
501
572
    </para>
502
573
  </refsect1>
503
574