Provided by: openswan_2.6.38-1_amd64 
NAME
ipsec_pluto - ipsec whack : IPsec IKE keying daemon and control interface
SYNOPSIS
ipsec pluto [--help] [--version] [--optionsfrom filename] [--nofork] [--stderrlog]
[--use-auto] [--use-klips] [--use-mast] [--use-netkey] [--use-nostack] [--uniqueids]
[--nat_traversal] [--virtual_private network_list] [--keep_alive delay_sec]
[--force_keepalive] [--force_busy] [--disable_port_floating] [--nocrsend]
[--strictcrlpolicy] [--crlcheckinterval] [--ocspuri] [--interface interfacename]
[--listen ipaddr] [--ikeport portnumber] [--ctlbase path]
[--secretsfile secrets-file] [--adns pathname] [--nhelpers number]
[--lwdnsq pathname] [--perpeerlog] [--perpeerlogbase dirname] [--ipsecdir dirname]
[--coredir dirname] [--noretransmits]
ipsec whack [--help] [--version]
ipsec whack [--debug-none] [--debug-all] [--debug-raw] [--debug-crypt] [--debug-parsing]
[--debug-emitting] [--debug-control] [--debug-lifecycle] [--debug-klips]
[--debug-pfkey] [--debug-nat-t] [--debug-dpd] [--debug-dns] [--debug-oppo]
[--debug-oppoinfo] [--debug-whackwatch] [--debug-private]
ipsec whack --name connection-name [[--ipv4] | [--ipv6]] [[--tunnelipv4] | [--tunnelipv6]]
[--id identity] [--host ip-address] [--cert path] [--ca distinguished name]
[--groups access control groups]
[--sendcert yes | forced | always | ifasked | no | never] [--certtype number]
[--ikeport portnumber] [--nexthop ip-address] [[--client subnet] |
[--clientwithin subnet]] [--clientprotoport protocol/port] [--srcip ip-address]
[--xauthserver] [--xauthclient] [--modecfgserver] [--modecfgclient] [--modecfgdns1]
[--modecfgdns2] [--modecfgwins1] [--modecfgwins2] [--dnskeyondemand]
[--updown updown]
--to
[--id identity] [--host ip-address] [--cert path] [--ca distinguished name]
[--groups access control groups] [--sendcert yes | always | ifasked | no | never]
[--certtype number] [--ikeport port-number] [--nexthop ip-address] [--client subnet]
[--clientwithin subnet] [--clientprotoport protocol/port] [--srcip ip-address]
[--xauthserver] [--xauthclient] [--modecfgserver] [--modecfgclient]
[--modecfgdns1 ip-address] [--modecfgdns2 ip-address] [--modecfgwins1 ip-address]
[--modecfgwins2 ip-address] [--dnskeyondemand] [--updown updown]
[--tunnel] [--psk] [--rsasig] [--encrypt] [--authenticate] [--compress] [--pfs]
[--pfsgroup [modp1024] | [modp1536] | [modp2048] | [modp3072] | [modp4096] |
[modp6144] | [modp8192]] [--disablearrivalcheck] [--ikelifetime seconds]
[--ipseclifetime seconds] [--rekeymargin seconds] [--rekeyfuzz percentage]
[--keyingtries count] [--esp esp-algos] [--dontrekey] [--aggrmode] [--modecfgpull]
[[--dpddelay seconds] | [--dpdtimeout seconds]] [--dpdaction [clear] | [hold] |
[restart]] [--forceencaps] [[--initiateontraffic] | [--pass] | [--drop] |
[--reject]] [[--failnone] | [--failpass] | [--faildrop] | [--failreject]] [--ctlbase
path] [--optionsfrom filename] [--label string]
ipsec whack --keyid id [--addkey] [--pubkeyrsa key] [--ctlbase path]
[--optionsfrom filename] [--label string]
ipsec whack --myid id
ipsec whack --listen | --unlisten [--ctlbase path] [--optionsfrom filename]
[--label string]
ipsec whack --route | --unroute --name connection-name [--ctlbase path]
[--optionsfrom filename] [--label string]
ipsec whack --initiate | --terminate --name connection-name [--xauthuser user]
[--xauthpass pass] [--asynchronous] [--ctlbase path] [--optionsfrom filename]
[--label string]
ipsec whack [[--tunnelipv4] | [--tunnelipv6]] --oppohere ip-address --oppothere ip-address
ipsec whack --crash [ipaddress]
ipsec whack --whackrecord [filename]
ipsec whack --whackstoprecord
ipsec whack --name connection-name --delete [--ctlbase path] [--optionsfrom filename]
[--label string]
ipsec whack --deletestate state-number [--ctlbase path] [--optionsfrom filename]
[--label string]
ipsec whack [--name connection-name] [--debug-none] [--debug-all] [--debug-raw]
[--debug-crypt] [--debug-parsing] [--debug-emitting] [--debug-control]
[--debug-controlmore] [--debug-lifecycle] [--debug-klips] [--debug-pfkey]
[--debug-dns] [--debug-dpd] [--debug-natt] [--debug-oppo] [--debug-oppoinfo]
[--debug-whackwatch] [--debug-private] [--impair-delay-adns-key-answer]
[--impair-delay-adns-txt-answer] [--impair-bust-mi2] [--impair-bust-mr2]
[--impair-sa-fail] [--impair-die-oninfo] [--impair-jacob-two-two]
ipsec whack [--utc] [--listall] [--listpubkeys] [--listcerts] [--listcacerts]
[--listacerts] [--listaacerts] [--listocspcerts] [--listgroups] [--listcrls]
[--listocsp]
ipsec whack [--utc] [--rereadsecrets] [--rereadall] [--rereadcacerts] [--rereadacerts]
[--rereadaacerts] [--rereadocspcerts] [--rereadcrls]
ipsec whack --purgeocsp
ipsec whack --listevents
ipsec whack --status [--ctlbase path] [--optionsfrom filename] [--label string]
ipsec whack --shutdown [--ctlbase path] [--optionsfrom filename] [--label string]
DESCRIPTION
pluto is an IKE (“IPsec Key Exchange”) daemon. whack is an auxiliary program to allow
requests to be made to a running pluto.
pluto is used to automatically build shared “security associations” on a system that has
IPsec, the secure IP protocol. In other words, pluto can eliminate much of the work of
manual keying. The actual secure transmission of packets is the responsibility of other
parts of the system - the kernel. Pluto can talk to various kernel implementations, such
as KLIPS, such as NETKEY, and such as KAME IPsec stacks. ipsec_auto(8) provides a more
convenient interface to pluto and whack.
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. An ISAKMP SA is used to protect communication
between the two IKEs. IPsec SAs can then be built by the IKEs - these are used to carry
protected IP traffic between the systems.
The negotiation of the ISAKMP SA is known as Phase 1. In theory, Phase 1 can be
accomplished by a couple of different exchange types. Currently, Main Mode and Aggressive
Mode are implemented.
Any negotiation under the protection of an ISAKMP SA, including the negotiation of IPsec
SAs, is part of Phase 2. The exchange type that we use to negotiate an IPsec SA is called
Quick Mode.
IKE instances must be able to authenticate each other as part of their negotiation of an
ISAKMP SA. This can be done by several mechanisms described in the draft standards.
IKE negotiation can be initiated by any instance with any other. If both can find an
agreeable set of characteristics for a Security Association, and both recognize each
others authenticity, they can set up a Security Association. The standards do not specify
what causes an IKE instance to initiate a negotiation.
In summary, an IKE instance is prepared to automate the management of Security
Associations in an IPsec environment, but a number of issues are considered policy and are
left in the system administrator´s hands.
Pluto
pluto is an implementation of IKE. It runs as a daemon on a network node. Currently, this
network node must be a LINUX system running the KLIPS or NETKEY implementation of IPsec,
or a FreeBSD/NetBSD/Mac OSX system running the KAME implementation of IPsec.
pluto implements a large subset of IKE. This is enough for it to interoperate with other
instances of pluto, and many other IKE implementations. It currently supports XAUTH,
ModeConfig, X.509, Dead Peer Detection, Opportunistic Encryption and all the NAT Traversal
standards.
The policy for acceptable characteristics for Security Associations is mostly hardwired
into the code of pluto (spdb.c). Eventually this will be moved into a security policy
database with reasonable expressive power and more convenience.
pluto uses shared secrets or RSA signatures to authenticate peers with whom it is
negotiating. These RSA signatures can come from DNS(SEC), a configuration file, or from
X.509 and CA certificates.
pluto initiates negotiation of a Security Association when it is manually prodded: the
program whack is run to trigger this. It will also initiate a negotiation when KLIPS traps
an outbound packet for Opportunistic Encryption.
pluto implements ISAKMP SAs itself. After it has negotiated the characteristics of an
IPsec SA, it directs the kernel to implement it. If necessary, it also invokes a script to
adjust any firewall and issue route(8) commands to direct IP packets.
When pluto shuts down, it closes all Security Associations.
Before Running Pluto
pluto runs as a daemon with userid root. Before running it, a few things must be set up.
pluto requires a working IPsec stack.
pluto supports multiple public networks (that is, networks that are considered insecure
and thus need to have their traffic encrypted or authenticated). It discovers the public
interfaces to use by looking at all interfaces that are configured (the --interface option
can be used to limit the interfaces considered). It does this only when whack tells it to
--listen, so the interfaces must be configured by then. Each interface with a name of the
form ipsec[0-9] is taken as a KLIPS virtual public interface. Another network interface
with the same IP address (the first one found will be used) is taken as the corresponding
real public interface. The --listen can be used to limit listening on only 1 IP address of
a certain interface. ifconfig(8) or ip(8) with the -a flag will show the name and status
of each network interface.
pluto requires a database of preshared secrets and RSA private keys. This is described in
the ipsec.secrets(5). pluto is told of RSA public keys via whack commands. If the
connection is Opportunistic, and no RSA public key is known, pluto will attempt to fetch
RSA keys using the Domain Name System.
Setting up KLIPS for pluto
The most basic network topology that pluto supports has two security gateways negotiating
on behalf of client subnets. The diagram of RGB´s testbed is a good example (see
klips/doc/rgb_setup.txt).
The file INSTALL in the base directory of this distribution explains how to start setting
up the whole system, including KLIPS.
Make sure that the security gateways have routes to each other. This is usually covered by
the default route, but may require issuing route(8) commands. The route must go through a
particular IP interface (we will assume it is eth0, but it need not be). The interface
that connects the security gateway to its client must be a different one.
It is necessary to issue a ipsec_tncfg(8) command on each gateway. The required command
is:
ipsec tncfg --attach --virtual ipsec0 --physical eth0
A command to set up the ipsec0 virtual interface will also need to be run. It will have
the same parameters as the command used to set up the physical interface to which it has
just been connected using ipsec_tncfg(8).
Setting up NETKEY for pluto
No special requirements are necessary to use NETKEY - it ships with all modern versions of
Linux 2.4 and 2.6. however, note that certain vendors or older distributions use old
versions or backports of NETKEY which are broken. If possible use a NETKEY version that is
at least based on, or backported from Linux 2.6.11 or newer.
ipsec.secrets file
A pluto daemon and another IKE daemon (for example, another instance of pluto) must
convince each other that they are who they are supposed to be before any negotiation can
succeed. This authentication is accomplished by using either secrets that have been shared
beforehand (manually) or by using RSA signatures. There are other techniques, but they
have not been implemented in pluto.
The file /etc/ipsec.secrets is used to keep preshared secret keys, RSA private keys, X.509
encoded keyfiles and XAUTH passwords. Smartcards are handled via NSS. For debugging, there
is an argument to the pluto command to use a different file. This file is described in
ipsec.secrets(5).
Running Pluto
To fire up the daemon, just type pluto (be sure to be running as the superuser). The
default IKE port number is 500, the UDP port assigned by IANA for IKE Daemons. pluto must
be run by the superuser to be able to use the UDP 500 port. If pluto is told to enable
NAT-Traversal, then UDP port 4500 is also taken by pluto to listen on.
Pluto supports different IPstacks on different operating systems. The option --use-auto,
which is also the default, lets pluto find a stack automatically. This behaviour can be
changed by explicitly setting the stack using --use-klips, --use-mast, --use-bsdkame
--use-netkey or --use-nostack. The latter is meant for testing only - no actual IPsec
connections will be loaded into the kernel.
Pluto supports the NAT-Traversal drafts and the final standard, RFC 3947, if the
--nat_traversal is specified. The allowed range behind the NAT routers is submitted using
the --virtual_private option. See ipsec.conf(5) for the syntax. The option
--force_keepalive forces the sending of the keep-alive packets, which are send to prevent
the NAT router from closing its port when there is not enough traffic on the IPsec
connection. The --keep_alive sets the delay (in seconds) of these keep-alive packets. The
newer NAT-T standards support port floating, and Openswan enables this per default. It can
be disabled using the --disable_port_floating option.
Pluto supports the use of X.509 certificates and sends it certificate when needed. This
can confuse IKE implementations that do not implement this, such as the old FreeS/WAN
implementation. The --nocrsend prevents pluto from sending these. At startup, pluto loads
all the X.509 related files from the directories /etc/ipsec.d/certs, /etc/ipsec.d/cacerts,
/etc/ipsec.d/aacerts, /etc/ipsec.d/ocspcerts, /etc/ipsec.d/private and /etc/ipsec.d/crls.
The Certificate Revocation Lists can also be retrieved from an URL. The option
--crlcheckinterval sets the time between checking for CRL expiration and issuing new fetch
commands. The first attempt to update a CRL is started at 2*crlcheckinterval before the
next update time. Pluto logs a warning if no valid CRL was loaded or obtained for a
connection. If --strictcrlpolicy is given, the connection will be rejected until a valid
CRL has been loaded. Pluto also has support for the Online Certificate Store Protocol
(OSCP) as defined in RFC 2560. The URL to the OSCP store can be given to pluto via the
--ocspuri option.
Pluto can use the BIND9 secure resolver, which means it has support for DNSSEC, using the
BIND9 lwres {} interface, see named.conf(5). Pluto can also use the old adns interface if
there is no BIND9 running with lwres {} on the host, but then pluto cannot do any DNSSEC
processing. Pluto forks and starts these DNS helpers in separate children. The options
--lwdnsq and --adns invoke these resolvers.
Pluto can also use helper children to off-load cryptographic operations. This behavior can
be fine tuned using the --nhelpers. Pluto will start (n-1) of them, where n is the number
of CPU’s you have (including hypherthreaded CPU’s). A value of 0 forces pluto to do all
operations in the main process. A value of -1 tells pluto to perform the above
calculation. Any other value forces the number to that amount.
pluto attempts to create a lockfile with the name /var/run/pluto/pluto.pid. If the
lockfile cannot be created, pluto exits - this prevents multiple plutos from competing Any
“leftover” lockfile must be removed before pluto will run. pluto writes its pid into this
file so that scripts can find it. This lock will not function properly if it is on an NFS
volume (but sharing locks on multiple machines doesn´t make sense anyway).
pluto then forks and the parent exits. This is the conventional “daemon fork”. It can make
debugging awkward, so there is an option to suppress this fork. In certain configurations,
pluto might also launch helper programs to assist with DNS queries or to offload
cryptographic operations.
All logging, including diagnostics, is sent to syslog(3) with facility=authpriv; it
decides where to put these messages (possibly in /var/log/secure). Since this too can make
debugging awkward, the option --stderrlog is used to steer logging to stderr.
If the --perpeerlog option is given, then pluto will open a log file per connection. By
default, this is in /var/log/pluto/peer, in a subdirectory formed by turning all dot (.)
[IPv4} or colon (:) [IPv6] into slashes (/).
The base directory can be changed with the --perpeerlogbase.
Once pluto is started, it waits for requests from whack.
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.
Pluto supports food groups, and X.509 certificates. These are located in /etc/ipsec.d, or
another directory as specified by --ipsecdir.
Pluto may core dump. It will normally do so into the current working directory. The
standard scripts have an option dumpdir=, which can set the current directory to determine
where the core dump will go. In some cases, it may be more convenient to specify it on the
command line using --coredir. A third method is to set the environment variable
PLUTO_CORE_DIR. The command line argument takes precedence over the environment variable.
The option plutorestartoncrash can be set to no to prevent multiple core files and a
looping pluto process. Normally, when pluto crashes, another pluto process is started.
At times it may be desireable to turn off all timed events in pluto, this can be done with
--noretransmits.
The (potential) connection database describes attributes of a connection. These include
the IP addresses of the hosts and client subnets and the security characteristics desired.
pluto requires this information (simply called a connection) before it can respond to a
request to build an SA. Each connection is given a name when it is created, and all
references are made using this name.
During the IKE exchange to build an SA, the information about the negotiation is
represented in a state object. Each state object reflects how far the negotiation has
reached. Once the negotiation is complete and the SA established, the state object remains
to represent the SA. When the SA is terminated, the state object is discarded. Each State
object is given a serial number and this is used to refer to the state objects in logged
messages.
Each state object corresponds to a connection and can be thought of as an instantiation of
that connection. At any particular time, there may be any number of state objects
corresponding to a particular connection. Often there is one representing an ISAKMP SA and
another representing an IPsec SA.
KLIPS hooks into the routing code in a LINUX kernel. Traffic to be processed by an IPsec
SA must be directed through KLIPS by routing commands. Furthermore, the processing to be
done is specified by ipsec eroute(8) commands. pluto takes the responsibility of managing
both of these special kinds of routes.
NETKEY requires no special routing.
Each connection may be routed, and must be while it has an IPsec SA. The connection
specifies the characteristics of the route: the interface on this machine, the “gateway”
(the nexthop), and the peer´s client subnet. Two connections may not be simultaneously
routed if they are for the same peer´s client subnet but use different interfaces or
gateways (pluto´s logic does not reflect any advanced routing capabilities).
On KLIPS, each eroute is associated with the state object for an IPsec SA because it has
the particular characteristics of the SA. Two eroutes conflict if they specify the
identical local and remote clients (unlike for routes, the local clients are taken into
account).
When pluto needs to install a route for a connection, it must make sure that no
conflicting route is in use. If another connection has a conflicting route, that route
will be taken down, as long as there is no IPsec SA instantiating that connection. If
there is such an IPsec SA, the attempt to install a route will fail.
There is an exception. If pluto, as Responder, needs to install a route to a fixed client
subnet for a connection, and there is already a conflicting route, then the SAs using the
route are deleted to make room for the new SAs. The rationale is that the new connection
is probably more current. The need for this usually is a product of Road Warrior
connections (these are explained later; they cannot be used to initiate).
When pluto needs to install an eroute for an IPsec SA (for a state object), first the
state object´s connection must be routed (if this cannot be done, the eroute and SA will
not be installed). If a conflicting eroute is already in place for another connection, the
eroute and SA will not be installed (but note that the routing exception mentioned above
may have already deleted potentially conflicting SAs). If another IPsec SA for the same
connection already has an eroute, all its outgoing traffic is taken over by the new
eroute. The incoming traffic will still be processed. This characteristic is exploited
during rekeying.
All of these routing characteristics are expected change when KLIPS and NETKEY merge into
a single new stack.
Using Whack
whack is used to command a running pluto. whack uses a UNIX domain socket to speak to
pluto (by default, /var/pluto.ctl).
whack has an intricate argument syntax. This syntax allows many different functions to be
specified. The help form shows the usage or version information. The connection form gives
pluto a description of a potential connection. The public key form informs pluto of the
RSA public key for a potential peer. The delete form deletes a connection description and
all SAs corresponding to it. The listen form tells pluto to start or stop listening on the
public interfaces for IKE requests from peers. The route form tells pluto to set up
routing for a connection; the unroute form undoes this. The initiate form tells pluto to
negotiate an SA corresponding to a connection. The terminate form tells pluto to remove
all SAs corresponding to a connection, including those being negotiated. The status form
displays the pluto´s internal state. The debug form tells pluto to change the selection of
debugging output “on the fly”. The shutdown form tells pluto to shut down, deleting all
SAs.
The crash option asks pluto to consider a particularly target IP to have crashed, and to
attempt to restart all connections with that IP address as a gateway. In general, you
should use Dead Peer Detection to detect this kind of situation automatically, but this is
not always possible.
Most options are specific to one of the forms, and will be described with that form. There
are three options that apply to all forms.
--ctlbase path
path.ctl is used as the UNIX domain socket for talking to pluto. This option
facilitates debugging.
--optionsfrom filename
adds the contents of the file to the argument list.
--label string
adds the string to all error messages generated by whack.
The help form of whack is self-explanatory.
--help
display the usage message.
--version
display the version of whack.
The connection form describes a potential connection to pluto. pluto needs to know what
connections can and should be negotiated. When pluto is the initiator, it needs to know
what to propose. When pluto is the responder, it needs to know enough to decide whether is
is willing to set up the proposed connection.
The description of a potential connection can specify a large number of details. Each
connection has a unique name. This name will appear in a updown shell command, so it
should not contain punctuation that would make the command ill-formed.
--name connection-name
sets the name of the connection
The topology of a connection is symmetric, so to save space here is half a picture:
client_subnet<-->host:ikeport<-->nexthop<---
A similar trick is used in the flags. The same flag names are used for both ends. Those
before the --to flag describe the left side and those afterwards describe the right side.
When pluto attempts to use the connection, it decides whether it is the left side or the
right side of the connection, based on the IP numbers of its interfaces.
--id id
the identity of the end. Currently, this can be an IP address (specified as dotted
quad or as a Fully Qualified Domain Name, which will be resolved immediately) or as a
Fully Qualified Domain Name itself (prefixed by “@” to signify that it should not be
resolved), or as user@FQDN, or an X.509 DN, or as the magic value %myid. Pluto only
authenticates the identity, and does not use it for addressing, so, for example, an IP
address need not be the one to which packets are to be sent. If the option is absent,
the identity defaults to the IP address specified by --host. %myid allows the
identity to be separately specified (by the pluto or whack option --myid or by the
ipsec.conf(5) config setup parameter myid). Otherwise, pluto tries to guess what %myid
should stand for: the IP address of %defaultroute, if it is supported by a suitable
TXT record in the reverse domain for that IP address, or the system´s hostname, if it
is supported by a suitable TXT record in its forward domain.
--host ip-address, --host %any, --host %opportunistic
the IP address of the end (generally the public interface). If pluto is to act as a
responder for IKE negotiations initiated from unknown IP addresses (the “Road Warrior”
case), the IP address should be specified as %any (currently, the obsolete notation
0.0.0.0 is also accepted for this). If pluto is to opportunistically initiate the
connection, use %opportunistic
--cert filename
The filename of the X.509 certificate. This must be the public key certificate only,
and cannot be the PKCS#12 certificate file. See ipsec.conf(5) on how to extrac this
from the PKCS#12 file.
--ca distinguished name
the X.509 Certificate Authority´s Distinguished Name (DN) used as trust anchor for
this connection. This is the CA certificate that signed the host certificate, as well
as the certificate of the incoming client.
--groups access control groups
the access control groups used.
--sendcert yes|forced|always|ifasked|no|never
Wether or not to send our X.509 certificate credentials. This could potentially give
an attacker too much information about which identities are allowed to connect to this
host. The default is to use ifasked when we are a Responder, and to use yes (which is
the same as forced and always if we are an Initiator. The values no and never are
equivalent. NOTE: "forced" does not seem to be actually implemented - do not use it.
--certtype number
The X.509 certificate type number.
--ikeport port-number
the UDP port that IKE listens to on that host. The default is 500. (pluto on this
machine uses the port specified by its own command line argument, so this only affects
where pluto sends messages.)
--nexthop ip-address
where to route packets for the peer´s client (presumably for the peer too, but it will
not be used for this). When pluto installs an IPsec SA, it issues a route command. It
uses the nexthop as the gateway. The default is the peer´s IP address (this can be
explicitly written as %direct; the obsolete notation 0.0.0.0 is accepted). This option
is necessary if pluto´s host´s interface used for sending packets to the peer is
neither point-to-point nor directly connected to the peer.
--client subnet
the subnet for which the IPsec traffic will be destined. If not specified, the host
will be the client. The subnet can be specified in any of the forms supported by
ipsec_atosubnet(3). The general form is address/mask. The address can be either a
domain name or four decimal numbers (specifying octets) separated by dots. The most
convenient form of the mask is a decimal integer, specifying the number of leading one
bits in the mask. So, for example, 10.0.0.0/8 would specify the class A network “Net
10”.
--clientwithin subnet
This option is obsolete and will be removed. Do not use this option anymore.
--clientprotoport protocol/port
specify the Port Selectors (filters) to be used on this connection. The general form
is protocol/port. This is most commonly used to limit the connection to L2TP traffic
only by specifying a value of 17/1701 for UDP (protocol 17) and port 1701. The
notation 17/%any can be used to allow all UDP traffic and is needed for L2TP
connections with Windows XP machines before Service Pack 2.
--srcip ip-address
the IP address for this host to use when transmitting a packet to the remote IPsec
gateway itself. This option is used to make the gateway itself use its internal IP,
which is part of the --client subnet. Otherwise it will use its nearest IP address,
which is its public IP address, which is not part of the subnet-subnet IPsec tunnel,
and would therefor not get encrypted.
--xauthserver
this end is an xauthserver. It will lookup the xauth user name and password and verify
this before allowing the connection to get established.
--xauthclient
this end is an xauthclient. To bring this connection up with the --initiate also
requires the client to specify --xauthuser username and --xauthpass password
--xauthuser
The username for the xauth authentication.This option is normally passed along by
ipsec_auto(8) when an xauth connection is started using ipsec auto --up conn
--xauthpass
The password for the xauth authentication. This option is normally passed along by
ipsec_auto(8) when an xauth connection is started using ipsec auto --up conn
--modecfgserver
this end is an Mode Config server
--modecfgclient
this end is an Mode Config client
--modecfgdns1
The IP address of the first DNS server to pass along to the ModeConfig Client
--modecfgdns2
The IP address of the second DNS server to pass along to the ModeConfig Client
--modecfgwins1
The IP address of the first WINS server to pass along to the ModeConfig Client
--modecfgwins2
The IP address of the second WINS server to pass along to the ModeConfig Client
--dnskeyondemand
specifies that when an RSA public key is needed to authenticate this host, and it
isn´t already known, fetch it from DNS.
--updown updown
specifies an external shell command to be run whenever pluto brings up or down a
connection. The script is used to build a shell command, so it may contain positional
parameters, but ought not to have punctuation that would cause the resulting command
to be ill-formed. The default is ipsec _updown. Pluto passes a dozen environment
variables to the script about the connection involved.
--to
separates the specification of the left and right ends of the connection. Pluto tries
to decide wether it is left or right based on the information provided on both sides
of this option.
The potential connection description also specifies characteristics of rekeying and
security.
--psk
Propose and allow preshared secret authentication for IKE peers. This authentication
requires that each side use the same secret. May be combined with --rsasig; at least
one must be specified.
--rsasig
Propose and allow RSA signatures for authentication of IKE peers. This authentication
requires that each side have have a private key of its own and know the public key of
its peer. May be combined with --psk; at least one must be specified.
--encrypt
All proposed or accepted IPsec SAs will include non-null ESP. The actual choices of
transforms are wired into pluto.
--authenticate
All proposed IPsec SAs will include AH. All accepted IPsec SAs will include AH or ESP
with authentication. The actual choices of transforms are wired into pluto. Note that
this has nothing to do with IKE authentication.
--compress
All proposed IPsec SAs will include IPCOMP (compression). This will be ignored if
KLIPS is not configured with IPCOMP support.
--tunnel
the IPsec SA should use tunneling. Implicit if the SA is for clients. Must only be
used with --authenticate or --encrypt.
--ipv4
The host addresses will be interpreted as IPv4 addresses. This is the default. Note
that for a connection, all host addresses must be of the same Address Family (IPv4 and
IPv6 use different Address Families).
--ipv6
The host addresses (including nexthop) will be interpreted as IPv6 addresses. Note
that for a connection, all host addresses must be of the same Address Family (IPv4 and
IPv6 use different Address Families).
--tunnelipv4
The client addresses will be interpreted as IPv4 addresses. The default is to match
what the host will be. This does not imply --tunnel so the flag can be safely used
when no tunnel is actually specified. Note that for a connection, all tunnel addresses
must be of the same Address Family.
--tunnelipv6
The client addresses will be interpreted as IPv6 addresses. The default is to match
what the host will be. This does not imply --tunnel so the flag can be safely used
when no tunnel is actually specified. Note that for a connection, all tunnel addresses
must be of the same Address Family.
--pfs
There should be Perfect Forward Secrecy - new keying material will be generated for
each IPsec SA rather than being derived from the ISAKMP SA keying material. Since the
group to be used cannot be negotiated (a dubious feature of the standard), pluto will
propose the same group that was used during Phase 1. We don´t implement a stronger
form of PFS which would require that the ISAKMP SA be deleted after the IPSEC SA is
negotiated.
--pfsgroup modp-group
Sets the Diffie-Hellman group used. Currently the following values are supported:
modp1024 (DHgroup 2), modp1536 (DHgroup 5), modp2048 (DHgroup 14), modp3072 (DHgroup
15), modp4096 (DHgroup 16), modp6144 (DHgroup 17), and modp8192 (DHgroup 18). It is
possible to support the weak and broken modp768 (DHgroup 1), but this requires a
manual recompile and is strongly discouraged.
--disablearrivalcheck
If the connection is a tunnel, allow packets arriving through the tunnel to have any
source and destination addresses.
--esp esp-algos
ESP encryption/authentication algorithm to be used for the connection (phase2 aka
IPsec SA). The options must be suitable as a value of ipsec_spi(8). See ipsec.conf(5)
for a detailed description of the algorithm format.
--aggrmode
This tunnel is using aggressive mode ISAKMP negotiation. The default is main mode.
Aggressive mode is less secure than main mode as it reveals your identity to an
eavesdropper, but is needed to support road warriors using PSK keys or to interoperate
with other buggy implementations insisting on using aggressive mode.
--modecfgpull
Pull the Mode Config network information from the peer.
--dpddelay seconds
Set the delay (in seconds) between Dead Peer Dectection (RFC 3706) keepalives
(R_U_THERE, R_U_THERE_ACK) that are sent for this connection (default 30 seconds).
--timeout seconds
Set the length of time (in seconds) we will idle without hearing either an R_U_THERE
poll from our peer, or an R_U_THERE_ACK reply. After this period has elapsed with no
response and no traffic, we will declare the peer dead, and remove the SA (default 120
seconds).
--dpdaction action
When a DPD enabled peer is declared dead, what action should be taken. hold(default)
means the eroute will be put into %hold status, while clearmeans the eroute and SA
with both be cleared. Clear is really only useful on the server of a Road Warrior
config. The action restart is used on tunnels that need to be permanently up, and have
static IP addresses.
--forceencaps
In some cases, for example when ESP packets are filtered or when a broken IPsec peer
does not properly recognise NAT, it can be useful to force RFC-3948 encapsulation
using this option. It causes pluto lie and tell the remote peer that RFC-3948
encapsulation (ESP in UDP port 4500 packets) is required. For this option to have any
effect, pluto must have been started with the --nat_traversal option.
If none of the --encrypt, --authenticate, --compress, or --pfs flags is given, the
initiating the connection will only build an ISAKMP SA. For such a connection, client
subnets have no meaning and must not be specified.
Apart from initiating directly using the --initiate option, a tunnel can be loaded with a
different policy
--initiateontraffic
Only initiate the connection when we have traffic to send over the connection
--pass
Allow unencrypted traffic to flow until the tunnel is initiated.
--drop
Drop unencrypted traffic silently.
--reject
Drop unencrypted traffic silently, but send an ICMP message notifying the other end.
These options need to be documented
--failnone
to be documented
--failpass
to be documented
--faildrop
to be documented
--failreject
to be documented
pluto supports various X.509 Certificate related options.
--utc
display all times in UTC.
--listall
lists all of the X.509 information known to pluto.
--listpubkeys
list all the public keys that have been successfully loaded.
--listcerts
list all the X.509 certificates that are currently loaded.
--checkpubkeys
list all the loaded X.509 certificates which are about to expire or have been expired.
--listcacerts
list all the X.509 Certificate Authority (CA) certificates that are currently loaded.
--listacerts
list all the X.509 Attribute certificates that are currently loaded
--listaacerts
--ocspcerts
list all of the X.509 certificates obtained via the Online Certificate Store Protocol
(OCSP)
--listgroups
--listcrls
list all the loaded Certificate Revocation Lists (CRLs)
The corresponding options --rereadsecrets, --rereadall, --rereadcacerts, --rereadacerts,
--rereadaacerts, --rereadocspcerts --rereadcrls, and --purgeocsp, options reread this
information from their respective sources, and purge all the online obtained information.
The option --listevents lists all pending CRL fetch commands.
More work is needed to allow for flexible policies. Currently policy is hardwired in the
source file spdb.c. The ISAKMP SAs may use Oakley groups MODP1024 and MODP1536; AES or
3DES encryption; SHA1-96 and MD5-96 authentication. The IPsec SAs may use AES or 3DES and
MD5-96 or SHA1-96 for ESP, or just MD5-96 or SHA1-96 for AH. IPCOMP Compression is always
Deflate.
--ikelifetime seconds
how long pluto will propose that an ISAKMP SA be allowed to live. The default is 3600
(one hour) and the maximum is 86400 (1 day). This option will not affect what is
accepted. pluto will reject proposals that exceed the maximum.
--ipseclifetime seconds
how long pluto will propose that an IPsec SA be allowed to live. The default is 28800
(eight hours) and the maximum is 86400 (one day). This option will not affect what is
accepted. pluto will reject proposals that exceed the maximum.
--rekeymargin seconds
how long before an SA´s expiration should pluto try to negotiate a replacement SA.
This will only happen if pluto was the initiator. The default is 540 (nine minutes).
--rekeyfuzz percentage
maximum size of random component to add to rekeymargin, expressed as a percentage of
rekeymargin. pluto will select a delay uniformly distributed within this range. By
default, the percentage will be 100. If greater determinism is desired, specify 0. It
may be appropriate for the percentage to be much larger than 100.
--keyingtries count
how many times pluto should try to negotiate an SA, either for the first time or for
rekeying. A value of 0 is interpreted as a very large number: never give up. The
default is three.
--dontrekey
A misnomer. Only rekey a connection if we were the Initiator and there was recent
traffic on the existing connection. This applies to Phase 1 and Phase 2. This is
currently the only automatic way for a connection to terminate. It may be useful with
Road Warrior or Opportunistic connections. Since SA lifetime negotiation is
take-it-or-leave it, a Responder normally uses the shorter of the negotiated or the
configured lifetime. This only works because if the lifetime is shorter than
negotiated, the Responder will rekey in time so that everything works. This interacts
badly with --dontrekey. In this case, the Responder will end up rekeying to rectify a
shortfall in an IPsec SA lifetime; for an ISAKMP SA, the Responder will accept the
negotiated lifetime.
--delete
when used in the connection form, it causes any previous connection with this name to
be deleted before this one is added. Unlike a normal delete, no diagnostic is produced
if there was no previous connection to delete. Any routing in place for the connection
is undone.
--delete, --name connection-name
The delete form deletes a named connection description and any SAs established or
negotiations initiated using this connection. Any routing in place for the connection
is undone.
--deletestate state-number
The deletestate form deletes the state object with the specified serial number. This
is useful for selectively deleting instances of connections.
The route form of the whack command tells pluto to set up routing for a connection.
Although like a traditional route, it uses an ipsec device as a virtual interface. Once
routing is set up, no packets will be sent “in the clear” to the peer´s client specified
in the connection. A TRAP shunt eroute will be installed; if outbound traffic is caught,
Pluto will initiate the connection. An explicit whack route is not always needed: if it
hasn´t been done when an IPsec SA is being installed, one will be automatically attempted.
--route, --name connection-name
When a routing is attempted for a connection, there must not already be a routing for
a different connection with the same subnet but different interface or destination, or
if there is, it must not be being used by an IPsec SA. Otherwise the attempt will
fail.
--unroute, --name connection-name
The unroute form of the whack command tells pluto to undo a routing. pluto will
refuse if an IPsec SA is using the connection. If another connection is sharing the
same routing, it will be left in place. Without a routing, packets will be sent
without encryption or authentication.
The initiate form tells pluto to initiate a negotiation with another pluto (or other IKE
daemon) according to the named connection. Initiation requires a route that --route would
provide; if none is in place at the time an IPsec SA is being installed, pluto attempts to
set one up.
--initiate, --name connection-name, --asynchronous
The initiate form of the whack command will relay back from pluto status information
via the UNIX domain socket (unless --asynchronous is specified). The status
information is meant to look a bit like that from FTP. Currently whack simply copies
this to stderr. When the request is finished (eg. the SAs are established or pluto
gives up), pluto closes the channel, causing whack to terminate.
The opportunistic initiate form is mainly used for debugging.
--tunnelipv4, --tunnelipv6, --oppohere ip-address, --oppothere ip-address
This will cause pluto to attempt to opportunistically initiate a connection from here
to the there, even if a previous attempt had been made. The whack log will show the
progress of this attempt.
Ending an connection
--terminate, --name connection-name
the terminate form tells pluto to delete any sas that use the specified connection and
to stop any negotiations in process. it does not prevent new negotiations from
starting (the delete form has this effect).
--crash ip-address
If the remote peer has crashed, and therefor did not notify us, we keep sending
encrypted traffic, and rejecting all plaintext (non-IKE) traffic from that remote
peer. The --crash brings our end down as well for all the known connections to the
specified ip-address
--whackrecordfilename, --whackstoprecord
this causes plutoto open the given filename for write, and record each of the messages
received from whack or addconn. This continues until the whackstoprecord option is
used. This option may not be combined with any other command. The start/stop commands
are not recorded themselves. These files are usually used to create input files for
unit tests, particularly for complex setups where policies may in fact overlap.
The format of the file consists of a line starting with #!pluto-whack and the date
that the file was started, as well as the hostname, and a linefeed. What follows are
binary format records consisting of a 32-bit record length in bytes, (including the
length record itself), a 64-bit timestamp, and then the literal contents of the whack
message that was received. All integers are in host format. In order to unambigously
determine the host order, the first record is an empty record that contains only the
current WHACK_MAGIC value. This record is 16 bytes long.
ip-address
If the remote peer has crashed, and therefor did not notify us, we keep sending
encrypted traffic, and rejecting all plaintext (non-IKE) traffic from that remote
peer. The --crash brings our end down as well for all the known connections to the
specified ip-address
The public key for informs pluto of the RSA public key for a potential peer. Private keys
must be kept secret, so they are kept in ipsec.secrets(5).
--keyid id
specififies the identity of the peer for which a public key should be used. Its form
is identical to the identity in the connection. If no public key is specified, pluto
attempts to find KEY records from DNS for the id (if a FQDN) or through reverse lookup
(if an IP address). Note that there several interesting ways in which this is not
secure.
--addkey
specifies that the new key is added to the collection; otherwise the new key replaces
any old ones.
--pubkeyrsa key
specifies the value of the RSA public key. It is a sequence of bytes as described in
RFC 2537 “RSA/MD5 KEYs and SIGs in the Domain Name System (DNS)”. It is denoted in a
way suitable for ipsec_ttodata(3). For example, a base 64 numeral starts with 0s.
The listen form tells pluto to start listening for IKE requests on its public interfaces.
To avoid race conditions, it is normal to load the appropriate connections into pluto
before allowing it to listen. If pluto isn´t listening, it is pointless to initiate
negotiations, so it will refuse requests to do so. Whenever the listen form is used, pluto
looks for public interfaces and will notice when new ones have been added and when old
ones have been removed. This is also the trigger for pluto to read the ipsec.secrets file.
So listen may useful more than once.
--listen
start listening for IKE traffic on public interfaces.
--unlisten
stop listening for IKE traffic on public interfaces.
The status form will display information about the internal state of pluto: information
about each potential connection, about each state object, and about each shunt that pluto
is managing without an associated connection.
--status
The shutdown form is the proper way to shut down pluto. It will tear down the SAs on this
machine that pluto has negotiated. It does not inform its peers, so the SAs on their
machines remain.
--shutdown
Examples
It would be normal to start pluto in one of the system initialization scripts. It needs to
be run by the superuser. Generally, no arguments are needed. To run in manually, the
superuser can simply type
ipsec pluto
The command will immediately return, but a pluto process will be left running, waiting for
requests from whack or a peer.
Using whack, several potential connections would be described:
ipsec whack --name silly --host 127.0.0.1 --to --host 127.0.0.2 --ikelifetime 900
--ipseclifetime 800 --keyingtries 3
Since this silly connection description specifies neither encryption, authentication, nor
tunneling, it could only be used to establish an ISAKMP SA.
ipsec whack --name secret --host 10.0.0.1 --client 10.0.1.0/24 --to --host 10.0.0.2
--client 10.0.2.0/24 --encrypt
This is something that must be done on both sides. If the other side is pluto, the same
whack command could be used on it (the command syntax is designed to not distinguish which
end is ours).
Now that the connections are specified, pluto is ready to handle requests and replies via
the public interfaces. We must tell it to discover those interfaces and start accepting
messages from peers:
ipsec whack --listen
If we don´t immediately wish to bring up a secure connection between the two clients, we
might wish to prevent insecure traffic. The routing form asks pluto to cause the packets
sent from our client to the peer´s client to be routed through the ipsec0 device; if there
is no SA, they will be discarded:
ipsec whack --route secret
Finally, we are ready to get pluto to initiate negotiation for an IPsec SA (and
implicitly, an ISAKMP SA):
ipsec whack --initiate --name secret
A small log of interesting events will appear on standard output (other logging is sent to
syslog).
whack can also be used to terminate pluto cleanly, tearing down all SAs that it has
negotiated.
ipsec whack --shutdown
Notification of any IPSEC SA deletion, but not ISAKMP SA deletion is sent to the peer.
Unfortunately, such Notification is not reliable. Furthermore, pluto itself ignores
Notifications.
XAUTH
If pluto needs additional authentication, such as defined by the XAUTH specifications,
then it may ask whack to prompt the operator for username or passwords. Typically, these
will be entered interactively. A GUI that wraps around whack may look for the 041
(username) or 040 (password) prompts, and display them to the user.
For testing purposes, the options --xauthuser user --xauthpass pass may be be given prior
to the --initiate to provide responses to the username and password prompts.
The updown command
Whenever pluto brings a connection up or down, it invokes the updown command. This command
is specified using the --updown option. This allows for customized control over routing
and firewall manipulation.
The updown is invoked for five different operations. Each of these operations can be for
our client subnet or for our host itself.
prepare-host or prepare-client
is run before bringing up a new connection if no other connection with the same
clients is up. Generally, this is useful for deleting a route that might have been set
up before pluto was run or perhaps by some agent not known to pluto.
route-host or route-client
is run when bringing up a connection for a new peer client subnet (even if
prepare-host or prepare-client was run). The command should install a suitable route.
Routing decisions are based only on the destination (peer´s client) subnet address,
unlike eroutes which discriminate based on source too.
unroute-host or unroute-client
is run when bringing down the last connection for a particular peer client subnet. It
should undo what the route-host or route-client did.
up-host or up-client
is run when bringing up a tunnel eroute with a pair of client subnets that does not
already have a tunnel eroute. This command should install firewall rules as
appropriate. It is generally a good idea to allow IKE messages (UDP port 500) travel
between the hosts.
down-host or down-client
is run when bringing down the eroute for a pair of client subnets. This command should
delete firewall rules as appropriate. Note that there may remain some inbound IPsec
SAs with these client subnets.
The script is passed a large number of environment variables to specify what needs to be
done.
PLUTO_VERSION
indicates what version of this interface is being used. This document describes
version 1.1. This is upwardly compatible with version 1.0.
PLUTO_VERB
specifies the name of the operation to be performed (prepare-host,r prepare-client,
up-host, up-client, down-host, or down-client). If the address family for security
gateway to security gateway communications is IPv6, then a suffix of -v6 is added to
the verb.
PLUTO_CONNECTION
is the name of the connection for which we are routing.
PLUTO_NEXT_HOP
is the next hop to which packets bound for the peer must be sent.
PLUTO_INTERFACE
is the name of the ipsec interface to be used.
PLUTO_ME
is the IP address of our host.
PLUTO_MY_CLIENT
is the IP address / count of our client subnet. If the client is just the host, this
will be the host´s own IP address / max (where max is 32 for IPv4 and 128 for IPv6).
PLUTO_MY_CLIENT_NET
is the IP address of our client net. If the client is just the host, this will be the
host´s own IP address.
PLUTO_MY_CLIENT_MASK
is the mask for our client net. If the client is just the host, this will be
255.255.255.255.
PLUTO_PEER
is the IP address of our peer.
PLUTO_PEER_CLIENT
is the IP address / count of the peer´s client subnet. If the client is just the peer,
this will be the peer´s own IP address / max (where max is 32 for IPv4 and 128 for
IPv6).
PLUTO_PEER_CLIENT_NET
is the IP address of the peer´s client net. If the client is just the peer, this will
be the peer´s own IP address.
PLUTO_PEER_CLIENT_MASK
is the mask for the peer´s client net. If the client is just the peer, this will be
255.255.255.255.
PLUTO_MY_PROTOCOL
lists the protocols allowed over this IPsec SA.
PLUTO_PEER_PROTOCOL
lists the protocols the peer allows over this IPsec SA.
PLUTO_MY_PORT
lists the ports allowed over this IPsec SA.
PLUTO_PEER_PORT
lists the ports the peer allows over this IPsec SA.
PLUTO_MY_ID
lists our id.
PLUTO_PEER_ID
Dlists our peer´s id.
PLUTO_PEER_CA
lists the peer´s CA.
All output sent by the script to stderr or stdout is logged. The script should return an
exit status of 0 if and only if it succeeds.
Pluto waits for the script to finish and will not do any other processing while it is
waiting. The script may assume that pluto will not change anything while the script runs.
The script should avoid doing anything that takes much time and it should not issue any
command that requires processing by pluto. Either of these activities could be performed
by a background subprocess of the script.
Rekeying
When an SA that was initiated by pluto has only a bit of lifetime left, pluto will
initiate the creation of a new SA. This applies to ISAKMP and IPsec SAs. The rekeying will
be initiated when the SA´s remaining lifetime is less than the rekeymargin plus a random
percentage, between 0 and rekeyfuzz, of the rekeymargin.
Similarly, when an SA that was initiated by the peer has only a bit of lifetime left,
pluto will try to initiate the creation of a replacement. To give preference to the
initiator, this rekeying will only be initiated when the SA´s remaining lifetime is half
of rekeymargin. If rekeying is done by the responder, the roles will be reversed: the
responder for the old SA will be the initiator for the replacement. The former initiator
might also initiate rekeying, so there may be redundant SAs created. To avoid these
complications, make sure that rekeymargin is generous.
One risk of having the former responder initiate is that perhaps none of its proposals is
acceptable to the former initiator (they have not been used in a successful negotiation).
To reduce the chances of this happening, and to prevent loss of security, the policy
settings are taken from the old SA (this is the case even if the former initiator is
initiating). These may be stricter than those of the connection.
pluto will not rekey an SA if that SA is not the most recent of its type (IPsec or ISAKMP)
for its potential connection. This avoids creating redundant SAs.
The random component in the rekeying time (rekeyfuzz) is intended to make certain
pathological patterns of rekeying unstable. If both sides decide to rekey at the same
time, twice as many SAs as necessary are created. This could become a stable pattern
without the randomness.
Another more important case occurs when a security gateway has SAs with many other
security gateways. Each of these connections might need to be rekeyed at the same time.
This would cause a high peek requirement for resources (network bandwidth, CPU time,
entropy for random numbers). The rekeyfuzz can be used to stagger the rekeying times.
Once a new set of SAs has been negotiated, pluto will never send traffic on a superseded
one. Traffic will be accepted on an old SA until it expires.
Selecting a Connection When Responding: Road Warrior Support
When pluto receives an initial Main Mode message, it needs to decide which connection this
message is for. It picks based solely on the source and destination IP addresses of the
message. There might be several connections with suitable IP addresses, in which case one
of them is arbitrarily chosen. (The ISAKMP SA proposal contained in the message could be
taken into account, but it is not.)
The ISAKMP SA is negotiated before the parties pass further identifying information, so
all ISAKMP SA characteristics specified in the connection description should be the same
for every connection with the same two host IP addresses. At the moment, the only
characteristic that might differ is authentication method.
Up to this point, all configuring has presumed that the IP addresses are known to all
parties ahead of time. This will not work when either end is mobile (or assigned a dynamic
IP address for other reasons). We call this situation “Road Warrior”. It is fairly tricky
and has some important limitations, most of which are features of the IKE protocol.
Only the initiator may be mobile: the initiator may have an IP number unknown to the
responder. When the responder doesn´t recognize the IP address on the first Main Mode
packet, it looks for a connection with itself as one end and %any as the other. If it
cannot find one, it refuses to negotiate. If it does find one, it creates a temporary
connection that is a duplicate except with the %any replaced by the source IP address from
the packet; if there was no identity specified for the peer, the new IP address will be
used.
When pluto is using one of these temporary connections and needs to find the preshared
secret or RSA private key in ipsec.secrets, and and the connection specified no identity
for the peer, %any is used as its identity. After all, the real IP address was apparently
unknown to the configuration, so it is unreasonable to require that it be used in this
table.
Part way into the Phase 1 (Main Mode) negotiation using one of these temporary connection
descriptions, pluto will be receive an Identity Payload. At this point, pluto checks for a
more appropriate connection, one with an identity for the peer that matches the payload
but which would use the same keys so-far used for authentication. If it finds one, it will
switch to using this better connection (or a temporary derived from this, if it has %any
for the peer´s IP address). It may even turn out that no connection matches the newly
discovered identity, including the current connection; if so, pluto terminates
negotiation.
Unfortunately, if preshared secret authentication is being used, the Identity Payload is
encrypted using this secret, so the secret must be selected by the responder without
knowing this payload. This limits there to being at most one preshared secret for all Road
Warrior systems connecting to a host. RSA Signature authentications does not require that
the responder know how to select the initiator´s public key until after the initiator´s
Identity Payload is decoded (using the responder´s private key, so that must be
preselected).
When pluto is responding to a Quick Mode negotiation via one of these temporary connection
descriptions, it may well find that the subnets specified by the initiator don´t match
those in the temporary connection description. If so, it will look for a connection with
matching subnets, its own host address, a peer address of %any and matching identities. If
it finds one, a new temporary connection is derived from this one and used for the Quick
Mode negotiation of IPsec SAs. If it does not find one, pluto terminates negotiation.
Be sure to specify an appropriate nexthop for the responder to send a message to the
initiator: pluto has no way of guessing it (if forwarding isn´t required, use an explicit
%direct as the nexthop and the IP address of the initiator will be filled in; the obsolete
notation 0.0.0.0 is still accepted).
pluto has no special provision for the initiator side. The current (possibly dynamic) IP
address and nexthop must be used in defining connections. These must be properly
configured each time the initiator´s IP address changes. pluto has no mechanism to do
this automatically.
Although we call this Road Warrior Support, it could also be used to support encrypted
connections with anonymous initiators. The responder´s organization could announce the
preshared secret that would be used with unrecognized initiators and let anyone connect.
Of course the initiator´s identity would not be authenticated.
If any Road Warrior connections are supported, pluto cannot reject an exchange initiated
by an unknown host until it has determined that the secret is not shared or the signature
is invalid. This must await the third Main Mode message from the initiator. If no Road
Warrior connection is supported, the first message from an unknown source would be
rejected. This has implications for ease of debugging configurations and for denial of
service attacks.
Although a Road Warrior connection must be initiated by the mobile side, the other side
can and will rekey using the temporary connection it has created. If the Road Warrior
wishes to be able to disconnect, it is probably wise to set --keyingtries to 1 in the
connection on the non-mobile side to prevent it trying to rekey the connection.
Unfortunately, there is no mechanism to unroute the connection automatically.
Debugging
pluto accepts several optional arguments, useful mostly for debugging. Except for
--interface, each should appear at most once.
--interface interfacename
specifies that the named real public network interface should be considered. The
interface name specified should not be ipsecN. If the option doesn´t appear, all
interfaces are considered. To specify several interfaces, use the option once for
each. One use of this option is to specify which interface should be used when two or
more share the same IP address.
--ikeport port-number
changes the UDP port that pluto will use (default, specified by IANA: 500)
--ctlbase path
basename for control files. path.ctl is the socket through which whack communicates
with pluto. path.pid is the lockfile to prevent multiple pluto instances. The default
is /var/run/pluto/pluto).
--secretsfile file
specifies the file for authentication secrets (default: /etc/ipsec.secrets). This name
is subject to “globbing” as in sh(1), so every file with a matching name is processed.
Quoting is generally needed to prevent the shell from doing the globbing.
--adns path to adns, --lwdnsq path to lwdnsq
specifies where to find pluto´s helper program for asynchronous DNS lookup. pluto can
be built to use one of two helper programs: _pluto_adns or lwdnsq. You must use the
program for which it was built. By default, pluto will look for the program in
$IPSEC_DIR (if that environment variable is defined) or, failing that, in the same
directory as pluto.
--nofork
disable “daemon fork” (default is to fork). In addition, after the lock file and
control socket are created, print the line “Pluto initialized” to standard out.
--uniqueids
if this option has been selected, whenever a new ISAKMP SA is established, any
connection with the same Peer ID but a different Peer IP address is unoriented
(causing all its SAs to be deleted). This helps clean up dangling SAs when a
connection is lost and then regained at another IP address.
--force_busy
if this option has been selected, pluto will be forced to be "busy". In this state,
which happens when there is a Denial of Service attack, will force pluto to use
cookies before accepting new incoming IKE packets. Cookies are send and required in
ikev1 Aggressive Mode and in ikev2. This option is mostly used for testing purposes,
but can be selected by paranoid administrators as well.
--stderrlog
log goes to standard out {default is to use syslogd(8))
For example
pluto --secretsfile ipsec.secrets --ctlbase pluto.base --ikeport 8500 --nofork
--use-nostack --stderrlog
lets one test pluto without using the superuser account.
pluto is willing to produce a prodigious amount of debugging information. To do so, it
must be compiled with -DDEBUG. There are several classes of debugging output, and pluto
may be directed to produce a selection of them. All lines of debugging output are prefixed
with “| ” to distinguish them from error messages.
When pluto is invoked, it may be given arguments to specify which classes to output. The
current options are:
--debug-none
disable all debugging
--debug-all
enable all debugging
--debug-raw
show the raw bytes of messages
--debug-crypt
show the encryption and decryption of messages
--debug-parsing
show the structure of input messages
--debug-emitting
show the structure of output messages
--debug-control
show pluto´s decision making
--debug-controlmore
show even more detailed pluto decision making
--debug-lifecycle
[this option is temporary] log more detail of lifecycle of SAs
--debug-klips
show pluto´s interaction with KLIPS
--debug-pfkey
show pluto´s PFKEYinterface communication
--debug-dns
show pluto´s interaction with DNS for KEY and TXT records
--debug-dpd
show pluto´s Dead Peer Detection handling
--debug-natt
show pluto´s NAT Traversal handling
--debug-oppo
show why pluto didn´t find a suitable DNS TXT record to authorize opportunistic
initiation
--debug-oppoinfo
log when connections are initiated due to acquires from the kernel. This is often
useful to know, but can be extremely chatty on a busy system.
--debug-whackwatch
if set, causes pluto not to release the whack --initiate channel until the SA is
completely up. This will cause the requestor to possibly wait forever while pluto
unsuccessfully negotiates. Used often in test cases.
--debug-private
allow debugging output with private keys.
The debug form of the whack command will change the selection in a running pluto. If a
connection name is specified, the flags are added whenever pluto has identified that it is
dealing with that connection. Unfortunately, this is often part way into the operation
being observed.
For example, to start a pluto with a display of the structure of input and output:
pluto --debug-emitting --debug-parsing
To later change this pluto to only display raw bytes:
whack --debug-raw
For testing, SSH´s IKE test page is quite useful:
http://isakmp-test.ssh.fi/
Hint: ISAKMP SAs are often kept alive by IKEs even after the IPsec SA is established. This
allows future IPsec SA´s to be negotiated directly. If one of the IKEs is restarted, the
other may try to use the ISAKMP SA but the new IKE won´t know about it. This can lead to
much confusion. pluto is not yet smart enough to get out of such a mess.
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 which it didn´t like and so ignored, so it was still awaiting
an acceptable message and got impatient) or on the other system (pluto didn´t send a reply
because it wasn´t happy with the previous message).
Notes
If pluto is compiled without -DKLIPS, it negotiates Security Associations but never ask
the kernel to put them in place and never makes routing changes. This allows pluto to be
tested on systems without KLIPS, but makes it rather useless.
Each IPsec SA is assigned an SPI, a 32-bit number used to refer to the SA. The IKE
protocol lets the destination of the SA choose the SPI. The range 0 to 0xFF is reserved
for IANA. Pluto also avoids choosing an SPI in the range 0x100 to 0xFFF, leaving these
SPIs free for manual keying. Remember that the peer, if not pluto, may well chose SPIs in
this range.
Policies
This catalogue of policies may be of use when trying to configure Pluto and another IKE
implementation to interoperate.
In Phase 1, only Main Mode is supported. We are not sure that Aggressive Mode is secure.
For one thing, it does not support identity protection. It may allow more severe Denial Of
Service attacks.
No Informational Exchanges are supported. These are optional and since their delivery is
not assured, they must not matter. It is the case that some IKE implementations won´t
interoperate without Informational Exchanges, but we feel they are broken.
No Informational Payloads are supported. These are optional, but useful. It is of concern
that these payloads are not authenticated in Phase 1, nor in those Phase 2 messages
authenticated with HASH(3).
•
Diffie Hellman Groups MODP 1024 and MODP 1536 (2 and 5) are supported. Group MODP768
(1) is not supported because it is too weak.
•
Host authetication can be done by RSA Signatures or Pre-Shared Secrets.
•
3DES CBC (Cypher Block Chaining mode) is the only encryption supported, both for
ISAKMP SAs and IPSEC SAs.
•
MD5 and SHA1 hashing are supported for packet authentication in both kinds of SAs.
•
The ESP, AH, or AH plus ESP are supported. If, and only if, AH and ESP are combined,
the ESP need not have its own authentication component. The selection is controlled by
the --encrypt and --authenticate flags.
•
Each of these may be combined with IPCOMP Deflate compression, but only if the
potential connection specifies compression and only if KLIPS is configured with IPCOMP
support.
•
The IPSEC SAs may be tunnel or transport mode, where appropriate. The --tunnel flag
controls this when pluto is initiating.
•
When responding to an ISAKMP SA proposal, the maximum acceptable lifetime is eight
hours. The default is one hour. There is no minimum. The --ikelifetime flag controls
this when pluto is initiating.
•
When responding to an IPSEC SA proposal, the maximum acceptable lifetime is one day.
The default is eight hours. There is no minimum. The --ipseclifetime flag controls
this when pluto is initiating.
•
PFS is acceptable, and will be proposed if the --pfs flag was specified. The DH group
proposed will be the same as negotiated for Phase 1.
SIGNALS
Pluto responds to SIGHUP by issuing a suggestion that ``whack --listen´´ might have been
intended.
Pluto exits when it recieves SIGTERM.
EXIT STATUS
pluto normally forks a daemon process, so the exit status is normally a very preliminary
result.
0
means that all is OK so far.
1
means that something was wrong.
10
means that the lock file already exists.
If whack detects a problem, it will return an exit status of 1. If it received progress
messages from pluto, it returns as status the value of the numeric prefix from the last
such message that was not a message sent to syslog or a comment (but the prefix for
success is treated as 0). Otherwise, the exit status is 0.
FILES
/var/run/pluto/pluto.pid
/var/run/pluto/pluto.ctl
/etc/ipsec.secrets
$IPSEC_LIBDIR/_pluto_adns
$IPSEC_EXECDIR/lwdnsq
/dev/urandom
ENVIRONMENT
IPSEC_LIBDIR
IPSEC_EXECDIR
IPSECmyid
PLUTO_CORE_DIR
SEE ALSO
The rest of the Openswan distribution, in particular ipsec(8).
ipsec_auto(8) is designed to make using pluto more pleasant. Use it!
ipsec.secrets(5) describes the format of the secrets file.
ipsec_atoaddr(3), part of the Openswan distribution, describes the forms that IP addresses
may take. ipsec_atosubnet(3), part of the Openswan distribution, describes the forms that
subnet specifications.
For more information on IPsec, the mailing list, and the relevant documents, see:
http://www.ietf.cnri.reston.va.us/html.charters/ipsec-charter.html
At the time of writing, the most relevant IETF RFCs are:
RFC2409 The Internet Key Exchange (IKE)
RFC2408 Internet Security Association and Key Management Protocol (ISAKMP)
RFC2407 The Internet IP Security Domain of Interpretation for ISAKMP
The Openswan web site <htp://www.openswan.org> and the mailing lists described there.
HISTORY
This code is released under the GPL terms. See the accompanying files COPYING and CREDITS
for more details. The GPL does NOT apply to those pieces of code written by others which
are included in this distribution, except as noted by the individual authors.
This software was originally written for the FreeS/WAN project <http://www.freeswan.org>,
founded by John Gilmore and managed by Hugh Daniel. It was written by Angelos D. Keromytis
(angelos@dsl.cis.upenn.edu), in May/June 1997, in Athens, Greece. Thanks go to John
Ioannidis for his help.
It is currently maintained and extended by Xelerance Corporation, in Canada under the
Openswan name. See CHANGES for details.
FreeS/WAN was developed/maintained from 2000-2004 by D. Hugh Redelmeier (hugh@mimosa.com),
in Canada. The regulations of Greece and Canada allow the code to be freely
redistributable.
Kai Martius (admin@imib.med.tu-dresden.de) contributed the initial version of the code
supporting PFS.
Richard Guy Briggs <rgb@conscoop.ottawa.on.ca> and Peter Onion <ponion@srd.bt.co.uk> added
the PFKEY2 support.
We gratefully acknowledge that we use parts of Eric Young´s libdes package; see
../libdes/COPYRIGHT.
BUGS
pluto is a work-in-progress. It currently has many limitations. For example, it ignores
notification messages that it receives, and it generates only Delete Notifications and
those only for IPSEC SAs.
pluto does not support the Commit Flag. The Commit Flag is a bad feature of the IKE
protocol. It isn´t protected -- neither encrypted nor authenticated. A man in the middle
could turn it on, leading to DoS. We just ignore it, with a warning. This should let us
interoperate with implementations that insist on it, with minor damage.
pluto does not check that the SA returned by the Responder is actually one that was
proposed. It only checks that the SA is acceptable. The difference is not large, but can
show up in attributes such as SA lifetime.
There is no good way for a connection to be automatically terminated. This is a problem
for Road Warrior and Opportunistic connections. The --dontrekey option does prevent the
SAs from being rekeyed on expiry. Additonally, if a Road Warrior connection has a client
subnet with a fixed IP address, a negotiation with that subnet will cause any other
connection instantiations with that same subnet to be unoriented (deleted, in effect). See
also the --uniqueids option for an extension of this.
When pluto sends a message to a peer that has disappeared, pluto receives incomplete
information from the kernel, so it logs the unsatisfactory message “some IKE message we
sent has been rejected with ECONNREFUSED (kernel supplied no details)”. John Denker
suggests that this command is useful for tracking down the source of these problems:
tcpdump -i eth0 icmp[0] != 8 and icmp[0] != 0 Substitute your public interface for eth0 if
it is different.
The word “authenticate” is used for two different features. We must authenticate each IKE
peer to the other. This is an important task of Phase 1. Each packet must be
authenticated, both in IKE and in IPsec, and the method for IPsec is negotiated as an AH
SA or part of an ESP SA. Unfortunately, the protocol has no mechanism for authenticating
the Phase 2 identities.
Bugs should be reported to the <users@lists.openswan.org> mailing list.
[FIXME: source] 26 October 2006 IPSEC_PLUTO(8)