/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-25 01:16:38 UTC
  • Revision ID: teddy@fukt.bsnet.se-20080825011638-zgqej2cafhne05ay
* mandos-keygen: Strip 24-bit checksum of Radix-64 from output to make
                 output strictly base64.

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">
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>
34
32
      <holder>Teddy Hogeborn</holder>
35
33
      <holder>Björn Påhlsson</holder>
36
34
    </copyright>
37
 
    <xi:include href="legalnotice.xml"/>
 
35
    <legalnotice>
 
36
      <para>
 
37
        This manual page is free software: you can redistribute it
 
38
        and/or modify it under the terms of the GNU General Public
 
39
        License as published by the Free Software Foundation,
 
40
        either version 3 of the License, or (at your option) any
 
41
        later version.
 
42
      </para>
 
43
 
 
44
      <para>
 
45
        This manual page is distributed in the hope that it will
 
46
        be useful, but WITHOUT ANY WARRANTY; without even the
 
47
        implied warranty of MERCHANTABILITY or FITNESS FOR A
 
48
        PARTICULAR PURPOSE.  See the GNU General Public License
 
49
        for more details.
 
50
      </para>
 
51
 
 
52
      <para>
 
53
        You should have received a copy of the GNU General Public
 
54
        License along with this program; If not, see
 
55
        <ulink url="http://www.gnu.org/licenses/"/>.
 
56
      </para>
 
57
    </legalnotice>
38
58
  </refentryinfo>
39
59
 
40
60
  <refmeta>
45
65
  <refnamediv>
46
66
    <refname><command>&COMMANDNAME;</command></refname>
47
67
    <refpurpose>
48
 
      Generate key and password for Mandos client and server.
 
68
      Generate keys for <citerefentry><refentrytitle>password-request
 
69
      </refentrytitle><manvolnum>8mandos</manvolnum></citerefentry>
49
70
    </refpurpose>
50
71
  </refnamediv>
51
72
 
52
73
  <refsynopsisdiv>
53
74
    <cmdsynopsis>
54
75
      <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>
 
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>
119
157
    </cmdsynopsis>
120
158
    <cmdsynopsis>
121
159
      <command>&COMMANDNAME;</command>
122
160
      <group choice="req">
 
161
        <arg choice="plain"><option>-p</option></arg>
123
162
        <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>
 
163
      </group>
 
164
      <group choice="opt">
 
165
        <arg choice="plain"><option>--dir</option>
 
166
        <replaceable>directory</replaceable></arg>
 
167
      </group>
 
168
      <group choice="opt">
 
169
        <arg choice="plain"><option>--name</option>
 
170
        <replaceable>NAME</replaceable></arg>
139
171
      </group>
140
172
    </cmdsynopsis>
141
173
    <cmdsynopsis>
142
174
      <command>&COMMANDNAME;</command>
143
175
      <group choice="req">
 
176
        <arg choice="plain"><option>-h</option></arg>
144
177
        <arg choice="plain"><option>--help</option></arg>
145
 
        <arg choice="plain"><option>-h</option></arg>
146
178
      </group>
147
179
    </cmdsynopsis>
148
180
    <cmdsynopsis>
149
181
      <command>&COMMANDNAME;</command>
150
182
      <group choice="req">
 
183
        <arg choice="plain"><option>-v</option></arg>
151
184
        <arg choice="plain"><option>--version</option></arg>
152
 
        <arg choice="plain"><option>-v</option></arg>
153
185
      </group>
154
186
    </cmdsynopsis>
155
187
  </refsynopsisdiv>
156
 
  
 
188
 
157
189
  <refsect1 id="description">
158
190
    <title>DESCRIPTION</title>
159
191
    <para>
160
192
      <command>&COMMANDNAME;</command> is a program to generate the
161
 
      OpenPGP key used by
 
193
      OpenPGP keys used by
162
194
      <citerefentry><refentrytitle>password-request</refentrytitle>
163
 
      <manvolnum>8mandos</manvolnum></citerefentry>.  The key is
 
195
      <manvolnum>8mandos</manvolnum></citerefentry>.  The keys are
164
196
      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.
 
197
      initrd image, but this, like most things, can be changed with
 
198
      command line options.
167
199
    </para>
168
200
    <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
 
201
      It can also be used to generate ready-made sections for
172
202
      <citerefentry><refentrytitle>mandos-clients.conf</refentrytitle>
173
 
      <manvolnum>5</manvolnum></citerefentry>).
 
203
      <manvolnum>5</manvolnum></citerefentry> using the
 
204
      <option>--password</option> option.
174
205
    </para>
175
206
  </refsect1>
176
207
  
177
208
  <refsect1 id="purpose">
178
209
    <title>PURPOSE</title>
 
210
 
179
211
    <para>
180
212
      The purpose of this is to enable <emphasis>remote and unattended
181
213
      rebooting</emphasis> of client host computer with an
182
214
      <emphasis>encrypted root file system</emphasis>.  See <xref
183
215
      linkend="overview"/> for details.
184
216
    </para>
 
217
 
185
218
  </refsect1>
186
219
  
187
220
  <refsect1 id="options">
188
221
    <title>OPTIONS</title>
189
 
    
 
222
 
190
223
    <variablelist>
191
224
      <varlistentry>
192
 
        <term><option>--help</option></term>
193
 
        <term><option>-h</option></term>
 
225
        <term><literal>-h</literal>, <literal>--help</literal></term>
194
226
        <listitem>
195
227
          <para>
196
228
            Show a help message and exit
199
231
      </varlistentry>
200
232
 
201
233
      <varlistentry>
202
 
        <term><option>--dir
203
 
        <replaceable>DIRECTORY</replaceable></option></term>
204
 
        <term><option>-d
205
 
        <replaceable>DIRECTORY</replaceable></option></term>
 
234
        <term><literal>-d</literal>, <literal>--dir
 
235
        <replaceable>directory</replaceable></literal></term>
206
236
        <listitem>
207
237
          <para>
208
238
            Target directory for key files.  Default is
212
242
      </varlistentry>
213
243
 
214
244
      <varlistentry>
215
 
        <term><option>--type
216
 
        <replaceable>TYPE</replaceable></option></term>
217
 
        <term><option>-t
218
 
        <replaceable>TYPE</replaceable></option></term>
 
245
        <term><literal>-t</literal>, <literal>--type
 
246
        <replaceable>type</replaceable></literal></term>
219
247
        <listitem>
220
248
          <para>
221
249
            Key type.  Default is <quote>DSA</quote>.
224
252
      </varlistentry>
225
253
 
226
254
      <varlistentry>
227
 
        <term><option>--length
228
 
        <replaceable>BITS</replaceable></option></term>
229
 
        <term><option>-l
230
 
        <replaceable>BITS</replaceable></option></term>
 
255
        <term><literal>-l</literal>, <literal>--length
 
256
        <replaceable>bits</replaceable></literal></term>
231
257
        <listitem>
232
258
          <para>
233
 
            Key length in bits.  Default is 2048.
 
259
            Key length in bits.  Default is 1024.
234
260
          </para>
235
261
        </listitem>
236
262
      </varlistentry>
237
263
 
238
264
      <varlistentry>
239
 
        <term><option>--subtype
240
 
        <replaceable>KEYTYPE</replaceable></option></term>
241
 
        <term><option>-s
242
 
        <replaceable>KEYTYPE</replaceable></option></term>
 
265
        <term><literal>-s</literal>, <literal>--subtype
 
266
        <replaceable>type</replaceable></literal></term>
243
267
        <listitem>
244
268
          <para>
245
269
            Subkey type.  Default is <quote>ELG-E</quote> (Elgamal
249
273
      </varlistentry>
250
274
 
251
275
      <varlistentry>
252
 
        <term><option>--sublength
253
 
        <replaceable>BITS</replaceable></option></term>
254
 
        <term><option>-L
255
 
        <replaceable>BITS</replaceable></option></term>
 
276
        <term><literal>-L</literal>, <literal>--sublength
 
277
        <replaceable>bits</replaceable></literal></term>
256
278
        <listitem>
257
279
          <para>
258
280
            Subkey length in bits.  Default is 2048.
261
283
      </varlistentry>
262
284
 
263
285
      <varlistentry>
264
 
        <term><option>--email
265
 
        <replaceable>ADDRESS</replaceable></option></term>
266
 
        <term><option>-e
267
 
        <replaceable>ADDRESS</replaceable></option></term>
 
286
        <term><literal>-e</literal>, <literal>--email</literal>
 
287
        <replaceable>address</replaceable></term>
268
288
        <listitem>
269
289
          <para>
270
290
            Email address of key.  Default is empty.
273
293
      </varlistentry>
274
294
 
275
295
      <varlistentry>
276
 
        <term><option>--comment
277
 
        <replaceable>TEXT</replaceable></option></term>
278
 
        <term><option>-c
279
 
        <replaceable>TEXT</replaceable></option></term>
 
296
        <term><literal>-c</literal>, <literal>--comment</literal>
 
297
        <replaceable>comment</replaceable></term>
280
298
        <listitem>
281
299
          <para>
282
300
            Comment field for key.  The default value is
286
304
      </varlistentry>
287
305
 
288
306
      <varlistentry>
289
 
        <term><option>--expire
290
 
        <replaceable>TIME</replaceable></option></term>
291
 
        <term><option>-x
292
 
        <replaceable>TIME</replaceable></option></term>
 
307
        <term><literal>-x</literal>, <literal>--expire</literal>
 
308
        <replaceable>time</replaceable></term>
293
309
        <listitem>
294
310
          <para>
295
311
            Key expire time.  Default is no expiration.  See
300
316
      </varlistentry>
301
317
 
302
318
      <varlistentry>
303
 
        <term><option>--force</option></term>
304
 
        <term><option>-f</option></term>
 
319
        <term><literal>-f</literal>, <literal>--force</literal></term>
305
320
        <listitem>
306
321
          <para>
307
 
            Force overwriting old key.
 
322
            Force overwriting old keys.
308
323
          </para>
309
324
        </listitem>
310
325
      </varlistentry>
311
326
      <varlistentry>
312
 
        <term><option>--password</option></term>
313
 
        <term><option>-p</option></term>
 
327
        <term><literal>-p</literal>, <literal>--password</literal
 
328
        ></term>
314
329
        <listitem>
315
330
          <para>
316
331
            Prompt for a password and encrypt it with the key already
322
337
            >8</manvolnum></citerefentry>.  The host name or the name
323
338
            specified with the <option>--name</option> option is used
324
339
            for the section header.  All other options are ignored,
325
 
            and no key is created.
 
340
            and no keys are created.
326
341
          </para>
327
342
        </listitem>
328
343
      </varlistentry>
334
349
    <xi:include href="overview.xml"/>
335
350
    <para>
336
351
      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.
 
352
      new Mandos clients.
339
353
    </para>
340
354
  </refsect1>
341
355
 
342
356
  <refsect1 id="exit_status">
343
357
    <title>EXIT STATUS</title>
344
358
    <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.
 
359
      The exit status will be 0 if new keys were successfully created,
 
360
      otherwise not.
348
361
    </para>
349
362
  </refsect1>
350
363
  
352
365
    <title>ENVIRONMENT</title>
353
366
    <variablelist>
354
367
      <varlistentry>
355
 
        <term><envar>TMPDIR</envar></term>
 
368
        <term><varname>TMPDIR</varname></term>
356
369
        <listitem>
357
370
          <para>
358
371
            If set, temporary files will be created here. See
402
415
    </variablelist>
403
416
  </refsect1>
404
417
 
405
 
<!--   <refsect1 id="bugs"> -->
406
 
<!--     <title>BUGS</title> -->
407
 
<!--     <para> -->
408
 
<!--     </para> -->
409
 
<!--   </refsect1> -->
 
418
  <refsect1 id="bugs">
 
419
    <title>BUGS</title>
 
420
    <para>
 
421
      None are known at this time.
 
422
    </para>
 
423
  </refsect1>
410
424
 
411
425
  <refsect1 id="example">
412
426
    <title>EXAMPLE</title>
415
429
        Normal invocation needs no options:
416
430
      </para>
417
431
      <para>
418
 
        <userinput>&COMMANDNAME;</userinput>
 
432
        <userinput>mandos-keygen</userinput>
419
433
      </para>
420
434
    </informalexample>
421
435
    <informalexample>
422
436
      <para>
423
 
        Create key in another directory and of another type.  Force
 
437
        Create keys in another directory and of another type.  Force
424
438
        overwriting old key files:
425
439
      </para>
426
440
      <para>
427
441
 
428
442
<!-- do not wrap this line -->
429
 
<userinput>&COMMANDNAME; --dir ~/keydir --type RSA --force</userinput>
430
 
 
431
 
      </para>
432
 
    </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>
 
443
<userinput>mandos-keygen --dir ~/keydir --type RSA --force</userinput>
453
444
 
454
445
      </para>
455
446
    </informalexample>
460
451
    <para>
461
452
      The <option>--type</option>, <option>--length</option>,
462
453
      <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.
 
454
      options can be used to create keys of insufficient security.  If
 
455
      in doubt, leave them to the default values.
465
456
    </para>
466
457
    <para>
467
 
      The key expire time is <emphasis>not</emphasis> guaranteed to be
468
 
      honored by <citerefentry><refentrytitle>mandos</refentrytitle>
 
458
      The key expire time is not guaranteed to be honored by
 
459
      <citerefentry><refentrytitle>mandos</refentrytitle>
469
460
      <manvolnum>8</manvolnum></citerefentry>.
470
461
    </para>
471
462
  </refsect1>
473
464
  <refsect1 id="see_also">
474
465
    <title>SEE ALSO</title>
475
466
    <para>
 
467
      <citerefentry><refentrytitle>password-request</refentrytitle>
 
468
      <manvolnum>8mandos</manvolnum></citerefentry>,
 
469
      <citerefentry><refentrytitle>mandos</refentrytitle>
 
470
      <manvolnum>8</manvolnum></citerefentry>,
476
471
      <citerefentry><refentrytitle>gpg</refentrytitle>
477
 
      <manvolnum>1</manvolnum></citerefentry>,
478
 
      <citerefentry><refentrytitle>mandos-clients.conf</refentrytitle>
479
 
      <manvolnum>5</manvolnum></citerefentry>,
480
 
      <citerefentry><refentrytitle>mandos</refentrytitle>
481
 
      <manvolnum>8</manvolnum></citerefentry>,
482
 
      <citerefentry><refentrytitle>password-request</refentrytitle>
483
 
      <manvolnum>8mandos</manvolnum></citerefentry>
 
472
      <manvolnum>1</manvolnum></citerefentry>
484
473
    </para>
485
474
  </refsect1>
486
475
  
487
476
</refentry>
488
 
<!-- Local Variables: -->
489
 
<!-- time-stamp-start: "<!ENTITY TIMESTAMP [\"']" -->
490
 
<!-- time-stamp-end: "[\"']>" -->
491
 
<!-- time-stamp-format: "%:y-%02m-%02d" -->
492
 
<!-- End: -->