/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
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-03">
 
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>
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
 
      </group>
126
 
      <sbr/>
127
 
      <group>
128
 
        <arg choice="plain"><option>--dir
129
 
        <replaceable>DIRECTORY</replaceable></option></arg>
130
 
        <arg choice="plain"><option>-d
131
 
        <replaceable>DIRECTORY</replaceable></option></arg>
132
 
      </group>
133
 
      <sbr/>
134
 
      <group>
135
 
        <arg choice="plain"><option>--name
136
 
        <replaceable>NAME</replaceable></option></arg>
137
 
        <arg choice="plain"><option>-n
138
 
        <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>
139
173
      </group>
140
174
    </cmdsynopsis>
141
175
    <cmdsynopsis>
142
176
      <command>&COMMANDNAME;</command>
143
177
      <group choice="req">
 
178
        <arg choice="plain"><option>-h</option></arg>
144
179
        <arg choice="plain"><option>--help</option></arg>
145
 
        <arg choice="plain"><option>-h</option></arg>
146
180
      </group>
147
181
    </cmdsynopsis>
148
182
    <cmdsynopsis>
149
183
      <command>&COMMANDNAME;</command>
150
184
      <group choice="req">
 
185
        <arg choice="plain"><option>-v</option></arg>
151
186
        <arg choice="plain"><option>--version</option></arg>
152
 
        <arg choice="plain"><option>-v</option></arg>
153
187
      </group>
154
188
    </cmdsynopsis>
155
189
  </refsynopsisdiv>
156
 
  
 
190
 
157
191
  <refsect1 id="description">
158
192
    <title>DESCRIPTION</title>
159
193
    <para>
160
194
      <command>&COMMANDNAME;</command> is a program to generate the
161
 
      OpenPGP key used by
 
195
      OpenPGP keys used by
162
196
      <citerefentry><refentrytitle>password-request</refentrytitle>
163
 
      <manvolnum>8mandos</manvolnum></citerefentry>.  The key is
 
197
      <manvolnum>8mandos</manvolnum></citerefentry>.  The keys are
164
198
      normally written to /etc/mandos for later installation into the
165
 
      initrd image, but this, and most other things, can be changed
166
 
      with command line options.
 
199
      initrd image, but this, like most things, can be changed with
 
200
      command line options.
167
201
    </para>
168
202
    <para>
169
 
      This program can also be used with the
170
 
      <option>--password</option> option to generate a ready-made
171
 
      section for <filename>clients.conf</filename> (see
 
203
      It can also be used to generate ready-made sections for
172
204
      <citerefentry><refentrytitle>mandos-clients.conf</refentrytitle>
173
 
      <manvolnum>5</manvolnum></citerefentry>).
 
205
      <manvolnum>5</manvolnum></citerefentry> using the
 
206
      <option>--password</option> option.
174
207
    </para>
175
208
  </refsect1>
176
209
  
177
210
  <refsect1 id="purpose">
178
211
    <title>PURPOSE</title>
 
212
 
179
213
    <para>
180
214
      The purpose of this is to enable <emphasis>remote and unattended
181
215
      rebooting</emphasis> of client host computer with an
182
216
      <emphasis>encrypted root file system</emphasis>.  See <xref
183
217
      linkend="overview"/> for details.
184
218
    </para>
 
219
 
185
220
  </refsect1>
186
221
  
187
222
  <refsect1 id="options">
188
223
    <title>OPTIONS</title>
189
 
    
 
224
 
190
225
    <variablelist>
191
226
      <varlistentry>
192
 
        <term><option>--help</option></term>
193
 
        <term><option>-h</option></term>
 
227
        <term><literal>-h</literal>, <literal>--help</literal></term>
194
228
        <listitem>
195
229
          <para>
196
230
            Show a help message and exit
199
233
      </varlistentry>
200
234
 
201
235
      <varlistentry>
202
 
        <term><option>--dir
203
 
        <replaceable>DIRECTORY</replaceable></option></term>
204
 
        <term><option>-d
205
 
        <replaceable>DIRECTORY</replaceable></option></term>
 
236
        <term><literal>-d</literal>, <literal>--dir
 
237
        <replaceable>directory</replaceable></literal></term>
206
238
        <listitem>
207
239
          <para>
208
240
            Target directory for key files.  Default is
212
244
      </varlistentry>
213
245
 
214
246
      <varlistentry>
215
 
        <term><option>--type
216
 
        <replaceable>TYPE</replaceable></option></term>
217
 
        <term><option>-t
218
 
        <replaceable>TYPE</replaceable></option></term>
 
247
        <term><literal>-t</literal>, <literal>--type
 
248
        <replaceable>type</replaceable></literal></term>
219
249
        <listitem>
220
250
          <para>
221
251
            Key type.  Default is <quote>DSA</quote>.
224
254
      </varlistentry>
225
255
 
226
256
      <varlistentry>
227
 
        <term><option>--length
228
 
        <replaceable>BITS</replaceable></option></term>
229
 
        <term><option>-l
230
 
        <replaceable>BITS</replaceable></option></term>
 
257
        <term><literal>-l</literal>, <literal>--length
 
258
        <replaceable>bits</replaceable></literal></term>
231
259
        <listitem>
232
260
          <para>
233
261
            Key length in bits.  Default is 2048.
236
264
      </varlistentry>
237
265
 
238
266
      <varlistentry>
239
 
        <term><option>--subtype
240
 
        <replaceable>KEYTYPE</replaceable></option></term>
241
 
        <term><option>-s
242
 
        <replaceable>KEYTYPE</replaceable></option></term>
 
267
        <term><literal>-s</literal>, <literal>--subtype
 
268
        <replaceable>type</replaceable></literal></term>
243
269
        <listitem>
244
270
          <para>
245
271
            Subkey type.  Default is <quote>ELG-E</quote> (Elgamal
249
275
      </varlistentry>
250
276
 
251
277
      <varlistentry>
252
 
        <term><option>--sublength
253
 
        <replaceable>BITS</replaceable></option></term>
254
 
        <term><option>-L
255
 
        <replaceable>BITS</replaceable></option></term>
 
278
        <term><literal>-L</literal>, <literal>--sublength
 
279
        <replaceable>bits</replaceable></literal></term>
256
280
        <listitem>
257
281
          <para>
258
282
            Subkey length in bits.  Default is 2048.
261
285
      </varlistentry>
262
286
 
263
287
      <varlistentry>
264
 
        <term><option>--email
265
 
        <replaceable>ADDRESS</replaceable></option></term>
266
 
        <term><option>-e
267
 
        <replaceable>ADDRESS</replaceable></option></term>
 
288
        <term><literal>-e</literal>, <literal>--email</literal>
 
289
        <replaceable>address</replaceable></term>
268
290
        <listitem>
269
291
          <para>
270
292
            Email address of key.  Default is empty.
273
295
      </varlistentry>
274
296
 
275
297
      <varlistentry>
276
 
        <term><option>--comment
277
 
        <replaceable>TEXT</replaceable></option></term>
278
 
        <term><option>-c
279
 
        <replaceable>TEXT</replaceable></option></term>
 
298
        <term><literal>-c</literal>, <literal>--comment</literal>
 
299
        <replaceable>comment</replaceable></term>
280
300
        <listitem>
281
301
          <para>
282
302
            Comment field for key.  The default value is
286
306
      </varlistentry>
287
307
 
288
308
      <varlistentry>
289
 
        <term><option>--expire
290
 
        <replaceable>TIME</replaceable></option></term>
291
 
        <term><option>-x
292
 
        <replaceable>TIME</replaceable></option></term>
 
309
        <term><literal>-x</literal>, <literal>--expire</literal>
 
310
        <replaceable>time</replaceable></term>
293
311
        <listitem>
294
312
          <para>
295
313
            Key expire time.  Default is no expiration.  See
300
318
      </varlistentry>
301
319
 
302
320
      <varlistentry>
303
 
        <term><option>--force</option></term>
304
 
        <term><option>-f</option></term>
 
321
        <term><literal>-f</literal>, <literal>--force</literal></term>
305
322
        <listitem>
306
323
          <para>
307
 
            Force overwriting old key.
 
324
            Force overwriting old keys.
308
325
          </para>
309
326
        </listitem>
310
327
      </varlistentry>
311
328
      <varlistentry>
312
 
        <term><option>--password</option></term>
313
 
        <term><option>-p</option></term>
 
329
        <term><literal>-p</literal>, <literal>--password</literal
 
330
        ></term>
314
331
        <listitem>
315
332
          <para>
316
333
            Prompt for a password and encrypt it with the key already
322
339
            >8</manvolnum></citerefentry>.  The host name or the name
323
340
            specified with the <option>--name</option> option is used
324
341
            for the section header.  All other options are ignored,
325
 
            and no key is created.
 
342
            and no keys are created.
326
343
          </para>
327
344
        </listitem>
328
345
      </varlistentry>
334
351
    <xi:include href="overview.xml"/>
335
352
    <para>
336
353
      This program is a small utility to generate new OpenPGP keys for
337
 
      new Mandos clients, and to generate sections for inclusion in
338
 
      <filename>clients.conf</filename> on the server.
 
354
      new Mandos clients.
339
355
    </para>
340
356
  </refsect1>
341
357
 
342
358
  <refsect1 id="exit_status">
343
359
    <title>EXIT STATUS</title>
344
360
    <para>
345
 
      The exit status will be 0 if a new key (or password, if the
346
 
      <option>--password</option> option was used) was successfully
347
 
      created, otherwise not.
 
361
      The exit status will be 0 if new keys were successfully created,
 
362
      otherwise not.
348
363
    </para>
349
364
  </refsect1>
350
365
  
352
367
    <title>ENVIRONMENT</title>
353
368
    <variablelist>
354
369
      <varlistentry>
355
 
        <term><envar>TMPDIR</envar></term>
 
370
        <term><varname>TMPDIR</varname></term>
356
371
        <listitem>
357
372
          <para>
358
373
            If set, temporary files will be created here. See
402
417
    </variablelist>
403
418
  </refsect1>
404
419
 
405
 
<!--   <refsect1 id="bugs"> -->
406
 
<!--     <title>BUGS</title> -->
407
 
<!--     <para> -->
408
 
<!--     </para> -->
409
 
<!--   </refsect1> -->
 
420
  <refsect1 id="bugs">
 
421
    <title>BUGS</title>
 
422
    <para>
 
423
      None are known at this time.
 
424
    </para>
 
425
  </refsect1>
410
426
 
411
427
  <refsect1 id="example">
412
428
    <title>EXAMPLE</title>
420
436
    </informalexample>
421
437
    <informalexample>
422
438
      <para>
423
 
        Create key in another directory and of another type.  Force
 
439
        Create keys in another directory and of another type.  Force
424
440
        overwriting old key files:
425
441
      </para>
426
442
      <para>
430
446
 
431
447
      </para>
432
448
    </informalexample>
433
 
    <informalexample>
434
 
      <para>
435
 
        Prompt for a password, encrypt it with the key in
436
 
        <filename>/etc/mandos</filename> and output a section suitable
437
 
        for <filename>clients.conf</filename>.
438
 
      </para>
439
 
      <para>
440
 
        <userinput>&COMMANDNAME; --password</userinput>
441
 
      </para>
442
 
    </informalexample>
443
 
    <informalexample>
444
 
      <para>
445
 
        Prompt for a password, encrypt it with the key in the
446
 
        <filename>client-key</filename> directory and output a section
447
 
        suitable for <filename>clients.conf</filename>.
448
 
      </para>
449
 
      <para>
450
 
 
451
 
<!-- do not wrap this line -->
452
 
<userinput>&COMMANDNAME; --password --dir client-key</userinput>
453
 
 
454
 
      </para>
455
 
    </informalexample>
456
449
  </refsect1>
457
450
 
458
451
  <refsect1 id="security">
460
453
    <para>
461
454
      The <option>--type</option>, <option>--length</option>,
462
455
      <option>--subtype</option>, and <option>--sublength</option>
463
 
      options can be used to create keys of low security.  If in
464
 
      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.
465
458
    </para>
466
459
    <para>
467
 
      The key expire time is <emphasis>not</emphasis> guaranteed to be
468
 
      honored by <citerefentry><refentrytitle>mandos</refentrytitle>
 
460
      The key expire time is not guaranteed to be honored by
 
461
      <citerefentry><refentrytitle>mandos</refentrytitle>
469
462
      <manvolnum>8</manvolnum></citerefentry>.
470
463
    </para>
471
464
  </refsect1>
475
468
    <para>
476
469
      <citerefentry><refentrytitle>gpg</refentrytitle>
477
470
      <manvolnum>1</manvolnum></citerefentry>,
478
 
      <citerefentry><refentrytitle>mandos-clients.conf</refentrytitle>
479
 
      <manvolnum>5</manvolnum></citerefentry>,
480
471
      <citerefentry><refentrytitle>mandos</refentrytitle>
481
472
      <manvolnum>8</manvolnum></citerefentry>,
482
473
      <citerefentry><refentrytitle>password-request</refentrytitle>