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