/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-09 23:34:15 UTC
  • Revision ID: teddy@recompile.se-20190209233415-m1ntebuepwna1xg1
Doc fix: Change some "/etc/mandos" to "/etc/keys/mandos"

* clients.conf: Change "/etc/mandos" to "/etc/keys/mandos" where
                appropriate
* mandos-keygen.xml: - '' -

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-08-31">
 
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>
37
 
    <legalnotice>
38
 
      <para>
39
 
        This manual page is free software: you can redistribute it
40
 
        and/or modify it under the terms of the GNU General Public
41
 
        License as published by the Free Software Foundation,
42
 
        either version 3 of the License, or (at your option) any
43
 
        later version.
44
 
      </para>
45
 
 
46
 
      <para>
47
 
        This manual page is distributed in the hope that it will
48
 
        be useful, but WITHOUT ANY WARRANTY; without even the
49
 
        implied warranty of MERCHANTABILITY or FITNESS FOR A
50
 
        PARTICULAR PURPOSE.  See the GNU General Public License
51
 
        for more details.
52
 
      </para>
53
 
 
54
 
      <para>
55
 
        You should have received a copy of the GNU General Public
56
 
        License along with this program; If not, see
57
 
        <ulink url="http://www.gnu.org/licenses/"/>.
58
 
      </para>
59
 
    </legalnotice>
 
48
    <xi:include href="legalnotice.xml"/>
60
49
  </refentryinfo>
61
 
 
 
50
  
62
51
  <refmeta>
63
52
    <refentrytitle>&COMMANDNAME;</refentrytitle>
64
53
    <manvolnum>8</manvolnum>
70
59
      Generate key and password for Mandos client and server.
71
60
    </refpurpose>
72
61
  </refnamediv>
73
 
 
 
62
  
74
63
  <refsynopsisdiv>
75
64
    <cmdsynopsis>
76
65
      <command>&COMMANDNAME;</command>
137
126
        <replaceable>TIME</replaceable></option></arg>
138
127
      </group>
139
128
      <sbr/>
140
 
      <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>
141
140
    </cmdsynopsis>
142
141
    <cmdsynopsis>
143
142
      <command>&COMMANDNAME;</command>
144
143
      <group choice="req">
145
144
        <arg choice="plain"><option>--password</option></arg>
146
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>
147
150
      </group>
148
151
      <sbr/>
149
152
      <group>
159
162
        <arg choice="plain"><option>-n
160
163
        <replaceable>NAME</replaceable></option></arg>
161
164
      </group>
 
165
      <group>
 
166
        <arg choice="plain"><option>--no-ssh</option></arg>
 
167
        <arg choice="plain"><option>-S</option></arg>
 
168
      </group>
162
169
    </cmdsynopsis>
163
170
    <cmdsynopsis>
164
171
      <command>&COMMANDNAME;</command>
180
187
    <title>DESCRIPTION</title>
181
188
    <para>
182
189
      <command>&COMMANDNAME;</command> is a program to generate the
183
 
      OpenPGP key used by
184
 
      <citerefentry><refentrytitle>password-request</refentrytitle>
185
 
      <manvolnum>8mandos</manvolnum></citerefentry>.  The key is
186
 
      normally written to /etc/mandos for later installation into the
187
 
      initrd image, but this, and most other things, can be changed
188
 
      with command line options.
 
190
      TLS and OpenPGP keys used by
 
191
      <citerefentry><refentrytitle>mandos-client</refentrytitle>
 
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.
189
196
    </para>
190
197
    <para>
191
198
      This program can also be used with the
192
 
      <option>--password</option> option to generate a ready-made
193
 
      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
194
202
      <citerefentry><refentrytitle>mandos-clients.conf</refentrytitle>
195
203
      <manvolnum>5</manvolnum></citerefentry>).
196
204
    </para>
219
227
          </para>
220
228
        </listitem>
221
229
      </varlistentry>
222
 
 
 
230
      
223
231
      <varlistentry>
224
232
        <term><option>--dir
225
233
        <replaceable>DIRECTORY</replaceable></option></term>
227
235
        <replaceable>DIRECTORY</replaceable></option></term>
228
236
        <listitem>
229
237
          <para>
230
 
            Target directory for key files.  Default is
231
 
            <filename>/etc/mandos</filename>.
 
238
            Target directory for key files.  Default is <filename
 
239
            class="directory">/etc/keys/mandos</filename>.
232
240
          </para>
233
241
        </listitem>
234
242
      </varlistentry>
235
 
 
 
243
      
236
244
      <varlistentry>
237
245
        <term><option>--type
238
246
        <replaceable>TYPE</replaceable></option></term>
240
248
        <replaceable>TYPE</replaceable></option></term>
241
249
        <listitem>
242
250
          <para>
243
 
            Key type.  Default is <quote>DSA</quote>.
 
251
            OpenPGP key type.  Default is <quote>RSA</quote>.
244
252
          </para>
245
253
        </listitem>
246
254
      </varlistentry>
247
 
 
 
255
      
248
256
      <varlistentry>
249
257
        <term><option>--length
250
258
        <replaceable>BITS</replaceable></option></term>
252
260
        <replaceable>BITS</replaceable></option></term>
253
261
        <listitem>
254
262
          <para>
255
 
            Key length in bits.  Default is 2048.
 
263
            OpenPGP key length in bits.  Default is 4096.
256
264
          </para>
257
265
        </listitem>
258
266
      </varlistentry>
259
 
 
 
267
      
260
268
      <varlistentry>
261
269
        <term><option>--subtype
262
270
        <replaceable>KEYTYPE</replaceable></option></term>
264
272
        <replaceable>KEYTYPE</replaceable></option></term>
265
273
        <listitem>
266
274
          <para>
267
 
            Subkey type.  Default is <quote>ELG-E</quote> (Elgamal
268
 
            encryption-only).
 
275
            OpenPGP subkey type.  Default is <quote>RSA</quote>
269
276
          </para>
270
277
        </listitem>
271
278
      </varlistentry>
272
 
 
 
279
      
273
280
      <varlistentry>
274
281
        <term><option>--sublength
275
282
        <replaceable>BITS</replaceable></option></term>
277
284
        <replaceable>BITS</replaceable></option></term>
278
285
        <listitem>
279
286
          <para>
280
 
            Subkey length in bits.  Default is 2048.
 
287
            OpenPGP subkey length in bits.  Default is 4096.
281
288
          </para>
282
289
        </listitem>
283
290
      </varlistentry>
284
 
 
 
291
      
285
292
      <varlistentry>
286
293
        <term><option>--email
287
294
        <replaceable>ADDRESS</replaceable></option></term>
293
300
          </para>
294
301
        </listitem>
295
302
      </varlistentry>
296
 
 
 
303
      
297
304
      <varlistentry>
298
305
        <term><option>--comment
299
306
        <replaceable>TEXT</replaceable></option></term>
301
308
        <replaceable>TEXT</replaceable></option></term>
302
309
        <listitem>
303
310
          <para>
304
 
            Comment field for key.  The default value is
305
 
            <quote><literal>Mandos client key</literal></quote>.
 
311
            Comment field for key.  Default is empty.
306
312
          </para>
307
313
        </listitem>
308
314
      </varlistentry>
309
 
 
 
315
      
310
316
      <varlistentry>
311
317
        <term><option>--expire
312
318
        <replaceable>TIME</replaceable></option></term>
320
326
          </para>
321
327
        </listitem>
322
328
      </varlistentry>
323
 
 
 
329
      
 
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
      
324
342
      <varlistentry>
325
343
        <term><option>--force</option></term>
326
344
        <term><option>-f</option></term>
336
354
        <listitem>
337
355
          <para>
338
356
            Prompt for a password and encrypt it with the key already
339
 
            present in either <filename>/etc/mandos</filename> or the
340
 
            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>
341
359
            option.  Outputs, on standard output, a section suitable
342
360
            for inclusion in <citerefentry><refentrytitle
343
361
            >mandos-clients.conf</refentrytitle><manvolnum
348
366
          </para>
349
367
        </listitem>
350
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>
351
397
    </variablelist>
352
398
  </refsect1>
353
 
 
 
399
  
354
400
  <refsect1 id="overview">
355
401
    <title>OVERVIEW</title>
356
402
    <xi:include href="overview.xml"/>
357
403
    <para>
358
 
      This program is a small utility to generate new OpenPGP keys for
359
 
      new Mandos clients, and to generate sections for inclusion in
360
 
      <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.
361
407
    </para>
362
408
  </refsect1>
363
 
 
 
409
  
364
410
  <refsect1 id="exit_status">
365
411
    <title>EXIT STATUS</title>
366
412
    <para>
386
432
    </variablelist>
387
433
  </refsect1>
388
434
  
389
 
  <refsect1 id="file">
 
435
  <refsect1 id="files">
390
436
    <title>FILES</title>
391
437
    <para>
392
438
      Use the <option>--dir</option> option to change where
395
441
    </para>
396
442
    <variablelist>
397
443
      <varlistentry>
398
 
        <term><filename>/etc/mandos/seckey.txt</filename></term>
 
444
        <term><filename>/etc/keys/mandos/seckey.txt</filename></term>
399
445
        <listitem>
400
446
          <para>
401
447
            OpenPGP secret key file which will be created or
404
450
        </listitem>
405
451
      </varlistentry>
406
452
      <varlistentry>
407
 
        <term><filename>/etc/mandos/pubkey.txt</filename></term>
 
453
        <term><filename>/etc/keys/mandos/pubkey.txt</filename></term>
408
454
        <listitem>
409
455
          <para>
410
456
            OpenPGP public key file which will be created or
413
459
        </listitem>
414
460
      </varlistentry>
415
461
      <varlistentry>
416
 
        <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>
417
479
        <listitem>
418
480
          <para>
419
481
            Temporary files will be written here if
423
485
      </varlistentry>
424
486
    </variablelist>
425
487
  </refsect1>
426
 
 
 
488
  
427
489
  <refsect1 id="bugs">
428
490
    <title>BUGS</title>
429
 
    <para>
430
 
      None are known at this time.
431
 
    </para>
 
491
    <xi:include href="bugs.xml"/>
432
492
  </refsect1>
433
 
 
 
493
  
434
494
  <refsect1 id="example">
435
495
    <title>EXAMPLE</title>
436
496
    <informalexample>
455
515
    </informalexample>
456
516
    <informalexample>
457
517
      <para>
458
 
        Prompt for a password, encrypt it with the key in
459
 
        <filename>/etc/mandos</filename> and output a section suitable
460
 
        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>.
461
521
      </para>
462
522
      <para>
463
523
        <userinput>&COMMANDNAME; --password</userinput>
465
525
    </informalexample>
466
526
    <informalexample>
467
527
      <para>
468
 
        Prompt for a password, encrypt it with the key in the
 
528
        Prompt for a password, encrypt it with the keys in the
469
529
        <filename>client-key</filename> directory and output a section
470
530
        suitable for <filename>clients.conf</filename>.
471
531
      </para>
477
537
      </para>
478
538
    </informalexample>
479
539
  </refsect1>
480
 
 
 
540
  
481
541
  <refsect1 id="security">
482
542
    <title>SECURITY</title>
483
543
    <para>
492
552
      <manvolnum>8</manvolnum></citerefentry>.
493
553
    </para>
494
554
  </refsect1>
495
 
 
 
555
  
496
556
  <refsect1 id="see_also">
497
557
    <title>SEE ALSO</title>
498
558
    <para>
 
559
      <citerefentry><refentrytitle>intro</refentrytitle>
 
560
      <manvolnum>8mandos</manvolnum></citerefentry>,
499
561
      <citerefentry><refentrytitle>gpg</refentrytitle>
500
562
      <manvolnum>1</manvolnum></citerefentry>,
501
563
      <citerefentry><refentrytitle>mandos-clients.conf</refentrytitle>
502
564
      <manvolnum>5</manvolnum></citerefentry>,
503
565
      <citerefentry><refentrytitle>mandos</refentrytitle>
504
566
      <manvolnum>8</manvolnum></citerefentry>,
505
 
      <citerefentry><refentrytitle>password-request</refentrytitle>
506
 
      <manvolnum>8mandos</manvolnum></citerefentry>
 
567
      <citerefentry><refentrytitle>mandos-client</refentrytitle>
 
568
      <manvolnum>8mandos</manvolnum></citerefentry>,
 
569
      <citerefentry><refentrytitle>ssh-keyscan</refentrytitle>
 
570
      <manvolnum>1</manvolnum></citerefentry>
507
571
    </para>
508
572
  </refsect1>
509
573