/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-12">
 
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>
122
143
      <group choice="req">
123
144
        <arg choice="plain"><option>--password</option></arg>
124
145
        <arg choice="plain"><option>-p</option></arg>
 
146
        <arg choice="plain"><option>--passfile
 
147
        <replaceable>FILE</replaceable></option></arg>
 
148
        <arg choice="plain"><option>-F</option>
 
149
        <replaceable>FILE</replaceable></arg>
125
150
      </group>
126
151
      <sbr/>
127
152
      <group>
137
162
        <arg choice="plain"><option>-n
138
163
        <replaceable>NAME</replaceable></option></arg>
139
164
      </group>
 
165
      <group>
 
166
        <arg choice="plain"><option>--no-ssh</option></arg>
 
167
        <arg choice="plain"><option>-S</option></arg>
 
168
      </group>
140
169
    </cmdsynopsis>
141
170
    <cmdsynopsis>
142
171
      <command>&COMMANDNAME;</command>
158
187
    <title>DESCRIPTION</title>
159
188
    <para>
160
189
      <command>&COMMANDNAME;</command> is a program to generate the
161
 
      OpenPGP key used by
 
190
      TLS and OpenPGP keys used by
162
191
      <citerefentry><refentrytitle>mandos-client</refentrytitle>
163
 
      <manvolnum>8mandos</manvolnum></citerefentry>.  The key is
164
 
      normally written to /etc/mandos for later installation into the
165
 
      initrd image, but this, and most other things, can be changed
166
 
      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.
167
196
    </para>
168
197
    <para>
169
198
      This program can also be used with the
170
 
      <option>--password</option> option to generate a ready-made
171
 
      section for <filename>clients.conf</filename> (see
 
199
      <option>--password</option> or <option>--passfile</option>
 
200
      options to generate a ready-made section for
 
201
      <filename>clients.conf</filename> (see
172
202
      <citerefentry><refentrytitle>mandos-clients.conf</refentrytitle>
173
203
      <manvolnum>5</manvolnum></citerefentry>).
174
204
    </para>
205
235
        <replaceable>DIRECTORY</replaceable></option></term>
206
236
        <listitem>
207
237
          <para>
208
 
            Target directory for key files.  Default is
209
 
            <filename>/etc/mandos</filename>.
 
238
            Target directory for key files.  Default is <filename
 
239
            class="directory">/etc/keys/mandos</filename>.
210
240
          </para>
211
241
        </listitem>
212
242
      </varlistentry>
218
248
        <replaceable>TYPE</replaceable></option></term>
219
249
        <listitem>
220
250
          <para>
221
 
            Key type.  Default is <quote>DSA</quote>.
 
251
            OpenPGP key type.  Default is <quote>RSA</quote>.
222
252
          </para>
223
253
        </listitem>
224
254
      </varlistentry>
230
260
        <replaceable>BITS</replaceable></option></term>
231
261
        <listitem>
232
262
          <para>
233
 
            Key length in bits.  Default is 2048.
 
263
            OpenPGP key length in bits.  Default is 4096.
234
264
          </para>
235
265
        </listitem>
236
266
      </varlistentry>
242
272
        <replaceable>KEYTYPE</replaceable></option></term>
243
273
        <listitem>
244
274
          <para>
245
 
            Subkey type.  Default is <quote>ELG-E</quote> (Elgamal
246
 
            encryption-only).
 
275
            OpenPGP subkey type.  Default is <quote>RSA</quote>
247
276
          </para>
248
277
        </listitem>
249
278
      </varlistentry>
255
284
        <replaceable>BITS</replaceable></option></term>
256
285
        <listitem>
257
286
          <para>
258
 
            Subkey length in bits.  Default is 2048.
 
287
            OpenPGP subkey length in bits.  Default is 4096.
259
288
          </para>
260
289
        </listitem>
261
290
      </varlistentry>
279
308
        <replaceable>TEXT</replaceable></option></term>
280
309
        <listitem>
281
310
          <para>
282
 
            Comment field for key.  The default value is
283
 
            <quote><literal>Mandos client key</literal></quote>.
 
311
            Comment field for key.  Default is empty.
284
312
          </para>
285
313
        </listitem>
286
314
      </varlistentry>
300
328
      </varlistentry>
301
329
      
302
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>
303
343
        <term><option>--force</option></term>
304
344
        <term><option>-f</option></term>
305
345
        <listitem>
314
354
        <listitem>
315
355
          <para>
316
356
            Prompt for a password and encrypt it with the key already
317
 
            present in either <filename>/etc/mandos</filename> or the
318
 
            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>
319
359
            option.  Outputs, on standard output, a section suitable
320
360
            for inclusion in <citerefentry><refentrytitle
321
361
            >mandos-clients.conf</refentrytitle><manvolnum
326
366
          </para>
327
367
        </listitem>
328
368
      </varlistentry>
 
369
      <varlistentry>
 
370
        <term><option>--passfile
 
371
        <replaceable>FILE</replaceable></option></term>
 
372
        <term><option>-F
 
373
        <replaceable>FILE</replaceable></option></term>
 
374
        <listitem>
 
375
          <para>
 
376
            The same as <option>--password</option>, but read from
 
377
            <replaceable>FILE</replaceable>, not the terminal.
 
378
          </para>
 
379
        </listitem>
 
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>
329
397
    </variablelist>
330
398
  </refsect1>
331
399
  
333
401
    <title>OVERVIEW</title>
334
402
    <xi:include href="overview.xml"/>
335
403
    <para>
336
 
      This program is a small utility to generate new OpenPGP keys for
337
 
      new Mandos clients, and to generate sections for inclusion in
338
 
      <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.
339
407
    </para>
340
408
  </refsect1>
341
409
  
364
432
    </variablelist>
365
433
  </refsect1>
366
434
  
367
 
  <refsect1 id="file">
 
435
  <refsect1 id="files">
368
436
    <title>FILES</title>
369
437
    <para>
370
438
      Use the <option>--dir</option> option to change where
373
441
    </para>
374
442
    <variablelist>
375
443
      <varlistentry>
376
 
        <term><filename>/etc/mandos/seckey.txt</filename></term>
 
444
        <term><filename>/etc/keys/mandos/seckey.txt</filename></term>
377
445
        <listitem>
378
446
          <para>
379
447
            OpenPGP secret key file which will be created or
382
450
        </listitem>
383
451
      </varlistentry>
384
452
      <varlistentry>
385
 
        <term><filename>/etc/mandos/pubkey.txt</filename></term>
 
453
        <term><filename>/etc/keys/mandos/pubkey.txt</filename></term>
386
454
        <listitem>
387
455
          <para>
388
456
            OpenPGP public key file which will be created or
391
459
        </listitem>
392
460
      </varlistentry>
393
461
      <varlistentry>
394
 
        <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>
395
479
        <listitem>
396
480
          <para>
397
481
            Temporary files will be written here if
402
486
    </variablelist>
403
487
  </refsect1>
404
488
  
405
 
<!--   <refsect1 id="bugs"> -->
406
 
<!--     <title>BUGS</title> -->
407
 
<!--     <para> -->
408
 
<!--     </para> -->
409
 
<!--   </refsect1> -->
 
489
  <refsect1 id="bugs">
 
490
    <title>BUGS</title>
 
491
    <xi:include href="bugs.xml"/>
 
492
  </refsect1>
410
493
  
411
494
  <refsect1 id="example">
412
495
    <title>EXAMPLE</title>
432
515
    </informalexample>
433
516
    <informalexample>
434
517
      <para>
435
 
        Prompt for a password, encrypt it with the key in
436
 
        <filename>/etc/mandos</filename> and output a section suitable
437
 
        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>.
438
521
      </para>
439
522
      <para>
440
523
        <userinput>&COMMANDNAME; --password</userinput>
442
525
    </informalexample>
443
526
    <informalexample>
444
527
      <para>
445
 
        Prompt for a password, encrypt it with the key in the
 
528
        Prompt for a password, encrypt it with the keys in the
446
529
        <filename>client-key</filename> directory and output a section
447
530
        suitable for <filename>clients.conf</filename>.
448
531
      </para>
473
556
  <refsect1 id="see_also">
474
557
    <title>SEE ALSO</title>
475
558
    <para>
 
559
      <citerefentry><refentrytitle>intro</refentrytitle>
 
560
      <manvolnum>8mandos</manvolnum></citerefentry>,
476
561
      <citerefentry><refentrytitle>gpg</refentrytitle>
477
562
      <manvolnum>1</manvolnum></citerefentry>,
478
563
      <citerefentry><refentrytitle>mandos-clients.conf</refentrytitle>
480
565
      <citerefentry><refentrytitle>mandos</refentrytitle>
481
566
      <manvolnum>8</manvolnum></citerefentry>,
482
567
      <citerefentry><refentrytitle>mandos-client</refentrytitle>
483
 
      <manvolnum>8mandos</manvolnum></citerefentry>
 
568
      <manvolnum>8mandos</manvolnum></citerefentry>,
 
569
      <citerefentry><refentrytitle>ssh-keyscan</refentrytitle>
 
570
      <manvolnum>1</manvolnum></citerefentry>
484
571
    </para>
485
572
  </refsect1>
486
573