1605 lines
61 KiB
Groff
1605 lines
61 KiB
Groff
.TH IPSEC_PLUTO 8 "28 March 1999"
|
|
.SH NAME
|
|
ipsec pluto \- IPsec IKE keying daemon
|
|
.br
|
|
ipsec whack \- control interface for IPSEC keying daemon
|
|
.SH SYNOPSIS
|
|
.na
|
|
.nh
|
|
.HP
|
|
.ft B
|
|
ipsec pluto
|
|
[\-\-help]
|
|
[\-\-version]
|
|
[\-\-optionsfrom\ \c
|
|
\fIfilename\fP]
|
|
[\-\-nofork]
|
|
[\-\-stderrlog]
|
|
[\-\-noklips]
|
|
[\-\-uniqueids]
|
|
[\fB\-\-interface\fP \fIinterfacename\fP]
|
|
[\-\-ikeport\ \c
|
|
\fIportnumber\fP]
|
|
[\-\-ctlbase\ \c
|
|
\fIpath\fP]
|
|
[\-\-secretsfile\ \c
|
|
\fIsecrets\(hyfile\fP]
|
|
[\-\-adns \fIpathname\fP]
|
|
[\-\-lwdnsq \fIpathname\fP]
|
|
[\-\-perpeerlog]
|
|
[\-\-perpeerlogbase\ \c
|
|
\fIdirname\fP]
|
|
[\-\-debug\(hynone]
|
|
[\-\-debug\(hyall]
|
|
[\-\-debug\(hyraw]
|
|
[\-\-debug\(hycrypt]
|
|
[\-\-debug\(hyparsing]
|
|
[\-\-debug\(hyemitting]
|
|
[\-\-debug\(hycontrol]
|
|
[\-\-debug\(hylifecycle]
|
|
[\-\-debug\(hykernel]
|
|
[\-\-debug\(hydns]
|
|
[\-\-debug\(hyoppo]
|
|
[\-\-debug\(hyprivate]
|
|
.HP
|
|
.ft B
|
|
ipsec whack
|
|
[\-\-help]
|
|
[\-\-version]
|
|
.HP
|
|
.ft B
|
|
ipsec whack
|
|
\-\-name\ \c
|
|
\fIconnection-name\fP
|
|
.br
|
|
[\-\-id\ \c
|
|
\fIid\fP] \c
|
|
[\-\-host\ \c
|
|
\fIip\(hyaddress\fP]
|
|
[\-\-ikeport\ \c
|
|
\fIport\(hynumber\fP]
|
|
[\-\-nexthop\ \c
|
|
\fIip\(hyaddress\fP]
|
|
[\-\-client\ \c
|
|
\fIsubnet\fP]
|
|
[\-\-dnskeyondemand]
|
|
[\-\-updown\ \c
|
|
\fIupdown\fP]
|
|
.br
|
|
\-\-to
|
|
.br
|
|
[\-\-id\ \c
|
|
\fIid\fP]
|
|
[\-\-host\ \c
|
|
\fIip\(hyaddress\fP]
|
|
[\-\-ikeport\ \c
|
|
\fIport\(hynumber\fP]
|
|
[\-\-nexthop\ \c
|
|
\fIip\(hyaddress\fP]
|
|
[\-\-client\ \c
|
|
\fIsubnet\fP]
|
|
[\-\-dnskeyondemand]
|
|
[\-\-updown\ \c
|
|
\fIupdown\fP]
|
|
.br
|
|
[\-\-psk]
|
|
[\-\-rsasig]
|
|
[\-\-encrypt]
|
|
[\-\-authenticate]
|
|
[\-\-compress]
|
|
[\-\-tunnel]
|
|
[\-\-pfs]
|
|
[\-\-disablearrivalcheck]
|
|
[\-\-ipv4]
|
|
[\-\-ipv6]
|
|
[\-\-tunnelipv4]
|
|
[\-\-tunnelipv6]
|
|
[\-\-ikelifetime\ \c
|
|
\fIseconds\fP]
|
|
[\-\-ipseclifetime\ \c
|
|
\fIseconds\fP]
|
|
[\-\-rekeymargin\ \c
|
|
\fIseconds\fP]
|
|
[\-\-rekeyfuzz\ \c
|
|
\fIpercentage\fP]
|
|
[\-\-keyingtries\ \c
|
|
\fIcount\fP]
|
|
[\-\-dontrekey]
|
|
[\-\-delete]
|
|
[\-\-ctlbase\ \c
|
|
\fIpath\fP]
|
|
[\-\-optionsfrom\ \c
|
|
\fIfilename\fP]
|
|
[\-\-label\ \c
|
|
\fIstring\fP]
|
|
.HP
|
|
.ft B
|
|
ipsec whack
|
|
\-\-keyid\ \c
|
|
\fIid\fP
|
|
[\-\-addkey]
|
|
[\-\-pubkeyrsa\ \c
|
|
\fIkey\fP]
|
|
[\-\-ctlbase\ \c
|
|
\fIpath\fP]
|
|
[\-\-optionsfrom\ \c
|
|
\fIfilename\fP]
|
|
[\-\-label\ \c
|
|
\fIstring\fP]
|
|
.HP
|
|
.ft B
|
|
ipsec whack
|
|
\-\-myid\ \c
|
|
\fIid\fP
|
|
.HP
|
|
.ft B
|
|
ipsec whack
|
|
\-\-listen|\-\-unlisten
|
|
[\-\-ctlbase\ \c
|
|
\fIpath\fP]
|
|
[\-\-optionsfrom\ \c
|
|
\fIfilename\fP]
|
|
[\-\-label\ \c
|
|
\fIstring\fP]
|
|
.HP
|
|
.ft B
|
|
ipsec whack
|
|
\-\-route|\-\-unroute
|
|
\-\-name\ \c
|
|
\fIconnection-name\fP
|
|
[\-\-ctlbase\ \c
|
|
\fIpath\fP]
|
|
[\-\-optionsfrom\ \c
|
|
\fIfilename\fP]
|
|
[\-\-label\ \c
|
|
\fIstring\fP]
|
|
.HP
|
|
.ft B
|
|
ipsec whack
|
|
\-\-initiate|\-\-terminate
|
|
\-\-name\ \c
|
|
\fIconnection-name\fP
|
|
[\-\-asynchronous]
|
|
[\-\-ctlbase\ \c
|
|
\fIpath\fP]
|
|
[\-\-optionsfrom\ \c
|
|
\fIfilename\fP]
|
|
[\-\-label\ \c
|
|
\fIstring\fP]
|
|
.HP
|
|
.ft B
|
|
ipsec whack
|
|
[\-\-tunnelipv4]
|
|
[\-\-tunnelipv6]
|
|
\-\-oppohere \fIip\(hyaddress\fP
|
|
\-\-oppothere \fIip\(hyaddress\fP
|
|
.HP
|
|
.ft B
|
|
ipsec whack
|
|
\-\-delete
|
|
\-\-name\ \c
|
|
\fIconnection-name\fP
|
|
[\-\-ctlbase\ \c
|
|
\fIpath\fP]
|
|
[\-\-optionsfrom\ \c
|
|
\fIfilename\fP]
|
|
[\-\-label\ \c
|
|
\fIstring\fP]
|
|
.HP
|
|
.ft B
|
|
ipsec whack
|
|
\-\-deletestate\ \c
|
|
\fIstate-number\fP
|
|
[\-\-ctlbase\ \c
|
|
\fIpath\fP]
|
|
[\-\-optionsfrom\ \c
|
|
\fIfilename\fP]
|
|
[\-\-label\ \c
|
|
\fIstring\fP]
|
|
.HP
|
|
.ft B
|
|
ipsec whack
|
|
[\-\-name\ \c
|
|
\fIconnection-name\fP]
|
|
[\-\-debug\(hynone]
|
|
[\-\-debug\(hyall]
|
|
[\-\-debug\(hyraw]
|
|
[\-\-debug\(hycrypt]
|
|
[\-\-debug\(hyparsing]
|
|
[\-\-debug\(hyemitting]
|
|
[\-\-debug\(hycontrol]
|
|
[\-\-debug\(hylifecycle]
|
|
[\-\-debug\(hykernel]
|
|
[\-\-debug\(hydns]
|
|
[\-\-debug\(hyoppo]
|
|
[\-\-debug\(hyprivate]
|
|
[\-\-ctlbase\ \c
|
|
\fIpath\fP]
|
|
[\-\-optionsfrom\ \c
|
|
\fIfilename\fP]
|
|
[\-\-label\ \c
|
|
\fIstring\fP]
|
|
.HP
|
|
.ft B
|
|
ipsec whack
|
|
\-\-status
|
|
[\-\-ctlbase\ \c
|
|
\fIpath\fP]
|
|
[\-\-optionsfrom\ \c
|
|
\fIfilename\fP]
|
|
[\-\-label\ \c
|
|
\fIstring\fP]
|
|
.HP
|
|
.ft B
|
|
ipsec whack
|
|
\-\-shutdown
|
|
[\-\-ctlbase\ \c
|
|
\fIpath\fP]
|
|
[\-\-optionsfrom\ \c
|
|
\fIfilename\fP]
|
|
[\-\-label\ \c
|
|
\fIstring\fP]
|
|
.ft R
|
|
.hy
|
|
.ad
|
|
.SH DESCRIPTION
|
|
.BR pluto
|
|
is an IKE (``IPsec Key Exchange'') daemon.
|
|
.BR whack
|
|
is an auxiliary program to allow requests to be made to a running
|
|
.BR pluto .
|
|
.LP
|
|
.BR pluto
|
|
is used to automatically build shared ``security associations'' on a
|
|
system that has IPsec, the secure IP protocol.
|
|
In other words,
|
|
.BR pluto
|
|
can eliminate much of the work of manual keying.
|
|
The actual
|
|
secure transmission of packets is the responsibility of the Linux kernel.
|
|
\fIipsec_auto\fP(8) provides a more convenient interface to
|
|
\fBpluto\fP and \fBwhack\fP.
|
|
.SS IKE's Job
|
|
.LP
|
|
A \fISecurity Association\fP (\fISA\fP) is an agreement between two network nodes on
|
|
how to process certain traffic between them. This processing involves
|
|
encapsulation, authentication, encryption, or compression.
|
|
.LP
|
|
IKE can be deployed on a network node to negotiate Security
|
|
Associations for that node. These IKE implementations can only
|
|
negotiate with other IKE implementations, so IKE must be on each node
|
|
that is to be an endpoint of an IKE-negotiated Security Association.
|
|
No other nodes need to be running IKE.
|
|
.LP
|
|
An IKE instance (i.e. an IKE implementation on a particular network
|
|
node) communicates with another IKE instance using UDP IP packets, so
|
|
there must be a route between the nodes in each direction.
|
|
.LP
|
|
The negotiation of Security Associations requires a number of choices
|
|
that involve tradeoffs between security, convenience, trust, and
|
|
efficiency. These are policy issues and are normally specified to the
|
|
IKE instance by the system administrator.
|
|
.LP
|
|
IKE deals with two kinds of Security Associations. The first part of
|
|
a negotiation between IKE instances is to build an ISAKMP SA. An
|
|
ISAKMP SA is used to protect communication between the two IKEs.
|
|
IPsec SAs can then be built by the IKEs \- these are used to carry
|
|
protected IP traffic between the systems.
|
|
.LP
|
|
The negotiation of the ISAKMP SA is known as Phase 1. In theory,
|
|
Phase 1 can be accomplished by a couple of different exchange types,
|
|
but we only implement one called Main Mode (we don't implement
|
|
Aggressive Mode).
|
|
.LP
|
|
Any negotiation under the protection of an ISAKMP SA, including the
|
|
negotiation of IPsec SAs, is part of Phase 2. The exchange type
|
|
that we use to negotiate an IPsec SA is called Quick Mode.
|
|
.LP
|
|
IKE instances must be able to authenticate each other as part of their
|
|
negotiation of an ISAKMP SA. This can be done by several mechanisms
|
|
described in the draft standards.
|
|
.LP
|
|
IKE negotiation can be initiated by any instance with any other. If
|
|
both can find an agreeable set of characteristics for a Security
|
|
Association, and both recognize each others authenticity, they can set
|
|
up a Security Association. The standards do not specify what causes
|
|
an IKE instance to initiate a negotiation.
|
|
.LP
|
|
In summary, an IKE instance is prepared to automate the management of
|
|
Security Associations in an IPsec environment, but a number of issues
|
|
are considered policy and are left in the system administrator's hands.
|
|
.SS Pluto
|
|
.LP
|
|
\fBpluto\fP is an implementation of IKE. It runs as a daemon on a network
|
|
node. Currently, this network node must be a Linux 2.6 system running the
|
|
native \fBNETKEY\fP IPsec stack.
|
|
.LP
|
|
\fBpluto\fP only implements a subset of IKE. This is enough for it to
|
|
interoperate with other instances of \fBpluto\fP, and many other IKE
|
|
implementations. We are working on implementing more of IKE.
|
|
.LP
|
|
The policy for acceptable characteristics for Security Associations is
|
|
mostly hardwired into the code of \fBpluto\fP (spdb.c). Eventually
|
|
this will be moved into a security policy database with reasonable
|
|
expressive power and more convenience.
|
|
.LP
|
|
\fBpluto\fP uses shared secrets or RSA signatures to authenticate
|
|
peers with whom it is negotiating.
|
|
.LP
|
|
\fBpluto\fP initiates negotiation of a Security Association when it is
|
|
manually prodded: the program \fBwhack\fP is run to trigger this.
|
|
It will also initiate a negotiation when the Linux kernel traps an outbound
|
|
packet for Opportunistic Encryption.
|
|
.LP
|
|
\fBpluto\fP implements ISAKMP SAs itself. After it has negotiated the
|
|
characteristics of an IPsec SA, it directs the Linux kernel to implement it.
|
|
It also invokes a script to adjust any firewall and issue \fIroute\fP(8)
|
|
commands.
|
|
.LP
|
|
When \fBpluto\fP shuts down, it closes all Security Associations.
|
|
.SS Before Running Pluto
|
|
.LP
|
|
\fBpluto\fP runs as a daemon with userid root. Before running it, a few
|
|
things must be set up.
|
|
.LP
|
|
\fBpluto\fP requires a Linux 2.6 kernel with the modules for the native IPsec
|
|
stack enabled.
|
|
.LP
|
|
\fBpluto\fP supports multiple public networks (that is, networks
|
|
that are considered insecure and thus need to have their traffic
|
|
encrypted or authenticated). It discovers the
|
|
public interfaces to use by looking at all interfaces that are
|
|
configured (the \fB\-\-interface\fP option can be used to limit
|
|
the interfaces considered).
|
|
It does this only when \fBwhack\fP tells it to \-\-listen,
|
|
so the interfaces must be configured by then.
|
|
\fIifconfig\fP(8) with the \fB\-a\fP flag will show
|
|
the name and status of each network interface.
|
|
.LP
|
|
\fBpluto\fP requires a database of preshared secrets and RSA private keys.
|
|
This is described in the
|
|
.IR ipsec.secrets (5).
|
|
\fBpluto\fP is told of RSA public keys via \fBwhack\fP commands.
|
|
If the connection is Opportunistic, and no RSA public key is known,
|
|
\fBpluto\fP will attempt to fetch RSA keys using the Domain Name System.
|
|
.SS ipsec.secrets file
|
|
.LP
|
|
A \fBpluto\fP daemon and another IKE daemon (for example, another instance
|
|
of \fBpluto\fP) must convince each other that they are who they are supposed
|
|
to be before any negotiation can succeed. This authentication is
|
|
accomplished by using either secrets that have been shared beforehand
|
|
(manually) or by using RSA signatures. There are other techniques,
|
|
but they have not been implemented in \fBpluto\fP.
|
|
.LP
|
|
The file \fI/etc/ipsec.secrets\fP is used to keep preshared secret keys
|
|
and RSA private keys for
|
|
authentication with other IKE daemons. For debugging, there is an
|
|
argument to the \fBpluto\fP command to use a different file.
|
|
This file is described in
|
|
.IR ipsec.secrets (5).
|
|
.SS Running Pluto
|
|
.LP
|
|
To fire up the daemon, just type \fBpluto\fP (be sure to be running as
|
|
the superuser).
|
|
The default IKE port number is 500, the UDP port assigned by IANA for IKE Daemons.
|
|
\fBpluto\fP must be run by the superuser to be able to use the UDP 500 port.
|
|
.LP
|
|
\fBpluto\fP attempts to create a lockfile with the name
|
|
\fI/var/run/pluto.pid\fP. If the lockfile cannot be created,
|
|
\fBpluto\fP exits \- this prevents multiple \fBpluto\fPs from
|
|
competing Any ``leftover'' lockfile must be removed before
|
|
\fBpluto\fP will run. \fBpluto\fP writes its pid into this file so
|
|
that scripts can find it. This lock will not function properly if it
|
|
is on an NFS volume (but sharing locks on multiple machines doesn't
|
|
make sense anyway).
|
|
.LP
|
|
\fBpluto\fP then forks and the parent exits. This is the conventional
|
|
``daemon fork''. It can make debugging awkward, so there is an option
|
|
to suppress this fork.
|
|
.LP
|
|
All logging, including diagnostics, is sent to
|
|
.IR syslog (3)
|
|
with facility=authpriv;
|
|
it decides where to put these messages (possibly in /var/log/secure).
|
|
Since this too can make debugging awkward, there is an option to
|
|
steer logging to stderr.
|
|
.LP
|
|
If the \fB\-\-perpeerlog\fP option is given, then pluto will open
|
|
a log file per connection. By default, this is in /var/log/pluto/peer,
|
|
in a subdirectory formed by turning all dot (.) [IPv4} or colon (:)
|
|
[IPv6] into slashes (/).
|
|
.LP
|
|
The base directory can be changed with the \fB\-\-perpeerlogbase\fP.
|
|
.LP
|
|
Once \fBpluto\fP is started, it waits for requests from \fBwhack\fP.
|
|
.SS Pluto's Internal State
|
|
.LP
|
|
To understand how to use \fBpluto\fP, it is helpful to understand a little
|
|
about its internal state. Furthermore, the terminology is needed to decipher
|
|
some of the diagnostic messages.
|
|
.LP
|
|
The \fI(potential) connection\fP database describes attributes of a
|
|
connection. These include the IP addresses of the hosts and client
|
|
subnets and the security characteristics desired. \fBpluto\fP
|
|
requires this information (simply called a connection) before it can
|
|
respond to a request to build an SA. Each connection is given a name
|
|
when it is created, and all references are made using this name.
|
|
.LP
|
|
During the IKE exchange to build an SA, the information about the
|
|
negotiation is represented in a \fIstate object\fP. Each state object
|
|
reflects how far the negotiation has reached. Once the negotiation is
|
|
complete and the SA established, the state object remains to represent
|
|
the SA. When the SA is terminated, the state object is discarded.
|
|
Each State object is given a serial number and this is used to refer
|
|
to the state objects in logged messages.
|
|
.LP
|
|
Each state object corresponds to a connection and can be thought of
|
|
as an instantiation of that connection.
|
|
At any particular time, there may be any number of state objects
|
|
corresponding to a particular connection.
|
|
Often there is one representing an ISAKMP SA and another representing
|
|
an IPsec SA.
|
|
.LP
|
|
Each connection may be routed, and must be while it has an IPsec SA.
|
|
The connection specifies the characteristics of the route: the
|
|
interface on this machine, the ``gateway'' (the nexthop),
|
|
and the peer's client subnet. Two
|
|
connections may not be simultaneously routed if they are for the same
|
|
peer's client subnet but use different interfaces or gateways
|
|
(\fBpluto\fP's logic does not reflect any advanced routing capabilities).
|
|
.LP
|
|
Each eroute is associated with the state object for an IPsec SA
|
|
because it has the particular characteristics of the SA.
|
|
Two eroutes conflict if they specify the identical local
|
|
and remote clients (unlike for routes, the local clients are
|
|
taken into account).
|
|
.LP
|
|
When \fBpluto\fP needs to install a route for a connection,
|
|
it must make sure that no conflicting route is in use. If another
|
|
connection has a conflicting route, that route will be taken down, as long
|
|
as there is no IPsec SA instantiating that connection.
|
|
If there is such an IPsec SA, the attempt to install a route will fail.
|
|
.LP
|
|
There is an exception. If \fBpluto\fP, as Responder, needs to install
|
|
a route to a fixed client subnet for a connection, and there is
|
|
already a conflicting route, then the SAs using the route are deleted
|
|
to make room for the new SAs. The rationale is that the new
|
|
connection is probably more current. The need for this usually is a
|
|
product of Road Warrior connections (these are explained later; they
|
|
cannot be used to initiate).
|
|
.LP
|
|
When \fBpluto\fP needs to install an eroute for an IPsec SA (for a
|
|
state object), first the state object's connection must be routed (if
|
|
this cannot be done, the eroute and SA will not be installed).
|
|
If a conflicting eroute is already in place for another connection,
|
|
the eroute and SA will not be installed (but note that the routing
|
|
exception mentioned above may have already deleted potentially conflicting SAs).
|
|
If another IPsec
|
|
SA for the same connection already has an eroute, all its outgoing traffic
|
|
is taken over by the new eroute. The incoming traffic will still be
|
|
processed. This characteristic is exploited during rekeying.
|
|
.LP
|
|
Some of these routing characteristics are specific to \fBKLIPS\fP, the FreeS/WAN
|
|
implementation of IPsec and are not relevant when running pluto on the native
|
|
Linux 2.6 IPsec stack.
|
|
.SS Using Whack
|
|
.LP
|
|
\fBwhack\fP is used to command a running \fBpluto\fP.
|
|
\fBwhack\fP uses a UNIX domain socket to speak to \fBpluto\fP
|
|
(by default, \fI/var/pluto.ctl\fP).
|
|
.LP
|
|
\fBwhack\fP has an intricate argument syntax.
|
|
This syntax allows many different functions to be specified.
|
|
The help form shows the usage or version information.
|
|
The connection form gives \fBpluto\fP a description of a potential connection.
|
|
The public key form informs \fBpluto\fP of the RSA public key for a potential peer.
|
|
The delete form deletes a connection description and all SAs corresponding
|
|
to it.
|
|
The listen form tells \fBpluto\fP to start or stop listening on the public interfaces
|
|
for IKE requests from peers.
|
|
The route form tells \fBpluto\fP to set up routing for a connection;
|
|
the unroute form undoes this.
|
|
The initiate form tells \fBpluto\fP to negotiate an SA corresponding to a connection.
|
|
The terminate form tells \fBpluto\fP to remove all SAs corresponding to a connection,
|
|
including those being negotiated.
|
|
The status form displays the \fBpluto\fP's internal state.
|
|
The debug form tells \fBpluto\fP to change the selection of debugging output
|
|
``on the fly''. The shutdown form tells
|
|
\fBpluto\fP to shut down, deleting all SAs.
|
|
.LP
|
|
Most options are specific to one of the forms, and will be described
|
|
with that form. There are three options that apply to all forms.
|
|
.TP
|
|
\fB\-\-ctlbase\fP\ \fIpath\fP
|
|
\fIpath\fP.ctl is used as the UNIX domain socket for talking
|
|
to \fBpluto\fP.
|
|
This option facilitates debugging.
|
|
.TP
|
|
\fB\-\-optionsfrom\fP\ \fIfilename\fP
|
|
adds the contents of the file to the argument list.
|
|
.TP
|
|
\fB\-\-label\fP\ \fIstring\fP
|
|
adds the string to all error messages generated by \fBwhack\fP.
|
|
.LP
|
|
The help form of \fBwhack\fP is self-explanatory.
|
|
.TP
|
|
\fB\-\-help\fP
|
|
display the usage message.
|
|
.TP
|
|
\fB\-\-version\fP
|
|
display the version of \fBwhack\fP.
|
|
.LP
|
|
The connection form describes a potential connection to \fBpluto\fP.
|
|
\fBpluto\fP needs to know what connections can and should be negotiated.
|
|
When \fBpluto\fP is the initiator, it needs to know what to propose.
|
|
When \fBpluto\fP is the responder, it needs to know enough to decide whether
|
|
is is willing to set up the proposed connection.
|
|
.LP
|
|
The description of a potential connection can specify a large number
|
|
of details. Each connection has a unique name. This name will appear
|
|
in a updown shell command, so it should not contain punctuation
|
|
that would make the command ill-formed.
|
|
.TP
|
|
\fB\-\-name\fP\ \fIconnection-name\fP
|
|
.LP
|
|
The topology of
|
|
a connection is symmetric, so to save space here is half a picture:
|
|
|
|
\ \ \ client_subnet<\-\->host:ikeport<\-\->nexthop<\-\-\-
|
|
|
|
A similar trick is used in the flags. The same flag names are used for
|
|
both ends. Those before the \fB\-\-to\fP flag describe the left side
|
|
and those afterwards describe the right side. When \fBpluto\fP attempts
|
|
to use the connection, it decides whether it is the left side or the right
|
|
side of the connection, based on the IP numbers of its interfaces.
|
|
.TP
|
|
\fB\-\-id\fP\ \fIid\fP
|
|
the identity of the end. Currently, this can be an IP address (specified
|
|
as dotted quad or as a Fully Qualified Domain Name, which will be resolved
|
|
immediately) or as a Fully Qualified Domain Name itself (prefixed by ``@''
|
|
to signify that it should not be resolved), or as user@FQDN, or as the
|
|
magic value \fB%myid\fP.
|
|
\fBPluto\fP only authenticates the identity, and does not use it for
|
|
addressing, so, for example, an IP address need not be the one to which
|
|
packets are to be sent. If the option is absent, the
|
|
identity defaults to the IP address specified by \fB\-\-host\fP.
|
|
\fB%myid\fP allows the identity to be separately specified (by the \fBpluto\fP or \fBwhack\fP option \fB\-\-myid\fP
|
|
or by the \fBipsec.conf\fP(5) \fBconfig setup\fP parameter \fPmyid\fP).
|
|
Otherwise, \fBpluto\fP tries to guess what \fB%myid\fP should stand for:
|
|
the IP address of \fB%defaultroute\fP, if it is supported by a suitable TXT record in the reverse domain for that IP address,
|
|
or the system's hostname, if it is supported by a suitable TXT record in its forward domain.
|
|
.\" The identity is transmitted in the IKE protocol, and is what is authenticated.
|
|
.TP
|
|
\fB\-\-host\fP\ \fIip\(hyaddress\fP
|
|
.TP
|
|
\fB\-\-host\fP\ \fB%any\fP
|
|
.TP
|
|
\fB\-\-host\fP\ \fB%opportunistic\fP
|
|
the IP address of the end (generally the public interface).
|
|
If \fBpluto\fP is to act as a responder
|
|
for IKE negotiations initiated from unknown IP addresses (the
|
|
``Road Warrior'' case), the
|
|
IP address should be specified as \fB%any\fP (currently,
|
|
the obsolete notation \fB0.0.0.0\fP is also accepted for this).
|
|
If \fBpluto\fP is to opportunistically initiate the connection,
|
|
use \fB%opportunistic\fP
|
|
.TP
|
|
\fB\-\-ikeport\fP\ \fIport\(hynumber\fP
|
|
the UDP port that IKE listens to on that host. The default is 500.
|
|
(\fBpluto\fP on this machine uses the port specified by its own command
|
|
line argument, so this only affects where \fBpluto\fP sends messages.)
|
|
.TP
|
|
\fB\-\-nexthop\fP\ \fIip\(hyaddress\fP
|
|
where to route packets for the peer's client (presumably for the peer too,
|
|
but it will not be used for this).
|
|
When \fBpluto\fP installs an IPsec SA, it issues a route command.
|
|
It uses the nexthop as the gateway.
|
|
The default is the peer's IP address (this can be explicitly written as
|
|
\fB%direct\fP; the obsolete notation \fB0.0.0.0\fP is accepted).
|
|
This option is necessary if \fBpluto\fP's host's interface used for sending
|
|
packets to the peer is neither point-to-point nor directly connected to the
|
|
peer.
|
|
.TP
|
|
\fB\-\-client\fP\ \fIsubnet\fP
|
|
the subnet for which the IPsec traffic will be destined. If not specified,
|
|
the host will be the client.
|
|
The subnet can be specified in any of the forms supported by \fIipsec_atosubnet\fP(3).
|
|
The general form is \fIaddress\fP/\fImask\fP. The \fIaddress\fP can be either
|
|
a domain name or four decimal numbers (specifying octets) separated by dots.
|
|
The most convenient form of the \fImask\fP is a decimal integer, specifying
|
|
the number of leading one bits in the mask. So, for example, 10.0.0.0/8
|
|
would specify the class A network ``Net 10''.
|
|
.TP
|
|
\fB\-\-dnskeyondemand]\fP
|
|
specifies that when an RSA public key is needed to authenticate this
|
|
host, and it isn't already known, fetch it from DNS.
|
|
.TP
|
|
\fB\-\-updown\fP\ \fIupdown\fP
|
|
specifies an external shell command to be run whenever \fBpluto\fP
|
|
brings up or down a connection.
|
|
The script is used to build a shell command, so it may contain positional
|
|
parameters, but ought not to have punctuation that would cause the
|
|
resulting command to be ill-formed.
|
|
The default is \fIipsec _updown\fP.
|
|
.TP
|
|
\fB\-\-to\fP
|
|
separates the specification of the left and right ends of the connection.
|
|
.LP
|
|
The potential connection description also specifies characteristics of
|
|
rekeying and security.
|
|
.TP
|
|
\fB\-\-psk\fP
|
|
Propose and allow preshared secret authentication for IKE peers. This authentication
|
|
requires that each side use the same secret. May be combined with \fB\-\-rsasig\fP;
|
|
at least one must be specified.
|
|
.TP
|
|
\fB\-\-rsasig\fP
|
|
Propose and allow RSA signatures for authentication of IKE peers. This authentication
|
|
requires that each side have have a private key of its own and know the
|
|
public key of its peer. May be combined with \fB\-\-psk\fP;
|
|
at least one must be specified.
|
|
.TP
|
|
\fB\-\-encrypt\fP
|
|
All proposed or accepted IPsec SAs will include non-null ESP.
|
|
The actual choices of transforms are wired into \fBpluto\fP.
|
|
.TP
|
|
\fB\-\-authenticate\fP
|
|
All proposed IPsec SAs will include AH.
|
|
All accepted IPsec SAs will include AH or ESP with authentication.
|
|
The actual choices of transforms are wired into \fBpluto\fP.
|
|
Note that this has nothing to do with IKE authentication.
|
|
.TP
|
|
\fB\-\-compress\fP
|
|
All proposed IPsec SAs will include IPCOMP (compression).
|
|
This will be ignored if the kernel is not configured with IPCOMP support.
|
|
.TP
|
|
\fB\-\-tunnel\fP
|
|
the IPsec SA should use tunneling. Implicit if the SA is for clients.
|
|
Must only be used with \fB\-\-authenticate\fP or \fB\-\-encrypt\fP.
|
|
.TP
|
|
\fB\-\-ipv4\fP
|
|
The host addresses will be interpreted as IPv4 addresses. This is the
|
|
default. Note that for a connection, all host addresses must be of
|
|
the same Address Family (IPv4 and IPv6 use different Address Families).
|
|
.TP
|
|
\fB\-\-ipv6\fP
|
|
The host addresses (including nexthop) will be interpreted as IPv6 addresses.
|
|
Note that for a connection, all host addresses must be of
|
|
the same Address Family (IPv4 and IPv6 use different Address Families).
|
|
.TP
|
|
\fB\-\-tunnelipv4\fP
|
|
The client addresses will be interpreted as IPv4 addresses. The default is
|
|
to match what the host will be. This does not imply \fB\-\-tunnel\fP so the
|
|
flag can be safely used when no tunnel is actually specified.
|
|
Note that for a connection, all tunnel addresses must be of the same
|
|
Address Family.
|
|
.TP
|
|
\fB\-\-tunnelipv6\fP
|
|
The client addresses will be interpreted as IPv6 addresses. The default is
|
|
to match what the host will be. This does not imply \fB\-\-tunnel\fP so the
|
|
flag can be safely used when no tunnel is actually specified.
|
|
Note that for a connection, all tunnel addresses must be of the same
|
|
Address Family.
|
|
.TP
|
|
\fB\-\-pfs\fP
|
|
There should be Perfect Forward Secrecy \- new keying material will
|
|
be generated for each IPsec SA rather than being derived from the ISAKMP
|
|
SA keying material.
|
|
Since the group to be used cannot be negotiated (a dubious feature of the
|
|
standard), \fBpluto\fP will propose the same group that was used during Phase 1.
|
|
We don't implement a stronger form of PFS which would require that the
|
|
ISAKMP SA be deleted after the IPSEC SA is negotiated.
|
|
.TP
|
|
\fB\-\-disablearrivalcheck\fP
|
|
If the connection is a tunnel, allow packets arriving through the tunnel
|
|
to have any source and destination addresses.
|
|
.LP
|
|
If none of the \fB\-\-encrypt\fP, \fB\-\-authenticate\fP, \fB\-\-compress\fP,
|
|
or \fB\-\-pfs\fP flags is given, the initiating the connection will
|
|
only build an ISAKMP SA. For such a connection, client subnets have
|
|
no meaning and must not be specified.
|
|
.LP
|
|
More work is needed to allow for flexible policies. Currently
|
|
policy is hardwired in the source file spdb.c. The ISAKMP SAs may use
|
|
Oakley groups MODP1024 and MODP1536; 3DES encryption; SHA1-96
|
|
and MD5-96 authentication. The IPsec SAs may use 3DES and
|
|
MD5-96 or SHA1-96 for ESP, or just MD5-96 or SHA1-96 for AH.
|
|
IPCOMP Compression is always Deflate.
|
|
.TP
|
|
\fB\-\-ikelifetime\fP\ \fIseconds\fP
|
|
how long \fBpluto\fP will propose that an ISAKMP SA be allowed to live.
|
|
The default is 10800 (three hours) and the maximum is 86400 (one day).
|
|
This option will not affect what is accepted.
|
|
\fBpluto\fP will reject proposals that exceed the maximum.
|
|
.TP
|
|
\fB\-\-ipseclifetime\fP\ \fIseconds\fP
|
|
how long \fBpluto\fP will propose that an IPsec SA be allowed to live.
|
|
The default is 3600 (one hour) and the maximum is 86400 (one day).
|
|
This option will not affect what is accepted.
|
|
\fBpluto\fP will reject proposals that exceed the maximum.
|
|
.TP
|
|
\fB\-\-rekeymargin\fP\ \fIseconds\fP
|
|
how long before an SA's expiration should \fBpluto\fP try to negotiate
|
|
a replacement SA. This will only happen if \fBpluto\fP was the initiator.
|
|
The default is 540 (nine minutes).
|
|
.TP
|
|
\fB\-\-rekeyfuzz\fP\ \fIpercentage\fP
|
|
maximum size of random component to add to rekeymargin, expressed as
|
|
a percentage of rekeymargin. \fBpluto\fP will select a delay uniformly
|
|
distributed within this range. By default, the percentage will be 100.
|
|
If greater determinism is desired, specify 0. It may be appropriate
|
|
for the percentage to be much larger than 100.
|
|
.TP
|
|
\fB\-\-keyingtries\fP\ \fIcount\fP
|
|
how many times \fBpluto\fP should try to negotiate an SA,
|
|
either for the first time or for rekeying.
|
|
A value of 0 is interpreted as a very large number: never give up.
|
|
The default is three.
|
|
.TP
|
|
\fB\-\-dontrekey\fP
|
|
A misnomer.
|
|
Only rekey a connection if we were the Initiator and there was recent
|
|
traffic on the existing connection.
|
|
This applies to Phase 1 and Phase 2.
|
|
This is currently the only automatic way for a connection to terminate.
|
|
It may be useful with Road Warrior or Opportunistic connections.
|
|
.br
|
|
Since SA lifetime negotiation is take-it-or-leave it, a Responder
|
|
normally uses the shorter of the negotiated or the configured lifetime.
|
|
This only works because if the lifetime is shorter than negotiated,
|
|
the Responder will rekey in time so that everything works.
|
|
This interacts badly with \fB\-\-dontrekey\fP. In this case,
|
|
the Responder will end up rekeying to rectify a shortfall in an IPsec SA
|
|
lifetime; for an ISAKMP SA, the Responder will accept the negotiated
|
|
lifetime.
|
|
.TP
|
|
\fB\-\-delete\fP
|
|
when used in the connection form, it causes any previous connection
|
|
with this name to be deleted before this one is added. Unlike a
|
|
normal delete, no diagnostic is produced if there was no previous
|
|
connection to delete. Any routing in place for the connection is undone.
|
|
.LP
|
|
The delete form deletes a named connection description and any
|
|
SAs established or negotiations initiated using this connection.
|
|
Any routing in place for the connection is undone.
|
|
.TP
|
|
\fB\-\-delete\fP
|
|
.TP
|
|
\fB\-\-name\fP\ \fIconnection-name\fP
|
|
.LP
|
|
The deletestate form deletes the state object with the specified serial number.
|
|
This is useful for selectively deleting instances of connections.
|
|
.TP
|
|
\fB\-\-deletestate\fP\ \fIstate-number\fP
|
|
.LP
|
|
The route form of the \fBwhack\fP command tells \fBpluto\fP to set up
|
|
routing for a connection.
|
|
Although like a traditional route, it uses an ipsec device as a
|
|
virtual interface.
|
|
Once routing is set up, no packets will be
|
|
sent ``in the clear'' to the peer's client specified in the connection.
|
|
A TRAP shunt eroute will be installed; if outbound traffic is caught,
|
|
Pluto will initiate the connection.
|
|
An explicit \fBwhack\fP route is not always needed: if it hasn't been
|
|
done when an IPsec SA is being installed, one will be automatically attempted.
|
|
.LP
|
|
When a routing is attempted for a connection, there must not already
|
|
be a routing for a different connection with the same subnet but different
|
|
interface or destination, or if
|
|
there is, it must not be being used by an IPsec SA. Otherwise the
|
|
attempt will fail.
|
|
.TP
|
|
\fB\-\-route\fP
|
|
.TP
|
|
\fB\-\-name\fP\ \fIconnection-name\fP
|
|
.LP
|
|
The unroute form of the \fBwhack\fP command tells \fBpluto\fP to undo
|
|
a routing. \fBpluto\fP will refuse if an IPsec SA is using the connection.
|
|
If another connection is sharing the same routing, it will be left in place.
|
|
Without a routing, packets will be sent without encryption or authentication.
|
|
.TP
|
|
\fB\-\-unroute\fP
|
|
.TP
|
|
\fB\-\-name\fP\ \fIconnection-name\fP
|
|
.LP
|
|
The initiate form tells \fBpluto\fP to initiate a negotiation with another
|
|
\fBpluto\fP (or other IKE daemon) according to the named connection.
|
|
Initiation requires a route that \fB\-\-route\fP would provide;
|
|
if none is in place at the time an IPsec SA is being installed,
|
|
\fBpluto\fP attempts to set one up.
|
|
.TP
|
|
\fB\-\-initiate\fP
|
|
.TP
|
|
\fB\-\-name\fP\ \fIconnection-name\fP
|
|
.TP
|
|
\fB\-\-asynchronous
|
|
.LP
|
|
The initiate form of the \fBwhack\fP command will relay back from
|
|
\fBpluto\fP status information via the UNIX domain socket (unless
|
|
\-\-asynchronous is specified). The status information is meant to
|
|
look a bit like that from \fBFTP\fP. Currently \fBwhack\fP simply
|
|
copies this to stderr. When the request is finished (eg. the SAs are
|
|
established or \fBpluto\fP gives up), \fBpluto\fP closes the channel,
|
|
causing \fBwhack\fP to terminate.
|
|
.LP
|
|
The opportunistic initiate form is mainly used for debugging.
|
|
.TP
|
|
\fB\-\-tunnelipv4\fP
|
|
.TP
|
|
\fB\-\-tunnelipv6\fP
|
|
.TP
|
|
\fB\-\-oppohere\fP\ \fIip-address\fP
|
|
.TP
|
|
\fB\-\-oppothere\fP\ \fIip-address\fP
|
|
.LP
|
|
This will cause \fBpluto\fP to attempt to opportunistically initiate a
|
|
connection from here to the there, even if a previous attempt
|
|
had been made.
|
|
The whack log will show the progress of this attempt.
|
|
.LP
|
|
The terminate form tells \fBpluto\fP to delete any SAs that use the specified
|
|
connection and to stop any negotiations in process.
|
|
It does not prevent new negotiations from starting (the delete form
|
|
has this effect).
|
|
.TP
|
|
\fB\-\-terminate\fP
|
|
.TP
|
|
\fB\-\-name\fP\ \fIconnection-name\fP
|
|
.LP
|
|
The public key for informs \fBpluto\fP of the RSA public key for a potential peer.
|
|
Private keys must be kept secret, so they are kept in
|
|
.IR ipsec.secrets (5).
|
|
.TP
|
|
\fB\-\-keyid\ \fP\fIid\fP
|
|
specififies the identity of the peer for which a public key should be used.
|
|
Its form is identical to the identity in the connection.
|
|
If no public key is specified, \fBpluto\fP attempts to find KEY records
|
|
from DNS for the id (if a FQDN) or through reverse lookup (if an IP address).
|
|
Note that there several interesting ways in which this is not secure.
|
|
.TP
|
|
\fB\-\-addkey\fP
|
|
specifies that the new key is added to the collection; otherwise the
|
|
new key replaces any old ones.
|
|
.TP
|
|
\fB\-\-pubkeyrsa\ \fP\fIkey\fP
|
|
specifies the value of the RSA public key. It is a sequence of bytes
|
|
as described in RFC 2537 ``RSA/MD5 KEYs and SIGs in the Domain Name System (DNS)''.
|
|
It is denoted in a way suitable for \fIipsec_ttodata\fP(3).
|
|
For example, a base 64 numeral starts with 0s.
|
|
.LP
|
|
The listen form tells \fBpluto\fP to start listening for IKE requests
|
|
on its public interfaces. To avoid race conditions, it is normal to
|
|
load the appropriate connections into \fBpluto\fP before allowing it
|
|
to listen. If \fBpluto\fP isn't listening, it is pointless to
|
|
initiate negotiations, so it will refuse requests to do so. Whenever
|
|
the listen form is used, \fBpluto\fP looks for public interfaces and
|
|
will notice when new ones have been added and when old ones have been
|
|
removed. This is also the trigger for \fBpluto\fP to read the
|
|
\fIipsec.secrets\fP file. So listen may useful more than once.
|
|
.TP
|
|
\fB\-\-listen\fP
|
|
start listening for IKE traffic on public interfaces.
|
|
.TP
|
|
\fB\-\-unlisten\fP
|
|
stop listening for IKE traffic on public interfaces.
|
|
.LP
|
|
The status form will display information about the internal state of
|
|
\fBpluto\fP: information about each potential connection, about
|
|
each state object, and about each shunt that \fBpluto\fP is managing
|
|
without an associated connection.
|
|
.TP
|
|
\fB\-\-status\fP
|
|
.LP
|
|
The shutdown form is the proper way to shut down \fBpluto\fP.
|
|
It will tear down the SAs on this machine that \fBpluto\fP has negotiated.
|
|
It does not inform its peers, so the SAs on their machines remain.
|
|
.TP
|
|
\fB\-\-shutdown\fP
|
|
.SS Examples
|
|
.LP
|
|
It would be normal to start \fBpluto\fP in one of the system initialization
|
|
scripts. It needs to be run by the superuser. Generally, no arguments are needed.
|
|
To run in manually, the superuser can simply type
|
|
|
|
\ \ \ ipsec pluto
|
|
|
|
The command will immediately return, but a \fBpluto\fP process will be left
|
|
running, waiting for requests from \fBwhack\fP or a peer.
|
|
.LP
|
|
Using \fBwhack\fP, several potential connections would be described:
|
|
.HP
|
|
.na
|
|
\ \ \ ipsec whack \-\-name\ silly
|
|
\-\-host\ 127.0.0.1 \-\-to \-\-host\ 127.0.0.2
|
|
\-\-ikelifetime\ 900 \-\-ipseclifetime\ 800 \-\-keyingtries\ 3
|
|
.ad
|
|
.LP
|
|
Since this silly connection description specifies neither encryption,
|
|
authentication, nor tunneling, it could only be used to establish
|
|
an ISAKMP SA.
|
|
.HP
|
|
.na
|
|
\ \ \ ipsec whack \-\-name\ secret \-\-host\ 10.0.0.1 \-\-client\ 10.0.1.0/24
|
|
\-\-to \-\-host\ 10.0.0.2 \-\-client\ 10.0.2.0/24
|
|
\-\-encrypt
|
|
.ad
|
|
.LP
|
|
This is something that must be done on both sides. If the other
|
|
side is \fBpluto\fP, the same \fBwhack\fP command could be used on it
|
|
(the command syntax is designed to not distinguish which end is ours).
|
|
.LP
|
|
Now that the connections are specified, \fBpluto\fP is ready to handle
|
|
requests and replies via the public interfaces. We must tell it to discover
|
|
those interfaces and start accepting messages from peers:
|
|
|
|
\ \ \ ipsec whack \-\-listen
|
|
.LP
|
|
If we don't immediately wish to bring up a secure connection between
|
|
the two clients, we might wish to prevent insecure traffic.
|
|
The routing form asks \fBpluto\fP to cause the packets sent from
|
|
our client to the peer's client to be routed through the ipsec0
|
|
device; if there is no SA, they will be discarded:
|
|
|
|
\ \ \ ipsec whack \-\-route secret
|
|
.LP
|
|
Finally, we are ready to get \fBpluto\fP to initiate negotiation
|
|
for an IPsec SA (and implicitly, an ISAKMP SA):
|
|
|
|
\ \ \ ipsec whack \-\-initiate\ \-\-name\ secret
|
|
|
|
A small log of interesting events will appear on standard output
|
|
(other logging is sent to syslog).
|
|
.LP
|
|
\fBwhack\fP can also be used to terminate \fBpluto\fP cleanly, tearing down
|
|
all SAs that it has negotiated.
|
|
|
|
\ \ \ ipsec whack \-\-shutdown
|
|
|
|
Notification of any IPSEC SA deletion, but not ISAKMP SA deletion
|
|
is sent to the peer. Unfortunately, such Notification is not reliable.
|
|
Furthermore, \fBpluto\fP itself ignores Notifications.
|
|
.SS The updown command
|
|
.LP
|
|
Whenever \fBpluto\fP brings a connection up or down, it invokes
|
|
the updown command. This command is specified using the \fB\-\-updown\fP
|
|
option. This allows for customized control over routing and firewall manipulation.
|
|
.LP
|
|
The updown is invoked for five different operations. Each of
|
|
these operations can be for our client subnet or for our host itself.
|
|
.TP
|
|
\fBprepare-host\fP or \fBprepare-client\fP
|
|
is run before bringing up a new connection if no other connection
|
|
with the same clients is up. Generally, this is useful for deleting a
|
|
route that might have been set up before \fBpluto\fP was run or
|
|
perhaps by some agent not known to \fBpluto\fP.
|
|
.TP
|
|
\fBroute-host\fP or \fBroute-client\fP
|
|
is run when bringing up a connection for a new peer client subnet
|
|
(even if \fBprepare-host\fP or \fBprepare-client\fP was run). The
|
|
command should install a suitable route. Routing decisions are based
|
|
only on the destination (peer's client) subnet address, unlike eroutes
|
|
which discriminate based on source too.
|
|
.TP
|
|
\fBunroute-host\fP or \fBunroute-client\fP
|
|
is run when bringing down the last connection for a particular peer
|
|
client subnet. It should undo what the \fBroute-host\fP or \fBroute-client\fP
|
|
did.
|
|
.TP
|
|
\fBup-host\fP or \fBup-client\fP
|
|
is run when bringing up a tunnel eroute with a pair of client subnets
|
|
that does not already have a tunnel eroute.
|
|
This command should install firewall rules as appropriate.
|
|
It is generally a good idea to allow IKE messages (UDP port 500)
|
|
travel between the hosts.
|
|
.TP
|
|
\fBdown-host\fP or \fBdown-client\fP
|
|
is run when bringing down the eroute for a pair of client subnets.
|
|
This command should delete firewall rules as appropriate. Note that
|
|
there may remain some inbound IPsec SAs with these client subnets.
|
|
.LP
|
|
The script is passed a large number of environment variables to specify
|
|
what needs to be done.
|
|
.TP
|
|
\fBPLUTO_VERSION\fP
|
|
indicates what version of this interface is being used. This document
|
|
describes version 1.1. This is upwardly compatible with version 1.0.
|
|
.TP
|
|
\fBPLUTO_VERB\fP
|
|
specifies the name of the operation to be performed
|
|
(\fBprepare-host\fP,r \fBprepare-client\fP,
|
|
\fBup-host\fP, \fBup-client\fP,
|
|
\fBdown-host\fP, or \fBdown-client\fP). If the address family for
|
|
security gateway to security gateway communications is IPv6, then
|
|
a suffix of -v6 is added to the verb.
|
|
.TP
|
|
\fBPLUTO_CONNECTION\fP
|
|
is the name of the connection for which we are routing.
|
|
.TP
|
|
\fBPLUTO_NEXT_HOP\fP
|
|
is the next hop to which packets bound for the peer must be sent.
|
|
.TP
|
|
\fBPLUTO_INTERFACE\fP
|
|
is the name of the ipsec interface to be used.
|
|
.TP
|
|
\fBPLUTO_ME\fP
|
|
is the IP address of our host.
|
|
.TP
|
|
\fBPLUTO_MY_CLIENT\fP
|
|
is the IP address / count of our client subnet.
|
|
If the client is just the host, this will be the host's own IP address / max
|
|
(where max is 32 for IPv4 and 128 for IPv6).
|
|
.TP
|
|
\fBPLUTO_MY_CLIENT_NET\fP
|
|
is the IP address of our client net.
|
|
If the client is just the host, this will be the host's own IP address.
|
|
.TP
|
|
\fBPLUTO_MY_CLIENT_MASK\fP
|
|
is the mask for our client net.
|
|
If the client is just the host, this will be 255.255.255.255.
|
|
.TP
|
|
\fBPLUTO_PEER\fP
|
|
is the IP address of our peer.
|
|
.TP
|
|
\fBPLUTO_PEER_CLIENT\fP
|
|
is the IP address / count of the peer's client subnet.
|
|
If the client is just the peer, this will be the peer's own IP address / max
|
|
(where max is 32 for IPv4 and 128 for IPv6).
|
|
.TP
|
|
\fBPLUTO_PEER_CLIENT_NET\fP
|
|
is the IP address of the peer's client net.
|
|
If the client is just the peer, this will be the peer's own IP address.
|
|
.TP
|
|
\fBPLUTO_PEER_CLIENT_MASK\fP
|
|
is the mask for the peer's client net.
|
|
If the client is just the peer, this will be 255.255.255.255.
|
|
.LP
|
|
All output sent by the script to stderr or stdout is logged. The
|
|
script should return an exit status of 0 if and only if it succeeds.
|
|
.LP
|
|
\fBPluto\fP waits for the script to finish and will not do any other
|
|
processing while it is waiting.
|
|
The script may assume that \fBpluto\fP will not change anything
|
|
while the script runs.
|
|
The script should avoid doing anything that takes much time and it
|
|
should not issue any command that requires processing by \fBpluto\fP.
|
|
Either of these activities could be performed by a background
|
|
subprocess of the script.
|
|
.SS Rekeying
|
|
.LP
|
|
When an SA that was initiated by \fBpluto\fP has only a bit of
|
|
lifetime left,
|
|
\fBpluto\fP will initiate the creation of a new SA. This applies to
|
|
ISAKMP and IPsec SAs.
|
|
The rekeying will be initiated when the SA's remaining lifetime is
|
|
less than the rekeymargin plus a random percentage, between 0 and
|
|
rekeyfuzz, of the rekeymargin.
|
|
.LP
|
|
Similarly, when an SA that was initiated by the peer has only a bit of
|
|
lifetime left, \fBpluto\fP will try to initiate the creation of a
|
|
replacement.
|
|
To give preference to the initiator, this rekeying will only be initiated
|
|
when the SA's remaining lifetime is half of rekeymargin.
|
|
If rekeying is done by the responder, the roles will be reversed: the
|
|
responder for the old SA will be the initiator for the replacement.
|
|
The former initiator might also initiate rekeying, so there may
|
|
be redundant SAs created.
|
|
To avoid these complications, make sure that rekeymargin is generous.
|
|
.LP
|
|
One risk of having the former responder initiate is that perhaps
|
|
none of its proposals is acceptable to the former initiator
|
|
(they have not been used in a successful negotiation).
|
|
To reduce the chances of this happening, and to prevent loss of security,
|
|
the policy settings are taken from the old SA (this is the case even if
|
|
the former initiator is initiating).
|
|
These may be stricter than those of the connection.
|
|
.LP
|
|
\fBpluto\fP will not rekey an SA if that SA is not the most recent of its
|
|
type (IPsec or ISAKMP) for its potential connection.
|
|
This avoids creating redundant SAs.
|
|
.LP
|
|
The random component in the rekeying time (rekeyfuzz) is intended to
|
|
make certain pathological patterns of rekeying unstable. If both
|
|
sides decide to rekey at the same time, twice as many SAs as necessary
|
|
are created. This could become a stable pattern without the
|
|
randomness.
|
|
.LP
|
|
Another more important case occurs when a security gateway has SAs
|
|
with many other security gateways. Each of these connections might
|
|
need to be rekeyed at the same time. This would cause a high peek
|
|
requirement for resources (network bandwidth, CPU time, entropy for
|
|
random numbers). The rekeyfuzz can be used to stagger the rekeying
|
|
times.
|
|
.LP
|
|
Once a new set of SAs has been negotiated, \fBpluto\fP will never send
|
|
traffic on a superseded one. Traffic will be accepted on an old SA
|
|
until it expires.
|
|
.SS Selecting a Connection When Responding: Road Warrior Support
|
|
.LP
|
|
When \fBpluto\fP receives an initial Main Mode message, it needs to
|
|
decide which connection this message is for. It picks based solely on
|
|
the source and destination IP addresses of the message. There might
|
|
be several connections with suitable IP addresses, in which case one
|
|
of them is arbitrarily chosen. (The ISAKMP SA proposal contained in
|
|
the message could be taken into account, but it is not.)
|
|
.LP
|
|
The ISAKMP SA is negotiated before the parties pass further
|
|
identifying information, so all ISAKMP SA characteristics specified in
|
|
the connection description should be the same for every connection
|
|
with the same two host IP addresses. At the moment, the only
|
|
characteristic that might differ is authentication method.
|
|
.LP
|
|
Up to this point,
|
|
all configuring has presumed that the IP addresses
|
|
are known to all parties ahead of time. This will not work
|
|
when either end is mobile (or assigned a dynamic IP address for other
|
|
reasons). We call this situation ``Road Warrior''. It is fairly tricky
|
|
and has some important limitations, most of which are features of
|
|
the IKE protocol.
|
|
.LP
|
|
Only the initiator may be mobile:
|
|
the initiator may have an IP number unknown to the responder. When
|
|
the responder doesn't recognize the IP address on the first Main Mode
|
|
packet, it looks for a connection with itself as one end and \fB%any\fP
|
|
as the other.
|
|
If it cannot find one, it refuses to negotiate. If it
|
|
does find one, it creates a temporary connection that is a duplicate
|
|
except with the \fB%any\fP replaced by the source IP address from the
|
|
packet; if there was no identity specified for the peer, the new IP
|
|
address will be used.
|
|
.LP
|
|
When \fBpluto\fP is using one of these temporary connections and
|
|
needs to find the preshared secret or RSA private key in \fIipsec.secrets\fP,
|
|
and and the connection specified no identity for the peer, \fB%any\fP
|
|
is used as its identity. After all, the real IP address was apparently
|
|
unknown to the configuration, so it is unreasonable to require that
|
|
it be used in this table.
|
|
.LP
|
|
Part way into the Phase 1 (Main Mode) negotiation using one of these
|
|
temporary connection descriptions, \fBpluto\fP will be receive an
|
|
Identity Payload. At this point, \fBpluto\fP checks for a more
|
|
appropriate connection, one with an identity for the peer that matches
|
|
the payload but which would use the same keys so-far used for
|
|
authentication. If it finds one, it will switch to using this better
|
|
connection (or a temporary derived from this, if it has \fB%any\fP
|
|
for the peer's IP address). It may even turn out that no connection
|
|
matches the newly discovered identity, including the current connection;
|
|
if so, \fBpluto\fP terminates negotiation.
|
|
.LP
|
|
Unfortunately, if preshared secret authentication is being used, the
|
|
Identity Payload is encrypted using this secret, so the secret must be
|
|
selected by the responder without knowing this payload. This
|
|
limits there to being at most one preshared secret for all Road Warrior
|
|
systems connecting to a host. RSA Signature authentications does not
|
|
require that the responder know how to select the initiator's public key
|
|
until after the initiator's Identity Payload is decoded (using the
|
|
responder's private key, so that must be preselected).
|
|
.LP
|
|
When \fBpluto\fP is responding to a Quick Mode negotiation via one of these
|
|
temporary connection descriptions, it may well find that the subnets
|
|
specified by the initiator don't match those in the temporary
|
|
connection description. If so, it will look for a connection with
|
|
matching subnets, its own host address, a peer address of \fB%any\fP
|
|
and matching identities.
|
|
If it finds one, a new temporary connection is derived from this one
|
|
and used for the Quick Mode negotiation of IPsec SAs. If it does not
|
|
find one, \fBpluto\fP terminates negotiation.
|
|
.LP
|
|
Be sure to specify an appropriate nexthop for the responder
|
|
to send a message to the initiator: \fBpluto\fP has no way of guessing
|
|
it (if forwarding isn't required, use an explicit \fB%direct\fP as the nexthop
|
|
and the IP address of the initiator will be filled in; the obsolete
|
|
notation \fB0.0.0.0\fP is still accepted).
|
|
.LP
|
|
\fBpluto\fP has no special provision for the initiator side. The current
|
|
(possibly dynamic) IP address and nexthop must be used in defining
|
|
connections. These must be
|
|
properly configured each time the initiator's IP address changes.
|
|
\fBpluto\fP has no mechanism to do this automatically.
|
|
.LP
|
|
Although we call this Road Warrior Support, it could also be used to
|
|
support encrypted connections with anonymous initiators. The
|
|
responder's organization could announce the preshared secret that would be used
|
|
with unrecognized initiators and let anyone connect. Of course the initiator's
|
|
identity would not be authenticated.
|
|
.LP
|
|
If any Road Warrior connections are supported, \fBpluto\fP cannot
|
|
reject an exchange initiated by an unknown host until it has
|
|
determined that the secret is not shared or the signature is invalid.
|
|
This must await the
|
|
third Main Mode message from the initiator. If no Road Warrior
|
|
connection is supported, the first message from an unknown source
|
|
would be rejected. This has implications for ease of debugging
|
|
configurations and for denial of service attacks.
|
|
.LP
|
|
Although a Road Warrior connection must be initiated by the mobile
|
|
side, the other side can and will rekey using the temporary connection
|
|
it has created. If the Road Warrior wishes to be able to disconnect,
|
|
it is probably wise to set \fB\-\-keyingtries\fP to 1 in the
|
|
connection on the non-mobile side to prevent it trying to rekey the
|
|
connection. Unfortunately, there is no mechanism to unroute the
|
|
connection automatically.
|
|
.SS Debugging
|
|
.LP
|
|
\fBpluto\fP accepts several optional arguments, useful mostly for debugging.
|
|
Except for \fB\-\-interface\fP, each should appear at most once.
|
|
.TP
|
|
\fB\-\-interface\fP \fIinterfacename\fP
|
|
specifies that the named real public network interface should be considered.
|
|
The interface name specified should not be \fBipsec\fP\fIN\fP.
|
|
If the option doesn't appear, all interfaces are considered.
|
|
To specify several interfaces, use the option once for each.
|
|
One use of this option is to specify which interface should be used
|
|
when two or more share the same IP address.
|
|
.TP
|
|
\fB\-\-ikeport\fP \fIport-number\fP
|
|
changes the UDP port that \fBpluto\fP will use
|
|
(default, specified by IANA: 500)
|
|
.TP
|
|
\fB\-\-ctlbase\fP \fIpath\fP
|
|
basename for control files.
|
|
\fIpath\fP.ctl is the socket through which \fBwhack\fP communicates with
|
|
\fBpluto\fP.
|
|
\fIpath\fP.pid is the lockfile to prevent multiple \fBpluto\fP instances.
|
|
The default is \fI/var/run/pluto\fP).
|
|
.TP
|
|
\fB\-\-secretsfile\fP \fIfile\fP
|
|
specifies the file for authentication secrets
|
|
(default: \fI/etc/ipsec.secrets\fP).
|
|
This name is subject to ``globbing'' as in \fIsh\fP(1),
|
|
so every file with a matching name is processed.
|
|
Quoting is generally needed to prevent the shell from doing the globbing.
|
|
.TP
|
|
\fB\-\-adns\fP \fIpathname\fP
|
|
.TP
|
|
\fB\-\-lwdnsq\fP \fIpathname\fP
|
|
specifies where to find \fBpluto\fP's helper program for asynchronous DNS lookup.
|
|
\fBpluto\fP can be built to use one of two helper programs: \fB_pluto_adns\fP
|
|
or \fBlwdnsq\fP. You must use the program for which it was built.
|
|
By default, \fBpluto\fP will look for the program in
|
|
\fB$IPSEC_DIR\fP (if that environment variable is defined) or, failing that,
|
|
in the same directory as \fBpluto\fP.
|
|
.TP
|
|
\fB\-\-nofork\fP
|
|
disable ``daemon fork'' (default is to fork). In addition, after the
|
|
lock file and control socket are created, print the line ``Pluto
|
|
initialized'' to standard out.
|
|
.TP
|
|
\fB\-\-noklips\fP
|
|
don't actually implement negotiated IPsec SAs
|
|
.TP
|
|
\fB\-\-uniqueids\fP
|
|
if this option has been selected, whenever a new ISAKMP SA is
|
|
established, any connection with the same Peer ID but a different
|
|
Peer IP address is unoriented (causing all its SAs to be deleted).
|
|
This helps clean up dangling SAs when a connection is lost and
|
|
then regained at another IP address.
|
|
.TP
|
|
\fB\-\-stderrlog\fP
|
|
log goes to standard out {default is to use \fIsyslogd\fP(8))
|
|
.LP
|
|
For example
|
|
.TP
|
|
pluto \-\-secretsfile\ ipsec.secrets \-\-ctlbase\ pluto.base \-\-ikeport\ 8500 \-\-nofork \-\-noklips \-\-stderrlog
|
|
.LP
|
|
lets one test \fBpluto\fP without using the superuser account.
|
|
.LP
|
|
\fBpluto\fP is willing to produce a prodigious amount of debugging
|
|
information. To do so, it must be compiled with \-DDEBUG. There are
|
|
several classes of debugging output, and \fBpluto\fP may be directed to
|
|
produce a selection of them. All lines of
|
|
debugging output are prefixed with ``|\ '' to distinguish them from error
|
|
messages.
|
|
.LP
|
|
When \fBpluto\fP is invoked, it may be given arguments to specify
|
|
which classes to output. The current options are:
|
|
.TP
|
|
\fB\-\-debug-raw\fP
|
|
show the raw bytes of messages
|
|
.TP
|
|
\fB\-\-debug-crypt\fP
|
|
show the encryption and decryption of messages
|
|
.TP
|
|
\fB\-\-debug-parsing\fP
|
|
show the structure of input messages
|
|
.TP
|
|
\fB\-\-debug-emitting\fP
|
|
show the structure of output messages
|
|
.TP
|
|
\fB\-\-debug-control\fP
|
|
show \fBpluto\fP's decision making
|
|
.TP
|
|
\fB\-\-debug-lifecycle\fP
|
|
[this option is temporary] log more detail of lifecycle of SAs
|
|
.TP
|
|
\fB\-\-debug-kernel\fP
|
|
show \fBpluto\fP's interaction with the kernel
|
|
.TP
|
|
\fB\-\-debug-dns\fP
|
|
show \fBpluto\fP's interaction with \fBDNS\fP for KEY and TXT records
|
|
.TP
|
|
\fB\-\-debug-oppo\fP
|
|
show why \fBpluto\fP didn't find a suitable DNS TXT record to authorize opportunistic initiation
|
|
.TP
|
|
\fB\-\-debug-all\fP
|
|
all of the above
|
|
.TP
|
|
\fB\-\-debug-private\fP
|
|
allow debugging output with private keys.
|
|
.TP
|
|
\fB\-\-debug-none\fP
|
|
none of the above
|
|
.LP
|
|
The debug form of the
|
|
\fBwhack\fP command will change the selection in a running
|
|
\fBpluto\fP.
|
|
If a connection name is specified, the flags are added whenever
|
|
\fBpluto\fP has identified that it is dealing with that connection.
|
|
Unfortunately, this is often part way into the operation being observed.
|
|
.LP
|
|
For example, to start a \fBpluto\fP with a display of the structure of input
|
|
and output:
|
|
.IP
|
|
pluto \-\-debug-emitting \-\-debug-parsing
|
|
.LP
|
|
To later change this \fBpluto\fP to only display raw bytes:
|
|
.IP
|
|
whack \-\-debug-raw
|
|
.LP
|
|
For testing, SSH's IKE test page is quite useful:
|
|
.IP
|
|
\fIhttp://isakmp-test.ssh.fi/\fP
|
|
.LP
|
|
Hint: ISAKMP SAs are often kept alive by IKEs even after the IPsec SA
|
|
is established. This allows future IPsec SA's to be negotiated
|
|
directly. If one of the IKEs is restarted, the other may try to use
|
|
the ISAKMP SA but the new IKE won't know about it. This can lead to
|
|
much confusion. \fBpluto\fP is not yet smart enough to get out of such a
|
|
mess.
|
|
.SS Pluto's Behaviour When Things Go Wrong
|
|
.LP
|
|
When \fBpluto\fP doesn't understand or accept a message, it just
|
|
ignores the message. It is not yet capable of communicating the
|
|
problem to the other IKE daemon (in the future it might use
|
|
Notifications to accomplish this in many cases). It does log a diagnostic.
|
|
.LP
|
|
When \fBpluto\fP gets no response from a message, it resends the same
|
|
message (a message will be sent at most three times). This is
|
|
appropriate: UDP is unreliable.
|
|
.LP
|
|
When pluto gets a message that it has already seen, there are many
|
|
cases when it notices and discards it. This too is appropriate for UDP.
|
|
.LP
|
|
Combine these three rules, and you can explain many apparently
|
|
mysterious behaviours. In a \fBpluto\fP log, retrying isn't usually the
|
|
interesting event. The critical thing is either earlier (\fBpluto\fP
|
|
got a message which it didn't like and so ignored, so it was still
|
|
awaiting an acceptable message and got impatient) or on the other
|
|
system (\fBpluto\fP didn't send a reply because it wasn't happy with
|
|
the previous message).
|
|
.SS Notes
|
|
.LP
|
|
Each IPsec SA is assigned an SPI, a 32-bit number used to refer to the SA.
|
|
The IKE protocol lets the destination of the SA choose the SPI.
|
|
The range 0 to 0xFF is reserved for IANA.
|
|
\fBPluto\fP also avoids choosing an SPI in the range 0x100 to 0xFFF,
|
|
leaving these SPIs free for manual keying.
|
|
Remember that the peer, if not \fBpluto\fP, may well chose
|
|
SPIs in this range.
|
|
.SS Policies
|
|
.LP
|
|
This catalogue of policies may be of use when trying to configure
|
|
\fBPluto\fP and another IKE implementation to interoperate.
|
|
.LP
|
|
In Phase 1, only Main Mode is supported. We are not sure that
|
|
Aggressive Mode is secure. For one thing, it does not support
|
|
identity protection. It may allow more severe Denial Of Service
|
|
attacks.
|
|
.LP
|
|
No Informational Exchanges are supported. These are optional and
|
|
since their delivery is not assured, they must not matter.
|
|
It is the case that some IKE implementations won't interoperate
|
|
without Informational Exchanges, but we feel they are broken.
|
|
.LP
|
|
No Informational Payloads are supported. These are optional, but
|
|
useful. It is of concern that these payloads are not authenticated in
|
|
Phase 1, nor in those Phase 2 messages authenticated with HASH(3).
|
|
.IP \(bu \w'\(bu\ 'u
|
|
Diffie Hellman Groups MODP 1024 and MODP 1536 (2 and 5)
|
|
are supported.
|
|
Group MODP768 (1) is not supported because it is too weak.
|
|
.IP \(bu
|
|
Host authetication can be done by RSA Signatures or Pre-Shared
|
|
Secrets.
|
|
.IP \(bu
|
|
3DES CBC (Cypher Block Chaining mode) is the only encryption
|
|
supported, both for ISAKMP SAs and IPSEC SAs.
|
|
.IP \(bu
|
|
MD5 and SHA1 hashing are supported for packet authentication in both
|
|
kinds of SAs.
|
|
.IP \(bu
|
|
The ESP, AH, or AH plus ESP are supported. If, and only if, AH and
|
|
ESP are combined, the ESP need not have its own authentication
|
|
component. The selection is controlled by the \-\-encrypt and
|
|
\-\-authenticate flags.
|
|
.IP \(bu
|
|
Each of these may be combined with IPCOMP Deflate compression,
|
|
but only if the potential connection specifies compression and only
|
|
if the kernel is configured with IPCOMP support.
|
|
.IP \(bu
|
|
The IPSEC SAs may be tunnel or transport mode, where appropriate.
|
|
The \-\-tunnel flag controls this when \fBpluto\fP is initiating.
|
|
.IP \(bu
|
|
When responding to an ISAKMP SA proposal, the maximum acceptable
|
|
lifetime is eight hours. The default is one hour. There is no
|
|
minimum. The \-\-ikelifetime flag controls this when \fBpluto\fP
|
|
is initiating.
|
|
.IP \(bu
|
|
When responding to an IPSEC SA proposal, the maximum acceptable
|
|
lifetime is one day. The default is eight hours. There is no
|
|
minimum. The \-\-ipseclifetime flag controls this when \fBpluto\fP
|
|
is initiating.
|
|
.IP \(bu
|
|
PFS is acceptable, and will be proposed if the \-\-pfs flag was
|
|
specified. The DH group proposed will be the same as negotiated for
|
|
Phase 1.
|
|
.SH SIGNALS
|
|
.LP
|
|
\fBPluto\fP responds to \fBSIGHUP\fP by issuing a suggestion that ``\fBwhack\fP
|
|
\-\-listen'' might have been intended.
|
|
.LP
|
|
\fBPluto\fP exits when it recieves \fBSIGTERM\fP.
|
|
.SH EXIT STATUS
|
|
.LP
|
|
\fBpluto\fP normally forks a daemon process, so the exit status is
|
|
normally a very preliminary result.
|
|
.TP
|
|
0
|
|
means that all is OK so far.
|
|
.TP
|
|
1
|
|
means that something was wrong.
|
|
.TP
|
|
10
|
|
means that the lock file already exists.
|
|
.LP
|
|
If \fBwhack\fP detects a problem, it will return an exit status of 1.
|
|
If it received progress messages from \fBpluto\fP, it returns as status
|
|
the value of the numeric prefix from the last such message
|
|
that was not a message sent to syslog or a comment
|
|
(but the prefix for success is treated as 0).
|
|
Otherwise, the exit status is 0.
|
|
.SH FILES
|
|
\fI/var/run/pluto.pid\fP
|
|
.br
|
|
\fI/var/run/pluto.ctl\fP
|
|
.br
|
|
\fI/etc/ipsec.secrets\fP
|
|
.br
|
|
\fI$IPSEC_LIBDIR/_pluto_adns\fP
|
|
.br
|
|
\fI$IPSEC_EXECDIR/lwdnsq\fP
|
|
.br
|
|
\fI/dev/urandom\fP
|
|
.SH ENVIRONMENT
|
|
\fIIPSEC_LIBDIR\fP
|
|
.br
|
|
\fIIPSEC_EXECDIR\fP
|
|
.br
|
|
\fIIPSECmyid\fP
|
|
.SH SEE ALSO
|
|
.LP
|
|
The rest of the FreeS/WAN distribution, in particular \fIipsec\fP(8).
|
|
.LP
|
|
\fIipsec_auto\fP(8) is designed to make using \fBpluto\fP more pleasant.
|
|
Use it!
|
|
.LP
|
|
.IR ipsec.secrets (5)
|
|
describes the format of the secrets file.
|
|
.LP
|
|
\fIipsec_atoaddr\fP(3), part of the FreeS/WAN distribution, describes the
|
|
forms that IP addresses may take.
|
|
\fIipsec_atosubnet\fP(3), part of the FreeS/WAN distribution, describes the
|
|
forms that subnet specifications.
|
|
.LP
|
|
For more information on IPsec, the mailing list, and the relevant
|
|
documents, see:
|
|
.IP
|
|
.nh
|
|
\fIhttp://www.ietf.cnri.reston.va.us/html.charters/ipsec-charter.html\fP
|
|
.hy
|
|
.LP
|
|
At the time of writing, the most relevant IETF RFCs are:
|
|
.IP
|
|
RFC2409 The Internet Key Exchange (IKE)
|
|
.IP
|
|
RFC2408 Internet Security Association and Key Management Protocol (ISAKMP)
|
|
.IP
|
|
RFC2407 The Internet IP Security Domain of Interpretation for ISAKMP
|
|
.LP
|
|
The FreeS/WAN web site <htp://www.freeswan.org>
|
|
and the mailing lists described there.
|
|
.SH HISTORY
|
|
This code is released under the GPL terms.
|
|
See the accompanying file COPYING-2.0 for more details.
|
|
The GPL does NOT apply to those pieces of code written by others
|
|
which are included in this distribution, except as noted by the
|
|
individual authors.
|
|
.LP
|
|
This software was originally written
|
|
for the FreeS/WAN project
|
|
<http://www.freeswan.org>
|
|
by Angelos D. Keromytis
|
|
(angelos@dsl.cis.upenn.edu), in May/June 1997, in Athens, Greece.
|
|
Thanks go to John Ioannidis for his help.
|
|
.LP
|
|
It is currently (2000)
|
|
being developed and maintained by D. Hugh Redelmeier
|
|
(hugh@mimosa.com), in Canada. The regulations of Greece and Canada
|
|
allow us to make the code freely redistributable.
|
|
.LP
|
|
Kai Martius (admin@imib.med.tu-dresden.de) contributed the initial
|
|
version of the code supporting PFS.
|
|
.LP
|
|
Richard Guy Briggs <rgb@conscoop.ottawa.on.ca> and Peter Onion
|
|
<ponion@srd.bt.co.uk> added the PFKEY2 support.
|
|
.LP
|
|
We gratefully acknowledge that we use parts of Eric Young's \fIlibdes\fP
|
|
package; see \fI../libdes/COPYRIGHT\fP.
|
|
.SH BUGS
|
|
.BR pluto
|
|
is a work-in-progress. It currently has many limitations.
|
|
For example, it ignores notification messages that it receives, and
|
|
it generates only Delete Notifications and those only for IPSEC SAs.
|
|
.LP
|
|
\fBpluto\fP does not support the Commit Flag.
|
|
The Commit Flag is a bad feature of the IKE protocol.
|
|
It isn't protected -- neither encrypted nor authenticated.
|
|
A man in the middle could turn it on, leading to DoS.
|
|
We just ignore it, with a warning.
|
|
This should let us interoperate with
|
|
implementations that insist on it, with minor damage.
|
|
.LP
|
|
\fBpluto\fP does not check that the SA returned by the Responder
|
|
is actually one that was proposed. It only checks that the SA is
|
|
acceptable. The difference is not large, but can show up in attributes
|
|
such as SA lifetime.
|
|
.LP
|
|
There is no good way for a connection to be automatically terminated.
|
|
This is a problem for Road Warrior and Opportunistic connections.
|
|
The \fB\-\-dontrekey\fP option does prevent the SAs from
|
|
being rekeyed on expiry.
|
|
Additonally, if a Road Warrior connection has a client subnet with a fixed IP
|
|
address, a negotiation with that subnet will cause any other
|
|
connection instantiations with that same subnet to be unoriented
|
|
(deleted, in effect).
|
|
See also the \-\-uniqueids option for an extension of this.
|
|
.LP
|
|
When \fBpluto\fP sends a message to a peer that has disappeared,
|
|
\fBpluto\fP receives incomplete information from the kernel, so it
|
|
logs the unsatisfactory message ``some IKE message we sent has been
|
|
rejected with ECONNREFUSED (kernel supplied no details)''. John
|
|
Denker suggests that this command is useful for tracking down the
|
|
source of these problems:
|
|
.br
|
|
tcpdump -i eth0 icmp[0] != 8 and icmp[0] != 0
|
|
.br
|
|
Substitute your public interface for eth0 if it is different.
|
|
.LP
|
|
The word ``authenticate'' is used for two different features. We must
|
|
authenticate each IKE peer to the other. This is an important task of
|
|
Phase 1. Each packet must be authenticated, both in IKE and in IPsec,
|
|
and the method for IPsec is negotiated as an AH SA or part of an ESP SA.
|
|
Unfortunately, the protocol has no mechanism for authenticating the Phase 2
|
|
identities.
|
|
.LP
|
|
Bugs should be reported to the <users@lists.freeswan.org> mailing list.
|
|
Caution: we cannot accept
|
|
actual code from US residents, or even US citizens living outside the
|
|
US, because that would bring FreeS/WAN under US export law. Some
|
|
other countries cause similar problems. In general, we would prefer
|
|
that you send detailed problem reports rather than code: we want
|
|
FreeS/WAN to be unquestionably freely exportable, which means being
|
|
very careful about where the code comes from, and for a small bug fix,
|
|
that is often more time-consuming than just reinventing the fix
|
|
ourselves.
|