/mandos/trunk

<?xml version="1.0" encoding="UTF-8"?>

<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"

	"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [

<!ENTITY VERSION "1.0">

<!ENTITY COMMANDNAME "password-request">

<!ENTITY TIMESTAMP "2008-09-03">

]>

<refentry xmlns:xi="http://www.w3.org/2001/XInclude">

  <refentryinfo>

    <title>Mandos Manual</title>

    <!-- Nwalsh’s docbook scripts use this to generate the footer: -->

    <productname>Mandos</productname>

    <productnumber>&VERSION;</productnumber>

    <date>&TIMESTAMP;</date>

    <authorgroup>

      <author>

	<firstname>Björn</firstname>

	<surname>Påhlsson</surname>

	<address>

	  <email>belorn@fukt.bsnet.se</email>

	</address>

      </author>

      <author>

	<firstname>Teddy</firstname>

	<surname>Hogeborn</surname>

	<address>

	  <email>teddy@fukt.bsnet.se</email>

	</address>

      </author>

    </authorgroup>

    <copyright>

      <year>2008</year>

      <holder>Teddy Hogeborn</holder>

      <holder>Björn Påhlsson</holder>

    </copyright>

    <xi:include href="../legalnotice.xml"/>

  </refentryinfo>

  <refmeta>

    <refentrytitle>&COMMANDNAME;</refentrytitle>

    <manvolnum>8mandos</manvolnum>

  </refmeta>

  <refnamediv>

    <refname><command>&COMMANDNAME;</command></refname>

    <refpurpose>

      Client for mandos

    </refpurpose>

  </refnamediv>

  <refsynopsisdiv>

    <cmdsynopsis>

      <command>&COMMANDNAME;</command>

      <group>

	<arg choice="plain"><option>--connect

	<replaceable>IPADDR</replaceable><literal>:</literal

	><replaceable>PORT</replaceable></option></arg>

	<arg choice="plain"><option>-c

	<replaceable>IPADDR</replaceable><literal>:</literal

	><replaceable>PORT</replaceable></option></arg>

      </group>

      <sbr/>

      <group>

	<arg choice="plain"><option>--keydir

	<replaceable>DIRECTORY</replaceable></option></arg>

	<arg choice="plain"><option>-d

	<replaceable>DIRECTORY</replaceable></option></arg>

      </group>

      <sbr/>

      <group>

	<arg choice="plain"><option>--interface

	<replaceable>NAME</replaceable></option></arg>

	<arg choice="plain"><option>-i

	<replaceable>NAME</replaceable></option></arg>

      </group>

      <sbr/>

      <group>

	<arg choice="plain"><option>--pubkey

	<replaceable>FILE</replaceable></option></arg>

	<arg choice="plain"><option>-p

	<replaceable>FILE</replaceable></option></arg>

      </group>

      <sbr/>

      <group>

	<arg choice="plain"><option>--seckey

	<replaceable>FILE</replaceable></option></arg>

	<arg choice="plain"><option>-s

	<replaceable>FILE</replaceable></option></arg>

      </group>

      <sbr/>

      <arg>

	<option>--priority <replaceable>STRING</replaceable></option>

      </arg>

      <sbr/>

      <arg>

	<option>--dh-bits <replaceable>BITS</replaceable></option>

      </arg>

      <sbr/>

      <arg>

	<option>--debug</option>

      </arg>

    </cmdsynopsis>

    <cmdsynopsis>

      <command>&COMMANDNAME;</command>

      <group choice="req">

	<arg choice="plain"><option>--help</option></arg>

	<arg choice="plain"><option>-?</option></arg>

      </group>

    </cmdsynopsis>

    <cmdsynopsis>

      <command>&COMMANDNAME;</command>

      <arg choice="plain"><option>--usage</option></arg>

    </cmdsynopsis>

    <cmdsynopsis>

      <command>&COMMANDNAME;</command>

      <group choice="req">

	<arg choice="plain"><option>--version</option></arg>

	<arg choice="plain"><option>-V</option></arg>

      </group>

    </cmdsynopsis>

  </refsynopsisdiv>

  <refsect1 id="description">

    <title>DESCRIPTION</title>

    <para>

      <command>&COMMANDNAME;</command> is a client program that

      communicates with <citerefentry><refentrytitle

      >mandos</refentrytitle><manvolnum>8</manvolnum></citerefentry>

      to get a password.  It uses IPv6 link-local addresses to get

      network connectivity, Zeroconf to find servers, and TLS with an

      OpenPGP key to ensure authenticity and confidentiality.  It

      keeps running, trying all servers on the network, until it

      receives a satisfactory reply or a TERM signal is recieved.

    </para>

    <para>

      This program is not meant to be run directly; it is really meant

      to run as a plugin of the <application>Mandos</application>

      <citerefentry><refentrytitle>plugin-runner</refentrytitle>

      <manvolnum>8mandos</manvolnum></citerefentry>, which runs in the

      initial <acronym>RAM</acronym> disk environment because it is

      specified as a <quote>keyscript</quote> in the <citerefentry>

      <refentrytitle>crypttab</refentrytitle><manvolnum>5</manvolnum>

      </citerefentry> file.

    </para>

  </refsect1>

  <refsect1 id="purpose">

    <title>PURPOSE</title>

    <para>

      The purpose of this is to enable <emphasis>remote and unattended

      rebooting</emphasis> of client host computer with an

      <emphasis>encrypted root file system</emphasis>.  See <xref

      linkend="overview"/> for details.

    </para>

  </refsect1>

  <refsect1 id="options">

    <title>OPTIONS</title>

    <para>

      This program is commonly not invoked from the command line; it

      is normally started by the <application>Mandos</application>

      plugin runner, see <citerefentry><refentrytitle

      >plugin-runner</refentrytitle><manvolnum>8mandos</manvolnum>

      </citerefentry>.  Any command line options this program accepts

      are therefore normally provided by the plugin runner, and not

      directly.

    </para>

    <variablelist>

      <varlistentry>

	<term><option>--connect=<replaceable

	>ADDRESS</replaceable><literal>:</literal><replaceable

	>PORT</replaceable></option></term>

	<term><option>-c

	<replaceable>ADDRESS</replaceable><literal>:</literal

	><replaceable>PORT</replaceable></option></term>

	<listitem>

	  <para>

	    Do not use Zeroconf to locate servers.  Connect directly

	    to only one specified <application>Mandos</application>

	    server.  Note that an IPv6 address has colon characters in

	    it, so the <emphasis>last</emphasis> colon character is

	    assumed to separate the address from the port number.

	  </para>

	  <para>

	    This option is normally only useful for testing and

	    debugging.

	  </para>

	</listitem>

      </varlistentry>

      <varlistentry>

	<term><option>--keydir=<replaceable

	>DIRECTORY</replaceable></option></term>

	<term><option>-d

	<replaceable>DIRECTORY</replaceable></option></term>

	<listitem>

	  <para>

	    Directory to read the OpenPGP key files

	    <filename>pubkey.txt</filename> and

	    <filename>seckey.txt</filename> from.  The default is

	    <filename>/conf/conf.d/mandos</filename> (in the initial

	    <acronym>RAM</acronym> disk environment).

	  </para>

	</listitem>

      </varlistentry>

      <varlistentry>

	<term><option>--interface=

	<replaceable>NAME</replaceable></option></term>

	<term><option>-i

	<replaceable>NAME</replaceable></option></term>

	<listitem>

	  <para>

	    Network interface that will be brought up and scanned for

	    Mandos servers to connect to.  The default it

	    <quote><literal>eth0</literal></quote>.

	  </para>

	  <para>

	    If the <option>--connect</option> option is used, this

	    specifies the interface to use to connect to the address

	    given.

	  </para>

	</listitem>

      </varlistentry>

      <varlistentry>

	<term><option>--pubkey=<replaceable

	>FILE</replaceable></option></term>

	<term><option>-p

	<replaceable>FILE</replaceable></option></term>

	<listitem>

	  <para>

	    OpenPGP public key file base name.  This will be combined

	    with the directory from the <option>--keydir</option>

	    option to form an absolute file name.  The default name is

	    <quote><literal>pubkey.txt</literal></quote>.

	  </para>

	</listitem>

      </varlistentry>

      <varlistentry>

	<term><option>--seckey=<replaceable

	>FILE</replaceable></option></term>

	<term><option>-s

	<replaceable>FILE</replaceable></option></term>

	<listitem>

	  <para>

	    OpenPGP secret key file base name.  This will be combined

	    with the directory from the <option>--keydir</option>

	    option to form an absolute file name.  The default name is

	    <quote><literal>seckey.txt</literal></quote>.

	  </para>

	</listitem>

      </varlistentry>

      <varlistentry>

	<term><option>--priority=<replaceable

	>STRING</replaceable></option></term>

	<listitem>

	  <xi:include href="../mandos-options.xml"

		      xpointer="priority"/>

	</listitem>

      </varlistentry>

      <varlistentry>

	<term><option>--dh-bits=<replaceable

	>BITS</replaceable></option></term>

	<listitem>

	  <para>

	    Sets the number of bits to use for the prime number in the

	    TLS Diffie-Hellman key exchange.  Default is 1024.

	  </para>

	</listitem>

      </varlistentry>

      <varlistentry>

	<term><option>--debug</option></term>

	<listitem>

	  <para>

	    Enable debug mode.  This will enable a lot of output to

	    standard error about what the program is doing.  The

	    program will still perform all other functions normally.

	  </para>

	  <para>

	    It will also enable debug mode in the Avahi and GnuTLS

	    libraries, making them print large amounts of debugging

	    output.

	  </para>

	</listitem>

      </varlistentry>

      <varlistentry>

	<term><option>--help</option></term>

	<term><option>-?</option></term>

	<listitem>

	  <para>

	    Gives a help message about options and their meanings.

	  </para>

	</listitem>

      </varlistentry>

      <varlistentry>

	<term><option>--usage</option></term>

	<listitem>

	  <para>

	    Gives a short usage message.

	  </para>

	</listitem>

      </varlistentry>

      <varlistentry>

	<term><option>--version</option></term>

	<term><option>-V</option></term>

	<listitem>

	  <para>

	    Prints the program version.

	  </para>

	</listitem>

      </varlistentry>

    </variablelist>

  </refsect1>

  <refsect1 id="overview">

    <title>OVERVIEW</title>

    <xi:include href="../overview.xml"/>

    <para>

      This program is the client part.  It is a plugin started by

      <citerefentry><refentrytitle>plugin-runner</refentrytitle>

      <manvolnum>8mandos</manvolnum></citerefentry> which will run in

      an initial <acronym>RAM</acronym> disk environment.

    </para>

    <para>

      This program could, theoretically, be used as a keyscript in

      <filename>/etc/crypttab</filename>, but it would then be

      impossible to enter a password for the encrypted root disk at

      the console, since this program does not read from the console

      at all.  This is why a separate plugin does that, which will be

      run in parallell to this one by the plugin runner.

    </para>

  </refsect1>

  <refsect1 id="exit_status">

    <title>EXIT STATUS</title>

    <para>

      This program will exit with a successful (zero) exit status if a

      server could be found and the password received from it could be

      successfully decrypted and output on standard output.  The

      program will exit with a non-zero exit status only if a critical

      error occurs.  Otherwise, it will forever connect to new

      <application>Mandos</application> servers as they appear, trying

      to get a decryptable password.

    </para>

  </refsect1>

  <refsect1 id="environment">

    <title>ENVIRONMENT</title>

    <para>

      This program does not use any environment variables, not even

      the ones provided by <citerefentry><refentrytitle

      >cryptsetup</refentrytitle><manvolnum>8</manvolnum>

    </citerefentry>.

    </para>

  </refsect1>

  <refsect1 id="file">

    <title>FILES</title>

    <variablelist>

      <varlistentry>

	<term><filename>/conf/conf.d/mandos/pubkey.txt</filename

	></term>

	<term><filename>/conf/conf.d/mandos/seckey.txt</filename

	></term>

	<listitem>

	  <para>

	    OpenPGP public and private key files, in <quote>ASCII

	    Armor</quote> format.  These are the default file names,

	    they can be changed with the <option>--pubkey</option> and

	    <option>--seckey</option> options.

	  </para>

	</listitem>

      </varlistentry>

    </variablelist>

  </refsect1>

<!--   <refsect1 id="bugs"> -->

<!--     <title>BUGS</title> -->

<!--     <para> -->

<!--     </para> -->

<!--   </refsect1> -->

  <refsect1 id="example">

    <title>EXAMPLE</title>

    <para>

      Note that normally, command line options will not be given

      directly, but via options for the Mandos <citerefentry

      ><refentrytitle>plugin-runner</refentrytitle>

      <manvolnum>8mandos</manvolnum></citerefentry>.

    </para>

    <informalexample>

      <para>

	Normal invocation needs no options, if the network interface

	is <quote>eth0</quote>:

      </para>

      <para>

	<userinput>&COMMANDNAME;</userinput>

      </para>

    </informalexample>

    <informalexample>

      <para>

	Search for Mandos servers on another interface:

      </para>

      <para>

	<!-- do not wrap this line -->

	<userinput>&COMMANDNAME; --interface eth1</userinput>

      </para>

    </informalexample>

    <informalexample>

      <para>

	Run in debug mode, and use a custom key directory:

      </para>

      <para>

	<!-- do not wrap this line -->

	<userinput>&COMMANDNAME; --debug --keydir keydir</userinput>

      </para>

    </informalexample>

    <informalexample>

      <para>

	Run in debug mode, with a custom key directory, and do not use

	Zeroconf to locate a server; connect directly to the IPv6

	address <quote><systemitem class="ipaddress"

	>2001:db8:f983:bd0b:30de:ae4a:71f2:f672</systemitem></quote>,

	port 4711, using interface eth2:

      </para>

      <para>

<!-- do not wrap this line -->

<userinput>&COMMANDNAME; --debug --keydir keydir --connect 2001:db8:f983:bd0b:30de:ae4a:71f2:f672:4711 --interface eth2</userinput>

      </para>

    </informalexample>

  </refsect1>

  <refsect1 id="security">

    <title>SECURITY</title>

    <para>

      This program is set-uid to root, but will switch back to the

      original user and group after bringing up the network interface.

    </para>

    <para>

      To use this program for its intended purpose (see <xref

      linkend="purpose"/>), the password for the root file system will

      have to be given out to be stored in a server computer, after

      having been encrypted using an OpenPGP key.  This encrypted data

      which will be stored in a server can only be decrypted by the

      OpenPGP key, and the data will only be given out to those

      clients who can prove they actually have that key.  This key,

      however, is stored unencrypted on the client side in its initial

      <acronym>RAM</acronym> disk image file system.  This is normally

      readable by all, but this is normally fixed during installation

      of this program; file permissions are set so that no-one is able

      to read that file.

    </para>

    <para>

      The only remaining weak point is that someone with physical

      access to the client hard drive might turn off the client

      computer, read the OpenPGP keys directly from the hard drive,

      and communicate with the server.  The defense against this is

      that the server is supposed to notice the client disappearing

      and will stop giving out the encrypted data.  Therefore, it is

      important to set the timeout and checker interval values tightly

      on the server.  See <citerefentry><refentrytitle

      >mandos</refentrytitle><manvolnum>8</manvolnum></citerefentry>.

    </para>

    <para>

      <emphasis>Note</emphasis>: This makes it impossible to have

      <application >Mandos</application> clients which dual-boot to

      another operating system which does <emphasis>not</emphasis> run

      a <application>Mandos</application> client.

    </para>

  </refsect1>

  <refsect1 id="see_also">

    <title>SEE ALSO</title>

    <para>

      <citerefentry><refentrytitle>mandos</refentrytitle>

      <manvolnum>8</manvolnum></citerefentry>,

      <citerefentry><refentrytitle>password-prompt</refentrytitle>

      <manvolnum>8mandos</manvolnum></citerefentry>,

      <citerefentry><refentrytitle>plugin-runner</refentrytitle>

      <manvolnum>8mandos</manvolnum></citerefentry>

    </para>

    <itemizedlist>

      <listitem><para>

	<ulink url="http://www.zeroconf.org/">Zeroconf</ulink>

      </para></listitem>

      <listitem><para>

	<ulink url="http://www.avahi.org/">Avahi</ulink>

      </para></listitem>

      <listitem><para>

	<ulink

	    url="http://www.gnu.org/software/gnutls/">GnuTLS</ulink>

      </para></listitem>

      <listitem><para>

	<ulink

	url="http://www.gnupg.org/related_software/gpgme/"

	>GPGME</ulink>

      </para></listitem>

      <listitem><para>

	<citation>RFC 4880: <citetitle>OpenPGP Message

	Format</citetitle></citation>

      </para></listitem>

      <listitem><para>

	<citation>RFC 5081: <citetitle>Using OpenPGP Keys for

	Transport Layer Security</citetitle></citation>

      </para></listitem>

      <listitem><para>

	<citation>RFC 4291: <citetitle>IP Version 6 Addressing

	Architecture</citetitle>, section 2.5.6, Link-Local IPv6

	Unicast Addresses</citation>

      </para></listitem>

    </itemizedlist>

  </refsect1>

</refentry>

<!-- Local Variables: -->

<!-- time-stamp-start: "<!ENTITY TIMESTAMP [\"']" -->

<!-- time-stamp-end: "[\"']>" -->

<!-- time-stamp-format: "%:y-%02m-%02d" -->

<!-- End: -->