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