Content-type: text/html Manpage of IPSEC_PLUTO

IPSEC_PLUTO

Section: Maintenance Commands (8)
Updated: 28 March 1999
Index Return to Main Contents
 

NAME

ipsec pluto - IPsec IKE keying daemon
ipsec whack - control interface for IPSEC keying daemon  

SYNOPSIS

ipsec pluto [--help] [--version] [--optionsfrom filename] [--nofork] [--stderrlog] [--noklips] [--ikeport portnumber] [--ctlbase path] [--secretsfile secrets-file] [--debug-none] [--debug-all] [--debug-raw] [--debug-crypt] [--debug-parsing] [--debug-emitting] [--debug-control] [--debug-klips] [--debug-private]
ipsec whack [--help] [--version]
ipsec whack --name connection-name
[--id id] [--host ip-address] [--ikeport port-number] [--nexthop ip-address] [--client subnet] [--firewall]
--to
[--id id] [--host ip-address] [--ikeport port-number] [--nexthop ip-address] [--client subnet] [--firewall]
[--encrypt] [--authenticate] [--tunnel] [--pfs] [--ikelifetime seconds] [--ipseclifetime seconds] [--rekeymargin seconds] [--rekeyfuzz percentage] [--keyingtries count] [--delete] [--ctlbase path] [--optionsfrom filename] [--label string]
ipsec whack --keyid id --pubkeyrsa key [--ctlbase path] [--optionsfrom filename] [--label string]
ipsec whack --listen|--unlisten [--ctlbase path] [--optionsfrom filename] [--label string]
ipsec whack --route|--unroute --name connection-name [--ctlbase path] [--optionsfrom filename] [--label string]
ipsec whack --initiate|--terminate --name connection-name [--asynchronous] [--ctlbase path] [--optionsfrom filename] [--label string]
ipsec whack --delete --name connection-name [--ctlbase path] [--optionsfrom filename] [--label string]
ipsec whack [--debug-none] [--debug-all] [--debug-raw] [--debug-crypt] [--debug-parsing] [--debug-emitting] [--debug-control] [--debug-klips] [--debug-private] [--ctlbase path] [--optionsfrom filename] [--label string]
ipsec whack --status [--ctlbase path] [--optionsfrom filename] [--label string]
ipsec whack --shutdown [--ctlbase path] [--optionsfrom filename] [--label string]
 

DESCRIPTION

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

pluto is used to automatically build shared ``security associations'' on a system that has IPsec, the secure IP protocol. In other words, pluto can eliminate much of the work of manual keying. The actual secure transmission of packets is the responsibility of other parts of the system (see KLIPS, the companion implementation of IPsec). ipsec_auto(8) provides a more convenient interface to pluto and whack.  

IKE's Job

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

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

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

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

IKE deals with two kinds of Security Associations. The first part of a negotiation between IKE instances is to build an ISAKMP SA. ISAKMP SAs are only used by the IKEs to communicate between themselves. IPsec SAs can then be built by the IKEs - these are for the use of other programs.

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

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

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

Pluto

pluto is an implementation of IKE. It runs as a daemon on a network node. Currently, this network node must be a LINUX system running the KLIPS implementation of IPsec.

pluto only implements a subset of IKE. This is enough for it to interoperate with other instances of pluto, and many other IKE implementations. We are working on implementing more of IKE.

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

pluto uses shared secrets or RSA signatures to authenticate peers with whom it is negotiating. In future other techniques will be supported.

pluto initiates negotiation of a Security Association when it is manually prodded: the program whack is run to trigger this. Eventually, more convenient and useful mechanisms will be implemented.

pluto implements ISAKMP SAs itself. After it has negotiated the characteristics of an IPsec SA, it directs KLIPS to implement it. It also issues route(8) commands to direct messages through KLIPS.

When pluto shuts down, it closes all Security Associations.  

Before Running Pluto

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

pluto requires KLIPS, the FreeS/WAN implementation of IPsec. All of the components of KLIPS and pluto should be installed.

pluto supports multiple public networks (that is, networks that are considered insecure and thus need to have their traffic encrypted or authenticated). It discovers the public interfaces to use by looking at all interfaces that are configured. It does this only when whack tells it to --listen, so the interfaces must be configured by then. Each interface with a name of the form ipsec[0-9] is taken as a KLIPS virtual public interface. Another network interface with the same IP address (there should be only one) is taken as the corresponding real public interface. ifconfig(8) with the -a flag will show the name and status of each network interface.

pluto requires a database of preshared secrets and RSA private keys. This is described in the ipsec.secrets(5). pluto is told of RSA public keys via whack commands.  

Setting up KLIPS for pluto

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

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

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

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

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

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

ipsec.secrets file

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

The file /etc/ipsec.secrets is used to keep preshared secret keys and RSA private keys for authentication with other IKE daemons. For debugging, there is an argument to the pluto command to use a different file. This file is described in ipsec.secrets(5).  

Running Pluto

To fire up the daemon, just type pluto (be sure to be running as the superuser). The default IKE port number is 500, the UDP port assigned by IANA for IKE Daemons. pluto must be run by the superuser to be able to use the UDP 500 port.

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

pluto then forks and the parent exits. This is the conventional ``daemon fork''. It can make debugging awkward, so there is an option to suppress this fork.

All logging, including diagnostics, is sent to syslog(3); 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.

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

Pluto's Internal State

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

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

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

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

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

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 peer's IP address or the nexthop if specified), 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 gateways or interfaces.

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

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

When pluto needs to install an eroute for an IPsec SA (for a state object), first the state object's connection must be routed (if this cannot be done, the eroute and SA will not be installed). If a conflicting eroute is already in place for another connection, the eroute and SA will not be installed. If another IPsec SA for the same connection already has an eroute, all its outgoing traffic is taken over by the new eroute. The incoming traffic will still be processed. This characteristic is exploited during rekeying.

All of these routing characteristics are expected change when KLIPS is modified to use the firewall hooks in the LINUX 2.2.x kernel.  

Using Whack

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

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

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

--ctlbase path
path.ctl is used as the UNIX domain socket for talking to pluto. This option facilitates debugging.
--optionsfrom filename
adds the contents of the file to the argument list.
--label string
adds the string to all error messages generated by whack.

The help form of whack is self-explanatory.

--help
display the usage message.
--version
display the version of whack.

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

The description of a potential connection can specify a large number of details. Each connection has a unique name.

--name connection-name

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

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

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

--id id
the identity of the end. Currently, this can be an IP address (specified as dotted quad or as a Fully Qualified Domain Name, which will be resolved immediately) or as a Fully Qualified Domain Name itself (prefixed by ``@'' to signify that it should not be resolved). If the option is absent, the identity defaults to the IP address specified by --host.
--host ip-address
the IP address of the end. If pluto is to act as a responder for IKE negotiations initiated from unknown IP addresses, the IP address should not be specified for the peer. In other cases, it must be.
--ikeport port-number
the UDP port that IKE listens to on that host. The default is 500. (pluto on this machine uses the port specified by its own command line argument, so this only affects where pluto sends messages.)
--nexthop ip-address
where to route packets for the peer's client (presumably for the peer too, but it will not be used for this). When pluto installs an IPsec SA, it issues a route command. It uses the nexthop as the gateway. The default is the peer's IP address, and this is usually correct. This option is necessary if pluto's host's interface used for sending packets to the peer is neither point-to-point nor directly connected to the peer.
--client subnet
the subnet for which the IPsec traffic will be destined. If not specified, the host will be the client (but this doesn't yet work). The subnet can be specified in any of the forms supported by ipsec_atosubnet(3). The general form is address/mask. The address can be either a domain name or four decimal numbers (specifying octets) separated by dots. The most convenient form of the mask is a decimal integer, specifying the number of leading one bits in the mask. So, for example, 10.0.0.0/8 would specify the class A network ``Net 10''.
--firewall
This indicates that whenever the connection is routed, pluto should instruct the firewall (via ipfwadm(8)) to forward these packets without masquerading. This option will only be acted upon if there is a client subnet containing more than just the host.
--to
separates the specification of the left and right ends of the connection.

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

--rsasig
Propose and allow RSA signatures for authentication of IKE peers. This authentication requires that each side have have a private key of its own and know the public key of its peer. May be combined with --psk.
--psk
Propose and allow preshared secret authentication for IKE peers. This authentication requires that each side use the same secret. May be combined with --rsasig. pluto supported for a long time.

If neither --rsasig nor --psk is specified, the initiator will default to proposing those for which it has the required keying material. The responder defaults similarly, but does not know the identity of the initiator (except for its IP address), so it is willing to accept RSA Sig if it is proposed (PSK cannot use the Identity payload, so the responder does know if it can handle PSK).

--encrypt
All proposed or accepted IPsec SAs will include non-null ESP. The actual choices of transforms are wired into pluto.
--authenticate
All proposed IPsec SAs will include AH. All accepted IPsec SAs will include AH or ESP with authentication. The actual choices of transforms are wired into pluto.
--tunnel
the IPsec SA should use tunneling. Implicit if the SA is for clients. Must only be used with --authenticate or --encrypt.
--pfs
There should be Perfect Forward Secrecy - new keying material should be generated for each IPsec SA rather than being derived from the ISAKMP SA keying material. Since the group to be used cannot be negotiated (a dubious feature of the standard), pluto will propose the same group that was used in Phase 1.

If none of the --encrypt, --authenticate, or --pfs flags is given, the initiating the connection will only build an ISAKMP SA.

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 MODP768 and MODP1024; 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.

--ikelifetime seconds
how long an ISAKMP SA is allowed to live. The default is 3600 (one hour).
--ipseclifetime seconds
how long an IPsec SA is allowed to live. The default is 28800 (eight hours).
--rekeymargin seconds
how long before an SA's expiration should pluto try to negotiate a replacement SA. This will only happen if pluto was the Initiator. The default is 540 (nine minutes).
--rekeyfuzz percentage
maximum size of random component to add to rekeymargin, expressed as a percentage of rekeymargin. pluto will select a delay uniformly distributed within this range. By default, the percentage will be 100. If greater determinism is desired, specify 0. It may be appropriate for the percentage to be much larger than 100.
--keyingtries count
how many times pluto should try to negotiate an SA, either for the first time or for rekeying. A value of 0 is interpreted as a very large number: never give up. The default is three.
--delete
when used in the connection form, it causes any previous connection with this name to be deleted before this one is added. Unlike a normal delete, no diagnostic is produced if there was no previous connection to delete. Any routing in place for the connection is undone.

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.

--delete
--name connection-name

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

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.

--route
--name connection-name

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

--unroute
--name connection-name

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

--initiate
--name connection-name
--asynchronous

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

The terminate form tells pluto to delete any SAs that use the specified connection and to stop any negotiations in process. It does not prevent new negotiations from starting (the delete form has this effect).

--terminate
--name connection-name

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

--keyid id
specififies the identity of the peer for which this public key should be used. Its form is identical to the identity in the connection.
--pubkeyrsa key
specifies the value of the RSA public key. It is a sequence of bytes as described in RFC 2537 ``RSA/MD5 KEYs ind SIGs in the Domain Name System (DNS)''. It is denoted in a way suitable for ipsec_atodata(3). For example, a base 64 numeral starts with 0s.

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

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

The status form will display information about the internal state of pluto: information about each potential connection and about each state object.

--status

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

--shutdown
 

Examples

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

   ipsec pluto

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

Using whack, several potential connections would be described:

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

Since this silly connection description specifies neither encryption, authentication, nor tunneling, it could only be used to establish an ISAKMP SA.
   ipsec whack --name secret --host 10.0.0.1 --client 10.0.1.0/24 --to --host 10.0.0.2 --client 10.0.2.0/24 --encrypt

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

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

   ipsec whack --listen

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

   ipsec whack --route secret

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

   ipsec whack --initiate --name secret

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

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

   ipsec whack --shutdown

At this time, the tearing down is all local: no notification is given to the peers.  

Rekeying

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

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

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

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

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

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

Road Warrior Support

All configuring has presumed that the IP addresses (or domain names) 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). Worse, the IKE protocol's Main Mode doesn't support authentication by preshared key when the identity of each party isn't evident from the source IP address of its packets.

There are several ways to support mobile parties. As a temporary expedient pluto implements the following scheme. This technique will likely be replaced by a better one. 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 0.0.0.0 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 0.0.0.0 replaced by the source IP address from the packet. This connection is used for the rest of the negotiation of the ISAKMP SA. When it needs to find the preshared secret or RSA public key, it looks for one with indices of its own IP number and 0.0.0.0 (there must never be more than one).

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

To configure support for Road Warrior, the responder must have a connection with 0.0.0.0 (as described above) and it must have a single secret with 0.0.0.0 as an index (and its own IP number as another index). Be sure to specify an appropriate nexthop for the responder to send a message to the initiator: pluto has no way of guessing it (if forwarding isn't required, use an explicit 0.0.0.0 as the nexthop and the IP address of the initiator will be filled in).

Although several different mobile initiators can be supported at once, there are important limitations. All mobile initiators must share the same secret (not a very healthy situation). All must share the same (pre-substitution) connection descriptions. This makes supporting mobile client subnets difficult because all road warriors are hence authorized to use the same set of subnets. Furthermore, pluto does no automatic substitution of client subnets.

pluto has no special provision for the initiator side. The current (possibly dynamic) IP address and gateway must be used in defining connections and as an index in the ipsec.secrets file. These must be properly configured each time the initiator's IP address changes. pluto has no mechanism to do this automatically.

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

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

Debugging

pluto accepts several optional arguments, useful mostly for debugging.

--ikeport port-number
changes the UDP port that pluto will use (default, specified by IANA: 500)
--ctlbase path
basename for control files. path.ctl is the socket through which whack communicates with pluto. path.pid is the lockfile to prevent multiple pluto instances. The default is /var/run/pluto).
--secretsfile file
specifies the file for authentication secrets (default: /etc/ipsec.secrets). This name is subject to ``globbing'' as in sh(1), so every file with a matching name is processed. Quoting is generally needed to prevent the shell from doing the globbing.
--nofork
disable ``daemon fork'' (default is to fork)
--noklips
don't actually implement negotiated IPsec SAs
--stderrlog
log goes to standard out {default is to use syslogd(8))

For example

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

lets one test pluto without using the superuser account.

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

When pluto is invoked, it may be given arguments to specify which classes to output. Furthermore, the debug form of the whack command will change the selection in a running pluto. The current options are:

--debug-raw
show the raw bytes of messages
--debug-crypt
show the encryption and decryption of messages
--debug-parsing
show the structure of input messages
--debug-emitting
show the structure of output messages
--debug-control
show pluto's decision making
--debug-klips
show pluto's interaction with KLIPS
--debug-all
all of the above
--debug-private
allow debugging output with private keys.
--debug-none
none of the above

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

pluto --debug-emitting --debug-parsing

To later change this pluto to only display raw bytes:

whack --debug-raw

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

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

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

Pluto's Behaviour When Things Go Wrong

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

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

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

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

Notes

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

EXIT STATUS

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

0
means that all is OK so far.
1
means that something was wrong.
10
means that the lock file already exists.

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

FILES

/var/run/pluto.pid
/var/run/pluto.ctl
/etc/ipsec.secrets  

SEE ALSO

The rest of the FreeS/WAN distribution, in particular ipsec(8).

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

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

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

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

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

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

RFC2409 The Internet Key Exchange (IKE)
RFC2408 Internet Security Association and Key Management Protocol (ISAKMP)
RFC2407 The Internet IP Security Domain of Interpretation for ISAKMP

The linux-ipsec@clinet.fi mailing list.  

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.

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

It is currently (1999) 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.

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

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

BUGS

pluto is a work-in-progress. It currently has many limitations. For example, it ignores notification messages that it receives, and it generates none.

FreeS/WAN currently provides no support for IPcomp compression.

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

Substitute your public interface for eth0 if it is different.

The RSA signature authentication mode uses code that, if executed in the United States before 2000 September 20, violates a US patent. There is a compile-time option to eliminate this temptation (NO_RSA). If we allowed RSAREF code to be substituted, this restriction would not apply in certain cases.

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.

Bugs should be reported to the linux-ipsec@clinet.fi 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.


 

Index

NAME
SYNOPSIS
DESCRIPTION
IKE's Job
Pluto
Before Running Pluto
Setting up KLIPS for pluto
ipsec.secrets file
Running Pluto
Pluto's Internal State
Using Whack
Examples
Rekeying
Road Warrior Support
Debugging
Pluto's Behaviour When Things Go Wrong
Notes
EXIT STATUS
FILES
SEE ALSO
HISTORY
BUGS

This document was created by man2html, using the manual pages.
Time: 22:03:03 GMT, December 14, 1999