/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-08-24 06:17:02 UTC
  • Revision ID: teddy@fukt.bsnet.se-20080824061702-zxrru4r1vxmx4tuq
* Makefile (PREFIX, CONFDIR, MANDIR): Use $(DESTDIR).
  (install-server, install-client): Use "install --directory" instead
                                    of mkdir.

* mandos-keygen: New options --subtype and --sublength.
  (trap): Added semicolons and backslashes.
  (gpg): Added "--enable-dsa2" to all invocations.

* mandos-keygen.xml: Changed single quotes to double quotes for
                     consistency.
  (/refentry/refentryinfo/copyright) Split copyright holders.
  (SYNOPSIS): Added "--subtype", "--sublength", "-s", and "-L".
  (OPTIONS): Document the subtype and sublength options.
  (SECURITY): Also note the "--subtype" and "--sublength" options.

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-31">
7
6
]>
8
7
 
9
8
<refentry xmlns:xi="http://www.w3.org/2001/XInclude">
10
9
  <refentryinfo>
11
 
    <title>Mandos Manual</title>
 
10
    <title>&COMMANDNAME;</title>
12
11
    <!-- NWalsh’s docbook scripts use this to generate the footer: -->
13
 
    <productname>Mandos</productname>
 
12
    <productname>&COMMANDNAME;</productname>
14
13
    <productnumber>&VERSION;</productnumber>
15
 
    <date>&TIMESTAMP;</date>
16
14
    <authorgroup>
17
15
      <author>
18
16
        <firstname>Björn</firstname>
67
65
  <refnamediv>
68
66
    <refname><command>&COMMANDNAME;</command></refname>
69
67
    <refpurpose>
70
 
      Generate key and password for Mandos client and server.
 
68
      Generate keys for <citerefentry><refentrytitle>password-request
 
69
      </refentrytitle><manvolnum>8mandos</manvolnum></citerefentry>
71
70
    </refpurpose>
72
71
  </refnamediv>
73
72
 
74
73
  <refsynopsisdiv>
75
74
    <cmdsynopsis>
76
75
      <command>&COMMANDNAME;</command>
77
 
      <group>
78
 
        <arg choice="plain"><option>--dir
79
 
        <replaceable>DIRECTORY</replaceable></option></arg>
80
 
        <arg choice="plain"><option>-d
81
 
        <replaceable>DIRECTORY</replaceable></option></arg>
82
 
      </group>
83
 
      <sbr/>
84
 
      <group>
85
 
        <arg choice="plain"><option>--type
86
 
        <replaceable>KEYTYPE</replaceable></option></arg>
87
 
        <arg choice="plain"><option>-t
88
 
        <replaceable>KEYTYPE</replaceable></option></arg>
89
 
      </group>
90
 
      <sbr/>
91
 
      <group>
92
 
        <arg choice="plain"><option>--length
93
 
        <replaceable>BITS</replaceable></option></arg>
94
 
        <arg choice="plain"><option>-l
95
 
        <replaceable>BITS</replaceable></option></arg>
96
 
      </group>
97
 
      <sbr/>
98
 
      <group>
99
 
        <arg choice="plain"><option>--subtype
100
 
        <replaceable>KEYTYPE</replaceable></option></arg>
101
 
        <arg choice="plain"><option>-s
102
 
        <replaceable>KEYTYPE</replaceable></option></arg>
103
 
      </group>
104
 
      <sbr/>
105
 
      <group>
106
 
        <arg choice="plain"><option>--sublength
107
 
        <replaceable>BITS</replaceable></option></arg>
108
 
        <arg choice="plain"><option>-L
109
 
        <replaceable>BITS</replaceable></option></arg>
110
 
      </group>
111
 
      <sbr/>
112
 
      <group>
113
 
        <arg choice="plain"><option>--name
114
 
        <replaceable>NAME</replaceable></option></arg>
115
 
        <arg choice="plain"><option>-n
116
 
        <replaceable>NAME</replaceable></option></arg>
117
 
      </group>
118
 
      <sbr/>
119
 
      <group>
120
 
        <arg choice="plain"><option>--email
121
 
        <replaceable>ADDRESS</replaceable></option></arg>
122
 
        <arg choice="plain"><option>-e
123
 
        <replaceable>ADDRESS</replaceable></option></arg>
124
 
      </group>
125
 
      <sbr/>
126
 
      <group>
127
 
        <arg choice="plain"><option>--comment
128
 
        <replaceable>TEXT</replaceable></option></arg>
129
 
        <arg choice="plain"><option>-c
130
 
        <replaceable>TEXT</replaceable></option></arg>
131
 
      </group>
132
 
      <sbr/>
133
 
      <group>
134
 
        <arg choice="plain"><option>--expire
135
 
        <replaceable>TIME</replaceable></option></arg>
136
 
        <arg choice="plain"><option>-x
137
 
        <replaceable>TIME</replaceable></option></arg>
138
 
      </group>
139
 
      <sbr/>
140
 
      <arg><option>--force</option></arg>
141
 
    </cmdsynopsis>
142
 
    <cmdsynopsis>
143
 
      <command>&COMMANDNAME;</command>
144
 
      <group choice="req">
145
 
        <arg choice="plain"><option>--password</option></arg>
146
 
        <arg choice="plain"><option>-p</option></arg>
147
 
      </group>
148
 
      <sbr/>
149
 
      <group>
150
 
        <arg choice="plain"><option>--dir
151
 
        <replaceable>DIRECTORY</replaceable></option></arg>
152
 
        <arg choice="plain"><option>-d
153
 
        <replaceable>DIRECTORY</replaceable></option></arg>
154
 
      </group>
155
 
      <sbr/>
156
 
      <group>
157
 
        <arg choice="plain"><option>--name
158
 
        <replaceable>NAME</replaceable></option></arg>
159
 
        <arg choice="plain"><option>-n
160
 
        <replaceable>NAME</replaceable></option></arg>
161
 
      </group>
162
 
    </cmdsynopsis>
163
 
    <cmdsynopsis>
164
 
      <command>&COMMANDNAME;</command>
165
 
      <group choice="req">
 
76
      <group choice="opt">
 
77
        <arg choice="plain"><option>--dir</option>
 
78
        <replaceable>directory</replaceable></arg>
 
79
      </group>
 
80
      <group choice="opt">
 
81
        <arg choice="plain"><option>--type</option>
 
82
        <replaceable>type</replaceable></arg>
 
83
      </group>
 
84
      <group choice="opt">
 
85
        <arg choice="plain"><option>--length</option>
 
86
        <replaceable>bits</replaceable></arg>
 
87
      </group>
 
88
      <group choice="opt">
 
89
        <arg choice="plain"><option>--subtype</option>
 
90
        <replaceable>type</replaceable></arg>
 
91
      </group>
 
92
      <group choice="opt">
 
93
        <arg choice="plain"><option>--sublength</option>
 
94
        <replaceable>bits</replaceable></arg>
 
95
      </group>
 
96
      <group choice="opt">
 
97
        <arg choice="plain"><option>--name</option>
 
98
        <replaceable>NAME</replaceable></arg>
 
99
      </group>
 
100
      <group choice="opt">
 
101
        <arg choice="plain"><option>--email</option>
 
102
        <replaceable>EMAIL</replaceable></arg>
 
103
      </group>
 
104
      <group choice="opt">
 
105
        <arg choice="plain"><option>--comment</option>
 
106
        <replaceable>COMMENT</replaceable></arg>
 
107
      </group>
 
108
      <group choice="opt">
 
109
        <arg choice="plain"><option>--expire</option>
 
110
        <replaceable>TIME</replaceable></arg>
 
111
      </group>
 
112
      <group choice="opt">
 
113
        <arg choice="plain"><option>--force</option></arg>
 
114
      </group>
 
115
    </cmdsynopsis>
 
116
    <cmdsynopsis>
 
117
      <command>&COMMANDNAME;</command>
 
118
      <group choice="opt">
 
119
        <arg choice="plain"><option>-d</option>
 
120
        <replaceable>directory</replaceable></arg>
 
121
      </group>
 
122
      <group choice="opt">
 
123
        <arg choice="plain"><option>-t</option>
 
124
        <replaceable>type</replaceable></arg>
 
125
      </group>
 
126
      <group choice="opt">
 
127
        <arg choice="plain"><option>-l</option>
 
128
        <replaceable>bits</replaceable></arg>
 
129
      </group>
 
130
      <group choice="opt">
 
131
        <arg choice="plain"><option>-s</option>
 
132
        <replaceable>type</replaceable></arg>
 
133
      </group>
 
134
      <group choice="opt">
 
135
        <arg choice="plain"><option>-L</option>
 
136
        <replaceable>bits</replaceable></arg>
 
137
      </group>
 
138
      <group choice="opt">
 
139
        <arg choice="plain"><option>-n</option>
 
140
        <replaceable>NAME</replaceable></arg>
 
141
      </group>
 
142
      <group choice="opt">
 
143
        <arg choice="plain"><option>-e</option>
 
144
        <replaceable>EMAIL</replaceable></arg>
 
145
      </group>
 
146
      <group choice="opt">
 
147
        <arg choice="plain"><option>-c</option>
 
148
        <replaceable>COMMENT</replaceable></arg>
 
149
      </group>
 
150
      <group choice="opt">
 
151
        <arg choice="plain"><option>-x</option>
 
152
        <replaceable>TIME</replaceable></arg>
 
153
      </group>
 
154
      <group choice="opt">
 
155
        <arg choice="plain"><option>-f</option></arg>
 
156
      </group>
 
157
    </cmdsynopsis>
 
158
    <cmdsynopsis>
 
159
      <command>&COMMANDNAME;</command>
 
160
      <group choice="req">
 
161
        <arg choice="plain"><option>-h</option></arg>
166
162
        <arg choice="plain"><option>--help</option></arg>
167
 
        <arg choice="plain"><option>-h</option></arg>
168
163
      </group>
169
164
    </cmdsynopsis>
170
165
    <cmdsynopsis>
171
166
      <command>&COMMANDNAME;</command>
172
167
      <group choice="req">
 
168
        <arg choice="plain"><option>-v</option></arg>
173
169
        <arg choice="plain"><option>--version</option></arg>
174
 
        <arg choice="plain"><option>-v</option></arg>
175
170
      </group>
176
171
    </cmdsynopsis>
177
172
  </refsynopsisdiv>
178
 
  
 
173
 
179
174
  <refsect1 id="description">
180
175
    <title>DESCRIPTION</title>
181
176
    <para>
182
177
      <command>&COMMANDNAME;</command> is a program to generate the
183
 
      OpenPGP key used by
 
178
      OpenPGP keys used by
184
179
      <citerefentry><refentrytitle>password-request</refentrytitle>
185
 
      <manvolnum>8mandos</manvolnum></citerefentry>.  The key is
 
180
      <manvolnum>8mandos</manvolnum></citerefentry>.  The keys are
186
181
      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.
189
 
    </para>
190
 
    <para>
191
 
      This program can also be used with the
192
 
      <option>--password</option> option to generate a ready-made
193
 
      section for <filename>clients.conf</filename> (see
194
 
      <citerefentry><refentrytitle>mandos-clients.conf</refentrytitle>
195
 
      <manvolnum>5</manvolnum></citerefentry>).
 
182
      initrd image, but this, like most things, can be changed with
 
183
      command line options.
196
184
    </para>
197
185
  </refsect1>
198
186
  
199
187
  <refsect1 id="purpose">
200
188
    <title>PURPOSE</title>
 
189
 
201
190
    <para>
202
191
      The purpose of this is to enable <emphasis>remote and unattended
203
192
      rebooting</emphasis> of client host computer with an
204
193
      <emphasis>encrypted root file system</emphasis>.  See <xref
205
194
      linkend="overview"/> for details.
206
195
    </para>
 
196
 
207
197
  </refsect1>
208
198
  
209
199
  <refsect1 id="options">
210
200
    <title>OPTIONS</title>
211
 
    
 
201
 
212
202
    <variablelist>
213
203
      <varlistentry>
214
 
        <term><option>--help</option></term>
215
 
        <term><option>-h</option></term>
 
204
        <term><literal>-h</literal>, <literal>--help</literal></term>
216
205
        <listitem>
217
206
          <para>
218
207
            Show a help message and exit
221
210
      </varlistentry>
222
211
 
223
212
      <varlistentry>
224
 
        <term><option>--dir
225
 
        <replaceable>DIRECTORY</replaceable></option></term>
226
 
        <term><option>-d
227
 
        <replaceable>DIRECTORY</replaceable></option></term>
 
213
        <term><literal>-d</literal>, <literal>--dir
 
214
        <replaceable>directory</replaceable></literal></term>
228
215
        <listitem>
229
216
          <para>
230
 
            Target directory for key files.  Default is
231
 
            <filename>/etc/mandos</filename>.
 
217
            Target directory for key files.
232
218
          </para>
233
219
        </listitem>
234
220
      </varlistentry>
235
221
 
236
222
      <varlistentry>
237
 
        <term><option>--type
238
 
        <replaceable>TYPE</replaceable></option></term>
239
 
        <term><option>-t
240
 
        <replaceable>TYPE</replaceable></option></term>
 
223
        <term><literal>-t</literal>, <literal>--type
 
224
        <replaceable>type</replaceable></literal></term>
241
225
        <listitem>
242
226
          <para>
243
227
            Key type.  Default is <quote>DSA</quote>.
246
230
      </varlistentry>
247
231
 
248
232
      <varlistentry>
249
 
        <term><option>--length
250
 
        <replaceable>BITS</replaceable></option></term>
251
 
        <term><option>-l
252
 
        <replaceable>BITS</replaceable></option></term>
 
233
        <term><literal>-l</literal>, <literal>--length
 
234
        <replaceable>bits</replaceable></literal></term>
253
235
        <listitem>
254
236
          <para>
255
 
            Key length in bits.  Default is 2048.
 
237
            Key length in bits.  Default is 1024.
256
238
          </para>
257
239
        </listitem>
258
240
      </varlistentry>
259
241
 
260
242
      <varlistentry>
261
 
        <term><option>--subtype
262
 
        <replaceable>KEYTYPE</replaceable></option></term>
263
 
        <term><option>-s
264
 
        <replaceable>KEYTYPE</replaceable></option></term>
 
243
        <term><literal>-s</literal>, <literal>--subtype
 
244
        <replaceable>type</replaceable></literal></term>
265
245
        <listitem>
266
246
          <para>
267
247
            Subkey type.  Default is <quote>ELG-E</quote> (Elgamal
271
251
      </varlistentry>
272
252
 
273
253
      <varlistentry>
274
 
        <term><option>--sublength
275
 
        <replaceable>BITS</replaceable></option></term>
276
 
        <term><option>-L
277
 
        <replaceable>BITS</replaceable></option></term>
 
254
        <term><literal>-L</literal>, <literal>--sublength
 
255
        <replaceable>bits</replaceable></literal></term>
278
256
        <listitem>
279
257
          <para>
280
258
            Subkey length in bits.  Default is 2048.
283
261
      </varlistentry>
284
262
 
285
263
      <varlistentry>
286
 
        <term><option>--email
287
 
        <replaceable>ADDRESS</replaceable></option></term>
288
 
        <term><option>-e
289
 
        <replaceable>ADDRESS</replaceable></option></term>
 
264
        <term><literal>-e</literal>, <literal>--email</literal>
 
265
        <replaceable>address</replaceable></term>
290
266
        <listitem>
291
267
          <para>
292
268
            Email address of key.  Default is empty.
295
271
      </varlistentry>
296
272
 
297
273
      <varlistentry>
298
 
        <term><option>--comment
299
 
        <replaceable>TEXT</replaceable></option></term>
300
 
        <term><option>-c
301
 
        <replaceable>TEXT</replaceable></option></term>
 
274
        <term><literal>-c</literal>, <literal>--comment</literal>
 
275
        <replaceable>comment</replaceable></term>
302
276
        <listitem>
303
277
          <para>
304
278
            Comment field for key.  The default value is
308
282
      </varlistentry>
309
283
 
310
284
      <varlistentry>
311
 
        <term><option>--expire
312
 
        <replaceable>TIME</replaceable></option></term>
313
 
        <term><option>-x
314
 
        <replaceable>TIME</replaceable></option></term>
 
285
        <term><literal>-x</literal>, <literal>--expire</literal>
 
286
        <replaceable>time</replaceable></term>
315
287
        <listitem>
316
288
          <para>
317
289
            Key expire time.  Default is no expiration.  See
322
294
      </varlistentry>
323
295
 
324
296
      <varlistentry>
325
 
        <term><option>--force</option></term>
326
 
        <term><option>-f</option></term>
327
 
        <listitem>
328
 
          <para>
329
 
            Force overwriting old key.
330
 
          </para>
331
 
        </listitem>
332
 
      </varlistentry>
333
 
      <varlistentry>
334
 
        <term><option>--password</option></term>
335
 
        <term><option>-p</option></term>
336
 
        <listitem>
337
 
          <para>
338
 
            Prompt for a password and encrypt it with the key already
339
 
            present in either <filename>/etc/mandos</filename> or the
340
 
            directory specified with the <option>--dir</option>
341
 
            option.  Outputs, on standard output, a section suitable
342
 
            for inclusion in <citerefentry><refentrytitle
343
 
            >mandos-clients.conf</refentrytitle><manvolnum
344
 
            >8</manvolnum></citerefentry>.  The host name or the name
345
 
            specified with the <option>--name</option> option is used
346
 
            for the section header.  All other options are ignored,
347
 
            and no key is created.
 
297
        <term><literal>-f</literal>, <literal>--force</literal></term>
 
298
        <listitem>
 
299
          <para>
 
300
            Force overwriting old keys.
348
301
          </para>
349
302
        </listitem>
350
303
      </varlistentry>
356
309
    <xi:include href="overview.xml"/>
357
310
    <para>
358
311
      This program is a small utility to generate new OpenPGP keys for
359
 
      new Mandos clients, and to generate sections for inclusion in
360
 
      <filename>clients.conf</filename> on the server.
 
312
      new Mandos clients.
361
313
    </para>
362
314
  </refsect1>
363
315
 
364
316
  <refsect1 id="exit_status">
365
317
    <title>EXIT STATUS</title>
366
318
    <para>
367
 
      The exit status will be 0 if a new key (or password, if the
368
 
      <option>--password</option> option was used) was successfully
369
 
      created, otherwise not.
 
319
      The exit status will be 0 if new keys were successfully created,
 
320
      otherwise not.
370
321
    </para>
371
322
  </refsect1>
372
323
  
374
325
    <title>ENVIRONMENT</title>
375
326
    <variablelist>
376
327
      <varlistentry>
377
 
        <term><envar>TMPDIR</envar></term>
 
328
        <term><varname>TMPDIR</varname></term>
378
329
        <listitem>
379
330
          <para>
380
331
            If set, temporary files will be created here. See
438
389
        Normal invocation needs no options:
439
390
      </para>
440
391
      <para>
441
 
        <userinput>&COMMANDNAME;</userinput>
 
392
        <userinput>mandos-keygen</userinput>
442
393
      </para>
443
394
    </informalexample>
444
395
    <informalexample>
445
396
      <para>
446
 
        Create key in another directory and of another type.  Force
 
397
        Create keys in another directory and of another type.  Force
447
398
        overwriting old key files:
448
399
      </para>
449
400
      <para>
450
401
 
451
402
<!-- do not wrap this line -->
452
 
<userinput>&COMMANDNAME; --dir ~/keydir --type RSA --force</userinput>
453
 
 
454
 
      </para>
455
 
    </informalexample>
456
 
    <informalexample>
457
 
      <para>
458
 
        Prompt for a password, encrypt it with the key in
459
 
        <filename>/etc/mandos</filename> and output a section suitable
460
 
        for <filename>clients.conf</filename>.
461
 
      </para>
462
 
      <para>
463
 
        <userinput>&COMMANDNAME; --password</userinput>
464
 
      </para>
465
 
    </informalexample>
466
 
    <informalexample>
467
 
      <para>
468
 
        Prompt for a password, encrypt it with the key in the
469
 
        <filename>client-key</filename> directory and output a section
470
 
        suitable for <filename>clients.conf</filename>.
471
 
      </para>
472
 
      <para>
473
 
 
474
 
<!-- do not wrap this line -->
475
 
<userinput>&COMMANDNAME; --password --dir client-key</userinput>
 
403
<userinput>mandos-keygen --dir ~/keydir --type RSA --force</userinput>
476
404
 
477
405
      </para>
478
406
    </informalexample>
483
411
    <para>
484
412
      The <option>--type</option>, <option>--length</option>,
485
413
      <option>--subtype</option>, and <option>--sublength</option>
486
 
      options can be used to create keys of low security.  If in
487
 
      doubt, leave them to the default values.
 
414
      options can be used to create keys of insufficient security.  If
 
415
      in doubt, leave them to the default values.
488
416
    </para>
489
417
    <para>
490
 
      The key expire time is <emphasis>not</emphasis> guaranteed to be
491
 
      honored by <citerefentry><refentrytitle>mandos</refentrytitle>
 
418
      The key expire time is not guaranteed to be honored by
 
419
      <citerefentry><refentrytitle>mandos</refentrytitle>
492
420
      <manvolnum>8</manvolnum></citerefentry>.
493
421
    </para>
494
422
  </refsect1>
496
424
  <refsect1 id="see_also">
497
425
    <title>SEE ALSO</title>
498
426
    <para>
 
427
      <citerefentry><refentrytitle>password-request</refentrytitle>
 
428
      <manvolnum>8mandos</manvolnum></citerefentry>,
 
429
      <citerefentry><refentrytitle>mandos</refentrytitle>
 
430
      <manvolnum>8</manvolnum></citerefentry>,
499
431
      <citerefentry><refentrytitle>gpg</refentrytitle>
500
 
      <manvolnum>1</manvolnum></citerefentry>,
501
 
      <citerefentry><refentrytitle>mandos-clients.conf</refentrytitle>
502
 
      <manvolnum>5</manvolnum></citerefentry>,
503
 
      <citerefentry><refentrytitle>mandos</refentrytitle>
504
 
      <manvolnum>8</manvolnum></citerefentry>,
505
 
      <citerefentry><refentrytitle>password-request</refentrytitle>
506
 
      <manvolnum>8mandos</manvolnum></citerefentry>
 
432
      <manvolnum>1</manvolnum></citerefentry>
507
433
    </para>
508
434
  </refsect1>
509
435
  
510
436
</refentry>
511
 
<!-- Local Variables: -->
512
 
<!-- time-stamp-start: "<!ENTITY TIMESTAMP [\"']" -->
513
 
<!-- time-stamp-end: "[\"']>" -->
514
 
<!-- time-stamp-format: "%:y-%02m-%02d" -->
515
 
<!-- End: -->