Linux FreeS/WAN Setup

Setting up a secure tunnel to create a VPN

This document describes setting up a VPN (Virtual Private Network) using Linux FreeS/WAN (Secure Wide Area Network). Information on configuration options once the basic setup is done is in a separate Configuration document.

The problem we are trying to solve is that of letting two networks communicate securely when the only connection between them is over a third network which they do not trust.

The solution is to put a security gateway machine between each of the communicating networks and the untrusted network. The gateway machines encrypt packets entering the untrusted net and decrypt packets leaving it, creating a secure tunnel through it.

The result is called a VPN, a Virtual Private Network. If the cryptography is strong, the implementation careful, and the administration of the gateways competent, then one can reasonably place considerable confidence in the security of the tunnel. The two networks then behave like a large private network, some of whose links are encrypted tunnels through untrusted nets.

Actual VPNs are often more complex. One organisation may have fifty branch offices, plus some suppliers and clients, with whom it needs to communicate securely. Another might have 5,000 stores, or 50,000 point-of-sale devices. Many VPNs need to handle travelling users, the "road warrior" connecting to home base from a laptop machine.

The untrusted network need not be the Internet. All the same issues arise on a corporate or institutional network whenever two departments want to communicate privately with each other.

Our example network

For our example, we assume that there are only three networks involved, two that want to talk to each other plus the Internet in the role of the third, untrusted, net. Once you have this working between two network gateways, extending it to three or more is straightforward.

We also assume here that all machines involved have known, fixed IP addresses. See our Configuration document for some information on supporting "road warriors".

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

Installation steps

    Before starting the install

  1. Configure, compile, install, test and back up Linux kernels on both gateways, without FreeS/WAN.

    Development work is currently done using a Red Hat 5.2 distribution and kernel version 2.0.36 on Intel architecture machines. We recommend those Linux versions for a simple install. For information on other versions and other CPU architectures see our Implementation Notes file and our Compatibility document.

    There are many sources on the net for Linux kernels. Use your favourite if you have one, or go to Red Hat's list of mirror sites and chose a mirror that is close to you. Using a Red Hat kernel may save you some annoyance later. Different distributions put the kernel in different places (/vmlinuz, /boot/vmlinuz, ...) and set lilo (the Linux loader) up differently. With a Red Hat kernel on a Red Hat distribution, everything works right. With other combinations, a newly compiled kernel may be installed in one place while lilo is looking in another. You can of course adjust makefiles and/or lilo to solve this problem, but we suggest just avoiding it.

    You need to configure the gateway kernels because some of our utilities rely on the results of configuration.

    You should compile, install and test the kernels as you have configured them, so that you have a known stable starting point. Then if there is a problem after you add FreeS/WAN, tracking it down is much simpler.

    If you need advice on this process, or general Linux background information, try our list of Linux web references. The most directly relevant document is the Kernel HOWTO. We also provide a file of notes on kernel installation.

  2. Configure and test IP networking on both gateways and on at least one client machine behind each of them. If you need advice on this, your best sources are likely the Net-3 Networking Howto and the Network Administrator's Guide.

    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.

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

    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.

    Building the software

  3. Did you do the steps listed above? If not, go back and do them now.

  4. Build and install FreeS/WAN per the INSTALL file (found in the top level directory of the distribution) on both gateways.

    This installs various programs, man pages, and configuration files. It also adds FreeS/WAN code to the kernel, then re-compiles and re-configures the kernel to activate that code.

    NOTE:
    When you get to the step using make menuconfig to check configuration after adding the FreeS/WAN patches to your kernel, save the new configuration even if you make no changes. This ensures that the FreeS/WAN changes are actually seen by the system.

    The ipsec.conf(5) configuration file

  5. Pick one machine on which you will edit the two files:

    • /etc/ipsec.conf -- configuration of ipsec connections
    • /etc/ipsec.secrets -- secrets shared with other machines

    Note that these edits must be done securely if you are to have any confidence in your IPSEC security. If someone can get the contents of these files, for example by looking at your screen as you work or by intercepting packets between your X desktop and the gateway machine, then they can easily bypass IPSEC. You need to edit these two files to configure at least one IPSEC connection.

    As with most things on any Unix-like system, most parts of Linux FreeS/WAN are documented in online manual pages. We provide an HTML list of FreeS/WAN man pages. The /etc/ipsec.conf file is documented in the ipsec.conf(5) man page so your next command should be:

    	man 5 ipsec.conf
    
    You may also want to look at manual pages for ipsec_manual(8) and ipsec_auto(8) which document the two types of connections you will set up here, and at our example configurations file.

    We currently support two types of connections, started with commands such as:

    	ipsec manual --start name
    	ipsec auto --start name
    
    The difference is in how they are keyed.
    Manually keyed connections
    use keys stored in /etc/ipsec.conf.
    Automatically keyed connections
    use keys automatically generated by the Pluto key negotiation daemon.

    Here we will set up a connection for both manual mode (useful for testing) and automatic mode (more secure, used in production). The steps involved are:

    Editing connections in /etc/ipsec.conf

  6. The easiest way to create a connection is by editing one of our examples, either the one in the /etc/ipsec.conf file or one from our doc/examples file.

    Choose an example connection similar to what you want to do, e.g. the subnet tunnel example if you have routable IP addresses for the client systems or the masqueraded tunnel example if not. Copy that example and 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" and to define another connection you make a copy with a new name such as:
    	conn reno-van
    

    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.
    leftnexthop
    Where left should send packets whose destination is right, typically the first router in the appropriate direction.
    leftsubnet
    Addresses for client machines left is protecting.
    • Often something like 202.303.404.0/24 to indicate that a subnet resides behind left. This gives a tunnel mode connection.
    • If you omit this parameter (or set it to left's address and add a /32 netmask), then left is both the security gateway and the only client on that end.
    leftfirewall
    Set to "yes" if the subnet behind left uses non-routable addresses and left does IP masquerade for them.
    There are corresponding right* parameters of course.

    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.

    In general, 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.

    The "nexthop" parameters are not needed if the two gateways are directly connected to each other. Otherwise they are the addresses of the next network gateways on both ends. For example, if the network is like this:

    Sunset======West------Westgate........Eastgate-------East======Sunrise

    and West is "left", then leftnexthop=Westgate and rightnexthop=Eastgate.

    Creating keys with ranbits

    Notice that at this point you may have two connections with identical keys, the one you copied and the one you just created. This creates a potential security hole. If you ever use the duplicate keys on two different connections, then either of the remote admins can read traffic destined for the other's system. Delete one copy of the key material now to avoid any risk of inadvertently doing that.

    The keys currently in the file were supplied by the installation process and are moderately random. These can be used for testing, but should be changed before any data of real value is sent.

    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:

    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.

    Putting secrets in /etc/ipsec.secrets

    This file stores the secrets used to authenticate communication for the Diffie-Hellman key exchange in the IKE protocol.

    Each line has the IP addresses of the two gateways plus the secret. For details, see the ipsec.secrets(5) man page. 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 has supplied a fairly random secret. Again, fine for testing, but you should change it for production use. To create a new secret, use:

          umask 177
          ipsec ranbits 256  > temp
    
    Remember to delete the temporary file.
  7. Copy the two files:

    to the other gateway machine by some secure means.

    Don't just FTP or mail these files! It is vital that the keys in /etc/ipsec.conf and the secrets in /etc/ipsec.secrets remain secret. An attacker who knew those could easily have all the data on your "secure" connection. Carry the files on a floppy, and lock the floppy in a good safe or erase it extremely thoroughly afterward. Or use PGP or SSH to make the transfer.

    Note also that those files should be owned by root, and have permissions rw-------.

    Setting up interfaces

  8. For now, these files don't have to be changed much. They can be identical on the two gateways except that each gateway must have the correct interfaces setting in its copy of /etc/ipsec.conf. This is in the file section labelled by the line config setup.

    interfaces
    Tells the KLIPS IPSEC code in the Linux kernel which interface to use
    For example
    interfaces="ipsec0=eth0"
    tells KLIPS to use eth0 as ipsec0
    This should be the interface through which this gateway machine communicates with the other gateway. If this is not correct, nothing works.

    If you need to discover which interface it is, use the command:

    	ifconfig
    
    If you have PCMCIA or other interfaces that are not available at boot time, special measures are required. See our Configuration document.

    For now, all you need to do in the overall config setup section of the file is set interfaces. We cover other options in our Configuration document. When you go to three or more gateways, however, you should ensure that distribution of keys and secrets is kept to a minimum. If Reno, Vancouver and Munich offices all communicate, there is no reason to give Reno keys to the Vancouver-Munich tunnel, for example.

    Matching numbers

    It is important that the numbers here match the network configuration. 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. It then sets itself up with the other left* parameters

    leftnexthop
    The next hop on the path from left to right. In many applications this will be a router at left's ISP. For an IPSEC gateway to a departmental LAN, the next hop might be a router on the corporate LAN.
    leftsubnet
    Subnet address for clients behind left, with netmask. Often something like:
    	leftsubnet=192.168.3.0/24
    
    This can be ommitted if there is no subnet, if left is acting as its own gateway.
    leftfirewall
    Set to yes if left is masquerading for its clients.
    Once it has these parameters, FreeS/WAN sets things so that All should be well.

    Of course, there must also be an interface and routes set up so that this machine can exchange non-IPSEC packets 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 problem reporting file to get help interpreting them if required.

    We recommend double-checking for consistency here before continuing.

    Testing the installation

  9. Reboot both gateways to get FreeS/WAN started. No connections are actually made yet, but the stage is set.

    Examine /var/log/messages for any signs of trouble.

    On both gateways, the following entries should now exist in the /proc/net/ directory:

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

    	cat /proc/net/ipsec_tncfg
    

    You should see at least device ipsec0. 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.

    Minor confusion sometimes arises when people find that /dev/ipsec0, and /dev/ipsec1 are not visible with 'ls'. This is as it should be. 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.

    Manually keyed test

    The initial tests should be done with manually keyed connections. This lets you test the lower-level parts of Linux FreeS/WAN (mainly the KLIPS code which you've added to your kernel) while bypassing the higher-level parts. We will get to those once we're sure the low level works right.

  10. On one gateway, start IPSEC with:

    	ipsec manual --up name
    
    replacing name with the connection name you used in /etc/ipsec.conf.

    If it 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 through an IPSEC tunnel to the gateway 11.0.0.1.

  11. A manual connection must be set up on both ends to work. So give the same commands:
    	ipsec manual --up name
    	ipsec look
    

    on the other gateway and look for similar results.

  12. If that works, test whether Sunrise can ping Sunset and vice versa. It is not enough to just test that East can ping West; the goal is to secure traffic between the subnets, not between the security gateways themselves.

    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 West
    
    where the interface specified (eth0 in the example) is the protected subnet side of East, not the interface to the Internet through which packets to West would normally be routed. This forces the packets through the IPSEC tunnel you want to test. Without the "-i eth0" they might just take a default unencrypted route to West.

    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

  13. To verify that all is working, run tcpdump(8) on a machine which can listen to the traffic between the gateways.

    This really has to be done from a third machine, not from one of the gateways. On the gateways you'll see packets at intermediate stages of processing and the result will be confusing. Also, both tcpdump(8) and nmap(8) use the libpcap library. That library does not recognise ipsec? devices and will generate "bad physical medium" error messages if you try to use it with them.

    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.

    Testing Automatic connections

  14. Do
    	ipsec manual --down name
    
    on both gateways. This shuts down the named tunnel. You can verify with the same commands used to check it was up:
    	ps -ax
    	ipsec look
    

  15. Now, do
    	ipsec auto --add name
    
    on both gateway machines. Then do:
    	ipsec auto --up name
    
    on one gateway. The first command adds the information on this connection to Pluto's database. The second makes the connection active.

    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.

    For information on configuring the system for production use, see our Configuration document.


Click below to go to: