/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 "2011-08-08">
 
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
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>
37
45
      <holder>Teddy Hogeborn</holder>
38
46
      <holder>Björn Påhlsson</holder>
39
47
    </copyright>
118
126
        <replaceable>TIME</replaceable></option></arg>
119
127
      </group>
120
128
      <sbr/>
121
 
      <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>
122
140
    </cmdsynopsis>
123
141
    <cmdsynopsis>
124
142
      <command>&COMMANDNAME;</command>
144
162
        <arg choice="plain"><option>-n
145
163
        <replaceable>NAME</replaceable></option></arg>
146
164
      </group>
 
165
      <group>
 
166
        <arg choice="plain"><option>--no-ssh</option></arg>
 
167
        <arg choice="plain"><option>-S</option></arg>
 
168
      </group>
147
169
    </cmdsynopsis>
148
170
    <cmdsynopsis>
149
171
      <command>&COMMANDNAME;</command>
165
187
    <title>DESCRIPTION</title>
166
188
    <para>
167
189
      <command>&COMMANDNAME;</command> is a program to generate the
168
 
      OpenPGP key used by
 
190
      TLS and OpenPGP keys used by
169
191
      <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.
 
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.
174
196
    </para>
175
197
    <para>
176
198
      This program can also be used with the
213
235
        <replaceable>DIRECTORY</replaceable></option></term>
214
236
        <listitem>
215
237
          <para>
216
 
            Target directory for key files.  Default is
217
 
            <filename>/etc/mandos</filename>.
 
238
            Target directory for key files.  Default is <filename
 
239
            class="directory">/etc/keys/mandos</filename>.
218
240
          </para>
219
241
        </listitem>
220
242
      </varlistentry>
226
248
        <replaceable>TYPE</replaceable></option></term>
227
249
        <listitem>
228
250
          <para>
229
 
            Key type.  Default is <quote>DSA</quote>.
 
251
            OpenPGP key type.  Default is <quote>RSA</quote>.
230
252
          </para>
231
253
        </listitem>
232
254
      </varlistentry>
238
260
        <replaceable>BITS</replaceable></option></term>
239
261
        <listitem>
240
262
          <para>
241
 
            Key length in bits.  Default is 2048.
 
263
            OpenPGP key length in bits.  Default is 4096.
242
264
          </para>
243
265
        </listitem>
244
266
      </varlistentry>
250
272
        <replaceable>KEYTYPE</replaceable></option></term>
251
273
        <listitem>
252
274
          <para>
253
 
            Subkey type.  Default is <quote>ELG-E</quote> (Elgamal
254
 
            encryption-only).
 
275
            OpenPGP subkey type.  Default is <quote>RSA</quote>
255
276
          </para>
256
277
        </listitem>
257
278
      </varlistentry>
263
284
        <replaceable>BITS</replaceable></option></term>
264
285
        <listitem>
265
286
          <para>
266
 
            Subkey length in bits.  Default is 2048.
 
287
            OpenPGP subkey length in bits.  Default is 4096.
267
288
          </para>
268
289
        </listitem>
269
290
      </varlistentry>
287
308
        <replaceable>TEXT</replaceable></option></term>
288
309
        <listitem>
289
310
          <para>
290
 
            Comment field for key.  The default value is
291
 
            <quote><literal>Mandos client key</literal></quote>.
 
311
            Comment field for key.  Default is empty.
292
312
          </para>
293
313
        </listitem>
294
314
      </varlistentry>
308
328
      </varlistentry>
309
329
      
310
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>
311
343
        <term><option>--force</option></term>
312
344
        <term><option>-f</option></term>
313
345
        <listitem>
322
354
        <listitem>
323
355
          <para>
324
356
            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>
 
357
            present in either <filename>/etc/keys/mandos</filename> or
 
358
            the directory specified with the <option>--dir</option>
327
359
            option.  Outputs, on standard output, a section suitable
328
360
            for inclusion in <citerefentry><refentrytitle
329
361
            >mandos-clients.conf</refentrytitle><manvolnum
346
378
          </para>
347
379
        </listitem>
348
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>
349
397
    </variablelist>
350
398
  </refsect1>
351
399
  
353
401
    <title>OVERVIEW</title>
354
402
    <xi:include href="overview.xml"/>
355
403
    <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.
 
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.
359
407
    </para>
360
408
  </refsect1>
361
409
  
393
441
    </para>
394
442
    <variablelist>
395
443
      <varlistentry>
396
 
        <term><filename>/etc/mandos/seckey.txt</filename></term>
 
444
        <term><filename>/etc/keys/mandos/seckey.txt</filename></term>
397
445
        <listitem>
398
446
          <para>
399
447
            OpenPGP secret key file which will be created or
402
450
        </listitem>
403
451
      </varlistentry>
404
452
      <varlistentry>
405
 
        <term><filename>/etc/mandos/pubkey.txt</filename></term>
 
453
        <term><filename>/etc/keys/mandos/pubkey.txt</filename></term>
406
454
        <listitem>
407
455
          <para>
408
456
            OpenPGP public key file which will be created or
411
459
        </listitem>
412
460
      </varlistentry>
413
461
      <varlistentry>
414
 
        <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>
415
479
        <listitem>
416
480
          <para>
417
481
            Temporary files will be written here if
422
486
    </variablelist>
423
487
  </refsect1>
424
488
  
425
 
<!--   <refsect1 id="bugs"> -->
426
 
<!--     <title>BUGS</title> -->
427
 
<!--     <para> -->
428
 
<!--     </para> -->
429
 
<!--   </refsect1> -->
 
489
  <refsect1 id="bugs">
 
490
    <title>BUGS</title>
 
491
    <xi:include href="bugs.xml"/>
 
492
  </refsect1>
430
493
  
431
494
  <refsect1 id="example">
432
495
    <title>EXAMPLE</title>
452
515
    </informalexample>
453
516
    <informalexample>
454
517
      <para>
455
 
        Prompt for a password, encrypt it with the key in
456
 
        <filename>/etc/mandos</filename> and output a section suitable
457
 
        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>.
458
521
      </para>
459
522
      <para>
460
523
        <userinput>&COMMANDNAME; --password</userinput>
462
525
    </informalexample>
463
526
    <informalexample>
464
527
      <para>
465
 
        Prompt for a password, encrypt it with the key in the
 
528
        Prompt for a password, encrypt it with the keys in the
466
529
        <filename>client-key</filename> directory and output a section
467
530
        suitable for <filename>clients.conf</filename>.
468
531
      </para>
502
565
      <citerefentry><refentrytitle>mandos</refentrytitle>
503
566
      <manvolnum>8</manvolnum></citerefentry>,
504
567
      <citerefentry><refentrytitle>mandos-client</refentrytitle>
505
 
      <manvolnum>8mandos</manvolnum></citerefentry>
 
568
      <manvolnum>8mandos</manvolnum></citerefentry>,
 
569
      <citerefentry><refentrytitle>ssh-keyscan</refentrytitle>
 
570
      <manvolnum>1</manvolnum></citerefentry>
506
571
    </para>
507
572
  </refsect1>
508
573