diff options
Diffstat (limited to 'src/pluto/pluto.8')
| -rw-r--r-- | src/pluto/pluto.8 | 1649 |
1 files changed, 1649 insertions, 0 deletions
diff --git a/src/pluto/pluto.8 b/src/pluto/pluto.8 new file mode 100644 index 000000000..b80d13772 --- /dev/null +++ b/src/pluto/pluto.8 @@ -0,0 +1,1649 @@ +.TH IPSEC_PLUTO 8 "28 March 1999" +.SH NAME +ipsec pluto \- IPsec IKE keying daemon +.br +ipsec whack \- control interface for IPSEC keying daemon +.SH SYNOPSIS +.na +.nh +.HP +.ft B +ipsec pluto +[\-\-help] +[\-\-version] +[\-\-optionsfrom\ \c +\fIfilename\fP] +[\-\-nofork] +[\-\-stderrlog] +[\-\-noklips] +[\-\-uniqueids] +[\fB\-\-interface\fP \fIinterfacename\fP] +[\-\-ikeport\ \c +\fIportnumber\fP] +[\-\-ctlbase\ \c +\fIpath\fP] +[\-\-secretsfile\ \c +\fIsecrets\(hyfile\fP] +[\-\-adns \fIpathname\fP] +[\-\-lwdnsq \fIpathname\fP] +[\-\-perpeerlog] +[\-\-perpeerlogbase\ \c +\fIdirname\fP] +[\-\-debug\(hynone] +[\-\-debug\(hyall] +[\-\-debug\(hyraw] +[\-\-debug\(hycrypt] +[\-\-debug\(hyparsing] +[\-\-debug\(hyemitting] +[\-\-debug\(hycontrol] +[\-\-debug\(hylifecycle] +[\-\-debug\(hyklips] +[\-\-debug\(hydns] +[\-\-debug\(hyoppo] +[\-\-debug\(hyprivate] +.HP +.ft B +ipsec whack +[\-\-help] +[\-\-version] +.HP +.ft B +ipsec whack +\-\-name\ \c +\fIconnection-name\fP +.br +[\-\-id\ \c +\fIid\fP] \c +[\-\-host\ \c +\fIip\(hyaddress\fP] +[\-\-ikeport\ \c +\fIport\(hynumber\fP] +[\-\-nexthop\ \c +\fIip\(hyaddress\fP] +[\-\-client\ \c +\fIsubnet\fP] +[\-\-dnskeyondemand] +[\-\-updown\ \c +\fIupdown\fP] +.br +\-\-to +.br +[\-\-id\ \c +\fIid\fP] +[\-\-host\ \c +\fIip\(hyaddress\fP] +[\-\-ikeport\ \c +\fIport\(hynumber\fP] +[\-\-nexthop\ \c +\fIip\(hyaddress\fP] +[\-\-client\ \c +\fIsubnet\fP] +[\-\-dnskeyondemand] +[\-\-updown\ \c +\fIupdown\fP] +.br +[\-\-psk] +[\-\-rsasig] +[\-\-encrypt] +[\-\-authenticate] +[\-\-compress] +[\-\-tunnel] +[\-\-pfs] +[\-\-disablearrivalcheck] +[\-\-ipv4] +[\-\-ipv6] +[\-\-tunnelipv4] +[\-\-tunnelipv6] +[\-\-ikelifetime\ \c +\fIseconds\fP] +[\-\-ipseclifetime\ \c +\fIseconds\fP] +[\-\-rekeymargin\ \c +\fIseconds\fP] +[\-\-rekeyfuzz\ \c +\fIpercentage\fP] +[\-\-keyingtries\ \c +\fIcount\fP] +[\-\-dontrekey] +[\-\-delete] +[\-\-ctlbase\ \c +\fIpath\fP] +[\-\-optionsfrom\ \c +\fIfilename\fP] +[\-\-label\ \c +\fIstring\fP] +.HP +.ft B +ipsec whack +\-\-keyid\ \c +\fIid\fP +[\-\-addkey] +[\-\-pubkeyrsa\ \c +\fIkey\fP] +[\-\-ctlbase\ \c +\fIpath\fP] +[\-\-optionsfrom\ \c +\fIfilename\fP] +[\-\-label\ \c +\fIstring\fP] +.HP +.ft B +ipsec whack +\-\-myid\ \c +\fIid\fP +.HP +.ft B +ipsec whack +\-\-listen|\-\-unlisten +[\-\-ctlbase\ \c +\fIpath\fP] +[\-\-optionsfrom\ \c +\fIfilename\fP] +[\-\-label\ \c +\fIstring\fP] +.HP +.ft B +ipsec whack +\-\-route|\-\-unroute +\-\-name\ \c +\fIconnection-name\fP +[\-\-ctlbase\ \c +\fIpath\fP] +[\-\-optionsfrom\ \c +\fIfilename\fP] +[\-\-label\ \c +\fIstring\fP] +.HP +.ft B +ipsec whack +\-\-initiate|\-\-terminate +\-\-name\ \c +\fIconnection-name\fP +[\-\-asynchronous] +[\-\-ctlbase\ \c +\fIpath\fP] +[\-\-optionsfrom\ \c +\fIfilename\fP] +[\-\-label\ \c +\fIstring\fP] +.HP +.ft B +ipsec whack +[\-\-tunnelipv4] +[\-\-tunnelipv6] +\-\-oppohere \fIip\(hyaddress\fP +\-\-oppothere \fIip\(hyaddress\fP +.HP +.ft B +ipsec whack +\-\-delete +\-\-name\ \c +\fIconnection-name\fP +[\-\-ctlbase\ \c +\fIpath\fP] +[\-\-optionsfrom\ \c +\fIfilename\fP] +[\-\-label\ \c +\fIstring\fP] +.HP +.ft B +ipsec whack +\-\-deletestate\ \c +\fIstate-number\fP +[\-\-ctlbase\ \c +\fIpath\fP] +[\-\-optionsfrom\ \c +\fIfilename\fP] +[\-\-label\ \c +\fIstring\fP] +.HP +.ft B +ipsec whack +[\-\-name\ \c +\fIconnection-name\fP] +[\-\-debug\(hynone] +[\-\-debug\(hyall] +[\-\-debug\(hyraw] +[\-\-debug\(hycrypt] +[\-\-debug\(hyparsing] +[\-\-debug\(hyemitting] +[\-\-debug\(hycontrol] +[\-\-debug\(hylifecycle] +[\-\-debug\(hyklips] +[\-\-debug\(hydns] +[\-\-debug\(hyoppo] +[\-\-debug\(hyprivate] +[\-\-ctlbase\ \c +\fIpath\fP] +[\-\-optionsfrom\ \c +\fIfilename\fP] +[\-\-label\ \c +\fIstring\fP] +.HP +.ft B +ipsec whack +\-\-status +[\-\-ctlbase\ \c +\fIpath\fP] +[\-\-optionsfrom\ \c +\fIfilename\fP] +[\-\-label\ \c +\fIstring\fP] +.HP +.ft B +ipsec whack +\-\-shutdown +[\-\-ctlbase\ \c +\fIpath\fP] +[\-\-optionsfrom\ \c +\fIfilename\fP] +[\-\-label\ \c +\fIstring\fP] +.ft R +.hy +.ad +.SH DESCRIPTION +.BR pluto +is an IKE (``IPsec Key Exchange'') daemon. +.BR whack +is an auxiliary program to allow requests to be made to a running +.BR pluto . +.LP +.BR pluto +is used to automatically build shared ``security associations'' on a +system that has IPsec, the secure IP protocol. +In other words, +.BR 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 (see +.BR KLIPS , +the companion implementation of IPsec). +\fIipsec_auto\fP(8) provides a more convenient interface to +\fBpluto\fP and \fBwhack\fP. +.SS IKE's Job +.LP +A \fISecurity Association\fP (\fISA\fP) is an agreement between two network nodes on +how to process certain traffic between them. This processing involves +encapsulation, authentication, encryption, or compression. +.LP +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. +.LP +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. +.LP +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. +.LP +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. +.LP +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). +.LP +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. +.LP +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. +.LP +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. +.LP +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. +.SS Pluto +.LP +\fBpluto\fP 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 +\fBKLIPS\fP implementation of IPsec. +.LP +\fBpluto\fP only implements a subset of IKE. This is enough for it to +interoperate with other instances of \fBpluto\fP, and many other IKE +implementations. We are working on implementing more of IKE. +.LP +The policy for acceptable characteristics for Security Associations is +mostly hardwired into the code of \fBpluto\fP (spdb.c). Eventually +this will be moved into a security policy database with reasonable +expressive power and more convenience. +.LP +\fBpluto\fP uses shared secrets or RSA signatures to authenticate +peers with whom it is negotiating. +.LP +\fBpluto\fP initiates negotiation of a Security Association when it is +manually prodded: the program \fBwhack\fP is run to trigger this. +It will also initiate a negotiation when \fBKLIPS\fP traps an outbound packet +for Opportunistic Encryption. +.LP +\fBpluto\fP implements ISAKMP SAs itself. After it has negotiated the +characteristics of an IPsec SA, it directs \fBKLIPS\fP to implement it. +It also invokes a script to adjust any firewall and issue \fIroute\fP(8) +commands to direct IP packets through \fBKLIPS\fP. +.LP +When \fBpluto\fP shuts down, it closes all Security Associations. +.SS Before Running Pluto +.LP +\fBpluto\fP runs as a daemon with userid root. Before running it, a few +things must be set up. +.LP +\fBpluto\fP requires \fBKLIPS\fP, the FreeS/WAN implementation of IPsec. +All of the components of \fBKLIPS\fP and \fBpluto\fP should be installed. +.LP +\fBpluto\fP 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 \fB\-\-interface\fP option can be used to limit +the interfaces considered). +It does this only when \fBwhack\fP tells it to \-\-listen, +so the interfaces must be configured by then. Each interface with a name of the form +\fBipsec\fP[\fB0\fP-\fB9\fP] is taken as a \fBKLIPS\fP virtual public interface. +Another network interface with the same IP address (there should be only +one) is taken as the corresponding real public +interface. \fIifconfig\fP(8) with the \fB\-a\fP flag will show +the name and status of each network interface. +.LP +\fBpluto\fP requires a database of preshared secrets and RSA private keys. +This is described in the +.IR ipsec.secrets (5). +\fBpluto\fP is told of RSA public keys via \fBwhack\fP commands. +If the connection is Opportunistic, and no RSA public key is known, +\fBpluto\fP will attempt to fetch RSA keys using the Domain Name System. +.SS Setting up \fBKLIPS\fP for \fBpluto\fP +.LP +The most basic network topology that \fBpluto\fP supports has two security +gateways negotiating on behalf of client subnets. The diagram of RGB's +testbed is a good example (see \fIklips/doc/rgb_setup.txt\fP). +.LP +The file \fIINSTALL\fP in the base directory of this distribution +explains how to start setting up the whole system, including \fBKLIPS\fP. +.LP +Make sure that the security gateways have routes to each other. This +is usually covered by the default route, but may require issuing +.IR route (8) +commands. The route must go through a particular IP +interface (we will assume it is \fIeth0\fP, but it need not be). The +interface that connects the security gateway to its client must be a +different one. +.LP +It is necessary to issue a +.IR 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 +.IR ipsec_tncfg (8). +.SS ipsec.secrets file +.LP +A \fBpluto\fP daemon and another IKE daemon (for example, another instance +of \fBpluto\fP) 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 \fBpluto\fP. +.LP +The file \fI/etc/ipsec.secrets\fP 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 \fBpluto\fP command to use a different file. +This file is described in +.IR ipsec.secrets (5). +.SS Running Pluto +.LP +To fire up the daemon, just type \fBpluto\fP (be sure to be running as +the superuser). +The default IKE port number is 500, the UDP port assigned by IANA for IKE Daemons. +\fBpluto\fP must be run by the superuser to be able to use the UDP 500 port. +.LP +\fBpluto\fP attempts to create a lockfile with the name +\fI/var/run/pluto.pid\fP. If the lockfile cannot be created, +\fBpluto\fP exits \- this prevents multiple \fBpluto\fPs from +competing Any ``leftover'' lockfile must be removed before +\fBpluto\fP will run. \fBpluto\fP 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). +.LP +\fBpluto\fP 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. +.LP +All logging, including diagnostics, is sent to +.IR syslog (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. +.LP +If the \fB\-\-perpeerlog\fP 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 (/). +.LP +The base directory can be changed with the \fB\-\-perpeerlogbase\fP. +.LP +Once \fBpluto\fP is started, it waits for requests from \fBwhack\fP. +.SS Pluto's Internal State +.LP +To understand how to use \fBpluto\fP, it is helpful to understand a little +about its internal state. Furthermore, the terminology is needed to decipher +some of the diagnostic messages. +.LP +The \fI(potential) connection\fP database describes attributes of a +connection. These include the IP addresses of the hosts and client +subnets and the security characteristics desired. \fBpluto\fP +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. +.LP +During the IKE exchange to build an SA, the information about the +negotiation is represented in a \fIstate object\fP. 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. +.LP +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. +.LP +\fBKLIPS\fP hooks into the routing code in a LINUX kernel. +Traffic to be processed by an IPsec SA must be directed through +\fBKLIPS\fP by routing commands. Furthermore, the processing to be +done is specified by \fIipsec eroute(8)\fP commands. +\fBpluto\fP takes the responsibility of managing both of these special +kinds of routes. +.LP +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 +(\fBpluto\fP's logic does not reflect any advanced routing capabilities). +.LP +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). +.LP +When \fBpluto\fP 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. +.LP +There is an exception. If \fBpluto\fP, 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). +.LP +When \fBpluto\fP 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. +.LP +All of these routing characteristics are expected change when +\fBKLIPS\fP is modified to use the firewall hooks in the LINUX 2.4.x +kernel. +.SS Using Whack +.LP +\fBwhack\fP is used to command a running \fBpluto\fP. +\fBwhack\fP uses a UNIX domain socket to speak to \fBpluto\fP +(by default, \fI/var/pluto.ctl\fP). +.LP +\fBwhack\fP 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 \fBpluto\fP a description of a potential connection. +The public key form informs \fBpluto\fP 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 \fBpluto\fP to start or stop listening on the public interfaces +for IKE requests from peers. +The route form tells \fBpluto\fP to set up routing for a connection; +the unroute form undoes this. +The initiate form tells \fBpluto\fP to negotiate an SA corresponding to a connection. +The terminate form tells \fBpluto\fP to remove all SAs corresponding to a connection, +including those being negotiated. +The status form displays the \fBpluto\fP's internal state. +The debug form tells \fBpluto\fP to change the selection of debugging output +``on the fly''. The shutdown form tells +\fBpluto\fP to shut down, deleting all SAs. +.LP +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. +.TP +\fB\-\-ctlbase\fP\ \fIpath\fP +\fIpath\fP.ctl is used as the UNIX domain socket for talking +to \fBpluto\fP. +This option facilitates debugging. +.TP +\fB\-\-optionsfrom\fP\ \fIfilename\fP +adds the contents of the file to the argument list. +.TP +\fB\-\-label\fP\ \fIstring\fP +adds the string to all error messages generated by \fBwhack\fP. +.LP +The help form of \fBwhack\fP is self-explanatory. +.TP +\fB\-\-help\fP +display the usage message. +.TP +\fB\-\-version\fP +display the version of \fBwhack\fP. +.LP +The connection form describes a potential connection to \fBpluto\fP. +\fBpluto\fP needs to know what connections can and should be negotiated. +When \fBpluto\fP is the initiator, it needs to know what to propose. +When \fBpluto\fP is the responder, it needs to know enough to decide whether +is is willing to set up the proposed connection. +.LP +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. +.TP +\fB\-\-name\fP\ \fIconnection-name\fP +.LP +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 \fB\-\-to\fP flag describe the left side +and those afterwards describe the right side. When \fBpluto\fP 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. +.TP +\fB\-\-id\fP\ \fIid\fP +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 as the +magic value \fB%myid\fP. +\fBPluto\fP 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 \fB\-\-host\fP. +\fB%myid\fP allows the identity to be separately specified (by the \fBpluto\fP or \fBwhack\fP option \fB\-\-myid\fP +or by the \fBipsec.conf\fP(5) \fBconfig setup\fP parameter \fPmyid\fP). +Otherwise, \fBpluto\fP tries to guess what \fB%myid\fP should stand for: +the IP address of \fB%defaultroute\fP, 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. +.\" The identity is transmitted in the IKE protocol, and is what is authenticated. +.TP +\fB\-\-host\fP\ \fIip\(hyaddress\fP +.TP +\fB\-\-host\fP\ \fB%any\fP +.TP +\fB\-\-host\fP\ \fB%opportunistic\fP +the IP address of the end (generally the public interface). +If \fBpluto\fP 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 \fB%any\fP (currently, +the obsolete notation \fB0.0.0.0\fP is also accepted for this). +If \fBpluto\fP is to opportunistically initiate the connection, +use \fB%opportunistic\fP +.TP +\fB\-\-ikeport\fP\ \fIport\(hynumber\fP +the UDP port that IKE listens to on that host. The default is 500. +(\fBpluto\fP on this machine uses the port specified by its own command +line argument, so this only affects where \fBpluto\fP sends messages.) +.TP +\fB\-\-nexthop\fP\ \fIip\(hyaddress\fP +where to route packets for the peer's client (presumably for the peer too, +but it will not be used for this). +When \fBpluto\fP 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 +\fB%direct\fP; the obsolete notation \fB0.0.0.0\fP is accepted). +This option is necessary if \fBpluto\fP's host's interface used for sending +packets to the peer is neither point-to-point nor directly connected to the +peer. +.TP +\fB\-\-client\fP\ \fIsubnet\fP +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 \fIipsec_atosubnet\fP(3). +The general form is \fIaddress\fP/\fImask\fP. The \fIaddress\fP can be either +a domain name or four decimal numbers (specifying octets) separated by dots. +The most convenient form of the \fImask\fP 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''. +.TP +\fB\-\-dnskeyondemand]\fP +specifies that when an RSA public key is needed to authenticate this +host, and it isn't already known, fetch it from DNS. +.TP +\fB\-\-updown\fP\ \fIupdown\fP +specifies an external shell command to be run whenever \fBpluto\fP +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 \fIipsec _updown\fP. +.TP +\fB\-\-to\fP +separates the specification of the left and right ends of the connection. +.LP +The potential connection description also specifies characteristics of +rekeying and security. +.TP +\fB\-\-psk\fP +Propose and allow preshared secret authentication for IKE peers. This authentication +requires that each side use the same secret. May be combined with \fB\-\-rsasig\fP; +at least one must be specified. +.TP +\fB\-\-rsasig\fP +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 \fB\-\-psk\fP; +at least one must be specified. +.TP +\fB\-\-encrypt\fP +All proposed or accepted IPsec SAs will include non-null ESP. +The actual choices of transforms are wired into \fBpluto\fP. +.TP +\fB\-\-authenticate\fP +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 \fBpluto\fP. +Note that this has nothing to do with IKE authentication. +.TP +\fB\-\-compress\fP +All proposed IPsec SAs will include IPCOMP (compression). +This will be ignored if KLIPS is not configured with IPCOMP support. +.TP +\fB\-\-tunnel\fP +the IPsec SA should use tunneling. Implicit if the SA is for clients. +Must only be used with \fB\-\-authenticate\fP or \fB\-\-encrypt\fP. +.TP +\fB\-\-ipv4\fP +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). +.TP +\fB\-\-ipv6\fP +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). +.TP +\fB\-\-tunnelipv4\fP +The client addresses will be interpreted as IPv4 addresses. The default is +to match what the host will be. This does not imply \fB\-\-tunnel\fP 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. +.TP +\fB\-\-tunnelipv6\fP +The client addresses will be interpreted as IPv6 addresses. The default is +to match what the host will be. This does not imply \fB\-\-tunnel\fP 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. +.TP +\fB\-\-pfs\fP +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), \fBpluto\fP 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. +.TP +\fB\-\-disablearrivalcheck\fP +If the connection is a tunnel, allow packets arriving through the tunnel +to have any source and destination addresses. +.LP +If none of the \fB\-\-encrypt\fP, \fB\-\-authenticate\fP, \fB\-\-compress\fP, +or \fB\-\-pfs\fP 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. +.LP +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. +.TP +\fB\-\-ikelifetime\fP\ \fIseconds\fP +how long \fBpluto\fP will propose that an ISAKMP SA be allowed to live. +The default is 10800 (three hours) and the maximum is 86400 (one day). +This option will not affect what is accepted. +\fBpluto\fP will reject proposals that exceed the maximum. +.TP +\fB\-\-ipseclifetime\fP\ \fIseconds\fP +how long \fBpluto\fP will propose that an IPsec SA be allowed to live. +The default is 3600 (one hour) and the maximum is 86400 (one day). +This option will not affect what is accepted. +\fBpluto\fP will reject proposals that exceed the maximum. +.TP +\fB\-\-rekeymargin\fP\ \fIseconds\fP +how long before an SA's expiration should \fBpluto\fP try to negotiate +a replacement SA. This will only happen if \fBpluto\fP was the initiator. +The default is 540 (nine minutes). +.TP +\fB\-\-rekeyfuzz\fP\ \fIpercentage\fP +maximum size of random component to add to rekeymargin, expressed as +a percentage of rekeymargin. \fBpluto\fP 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. +.TP +\fB\-\-keyingtries\fP\ \fIcount\fP +how many times \fBpluto\fP 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. +.TP +\fB\-\-dontrekey\fP +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 \fB\-\-dontrekey\fP. 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. +.TP +\fB\-\-delete\fP +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. +.LP +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. +.TP +\fB\-\-delete\fP +.TP +\fB\-\-name\fP\ \fIconnection-name\fP +.LP +The deletestate form deletes the state object with the specified serial number. +This is useful for selectively deleting instances of connections. +.TP +\fB\-\-deletestate\fP\ \fIstate-number\fP +.LP +The route form of the \fBwhack\fP command tells \fBpluto\fP 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 \fBwhack\fP route is not always needed: if it hasn't been +done when an IPsec SA is being installed, one will be automatically attempted. +.LP +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. +.TP +\fB\-\-route\fP +.TP +\fB\-\-name\fP\ \fIconnection-name\fP +.LP +The unroute form of the \fBwhack\fP command tells \fBpluto\fP to undo +a routing. \fBpluto\fP 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. +.TP +\fB\-\-unroute\fP +.TP +\fB\-\-name\fP\ \fIconnection-name\fP +.LP +The initiate form tells \fBpluto\fP to initiate a negotiation with another +\fBpluto\fP (or other IKE daemon) according to the named connection. +Initiation requires a route that \fB\-\-route\fP would provide; +if none is in place at the time an IPsec SA is being installed, +\fBpluto\fP attempts to set one up. +.TP +\fB\-\-initiate\fP +.TP +\fB\-\-name\fP\ \fIconnection-name\fP +.TP +\fB\-\-asynchronous +.LP +The initiate form of the \fBwhack\fP command will relay back from +\fBpluto\fP status information via the UNIX domain socket (unless +\-\-asynchronous is specified). The status information is meant to +look a bit like that from \fBFTP\fP. Currently \fBwhack\fP simply +copies this to stderr. When the request is finished (eg. the SAs are +established or \fBpluto\fP gives up), \fBpluto\fP closes the channel, +causing \fBwhack\fP to terminate. +.LP +The opportunistic initiate form is mainly used for debugging. +.TP +\fB\-\-tunnelipv4\fP +.TP +\fB\-\-tunnelipv6\fP +.TP +\fB\-\-oppohere\fP\ \fIip-address\fP +.TP +\fB\-\-oppothere\fP\ \fIip-address\fP +.LP +This will cause \fBpluto\fP 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. +.LP +The terminate form tells \fBpluto\fP 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). +.TP +\fB\-\-terminate\fP +.TP +\fB\-\-name\fP\ \fIconnection-name\fP +.LP +The public key for informs \fBpluto\fP of the RSA public key for a potential peer. +Private keys must be kept secret, so they are kept in +.IR ipsec.secrets (5). +.TP +\fB\-\-keyid\ \fP\fIid\fP +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, \fBpluto\fP 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. +.TP +\fB\-\-addkey\fP +specifies that the new key is added to the collection; otherwise the +new key replaces any old ones. +.TP +\fB\-\-pubkeyrsa\ \fP\fIkey\fP +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 \fIipsec_ttodata\fP(3). +For example, a base 64 numeral starts with 0s. +.LP +The listen form tells \fBpluto\fP to start listening for IKE requests +on its public interfaces. To avoid race conditions, it is normal to +load the appropriate connections into \fBpluto\fP before allowing it +to listen. If \fBpluto\fP isn't listening, it is pointless to +initiate negotiations, so it will refuse requests to do so. Whenever +the listen form is used, \fBpluto\fP 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 \fBpluto\fP to read the +\fIipsec.secrets\fP file. So listen may useful more than once. +.TP +\fB\-\-listen\fP +start listening for IKE traffic on public interfaces. +.TP +\fB\-\-unlisten\fP +stop listening for IKE traffic on public interfaces. +.LP +The status form will display information about the internal state of +\fBpluto\fP: information about each potential connection, about +each state object, and about each shunt that \fBpluto\fP is managing +without an associated connection. +.TP +\fB\-\-status\fP +.LP +The shutdown form is the proper way to shut down \fBpluto\fP. +It will tear down the SAs on this machine that \fBpluto\fP has negotiated. +It does not inform its peers, so the SAs on their machines remain. +.TP +\fB\-\-shutdown\fP +.SS Examples +.LP +It would be normal to start \fBpluto\fP 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 \fBpluto\fP process will be left +running, waiting for requests from \fBwhack\fP or a peer. +.LP +Using \fBwhack\fP, several potential connections would be described: +.HP +.na +\ \ \ ipsec whack \-\-name\ silly +\-\-host\ 127.0.0.1 \-\-to \-\-host\ 127.0.0.2 +\-\-ikelifetime\ 900 \-\-ipseclifetime\ 800 \-\-keyingtries\ 3 +.ad +.LP +Since this silly connection description specifies neither encryption, +authentication, nor tunneling, it could only be used to establish +an ISAKMP SA. +.HP +.na +\ \ \ 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 +.ad +.LP +This is something that must be done on both sides. If the other +side is \fBpluto\fP, the same \fBwhack\fP command could be used on it +(the command syntax is designed to not distinguish which end is ours). +.LP +Now that the connections are specified, \fBpluto\fP 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 +.LP +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 \fBpluto\fP 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 +.LP +Finally, we are ready to get \fBpluto\fP 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). +.LP +\fBwhack\fP can also be used to terminate \fBpluto\fP 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, \fBpluto\fP itself ignores Notifications. +.SS The updown command +.LP +Whenever \fBpluto\fP brings a connection up or down, it invokes +the updown command. This command is specified using the \fB\-\-updown\fP +option. This allows for customized control over routing and firewall manipulation. +.LP +The updown is invoked for five different operations. Each of +these operations can be for our client subnet or for our host itself. +.TP +\fBprepare-host\fP or \fBprepare-client\fP +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 \fBpluto\fP was run or +perhaps by some agent not known to \fBpluto\fP. +.TP +\fBroute-host\fP or \fBroute-client\fP +is run when bringing up a connection for a new peer client subnet +(even if \fBprepare-host\fP or \fBprepare-client\fP 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. +.TP +\fBunroute-host\fP or \fBunroute-client\fP +is run when bringing down the last connection for a particular peer +client subnet. It should undo what the \fBroute-host\fP or \fBroute-client\fP +did. +.TP +\fBup-host\fP or \fBup-client\fP +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. +.TP +\fBdown-host\fP or \fBdown-client\fP +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. +.LP +The script is passed a large number of environment variables to specify +what needs to be done. +.TP +\fBPLUTO_VERSION\fP +indicates what version of this interface is being used. This document +describes version 1.1. This is upwardly compatible with version 1.0. +.TP +\fBPLUTO_VERB\fP +specifies the name of the operation to be performed +(\fBprepare-host\fP,r \fBprepare-client\fP, +\fBup-host\fP, \fBup-client\fP, +\fBdown-host\fP, or \fBdown-client\fP). If the address family for +security gateway to security gateway communications is IPv6, then +a suffix of -v6 is added to the verb. +.TP +\fBPLUTO_CONNECTION\fP +is the name of the connection for which we are routing. +.TP +\fBPLUTO_NEXT_HOP\fP +is the next hop to which packets bound for the peer must be sent. +.TP +\fBPLUTO_INTERFACE\fP +is the name of the ipsec interface to be used. +.TP +\fBPLUTO_ME\fP +is the IP address of our host. +.TP +\fBPLUTO_MY_CLIENT\fP +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). +.TP +\fBPLUTO_MY_CLIENT_NET\fP +is the IP address of our client net. +If the client is just the host, this will be the host's own IP address. +.TP +\fBPLUTO_MY_CLIENT_MASK\fP +is the mask for our client net. +If the client is just the host, this will be 255.255.255.255. +.TP +\fBPLUTO_PEER\fP +is the IP address of our peer. +.TP +\fBPLUTO_PEER_CLIENT\fP +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). +.TP +\fBPLUTO_PEER_CLIENT_NET\fP +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. +.TP +\fBPLUTO_PEER_CLIENT_MASK\fP +is the mask for the peer's client net. +If the client is just the peer, this will be 255.255.255.255. +.LP +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. +.LP +\fBPluto\fP waits for the script to finish and will not do any other +processing while it is waiting. +The script may assume that \fBpluto\fP 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 \fBpluto\fP. +Either of these activities could be performed by a background +subprocess of the script. +.SS Rekeying +.LP +When an SA that was initiated by \fBpluto\fP has only a bit of +lifetime left, +\fBpluto\fP 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. +.LP +Similarly, when an SA that was initiated by the peer has only a bit of +lifetime left, \fBpluto\fP 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. +.LP +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. +.LP +\fBpluto\fP 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. +.LP +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. +.LP +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. +.LP +Once a new set of SAs has been negotiated, \fBpluto\fP will never send +traffic on a superseded one. Traffic will be accepted on an old SA +until it expires. +.SS Selecting a Connection When Responding: Road Warrior Support +.LP +When \fBpluto\fP 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.) +.LP +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. +.LP +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. +.LP +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 \fB%any\fP +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 \fB%any\fP 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. +.LP +When \fBpluto\fP is using one of these temporary connections and +needs to find the preshared secret or RSA private key in \fIipsec.secrets\fP, +and and the connection specified no identity for the peer, \fB%any\fP +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. +.LP +Part way into the Phase 1 (Main Mode) negotiation using one of these +temporary connection descriptions, \fBpluto\fP will be receive an +Identity Payload. At this point, \fBpluto\fP 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 \fB%any\fP +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, \fBpluto\fP terminates negotiation. +.LP +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). +.LP +When \fBpluto\fP 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 \fB%any\fP +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, \fBpluto\fP terminates negotiation. +.LP +Be sure to specify an appropriate nexthop for the responder +to send a message to the initiator: \fBpluto\fP has no way of guessing +it (if forwarding isn't required, use an explicit \fB%direct\fP as the nexthop +and the IP address of the initiator will be filled in; the obsolete +notation \fB0.0.0.0\fP is still accepted). +.LP +\fBpluto\fP 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. +\fBpluto\fP has no mechanism to do this automatically. +.LP +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. +.LP +If any Road Warrior connections are supported, \fBpluto\fP 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. +.LP +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 \fB\-\-keyingtries\fP 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. +.SS Debugging +.LP +\fBpluto\fP accepts several optional arguments, useful mostly for debugging. +Except for \fB\-\-interface\fP, each should appear at most once. +.TP +\fB\-\-interface\fP \fIinterfacename\fP +specifies that the named real public network interface should be considered. +The interface name specified should not be \fBipsec\fP\fIN\fP. +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. +.TP +\fB\-\-ikeport\fP \fIport-number\fP +changes the UDP port that \fBpluto\fP will use +(default, specified by IANA: 500) +.TP +\fB\-\-ctlbase\fP \fIpath\fP +basename for control files. +\fIpath\fP.ctl is the socket through which \fBwhack\fP communicates with +\fBpluto\fP. +\fIpath\fP.pid is the lockfile to prevent multiple \fBpluto\fP instances. +The default is \fI/var/run/pluto\fP). +.TP +\fB\-\-secretsfile\fP \fIfile\fP +specifies the file for authentication secrets +(default: \fI/etc/ipsec.secrets\fP). +This name is subject to ``globbing'' as in \fIsh\fP(1), +so every file with a matching name is processed. +Quoting is generally needed to prevent the shell from doing the globbing. +.TP +\fB\-\-adns\fP \fIpathname\fP +.TP +\fB\-\-lwdnsq\fP \fIpathname\fP +specifies where to find \fBpluto\fP's helper program for asynchronous DNS lookup. +\fBpluto\fP can be built to use one of two helper programs: \fB_pluto_adns\fP +or \fBlwdnsq\fP. You must use the program for which it was built. +By default, \fBpluto\fP will look for the program in +\fB$IPSEC_DIR\fP (if that environment variable is defined) or, failing that, +in the same directory as \fBpluto\fP. +.TP +\fB\-\-nofork\fP +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. +.TP +\fB\-\-noklips\fP +don't actually implement negotiated IPsec SAs +.TP +\fB\-\-uniqueids\fP +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. +.TP +\fB\-\-stderrlog\fP +log goes to standard out {default is to use \fIsyslogd\fP(8)) +.LP +For example +.TP +pluto \-\-secretsfile\ ipsec.secrets \-\-ctlbase\ pluto.base \-\-ikeport\ 8500 \-\-nofork \-\-noklips \-\-stderrlog +.LP +lets one test \fBpluto\fP without using the superuser account. +.LP +\fBpluto\fP 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 \fBpluto\fP may be directed to +produce a selection of them. All lines of +debugging output are prefixed with ``|\ '' to distinguish them from error +messages. +.LP +When \fBpluto\fP is invoked, it may be given arguments to specify +which classes to output. The current options are: +.TP +\fB\-\-debug-raw\fP +show the raw bytes of messages +.TP +\fB\-\-debug-crypt\fP +show the encryption and decryption of messages +.TP +\fB\-\-debug-parsing\fP +show the structure of input messages +.TP +\fB\-\-debug-emitting\fP +show the structure of output messages +.TP +\fB\-\-debug-control\fP +show \fBpluto\fP's decision making +.TP +\fB\-\-debug-lifecycle\fP +[this option is temporary] log more detail of lifecycle of SAs +.TP +\fB\-\-debug-klips\fP +show \fBpluto\fP's interaction with \fBKLIPS\fP +.TP +\fB\-\-debug-dns\fP +show \fBpluto\fP's interaction with \fBDNS\fP for KEY and TXT records +.TP +\fB\-\-debug-oppo\fP +show why \fBpluto\fP didn't find a suitable DNS TXT record to authorize opportunistic initiation +.TP +\fB\-\-debug-all\fP +all of the above +.TP +\fB\-\-debug-private\fP +allow debugging output with private keys. +.TP +\fB\-\-debug-none\fP +none of the above +.LP +The debug form of the +\fBwhack\fP command will change the selection in a running +\fBpluto\fP. +If a connection name is specified, the flags are added whenever +\fBpluto\fP has identified that it is dealing with that connection. +Unfortunately, this is often part way into the operation being observed. +.LP +For example, to start a \fBpluto\fP with a display of the structure of input +and output: +.IP +pluto \-\-debug-emitting \-\-debug-parsing +.LP +To later change this \fBpluto\fP to only display raw bytes: +.IP +whack \-\-debug-raw +.LP +For testing, SSH's IKE test page is quite useful: +.IP +\fIhttp://isakmp-test.ssh.fi/\fP +.LP +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. \fBpluto\fP is not yet smart enough to get out of such a +mess. +.SS Pluto's Behaviour When Things Go Wrong +.LP +When \fBpluto\fP 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. +.LP +When \fBpluto\fP 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. +.LP +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. +.LP +Combine these three rules, and you can explain many apparently +mysterious behaviours. In a \fBpluto\fP log, retrying isn't usually the +interesting event. The critical thing is either earlier (\fBpluto\fP +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 (\fBpluto\fP didn't send a reply because it wasn't happy with +the previous message). +.SS Notes +.LP +If \fBpluto\fP 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 \fBpluto\fP to be tested on systems +without \fBKLIPS\fP, but makes it rather useless. +.LP +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. +\fBPluto\fP also avoids choosing an SPI in the range 0x100 to 0xFFF, +leaving these SPIs free for manual keying. +Remember that the peer, if not \fBpluto\fP, may well chose +SPIs in this range. +.SS Policies +.LP +This catalogue of policies may be of use when trying to configure +\fBPluto\fP and another IKE implementation to interoperate. +.LP +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. +.LP +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. +.LP +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). +.IP \(bu \w'\(bu\ 'u +Diffie Hellman Groups MODP 1024 and MODP 1536 (2 and 5) +are supported. +Group MODP768 (1) is not supported because it is too weak. +.IP \(bu +Host authetication can be done by RSA Signatures or Pre-Shared +Secrets. +.IP \(bu +3DES CBC (Cypher Block Chaining mode) is the only encryption +supported, both for ISAKMP SAs and IPSEC SAs. +.IP \(bu +MD5 and SHA1 hashing are supported for packet authentication in both +kinds of SAs. +.IP \(bu +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. +.IP \(bu +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. +.IP \(bu +The IPSEC SAs may be tunnel or transport mode, where appropriate. +The \-\-tunnel flag controls this when \fBpluto\fP is initiating. +.IP \(bu +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 \fBpluto\fP +is initiating. +.IP \(bu +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 \fBpluto\fP +is initiating. +.IP \(bu +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. +.SH SIGNALS +.LP +\fBPluto\fP responds to \fBSIGHUP\fP by issuing a suggestion that ``\fBwhack\fP +\-\-listen'' might have been intended. +.LP +\fBPluto\fP exits when it recieves \fBSIGTERM\fP. +.SH EXIT STATUS +.LP +\fBpluto\fP normally forks a daemon process, so the exit status is +normally a very preliminary result. +.TP +0 +means that all is OK so far. +.TP +1 +means that something was wrong. +.TP +10 +means that the lock file already exists. +.LP +If \fBwhack\fP detects a problem, it will return an exit status of 1. +If it received progress messages from \fBpluto\fP, 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. +.SH FILES +\fI/var/run/pluto.pid\fP +.br +\fI/var/run/pluto.ctl\fP +.br +\fI/etc/ipsec.secrets\fP +.br +\fI$IPSEC_LIBDIR/_pluto_adns\fP +.br +\fI$IPSEC_EXECDIR/lwdnsq\fP +.br +\fI/dev/urandom\fP +.SH ENVIRONMENT +\fIIPSEC_LIBDIR\fP +.br +\fIIPSEC_EXECDIR\fP +.br +\fIIPSECmyid\fP +.SH SEE ALSO +.LP +The rest of the FreeS/WAN distribution, in particular \fIipsec\fP(8). +.LP +\fIipsec_auto\fP(8) is designed to make using \fBpluto\fP more pleasant. +Use it! +.LP +.IR ipsec.secrets (5) +describes the format of the secrets file. +.LP +\fIipsec_atoaddr\fP(3), part of the FreeS/WAN distribution, describes the +forms that IP addresses may take. +\fIipsec_atosubnet\fP(3), part of the FreeS/WAN distribution, describes the +forms that subnet specifications. +.LP +For more information on IPsec, the mailing list, and the relevant +documents, see: +.IP +.nh +\fIhttp://www.ietf.cnri.reston.va.us/html.charters/ipsec-charter.html\fP +.hy +.LP +At the time of writing, the most relevant IETF RFCs are: +.IP +RFC2409 The Internet Key Exchange (IKE) +.IP +RFC2408 Internet Security Association and Key Management Protocol (ISAKMP) +.IP +RFC2407 The Internet IP Security Domain of Interpretation for ISAKMP +.LP +The FreeS/WAN web site <htp://www.freeswan.org> +and the mailing lists described there. +.SH HISTORY +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. +.LP +This software was originally written +for the FreeS/WAN project +<http://www.freeswan.org> +by Angelos D. Keromytis +(angelos@dsl.cis.upenn.edu), in May/June 1997, in Athens, Greece. +Thanks go to John Ioannidis for his help. +.LP +It is currently (2000) +being developed and maintained by D. Hugh Redelmeier +(hugh@mimosa.com), in Canada. The regulations of Greece and Canada +allow us to make the code freely redistributable. +.LP +Kai Martius (admin@imib.med.tu-dresden.de) contributed the initial +version of the code supporting PFS. +.LP +Richard Guy Briggs <rgb@conscoop.ottawa.on.ca> and Peter Onion +<ponion@srd.bt.co.uk> added the PFKEY2 support. +.LP +We gratefully acknowledge that we use parts of Eric Young's \fIlibdes\fP +package; see \fI../libdes/COPYRIGHT\fP. +.SH BUGS +.BR 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. +.LP +\fBpluto\fP 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. +.LP +\fBpluto\fP 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. +.LP +There is no good way for a connection to be automatically terminated. +This is a problem for Road Warrior and Opportunistic connections. +The \fB\-\-dontrekey\fP 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. +.LP +When \fBpluto\fP sends a message to a peer that has disappeared, +\fBpluto\fP 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 + tcpdump -i eth0 icmp[0] != 8 and icmp[0] != 0 +.br +Substitute your public interface for eth0 if it is different. +.LP +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. +.LP +Bugs should be reported to the <users@lists.freeswan.org> 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. |