/mandos/release

To get this branch, use:
bzr branch http://bzr.recompile.se/loggerhead/mandos/release

« back to all changes in this revision

Viewing changes to mandos-keygen.xml

  • Committer: Teddy Hogeborn
  • Date: 2019-03-18 22:29:25 UTC
  • mto: This revision was merged to the branch mainline in revision 382.
  • 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 "2011-10-03">
 
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>
 
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>
37
46
      <holder>Teddy Hogeborn</holder>
38
47
      <holder>Björn Påhlsson</holder>
39
48
    </copyright>
118
127
        <replaceable>TIME</replaceable></option></arg>
119
128
      </group>
120
129
      <sbr/>
121
 
      <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>
122
141
    </cmdsynopsis>
123
142
    <cmdsynopsis>
124
143
      <command>&COMMANDNAME;</command>
144
163
        <arg choice="plain"><option>-n
145
164
        <replaceable>NAME</replaceable></option></arg>
146
165
      </group>
 
166
      <group>
 
167
        <arg choice="plain"><option>--no-ssh</option></arg>
 
168
        <arg choice="plain"><option>-S</option></arg>
 
169
      </group>
147
170
    </cmdsynopsis>
148
171
    <cmdsynopsis>
149
172
      <command>&COMMANDNAME;</command>
165
188
    <title>DESCRIPTION</title>
166
189
    <para>
167
190
      <command>&COMMANDNAME;</command> is a program to generate the
168
 
      OpenPGP key used by
 
191
      TLS and OpenPGP keys used by
169
192
      <citerefentry><refentrytitle>mandos-client</refentrytitle>
170
 
      <manvolnum>8mandos</manvolnum></citerefentry>.  The key is
171
 
      normally written to /etc/mandos for later installation into the
172
 
      initrd image, but this, and most other things, can be changed
173
 
      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.
174
197
    </para>
175
198
    <para>
176
199
      This program can also be used with the
213
236
        <replaceable>DIRECTORY</replaceable></option></term>
214
237
        <listitem>
215
238
          <para>
216
 
            Target directory for key files.  Default is
217
 
            <filename class="directory">/etc/mandos</filename>.
 
239
            Target directory for key files.  Default is <filename
 
240
            class="directory">/etc/keys/mandos</filename>.
218
241
          </para>
219
242
        </listitem>
220
243
      </varlistentry>
226
249
        <replaceable>TYPE</replaceable></option></term>
227
250
        <listitem>
228
251
          <para>
229
 
            Key type.  Default is <quote>DSA</quote>.
 
252
            OpenPGP key type.  Default is <quote>RSA</quote>.
230
253
          </para>
231
254
        </listitem>
232
255
      </varlistentry>
238
261
        <replaceable>BITS</replaceable></option></term>
239
262
        <listitem>
240
263
          <para>
241
 
            Key length in bits.  Default is 2048.
 
264
            OpenPGP key length in bits.  Default is 4096.
242
265
          </para>
243
266
        </listitem>
244
267
      </varlistentry>
250
273
        <replaceable>KEYTYPE</replaceable></option></term>
251
274
        <listitem>
252
275
          <para>
253
 
            Subkey type.  Default is <quote>ELG-E</quote> (Elgamal
254
 
            encryption-only).
 
276
            OpenPGP subkey type.  Default is <quote>RSA</quote>
255
277
          </para>
256
278
        </listitem>
257
279
      </varlistentry>
263
285
        <replaceable>BITS</replaceable></option></term>
264
286
        <listitem>
265
287
          <para>
266
 
            Subkey length in bits.  Default is 2048.
 
288
            OpenPGP subkey length in bits.  Default is 4096.
267
289
          </para>
268
290
        </listitem>
269
291
      </varlistentry>
287
309
        <replaceable>TEXT</replaceable></option></term>
288
310
        <listitem>
289
311
          <para>
290
 
            Comment field for key.  The default value is
291
 
            <quote><literal>Mandos client key</literal></quote>.
 
312
            Comment field for key.  Default is empty.
292
313
          </para>
293
314
        </listitem>
294
315
      </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
346
379
          </para>
347
380
        </listitem>
348
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>
349
398
    </variablelist>
350
399
  </refsect1>
351
400
  
353
402
    <title>OVERVIEW</title>
354
403
    <xi:include href="overview.xml"/>
355
404
    <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.
 
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.
359
408
    </para>
360
409
  </refsect1>
361
410
  
393
442
    </para>
394
443
    <variablelist>
395
444
      <varlistentry>
396
 
        <term><filename>/etc/mandos/seckey.txt</filename></term>
 
445
        <term><filename>/etc/keys/mandos/seckey.txt</filename></term>
397
446
        <listitem>
398
447
          <para>
399
448
            OpenPGP secret key file which will be created or
402
451
        </listitem>
403
452
      </varlistentry>
404
453
      <varlistentry>
405
 
        <term><filename>/etc/mandos/pubkey.txt</filename></term>
 
454
        <term><filename>/etc/keys/mandos/pubkey.txt</filename></term>
406
455
        <listitem>
407
456
          <para>
408
457
            OpenPGP public key file which will be created or
411
460
        </listitem>
412
461
      </varlistentry>
413
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>
414
479
        <term><filename class="directory">/tmp</filename></term>
415
480
        <listitem>
416
481
          <para>
422
487
    </variablelist>
423
488
  </refsect1>
424
489
  
425
 
<!--   <refsect1 id="bugs"> -->
426
 
<!--     <title>BUGS</title> -->
427
 
<!--     <para> -->
428
 
<!--     </para> -->
429
 
<!--   </refsect1> -->
 
490
  <refsect1 id="bugs">
 
491
    <title>BUGS</title>
 
492
    <xi:include href="bugs.xml"/>
 
493
  </refsect1>
430
494
  
431
495
  <refsect1 id="example">
432
496
    <title>EXAMPLE</title>
452
516
    </informalexample>
453
517
    <informalexample>
454
518
      <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>.
 
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>.
458
522
      </para>
459
523
      <para>
460
524
        <userinput>&COMMANDNAME; --password</userinput>
462
526
    </informalexample>
463
527
    <informalexample>
464
528
      <para>
465
 
        Prompt for a password, encrypt it with the key in the
 
529
        Prompt for a password, encrypt it with the keys in the
466
530
        <filename>client-key</filename> directory and output a section
467
531
        suitable for <filename>clients.conf</filename>.
468
532
      </para>
502
566
      <citerefentry><refentrytitle>mandos</refentrytitle>
503
567
      <manvolnum>8</manvolnum></citerefentry>,
504
568
      <citerefentry><refentrytitle>mandos-client</refentrytitle>
505
 
      <manvolnum>8mandos</manvolnum></citerefentry>
 
569
      <manvolnum>8mandos</manvolnum></citerefentry>,
 
570
      <citerefentry><refentrytitle>ssh-keyscan</refentrytitle>
 
571
      <manvolnum>1</manvolnum></citerefentry>
506
572
    </para>
507
573
  </refsect1>
508
574