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