http://www.freeswan.org/freeswan_trees/freeswan-1.97/doc/index.html
Configuration
This section describes setting up and testing Linux FreeS/WAN.
This document is almost obsolete. It is being replaced by our new Quickstart Guide. We
recommend that most users use that.
There are separate documents on testbed configurations and performance measurement which
some users may want to consult along with this one. If you just want to get a few connections
up, this document should have everything you need.
Before attempting this, you should:
" look at our introduction section. We assume here that you understand concepts and
terms described there.
" ensure that FreeS/WAN is installed on your system. See these links:
testing whether FreeS/WAN is installed
performing an installation
You also need to set up and test IP networking on all the machines you plan to install
FreeS/WAN on or to use in testing, before trying to set up FreeS/WAN.
Our example networks
In our examples, we describe a setup with three networks -- two that want to talk to each other
plus the Internet in the middle. The idea is to build an encrypted tunnel across the Internet so
the two networks can talk securely.
We'll call the two gateways East and West. We'll have a client machine on each net: Sunrise
in the East and Sunset in the West.
Of course one does not always have a security gateway separate from the client machine. It is
also quite common to use IPsec on a network that looks like this:
We treat this setup as degenerate cases of the network-to-network link. The East computer is a
gateway for a one-client subnet, and it is also the client.
Our goal here is to tell you how to set up the two gateways, East and West. We assume your
goal is to ensure that East and West encrypt all traffic between them.
1
More complicated network configurations are described later.
Set up and test networking
Before trying to get FreeS/WAN working, you should configure and test IP networking on
both gateways and on at least one client machine behind each of them. IPsec cannot work
without a working IP network beneath it.
Many reported "FreeS/WAN problems" turn out to actually be problems with routing or
firewalling. If any actual IPsec problems turn up, you often cannot even recognise them
(much less debug them) unless the underlying network is right.
If you need advice on this, your best sources are likely:
" the Networking Howto
" the Network Administrator's Guide.
" the Linux Networking-concepts HOWTO from Rusty Russell, author of most of the
Linux firewalling code
See also our bibliography.
Here is our network diagram again:
The client machines, Sunrise and Sunset in our example, may have assigned routable IP
addresses, or they may be using private non-routable addresses (as defined in RFC 1918) with
the gateways doing IP masquerade. It doesn't matter which, as long as whatever it is works
correctly. Note, however, that the two client subnets must have distinct addresses. You cannot
have them both masqueraded to the same range of RFC 1918 addresses.
You must have a working IP network before you try to add IPsec:
" If Sunrise and Sunset have routable IP addresses, test that they can ping each other.
" If IP masquerading is in use, test as far as you can. Even with masquerading on both
ends, Sunset should be able to ping East and Sunrise able to ping West.
It is not enough to just test that your gateways (East and West in the example) can
communicate. You need to test routing to the clients (Sunrise and Sunset) as well.
If you want to run some service encapsulated in IP -- perhaps to use Novell protocols
encapsulated in IPX or to make Windows file sharing or NT domains work across the IPsec
tunnel -- then please build and test what you need for that service on plain IP before trying it
over IPsec. It can be a real nightmare trying to debug such things when you don't know if the
problem is in IPsec, firewall rules, routing, or the configuration of the service itself. Some
advice on making such things work with IPsec is in our interoperation section.
Enabling packet forwarding
2
Some systems turn off packet forwarding by default. This is the safe default. You don't want
systems forwarding packets in uncontrolled ways.
There are three places where you can enable or disable IP forwarding:
in kernel configuration, before compiling the kernel
for FreeS/WAN use, forwarding must always be enabled here. If forwarding is not
compiled into your kernel, attempts to enable or use it will fail.
in the standard boot scripts.
If your kernel has forwarding, you can have it turned on automatically by the standard
boot scripts. The exact method varies from distribution to distribution:
Older Redhat
in the file /etc/sysconfig/network, set FORWARD_IPV4=yes
Redhat 6.x and 7.0
in the file /etc/sysconfig/network, set net.ipv4.ip_forward=1
Debian r2.2 systems (and most likely Debian r2.2 derived systems):
in the file /etc/network/options, set ip_forward=yes
From the command line or your own scripts
use the command:
You need root privileges to write to that file.
A gateway machine needs forwarding enabled or it will not route packets between the two
networks it is attached to. The simplest way to ensure this is to enable forwarding using your
distribution's standard boot scripts. See above.
A more conservative approach is to disable forwarding in your system configuration, and only
enable it after appropriate firewall rules and IPsec tunnels are in place. This reduces the risk
of something slipping past your defenses before they are fully set up. On most systems, this
can conveniently be done by adding a line to /etc/rc.d/rc.local , which is usually the last script
run at boot time.
Other software
Configure and test any other software you will want to use for testing once IPsec is up. For
example, you might put an HTTP daemon on Sunset and a browser on Sunrise. Make sure
these work without IPsec.
If these tests fail, figure out why and fix it. Do not proceed until it works.
Setting up RSA authentication keys
To build a connection, the two gateway machines must be able to authenticate each other. For
FreeS/WAN, the default is public key authentication based on the RSA algorithm. IPsec does
allow several other authentication methods; using some of them with FreeS/WAN is
discussed in our advanced configuration section.
This section covers setting up RSA keys. The example connections to follow (VPN, road
warrior and opportunistic) all use RSA.
3
How RSA works
RSA keys are created as matched pairs. Each pair includes:
" a public key which need not be kept secure. Everyone you plan to communicate with
must be able to get a copy of this. It does not matter if an enemy gets it as well.
" a private key which must be kept secure. No-one but you should have access to it.
For FreeS/WAN, both keys for your system are in the ipsec.secrets file. Maintaining security
of this file is essential since it holds your private key.
Public keys for the gateways you communicate with must be made available to your gateway.
There are several ways to do this:
" arrange for the administrators of those gateways to place their public keys in their
DNS records so your gateway can look them up as required
" collect the public keys for the gateways you talk to, and place them in the connection
descriptions for those gateways in ipsec.conf.
" if you are using the X.509 patches, collect X.509 certificates for the other gateways,
and place them in the appropriate file
The first two methods are described in more detail below. See the X.509 patch documentation
for details of the third, if required.
Remember that public key systems are designed so that it does not matter if an enemy
knows the public keys. However, the private keys must be scrupulously protected.
Generating an RSA key pair
If you installed FreeS/WAN yourself, then the installation process has already generated an
RSA key pair for you and placed it in the ipsec.secrets file. If not, then you need to generate
an RSA key pair (private and public).
If you have the common simple situation where:
" the gateway needs only one RSA private key
" the output of the hostname command is a suitable identifier
then you can just give these commands as root:
For other options, for example if you want to use different identities with different partners,
see the ipsec.secrets and ipsec_newhostkey man pages.
Key generation may take some time, even on a fast system. Also, it needs a lot of random
numbers so you may need to switch consoles and do something like typing a lot of text or
running du / > /dev/null. These give random some inputs to work with.
4
The RSA keys we generate are suitable only for authentication, not for encryption. IPsec uses
them only for authentication. See our IPsec section for details.
It is also possible to use keys in other formats, not generated by FreeS/WAN. This may be
necessary for interoperation with other IPsec implementations. See our links to patches which
add support for keys generated by PGP or embedded in X.509 certificates.
Exchanging authentication keys
Once your gateway's key is in ipsec.secrets, the next step is to send your public key to
everyone you need to set up connections with and collect their public keys. The other players
will be:
for a VPN
each gateway administrator needs public keys for all the other gateways his or her
machine talks to
for a Road Warrior
the gateway needs public keys for all Warriors that connect to it, and each Warrior
needs the gateway public key
for opportunistic encryption
no explicit key exchange is needed, but you must put your public key in DNS so
others can find it when they need it
You need to extract the public part in a suitable suitable format. This done with the
ipsec_showhostkey command. For VPN or Road Warrior applications, use one of:
These two produce the key formatted for insertion in an ipsec.conf file.
For opportunistic encryption, just use:
This gives the key in a format suitable for use in DNS records.
Public keys need not be protected as fanatically as private keys. They are intended to be made
public; the system is designed to work even if an enemy knows all the public keys used. You
can safely make them publicly accessible -- for example, put a gateway key on a web page,
make in available in DNS or via finger(1) -- or transmit it with an insecure method such as
email. However, the recipient must be able to authenticate them, as described in the next
section.
Authenticating public key exchange
Authentication of public keys is critical. It does not matter if an enemy knows your public
keys, but if you can be tricked into trusting a public key supplied by an enemy, you are
in deep trouble .
For example, consider the fellow who wants to communicate with his mistress, keeping
messages secret from his wife.
5
" If the wife obtains the mistress' public key, that is not a problem. As long as she does
not get the private key, she can neither read things sent to the mistress nor authenticate
herself as the mistress.
" If the mistress has any sense, she protects her private key carefully. So long as she
does that, and the husband encrypts his messages correctly, there should be no
(cryptographic!) problem.
" Imagine that the wife is somewhat devious. She generates a public/private key pair
and sends the husband that public key, forging the message to look as if it came from
the mistress. Of course this fails if the husband has enough sense to check the key's
validitybefore using it.
" However, if the husband blindly accepts that key without verification, it is extremely
unlikely that he will be pleased with the results.
" If he accepts that key, the wife can read every message he sends to it. The mistress
cannot.
" The wife can also pose as the mistress and send him whatever bogus messages she
likes. As long as he trusts that key, he will believe these came from the mistress.
The minute he begins to trust a bogus key, the cryptography does not just stop working for
him. Instead, it becomes a powerful weapon against him.
You must authenticate any public keys received before using them. For remote sites, the
simplest method is to exchange them using PGP-signed email (taking appropriate steps to
authenticate the signing keys). Keys posted on the web or made available for finger should
also be PGP-signed. Keys in DNS should be protected by DNS Security. For nearby
machines, a floppy disk or trusted network is fine.
Using RSA signatures for authentication
For each system you will communicate with, you need an RSA public key and an identifier
associated with it. The identifiers go in the leftid= and rightid= lines of connection
descriptions in ipsec.conf. They are the names the systems use to identify themselves during
connection negotiation.
The syntax rules allow four types of identifier:
" an IP address in dotted quad notation, four numbers separated by periods (10.1.19.32).
" a domain name, which will be resolved immediately (bad.example.com).
" a fully qualified domain name (FQDN) with a leading "@" to indicate that it should
not be resolved (@good.example.com)
" user@FQDN ([e-mail])
We recommend that only the @FQDN form be used in most applications. The other three
forms have problems:
" IP addresses make remarkably uninteresting names
" Resolving a name to an IP address is not useful. Why pay the overheads just to get
something that, in this context, is less interesting than the name you started with?
Also, the attempt to resolve it may cause long delays if DNS is down or may cause
security problems if someone subverts a DNS server which you rely on.
" [e-mail] has no advantage over @fred.example.com
6
If your domain is example.com, the gateway identifiers you use should be all be of the form
"@something.example.com" with some convenient string replacing something.
In order to facilitate distributing keys through DNS, we recommend avoiding
" names from non-existent domains
" names from other people's domains
" names which conflict with machine names in your domain
" user@FQDN
For example, if you have a server alice.example.com, then you should not use
"@alice.example.com" to identify Alice's laptop for IPsec.
One convenient scheme is to
use DNS names for your gateways
their IPsec identifiers are things like @firewall.example.com or
@toronto.example.com
add a "road" label in the identifiers for your remote users ("Road Warriors")
Alice's laptop uses the identifier @alice.road.example.com.
The configuration file
FreeS/WAN uses a configuration file, ipsec.conf.
This section describes setting up the parts of that file that apply to all connections:
config setup section
describes machine configuration
conn default section
default parameters which apply to all connections
and gives an introduction to the parts of the file that specify the actual connections. The
following section covers setting up three common types of connection, all using automatic
keying with RSA authentication of the gateways:
conventional VPN
two security gateways, each with a known fixed IP address and with a network of
client machines behind it
Road Warrior
one player has a dynamically-assigned address
opportunistic encryption
the two machines have no prior knowledge of each other, but are set up to secure
connections whenever possible
Setup is quite similar for each of these, but details differ.
Other types of connections are covered in later sections.
7
The easiest way to create a connection is by editing one of our examples. Here we will use the
one in the installation ipsec.conf file. You could also start with one from our doc/examples
file if one of those is closer to what you need to do.
General comments on ipsec.conf
The ipsec.conf file is divided into sections, and the following rules apply:
" the '#' character marks a comment
" the first uncommented line of a section must be at the margin, not indented
" all other non-comment lines of a section must be indented
" blank lines separate sections
" you cannot put a blank line within a section; use a lone '#' instead
For more detail, see the man page.
Which is which?
The confguration file uses left and right to refer to the two gateways involved in a connection,
and has other parameters which come in left/right pairs. For example, leftsubnet is the subnet
behind left.
Which gateway is left and which is right is arbitrary, entirely up to you.
We suggest that you name connections by their ends. For example, name the link between
Fred and Susan's machines "fred-susan" or the link between your Reno and Vancouver offices
"reno-van". You can then let "left" refer to the left half of the name, "fred" or "reno" in our
examples, and "right" to the other half.
To simplify administration, we recommend that you use the same names in the ipsec.conf files
on both ends. The name reno , for example, should refer to the machine in Reno, no matter
which city the file is in.
Then when you copy the file from one machine to the other, the only change you need to
make on the second machine is changing the interfaces= line to match the interface that
machine uses for IPsec.
Of course the software does not actually require this. The names are just arbitrary strings to it.
If your administrator in Reno wants to refer to the machines as "Phobos" and "Demios" while
the Vancouver admin calls them "George" and "Gracie", things should still work.
The setup section of ipsec.conf
The first section of ipsec.conf contains overall setup parameters for IPsec, which apply to all
connections. In our example file, it is:
8
The variables set here are:
interfaces
Tells the KLIPS IPsec code in the Linux kernel which network interface to use. The
interfaces specified here are the only ones this gateway machine will use to
communicate with other IPsec gateways. If this is not correct, nothing works.
In many cases, the appropriate interface is just your default connection to the world
(the Internet, or your corporate network). In these cases, you can use the default
setting:
" interfaces=%defaultroute
To check what FreeS/WAN sees as the default route, you can use the command ipsec
showdefaults. You may need to compare this with the output from route -n to get a
more complete picture.
In other cases, you can name one or more specific interfaces to be used by
FreeS/WAN. For example:
" interfaces="ipsec0=eth0"
" interfaces="ipsec0=eth0 ipsec1=ppp0"
Both tell KLIPS to use eth0 as ipsec0. The second one also supports IPsec over PPP.
Note that
" Multiple tunnels do not require multiple interfaces. It is possible, and even
common, to have one ipsec interface carrying traffic for many tunnels.
" For PPP connections, you specify the virtual PPP interface (for example ppp0)
here, not the underlying physical interface.
If you need to discover interface names, use the command:
If you have PCMCIA or other interfaces that are not available at boot time, special
measures are required. See our section on that.
klipsdebug
Debugging setting for the KLIPS kernel code
plutodebug
9
Debugging setting for the Pluto key and connection negotiation daemon.
klipsdebug and plutodebug can each be set to "none" or to "all" in most circumstances.
There are other options; see the relevant man pages.
plutoload
List of connections to be automatically loaded into memory when Pluto starts.
plutostart
List of connections to be automatically negotiated when Pluto starts.
plutoload and plutostart can be quoted lists of connection names, but are often set to
%search as in our example. Any connection with auto=add in its connection
definition is then loaded, and any connection with auto=start is started.
In most cases, you want plutostart=%search here and auto=start in your connection
descriptions. That way when a connection is broken, for example if one machine
crashes or is taken down for some reason, it will be reliably rebuilt. If only one end is
told to start the connection, then if the other end crashes, you may lose the connection
for a long time. The end that could rebuild does not know it needs to.
The exception to the above is when you have many road warriors connecting to a
single gateway. Having the gateway trying to rebuild tunnels to systems which are
offline can waste considerable resources. In this case, the gateway should have
auto=add for all connections, and let the remote systems start negotiations.
uniqueids
Controls whether two connections with the same subnet on the remote end are
allowed. Normally this is set to yes so that when a remote system disconnects and
reconnects, Pluto will automatically take the old connection down.
Connection defaults
There is a special name %default that let
s you define things that apply to all connections.
You can also set general defaults here but override them later for specific connections. If both
the %default section and the actual connection description set the same variable, then the
connection description takes precedence.
Our example file has:
Variables set here are:
10
keyingtries
How persistent to be in (re)keying negotiations (0 means very).
For testing, you might wish to set this to some small number, perhaps even to 1, to
avoid wasting resources on incorrectly set up connections. In production, it is often set
to zero (retry forever). Keeping the connection up is what machine resources are for,
so if a connection is down you might as well waste resources retrying as waste them
by sitting idle. Of course some caution should be exercised with this, since it can
waste network resources as well.
authby=rsasig
authenticate gateways using RSA signatures. This is the preferred method and is what
we will use in this section's examples. An alternate method is to use shared secrets.
auto=add
automatically add connections descriptions to Pluto's in-memory database at startup.
This is required before Pluto can recognise incoming requests for that connection, so
we suggest making it the default here.
To actually start negotiations for a given connection, you need auto=start. You could
make that the default here or leave auto=add as the default and override it where
needed with auto=start in individual connection descriptions.
Once you are finished testing, you can edit these defaults, adding anything that is standard for
all gateways in your organisation.
Editing a connection description
Edit our example connection to match what you want to do. Rename it appropriately for the
connection you would like to build: "fred-susan", "reno-van" or whatever. The name is the
second string in the line that begins with "conn", for example in:
The connection name is "snt" (subn et tunnel) and to define another connection you make a
copy with a new name such as:
A sample connection description is:
11
We omit here the variables we have shown as set in the default connection above. All of them
could also be set here. If they are set in both places, settings here take precedence. Defaults
are used only if the specific connection description has no value set.
The network described above looks like this:
You need to edit the connection description, inserting appropriate IP addresses and subnet
descriptions so that it describes your network.
The [whatever]s above indicate places where all that matters is routing.
" in simple cases, the inside interface is directly connected to the protected subnet and
has an address on that subnet
" in a large organisation, there might be several routers between gateway and subnet
It does not matter what is between the inside interface and the protected subnet, as long as the
gateway knows how to get packets to the subnet.
You do not need to tell FreeS/WAN anything about the inside interfaces. In fact, there is no
parameter you could use to do that. What you do have to do is make sure the gateway can
route to its client subnet.
12
In most cases, you should use numeric IP addresses, not names, here. The file syntax allows
names to be used, but this creates an additional risk. If someone can subvert the DNS service,
then they can redirect packets whose addresses are looked up via that service.
Many of the variables in this file come in pairs such as "leftsubnet: and "rightsubnet", one for
each end of the connection. The variables on the left side are:
left
The gateway's external interface, the one it uses to talk to the other gateway. This can
be left=%defaultroute.
leftnexthop
Where left should send packets whose destination is right, typically the first router in
the appropriate direction.
This need not always be set.
" If the two gateways are directly linked (packets can go from one to the other
without IP routing by any intermediate device) then you need not set either
leftnexthop or rightnexthop.
" a connection with left=%defaultroute or right=%defaultroute must not have
the corresponding nexthop parameter set
However, in all other cases, you must provide nexthop information. KLIPS
(Kernel IP Security) bypasses the normal routing machinery, so you must give KLIPS
the information even though routing already knows it.
(Yes, we know that design is not ideal, and we plan to change it. See extensive
discussions on the mailing list, mostly with "routing" or "KLIPS 2" in the subject
lines.)
leftsubnet
Addresses for the machines which left is protecting.
" Often something like 101.202.203.0/24 to indicate that a subnet resides behind
left. Often this subnet will be directly connected to left, but this not necessary.
The only requirement is that left must be able to route to it.
" If you omit the leftsubnet line, then left is both the security gateway and the
only client on that end.
For some applications, you may want to create two connections, one to protect traffic
from the subnet behind left and another to protect traffic from the left gateway itself.
This takes two connection descriptions. See below.
auto
If the conn setup section has plutoload=%search , then all connections marked
auto=add are loaded when Pluto starts.
If the conn setup section has plutostart=%search , then all connections marked
auto=start are started when Pluto starts.
13
Initially, we suggest using auto=add on all connections. This lets you start them
manually during testing. Once they are tested, you can change many of them to
auto=start.
For each left* parameter, there is a corresponding right* parameter.
Note that a connection to a subnet behind left does not include left itself. The tunnel described
above protects packets going from one subnet to the other. It does not apply to packets which
either begin or end their journey on one of the gateways. If you need to protect those packets,
you must build separate tunnel descriptions for them.
It is a common error to attempt testing a subnet-to-subnet connection by pinging from one of
the gateways to the far end or vice versa. This does not work, even if the connection is
functioning perfectly, because traffic to or from the gateway itself is not sent on that
connection. If you want to protect traffic originating or terminating on the gateway, then you
need a separate tunnel for that in addition to the subnet's tunnel. See the section on multiple
tunnels.
Example setups
In this section we show examples of three common setups:
" a VPN connection
" road warrior support
" opportunistic encryption
We use a, b, c ... to indicate components of IP addresses. Each letter is some number in the
range 0 to 255, inclusive.
For additional examples, see our examples file.
VPN
For a site-to-site VPN, a simple network diagram looks like this:
which we describe in our config files as:
In most cases, we also have to provide next hop information. A more detailed diagram might
look like this:
(using a, b, c, ... to refer to arbitrary numbers 0 to 255)
14
The ipsec.conf file for the above network would look like this (with RSA keys shortened for
easy display):
15
For more on the use of the firewalling parameters -- leftfirewall, rightfirewall, leftupdown and
rightupdown -- see our IPsec and firewalls section.
The versions of this file at the two ends should be identical, except that each must have an
interfaces= line appropriate for the local machine.
Routable and non-routable addresses
RFC 1918 reserves three groups of addresses for use on private networks:
" 10.0.0.0/8
" 172.16.0.0/12
" 192.168.0.0/16
Addresses in these ranges will never be assigned to anything on the Internet. Many routers
automatically drop any packet with one of these addresses as either source or destination.
You can use FreeS/WAN to:
" make such a network visible to remote clients. For example, with the above
description, any of the client machines on the leftsubnet can talk to machines on
rightsubnet=192.168.0.0/24.
" route between two such networks, using for example leftsubnet=192.168.1.0/24 and
rightsubnet=192.168.0.0/24 .
If you do this, the non-routable addresses still do not appear on the Internet. They are
encapsulated inside IPsec packets which have the gateways' external addresses (from the left
and right parameters of the connection description) in their headers.
Of course FreeS/WAN can also tunnel packets between subnets with normal routable IP
address.
Road Warrior
For our purposes, a "road warrior" is any machine that does not have a fixed IP address. This
includes:
" a traveller who might connect from anywhere
16
" any machine that has a dynamic IP address -- nearly all dialup connections and most
DSL or cable modem connections, at least in North America
" most home machines connecting to the office. If you have a home firewall that is
always left on and has a static IP address, then you can use the VPN configuration
described above. Otherwise, consider yourself a road warrior.
The configuration for road warrior support looks slightly different from a VPN configuration.
We cannot use the road warrior's IP address in the configuration file since we don't know it,
and we don't want to have our server retrying connections to road warriors that are no longer
online.
Some machines, such as home firewalls, may have a dynamic IP address and have a protected
subnet behind them. For this example, however, we assume the Road Warrior is a standalone
machine:
In more detail, the network looks like this:
(using a, b, c, ... to refer to arbitrary numbers 0 to 255)
Here the ipsec.conf files on the two ends are slightly different. The one at the office might
have exactly the same config setup and conn %default sections as in the VPN example.
Then add a description for the road warrior connection:
17
On the gateway end we use the values shown above:
" right=%any so we have no preset idea of right's IP address and will accept whatever
arrives on the packets
" auto=add so we accept connections but don't initiate
" keyingtries=1 so we do not retry to excess when the partner disconnects or changes IP
address
The file on the road warrior end is nearly identical, except that it has:
" interfaces=%defaultroute to handle the dynamic IP address.
" right=%defaultroute
" auto=start to start the connection
" keyingtries=0 to try to maintain the connection
Because we are using right=%defaultroute, we omit the rightnexthop parameter.
Additional road warriors can be added as required. Each should have his or her own
connection description with unique settings for rightid and rightrsasigkey.
If necessary, a single road warrior can have multiple connections, all with the same rightid
and rightrsasigkey, but with different values for leftsubnet to give access to different parts of
the office network.
Jean-Francois Nadeau's Practical Configurations document also has an example of using RSA
authentication for road warriors.
Opportunistic encryption
18
We use the term opportunistic encryption for encryption which does not rely on any pre-
arranged connection, hence does not require that the administrators of the two gateways
involved communicate with each other (for example, to exchange keys) before their systems
can create a secure connection.
The idea is that each gateway check the destinations of outgoing packets, see if an encrypted
connection is possible and, if so, take the opportuntity to encrypt. The opportunity will exist
whenever the admins on both ends have set their systems up for opportunistic encryption.
This makes encryption the default behaviour, and could greatly increase the overall security
of the Internet if it were widely enough adopted. See our documents:
history and politics
for the reasons we want to do this
IPsec protocols
for discussion of the general principle of encrypting as much as possible
The gateways must be able to authenticate each other for IPsec to be secure. For opportunistic
encryption, we rely on the domain name system, DNS, to provide the RSA keys needed for
this authentication. Note, that currently this is not entirely secure because the DNS
mechanism it relies on is not fully secure. Eventually, as secure DNS becomes widely
deployed, this will change.
Status
The team have been working on this for some time, and testing internally. The code is now
ready for wider testing. We encourage everyone to try it.
The main documentation items so far are:
" an Opportunism HowTo by Pluto programmer Hugh Redelmeier
" the project's internal opportunism design document by Hugh and technical lead Henry
Spencer.
" an Internet Draft by Michael Richardson, Hugh and Henry. This is largely a rewrite of
the internal document, a first step toward getting the protocol standardised so there can
be multiple implementations of it.
I am playing catch up. HTML documentation so far is neither complete nor particularly clear.
What I have so far is below.
We do not yet recommend this code for production use . You should still protect your
critical data with explicitly configured IPsec tunnels, rather than relying on opportunistic for
everything at this stage.
ipsec.conf entries for opportunism
The relevant lines in the config file might look like this:
19
The public key, in our format, must be in a KEY record of the appropriate DNS entry for this
to work. We provide some background information on DNS in another file.
Each opportunistic connection supports a single source/destination pair of IP addresses. There
is no way to build an opportunistic connection for a larger subnet. Specifying a subnet in the
connection description, as in the example above, just means that any host in that subnet may
have opportunistic connections.
Putting IPsec information in DNS
To set up for opportunistic encryption, you add some KEY and TXT records to your DNS
data. Specifically:
" each gateway must have a KEY record which other gateways can query to fetch its
RSA authentication key
" any client whose communications are to be protected by a gateway must have a TXT
record pointing to that machine as an authorised IPsec gateway
ipsec_showhostkey provides the key in DNS record format. You will need to put it in the
appropriate place in the DNS records.
To be more precise, quoting the Opportunism Design document:
DNS records for client systems
You must have control of the reverse maps for your client systems, or opportunistic IPsec
cannot be made to work.
The client systems will be either Source or Destination, so they must have:
20
If you control the gateway's reverse map, example client records would look like this:
which can also be written as just:
This provides the IP address of the security gateway and the public key which the gateway
will use to authenticate itself. This is the preferred method.
DNS records for gateway systems
The gateways will be either Initiator or Responder so they need:
If you control the gateway's reverse map, you just add a KEY record there. That is all the
gateway reverse map needs, whether it is working as Initiator or Responder.
Here is an example, with many characters of the key itself left out:
This allows lookups on the IP address of the gateway to retrieve the key.
If you don't control the gateway's reverse map
The approach must be different if you do not have control over the reverse map for your
gateway. Perhaps your ISP controls that, and provides no way for you to put data into their
maps. Without that, you cannot set your gateway up to respond to incoming opportunistic
requests (short of changing ISPs, which you might consider).
However, suppose a friend over at example.org will let you put things in their maps. That will
allow you to set your gateway up to handle opportunistic connections for which it is the
initiator.
21
You still need to be able to put data in the reverse map for your clients. However, that data is
slightly different:
Over at example.org, your friend puts these lines in the DNS data files:
Your gateway must identify itself in IKE as something.example.org, not as
gateway.example.com. You set that up via leftid= or rightid= entries in ipsec.conf.
With this arrangement, the remote gateway receives an ID payload early in IKE with your
(bogus) gateway name "something.example.org". Then it looks up that name to get the IP
address and key for the gateway.
Going beyond the examples
The examples above each described a single connection. This section discusses some issues in
going beyond that, dealing with more complicated networks.
If your network is simple enough that one of the examples had all you need, then you can skip
ahead to firewall setup.
Simplifying ipsec.conf files
We provide several features in the syntax of the ipsec.conf file that are intended to simplify
the work of managing complex multi-connection setups:
" a conn %default connection description for information common to all connections
" also= lines allow a piece of a description to be defined in one place and used in
several (the definition must be after all references)
" include directives allow information to be stored in separate files but used as part of
the configuration
These can be combined in whatever way suits your application. One example is this
ipsec.conf file for a gateway supporting multiple road warriors, all using RSA authentication:
22
On the left gateway, we can omit leftrsasig. That gateway uses the private key stored in
ipsec.secrets and has no need for its own public key. Similarly, the road warriors need not
have their own public keys in ipsec.conf, only the gateway's public key.
The remote connection descriptions in /etc/ipsec/remote.*.conn need then have only a few
lines each:
Be careful with the order of sections in ipsec.conf and any included files. The parser requires
that a definition comes after the also= line which uses it. In our example, the include inserts
the files with the also=leftstuff lines before the definition of conn leftstuff so things are parsed
in the correct order.
The above method, using conn leftstuff and also= , is only one alternative. In simple cases,
you can just put all the information about the left gateway in the conn default section instead
and use no also= lines.
Is there a firewall in play?
If firewall packet filtering is being done on either of the FreeS/WAN gateway machines, or on
any machine on the path between them, then you will probably need to adjust the filters
before FreeS/WAN can work. The filters must allow:
" UDP packets between port 500 on one gateway and port 500 on the other, used by the
automatic keying daemon Pluto.
" at least one of protocol 50 (ESP) and 51 (AH). Most applications want ESP since AH
does only authentication, not encryption.
For more detail, see our IPsec and firewalls document.
Testing the installation
23
This section covers testing connections once you have FreeS/WAN installed and your
ipsec.conf file set up. A separate testing document has more information if required.
We assume all your connection descriptions use auto=add so that ipsec_pluto loads the
descriptions into its internal database at startup but does not attempt to start the connections
until you tell it to.
Matching numbers
It is important that the numbers in your connection descriptions match the network
configuration. FreeS/WAN is almost certain to fail if they do not.
Suppose you are at the Reno office and your ipsec.conf file now has, among others, these
lines:
When you tell FreeS/WAN to start the reno-van connection, it doesn't automagically know
that it is in Reno, or that it is left in the configuration. It discovers that by comparing the IP
address for ipsec0 (and, if it is set, for ipsec1) to the addresses for left and right. ipsec0
inherits its address from the underlying device, eth0 in our example.
So in our example, if eth0 has IP address 101.101.101.101 then ipsec0 inherits that address,
the correct match is found, and this FreeS/WAN discovers that it is left. (If no match is found,
Pluto reports "unable to orient connection".) It then sets itself up with any other left*
parameters in use -- some of leftnexthop , leftsubnet, and leftid.
Once it has these parameters, FreeS/WAN sets things so that
" packets from leftsubnet addressed to rightsubnet are routed through a tunnel to right.
" packets for leftsubnet can be received on the tunnel and delivered.
All should be well.
Of course, there must also be interfaces and routes set up so that this machine can exchange
IP packets both with the right gateway and with clients on leftsubnet. This is done with
standard Linux utilities such as ifconfig and route. Also, things must be correct on right in
Vancouver. It takes two to tunnel.
A data mismatch anywhere in this configuration will cause FreeS/WAN to fail and to log
various error messages. Depending on just how confused FreeS/WAN is and about what, the
error messages may be somewhat confusing. See our troubleshooting section and the FAQ
section om error messages to get help interpreting them if required.
We recommend double-checking for consistency here before starting actual tests..
24
Sanity checking
Reboot both gateways to get FreeS/WAN started. No connections are actually made yet, but
the stage is set.
Examine /var/log/messages for any signs of trouble.
On both gateways, the following entries should now exist in the /proc/net/ directory:
" ipsec_eroute
" ipsec_spi
" ipsec_spigrp
" ipsec_spinew
" ipsec_tncfg
" ipsec_version
and the IPsec interfaces should be attached on top of the specified physical interfaces.
Confirm that with:
You should see at least device ipsec0, and each ipsec device should point to a physical device,
eg. 'ipsec0 -> eth0 mtu=16260 -> 1500'.
Routing connections through these ipsec pseudo-devices causes the data to be encrypted
before being delivered to the underlying network interface. This can be done manually with
our eroute utility, but in most cases you do not need to use that utility directly. Just bring the
connections up and down and the scripts call it as required.
Don't be surprised when you cannot find /dev/ipsec0 or /dev/ipsec1. They do not exist. Other
network pseudo-devices such as eth0 and eth1 do not have entries in /dev either. In general,
network devices do not need such entries.
Starting a connection
On one gateway, start IPsec with:
replacing name with the connection name you used in ipsec.conf.
For this to work, the connection description must already be loaded into Pluto's database,
either via auto=add in the connection description or with an explicit ipsec auto --add name
command.
Note that to shut down a connection, you must do:
on both gateway machines, even though you only start it from one.
25
If the ipsec auto --up command doesn't generate any errors, do
and see if the output looks something like this:
If it does, you're probably in business.
This example shows:
Both connections use ESP with 3DES encryption and MD5 authentication.
The routing is:
This routes all traffic to the protected network 11.0.1.0/24 through an IPsec tunnel to the
gateway 11.0.0.1.
Ping tests
If that works, test whether Sunrise can ping Sunset and vice versa. Our example setup again
is:
There is no point in testing to or from the gateways themselves; the goal is to secure traffic
between the subnets, not between the security gateways themselves.
In general, pings or other tests using the public interfaces of East and/or West are entirely
useless. The IPsec tunnel is for packets between the two protected subnets and the outside
26
interfaces are not on those subnets. Depending on your routing configuration, test packets sent
via those interfaces will be:
" either transmitted in the clear, bypassing the tunnel,
" or discarded because there is no tunnel in place to handle them
In either case, they tell you nothing about the tunnel .
Sometimes it will be inconvenient to use the client machines (Sunrise and Sunset in our
example) for testing. In these cases, use a command such as:
where each of the interfaces specified (eth0 and 192.168.7.1 in the example) are on one of the
protected subnets, eth0 being the local gateway's interface on that side and 192.168.7.1 the
remote gateway's subnet interface. This forces the packets through the IPsec tunnel you want
to test.
For information on setting things up so that gateways can do IPsec to each other or to remote
subnets, see below.
If you have other software set up, test with it as well. Telnet from Sunrise to Sunset, browse a
web server on the remote net and so on.
Testing with tcpdump
To verify that all is working, run tcpdump on a machine which can listen to the traffic
between the gateways.
This is most easily done from a third machine, rather than from one of the gateways. On the
gateways you may see packets at intermediate stages of processing and the result may be
confusing.
If the results make no sense at all, or you see "bad physical medium" error messages, you
probably have an outdated version of tcpdump(8) that does not handle IPsec at all. See this
discussion.
If packets look like total garbage, nothing recognizable, all is well.
See our document on testing for more detail if required.
Shutting down connections
To shut down a connection, you must do:
on both gateway machines, even though you only start it from one.
27
Again, you can verify with the same commands. Repeat the ping test. Repeat the tcpdump
test.
If everything succeeds, congratulations. You now have a working Linux FreeS/WAN
installation.
What next?
At this point you should have a working FreeS/WAN setup. If not, you could go back and
doublecheck various things above or try:
" our FAQ
" our troubleshooting section
" additional configuration examples
If all is well so far, you could go to:
" more detail on the IPsec protocols
" history and politics of cryptography
" advanced configuration, other ways to configure FreeS/WAN connections
" interoperating with other IPsec implementations
Of course you might just go off for a beverage or meal at this point as well.
Other configuration possibilities
This document describes various options for FreeS/WAN configuration which are less used or
more complex (often both) than the standard cases described in our quickstart document.
Some rules of thumb about configuration
Tunnels are cheap
Nearly all of the overhead in IPsec processing is in the encryption and authentication of
packets. Our performance document discusses these overheads.
Beside those overheads, the cost of managing additional tunnels is trivial. Whether your
gateway supports one tunnel or ten just does not matter. A hundred might be a problem; there
is a section on this in the performance document.
So, in nearly all cases, if using multiple tunnels gives you a reasonable way to describe what
you need to do, you should describe it that way in your configuration files.
For example, one user recently asked on a mailing list about this network configuration:
28
The user had constructed only one tunnel, netA to netB, and wanted to know how to use ip-
route to get netC packets into it. This is entirely unnecessary. One of the replies was:
This would still be correct even if we added nets D, E, F, ... to the above diagram and needed
twenty tunnels.
Of course another possibility would be to just use one tunnel, with a subnet mask that includes
both netB and netC (or B, C, D, ...). See next section.
In general, you can construct as many tunnels as you need. Networks like netC in this
example that do not connect directly to the gateway are fine, as long as the gateway can route
to them.
The number of tunnels can become an issue if it reaches 50 or so. This is discussed in the
performance document. Look there for information on supporting hundreds of Road Warriors
from one gateway.
If you find yourself with too many tunnels for some reason like having eight subnets at one
location and nine at another so you end up with 9*8=72tunnels, read the next section here.
Subnet sizes
The subnets used in leftsubnet and rightsubnet can be of any size that fits your needs, and they
need not correspond to physical networks.
You adjust the size by changing the subnet mask, the number after the slash in the subnet
description. For example
" in 192.168.100.0/24 the /24 mask says 24 bits are used to designate the network. This
leave 8 bits to label machines. This subnet has 256 addresses. .0 and .255 are reserved,
so it can have 254 machines.
" A subnet with a /23 mask would be twice as large, 512 addresses.
" A subnet with a /25 mask would be half the size, 128 addresses.
" /0 is the whole Internet
" /32 is a single machine
29
As an example of using these in connection descriptions, suppose your company's head office
has four physical networks using the address ranges:
192.168.100.0/24
development
192.168.101.0/24
production
192.168.102.0/24
marketing
192.168.103.0/24
administration
You can use exactly those subnets in your connection descriptions, or use larger subnets to
grant broad access if required:
leftsubnet=192.168.100.0/24
remote hosts can access only development
leftsubnet=192.168.100.0/23
remote hosts can access development or production
leftsubnet=192.168.102.0/23
remote hosts can access marketing or administration
leftsubnet=192.168.100.0/22
remote hosts can access any of the four departments
or use smaller subnets to restrict access:
leftsubnet=192.168.103.0/24
remote hosts can access any machine in administration
leftsubnet=192.168.103.64/28
remote hosts can access only certain machines in administration.
leftsubnet=192.168.103.42/32
remote hosts can access only one particular machine in administration
To be exact, 192.68.103.64/28 means all addresses whose top 28 bits match 192.168.103.64.
There are 16 of these because there are 16 possibilities for the remainingg 4 bits. Their
addresses are 192.168.103.64 to 192.168.103.79.
Each connection description can use a different subnet if required.
It is possible to use all the examples above on the same FreeS/WAN gateway, each in a
different connection description, perhaps for different classes of user or for different remote
offices.
It is also possible to have multiple tunnels using different leftsubnet descriptions with the
same right. For example, when the marketing manager is on the road he or she might have
access to:
leftsubnet=192.168.102.0/24
all machines in marketing
192.168.101.32/29
30
some machines in production
leftsubnet=192.168.103.42/32
one particular machine in administration
This takes three tunnels, but tunnels are cheap. If the laptop is set up to build all three tunnels
automatically, then he or she can access all these machines concurrently, perhaps from
different windows.
Other network layouts
Here is the usual network picture for a site-to-site VPN::
and for the Road Warrior::
Other configurations are also possible.
The Internet as a big subnet
A telecommuter might have:
This can be described as a special case of the general subnet-to-subnet connection. The subnet
on the right is 0.0.0.0/0, the whole Internet.
West (the home gateway) can have its firewall rules set up so that only IPsec packets to East
are allowed out. It will then behave as if its only connection to the world was a wire to East.
When machines on the home network need to reach the Internet, they do so via the tunnel,
East and the corporate firewall. From the viewpoint of the Internet (perhaps of some EvilDoer
trying to break in!), those home office machines are behind the firewall and protected by it.
Wireless
Another possible configuration comes up when you do not trust the local network, either
because you have very high security standards or because your are using easily-intercepted
wireless signals.
Some wireless networks have built-in encryption called WEP, but its security is dubious. It is
a fairly common practice to use IPsec instead.
31
In this case, part of your network may look like this:
Of course, there would likely be several wireless workstations, each with its own IPsec tunnel
to the East gateway.
The connection descriptions look much like Road Warrior descriptions:
" each workstation should have its own unique
identifier for IPsec
RSA key
connection description.
" on the gateway, use left=%any, or the workstation IP address
" on workstations, left=%defaultroute, or the workstation IP address
" leftsubnet= is not used.
The rightsubnet= parameter might be set in any of several ways:
rightsubnet=0.0.0.0/0
allowing workstations to access the entire Internet (see above)
rightsubnet=a.b.c.0/24
allowing access to your entire local network
rightsubnet=a.b.c.d/32
restricting the workstation to connecting to a particular server
Of course you can mix and match these as required. For example, a university might allow
faculty full Internet access while letting student laptops connect only to a group of lab
machines.
Choosing connection types
One choice you need to make before configuring additional connections is what type or types
of connections you will use. There are several options, and you can use more than one
concurrently.
Manual vs. automatic keying
IPsec allows two types of connections, with manual or automatic keying. FreeS/WAN starts
them with commands such as:
The difference is in how they are keyed.
Manually keyed connections
use keys stored in ipsec.conf.
Automatically keyed connections
32
use keys automatically generated by the Pluto key negotiation daemon. The key
negotiation protocol, IKE , must authenticate the other system. (It is vulnerable to a
man-in-the-middle attack if used without authentication.) We currently support two
authentication methods:
" using shared secrets stored in ipsec.secrets.
" RSA public key authentication, with our machine's private key in ipsec.secrets.
Public keys for other machines may either be placed in ipsec.conf or provided
via DNS.
A third method, using RSA keys embedded in X.509 certtificates, is provided
by user patches.
Manually keyed connections provide weaker security than automatically keyed connections.
An opponent who reads ipsec.secrets gets your encryption key and can read all data encrypted
by it. If he or she has an archive of old messages, all of them back to your last key change are
also readable.
With automatically-(re)-keyed connections, an opponent who reads ipsec.secrets gets the key
used to authenticate your system in IKE -- the shared secret or your private key, depending
what authentication mechanism is in use. However, he or she does not automatically gain
access to any encryption keys or any data.
An attacker who has your authentication key can mount a man-in-the-middle attack and, if
that succeeds, he or she will get encryption keys and data. This is a serious danger, but it is
better than having the attacker read everyting as soon as he or she breaks into ipsec.secrets.
Moreover, the keys change often so an opponent who gets one key does not get a large
amount of data. To read all your data, he or she would have to do a man-in-the-middle attack
at every key change.
We discuss using manual keying in production below, but this is not recommended except in
special circumstances, such as needing to communicate with some implementation that offers
no auto-keyed mode compatible with FreeS/WAN.
Manual keying may also be useful for testing. There is some discussion of this in our FAQ.
Authentication methods for auto-keying
The IKE protocol which Pluto uses to negotiate connections between gateways must use some
form of authentication of peers. A gateway must know who it is talking to before it can create
a secure connection. We support two basic methods for this authentication:
" shared secrets, stored in ipsec.secrets
" RSA authentication
There are, howver, several variations on the RSA theme, using different methods of managing
the RSA keys:
" our RSA private key in ipsec.secrets with other gateways' public keys
33
either
stored in ipsec.conf
or
looked up via DNS
" authentication with x.509 certificates.; See our links section for information on user-
contributed patches for this.:
Public keys in ipsec.conf give a reasonably straightforward method of specifying keys for
explicitly configured connections.
Putting public keys in DNS allows us to support opportunistic encryption. Any two
FreeS/WAN gateways can provide secure communication, without either of them having any
preset information about the other.
X.509 certificates may be required to interface to various PKIs.
Advantages of public key methods
Authentication with a public key method such as RSA has some important advantages over
using shared secrets.
" no problem of secure transmission of secrets
A shared secret must be shared, so you have the problem of transmitting it
securely to the other party. If you get this wrong, you have no security.
With a public key technique, you transmit only your public key. The system is
designed to ensure that it does not matter if an enemy obtains public keys. The
private key never leaves your machine.
" easier management
Suppose you have 20 branch offices all connecting to one gateway at head
office, and all using shared secrets. Then the head office admin has 20 secrets
to manage. Each of them must be kept secret not only from outsiders, but also
from 19 of the branch office admins. The branch office admins have only one
secret each to manage.
If the branch offices need to talk to each other, this becomes problematic. You
need another 20*19/2 = 190secrets for branch-to-branch communication, each
known to exactly two branches. Now all the branch admins have the headache
of handling 20 keys, each shared with exactly one other branch or with head
office.
For larger numbers of branches, the number of connections and secrets
increases quadratically and managing them becomes a nightmare. A 1000-
gateway fully connected network needs 499,500 secrets, each known to exactly
two players. There are ways to reduce this problem, for example by
introducing a central key server, but these involve additional communication
overheads, more administrative work, and new threats that must be carefully
guarded against.
34
" With public key techniques, the only thing you have to keep secret is your private key,
and you keep that secret from everyone .
As network size increaes, the number of public keys used increases linearly with the
number of nodes. This still requires careful administration in large applications, but is
nothing like the disaster of a quadratic increase. On a 1000-gateway network, you
have 1000 private keys, each of which must be kept secure on one machine, and 1000
public keys which must be distributed. This is not a trivial problem, but it is
manageable.
" does not require fixed IP addresses
" When shared secrets are used in IPsec, the responder must be able to tell which secret
to use by looking at the IP address on the incoming packets. When the other parties do
not have a fixed IP address to be identified by (for example, on nearly all dialup ISP
connections and many cable or ADSL links), this does not work well -- all must share
the same secret!
" When RSA authentication is in use, the initiator can identify itself by name before the
key must be determined. The responder then checks that the message is signed with
the public key corresponding to that name.
There is also a disadvantage:
" your private key is a single point of attack, extremely valuable to an enemy
with shared secrets, an attacker who steals your ipsec.secrets file can
impersonate you or try man-in-the-middle attacks, but can only attack
connections described in that file
an attacker who steals your private key gains the chance to attack not only
existing connections but also any future connections created using that key
This is partly counterbalanced by the fact that the key is never transmitted and remains under
your control at all times. It is likely necessary, however, to take account of this in setting
security policy. For example, you should change gateway keys when an administrator leaves
the company, and should change them periodically in any case.
Overall, public key methods are more secure, more easily managed and more flexible. We
recommend that they be used for all connections, unless there is a compelling reason to do
otherwise.
Using shared secrets in production
Generally, public key methods are preferred for reasons given above, but shared secrets can
be used with no loss of security, just more work and perhaps more need to take precautions.
What I call "shared secrets" are sometimes also called "pre-shared keys". They are used only
for for authentication, never for encryption. Calling them "pre-shared keys" has confused
some users into thinking they were encryption keys, so I prefer to avoid the term..
If you are interoperating with another IPsec implementation, you may find its documentation
calling them "passphrases".
35
Putting secrets in ipsec.secrets
If shared secrets are to be used to authenticate communication for the Diffie-Hellman key
exchange in the IKE protocol, then those secrets must be stored in /etc/ipsec.secrets . For
details, see the ipsec.secrets man page.
A few considerations are vital:
" make the secrets long and unguessable. Since they need not be remembered by
humans, very long ugly strings may be used. We suggest using our ipsec_ranbits
utility to generate long (128 bits or more) random strings.
" transmit secrets securely. You have to share them with other systems, but you lose if
they are intercepted and used against you. Use PGP, SSH, hand delivery of a floppy
disk which is then destroyed, or some other trustworthy method to deliver them.
" store secrets securely, in root-owned files with permissions rw------.
" limit sharing of secrets. Alice, Bob, Carol and Dave may all talk to each other, but
only Alice and Bob should know the secret for an Alice-Bob link.
" do not share private keys. The private key for RSA authentication of your system is
stored in ipsec.secrets, but it is a different class of secret from the pre-shared keys used
for the "shared secret" authentication. No-one but you should have the RSA private
key.
Each line has the IP addresses of the two gateways plus the secret. It should look something
like this:
PSK indicates the use of a pre-s hared key. The quotes and the whitespace shown are
required.
You can use any character string as your secret. For security, it should be both long and
extremely hard to guess. We provide a utility to generate such strings, ipsec_ranbits.
You want the same secret on the two gateways used, so you create a line with that secret and
the two gateway IP addresses. The installation process supplies an example secret, useful only
for testing. You must change it for production use.
File security
You must deliver this file, or the relevant part of it, to the other gateway machine by some
secure means. Don't just FTP or mail the file! It is vital that the secrets in it remain secret. An
attacker who knew those could easily have all the data on your "secure" connection.
This file must be owned by root and should have permissions rw-------.
Shared secrets for road warriors
36
You can use a shared secret to support a single road warrior connecting to your gateway, and
this is a reasonable thing to do in some circumstances. Public key methods have advantages,
discussed above, but they are not critical in this case.
To do this, the line in ipsec.secrets is something like:
where the 0.0.0.0 means that any IP address is acceptable.
For more than one road warrior, shared secrets are not recommended. If shared secrets
are used, then when the responder needs to look up the secret, all it knows about the sender is
an IP address. This is fine if the sender is at a fixed IP address specified in the config file. It is
also fine if only one road warrior uses the wildcard 0.0.0.0 address. However, if you have
more than one road warrior using shared secret authentication, then they must all use that
wildcard and therefore all road warriors using PSK autentication must use the same
secret. Obviously, this is insecure.
For multiple road warriors, use public key authentication. Each roadwarrior can then have
its own identity (our leftid= or rightid= parameters), its own public/private key pair, and its
own secure connection.
Using manual keying in production
Generally, automatic keying is preferred over manual keying for production use because it is
both easier to manage and more secure. Automatic keying frees the admin from much of the
burden of managing keys securely, and can provide perfect forward secrecy. This is discussed
in more detail above.
However, it is possible to use manual keying in production if that is what you want to do. This
might be necessary, for example, in order to interoperate with some device that either does not
provide automatic keying or provides it in some version we cannot talk to.
Note that with manual keying all security rests with the keys . If an adversary acquires your
keys, you've had it. He or she can read everything ever sent with those keys, including old
messages he or she may have archived.
You need to be really paranoid about keys if you're going to rely on manual keying for
anything important.
" keep keys in files with 600 permissions, owned by root
" be extremely careful about security of your gateway systems. Anyone who breaks into
a gateway and gains root privileges can get all your keys and read everything ever
encrypted with those keys, both old messages he has archived and any new ones you
may send.
" change keys regularly. This can be a considerable bother, (and provides an excellent
reason to consider automatic keying instead), but it is absolutely essential for security.
Consider a manually keyed system in which you leave the same key in place for
months:
37
 an attacker can have a very large sample of text sent with that key to work
with. This makes various cryptographic attacks much more likely to succeed.
The chances of the key being compromised in some non-cryptographic manner
-- a spy finds it on a discarded notepad, someone breaks into your server or
your building and steals it, a staff member is bribed, tricked, seduced or
coerced into revealing it, etc. -- also increase over time.
a successful attacker can read everything ever sent with that key. This makes
any successful attack extremely damaging.
It is clear that you must change keys often to have any useful security. The only
question is how often.
" use PGP or SSH for all key transfers
" don't edit files with keys in them when someone can look over your shoulder
" worry about network security; could someone get keys by snooping packets on the
LAN between your X desktop and the gateway?
" lock up your backup tapes for the gateway system
" ... and so on
Linux FreeS/WAN provides some facilities to help with this. In particular, it is good policy to
keep keys in separate files so you can edit configuration information in /etc/ipsec.conf
without exposing keys to "shoulder surfers" or network snoops. We support this with the
also= and include syntax in ipsec.conf.
See the last example in our examples file. In the /etc/ipsec.conf conn samplesep section, it has
the line:
which tells the "ipsec manual" script to insert the configuration description labelled
"samplesep-keys" if it can find it. The /etc/ipsec.conf file must also have a line such as:
which tells it to read other files. One of those other files then might contain the additional
data:
The first line matches the label in the "also=" line, so the indented lines are inserted. The net
effect is exactly as if the inserted lines had occurred in the original file in place of the "also="
line.
Variables set here are:
spi
38
A number needed by the manual keying code. Any 3-digit hex number will do, but if
you have more than one manual connection then spi must be different for each
connection.
esp
Options for ESP (Encapsulated Security Payload), the usual IPsec encryption mode.
Settings here are for encryption using triple DES and authentication using MD5. Note
that encryption without authentication should not be used; it is insecure.
espenkey
Key for ESP encryption. Here, a 192-bit hex number for triple DES.
espauthkey
Key for ESP authentication. Here, a 128-bit hex number for MD5.
Note that the example keys we supply are intended only for testing. For real use, you should
go to automatic keying. If that is not possible, create your own keys for manual mode and
keep them secret
Of course, any files containing keys must have 600 permissions and be owned by root.
If you connect in this way to multiple sites, we recommend that you keep keys for each site in
a separate file and adopt some naming convention that lets you pick them all up with a single
"include" line. This minimizes the risk of losing several keys to one error or attack and of
accidentally giving another site admin keys which he or she has no business knowing.
Also note that if you have multiple manually keyed connections on a single machine, then the
spi parameter must be different for each one. Any 3-digit hex number is OK, provided they
are different for each connection. We reserve the range 0x100 to 0xfff for manual
connections. Pluto assigns SPIs from 0x1000 up for automatically keyed connections.
If ipsec.conf contains keys for manual mode connections, then it too must have permissions
rw-------. We recommend instead that, if you must manual keying in production, you keep the
keys in separate files.
Note also that ipsec.conf is installed with permissions rw-r--r--. If you plan to use manually
keyed connections for anything more than initial testing, you must:
" either change permissions to rw-------
" or store keys separately in secure files and access them via include statements in
ipsec.conf.
We recommend the latter method for all but the simplest configurations.
Creating keys with ranbits
You can create new random keys with the ranbits utility. For example, the commands:
create keys in the sizes needed for our default algorithms:
39
" 192-bit key for 3DES encryption
(only 168 bits are used; parity bits are ignored)
" 128-bit key for keyed MD5 authentication
If you want to use SHA instead of MD5, that requires a 160-bit key
Note that any temporary files used must be kept secure since they contain keys. That is the
reason for the umask command above. The temporary file should be deleted as soon as you
are done with it. You may also want to change the umask back to its default value after you
are finished working on keys.
The ranbits utility may pause for a few seconds if not enough entropy is available
immediately. See ipsec_ranbits and random for details. You may wish to provide some
activity to feed entropy into the system. For example, you might move the mouse around, type
random characters, or do du /usr > /dev/null in the background.
Setting up connections at boot time
You can tell the system to set up connections automatically at boot time by putting suitable
stuff in /etc/ipsec.conf on both systems. The relevant section of the file is labelled by a line
reading config setup.
Details can be found in the ipsec.conf man page. We also provide a file of example
configurations.
The most likely options are something like:
interfaces="ipsec0=eth0 ipsec1=ppp0"
Tells KLIPS which interfaces to use. Up to four interfaces numbered ipsec[0-3] are
supported. Each interface can support an arbitrary number of tunnels.
Note that for PPP, you give the ppp[0-9] device name here, not the underlying device
such as modem (or eth1 if you are using PPPoE).
interfaces=%defaultroute
Alternative setting, useful in simple cases. KLIPS will pick up both its interface and
the next hop information from the settings of the Linux default route.
forwardcontrol=no
Normally "no". Set to "yes" if the IP forwarding option is disabled in your network
configuration. (This can be set as a kernel configuration option or later. e.g. on Redhat,
it's in /etc/sysconfig/network and on SuSE you can adjust it with Yast.) Linux
FreeS/WAN will then enable forwarding when starting up and turn it off when going
down. This is used to ensure that no packets will be forwarded before IPsec comes up
and takes control.
syslog=daemon.error
Used in messages to the system logging daemon (syslogd) to specify what type of
software is sending the messages. If the settings are "daemon.error" as in our example,
then syslogd treats the messages as error messages from a daemon.
40
Note that Pluto does not currently pay attention to this variable. The variable controls
setup messages only.
klipsdebug=
Debug settings for KLIPS.
plutodebug=
Debug settings for Pluto.
... for both the above DEBUG settings
Normally, leave empty as shown above for no debugging output.
Use "all" for maximum information.
See ipsec_klipsdebug and ipsec_pluto man page for other options. Beware that if you
set /etc/ipsec.conf to enable debug output, your system's log files may get large
quickly.
dumpdir=/safe/directory
Normally, programs started by ipsec setup don't crash. If they do, by default, no core
dump will be produced because such dumps would contain secrets. If you find you
need to debug such crashes, you can set dumpdir to the name of a directory in which
to collect the core file.
manualstart=
List of manually keyed connections to be automatically started at boot time. Useful for
testing, but not for long term use. Connections which are automatically started should
also be automatically re-keyed.
pluto=yes
Whether to start Pluto when ipsec startup is done.
This parameter is optional and defaults to "yes" if not present.
"yes" is strongly recommended for production use so that the keying daemon (Pluto)
will automatically re-key the connections regularly. The ipsec-auto parameters
ikelifetime, ipseclifetime and reykeywindow give you control over frequency of
rekeying.
plutoload="reno-van reno-adam reno-nyc"
List of tunnels (by name, e.g. fred-susan or reno-van in our examples) to be loaded
into Pluto's internal database at startup. In this example, Pluto loads three tunnels into
its database when it is started.
If plutoload is "%search", Pluto will load any connections whose description includes
"auto=add" or "auto=start".
plutostart="reno-van reno-adam reno-nyc"
List of tunnels to attempt to negotiate when Pluto is started.
If plutostart is "%search", Pluto will start any connections whose description includes
"auto=start".
Note that, for a connection intended to be permanent, both gateways should be set
try to start the tunnel. This allows quick recovery if either gateway is rebooted or has
its IPsec restarted. If only one gateway is set to start the tunnel and the other gateway
restarts, the tunnel may not be rebuilt.
41
plutowait=no
Controls whether Pluto waits for one tunnel to be established before starting to
negotiate the next. You might set this to "yes"
" if your gateway is a very limited machine and you need to conserve resources.
" for debugging; the logs are clearer if only one connection is brought up at a
time
For a busy and resource-laden production gateway, you likely want "no" so that
connections are brought up in parallel and the whole process takes less time.
The example assumes you are at the Reno office and will use IPsec to Vancouver, New York
City and Amsterdam.
Multiple tunnels between the same two gateways
Consider a pair of subnets, each with a security gateway, connected via the Internet:
A tunnel specification such as:
will allow machines on the two subnets to talk to each other. You might test this by pinging
from polarbear (192.168.100.7) to penguin (192.168.200.5).
However, this does not cover other traffic you might want to secure. To handle all the
possibilities, you might also want these connection descriptions:
42
Without these, neither gateway can do IPsec to the remote subnet. There is no IPsec tunnel or
eroute set up for the traffic.
In our example, with the non-routable 192.168.* addresses used, packets would simply be
discarded. In a different configuration, with routable addresses for the remote subnet, they
would be sent unencrypted since there would be no IPsec eroute and there would be a
normal IP route.
You might also want:
This is required if you want the two gateways to speak IPsec to each other.
This requires a lot of duplication of details. Judicious use of also= and include can reduce this
problem.
Note that, while FreeS/WAN supports all four tunnel types, not all implementations do. In
particular, some versions of Windows 2000 and the freely downloadable version of PGP
provide only "client" functionality. You cannot use them as gateways with a subnet behind
them. To get that functionality, you must upgrade to Windows 2000 server or the
commercially available PGP products.
One tunnel plus advanced routing
It is also possible to use the new routing features in 2.2 and later kernels to avoid most needs
for multple tunnels. Here is one mailing list message on the topic:
43
and FreeS/WAN technical lead Henry Spencer's comment:
Extruded Subnets
What we call extruded subnets are a special case of VPNs.
If your buddy has some unused IP addresses, in his subnet far off at the other side of the
Internet, he can loan them to you... provided that the connection between you and him is fast
enough to carry all the traffic between your machines and the rest of the Internet. In effect, he
"extrudes" a part of his address space over the network to you, with your Internet traffic
appearing to originate from behind his Internet gateway.
Suppose your friend has a.b.c.0/24 and wants to give you a.b.c.240/28. The initial situation is:
where anything from the Internet destined for any machine in a.b.c.0/24 is routed via p.q.r.s
and that gateway knows what to do from there.
Of course it is quite normal for various smaller subnets to exist behind your friend's gateway.
For example, your friend's company might have a.b.c.16/28=development,
a.b.c.32/28=marketing and so on. The Internet neither knows not cares about this; it just
delivers packets to the p.q.r.s and lets the gateway do whatever needs to be done from there.
What we want to do is take a subnet, perhaps a.b.c.240/28, out of your friend's physical
location while still having your friend's gateway route to it. As far as the Internet is
concerned, you remain behind that gateway.
44
The extruded addresses have to be a complete subnet.
In our example, the friend's security gateway is also his Internet gateway, but this is not
necessary. As long as all traffic from the Internet to his addresses passes through the Internet
gate, the security gate could be a machine behind that. The IG would need to route all traffic
for the extruded subnet to the SG, and the SG could handle the rest.
First, configure your subnet using the extruded addresses. Your security gateway's interface to
your subnet needs to have an extruded address (possibly using a Linux virtual interface, if it
also has to have a different address). Your gateway needs to have a route to the extruded
subnet, pointing to that interface. The other machines at your site need to have addresses in
that subnet, and default routes pointing to your gateway.
If any of your friend's machines need to talk to the extruded subnet, they need to have a route
for the extruded subnet, pointing at his gateway.
Then set up an IPsec subnet-to-subnet tunnel between your gateway and his, with your subnet
specified as the extruded subnet, and his subnet specified as "0.0.0.0/0". Do it with manual
keying first for testing, and then with automatic keying for production use.
The tunnel description should be:
If either side was doing firewalling for the extruded subnet before the IPsec connection is set
up, ipsec_manual and ipsec_auto need to know about that (via the {left|right}firewall
parameters) so that it can be overridden for the duration of the connection.
And it all just works. Your SG routes traffic for 0.0.0.0/0 -- that is, the whole Internet --
through the tunnel to his SG, which then sends it onward as if it came from his subnet. When
traffic for the extruded subnet arrives at his SG, it gets sent through the tunnel to your SG,
which passes it to the right machine.
Remember that when ipsec_manual or ipsec_auto takes a connection down, it does not undo
the route it made for that connection. This lets you take a connection down and bring up a
new one, or a modified version of the old one, without having to rebuild the route it uses and
without any risk of packets which should use IPsec accidentally going out in the clear.
Because the route always points into KLIPS, the packets will always go there. Because
KLIPS temporarily has no idea what to do with them (no eroute for them), they will be
discarded.
If you do want to take the route down, this is what the "unroute" operation in manual and auto
is for. Just do an unroute after doing the down.
Note that the route for a connection may have replaced an existing non-IPsec route. Nothing
in Linux FreeS/WAN will put that pre-IPsec route back. If you need it back, you have to
create it with the route command.
45
Road Warrior with virtual IP address
Here is a mailing list message about another way to configure for road warrior support:
46
Dynamic Network Interfaces
47
Sometimes you have to cope with a situation where the network interface(s) aren't all there at
boot. The common example is notebooks with PCMCIA.
Basics
The key issue here is that the config setup section of the /etc/ipsec.conf configuration file lists
the connection between ipsecN and hardware interfaces, in the interfaces= variable. At any
time when ipsec setup start or ipsec setup restart is run this variable must correspond to the
current real situation. More precisely, it must not mention any hardware interfaces which
don't currently exist. The difficulty is that an ipsec setup start command is normally run at
boot time so interfaces that are not up then are mis-handled.
Boot Time
Normally, an ipsec setup start is run at boot time. However, if the hardware situation at boot
time is uncertain, one of two things must be done.
" One possibility is simply not to have IPsec brought up at boot time. To do this:
That's for modern Red Hats or other Linuxes with chkconfig. Systems which lack this
will require fiddling with symlinks in /etc/rc.d/rc?.d or the equivalent.
" Another possibility is to bring IPsec up with no interfaces, which is less aesthetically
satisfying but simpler. Just put
in the configuration file. KLIPS and Pluto will be started, but won't do anything.
Change Time
When the hardware *is* in place, IPsec has to be made aware of it. Someday there may be a
nice way to do this.
Right now, the way to do it is to fix the /etc/ipsec.conf file appropriately, so interfaces reflects
the new situation, and then restart the IPsec subsystem. This does break any existing IPsec
connections.
If IPsec wasn't brought up at boot time, do
while if it was, do
which won't be as quick.
If some of the hardware is to be taken out, before doing that, amend the configuration file so
interfaces no longer includes it, and do
48
Again, this breaks any existing connections.
Unencrypted tunnels
Sometimes you might want to create a tunnel without encryption. Often this is a bad idea,
even if you have some data which need not be private. See this discussion.
The IPsec protocols provide two ways to do build such tunnels:
using ESP with null encryption
not supported by FreeS/WAN
using AH without ESP
supported for manually keyed connections
possible with explicit commands via ipsec_whack (see this list message)
not supported in the ipsec_auto scripts.
One situation in which this comes up is when otherwise some data would be encrypted twice.
Alice wants a secure tunnel from her machine to Bob's. Since she's behind one security
gateway and he's behind another, part of the tunnel that they build passes through the tunnel
that their site admins have built between the gateways. All of Alice and Bob's messages are
encrypted twice.
There are several ways to handle this.
" Just accept the overhead of double encryption. The site admins might choose this if
any of the following apply:
policy says encrypt everything (usually, it should)
they don't entirely trust Alice and Bob (usually, if they don't have to, they
shouldn't)
if they don't feel the saved cycles are worth the time they'd need to build a non-
encrypted tunnel for Alice and Bob's packets (often, they aren't)
" Use a plain IP-in-IP tunnel. These are not well documented. A good starting point is in
the Linux kernel source tree, in /usr/src/linux/drivers/net/README.tunnel.
" Use a manually-keyed AH-only tunnel.
Note that if Alice and Bob want end-to-end security, they must build a tunnel end-to-end
between their machines or use some other end-to-end tool such as PGP or SSL that suits their
data. The only question is whether the admins build some special unencrypted tunnel for those
already-encrypted packets.
http://www.freeswan.org/freeswan_trees/freeswan-1.97/doc/index.html
49