Man Linux: Main Page and Category List

NAME

       ipsec_pluto - ipsec whack : IPsec IKE keying daemon and control
       interface

SYNOPSIS

       ipsec pluto [--help] [--version] [--optionsfrom filename] [--nofork]
             [--stderrlog] [--use-auto] [--use-klips] [--use-netkey]
             [--use-nostack] [--uniqueids] [--nat_traversal]
             [--virtual_private network_list] [--keep_alive delay_sec]
             [--force_keepalive] [--force_busy] [--disable_port_floating]
             [--nocrsend] [--strictcrlpolicy] [--crlcheckinterval] [--ocspuri]
             [--interface interfacename] [--ikeport portnumber]
             [--ctlbase path] [--secretsfile secrets-file] [--adns pathname]
             [--nhelpers number] [--lwdnsq pathname] [--perpeerlog]
             [--perpeerlogbase dirname] [--ipsecdir dirname]
             [--coredir dirname] [--noretransmits]

       ipsec whack [--help] [--version]

       ipsec whack [--debug-none] [--debug-all] [--debug-raw] [--debug-crypt]
             [--debug-parsing] [--debug-emitting] [--debug-control]
             [--debug-lifecycle] [--debug-klips] [--debug-pfkey]
             [--debug-nat-t] [--debug-dpd] [--debug-dns] [--debug-oppo]
             [--debug-oppoinfo] [--debug-whackwatch] [--debug-private]

       ipsec whack --name connection-name [[--ipv4] | [--ipv6]]
             [[--tunnelipv4] | [--tunnelipv6]]

             [--id identity] [--host ip-address] [--cert path]
             [--ca distinguished name] [--groups access control groups]
             [--sendcert yes | forced | always | ifasked | no | never]
             [--certtype number] [--ikeport portnumber] [--nexthop ip-address]
             [[--client subnet] | [--clientwithin subnet]]
             [--clientprotoport protocol/port] [--srcip ip-address]
             [--xauthserver] [--xauthclient] [--modecfgserver]
             [--modecfgclient] [--modecfgdns1] [--modecfgdns2]
             [--modecfgwins1] [--modecfgwins2] [--dnskeyondemand]
             [--updown updown]

             --to

             [--id identity] [--host ip-address] [--cert path]
             [--ca distinguished name] [--groups access control groups]
             [--sendcert yes | always | ifasked | no | never]
             [--certtype number] [--ikeport port-number]
             [--nexthop ip-address] [--client subnet] [--clientwithin subnet]
             [--clientprotoport protocol/port] [--srcip ip-address]
             [--xauthserver] [--xauthclient] [--modecfgserver]
             [--modecfgclient] [--modecfgdns1 ip-address]
             [--modecfgdns2 ip-address] [--modecfgwins1 ip-address]
             [--modecfgwins2 ip-address] [--dnskeyondemand] [--updown updown]

             [--tunnel] [--psk] [--rsasig] [--encrypt] [--authenticate]
             [--compress] [--pfs] [--pfsgroup [modp1024] | [modp1536] |
             [modp2048] | [modp3072] | [modp4096] | [modp6144] | [modp8192]]
             [--disablearrivalcheck] [--ikelifetime seconds] [--ipseclifetime
             seconds] [--rekeymargin seconds] [--rekeyfuzz percentage]
             [--keyingtries count] [--esp esp-algos] [--dontrekey]
             [--aggrmode] [--modecfgpull] [[--dpddelay seconds] |
             [--dpdtimeout seconds]] [--dpdaction [clear] | [hold] |
             [restart]] [--forceencaps] [[--initiateontraffic] | [--pass] |
             [--drop] | [--reject]] [[--failnone] | [--failpass] |
             [--faildrop] | [--failreject]] [--ctlbase path] [--optionsfrom
             filename] [--label string]

       ipsec whack --keyid id [--addkey] [--pubkeyrsa key] [--ctlbase path]
             [--optionsfrom filename] [--label string]

       ipsec whack --myid id

       ipsec whack --listen | --unlisten  [--ctlbase path]
             [--optionsfrom filename] [--label string]

       ipsec whack --route | --unroute  --name connection-name
             [--ctlbase path] [--optionsfrom filename] [--label string]

       ipsec whack --initiate | --terminate  --name connection-name
             [--xauthuser user] [--xauthpass pass] [--asynchronous]
             [--ctlbase path] [--optionsfrom filename] [--label string]

       ipsec whack [[--tunnelipv4] | [--tunnelipv6]] --oppohere ip-address
             --oppothere ip-address

       ipsec whack --crash [ipaddress]

       ipsec whack --whackrecord [filename]

       ipsec whack --whackstoprecord

       ipsec whack --name connection-name --delete [--ctlbase path]
             [--optionsfrom filename] [--label string]

       ipsec whack --deletestate state-number [--ctlbase path]
             [--optionsfrom filename] [--label string]

       ipsec whack [--name connection-name] [--debug-none] [--debug-all]
             [--debug-raw] [--debug-crypt] [--debug-parsing]
             [--debug-emitting] [--debug-control] [--debug-controlmore]
             [--debug-lifecycle] [--debug-klips] [--debug-pfkey] [--debug-dns]
             [--debug-dpd] [--debug-natt] [--debug-oppo] [--debug-oppoinfo]
             [--debug-whackwatch] [--debug-private]
             [--impair-delay-adns-key-answer] [--impair-delay-adns-txt-answer]
             [--impair-bust-mi2] [--impair-bust-mr2] [--impair-sa-fail]
             [--impair-die-oninfo] [--impair-jacob-two-two]

       ipsec whack [--utc] [--listall] [--listpubkeys] [--listcerts]
             [--listcacerts] [--listacerts] [--listaacerts] [--listocspcerts]
             [--listgroups] [--listcrls] [--listocsp]

       ipsec whack [--utc] [--rereadsecrets] [--rereadall] [--rereadcacerts]
             [--rereadacerts] [--rereadaacerts] [--rereadocspcerts]
             [--rereadcrls]

       ipsec whack --purgeocsp

       ipsec whack --listevents

       ipsec whack --status [--ctlbase path] [--optionsfrom filename]
             [--label string]

       ipsec whack --shutdown [--ctlbase path] [--optionsfrom filename]
             [--label string]

DESCRIPTION

       pluto is an IKE (“IPsec Key Exchange”) daemon.  whack is an auxiliary
       program to allow requests to be made to a running pluto.

       pluto is used to automatically build shared “security associations” on
       a system that has IPsec, the secure IP protocol. In other words, pluto
       can eliminate much of the work of manual keying. The actual secure
       transmission of packets is the responsibility of other parts of the
       system - the kernel. Pluto can talk to various kernel implementations,
       such as KLIPS, such as NETKEY, and such as KAME IPsec stacks.
       ipsec_auto(8) provides a more convenient interface to pluto and whack.

   IKEs Job
       A Security Association (SA) is an agreement between two network nodes
       on how to process certain traffic between them. This processing
       involves encapsulation, authentication, encryption, or compression.

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

       An IKE instance (i.e. an IKE implementation on a particular network
       node) communicates with another IKE instance using UDP IP packets, so
       there must be a route between the nodes in each direction.

       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.

       IKE deals with two kinds of Security Associations. The first part of a
       negotiation between IKE instances is to build an ISAKMP SA. An ISAKMP
       SA is used to protect communication between the two IKEs. IPsec SAs can
       then be built by the IKEs - these are used to carry protected IP
       traffic between the systems.

       The negotiation of the ISAKMP SA is known as Phase 1. In theory, Phase
       1 can be accomplished by a couple of different exchange types.
       Currently, Main Mode and Aggressive Mode are implemented.

       Any negotiation under the protection of an ISAKMP SA, including the
       negotiation of IPsec SAs, is part of Phase 2. The exchange type that we
       use to negotiate an IPsec SA is called Quick Mode.

       IKE instances must be able to authenticate each other as part of their
       negotiation of an ISAKMP SA. This can be done by several mechanisms
       described in the draft standards.

       IKE negotiation can be initiated by any instance with any other. 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.

       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.

   Pluto
       pluto is an implementation of IKE. It runs as a daemon on a network
       node. Currently, this network node must be a LINUX system running the
       KLIPS or NETKEY implementation of IPsec, or a FreeBSD/NetBSD/Mac OSX
       system running the KAME implementation of IPsec.

       pluto implements a large subset of IKE. This is enough for it to
       interoperate with other instances of pluto, and many other IKE
       implementations. It currently supports XAUTH, ModeConfig, X.509, Dead
       Peer Detection, Opportunistic Encryption and all the NAT Traversal
       standards.

       The policy for acceptable characteristics for Security Associations is
       mostly hardwired into the code of pluto (spdb.c). Eventually this will
       be moved into a security policy database with reasonable expressive
       power and more convenience.

       pluto uses shared secrets or RSA signatures to authenticate peers with
       whom it is negotiating. These RSA signatures can come from DNS(SEC), a
       configuration file, or from X.509 and CA certificates.

       pluto initiates negotiation of a Security Association when it is
       manually prodded: the program whack is run to trigger this. It will
       also initiate a negotiation when KLIPS traps an outbound packet for
       Opportunistic Encryption.

       pluto implements ISAKMP SAs itself. After it has negotiated the
       characteristics of an IPsec SA, it directs the kernel to implement it.
       If necessary, it also invokes a script to adjust any firewall and issue
       route(8) commands to direct IP packets.

       When pluto shuts down, it closes all Security Associations.

   Before Running Pluto
       pluto runs as a daemon with userid root. Before running it, a few
       things must be set up.

       pluto requires a working IPsec stack.

       pluto 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 --interface option can be used
       to limit the interfaces considered). It does this only when whack tells
       it to --listen, so the interfaces must be configured by then. Each
       interface with a name of the form ipsec[0-9] is taken as a KLIPS
       virtual public interface. Another network interface with the same IP
       address (the first one found will be used) is taken as the
       corresponding real public interface.  ifconfig(8) or ip(8) with the -a
       flag will show the name and status of each network interface.

       pluto requires a database of preshared secrets and RSA private keys.
       This is described in the ipsec.secrets(5).  pluto is told of RSA public
       keys via whack commands. If the connection is Opportunistic, and no RSA
       public key is known, pluto will attempt to fetch RSA keys using the
       Domain Name System.

   Setting up KLIPS for pluto
       The most basic network topology that pluto supports has two security
       gateways negotiating on behalf of client subnets. The diagram of RGB’s
       testbed is a good example (see klips/doc/rgb_setup.txt).

       The file INSTALL in the base directory of this distribution explains
       how to start setting up the whole system, including KLIPS.

       Make sure that the security gateways have routes to each other. This is
       usually covered by the default route, but may require issuing route(8)
       commands. The route must go through a particular IP interface (we will
       assume it is eth0, but it need not be). The interface that connects the
       security gateway to its client must be a different one.

       It is necessary to issue a ipsec_tncfg(8) command on each gateway. The
       required command is:

          ipsec tncfg --attach --virtual ipsec0 --physical eth0

       A command to set up the ipsec0 virtual interface will also need to be
       run. It will have the same parameters as the command used to set up the
       physical interface to which it has just been connected using
       ipsec_tncfg(8).

   Setting up NETKEY for pluto
       No special requirements are necessary to use NETKEY - it ships with all
       modern versions of Linux 2.4 and 2.6. however, note that certain
       vendors or older distributions use old versions or backports of NETKEY
       which are broken. If possible use a NETKEY version that is at least
       based on, or backported from Linux 2.6.11 or newer.

   ipsec.secrets file
       A pluto daemon and another IKE daemon (for example, another instance of
       pluto) 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 pluto.

       The file /etc/ipsec.secrets is used to keep preshared secret keys, RSA
       private keys, X.509 encoded keyfiles and XAUTH passwords. Smartcards
       are handled via NSS. For debugging, there is an argument to the pluto
       command to use a different file. This file is described in
       ipsec.secrets(5).

   Running Pluto
       To fire up the daemon, just type pluto (be sure to be running as the
       superuser). The default IKE port number is 500, the UDP port assigned
       by IANA for IKE Daemons.  pluto 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.

       Pluto supports different IPstacks on different operating systems. The
       option --use-auto, which is also the default, lets pluto find a stack
       automatically. This behaviour can be changed by explicitly setting the
       stack using --use-klips, --use-netkey or --use-nostack. The latter is
       meant for testing only - no actual IPsec connections will be loaded
       into the kernel.

       Pluto supports the NAT-Traversal drafts and the final standard, RFC
       3947, if the --nat_traversal is specified. The allowed range behind the
       NAT routers is submitted using the --virtual_private option. See
       ipsec.conf(5) for the syntax. The option --force_keepalive forces the
       sending of the keep-alive packets, which are send to prevent the NAT
       router from closing its port when there is not enough traffic on the
       IPsec connection. The --keep_alive sets the delay (in seconds) of these
       keep-alive packets. The newer NAT-T standards support port floating,
       and Openswan enables this per default. It can be disabled using the
       --disable_port_floating option.

       Pluto supports the use of X.509 certificates and sends it certificate
       when needed. This can confuse IKE implementations that do not implement
       this, such as the old FreeS/WAN implementation. The --nocrsend prevents
       pluto from sending these. At startup, pluto loads all the X.509 related
       files from the directories /etc/ipsec.d/certs, /etc/ipsec.d/cacerts,
       /etc/ipsec.d/aacerts, /etc/ipsec.d/ocspcerts, /etc/ipsec.d/private and
       /etc/ipsec.d/crls. The Certificate Revocation Lists can also be
       retrieved from an URL. The option --crlcheckinterval sets the time
       between checking for CRL expiration and issuing new fetch commands. The
       first attempt to update a CRL is started at 2*crlcheckinterval before
       the next update time. Pluto logs a warning if no valid CRL was loaded
       or obtained for a connection. If --strictcrlpolicy is given, the
       connection will be rejected until a valid CRL has been loaded. Pluto
       also has support for the Online Certificate Store Protocol (OSCP) as
       defined in RFC 2560. The URL to the OSCP store can be given to pluto
       via the --ocspuri option.

       Pluto can use the BIND9 secure resolver, which means it has support for
       DNSSEC, using the BIND9 lwres {} interface, see named.conf(5). Pluto
       can also use the old adns interface if there is no BIND9 running with
       lwres {} on the host, but then pluto cannot do any DNSSEC processing.
       Pluto forks and starts these DNS helpers in separate children. The
       options --lwdnsq and --adns invoke these resolvers.

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

       pluto attempts to create a lockfile with the name
       /var/run/pluto/pluto.pid. If the lockfile cannot be created, pluto
       exits - this prevents multiple plutos from competing Any “leftover”
       lockfile must be removed before pluto will run.  pluto 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).

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

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

       If the --perpeerlog option is given, then pluto will open a log file
       per connection. By default, this is in /var/log/pluto/peer, in a
       subdirectory formed by turning all dot (.) [IPv4} or colon (:) [IPv6]
       into slashes (/).

       The base directory can be changed with the --perpeerlogbase.

       Once pluto is started, it waits for requests from whack.

   Plutos Internal State
       To understand how to use pluto, it is helpful to understand a little
       about its internal state. Furthermore, the terminology is needed to
       decipher some of the diagnostic messages.

       Pluto supports food groups, and X.509 certificates. These are located
       in /etc/ipsec.d, or another directory as specified by --ipsecdir.

       Pluto may core dump. It will normally do so into the current working
       directory. The standard scripts have an option dumpdir=, which can set
       the current directory to determine where the core dump will go. In some
       cases, it may be more convenient to specify it on the command line
       using --coredir. A third method is to set the environment variable
       PLUTO_CORE_DIR. The command line argument takes precedence over the
       environment variable. The option plutorestartoncrash can be set to no
       to prevent multiple core files and a looping pluto process. Normally,
       when pluto crashes, another pluto process is started.

       At times it may be desireable to turn off all timed events in pluto,
       this can be done with --noretransmits.

       The (potential) connection database describes attributes of a
       connection. These include the IP addresses of the hosts and client
       subnets and the security characteristics desired.  pluto 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.

       During the IKE exchange to build an SA, the information about the
       negotiation is represented in a state object. 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.

       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.

       KLIPS hooks into the routing code in a LINUX kernel. Traffic to be
       processed by an IPsec SA must be directed through KLIPS by routing
       commands. Furthermore, the processing to be done is specified by ipsec
       eroute(8) commands.  pluto takes the responsibility of managing both of
       these special kinds of routes.

       NETKEY requires no special routing.

       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 (pluto’s logic does not reflect any advanced routing
       capabilities).

       On KLIPS, each eroute is associated with the state object for an IPsec
       SA because it has the particular characteristics of the SA. Two eroutes
       conflict if they specify the identical local and remote clients (unlike
       for routes, the local clients are taken into account).

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

       There is an exception. If pluto, 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).

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

       All of these routing characteristics are expected change when KLIPS and
       NETKEY merge into a single new stack.

   Using Whack
       whack is used to command a running pluto.  whack uses a UNIX domain
       socket to speak to pluto (by default, /var/pluto.ctl).

       whack has an intricate argument syntax. This syntax allows many
       different functions to be specified. The help form shows the usage or
       version information. The connection form gives pluto a description of a
       potential connection. The public key form informs pluto of the RSA
       public key for a potential peer. The delete form deletes a connection
       description and all SAs corresponding to it. The listen form tells
       pluto to start or stop listening on the public interfaces for IKE
       requests from peers. The route form tells pluto to set up routing for a
       connection; the unroute form undoes this. The initiate form tells pluto
       to negotiate an SA corresponding to a connection. The terminate form
       tells pluto to remove all SAs corresponding to a connection, including
       those being negotiated. The status form displays the pluto’s internal
       state. The debug form tells pluto to change the selection of debugging
       output “on the fly”. The shutdown form tells pluto to shut down,
       deleting all SAs.

       The crash option asks pluto to consider a particularly target IP to
       have crashed, and to attempt to restart all connections with that IP
       address as a gateway. In general, you should use Dead Peer Detection to
       detect this kind of situation automatically, but this is not always
       possible.

       Most options are specific to one of the forms, and will be described
       with that form. There are three options that apply to all forms.

       --ctlbase path
           path.ctl is used as the UNIX domain socket for talking to pluto.
           This option facilitates debugging.

       --optionsfrom filename
           adds the contents of the file to the argument list.

       --label string
           adds the string to all error messages generated by whack.

       The help form of whack is self-explanatory.

       --help
           display the usage message.

       --version
           display the version of whack.

       The connection form describes a potential connection to pluto.  pluto
       needs to know what connections can and should be negotiated. When pluto
       is the initiator, it needs to know what to propose. When pluto is the
       responder, it needs to know enough to decide whether is is willing to
       set up the proposed connection.

       The description of a potential connection can specify a large number of
       details. Each connection has a unique name. This name will appear in a
       updown shell command, so it should not contain punctuation that would
       make the command ill-formed.

       --name connection-name
           sets the name of the connection

       The topology of a connection is symmetric, so to save space here is
       half a picture:

          client_subnet<-->host:ikeport<-->nexthop<---

       A similar trick is used in the flags. The same flag names are used for
       both ends. Those before the --to flag describe the left side and those
       afterwards describe the right side. When pluto attempts to use the
       connection, it decides whether it is the left side or the right side of
       the connection, based on the IP numbers of its interfaces.

       --id id
           the identity of the end. Currently, this can be an IP address
           (specified as dotted quad or as a Fully Qualified Domain Name,
           which will be resolved immediately) or as a Fully Qualified Domain
           Name itself (prefixed by “@” to signify that it should not be
           resolved), or as user@FQDN, or an X.509 DN, or as the magic value
           %myid.  Pluto only authenticates the identity, and does not use it
           for addressing, so, for example, an IP address need not be the one
           to which packets are to be sent. If the option is absent, the
           identity defaults to the IP address specified by --host.  %myid
           allows the identity to be separately specified (by the pluto or
           whack option --myid or by the ipsec.conf(5) config setup parameter
           myid). Otherwise, pluto tries to guess what %myid should stand for:
           the IP address of %defaultroute, if it is supported by a suitable
           TXT record in the reverse domain for that IP address, or the
           system’s hostname, if it is supported by a suitable TXT record in
           its forward domain.

       --host ip-address, --host %any, --host %opportunistic
           the IP address of the end (generally the public interface). If
           pluto is to act as a responder for IKE negotiations initiated from
           unknown IP addresses (the “Road Warrior” case), the IP address
           should be specified as %any (currently, the obsolete notation
           0.0.0.0 is also accepted for this). If pluto is to
           opportunistically initiate the connection, use %opportunistic

       --cert filename
           The filename of the X.509 certificate. This must be the public key
           certificate only, and cannot be the PKCS#12 certificate file. See
           ipsec.conf(5) on how to extrac this from the PKCS#12 file.

       --ca distinguished name
           the X.509 Certificate Authority’s Distinguished Name (DN) used as
           trust anchor for this connection. This is the CA certificate that
           signed the host certificate, as well as the certificate of the
           incoming client.

       --groups access control groups
           the access control groups used.

       --sendcert yes|forced|always|ifasked|no|never
           Wether or not to send our X.509 certificate credentials. This could
           potentially give an attacker too much information about which
           identities are allowed to connect to this host. The default is to
           use ifasked when we are a Responder, and to use yes (which is the
           same as forced and always if we are an Initiator. The values no and
           never are equivalent. NOTE: "forced" does not seem to be actually
           implemented - do not use it.

       --certtype number
           The X.509 certificate type number.

       --ikeport port-number
           the UDP port that IKE listens to on that host. The default is 500.
           (pluto on this machine uses the port specified by its own command
           line argument, so this only affects where pluto sends messages.)

       --nexthop ip-address
           where to route packets for the peer’s client (presumably for the
           peer too, but it will not be used for this). When pluto installs an
           IPsec SA, it issues a route command. It uses the nexthop as the
           gateway. The default is the peer’s IP address (this can be
           explicitly written as %direct; the obsolete notation 0.0.0.0 is
           accepted). This option is necessary if pluto’s host’s interface
           used for sending packets to the peer is neither point-to-point nor
           directly connected to the peer.

       --client subnet
           the subnet for which the IPsec traffic will be destined. If not
           specified, the host will be the client. The subnet can be specified
           in any of the forms supported by ipsec_atosubnet(3). The general
           form is address/mask. The address can be either a domain name or
           four decimal numbers (specifying octets) separated by dots. The
           most convenient form of the mask is a decimal integer, specifying
           the number of leading one bits in the mask. So, for example,
           10.0.0.0/8 would specify the class A network “Net 10”.

       --clientwithin subnet
           This option is obsolete and will be removed. Do not use this option
           anymore.

       --clientprotoport protocol/port
           specify the Port Selectors (filters) to be used on this connection.
           The general form is protocol/port. This is most commonly used to
           limit the connection to L2TP traffic only by specifying a value of
           17/1701 for UDP (protocol 17) and port 1701. The notation 17/%any
           can be used to allow all UDP traffic and is needed for L2TP
           connections with Windows XP machines before Service Pack 2.

       --srcip ip-address
           the IP address for this host to use when transmitting a packet to
           the remote IPsec gateway itself. This option is used to make the
           gateway itself use its internal IP, which is part of the --client
           subnet. Otherwise it will use its nearest IP address, which is its
           public IP address, which is not part of the subnet-subnet IPsec
           tunnel, and would therefor not get encrypted.

       --xauthserver
           this end is an xauthserver. It will lookup the xauth user name and
           password and verify this before allowing the connection to get
           established.

       --xauthclient
           this end is an xauthclient. To bring this connection up with the
           --initiate also requires the client to specify --xauthuser username
           and --xauthpass password

       --xauthuser
           The username for the xauth authentication.This option is normally
           passed along by ipsec_auto(8) when an xauth connection is started
           using ipsec auto --up conn

       --xauthpass
           The password for the xauth authentication. This option is normally
           passed along by ipsec_auto(8) when an xauth connection is started
           using ipsec auto --up conn

       --modecfgserver
           this end is an Mode Config server

       --modecfgclient
           this end is an Mode Config client

       --modecfgdns1
           The IP address of the first DNS server to pass along to the
           ModeConfig Client

       --modecfgdns2
           The IP address of the second DNS server to pass along to the
           ModeConfig Client

       --modecfgwins1
           The IP address of the first WINS server to pass along to the
           ModeConfig Client

       --modecfgwins2
           The IP address of the second WINS server to pass along to the
           ModeConfig Client

       --dnskeyondemand
           specifies that when an RSA public key is needed to authenticate
           this host, and it isn’t already known, fetch it from DNS.

       --updown updown
           specifies an external shell command to be run whenever pluto brings
           up or down a connection. The script is used to build a shell
           command, so it may contain positional parameters, but ought not to
           have punctuation that would cause the resulting command to be
           ill-formed. The default is ipsec _updown. Pluto passes a dozen
           environment variables to the script about the connection involved.

       --to
           separates the specification of the left and right ends of the
           connection. Pluto tries to decide wether it is left or right based
           on the information provided on both sides of this option.

       The potential connection description also specifies characteristics of
       rekeying and security.

       --psk
           Propose and allow preshared secret authentication for IKE peers.
           This authentication requires that each side use the same secret.
           May be combined with --rsasig; at least one must be specified.

       --rsasig
           Propose and allow RSA signatures for authentication of IKE peers.
           This authentication requires that each side have have a private key
           of its own and know the public key of its peer. May be combined
           with --psk; at least one must be specified.

       --encrypt
           All proposed or accepted IPsec SAs will include non-null ESP. The
           actual choices of transforms are wired into pluto.

       --authenticate
           All proposed IPsec SAs will include AH. All accepted IPsec SAs will
           include AH or ESP with authentication. The actual choices of
           transforms are wired into pluto. Note that this has nothing to do
           with IKE authentication.

       --compress
           All proposed IPsec SAs will include IPCOMP (compression). This will
           be ignored if KLIPS is not configured with IPCOMP support.

       --tunnel
           the IPsec SA should use tunneling. Implicit if the SA is for
           clients. Must only be used with --authenticate or --encrypt.

       --ipv4
           The host addresses will be interpreted as IPv4 addresses. This is
           the default. Note that for a connection, all host addresses must be
           of the same Address Family (IPv4 and IPv6 use different Address
           Families).

       --ipv6
           The host addresses (including nexthop) will be interpreted as IPv6
           addresses. Note that for a connection, all host addresses must be
           of the same Address Family (IPv4 and IPv6 use different Address
           Families).

       --tunnelipv4
           The client addresses will be interpreted as IPv4 addresses. The
           default is to match what the host will be. This does not imply
           --tunnel so the flag can be safely used when no tunnel is actually
           specified. Note that for a connection, all tunnel addresses must be
           of the same Address Family.

       --tunnelipv6
           The client addresses will be interpreted as IPv6 addresses. The
           default is to match what the host will be. This does not imply
           --tunnel so the flag can be safely used when no tunnel is actually
           specified. Note that for a connection, all tunnel addresses must be
           of the same Address Family.

       --pfs
           There should be Perfect Forward Secrecy - new keying material will
           be generated for each IPsec SA rather than being derived from the
           ISAKMP SA keying material. Since the group to be used cannot be
           negotiated (a dubious feature of the standard), pluto will propose
           the same group that was used during Phase 1. We don’t implement a
           stronger form of PFS which would require that the ISAKMP SA be
           deleted after the IPSEC SA is negotiated.

       --pfsgroup modp-group
           Sets the Diffie-Hellman group used. Currently the following values
           are supported: modp1024 (DHgroup 2), modp1536 (DHgroup 5), modp2048
           (DHgroup 14), modp3072 (DHgroup 15), modp4096 (DHgroup 16),
           modp6144 (DHgroup 17), and modp8192 (DHgroup 18). It is possible to
           support the weak and broken modp768 (DHgroup 1), but this requires
           a manual recompile and is strongly discouraged.

       --disablearrivalcheck
           If the connection is a tunnel, allow packets arriving through the
           tunnel to have any source and destination addresses.

       --esp esp-algos
           ESP encryption/authentication algorithm to be used for the
           connection (phase2 aka IPsec SA). The options must be suitable as a
           value of ipsec_spi(8). See ipsec.conf(5) for a detailed description
           of the algorithm format.

       --aggrmode
           This tunnel is using aggressive mode ISAKMP negotiation. The
           default is main mode. Aggressive mode is less secure than main mode
           as it reveals your identity to an eavesdropper, but is needed to
           support road warriors using PSK keys or to interoperate with other
           buggy implementations insisting on using aggressive mode.

       --modecfgpull
           Pull the Mode Config network information from the peer.

       --dpddelay seconds
           Set the delay (in seconds) between Dead Peer Dectection (RFC 3706)
           keepalives (R_U_THERE, R_U_THERE_ACK) that are sent for this
           connection (default 30 seconds).

       --timeout seconds
           Set the length of time (in seconds) we will idle without hearing
           either an R_U_THERE poll from our peer, or an R_U_THERE_ACK reply.
           After this period has elapsed with no response and no traffic, we
           will declare the peer dead, and remove the SA (default 120
           seconds).

       --dpdaction action
           When a DPD enabled peer is declared dead, what action should be
           taken.  hold(default) means the eroute will be put into %hold
           status, while clearmeans the eroute and SA with both be cleared.
           Clear is really only useful on the server of a Road Warrior config.
           The action restart is used on tunnels that need to be permanently
           up, and have static IP addresses.

       --forceencaps
           In some cases, for example when ESP packets are filtered or when a
           broken IPsec peer does not properly recognise NAT, it can be useful
           to force RFC-3948 encapsulation using this option. It causes pluto
           lie and tell the remote peer that RFC-3948 encapsulation (ESP in
           UDP port 4500 packets) is required. For this option to have any
           effect, pluto must have been started with the --nat_traversal
           option.

       If none of the --encrypt, --authenticate, --compress, or --pfs flags is
       given, the initiating the connection will only build an ISAKMP SA. For
       such a connection, client subnets have no meaning and must not be
       specified.

       Apart from initiating directly using the --initiate option, a tunnel
       can be loaded with a different policy

       --initiateontraffic
           Only initiate the connection when we have traffic to send over the
           connection

       --pass
           Allow unencrypted traffic to flow until the tunnel is initiated.

       --drop
           Drop unencrypted traffic silently.

       --reject
           Drop unencrypted traffic silently, but send an ICMP message
           notifying the other end.

       These options need to be documented

       --failnone
           to be documented

       --failpass
           to be documented

       --faildrop
           to be documented

       --failreject
           to be documented

       pluto supports various X.509 Certificate related options.

       --utc
           display all times in UTC.

       --listall
           lists all of the X.509 information known to pluto.

       --listpubkeys
           list all the public keys that have been successfully loaded.

       --listcerts
           list all the X.509 certificates that are currently loaded.

       --listcacerts
           list all the X.509 Certificate Agency (CA) certificates that are
           currently loaded.

       --listacerts
           list all the X.509 Attribute certificates that are currently loaded

       --listaacerts

       --ocspcerts
           list all of the X.509 certificates obtained via the Online
           Certificate Store Protocol (OCSP)

       --listgroups

       --listcrls
           list all the loaded Certificate Revocation Lists (CRLs)

       The corresponding options --rereadsecrets, --rereadall,
       --rereadcacerts, --rereadacerts, --rereadaacerts, --rereadocspcerts
       --rereadcrls, and --purgeocsp, options reread this information from
       their respective sources, and purge all the online obtained
       information. The option --listevents lists all pending CRL fetch
       commands.

       More work is needed to allow for flexible policies. Currently policy is
       hardwired in the source file spdb.c. The ISAKMP SAs may use Oakley
       groups MODP1024 and MODP1536; AES or 3DES encryption; SHA1-96 and
       MD5-96 authentication. The IPsec SAs may use AES or 3DES and MD5-96 or
       SHA1-96 for ESP, or just MD5-96 or SHA1-96 for AH. IPCOMP Compression
       is always Deflate.

       --ikelifetime seconds
           how long pluto will propose that an ISAKMP SA be allowed to live.
           The default is 3600 (one hour) and the maximum is 86400 (1 day).
           This option will not affect what is accepted.  pluto will reject
           proposals that exceed the maximum.

       --ipseclifetime seconds
           how long pluto will propose that an IPsec SA be allowed to live.
           The default is 28800 (eight hours) and the maximum is 86400 (one
           day). This option will not affect what is accepted.  pluto will
           reject proposals that exceed the maximum.

       --rekeymargin seconds
           how long before an SA’s expiration should pluto try to negotiate a
           replacement SA. This will only happen if pluto was the initiator.
           The default is 540 (nine minutes).

       --rekeyfuzz percentage
           maximum size of random component to add to rekeymargin, expressed
           as a percentage of rekeymargin.  pluto will select a delay
           uniformly distributed within this range. By default, the percentage
           will be 100. If greater determinism is desired, specify 0. It may
           be appropriate for the percentage to be much larger than 100.

       --keyingtries count
           how many times pluto should try to negotiate an SA, either for the
           first time or for rekeying. A value of 0 is interpreted as a very
           large number: never give up. The default is three.

       --dontrekey
           A misnomer. Only rekey a connection if we were the Initiator and
           there was recent traffic on the existing connection. This applies
           to Phase 1 and Phase 2. This is currently the only automatic way
           for a connection to terminate. It may be useful with Road Warrior
           or Opportunistic connections.  Since SA lifetime negotiation is
           take-it-or-leave it, a Responder normally uses the shorter of the
           negotiated or the configured lifetime. This only works because if
           the lifetime is shorter than negotiated, the Responder will rekey
           in time so that everything works. This interacts badly with
           --dontrekey. In this case, the Responder will end up rekeying to
           rectify a shortfall in an IPsec SA lifetime; for an ISAKMP SA, the
           Responder will accept the negotiated lifetime.

       --delete
           when used in the connection form, it causes any previous connection
           with this name to be deleted before this one is added. Unlike a
           normal delete, no diagnostic is produced if there was no previous
           connection to delete. Any routing in place for the connection is
           undone.

       --delete, --name connection-name
           The delete form deletes a named connection description and any SAs
           established or negotiations initiated using this connection. Any
           routing in place for the connection is undone.

       --deletestate state-number
           The deletestate form deletes the state object with the specified
           serial number. This is useful for selectively deleting instances of
           connections.

       The route form of the whack command tells pluto to set up routing for a
       connection. Although like a traditional route, it uses an ipsec device
       as a virtual interface. Once routing is set up, no packets will be sent
       “in the clear” to the peer’s client specified in the connection. A TRAP
       shunt eroute will be installed; if outbound traffic is caught, Pluto
       will initiate the connection. An explicit whack route is not always
       needed: if it hasn’t been done when an IPsec SA is being installed, one
       will be automatically attempted.

       --route, --name connection-name
           When a routing is attempted for a connection, there must not
           already be a routing for a different connection with the same
           subnet but different interface or destination, or if there is, it
           must not be being used by an IPsec SA. Otherwise the attempt will
           fail.

       --unroute, --name connection-name
           The unroute form of the whack command tells pluto to undo a
           routing.  pluto will refuse if an IPsec SA is using the connection.
           If another connection is sharing the same routing, it will be left
           in place. Without a routing, packets will be sent without
           encryption or authentication.

       The initiate form tells pluto to initiate a negotiation with another
       pluto (or other IKE daemon) according to the named connection.
       Initiation requires a route that --route would provide; if none is in
       place at the time an IPsec SA is being installed, pluto attempts to set
       one up.

       --initiate, --name connection-name, --asynchronous
           The initiate form of the whack command will relay back from pluto
           status information via the UNIX domain socket (unless
           --asynchronous is specified). The status information is meant to
           look a bit like that from FTP. Currently whack simply copies this
           to stderr. When the request is finished (eg. the SAs are
           established or pluto gives up), pluto closes the channel, causing
           whack to terminate.

       The opportunistic initiate form is mainly used for debugging.

       --tunnelipv4, --tunnelipv6, --oppohere ip-address,
       --oppothere ip-address
           This will cause pluto to attempt to opportunistically initiate a
           connection from here to the there, even if a previous attempt had
           been made. The whack log will show the progress of this attempt.

       Ending an connection

       --terminate, --name connection-name
           the terminate form tells pluto to delete any sas that use the
           specified connection and to stop any negotiations in process. it
           does not prevent new negotiations from starting (the delete form
           has this effect).

       --crash ip-address
           If the remote peer has crashed, and therefor did not notify us, we
           keep sending encrypted traffic, and rejecting all plaintext
           (non-IKE) traffic from that remote peer. The --crash brings our end
           down as well for all the known connections to the specified
           ip-address

       --whackrecordfilename, --whackstoprecord
           this causes plutoto open the given filename for write, and record
           each of the messages received from whack or addconn. This continues
           until the whackstoprecord option is used. This option may not be
           combined with any other command. The start/stop commands are not
           recorded themselves. These files are usually used to create input
           files for unit tests, particularly for complex setups where
           policies may in fact overlap.

           The format of the file consists of a line starting with
           #!pluto-whack and the date that the file was started, as well as
           the hostname, and a linefeed. What follows are binary format
           records consisting of a 32-bit record length in bytes, (including
           the length record itself), a 64-bit timestamp, and then the literal
           contents of the whack message that was received. All integers are
           in host format. In order to unambigously determine the host order,
           the first record is an empty record that contains only the current
           WHACK_MAGIC value. This record is 16 bytes long.

       ip-address
           If the remote peer has crashed, and therefor did not notify us, we
           keep sending encrypted traffic, and rejecting all plaintext
           (non-IKE) traffic from that remote peer. The --crash brings our end
           down as well for all the known connections to the specified
           ip-address

       The public key for informs pluto of the RSA public key for a potential
       peer. Private keys must be kept secret, so they are kept in
       ipsec.secrets(5).

       --keyid id
           specififies the identity of the peer for which a public key should
           be used. Its form is identical to the identity in the connection.
           If no public key is specified, pluto attempts to find KEY records
           from DNS for the id (if a FQDN) or through reverse lookup (if an IP
           address). Note that there several interesting ways in which this is
           not secure.

       --addkey
           specifies that the new key is added to the collection; otherwise
           the new key replaces any old ones.

       --pubkeyrsa key
           specifies the value of the RSA public key. It is a sequence of
           bytes as described in RFC 2537 “RSA/MD5 KEYs and SIGs in the Domain
           Name System (DNS)”. It is denoted in a way suitable for
           ipsec_ttodata(3). For example, a base 64 numeral starts with 0s.

       The listen form tells pluto to start listening for IKE requests on its
       public interfaces. To avoid race conditions, it is normal to load the
       appropriate connections into pluto before allowing it to listen. If
       pluto isn’t listening, it is pointless to initiate negotiations, so it
       will refuse requests to do so. Whenever the listen form is used, pluto
       looks for public interfaces and will notice when new ones have been
       added and when old ones have been removed. This is also the trigger for
       pluto to read the ipsec.secrets file. So listen may useful more than
       once.

       --listen
           start listening for IKE traffic on public interfaces.

       --unlisten
           stop listening for IKE traffic on public interfaces.

       The status form will display information about the internal state of
       pluto: information about each potential connection, about each state
       object, and about each shunt that pluto is managing without an
       associated connection.

       --status

       The shutdown form is the proper way to shut down pluto. It will tear
       down the SAs on this machine that pluto has negotiated. It does not
       inform its peers, so the SAs on their machines remain.

       --shutdown

   Examples
       It would be normal to start pluto 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

          ipsec pluto

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

       Using whack, several potential connections would be described:

          ipsec whack --name silly --host 127.0.0.1 --to --host 127.0.0.2
       --ikelifetime 900 --ipseclifetime 800 --keyingtries 3

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

          ipsec whack --name secret --host 10.0.0.1 --client 10.0.1.0/24 --to
       --host 10.0.0.2 --client 10.0.2.0/24 --encrypt

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

       Now that the connections are specified, pluto 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:

          ipsec whack --listen

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

          ipsec whack --route secret

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

          ipsec whack --initiate --name secret

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

       whack can also be used to terminate pluto cleanly, tearing down all SAs
       that it has negotiated.

          ipsec whack --shutdown

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

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

       For testing purposes, the options --xauthuser user --xauthpass pass may
       be be given prior to the --initiate  to provide responses to the
       username and password prompts.

   The updown command
       Whenever pluto brings a connection up or down, it invokes the updown
       command. This command is specified using the --updown option. This
       allows for customized control over routing and firewall manipulation.

       The updown is invoked for five different operations. Each of these
       operations can be for our client subnet or for our host itself.

       prepare-host or prepare-client
           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 pluto was run or perhaps
           by some agent not known to pluto.

       route-host or route-client
           is run when bringing up a connection for a new peer client subnet
           (even if prepare-host or prepare-client was run). The command
           should install a suitable route. Routing decisions are based only
           on the destination (peer’s client) subnet address, unlike eroutes
           which discriminate based on source too.

       unroute-host or unroute-client
           is run when bringing down the last connection for a particular peer
           client subnet. It should undo what the route-host or route-client
           did.

       up-host or up-client
           is run when bringing up a tunnel eroute with a pair of client
           subnets that does not already have a tunnel eroute. 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.

       down-host or down-client
           is run when bringing down the eroute 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.

       The script is passed a large number of environment variables to specify
       what needs to be done.

       PLUTO_VERSION
           indicates what version of this interface is being used. This
           document describes version 1.1. This is upwardly compatible with
           version 1.0.

       PLUTO_VERB
           specifies the name of the operation to be performed (prepare-host,r
           prepare-client, up-host, up-client, down-host, or down-client). If
           the address family for security gateway to security gateway
           communications is IPv6, then a suffix of -v6 is added to the verb.

       PLUTO_CONNECTION
           is the name of the connection for which we are routing.

       PLUTO_NEXT_HOP
           is the next hop to which packets bound for the peer must be sent.

       PLUTO_INTERFACE
           is the name of the ipsec interface to be used.

       PLUTO_ME
           is the IP address of our host.

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

       PLUTO_MY_CLIENT_NET
           is the IP address of our client net. If the client is just the
           host, this will be the host’s own IP address.

       PLUTO_MY_CLIENT_MASK
           is the mask for our client net. If the client is just the host,
           this will be 255.255.255.255.

       PLUTO_PEER
           is the IP address of our peer.

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

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

       PLUTO_PEER_CLIENT_MASK
           is the mask for the peer’s client net. If the client is just the
           peer, this will be 255.255.255.255.

       PLUTO_MY_PROTOCOL
           lists the protocols allowed over this IPsec SA.

       PLUTO_PEER_PROTOCOL
           lists the protocols the peer allows over this IPsec SA.

       PLUTO_MY_PORT
           lists the ports allowed over this IPsec SA.

       PLUTO_PEER_PORT
           lists the ports the peer allows over this IPsec SA.

       PLUTO_MY_ID
           lists our id.

       PLUTO_PEER_ID
           Dlists our peer’s id.

       PLUTO_PEER_CA
           lists the peer’s CA.

       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.

       Pluto waits for the script to finish and will not do any other
       processing while it is waiting. The script may assume that pluto 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 pluto. Either of these activities could be
       performed by a background subprocess of the script.

   Rekeying
       When an SA that was initiated by pluto has only a bit of lifetime left,
       pluto 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.

       Similarly, when an SA that was initiated by the peer has only a bit of
       lifetime left, pluto 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.

       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.

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

       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.

       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.

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

   Selecting a Connection When Responding: Road Warrior Support
       When pluto 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.)

       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.

       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.

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

       When pluto is using one of these temporary connections and needs to
       find the preshared secret or RSA private key in ipsec.secrets, and and
       the connection specified no identity for the peer, %any 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.

       Part way into the Phase 1 (Main Mode) negotiation using one of these
       temporary connection descriptions, pluto will be receive an Identity
       Payload. At this point, pluto checks for a more appropriate connection,
       one with an identity for the peer that matches the payload but which
       would use the same keys so-far used for authentication. If it finds
       one, it will switch to using this better connection (or a temporary
       derived from this, if it has %any 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, pluto terminates negotiation.

       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 authentications does not
       require that the responder know 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).

       When pluto 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 %any 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, pluto terminates negotiation.

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

       pluto 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.  pluto has no mechanism to do this
       automatically.

       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.

       If any Road Warrior connections are supported, pluto 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.

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

   Debugging
       pluto accepts several optional arguments, useful mostly for debugging.
       Except for --interface, each should appear at most once.

       --interface interfacename
           specifies that the named real public network interface should be
           considered. The interface name specified should not be ipsecN. 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.

       --ikeport port-number
           changes the UDP port that pluto will use (default, specified by
           IANA: 500)

       --ctlbase path
           basename for control files.  path.ctl is the socket through which
           whack communicates with pluto.  path.pid is the lockfile to prevent
           multiple pluto instances. The default is /var/run/pluto/pluto).

       --secretsfile file
           specifies the file for authentication secrets (default:
           /etc/ipsec.secrets). This name is subject to “globbing” as in
           sh(1), so every file with a matching name is processed. Quoting is
           generally needed to prevent the shell from doing the globbing.

       --adns path to adns, --lwdnsq path to lwdnsq
           specifies where to find pluto’s helper program for asynchronous DNS
           lookup.  pluto can be built to use one of two helper programs:
           _pluto_adns or lwdnsq. You must use the program for which it was
           built. By default, pluto will look for the program in $IPSEC_DIR
           (if that environment variable is defined) or, failing that, in the
           same directory as pluto.

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

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

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

       --stderrlog
           log goes to standard out {default is to use syslogd(8))

       For example

       pluto --secretsfile ipsec.secrets --ctlbase pluto.base --ikeport 8500
       --nofork --use-nostack --stderrlog

       lets one test pluto without using the superuser account.

       pluto is willing to produce a prodigious amount of debugging
       information. To do so, it must be compiled with -DDEBUG. There are
       several classes of debugging output, and pluto may be directed to
       produce a selection of them. All lines of debugging output are prefixed
       with “| ” to distinguish them from error messages.

       When pluto is invoked, it may be given arguments to specify which
       classes to output. The current options are:

       --debug-none
           disable all debugging

       --debug-all
           enable all debugging

       --debug-raw
           show the raw bytes of messages

       --debug-crypt
           show the encryption and decryption of messages

       --debug-parsing
           show the structure of input messages

       --debug-emitting
           show the structure of output messages

       --debug-control
           show pluto’s decision making

       --debug-controlmore
           show even more detailed pluto decision making

       --debug-lifecycle
           [this option is temporary] log more detail of lifecycle of SAs

       --debug-klips
           show pluto’s interaction with KLIPS

       --debug-pfkey
           show pluto’s PFKEYinterface communication

       --debug-dns
           show pluto’s interaction with DNS for KEY and TXT records

       --debug-dpd
           show pluto’s Dead Peer Detection handling

       --debug-natt
           show pluto’s NAT Traversal handling

       --debug-oppo
           show why pluto didn’t find a suitable DNS TXT record to authorize
           opportunistic initiation

       --debug-oppoinfo
           log when connections are initiated due to acquires from the kernel.
           This is often useful to know, but can be extremely chatty on a busy
           system.

       --debug-whackwatch
           if set, causes pluto not to release the whack --initiate channel
           until the SA is completely up. This will cause the requestor to
           possibly wait forever while pluto unsuccessfully negotiates. Used
           often in test cases.

       --debug-private
           allow debugging output with private keys.

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

       For example, to start a pluto with a display of the structure of input
       and output:

       pluto --debug-emitting --debug-parsing

       To later change this pluto to only display raw bytes:

       whack --debug-raw

       For testing, SSH’s IKE test page is quite useful:

       http://isakmp-test.ssh.fi/

       Hint: ISAKMP SAs are often kept alive by IKEs even after the IPsec SA
       is established. This allows future IPsec SA’s to be negotiated
       directly. If one of the IKEs is restarted, the other may try to use the
       ISAKMP SA but the new IKE won’t know about it. This can lead to much
       confusion.  pluto is not yet smart enough to get out of such a mess.

   Plutos Behaviour When Things Go Wrong
       When pluto 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.

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

       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.

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

   Notes
       If pluto is compiled without -DKLIPS, it negotiates Security
       Associations but never ask the kernel to put them in place and never
       makes routing changes. This allows pluto to be tested on systems
       without KLIPS, but makes it rather useless.

       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.  Pluto also avoids choosing an
       SPI in the range 0x100 to 0xFFF, leaving these SPIs free for manual
       keying. Remember that the peer, if not pluto, may well chose SPIs in
       this range.

   Policies
       This catalogue of policies may be of use when trying to configure Pluto
       and another IKE implementation to interoperate.

       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.

       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.

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

       ·
           Diffie Hellman Groups MODP 1024 and MODP 1536 (2 and 5) are
           supported. Group MODP768 (1) is not supported because it is too
           weak.

       ·
           Host authetication can be done by RSA Signatures or Pre-Shared
           Secrets.

       ·
           3DES CBC (Cypher Block Chaining mode) is the only encryption
           supported, both for ISAKMP SAs and IPSEC SAs.

       ·
           MD5 and SHA1 hashing are supported for packet authentication in
           both kinds of SAs.

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

       ·
           Each of these may be combined with IPCOMP Deflate compression, but
           only if the potential connection specifies compression and only if
           KLIPS is configured with IPCOMP support.

       ·
           The IPSEC SAs may be tunnel or transport mode, where appropriate.
           The --tunnel flag controls this when pluto is initiating.

       ·
           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 pluto is
           initiating.

       ·
           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 pluto is
           initiating.

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

SIGNALS

       Pluto responds to SIGHUP by issuing a suggestion that ‘‘whack
       --listen’’ might have been intended.

       Pluto exits when it recieves SIGTERM.

EXIT STATUS

       pluto normally forks a daemon process, so the exit status is normally a
       very preliminary result.

       0
           means that all is OK so far.

       1
           means that something was wrong.

       10
           means that the lock file already exists.

       If whack detects a problem, it will return an exit status of 1. If it
       received progress messages from pluto, 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.

FILES

       /var/run/pluto/pluto.pid

       /var/run/pluto/pluto.ctl

       /etc/ipsec.secrets

       $IPSEC_LIBDIR/_pluto_adns

       $IPSEC_EXECDIR/lwdnsq

       /dev/urandom

ENVIRONMENT

       IPSEC_LIBDIR

       IPSEC_EXECDIR

       IPSECmyid

       PLUTO_CORE_DIR

SEE ALSO

       The rest of the Openswan distribution, in particular ipsec(8).

       ipsec_auto(8) is designed to make using pluto more pleasant. Use it!

       ipsec.secrets(5) describes the format of the secrets file.

       ipsec_atoaddr(3), part of the Openswan distribution, describes the
       forms that IP addresses may take.  ipsec_atosubnet(3), part of the
       Openswan distribution, describes the forms that subnet specifications.

       For more information on IPsec, the mailing list, and the relevant
       documents, see:

       http://www.ietf.cnri.reston.va.us/html.charters/ipsec-charter.html

       At the time of writing, the most relevant IETF RFCs are:

       RFC2409 The Internet Key Exchange (IKE)

       RFC2408 Internet Security Association and Key Management Protocol
       (ISAKMP)

       RFC2407 The Internet IP Security Domain of Interpretation for ISAKMP

       The Openswan web site <htp://www.openswan.org> and the mailing lists
       described there.

HISTORY

       This code is released under the GPL terms. See the accompanying files
       COPYING and CREDITS for more details. The GPL does NOT apply to those
       pieces of code written by others which are included in this
       distribution, except as noted by the individual authors.

       This software was originally written for the FreeS/WAN project
       <http://www.freeswan.org>, founded by John Gilmore and managed by Hugh
       Daniel. It was written by Angelos D. Keromytis
       (angelos@dsl.cis.upenn.edu), in May/June 1997, in Athens, Greece.
       Thanks go to John Ioannidis for his help.

       It is currently maintained and extended by Xelerance Corporation, in
       Canada under the Openswan name. See CHANGES for details.

       FreeS/WAN was developed/maintained from 2000-2004 by D. Hugh Redelmeier
       (hugh@mimosa.com), in Canada. The regulations of Greece and Canada
       allow the code to be freely redistributable.

       Kai Martius (admin@imib.med.tu-dresden.de) contributed the initial
       version of the code supporting PFS.

       Richard Guy Briggs <rgb@conscoop.ottawa.on.ca> and Peter Onion
       <ponion@srd.bt.co.uk> added the PFKEY2 support.

       We gratefully acknowledge that we use parts of Eric Young’s libdes
       package; see ../libdes/COPYRIGHT.

BUGS

       pluto is a work-in-progress. It currently has many limitations. For
       example, it ignores notification messages that it receives, and it
       generates only Delete Notifications and those only for IPSEC SAs.

       pluto does not support the Commit Flag. The Commit Flag is a bad
       feature of the IKE protocol. It isn’t protected -- neither encrypted
       nor authenticated. A man in the middle could turn it on, leading to
       DoS. We just ignore it, with a warning. This should let us interoperate
       with implementations that insist on it, with minor damage.

       pluto does not check that the SA returned by the Responder is actually
       one that was proposed. It only checks that the SA is acceptable. The
       difference is not large, but can show up in attributes such as SA
       lifetime.

       There is no good way for a connection to be automatically terminated.
       This is a problem for Road Warrior and Opportunistic connections. The
       --dontrekey option does prevent the SAs from being rekeyed on expiry.
       Additonally, if a Road Warrior connection has a client subnet with a
       fixed IP address, a negotiation with that subnet will cause any other
       connection instantiations with that same subnet to be unoriented
       (deleted, in effect). See also the --uniqueids option for an extension
       of this.

       When pluto sends a message to a peer that has disappeared, pluto
       receives incomplete information from the kernel, so it logs the
       unsatisfactory message “some IKE message we sent has been rejected with
       ECONNREFUSED (kernel supplied no details)”. John Denker suggests that
       this command is useful for tracking down the source of these problems:
       tcpdump -i eth0 icmp[0] != 8 and icmp[0] != 0 Substitute your public
       interface for eth0 if it is different.

       The word “authenticate” is used for two different features. We must
       authenticate each IKE peer to the other. This is an important task of
       Phase 1. Each packet must be authenticated, both in IKE and in IPsec,
       and the method for IPsec is negotiated as an AH SA or part of an ESP
       SA. Unfortunately, the protocol has no mechanism for authenticating the
       Phase 2 identities.

       Bugs should be reported to the <users@lists.openswan.org> mailing list.

[FIXME: source]                 26 October 2006