diff options
Diffstat (limited to 'doc/manpage.d/ipsec_pluto.8.html')
| -rw-r--r-- | doc/manpage.d/ipsec_pluto.8.html | 1824 |
1 files changed, 1824 insertions, 0 deletions
diff --git a/doc/manpage.d/ipsec_pluto.8.html b/doc/manpage.d/ipsec_pluto.8.html new file mode 100644 index 000000000..2e2ce4c2f --- /dev/null +++ b/doc/manpage.d/ipsec_pluto.8.html @@ -0,0 +1,1824 @@ +Content-type: text/html + +<HTML><HEAD><TITLE>Manpage of IPSEC_PLUTO</TITLE> +</HEAD><BODY> +<H1>IPSEC_PLUTO</H1> +Section: Maintenance Commands (8)<BR>Updated: 28 March 1999<BR><A HREF="#index">Index</A> +<A HREF="http://localhost/cgi-bin/man/man2html">Return to Main Contents</A><HR> + +<A NAME="lbAB"> </A> +<H2>NAME</H2> + +ipsec pluto - IPsec IKE keying daemon +<BR> + +ipsec whack - control interface for IPSEC keying daemon +<A NAME="lbAC"> </A> +<H2>SYNOPSIS</H2> + + + +<DL COMPACT> +<DT> +<B> +<DD>ipsec pluto +[--help] +[--version] +[--optionsfrom </B><I>filename</I>] +[--nofork] +[--stderrlog] +[--noklips] +[--uniqueids] +[<B>--interface</B> <I>interfacename</I>] +[--ikeport <I>portnumber</I>] +[--ctlbase <I>path</I>] +[--secretsfile <I>secrets-file</I>] +[--adns <I>pathname</I>] +[--lwdnsq <I>pathname</I>] +[--perpeerlog] +[--perpeerlogbase <I>dirname</I>] +[--debug-none] +[--debug-all] +[--debug-raw] +[--debug-crypt] +[--debug-parsing] +[--debug-emitting] +[--debug-control] +[--debug-lifecycle] +[--debug-klips] +[--debug-dns] +[--debug-oppo] +[--debug-private] +<DT> +<B> +<DD>ipsec whack +[--help] +[--version] +<DT> + +<DD>ipsec whack +--name </B><I>connection-name</I> +<BR> + +[--id <I>id</I>] [--host <I>ip-address</I>] +[--ikeport <I>port-number</I>] +[--nexthop <I>ip-address</I>] +[--client <I>subnet</I>] +[--dnskeyondemand] +[--updown <I>updown</I>] +<BR> + +--to +<BR> + +[--id <I>id</I>] +[--host <I>ip-address</I>] +[--ikeport <I>port-number</I>] +[--nexthop <I>ip-address</I>] +[--client <I>subnet</I>] +[--dnskeyondemand] +[--updown <I>updown</I>] +<BR> + +[--psk] +[--rsasig] +[--encrypt] +[--authenticate] +[--compress] +[--tunnel] +[--pfs] +[--disablearrivalcheck] +[--ipv4] +[--ipv6] +[--tunnelipv4] +[--tunnelipv6] +[--ikelifetime <I>seconds</I>] +[--ipseclifetime <I>seconds</I>] +[--rekeymargin <I>seconds</I>] +[--rekeyfuzz <I>percentage</I>] +[--keyingtries <I>count</I>] +[--dontrekey] +[--delete] +[--ctlbase <I>path</I>] +[--optionsfrom <I>filename</I>] +[--label <I>string</I>] +<DT> +<B> +<DD>ipsec whack +--keyid </B><I>id</I> +[--addkey] +[--pubkeyrsa <I>key</I>] +[--ctlbase <I>path</I>] +[--optionsfrom <I>filename</I>] +[--label <I>string</I>] +<DT> +<B> +<DD>ipsec whack +--myid </B><I>id</I> +<DT> +<B> +<DD>ipsec whack +--listen|--unlisten +[--ctlbase </B><I>path</I>] +[--optionsfrom <I>filename</I>] +[--label <I>string</I>] +<DT> +<B> +<DD>ipsec whack +--route|--unroute +--name </B><I>connection-name</I> +[--ctlbase <I>path</I>] +[--optionsfrom <I>filename</I>] +[--label <I>string</I>] +<DT> +<B> +<DD>ipsec whack +--initiate|--terminate +--name </B><I>connection-name</I> +[--asynchronous] +[--ctlbase <I>path</I>] +[--optionsfrom <I>filename</I>] +[--label <I>string</I>] +<DT> +<B> +<DD>ipsec whack +[--tunnelipv4] +[--tunnelipv6] +--oppohere </B><I>ip-address</I> +--oppothere <I>ip-address</I> +<DT> +<B> +<DD>ipsec whack +--delete +--name </B><I>connection-name</I> +[--ctlbase <I>path</I>] +[--optionsfrom <I>filename</I>] +[--label <I>string</I>] +<DT> +<B> +<DD>ipsec whack +--deletestate </B><I>state-number</I> +[--ctlbase <I>path</I>] +[--optionsfrom <I>filename</I>] +[--label <I>string</I>] +<DT> +<B> +<DD>ipsec whack +[--name </B><I>connection-name</I>] +[--debug-none] +[--debug-all] +[--debug-raw] +[--debug-crypt] +[--debug-parsing] +[--debug-emitting] +[--debug-control] +[--debug-lifecycle] +[--debug-klips] +[--debug-dns] +[--debug-oppo] +[--debug-private] +[--ctlbase <I>path</I>] +[--optionsfrom <I>filename</I>] +[--label <I>string</I>] +<DT> +<B> +<DD>ipsec whack +--status +[--ctlbase </B><I>path</I>] +[--optionsfrom <I>filename</I>] +[--label <I>string</I>] +<DT> +<B> +<DD>ipsec whack +--shutdown +[--ctlbase </B><I>path</I>] +[--optionsfrom <I>filename</I>] +[--label <I>string</I>] + + + +</DL> +<A NAME="lbAD"> </A> +<H2>DESCRIPTION</H2> + +<B>pluto</B> + +is an IKE (``IPsec Key Exchange'') daemon. +<B>whack</B> + +is an auxiliary program to allow requests to be made to a running +<B>pluto</B>. + +<P> + +<B>pluto</B> + +is used to automatically build shared ``security associations'' on a +system that has IPsec, the secure IP protocol. +In other words, +<B>pluto</B> + +can eliminate much of the work of manual keying. +The actual +secure transmission of packets is the responsibility of other parts of +the system (see +<B>KLIPS</B>, + +the companion implementation of IPsec). +<I><A HREF="ipsec_auto.8.html">ipsec_auto</A></I>(8) provides a more convenient interface to +<B>pluto</B> and <B>whack</B>. +<A NAME="lbAE"> </A> +<H3>IKE's Job</H3> + +<P> + +A <I>Security Association</I> (<I>SA</I>) is an agreement between two network nodes on +how to process certain traffic between them. This processing involves +encapsulation, authentication, encryption, or compression. +<P> + +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. +<P> + +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. +<P> + +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. +<P> + +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. +<P> + +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, +but we only implement one called Main Mode (we don't implement +Aggressive Mode). +<P> + +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. +<P> + +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. +<P> + +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. +<P> + +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. +<A NAME="lbAF"> </A> +<H3>Pluto</H3> + +<P> + +<B>pluto</B> 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 +<B>KLIPS</B> implementation of IPsec. +<P> + +<B>pluto</B> only implements a subset of IKE. This is enough for it to +interoperate with other instances of <B>pluto</B>, and many other IKE +implementations. We are working on implementing more of IKE. +<P> + +The policy for acceptable characteristics for Security Associations is +mostly hardwired into the code of <B>pluto</B> (spdb.c). Eventually +this will be moved into a security policy database with reasonable +expressive power and more convenience. +<P> + +<B>pluto</B> uses shared secrets or RSA signatures to authenticate +peers with whom it is negotiating. +<P> + +<B>pluto</B> initiates negotiation of a Security Association when it is +manually prodded: the program <B>whack</B> is run to trigger this. +It will also initiate a negotiation when <B>KLIPS</B> traps an outbound packet +for Opportunistic Encryption. +<P> + +<B>pluto</B> implements ISAKMP SAs itself. After it has negotiated the +characteristics of an IPsec SA, it directs <B>KLIPS</B> to implement it. +It also invokes a script to adjust any firewall and issue <I><A HREF="route.8.html">route</A></I>(8) +commands to direct IP packets through <B>KLIPS</B>. +<P> + +When <B>pluto</B> shuts down, it closes all Security Associations. +<A NAME="lbAG"> </A> +<H3>Before Running Pluto</H3> + +<P> + +<B>pluto</B> runs as a daemon with userid root. Before running it, a few +things must be set up. +<P> + +<B>pluto</B> requires <B>KLIPS</B>, the FreeS/WAN implementation of IPsec. +All of the components of <B>KLIPS</B> and <B>pluto</B> should be installed. +<P> + +<B>pluto</B> 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 <B>--interface</B> option can be used to limit +the interfaces considered). +It does this only when <B>whack</B> tells it to --listen, +so the interfaces must be configured by then. Each interface with a name of the form +<B>ipsec</B>[<B>0</B>-<B>9</B>] is taken as a <B>KLIPS</B> virtual public interface. +Another network interface with the same IP address (there should be only +one) is taken as the corresponding real public +interface. <I><A HREF="ifconfig.8.html">ifconfig</A></I>(8) with the <B>-a</B> flag will show +the name and status of each network interface. +<P> + +<B>pluto</B> requires a database of preshared secrets and RSA private keys. +This is described in the +<I><A HREF="ipsec.secrets.5.html">ipsec.secrets</A></I>(5). + +<B>pluto</B> is told of RSA public keys via <B>whack</B> commands. +If the connection is Opportunistic, and no RSA public key is known, +<B>pluto</B> will attempt to fetch RSA keys using the Domain Name System. +<A NAME="lbAH"> </A> +<H3>Setting up <B>KLIPS</B> for <B>pluto</B></H3> + +<P> + +The most basic network topology that <B>pluto</B> supports has two security +gateways negotiating on behalf of client subnets. The diagram of RGB's +testbed is a good example (see <I>klips/doc/rgb_setup.txt</I>). +<P> + +The file <I>INSTALL</I> in the base directory of this distribution +explains how to start setting up the whole system, including <B>KLIPS</B>. +<P> + +Make sure that the security gateways have routes to each other. This +is usually covered by the default route, but may require issuing +<I><A HREF="route.8.html">route</A></I>(8) + +commands. The route must go through a particular IP +interface (we will assume it is <I>eth0</I>, but it need not be). The +interface that connects the security gateway to its client must be a +different one. +<P> + +It is necessary to issue a +<I><A HREF="ipsec_tncfg.8.html">ipsec_tncfg</A></I>(8) + +command on each gateway. The required command is: +<P> + ipsec tncfg --attach --virtual ipsec0 --physical eth0 +<P> +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 +<I><A HREF="ipsec_tncfg.8.html">ipsec_tncfg</A></I>(8). + +<A NAME="lbAI"> </A> +<H3>ipsec.secrets file</H3> + +<P> + +A <B>pluto</B> daemon and another IKE daemon (for example, another instance +of <B>pluto</B>) 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 <B>pluto</B>. +<P> + +The file <I>/etc/ipsec.secrets</I> is used to keep preshared secret keys +and RSA private keys for +authentication with other IKE daemons. For debugging, there is an +argument to the <B>pluto</B> command to use a different file. +This file is described in +<I><A HREF="ipsec.secrets.5.html">ipsec.secrets</A></I>(5). + +<A NAME="lbAJ"> </A> +<H3>Running Pluto</H3> + +<P> + +To fire up the daemon, just type <B>pluto</B> (be sure to be running as +the superuser). +The default IKE port number is 500, the UDP port assigned by IANA for IKE Daemons. +<B>pluto</B> must be run by the superuser to be able to use the UDP 500 port. +<P> + +<B>pluto</B> attempts to create a lockfile with the name +<I>/var/run/pluto.pid</I>. If the lockfile cannot be created, +<B>pluto</B> exits - this prevents multiple <B>pluto</B>s from +competing Any ``leftover'' lockfile must be removed before +<B>pluto</B> will run. <B>pluto</B> 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). +<P> + +<B>pluto</B> 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. +<P> + +All logging, including diagnostics, is sent to +<I><A HREF="syslog.3.html">syslog</A></I>(3) + +with facility=authpriv; +it decides where to put these messages (possibly in /var/log/secure). +Since this too can make debugging awkward, there is an option to +steer logging to stderr. +<P> + +If the <B>--perpeerlog</B> 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 (/). +<P> + +The base directory can be changed with the <B>--perpeerlogbase</B>. +<P> + +Once <B>pluto</B> is started, it waits for requests from <B>whack</B>. +<A NAME="lbAK"> </A> +<H3>Pluto's Internal State</H3> + +<P> + +To understand how to use <B>pluto</B>, it is helpful to understand a little +about its internal state. Furthermore, the terminology is needed to decipher +some of the diagnostic messages. +<P> + +The <I>(potential) connection</I> database describes attributes of a +connection. These include the IP addresses of the hosts and client +subnets and the security characteristics desired. <B>pluto</B> +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. +<P> + +During the IKE exchange to build an SA, the information about the +negotiation is represented in a <I>state object</I>. 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. +<P> + +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. +<P> + +<B>KLIPS</B> hooks into the routing code in a LINUX kernel. +Traffic to be processed by an IPsec SA must be directed through +<B>KLIPS</B> by routing commands. Furthermore, the processing to be +done is specified by <I>ipsec <A HREF="eroute.8.html">eroute</A>(8)</I> commands. +<B>pluto</B> takes the responsibility of managing both of these special +kinds of routes. +<P> + +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 +(<B>pluto</B>'s logic does not reflect any advanced routing capabilities). +<P> + +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). +<P> + +When <B>pluto</B> 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. +<P> + +There is an exception. If <B>pluto</B>, 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). +<P> + +When <B>pluto</B> 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. +<P> + +All of these routing characteristics are expected change when +<B>KLIPS</B> is modified to use the firewall hooks in the LINUX 2.4.x +kernel. +<A NAME="lbAL"> </A> +<H3>Using Whack</H3> + +<P> + +<B>whack</B> is used to command a running <B>pluto</B>. +<B>whack</B> uses a UNIX domain socket to speak to <B>pluto</B> +(by default, <I>/var/pluto.ctl</I>). +<P> + +<B>whack</B> 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 <B>pluto</B> a description of a potential connection. +The public key form informs <B>pluto</B> 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 <B>pluto</B> to start or stop listening on the public interfaces +for IKE requests from peers. +The route form tells <B>pluto</B> to set up routing for a connection; +the unroute form undoes this. +The initiate form tells <B>pluto</B> to negotiate an SA corresponding to a connection. +The terminate form tells <B>pluto</B> to remove all SAs corresponding to a connection, +including those being negotiated. +The status form displays the <B>pluto</B>'s internal state. +The debug form tells <B>pluto</B> to change the selection of debugging output +``on the fly''. The shutdown form tells +<B>pluto</B> to shut down, deleting all SAs. +<P> + +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. +<DL COMPACT> +<DT><B>--ctlbase</B> <I>path</I><DD> +<I>path</I>.ctl is used as the UNIX domain socket for talking +to <B>pluto</B>. +This option facilitates debugging. +<DT><B>--optionsfrom</B> <I>filename</I><DD> +adds the contents of the file to the argument list. +<DT><B>--label</B> <I>string</I><DD> +adds the string to all error messages generated by <B>whack</B>. +</DL> +<P> + +The help form of <B>whack</B> is self-explanatory. +<DL COMPACT> +<DT><B>--help</B><DD> +display the usage message. +<DT><B>--version</B><DD> +display the version of <B>whack</B>. +</DL> +<P> + +The connection form describes a potential connection to <B>pluto</B>. +<B>pluto</B> needs to know what connections can and should be negotiated. +When <B>pluto</B> is the initiator, it needs to know what to propose. +When <B>pluto</B> is the responder, it needs to know enough to decide whether +is is willing to set up the proposed connection. +<P> + +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. +<DL COMPACT> +<DT><B>--name</B> <I>connection-name</I><DD> +</DL> +<P> + +The topology of +a connection is symmetric, so to save space here is half a picture: +<P> + client_subnet<-->host:ikeport<-->nexthop<--- +<P> +A similar trick is used in the flags. The same flag names are used for +both ends. Those before the <B>--to</B> flag describe the left side +and those afterwards describe the right side. When <B>pluto</B> 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. +<DL COMPACT> +<DT><B>--id</B> <I>id</I><DD> +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 <A HREF="mailto:user@FQDN">user@FQDN</A>, or as the +magic value <B>%myid</B>. +<B>Pluto</B> 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 <B>--host</B>. +<B>%myid</B> allows the identity to be separately specified (by the <B>pluto</B> or <B>whack</B> option <B>--myid</B> +or by the <B><A HREF="ipsec.conf.5.html">ipsec.conf</A></B>(5) <B>config setup</B> parameter myid). +Otherwise, <B>pluto</B> tries to guess what <B>%myid</B> should stand for: +the IP address of <B>%defaultroute</B>, 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. + +<DT><B>--host</B> <I>ip-address</I><DD> +<DT><B>--host</B> <B>%any</B><DD> +<DT><B>--host</B> <B>%opportunistic</B><DD> +the IP address of the end (generally the public interface). +If <B>pluto</B> 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 <B>%any</B> (currently, +the obsolete notation <B>0.0.0.0</B> is also accepted for this). +If <B>pluto</B> is to opportunistically initiate the connection, +use <B>%opportunistic</B> +<DT><B>--ikeport</B> <I>port-number</I><DD> +the UDP port that IKE listens to on that host. The default is 500. +(<B>pluto</B> on this machine uses the port specified by its own command +line argument, so this only affects where <B>pluto</B> sends messages.) +<DT><B>--nexthop</B> <I>ip-address</I><DD> +where to route packets for the peer's client (presumably for the peer too, +but it will not be used for this). +When <B>pluto</B> 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 +<B>%direct</B>; the obsolete notation <B>0.0.0.0</B> is accepted). +This option is necessary if <B>pluto</B>'s host's interface used for sending +packets to the peer is neither point-to-point nor directly connected to the +peer. +<DT><B>--client</B> <I>subnet</I><DD> +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 <I><A HREF="ipsec_atosubnet.3.html">ipsec_atosubnet</A></I>(3). +The general form is <I>address</I>/<I>mask</I>. The <I>address</I> can be either +a domain name or four decimal numbers (specifying octets) separated by dots. +The most convenient form of the <I>mask</I> 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''. +<DT><B>--dnskeyondemand]</B><DD> +specifies that when an RSA public key is needed to authenticate this +host, and it isn't already known, fetch it from DNS. +<DT><B>--updown</B> <I>updown</I><DD> +specifies an external shell command to be run whenever <B>pluto</B> +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 <I>ipsec _updown</I>. +<DT><B>--to</B><DD> +separates the specification of the left and right ends of the connection. +</DL> +<P> + +The potential connection description also specifies characteristics of +rekeying and security. +<DL COMPACT> +<DT><B>--psk</B><DD> +Propose and allow preshared secret authentication for IKE peers. This authentication +requires that each side use the same secret. May be combined with <B>--rsasig</B>; +at least one must be specified. +<DT><B>--rsasig</B><DD> +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 <B>--psk</B>; +at least one must be specified. +<DT><B>--encrypt</B><DD> +All proposed or accepted IPsec SAs will include non-null ESP. +The actual choices of transforms are wired into <B>pluto</B>. +<DT><B>--authenticate</B><DD> +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 <B>pluto</B>. +Note that this has nothing to do with IKE authentication. +<DT><B>--compress</B><DD> +All proposed IPsec SAs will include IPCOMP (compression). +This will be ignored if KLIPS is not configured with IPCOMP support. +<DT><B>--tunnel</B><DD> +the IPsec SA should use tunneling. Implicit if the SA is for clients. +Must only be used with <B>--authenticate</B> or <B>--encrypt</B>. +<DT><B>--ipv4</B><DD> +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). +<DT><B>--ipv6</B><DD> +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). +<DT><B>--tunnelipv4</B><DD> +The client addresses will be interpreted as IPv4 addresses. The default is +to match what the host will be. This does not imply <B>--tunnel</B> 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. +<DT><B>--tunnelipv6</B><DD> +The client addresses will be interpreted as IPv6 addresses. The default is +to match what the host will be. This does not imply <B>--tunnel</B> 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. +<DT><B>--pfs</B><DD> +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), <B>pluto</B> 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. +<DT><B>--disablearrivalcheck</B><DD> +If the connection is a tunnel, allow packets arriving through the tunnel +to have any source and destination addresses. +</DL> +<P> + +If none of the <B>--encrypt</B>, <B>--authenticate</B>, <B>--compress</B>, +or <B>--pfs</B> 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. +<P> + +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; 3DES encryption; SHA1-96 +and MD5-96 authentication. The IPsec SAs may use 3DES and +MD5-96 or SHA1-96 for ESP, or just MD5-96 or SHA1-96 for AH. +IPCOMP Compression is always Deflate. +<DL COMPACT> +<DT><B>--ikelifetime</B> <I>seconds</I><DD> +how long <B>pluto</B> will propose that an ISAKMP SA be allowed to live. +The default is 3600 (one hour) and the maximum is 28800 (8 hours). +This option will not affect what is accepted. +<B>pluto</B> will reject proposals that exceed the maximum. +<DT><B>--ipseclifetime</B> <I>seconds</I><DD> +how long <B>pluto</B> 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. +<B>pluto</B> will reject proposals that exceed the maximum. +<DT><B>--rekeymargin</B> <I>seconds</I><DD> +how long before an SA's expiration should <B>pluto</B> try to negotiate +a replacement SA. This will only happen if <B>pluto</B> was the initiator. +The default is 540 (nine minutes). +<DT><B>--rekeyfuzz</B> <I>percentage</I><DD> +maximum size of random component to add to rekeymargin, expressed as +a percentage of rekeymargin. <B>pluto</B> 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. +<DT><B>--keyingtries</B> <I>count</I><DD> +how many times <B>pluto</B> 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. +<DT><B>--dontrekey</B><DD> +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. +<BR> + +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 <B>--dontrekey</B>. 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. +<DT><B>--delete</B><DD> +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. +</DL> +<P> + +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. +<DL COMPACT> +<DT><B>--delete</B><DD> +<DT><B>--name</B> <I>connection-name</I><DD> +</DL> +<P> + +The deletestate form deletes the state object with the specified serial number. +This is useful for selectively deleting instances of connections. +<DL COMPACT> +<DT><B>--deletestate</B> <I>state-number</I><DD> +</DL> +<P> + +The route form of the <B>whack</B> command tells <B>pluto</B> 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 <B>whack</B> route is not always needed: if it hasn't been +done when an IPsec SA is being installed, one will be automatically attempted. +<P> + +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. +<DL COMPACT> +<DT><B>--route</B><DD> +<DT><B>--name</B> <I>connection-name</I><DD> +</DL> +<P> + +The unroute form of the <B>whack</B> command tells <B>pluto</B> to undo +a routing. <B>pluto</B> 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. +<DL COMPACT> +<DT><B>--unroute</B><DD> +<DT><B>--name</B> <I>connection-name</I><DD> +</DL> +<P> + +The initiate form tells <B>pluto</B> to initiate a negotiation with another +<B>pluto</B> (or other IKE daemon) according to the named connection. +Initiation requires a route that <B>--route</B> would provide; +if none is in place at the time an IPsec SA is being installed, +<B>pluto</B> attempts to set one up. +<DL COMPACT> +<DT><B>--initiate</B><DD> +<DT><B>--name</B> <I>connection-name</I><DD> +<DT><B>--asynchronous<DD> +</DL> +<P> + +The initiate form of the whack</B> command will relay back from +<B>pluto</B> status information via the UNIX domain socket (unless +--asynchronous is specified). The status information is meant to +look a bit like that from <B>FTP</B>. Currently <B>whack</B> simply +copies this to stderr. When the request is finished (eg. the SAs are +established or <B>pluto</B> gives up), <B>pluto</B> closes the channel, +causing <B>whack</B> to terminate. +<P> + +The opportunistic initiate form is mainly used for debugging. +<DL COMPACT> +<DT><B>--tunnelipv4</B><DD> +<DT><B>--tunnelipv6</B><DD> +<DT><B>--oppohere</B> <I>ip-address</I><DD> +<DT><B>--oppothere</B> <I>ip-address</I><DD> +</DL> +<P> + +This will cause <B>pluto</B> 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. +<P> + +The terminate form tells <B>pluto</B> 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). +<DL COMPACT> +<DT><B>--terminate</B><DD> +<DT><B>--name</B> <I>connection-name</I><DD> +</DL> +<P> + +The public key for informs <B>pluto</B> of the RSA public key for a potential peer. +Private keys must be kept secret, so they are kept in +<I><A HREF="ipsec.secrets.5.html">ipsec.secrets</A></I>(5). + +<DL COMPACT> +<DT><B>--keyid </B><I>id</I><DD> +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, <B>pluto</B> 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. +<DT><B>--addkey</B><DD> +specifies that the new key is added to the collection; otherwise the +new key replaces any old ones. +<DT><B>--pubkeyrsa </B><I>key</I><DD> +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 <I><A HREF="ipsec_ttodata.3.html">ipsec_ttodata</A></I>(3). +For example, a base 64 numeral starts with 0s. +</DL> +<P> + +The listen form tells <B>pluto</B> to start listening for IKE requests +on its public interfaces. To avoid race conditions, it is normal to +load the appropriate connections into <B>pluto</B> before allowing it +to listen. If <B>pluto</B> isn't listening, it is pointless to +initiate negotiations, so it will refuse requests to do so. Whenever +the listen form is used, <B>pluto</B> 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 <B>pluto</B> to read the +<I>ipsec.secrets</I> file. So listen may useful more than once. +<DL COMPACT> +<DT><B>--listen</B><DD> +start listening for IKE traffic on public interfaces. +<DT><B>--unlisten</B><DD> +stop listening for IKE traffic on public interfaces. +</DL> +<P> + +The status form will display information about the internal state of +<B>pluto</B>: information about each potential connection, about +each state object, and about each shunt that <B>pluto</B> is managing +without an associated connection. +<DL COMPACT> +<DT><B>--status</B><DD> +</DL> +<P> + +The shutdown form is the proper way to shut down <B>pluto</B>. +It will tear down the SAs on this machine that <B>pluto</B> has negotiated. +It does not inform its peers, so the SAs on their machines remain. +<DL COMPACT> +<DT><B>--shutdown</B><DD> +</DL> +<A NAME="lbAM"> </A> +<H3>Examples</H3> + +<P> + +It would be normal to start <B>pluto</B> 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 +<P> + ipsec pluto +<P> +The command will immediately return, but a <B>pluto</B> process will be left +running, waiting for requests from <B>whack</B> or a peer. +<P> + +Using <B>whack</B>, several potential connections would be described: +<DL COMPACT> +<DT> + + ipsec whack --name silly +--host 127.0.0.1 --to --host 127.0.0.2 +--ikelifetime 900 --ipseclifetime 800 --keyingtries 3 + +</DL> +<P> + +<DD>Since this silly connection description specifies neither encryption, +authentication, nor tunneling, it could only be used to establish +an ISAKMP SA. +<DL COMPACT> +<DT> + + 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 + +</DL> +<P> + +<DD>This is something that must be done on both sides. If the other +side is <B>pluto</B>, the same <B>whack</B> command could be used on it +(the command syntax is designed to not distinguish which end is ours). +<P> + +Now that the connections are specified, <B>pluto</B> 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: +<P> + ipsec whack --listen +<P> + +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 <B>pluto</B> 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: +<P> + ipsec whack --route secret +<P> + +Finally, we are ready to get <B>pluto</B> to initiate negotiation +for an IPsec SA (and implicitly, an ISAKMP SA): +<P> + ipsec whack --initiate --name secret +<P> +A small log of interesting events will appear on standard output +(other logging is sent to syslog). +<P> + +<B>whack</B> can also be used to terminate <B>pluto</B> cleanly, tearing down +all SAs that it has negotiated. +<P> + ipsec whack --shutdown +<P> +Notification of any IPSEC SA deletion, but not ISAKMP SA deletion +is sent to the peer. Unfortunately, such Notification is not reliable. +Furthermore, <B>pluto</B> itself ignores Notifications. +<A NAME="lbAN"> </A> +<H3>The updown command</H3> + +<P> + +Whenever <B>pluto</B> brings a connection up or down, it invokes +the updown command. This command is specified using the <B>--updown</B> +option. This allows for customized control over routing and firewall manipulation. +<P> + +The updown is invoked for five different operations. Each of +these operations can be for our client subnet or for our host itself. +<DL COMPACT> +<DT><B>prepare-host</B> or <B>prepare-client</B><DD> +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 <B>pluto</B> was run or +perhaps by some agent not known to <B>pluto</B>. +<DT><B>route-host</B> or <B>route-client</B><DD> +is run when bringing up a connection for a new peer client subnet +(even if <B>prepare-host</B> or <B>prepare-client</B> 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. +<DT><B>unroute-host</B> or <B>unroute-client</B><DD> +is run when bringing down the last connection for a particular peer +client subnet. It should undo what the <B>route-host</B> or <B>route-client</B> +did. +<DT><B>up-host</B> or <B>up-client</B><DD> +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. +<DT><B>down-host</B> or <B>down-client</B><DD> +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. +</DL> +<P> + +The script is passed a large number of environment variables to specify +what needs to be done. +<DL COMPACT> +<DT><B>PLUTO_VERSION</B><DD> +indicates what version of this interface is being used. This document +describes version 1.1. This is upwardly compatible with version 1.0. +<DT><B>PLUTO_VERB</B><DD> +specifies the name of the operation to be performed +(<B>prepare-host</B>,r <B>prepare-client</B>, +<B>up-host</B>, <B>up-client</B>, +<B>down-host</B>, or <B>down-client</B>). If the address family for +security gateway to security gateway communications is IPv6, then +a suffix of -v6 is added to the verb. +<DT><B>PLUTO_CONNECTION</B><DD> +is the name of the connection for which we are routing. +<DT><B>PLUTO_NEXT_HOP</B><DD> +is the next hop to which packets bound for the peer must be sent. +<DT><B>PLUTO_INTERFACE</B><DD> +is the name of the ipsec interface to be used. +<DT><B>PLUTO_ME</B><DD> +is the IP address of our host. +<DT><B>PLUTO_MY_CLIENT</B><DD> +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). +<DT><B>PLUTO_MY_CLIENT_NET</B><DD> +is the IP address of our client net. +If the client is just the host, this will be the host's own IP address. +<DT><B>PLUTO_MY_CLIENT_MASK</B><DD> +is the mask for our client net. +If the client is just the host, this will be 255.255.255.255. +<DT><B>PLUTO_PEER</B><DD> +is the IP address of our peer. +<DT><B>PLUTO_PEER_CLIENT</B><DD> +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). +<DT><B>PLUTO_PEER_CLIENT_NET</B><DD> +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. +<DT><B>PLUTO_PEER_CLIENT_MASK</B><DD> +is the mask for the peer's client net. +If the client is just the peer, this will be 255.255.255.255. +</DL> +<P> + +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. +<P> + +<B>Pluto</B> waits for the script to finish and will not do any other +processing while it is waiting. +The script may assume that <B>pluto</B> 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 <B>pluto</B>. +Either of these activities could be performed by a background +subprocess of the script. +<A NAME="lbAO"> </A> +<H3>Rekeying</H3> + +<P> + +When an SA that was initiated by <B>pluto</B> has only a bit of +lifetime left, +<B>pluto</B> 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. +<P> + +Similarly, when an SA that was initiated by the peer has only a bit of +lifetime left, <B>pluto</B> 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. +<P> + +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. +<P> + +<B>pluto</B> 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. +<P> + +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. +<P> + +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. +<P> + +Once a new set of SAs has been negotiated, <B>pluto</B> will never send +traffic on a superseded one. Traffic will be accepted on an old SA +until it expires. +<A NAME="lbAP"> </A> +<H3>Selecting a Connection When Responding: Road Warrior Support</H3> + +<P> + +When <B>pluto</B> 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.) +<P> + +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. +<P> + +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. +<P> + +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 <B>%any</B> +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 <B>%any</B> 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. +<P> + +When <B>pluto</B> is using one of these temporary connections and +needs to find the preshared secret or RSA private key in <I>ipsec.secrets</I>, +and and the connection specified no identity for the peer, <B>%any</B> +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. +<P> + +Part way into the Phase 1 (Main Mode) negotiation using one of these +temporary connection descriptions, <B>pluto</B> will be receive an +Identity Payload. At this point, <B>pluto</B> 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 <B>%any</B> +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, <B>pluto</B> terminates negotiation. +<P> + +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). +<P> + +When <B>pluto</B> 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 <B>%any</B> +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, <B>pluto</B> terminates negotiation. +<P> + +Be sure to specify an appropriate nexthop for the responder +to send a message to the initiator: <B>pluto</B> has no way of guessing +it (if forwarding isn't required, use an explicit <B>%direct</B> as the nexthop +and the IP address of the initiator will be filled in; the obsolete +notation <B>0.0.0.0</B> is still accepted). +<P> + +<B>pluto</B> 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. +<B>pluto</B> has no mechanism to do this automatically. +<P> + +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. +<P> + +If any Road Warrior connections are supported, <B>pluto</B> 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. +<P> + +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 <B>--keyingtries</B> 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. +<A NAME="lbAQ"> </A> +<H3>Debugging</H3> + +<P> + +<B>pluto</B> accepts several optional arguments, useful mostly for debugging. +Except for <B>--interface</B>, each should appear at most once. +<DL COMPACT> +<DT><B>--interface</B> <I>interfacename</I><DD> +specifies that the named real public network interface should be considered. +The interface name specified should not be <B>ipsec</B><I>N</I>. +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. +<DT><B>--ikeport</B> <I>port-number</I><DD> +changes the UDP port that <B>pluto</B> will use +(default, specified by IANA: 500) +<DT><B>--ctlbase</B> <I>path</I><DD> +basename for control files. +<I>path</I>.ctl is the socket through which <B>whack</B> communicates with +<B>pluto</B>. +<I>path</I>.pid is the lockfile to prevent multiple <B>pluto</B> instances. +The default is <I>/var/run/pluto</I>). +<DT><B>--secretsfile</B> <I>file</I><DD> +specifies the file for authentication secrets +(default: <I>/etc/ipsec.secrets</I>). +This name is subject to ``globbing'' as in <I><A HREF="sh.1.html">sh</A></I>(1), +so every file with a matching name is processed. +Quoting is generally needed to prevent the shell from doing the globbing. +<DT><B>--adns</B> <I>pathname</I><DD> +<DT><B>--lwdnsq</B> <I>pathname</I><DD> +specifies where to find <B>pluto</B>'s helper program for asynchronous DNS lookup. +<B>pluto</B> can be built to use one of two helper programs: <B>_pluto_adns</B> +or <B>lwdnsq</B>. You must use the program for which it was built. +By default, <B>pluto</B> will look for the program in +<B>$IPSEC_DIR</B> (if that environment variable is defined) or, failing that, +in the same directory as <B>pluto</B>. +<DT><B>--nofork</B><DD> +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. +<DT><B>--noklips</B><DD> +don't actually implement negotiated IPsec SAs +<DT><B>--uniqueids</B><DD> +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. +<DT><B>--stderrlog</B><DD> +log goes to standard out {default is to use <I><A HREF="syslogd.8.html">syslogd</A></I>(8)) +</DL> +<P> + +For example +<DL COMPACT> +<DT>pluto --secretsfile ipsec.secrets --ctlbase pluto.base --ikeport 8500 --nofork --noklips --stderrlog<DD> +</DL> +<P> + +lets one test <B>pluto</B> without using the superuser account. +<P> + +<B>pluto</B> 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 <B>pluto</B> may be directed to +produce a selection of them. All lines of +debugging output are prefixed with ``| '' to distinguish them from error +messages. +<P> + +When <B>pluto</B> is invoked, it may be given arguments to specify +which classes to output. The current options are: +<DL COMPACT> +<DT><B>--debug-raw</B><DD> +show the raw bytes of messages +<DT><B>--debug-crypt</B><DD> +show the encryption and decryption of messages +<DT><B>--debug-parsing</B><DD> +show the structure of input messages +<DT><B>--debug-emitting</B><DD> +show the structure of output messages +<DT><B>--debug-control</B><DD> +show <B>pluto</B>'s decision making +<DT><B>--debug-lifecycle</B><DD> +[this option is temporary] log more detail of lifecycle of SAs +<DT><B>--debug-klips</B><DD> +show <B>pluto</B>'s interaction with <B>KLIPS</B> +<DT><B>--debug-dns</B><DD> +show <B>pluto</B>'s interaction with <B>DNS</B> for KEY and TXT records +<DT><B>--debug-oppo</B><DD> +show why <B>pluto</B> didn't find a suitable DNS TXT record to authorize opportunistic initiation +<DT><B>--debug-all</B><DD> +all of the above +<DT><B>--debug-private</B><DD> +allow debugging output with private keys. +<DT><B>--debug-none</B><DD> +none of the above +</DL> +<P> + +The debug form of the +<B>whack</B> command will change the selection in a running +<B>pluto</B>. +If a connection name is specified, the flags are added whenever +<B>pluto</B> has identified that it is dealing with that connection. +Unfortunately, this is often part way into the operation being observed. +<P> + +For example, to start a <B>pluto</B> with a display of the structure of input +and output: +<DL COMPACT> +<DT><DD> +pluto --debug-emitting --debug-parsing +</DL> +<P> + +To later change this <B>pluto</B> to only display raw bytes: +<DL COMPACT> +<DT><DD> +whack --debug-raw +</DL> +<P> + +For testing, SSH's IKE test page is quite useful: +<DL COMPACT> +<DT><DD> +<I><A HREF="http://isakmp-test.ssh.fi/">http://isakmp-test.ssh.fi/</A></I> +</DL> +<P> + +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. <B>pluto</B> is not yet smart enough to get out of such a +mess. +<A NAME="lbAR"> </A> +<H3>Pluto's Behaviour When Things Go Wrong</H3> + +<P> + +When <B>pluto</B> 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. +<P> + +When <B>pluto</B> 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. +<P> + +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. +<P> + +Combine these three rules, and you can explain many apparently +mysterious behaviours. In a <B>pluto</B> log, retrying isn't usually the +interesting event. The critical thing is either earlier (<B>pluto</B> +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 (<B>pluto</B> didn't send a reply because it wasn't happy with +the previous message). +<A NAME="lbAS"> </A> +<H3>Notes</H3> + +<P> + +If <B>pluto</B> 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 <B>pluto</B> to be tested on systems +without <B>KLIPS</B>, but makes it rather useless. +<P> + +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. +<B>Pluto</B> also avoids choosing an SPI in the range 0x100 to 0xFFF, +leaving these SPIs free for manual keying. +Remember that the peer, if not <B>pluto</B>, may well chose +SPIs in this range. +<A NAME="lbAT"> </A> +<H3>Policies</H3> + +<P> + +This catalogue of policies may be of use when trying to configure +<B>Pluto</B> and another IKE implementation to interoperate. +<P> + +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. +<P> + +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. +<P> + +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 <A HREF="HASH.3.html">HASH</A>(3). +<DL COMPACT> +<DT>*<DD> +Diffie Hellman Groups MODP 1024 and MODP 1536 (2 and 5) +are supported. +Group MODP768 (1) is not supported because it is too weak. +<DT>*<DD> +Host authetication can be done by RSA Signatures or Pre-Shared +Secrets. +<DT>*<DD> +3DES CBC (Cypher Block Chaining mode) is the only encryption +supported, both for ISAKMP SAs and IPSEC SAs. +<DT>*<DD> +MD5 and SHA1 hashing are supported for packet authentication in both +kinds of SAs. +<DT>*<DD> +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. +<DT>*<DD> +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. +<DT>*<DD> +The IPSEC SAs may be tunnel or transport mode, where appropriate. +The --tunnel flag controls this when <B>pluto</B> is initiating. +<DT>*<DD> +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 <B>pluto</B> +is initiating. +<DT>*<DD> +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 <B>pluto</B> +is initiating. +<DT>*<DD> +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. +</DL> +<A NAME="lbAU"> </A> +<H2>SIGNALS</H2> + +<P> + +<B>Pluto</B> responds to <B>SIGHUP</B> by issuing a suggestion that ``<B>whack</B> +--listen'' might have been intended. +<P> + +<B>Pluto</B> exits when it recieves <B>SIGTERM</B>. +<A NAME="lbAV"> </A> +<H2>EXIT STATUS</H2> + +<P> + +<B>pluto</B> normally forks a daemon process, so the exit status is +normally a very preliminary result. +<DL COMPACT> +<DT>0<DD> +means that all is OK so far. +<DT>1<DD> +means that something was wrong. +<DT>10<DD> +means that the lock file already exists. +</DL> +<P> + +If <B>whack</B> detects a problem, it will return an exit status of 1. +If it received progress messages from <B>pluto</B>, 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. +<A NAME="lbAW"> </A> +<H2>FILES</H2> + +<I>/var/run/pluto.pid</I> +<BR> + +<I>/var/run/pluto.ctl</I> +<BR> + +<I>/etc/ipsec.secrets</I> +<BR> + +<I>$IPSEC_LIBDIR/_pluto_adns</I> +<BR> + +<I>$IPSEC_EXECDIR/lwdnsq</I> +<BR> + +<I>/dev/urandom</I> +<A NAME="lbAX"> </A> +<H2>ENVIRONMENT</H2> + +<I>IPSEC_LIBDIR</I> +<BR> + +<I>IPSEC_EXECDIR</I> +<BR> + +<I>IPSECmyid</I> +<A NAME="lbAY"> </A> +<H2>SEE ALSO</H2> + +<P> + +The rest of the FreeS/WAN distribution, in particular <I><A HREF="ipsec.8.html">ipsec</A></I>(8). +<P> + +<I><A HREF="ipsec_auto.8.html">ipsec_auto</A></I>(8) is designed to make using <B>pluto</B> more pleasant. +Use it! +<P> + +<I><A HREF="ipsec.secrets.5.html">ipsec.secrets</A></I>(5) + +describes the format of the secrets file. +<P> + +<I><A HREF="ipsec_atoaddr.3.html">ipsec_atoaddr</A></I>(3), part of the FreeS/WAN distribution, describes the +forms that IP addresses may take. +<I><A HREF="ipsec_atosubnet.3.html">ipsec_atosubnet</A></I>(3), part of the FreeS/WAN distribution, describes the +forms that subnet specifications. +<P> + +For more information on IPsec, the mailing list, and the relevant +documents, see: +<DL COMPACT> +<DT><DD> + +<I><A HREF="http://www.ietf.cnri.reston.va.us/html.charters/ipsec-charter.html">http://www.ietf.cnri.reston.va.us/html.charters/ipsec-charter.html</A></I> + +</DL> +<P> + +At the time of writing, the most relevant IETF RFCs are: +<DL COMPACT> +<DT><DD> +RFC2409 The Internet Key Exchange (IKE) +<DT><DD> +RFC2408 Internet Security Association and Key Management Protocol (ISAKMP) +<DT><DD> +RFC2407 The Internet IP Security Domain of Interpretation for ISAKMP +</DL> +<P> + +The FreeS/WAN web site <<A HREF="htp://www.freeswan.org">htp://www.freeswan.org</A>> +and the mailing lists described there. +<A NAME="lbAZ"> </A> +<H2>HISTORY</H2> + +This code is released under the GPL terms. +See the accompanying file COPYING-2.0 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. +<P> + +This software was originally written +for the FreeS/WAN project +<<A HREF="http://www.freeswan.org">http://www.freeswan.org</A>> +by Angelos D. Keromytis +(<A HREF="mailto:angelos@dsl.cis.upenn.edu">angelos@dsl.cis.upenn.edu</A>), in May/June 1997, in Athens, Greece. +Thanks go to John Ioannidis for his help. +<P> + +It is currently (2000) +being developed and maintained by D. Hugh Redelmeier +(<A HREF="mailto:hugh@mimosa.com">hugh@mimosa.com</A>), in Canada. The regulations of Greece and Canada +allow us to make the code freely redistributable. +<P> + +Kai Martius (<A HREF="mailto:admin@imib.med.tu-dresden.de">admin@imib.med.tu-dresden.de</A>) contributed the initial +version of the code supporting PFS. +<P> + +Richard Guy Briggs <<A HREF="mailto:rgb@conscoop.ottawa.on.ca">rgb@conscoop.ottawa.on.ca</A>> and Peter Onion +<<A HREF="mailto:ponion@srd.bt.co.uk">ponion@srd.bt.co.uk</A>> added the PFKEY2 support. +<P> + +We gratefully acknowledge that we use parts of Eric Young's <I>libdes</I> +package; see <I>../libdes/COPYRIGHT</I>. +<A NAME="lbBA"> </A> +<H2>BUGS</H2> + +<B>pluto</B> + +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. +<P> + +<B>pluto</B> 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. +<P> + +<B>pluto</B> 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. +<P> + +There is no good way for a connection to be automatically terminated. +This is a problem for Road Warrior and Opportunistic connections. +The <B>--dontrekey</B> 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. +<P> + +When <B>pluto</B> sends a message to a peer that has disappeared, +<B>pluto</B> 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: +<BR> + +<TT> </TT>tcpdump -i eth0 icmp[0] != 8 and icmp[0] != 0<BR> +<BR> + +Substitute your public interface for eth0 if it is different. +<P> + +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. +<P> + +Bugs should be reported to the <<A HREF="mailto:users@lists.freeswan.org">users@lists.freeswan.org</A>> mailing list. +Caution: we cannot accept +actual code from US residents, or even US citizens living outside the +US, because that would bring FreeS/WAN under US export law. Some +other countries cause similar problems. In general, we would prefer +that you send detailed problem reports rather than code: we want +FreeS/WAN to be unquestionably freely exportable, which means being +very careful about where the code comes from, and for a small bug fix, +that is often more time-consuming than just reinventing the fix +ourselves. +<P> + +<HR> +<A NAME="index"> </A><H2>Index</H2> +<DL> +<DT><A HREF="#lbAB">NAME</A><DD> +<DT><A HREF="#lbAC">SYNOPSIS</A><DD> +<DT><A HREF="#lbAD">DESCRIPTION</A><DD> +<DL> +<DT><A HREF="#lbAE">IKE's Job</A><DD> +<DT><A HREF="#lbAF">Pluto</A><DD> +<DT><A HREF="#lbAG">Before Running Pluto</A><DD> +<DT><A HREF="#lbAH">Setting up <B>KLIPS</B> for <B>pluto</B></A><DD> +<DT><A HREF="#lbAI">ipsec.secrets file</A><DD> +<DT><A HREF="#lbAJ">Running Pluto</A><DD> +<DT><A HREF="#lbAK">Pluto's Internal State</A><DD> +<DT><A HREF="#lbAL">Using Whack</A><DD> +<DT><A HREF="#lbAM">Examples</A><DD> +<DT><A HREF="#lbAN">The updown command</A><DD> +<DT><A HREF="#lbAO">Rekeying</A><DD> +<DT><A HREF="#lbAP">Selecting a Connection When Responding: Road Warrior Support</A><DD> +<DT><A HREF="#lbAQ">Debugging</A><DD> +<DT><A HREF="#lbAR">Pluto's Behaviour When Things Go Wrong</A><DD> +<DT><A HREF="#lbAS">Notes</A><DD> +<DT><A HREF="#lbAT">Policies</A><DD> +</DL> +<DT><A HREF="#lbAU">SIGNALS</A><DD> +<DT><A HREF="#lbAV">EXIT STATUS</A><DD> +<DT><A HREF="#lbAW">FILES</A><DD> +<DT><A HREF="#lbAX">ENVIRONMENT</A><DD> +<DT><A HREF="#lbAY">SEE ALSO</A><DD> +<DT><A HREF="#lbAZ">HISTORY</A><DD> +<DT><A HREF="#lbBA">BUGS</A><DD> +</DL> +<HR> +This document was created by +<A HREF="http://localhost/cgi-bin/man/man2html">man2html</A>, +using the manual pages.<BR> +Time: 21:40:18 GMT, November 11, 2003 +</BODY> +</HTML> |