/mandos/trunk

<!ENTITY TIMESTAMP "2023-10-21">

<!ENTITY % common SYSTEM "../common.ent">

%common;

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

    <productnumber>&version;</productnumber>

          <email>belorn@recompile.se</email>

          <email>teddy@recompile.se</email>

      <year>2009</year>

      <year>2010</year>

      <year>2011</year>

      <year>2012</year>

      <year>2013</year>

      <year>2014</year>

      <year>2015</year>

      <year>2016</year>

      <year>2017</year>

      <year>2018</year>

      <year>2019</year>

      <group rep='repeat'>

        <replaceable>NAME</replaceable><arg rep='repeat'

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

        <arg choice="plain"><option>-i <replaceable>NAME</replaceable

        ><arg rep='repeat'>,<replaceable>NAME</replaceable></arg

        ></option></arg>

      <group>

        <arg choice="plain"><option>--tls-privkey

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

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

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

      </group>

      <sbr/>

      <group>

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

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

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

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

      </group>

      <sbr/>

        <option>--dh-params <replaceable>FILE</replaceable></option>

      </arg>

      <sbr/>

      <arg>

        <option>--delay <replaceable>SECONDS</replaceable></option>

      </arg>

      <sbr/>

      <arg>

        <option>--retry <replaceable>SECONDS</replaceable></option>

      </arg>

      <sbr/>

      <arg>

        <option>--network-hook-dir

        <replaceable>DIR</replaceable></option>

      </arg>

      <sbr/>

      <arg>

      to get a password.  In slightly more detail, this client program

      brings up network interfaces, uses the interfaces’ IPv6

      link-local addresses to get network connectivity, uses Zeroconf

      to find servers on the local network, and communicates with

      servers using TLS with a raw public key to ensure authenticity

      and confidentiality.  This client program keeps running, trying

      all servers on the network, until it receives a satisfactory

      reply or a TERM signal.  After all servers have been tried, all

      servers are periodically retried.  If no servers are found it

      will wait indefinitely for new servers to appear.

    </para>

    <para>

      The network interfaces are selected like this: If any interfaces

      are specified using the <option>--interface</option> option,

      those interface are used.  Otherwise,

      <command>&COMMANDNAME;</command> will use all interfaces that

      are not loopback interfaces, are not point-to-point interfaces,

      are capable of broadcasting and do not have the NOARP flag (see

      <citerefentry><refentrytitle>netdevice</refentrytitle>

      <manvolnum>7</manvolnum></citerefentry>).  (If the

      <option>--connect</option> option is used, point-to-point

      interfaces and non-broadcast interfaces are accepted.)  If any

      used interfaces are not up and running, they are first taken up

      (and later taken down again on program exit).

    </para>

    <para>

      Before network interfaces are selected, all <quote>network

      hooks</quote> are run; see <xref linkend="network-hooks"/>.

      to be run by other programs in the initial

      <acronym>RAM</acronym> disk environment; see <xref

      linkend="overview"/>.

      is normally started by another program as described in <xref

      linkend="description"/>.  Any command line options this program

      accepts are therefore normally provided by the invoking program,

      and not directly.

            Normally, Zeroconf would be used to locate Mandos servers,

            in which case this option would only be used when testing

            and debugging.

        <term><option>--interface=<replaceable

        >NAME</replaceable><arg rep='repeat'>,<replaceable

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

        <replaceable>NAME</replaceable><arg rep='repeat'>,<replaceable

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

            Comma separated list of network interfaces that will be

            brought up and scanned for Mandos servers to connect to.

            The default is the empty string, which will automatically

            use all appropriate interfaces.

          </para>

          <para>

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

            exactly one interface name is specified (except

            <quote><literal>none</literal></quote>), this specifies

            the interface to use to connect to the address given.

          </para>

          <para>

            Note that since this program will normally run in the

            initial RAM disk environment, the interface must be an

            interface which exists at that stage.  Thus, the interface

            can normally not be a pseudo-interface such as

            <quote>br0</quote> or <quote>tun0</quote>; such interfaces

            will not exist until much later in the boot process, and

            can not be used by this program, unless created by a

            <quote>network hook</quote> — see <xref

            linkend="network-hooks"/>.

          </para>

          <para>

            <replaceable>NAME</replaceable> can be the string

            <quote><literal>none</literal></quote>; this will make

            <command>&COMMANDNAME;</command> only bring up interfaces

            specified <emphasis>before</emphasis> this string.  This

            is not recommended, and only meant for advanced users.

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

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

        <term><option>-T

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

        <listitem>

          <para>

            TLS raw public key file name.  The default name is

            <quote><filename>/conf/conf.d/mandos/tls-pubkey.pem</filename

            ></quote>.

          </para>

        </listitem>

      </varlistentry>

 

      <varlistentry>

        <term><option>--tls-privkey=<replaceable

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

        <term><option>-t

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

        <listitem>

          <para>

            TLS secret key file name.  The default name is

            <quote><filename>/conf/conf.d/mandos/tls-privkey.pem</filename

            ></quote>.

          </para>

        </listitem>

      </varlistentry>

 

      <varlistentry>

            TLS Diffie-Hellman key exchange.  The default value is

            selected automatically based on the GnuTLS security

            profile set in its priority string.  Note that if the

            <option>--dh-params</option> option is used, the values

            from that file will be used instead.

          </para>

        </listitem>

      </varlistentry>

      

      <varlistentry>

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

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

        <listitem>

          <para>

            Specifies a PEM-encoded PKCS#3 file to read the parameters

            needed by the TLS Diffie-Hellman key exchange from.  If

            this option is not given, or if the file for some reason

            could not be used, the parameters will be generated on

            startup, which will take some time and processing power.

            Those using servers running under time, power or processor

            constraints may want to generate such a file in advance

            and use this option.

          </para>

        </listitem>

      </varlistentry>

 

      <varlistentry>

        <term><option>--delay=<replaceable

        >SECONDS</replaceable></option></term>

        <listitem>

          <para>

            After bringing a network interface up, the program waits

            for the interface to arrive in a <quote>running</quote>

            state before proceeding.  During this time, the kernel log

            level will be lowered to reduce clutter on the system

            console, alleviating any other plugins which might be

            using the system console.  This option sets the upper

            limit of seconds to wait.  The default is 2.5 seconds.

          </para>

        </listitem>

      </varlistentry>

 

      <varlistentry>

        <term><option>--retry=<replaceable

        >SECONDS</replaceable></option></term>

        <listitem>

          <para>

            All Mandos servers are tried repeatedly until a password

            is received.  This value specifies, in seconds, how long

            between each successive try <emphasis>for the same

            server</emphasis>.  The default is 10 seconds.

          </para>

        </listitem>

      </varlistentry>

 

      <varlistentry>

        <term><option>--network-hook-dir=<replaceable

        >DIR</replaceable></option></term>

        <listitem>

          <para>

            Network hook directory.  The default directory is

            <quote><filename class="directory"

            >/lib/mandos/network-hooks.d</filename></quote>.

      This program is the client part.  It is run automatically in an

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

    </para>

    <para>

      In an initial <acronym>RAM</acronym> disk environment using

      <citerefentry><refentrytitle>systemd</refentrytitle>

      <manvolnum>1</manvolnum></citerefentry>, this program is started

      by the <application>Mandos</application> <citerefentry>

      <refentrytitle>password-agent</refentrytitle>

      <manvolnum>8mandos</manvolnum></citerefentry>, which in turn is

      started automatically by the <citerefentry>

      <refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum>

      </citerefentry> <quote>Password Agent</quote> system.

    </para>

    <para>

      In the case of a non-<citerefentry>

      <refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum>

      </citerefentry> environment, this program is started 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.

      at all.

      error occurs.  Otherwise, it will forever connect to any

      discovered <application>Mandos</application> servers, trying to

      get a decryptable password and print it.

    <variablelist>

      <varlistentry>

        <term><envar>MANDOSPLUGINHELPERDIR</envar></term>

        <listitem>

          <para>

            This environment variable will be assumed to contain the

            directory containing any helper executables.  The use and

            nature of these helper executables, if any, is purposely

            not documented.

        </para>

        </listitem>

      </varlistentry>

    </variablelist>

      This program does not use any other environment variables, not

      even the ones provided by <citerefentry><refentrytitle

  <refsect1 id="network-hooks">

    <title>NETWORK HOOKS</title>

    <para>

      If a network interface like a bridge or tunnel is required to

      find a Mandos server, this requires the interface to be up and

      running before <command>&COMMANDNAME;</command> starts looking

      for Mandos servers.  This can be accomplished by creating a

      <quote>network hook</quote> program, and placing it in a special

      directory.

    </para>

    <para>

      Before the network is used (and again before program exit), any

      runnable programs found in the network hook directory are run

      with the argument <quote><literal>start</literal></quote> or

      <quote><literal>stop</literal></quote>.  This should bring up or

      down, respectively, any network interface which

      <command>&COMMANDNAME;</command> should use.

    </para>

    <refsect2 id="hook-requirements">

      <title>REQUIREMENTS</title>

      <para>

        A network hook must be an executable file, and its name must

        consist entirely of upper and lower case letters, digits,

        underscores, periods, and hyphens.

      </para>

      <para>

        A network hook will receive one argument, which can be one of

        the following:

      </para>

      <variablelist>

        <varlistentry>

          <term><literal>start</literal></term>

          <listitem>

            <para>

              This should make the network hook create (if necessary)

              and bring up a network interface.

            </para>

          </listitem>

        </varlistentry>

        <varlistentry>

          <term><literal>stop</literal></term>

          <listitem>

            <para>

              This should make the network hook take down a network

              interface, and delete it if it did not exist previously.

            </para>

          </listitem>

        </varlistentry>

        <varlistentry>

          <term><literal>files</literal></term>

          <listitem>

            <para>

              This should make the network hook print, <emphasis>one

              file per line</emphasis>, all the files needed for it to

              run.  (These files will be copied into the initial RAM

              filesystem.)  Typical use is for a network hook which is

              a shell script to print its needed binaries.

            </para>

            <para>

              It is not necessary to print any non-executable files

              already in the network hook directory, these will be

              copied implicitly if they otherwise satisfy the name

              requirements.

            </para>

          </listitem>

        </varlistentry>

        <varlistentry>

          <term><literal>modules</literal></term>

          <listitem>

            <para>

              This should make the network hook print, <emphasis>on

              separate lines</emphasis>, all the kernel modules needed

              for it to run.  (These modules will be copied into the

              initial RAM filesystem.)  For instance, a tunnel

              interface needs the

              <quote><literal>tun</literal></quote> module.

            </para>

          </listitem>

        </varlistentry>

      </variablelist>

      <para>

        The network hook will be provided with a number of environment

        variables:

      </para>

      <variablelist>

        <varlistentry>

          <term><envar>MANDOSNETHOOKDIR</envar></term>

          <listitem>

            <para>

              The network hook directory, specified to

              <command>&COMMANDNAME;</command> by the

              <option>--network-hook-dir</option> option.  Note: this

              should <emphasis>always</emphasis> be used by the

              network hook to refer to itself or any files in the hook

              directory it may require.

            </para>

          </listitem>

        </varlistentry>

        <varlistentry>

          <term><envar>DEVICE</envar></term>

          <listitem>

            <para>

              The network interfaces, as specified to

              <command>&COMMANDNAME;</command> by the

              <option>--interface</option> option, combined to one

              string and separated by commas.  If this is set, and

              does not contain the interface a hook will bring up,

              there is no reason for a hook to continue.

            </para>

          </listitem>

        </varlistentry>

        <varlistentry>

          <term><envar>MODE</envar></term>

          <listitem>

            <para>

              This will be the same as the first argument;

              i.e. <quote><literal>start</literal></quote>,

              <quote><literal>stop</literal></quote>,

              <quote><literal>files</literal></quote>, or

              <quote><literal>modules</literal></quote>.

            </para>

          </listitem>

        </varlistentry>

        <varlistentry>

          <term><envar>VERBOSITY</envar></term>

          <listitem>

            <para>

              This will be the <quote><literal>1</literal></quote> if

              the <option>--debug</option> option is passed to

              <command>&COMMANDNAME;</command>, otherwise

              <quote><literal>0</literal></quote>.

            </para>

          </listitem>

        </varlistentry>

        <varlistentry>

          <term><envar>DELAY</envar></term>

          <listitem>

            <para>

              This will be the same as the <option>--delay</option>

              option passed to <command>&COMMANDNAME;</command>.  Is

              only set if <envar>MODE</envar> is

              <quote><literal>start</literal></quote> or

              <quote><literal>stop</literal></quote>.

            </para>

          </listitem>

        </varlistentry>

        <varlistentry>

          <term><envar>CONNECT</envar></term>

          <listitem>

            <para>

              This will be the same as the <option>--connect</option>

              option passed to <command>&COMMANDNAME;</command>.  Is

              only set if <option>--connect</option> is passed and

              <envar>MODE</envar> is

              <quote><literal>start</literal></quote> or

              <quote><literal>stop</literal></quote>.

            </para>

          </listitem>

        </varlistentry>

      </variablelist>

      <para>

        A hook may not read from standard input, and should be

        restrictive in printing to standard output or standard error

        unless <varname>VERBOSITY</varname> is

        <quote><literal>1</literal></quote>.

      </para>

    </refsect2>

  </refsect1>

  

  <refsect1 id="files">

      <varlistentry>

        <term><filename>/conf/conf.d/mandos/tls-pubkey.pem</filename

        ></term>

        <term><filename>/conf/conf.d/mandos/tls-privkey.pem</filename

        ></term>

        <listitem>

          <para>

            Public and private raw key files, in <quote>PEM</quote>

            format.  These are the default file names, they can be

            changed with the <option>--tls-pubkey</option> and

            <option>--tls-privkey</option> options.

          </para>

        </listitem>

      </varlistentry>

      <varlistentry>

        <term><filename

        class="directory">/lib/mandos/network-hooks.d</filename></term>

        <listitem>

          <para>

            Directory where network hooks are located.  Change this

            with the <option>--network-hook-dir</option> option.  See

            <xref linkend="network-hooks"/>.

          </para>

        </listitem>

      </varlistentry>

  <refsect1 id="bugs">

    <title>BUGS</title>

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

  </refsect1>

      directly, but passed on via the program responsible for starting

      this program; see <xref linkend="overview"/>.

        Normal invocation needs no options, if the network interfaces

        can be automatically determined:

        Search for Mandos servers (and connect to them) using one

        specific interface:

        Run in debug mode, and use custom keys:

<userinput>&COMMANDNAME; --debug --pubkey keydir/pubkey.txt --seckey keydir/seckey.txt --tls-pubkey keydir/tls-pubkey.pem --tls-privkey keydir/tls-privkey.pem</userinput>

        Run in debug mode, with custom keys, and do not use Zeroconf

        to locate a server; connect directly to the IPv6 link-local

        address <quote><systemitem class="ipaddress"

        >fe80::aede:48ff:fe71:f6f2</systemitem></quote>, port 4711,

        using interface eth2:

<userinput>&COMMANDNAME; --debug --pubkey keydir/pubkey.txt --seckey keydir/seckey.txt --tls-pubkey keydir/tls-pubkey.pem --tls-privkey keydir/tls-privkey.pem --connect fe80::aede:48ff:fe71:f6f2:4711 --interface eth2</userinput>

      This program assumes that it is set-uid to root, and will switch

      back to the original (and presumably non-privileged) user and

      group after bringing up the network interface.

      computer, read the OpenPGP and TLS keys directly from the hard

      drive, and communicate with the server.  To safeguard against

      this, the server is supposed to notice the client disappearing

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

      spoofed by someone else on the network, like SSH server key

      fingerprints, and unlike unencrypted <acronym>ICMP</acronym>

      echo (<quote>ping</quote>) replies.

      <citerefentry><refentrytitle>intro</refentrytitle>

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

      <citerefentry><refentrytitle>password-agent</refentrytitle>

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

          <ulink url="https://www.gnutls.org/">GnuTLS</ulink>

          send the public key to the server.

          <ulink url="https://www.gnupg.org/related_software/gpgme/"

                automatically assigned to a network interface when it

          RFC 5246: <citetitle>The Transport Layer Security (TLS)

          Protocol Version 1.2</citetitle>

          TLS 1.2 is the protocol implemented by GnuTLS.

          RFC 7250: <citetitle>Using Raw Public Keys in Transport

          Layer Security (TLS) and Datagram Transport Layer Security

          (DTLS)</citetitle>

        </term>

      <listitem>

        <para>

          This is implemented by GnuTLS in version 3.6.6 and is, if

          present, used by this program so that raw public keys can be

          used.

        </para>

      </listitem>

      </varlistentry>

      <varlistentry>

        <term>

          RFC 6091: <citetitle>Using OpenPGP Keys for Transport Layer

          This is implemented by GnuTLS before version 3.6.0 and is,

          if present, used by this program so that OpenPGP keys can be

          used.