/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: Björn Påhlsson
  • Date: 2008-07-20 02:52:20 UTC
  • Revision ID: belorn@braxen-20080720025220-r5u0388uy9iu23h6
Added following support:
Pluginbased client handler
rewritten Mandos client
       Avahi instead of udp server discovery
       openpgp encrypted key support
Passprompt stand alone application for direct console input
Added logging for Mandos server

Show diffs side-by-side

added added

removed removed

Lines of Context:
mandos-keygen.xml
1
 
<?xml version="1.0" encoding="UTF-8"?>
2
 
<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
3
 
        "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
4
 
<!ENTITY VERSION "1.0">
5
 
<!ENTITY COMMANDNAME "mandos-keygen">
6
 
<!ENTITY TIMESTAMP "2008-09-20">
7
 
]>
8
 
 
9
 
<refentry xmlns:xi="http://www.w3.org/2001/XInclude">
10
 
  <refentryinfo>
11
 
    <title>Mandos Manual</title>
12
 
    <!-- NWalsh’s docbook scripts use this to generate the footer: -->
13
 
    <productname>Mandos</productname>
14
 
    <productnumber>&VERSION;</productnumber>
15
 
    <date>&TIMESTAMP;</date>
16
 
    <authorgroup>
17
 
      <author>
18
 
        <firstname>Björn</firstname>
19
 
        <surname>Påhlsson</surname>
20
 
        <address>
21
 
          <email>belorn@fukt.bsnet.se</email>
22
 
        </address>
23
 
      </author>
24
 
      <author>
25
 
        <firstname>Teddy</firstname>
26
 
        <surname>Hogeborn</surname>
27
 
        <address>
28
 
          <email>teddy@fukt.bsnet.se</email>
29
 
        </address>
30
 
      </author>
31
 
    </authorgroup>
32
 
    <copyright>
33
 
      <year>2008</year>
34
 
      <holder>Teddy Hogeborn</holder>
35
 
      <holder>Björn Påhlsson</holder>
36
 
    </copyright>
37
 
    <xi:include href="legalnotice.xml"/>
38
 
  </refentryinfo>
39
 
  
40
 
  <refmeta>
41
 
    <refentrytitle>&COMMANDNAME;</refentrytitle>
42
 
    <manvolnum>8</manvolnum>
43
 
  </refmeta>
44
 
  
45
 
  <refnamediv>
46
 
    <refname><command>&COMMANDNAME;</command></refname>
47
 
    <refpurpose>
48
 
      Generate key and password for Mandos client and server.
49
 
    </refpurpose>
50
 
  </refnamediv>
51
 
  
52
 
  <refsynopsisdiv>
53
 
    <cmdsynopsis>
54
 
      <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>
119
 
    </cmdsynopsis>
120
 
    <cmdsynopsis>
121
 
      <command>&COMMANDNAME;</command>
122
 
      <group choice="req">
123
 
        <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>
143
 
      </group>
144
 
    </cmdsynopsis>
145
 
    <cmdsynopsis>
146
 
      <command>&COMMANDNAME;</command>
147
 
      <group choice="req">
148
 
        <arg choice="plain"><option>--help</option></arg>
149
 
        <arg choice="plain"><option>-h</option></arg>
150
 
      </group>
151
 
    </cmdsynopsis>
152
 
    <cmdsynopsis>
153
 
      <command>&COMMANDNAME;</command>
154
 
      <group choice="req">
155
 
        <arg choice="plain"><option>--version</option></arg>
156
 
        <arg choice="plain"><option>-v</option></arg>
157
 
      </group>
158
 
    </cmdsynopsis>
159
 
  </refsynopsisdiv>
160
 
  
161
 
  <refsect1 id="description">
162
 
    <title>DESCRIPTION</title>
163
 
    <para>
164
 
      <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
168
 
      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.
171
 
    </para>
172
 
    <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
177
 
      <citerefentry><refentrytitle>mandos-clients.conf</refentrytitle>
178
 
      <manvolnum>5</manvolnum></citerefentry>).
179
 
    </para>
180
 
  </refsect1>
181
 
  
182
 
  <refsect1 id="purpose">
183
 
    <title>PURPOSE</title>
184
 
    <para>
185
 
      The purpose of this is to enable <emphasis>remote and unattended
186
 
      rebooting</emphasis> of client host computer with an
187
 
      <emphasis>encrypted root file system</emphasis>.  See <xref
188
 
      linkend="overview"/> for details.
189
 
    </para>
190
 
  </refsect1>
191
 
  
192
 
  <refsect1 id="options">
193
 
    <title>OPTIONS</title>
194
 
    
195
 
    <variablelist>
196
 
      <varlistentry>
197
 
        <term><option>--help</option></term>
198
 
        <term><option>-h</option></term>
199
 
        <listitem>
200
 
          <para>
201
 
            Show a help message and exit
202
 
          </para>
203
 
        </listitem>
204
 
      </varlistentry>
205
 
      
206
 
      <varlistentry>
207
 
        <term><option>--dir
208
 
        <replaceable>DIRECTORY</replaceable></option></term>
209
 
        <term><option>-d
210
 
        <replaceable>DIRECTORY</replaceable></option></term>
211
 
        <listitem>
212
 
          <para>
213
 
            Target directory for key files.  Default is
214
 
            <filename>/etc/mandos</filename>.
215
 
          </para>
216
 
        </listitem>
217
 
      </varlistentry>
218
 
      
219
 
      <varlistentry>
220
 
        <term><option>--type
221
 
        <replaceable>TYPE</replaceable></option></term>
222
 
        <term><option>-t
223
 
        <replaceable>TYPE</replaceable></option></term>
224
 
        <listitem>
225
 
          <para>
226
 
            Key type.  Default is <quote>DSA</quote>.
227
 
          </para>
228
 
        </listitem>
229
 
      </varlistentry>
230
 
      
231
 
      <varlistentry>
232
 
        <term><option>--length
233
 
        <replaceable>BITS</replaceable></option></term>
234
 
        <term><option>-l
235
 
        <replaceable>BITS</replaceable></option></term>
236
 
        <listitem>
237
 
          <para>
238
 
            Key length in bits.  Default is 2048.
239
 
          </para>
240
 
        </listitem>
241
 
      </varlistentry>
242
 
      
243
 
      <varlistentry>
244
 
        <term><option>--subtype
245
 
        <replaceable>KEYTYPE</replaceable></option></term>
246
 
        <term><option>-s
247
 
        <replaceable>KEYTYPE</replaceable></option></term>
248
 
        <listitem>
249
 
          <para>
250
 
            Subkey type.  Default is <quote>ELG-E</quote> (Elgamal
251
 
            encryption-only).
252
 
          </para>
253
 
        </listitem>
254
 
      </varlistentry>
255
 
      
256
 
      <varlistentry>
257
 
        <term><option>--sublength
258
 
        <replaceable>BITS</replaceable></option></term>
259
 
        <term><option>-L
260
 
        <replaceable>BITS</replaceable></option></term>
261
 
        <listitem>
262
 
          <para>
263
 
            Subkey length in bits.  Default is 2048.
264
 
          </para>
265
 
        </listitem>
266
 
      </varlistentry>
267
 
      
268
 
      <varlistentry>
269
 
        <term><option>--email
270
 
        <replaceable>ADDRESS</replaceable></option></term>
271
 
        <term><option>-e
272
 
        <replaceable>ADDRESS</replaceable></option></term>
273
 
        <listitem>
274
 
          <para>
275
 
            Email address of key.  Default is empty.
276
 
          </para>
277
 
        </listitem>
278
 
      </varlistentry>
279
 
      
280
 
      <varlistentry>
281
 
        <term><option>--comment
282
 
        <replaceable>TEXT</replaceable></option></term>
283
 
        <term><option>-c
284
 
        <replaceable>TEXT</replaceable></option></term>
285
 
        <listitem>
286
 
          <para>
287
 
            Comment field for key.  The default value is
288
 
            <quote><literal>Mandos client key</literal></quote>.
289
 
          </para>
290
 
        </listitem>
291
 
      </varlistentry>
292
 
      
293
 
      <varlistentry>
294
 
        <term><option>--expire
295
 
        <replaceable>TIME</replaceable></option></term>
296
 
        <term><option>-x
297
 
        <replaceable>TIME</replaceable></option></term>
298
 
        <listitem>
299
 
          <para>
300
 
            Key expire time.  Default is no expiration.  See
301
 
            <citerefentry><refentrytitle>gpg</refentrytitle>
302
 
            <manvolnum>1</manvolnum></citerefentry> for syntax.
303
 
          </para>
304
 
        </listitem>
305
 
      </varlistentry>
306
 
      
307
 
      <varlistentry>
308
 
        <term><option>--force</option></term>
309
 
        <term><option>-f</option></term>
310
 
        <listitem>
311
 
          <para>
312
 
            Force overwriting old key.
313
 
          </para>
314
 
        </listitem>
315
 
      </varlistentry>
316
 
      <varlistentry>
317
 
        <term><option>--password</option></term>
318
 
        <term><option>-p</option></term>
319
 
        <listitem>
320
 
          <para>
321
 
            Prompt for a password and encrypt it with the key already
322
 
            present in either <filename>/etc/mandos</filename> or the
323
 
            directory specified with the <option>--dir</option>
324
 
            option.  Outputs, on standard output, a section suitable
325
 
            for inclusion in <citerefentry><refentrytitle
326
 
            >mandos-clients.conf</refentrytitle><manvolnum
327
 
            >8</manvolnum></citerefentry>.  The host name or the name
328
 
            specified with the <option>--name</option> option is used
329
 
            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.
343
 
          </para>
344
 
        </listitem>
345
 
      </varlistentry>
346
 
    </variablelist>
347
 
  </refsect1>
348
 
  
349
 
  <refsect1 id="overview">
350
 
    <title>OVERVIEW</title>
351
 
    <xi:include href="overview.xml"/>
352
 
    <para>
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.
356
 
    </para>
357
 
  </refsect1>
358
 
  
359
 
  <refsect1 id="exit_status">
360
 
    <title>EXIT STATUS</title>
361
 
    <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.
365
 
    </para>
366
 
  </refsect1>
367
 
  
368
 
  <refsect1 id="environment">
369
 
    <title>ENVIRONMENT</title>
370
 
    <variablelist>
371
 
      <varlistentry>
372
 
        <term><envar>TMPDIR</envar></term>
373
 
        <listitem>
374
 
          <para>
375
 
            If set, temporary files will be created here. See
376
 
            <citerefentry><refentrytitle>mktemp</refentrytitle>
377
 
            <manvolnum>1</manvolnum></citerefentry>.
378
 
          </para>
379
 
        </listitem>
380
 
      </varlistentry>
381
 
    </variablelist>
382
 
  </refsect1>
383
 
  
384
 
  <refsect1 id="file">
385
 
    <title>FILES</title>
386
 
    <para>
387
 
      Use the <option>--dir</option> option to change where
388
 
      <command>&COMMANDNAME;</command> will write the key files.  The
389
 
      default file names are shown here.
390
 
    </para>
391
 
    <variablelist>
392
 
      <varlistentry>
393
 
        <term><filename>/etc/mandos/seckey.txt</filename></term>
394
 
        <listitem>
395
 
          <para>
396
 
            OpenPGP secret key file which will be created or
397
 
            overwritten.
398
 
          </para>
399
 
        </listitem>
400
 
      </varlistentry>
401
 
      <varlistentry>
402
 
        <term><filename>/etc/mandos/pubkey.txt</filename></term>
403
 
        <listitem>
404
 
          <para>
405
 
            OpenPGP public key file which will be created or
406
 
            overwritten.
407
 
          </para>
408
 
        </listitem>
409
 
      </varlistentry>
410
 
      <varlistentry>
411
 
        <term><filename>/tmp</filename></term>
412
 
        <listitem>
413
 
          <para>
414
 
            Temporary files will be written here if
415
 
            <varname>TMPDIR</varname> is not set.
416
 
          </para>
417
 
        </listitem>
418
 
      </varlistentry>
419
 
    </variablelist>
420
 
  </refsect1>
421
 
  
422
 
<!--   <refsect1 id="bugs"> -->
423
 
<!--     <title>BUGS</title> -->
424
 
<!--     <para> -->
425
 
<!--     </para> -->
426
 
<!--   </refsect1> -->
427
 
  
428
 
  <refsect1 id="example">
429
 
    <title>EXAMPLE</title>
430
 
    <informalexample>
431
 
      <para>
432
 
        Normal invocation needs no options:
433
 
      </para>
434
 
      <para>
435
 
        <userinput>&COMMANDNAME;</userinput>
436
 
      </para>
437
 
    </informalexample>
438
 
    <informalexample>
439
 
      <para>
440
 
        Create key in another directory and of another type.  Force
441
 
        overwriting old key files:
442
 
      </para>
443
 
      <para>
444
 
 
445
 
<!-- do not wrap this line -->
446
 
<userinput>&COMMANDNAME; --dir ~/keydir --type RSA --force</userinput>
447
 
 
448
 
      </para>
449
 
    </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
 
  </refsect1>
474
 
  
475
 
  <refsect1 id="security">
476
 
    <title>SECURITY</title>
477
 
    <para>
478
 
      The <option>--type</option>, <option>--length</option>,
479
 
      <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.
482
 
    </para>
483
 
    <para>
484
 
      The key expire time is <emphasis>not</emphasis> guaranteed to be
485
 
      honored by <citerefentry><refentrytitle>mandos</refentrytitle>
486
 
      <manvolnum>8</manvolnum></citerefentry>.
487
 
    </para>
488
 
  </refsect1>
489
 
  
490
 
  <refsect1 id="see_also">
491
 
    <title>SEE ALSO</title>
492
 
    <para>
493
 
      <citerefentry><refentrytitle>gpg</refentrytitle>
494
 
      <manvolnum>1</manvolnum></citerefentry>,
495
 
      <citerefentry><refentrytitle>mandos-clients.conf</refentrytitle>
496
 
      <manvolnum>5</manvolnum></citerefentry>,
497
 
      <citerefentry><refentrytitle>mandos</refentrytitle>
498
 
      <manvolnum>8</manvolnum></citerefentry>,
499
 
      <citerefentry><refentrytitle>mandos-client</refentrytitle>
500
 
      <manvolnum>8mandos</manvolnum></citerefentry>
501
 
    </para>
502
 
  </refsect1>
503
 
  
504
 
</refentry>
505
 
<!-- Local Variables: -->
506
 
<!-- time-stamp-start: "<!ENTITY TIMESTAMP [\"']" -->
507
 
<!-- time-stamp-end: "[\"']>" -->
508
 
<!-- time-stamp-format: "%:y-%02m-%02d" -->
509
 
<!-- End: -->