/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

merge

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 "2018-02-08">
6
 
<!ENTITY % common SYSTEM "common.ent">
7
 
%common;
 
6
<!ENTITY TIMESTAMP "2008-08-30">
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>--force</option></arg>
131
 
        <arg choice="plain"><option>-f</option></arg>
132
 
      </group>
 
141
      <arg><option>--force</option></arg>
133
142
    </cmdsynopsis>
134
143
    <cmdsynopsis>
135
144
      <command>&COMMANDNAME;</command>
136
145
      <group choice="req">
 
146
        <arg choice="plain"><option>-p</option></arg>
137
147
        <arg choice="plain"><option>--password</option></arg>
138
 
        <arg choice="plain"><option>-p</option></arg>
139
 
        <arg choice="plain"><option>--passfile
140
 
        <replaceable>FILE</replaceable></option></arg>
141
 
        <arg choice="plain"><option>-F</option>
142
 
        <replaceable>FILE</replaceable></arg>
143
148
      </group>
144
149
      <sbr/>
145
150
      <group>
155
160
        <arg choice="plain"><option>-n
156
161
        <replaceable>NAME</replaceable></option></arg>
157
162
      </group>
158
 
      <group>
159
 
        <arg choice="plain"><option>--no-ssh</option></arg>
160
 
        <arg choice="plain"><option>-S</option></arg>
161
 
      </group>
162
163
    </cmdsynopsis>
163
164
    <cmdsynopsis>
164
165
      <command>&COMMANDNAME;</command>
165
166
      <group choice="req">
 
167
        <arg choice="plain"><option>-h</option></arg>
166
168
        <arg choice="plain"><option>--help</option></arg>
167
 
        <arg choice="plain"><option>-h</option></arg>
168
169
      </group>
169
170
    </cmdsynopsis>
170
171
    <cmdsynopsis>
171
172
      <command>&COMMANDNAME;</command>
172
173
      <group choice="req">
 
174
        <arg choice="plain"><option>-v</option></arg>
173
175
        <arg choice="plain"><option>--version</option></arg>
174
 
        <arg choice="plain"><option>-v</option></arg>
175
176
      </group>
176
177
    </cmdsynopsis>
177
178
  </refsynopsisdiv>
178
 
  
 
179
 
179
180
  <refsect1 id="description">
180
181
    <title>DESCRIPTION</title>
181
182
    <para>
182
183
      <command>&COMMANDNAME;</command> is a program to generate the
183
 
      OpenPGP key used by
184
 
      <citerefentry><refentrytitle>mandos-client</refentrytitle>
185
 
      <manvolnum>8mandos</manvolnum></citerefentry>.  The key is
 
184
      OpenPGP keys used by
 
185
      <citerefentry><refentrytitle>password-request</refentrytitle>
 
186
      <manvolnum>8mandos</manvolnum></citerefentry>.  The keys are
186
187
      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.
 
188
      initrd image, but this, like most things, can be changed with
 
189
      command line options.
189
190
    </para>
190
191
    <para>
191
 
      This program can also be used with the
192
 
      <option>--password</option> or <option>--passfile</option>
193
 
      options to generate a ready-made section for
194
 
      <filename>clients.conf</filename> (see
 
192
      It can also be used to generate ready-made sections for
195
193
      <citerefentry><refentrytitle>mandos-clients.conf</refentrytitle>
196
 
      <manvolnum>5</manvolnum></citerefentry>).
 
194
      <manvolnum>5</manvolnum></citerefentry> using the
 
195
      <option>--password</option> option.
197
196
    </para>
198
197
  </refsect1>
199
198
  
200
199
  <refsect1 id="purpose">
201
200
    <title>PURPOSE</title>
 
201
 
202
202
    <para>
203
203
      The purpose of this is to enable <emphasis>remote and unattended
204
204
      rebooting</emphasis> of client host computer with an
205
205
      <emphasis>encrypted root file system</emphasis>.  See <xref
206
206
      linkend="overview"/> for details.
207
207
    </para>
 
208
 
208
209
  </refsect1>
209
210
  
210
211
  <refsect1 id="options">
211
212
    <title>OPTIONS</title>
212
 
    
 
213
 
213
214
    <variablelist>
214
215
      <varlistentry>
215
 
        <term><option>--help</option></term>
216
 
        <term><option>-h</option></term>
 
216
        <term><literal>-h</literal>, <literal>--help</literal></term>
217
217
        <listitem>
218
218
          <para>
219
219
            Show a help message and exit
220
220
          </para>
221
221
        </listitem>
222
222
      </varlistentry>
223
 
      
 
223
 
224
224
      <varlistentry>
225
 
        <term><option>--dir
226
 
        <replaceable>DIRECTORY</replaceable></option></term>
227
 
        <term><option>-d
228
 
        <replaceable>DIRECTORY</replaceable></option></term>
 
225
        <term><literal>-d</literal>, <literal>--dir
 
226
        <replaceable>directory</replaceable></literal></term>
229
227
        <listitem>
230
228
          <para>
231
229
            Target directory for key files.  Default is
232
 
            <filename class="directory">/etc/mandos</filename>.
233
 
          </para>
234
 
        </listitem>
235
 
      </varlistentry>
236
 
      
237
 
      <varlistentry>
238
 
        <term><option>--type
239
 
        <replaceable>TYPE</replaceable></option></term>
240
 
        <term><option>-t
241
 
        <replaceable>TYPE</replaceable></option></term>
242
 
        <listitem>
243
 
          <para>
244
 
            Key type.  Default is <quote>RSA</quote>.
245
 
          </para>
246
 
        </listitem>
247
 
      </varlistentry>
248
 
      
249
 
      <varlistentry>
250
 
        <term><option>--length
251
 
        <replaceable>BITS</replaceable></option></term>
252
 
        <term><option>-l
253
 
        <replaceable>BITS</replaceable></option></term>
254
 
        <listitem>
255
 
          <para>
256
 
            Key length in bits.  Default is 4096.
257
 
          </para>
258
 
        </listitem>
259
 
      </varlistentry>
260
 
      
261
 
      <varlistentry>
262
 
        <term><option>--subtype
263
 
        <replaceable>KEYTYPE</replaceable></option></term>
264
 
        <term><option>-s
265
 
        <replaceable>KEYTYPE</replaceable></option></term>
266
 
        <listitem>
267
 
          <para>
268
 
            Subkey type.  Default is <quote>RSA</quote> (Elgamal
 
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
269
261
            encryption-only).
270
262
          </para>
271
263
        </listitem>
272
264
      </varlistentry>
273
 
      
 
265
 
274
266
      <varlistentry>
275
 
        <term><option>--sublength
276
 
        <replaceable>BITS</replaceable></option></term>
277
 
        <term><option>-L
278
 
        <replaceable>BITS</replaceable></option></term>
 
267
        <term><literal>-L</literal>, <literal>--sublength
 
268
        <replaceable>bits</replaceable></literal></term>
279
269
        <listitem>
280
270
          <para>
281
 
            Subkey length in bits.  Default is 4096.
 
271
            Subkey length in bits.  Default is 2048.
282
272
          </para>
283
273
        </listitem>
284
274
      </varlistentry>
285
 
      
 
275
 
286
276
      <varlistentry>
287
 
        <term><option>--email
288
 
        <replaceable>ADDRESS</replaceable></option></term>
289
 
        <term><option>-e
290
 
        <replaceable>ADDRESS</replaceable></option></term>
 
277
        <term><literal>-e</literal>, <literal>--email</literal>
 
278
        <replaceable>address</replaceable></term>
291
279
        <listitem>
292
280
          <para>
293
281
            Email address of key.  Default is empty.
294
282
          </para>
295
283
        </listitem>
296
284
      </varlistentry>
297
 
      
 
285
 
298
286
      <varlistentry>
299
 
        <term><option>--comment
300
 
        <replaceable>TEXT</replaceable></option></term>
301
 
        <term><option>-c
302
 
        <replaceable>TEXT</replaceable></option></term>
 
287
        <term><literal>-c</literal>, <literal>--comment</literal>
 
288
        <replaceable>comment</replaceable></term>
303
289
        <listitem>
304
290
          <para>
305
 
            Comment field for key.  Default is empty.
 
291
            Comment field for key.  The default value is
 
292
            <quote><literal>Mandos client key</literal></quote>.
306
293
          </para>
307
294
        </listitem>
308
295
      </varlistentry>
309
 
      
 
296
 
310
297
      <varlistentry>
311
 
        <term><option>--expire
312
 
        <replaceable>TIME</replaceable></option></term>
313
 
        <term><option>-x
314
 
        <replaceable>TIME</replaceable></option></term>
 
298
        <term><literal>-x</literal>, <literal>--expire</literal>
 
299
        <replaceable>time</replaceable></term>
315
300
        <listitem>
316
301
          <para>
317
302
            Key expire time.  Default is no expiration.  See
320
305
          </para>
321
306
        </listitem>
322
307
      </varlistentry>
323
 
      
 
308
 
324
309
      <varlistentry>
325
 
        <term><option>--force</option></term>
326
 
        <term><option>-f</option></term>
 
310
        <term><literal>-f</literal>, <literal>--force</literal></term>
327
311
        <listitem>
328
312
          <para>
329
 
            Force overwriting old key.
 
313
            Force overwriting old keys.
330
314
          </para>
331
315
        </listitem>
332
316
      </varlistentry>
333
317
      <varlistentry>
334
 
        <term><option>--password</option></term>
335
 
        <term><option>-p</option></term>
 
318
        <term><literal>-p</literal>, <literal>--password</literal
 
319
        ></term>
336
320
        <listitem>
337
321
          <para>
338
322
            Prompt for a password and encrypt it with the key already
344
328
            >8</manvolnum></citerefentry>.  The host name or the name
345
329
            specified with the <option>--name</option> option is used
346
330
            for the section header.  All other options are ignored,
347
 
            and no key is created.
348
 
          </para>
349
 
        </listitem>
350
 
      </varlistentry>
351
 
      <varlistentry>
352
 
        <term><option>--passfile
353
 
        <replaceable>FILE</replaceable></option></term>
354
 
        <term><option>-F
355
 
        <replaceable>FILE</replaceable></option></term>
356
 
        <listitem>
357
 
          <para>
358
 
            The same as <option>--password</option>, but read from
359
 
            <replaceable>FILE</replaceable>, not the terminal.
360
 
          </para>
361
 
        </listitem>
362
 
      </varlistentry>
363
 
      <varlistentry>
364
 
        <term><option>--no-ssh</option></term>
365
 
        <term><option>-S</option></term>
366
 
        <listitem>
367
 
          <para>
368
 
            When <option>--password</option> or
369
 
            <option>--passfile</option> is given, this option will
370
 
            prevent <command>&COMMANDNAME;</command> from calling
371
 
            <command>ssh-keyscan</command> to get an SSH fingerprint
372
 
            for this host and, if successful, output suitable config
373
 
            options to use this fingerprint as a
374
 
            <option>checker</option> option in the output.  This is
375
 
            otherwise the default behavior.
 
331
            and no keys are created.
376
332
          </para>
377
333
        </listitem>
378
334
      </varlistentry>
379
335
    </variablelist>
380
336
  </refsect1>
381
 
  
 
337
 
382
338
  <refsect1 id="overview">
383
339
    <title>OVERVIEW</title>
384
340
    <xi:include href="overview.xml"/>
385
341
    <para>
386
342
      This program is a small utility to generate new OpenPGP keys for
387
 
      new Mandos clients, and to generate sections for inclusion in
388
 
      <filename>clients.conf</filename> on the server.
 
343
      new Mandos clients.
389
344
    </para>
390
345
  </refsect1>
391
 
  
 
346
 
392
347
  <refsect1 id="exit_status">
393
348
    <title>EXIT STATUS</title>
394
349
    <para>
395
 
      The exit status will be 0 if a new key (or password, if the
396
 
      <option>--password</option> option was used) was successfully
397
 
      created, otherwise not.
 
350
      The exit status will be 0 if new keys were successfully created,
 
351
      otherwise not.
398
352
    </para>
399
353
  </refsect1>
400
354
  
414
368
    </variablelist>
415
369
  </refsect1>
416
370
  
417
 
  <refsect1 id="files">
 
371
  <refsect1 id="file">
418
372
    <title>FILES</title>
419
373
    <para>
420
374
      Use the <option>--dir</option> option to change where
441
395
        </listitem>
442
396
      </varlistentry>
443
397
      <varlistentry>
444
 
        <term><filename class="directory">/tmp</filename></term>
 
398
        <term><filename>/tmp</filename></term>
445
399
        <listitem>
446
400
          <para>
447
401
            Temporary files will be written here if
451
405
      </varlistentry>
452
406
    </variablelist>
453
407
  </refsect1>
454
 
  
 
408
 
455
409
  <refsect1 id="bugs">
456
410
    <title>BUGS</title>
457
 
    <xi:include href="bugs.xml"/>
 
411
    <para>
 
412
      None are known at this time.
 
413
    </para>
458
414
  </refsect1>
459
 
  
 
415
 
460
416
  <refsect1 id="example">
461
417
    <title>EXAMPLE</title>
462
418
    <informalexample>
469
425
    </informalexample>
470
426
    <informalexample>
471
427
      <para>
472
 
        Create key in another directory and of another type.  Force
 
428
        Create keys in another directory and of another type.  Force
473
429
        overwriting old key files:
474
430
      </para>
475
431
      <para>
479
435
 
480
436
      </para>
481
437
    </informalexample>
482
 
    <informalexample>
483
 
      <para>
484
 
        Prompt for a password, encrypt it with the key in <filename
485
 
        class="directory">/etc/mandos</filename> and output a section
486
 
        suitable for <filename>clients.conf</filename>.
487
 
      </para>
488
 
      <para>
489
 
        <userinput>&COMMANDNAME; --password</userinput>
490
 
      </para>
491
 
    </informalexample>
492
 
    <informalexample>
493
 
      <para>
494
 
        Prompt for a password, encrypt it with the key in the
495
 
        <filename>client-key</filename> directory and output a section
496
 
        suitable for <filename>clients.conf</filename>.
497
 
      </para>
498
 
      <para>
499
 
 
500
 
<!-- do not wrap this line -->
501
 
<userinput>&COMMANDNAME; --password --dir client-key</userinput>
502
 
 
503
 
      </para>
504
 
    </informalexample>
505
438
  </refsect1>
506
 
  
 
439
 
507
440
  <refsect1 id="security">
508
441
    <title>SECURITY</title>
509
442
    <para>
510
443
      The <option>--type</option>, <option>--length</option>,
511
444
      <option>--subtype</option>, and <option>--sublength</option>
512
 
      options can be used to create keys of low security.  If in
513
 
      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.
514
447
    </para>
515
448
    <para>
516
 
      The key expire time is <emphasis>not</emphasis> guaranteed to be
517
 
      honored by <citerefentry><refentrytitle>mandos</refentrytitle>
 
449
      The key expire time is not guaranteed to be honored by
 
450
      <citerefentry><refentrytitle>mandos</refentrytitle>
518
451
      <manvolnum>8</manvolnum></citerefentry>.
519
452
    </para>
520
453
  </refsect1>
521
 
  
 
454
 
522
455
  <refsect1 id="see_also">
523
456
    <title>SEE ALSO</title>
524
457
    <para>
525
 
      <citerefentry><refentrytitle>intro</refentrytitle>
526
 
      <manvolnum>8mandos</manvolnum></citerefentry>,
527
458
      <citerefentry><refentrytitle>gpg</refentrytitle>
528
459
      <manvolnum>1</manvolnum></citerefentry>,
529
 
      <citerefentry><refentrytitle>mandos-clients.conf</refentrytitle>
530
 
      <manvolnum>5</manvolnum></citerefentry>,
531
460
      <citerefentry><refentrytitle>mandos</refentrytitle>
532
461
      <manvolnum>8</manvolnum></citerefentry>,
533
 
      <citerefentry><refentrytitle>mandos-client</refentrytitle>
534
 
      <manvolnum>8mandos</manvolnum></citerefentry>,
535
 
      <citerefentry><refentrytitle>ssh-keyscan</refentrytitle>
536
 
      <manvolnum>1</manvolnum></citerefentry>
 
462
      <citerefentry><refentrytitle>password-request</refentrytitle>
 
463
      <manvolnum>8mandos</manvolnum></citerefentry>
537
464
    </para>
538
465
  </refsect1>
539
466