Introduction to FreeS/WAN

Contents Previous Next

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

         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:

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

            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:

- 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

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:

             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.

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

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

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

            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.

- 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 validity before 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(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:

- 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 (fred@example.com)

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.
- fred@example.com has no advantage over @fred.example.com

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

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

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

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

            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.

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

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.

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:

            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:

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

                                               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:

- 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

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:

    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:

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

    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:

- 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

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

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

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

            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:

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

         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:

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

Contents Previous Next