/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-12">
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
 
      </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>
139
 
      </group>
140
 
    </cmdsynopsis>
141
 
    <cmdsynopsis>
142
 
      <command>&COMMANDNAME;</command>
143
 
      <group choice="req">
144
 
        <arg choice="plain"><option>--help</option></arg>
145
 
        <arg choice="plain"><option>-h</option></arg>
146
 
      </group>
147
 
    </cmdsynopsis>
148
 
    <cmdsynopsis>
149
 
      <command>&COMMANDNAME;</command>
150
 
      <group choice="req">
151
 
        <arg choice="plain"><option>--version</option></arg>
152
 
        <arg choice="plain"><option>-v</option></arg>
153
 
      </group>
154
 
    </cmdsynopsis>
155
 
  </refsynopsisdiv>
156
 
  
157
 
  <refsect1 id="description">
158
 
    <title>DESCRIPTION</title>
159
 
    <para>
160
 
      <command>&COMMANDNAME;</command> is a program to generate the
161
 
      OpenPGP key used by
162
 
      <citerefentry><refentrytitle>mandos-client</refentrytitle>
163
 
      <manvolnum>8mandos</manvolnum></citerefentry>.  The key is
164
 
      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.
167
 
    </para>
168
 
    <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
172
 
      <citerefentry><refentrytitle>mandos-clients.conf</refentrytitle>
173
 
      <manvolnum>5</manvolnum></citerefentry>).
174
 
    </para>
175
 
  </refsect1>
176
 
  
177
 
  <refsect1 id="purpose">
178
 
    <title>PURPOSE</title>
179
 
    <para>
180
 
      The purpose of this is to enable <emphasis>remote and unattended
181
 
      rebooting</emphasis> of client host computer with an
182
 
      <emphasis>encrypted root file system</emphasis>.  See <xref
183
 
      linkend="overview"/> for details.
184
 
    </para>
185
 
  </refsect1>
186
 
  
187
 
  <refsect1 id="options">
188
 
    <title>OPTIONS</title>
189
 
    
190
 
    <variablelist>
191
 
      <varlistentry>
192
 
        <term><option>--help</option></term>
193
 
        <term><option>-h</option></term>
194
 
        <listitem>
195
 
          <para>
196
 
            Show a help message and exit
197
 
          </para>
198
 
        </listitem>
199
 
      </varlistentry>
200
 
      
201
 
      <varlistentry>
202
 
        <term><option>--dir
203
 
        <replaceable>DIRECTORY</replaceable></option></term>
204
 
        <term><option>-d
205
 
        <replaceable>DIRECTORY</replaceable></option></term>
206
 
        <listitem>
207
 
          <para>
208
 
            Target directory for key files.  Default is
209
 
            <filename>/etc/mandos</filename>.
210
 
          </para>
211
 
        </listitem>
212
 
      </varlistentry>
213
 
      
214
 
      <varlistentry>
215
 
        <term><option>--type
216
 
        <replaceable>TYPE</replaceable></option></term>
217
 
        <term><option>-t
218
 
        <replaceable>TYPE</replaceable></option></term>
219
 
        <listitem>
220
 
          <para>
221
 
            Key type.  Default is <quote>DSA</quote>.
222
 
          </para>
223
 
        </listitem>
224
 
      </varlistentry>
225
 
      
226
 
      <varlistentry>
227
 
        <term><option>--length
228
 
        <replaceable>BITS</replaceable></option></term>
229
 
        <term><option>-l
230
 
        <replaceable>BITS</replaceable></option></term>
231
 
        <listitem>
232
 
          <para>
233
 
            Key length in bits.  Default is 2048.
234
 
          </para>
235
 
        </listitem>
236
 
      </varlistentry>
237
 
      
238
 
      <varlistentry>
239
 
        <term><option>--subtype
240
 
        <replaceable>KEYTYPE</replaceable></option></term>
241
 
        <term><option>-s
242
 
        <replaceable>KEYTYPE</replaceable></option></term>
243
 
        <listitem>
244
 
          <para>
245
 
            Subkey type.  Default is <quote>ELG-E</quote> (Elgamal
246
 
            encryption-only).
247
 
          </para>
248
 
        </listitem>
249
 
      </varlistentry>
250
 
      
251
 
      <varlistentry>
252
 
        <term><option>--sublength
253
 
        <replaceable>BITS</replaceable></option></term>
254
 
        <term><option>-L
255
 
        <replaceable>BITS</replaceable></option></term>
256
 
        <listitem>
257
 
          <para>
258
 
            Subkey length in bits.  Default is 2048.
259
 
          </para>
260
 
        </listitem>
261
 
      </varlistentry>
262
 
      
263
 
      <varlistentry>
264
 
        <term><option>--email
265
 
        <replaceable>ADDRESS</replaceable></option></term>
266
 
        <term><option>-e
267
 
        <replaceable>ADDRESS</replaceable></option></term>
268
 
        <listitem>
269
 
          <para>
270
 
            Email address of key.  Default is empty.
271
 
          </para>
272
 
        </listitem>
273
 
      </varlistentry>
274
 
      
275
 
      <varlistentry>
276
 
        <term><option>--comment
277
 
        <replaceable>TEXT</replaceable></option></term>
278
 
        <term><option>-c
279
 
        <replaceable>TEXT</replaceable></option></term>
280
 
        <listitem>
281
 
          <para>
282
 
            Comment field for key.  The default value is
283
 
            <quote><literal>Mandos client key</literal></quote>.
284
 
          </para>
285
 
        </listitem>
286
 
      </varlistentry>
287
 
      
288
 
      <varlistentry>
289
 
        <term><option>--expire
290
 
        <replaceable>TIME</replaceable></option></term>
291
 
        <term><option>-x
292
 
        <replaceable>TIME</replaceable></option></term>
293
 
        <listitem>
294
 
          <para>
295
 
            Key expire time.  Default is no expiration.  See
296
 
            <citerefentry><refentrytitle>gpg</refentrytitle>
297
 
            <manvolnum>1</manvolnum></citerefentry> for syntax.
298
 
          </para>
299
 
        </listitem>
300
 
      </varlistentry>
301
 
      
302
 
      <varlistentry>
303
 
        <term><option>--force</option></term>
304
 
        <term><option>-f</option></term>
305
 
        <listitem>
306
 
          <para>
307
 
            Force overwriting old key.
308
 
          </para>
309
 
        </listitem>
310
 
      </varlistentry>
311
 
      <varlistentry>
312
 
        <term><option>--password</option></term>
313
 
        <term><option>-p</option></term>
314
 
        <listitem>
315
 
          <para>
316
 
            Prompt for a password and encrypt it with the key already
317
 
            present in either <filename>/etc/mandos</filename> or the
318
 
            directory specified with the <option>--dir</option>
319
 
            option.  Outputs, on standard output, a section suitable
320
 
            for inclusion in <citerefentry><refentrytitle
321
 
            >mandos-clients.conf</refentrytitle><manvolnum
322
 
            >8</manvolnum></citerefentry>.  The host name or the name
323
 
            specified with the <option>--name</option> option is used
324
 
            for the section header.  All other options are ignored,
325
 
            and no key is created.
326
 
          </para>
327
 
        </listitem>
328
 
      </varlistentry>
329
 
    </variablelist>
330
 
  </refsect1>
331
 
  
332
 
  <refsect1 id="overview">
333
 
    <title>OVERVIEW</title>
334
 
    <xi:include href="overview.xml"/>
335
 
    <para>
336
 
      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.
339
 
    </para>
340
 
  </refsect1>
341
 
  
342
 
  <refsect1 id="exit_status">
343
 
    <title>EXIT STATUS</title>
344
 
    <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.
348
 
    </para>
349
 
  </refsect1>
350
 
  
351
 
  <refsect1 id="environment">
352
 
    <title>ENVIRONMENT</title>
353
 
    <variablelist>
354
 
      <varlistentry>
355
 
        <term><envar>TMPDIR</envar></term>
356
 
        <listitem>
357
 
          <para>
358
 
            If set, temporary files will be created here. See
359
 
            <citerefentry><refentrytitle>mktemp</refentrytitle>
360
 
            <manvolnum>1</manvolnum></citerefentry>.
361
 
          </para>
362
 
        </listitem>
363
 
      </varlistentry>
364
 
    </variablelist>
365
 
  </refsect1>
366
 
  
367
 
  <refsect1 id="file">
368
 
    <title>FILES</title>
369
 
    <para>
370
 
      Use the <option>--dir</option> option to change where
371
 
      <command>&COMMANDNAME;</command> will write the key files.  The
372
 
      default file names are shown here.
373
 
    </para>
374
 
    <variablelist>
375
 
      <varlistentry>
376
 
        <term><filename>/etc/mandos/seckey.txt</filename></term>
377
 
        <listitem>
378
 
          <para>
379
 
            OpenPGP secret key file which will be created or
380
 
            overwritten.
381
 
          </para>
382
 
        </listitem>
383
 
      </varlistentry>
384
 
      <varlistentry>
385
 
        <term><filename>/etc/mandos/pubkey.txt</filename></term>
386
 
        <listitem>
387
 
          <para>
388
 
            OpenPGP public key file which will be created or
389
 
            overwritten.
390
 
          </para>
391
 
        </listitem>
392
 
      </varlistentry>
393
 
      <varlistentry>
394
 
        <term><filename>/tmp</filename></term>
395
 
        <listitem>
396
 
          <para>
397
 
            Temporary files will be written here if
398
 
            <varname>TMPDIR</varname> is not set.
399
 
          </para>
400
 
        </listitem>
401
 
      </varlistentry>
402
 
    </variablelist>
403
 
  </refsect1>
404
 
  
405
 
<!--   <refsect1 id="bugs"> -->
406
 
<!--     <title>BUGS</title> -->
407
 
<!--     <para> -->
408
 
<!--     </para> -->
409
 
<!--   </refsect1> -->
410
 
  
411
 
  <refsect1 id="example">
412
 
    <title>EXAMPLE</title>
413
 
    <informalexample>
414
 
      <para>
415
 
        Normal invocation needs no options:
416
 
      </para>
417
 
      <para>
418
 
        <userinput>&COMMANDNAME;</userinput>
419
 
      </para>
420
 
    </informalexample>
421
 
    <informalexample>
422
 
      <para>
423
 
        Create key in another directory and of another type.  Force
424
 
        overwriting old key files:
425
 
      </para>
426
 
      <para>
427
 
 
428
 
<!-- 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>
453
 
 
454
 
      </para>
455
 
    </informalexample>
456
 
  </refsect1>
457
 
  
458
 
  <refsect1 id="security">
459
 
    <title>SECURITY</title>
460
 
    <para>
461
 
      The <option>--type</option>, <option>--length</option>,
462
 
      <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.
465
 
    </para>
466
 
    <para>
467
 
      The key expire time is <emphasis>not</emphasis> guaranteed to be
468
 
      honored by <citerefentry><refentrytitle>mandos</refentrytitle>
469
 
      <manvolnum>8</manvolnum></citerefentry>.
470
 
    </para>
471
 
  </refsect1>
472
 
  
473
 
  <refsect1 id="see_also">
474
 
    <title>SEE ALSO</title>
475
 
    <para>
476
 
      <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>mandos-client</refentrytitle>
483
 
      <manvolnum>8mandos</manvolnum></citerefentry>
484
 
    </para>
485
 
  </refsect1>
486
 
  
487
 
</refentry>
488
 
<!-- Local Variables: -->
489
 
<!-- time-stamp-start: "<!ENTITY TIMESTAMP [\"']" -->
490
 
<!-- time-stamp-end: "[\"']>" -->
491
 
<!-- time-stamp-format: "%:y-%02m-%02d" -->
492
 
<!-- End: -->