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 --host127.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 conn_name --host 10.0.0.1 --client 10.0.1.0/24 --to --host 10.0.0.2 --client 10.0.2.0/24 --encrypt

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 conn_name

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

ipsec whack --initiate --name conn_name

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

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

ipsec whack --shutdown

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

XAUTH¶

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

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

The updown command¶

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

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

prepare-host or prepare-client

route-host or route-client

unroute-host or unroute-client

up-host or up-client

down-host or down-client

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

PLUTO_VERB

PLUTO_CONNECTION

PLUTO_NEXT_HOP

PLUTO_INTERFACE

PLUTO_ME

PLUTO_MY_CLIENT

PLUTO_MY_CLIENT_NET

PLUTO_MY_CLIENT_MASK

PLUTO_PEER

PLUTO_PEER_CLIENT

PLUTO_PEER_CLIENT_NET

PLUTO_PEER_CLIENT_MASK

PLUTO_MY_PROTOCOL

PLUTO_PEER_PROTOCOL

PLUTO_MY_PORT

PLUTO_PEER_PORT

PLUTO_MY_ID

PLUTO_PEER_ID

PLUTO_PEER_CA

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

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

Rekeying¶

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

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

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

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

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

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

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

Selecting a Connection When Responding: Road Warrior Support¶

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

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

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

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

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

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

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

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

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

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

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

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

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

Debugging¶

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

--interface interfacename

--ikeport port-number

--secretsfile file

--nofork

--uniqueids

--force-busy

--stderrlog

pluto is willing to produce a prodigious amount of debugging information. 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 normal diagnostic messages.

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

--debug help (whack only)

--debug none

--debug base

--debug cpu-usage

--debug class, --no-debug class, --debug no-class

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

For example, to start pluto with both base and cpu-usage debug-logging enabled:

To later change this pluto to disable base debug-logging use either:

or:

Impairing¶

pluto and whack accept several optional arguments that alter (impair) correct behaviour.

These options are solely intended for use by developers when testing pluto.

--impair help (whack only)

--impair list (whack only)

--impair none

--impair behaviour, --impair behaviour:how, --no-impair behaviour

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 might use Notifications to accomplish this in many cases). It does log a diagnostic.

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

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

Combine these three rules, and you can explain many apparently mysterious behaviours. In a pluto log, retrying isn't usually the interesting event. The critical thing is either earlier (pluto got a message that 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¶

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

Policies¶

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

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

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

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

•

•

•

•

•

•

•

•

•

•