Import initial strongswan 2.7.0 version into SVN.

1 files changed, 415 insertions, 0 deletions

diff --git a/doc/opportunism.howto b/doc/opportunism.howto
new file mode 100644
index 000000000..14b5ed5a2
--- /dev/null
+++ b/doc/opportunism.howto
@@ -0,0 +1,415 @@
+FreeS/WAN Opportunism HowTo
+===========================
+
+RCSID $Id: opportunism.howto,v 1.1 2004/03/15 20:35:21 as Exp $
+
+D. Hugh Redelmeier
+
+
+FreeS/WAN, the LINUX IPSEC implementation, is intended to allow
+systems to connect through secure tunnels with or without prearrangement.
+We use the term "Opportunism" to describe tunnels set up without
+prearrangement.  This HowTo will show you how to set your system up
+for Opportunism.
+
+You are expected to already have built and used FreeS/WAN.  Much more
+information about FreeS/WAN is provided at http://www.freeswan.org.
+This document is only intended to describe the support for
+opportunism.  The features described here are available in FreeS/WAN
+version 1.91 or later (there were important bugs up until 1.95).
+
+For a more complete description of the design of Opportunism, see our
+paper "Opportunistic Encryption" (available as opportunism.spec in
+the same directory as this document).
+
+
+Steps
+=====
+
+- Understand what you are attempting.  Security requires care.
+  Problems are hard to untangle.  Be sure to read the last section
+  "Important Limitations".
+
+- Install FreeS/WAN (version 1.91 or later).
+
+- Add appropriate DNS records to your reverse-map domains.
+
+- Add suitable conns to /etc/ipsec.conf.
+
+- Try it out: start it, monitor it, fix it.
+
+- Now you understand the system better, reread "Important Limitations"
+
+These steps are also an outline of this document.
+
+
+Theory
+======
+
+FreeS/WAN runs on a machine that we will call a "Security Gateway".
+Usually this machine is a gateway to the internet.  It may be that the
+only machine for which it provides gateway services is itself, but
+that is just a special case -- we will still call it a Security
+Gateway.
+
+A FreeS/WAN Security Gateway implements secure tunnels to other
+Security Gateways.  One problem is to arrange for these tunnels to be
+created and used.  If opportunism is enabled, a Security Gateway
+running FreeS/WAN will intercept the first outbound packet to a
+particular destination (IP address), and try to negotiate a security
+tunnel suitable for traffic to that destination.
+
+To make this work going the other way, the Security Gateway must be
+willing to negotiate with peers trying to protect traffic initiated
+from their side.
+
+The first novel problem is that our Security Gateway needs to discover
+the IP address of the other Security Gateway for the packet that
+prompted the negotiation.  Oh, and quickly discover if there is none
+-- that negotiation will be impossible.
+
+The second novel problem is that our Security Gateway needs to
+authenticate the other Security Gateway.  This authentication needs to
+ensure that the other Security Gateway is who it claims to be AND that
+it is authorized to represent the client for which it claims to be the
+gateway.
+
+The roles in a particular negotiation are:
+     Source----Initiator----...----Responder----Destination
+
+The Source and Destination are endpoints of the traffic that is to be
+protected.  The Source is the one that happened to send the first
+packet of traffic.  Neither needs to be aware of IPSEC or FreeS/WAN.
+That is the job of their respective Security Gateways, Initiator and
+Responder.  The names "Initiator" and "Responder" match those used in
+the IPSEC standards for IKE negotiation.  Remember that Source and
+Initiator could be the same machine; similarly, Destination and
+Responder could be the same.  All traffic from Source or Destination
+must flow through their Security Gateways if it is to be considered
+for protection.  These roles are fluid -- they can be different for
+each negotiation.
+
+We use the DNS (the Domain Name System) as a distributed database to
+publish the required information.
+
+
+DNS Records Required
+====================
+
+See section 2.3 of "Opportunistic Encryption" for a fuller
+explanation.
+
+Generally, we need to add records to the reverse-map DNS entries for
+the client machine and its Security Gateway machine.  There are
+special cases that are exceptions.
+
+A Security Gateway that is going to initiate an Opportunistic
+negotiation needs to provide a way for the Responding SG to find a
+public key for the Initiator to allow authentication.  This is
+accomplished by putting the public key in a KEY record in the
+reverse-map of the Initiator.  Conveniently, the KEY record can
+be generated by the ipsec_showhostkey(8) command.
+
+	ipsec showhostkey
+
+Here is an example of the output, with many characters of the key
+itself left out:
+
+	; RSA 2048 bits   xy.example.com   Sat Apr 15 13:53:22 2000
+	xy.example.com.   IN   KEY   0x4200 4 1 AQOF8tZ2...+buFuFn/
+
+=> Copy the output of the command into the zone information for the
+   reverse-map of the Security Gateway's public interface.
+
+Each client that is to be protected by Opportunistic Encryption must
+include a special TXT record in its reverse-map.  The
+ipsec_showhostkey(8) command can create this too.  Remember:  this
+command must be run on the Security Gateway where the ipsec.secrets
+file resides.  You must tell the command what IP address to put in the
+TXT record.  The IP address is that of the Security Gateway.
+
+	ipsec showhostkey --txt 10.11.12.13
+
+This command might produce the output:
+
+	; RSA 2048 bits   xy.example.com   Sat Apr 15 13:53:22 2000
+	IN TXT  "X-IPsec-Server(10)=10.11.12.13 AQOF8tZ2...+buFuFn/"
+
+- The quotes matter: this is a single string, as far as DNS is
+  concerned.
+
+- The X-IPsec-Server is a prefix that signifies that the TXT record
+  contains Opportunism configuration information.
+
+- The (10) specifies a precedence for this record.  This is similar
+  to MX record preferences.  Lower numbers have stronger preference.
+
+- 10.11.12.13 specifies the IP address of the Security Gateway for
+  this machine.
+
+- AQOF8tZ2...+buFuFn/ is the (shortened) encoding of the RSA Public
+  key of the Security Gateway.
+
+=> Added this output to the zone information for the reverse-map for
+   each client machine.  This gets a bit dull and repetitive.
+
+Unfortunately, not every administrator has control over the contents
+of the reverse-map.  The only case where we can work around this is
+where the Initiator has no suitable reverse map.  In this case, the
+Source's TXT record gives @FQDN ("Fully Qualified Domain Name") in
+place of its Security Gateway's IP address.  This FQDN must match the
+ID-payload used by the Initiator.  Furthermore, a forward lookup for a
+KEY record on the FQDN must yield the Initiator's public key.
+
+If the Source's IP address is the same as the Initiator's IP address,
+the Responder will assume that the Initiator is authorized to talk for
+the Source (itself!).  In this case, the Responder won't try to fetch
+the Source's TXT record from the reverse map for the Source's IP
+address.
+
+These two features can be combined.  If the Source and the Initiator
+are the same (i.e. the Security Gateway is protecting itself), and the
+Initiator uses a @FQDN ID (leftid=@example.com), then the
+administrator of that machine need only have installed a KEY record in
+the FQDN domain -- he need not control any reverse map.
+
+Obscure fact: the forward lookup is only done by a Responder, and then
+only when the Initiator's ID payload specifies the FQDN.  There is no
+provision for a Responder with no control over its reverse-map.
+
+Beware: DNS changes sometimes take a long time to propagate.
+
+
+Configuring FreeS/WAN
+=====================
+
+To enable opportunism, you must include a suitable conn in
+/etc/ipsec.conf and you must enable it.
+
+A suitable conn looks roughly like an ordinary conn.  It more closely
+resembles a Road Warrior conn (a Road Warrior conn is one that has a
+wildcard %any specified as the other Security Gateway).  But in the
+Opportunistic case, both the other Security Gateway AND its client are
+unknown ahead of time.
+
+conn client-to-anyone	# for our client subnet
+	leftsubnet=10.3.2.1.0/24	# any single client in our subnet
+	also=sg-to-anyone	# rest is same as for SG
+
+conn sg-to-anyone	# for our Security Gateway
+	left=%defaultroute	# our SG (defaults leftnexthop too)
+	right=%opportunistic
+	authby=rsasig	# almost always the right choice
+	keyingtries=2	# don't be persistent -- peer might disappear
+	auto=route	# enable at ipsec startup
+
+(%defaultroute only works if you have specified
+interfaces=%defaultroute.  Since this isn't the topic of the howto,
+you will have to look at the other documentation to find out how to
+handle other cases.)
+
+You can have any number of opportunistic conns, but generally it only
+makes sense to have one for each client subnet and one for the
+Security Gateway itself.
+
+Currently only one interface may be used for opportunism: Pluto knows
+nothing about routing, so would be unable to choose amongst several.
+Almost certainly our side's nexthop must be predetermined
+(%defaultroute will do that).
+
+Note: the routing done for outbound Opportunism will catch any packets
+not covered by a more specific route.  This is what you want for
+packets that are also covered by an eroute.  But packets caught by the
+route and not an eroute will be subject to the no-eroute policy of
+KLIPS, which defaults to %drop.  Remember that routing ignores the
+packet's source address, but erouting pays attention to it.  So if
+Opportunism is enabled, it is best to provide for it covering all IP
+addresses behind or on the Security Gateway.
+
+To enable these conns for inbound opportunistic negotiation, they must be
+--added.  auto=add would accomplish this at ipsec startup, but if you cannot
+wait:
+	ipsec auto --add sg-to-anyone
+	ipsec auto --add client-to-anyone
+
+To enable these conns for outbound opportunistic negotiation, they must
+be both --added and --routed.  Outbound packets will then be trapped
+and will trigger negotiation.  auto=route would cause this to happen
+at startup, but if you wish to do this at another time:
+	ipsec auto --add sg-to-anyone
+	ipsec auto --add client-to-anyone
+	ipsec auto --route sg-to-anyone
+	ipsec auto --route client-to-anyone
+
+
+Getting DNS Through
+===================
+
+There is a serious chicken-and-egg problem.  Outbound Opportunism blocks
+communication with an IP address until Pluto discovers whether that IP
+address can have an IPSEC connection negotiated.  This discovery takes
+DNS queries.  These DNS queries might involve communicating with
+arbitrary IP addresses.  Thus we require DNS queries to succeed before
+any communication succeeds, including those same DNS queries!  The way
+out of this conundrum is to exempt at least some DNS query IP traffic
+from Opportunism.
+
+There are several possible solutions, all of which have advantages and
+disadvantages.
+
+1. If you use a single machine, outside your Security Gateway, as DNS
+server, you can build a clear path (or even an IPSEC tunnel, but not
+opportunistically) directly to that machine.
+
+- you could use a type=passthrough conn to provide a clear path
+  between your machine and the DNS machine.
+
+- better still, you could explicitly create an IPSEC connection to
+  your DNS server.  Just be sure that Pluto does not need to access
+  DNS to find the IP addresses or RSA public keys for that connection!
+
+- you could install an explicit route to the DNS machine through
+  your public interface (not ipsecN).  This will bypass KLIPS
+  processing.  You might have to adjust your firewall.  For example:
+
+  	route add host -net ns.example.com gw gw.example.com dev eth1
+
+2. Generally, it is better to run DNS on your Security Gateway.  This
+leads to a need for non-opportunistic paths to an arbitrary number of
+DNS servers in the internet.  One way to accomplish this is to NOT
+have outbound opportunism cover the SG itself, but only the subnet
+behind it.  In other words, leave out the
+	ipsec auto --route sg-to-anyone
+You must also add a type=passthrough eroute specifically for
+sg-to-anyone (without this, the traffic will be handled by the KLIPS
+no-eroute policy).
+
+3. It is actually possible to use a single machine inside your client
+subnet as a DNS server.  The techniques listed in 1 could be used to
+let it communicate with other DNS servers without interference.  This
+might have advantages over 1 if the DNS machine *only* did DNS.
+Another technique (not often possible or reasonable) is to give this
+machine another route to the internet, one that avoids the SG.
+
+4. DNS queries will eventually time out and then Pluto will give up
+and establish %pass eroutes.  So communications should start flowing.
+
+We would like to have better solutions.  Perhaps we will in the
+future.  Suggestions are welcome.
+
+
+Figuring out what is going on
+=============================
+
+Since Opportunism lets your SG operate with less supervision, you may
+be puzzled by what it is up to.  The usual tools exist, but their use
+is more important.  To look at what Pluto is doing, use:
+	ipsec auto --status
+To look at what KLIPS is doing, use
+	ipsec look
+
+To just see the kernel's eroute table, look at the "file"
+/proc/net/ipsec_eroute.  It contains a description of all the eroutes
+in the kernel.  Here is an example:
+
+10         10.2.1.0/24      -> 0.0.0.0/0          => %trap
+259        10.2.1.115/32    -> 10.19.75.161/32    => tun0x1002@10.19.75.145
+71         10.44.73.97/32   -> 0.0.0.0/0          => %trap
+4119       10.44.73.97/32   -> 10.114.121.41/32   => %pass
+
+You read each line as: a packet from within the first subnet, destined
+for the second subnet, will be processed by the Security Association
+Identity (SAID) specified last.  The first column is the number of
+(outbound) packets processed by this eroute.
+
+For shunt eroutes, the SAID is printed as just the type of shunt:
+%pass	pass the packet through with no processing
+%drop	discard the packet
+%reject	discard the packet and notify sender
+%hold	keep the last packet; discard others
+%trap	cause any trapped packet to generate a PF_KEY ACQUIRE
+	to request negotiation; install a corresponding %hold
+	shunt and attach this packet to the %hold
+
+For other eroutes, the SAID is printed as a triple: protocol (three
+letters), SPI (32-bit number in hex), and destination IP address.
+Protocols include:
+
+tun	IP in IP encapsulation (used for most tunnels)
+esp	ESP encapsulation -- part of an IPSEC SA group
+ah	AH packet authentication -- part of an IPSEC SA group
+
+So, looking at our sample eroutes:
+
+10         10.2.1.0/24      -> 0.0.0.0/0          => %trap
+
+	This is a TRAP (int0x104) shunt eroute.  It was installed by
+	Pluto so that it can catch all traffic from its client subnet
+	to the world at large.  Ten outbound packets have been trapped.
+
+259        10.2.1.115/32    -> 10.19.75.161/32    => tun0x1002@10.19.75.145
+
+	This is a tunnel eroute: packets from 10.2.1.115 (within
+	our client subnet) going to 10.19.75.161 will be encrypted
+	and sent to the peer SG 10.19.75.145.  This was the product
+	of an Opportunistic negotiation (a hint is that each client
+	subnet has only one member).  259 packets have been sent
+	through this tunnel.
+
+71         10.44.73.97/32   -> 0.0.0.0/0          => %trap
+
+	This is another TRAP shunt eroute.  It is to catch traffic
+	from the Security Gateway to the world.  It has caught
+	71 outbound packets.
+
+4119       10.44.73.97/32   -> 10.114.121.41/32   => %pass
+
+	This is a %pass (0x100) shunt eroute.  It was installed when an
+	attempted Opportunistic negotiation failed because the reverse
+	domain of 10.114.121.41 had no suitable TXT record.  4119
+	outbound packets have been passed.
+
+
+Important Limitations
+=====================
+
+Pluto's DNS lookup is synchronous (single-threaded).  Not only does
+this slow things down, but it turns out that in extreme cases where
+there are a lot of ACQUIRE messages from KLIPS at once, some of those
+messages can be lost and communications will be blocked by the %hold
+eroute that Pluto doesn't know about.  Pluto now looks every 2 minutes
+for any %holds that it missed.
+
+DNS lookup is not verified -- we don't use Secure DNS.  A spoofed DNS
+could compromise Opportunism.
+
+There are several new opportunities for Denial of Service attacks.
+For example, a Bad Guy could spray our system with pings with forged
+source addresses.  For each unique source address, our system would do
+a (synchronous!) DNS lookup.
+
+Once a %pass eroute is added for a failed negotiation, it will stay
+until it has been inactive for about 15 minutes.  The only activity
+that counts is outbound -- not surprising since a %pass only affects
+outbound traffic.
+
+If a destination's DNS entry specifies the information we need for
+negotiation, Pluto will not let communications proceed without
+negotiating a Security Tunnel.
+
+There is currently no way to tear down a tunnel that is no longer in
+use.  To add insult to injury, when the lifetime is about to be
+exceeded, the initiating Pluto will rekey!  Restarting will clear
+these out.  rekey=no doesn't solve this since SA expiry would be
+uncoordinated and hence cause packets to be lost.
+
+If one side of a Security Tunnel restarts, but doesn't initiate
+negotiation with its peer, the peer will not be able to communicate
+with it until the peer thinks the tunnel needs rekeying due to
+lifetime, or the restarted Security Gateway decides to negotiate for
+its own reasons.
+
+It isn't clear what firewall policies make sense with Opportunism.
+
+If VPN and Opportunism connections coexist, security policies
+implemented via a firewall can only distinguish traffic by IP address.