/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

Merge new wireless network hook.  Fix bridge network hook to use
hardware addresses instead of interface names.  Implement and document
new "CONNECT" environment variable for network hooks.

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 "2019-07-18">
 
5
<!ENTITY TIMESTAMP "2011-10-03">
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>
37
36
      <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>
46
37
      <holder>Teddy Hogeborn</holder>
47
38
      <holder>Björn Påhlsson</holder>
48
39
    </copyright>
127
118
        <replaceable>TIME</replaceable></option></arg>
128
119
      </group>
129
120
      <sbr/>
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>
 
121
      <arg><option>--force</option></arg>
141
122
    </cmdsynopsis>
142
123
    <cmdsynopsis>
143
124
      <command>&COMMANDNAME;</command>
163
144
        <arg choice="plain"><option>-n
164
145
        <replaceable>NAME</replaceable></option></arg>
165
146
      </group>
166
 
      <group>
167
 
        <arg choice="plain"><option>--no-ssh</option></arg>
168
 
        <arg choice="plain"><option>-S</option></arg>
169
 
      </group>
170
147
    </cmdsynopsis>
171
148
    <cmdsynopsis>
172
149
      <command>&COMMANDNAME;</command>
188
165
    <title>DESCRIPTION</title>
189
166
    <para>
190
167
      <command>&COMMANDNAME;</command> is a program to generate the
191
 
      TLS and OpenPGP keys used by
 
168
      OpenPGP key used by
192
169
      <citerefentry><refentrytitle>mandos-client</refentrytitle>
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.
 
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.
197
174
    </para>
198
175
    <para>
199
176
      This program can also be used with the
236
213
        <replaceable>DIRECTORY</replaceable></option></term>
237
214
        <listitem>
238
215
          <para>
239
 
            Target directory for key files.  Default is <filename
240
 
            class="directory">/etc/keys/mandos</filename>.
 
216
            Target directory for key files.  Default is
 
217
            <filename class="directory">/etc/mandos</filename>.
241
218
          </para>
242
219
        </listitem>
243
220
      </varlistentry>
249
226
        <replaceable>TYPE</replaceable></option></term>
250
227
        <listitem>
251
228
          <para>
252
 
            OpenPGP key type.  Default is <quote>RSA</quote>.
 
229
            Key type.  Default is <quote>DSA</quote>.
253
230
          </para>
254
231
        </listitem>
255
232
      </varlistentry>
261
238
        <replaceable>BITS</replaceable></option></term>
262
239
        <listitem>
263
240
          <para>
264
 
            OpenPGP key length in bits.  Default is 4096.
 
241
            Key length in bits.  Default is 2048.
265
242
          </para>
266
243
        </listitem>
267
244
      </varlistentry>
273
250
        <replaceable>KEYTYPE</replaceable></option></term>
274
251
        <listitem>
275
252
          <para>
276
 
            OpenPGP subkey type.  Default is <quote>RSA</quote>
 
253
            Subkey type.  Default is <quote>ELG-E</quote> (Elgamal
 
254
            encryption-only).
277
255
          </para>
278
256
        </listitem>
279
257
      </varlistentry>
285
263
        <replaceable>BITS</replaceable></option></term>
286
264
        <listitem>
287
265
          <para>
288
 
            OpenPGP subkey length in bits.  Default is 4096.
 
266
            Subkey length in bits.  Default is 2048.
289
267
          </para>
290
268
        </listitem>
291
269
      </varlistentry>
309
287
        <replaceable>TEXT</replaceable></option></term>
310
288
        <listitem>
311
289
          <para>
312
 
            Comment field for key.  Default is empty.
 
290
            Comment field for key.  The default value is
 
291
            <quote><literal>Mandos client key</literal></quote>.
313
292
          </para>
314
293
        </listitem>
315
294
      </varlistentry>
329
308
      </varlistentry>
330
309
      
331
310
      <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>
344
311
        <term><option>--force</option></term>
345
312
        <term><option>-f</option></term>
346
313
        <listitem>
355
322
        <listitem>
356
323
          <para>
357
324
            Prompt for a password and encrypt it with the key already
358
 
            present in either <filename>/etc/keys/mandos</filename> or
359
 
            the directory specified with the <option>--dir</option>
 
325
            present in either <filename>/etc/mandos</filename> or the
 
326
            directory specified with the <option>--dir</option>
360
327
            option.  Outputs, on standard output, a section suitable
361
328
            for inclusion in <citerefentry><refentrytitle
362
329
            >mandos-clients.conf</refentrytitle><manvolnum
363
330
            >8</manvolnum></citerefentry>.  The host name or the name
364
331
            specified with the <option>--name</option> option is used
365
332
            for the section header.  All other options are ignored,
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"/>.
 
333
            and no key is created.
369
334
          </para>
370
335
        </listitem>
371
336
      </varlistentry>
377
342
        <listitem>
378
343
          <para>
379
344
            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.
 
345
            <replaceable>FILE</replaceable>, not the terminal.
398
346
          </para>
399
347
        </listitem>
400
348
      </varlistentry>
405
353
    <title>OVERVIEW</title>
406
354
    <xi:include href="overview.xml"/>
407
355
    <para>
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.
 
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.
411
359
    </para>
412
360
  </refsect1>
413
361
  
445
393
    </para>
446
394
    <variablelist>
447
395
      <varlistentry>
448
 
        <term><filename>/etc/keys/mandos/seckey.txt</filename></term>
 
396
        <term><filename>/etc/mandos/seckey.txt</filename></term>
449
397
        <listitem>
450
398
          <para>
451
399
            OpenPGP secret key file which will be created or
454
402
        </listitem>
455
403
      </varlistentry>
456
404
      <varlistentry>
457
 
        <term><filename>/etc/keys/mandos/pubkey.txt</filename></term>
 
405
        <term><filename>/etc/mandos/pubkey.txt</filename></term>
458
406
        <listitem>
459
407
          <para>
460
408
            OpenPGP public key file which will be created or
463
411
        </listitem>
464
412
      </varlistentry>
465
413
      <varlistentry>
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
414
        <term><filename class="directory">/tmp</filename></term>
483
415
        <listitem>
484
416
          <para>
490
422
    </variablelist>
491
423
  </refsect1>
492
424
  
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>
 
425
<!--   <refsect1 id="bugs"> -->
 
426
<!--     <title>BUGS</title> -->
 
427
<!--     <para> -->
 
428
<!--     </para> -->
 
429
<!--   </refsect1> -->
504
430
  
505
431
  <refsect1 id="example">
506
432
    <title>EXAMPLE</title>
526
452
    </informalexample>
527
453
    <informalexample>
528
454
      <para>
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>.
 
455
        Prompt for a password, encrypt it with the key in <filename
 
456
        class="directory">/etc/mandos</filename> and output a section
 
457
        suitable for <filename>clients.conf</filename>.
532
458
      </para>
533
459
      <para>
534
460
        <userinput>&COMMANDNAME; --password</userinput>
536
462
    </informalexample>
537
463
    <informalexample>
538
464
      <para>
539
 
        Prompt for a password, encrypt it with the keys in the
 
465
        Prompt for a password, encrypt it with the key in the
540
466
        <filename>client-key</filename> directory and output a section
541
467
        suitable for <filename>clients.conf</filename>.
542
468
      </para>
576
502
      <citerefentry><refentrytitle>mandos</refentrytitle>
577
503
      <manvolnum>8</manvolnum></citerefentry>,
578
504
      <citerefentry><refentrytitle>mandos-client</refentrytitle>
579
 
      <manvolnum>8mandos</manvolnum></citerefentry>,
580
 
      <citerefentry><refentrytitle>ssh-keyscan</refentrytitle>
581
 
      <manvolnum>1</manvolnum></citerefentry>
 
505
      <manvolnum>8mandos</manvolnum></citerefentry>
582
506
    </para>
583
507
  </refsect1>
584
508