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