/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

  • Committer: Teddy Hogeborn
  • Date: 2008-08-31 07:32:05 UTC
  • Revision ID: teddy@fukt.bsnet.se-20080831073205-9hggg03i1iird264
* mandos-keygen.xml (SYNOPSIS): Put long options before short.
* mandos.xml (SYNOPSIS): - '' -
* plugins.d/password-prompt.xml (SYNOPSIS): - '' -
* plugins.d/password-request.xml (SYNOPSIS): - '' -

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">
4
5
<!ENTITY COMMANDNAME "mandos-keygen">
5
 
<!ENTITY TIMESTAMP "2019-02-10">
6
 
<!ENTITY % common SYSTEM "common.ent">
7
 
%common;
 
6
<!ENTITY TIMESTAMP "2008-08-31">
8
7
]>
9
8
 
10
9
<refentry xmlns:xi="http://www.w3.org/2001/XInclude">
12
11
    <title>Mandos Manual</title>
13
12
    <!-- NWalsh’s docbook scripts use this to generate the footer: -->
14
13
    <productname>Mandos</productname>
15
 
    <productnumber>&version;</productnumber>
 
14
    <productnumber>&VERSION;</productnumber>
16
15
    <date>&TIMESTAMP;</date>
17
16
    <authorgroup>
18
17
      <author>
19
18
        <firstname>Björn</firstname>
20
19
        <surname>Påhlsson</surname>
21
20
        <address>
22
 
          <email>belorn@recompile.se</email>
 
21
          <email>belorn@fukt.bsnet.se</email>
23
22
        </address>
24
23
      </author>
25
24
      <author>
26
25
        <firstname>Teddy</firstname>
27
26
        <surname>Hogeborn</surname>
28
27
        <address>
29
 
          <email>teddy@recompile.se</email>
 
28
          <email>teddy@fukt.bsnet.se</email>
30
29
        </address>
31
30
      </author>
32
31
    </authorgroup>
33
32
    <copyright>
34
33
      <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
34
      <holder>Teddy Hogeborn</holder>
46
35
      <holder>Björn Påhlsson</holder>
47
36
    </copyright>
48
 
    <xi:include href="legalnotice.xml"/>
 
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
60
  </refentryinfo>
50
 
  
 
61
 
51
62
  <refmeta>
52
63
    <refentrytitle>&COMMANDNAME;</refentrytitle>
53
64
    <manvolnum>8</manvolnum>
56
67
  <refnamediv>
57
68
    <refname><command>&COMMANDNAME;</command></refname>
58
69
    <refpurpose>
59
 
      Generate key and password for Mandos client and server.
 
70
      Generate keys for <citerefentry><refentrytitle>password-request
 
71
      </refentrytitle><manvolnum>8mandos</manvolnum></citerefentry>
60
72
    </refpurpose>
61
73
  </refnamediv>
62
 
  
 
74
 
63
75
  <refsynopsisdiv>
64
76
    <cmdsynopsis>
65
77
      <command>&COMMANDNAME;</command>
126
138
        <replaceable>TIME</replaceable></option></arg>
127
139
      </group>
128
140
      <sbr/>
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
      <arg><option>--force</option></arg>
140
142
    </cmdsynopsis>
141
143
    <cmdsynopsis>
142
144
      <command>&COMMANDNAME;</command>
143
145
      <group choice="req">
144
146
        <arg choice="plain"><option>--password</option></arg>
145
147
        <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>
150
148
      </group>
151
149
      <sbr/>
152
150
      <group>
162
160
        <arg choice="plain"><option>-n
163
161
        <replaceable>NAME</replaceable></option></arg>
164
162
      </group>
165
 
      <group>
166
 
        <arg choice="plain"><option>--no-ssh</option></arg>
167
 
        <arg choice="plain"><option>-S</option></arg>
168
 
      </group>
169
163
    </cmdsynopsis>
170
164
    <cmdsynopsis>
171
165
      <command>&COMMANDNAME;</command>
182
176
      </group>
183
177
    </cmdsynopsis>
184
178
  </refsynopsisdiv>
185
 
  
 
179
 
186
180
  <refsect1 id="description">
187
181
    <title>DESCRIPTION</title>
188
182
    <para>
189
183
      <command>&COMMANDNAME;</command> is a program to generate the
190
 
      TLS and OpenPGP keys used by
191
 
      <citerefentry><refentrytitle>mandos-client</refentrytitle>
 
184
      OpenPGP keys used by
 
185
      <citerefentry><refentrytitle>password-request</refentrytitle>
192
186
      <manvolnum>8mandos</manvolnum></citerefentry>.  The keys are
193
187
      normally written to /etc/mandos for later installation into the
194
 
      initrd image, but this, and most other things, can be changed
195
 
      with command line options.
 
188
      initrd image, but this, like most things, can be changed with
 
189
      command line options.
196
190
    </para>
197
191
    <para>
198
 
      This program can also be used with the
199
 
      <option>--password</option> or <option>--passfile</option>
200
 
      options to generate a ready-made section for
201
 
      <filename>clients.conf</filename> (see
 
192
      It can also be used to generate ready-made sections for
202
193
      <citerefentry><refentrytitle>mandos-clients.conf</refentrytitle>
203
 
      <manvolnum>5</manvolnum></citerefentry>).
 
194
      <manvolnum>5</manvolnum></citerefentry> using the
 
195
      <option>--password</option> option.
204
196
    </para>
205
197
  </refsect1>
206
198
  
207
199
  <refsect1 id="purpose">
208
200
    <title>PURPOSE</title>
 
201
 
209
202
    <para>
210
203
      The purpose of this is to enable <emphasis>remote and unattended
211
204
      rebooting</emphasis> of client host computer with an
212
205
      <emphasis>encrypted root file system</emphasis>.  See <xref
213
206
      linkend="overview"/> for details.
214
207
    </para>
 
208
 
215
209
  </refsect1>
216
210
  
217
211
  <refsect1 id="options">
218
212
    <title>OPTIONS</title>
219
 
    
 
213
 
220
214
    <variablelist>
221
215
      <varlistentry>
222
 
        <term><option>--help</option></term>
223
 
        <term><option>-h</option></term>
 
216
        <term><literal>-h</literal>, <literal>--help</literal></term>
224
217
        <listitem>
225
218
          <para>
226
219
            Show a help message and exit
227
220
          </para>
228
221
        </listitem>
229
222
      </varlistentry>
230
 
      
 
223
 
231
224
      <varlistentry>
232
 
        <term><option>--dir
233
 
        <replaceable>DIRECTORY</replaceable></option></term>
234
 
        <term><option>-d
235
 
        <replaceable>DIRECTORY</replaceable></option></term>
 
225
        <term><literal>-d</literal>, <literal>--dir
 
226
        <replaceable>directory</replaceable></literal></term>
236
227
        <listitem>
237
228
          <para>
238
229
            Target directory for key files.  Default is
239
 
            <filename class="directory">/etc/mandos</filename>.
240
 
          </para>
241
 
        </listitem>
242
 
      </varlistentry>
243
 
      
244
 
      <varlistentry>
245
 
        <term><option>--type
246
 
        <replaceable>TYPE</replaceable></option></term>
247
 
        <term><option>-t
248
 
        <replaceable>TYPE</replaceable></option></term>
249
 
        <listitem>
250
 
          <para>
251
 
            OpenPGP key type.  Default is <quote>RSA</quote>.
252
 
          </para>
253
 
        </listitem>
254
 
      </varlistentry>
255
 
      
256
 
      <varlistentry>
257
 
        <term><option>--length
258
 
        <replaceable>BITS</replaceable></option></term>
259
 
        <term><option>-l
260
 
        <replaceable>BITS</replaceable></option></term>
261
 
        <listitem>
262
 
          <para>
263
 
            OpenPGP key length in bits.  Default is 4096.
264
 
          </para>
265
 
        </listitem>
266
 
      </varlistentry>
267
 
      
268
 
      <varlistentry>
269
 
        <term><option>--subtype
270
 
        <replaceable>KEYTYPE</replaceable></option></term>
271
 
        <term><option>-s
272
 
        <replaceable>KEYTYPE</replaceable></option></term>
273
 
        <listitem>
274
 
          <para>
275
 
            OpenPGP subkey type.  Default is <quote>RSA</quote>
276
 
          </para>
277
 
        </listitem>
278
 
      </varlistentry>
279
 
      
280
 
      <varlistentry>
281
 
        <term><option>--sublength
282
 
        <replaceable>BITS</replaceable></option></term>
283
 
        <term><option>-L
284
 
        <replaceable>BITS</replaceable></option></term>
285
 
        <listitem>
286
 
          <para>
287
 
            OpenPGP subkey length in bits.  Default is 4096.
288
 
          </para>
289
 
        </listitem>
290
 
      </varlistentry>
291
 
      
292
 
      <varlistentry>
293
 
        <term><option>--email
294
 
        <replaceable>ADDRESS</replaceable></option></term>
295
 
        <term><option>-e
296
 
        <replaceable>ADDRESS</replaceable></option></term>
 
230
            <filename>/etc/mandos</filename>.
 
231
          </para>
 
232
        </listitem>
 
233
      </varlistentry>
 
234
 
 
235
      <varlistentry>
 
236
        <term><literal>-t</literal>, <literal>--type
 
237
        <replaceable>type</replaceable></literal></term>
 
238
        <listitem>
 
239
          <para>
 
240
            Key type.  Default is <quote>DSA</quote>.
 
241
          </para>
 
242
        </listitem>
 
243
      </varlistentry>
 
244
 
 
245
      <varlistentry>
 
246
        <term><literal>-l</literal>, <literal>--length
 
247
        <replaceable>bits</replaceable></literal></term>
 
248
        <listitem>
 
249
          <para>
 
250
            Key length in bits.  Default is 2048.
 
251
          </para>
 
252
        </listitem>
 
253
      </varlistentry>
 
254
 
 
255
      <varlistentry>
 
256
        <term><literal>-s</literal>, <literal>--subtype
 
257
        <replaceable>type</replaceable></literal></term>
 
258
        <listitem>
 
259
          <para>
 
260
            Subkey type.  Default is <quote>ELG-E</quote> (Elgamal
 
261
            encryption-only).
 
262
          </para>
 
263
        </listitem>
 
264
      </varlistentry>
 
265
 
 
266
      <varlistentry>
 
267
        <term><literal>-L</literal>, <literal>--sublength
 
268
        <replaceable>bits</replaceable></literal></term>
 
269
        <listitem>
 
270
          <para>
 
271
            Subkey length in bits.  Default is 2048.
 
272
          </para>
 
273
        </listitem>
 
274
      </varlistentry>
 
275
 
 
276
      <varlistentry>
 
277
        <term><literal>-e</literal>, <literal>--email</literal>
 
278
        <replaceable>address</replaceable></term>
297
279
        <listitem>
298
280
          <para>
299
281
            Email address of key.  Default is empty.
300
282
          </para>
301
283
        </listitem>
302
284
      </varlistentry>
303
 
      
 
285
 
304
286
      <varlistentry>
305
 
        <term><option>--comment
306
 
        <replaceable>TEXT</replaceable></option></term>
307
 
        <term><option>-c
308
 
        <replaceable>TEXT</replaceable></option></term>
 
287
        <term><literal>-c</literal>, <literal>--comment</literal>
 
288
        <replaceable>comment</replaceable></term>
309
289
        <listitem>
310
290
          <para>
311
 
            Comment field for key.  Default is empty.
 
291
            Comment field for key.  The default value is
 
292
            <quote><literal>Mandos client key</literal></quote>.
312
293
          </para>
313
294
        </listitem>
314
295
      </varlistentry>
315
 
      
 
296
 
316
297
      <varlistentry>
317
 
        <term><option>--expire
318
 
        <replaceable>TIME</replaceable></option></term>
319
 
        <term><option>-x
320
 
        <replaceable>TIME</replaceable></option></term>
 
298
        <term><literal>-x</literal>, <literal>--expire</literal>
 
299
        <replaceable>time</replaceable></term>
321
300
        <listitem>
322
301
          <para>
323
302
            Key expire time.  Default is no expiration.  See
326
305
          </para>
327
306
        </listitem>
328
307
      </varlistentry>
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
 
      
342
 
      <varlistentry>
343
 
        <term><option>--force</option></term>
344
 
        <term><option>-f</option></term>
345
 
        <listitem>
346
 
          <para>
347
 
            Force overwriting old key.
348
 
          </para>
349
 
        </listitem>
350
 
      </varlistentry>
351
 
      <varlistentry>
352
 
        <term><option>--password</option></term>
353
 
        <term><option>-p</option></term>
 
308
 
 
309
      <varlistentry>
 
310
        <term><literal>-f</literal>, <literal>--force</literal></term>
 
311
        <listitem>
 
312
          <para>
 
313
            Force overwriting old keys.
 
314
          </para>
 
315
        </listitem>
 
316
      </varlistentry>
 
317
      <varlistentry>
 
318
        <term><literal>-p</literal>, <literal>--password</literal
 
319
        ></term>
354
320
        <listitem>
355
321
          <para>
356
322
            Prompt for a password and encrypt it with the key already
362
328
            >8</manvolnum></citerefentry>.  The host name or the name
363
329
            specified with the <option>--name</option> option is used
364
330
            for the section header.  All other options are ignored,
365
 
            and no key is created.
366
 
          </para>
367
 
        </listitem>
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.
 
331
            and no keys are created.
394
332
          </para>
395
333
        </listitem>
396
334
      </varlistentry>
397
335
    </variablelist>
398
336
  </refsect1>
399
 
  
 
337
 
400
338
  <refsect1 id="overview">
401
339
    <title>OVERVIEW</title>
402
340
    <xi:include href="overview.xml"/>
403
341
    <para>
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.
 
342
      This program is a small utility to generate new OpenPGP keys for
 
343
      new Mandos clients.
407
344
    </para>
408
345
  </refsect1>
409
 
  
 
346
 
410
347
  <refsect1 id="exit_status">
411
348
    <title>EXIT STATUS</title>
412
349
    <para>
413
 
      The exit status will be 0 if a new key (or password, if the
414
 
      <option>--password</option> option was used) was successfully
415
 
      created, otherwise not.
 
350
      The exit status will be 0 if new keys were successfully created,
 
351
      otherwise not.
416
352
    </para>
417
353
  </refsect1>
418
354
  
432
368
    </variablelist>
433
369
  </refsect1>
434
370
  
435
 
  <refsect1 id="files">
 
371
  <refsect1 id="file">
436
372
    <title>FILES</title>
437
373
    <para>
438
374
      Use the <option>--dir</option> option to change where
459
395
        </listitem>
460
396
      </varlistentry>
461
397
      <varlistentry>
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>
 
398
        <term><filename>/tmp</filename></term>
479
399
        <listitem>
480
400
          <para>
481
401
            Temporary files will be written here if
485
405
      </varlistentry>
486
406
    </variablelist>
487
407
  </refsect1>
488
 
  
 
408
 
489
409
  <refsect1 id="bugs">
490
410
    <title>BUGS</title>
491
 
    <xi:include href="bugs.xml"/>
 
411
    <para>
 
412
      None are known at this time.
 
413
    </para>
492
414
  </refsect1>
493
 
  
 
415
 
494
416
  <refsect1 id="example">
495
417
    <title>EXAMPLE</title>
496
418
    <informalexample>
503
425
    </informalexample>
504
426
    <informalexample>
505
427
      <para>
506
 
        Create key in another directory and of another type.  Force
 
428
        Create keys in another directory and of another type.  Force
507
429
        overwriting old key files:
508
430
      </para>
509
431
      <para>
513
435
 
514
436
      </para>
515
437
    </informalexample>
516
 
    <informalexample>
517
 
      <para>
518
 
        Prompt for a password, encrypt it with the key in <filename
519
 
        class="directory">/etc/mandos</filename> and output a section
520
 
        suitable for <filename>clients.conf</filename>.
521
 
      </para>
522
 
      <para>
523
 
        <userinput>&COMMANDNAME; --password</userinput>
524
 
      </para>
525
 
    </informalexample>
526
 
    <informalexample>
527
 
      <para>
528
 
        Prompt for a password, encrypt it with the key in the
529
 
        <filename>client-key</filename> directory and output a section
530
 
        suitable for <filename>clients.conf</filename>.
531
 
      </para>
532
 
      <para>
533
 
 
534
 
<!-- do not wrap this line -->
535
 
<userinput>&COMMANDNAME; --password --dir client-key</userinput>
536
 
 
537
 
      </para>
538
 
    </informalexample>
539
438
  </refsect1>
540
 
  
 
439
 
541
440
  <refsect1 id="security">
542
441
    <title>SECURITY</title>
543
442
    <para>
544
443
      The <option>--type</option>, <option>--length</option>,
545
444
      <option>--subtype</option>, and <option>--sublength</option>
546
 
      options can be used to create keys of low security.  If in
547
 
      doubt, leave them to the default values.
 
445
      options can be used to create keys of insufficient security.  If
 
446
      in doubt, leave them to the default values.
548
447
    </para>
549
448
    <para>
550
 
      The key expire time is <emphasis>not</emphasis> guaranteed to be
551
 
      honored by <citerefentry><refentrytitle>mandos</refentrytitle>
 
449
      The key expire time is not guaranteed to be honored by
 
450
      <citerefentry><refentrytitle>mandos</refentrytitle>
552
451
      <manvolnum>8</manvolnum></citerefentry>.
553
452
    </para>
554
453
  </refsect1>
555
 
  
 
454
 
556
455
  <refsect1 id="see_also">
557
456
    <title>SEE ALSO</title>
558
457
    <para>
559
 
      <citerefentry><refentrytitle>intro</refentrytitle>
560
 
      <manvolnum>8mandos</manvolnum></citerefentry>,
561
458
      <citerefentry><refentrytitle>gpg</refentrytitle>
562
459
      <manvolnum>1</manvolnum></citerefentry>,
563
 
      <citerefentry><refentrytitle>mandos-clients.conf</refentrytitle>
564
 
      <manvolnum>5</manvolnum></citerefentry>,
565
460
      <citerefentry><refentrytitle>mandos</refentrytitle>
566
461
      <manvolnum>8</manvolnum></citerefentry>,
567
 
      <citerefentry><refentrytitle>mandos-client</refentrytitle>
568
 
      <manvolnum>8mandos</manvolnum></citerefentry>,
569
 
      <citerefentry><refentrytitle>ssh-keyscan</refentrytitle>
570
 
      <manvolnum>1</manvolnum></citerefentry>
 
462
      <citerefentry><refentrytitle>password-request</refentrytitle>
 
463
      <manvolnum>8mandos</manvolnum></citerefentry>
571
464
    </para>
572
465
  </refsect1>
573
466