/mandos/release

To get this branch, use:
bzr branch http://bzr.recompile.se/loggerhead/mandos/release

« back to all changes in this revision

Viewing changes to plugins.d/password-request.xml

  • Committer: Teddy Hogeborn
  • Date: 2008-09-03 05:04:40 UTC
  • Revision ID: teddy@fukt.bsnet.se-20080903050440-7cwzxestx6pvdy1i
* Makefile (mandos.8): Add dependency on "overview.xml" and
                       "legalnotice.xml".
  (mandos-keygen.8): New target.
  (mandos-conf.5): Added dependency on "legalnotice.xml".
  (plugin-runner.8mandos): New target
  (plugins.d/password-request.8mandos): - '' -

* mandos-options.xml (priority): Make wording server/client neutral.

* plugins.d/password-request.c (main): Changed .arg fields of the argp
                                       options struct to be more
                                       consistent with the manual.

* plugins.d/password-request.xml (OVERVIEW): Moved to after "OPTIONS".
  (OPTIONS): Improved wording and names of replaceables.

Show diffs side-by-side

added added

removed removed

Lines of Context:
plugins.d/password-request.xml
128
128
      communicates with <citerefentry><refentrytitle
129
129
      >mandos</refentrytitle><manvolnum>8</manvolnum></citerefentry>
130
130
      to get a password.  It uses IPv6 link-local addresses to get
131
 
      network connectivity, Zeroconf to find servers, and TLS with an
132
 
      OpenPGP key to ensure authenticity and confidentiality.  It
 
131
      network connectivity, Zeroconf to find the server, and TLS with
 
132
      an OpenPGP key to ensure authenticity and confidentiality.  It
133
133
      keeps running, trying all servers on the network, until it
134
 
      receives a satisfactory reply or a TERM signal is recieved.
 
134
      receives a satisfactory reply.
135
135
    </para>
136
136
    <para>
137
137
      This program is not meant to be run directly; it is really meant
217
217
            Mandos servers to connect to.  The default it
218
218
            <quote><literal>eth0</literal></quote>.
219
219
          </para>
220
 
          <para>
221
 
            If the <option>--connect</option> option is used, this
222
 
            specifies the interface to use to connect to the address
223
 
            given.
224
 
          </para>
225
220
        </listitem>
226
221
      </varlistentry>
227
222
      
334
329
    <para>
335
330
      This program could, theoretically, be used as a keyscript in
336
331
      <filename>/etc/crypttab</filename>, but it would then be
337
 
      impossible to enter a password for the encrypted root disk at
338
 
      the console, since this program does not read from the console
339
 
      at all.  This is why a separate plugin does that, which will be
340
 
      run in parallell to this one by the plugin runner.
 
332
      impossible to enter the encrypted root disk password at the
 
333
      console, since this program does not read from the console at
 
334
      all.  This is why a separate plugin does that, which will be run
 
335
      in parallell to this one.
341
336
    </para>
342
337
  </refsect1>
343
338
  
349
344
      successfully decrypted and output on standard output.  The
350
345
      program will exit with a non-zero exit status only if a critical
351
346
      error occurs.  Otherwise, it will forever connect to new
352
 
      <application>Mandos</application> servers as they appear, trying
353
 
      to get a decryptable password.
 
347
      <application>Mandosservers</application> servers as they appear,
 
348
      trying to get a decryptable password.
354
349
    </para>
355
350
  </refsect1>
356
351
  
366
361
  
367
362
  <refsect1 id="file">
368
363
    <title>FILES</title>
369
 
    <variablelist>
370
 
      <varlistentry>
371
 
        <term><filename>/conf/conf.d/mandos/pubkey.txt</filename
372
 
        ></term>
373
 
        <term><filename>/conf/conf.d/mandos/seckey.txt</filename
374
 
        ></term>
375
 
        <listitem>
376
 
          <para>
377
 
            OpenPGP public and private key files, in <quote>ASCII
378
 
            Armor</quote> format.  These are the default file names,
379
 
            they can be changed with the <option>--pubkey</option> and
380
 
            <option>--seckey</option> options.
381
 
          </para>
382
 
        </listitem>
383
 
      </varlistentry>
384
 
    </variablelist>
 
364
    <para>
 
365
    </para>
385
366
  </refsect1>
386
367
  
387
 
<!--   <refsect1 id="bugs"> -->
388
 
<!--     <title>BUGS</title> -->
389
 
<!--     <para> -->
390
 
<!--     </para> -->
391
 
<!--   </refsect1> -->
 
368
  <refsect1 id="bugs">
 
369
    <title>BUGS</title>
 
370
    <para>
 
371
    </para>
 
372
  </refsect1>
392
373
 
393
374
  <refsect1 id="example">
394
375
    <title>EXAMPLE</title>
395
376
    <para>
396
 
      Note that normally, command line options will not be given
397
 
      directly, but via options for the Mandos <citerefentry
398
 
      ><refentrytitle>plugin-runner</refentrytitle>
399
 
      <manvolnum>8mandos</manvolnum></citerefentry>.
400
377
    </para>
401
 
    <informalexample>
402
 
      <para>
403
 
        Normal invocation needs no options, if the network interface
404
 
        is <quote>eth0</quote>:
405
 
      </para>
406
 
      <para>
407
 
        <userinput>&COMMANDNAME;</userinput>
408
 
      </para>
409
 
    </informalexample>
410
 
    <informalexample>
411
 
      <para>
412
 
        Search for Mandos servers on another interface:
413
 
      </para>
414
 
      <para>
415
 
        <!-- do not wrap this line -->
416
 
        <userinput>&COMMANDNAME; --interface eth1</userinput>
417
 
      </para>
418
 
    </informalexample>
419
 
    <informalexample>
420
 
      <para>
421
 
        Run in debug mode, and use a custom key directory:
422
 
      </para>
423
 
      <para>
424
 
        <!-- do not wrap this line -->
425
 
        <userinput>&COMMANDNAME; --debug --keydir keydir</userinput>
426
 
      </para>
427
 
    </informalexample>
428
 
    <informalexample>
429
 
      <para>
430
 
        Run in debug mode, with a custom key directory, and do not use
431
 
        Zeroconf to locate a server; connect directly to the IPv6
432
 
        address <quote><systemitem class="ipaddress"
433
 
        >2001:db8:f983:bd0b:30de:ae4a:71f2:f672</systemitem></quote>,
434
 
        port 4711, using interface eth2:
435
 
      </para>
436
 
      <para>
437
 
 
438
 
<!-- do not wrap this line -->
439
 
<userinput>&COMMANDNAME; --debug --keydir keydir --connect 2001:db8:f983:bd0b:30de:ae4a:71f2:f672:4711 --interface eth2</userinput>
440
 
 
441
 
      </para>
442
 
    </informalexample>
443
378
  </refsect1>
444
379
 
445
380
  <refsect1 id="security">
446
381
    <title>SECURITY</title>
447
382
    <para>
448
 
      This program is set-uid to root, but will switch back to the
449
 
      original user and group after bringing up the network interface.
450
 
    </para>
451
 
    <para>
452
 
      To use this program for its intended purpose (see <xref
453
 
      linkend="purpose"/>), the password for the root file system will
454
 
      have to be given out to be stored in a server computer, after
455
 
      having been encrypted using an OpenPGP key.  This encrypted data
456
 
      which will be stored in a server can only be decrypted by the
457
 
      OpenPGP key, and the data will only be given out to those
458
 
      clients who can prove they actually have that key.  This key,
459
 
      however, is stored unencrypted on the client side in its initial
460
 
      <acronym>RAM</acronym> disk image file system.  This is normally
461
 
      readable by all, but this is normally fixed during installation
462
 
      of this program; file permissions are set so that no-one is able
463
 
      to read that file.
464
 
    </para>
465
 
    <para>
466
 
      The only remaining weak point is that someone with physical
467
 
      access to the client hard drive might turn off the client
468
 
      computer, read the OpenPGP keys directly from the hard drive,
469
 
      and communicate with the server.  The defense against this is
470
 
      that the server is supposed to notice the client disappearing
471
 
      and will stop giving out the encrypted data.  Therefore, it is
472
 
      important to set the timeout and checker interval values tightly
473
 
      on the server.  See <citerefentry><refentrytitle
474
 
      >mandos</refentrytitle><manvolnum>8</manvolnum></citerefentry>.
475
 
    </para>
476
 
    <para>
477
 
      <emphasis>Note</emphasis>: This makes it impossible to have
478
 
      <application >Mandos</application> clients which dual-boot to
479
 
      another operating system which does <emphasis>not</emphasis> run
480
 
      a <application>Mandos</application> client.
481
383
    </para>
482
384
  </refsect1>
483
385