/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: Teddy Hogeborn
  • Date: 2017-08-20 16:20:54 UTC
  • Revision ID: teddy@recompile.se-20170820162054-jwig602syxx2k4l0
Alter copyright notices slightly.  Actual license is unchanged!

This alters all copyright notices to use the Free Software
Foundation's recommendations for license notices; from
<https://www.gnu.org/licenses/gpl-howto.html>:

  For programs that are more than one file, it is better to replace
  “this program” with the name of the program, and begin the statement
  with a line saying “This file is part of NAME”.

* DBUS-API: Use program name "Mandos" explicitly in license notice.
* debian/copyright: - '' -
* initramfs-unpack: - '' -
* legalnotice.xml: - '' -
* mandos: - '' -
* mandos-ctl: - '' -
* mandos-keygen: - '' -
* mandos-monitor: - '' -
* plugin-helpers/mandos-client-iprouteadddel.c: - '' -
* plugin-runner.c: - '' -
* plugins.d/askpass-fifo.c: - '' -
* plugins.d/mandos-client.c: - '' -
* plugins.d/password-prompt.c: - '' -
* plugins.d/plymouth.c: - '' -
* plugins.d/splashy.c: - '' -
* plugins.d/usplash.c: - '' -

Show diffs side-by-side

added added

removed removed

Lines of Context:
mandos-keygen.xml
1
1
<?xml version="1.0" encoding="UTF-8"?>
2
2
<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
3
3
        "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
4
 
<!ENTITY VERSION "1.0">
5
4
<!ENTITY COMMANDNAME "mandos-keygen">
6
 
<!ENTITY TIMESTAMP "2008-08-30">
 
5
<!ENTITY TIMESTAMP "2017-02-23">
 
6
<!ENTITY % common SYSTEM "common.ent">
 
7
%common;
7
8
]>
8
9
 
9
10
<refentry xmlns:xi="http://www.w3.org/2001/XInclude">
11
12
    <title>Mandos Manual</title>
12
13
    <!-- NWalsh’s docbook scripts use this to generate the footer: -->
13
14
    <productname>Mandos</productname>
14
 
    <productnumber>&VERSION;</productnumber>
 
15
    <productnumber>&version;</productnumber>
15
16
    <date>&TIMESTAMP;</date>
16
17
    <authorgroup>
17
18
      <author>
18
19
        <firstname>Björn</firstname>
19
20
        <surname>Påhlsson</surname>
20
21
        <address>
21
 
          <email>belorn@fukt.bsnet.se</email>
 
22
          <email>belorn@recompile.se</email>
22
23
        </address>
23
24
      </author>
24
25
      <author>
25
26
        <firstname>Teddy</firstname>
26
27
        <surname>Hogeborn</surname>
27
28
        <address>
28
 
          <email>teddy@fukt.bsnet.se</email>
 
29
          <email>teddy@recompile.se</email>
29
30
        </address>
30
31
      </author>
31
32
    </authorgroup>
32
33
    <copyright>
33
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>
34
44
      <holder>Teddy Hogeborn</holder>
35
45
      <holder>Björn Påhlsson</holder>
36
46
    </copyright>
37
 
    <legalnotice>
38
 
      <para>
39
 
        This manual page is free software: you can redistribute it
40
 
        and/or modify it under the terms of the GNU General Public
41
 
        License as published by the Free Software Foundation,
42
 
        either version 3 of the License, or (at your option) any
43
 
        later version.
44
 
      </para>
45
 
 
46
 
      <para>
47
 
        This manual page is distributed in the hope that it will
48
 
        be useful, but WITHOUT ANY WARRANTY; without even the
49
 
        implied warranty of MERCHANTABILITY or FITNESS FOR A
50
 
        PARTICULAR PURPOSE.  See the GNU General Public License
51
 
        for more details.
52
 
      </para>
53
 
 
54
 
      <para>
55
 
        You should have received a copy of the GNU General Public
56
 
        License along with this program; If not, see
57
 
        <ulink url="http://www.gnu.org/licenses/"/>.
58
 
      </para>
59
 
    </legalnotice>
 
47
    <xi:include href="legalnotice.xml"/>
60
48
  </refentryinfo>
61
 
 
 
49
  
62
50
  <refmeta>
63
51
    <refentrytitle>&COMMANDNAME;</refentrytitle>
64
52
    <manvolnum>8</manvolnum>
67
55
  <refnamediv>
68
56
    <refname><command>&COMMANDNAME;</command></refname>
69
57
    <refpurpose>
70
 
      Generate keys for <citerefentry><refentrytitle>password-request
71
 
      </refentrytitle><manvolnum>8mandos</manvolnum></citerefentry>
 
58
      Generate key and password for Mandos client and server.
72
59
    </refpurpose>
73
60
  </refnamediv>
74
 
 
 
61
  
75
62
  <refsynopsisdiv>
76
63
    <cmdsynopsis>
77
64
      <command>&COMMANDNAME;</command>
138
125
        <replaceable>TIME</replaceable></option></arg>
139
126
      </group>
140
127
      <sbr/>
141
 
      <arg><option>--force</option></arg>
 
128
      <group>
 
129
        <arg choice="plain"><option>--force</option></arg>
 
130
        <arg choice="plain"><option>-f</option></arg>
 
131
      </group>
142
132
    </cmdsynopsis>
143
133
    <cmdsynopsis>
144
134
      <command>&COMMANDNAME;</command>
145
135
      <group choice="req">
 
136
        <arg choice="plain"><option>--password</option></arg>
146
137
        <arg choice="plain"><option>-p</option></arg>
147
 
        <arg choice="plain"><option>--password</option></arg>
 
138
        <arg choice="plain"><option>--passfile
 
139
        <replaceable>FILE</replaceable></option></arg>
 
140
        <arg choice="plain"><option>-F</option>
 
141
        <replaceable>FILE</replaceable></arg>
148
142
      </group>
149
143
      <sbr/>
150
144
      <group>
160
154
        <arg choice="plain"><option>-n
161
155
        <replaceable>NAME</replaceable></option></arg>
162
156
      </group>
 
157
      <group>
 
158
        <arg choice="plain"><option>--no-ssh</option></arg>
 
159
        <arg choice="plain"><option>-S</option></arg>
 
160
      </group>
163
161
    </cmdsynopsis>
164
162
    <cmdsynopsis>
165
163
      <command>&COMMANDNAME;</command>
166
164
      <group choice="req">
 
165
        <arg choice="plain"><option>--help</option></arg>
167
166
        <arg choice="plain"><option>-h</option></arg>
168
 
        <arg choice="plain"><option>--help</option></arg>
169
167
      </group>
170
168
    </cmdsynopsis>
171
169
    <cmdsynopsis>
172
170
      <command>&COMMANDNAME;</command>
173
171
      <group choice="req">
 
172
        <arg choice="plain"><option>--version</option></arg>
174
173
        <arg choice="plain"><option>-v</option></arg>
175
 
        <arg choice="plain"><option>--version</option></arg>
176
174
      </group>
177
175
    </cmdsynopsis>
178
176
  </refsynopsisdiv>
179
 
 
 
177
  
180
178
  <refsect1 id="description">
181
179
    <title>DESCRIPTION</title>
182
180
    <para>
183
181
      <command>&COMMANDNAME;</command> is a program to generate the
184
 
      OpenPGP keys used by
185
 
      <citerefentry><refentrytitle>password-request</refentrytitle>
186
 
      <manvolnum>8mandos</manvolnum></citerefentry>.  The keys are
 
182
      OpenPGP key used by
 
183
      <citerefentry><refentrytitle>mandos-client</refentrytitle>
 
184
      <manvolnum>8mandos</manvolnum></citerefentry>.  The key is
187
185
      normally written to /etc/mandos for later installation into the
188
 
      initrd image, but this, like most things, can be changed with
189
 
      command line options.
 
186
      initrd image, but this, and most other things, can be changed
 
187
      with command line options.
190
188
    </para>
191
189
    <para>
192
 
      It can also be used to generate ready-made sections for
 
190
      This program can also be used with the
 
191
      <option>--password</option> or <option>--passfile</option>
 
192
      options to generate a ready-made section for
 
193
      <filename>clients.conf</filename> (see
193
194
      <citerefentry><refentrytitle>mandos-clients.conf</refentrytitle>
194
 
      <manvolnum>5</manvolnum></citerefentry> using the
195
 
      <option>--password</option> option.
 
195
      <manvolnum>5</manvolnum></citerefentry>).
196
196
    </para>
197
197
  </refsect1>
198
198
  
199
199
  <refsect1 id="purpose">
200
200
    <title>PURPOSE</title>
201
 
 
202
201
    <para>
203
202
      The purpose of this is to enable <emphasis>remote and unattended
204
203
      rebooting</emphasis> of client host computer with an
205
204
      <emphasis>encrypted root file system</emphasis>.  See <xref
206
205
      linkend="overview"/> for details.
207
206
    </para>
208
 
 
209
207
  </refsect1>
210
208
  
211
209
  <refsect1 id="options">
212
210
    <title>OPTIONS</title>
213
 
 
 
211
    
214
212
    <variablelist>
215
213
      <varlistentry>
216
 
        <term><literal>-h</literal>, <literal>--help</literal></term>
 
214
        <term><option>--help</option></term>
 
215
        <term><option>-h</option></term>
217
216
        <listitem>
218
217
          <para>
219
218
            Show a help message and exit
220
219
          </para>
221
220
        </listitem>
222
221
      </varlistentry>
223
 
 
 
222
      
224
223
      <varlistentry>
225
 
        <term><literal>-d</literal>, <literal>--dir
226
 
        <replaceable>directory</replaceable></literal></term>
 
224
        <term><option>--dir
 
225
        <replaceable>DIRECTORY</replaceable></option></term>
 
226
        <term><option>-d
 
227
        <replaceable>DIRECTORY</replaceable></option></term>
227
228
        <listitem>
228
229
          <para>
229
230
            Target directory for key files.  Default is
230
 
            <filename>/etc/mandos</filename>.
231
 
          </para>
232
 
        </listitem>
233
 
      </varlistentry>
234
 
 
235
 
      <varlistentry>
236
 
        <term><literal>-t</literal>, <literal>--type
237
 
        <replaceable>type</replaceable></literal></term>
238
 
        <listitem>
239
 
          <para>
240
 
            Key type.  Default is <quote>DSA</quote>.
241
 
          </para>
242
 
        </listitem>
243
 
      </varlistentry>
244
 
 
245
 
      <varlistentry>
246
 
        <term><literal>-l</literal>, <literal>--length
247
 
        <replaceable>bits</replaceable></literal></term>
248
 
        <listitem>
249
 
          <para>
250
 
            Key length in bits.  Default is 2048.
251
 
          </para>
252
 
        </listitem>
253
 
      </varlistentry>
254
 
 
255
 
      <varlistentry>
256
 
        <term><literal>-s</literal>, <literal>--subtype
257
 
        <replaceable>type</replaceable></literal></term>
258
 
        <listitem>
259
 
          <para>
260
 
            Subkey type.  Default is <quote>ELG-E</quote> (Elgamal
 
231
            <filename class="directory">/etc/mandos</filename>.
 
232
          </para>
 
233
        </listitem>
 
234
      </varlistentry>
 
235
      
 
236
      <varlistentry>
 
237
        <term><option>--type
 
238
        <replaceable>TYPE</replaceable></option></term>
 
239
        <term><option>-t
 
240
        <replaceable>TYPE</replaceable></option></term>
 
241
        <listitem>
 
242
          <para>
 
243
            Key type.  Default is <quote>RSA</quote>.
 
244
          </para>
 
245
        </listitem>
 
246
      </varlistentry>
 
247
      
 
248
      <varlistentry>
 
249
        <term><option>--length
 
250
        <replaceable>BITS</replaceable></option></term>
 
251
        <term><option>-l
 
252
        <replaceable>BITS</replaceable></option></term>
 
253
        <listitem>
 
254
          <para>
 
255
            Key length in bits.  Default is 4096.
 
256
          </para>
 
257
        </listitem>
 
258
      </varlistentry>
 
259
      
 
260
      <varlistentry>
 
261
        <term><option>--subtype
 
262
        <replaceable>KEYTYPE</replaceable></option></term>
 
263
        <term><option>-s
 
264
        <replaceable>KEYTYPE</replaceable></option></term>
 
265
        <listitem>
 
266
          <para>
 
267
            Subkey type.  Default is <quote>RSA</quote> (Elgamal
261
268
            encryption-only).
262
269
          </para>
263
270
        </listitem>
264
271
      </varlistentry>
265
 
 
 
272
      
266
273
      <varlistentry>
267
 
        <term><literal>-L</literal>, <literal>--sublength
268
 
        <replaceable>bits</replaceable></literal></term>
 
274
        <term><option>--sublength
 
275
        <replaceable>BITS</replaceable></option></term>
 
276
        <term><option>-L
 
277
        <replaceable>BITS</replaceable></option></term>
269
278
        <listitem>
270
279
          <para>
271
 
            Subkey length in bits.  Default is 2048.
 
280
            Subkey length in bits.  Default is 4096.
272
281
          </para>
273
282
        </listitem>
274
283
      </varlistentry>
275
 
 
 
284
      
276
285
      <varlistentry>
277
 
        <term><literal>-e</literal>, <literal>--email</literal>
278
 
        <replaceable>address</replaceable></term>
 
286
        <term><option>--email
 
287
        <replaceable>ADDRESS</replaceable></option></term>
 
288
        <term><option>-e
 
289
        <replaceable>ADDRESS</replaceable></option></term>
279
290
        <listitem>
280
291
          <para>
281
292
            Email address of key.  Default is empty.
282
293
          </para>
283
294
        </listitem>
284
295
      </varlistentry>
285
 
 
 
296
      
286
297
      <varlistentry>
287
 
        <term><literal>-c</literal>, <literal>--comment</literal>
288
 
        <replaceable>comment</replaceable></term>
 
298
        <term><option>--comment
 
299
        <replaceable>TEXT</replaceable></option></term>
 
300
        <term><option>-c
 
301
        <replaceable>TEXT</replaceable></option></term>
289
302
        <listitem>
290
303
          <para>
291
 
            Comment field for key.  The default value is
292
 
            <quote><literal>Mandos client key</literal></quote>.
 
304
            Comment field for key.  Default is empty.
293
305
          </para>
294
306
        </listitem>
295
307
      </varlistentry>
296
 
 
 
308
      
297
309
      <varlistentry>
298
 
        <term><literal>-x</literal>, <literal>--expire</literal>
299
 
        <replaceable>time</replaceable></term>
 
310
        <term><option>--expire
 
311
        <replaceable>TIME</replaceable></option></term>
 
312
        <term><option>-x
 
313
        <replaceable>TIME</replaceable></option></term>
300
314
        <listitem>
301
315
          <para>
302
316
            Key expire time.  Default is no expiration.  See
305
319
          </para>
306
320
        </listitem>
307
321
      </varlistentry>
308
 
 
 
322
      
309
323
      <varlistentry>
310
 
        <term><literal>-f</literal>, <literal>--force</literal></term>
 
324
        <term><option>--force</option></term>
 
325
        <term><option>-f</option></term>
311
326
        <listitem>
312
327
          <para>
313
 
            Force overwriting old keys.
 
328
            Force overwriting old key.
314
329
          </para>
315
330
        </listitem>
316
331
      </varlistentry>
317
332
      <varlistentry>
318
 
        <term><literal>-p</literal>, <literal>--password</literal
319
 
        ></term>
 
333
        <term><option>--password</option></term>
 
334
        <term><option>-p</option></term>
320
335
        <listitem>
321
336
          <para>
322
337
            Prompt for a password and encrypt it with the key already
328
343
            >8</manvolnum></citerefentry>.  The host name or the name
329
344
            specified with the <option>--name</option> option is used
330
345
            for the section header.  All other options are ignored,
331
 
            and no keys are created.
 
346
            and no key is created.
 
347
          </para>
 
348
        </listitem>
 
349
      </varlistentry>
 
350
      <varlistentry>
 
351
        <term><option>--passfile
 
352
        <replaceable>FILE</replaceable></option></term>
 
353
        <term><option>-F
 
354
        <replaceable>FILE</replaceable></option></term>
 
355
        <listitem>
 
356
          <para>
 
357
            The same as <option>--password</option>, but read from
 
358
            <replaceable>FILE</replaceable>, not the terminal.
 
359
          </para>
 
360
        </listitem>
 
361
      </varlistentry>
 
362
      <varlistentry>
 
363
        <term><option>--no-ssh</option></term>
 
364
        <term><option>-S</option></term>
 
365
        <listitem>
 
366
          <para>
 
367
            When <option>--password</option> or
 
368
            <option>--passfile</option> is given, this option will
 
369
            prevent <command>&COMMANDNAME;</command> from calling
 
370
            <command>ssh-keyscan</command> to get an SSH fingerprint
 
371
            for this host and, if successful, output suitable config
 
372
            options to use this fingerprint as a
 
373
            <option>checker</option> option in the output.  This is
 
374
            otherwise the default behavior.
332
375
          </para>
333
376
        </listitem>
334
377
      </varlistentry>
335
378
    </variablelist>
336
379
  </refsect1>
337
 
 
 
380
  
338
381
  <refsect1 id="overview">
339
382
    <title>OVERVIEW</title>
340
383
    <xi:include href="overview.xml"/>
341
384
    <para>
342
385
      This program is a small utility to generate new OpenPGP keys for
343
 
      new Mandos clients.
 
386
      new Mandos clients, and to generate sections for inclusion in
 
387
      <filename>clients.conf</filename> on the server.
344
388
    </para>
345
389
  </refsect1>
346
 
 
 
390
  
347
391
  <refsect1 id="exit_status">
348
392
    <title>EXIT STATUS</title>
349
393
    <para>
350
 
      The exit status will be 0 if new keys were successfully created,
351
 
      otherwise not.
 
394
      The exit status will be 0 if a new key (or password, if the
 
395
      <option>--password</option> option was used) was successfully
 
396
      created, otherwise not.
352
397
    </para>
353
398
  </refsect1>
354
399
  
368
413
    </variablelist>
369
414
  </refsect1>
370
415
  
371
 
  <refsect1 id="file">
 
416
  <refsect1 id="files">
372
417
    <title>FILES</title>
373
418
    <para>
374
419
      Use the <option>--dir</option> option to change where
395
440
        </listitem>
396
441
      </varlistentry>
397
442
      <varlistentry>
398
 
        <term><filename>/tmp</filename></term>
 
443
        <term><filename class="directory">/tmp</filename></term>
399
444
        <listitem>
400
445
          <para>
401
446
            Temporary files will be written here if
405
450
      </varlistentry>
406
451
    </variablelist>
407
452
  </refsect1>
408
 
 
 
453
  
409
454
  <refsect1 id="bugs">
410
455
    <title>BUGS</title>
411
 
    <para>
412
 
      None are known at this time.
413
 
    </para>
 
456
    <xi:include href="bugs.xml"/>
414
457
  </refsect1>
415
 
 
 
458
  
416
459
  <refsect1 id="example">
417
460
    <title>EXAMPLE</title>
418
461
    <informalexample>
425
468
    </informalexample>
426
469
    <informalexample>
427
470
      <para>
428
 
        Create keys in another directory and of another type.  Force
 
471
        Create key in another directory and of another type.  Force
429
472
        overwriting old key files:
430
473
      </para>
431
474
      <para>
435
478
 
436
479
      </para>
437
480
    </informalexample>
 
481
    <informalexample>
 
482
      <para>
 
483
        Prompt for a password, encrypt it with the key in <filename
 
484
        class="directory">/etc/mandos</filename> and output a section
 
485
        suitable for <filename>clients.conf</filename>.
 
486
      </para>
 
487
      <para>
 
488
        <userinput>&COMMANDNAME; --password</userinput>
 
489
      </para>
 
490
    </informalexample>
 
491
    <informalexample>
 
492
      <para>
 
493
        Prompt for a password, encrypt it with the key in the
 
494
        <filename>client-key</filename> directory and output a section
 
495
        suitable for <filename>clients.conf</filename>.
 
496
      </para>
 
497
      <para>
 
498
 
 
499
<!-- do not wrap this line -->
 
500
<userinput>&COMMANDNAME; --password --dir client-key</userinput>
 
501
 
 
502
      </para>
 
503
    </informalexample>
438
504
  </refsect1>
439
 
 
 
505
  
440
506
  <refsect1 id="security">
441
507
    <title>SECURITY</title>
442
508
    <para>
443
509
      The <option>--type</option>, <option>--length</option>,
444
510
      <option>--subtype</option>, and <option>--sublength</option>
445
 
      options can be used to create keys of insufficient security.  If
446
 
      in doubt, leave them to the default values.
 
511
      options can be used to create keys of low security.  If in
 
512
      doubt, leave them to the default values.
447
513
    </para>
448
514
    <para>
449
 
      The key expire time is not guaranteed to be honored by
450
 
      <citerefentry><refentrytitle>mandos</refentrytitle>
 
515
      The key expire time is <emphasis>not</emphasis> guaranteed to be
 
516
      honored by <citerefentry><refentrytitle>mandos</refentrytitle>
451
517
      <manvolnum>8</manvolnum></citerefentry>.
452
518
    </para>
453
519
  </refsect1>
454
 
 
 
520
  
455
521
  <refsect1 id="see_also">
456
522
    <title>SEE ALSO</title>
457
523
    <para>
 
524
      <citerefentry><refentrytitle>intro</refentrytitle>
 
525
      <manvolnum>8mandos</manvolnum></citerefentry>,
458
526
      <citerefentry><refentrytitle>gpg</refentrytitle>
459
527
      <manvolnum>1</manvolnum></citerefentry>,
 
528
      <citerefentry><refentrytitle>mandos-clients.conf</refentrytitle>
 
529
      <manvolnum>5</manvolnum></citerefentry>,
460
530
      <citerefentry><refentrytitle>mandos</refentrytitle>
461
531
      <manvolnum>8</manvolnum></citerefentry>,
462
 
      <citerefentry><refentrytitle>password-request</refentrytitle>
463
 
      <manvolnum>8mandos</manvolnum></citerefentry>
 
532
      <citerefentry><refentrytitle>mandos-client</refentrytitle>
 
533
      <manvolnum>8mandos</manvolnum></citerefentry>,
 
534
      <citerefentry><refentrytitle>ssh-keyscan</refentrytitle>
 
535
      <manvolnum>1</manvolnum></citerefentry>
464
536
    </para>
465
537
  </refsect1>
466
538