Contents Previous Next

Configuration

This section describes setting up and testing Linux FreeS/WAN.

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:

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.

     Sunset==========West------------------East=========Sunrise
           local net       untrusted net       local net

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:

                                           telecommuter's PC or
                                           traveller's laptop
     Sunset==========West------------------East
         corporate LAN     untrusted net

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.

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:

See also our bibliography.

Here is our network diagram again:

        Sunset==========West------------------East=========Sunrise
              local net       untrusted net       local net

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:

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

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 Red Hat
in the file /etc/sysconfig/network, set FORWARD_IPV4=yes
Red Hat 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:
         echo "1" > /proc/sys/net/ipv4/ip_forward
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.

RTFM (please Read The Fine Manuals)

As with most things on any Unix-like system, most parts of Linux FreeS/WAN are documented in online manual pages. We provide a list of FreeS/WAN man pages, with links to HTML versions of them.

The man pages describing configuration files are:

Man pages for commands used in this document include:

You can read these either in HTML using the links above or with the man(1) command.

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.

How RSA works

RSA keys are created as matched pairs. Each pair includes:

For FreeS/WAN, both keys for your system are in the ipsec.secrets(5) 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:

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(5) file. If not, then you need to generate an RSA key pair (private and public).

If you have the common simple situation where:

then you can just give these commands as root:

        ipsec newhostkey > /etc/ipsec.secrets
        chmod 600 /etc/ipsec.secrets

For other options, for example if you want to use different identities with different partners, see the ipsec.secrets(5) and ipsec_newhostkey(8) 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(4) some inputs to work with.

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(5), 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(8) command. For VPN or Road Warrior applications, use one of:

        ipsec showhostkey --left
        ipsec showhostkey --right

These two produce the key formatted for insertion in an ipsec.conf(5) file.

For opportunistic encryption, just use:

        ipsec showhostkey
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.

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(1) 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(5). They are the names the systems use to identify themselves during connection negotiation.

The syntax rules allow four types of identifier:

We recommend that only the @FQDN form be used in most applications. The other three forms have problems:

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

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(5).

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.

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(5) file is divided into sections, and the following rules apply:

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(5) 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(5)

The first section of ipsec.conf(5) contains overall setup parameters for IPsec, which apply to all connections. In our example file, it is:

# basic configuration
config setup
        # THIS SETTING MUST BE CORRECT or almost nothing will work;
        # %defaultroute is okay for most simple cases.
        interfaces=%defaultroute
        # Debug-logging controls:  "none" for (almost) none, "all" for lots.
        klipsdebug=none
        plutodebug=none
        # Use auto= parameters in conn descriptions to control startup actions.
        plutoload=%search
        plutostart=%search
        # Close down old connection when new one using same ID shows up.
        uniqueids=yes

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:

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:

Both tell KLIPS to use eth0 as ipsec0. The second one also supports IPsec over PPP.

Note that

If you need to discover interface names, use the command:

              ifconfig
      
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
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 lets 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:

# defaults for subsequent connection descriptions
conn %default
        # How persistent to be in (re)keying negotiations (0 means very).
        keyingtries=0
        # How to authenticate gateways
        authby=rsasig
        # Load all connection descriptions by default
        # Some will override this with auto=start
        auto=add

Variables set here are:

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 night 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:

        conn snt

The connection name is "snt" (subn et tunnel) and to define another connection you make a copy with a new name such as:

        conn reno-van

A sample connection description is:

# sample tunnel
# The network here looks like:
#   leftsubnet====left----leftnexthop......rightnexthop----right====rightsubnet
# If left and right are on the same Ethernet, omit leftnexthop and rightnexthop.
conn sample
        # left security gateway (public-network address)
        left=10.0.0.1
        # next hop to reach right
        leftnexthop=10.44.55.66
        # subnet behind left (omit if there is no subnet)
        leftsubnet=172.16.0.0/24
        # right s.g., subnet behind it, and next hop to reach left
        right=10.12.12.1
        rightnexthop=10.88.77.66
        rightsubnet=192.168.0.0/24
        auto=start

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:

         subnet 172.16.0.0/24              =leftsubnet
                |
                |                          [whatever]
                |
         inside interface
            left gateway machine
         interface 10.0.0.1                =left
                 |
         interface 10.44.55.66             =leftnexthop
              router
         interface we don't know
                 |
            INTERNET
                 |
         interface we don't know
              router
         interface 10.88.77.66             =rightnexthop
                 |
         interface 10.12.12.1              =right
            right gateway machine
         inside interface
                 |
                 |                         [whatever]
                 |
         subnet 192.168.0.0/24             =rightsubnet
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.

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.

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.

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. 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.

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:

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:
        Sunset==========West------------------East=========Sunrise
              local net       untrusted net       local net

which we describe in our config files as:

     leftsubnet === West------------------East=== rightsubnet
                        ^left       right^ 

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)

         subnet a.b.c.0/24                 =leftsubnet
                |          (head office has routable IP addresses)
         interface a.b.c.d
            left gateway machine
         interface e.f.g.h                 =left
                 |         (external address outside a.b.c.0 subnet)
         interface e.f.g.i                 =leftnexthop
              router
         interface we don't know
                 |
            INTERNET
                 |
         interface we don't know
              router
         interface j.k.l.m                =rightnexthop
                 |
         interface j.k.l.n                =right
            right gateway machine
         interface 192.168.0.something
                 |        (branch office uses private IP addresses)
         subnet 192.168.0.0/24             =rightsubnet

The ipsec.conf(5) file for the above network would look like this (with RSA keys shortened for easy display):

# basic configuration
config setup
        interfaces="%defaultroute"
        klipsdebug=none
        plutodebug=none
        plutoload=%search
        plutostart=%search

# defaults that apply to all connection descriptions
conn %default
        # How persistent to be in (re)keying negotiations (0 means very).
        keyingtries=0
        # How to authenticate gatways
        authby=rsasig

# VPN connection for head office and branch office
conn head-branch
        # identity we use in authentication exchanges
        leftid=@head.example.com
        leftrsasigkey=0x175cffc641f...
        # left security gateway (public-network address)
        left=e.f.g.h
        # next hop to reach right
        leftnexthop=e.f.g.i
        # subnet behind left (omit if there is no subnet)
        leftsubnet=a.b.c.0/24
        # right s.g., subnet behind it, and next hop to reach left
        rightid=@branch.example.com
        rightrsasigkey=0xfc641fd6d9a24...
        right=j.k.l.n
        rightnexthop=j.k.l.m
        rightsubnet=192.168.0.0/24
        #
        # right is masquerading
        # So you have three choices, none of them ideal
        #
        # uncomment this to use our default script
        # which works only with ipfwadm(8) on 2.0 kernels
        # or ipchains(8) on 2.2 in ipfwadm(8) emulation mode
        # rightfirewall=yes
        #
        # uncomment this and enter a name to write your own script
        # to use all features of ipchains(8) on 2.2
        # or to use iptables(8) on 2.4
        # rightupdown=whatever_you_want_to_name_the_script
        #
        # if you uncomment neither and remove the rightsubnet= line
        # then the tunnel terminates on the outside of your gateway
        # and the masqueraded subnet is not visible to the remote
        # subnet; they all think they're talking to the gateway
        #
        # try to start the connection
        auto=start

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:

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:

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:

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:

                                           telecommuter's PC or
                                           traveller's laptop
     Sunset==========West------------------East
         corporate LAN     untrusted net

In more detail, the network looks like this:
(using a, b, c, ... to refer to arbitrary numbers 0 to 255)

         subnet a.b.c.0/24               =leftsubnet
                |          (head office has routable IP addresses)
         interface a.b.c.d
            left gateway machine
         interface e.f.g.h               =left
                 |         (external address outside a.b.c.0 subnet)
         interface e.f.g.i               =leftnexthop
              router
                 |
            INTERNET
                 |
     interface with dynamic IP address
          road warrior machine

Here the ipsec.conf(5) 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.

# basic configuration
config setup
        interfaces="%defaultroute"
        klipsdebug=none
        plutodebug=none
        plutoload=%search
        plutostart=%search

# defaults that apply to all connection descriptions
conn %default
        # How persistent to be in (re)keying negotiations (0 means very).
        keyingtries=0
        # How to authenticate gatways
        authby=rsasig

Then add a description for the road warrior connection:

# Connection for road warrior Fred 
conn head-fred
        # identity we use in authentication exchanges
        leftid=@head.example.com
        leftrsasigkey=0x175cffc641f...
        # left security gateway (public-network address)
        left=e.f.g.h
        # next hop to reach right
        leftnexthop=e.f.g.i
        # subnet behind left (omit if there is no subnet)
        leftsubnet=a.b.c.0/24
        # accept any address for right
        right=%any
        # any address, provided authentication works
        rightid=@fred.road.example.com
        rightrsasigkey=0xd9a24765fe...
        #
        # no subnet for a typical road warrior
        # it is possible, but usually not needed
        # so the rightsubnet= parameter is omitted
        #
        # let the road warrior start the connection
        auto=add
        # override the default retry for road warriors
        # we don't want to retry if IP connectivity is gone
        keyingtries=1

On the gateway end we use the values shown above:

The file on the road warrior end is nearly identical, except that it has:

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

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:

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:

conn subnet-to-anyone              # for our client subnet
        leftsubnet=10.42.42.0/24   # any single client in our subnet
        left=%defaultroute         # our SG (defaults leftnexthop too)
        right=%opportunistic       # anyone we can authenticate via DNS
        rekey=no                   # let unused connections die

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: ipsec_showhostkey(8) 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:

For reference, the minimum set of DNS records needed to make
this all work is either:

1.  TXT in Destination reverse  map,  identifying  Responder
    and providing public key.
2.  KEY in Initiator reverse map, providing public key.
3.  TXT  in  Source  reverse  map, verifying relationship to
    Initiator.

or:

1.  TXT in Destination reverse map, identifying Responder.
2.  KEY in Responder reverse map, providing public key.
3.  KEY in Initiator reverse map, providing public key.
4.  TXT in Source reverse  map,  verifying  relationship  to
    Initiator.

Slight  complications  ensue  for dynamic addresses, lack of
control over reverse maps, etc.
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:

1.  TXT in Destination reverse  map,  identifying  Responder
    and providing public key.
2.  ...
3.  TXT  in  Source  reverse  map, verifying relationship to
    Initiator.

or:

1.  TXT in Destination reverse map, identifying Responder.
2.  ...
3.  ...
4.  TXT in Source reverse  map,  verifying  relationship  to
    Initiator.
If you control the gateway's reverse map, example client records would look like this:
42.42.42.10.in-addr.arpa. IN PTR deepthought.example.com.
42.42.42.10.in-addr.arpa. IN TXT "X-IPsec-Server(10)=10.20.30.40 AQNJjkKlIk9...nYyUkKK8"
which can also be written as just:
42.42.42.10.in-addr.arpa. IN PTR deepthought.example.com.
                          IN TXT "X-IPsec-Server(10)=10.20.30.40 AQNJjkKlIk9...nYyUkKK8"
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:
1.  ...
2.  KEY in Initiator reverse map, providing public key.
3.  ...

or:

1.  ...
2.  KEY in Responder reverse map, providing public key.
3.  KEY in Initiator reverse map, providing public key.
4.  ...

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:

40.30.20.10.in-addr.arpa. IN KEY 0x4200 4 1 AQNJjkKlIk9...nYyUkKK8
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.

You still need to be able to put data in the reverse map for your clients. However, that data is slightly different:

42.42.42.10.in-addr.arpa. IN PTR deepthought.example.com.
                          IN TXT "X-IPsec-Server(10)=something.example.org"
Over at example.org, your friend puts these lines in the DNS data files:
something.example.org. IN A 10.20.30.40
something.example.org. IN KEY 0x4200 4 1 AQNJjkKlIk9...nYyUkKK8
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(5).

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 described 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 .

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:

        netA---gwA---gwB---netB
                            |----netC

   netA and B are secured netC not.
   netA and gwA can not access netC
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:
  The simplest way and indeed the right way to
  solve this problem is to set up two connections:

        leftsubnet=NetA
        left=gwA
        right=gwB
        rightsubnet=NetB
  and
        leftsubnet=NetA
        left=gwA
        right=gwB
        rightsubnet=NetC

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

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
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

In our VPN example, we used a simple network picture:

     Sunset==========West------------------East=========Sunrise
           local net       untrusted net       local net

And for the Road Warrior, another:

                                           telecommuter's PC or
                                           traveller's laptop
     Sunset==========West------------------East
         corporate LAN     untrusted net

Other configurations are also possible.

The Internet as a big subnet

A telecommuter might have:

     Sunset==========West------------------East ================= firewall --- the Internet
         home network      untrusted net        corporate network
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.

In this case, part of your network may look like this:

          West-----------------------------East == the rest of your network
     workstation   untrusted wireless net
Of course, there would likely be several wireless workstations, each with its own IPsec tunnel to the East gateway.

In this example, 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.

Simplifying ipsec.conf files

We provide several features in the syntax of the ipsec.conf(5) file that are intended to simplify the work of managing complex multi-connection setups:

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:

conn %default
        type=tunnel
        pfs=yes
        keylife=2h
        # set some defaults appropriate for the gateway
        # these should be changed or overridden on the road warriors 
        keyingtries=1                   # road warrior can retry, we shouldn't
        auto=add                        # default is to load, but not start
        # some parameters are common to all remote systems
        authby=rsasig                   # all connections use RSA authentication
        right=%any                      # accept from any address

# pick up all remote system descriptions
# uses shell wildcards
include /etc/ipsec/remote.*.conn

# left side of all connections is the same
# define it after the descriptions which use it
conn leftstuff
        # left security gateway (public-network address)
        left=e.f.g.h
        # next hop to reach right
        leftnexthop=e.f.g.i
        # subnet behind left (omit if there is no subnet)
        leftsubnet=a.b.c.0/24
        leftid=@gateway.example.org

On the left gateway, we can omit leftrsasig. That gateway uses the private key stored in ipsec.secrets(5) and has no need for its own public key. Similarly, the road warriors need not have their own public keys in ipsec.conf(5), only the gateway's public key.

The remote connection descriptions in /etc/ipsec/remote.*.conn need then have only a few lines each:

conn myname
        # pick up common info for all connections
        also=leftstuff
        # identify the remote machine
        rightid=@myname.example.org
        rightrsasigkey=0xfc641fd6d9a24...

Be careful with the order of sections in ipsec.conf(5) 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:

For more detail, see our IPsec and firewalls document.

Testing the installation

This section covers testing connections once you have FreeS/WAN installed and your ipsec.conf(5) 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(8) 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:

config setup
        interfaces="ipsec0=eth0"

conn reno-van
        left=101.101.101.101
        right=202.202.202.202

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

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(8) and route(8). 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..

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:

and the IPsec interfaces should be attached on top of the specified physical interfaces. Confirm that with:

        cat /proc/net/ipsec_tncfg

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(8) 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:

        ipsec auto --up name

replacing name with the connection name you used in ipsec.conf(5).

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:

        ipsec auto --down name

on both gateway machines, even though you only start it from one.

If the ipsec auto --up command doesn't generate any errors, do

        ipsec look

and see if the output looks something like this:

foo.spsystems.net Wed Nov 25 22:51:45 EST 1998
-------------------------
10.0.1.0/24 -> 11.0.1.0/24 => tun0x200@11.0.0.1 esp0x202@11.0.0.1
-------------------------
tun0x200@11.0.0.1 IPv4_Encapsulation: dir=out   10.0.0.1 -> 11.0.0.1
esp0x203@10.0.0.1 3DES-MD5-96_Encryption: dir=in  iv=0xc2cbca5ba42ffbb6  seq=0  bit=0x00000000  win=0  flags=0x0<>
esp0x202@11.0.0.1 3DES-MD5-96_Encryption: dir=out  iv=0xc2cbca5ba42ffbb6  seq=0  bit=0x00000000  win=0  flags=0x0<>
Destination     Gateway         Genmask         Flags   MSS Window  irtt Iface
11.0.0.0        0.0.0.0         255.255.255.0   U      1500 0          0 eth1
11.0.1.0        11.0.0.1        255.255.255.0   UG     1404 0          0 ipsec0

If it does, you're probably in business.

This example shows:

        a tunnel              tun0x200 going to 11.0.0.1
        outgoing connection   esp0x202
        incoming connection   esp0x203

Both connections use ESP with 3DES encryption and MD5 authentication.

The routing is:

        11.0.0.0    via eth1 and the Internet
        11.0.1.0    via ipsec0 which encrypts and then sends to 11.0.0.1

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:

        Sunset==========West------------------East=========Sunrise
              local net       untrusted net       local net

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 interfaces are not on those subnets. Depending on your routing configuration, test packets sent via those interfaces will be:

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:

     traceroute -i eth0 -f 20 192.168.7.1

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(8) 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:

        ipsec auto --down name

on both gateway machines, even though you only start it from one.

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:

If all is well so far, you could go to:

Of course you might just go off for a beverage or meal at this point as well.


Contents Previous Next