/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
3
3
        "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
4
4
<!ENTITY VERSION "1.0">
5
5
<!ENTITY COMMANDNAME "mandos-keygen">
6
 
<!ENTITY TIMESTAMP "2008-09-20">
 
6
<!ENTITY TIMESTAMP "2008-08-29">
7
7
]>
8
8
 
9
9
<refentry xmlns:xi="http://www.w3.org/2001/XInclude">
34
34
      <holder>Teddy Hogeborn</holder>
35
35
      <holder>Björn Påhlsson</holder>
36
36
    </copyright>
37
 
    <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>
38
60
  </refentryinfo>
39
 
  
 
61
 
40
62
  <refmeta>
41
63
    <refentrytitle>&COMMANDNAME;</refentrytitle>
42
64
    <manvolnum>8</manvolnum>
45
67
  <refnamediv>
46
68
    <refname><command>&COMMANDNAME;</command></refname>
47
69
    <refpurpose>
48
 
      Generate key and password for Mandos client and server.
 
70
      Generate keys for <citerefentry><refentrytitle>password-request
 
71
      </refentrytitle><manvolnum>8mandos</manvolnum></citerefentry>
49
72
    </refpurpose>
50
73
  </refnamediv>
51
 
  
 
74
 
52
75
  <refsynopsisdiv>
53
76
    <cmdsynopsis>
54
77
      <command>&COMMANDNAME;</command>
55
 
      <group>
56
 
        <arg choice="plain"><option>--dir
57
 
        <replaceable>DIRECTORY</replaceable></option></arg>
58
 
        <arg choice="plain"><option>-d
59
 
        <replaceable>DIRECTORY</replaceable></option></arg>
60
 
      </group>
61
 
      <sbr/>
62
 
      <group>
63
 
        <arg choice="plain"><option>--type
64
 
        <replaceable>KEYTYPE</replaceable></option></arg>
65
 
        <arg choice="plain"><option>-t
66
 
        <replaceable>KEYTYPE</replaceable></option></arg>
67
 
      </group>
68
 
      <sbr/>
69
 
      <group>
70
 
        <arg choice="plain"><option>--length
71
 
        <replaceable>BITS</replaceable></option></arg>
72
 
        <arg choice="plain"><option>-l
73
 
        <replaceable>BITS</replaceable></option></arg>
74
 
      </group>
75
 
      <sbr/>
76
 
      <group>
77
 
        <arg choice="plain"><option>--subtype
78
 
        <replaceable>KEYTYPE</replaceable></option></arg>
79
 
        <arg choice="plain"><option>-s
80
 
        <replaceable>KEYTYPE</replaceable></option></arg>
81
 
      </group>
82
 
      <sbr/>
83
 
      <group>
84
 
        <arg choice="plain"><option>--sublength
85
 
        <replaceable>BITS</replaceable></option></arg>
86
 
        <arg choice="plain"><option>-L
87
 
        <replaceable>BITS</replaceable></option></arg>
88
 
      </group>
89
 
      <sbr/>
90
 
      <group>
91
 
        <arg choice="plain"><option>--name
92
 
        <replaceable>NAME</replaceable></option></arg>
93
 
        <arg choice="plain"><option>-n
94
 
        <replaceable>NAME</replaceable></option></arg>
95
 
      </group>
96
 
      <sbr/>
97
 
      <group>
98
 
        <arg choice="plain"><option>--email
99
 
        <replaceable>ADDRESS</replaceable></option></arg>
100
 
        <arg choice="plain"><option>-e
101
 
        <replaceable>ADDRESS</replaceable></option></arg>
102
 
      </group>
103
 
      <sbr/>
104
 
      <group>
105
 
        <arg choice="plain"><option>--comment
106
 
        <replaceable>TEXT</replaceable></option></arg>
107
 
        <arg choice="plain"><option>-c
108
 
        <replaceable>TEXT</replaceable></option></arg>
109
 
      </group>
110
 
      <sbr/>
111
 
      <group>
112
 
        <arg choice="plain"><option>--expire
113
 
        <replaceable>TIME</replaceable></option></arg>
114
 
        <arg choice="plain"><option>-x
115
 
        <replaceable>TIME</replaceable></option></arg>
116
 
      </group>
117
 
      <sbr/>
118
 
      <arg><option>--force</option></arg>
 
78
      <group choice="opt">
 
79
        <arg choice="plain"><option>--dir</option>
 
80
        <replaceable>directory</replaceable></arg>
 
81
      </group>
 
82
      <group choice="opt">
 
83
        <arg choice="plain"><option>--type</option>
 
84
        <replaceable>type</replaceable></arg>
 
85
      </group>
 
86
      <group choice="opt">
 
87
        <arg choice="plain"><option>--length</option>
 
88
        <replaceable>bits</replaceable></arg>
 
89
      </group>
 
90
      <group choice="opt">
 
91
        <arg choice="plain"><option>--subtype</option>
 
92
        <replaceable>type</replaceable></arg>
 
93
      </group>
 
94
      <group choice="opt">
 
95
        <arg choice="plain"><option>--sublength</option>
 
96
        <replaceable>bits</replaceable></arg>
 
97
      </group>
 
98
      <group choice="opt">
 
99
        <arg choice="plain"><option>--name</option>
 
100
        <replaceable>NAME</replaceable></arg>
 
101
      </group>
 
102
      <group choice="opt">
 
103
        <arg choice="plain"><option>--email</option>
 
104
        <replaceable>EMAIL</replaceable></arg>
 
105
      </group>
 
106
      <group choice="opt">
 
107
        <arg choice="plain"><option>--comment</option>
 
108
        <replaceable>COMMENT</replaceable></arg>
 
109
      </group>
 
110
      <group choice="opt">
 
111
        <arg choice="plain"><option>--expire</option>
 
112
        <replaceable>TIME</replaceable></arg>
 
113
      </group>
 
114
      <group choice="opt">
 
115
        <arg choice="plain"><option>--force</option></arg>
 
116
      </group>
 
117
    </cmdsynopsis>
 
118
    <cmdsynopsis>
 
119
      <command>&COMMANDNAME;</command>
 
120
      <group choice="opt">
 
121
        <arg choice="plain"><option>-d</option>
 
122
        <replaceable>directory</replaceable></arg>
 
123
      </group>
 
124
      <group choice="opt">
 
125
        <arg choice="plain"><option>-t</option>
 
126
        <replaceable>type</replaceable></arg>
 
127
      </group>
 
128
      <group choice="opt">
 
129
        <arg choice="plain"><option>-l</option>
 
130
        <replaceable>bits</replaceable></arg>
 
131
      </group>
 
132
      <group choice="opt">
 
133
        <arg choice="plain"><option>-s</option>
 
134
        <replaceable>type</replaceable></arg>
 
135
      </group>
 
136
      <group choice="opt">
 
137
        <arg choice="plain"><option>-L</option>
 
138
        <replaceable>bits</replaceable></arg>
 
139
      </group>
 
140
      <group choice="opt">
 
141
        <arg choice="plain"><option>-n</option>
 
142
        <replaceable>NAME</replaceable></arg>
 
143
      </group>
 
144
      <group choice="opt">
 
145
        <arg choice="plain"><option>-e</option>
 
146
        <replaceable>EMAIL</replaceable></arg>
 
147
      </group>
 
148
      <group choice="opt">
 
149
        <arg choice="plain"><option>-c</option>
 
150
        <replaceable>COMMENT</replaceable></arg>
 
151
      </group>
 
152
      <group choice="opt">
 
153
        <arg choice="plain"><option>-x</option>
 
154
        <replaceable>TIME</replaceable></arg>
 
155
      </group>
 
156
      <group choice="opt">
 
157
        <arg choice="plain"><option>-f</option></arg>
 
158
      </group>
119
159
    </cmdsynopsis>
120
160
    <cmdsynopsis>
121
161
      <command>&COMMANDNAME;</command>
122
162
      <group choice="req">
 
163
        <arg choice="plain"><option>-p</option></arg>
123
164
        <arg choice="plain"><option>--password</option></arg>
124
 
        <arg choice="plain"><option>-p</option></arg>
125
 
        <arg choice="plain"><option>--passfile
126
 
        <replaceable>FILE</replaceable></option></arg>
127
 
        <arg choice="plain"><option>-F</option>
128
 
        <replaceable>FILE</replaceable></arg>
129
 
      </group>
130
 
      <sbr/>
131
 
      <group>
132
 
        <arg choice="plain"><option>--dir
133
 
        <replaceable>DIRECTORY</replaceable></option></arg>
134
 
        <arg choice="plain"><option>-d
135
 
        <replaceable>DIRECTORY</replaceable></option></arg>
136
 
      </group>
137
 
      <sbr/>
138
 
      <group>
139
 
        <arg choice="plain"><option>--name
140
 
        <replaceable>NAME</replaceable></option></arg>
141
 
        <arg choice="plain"><option>-n
142
 
        <replaceable>NAME</replaceable></option></arg>
 
165
      </group>
 
166
      <group choice="opt">
 
167
        <arg choice="plain"><option>--dir</option>
 
168
        <replaceable>directory</replaceable></arg>
 
169
      </group>
 
170
      <group choice="opt">
 
171
        <arg choice="plain"><option>--name</option>
 
172
        <replaceable>NAME</replaceable></arg>
143
173
      </group>
144
174
    </cmdsynopsis>
145
175
    <cmdsynopsis>
146
176
      <command>&COMMANDNAME;</command>
147
177
      <group choice="req">
 
178
        <arg choice="plain"><option>-h</option></arg>
148
179
        <arg choice="plain"><option>--help</option></arg>
149
 
        <arg choice="plain"><option>-h</option></arg>
150
180
      </group>
151
181
    </cmdsynopsis>
152
182
    <cmdsynopsis>
153
183
      <command>&COMMANDNAME;</command>
154
184
      <group choice="req">
 
185
        <arg choice="plain"><option>-v</option></arg>
155
186
        <arg choice="plain"><option>--version</option></arg>
156
 
        <arg choice="plain"><option>-v</option></arg>
157
187
      </group>
158
188
    </cmdsynopsis>
159
189
  </refsynopsisdiv>
160
 
  
 
190
 
161
191
  <refsect1 id="description">
162
192
    <title>DESCRIPTION</title>
163
193
    <para>
164
194
      <command>&COMMANDNAME;</command> is a program to generate the
165
 
      OpenPGP key used by
166
 
      <citerefentry><refentrytitle>mandos-client</refentrytitle>
167
 
      <manvolnum>8mandos</manvolnum></citerefentry>.  The key is
 
195
      OpenPGP keys used by
 
196
      <citerefentry><refentrytitle>password-request</refentrytitle>
 
197
      <manvolnum>8mandos</manvolnum></citerefentry>.  The keys are
168
198
      normally written to /etc/mandos for later installation into the
169
 
      initrd image, but this, and most other things, can be changed
170
 
      with command line options.
 
199
      initrd image, but this, like most things, can be changed with
 
200
      command line options.
171
201
    </para>
172
202
    <para>
173
 
      This program can also be used with the
174
 
      <option>--password</option> or <option>--passfile</option>
175
 
      options to generate a ready-made section for
176
 
      <filename>clients.conf</filename> (see
 
203
      It can also be used to generate ready-made sections for
177
204
      <citerefentry><refentrytitle>mandos-clients.conf</refentrytitle>
178
 
      <manvolnum>5</manvolnum></citerefentry>).
 
205
      <manvolnum>5</manvolnum></citerefentry> using the
 
206
      <option>--password</option> option.
179
207
    </para>
180
208
  </refsect1>
181
209
  
182
210
  <refsect1 id="purpose">
183
211
    <title>PURPOSE</title>
 
212
 
184
213
    <para>
185
214
      The purpose of this is to enable <emphasis>remote and unattended
186
215
      rebooting</emphasis> of client host computer with an
187
216
      <emphasis>encrypted root file system</emphasis>.  See <xref
188
217
      linkend="overview"/> for details.
189
218
    </para>
 
219
 
190
220
  </refsect1>
191
221
  
192
222
  <refsect1 id="options">
193
223
    <title>OPTIONS</title>
194
 
    
 
224
 
195
225
    <variablelist>
196
226
      <varlistentry>
197
 
        <term><option>--help</option></term>
198
 
        <term><option>-h</option></term>
 
227
        <term><literal>-h</literal>, <literal>--help</literal></term>
199
228
        <listitem>
200
229
          <para>
201
230
            Show a help message and exit
202
231
          </para>
203
232
        </listitem>
204
233
      </varlistentry>
205
 
      
 
234
 
206
235
      <varlistentry>
207
 
        <term><option>--dir
208
 
        <replaceable>DIRECTORY</replaceable></option></term>
209
 
        <term><option>-d
210
 
        <replaceable>DIRECTORY</replaceable></option></term>
 
236
        <term><literal>-d</literal>, <literal>--dir
 
237
        <replaceable>directory</replaceable></literal></term>
211
238
        <listitem>
212
239
          <para>
213
240
            Target directory for key files.  Default is
215
242
          </para>
216
243
        </listitem>
217
244
      </varlistentry>
218
 
      
 
245
 
219
246
      <varlistentry>
220
 
        <term><option>--type
221
 
        <replaceable>TYPE</replaceable></option></term>
222
 
        <term><option>-t
223
 
        <replaceable>TYPE</replaceable></option></term>
 
247
        <term><literal>-t</literal>, <literal>--type
 
248
        <replaceable>type</replaceable></literal></term>
224
249
        <listitem>
225
250
          <para>
226
251
            Key type.  Default is <quote>DSA</quote>.
227
252
          </para>
228
253
        </listitem>
229
254
      </varlistentry>
230
 
      
 
255
 
231
256
      <varlistentry>
232
 
        <term><option>--length
233
 
        <replaceable>BITS</replaceable></option></term>
234
 
        <term><option>-l
235
 
        <replaceable>BITS</replaceable></option></term>
 
257
        <term><literal>-l</literal>, <literal>--length
 
258
        <replaceable>bits</replaceable></literal></term>
236
259
        <listitem>
237
260
          <para>
238
261
            Key length in bits.  Default is 2048.
239
262
          </para>
240
263
        </listitem>
241
264
      </varlistentry>
242
 
      
 
265
 
243
266
      <varlistentry>
244
 
        <term><option>--subtype
245
 
        <replaceable>KEYTYPE</replaceable></option></term>
246
 
        <term><option>-s
247
 
        <replaceable>KEYTYPE</replaceable></option></term>
 
267
        <term><literal>-s</literal>, <literal>--subtype
 
268
        <replaceable>type</replaceable></literal></term>
248
269
        <listitem>
249
270
          <para>
250
271
            Subkey type.  Default is <quote>ELG-E</quote> (Elgamal
252
273
          </para>
253
274
        </listitem>
254
275
      </varlistentry>
255
 
      
 
276
 
256
277
      <varlistentry>
257
 
        <term><option>--sublength
258
 
        <replaceable>BITS</replaceable></option></term>
259
 
        <term><option>-L
260
 
        <replaceable>BITS</replaceable></option></term>
 
278
        <term><literal>-L</literal>, <literal>--sublength
 
279
        <replaceable>bits</replaceable></literal></term>
261
280
        <listitem>
262
281
          <para>
263
282
            Subkey length in bits.  Default is 2048.
264
283
          </para>
265
284
        </listitem>
266
285
      </varlistentry>
267
 
      
 
286
 
268
287
      <varlistentry>
269
 
        <term><option>--email
270
 
        <replaceable>ADDRESS</replaceable></option></term>
271
 
        <term><option>-e
272
 
        <replaceable>ADDRESS</replaceable></option></term>
 
288
        <term><literal>-e</literal>, <literal>--email</literal>
 
289
        <replaceable>address</replaceable></term>
273
290
        <listitem>
274
291
          <para>
275
292
            Email address of key.  Default is empty.
276
293
          </para>
277
294
        </listitem>
278
295
      </varlistentry>
279
 
      
 
296
 
280
297
      <varlistentry>
281
 
        <term><option>--comment
282
 
        <replaceable>TEXT</replaceable></option></term>
283
 
        <term><option>-c
284
 
        <replaceable>TEXT</replaceable></option></term>
 
298
        <term><literal>-c</literal>, <literal>--comment</literal>
 
299
        <replaceable>comment</replaceable></term>
285
300
        <listitem>
286
301
          <para>
287
302
            Comment field for key.  The default value is
289
304
          </para>
290
305
        </listitem>
291
306
      </varlistentry>
292
 
      
 
307
 
293
308
      <varlistentry>
294
 
        <term><option>--expire
295
 
        <replaceable>TIME</replaceable></option></term>
296
 
        <term><option>-x
297
 
        <replaceable>TIME</replaceable></option></term>
 
309
        <term><literal>-x</literal>, <literal>--expire</literal>
 
310
        <replaceable>time</replaceable></term>
298
311
        <listitem>
299
312
          <para>
300
313
            Key expire time.  Default is no expiration.  See
303
316
          </para>
304
317
        </listitem>
305
318
      </varlistentry>
306
 
      
 
319
 
307
320
      <varlistentry>
308
 
        <term><option>--force</option></term>
309
 
        <term><option>-f</option></term>
 
321
        <term><literal>-f</literal>, <literal>--force</literal></term>
310
322
        <listitem>
311
323
          <para>
312
 
            Force overwriting old key.
 
324
            Force overwriting old keys.
313
325
          </para>
314
326
        </listitem>
315
327
      </varlistentry>
316
328
      <varlistentry>
317
 
        <term><option>--password</option></term>
318
 
        <term><option>-p</option></term>
 
329
        <term><literal>-p</literal>, <literal>--password</literal
 
330
        ></term>
319
331
        <listitem>
320
332
          <para>
321
333
            Prompt for a password and encrypt it with the key already
327
339
            >8</manvolnum></citerefentry>.  The host name or the name
328
340
            specified with the <option>--name</option> option is used
329
341
            for the section header.  All other options are ignored,
330
 
            and no key is created.
331
 
          </para>
332
 
        </listitem>
333
 
      </varlistentry>
334
 
      <varlistentry>
335
 
        <term><option>--passfile
336
 
        <replaceable>FILE</replaceable></option></term>
337
 
        <term><option>-F
338
 
        <replaceable>FILE</replaceable></option></term>
339
 
        <listitem>
340
 
          <para>
341
 
            The same as <option>--password</option>, but read from
342
 
            <replaceable>FILE</replaceable>, not the terminal.
 
342
            and no keys are created.
343
343
          </para>
344
344
        </listitem>
345
345
      </varlistentry>
346
346
    </variablelist>
347
347
  </refsect1>
348
 
  
 
348
 
349
349
  <refsect1 id="overview">
350
350
    <title>OVERVIEW</title>
351
351
    <xi:include href="overview.xml"/>
352
352
    <para>
353
353
      This program is a small utility to generate new OpenPGP keys for
354
 
      new Mandos clients, and to generate sections for inclusion in
355
 
      <filename>clients.conf</filename> on the server.
 
354
      new Mandos clients.
356
355
    </para>
357
356
  </refsect1>
358
 
  
 
357
 
359
358
  <refsect1 id="exit_status">
360
359
    <title>EXIT STATUS</title>
361
360
    <para>
362
 
      The exit status will be 0 if a new key (or password, if the
363
 
      <option>--password</option> option was used) was successfully
364
 
      created, otherwise not.
 
361
      The exit status will be 0 if new keys were successfully created,
 
362
      otherwise not.
365
363
    </para>
366
364
  </refsect1>
367
365
  
369
367
    <title>ENVIRONMENT</title>
370
368
    <variablelist>
371
369
      <varlistentry>
372
 
        <term><envar>TMPDIR</envar></term>
 
370
        <term><varname>TMPDIR</varname></term>
373
371
        <listitem>
374
372
          <para>
375
373
            If set, temporary files will be created here. See
418
416
      </varlistentry>
419
417
    </variablelist>
420
418
  </refsect1>
421
 
  
422
 
<!--   <refsect1 id="bugs"> -->
423
 
<!--     <title>BUGS</title> -->
424
 
<!--     <para> -->
425
 
<!--     </para> -->
426
 
<!--   </refsect1> -->
427
 
  
 
419
 
 
420
  <refsect1 id="bugs">
 
421
    <title>BUGS</title>
 
422
    <para>
 
423
      None are known at this time.
 
424
    </para>
 
425
  </refsect1>
 
426
 
428
427
  <refsect1 id="example">
429
428
    <title>EXAMPLE</title>
430
429
    <informalexample>
437
436
    </informalexample>
438
437
    <informalexample>
439
438
      <para>
440
 
        Create key in another directory and of another type.  Force
 
439
        Create keys in another directory and of another type.  Force
441
440
        overwriting old key files:
442
441
      </para>
443
442
      <para>
447
446
 
448
447
      </para>
449
448
    </informalexample>
450
 
    <informalexample>
451
 
      <para>
452
 
        Prompt for a password, encrypt it with the key in
453
 
        <filename>/etc/mandos</filename> and output a section suitable
454
 
        for <filename>clients.conf</filename>.
455
 
      </para>
456
 
      <para>
457
 
        <userinput>&COMMANDNAME; --password</userinput>
458
 
      </para>
459
 
    </informalexample>
460
 
    <informalexample>
461
 
      <para>
462
 
        Prompt for a password, encrypt it with the key in the
463
 
        <filename>client-key</filename> directory and output a section
464
 
        suitable for <filename>clients.conf</filename>.
465
 
      </para>
466
 
      <para>
467
 
 
468
 
<!-- do not wrap this line -->
469
 
<userinput>&COMMANDNAME; --password --dir client-key</userinput>
470
 
 
471
 
      </para>
472
 
    </informalexample>
473
449
  </refsect1>
474
 
  
 
450
 
475
451
  <refsect1 id="security">
476
452
    <title>SECURITY</title>
477
453
    <para>
478
454
      The <option>--type</option>, <option>--length</option>,
479
455
      <option>--subtype</option>, and <option>--sublength</option>
480
 
      options can be used to create keys of low security.  If in
481
 
      doubt, leave them to the default values.
 
456
      options can be used to create keys of insufficient security.  If
 
457
      in doubt, leave them to the default values.
482
458
    </para>
483
459
    <para>
484
 
      The key expire time is <emphasis>not</emphasis> guaranteed to be
485
 
      honored by <citerefentry><refentrytitle>mandos</refentrytitle>
 
460
      The key expire time is not guaranteed to be honored by
 
461
      <citerefentry><refentrytitle>mandos</refentrytitle>
486
462
      <manvolnum>8</manvolnum></citerefentry>.
487
463
    </para>
488
464
  </refsect1>
489
 
  
 
465
 
490
466
  <refsect1 id="see_also">
491
467
    <title>SEE ALSO</title>
492
468
    <para>
493
469
      <citerefentry><refentrytitle>gpg</refentrytitle>
494
470
      <manvolnum>1</manvolnum></citerefentry>,
495
 
      <citerefentry><refentrytitle>mandos-clients.conf</refentrytitle>
496
 
      <manvolnum>5</manvolnum></citerefentry>,
497
471
      <citerefentry><refentrytitle>mandos</refentrytitle>
498
472
      <manvolnum>8</manvolnum></citerefentry>,
499
 
      <citerefentry><refentrytitle>mandos-client</refentrytitle>
 
473
      <citerefentry><refentrytitle>password-request</refentrytitle>
500
474
      <manvolnum>8mandos</manvolnum></citerefentry>
501
475
    </para>
502
476
  </refsect1>