uml_netjig.8

openswan

specifies where to find \fBpluto\fP's helper program for asynchronous DNS lookup.
By default, this program will be called \fB_pluto_adns\fP and be in
\fB$IPSEC_DIR\fP (if that environment variable is defined) or, failing that,
in the same directory as \fBpluto\fP.
.TP
\fB\-\-nofork\fP
disable ``daemon fork'' (default is to fork).  In addition, after the
lock file and control socket are created, print the line ``Pluto
initialized'' to standard out.
.TP
\fB\-\-noklips\fP
don't actually implement negotiated IPsec SAs
.TP
\fB\-\-uniqueids\fP
if this option has been selected, whenever a new ISAKMP SA is
established, any connection with the same Peer ID but a different
Peer IP address is unoriented (causing all its SAs to be deleted).
This helps clean up dangling SAs when a connection is lost and
then regained at another IP address.
.TP
\fB\-\-stderrlog\fP
log goes to standard out {default is to use \fIsyslogd\fP(8))
.LP
For example
.TP
pluto \-\-secretsfile\ ipsec.secrets \-\-ctlbase\ pluto.base \-\-ikeport\ 8500 \-\-nofork \-\-noklips \-\-stderrlog
.LP
lets one test \fBpluto\fP without using the superuser account.
.LP
\fBpluto\fP is willing to produce a prodigious amount of debugging
information.  To do so, it must be compiled with \-DDEBUG.  There are
several classes of debugging output, and \fBpluto\fP may be directed to
produce a selection of them.  All lines of
debugging output are prefixed with ``|\ '' to distinguish them from error
messages.
.LP
When \fBpluto\fP is invoked, it may be given arguments to specify
which classes to output.  The current options are:
.TP
\fB\-\-debug-raw\fP
show the raw bytes of messages
.TP
\fB\-\-debug-crypt\fP
show the encryption and decryption of messages
.TP
\fB\-\-debug-parsing\fP
show the structure of input messages
.TP
\fB\-\-debug-emitting\fP
show the structure of output messages
.TP
\fB\-\-debug-control\fP
show \fBpluto\fP's decision making
.TP
\fB\-\-debug-lifecycle\fP
[this option is temporary] log more detail of lifecycle of SAs
.TP
\fB\-\-debug-klips\fP
show \fBpluto\fP's interaction with \fBKLIPS\fP
.TP
\fB\-\-debug-dns\fP
show \fBpluto\fP's interaction with \fBDNS\fP for KEY and TXT records.
.TP
\fB\-\-debug-all\fP
all of the above
.TP
\fB\-\-debug-private\fP
allow debugging output with private keys.
.TP
\fB\-\-debug-none\fP
none of the above
.LP
The debug form of the
\fBwhack\fP command will change the selection in a running
\fBpluto\fP.
If a connection name is specified, the flags are added whenever
\fBpluto\fP has identified that it is dealing with that connection.
Unfortunately, this is often part way into the operation being observed.
.LP
For example, to start a \fBpluto\fP with a display of the structure of input
and output:
.IP
pluto \-\-debug-emitting \-\-debug-parsing
.LP
To later change this \fBpluto\fP to only display raw bytes:
.IP
whack \-\-debug-raw
.LP
For testing, SSH's IKE test page is quite useful:
.IP
\fIhttp://isakmp-test.ssh.fi/\fP
.LP
Hint: ISAKMP SAs are often kept alive by IKEs even after the IPsec SA
is established.  This allows future IPsec SA's to be negotiated
directly.  If one of the IKEs is restarted, the other may try to use
the ISAKMP SA but the new IKE won't know about it.  This can lead to
much confusion.  \fBpluto\fP is not yet smart enough to get out of such a
mess.
.SS Pluto's Behaviour When Things Go Wrong
.LP
When \fBpluto\fP doesn't understand or accept a message, it just
ignores the message.  It is not yet capable of communicating the
problem to the other IKE daemon (in the future it might use
Notifications to accomplish this in many cases).  It does log a diagnostic.
.LP
When \fBpluto\fP gets no response from a message, it resends the same
message (a message will be sent at most three times).  This is
appropriate: UDP is unreliable.
.LP
When pluto gets a message that it has already seen, there are many
cases when it notices and discards it.  This too is appropriate for UDP.
.LP
Combine these three rules, and you can explain many apparently
mysterious behaviours.  In a \fBpluto\fP log, retrying isn't usually the
interesting event.  The critical thing is either earlier (\fBpluto\fP
got a message which it didn't like and so ignored, so it was still
awaiting an acceptable message and got impatient) or on the other
system (\fBpluto\fP didn't send a reply because it wasn't happy with
the previous message).
.SS Notes
.LP
If \fBpluto\fP is compiled without \-DKLIPS, it negotiates Security
Associations but never ask the kernel to put them in place and never
makes routing changes.  This allows \fBpluto\fP to be tested on systems
without \fBKLIPS\fP, but makes it rather useless.
.LP
Each IPsec SA is assigned an SPI, a 32-bit number used to refer to the SA.
The IKE protocol lets the destination of the SA choose the SPI.
The range 0 to 0xFF is reserved for IANA.
\fBPluto\fP also avoids choosing an SPI in the range 0x100 to 0xFFF,
leaving these SPIs free for manual keying.
Remember that the peer, if not \fBpluto\fP, may well chose
SPIs in this range.
.SS Policies
.LP
This catalogue of policies may be of use when trying to configure
\fBPluto\fP and another IKE implementation to interoperate.
.LP
In Phase 1, only Main Mode is supported.  We are not sure that
Aggressive Mode is secure.  For one thing, it does not support
identity protection.  It may allow more severe Denial Of Service
attacks.
.LP
No Informational Exchanges are supported.  These are optional and
since their delivery is not assured, they must not matter.
It is the case that some IKE implementations won't interoperate
without Informational Exchanges, but we feel they are broken.
.LP
No Informational Payloads are supported.  These are optional, but
useful.  It is of concern that these payloads are not authenticated in
Phase 1, nor in those Phase 2 messages authenticated with HASH(3).
.IP \(bu \w'\(bu\ 'u
Diffie Hellman Groups MODP 1024 and MODP 1536 (2 and 5)
are supported.
Group MODP768 (1) is not supported because it is too weak.
.IP \(bu
Host authetication can be done by RSA Signatures or Pre-Shared
Secrets.
.IP \(bu
3DES CBC (Cypher Block Chaining mode) is the only encryption
supported, both for ISAKMP SAs and IPSEC SAs.
.IP \(bu
MD5 and SHA1 hashing are supported for packet authentication in both
kinds of SAs.
.IP \(bu
The ESP, AH, or AH plus ESP are supported.  If, and only if, AH and
ESP are combined, the ESP need not have its own authentication
component.  The selection is controlled by the \-\-encrypt and
\-\-authenticate flags.
.IP \(bu
Each of these may be combined with IPCOMP Deflate compression,
but only if the potential connection specifies compression and only
if KLIPS is configured with IPCOMP support.
.IP \(bu
The IPSEC SAs may be tunnel or transport mode, where appropriate.
The \-\-tunnel flag controls this when \fBpluto\fP is initiating.
.IP \(bu
When responding to an ISAKMP SA proposal, the maximum acceptable
lifetime is eight hours.  The default is one hour.  There is no
minimum.  The \-\-ikelifetime flag controls this when \fBpluto\fP
is initiating.
.IP \(bu
When responding to an IPSEC SA proposal, the maximum acceptable
lifetime is one day.  The default is eight hours.  There is no
minimum.  The \-\-ipseclifetime flag controls this when \fBpluto\fP
is initiating.
.IP \(bu
PFS is acceptable, and will be proposed if the \-\-pfs flag was
specified.  The DH group proposed will be the same as negotiated for
Phase 1.
.SH SIGNALS
.LP
\fBPluto\fP responds to \fBSIGHUP\fP by issuing a suggestion that ``\fBwhack\fP
\-\-listen'' might have been intended.
.LP
\fBPluto\fP exits when it recieves \fBSIGTERM\fP.
.SH EXIT STATUS
.LP
\fBpluto\fP normally forks a daemon process, so the exit status is
normally a very preliminary result.
.TP
0
means that all is OK so far.
.TP
1
means that something was wrong.
.TP
10
means that the lock file already exists.
.LP
If \fBwhack\fP detects a problem, it will return an exit status of 1.
If it received progress messages from \fBpluto\fP, it returns as status
the value of the numeric prefix from the last such message
that was not a message sent to syslog or a comment
(but the prefix for success is treated as 0).
Otherwise, the exit status is 0.
.SH FILES
\fI/var/run/pluto/pluto.pid\fP
.br
\fI/var/run/pluto/pluto.ctl\fP
.br
\fI/etc/ipsec.secrets\fP
.br
\fI$IPSEC_DIR/_pluto_adns\fP
.br
\fI/dev/urandom\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
([e-mail]), 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
([e-mail]), in Canada.  The regulations of Greece and Canada
allow us to make the code freely redistributable.
.LP
Kai Martius ([e-mail]) contributed the initial
version of the code supporting PFS.
.LP
Richard Guy Briggs <[e-mail]> and Peter Onion
<[e-mail]> 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 <[e-mail]> 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.