/mandos/trunk

<!ENTITY TIMESTAMP "2025-06-27">

      <year>2010</year>

      <year>2011</year>

      <year>2013</year>

      <year>2014</year>

      <year>2015</year>

      <year>2016</year>

      <year>2017</year>

      <year>2018</year>

      <year>2019</year>

      <year>2020</year>

      <year>2021</year>

      <year>2022</year>

      <year>2023</year>

      <year>2024</year>

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

      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

      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>

            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.

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

      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.

        <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

        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.