/mandos/trunk

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

      <year>2010</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>

      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

      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

      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).

      Before network interfaces are selected, all <quote>network

      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.

        >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.

            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.

            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"/>.

            <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.

            After bringing a network interface up, the program waits

      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.

    <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

              requirements.

              The network interfaces, as specified to

              <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.

              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>.

        <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>

  <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

<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

      important to set the timeout and checker interval values tightly

      on the server.  See <citerefentry><refentrytitle

      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>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.