/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

  • Committer: Teddy Hogeborn
  • Date: 2008-09-03 17:34:29 UTC
  • Revision ID: teddy@fukt.bsnet.se-20080903173429-db2mjtddf7mgbx8z
* plugins.d/password-request.xml (OVERVIEW): Refer to
                                             password-prompt(8) by
                                             name.
  (SECURITY): Improved wording.  Add paragraph about insecurity of
              ping.
  (SEE ALSO): Add references to cryptsetup(8) and crypttab(5).
              Changed to be a <variablelist> and added text.

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