/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-08-05 21:14:05 UTC
  • Revision ID: teddy@recompile.se-20190805211405-9m6hecekaihpttz9
Override lintian warnings about upgrading from old versions

There are some really things which are imperative that we fix in case
someone were to upgrade from a really old version.  We want to keep
these fixes in the postinst maintainer scripts, even though lintian
complains about such old upgrades not being supported by Debian in
general.  We prefer the code being there, for the sake of the users.

* debian/mandos-client.lintian-overrides
  (maintainer-script-supports-ancient-package-version): New.
  debian/mandos.lintian-overrides
  (maintainer-script-supports-ancient-package-version): - '' -

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-07-18">
 
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>
 
45
      <year>2019</year>
34
46
      <holder>Teddy Hogeborn</holder>
35
47
      <holder>Björn Påhlsson</holder>
36
48
    </copyright>
115
127
        <replaceable>TIME</replaceable></option></arg>
116
128
      </group>
117
129
      <sbr/>
118
 
      <arg><option>--force</option></arg>
 
130
      <group>
 
131
        <arg choice="plain"><option>--tls-keytype
 
132
        <replaceable>KEYTYPE</replaceable></option></arg>
 
133
        <arg choice="plain"><option>-T
 
134
        <replaceable>KEYTYPE</replaceable></option></arg>
 
135
      </group>
 
136
      <sbr/>
 
137
      <group>
 
138
        <arg choice="plain"><option>--force</option></arg>
 
139
        <arg choice="plain"><option>-f</option></arg>
 
140
      </group>
119
141
    </cmdsynopsis>
120
142
    <cmdsynopsis>
121
143
      <command>&COMMANDNAME;</command>
122
144
      <group choice="req">
123
145
        <arg choice="plain"><option>--password</option></arg>
124
146
        <arg choice="plain"><option>-p</option></arg>
 
147
        <arg choice="plain"><option>--passfile
 
148
        <replaceable>FILE</replaceable></option></arg>
 
149
        <arg choice="plain"><option>-F</option>
 
150
        <replaceable>FILE</replaceable></arg>
125
151
      </group>
126
152
      <sbr/>
127
153
      <group>
137
163
        <arg choice="plain"><option>-n
138
164
        <replaceable>NAME</replaceable></option></arg>
139
165
      </group>
 
166
      <group>
 
167
        <arg choice="plain"><option>--no-ssh</option></arg>
 
168
        <arg choice="plain"><option>-S</option></arg>
 
169
      </group>
140
170
    </cmdsynopsis>
141
171
    <cmdsynopsis>
142
172
      <command>&COMMANDNAME;</command>
158
188
    <title>DESCRIPTION</title>
159
189
    <para>
160
190
      <command>&COMMANDNAME;</command> is a program to generate the
161
 
      OpenPGP key used by
 
191
      TLS and OpenPGP keys used by
162
192
      <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.
 
193
      <manvolnum>8mandos</manvolnum></citerefentry>.  The keys are
 
194
      normally written to /etc/keys/mandos for later installation into
 
195
      the initrd image, but this, and most other things, can be
 
196
      changed with command line options.
167
197
    </para>
168
198
    <para>
169
199
      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
 
200
      <option>--password</option> or <option>--passfile</option>
 
201
      options to generate a ready-made section for
 
202
      <filename>clients.conf</filename> (see
172
203
      <citerefentry><refentrytitle>mandos-clients.conf</refentrytitle>
173
204
      <manvolnum>5</manvolnum></citerefentry>).
174
205
    </para>
205
236
        <replaceable>DIRECTORY</replaceable></option></term>
206
237
        <listitem>
207
238
          <para>
208
 
            Target directory for key files.  Default is
209
 
            <filename>/etc/mandos</filename>.
 
239
            Target directory for key files.  Default is <filename
 
240
            class="directory">/etc/keys/mandos</filename>.
210
241
          </para>
211
242
        </listitem>
212
243
      </varlistentry>
218
249
        <replaceable>TYPE</replaceable></option></term>
219
250
        <listitem>
220
251
          <para>
221
 
            Key type.  Default is <quote>DSA</quote>.
 
252
            OpenPGP key type.  Default is <quote>RSA</quote>.
222
253
          </para>
223
254
        </listitem>
224
255
      </varlistentry>
230
261
        <replaceable>BITS</replaceable></option></term>
231
262
        <listitem>
232
263
          <para>
233
 
            Key length in bits.  Default is 2048.
 
264
            OpenPGP key length in bits.  Default is 4096.
234
265
          </para>
235
266
        </listitem>
236
267
      </varlistentry>
242
273
        <replaceable>KEYTYPE</replaceable></option></term>
243
274
        <listitem>
244
275
          <para>
245
 
            Subkey type.  Default is <quote>ELG-E</quote> (Elgamal
246
 
            encryption-only).
 
276
            OpenPGP subkey type.  Default is <quote>RSA</quote>
247
277
          </para>
248
278
        </listitem>
249
279
      </varlistentry>
255
285
        <replaceable>BITS</replaceable></option></term>
256
286
        <listitem>
257
287
          <para>
258
 
            Subkey length in bits.  Default is 2048.
 
288
            OpenPGP subkey length in bits.  Default is 4096.
259
289
          </para>
260
290
        </listitem>
261
291
      </varlistentry>
279
309
        <replaceable>TEXT</replaceable></option></term>
280
310
        <listitem>
281
311
          <para>
282
 
            Comment field for key.  The default value is
283
 
            <quote><literal>Mandos client key</literal></quote>.
 
312
            Comment field for key.  Default is empty.
284
313
          </para>
285
314
        </listitem>
286
315
      </varlistentry>
300
329
      </varlistentry>
301
330
      
302
331
      <varlistentry>
 
332
        <term><option>--tls-keytype
 
333
        <replaceable>KEYTYPE</replaceable></option></term>
 
334
        <term><option>-T
 
335
        <replaceable>KEYTYPE</replaceable></option></term>
 
336
        <listitem>
 
337
          <para>
 
338
            TLS key type.  Default is <quote>ed25519</quote>
 
339
          </para>
 
340
        </listitem>
 
341
      </varlistentry>
 
342
      
 
343
      <varlistentry>
303
344
        <term><option>--force</option></term>
304
345
        <term><option>-f</option></term>
305
346
        <listitem>
314
355
        <listitem>
315
356
          <para>
316
357
            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>
 
358
            present in either <filename>/etc/keys/mandos</filename> or
 
359
            the directory specified with the <option>--dir</option>
319
360
            option.  Outputs, on standard output, a section suitable
320
361
            for inclusion in <citerefentry><refentrytitle
321
362
            >mandos-clients.conf</refentrytitle><manvolnum
322
363
            >8</manvolnum></citerefentry>.  The host name or the name
323
364
            specified with the <option>--name</option> option is used
324
365
            for the section header.  All other options are ignored,
325
 
            and no key is created.
 
366
            and no key is created.  Note: white space is stripped from
 
367
            the beginning and from the end of the password; See <xref
 
368
            linkend="bugs"/>.
 
369
          </para>
 
370
        </listitem>
 
371
      </varlistentry>
 
372
      <varlistentry>
 
373
        <term><option>--passfile
 
374
        <replaceable>FILE</replaceable></option></term>
 
375
        <term><option>-F
 
376
        <replaceable>FILE</replaceable></option></term>
 
377
        <listitem>
 
378
          <para>
 
379
            The same as <option>--password</option>, but read from
 
380
            <replaceable>FILE</replaceable>, not the terminal, and
 
381
            white space is not stripped from the password in any way.
 
382
          </para>
 
383
        </listitem>
 
384
      </varlistentry>
 
385
      <varlistentry>
 
386
        <term><option>--no-ssh</option></term>
 
387
        <term><option>-S</option></term>
 
388
        <listitem>
 
389
          <para>
 
390
            When <option>--password</option> or
 
391
            <option>--passfile</option> is given, this option will
 
392
            prevent <command>&COMMANDNAME;</command> from calling
 
393
            <command>ssh-keyscan</command> to get an SSH fingerprint
 
394
            for this host and, if successful, output suitable config
 
395
            options to use this fingerprint as a
 
396
            <option>checker</option> option in the output.  This is
 
397
            otherwise the default behavior.
326
398
          </para>
327
399
        </listitem>
328
400
      </varlistentry>
333
405
    <title>OVERVIEW</title>
334
406
    <xi:include href="overview.xml"/>
335
407
    <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.
 
408
      This program is a small utility to generate new TLS and OpenPGP
 
409
      keys for new Mandos clients, and to generate sections for
 
410
      inclusion in <filename>clients.conf</filename> on the server.
339
411
    </para>
340
412
  </refsect1>
341
413
  
364
436
    </variablelist>
365
437
  </refsect1>
366
438
  
367
 
  <refsect1 id="file">
 
439
  <refsect1 id="files">
368
440
    <title>FILES</title>
369
441
    <para>
370
442
      Use the <option>--dir</option> option to change where
373
445
    </para>
374
446
    <variablelist>
375
447
      <varlistentry>
376
 
        <term><filename>/etc/mandos/seckey.txt</filename></term>
 
448
        <term><filename>/etc/keys/mandos/seckey.txt</filename></term>
377
449
        <listitem>
378
450
          <para>
379
451
            OpenPGP secret key file which will be created or
382
454
        </listitem>
383
455
      </varlistentry>
384
456
      <varlistentry>
385
 
        <term><filename>/etc/mandos/pubkey.txt</filename></term>
 
457
        <term><filename>/etc/keys/mandos/pubkey.txt</filename></term>
386
458
        <listitem>
387
459
          <para>
388
460
            OpenPGP public key file which will be created or
391
463
        </listitem>
392
464
      </varlistentry>
393
465
      <varlistentry>
394
 
        <term><filename>/tmp</filename></term>
 
466
        <term><filename>/etc/keys/mandos/tls-privkey.pem</filename></term>
 
467
        <listitem>
 
468
          <para>
 
469
            Private key file which will be created or overwritten.
 
470
          </para>
 
471
        </listitem>
 
472
      </varlistentry>
 
473
      <varlistentry>
 
474
        <term><filename>/etc/keys/mandos/tls-pubkey.pem</filename></term>
 
475
        <listitem>
 
476
          <para>
 
477
            Public key file which will be created or overwritten.
 
478
          </para>
 
479
        </listitem>
 
480
      </varlistentry>
 
481
      <varlistentry>
 
482
        <term><filename class="directory">/tmp</filename></term>
395
483
        <listitem>
396
484
          <para>
397
485
            Temporary files will be written here if
402
490
    </variablelist>
403
491
  </refsect1>
404
492
  
405
 
<!--   <refsect1 id="bugs"> -->
406
 
<!--     <title>BUGS</title> -->
407
 
<!--     <para> -->
408
 
<!--     </para> -->
409
 
<!--   </refsect1> -->
 
493
  <refsect1 id="bugs">
 
494
    <title>BUGS</title>
 
495
    <para>
 
496
      The <option>--password</option>/<option>-p</option> option
 
497
      strips white space from the start and from the end of the
 
498
      password before using it.  If this is a problem, use the
 
499
      <option>--passfile</option> option instead, which does not do
 
500
      this.
 
501
    </para>
 
502
    <xi:include href="bugs.xml"/>
 
503
  </refsect1>
410
504
  
411
505
  <refsect1 id="example">
412
506
    <title>EXAMPLE</title>
432
526
    </informalexample>
433
527
    <informalexample>
434
528
      <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>.
 
529
        Prompt for a password, encrypt it with the keys in <filename
 
530
        class="directory">/etc/keys/mandos</filename> and output a
 
531
        section suitable for <filename>clients.conf</filename>.
438
532
      </para>
439
533
      <para>
440
534
        <userinput>&COMMANDNAME; --password</userinput>
442
536
    </informalexample>
443
537
    <informalexample>
444
538
      <para>
445
 
        Prompt for a password, encrypt it with the key in the
 
539
        Prompt for a password, encrypt it with the keys in the
446
540
        <filename>client-key</filename> directory and output a section
447
541
        suitable for <filename>clients.conf</filename>.
448
542
      </para>
473
567
  <refsect1 id="see_also">
474
568
    <title>SEE ALSO</title>
475
569
    <para>
 
570
      <citerefentry><refentrytitle>intro</refentrytitle>
 
571
      <manvolnum>8mandos</manvolnum></citerefentry>,
476
572
      <citerefentry><refentrytitle>gpg</refentrytitle>
477
573
      <manvolnum>1</manvolnum></citerefentry>,
478
574
      <citerefentry><refentrytitle>mandos-clients.conf</refentrytitle>
480
576
      <citerefentry><refentrytitle>mandos</refentrytitle>
481
577
      <manvolnum>8</manvolnum></citerefentry>,
482
578
      <citerefentry><refentrytitle>mandos-client</refentrytitle>
483
 
      <manvolnum>8mandos</manvolnum></citerefentry>
 
579
      <manvolnum>8mandos</manvolnum></citerefentry>,
 
580
      <citerefentry><refentrytitle>ssh-keyscan</refentrytitle>
 
581
      <manvolnum>1</manvolnum></citerefentry>
484
582
    </para>
485
583
  </refsect1>
486
584