/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: 2014-06-22 02:19:30 UTC
  • Revision ID: teddy@recompile.se-20140622021930-icl7h4cm97blhjml
mandos-keygen: Generate "checker" option to use SSH fingerprints.

To turn this off, use a new "--no-ssh" option to mandos-keygen.

* INSTALL (Mandos Server, Mandos Client): Document new suggested
                                          installation of SSH.
* Makefile (confdir/clients.conf): Use new "--no-ssh" option to
                                   "mandos-keygen".
* debian/control (mandos/Depends): Changed to "fping | ssh-client".
  (mandos-client/Recommends): New; set to "ssh".
* intro.xml (FREQUENTLY ASKED QUESTIONS): Rename and rewrite section
                                          called "Faking ping
                                          replies?" to address new
                                          default behavior.
* mandos-clients.conf.xml (OPTIONS/checker): Briefly discuss new
                                             behavior of
                                             mandos-keygen.
* mandos-keygen: Bug fix: Suppress failure output of "shred" to remove
                 "sec*", since no such files may exist.
 (password mode): Scan for SSH key fingerprints and output as new
                  "checker" and "ssh_fingerprint" options, unless new
                  "--no-ssh" option is given.
* mandos-keygen.xml (SYNOPSIS/--force): Bug fix: Document short form.
  (OPTIONS/--no-ssh): New.
  (SEE ALSO): Add reference "ssh-keyscan(1)".
* plugins.d/mandos-client.xml (SECURITY): Briefly mention the
                                          possibility of using SSH key
                                          fingerprints for checking.

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-09-03">
 
5
<!ENTITY TIMESTAMP "2014-06-22">
 
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>2011</year>
 
37
      <year>2012</year>
34
38
      <holder>Teddy Hogeborn</holder>
35
39
      <holder>Björn Påhlsson</holder>
36
40
    </copyright>
37
41
    <xi:include href="legalnotice.xml"/>
38
42
  </refentryinfo>
39
 
 
 
43
  
40
44
  <refmeta>
41
45
    <refentrytitle>&COMMANDNAME;</refentrytitle>
42
46
    <manvolnum>8</manvolnum>
48
52
      Generate key and password for Mandos client and server.
49
53
    </refpurpose>
50
54
  </refnamediv>
51
 
 
 
55
  
52
56
  <refsynopsisdiv>
53
57
    <cmdsynopsis>
54
58
      <command>&COMMANDNAME;</command>
115
119
        <replaceable>TIME</replaceable></option></arg>
116
120
      </group>
117
121
      <sbr/>
118
 
      <arg><option>--force</option></arg>
 
122
      <group>
 
123
        <arg choice="plain"><option>--force</option></arg>
 
124
        <arg choice="plain"><option>-f</option></arg>
 
125
      </group>
119
126
    </cmdsynopsis>
120
127
    <cmdsynopsis>
121
128
      <command>&COMMANDNAME;</command>
122
129
      <group choice="req">
123
130
        <arg choice="plain"><option>--password</option></arg>
124
131
        <arg choice="plain"><option>-p</option></arg>
 
132
        <arg choice="plain"><option>--passfile
 
133
        <replaceable>FILE</replaceable></option></arg>
 
134
        <arg choice="plain"><option>-F</option>
 
135
        <replaceable>FILE</replaceable></arg>
125
136
      </group>
126
137
      <sbr/>
127
138
      <group>
137
148
        <arg choice="plain"><option>-n
138
149
        <replaceable>NAME</replaceable></option></arg>
139
150
      </group>
 
151
      <group>
 
152
        <arg choice="plain"><option>--no-ssh</option></arg>
 
153
        <arg choice="plain"><option>-S</option></arg>
 
154
      </group>
140
155
    </cmdsynopsis>
141
156
    <cmdsynopsis>
142
157
      <command>&COMMANDNAME;</command>
159
174
    <para>
160
175
      <command>&COMMANDNAME;</command> is a program to generate the
161
176
      OpenPGP key used by
162
 
      <citerefentry><refentrytitle>password-request</refentrytitle>
 
177
      <citerefentry><refentrytitle>mandos-client</refentrytitle>
163
178
      <manvolnum>8mandos</manvolnum></citerefentry>.  The key is
164
179
      normally written to /etc/mandos for later installation into the
165
180
      initrd image, but this, and most other things, can be changed
167
182
    </para>
168
183
    <para>
169
184
      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
 
185
      <option>--password</option> or <option>--passfile</option>
 
186
      options to generate a ready-made section for
 
187
      <filename>clients.conf</filename> (see
172
188
      <citerefentry><refentrytitle>mandos-clients.conf</refentrytitle>
173
189
      <manvolnum>5</manvolnum></citerefentry>).
174
190
    </para>
197
213
          </para>
198
214
        </listitem>
199
215
      </varlistentry>
200
 
 
 
216
      
201
217
      <varlistentry>
202
218
        <term><option>--dir
203
219
        <replaceable>DIRECTORY</replaceable></option></term>
206
222
        <listitem>
207
223
          <para>
208
224
            Target directory for key files.  Default is
209
 
            <filename>/etc/mandos</filename>.
 
225
            <filename class="directory">/etc/mandos</filename>.
210
226
          </para>
211
227
        </listitem>
212
228
      </varlistentry>
213
 
 
 
229
      
214
230
      <varlistentry>
215
231
        <term><option>--type
216
232
        <replaceable>TYPE</replaceable></option></term>
218
234
        <replaceable>TYPE</replaceable></option></term>
219
235
        <listitem>
220
236
          <para>
221
 
            Key type.  Default is <quote>DSA</quote>.
 
237
            Key type.  Default is <quote>RSA</quote>.
222
238
          </para>
223
239
        </listitem>
224
240
      </varlistentry>
225
 
 
 
241
      
226
242
      <varlistentry>
227
243
        <term><option>--length
228
244
        <replaceable>BITS</replaceable></option></term>
230
246
        <replaceable>BITS</replaceable></option></term>
231
247
        <listitem>
232
248
          <para>
233
 
            Key length in bits.  Default is 2048.
 
249
            Key length in bits.  Default is 4096.
234
250
          </para>
235
251
        </listitem>
236
252
      </varlistentry>
237
 
 
 
253
      
238
254
      <varlistentry>
239
255
        <term><option>--subtype
240
256
        <replaceable>KEYTYPE</replaceable></option></term>
242
258
        <replaceable>KEYTYPE</replaceable></option></term>
243
259
        <listitem>
244
260
          <para>
245
 
            Subkey type.  Default is <quote>ELG-E</quote> (Elgamal
 
261
            Subkey type.  Default is <quote>RSA</quote> (Elgamal
246
262
            encryption-only).
247
263
          </para>
248
264
        </listitem>
249
265
      </varlistentry>
250
 
 
 
266
      
251
267
      <varlistentry>
252
268
        <term><option>--sublength
253
269
        <replaceable>BITS</replaceable></option></term>
255
271
        <replaceable>BITS</replaceable></option></term>
256
272
        <listitem>
257
273
          <para>
258
 
            Subkey length in bits.  Default is 2048.
 
274
            Subkey length in bits.  Default is 4096.
259
275
          </para>
260
276
        </listitem>
261
277
      </varlistentry>
262
 
 
 
278
      
263
279
      <varlistentry>
264
280
        <term><option>--email
265
281
        <replaceable>ADDRESS</replaceable></option></term>
271
287
          </para>
272
288
        </listitem>
273
289
      </varlistentry>
274
 
 
 
290
      
275
291
      <varlistentry>
276
292
        <term><option>--comment
277
293
        <replaceable>TEXT</replaceable></option></term>
279
295
        <replaceable>TEXT</replaceable></option></term>
280
296
        <listitem>
281
297
          <para>
282
 
            Comment field for key.  The default value is
283
 
            <quote><literal>Mandos client key</literal></quote>.
 
298
            Comment field for key.  Default is empty.
284
299
          </para>
285
300
        </listitem>
286
301
      </varlistentry>
287
 
 
 
302
      
288
303
      <varlistentry>
289
304
        <term><option>--expire
290
305
        <replaceable>TIME</replaceable></option></term>
298
313
          </para>
299
314
        </listitem>
300
315
      </varlistentry>
301
 
 
 
316
      
302
317
      <varlistentry>
303
318
        <term><option>--force</option></term>
304
319
        <term><option>-f</option></term>
326
341
          </para>
327
342
        </listitem>
328
343
      </varlistentry>
 
344
      <varlistentry>
 
345
        <term><option>--passfile
 
346
        <replaceable>FILE</replaceable></option></term>
 
347
        <term><option>-F
 
348
        <replaceable>FILE</replaceable></option></term>
 
349
        <listitem>
 
350
          <para>
 
351
            The same as <option>--password</option>, but read from
 
352
            <replaceable>FILE</replaceable>, not the terminal.
 
353
          </para>
 
354
        </listitem>
 
355
      </varlistentry>
 
356
      <varlistentry>
 
357
        <term><option>--no-ssh</option></term>
 
358
        <term><option>-S</option></term>
 
359
        <listitem>
 
360
          <para>
 
361
            When <option>--password</option> or
 
362
            <option>--passfile</option> is given, this option will
 
363
            prevent <command>&COMMANDNAME;</command> from calling
 
364
            <command>ssh-keyscan</command> to get an SSH fingerprint
 
365
            for this host and, if successful, output suitable config
 
366
            options to use this fingerprint as a
 
367
            <option>checker</option> option in the output.  This is
 
368
            otherwise the default behavior.
 
369
          </para>
 
370
        </listitem>
 
371
      </varlistentry>
329
372
    </variablelist>
330
373
  </refsect1>
331
 
 
 
374
  
332
375
  <refsect1 id="overview">
333
376
    <title>OVERVIEW</title>
334
377
    <xi:include href="overview.xml"/>
338
381
      <filename>clients.conf</filename> on the server.
339
382
    </para>
340
383
  </refsect1>
341
 
 
 
384
  
342
385
  <refsect1 id="exit_status">
343
386
    <title>EXIT STATUS</title>
344
387
    <para>
364
407
    </variablelist>
365
408
  </refsect1>
366
409
  
367
 
  <refsect1 id="file">
 
410
  <refsect1 id="files">
368
411
    <title>FILES</title>
369
412
    <para>
370
413
      Use the <option>--dir</option> option to change where
391
434
        </listitem>
392
435
      </varlistentry>
393
436
      <varlistentry>
394
 
        <term><filename>/tmp</filename></term>
 
437
        <term><filename class="directory">/tmp</filename></term>
395
438
        <listitem>
396
439
          <para>
397
440
            Temporary files will be written here if
401
444
      </varlistentry>
402
445
    </variablelist>
403
446
  </refsect1>
404
 
 
 
447
  
405
448
<!--   <refsect1 id="bugs"> -->
406
449
<!--     <title>BUGS</title> -->
407
450
<!--     <para> -->
408
451
<!--     </para> -->
409
452
<!--   </refsect1> -->
410
 
 
 
453
  
411
454
  <refsect1 id="example">
412
455
    <title>EXAMPLE</title>
413
456
    <informalexample>
432
475
    </informalexample>
433
476
    <informalexample>
434
477
      <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>.
 
478
        Prompt for a password, encrypt it with the key in <filename
 
479
        class="directory">/etc/mandos</filename> and output a section
 
480
        suitable for <filename>clients.conf</filename>.
438
481
      </para>
439
482
      <para>
440
483
        <userinput>&COMMANDNAME; --password</userinput>
454
497
      </para>
455
498
    </informalexample>
456
499
  </refsect1>
457
 
 
 
500
  
458
501
  <refsect1 id="security">
459
502
    <title>SECURITY</title>
460
503
    <para>
469
512
      <manvolnum>8</manvolnum></citerefentry>.
470
513
    </para>
471
514
  </refsect1>
472
 
 
 
515
  
473
516
  <refsect1 id="see_also">
474
517
    <title>SEE ALSO</title>
475
518
    <para>
 
519
      <citerefentry><refentrytitle>intro</refentrytitle>
 
520
      <manvolnum>8mandos</manvolnum></citerefentry>,
476
521
      <citerefentry><refentrytitle>gpg</refentrytitle>
477
522
      <manvolnum>1</manvolnum></citerefentry>,
478
523
      <citerefentry><refentrytitle>mandos-clients.conf</refentrytitle>
479
524
      <manvolnum>5</manvolnum></citerefentry>,
480
525
      <citerefentry><refentrytitle>mandos</refentrytitle>
481
526
      <manvolnum>8</manvolnum></citerefentry>,
482
 
      <citerefentry><refentrytitle>password-request</refentrytitle>
483
 
      <manvolnum>8mandos</manvolnum></citerefentry>
 
527
      <citerefentry><refentrytitle>mandos-client</refentrytitle>
 
528
      <manvolnum>8mandos</manvolnum></citerefentry>,
 
529
      <citerefentry><refentrytitle>ssh-keyscan</refentrytitle>
 
530
      <manvolnum>1</manvolnum></citerefentry>
484
531
    </para>
485
532
  </refsect1>
486
533