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