/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

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