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