<?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">
<refentry id="libreswan7">
  <refmeta>
    <refentrytitle>LIBRESWAN</refentrytitle>
    <manvolnum>7</manvolnum>
    <refmiscinfo class="date">21 February 2024</refmiscinfo>
    <refmiscinfo class="source">Libreswan</refmiscinfo>
    <refmiscinfo class="version">@@IPSECVERSION@@</refmiscinfo>
    <refmiscinfo class="manual">Miscellaneous</refmiscinfo>
  </refmeta>

  <refnamediv id="name">
    <refname>libreswan</refname>
    <refpurpose>
      Internet Key Exchange (IKE) Manager for IPsec
    </refpurpose>
  </refnamediv>

  <refsect1 id="description">

    <title>
      DESCRIPTION
    </title>

    <para>
      <application>Libreswan</application> is an Internet Key Exchange
      (IKE) manager.

      It consists of the Internet Key Exchange Daemon
      <command>pluto</command> (see
      <citerefentry> <refentrytitle>ipsec-pluto</refentrytitle>
      <manvolnum>8</manvolnum> </citerefentry>), the auxiliary command
      <command>ipsec</command> that provides a way to
      manipulate <command>pluto</command> (see
      <citerefentry> <refentrytitle>ipsec</refentrytitle>
      <manvolnum>8</manvolnum> </citerefentry>), and the configuration
      file <filename>ipsec.conf</filename> (see 
      <citerefentry> <refentrytitle>ipsec.conf</refentrytitle>
      <manvolnum>5</manvolnum> </citerefentry>).

      For authentication, <application>Libreswan</application> uses
      an <application>NSS</application> trust store containing
      <application>X.509</application> certificates and raw private keys, or a
      separate file containing preshared secrets (see <citerefentry>
      <refentrytitle>ipsec.secrets</refentrytitle>
      <manvolnum>5</manvolnum> </citerefentry>).
    </para>

    <para>
      <application>Libreswan</application> is used to negotiate and create
      shared Security Associations (SA) on a system that has IPsec,
      the secure IP protocol using the IKE protocol. The actual transmission
      of IPsec packets is the responsibility of the kernel.
      <application>Libreswan</application> can talk to various IPsec kernel
      implementations, such as the <application>Linux
      XFRM</application> and <application>BSD KAME</application> IPsec
      stacks.
    </para>

    <para>
      <application>Libreswan</application> implements IKE version 1 (RFC 2409)
      and IKE version 2 (RFC 7296). IKEv1 is considered Deprecated (RFC 9395) and
      it is strongly recommended to migrate all existing IKEv1 configurations to
      IKEv2.  Currently, to enable IKEv1 at all, the <emphasis>ipsec.conf</emphasis>
      section <emphasis>config setup</emphasis> must contain the line
      <emphasis>ikev1-policy=yes</emphasis>. The default is to not accept IKEv1 packets.
      Each connection configuration needs to specify to use IKEv1 as well using the
      keyword <emphasis>keyexchange=ikev1</emphasis>. Finally, libreswan must have
      been compiled with <emphasis>USE_IKEv1=true</emphasis>. While this is the
      currently the default, it is expected to change in the near future. Unless the
      peer does not support IKEv2, IKEv1 SHOULD NOT be used. Peers that do not support
      IKEv2 at this point are likely running on "end of life" software or hardware.
      The IKEv1 code is in maintenance mode and no new features will be considered.
    </para>

    <refsect2 id="ike_overview">
      <title>Internet Key Exchange Protocol version 2</title>

      <para>
	A <emphasis>Security Association</emphasis>
	(<emphasis>SA</emphasis>) is an agreement between two network
	nodes on how to process certain traffic between them. This
	processing may involve encapsulation, authentication,
	encryption, and compression.  The <application>Internet
	Key Exchange Protocol</application> (<application>IKE</application>)
	provides a standardized way to establish these associations dynamically.
      </para>

      <para>
	<application>IKE</application> can be deployed on a network
	node to negotiate Security Associations for that node.  These
	<application>IKE</application> implementations can only
	negotiate with other <application>IKE</application>
	implementations, so <application>IKE</application> must be on
	each node that is to be an endpoint of an
	<application>IKE</application>-negotiated Security
	Association.  No other nodes need to be running
	<application>IKE</application>.
      </para>

      <para>
	An <application>IKE</application> instance (i.e. an IKE
	implementation on a particular network node) communicates with
	other <application>IKE</application> instance using either UDP
	or TCP packets, so there must be a route between the nodes
	in each direction.
      </para>

      <para>
	The negotiation of Security Associations requires a number of
	choices that involve tradeoffs between security, convenience,
	trust, and efficiency. These are policy issues and are
	normally specified to the IKE instance by the system
	administrator.
      </para>

      <para>
	<application>IKE</application> deals with two kinds of
	Security Associations.  The first part of a negotiation
	between IKE instances is to build an IKE SA.  An IKE SA is
	used to establish an authenticated and private communication
	channel between the two IKE nodes. This communication channel
	is used to negotiate the actually Child SAs, which are the
	actual IPsec SAs. The IPsec SAs carry protected IP traffic
	between the systems.
      </para>

      <para>
	Negotiating an IKE SA (referred to as the The Initial
	Exchanges) consists of at least the IKE_SA_INIT exchange to
	establish a private channel, and the IKE_AUTH exchange to
	authenticate the channel. Extensions, such as EAP and
	INTERMEDIATE, may add further exchanges.
      </para>

      <para>
	Negotiating a Child SA requires a single CREATE_CHILD_SA
	exchange.  As an optimization, the first Child SA's
	negotiation may be piggybacked on the IKE_AUTH exchange.
      </para>

      <para>
	IKE negotiation can be initiated by any instance with any
	other instance.  If both can find an agreeable set of characteristics
	for a Security Association, and both recognize each others
	authenticity, they can set up a Security Association.  The
	standards do not specify what causes an IKE instance to
	initiate a negotiation.
      </para>

      <para>
	In summary, an IKE instance is prepared to automate the
	management of Security Associations in an IPsec environment,
	but a number of issues are considered policy and are left in
	the system administrator's hands.
      </para>

    </refsect2>

    <refsect2 id="libreswan">
      <title>Libreswan</title>

      <para>
	<application>Libreswan</application> implements the Internet
	Key Exchange (both versions 1 and 2).  It runs as a daemon
	(called <command>pluto</command>) on a network node.
	Currently, this network node must be a
	<application>Linux</application>,
	<application>NetBSD</application>,
	<application>FreeBSD</application>, or
	<application>OpenBSD</application> system.
      </para>

      <para>
	The policy for acceptable characteristics for Security
	Associations are specified using the configuration file
	<filename>ipsec.conf</filename> (see <citerefentry>
	<refentrytitle>ipsec.conf</refentrytitle>
        <manvolnum>5</manvolnum> </citerefentry>).
      </para>

      <para>
	<application>Libreswan</application> can be configured to
	authenticate its peer using shared secrets or using public and
	private keys (see <citerefentry>
	<refentrytitle>ipsec.conf</refentrytitle>
	<manvolnum>5</manvolnum> </citerefentry>).  Shared secrets are
	stored in the file <filename>ipsec.secrets</filename> (see
	<citerefentry> <refentrytitle>ipsec.secrets</refentrytitle>
	<manvolnum>5</manvolnum> </citerefentry>).  Public keys (for
	instance, X.509 certificates) are stored in either
	<application>Libreswan's</application>
	<application>NSS</application> trust store, obtained from the
	peer, or using DNS(SEC).  Corresponding Private keys are
	always stored in the <application>Libreswan's</application>
	<application>NSS</application> trust store.
      </para>

      <para>
	<application>Libreswan</application> initiates negotiation of a
	Security Association when:
      </para>

      <itemizedlist>
	<listitem>
	  <para>
	    it is manually prodded (see <citerefentry>
	    <refentrytitle>ipsec-up</refentrytitle>
            <manvolnum>8</manvolnum> </citerefentry>)
	  </para>
	</listitem>
	<listitem>
	  <para>
	    it is configured to negotiate on-demand and traffic
	    flow (see <citerefentry>
	    <refentrytitle>ipsec-route</refentrytitle>
            <manvolnum>8</manvolnum> </citerefentry>)
	  </para>
	</listitem>
	<listitem>
	  <para>
	    it is configured to negotiate from startup (see
	    <computeroutput>auto=up</computeroutput> in <citerefentry>
	    <refentrytitle>ipsec.conf</refentrytitle>
            <manvolnum>5</manvolnum> </citerefentry>)
	  </para>
	</listitem>
      </itemizedlist>

      <para>
	<command>Libreswan</command> implements IKE SAs itself.  After
	it has negotiated the characteristics for a Child SA (IPsec
	SA), it directs the <application>kernel</application> to
	install the association.  If necessary, it also invokes a
	script to adjust any firewall or routing rules (see
	<citerefentry> <refentrytitle>ipsec-updown</refentrytitle>
	<manvolnum>5</manvolnum> </citerefentry>).
      </para>

      <para>
	When <application>Libreswan</application> shuts down, it
	closes all Security Associations.
      </para>
    </refsect2>

    <refsect2 id="the_updown_command">
      <title>
	The <command>updown</command> command
      </title>

      <para>
	Whenever <application>libreswan</application> brings a
	connection up or down, it invokes the
	<command>updown</command> command.  This command is specified
	either using <filename>ipsec.conf</filename> configuration
	file option <computeroutput>leftupdown=</computeroutput> or
	the <command>ipsec whack</command> option
	<option>--updown</option> option.  This allows for customized
	control over routing and firewall manipulation.
      </para>

      <para>
	The <command>updown</command> script is invoked for five
	different operations.  The operation name, with
	<literal>-host</literal>, <literal>-client</literal> and
	<literal>-v6</literal>, appended is passed to the
	<command>updown</command> script using the environment
	variable <varname>PLUTO_VERB</varname> (see below) The
	operations, in the order they are normally invoked, are as
	follows:
      </para>

      <variablelist>
        <varlistentry>
          <term><literal>prepare</literal></term>
          <listitem>
            <para>
	      is run before bringing up a new connection if no other
	      connection with the same clients is up.  Generally, this
	      is useful for deleting a route that might have been set
	      up before <application>libreswan</application> was
	      started or perhaps by some agent not known to
	      <application>libreswan</application>.
	    </para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term><literal>route</literal></term>
          <listitem>
            <para>
	      is run when bringing up a connection for a new peer
	      client subnet (even if <literal>prepare</literal> was
	      run).  The command should install a suitable route.
	      Routing decisions are based only on the destination
	      (peer's client) subnet address, unlike kernel policy
	      (SPDs) which discriminate based on source too.
	    </para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term><literal>up</literal></term>
          <listitem>
            <para>
	      is run when first bringing up the IPsec tunnel for a
	      pair of client subnets.  This command should install
	      firewall rules as appropriate. It is generally a good
	      idea to allow IKE messages (UDP port 500) travel between
	      the hosts.
	    </para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term><literal>down</literal></term>
          <listitem>
            <para>
	      is run when bringing down the IPsec tunnel for a pair of
	      client subnets.  This command should delete firewall
	      rules as appropriate.  Note that there may remain some
	      inbound IPsec SAs with these client subnets.
	    </para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term><literal>unroute</literal></term>
          <listitem>
            <para>
	      is run when bringing down the last connection for a
	      particular peer client subnet.  It should undo what
	      <literal>route</literal> did.
	    </para>
          </listitem>
        </varlistentry>

      </variablelist>

      <para>
	The script is passed a large number of environment variables
	to specify what needs to be done:
      </para>

      <variablelist>

        <varlistentry>
          <term><envar>PLUTO_VERB</envar></term>
          <listitem>
            <para>
	      specifies the name of the operation to be performed
	      (<literal>prepare-host</literal>,
	      <literal>prepare-client</literal>,
	      <literal>prepare-host-v6</literal>,
	      <literal>prepare-client-v6</literal>;
	      <literal>route-host</literal>,
	      <literal>route-client</literal>,
	      <literal>route-host-v6</literal>,
	      <literal>route-client-v6</literal>;
	      <literal>up-host</literal>,
	      <literal>up-client</literal>,
	      <literal>up-host-v6</literal>,
	      <literal>up-client-v6</literal>;
	      <literal>down-host</literal>,
	      <literal>down-client</literal>,
	      <literal>down-host-v6</literal>,
	      <literal>down-client-v6</literal>;
	      <literal>unroute-host</literal>,
	      <literal>unroute-client</literal>,
	      <literal>unroute-host-v6</literal>,
	      <literal>unroute-client-v6</literal>).  If the address
	      family for security gateway to security gateway
	      communications is IPv6, then a suffix of -v6 is added to
	      the verb.</para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term><envar>PLUTO_CONNECTION</envar></term>
          <listitem>
            <para>
	      is the name of the connection for which we are
              routing.
	    </para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term><envar>PLUTO_NEXT_HOP</envar></term>
          <listitem>
            <para>
	      is the next hop to which packets bound for the peer must be
              sent.
	    </para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term><envar>PLUTO_INTERFACE</envar></term>
          <listitem>
            <para>
	      is the name of the ipsec interface to be used.
	    </para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term><envar>PLUTO_ME</envar></term>
          <listitem>
            <para>
	      is the IP address of our host.
	    </para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term><envar>PLUTO_MY_CLIENT</envar></term>
          <listitem>
            <para>
	      is the IP address / count of our client subnet. If the
	      client is just the host, this will be the host's own IP
	      address / max (where max is 32 for IPv4 and 128 for
	      IPv6).
	    </para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term><envar>PLUTO_MY_CLIENT_NET</envar></term>
          <listitem>
            <para>
	      is the IP address of our client net. If the client is
	      just the host, this will be the host's own IP
	      address.
	    </para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term><envar>PLUTO_MY_CLIENT_MASK</envar></term>
          <listitem>
            <para>
	      is the mask for our client net. If the client is just
	      the host, this will be 255.255.255.255.
	    </para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term><envar>PLUTO_PEER</envar></term>
          <listitem>
            <para>
	      is the IP address of our peer.
	    </para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term><envar>PLUTO_PEER_CLIENT</envar></term>
          <listitem>
            <para>
	      is the IP address / count of the peer's client
	      subnet. If the client is just the peer, this will be the
	      peer's own IP address / max (where max is 32 for IPv4
	      and 128 for IPv6).
	    </para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term><envar>PLUTO_PEER_CLIENT_NET</envar></term>
          <listitem>
            <para>
	      is the IP address of the peer's client net. If the
	      client is just the peer, this will be the peer's own IP
	      address.
	    </para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term><envar>PLUTO_PEER_CLIENT_MASK</envar></term>
          <listitem>
            <para>
	      is the mask for the peer's client net. If the client is
	      just the peer, this will be 255.255.255.255.
	    </para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term><envar>PLUTO_MY_PROTOCOL</envar></term>
          <listitem>
            <para>
	      lists the protocols allowed over this IPsec SA.
	    </para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term><envar>PLUTO_PEER_PROTOCOL</envar></term>
          <listitem>
            <para>
	      lists the protocols the peer allows over this IPsec SA.
	    </para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term><envar>PLUTO_MY_PORT</envar></term>
          <listitem>
            <para>
	      lists the ports allowed over this IPsec SA.
	    </para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term><envar>PLUTO_PEER_PORT</envar></term>
          <listitem>
            <para>
	      lists the ports the peer allows over this IPsec SA.
	    </para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term><envar>PLUTO_MY_ID</envar></term>
          <listitem>
            <para>
	      lists our id.
	    </para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term><envar>PLUTO_PEER_ID</envar></term>
          <listitem>
            <para>
	      lists our peer's id.
	    </para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term><envar>PLUTO_PEER_CA</envar></term>
          <listitem>
            <para>
	      lists the peer's CA.
	    </para>
          </listitem>
        </varlistentry>
      </variablelist>

      <para>
	All output sent by the script to stderr or stdout is
	logged. The script should return an exit status of 0 if and
	only if it succeeds.
      </para>

      <para>
	<command>pluto</command> waits for the script to finish and
	will not do any other processing while it is waiting. The
	script may assume that <command>pluto</command> will not
	change anything while the script runs. The script should avoid
	doing anything that takes much time and it should not issue
	any command that requires processing by
	<command>pluto</command>.  Either of these activities could be
	performed by a background subprocess of the script.
      </para>

    </refsect2>

  </refsect1>

<!--
  <refsect1>
    <title>
      EXAMPLES
    </title>
    <refsect2>
      <title>
      </title>
      <para>
      </para>
    </refsect2>
    </refsect1>
-->

  <refsect1>
    <title>
      OLD DESCRIPTION
    </title>

    <para>
      What follows is older documentation.  Patches to overhaul it
      welcome.
    </para>

    <refsect2 id="before_running_pluto">
      <title>Before Running Pluto</title>

      <para>
	<command>pluto</command> runs as a daemon with userid
	root. Before running it, a few things must be set up.
      </para>

      <para>
	<command>pluto</command> requires a working IPsec stack.
      </para>

      <para>
	<command>pluto</command> supports multiple public
	networks (that is, networks that are considered insecure and thus
	need to have their traffic encrypted or authenticated). It discovers
	the public interfaces to use by looking at all interfaces that are
	configured (the <option>--interface</option> option can be used to limit
	the interfaces considered). It does this only when
	<emphasis>whack</emphasis> tells it to --listen, so the interfaces must
	be configured by then. The <option>--listen</option> can be used to
	limit listening on only 1 IP address of a certain interface.
	<citerefentry><refentrytitle>ip</refentrytitle><manvolnum>8</manvolnum>
        </citerefentry> with the <option>addr</option> option will show the name
	and status of each network interface.
      </para>

      <para>
	<command>pluto</command> requires a database of
	preshared secrets and RSA private keys. This is described in the
	<citerefentry>
          <refentrytitle>ipsec.secrets</refentrytitle>
          <manvolnum>5</manvolnum>
        </citerefentry>. <command>pluto</command> is told of RSA
	public keys via <command>whack</command> commands. If the
	connection is Opportunistic, and no RSA public key is known,
	<emphasis>pluto</emphasis> will attempt to fetch RSA keys using the
	Domain Name System.
      </para>
    </refsect2>

    <refsect2 id="setting_up_netkey_for_pluto">
      <title>
	Setting up <emphasis>XFRM</emphasis> for <emphasis>pluto</emphasis>
      </title>

      <para>
	No special requirements are necessary to use XFRM - it ships
	with all modern versions of Linux 2.4 and later.
      </para>
    </refsect2>

    <refsect2 id="ipsecsecrets_file">
      <title>ipsec.secrets file</title>

      <para>
	A <command>pluto</command> daemon and another IKE
	daemon (for example, another instance of <emphasis>pluto</emphasis>)
	must convince each other that they are who
	they are supposed to be before any negotiation can succeed. This
	authentication is accomplished by using either secrets that have been
	shared beforehand (manually) or by using RSA signatures. There are other
	techniques, but they have not been implemented in
	<emphasis>pluto</emphasis>.
      </para>

      <para>
	The file <filename>@@IPSEC_SECRETS@@</filename> is used to
	keep preshared secret keys and XAUTH passwords. RSA private
	keys, X.509 certificates, CRLs, OCSP and smartcards are
	handled via NSS. For debugging, there is an argument to the
	<emphasis>pluto</emphasis> command to use a
	different file. This file is described in
	<citerefentry>
	  <refentrytitle>ipsec.secrets</refentrytitle><manvolnum>5</manvolnum>
	</citerefentry>.
      </para>
    </refsect2>

    <refsect2 id="running_pluto">
      <title>Running Pluto</title>

      <para>
	To fire up the daemon, just type <emphasis>pluto</emphasis>
	(be sure to be running as the superuser). The
	default IKE port number is 500, the UDP port assigned by IANA for IKE
	Daemons. <command>pluto</command> must be run by the
	superuser to be able to use the UDP 500 port. If pluto is told to enable
	NAT-Traversal, then UDP port 4500 is also taken by pluto to listen
	on.
      </para>

      <para>
	Pluto supports different IPstacks on different operating
	systems.  This can be configured using one of the options
	<option>--use-netkey</option> (Linux),
	<option>--use-bsdkame</option> (BSD).  On startup, pluto might
	also read the <option>protostack=</option> option to select
	the IPsec stack to use if <option>--config
	/etc/ipsec.conf</option> is given as argument to pluto.  If
	both <option>--use-XXX</option> and <option>--config
	/etc/ipsec.conf</option> are specified, the last command line
	argument specified takes precedence.
      </para>

      <para>
	Pluto supports RFC 3947 NAT-Traversal.  The allowed range
	behind the NAT routers is submitted using the
	<option>--virtual-private</option> option. See <citerefentry>
        <refentrytitle>ipsec.conf</refentrytitle>
        <manvolnum>5</manvolnum>
        </citerefentry> for the syntax. The option
	<option>--force-keepalive</option> forces the sending of the
	<emphasis>keep-alive packets</emphasis>, which are send to prevent the
	NAT router from closing its port when there is not enough traffic on the
	IPsec connection. The <option>--keep-alive</option> sets the delay (in
	seconds) of these keep-alive packets. The newer NAT-T standards support
	<emphasis>port floating</emphasis>, and Libreswan enables this
	per default.
      </para>

      <para>
	Pluto supports the use of X.509 certificates and sends certificates
	when needed. Pluto uses NSS for all X.509 related data, including
	CAcerts, certs, CRLs and private keys. The <emphasis>Certificate
	Revocation Lists</emphasis>
	can also be retrieved from an URL. The option
	<option>--crlcheckinterval</option> sets the time between checking
	for CRL expiration and issuing new fetch commands.
	Pluto logs a warning if no valid CRL was loaded or obtained for a
	connection. If <option>--crl-strict</option> is given, the
	connection will be rejected until a valid CRL has been loaded.
      </para>

      <para>
	Pluto can also use helper children to off-load cryptographic
	operations. This behavior can be fine tuned using the
	<option>--nhelpers</option>. Pluto will start
	<emphasis>(n-1)</emphasis> of them, where <emphasis>n</emphasis>
	is the number of CPU's you have (including
	hypherthreaded CPU's). A value of <emphasis>0</emphasis>
	forces pluto to do all operations in the main process. A value of
	<emphasis>-1</emphasis> tells pluto to perform the above
	calculation. Any other value forces the number to that amount.
      </para>

      <para>
	Pluto uses the NSS crypto library as its random source. Some
	government Three Letter Agency requires that pluto reads 440 bits
	from /dev/random and feed this into the NSS RNG before drawing
	random from the NSS library, despite the NSS library itself
	already seeding its internal state. As this process can block
	pluto for an extended time, the default is to not perform this
	redundant seeding. The <option>--seedbits</option>
	option can be used to specify the number of bits that will be
	pulled from /dev/random and seeded into the NSS RNG.  This can
	also be accomplished by specifying seedbits in the "config setup"
	section of ipsec.conf. This option should not be used by most people.
      </para>

      <para>
	<command>pluto</command> attempts to create a lockfile
	with the name <filename>@@RUNDIR@@/pluto.pid</filename>. If the
	lockfile cannot be created, <command>pluto</command> exits -
	this prevents multiple <command>pluto</command>s from
	competing Any "leftover" lockfile must be removed before
	<emphasis>pluto</emphasis> will run. <emphasis>pluto</emphasis>
	writes its PID into this file so that scripts
	can find it. This lock will not function properly if it is on an NFS
	volume (but sharing locks on multiple machines doesn't make sense
	anyway).
      </para>

      <para>
	<command>pluto</command> then forks and the parent
	exits. This is the conventional "daemon fork". It can make debugging
	awkward, so there is an option to suppress this fork. In certain
	configurations, pluto might also launch helper programs to assist with
	DNS queries or to offload cryptographic operations.
      </para>

      <para>
	All logging, including diagnostics, is sent to <citerefentry>
	<refentrytitle>syslog</refentrytitle> <manvolnum>3</manvolnum>
	</citerefentry> with facility=authpriv; it decides where to
	put these messages (possibly in /var/log/secure or
	/var/log/auth.log). Since this too can make debugging awkward,
	the option <option>--stderrlog</option> is used to steer
	logging to stderr.
      </para>

      <para>
	Alternatively, <option>--logfile</option> can be used to send all
	logging information to a specific file.
      </para>

      <para>
	Once <command>pluto</command> is started, it waits for
	requests from <command>whack</command>.
      </para>
    </refsect2>

    <refsect2 id="plutos_internal_state">
      <title>Pluto's Internal State</title>

      <para>
	To understand how to use <command>pluto</command>, it
	is helpful to understand a little about its internal state. Furthermore,
	the terminology is needed to decipher some of the diagnostic
	messages.
      </para>

      <para>
	Pluto supports <emphasis>food groups</emphasis> for Opportunistic
	IPsec. The policies for these are located in /etc/ipsec.d/policies,
	or another directory as specified by <option>--ipsecdir</option>.
      </para>

      <para>
	Pluto supports X.509 Certificates.  All certificate handling
	is done using the NSS library and all certificate material is
	stored in an NSS database in
	<filename>@@IPSEC_NSSDIR@@</filename> or another directory as
	specified by <option>--nssdir</option>.
      </para>

      <para>
	Pluto may core dump. It will normally do so into the current
	working directory. You can specify the --coredir option for pluto, or
	specify the dumpdir= option in ipsec.conf.
      </para>

      <para>
	If you are investigating a potential memory leak in pluto,
	start pluto with the --leak-detective option.  Before the leak
	causes the system or pluto to die, shut down pluto in the regular
	way. pluto will display a list of leaks it has detected.
      </para>

      <para>
	If you are investigating a potential use-after-free or
	double-free in pluto, first build pluto with USE_EFENCE=true
	and then start pluto with --efence-protect.  See
	<citerefentry> <refentrytitle>efence</refentrytitle>
	<manvolnum>2</manvolnum> </citerefentry> and EF_PROTECT_BELOW
	and EF_PROTECT_FREE.
      </para>

      <para>
	The <emphasis>(potential) connection</emphasis> database
	describes attributes of a connection. These include the IP addresses of
	the hosts and client subnets and the security characteristics desired.
	<command>pluto</command> requires this information (simply
	called a connection) before it can respond to a request to build an SA.
	Each connection is given a name when it is created, and all references
	are made using this name.
      </para>

      <para>
	During the IKE exchange to build an SA, the information about the
	negotiation is represented in a <emphasis>state
	object</emphasis>. Each state object reflects how far the negotiation
	has reached. Once the negotiation is complete and the SA established,
	the state object remains to represent the SA. When the SA is terminated,
	the state object is discarded. Each State object is given a serial
	number and this is used to refer to the state objects in logged
	messages.
      </para>

      <para>
	Each state object corresponds to a connection and can be thought
	of as an instantiation of that connection. At any particular time, there
	may be any number of state objects corresponding to a particular
	connection. Often there is one representing an ISAKMP SA and another
	representing an IPsec SA.
      </para>

      <para>
	<emphasis>XFRM</emphasis> requires no special routing.
      </para>

      <para>
	Each connection may be routed, and must be while it has an IPsec
	SA. The connection specifies the characteristics of the route: the
	interface on this machine, the "gateway" (the nexthop), and the peer's
	client subnet. Two connections may not be simultaneously routed if they
	are for the same peer's client subnet but use different interfaces or
	gateways (<command>pluto</command>'s logic does not reflect
	any advanced routing capabilities).
      </para>

      <para>
	When <command>pluto</command> needs to install a route
	for a connection, it must make sure that no conflicting route is in use.
	If another connection has a conflicting route, that route will be taken
	down, as long as there is no IPsec SA instantiating that connection. If
	there is such an IPsec SA, the attempt to install a route will
	fail.
      </para>

      <para>
	There is an exception. If <command>pluto</command>, as
	Responder, needs to install a route to a fixed client subnet for a
	connection, and there is already a conflicting route, then the SAs using
	the route are deleted to make room for the new SAs. The rationale is
	that the new connection is probably more current. The need for this
	usually is a product of Road Warrior connections (these are explained
	later; they cannot be used to initiate).
      </para>

      <para>
	When <command>pluto</command> needs to install an
	eroute for an IPsec SA (for a state object), first the state object's
	connection must be routed (if this cannot be done, the eroute and SA
	will not be installed). If a conflicting eroute is already in place for
	another connection, the eroute and SA will not be installed (but note
	that the routing exception mentioned above may have already deleted
	potentially conflicting SAs). If another IPsec SA for the same
	connection already has an eroute, all its outgoing traffic is taken over
	by the new eroute. The incoming traffic will still be processed. This
	characteristic is exploited during rekeying.
      </para>
    </refsect2>

    <refsect2 id="examples">
      <title>Old Examples</title>

      <para>It would be normal to start <command>pluto</command>
      in one of the system initialization scripts. It needs to be run by the
      superuser. Generally, no arguments are needed. To run in manually, the
      superuser can simply type</para>

      <para><command>ipsec pluto</command></para>

      <para>The command will immediately return, but a <emphasis>pluto</emphasis>
      process will be left running, waiting for
      requests from <command>whack</command> or a peer.</para>

      <para>Using <command>whack</command>, several potential
      connections would be described:</para>

      <!-- .na -->

      <para>ipsec whack --name silly
      --host 127.0.0.1 --to --host 127.0.0.2 --ikelifetime 900
      --ipseclifetime 800 --keyingtries 3</para>

      <!-- .ad -->

      <para>Since this silly connection description specifies neither
      encryption, authentication, nor tunneling, it could only be used to
      establish an ISAKMP SA.</para>

      <!-- .na -->

      <para>ipsec whack --name conn_name
      --host 10.0.0.1 --client 10.0.1.0/24 --to --host 10.0.0.2
      --client 10.0.2.0/24 --encrypt</para>

      <!-- .ad -->

      <para>This is something that must be done on both sides. If the other
      side is <command>pluto</command>, the same <emphasis>whack</emphasis>
      command could be used on it (the command
      syntax is designed to not distinguish which end is ours).</para>

      <para>Now that the connections are specified, <emphasis>pluto</emphasis>
      is ready to handle requests and replies via
      the public interfaces. We must tell it to discover those interfaces and
      start accepting messages from peers:</para>

      <para>   ipsec whack --listen</para>

      <para>If we don't immediately wish to bring up a secure connection
      between the two clients, we might wish to prevent insecure traffic. The
      routing form asks <command>pluto</command> to cause the
      packets sent from our client to the peer's client to be routed through
      the ipsec0 device; if there is no SA, they will be discarded:</para>

      <para>   ipsec whack --route conn_name</para>

      <para>Finally, we are ready to get <command>pluto</command>
      to initiate negotiation for an IPsec SA (and implicitly, an ISAKMP
      SA):</para>

      <para>   ipsec whack
      --initiate --name conn_name</para>

      <para>A small log of interesting events will appear on standard output
      (other logging is sent to syslog).</para>

      <para><command>whack</command> can also be used to terminate
      <command>pluto</command> cleanly, tearing down all SAs that
      it has negotiated.</para>

      <para>   ipsec whack --shutdown</para>

      <para>Notification of any IPSEC SA deletion, but not ISAKMP SA deletion
      is sent to the peer. Unfortunately, such Notification is not reliable.
      Furthermore, <command>pluto</command> itself ignores
      Notifications.</para>
    </refsect2>

    <refsect2 id="xauth">
      <title>XAUTH</title>

      <para>If <command>pluto</command> needs additional
      authentication, such as defined by the XAUTH specifications, then it may
      ask <command>whack</command> to prompt the operator for
      username or passwords. Typically, these will be entered interactively. A
      GUI that wraps around <command>whack</command> may look for
      the 041 (username) or 040 (password) prompts, and display them to the
      user.</para>

      <para>
	For testing purposes, the options
	<option>--xauthuser</option>
	<replaceable>user</replaceable>
	<option>--xauthpass</option>
	<replaceable>pass</replaceable> may be be given prior to the
	<option>--initiate</option> to provide responses to the
	username and password prompts.
      </para>
    </refsect2>

    <refsect2 id="rekeying">
      <title>Rekeying</title>

      <para>When an SA that was initiated by <emphasis>pluto</emphasis>
      has only a bit of lifetime left, <emphasis>pluto</emphasis> will
      initiate the creation of a new SA. This
      applies to ISAKMP and IPsec SAs. The rekeying will be initiated when the
      SA's remaining lifetime is less than the rekeymargin plus a random
      percentage, between 0 and rekeyfuzz, of the rekeymargin.</para>

      <para>Similarly, when an SA that was initiated by the peer has only a
      bit of lifetime left, <command>pluto</command> will try to
      initiate the creation of a replacement. To give preference to the
      initiator, this rekeying will only be initiated when the SA's remaining
      lifetime is half of rekeymargin. If rekeying is done by the responder,
      the roles will be reversed: the responder for the old SA will be the
      initiator for the replacement. The former initiator might also initiate
      rekeying, so there may be redundant SAs created. To avoid these
      complications, make sure that rekeymargin is generous.</para>

      <para>One risk of having the former responder initiate is that perhaps
      none of its proposals is acceptable to the former initiator (they have
      not been used in a successful negotiation). To reduce the chances of
      this happening, and to prevent loss of security, the policy settings are
      taken from the old SA (this is the case even if the former initiator is
      initiating). These may be stricter than those of the connection.</para>

      <para><command>pluto</command> will not rekey an SA if that
      SA is not the most recent of its type (IPsec or ISAKMP) for its
      potential connection. This avoids creating redundant SAs.</para>

      <para>The random component in the rekeying time (rekeyfuzz) is intended
      to make certain pathological patterns of rekeying unstable. If both
      sides decide to rekey at the same time, twice as many SAs as necessary
      are created. This could become a stable pattern without the
      randomness.</para>

      <para>Another more important case occurs when a security gateway has SAs
      with many other security gateways. Each of these connections might need
      to be rekeyed at the same time. This would cause a high peek requirement
      for resources (network bandwidth, CPU time, entropy for random numbers).
      The rekeyfuzz can be used to stagger the rekeying times.</para>

      <para>Once a new set of SAs has been negotiated, <emphasis>pluto</emphasis>
      will never send traffic on a superseded one.
      Traffic will be accepted on an old SA until it expires.</para>
    </refsect2>

    <refsect2 id="selecting_a_connection_when_responding_r">
      <title>Selecting a Connection When Responding: Road Warrior
      Support</title>

      <para>When <command>pluto</command> receives an initial Main
      Mode message, it needs to decide which connection this message is for.
      It picks based solely on the source and destination IP addresses of the
      message. There might be several connections with suitable IP addresses,
      in which case one of them is arbitrarily chosen. (The ISAKMP SA proposal
      contained in the message could be taken into account, but it is
      not.)</para>

      <para>The ISAKMP SA is negotiated before the parties pass further
      identifying information, so all ISAKMP SA characteristics specified in
      the connection description should be the same for every connection with
      the same two host IP addresses. At the moment, the only characteristic
      that might differ is authentication method.</para>

      <para>Up to this point, all configuring has presumed that the IP
      addresses are known to all parties ahead of time. This will not work
      when either end is mobile (or assigned a dynamic IP address for other
      reasons). We call this situation "Road Warrior". It is fairly tricky and
      has some important limitations, most of which are features of the IKE
      protocol.</para>

      <para>Only the initiator may be mobile: the initiator may have an IP
      number unknown to the responder. When the responder doesn't recognize
      the IP address on the first Main Mode packet, it looks for a connection
      with itself as one end and <emphasis>%any</emphasis> as the
      other. If it cannot find one, it refuses to negotiate. If it does find
      one, it creates a temporary connection that is a duplicate except with
      the <emphasis>%any</emphasis> replaced by the source IP
      address from the packet; if there was no identity specified for the
      peer, the new IP address will be used.</para>

      <para>When <command>pluto</command> is using one of these
      temporary connections and needs to find the preshared secret or RSA
      private key in <emphasis>ipsec.secrets</emphasis>, and the
      connection specified no identity for the peer, <emphasis>%any</emphasis>
      is used as its identity. After all, the real
      IP address was apparently unknown to the configuration, so it is
      unreasonable to require that it be used in this table.</para>

      <para>Part way into the Phase 1 (Main Mode) negotiation using one of
      these temporary connection descriptions, <emphasis>pluto</emphasis>
      will receive an Identity Payload. At this
      point, <command>pluto</command> checks for a more
      appropriate connection, one with an identity for the peer that matches
      the payload and would use the same keys as so far used for
      authentication. If it finds one, it will switch to using this better
      connection (or a temporary one derived from this, if it has <emphasis>%any</emphasis>
      for the peer's IP address). It may even turn
      out that no connection matches the newly discovered identity, including
      the current connection; if so, <command>pluto</command>
      terminates negotiation.</para>

      <para>Unfortunately, if preshared secret authentication is being used,
      the Identity Payload is encrypted using this secret, so the secret must
      be selected by the responder without knowing this payload. This limits
      there to being at most one preshared secret for all Road Warrior systems
      connecting to a host. RSA Signature authentication does not require
      that the responder knows how to select the initiator's public key until
      after the initiator's Identity Payload is decoded (using the responder's
      private key, so that must be preselected).</para>

      <para>When <command>pluto</command> is responding to a Quick
      Mode negotiation via one of these temporary connection descriptions, it
      may well find that the subnets specified by the initiator don't match
      those in the temporary connection description. If so, it will look for a
      connection with matching subnets, its own host address, a peer address
      of <emphasis>%any</emphasis> and matching identities. If it
      finds one, a new temporary connection is derived from this one and used
      for the Quick Mode negotiation of IPsec SAs. If it does not find one,
      <command>pluto</command> terminates negotiation.</para>

      <para>Be sure to specify an appropriate nexthop for the responder to
      send a message to the initiator: <command>pluto</command>
      has no way of guessing it (if forwarding isn't required, use an explicit
      <emphasis>%direct</emphasis> as the nexthop and the IP address
      of the initiator will be filled in; the obsolete notation
      <literal>0.0.0.0</literal> is still accepted).</para>

      <para><command>pluto</command> has no special provision for
      the initiator side. The current (possibly dynamic) IP address and
      nexthop must be used in defining connections. These must be properly
      configured each time the initiator's IP address changes.
      <emphasis>pluto</emphasis> has no mechanism to do this
      automatically.</para>

      <para>Although we call this Road Warrior Support, it could also be used
      to support encrypted connections with anonymous initiators. The
      responder's organization could announce the preshared secret that would
      be used with unrecognized initiators and let anyone connect. Of course
      the initiator's identity would not be authenticated.</para>

      <para>If any Road Warrior connections are supported, <emphasis>pluto</emphasis>
      cannot reject an exchange initiated by an
      unknown host until it has determined that the secret is not shared or
      the signature is invalid. This must await the third Main Mode message
      from the initiator. If no Road Warrior connection is supported, the
      first message from an unknown source would be rejected. This has
      implications for ease of debugging configurations and for denial of
      service attacks.</para>

      <para>Although a Road Warrior connection must be initiated by the mobile
      side, the other side can and will rekey using the temporary connection
      it has created. If the Road Warrior wishes to be able to disconnect, it
      is probably wise to set <option>--keyingtries</option> to 1 in the
      connection on the non-mobile side to prevent it trying to rekey the
      connection. Unfortunately, there is no mechanism to unroute the
      connection automatically.</para>
    </refsect2>

    <refsect2 id="debugging">
      <title>Debugging</title>

      <para>
	<command>pluto</command> accepts several optional
	arguments, useful mostly for debugging. Except for
	<option>--interface</option>, each should appear at most
	once.
      </para>

      <variablelist>

        <varlistentry>
          <term>
	    <option>--interface <replaceable>interfacename</replaceable></option>
	  </term>
          <listitem>
            <para>
	      Specifies that the named real public network interface
	      should be considered. The interface name specified
	      should not be <command>ipsec</command><emphasis>N</emphasis>.
	      If the option doesn't appear, all interfaces are considered.
	      To specify several interfaces, use the option once for each. One use of
	      this option is to specify which interface should be used
	      when two or more share the same IP address.
	    </para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term>
	    <option>--ikeport <replaceable>port-number</replaceable></option>
	  </term>
          <listitem>
            <para>
	      Changes the UDP port that <emphasis>pluto</emphasis> will use
	      (default, specified by IANA: 500).
	    </para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term>
	    <option>--rundir <replaceable>@@RUNDIR@@</replaceable></option>
	  </term>
          <listitem>
            <para>
	      Directory to store control socket, <emphasis>pluto.ctl</emphasis>,
	      the socket through which <command>whack</command> communicates
	      with <command>pluto</command>. <emphasis>pluto.pid</emphasis>
	      is the lockfile to prevent multiple <command>pluto</command>
	      instances. The default is <filename>@@RUNDIR@@</filename>).
	    </para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term>
	    <option>--secretsfile <replaceable>file</replaceable></option>
	  </term>
          <listitem>
            <para>
	      Specifies the file for authentication secrets (default:
	      <filename>@@IPSEC_SECRETS@@</filename>). This name is
	      subject to "globbing" as in <citerefentry>
	      <refentrytitle>sh</refentrytitle>
	      <manvolnum>1</manvolnum> </citerefentry>, so every file
	      with a matching name is processed. Quoting is generally
	      needed to prevent the shell from doing the globbing.
	    </para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term>
	    <option>--nofork</option>
	  </term>
          <listitem>
            <para>
	      Disable "daemon fork" (default is to fork). In addition,
	      after the lock file and control socket are created,
	      print the line "Pluto initialized" to standard
	      out.
	    </para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term>
	    <option>--uniqueids</option>
	  </term>
          <listitem>
            <para>
	      If this option has been selected, whenever a new ISAKMP
	      SA is established, any connection with the same Peer ID
	      but a different Peer IP address is unoriented (causing
	      all its SAs to be deleted). This helps clean up dangling
	      SAs when a connection is lost and then regained at
	      another IP address.
	    </para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term>
	    <option>--force-busy</option>
	  </term>
          <listitem>
            <para>
	      If this option has been selected, pluto will be forced
	      to be "busy". In this state, which happens when there is
	      a Denial of Service attack, will force pluto to use
	      cookies before accepting new incoming IKE
	      packets. Cookies are send and required in ikev1
	      Aggressive Mode and in ikev2.  This option is mostly
	      used for testing purposes, but can be selected by
	      paranoid administrators as well.
	    </para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term>
	    <option>--stderrlog</option>
	  </term>
          <listitem>
            <para>
	      Log goes to standard out (default is to use
	      <citerefentry> <refentrytitle>syslogd</refentrytitle>
	      <manvolnum>8</manvolnum> </citerefentry>).
	    </para>
          </listitem>
        </varlistentry>
      </variablelist>

      <para>
	<command>pluto</command> is willing to produce a
	prodigious amount of debugging information.  There are several
	classes of debugging output, and <emphasis>pluto</emphasis>
	may be directed to produce a
	selection of them.  All lines of debugging output are prefixed
	with "|" to distinguish them from normal diagnostic
	messages.
      </para>

      <para>
	When <command>pluto</command> is invoked, it may
	be given arguments to specify which debug classes to output.
	The current options are:
      </para>

      <variablelist>

        <varlistentry>
          <term>
	    <option>--debug help</option> (whack only)
	  </term>
          <listitem>
            <para>
	      List the debugging classes recognised by <emphasis>pluto</emphasis>.
	    </para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term>
	    <option>--debug none</option>
	  </term>
          <listitem>
            <para>
	      Disable logging for all debugging classes.
	    </para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term>
	    <option>--debug base</option>
	  </term>
          <listitem>
            <para>
	      Enable debug-logging.
	    </para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term>
	    <option>--debug cpu-usage</option>
	  </term>
          <listitem>
            <para>
	      Enable cpu-usage logging.
	    </para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term>
	    <option>--debug <replaceable>class</replaceable></option>
	  </term>
          <term>
	    <option>--no-debug <replaceable>class</replaceable></option>
	  </term>
          <term>
	    <option>--debug no-<replaceable>class</replaceable></option>
	  </term>
          <listitem>
            <para>
	      Enable (disable) logging of the specified debugging
	      <replaceable>class</replaceable> (<option>--debug
	      help</option> lists debugging classes supported by this
	      version of <command>pluto</command>).
	    </para>
          </listitem>
        </varlistentry>

      </variablelist>

      <para>
	The debug form of the <command>whack</command>
	command will change the selection in a running <emphasis>pluto</emphasis>.
	If a connection name is specified,
	the flags are added whenever <emphasis>pluto</emphasis>
	has identified that it is dealing
	with that connection.  Unfortunately, this is often part way
	into the operation being observed.
      </para>

      <para>
	For example, to start <command>pluto</command>
	with both <emphasis>base</emphasis> and
	<emphasis>cpu-usage</emphasis> debug-logging enabled:
      </para>

      <para>
	<command>ipsec pluto --debug base --debug cpu-usage</command>
      </para>

      <para>
	To later change this <command>pluto</command> to
	disable <emphasis>base</emphasis> debug-logging use either:
      </para>

      <para>
	<command>ipsec whack --no-debug base</command>
      </para>

      <para>
	or:
      </para>

      <para>
	<command>ipsec whack --debug none --debug cpu-usage</command>
      </para>

    </refsect2>

    <refsect2 id="impairing">
      <title>Impairing</title>

      <para>
	<command>pluto</command> and <emphasis>whack</emphasis>
	accept several optional arguments
	that alter (impair) correct behaviour.
      </para>
      <para>
	These options are solely intended for use by developers when
	testing <command>pluto</command>.
      </para>

      <variablelist>

        <varlistentry>
          <term>
	    <option>--impair help</option> (whack only)
	  </term>
          <listitem>
            <para>
	      List all the behaviours that can be altered (impaired).
	    </para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term>
	    <option>--impair list</option> (whack only)
	  </term>
          <listitem>
            <para>
	      List all the behaviours that are currently altered
	      (impaired).
	    </para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term>
	    <option>--impair none</option>
	  </term>
          <listitem>
            <para>
	      Disable all altered (impaired) behaviours.
	    </para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term>
	    <option>--impair <replaceable>behaviour</replaceable></option>
	  </term>
          <term>
	    <option>--impair <replaceable>behaviour</replaceable>:<replaceable>how</replaceable></option>
	  </term>
          <term>
	    <option>--no-impair <replaceable>behaviour</replaceable></option>
	  </term>
          <listitem>
            <para>
	      Alter (impair) <command>pluto</command>
	      inducing the (possibly erroneous)
	      <replaceable>behaviour</replaceable>.
	    </para>
          </listitem>
        </varlistentry>

      </variablelist>

    </refsect2>

    <refsect2 id="plutos_behaviour_when_things_go_wrong">
      <title>Pluto's Behaviour When Things Go Wrong</title>

      <para>
	When <command>pluto</command> doesn't understand or
	accept a message, it just ignores the message. It is not yet capable of
	communicating the problem to the other IKE daemon (in the future it
	might use Notifications to accomplish this in many cases). It does log a
	diagnostic.
      </para>

      <para>
	When <command>pluto</command> gets no response from a
	message, it resends the same message (a message will be sent at most
	three times). This is appropriate: UDP is unreliable.
      </para>

      <para>
	When pluto gets a message that it has already seen, there are many
	cases when it notices and discards it. This too is appropriate for
	UDP.
      </para>

      <para>
	Combine these three rules, and you can explain many apparently
	mysterious behaviours. In a <command>pluto</command> log,
	retrying isn't usually the interesting event. The critical thing is
	either earlier (<command>pluto</command> got a message that
	it didn't like and so ignored, so it was still awaiting an acceptable
	message and got impatient) or on the other system (<emphasis>pluto</emphasis>
	didn't send a reply because it wasn't happy
	with the previous message).
      </para>
    </refsect2>

    <refsect2 id="notes">
      <title>Notes</title>

      <para>
	Each IPsec SA is assigned an SPI, a 32-bit number used to refer to
	the SA. The IKE protocol lets the destination of the SA choose the SPI.
	The range 0 to 0xFF is reserved for IANA. <emphasis>Pluto</emphasis>
	also avoids choosing an SPI in the range
	0x100 to 0xFFF, leaving these SPIs free for manual keying. Remember that
	the peer, if not <command>pluto</command>, may well chose
	SPIs in this range.
      </para>
    </refsect2>

    <refsect2 id="policies">
      <title>Policies</title>

      <para>
	This catalogue of policies may be of use when trying to configure
	<command>pluto</command> and another IKE implementation to
	interoperate.
      </para>

      <para>
	In Phase 1, only Main Mode is supported. We are not sure that
	Aggressive Mode is secure. For one thing, it does not support identity
	protection. It may allow more severe Denial Of Service attacks.
      </para>

      <para>
	No Informational Exchanges are supported. These are optional and
	since their delivery is not assured, they must not matter. It is the
	case that some IKE implementations won't interoperate without
	Informational Exchanges, but we feel they are broken.
      </para>

      <para>
	No Informational Payloads are supported. These are optional, but
	useful. It is of concern that these payloads are not authenticated in
	Phase 1, nor in those Phase 2 messages authenticated with
	HASH(3).
      </para>

      <variablelist>
        <varlistentry>
          <term>•</term>

          <listitem>
            <para>Diffie Hellman Group MODP 1536 (5) is
            supported. Groups MODP768 and MODP 1024 (1 and 2) are
	    not supported because those are too weak.</para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term>•</term>

          <listitem>
            <para>Host authentication can be done by RSA Signatures or
            Pre-Shared Secrets.</para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term>•</term>

          <listitem>
            <para>
	      TODO! This information is outdated.
	      3DES CBC (Cypher Block Chaining mode) is the only encryption
              supported, both for ISAKMP SAs and IPSEC SAs.
	    </para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term>•</term>

          <listitem>
            <para>MD5 and SHA1 hashing are supported for packet authentication
            in both kinds of SAs.</para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term>•</term>

          <listitem>
            <para>The ESP, AH, or AH plus ESP are supported. If, and only if,
            AH and ESP are combined, the ESP need not have its own
            authentication component. The selection is controlled by the
            --encrypt and --authenticate flags.</para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term>•</term>

          <listitem>
            <para>Each of these may be combined with IPCOMP Deflate
            compression, but only if the potential connection specifies
            compression.</para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term>•</term>

          <listitem>
            <para>The IPSEC SAs may be tunnel or transport mode, where
            appropriate. The --tunnel flag controls this when
	    <emphasis>pluto</emphasis> is initiating.</para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term>•</term>

          <listitem>
            <para>When responding to an ISAKMP SA proposal, the maximum
            acceptable lifetime is eight hours. The default is one hour. There
            is no minimum. The --ikelifetime flag controls this when
	    <emphasis>pluto</emphasis> is initiating.</para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term>•</term>

          <listitem>
            <para>When responding to an IPSEC SA proposal, the maximum
            acceptable lifetime is one day. The default is eight hours. There
            is no minimum. The --ipseclifetime flag controls this when
            <command>pluto</command> is initiating.</para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term>•</term>

          <listitem>
            <para>PFS is acceptable, and will be proposed if the --pfs flag
            was specified. The DH group proposed will be the same as
            negotiated for Phase 1.</para>
          </listitem>
        </varlistentry>
      </variablelist>
    </refsect2>
  </refsect1>

  <refsect1 id="signals">
    <title>SIGNALS</title>

    <para><command>pluto</command> responds to
    <constant>SIGHUP</constant> by issuing a suggestion that
    ``<emphasis>whack</emphasis> --listen'' might have been intended.</para>

    <para><command>pluto</command> exits when it receives
    <constant>SIGTERM</constant>.</para>
  </refsect1>

  <refsect1 id="exit_status">
    <title>EXIT STATUS</title>

    <para><command>pluto</command> normally forks a daemon
    process, so the exit status is normally a very preliminary result.</para>

    <variablelist>
      <varlistentry>
        <term>0</term>

        <listitem>
          <para>means that all is OK so far.</para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term>1</term>

        <listitem>
          <para>means that something was wrong.</para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term>10</term>

        <listitem>
          <para>means that the lock file already exists.</para>
        </listitem>
      </varlistentry>
    </variablelist>

    <para>If <command>whack</command> detects a problem, it will
    return an exit status of 1. If it received progress messages from
    <command>pluto</command>, it returns as status the value of
    the numeric prefix from the last such message that was not a message sent
    to syslog or a comment (but the prefix for success is treated as 0).
    Otherwise, the exit status is 0.</para>
  </refsect1>

  <refsect1 id="files">
    <title>FILES</title>

    <para><filename>@@RUNDIR@@/pluto.pid</filename>
    <filename>@@RUNDIR@@/pluto.ctl</filename>
    <filename>@@IPSEC_SECRETS@@</filename>
    <filename>/dev/urandom</filename></para>
  </refsect1>

  <refsect1 id="environment">
    <title>ENVIRONMENT</title>

    <para>pluto does not use any environment variables</para>
  </refsect1>

  <refsect1 id="see_also">
    <title>SEE ALSO</title>

    <para>The rest of the Libreswan distribution, in particular
    <citerefentry><refentrytitle>ipsec</refentrytitle><manvolnum>8</manvolnum></citerefentry>.</para>

    <para>
      <citerefentry>
        <refentrytitle>ipsec</refentrytitle>
        <manvolnum>8</manvolnum>
      </citerefentry>
      is designed to make using <command>pluto</command>
      more pleasant. Use it!
    </para>

    <para>
      <citerefentry>
        <refentrytitle>ipsec.secrets</refentrytitle>
        <manvolnum>5</manvolnum>
      </citerefentry>
      describes the format of the secrets file.
    </para>

    <para>
      For more information on IPsec, the mailing list, and the relevant
      documents, see:
    </para>

    <para>
      <emphasis><ulink url="https://datatracker.ietf.org/wg/ipsecme/charter/">https://datatracker.ietf.org/wg/ipsecme/charter/</ulink></emphasis>
    </para>

    <para>
      At the time of writing, the latest IETF IKE RFC is:
    </para>

    <para>
      RFC 7296 Internet Key Exchange Protocol Version 2 (IKEv2)
    </para>

    <para>
      The Libreswan web site <emphasis><ulink url="https://libreswan.org">https://libreswan.org</ulink></emphasis> and the mailing
      lists described there.
    </para>

    <para>
      The Libreswan wiki <emphasis><ulink url="https://libreswan.org/wiki">https://libreswan.org/wiki</ulink></emphasis> includes documentation.
    </para>

    <para>
      The Libreswan list of implemented RFCs <emphasis><ulink url="https://libreswan.org/wiki/Implemented_Standards">https://libreswan.org/wiki/Implemented_Standards</ulink></emphasis>.
    </para>
  </refsect1>

  <refsect1 id="history">
    <title>HISTORY</title>

    <para>
      This code is released under the GPL terms. See the accompanying
      files CHANGES COPYING and CREDITS.* for more details.
    </para>

    <para>
      Detailed history (including FreeS/WAN and Openswan) can be found in the docs/ directory.
    </para>

  </refsect1>

  <refsect1 id="bugs">
    <title>BUGS</title>

    <para>Please see
    &lt;<ulink url="https://github.com/libreswan/libreswan/issues">https://github.com/libreswan/libreswan/issues</ulink>&gt;
    for a list of currently known bugs and missing features.</para>

    <para>
      Bugs should be reported to the &lt;swan-dev@lists.libreswan.org&gt;
      mailing list.
    </para>
  </refsect1>

  <refsect1 id='author'>
    <title>AUTHOR</title>
    <para>
      <author><personname><firstname>Paul</firstname><surname>Wouters</surname></personname></author>,
      <author><personname><firstname>Andrew</firstname><surname>Cagney</surname></personname></author>
    </para>
  </refsect1>
</refentry>