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