/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-10 03:50:20 UTC
  • Revision ID: teddy@recompile.se-20190210035020-nttr1tybgwwixueu
http://bugs.debian.org/879538
http://bugs.debian.org/916673
Show debconf note about new TLS key IDs

If mandos-client did not see TLS keys and had to create them, or if
mandos sees GnuTLS version 3.6.6 or later, show an important notice on
package installation about the importance of adding the new key_id
options to clients.conf on the Mandos server.

* debian/control (Package: mandos, Package: mandos-client): Depend on
                                                            debconf.
* debian/mandos-client.lintian-overrides: Override warnings.
* debian/mandos-client.postinst (create_keys): Show notice if new TLS
                                               key files were created.
* debian/mandos-client.templates: New.
* debian/mandos.lintian-overrides: Override warnings.
* debian/mandos.postinst (configure): If GnuTLS 3.6.6 or later is
                                      detected, show an important
                                      notice (once) about the new
                                      key_id option required in
                                      clients.conf.
* debian/mandos.templates: 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-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>
34
45
      <holder>Teddy Hogeborn</holder>
35
46
      <holder>Björn Påhlsson</holder>
36
47
    </copyright>
115
126
        <replaceable>TIME</replaceable></option></arg>
116
127
      </group>
117
128
      <sbr/>
118
 
      <arg><option>--force</option></arg>
 
129
      <group>
 
130
        <arg choice="plain"><option>--tls-keytype
 
131
        <replaceable>KEYTYPE</replaceable></option></arg>
 
132
        <arg choice="plain"><option>-T
 
133
        <replaceable>KEYTYPE</replaceable></option></arg>
 
134
      </group>
 
135
      <sbr/>
 
136
      <group>
 
137
        <arg choice="plain"><option>--force</option></arg>
 
138
        <arg choice="plain"><option>-f</option></arg>
 
139
      </group>
119
140
    </cmdsynopsis>
120
141
    <cmdsynopsis>
121
142
      <command>&COMMANDNAME;</command>
141
162
        <arg choice="plain"><option>-n
142
163
        <replaceable>NAME</replaceable></option></arg>
143
164
      </group>
 
165
      <group>
 
166
        <arg choice="plain"><option>--no-ssh</option></arg>
 
167
        <arg choice="plain"><option>-S</option></arg>
 
168
      </group>
144
169
    </cmdsynopsis>
145
170
    <cmdsynopsis>
146
171
      <command>&COMMANDNAME;</command>
162
187
    <title>DESCRIPTION</title>
163
188
    <para>
164
189
      <command>&COMMANDNAME;</command> is a program to generate the
165
 
      OpenPGP key used by
 
190
      TLS and OpenPGP keys used by
166
191
      <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.
 
192
      <manvolnum>8mandos</manvolnum></citerefentry>.  The keys are
 
193
      normally written to /etc/keys/mandos for later installation into
 
194
      the initrd image, but this, and most other things, can be
 
195
      changed with command line options.
171
196
    </para>
172
197
    <para>
173
198
      This program can also be used with the
210
235
        <replaceable>DIRECTORY</replaceable></option></term>
211
236
        <listitem>
212
237
          <para>
213
 
            Target directory for key files.  Default is
214
 
            <filename>/etc/mandos</filename>.
 
238
            Target directory for key files.  Default is <filename
 
239
            class="directory">/etc/keys/mandos</filename>.
215
240
          </para>
216
241
        </listitem>
217
242
      </varlistentry>
223
248
        <replaceable>TYPE</replaceable></option></term>
224
249
        <listitem>
225
250
          <para>
226
 
            Key type.  Default is <quote>DSA</quote>.
 
251
            OpenPGP key type.  Default is <quote>RSA</quote>.
227
252
          </para>
228
253
        </listitem>
229
254
      </varlistentry>
235
260
        <replaceable>BITS</replaceable></option></term>
236
261
        <listitem>
237
262
          <para>
238
 
            Key length in bits.  Default is 2048.
 
263
            OpenPGP key length in bits.  Default is 4096.
239
264
          </para>
240
265
        </listitem>
241
266
      </varlistentry>
247
272
        <replaceable>KEYTYPE</replaceable></option></term>
248
273
        <listitem>
249
274
          <para>
250
 
            Subkey type.  Default is <quote>ELG-E</quote> (Elgamal
251
 
            encryption-only).
 
275
            OpenPGP subkey type.  Default is <quote>RSA</quote>
252
276
          </para>
253
277
        </listitem>
254
278
      </varlistentry>
260
284
        <replaceable>BITS</replaceable></option></term>
261
285
        <listitem>
262
286
          <para>
263
 
            Subkey length in bits.  Default is 2048.
 
287
            OpenPGP subkey length in bits.  Default is 4096.
264
288
          </para>
265
289
        </listitem>
266
290
      </varlistentry>
284
308
        <replaceable>TEXT</replaceable></option></term>
285
309
        <listitem>
286
310
          <para>
287
 
            Comment field for key.  The default value is
288
 
            <quote><literal>Mandos client key</literal></quote>.
 
311
            Comment field for key.  Default is empty.
289
312
          </para>
290
313
        </listitem>
291
314
      </varlistentry>
305
328
      </varlistentry>
306
329
      
307
330
      <varlistentry>
 
331
        <term><option>--tls-keytype
 
332
        <replaceable>KEYTYPE</replaceable></option></term>
 
333
        <term><option>-T
 
334
        <replaceable>KEYTYPE</replaceable></option></term>
 
335
        <listitem>
 
336
          <para>
 
337
            TLS key type.  Default is <quote>ed25519</quote>
 
338
          </para>
 
339
        </listitem>
 
340
      </varlistentry>
 
341
      
 
342
      <varlistentry>
308
343
        <term><option>--force</option></term>
309
344
        <term><option>-f</option></term>
310
345
        <listitem>
319
354
        <listitem>
320
355
          <para>
321
356
            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>
 
357
            present in either <filename>/etc/keys/mandos</filename> or
 
358
            the directory specified with the <option>--dir</option>
324
359
            option.  Outputs, on standard output, a section suitable
325
360
            for inclusion in <citerefentry><refentrytitle
326
361
            >mandos-clients.conf</refentrytitle><manvolnum
343
378
          </para>
344
379
        </listitem>
345
380
      </varlistentry>
 
381
      <varlistentry>
 
382
        <term><option>--no-ssh</option></term>
 
383
        <term><option>-S</option></term>
 
384
        <listitem>
 
385
          <para>
 
386
            When <option>--password</option> or
 
387
            <option>--passfile</option> is given, this option will
 
388
            prevent <command>&COMMANDNAME;</command> from calling
 
389
            <command>ssh-keyscan</command> to get an SSH fingerprint
 
390
            for this host and, if successful, output suitable config
 
391
            options to use this fingerprint as a
 
392
            <option>checker</option> option in the output.  This is
 
393
            otherwise the default behavior.
 
394
          </para>
 
395
        </listitem>
 
396
      </varlistentry>
346
397
    </variablelist>
347
398
  </refsect1>
348
399
  
350
401
    <title>OVERVIEW</title>
351
402
    <xi:include href="overview.xml"/>
352
403
    <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.
 
404
      This program is a small utility to generate new TLS and OpenPGP
 
405
      keys for new Mandos clients, and to generate sections for
 
406
      inclusion in <filename>clients.conf</filename> on the server.
356
407
    </para>
357
408
  </refsect1>
358
409
  
381
432
    </variablelist>
382
433
  </refsect1>
383
434
  
384
 
  <refsect1 id="file">
 
435
  <refsect1 id="files">
385
436
    <title>FILES</title>
386
437
    <para>
387
438
      Use the <option>--dir</option> option to change where
390
441
    </para>
391
442
    <variablelist>
392
443
      <varlistentry>
393
 
        <term><filename>/etc/mandos/seckey.txt</filename></term>
 
444
        <term><filename>/etc/keys/mandos/seckey.txt</filename></term>
394
445
        <listitem>
395
446
          <para>
396
447
            OpenPGP secret key file which will be created or
399
450
        </listitem>
400
451
      </varlistentry>
401
452
      <varlistentry>
402
 
        <term><filename>/etc/mandos/pubkey.txt</filename></term>
 
453
        <term><filename>/etc/keys/mandos/pubkey.txt</filename></term>
403
454
        <listitem>
404
455
          <para>
405
456
            OpenPGP public key file which will be created or
408
459
        </listitem>
409
460
      </varlistentry>
410
461
      <varlistentry>
411
 
        <term><filename>/tmp</filename></term>
 
462
        <term><filename>/etc/keys/mandos/tls-privkey.pem</filename></term>
 
463
        <listitem>
 
464
          <para>
 
465
            Private key file which will be created or overwritten.
 
466
          </para>
 
467
        </listitem>
 
468
      </varlistentry>
 
469
      <varlistentry>
 
470
        <term><filename>/etc/keys/mandos/tls-pubkey.pem</filename></term>
 
471
        <listitem>
 
472
          <para>
 
473
            Public key file which will be created or overwritten.
 
474
          </para>
 
475
        </listitem>
 
476
      </varlistentry>
 
477
      <varlistentry>
 
478
        <term><filename class="directory">/tmp</filename></term>
412
479
        <listitem>
413
480
          <para>
414
481
            Temporary files will be written here if
419
486
    </variablelist>
420
487
  </refsect1>
421
488
  
422
 
<!--   <refsect1 id="bugs"> -->
423
 
<!--     <title>BUGS</title> -->
424
 
<!--     <para> -->
425
 
<!--     </para> -->
426
 
<!--   </refsect1> -->
 
489
  <refsect1 id="bugs">
 
490
    <title>BUGS</title>
 
491
    <xi:include href="bugs.xml"/>
 
492
  </refsect1>
427
493
  
428
494
  <refsect1 id="example">
429
495
    <title>EXAMPLE</title>
449
515
    </informalexample>
450
516
    <informalexample>
451
517
      <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>.
 
518
        Prompt for a password, encrypt it with the keys in <filename
 
519
        class="directory">/etc/keys/mandos</filename> and output a
 
520
        section suitable for <filename>clients.conf</filename>.
455
521
      </para>
456
522
      <para>
457
523
        <userinput>&COMMANDNAME; --password</userinput>
459
525
    </informalexample>
460
526
    <informalexample>
461
527
      <para>
462
 
        Prompt for a password, encrypt it with the key in the
 
528
        Prompt for a password, encrypt it with the keys in the
463
529
        <filename>client-key</filename> directory and output a section
464
530
        suitable for <filename>clients.conf</filename>.
465
531
      </para>
490
556
  <refsect1 id="see_also">
491
557
    <title>SEE ALSO</title>
492
558
    <para>
 
559
      <citerefentry><refentrytitle>intro</refentrytitle>
 
560
      <manvolnum>8mandos</manvolnum></citerefentry>,
493
561
      <citerefentry><refentrytitle>gpg</refentrytitle>
494
562
      <manvolnum>1</manvolnum></citerefentry>,
495
563
      <citerefentry><refentrytitle>mandos-clients.conf</refentrytitle>
497
565
      <citerefentry><refentrytitle>mandos</refentrytitle>
498
566
      <manvolnum>8</manvolnum></citerefentry>,
499
567
      <citerefentry><refentrytitle>mandos-client</refentrytitle>
500
 
      <manvolnum>8mandos</manvolnum></citerefentry>
 
568
      <manvolnum>8mandos</manvolnum></citerefentry>,
 
569
      <citerefentry><refentrytitle>ssh-keyscan</refentrytitle>
 
570
      <manvolnum>1</manvolnum></citerefentry>
501
571
    </para>
502
572
  </refsect1>
503
573