An IPsec tunnel implementation for Linux 2.4

by Tobias Ringström <tobias@ringstrom.mine.nu>

Contents

• News
• Goals
• Background
• Mailing lists
  
• Download
• Documentation
• Interoperability
  
• TODO
  

News

Goals

Perhaps it's best to start with what ipsec_tunnel is not, which is a complete IPsec implementation. It will only give you IPsec tunnels, which is the perfect way to provide secure communication between private networks over the Internet. The main goals are:

• To provide an easy to use RFC compliant IPsec tunnel implementation, with
• Simple, intuitive, manual keying.
• Normal (i.e. sane) routing.
• Good documentation.
  
• To not requre kernel source code patching.

Background

I started this project because I was using a number of IPIP tunnels to create a VPN by connecting private networks over the Internet, but I needed encryption for a few resons. Above all I wanted to be able to use standard protocols such as FTP and NFS without having to worry about cleartext passwords and snooping.

I knew that I needed IPsec, and the only free implementation under active development for Linux was FreeSWAN. My first impression was that it was hard to understand and hard to configure, especially for the simple case of manually configured tunnels with fixed keys. Routing was also strange. I wanted something resembling the standard IPIP tunnel, and when I could not find it, I decided to print the IPsec RFCs and start read. It did not take long before I started coding.

I decided to use the CryptoAPI patches for the encryption/decryption algorithms, which really gave me a head start on the hard stuff. Since I often switch kernels, I find it inconvenient to have to patch the kernel, so the recommended installation procedure lets you build and install CryptoAPI and ipsec_tunnel using only kernel modules, and no kernel patching.

Mailing lists

There are two mailing lists. Subscribe to the ipsec_tunnel-announce list to get information on new releases and security information. There are two ways to join the list. The first one is to use the web interface, and the other is to send an email to ipsec_tunnel-announce-request@ringstrom.mine.nu with the word help or subscribe in the body of the email.

Subscribe to the ipsec_tunnel list to discuss anything related to ipsec_tunnel. There are two ways to join this list as well. Eith use the web interface, or send an email to ipsec_tunnel-request@ringstrom.mine.nu with the word help or subscribe in the body of the email. Due to a slight spam problem, this list is currently moderated.

Download

The ipsec_tunnel package is designed for and has been tested on Linux 2.4.x, where x is 18 or greater. It may or may not work on older kernels.

The latest (and greatest) version of ipsec_tunnel is 0.9, which you can find it on the download page. The installation instructions are included in the file INSTALL in the package. For version information, see the NEWS file which is also included in the package.

Please send me an email and let me know if it works (or doesn't work) for you! If you have a problem or a question, you can also send an email to the mailing list at ipsec_tunnel@ringstrom.mine.nu.

Documentation

The IPsec tunnel implementation is divided into two parts, one kernel module called ipsec_tunnel.o, and a tool to administrate security associations and tunnels, called ipsecadm.

Start by loading the kernel module into the Linux kernel. This is done using modprobe or insmod. After the modules has been inserted, you get a new inactive network device called ipsec0 which can be seen if you run ifconfig -a.

The ipsecadm tool has a built-in brief help which is displayed if you execute it without paramters, or with unknown or invalid parameters. The tool has three main modes. The first mode is for adding and removing security associations (SAs), the second is for adding, modifying and removing tunnels, and the third mode is for displaying statistics. Before we start, we need an example scenario. Let's say that we are going to create a tunnel between the two hosts A and B. The public IP number of host A is 1.2.3.4 and it's private IP address is is 10.0.1.0/24.

IPsec uses Security Associations (SA), which is another name for a security agreement between two hosts. The SA is uniquely described by two IP addresses and a 32-bit number number called a SPI. The SPI allows more than one SA between a pair of hosts. When the SA was agreed upon, the two parties agreed upon the type of the SA which can basically be encryption and/or authorization, but also the algorithms, key sizes and keys to be used. It's time for an example. This is an SA in (more or less) plain English:

Before we can create an SA, we need a key. One way to create a key is to use /dev/random. To create a 192-bit key (which corresponds to 24 bytes) and put it in the file /etc/ipsec/ipsec.key run the following:

mkdir /etc/ipsec
chmod 500 /etc/ipsec
dd if=/dev/random of=/etc/ipsec/example.key bs=24 count=1

Now we can use ipsecadm to create the SA above. The name of the cipher is specified using its CryptoAPI name, which can be a little strange. The name for tripple DES is 3des-cbc. You can see which ciphers you have installed by looking in the directory /proc/crypto/cipher/.

ipsecadm sa add --spi=0x1000 --dst=5.6.7.8 --src=1.2.3.4 \
         --cipher=3des-cbc --cipher-keyfile=/etc/ipsec/example.key \
         --duplex

Simple, isn't it? Wondering about the --duplex parameter? To create tunnel you need two SAs, one in each direction. Since it is common to use the same security settings for both directions you can create a pair of SAs in one go by using --duplex. Note that it is safer to supply the key as a file (using --cipher-keyfile) than to specify it on the command line (using --cipher-key) since it is easy for a local user to find out the key using w or ps. To look at the two SAs you just created, run the following:

ipsecadm sa show

Note that the SAs can be used for all IPsec traffic, and not only for tunnels, but right now only tunnels are implemented. Also make sure you add the SAs on both hosts. The next step is to create the tunnels. I will show the commands needed for host A, and leave the commands for host B as a simple excercise. Run the following:

ipsecadm tunnel add ipsec1 --local=1.2.3.4 --remote=5.6.7.8

As you can see there is no need to specify the SPI. You can do that if you want to using the --spi option, but if unspecified, the local and remote addresses will be used to find a suitable SA. Now we need to set an IP number on the newly created tunnel device, but what should it be? When a packet is created on a machine, the destination address is used by the routing table to find the outgoing device for the connection, and the source address is set to the address of the device. (This is a bit simplified, but enough for us now.) If you initiate a connection from host A to an address on the private network at host B, you probably want the source address of your packets to be the private address of host A, which is 10.0.1.1:

ifconfig ipsec1 10.0.1.1 up

The last step is to create an entry in the routing table that makes the packets to the private network at host B go out via the ipsec1 device:

route add -net 10.0.2.0/24 dev ipsec1

That's it! Do the equivalent thing on host B and you should be all set! Nothe that you should not generate a new key on host B, but copy the one you made for host A to host B. Make sure that you copy the key in a secure manner, e.g. using ssh/scp.

Interoperability

In this section, you can find information on how to use ipsec_tunnel with other IPsec implementations. I will add more systems as soon as I have the information on how to configure them. If you manage to use ipsec_tunnel with a system not mentioned here, please send me information on how to configure it and I will add the information here.

1. FreeS/WAN - An IPsec implementaion for Linux. (Information provided by Andreas Hansson)
2. OpenBSD
3. WatchGuard Firebox (Information provided by Erik Morén)
   

TODO

• Nothing is on my list at the moment.