/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: 2024-09-12 02:53:43 UTC
  • Revision ID: teddy@recompile.se-20240912025343-05elzcldczplvk89
Ignore some more files

* .bzrignore: Ignore "cl", which is used to temporarily save the
  commit message.  Ignore the .mypy_cache directories.  Ignore
  *.c.local files which are used by the tools to sort #include
  directives and associated comments.

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-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>
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>
 
49
    <xi:include href="legalnotice.xml"/>
60
50
  </refentryinfo>
61
 
 
 
51
  
62
52
  <refmeta>
63
53
    <refentrytitle>&COMMANDNAME;</refentrytitle>
64
54
    <manvolnum>8</manvolnum>
70
60
      Generate key and password for Mandos client and server.
71
61
    </refpurpose>
72
62
  </refnamediv>
73
 
 
 
63
  
74
64
  <refsynopsisdiv>
75
65
    <cmdsynopsis>
76
66
      <command>&COMMANDNAME;</command>
137
127
        <replaceable>TIME</replaceable></option></arg>
138
128
      </group>
139
129
      <sbr/>
140
 
      <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>
141
141
    </cmdsynopsis>
142
142
    <cmdsynopsis>
143
143
      <command>&COMMANDNAME;</command>
144
144
      <group choice="req">
145
145
        <arg choice="plain"><option>--password</option></arg>
146
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>
147
151
      </group>
148
152
      <sbr/>
149
153
      <group>
159
163
        <arg choice="plain"><option>-n
160
164
        <replaceable>NAME</replaceable></option></arg>
161
165
      </group>
 
166
      <group>
 
167
        <arg choice="plain"><option>--no-ssh</option></arg>
 
168
        <arg choice="plain"><option>-S</option></arg>
 
169
      </group>
162
170
    </cmdsynopsis>
163
171
    <cmdsynopsis>
164
172
      <command>&COMMANDNAME;</command>
180
188
    <title>DESCRIPTION</title>
181
189
    <para>
182
190
      <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.
 
191
      TLS and OpenPGP keys used by
 
192
      <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.
189
197
    </para>
190
198
    <para>
191
199
      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
 
200
      <option>--password</option> or <option>--passfile</option>
 
201
      options to generate a ready-made section for
 
202
      <filename>clients.conf</filename> (see
194
203
      <citerefentry><refentrytitle>mandos-clients.conf</refentrytitle>
195
204
      <manvolnum>5</manvolnum></citerefentry>).
196
205
    </para>
219
228
          </para>
220
229
        </listitem>
221
230
      </varlistentry>
222
 
 
 
231
      
223
232
      <varlistentry>
224
233
        <term><option>--dir
225
234
        <replaceable>DIRECTORY</replaceable></option></term>
227
236
        <replaceable>DIRECTORY</replaceable></option></term>
228
237
        <listitem>
229
238
          <para>
230
 
            Target directory for key files.  Default is
231
 
            <filename>/etc/mandos</filename>.
 
239
            Target directory for key files.  Default is <filename
 
240
            class="directory">/etc/keys/mandos</filename>.
232
241
          </para>
233
242
        </listitem>
234
243
      </varlistentry>
235
 
 
 
244
      
236
245
      <varlistentry>
237
246
        <term><option>--type
238
247
        <replaceable>TYPE</replaceable></option></term>
240
249
        <replaceable>TYPE</replaceable></option></term>
241
250
        <listitem>
242
251
          <para>
243
 
            Key type.  Default is <quote>DSA</quote>.
 
252
            OpenPGP key type.  Default is <quote>RSA</quote>.
244
253
          </para>
245
254
        </listitem>
246
255
      </varlistentry>
247
 
 
 
256
      
248
257
      <varlistentry>
249
258
        <term><option>--length
250
259
        <replaceable>BITS</replaceable></option></term>
252
261
        <replaceable>BITS</replaceable></option></term>
253
262
        <listitem>
254
263
          <para>
255
 
            Key length in bits.  Default is 2048.
 
264
            OpenPGP key length in bits.  Default is 4096.
256
265
          </para>
257
266
        </listitem>
258
267
      </varlistentry>
259
 
 
 
268
      
260
269
      <varlistentry>
261
270
        <term><option>--subtype
262
271
        <replaceable>KEYTYPE</replaceable></option></term>
264
273
        <replaceable>KEYTYPE</replaceable></option></term>
265
274
        <listitem>
266
275
          <para>
267
 
            Subkey type.  Default is <quote>ELG-E</quote> (Elgamal
268
 
            encryption-only).
 
276
            OpenPGP subkey type.  Default is <quote>RSA</quote>
269
277
          </para>
270
278
        </listitem>
271
279
      </varlistentry>
272
 
 
 
280
      
273
281
      <varlistentry>
274
282
        <term><option>--sublength
275
283
        <replaceable>BITS</replaceable></option></term>
277
285
        <replaceable>BITS</replaceable></option></term>
278
286
        <listitem>
279
287
          <para>
280
 
            Subkey length in bits.  Default is 2048.
 
288
            OpenPGP subkey length in bits.  Default is 4096.
281
289
          </para>
282
290
        </listitem>
283
291
      </varlistentry>
284
 
 
 
292
      
285
293
      <varlistentry>
286
294
        <term><option>--email
287
295
        <replaceable>ADDRESS</replaceable></option></term>
293
301
          </para>
294
302
        </listitem>
295
303
      </varlistentry>
296
 
 
 
304
      
297
305
      <varlistentry>
298
306
        <term><option>--comment
299
307
        <replaceable>TEXT</replaceable></option></term>
301
309
        <replaceable>TEXT</replaceable></option></term>
302
310
        <listitem>
303
311
          <para>
304
 
            Comment field for key.  The default value is
305
 
            <quote><literal>Mandos client key</literal></quote>.
 
312
            Comment field for key.  Default is empty.
306
313
          </para>
307
314
        </listitem>
308
315
      </varlistentry>
309
 
 
 
316
      
310
317
      <varlistentry>
311
318
        <term><option>--expire
312
319
        <replaceable>TIME</replaceable></option></term>
320
327
          </para>
321
328
        </listitem>
322
329
      </varlistentry>
323
 
 
 
330
      
 
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
      
324
343
      <varlistentry>
325
344
        <term><option>--force</option></term>
326
345
        <term><option>-f</option></term>
336
355
        <listitem>
337
356
          <para>
338
357
            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>
 
358
            present in either <filename>/etc/keys/mandos</filename> or
 
359
            the directory specified with the <option>--dir</option>
341
360
            option.  Outputs, on standard output, a section suitable
342
361
            for inclusion in <citerefentry><refentrytitle
343
362
            >mandos-clients.conf</refentrytitle><manvolnum
344
363
            >8</manvolnum></citerefentry>.  The host name or the name
345
364
            specified with the <option>--name</option> option is used
346
365
            for the section header.  All other options are ignored,
347
 
            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.
348
398
          </para>
349
399
        </listitem>
350
400
      </varlistentry>
351
401
    </variablelist>
352
402
  </refsect1>
353
 
 
 
403
  
354
404
  <refsect1 id="overview">
355
405
    <title>OVERVIEW</title>
356
406
    <xi:include href="overview.xml"/>
357
407
    <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.
 
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.
361
411
    </para>
362
412
  </refsect1>
363
 
 
 
413
  
364
414
  <refsect1 id="exit_status">
365
415
    <title>EXIT STATUS</title>
366
416
    <para>
386
436
    </variablelist>
387
437
  </refsect1>
388
438
  
389
 
  <refsect1 id="file">
 
439
  <refsect1 id="files">
390
440
    <title>FILES</title>
391
441
    <para>
392
442
      Use the <option>--dir</option> option to change where
395
445
    </para>
396
446
    <variablelist>
397
447
      <varlistentry>
398
 
        <term><filename>/etc/mandos/seckey.txt</filename></term>
 
448
        <term><filename>/etc/keys/mandos/seckey.txt</filename></term>
399
449
        <listitem>
400
450
          <para>
401
451
            OpenPGP secret key file which will be created or
404
454
        </listitem>
405
455
      </varlistentry>
406
456
      <varlistentry>
407
 
        <term><filename>/etc/mandos/pubkey.txt</filename></term>
 
457
        <term><filename>/etc/keys/mandos/pubkey.txt</filename></term>
408
458
        <listitem>
409
459
          <para>
410
460
            OpenPGP public key file which will be created or
413
463
        </listitem>
414
464
      </varlistentry>
415
465
      <varlistentry>
416
 
        <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>
417
483
        <listitem>
418
484
          <para>
419
485
            Temporary files will be written here if
423
489
      </varlistentry>
424
490
    </variablelist>
425
491
  </refsect1>
426
 
 
 
492
  
427
493
  <refsect1 id="bugs">
428
494
    <title>BUGS</title>
429
495
    <para>
430
 
      None are known at this time.
 
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.
431
501
    </para>
 
502
    <xi:include href="bugs.xml"/>
432
503
  </refsect1>
433
 
 
 
504
  
434
505
  <refsect1 id="example">
435
506
    <title>EXAMPLE</title>
436
507
    <informalexample>
455
526
    </informalexample>
456
527
    <informalexample>
457
528
      <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>.
 
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>.
461
532
      </para>
462
533
      <para>
463
534
        <userinput>&COMMANDNAME; --password</userinput>
465
536
    </informalexample>
466
537
    <informalexample>
467
538
      <para>
468
 
        Prompt for a password, encrypt it with the key in the
 
539
        Prompt for a password, encrypt it with the keys in the
469
540
        <filename>client-key</filename> directory and output a section
470
541
        suitable for <filename>clients.conf</filename>.
471
542
      </para>
477
548
      </para>
478
549
    </informalexample>
479
550
  </refsect1>
480
 
 
 
551
  
481
552
  <refsect1 id="security">
482
553
    <title>SECURITY</title>
483
554
    <para>
492
563
      <manvolnum>8</manvolnum></citerefentry>.
493
564
    </para>
494
565
  </refsect1>
495
 
 
 
566
  
496
567
  <refsect1 id="see_also">
497
568
    <title>SEE ALSO</title>
498
569
    <para>
 
570
      <citerefentry><refentrytitle>intro</refentrytitle>
 
571
      <manvolnum>8mandos</manvolnum></citerefentry>,
499
572
      <citerefentry><refentrytitle>gpg</refentrytitle>
500
573
      <manvolnum>1</manvolnum></citerefentry>,
501
574
      <citerefentry><refentrytitle>mandos-clients.conf</refentrytitle>
502
575
      <manvolnum>5</manvolnum></citerefentry>,
503
576
      <citerefentry><refentrytitle>mandos</refentrytitle>
504
577
      <manvolnum>8</manvolnum></citerefentry>,
505
 
      <citerefentry><refentrytitle>password-request</refentrytitle>
506
 
      <manvolnum>8mandos</manvolnum></citerefentry>
 
578
      <citerefentry><refentrytitle>mandos-client</refentrytitle>
 
579
      <manvolnum>8mandos</manvolnum></citerefentry>,
 
580
      <citerefentry><refentrytitle>ssh-keyscan</refentrytitle>
 
581
      <manvolnum>1</manvolnum></citerefentry>
507
582
    </para>
508
583
  </refsect1>
509
584