# Configuration

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

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. This is discussed in more detail after the description of our example networks.

## Our example networks

For our examples, we assume that there are only three networks involved, 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. Once you have this working between two network gateways, extending it to three or more is straightforward.

In our examples, we'll call the two gateways East and West. We'll have only one client machine on each net: Sunrise in the East and Sunset in the West.

A diagram:

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

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, or at least all that your security policies require them to encrypt.

Of course one does not always have a security gateway separate from the client machine. Especially for road warriors, a network that looks like this is common:

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

and this is possible:

                         West------------------East
                               untrusted net

In our configuration files, and in this discussion, we treat the two simpler setups as degenerate cases of the network-to-network link. For all the diagrams above, for example, we speak of "the subnet behind East". In two of the diagrams, of course, that "subnet" is just the machine itself.

This may take some getting used to, but we hope it is less confusing than continually having to say things like "the subnet behind East (or the East machine itself if there is no client subnet)".

## Configuration for a testbed network

Many users just want to get IPSEC installed on a few machines. They can skip this section.

Others may want to build a testbed network, for any of a number of reasons. For them, we have some suggestions.

The ideal test setup for IPSEC is something like:

            Sunset==========West-----eth0    eth1-----East=========Sunrise
                  local net          test machine         local net

The test machine routes packets between the two gateways. This makes things more complicated than if you just connected the two gateway machines directly to each other, but it also makes your test setup much more like the environment you actually use IPSEC in. Those environments nearly always involve routing, and quite a few apparent IPSEC failures turn out to be problems with routing or with firewalls dropping packets. This approach lets you deal with those problems on your test setup.

Also, the test machine is in the ideal position to run diagnostic software (such as tcpdump(8)) for checking IPSEC packets. Such software is likely to misbehave if run on the gateways themselves. It is designed to look into a normal IP stack and may become confused if you ask it to display data from a stack which has IPSEC in play.

For more detailed testbed information see these mailing list messages:

- a user's detailed setup diary for his testbed network
- a FreeS/WAN team member's notes from testing at an IPSEC interop "bakeoff"

## 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 subnets must have distinct addresses. You cannot have them both masqueraded to the same range of RFC 1918 addresses.

- 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. For example, if Sunset is masqueraded behind West then Sunrise cannot ping Sunset but should be able to ping West. Whether Sunset can ping Sunrise, assuming Sunrise is not masqueraded, would depend on whether West's rules let ICMP packets through. If not, you should adjust those rules.

In any case, it is not enough to just test that East and West can communicate.

### Enabling packet forwarding

Some systems turn off packet forwarding by default, even for kernels in which it has been enabled. This is the safe default. You don't want systems forwarding packets in uncontrolled ways.

To turn forwarding on temporarily, use the following command as root:

             echo "1" > /proc/sys/net/ipv4/ip_forward

Turning it on permanently is also possible. The exact method varies from distribution to distribution:

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

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 whatever method your distribution provides. See list above.

A more conservative approach is to disable forwarding in your system configuration, then enable from your boot scripts after appropriate firewall scripts are in place.

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

- ipsec.conf(5)
- ipsec.secrets(5)

Man pages for commands used in this document include:

- ipsec(8)
- ipsec_pluto(8)
- ipsec_rsasigkey(8)
- ipsec_auto(8)
- ipsec_manual(8)

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

## Setting up RSA authentication keys

RSA keys come in 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 systems you communicate with are placed in ipsec.conf(5). Security here is less vital (unless you are using manual keying as well, in which case the file may have secret keys). It does not matter if an enemy knows the public keys, as long as the private keys are 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, you need to:

- Generate an RSA key pair (private and public) using ipsec_rsasigkey(8).
- Put the private key in ipsec.secrets, with a wrapper. The result looks like this:

      : RSA {
            <stuff generated by rsasigkey>

            }

  Note that:
  - the ":" must be unindented (at the margin)
  - the other lines, including the "}", must be indented (not at the margin)
  - spaces are needed to separate tokens so, for example, ":RSA{" won't work.

This means "always use this as my private RSA key". For other options, for example if you want to use different keys with different partners, see the man pages.

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

The next step is to send your public key to everyone you need to set up connections with, and collect their public keys. The public key is the line in the output of rsasigkey starting "#pubkey=0x".

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.

Note, however, that 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.
- However, 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.
- She can also pose as the mistress and send him whatever messages she likes.

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

There are four possible forms for these identifiers:

- 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. IP addresses make remarkably uninteresting names. Resolving a name to an IP address is not interesting in this context, and attempting to resolve it may cause problems if DNS is down or if someone subverts a DNS server which you rely on.

If your domain is example.com, the names you use should be of three types:

- machine names such as "@firewall.example.com".
- names for other resources, chosen not to conflict, such as "@fireplug.example.com"
- identifiers for people (actually for their road warrior machines), such as "@alice.example.com" or, if she prefers, "@cleopatra.example.com".

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.

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

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

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.

Once you are finished testing, you can edit these defaults, adding anything that is standard for all gateways in your organisation.

Previous versions of this document said:

> Note, however, that setting the auto= parameter in the default connection description does not work. You cannot use auto=start here to get all connections started automatically or auto=add to get them all loaded. You must set that in the individual connection descriptions.

This restriction has been removed in FreeS/WAN 1.9. However, if the other end of the tunnel is an older version, the restriction will still apply there, so some caution is still required.

### 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" (subnet 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
                    |
             interface 172.16.0.something
                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
             interface 192.168.0.something
                     |
             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.

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.
leftfirewall
  Set to "yes" if there is a firewall in play that suppresses forwarding, for example if a subnet behind left uses non-routable addresses and left does IP masquerade for them. This will cause Pluto to invoke our default script to adjust the firewall as required.

  For more detail, including ways to invoke your own customised script instead, see our FreeS/WAN and firewalls section.

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

### Which is which?

Which security gateway is "left" and which is "right" is arbitrary.

We suggest that you name connections by their ends. For example, name the link between Fred and Susan's machines "fred-susan" or the link between your Reno and Vancouver offices "reno-van". You can then let "left" refer to the left half of the name, "fred" or "reno" in our examples, and "right" to the other half.

To simplify administration, we recommend that you use the same names in the ipsec.conf files on both ends. The name "reno", for example, should refer to the machine in Reno, no matter which city the file is in, and if "reno" is "left" in the reno-van description in Reno, then "reno" should be "left" in that description on the Vancouver machine as well.

Then when you copy the file from one machine to the other, the only change you should 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.

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

In this example, the network looks like this:

             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 might look like this (with RSA keys shortened for easy display):

    # basic configuration
    config setup
            interfaces=eth0
            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
            rightfirewall=yes
            auto=start

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 route between two such networks, using for example leftsubnet=192.168.47.0/24 and rightsubnet=192.168.48.0/24. These 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.

### Road Warrior

For our purposes, a "road warrior" is any machine that does not have a fixed IP address where it can normally be expected to be on line. 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.

In this example, the network looks like this:

             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 setuo and conn %default sections as in the VPN example.

    # basic configuration
    config setup
            interfaces=eth0
            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.example.com
            rightrsasigkey=0xd9a24765fe...
            # no subnet for a typical road warrior
            # it is possible, but usually not needed
            # 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

- 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

Additional road warriors can be added as required. Each should have his or her own connection description with unique settings for rightid and rightrsasigkey.

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. As of late May, 2001 this code is 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
- a design document by Hugh and technical lead Henry Spencer.

I am playing catch up. HTML documentation so far is neither complete nor particularly clear, and not all of it has had technical review by the developers, so it may have errors. What I have so far is below.

Note that both software and documentation for this are changing quickly. You may want the latest snapshot for opportunism experiments.

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

The public key, in our format, must be in a KEY record of the appropriate DNS entry for this to work.

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.

#### Some DNS background

Opportunism requires that the gateway systems be able to fetch public keys, and other IPSEC-related information, from each other's DNS (domain name service) records.

DNS is a distributed database that maps names to IP addresses and vice versa. A system named gateway.example.com with IP address 10.20.30.40 should have at least two DNS records:

gateway.example.com. IN A 10.20.30.40
  used to look up the name and get an IP address
40.30.20.10.in-addr.arpa. IN PTR gateway.example.com.
  used for reverse lookups, looking up an address to get the associated name. Notice that the digits here are in reverse order; the actual address is 10.20.30.40 but we use 40.30.20.10 here.

Some syntactic details are:

- the IN indicates that these records are for Internet addresses
- The final periods in '.com.' and '.arpa.' are required. They indicate the root of the domain name system.

For much more detail, see:

- Linux Network Administrator's Guide
- the standard DNS reference book
- BIND overview
- BIND 9 Administrator's Reference

The capitalised strings after IN indicate the type of record. Possible types include:

- Address
- PoinTeR
- Canonical NAME, records to support aliasing, multiple names for one address
- MX, used in mail handling
- SIGnature, used in secure DNS
- KEY, used in secure DNS
- TeXT, a multi-purpose record type

To set up for opportunistic encryption, you add some KEY and TXT records to your DNS data.

#### Putting IPSEC information in DNS

There are two types of DNS record to be added:

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

## 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
            authby=rsasig                   # all connections use RSA authentication
            keyingtries=1                   # road warrior can retry, we shouldn't
            # some parameters are common to all remote systems
            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=101.101.101.101
            leftnexthop=101.101.101.1
            leftsubnet=202.202.202.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...
            # we cannot use auto= in default or an also= section
            # so do it here
            auto=add                       # load, but don't start

Note that if auto=add or auto=start parameters are used, they must be in the actual connection descriptions. Neither putting them in the conn default section nor including them via an also= line will work.

Also, be careful with the order of sections in this file. The parser used 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.

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

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, leftfirewall 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 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 this pseudo-device with our eroute(8) utility causes the data to be encrypted before being delivered to the underlying network interface.

Don't be surprised when you cannot find that /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).

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

The packets should, except for some of the header information, be utterly unintelligible. The output of good encryption looks exactly like random noise.

You can put recognizable data in the ping packets with something like:

            ping -p feedfacedeadbeef 11.0.1.1

"feedfacedeadbeef" is a legal hexadecimal pattern that is easy to pick out of hex dumps.

For many other protocols, you need to check if you have encrypted data or ASCII text. Encrypted data has approximately equal frequencies for all 256 possible characters. ASCII text has most characters in the printable range 0x20-0x7f, a few control characters less than 0x20, and none at all in the range 0x80-0xff.

0x20, space, is a good character to look for. In normal English text space occurs about once in seven characters, versus about once in 256 for random or encrypted data. You can put long sequences of spaces in your data and look for 0x20202020 in output, but this is not usually necessary.

If packets look like total garbage, nothing recognizable, all is well.

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.

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

If all is well so far, you could continue with this section to explore other ways to configure FreeS/WAN connections or branch out to:

- more detail on the IPSEC protocols
- interoperating with other IPSEC implementations
- history and politics of cryptography
- additional configuration examples

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

## Other configuration possibilities

The rest of this section describes various less-used options for FreeS/WAN.

### Choosing connection types

The first major decision you need to make before configuring additional connections is what type or types of connections you will use. There are several options, and you can use more than one concurrently.

#### Manual vs. automatic keying

IPSEC allows two types of connections, with manual or automatic keying. FreeS/WAN starts them with commands such as:

            ipsec manual --start name
            ipsec auto --up name

The difference is in how they are keyed.

Manually keyed connections
  use keys stored in ipsec.conf.
Automatically keyed connections
  use keys automatically generated by the Pluto key negotiation daemon. The key negotiation protocol, IKE, must authenticate the other system. (It is vulnerable to a man-in-the-middle attack if used without authentication.) We currently support two authentication methods:
  - using shared secrets stored in ipsec.secrets.
  - RSA public key authentication, with public keys for other machines in ipsec.conf and our machine's private key in ipsec.secrets.

Manually keyed connections provide weaker security than automatically keyed connections. An opponent who gets a key gets all data encrypted by it. We discuss using manual keying in production below, but this is not recommended except in special circumstances, such as needing to communicate with some implementation that offers no auto-keyed mode compatible with FreeS/WAN. Manual keying is useful for testing.

With automatically-(re)-keyed connections, the keys change often so an opponent who gets one key does not get a large amount of data. An opponent who gets a shared secret, or your private key if public key authentication is used, does not automatically gain access to any encryption keys or any data. Once your authentication mechanism has been subverted you have no way to prevent the attacker getting keys and data, but the attacker still has to work for them.

#### Authentication methods for auto-keying

The IKE protocol which Pluto uses to negotiate connections between gateways must use some form of authentication of peers. A gateway must know who it is talking to before it can create a secure connection. We currently support two methods for this authentication:

- shared secrets
- RSA authentication

See our links section for information on user-contributed patches which provide a third mechanism:

- authentication with x.509 certificates

As a long-term goal, FreeS/WAN plans to support distribution of public keys for authentication via secure DNS. This would allow us to support opportunistic encryption. Any two FreeS/WAN gateways could provide secure communication, without either of them having any preset information about the other.

This is not implemented in this release.

#### Advantages of public key methods

Authentication with a public key method such as RSA has some important advantages over using shared secrets.

- no problem of secure transmission of secrets
  - A shared secret must be shared, so you have the problem of transmitting it securely to the other party. If you get this wrong, you have no security.
  - With a public key technique, you transmit only your public key. The system is designed to ensure that it does not matter if an enemy obtains public keys. The private key never leaves your machine.
- easier management
  - Suppose you have 20 branch offices all connecting to one gateway at head office, and all using shared secrets. Then the head office admin has 20 secrets to manage. Each of them must be kept secret not only from outsiders, but also from 19 of the branch office admins. The branch office admins have only one secret each to manage.

    If the branch offices need to talk to each other, this becomes problematic. You need another 20*19/2 = 190 secrets for branch-to-branch communication, each known to exactly two branches. Now all the branch admins have the headache of handling 20 keys, each shared with exactly one other branch or with head office.

    For larger numbers of branches, the number of connections and secrets increases quadratically and managing them becomes a nightmare. A 1000-gateway fully connected network needs 499,500 secrets, each known to exactly two players. There are ways to reduce this problem, for example by introducing a central key server, but these involve additional communication overheads, more administrative work, and new threats that must be carefully guarded against.

  - With public key techniques, the only thing you have to keep secret is your private key, and you keep that secret from everyone.

    As network size increaes, the number of public keys used increases linearly with the number of nodes. This still requires careful administration in large applications, but is nothing like the disaster of a quadratic increase. On a 1000-gateway network, you have 1000 private keys, each of which must be kept secure on one machine, and 1000 public keys which must be distributed. This is not a trivial problem, but it is manageable.

- does not require fixed IP addresses
  - When shared secrets are used in IPSEC, the responder must be able to tell which secret to use by looking at the IP address on the incoming packets. When the other parties do not have a fixed IP address to be identified by (for example, on nearly all dialup ISP connections and many cable or ADSL links), this does not work well -- all must share the same secret!
  - When RSA authentication is in use, the initiator can identify itself by name before the key must be determined. The responder then checks that the message is signed with the public key corresponding to that name.

There is also a disadvantage:

- your private key is a single point of attack, extremely valuable to an enemy
  - with shared secrets, an attacker who steals your ipsec.secrets file can impersonate you or try man-in-the-middle attacks, but can only attack connections described in that file
  - an attacker who steals your private key gains the chance to attack not only existing connections but also any future connections created using that key

This is partly counterbalanced by the fact that the key is never transmitted and remains under your control at all times. It is likely necessary, however, to take account of this in setting security policy. For example, you should change gateway keys when an administrator leaves the company, and should change them periodically in any case.

Overall, public key methods are more secure, more easily managed and more flexible. We recommend that they be used for all connections, unless there is a compelling reason to do otherwise.

### Using shared secrets in production

Generally, public key methods are preferred for reasons given above, but shared secrets can be used with no loss of security, just more work and perhaps more need to take precautions.

#### Putting secrets in ipsec.secrets(5)

If shared secrets are to be used to authenticate communication for the Diffie-Hellman key exchange in the IKE protocol, then those secrets must be stored in /etc/ipsec.secrets. For details, see the ipsec.secrets(5) man page.

A few considerations are vital:

- make the secrets long and unguessable. Since they need not be remembered by humans, very long ugly strings may be used. We suggest using our ipsec_ranbits(8) utility to generate long (128 bits or more) random strings.
- transmit secrets securely. You have to share them with other systems, but you lose if they are intercepted and used against you. Use PGP, SSH, hand delivery of a floppy disk which is then destroyed, or some other trustworthy method to deliver them.
- store secrets securely, in root-owned files with permissions rw------.
- limit sharing of secrets. Alice, Bob, Carol and Dave may all talk to each other, but only Alice and Bob should know the secret for an Alice-Bob link.
- do not share private keys. The private key for RSA authentication of your system is stored in ipsec.secrets(5), but it is a different class of secret from the pre-shared keys used for the "shared secret" authentication. No-one but you should have the RSA private key.

Each line has the IP addresses of the two gateways plus the secret. It should look something like this:

            10.0.0.1 11.0.0.1 : PSK "jxTR1lnmSjuj33n4W51uW3kTR55luUmSmnlRUuWnkjRj3UuTV4T3USSu23Uk55nWu5TkTUnjT"

PSK indicates the use of a pre-shared key. The quotes and the whitespace shown are required.

You can use any character string as your secret. For security, it should be both long and extremely hard to guess. We provide a utility to generate such strings, ipsec_ranbits(8).

You want the same secret on the two gateways used, so you create a line with that secret and the two gateway IP addresses. The installation process supplies an example secret, useful only for testing. You must change it for production use.

#### File security

You must deliver this file, or the relevant part of it, to the other gateway machine by some secure means. Don't just FTP or mail the file! It is vital that the secrets in it remain secret. An attacker who knew those could easily have all the data on your "secure" connection.

This file must be owned by root and should have permissions rw-------.

#### Shared secrets for road warriors

You can use a shared secret to support a single road warrior connecting to your gateway, and this is a reasonable thing to do in some circumstances. Public key methods have advantages, discussed above, but they are not critical in this case.

To do this, the line in ipsec.secrets(5) is something like:

            10.0.0.1 0.0.0.0 : PSK "jxTR1lnmSjuj33n4W51uW3kTR55luUmSmnlRUuWnkjRj3UuTV4T3USSu23Uk55nWu5TkTUnjT"

where the 0.0.0.0 means that any IP address is acceptable.

For more than one road warrior, shared secrets are not recommended. If shared secrets are used, then when the responder needs to look up the secret, all it knows about the sender is an IP address. This is fine if the sender is at a fixed IP address specified in the config file. It is also fine if only one road warrior uses the wildcard 0.0.0.0 address. However, if you have more than one road warrior using shared secret authentication, then they must all use that wildcard and therefore all road warriors using PSK autentication must use the same secret. Obviously, this is insecure.

For multiple road warriors, use public key authentication. Each roadwarrior can then have its own identity (our leftid= or rightid= parameters), its own public/private key pair, and its own secure connection.

### Using manual keying in production

Generally, automatic keying is preferred over manual keying for production use because it is both easier to manage and more secure. Automatic keying frees the admin from much of the burden of managing keys securely, and can provide perfect forward secrecy.

However, it is possible to use manual keying in production if that is what you want to do. This might be necessary, for example, in order to interoperate with some device that either does not provide automatic keying or provides it in some version we cannot talk to.

Note that with manual keying all security rests with the keys. If an adversary acquires your keys, you've had it. He or she can read everything ever sent with those keys, including old messages he or she may have archived. You need to be really paranoid about keys if you're going to rely on manual keying for anything important.

- keep keys in files with 600 permissions, owned by root
- be extremely careful about security of your gateway systems. Anyone who breaks into a gateway and gains root privileges can get all your keys and read everything ever encrypted with those keys, both old messages he has archived and any new ones you may send.
- change keys regularly. This can be a considerable bother, (and provides an excellent reason to consider automatic keying instead), but it is absolutely essential for security. Consider a manually keyed system in which you leave the same key in place for months:
  - an attacker can have a very large sample of text sent with that key to work with. This makes various cryptographic attacks much more likely to succeed.
  - The chances of the key being compromised in some non-cryptographic manner -- a spy finds it on a discarded notepad, someone breaks into your server or your building and steals it, a staff member is bribed, tricked, seduced or coerced into revealing it, etc. -- also increase over time.
  - a successful attacker can read everything ever sent with that key. This makes any successful attack extremely damaging.
  It is clear that you must change keys often to have any useful security. The only question is how often.
- use PGP or SSH for all key transfers
- don't edit files with keys in them when someone can look over your shoulder
- worry about network security; could someone get keys by snooping packets on the LAN between your X desktop and the gateway?
- lock up your backup tapes for the gateway system
- ... and so on

Linux FreeS/WAN provides some facilities to help with this. In particular, it is good policy to keep keys in separate files so you can edit configuration information in /etc/ipsec.conf without exposing keys to "shoulder surfers" or network snoops. We support this with the also= and include syntax in ipsec.conf(5).

See the last example in our examples file. In the /etc/ipsec.conf conn samplesep section, it has the line:

            also=samplesep-keys

which tells the "ipsec manual" script to insert the configuration description labelled "samplesep-keys" if it can find it. The /etc/ipsec.conf file must also have a line such as:

    include ipsec.*.conf

which tells it to read other files. One of those other files then might contain the additional data:

    conn samplesep-keys
      spi=0x200
      esp=3des-md5-96
      espenckey=0x01234567_89abcdef_02468ace_13579bdf_12345678_9abcdef0
      espauthkey=0x12345678_9abcdef0_2468ace0_13579bdf

The first line matches the label in the "also=" line, so the indented lines are inserted. The net effect is exactly as if the inserted lines had occurred in the original file in place of the "also=" line.

Variables set here are:

spi
  A number needed by the manual keying code. Any 3-digit hex number will do, but if you have more than one manual connection then spi must be different for each connection.
esp
  Options for ESP (Encapsulated Security Payload), the usual IPSEC encryption mode. Settings here are for encryption using triple DES and authentication using MD5. Note that encryption without authentication should not be used; it is insecure.
espenkey
  Key for ESP encryption. Here, a 192-bit hex number for triple DES.
espauthkey
  Key for ESP authentication. Here, a 128-bit hex number for MD5.

Note that the example keys we supply are intended only for testing. For real use, you should go to automatic keying. If that is not possible, create your own keys for manual mode and keep them secret

Of course, any files containing keys must have 600 permissions and be owned by root.

If you connect in this way to multiple sites, we recommend that you keep keys for each site in a separate file and adopt some naming convention that lets you pick them all up with a single "include" line. This minimizes the risk of losing several keys to one error or attack and of accidentally giving another site admin keys which he or she has no business knowing.

Also note that if you have multiple manually keyed connections on a single machine, then the spi parameter must be different for each one. Any 3-digit hex number is OK, provided they are different for each connection. We reserve the range 0x100 to 0xfff for manual connections. Pluto assigns SPIs from 0x1000 up for automatically keyed connections.

If ipsec.conf(5) contains keys for manual mode connections, then it too must have permissions rw-------. We recommend instead that, if you must manual keying in production, you keep the keys in separate files.

Note also that ipsec.conf is installed with permissions rw-r--r--. If you plan to use manually keyed connections for anything more than initial testing, you must:

- either change permissions to rw-------
- or store keys separately in secure files and access them via include statements in ipsec.conf.

We recommend the latter method for all but the simplest configurations.

#### Creating keys with ranbits

You can create new random keys with the ranbits(8) utility. For example, the commands:

          umask 177
          ipsec ranbits 192  > temp
          ipsec ranbits 128 >> temp

create keys in the sizes needed for our default algorithms:

- 192-bit key for 3DES encryption
  (only 168 bits are used; parity bits are ignored)
- 128-bit key for keyed MD5 authentication

If you want to use SHA instead of MD5, that requires a 160-bit key

Note that any temporary files used must be kept secure since they contain keys. That is the reason for the umask command above. The temporary file should be deleted as soon as you are done with it. You may also want to change the umask back to its default value after you are finished working on keys.

The ranbits utility may pause for a few seconds if not enough entropy is available immediately. See ipsec_ranbits(8) and random(4) for details. You may wish to provide some activity to feed entropy into the system. For example, you might move the mouse around, type random characters, or do du /usr > /dev/null in the background.

### Setting up connections at boot time

You can tell the system to set up connections automatically at boot time by putting suitable stuff in /etc/ipsec.conf on both systems. The relevant section of the file is labelled by a line reading config setup.

Details can be found in the ipsec.conf(5) man page. We also provide a file of example configurations.

The most likely options are something like:

interfaces="ipsec0=eth0 ipsec1=ppp0"
  Tells KLIPS which interfaces to use. Up to four interfaces numbered ipsec[0-3] are supported. Each interface can support an arbitrary number of tunnels.

  Note that for PPP, you give the ppp[0-9] device name here, not the underlying device such as modem (or eth1 if you are using PPPoE).

interfaces=%defaultroute
  Alternative setting, useful in simple cases. KLIPS will pick up both its interface and the next hop information from the settings of the Linux default route.
forwardcontrol=no
  Normally "no". Set to "yes" if the IP forwarding option is disabled in your network configuration. (This can be set as a kernel configuration option or later. e.g. on Redhat, it's in /etc/sysconfig/network and on SuSE you can adjust it with Yast.) Linux FreeS/WAN will then enable forwarding when starting up and turn it off when going down. This is used to ensure that no packets will be forwarded before IPSEC comes up and takes control.
syslog=daemon.error
  Used in messages to the system logging daemon (syslogd) to specify what type of software is sending the messages. If the settings are "daemon.error" as in our example, then syslogd treats the messages as error messages from a daemon.

  Note that Pluto does not currently pay attention to this variable. The variable controls setup messages only.

klipsdebug=
  Debug settings for KLIPS.
plutodebug=
  Debug settings for Pluto.
... for both the above DEBUG settings
  Normally, leave empty as shown above for no debugging output.
  Use "all" for maximum information.
  See ipsec_klipsdebug(8) and ipsec_pluto(8) man page for other options. Beware that if you set /etc/ipsec.conf to enable debug output, your system's log files may get large quickly.
dumpdir=/safe/directory
  Normally, programs started by ipsec setup don't crash. If they do, by default, no core dump will be produced because such dumps would contain secrets. If you find you need to debug such crashes, you can set dumpdir to the name of a directory in which to collect the core file.
manualstart=
  List of manually keyed connections to be automatically started at boot time. Useful for testing, but not for long term use. Connections which are automatically started should also be automatically re-keyed.
pluto=yes
  Whether to start Pluto when ipsec startup is done.
  This parameter is optional and defaults to "yes" if not present.

  "yes" is strongly recommended for production use so that the keying daemon (Pluto) will automatically re-key the connections regularly. The ipsec-auto parameters ikelifetime, ipseclifetime and reykeywindow give you control over frequency of rekeying.

plutoload="reno-van reno-adam reno-nyc"
  List of tunnels (by name, e.g. fred-susan or reno-van in our examples) to be loaded into Pluto's internal database at startup. In this example, Pluto loads three tunnels into its database when it is started.

  If plutoload is "%search", Pluto will load any connections whose description includes "auto=add" or "auto=start".

plutostart="reno-van reno-adam reno-nyc"
  List of tunnels to attempt to negotiate when Pluto is started.

  If plutostart is "%search", Pluto will start any connections whose description includes "auto=start".

  Note that, for a connection intended to be permanent, both gateways should be set try to start the tunnel. This allows quick recovery if either gateway is rebooted or has its IPSEC restarted. If only one gateway is set to start the tunnel and the other gateway restarts, the tunnel may not be rebuilt.

plutowait=no
  Controls whether Pluto waits for one tunnel to be established before starting to negotiate the next. You might set this to "yes"
  - if your gateway is a very limited machine and you need to conserve resources.
  - for debugging; the logs are clearer if only one connection is brought up at a time
  For a busy and resource-laden production gateway, you likely want "no" so that connections are brought up in parallel and the whole process takes less time.

The example assumes you are at the Reno office and will use IPSEC to Vancouver, New York City and Amsterdam.

### Multiple tunnels between the same two gateways

Consider a pair of subnets, each with a security gateway, connected via the Internet:

             192.168.100.0/24           left subnet
                  |
             192.168.100.1
             North Gateway
             101.101.101.101            left
                  |
             101.101.101.1              left next hop
             [Internet]
             202.202.202.1              right next hop
                  |
             202.202.202.202            right
             South gateway
             192.168.200.1
                  |
             192.168.200.0/24           right subnet

A tunnel specification such as:

    conn northnet-southnet
          left=101.101.101.101
          leftnexthop=101.101.101.1
          leftsubnet=192.168.100.0/24
          leftfirewall=yes
          right=202.202.202.202
          rightnexthop=202.202.202.1
          rightsubnet=192.168.200.0/24
          rightfirewall=yes

will allow machines on the two subnets to talk to each other. You might test this by pinging from polarbear (192.168.100.7) to penguin (192.168.200.5).

However, this does not cover other traffic you might want to secure. To handle all the possibilities, you might also want these connection descriptions:

    conn northgate-southnet
          left=101.101.101.101
          leftnexthop=101.101.101.1
          right=202.202.202.202
          rightnexthop=202.202.202.1
          rightsubnet=192.168.200.0/24
          rightfirewall=yes

    conn northnet-southgate
          left=101.101.101.101
          leftnexthop=101.101.101.1
          leftsubnet=192.168.100.0/24
          leftfirewall=yes
          right=202.202.202.202
          rightnexthop=202.202.202.1

Without these, neither gateway can do IPSEC to the remote subnet. There is no IPSEC tunnel or eroute set up for the traffic.

In our example, with the non-routable 192.168.* addresses used, packets would simply be discarded. In a different configuration, with routable addresses for the remote subnet, they would be sent unencrypted since there would be no IPSEC eroute and there would be a normal IP route.

You might also want:

    conn northgate-southgate
          left=101.101.101.101
          leftnexthop=101.101.101.1
          right=202.202.202.202
          rightnexthop=202.202.202.1

This is required if you want the two gateways to speak IPSEC to each other.

This requires a lot of duplication of details. Judicious use of also= and include can reduce this problem.

Note that, while FreeS/WAN supports all four tunnel types, not all implementations do. In particular, some versions of Windows 2000 and the freely downloadable version of PGP provide only "client" functionality. You cannot use them as gateways with a subnet behind them. To get that functionality, you must upgrade to Windows 2000 server or the commercially available PGP products.

#### One tunnel plus advanced routing

It is also possible to use the new routing features in 2.2 and later kernels to avoid most needs for multple tunnels. Here is one mailing list message on the topic:

    Subject: Re: linux-ipsec: IPSec packets not entering tunnel?
       Date: Mon, 20 Nov 2000
       From: Justin Guyett <jfg@sonicity.com>

    On Mon, 20 Nov 2000, Claudia Schmeing wrote:

    > Right                                                         Left
    >                      "home"                "office"
    > 10.92.10.0/24 ---- 24.93.85.110 ========= 216.175.164.91 ---- 10.91.10.24/24
    >
    > I've created all four tunnels, and can ping to test each of them,
    > *except* homegate-officenet.

    I keep wondering why people create all four tunnels.  Why not route
    traffic generated from home to 10.91.10.24/24 out ipsec0 with iproute2?
    And 99% of the time you don't need to access "office" directly, which
    means you can eliminate all but the subnet<->subnet connection.

and FreeS/WAN technical lead Henry Spencer's comment:

    > I keep wondering why people create all four tunnels.  Why not route
    > traffic generated from home to 10.91.10.24/24 out ipsec0 with iproute2?

    This is feasible, given some iproute2 attention to source addresses, but
    it isn't something we've documented yet... (partly because we're still
    making some attempt to support 2.0.xx kernels, which can't do this, but
    mostly because we haven't caught up with it yet).

    > And 99% of the time you don't need to access "office" directly, which
    > means you can eliminate all but the subnet<->subnet connection.

    Correct in principle, but people will keep trying to ping to or from the
    gateways during testing, and sometimes they want to run services on the
    gateway machines too.

### Many tunnels from a single gateway

FreeS/WAN allows a single gateway machine to build tunnels to many others. There may, however, be some problems for large numbers as indicated in this message from the mailing list:

    Subject: Re: Maximum number of ipsec tunnels?
       Date: Tue, 18 Apr 2000
       From: "John S. Denker" <jsd@research.att.com>

    Christopher Ferris wrote:

    >> What are the maximum number ipsec tunnels FreeS/WAN can handle??

    Henry Spencer wrote:

    >There is no particular limit.  Some of the setup procedures currently
    >scale poorly to large numbers of connections, but there are (clumsy)
    >workarounds for that now, and proper fixes are coming.

    1) "Large" numbers means anything over 50 or so.  I routinely run boxes
    with about 200 tunnels.  Once you get more than 50 or so, you need to worry
    about several scalability issues:

    a) You need to put a "-" sign in syslogd.conf, and rotate the logs daily
    not weekly.

    b) Processor load per tunnel is small unless the tunnel is not up, in which
    case a new half-key gets generated every 90 seconds, which can add up if
    you've got a lot of down tunnels.

    c) There's other bits of lore you need when running a large number of
    tunnels.  For instance, systematically keeping the .conf file free of
    conflicts requires tools that aren't shipped with the standard freeswan
    package.

    d) The pluto startup behavior is quadratic.  With 200 tunnels, this eats up
    several minutes at every restart.   I'm told fixes are coming soon.

    2) Other than item (1b), the CPU load depends mainly on the size of the
    pipe attached, not on the number of tunnels.

It is worth noting that item (1b) applies only to repeated attempts to re-key a data connection (IPSEC SA, Phase 2) over an established keying connection (ISAKMP SA, Phase 1). There are two ways to reduce this overhead using settings in ipsec.conf(5):

- set keyingtries to some small value to limit repetitions
- set keylife to a short time so that a failing data connection will be cleaned up when the keying connection is reset.

The overheads for establishing keying connections (ISAKMP SAs, Phase 1) are lower because for these Pluto does not perform expensive operations before receiving a reply from the peer.

### Extruded Subnets

What we call extruded subnets are a special case of VPNs.

If your buddy has some unused IP addresses, in his subnet far off at the other side of the Internet, he can loan them to you... provided that the connection between you and him is fast enough to carry all the traffic between your machines and the rest of the Internet. In effect, he "extrudes" a part of his address space over the network to you, with your Internet traffic appearing to originate from behind his Internet gateway.

Suppose your friend has a.b.c.0/24 and wants to give you a.b.c.240/28. The initial situation is:

        subnet           gateway          Internet
      a.b.c.0/24    a.b.c.1    p.q.r.s

where anything from the Internet destined for any machine in a.b.c.0/24 is routed via p.q.r.s and that gateway knows what to do from there.

Of course it is quite normal for various smaller subnets to exist behind your friend's gateway. For example, your friend's company might have a.b.c.16/28=development, a.b.c.32/28=marketing and so on. The Internet neither knows not cares about this; it just delivers packets to the p.q.r.s and lets the gateway do whatever needs to be done from there.

What we want to do is take a subnet, perhaps a.b.c.240/28, out of your friend's physical location while still having your friend's gateway route to it. As far as the Internet is concerned, you remain behind that gateway.

        subnet           gateway          Internet       your gate  extruded

      a.b.c.0/24   a.b.c.1     p.q.r.s              d.e.f.g         a.b.c.240/28

                               ========== tunnel ==========

The extruded addresses have to be a complete subnet.

In our example, the friend's security gateway is also his Internet gateway, but this is not necessary. As long as all traffic from the Internet to his addresses passes through the Internet gate, the security gate could be a machine behind that. The IG would need to route all traffic for the extruded subnet to the SG, and the SG could handle the rest.

First, configure your subnet using the extruded addresses. Your security gateway's interface to your subnet needs to have an extruded address (possibly using a Linux virtual interface, if it also has to have a different address). Your gateway needs to have a route to the extruded subnet, pointing to that interface. The other machines at your site need to have addresses in that subnet, and default routes pointing to your gateway.

If any of your friend's machines need to talk to the extruded subnet, they need to have a route for the extruded subnet, pointing at his gateway.

Then set up an IPSEC subnet-to-subnet tunnel between your gateway and his, with your subnet specified as the extruded subnet, and his subnet specified as "0.0.0.0/0". Do it with manual keying first for testing, and then with automatic keying for production use.

The tunnel description should be:

    conn extruded
            left=p.q.r.s
            leftsubnet=0.0.0.0/0
            right=d.e.f.g
            rightsubnet=a.b.c.0/28

If either side was doing firewalling for the extruded subnet before the IPSEC connection is set up, ipsec_manual and ipsec_auto need to know about that (via the {left|right}firewall parameters) so that it can be overridden for the duration of the connection.

And it all just works. Your SG routes traffic for 0.0.0.0/0 -- that is, the whole Internet -- through the tunnel to his SG, which then sends it onward as if it came from his subnet. When traffic for the extruded subnet arrives at his SG, it gets sent through the tunnel to your SG, which passes it to the right machine.

Remember that when ipsec_manual or ipsec_auto takes a connection down, it does not undo the route it made for that connection. This lets you take a connection down and bring up a new one, or a modified version of the old one, without having to rebuild the route it uses and without any risk of packets which should use IPSEC accidentally going out in the clear. Because the route always points into KLIPS, the packets will always go there. Because KLIPS temporarily has no idea what to do with them (no eroute for them), they will be discarded.

If you do want to take the route down, this is what the "unroute" operation in manual and auto is for. Just do an unroute after doing the down.

Note that the route for a connection may have replaced an existing non-IPSEC route. Nothing in Linux FreeS/WAN will put that pre-IPSEC route back. If you need it back, you have to create it with the route command.

### Road Warrior with virtual IP address

Here is a mailing list message about another way to configure for road warrior support:

    Subject: Re: linux-ipsec: understanding the vpn
       Date: Thu, 28 Oct 1999 10:43:22 -0400
       From: Irving Reid <irving@nevex.com>

    >  local-------linux------internet------mobile
    >  LAN        box                         user
    >  ...

    >  now when the mobile user connects to the linux box
    >  it is given a virtual IP address, i have configured it to
    >  be in the 10.x.x.x range. mobile user and linux box
    >  have a tunnel between them with these IP addresses.

    >   Uptil this all is fine.

    If it is possible to configure your mobile client software *not* to
    use a virtual IP address, that will make your life easier. It is easier
    to configure FreeS/WAN to use the actual address the mobile user gets
    from its ISP.

    Unfortunately, some Windows clients don't let you choose.

    >  what i would like to know is that how does the mobile
    >  user communicate with other computers on the local
    >  LAN , of course with the vpn ?

    >   what IP address should the local LAN
    >  computers have ? I guess their default gateway
    >  should be the linux box ? and does the linux box need
    >  to be a 2 NIC card box or one is fine.

    As someone else stated, yes, the Linux box would usually be the default
    IP gateway for the local lan.

    However...

    If you mobile user has software that *must* use a virtual IP address,
    the whole picture changes. Nobody has put much effort into getting
    FreeS/WAN to play well in this environment, but here's a sketch of one
    approach:

    Local Lan 1.0.0.0/24
        |
        +- Linux FreeS/WAN 1.0.0.2
        |
        | 1.0.0.1
     Router
        | 2.0.0.1
        |
    Internet
        |
        | 3.0.0.1
    Mobile User
          Virtual Address: 1.0.0.3

    Note that the Local Lan network (1.0.0.x) can be registered, routable
    addresses.

    Now, the Mobile User sets up an IPSec security association with the
    Linux box (1.0.0.2); it should ESP encapsulate all traffic to the
    network 1.0.0.x **EXCEPT** UDP port 500. 500/udp is required for the key
    negotiation, which needs to work outside of the IPSec tunnel.

    On the Linux side, there's a bunch of stuff you need to do by hand (for
    now). FreeS/WAN should correctly handle setting up the IPSec SA and
    routes, but I haven't tested it so this may not work...

    The FreeS/WAN conn should look like:

    conn mobile
            right=1.0.0.2
            rightsubnet=1.0.0.0/24
            rightnexthop=1.0.0.1
            left=0.0.0.0  # The infamous "road warrior"
            leftsubnet=1.0.0.3/32

    Note that the left subnet contains *only* the remote host's virtual
    address.

    Hopefully the routing table on the FreeS/WAN box ends up looking like
    this:

    % netstat -rn
    Kernel IP routing table
    Destination     Gateway      Genmask         Flags   MSS Window  irtt Iface
    1.0.0.0         0.0.0.0      255.255.255.0   U      1500 0          0 eth0
    127.0.0.0       0.0.0.0      255.0.0.0       U      3584 0          0 lo
    0.0.0.0         1.0.0.1      0.0.0.0         UG     1500 0          0 eth0
    1.0.0.3         1.0.0.1      255.255.255.255 UG     1433 0          0 ipsec0

    So, if anybody sends a packet for 1.0.0.3 to the Linux box, it should
    get bundled up and sent through the tunnel. To get the packets for
    1.0.0.3 to the Linux box in the first place, you need to use "proxy
    ARP".

    How this works is: when a host or router on the local Ethernet segment
    wants to send a packet to 1.0.0.3, it sends out an Ethernet level
    broadcast "ARP request". If 1.0.0.3 was on the local LAN, it would
    reply, saying "send IP packets for 1.0.0.3 to my Ethernet address".

    Instead, you need to set up the Linux box so that _it_ answers ARP
    requests for 1.0.0.3, even though that isn't its IP address. That
    convinces everyone else on the lan to send 1.0.0.3 packets to the Linux
    box, where the usual FreeS/WAN processing and routing take over.

    % arp -i eth0 -s 1.0.0.3 -D eth0 pub

    This says, if you see an ARP request on interface eth0 asking for
    1.0.0.3, respond with the Ethernet address of interface eth0.

    Now, as I said at the very beginning, if it is *at all* possible to
    configure your client *not* to use the virtual IP address, you can avoid
    this whole mess.

### Dynamic Network Interfaces

Sometimes you have to cope with a situation where the network interface(s) aren't all there at boot. The common example is notebooks with PCMCIA.

#### Basics

The key issue here is that the config setup section of the /etc/ipsec.conf configuration file lists the connection between ipsecN and hardware interfaces, in the interfaces= variable. At any time when ipsec setup start or ipsec setup restart is run this variable must correspond to the current real situation. More precisely, it must not mention any hardware interfaces which don't currently exist. The difficulty is that an ipsec setup start command is normally run at boot time so interfaces that are not up then are mis-handled.

#### Boot Time

Normally, an ipsec setup start is run at boot time. However, if the hardware situation at boot time is uncertain, one of two things must be done.

- One possibility is simply not to have IPSEC brought up at boot time. To do this:

              chkconfig --level 2345 ipsec off

  That's for modern Red Hats or other Linuxes with chkconfig. Systems which lack this will require fiddling with symlinks in /etc/rc.d/rc?.d or the equivalent.
- Another possibility is to bring IPSEC up with no interfaces, which is less aesthetically satisfying but simpler. Just put

              interfaces=

  in the configuration file. KLIPS and Pluto will be started, but won't do anything.

#### Change Time

When the hardware *is* in place, IPSEC has to be made aware of it. Someday there may be a nice way to do this.

Right now, the way to do it is to fix the /etc/ipsec.conf file appropriately, so interfaces reflects the new situation, and then restart the IPSEC subsystem. This does break any existing IPSEC connections.

If IPSEC wasn't brought up at boot time, do

            ipsec setup start

while if it was, do

            ipsec setup restart

which won't be as quick.

If some of the hardware is to be taken out, before doing that, amend the configuration file so interfaces no longer includes it, and do

            ipsec setup restart

Again, this breaks any existing connections.

### Unencrypted tunnels

Sometimes you might want to create a tunnel without encryption. Often this is a bad idea, even if you have some data which need not be private. See this discussion.

The IPSEC protocols provide two ways to do build such tunnels:

using ESP with null encryption
  not supported by FreeS/WAN
using AH without ESP
  supported for manually keyed connections
  possible with explicit commands via ipsec_whack(8) (see this list message)
  not supported in the ipsec_auto(8) scripts.

One situation in which this comes up is when otherwise some data would be encrypted twice. Alice wants a secure tunnel from her machine to Bob's. Since she's behind one security gateway and he's behind another, part of the tunnel that they build passes through the tunnel that their site admins have built between the gateways. All of Alice and Bob's messages are encrypted twice.

There are several ways to handle this.

- Just accept the overhead of double encryption. The site admins might choose this if any of the following apply:
  - policy says encrypt everything (usually, it should)
  - they don't entirely trust Alice and Bob (usually, if they don't have to, they shouldn't)
  - if they don't feel the saved cycles are worth the time they'd need to build a non-encrypted tunnel for Alice and Bob's packets (often, they aren't)
- Use a plain IP-in-IP tunnel. These are not well documented. A good starting point is in the Linux kernel source tree, in /usr/src/linux/drivers/net/README.tunnel.
- Use a manually-keyed AH-only tunnel.

Note that if Alice and Bob want end-to-end security, they must build a tunnel end-to-end between their machines or use some other end-to-end tool such as PGP or SSL that suits their data. The only question is whether the admins build some special unencrypted tunnel for those already-encrypted packets.