/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-02-28 18:48:33 UTC
  • Revision ID: teddy@recompile.se-20190228184833-nlg1xxlhnldso9ya
Make mandos-ctl use unittest instead of doctest module

* mandos-ctl: Before running main(), check if we should only run tests
              by seeing if the --check option was passed.
  (main): Don't look for the --check option.
  (should_only_run_tests): New.
  (load_tests): New.

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-03">
 
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>
37
49
    <xi:include href="legalnotice.xml"/>
38
50
  </refentryinfo>
39
 
 
 
51
  
40
52
  <refmeta>
41
53
    <refentrytitle>&COMMANDNAME;</refentrytitle>
42
54
    <manvolnum>8</manvolnum>
48
60
      Generate key and password for Mandos client and server.
49
61
    </refpurpose>
50
62
  </refnamediv>
51
 
 
 
63
  
52
64
  <refsynopsisdiv>
53
65
    <cmdsynopsis>
54
66
      <command>&COMMANDNAME;</command>
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>
122
144
      <group choice="req">
123
145
        <arg choice="plain"><option>--password</option></arg>
124
146
        <arg choice="plain"><option>-p</option></arg>
 
147
        <arg choice="plain"><option>--passfile
 
148
        <replaceable>FILE</replaceable></option></arg>
 
149
        <arg choice="plain"><option>-F</option>
 
150
        <replaceable>FILE</replaceable></arg>
125
151
      </group>
126
152
      <sbr/>
127
153
      <group>
137
163
        <arg choice="plain"><option>-n
138
164
        <replaceable>NAME</replaceable></option></arg>
139
165
      </group>
 
166
      <group>
 
167
        <arg choice="plain"><option>--no-ssh</option></arg>
 
168
        <arg choice="plain"><option>-S</option></arg>
 
169
      </group>
140
170
    </cmdsynopsis>
141
171
    <cmdsynopsis>
142
172
      <command>&COMMANDNAME;</command>
158
188
    <title>DESCRIPTION</title>
159
189
    <para>
160
190
      <command>&COMMANDNAME;</command> is a program to generate the
161
 
      OpenPGP key used by
162
 
      <citerefentry><refentrytitle>password-request</refentrytitle>
163
 
      <manvolnum>8mandos</manvolnum></citerefentry>.  The key is
164
 
      normally written to /etc/mandos for later installation into the
165
 
      initrd image, but this, and most other things, can be changed
166
 
      with command line options.
 
191
      TLS and OpenPGP keys used by
 
192
      <citerefentry><refentrytitle>mandos-client</refentrytitle>
 
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.
167
197
    </para>
168
198
    <para>
169
199
      This program can also be used with the
170
 
      <option>--password</option> option to generate a ready-made
171
 
      section for <filename>clients.conf</filename> (see
 
200
      <option>--password</option> or <option>--passfile</option>
 
201
      options to generate a ready-made section for
 
202
      <filename>clients.conf</filename> (see
172
203
      <citerefentry><refentrytitle>mandos-clients.conf</refentrytitle>
173
204
      <manvolnum>5</manvolnum></citerefentry>).
174
205
    </para>
197
228
          </para>
198
229
        </listitem>
199
230
      </varlistentry>
200
 
 
 
231
      
201
232
      <varlistentry>
202
233
        <term><option>--dir
203
234
        <replaceable>DIRECTORY</replaceable></option></term>
205
236
        <replaceable>DIRECTORY</replaceable></option></term>
206
237
        <listitem>
207
238
          <para>
208
 
            Target directory for key files.  Default is
209
 
            <filename>/etc/mandos</filename>.
 
239
            Target directory for key files.  Default is <filename
 
240
            class="directory">/etc/keys/mandos</filename>.
210
241
          </para>
211
242
        </listitem>
212
243
      </varlistentry>
213
 
 
 
244
      
214
245
      <varlistentry>
215
246
        <term><option>--type
216
247
        <replaceable>TYPE</replaceable></option></term>
218
249
        <replaceable>TYPE</replaceable></option></term>
219
250
        <listitem>
220
251
          <para>
221
 
            Key type.  Default is <quote>DSA</quote>.
 
252
            OpenPGP key type.  Default is <quote>RSA</quote>.
222
253
          </para>
223
254
        </listitem>
224
255
      </varlistentry>
225
 
 
 
256
      
226
257
      <varlistentry>
227
258
        <term><option>--length
228
259
        <replaceable>BITS</replaceable></option></term>
230
261
        <replaceable>BITS</replaceable></option></term>
231
262
        <listitem>
232
263
          <para>
233
 
            Key length in bits.  Default is 2048.
 
264
            OpenPGP key length in bits.  Default is 4096.
234
265
          </para>
235
266
        </listitem>
236
267
      </varlistentry>
237
 
 
 
268
      
238
269
      <varlistentry>
239
270
        <term><option>--subtype
240
271
        <replaceable>KEYTYPE</replaceable></option></term>
242
273
        <replaceable>KEYTYPE</replaceable></option></term>
243
274
        <listitem>
244
275
          <para>
245
 
            Subkey type.  Default is <quote>ELG-E</quote> (Elgamal
246
 
            encryption-only).
 
276
            OpenPGP subkey type.  Default is <quote>RSA</quote>
247
277
          </para>
248
278
        </listitem>
249
279
      </varlistentry>
250
 
 
 
280
      
251
281
      <varlistentry>
252
282
        <term><option>--sublength
253
283
        <replaceable>BITS</replaceable></option></term>
255
285
        <replaceable>BITS</replaceable></option></term>
256
286
        <listitem>
257
287
          <para>
258
 
            Subkey length in bits.  Default is 2048.
 
288
            OpenPGP subkey length in bits.  Default is 4096.
259
289
          </para>
260
290
        </listitem>
261
291
      </varlistentry>
262
 
 
 
292
      
263
293
      <varlistentry>
264
294
        <term><option>--email
265
295
        <replaceable>ADDRESS</replaceable></option></term>
271
301
          </para>
272
302
        </listitem>
273
303
      </varlistentry>
274
 
 
 
304
      
275
305
      <varlistentry>
276
306
        <term><option>--comment
277
307
        <replaceable>TEXT</replaceable></option></term>
279
309
        <replaceable>TEXT</replaceable></option></term>
280
310
        <listitem>
281
311
          <para>
282
 
            Comment field for key.  The default value is
283
 
            <quote><literal>Mandos client key</literal></quote>.
 
312
            Comment field for key.  Default is empty.
284
313
          </para>
285
314
        </listitem>
286
315
      </varlistentry>
287
 
 
 
316
      
288
317
      <varlistentry>
289
318
        <term><option>--expire
290
319
        <replaceable>TIME</replaceable></option></term>
298
327
          </para>
299
328
        </listitem>
300
329
      </varlistentry>
301
 
 
 
330
      
 
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
      
302
343
      <varlistentry>
303
344
        <term><option>--force</option></term>
304
345
        <term><option>-f</option></term>
314
355
        <listitem>
315
356
          <para>
316
357
            Prompt for a password and encrypt it with the key already
317
 
            present in either <filename>/etc/mandos</filename> or the
318
 
            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>
319
360
            option.  Outputs, on standard output, a section suitable
320
361
            for inclusion in <citerefentry><refentrytitle
321
362
            >mandos-clients.conf</refentrytitle><manvolnum
326
367
          </para>
327
368
        </listitem>
328
369
      </varlistentry>
 
370
      <varlistentry>
 
371
        <term><option>--passfile
 
372
        <replaceable>FILE</replaceable></option></term>
 
373
        <term><option>-F
 
374
        <replaceable>FILE</replaceable></option></term>
 
375
        <listitem>
 
376
          <para>
 
377
            The same as <option>--password</option>, but read from
 
378
            <replaceable>FILE</replaceable>, not the terminal.
 
379
          </para>
 
380
        </listitem>
 
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>
329
398
    </variablelist>
330
399
  </refsect1>
331
 
 
 
400
  
332
401
  <refsect1 id="overview">
333
402
    <title>OVERVIEW</title>
334
403
    <xi:include href="overview.xml"/>
335
404
    <para>
336
 
      This program is a small utility to generate new OpenPGP keys for
337
 
      new Mandos clients, and to generate sections for inclusion in
338
 
      <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.
339
408
    </para>
340
409
  </refsect1>
341
 
 
 
410
  
342
411
  <refsect1 id="exit_status">
343
412
    <title>EXIT STATUS</title>
344
413
    <para>
364
433
    </variablelist>
365
434
  </refsect1>
366
435
  
367
 
  <refsect1 id="file">
 
436
  <refsect1 id="files">
368
437
    <title>FILES</title>
369
438
    <para>
370
439
      Use the <option>--dir</option> option to change where
373
442
    </para>
374
443
    <variablelist>
375
444
      <varlistentry>
376
 
        <term><filename>/etc/mandos/seckey.txt</filename></term>
 
445
        <term><filename>/etc/keys/mandos/seckey.txt</filename></term>
377
446
        <listitem>
378
447
          <para>
379
448
            OpenPGP secret key file which will be created or
382
451
        </listitem>
383
452
      </varlistentry>
384
453
      <varlistentry>
385
 
        <term><filename>/etc/mandos/pubkey.txt</filename></term>
 
454
        <term><filename>/etc/keys/mandos/pubkey.txt</filename></term>
386
455
        <listitem>
387
456
          <para>
388
457
            OpenPGP public key file which will be created or
391
460
        </listitem>
392
461
      </varlistentry>
393
462
      <varlistentry>
394
 
        <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>
395
480
        <listitem>
396
481
          <para>
397
482
            Temporary files will be written here if
401
486
      </varlistentry>
402
487
    </variablelist>
403
488
  </refsect1>
404
 
 
405
 
<!--   <refsect1 id="bugs"> -->
406
 
<!--     <title>BUGS</title> -->
407
 
<!--     <para> -->
408
 
<!--     </para> -->
409
 
<!--   </refsect1> -->
410
 
 
 
489
  
 
490
  <refsect1 id="bugs">
 
491
    <title>BUGS</title>
 
492
    <xi:include href="bugs.xml"/>
 
493
  </refsect1>
 
494
  
411
495
  <refsect1 id="example">
412
496
    <title>EXAMPLE</title>
413
497
    <informalexample>
432
516
    </informalexample>
433
517
    <informalexample>
434
518
      <para>
435
 
        Prompt for a password, encrypt it with the key in
436
 
        <filename>/etc/mandos</filename> and output a section suitable
437
 
        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>.
438
522
      </para>
439
523
      <para>
440
524
        <userinput>&COMMANDNAME; --password</userinput>
442
526
    </informalexample>
443
527
    <informalexample>
444
528
      <para>
445
 
        Prompt for a password, encrypt it with the key in the
 
529
        Prompt for a password, encrypt it with the keys in the
446
530
        <filename>client-key</filename> directory and output a section
447
531
        suitable for <filename>clients.conf</filename>.
448
532
      </para>
454
538
      </para>
455
539
    </informalexample>
456
540
  </refsect1>
457
 
 
 
541
  
458
542
  <refsect1 id="security">
459
543
    <title>SECURITY</title>
460
544
    <para>
469
553
      <manvolnum>8</manvolnum></citerefentry>.
470
554
    </para>
471
555
  </refsect1>
472
 
 
 
556
  
473
557
  <refsect1 id="see_also">
474
558
    <title>SEE ALSO</title>
475
559
    <para>
 
560
      <citerefentry><refentrytitle>intro</refentrytitle>
 
561
      <manvolnum>8mandos</manvolnum></citerefentry>,
476
562
      <citerefentry><refentrytitle>gpg</refentrytitle>
477
563
      <manvolnum>1</manvolnum></citerefentry>,
478
564
      <citerefentry><refentrytitle>mandos-clients.conf</refentrytitle>
479
565
      <manvolnum>5</manvolnum></citerefentry>,
480
566
      <citerefentry><refentrytitle>mandos</refentrytitle>
481
567
      <manvolnum>8</manvolnum></citerefentry>,
482
 
      <citerefentry><refentrytitle>password-request</refentrytitle>
483
 
      <manvolnum>8mandos</manvolnum></citerefentry>
 
568
      <citerefentry><refentrytitle>mandos-client</refentrytitle>
 
569
      <manvolnum>8mandos</manvolnum></citerefentry>,
 
570
      <citerefentry><refentrytitle>ssh-keyscan</refentrytitle>
 
571
      <manvolnum>1</manvolnum></citerefentry>
484
572
    </para>
485
573
  </refsect1>
486
574