You also need to create a TXT record, to let others know that this machine can receive opportunistic connections. It also lets them know that the machine is authorized to encrypt on its own behalf.

Use the command:

     ipsec showhostkey --txt 1.2.3.4

where you replace 1.2.3.4 with your public IP.

The record (with key shortened) looks like this:

        ; RSA 2048 bits  xy.example.com   Sat Apr 15 13:53:22 2000
        IN TXT  "X-IPsec-Server(10)=1.2.3.4 AQOF8tZ2...+buFuFn/"

Send both records to your ISP, to be published in your IP's reverse map.

Firewalling incoming opportunistic connections

There is a particular security concern when you allow incoming opportunism.

Incoming opportunistic packets enter your machine via an IPSec tunnel. That is, they all appear as ESP (protocol 50) packets, concealing whatever port and protocol characteristics the packet within the tunnel has. Contained in the tunnel as they pass through ppp0 or eth0, these packets can bypass your usual firewall rules on these interfaces.

Since you will be exchanging opportunistic packets with peers who are not familiar to you, you will want to firewall your ipsec interfaces the way you would any publicly accessible interface.

A simple way to do this is to create one iptables(8) table with all your filtering rules for incoming packets, and apply the entire table to all public interfaces, including ipsec interfaces.

An opportunistic gateway

Next we expand from a standalone system (which protects only its own traffic) to a gateway (which protects traffic for other systems).

There is one special case in which gateway configuration is quite simple -- if all the machines behind the gateway are hidden from the Internet. We describe that first, then go on to describe gateways for visible clients.

NAT for hidden clients

If your gateway uses NAT to allow machines to access the Internet without having their own routable IP addresses, then from the point of view of anyone else on the Internet:

• the systems behind the gateway are completely hidden
• only one machine with one IP address is visible
• the gateway appears to be a standalone system

For purposes of IPsec across the Internet, your gateway can be treated as a standalone machine. Consequently,

• your ipsec.conf(5) file needs no changes to support the NAT. It can be identical to what you would use on a standalone system -- either initiate-only or with incoming connection support -- as shown above.
• the firewall rules for your Internet interface can be identical to those for a standalone system, as above
• the only thing you must change are the firewall rules that control forwarding to the NAT network

For a more detailed discussion of NAT, see our background section.

Gateway for visible clients

Many gateways will need to support client systems that have routable addresses and are thus visible to the Internet. To equip such a gateway with opportunistic encryption, you'll need a co-operative ISP that will allow you to insert resource records into reverse DNS.

Setup for a gateway involves:

• adding a connection description in ipsec.conf(5)
• adding a DNS record for each client, pointing to its FreeS/WAN gateway.

ipsec.conf(5) for an opportunistic gateway

You need only make a few additions to in the ipsec.conf(5) file:

• keep the connection description for the gateway itself
• add another one for its clients
• in that connection, specify the clients in a leftsubnet= line

In ipsec.conf(5), a new conn is needed for each local subnet to be protected by opportunistic encryption. If you are also protecting the gateway, most of the new conn can be borrowed from the old one. Place this before me-to-anyone:

conn subnet-to-anyone
       also=me-to-anyone
       leftsubnet=42.42.42.0/24

Note that a subnet described in ipsec.conf(5) need not correspond to a physical network segment. This is discussed in more detail in our advanced configuration document.

If required, a gateway can easily provide this service for more than one subnet. You just add a connection description for each.

DNS entries for an opportunistic gateway

We assume you already have a KEY record in the reverse map for your gateway's public IP address, so your gateway can accept incoming connections. This is described above.

For the gateway to provide an opportunistic encryption service for other systems, it must be possible for the initiator of an IPsec connection to:

• discover the gateway's address, knowing only the IP address that packets are bound for
• verify that the gateway is authorised to encrypt for that endpoint

This is done by adding a TXT record to the reverse map for the endpoint. The record (with key shortened) looks like this:

        ; RSA 2048 bits  gateway.example.com   Sat Apr 15 13:53:22 2000
        IN TXT  "X-IPsec-Server(10)=1.2.3.4 AQOF8tZ2...+buFuFn/"

This record must be generated on the gateway so it can get the key from ipsec.secrets(5). The command is:

     ipsec showhostkey --txt 1.2.3.4

You must supply the gateway IP address on the command line.

One of these records is required in the reverse map for each system using this gateway for opportunistic IPsec. You insert it in the reverse map part of the zone file right after the line for that system's IP address, so part of the file might look like this:

      1.42.42.42.in-addr.arpa. IN PTR arthur.example.com 
        ; RSA 2048 bits  gateway.example.com   Sat Apr 15 13:53:22 2000
        IN TXT  "X-IPsec-Server(10)=1.2.3.4 AQOF8tZ2...+buFuFn/"
      2.42.42.42.in-addr.arpa. IN PTR ford.example.com 
        ; RSA 2048 bits  gateway.example.com   Sat Apr 15 13:53:22 2000
        IN TXT  "X-IPsec-Server(10)=1.2.3.4 AQOF8tZ2...+buFuFn/"
      3.42.42.42.in-addr.arpa. IN PTR trillian.example.com 
        ; RSA 2048 bits  gateway.example.com   Sat Apr 15 13:53:22 2000
        IN TXT  "X-IPsec-Server(10)=1.2.3.4 AQOF8tZ2...+buFuFn/"

You need one TXT record per client, but the TXT records can all be identical.

Pre-configured connections

Some circumstances call for pre-configured IPSec connections, also known as VPNs (Virtual Private Networks). In particular, when you need strong authentication, ie. to access an office network, VPN is your best current choice. This may change when secure DNS arrives, since secure DNS will strengthen the authentication system for opportunistic encryption.

Below are instructions for pre-configuring:

• "Road warrior" remote access
• Network-to-network configuration

as well as tips on:

• what to look at next

"Road warrior" remote access

A common requirement is for pre-configured connections between a specific network and some set of remote machines. For example, an office network will often need to provide remote access services for:

• employees' or contractors' home offices (standalone machine or firewall plus client machines)
• travelling employees

We refer to the remote machines as "road warriors". For purposes of IPsec, anyone with a dynamic IP address is a road warrior.

Of course, if both the warrior and the gateway at the office are set up for opportunistic encryption, then you may not need the pre-configured connection. Here we assume that you do need it. For example:

• a corporate security policy might require explicitly-configured connections for some applications
• either end might be using a product which does not yet support opportunistic encryption

This section has three sub-sections:

• exchanging the information required to build explicitly configured connections
• setup on the "road warrior" end
• setup on the gateway end

On either end, the opportunistic setup is unaffected by this. You leave it in place so both systems can continue to do opportunistic encryption with everyone but each other.

Information exchange

To set up an explicitly configured connection, you need some information about the system on the other end.

Connection descriptions use left and right to designate the two ends. We adopt the convention that, from the gateway's point of view left=local and right =remote.

The gateway administrator needs to know some things about each road warrior:

• the system's public key
• the ID that system uses in IPsec negotiation

To get this information, in a format suitable for insertion directly into the gateway's ipsec.conf(5) file, issue this command on the warrior machine:

        ipsec showhostkey --right

The output should look like this (with the key shortened for easy reading):

        rightid=@xy.example.com
        rightrsasigkey=0s1LgR7/oUM...

The road warrior needs to know:

• the gateway's public key
• the ID the gateway uses in IPsec negotiation

which can be generated by running ipsec showhostkey --left on the gateway. Each warrior must also know:

• the IP address of the gateway
• the subnet to which an IPsec tunnel provides access

This information should be provided in a convenient format, ready for insertion in the warrior's ipsec.conf(5) file. For example:

        left=1.2.3.4
        leftsubnet=42.42.42.0/24
        leftid=@gateway.example.com
        leftrsasigkey=0s1LgR7/oUM...

The gateway administrator typically needs to generate this only once. The same file can be given to all warriors.

Of course it is also possible to provide different versions, with access to different subnets, to different groups of warriors. See our advanced configuration document.

Setup on the road warrior machine

To set up a road warrior machine, we start from the opportunistic initiator setup shown above.

Simply add a connection description us-to-office, with the left and right information you gathered above. This might look like:

# pre-configured link to office network
conn us-to-office
        # information obtained from office system admin
        left=1.2.3.4                # gateway IP address
        leftsubnet=42.42.42.0/24   # the office network
        leftid=@gateway.example.com
        # real keys are much longer than shown here
        leftrsasigkey=0s1LgR7/oUM...
        # our stuff, same when we are opportunistic initiator
        right=%defaultroute
        rightid=@xy.example.com

Here's more detail on this configuration.

We could easily add more connections as required, perhaps one each for his office, her office, the kid's school,... The file would grow longer, but nothing already in the file would need to change.

Once you have a number of connections, you may like to make your ipsec.conf modular, to save typing. See these instructions.

Road warrior support on an office gateway

Adding road warrior support so people can connect remotely to your office network is straightforward.

We start from the opportunistic gateway setup shown above.

Putting connection descriptions in separate files

You could put a complete connection description for each warrior in your ipsec.conf(5) file, but this makes for a rather unmanageable file if you have many warriors.

Instead, we suggest you give each warrior its own file, choosing some directory and naming convention that suits your system and style.

For this example, we use the directory /etc/ipsec.road and use filenames based on IPsec ID, so the warrior using ID xy.example.com gets a file named xy.conf.

Using such files, you need add only one line to ipsec.conf(5). With our naming convention, the line is:

      include /etc/ipsec.road/*.conf

FreeS/WAN will then read all those files and behave as if they were part of the ipsec.conf(5) file.

We suggest you make your ipsec.conf modular, so that each file does not need to include information for the gateway side. Create a separate connection conn gate_stuff , containing this common information. For example:

conn gate_stuff
        left=1.2.3.4
        leftsubnet=42.42.42.0/24
        leftid=@gateway.example.com
        leftrsasigkey=0s1LgR7/oUM...

You will reference this in each road warrior connection.

Your include line needs to be before conn gate_stuff . A convenient place for the line is right after the conn %default section.

Each of the road warrior files then contains a connection description for that warrior. For example:

# connection description for road warrior "xy"
conn gate-xy
        # use the gateway description in ipsec.conf(5)
        also=gate_stuff
        # allow connection attempt from any address
        # attempt fails if caller cannot authenticate
        right=%any
        # authentication information
        rightid=@xy.example.com
        rightrsasigkey=0s1LgR7/oUM...

With this technique, it becomes fairly simple to administer a gateway that supports many road warriors. For example:

To add a new user, simply add a suitable file.

To disable an account -- for example if a key is compromised -- take any existing connection down and delete it from Pluto's internal database with:

        ipsec auto --delete connection

and remove or correct the affected file.

If you have many users, it would be worthwhile to write scripts to automate such tasks.

Network-to-network VPN

Often it is useful to have explicitly configured IPsec tunnels between different offices of an organisation, or between organisations that have joint projects.

Of course, if both offices are set up for opportunistic encryption and the security policies in place allow you to use that, explicitly configured tunnels become unnecessary. However, this will not always be the case.

Gateway setup for net-to-net

Adding up a network-to-network tunnel does not require any change to the opportunistic or road warrior parts of your ipsec.conf(5). You can keep those parts exactly as shown above.

Of course, a network-to-network tunnel requires its own connection description, so you have to add that. There are two ways to do this.

identical connection description on the two ends

needs to specify more detail so the machine can figure out which end it is on

slightly different descriptions on the two ends

needs less detail, but you need to manage two descriptions

Choose whichever is more convenient to administer in your environment.

A connection description that works on either end

Here is a network-to-network tunnel description from our examples file:

# 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

If you give an explicit IP address for left (and left and right are not directly connected), then you must specify leftnexthop (the router which left sends packets to in order to get them delivered to right). Similarly, you may need to specify rightnexthop (vice versa).

The *nexthop parameters are needed because of an unfortunate interaction between FreeS/WAN and the kernel routing code. They will be eliminated in a future release, but perhaps not soon. We know they should go, but getting them out is not a simple problem.

This description can be generated on either machine and simply inserted in the ipsec.conf(5) file on the other. No change is required or desired.

Using slightly different descriptions

Provided both machines do IPsec over the interface that is their default route to the Internet (a common case, but by no means the only one) you can simplify the description somewhat.

When using left=%defaultroute, you do not need to specify leftnexthop. left does not need to know rightnexthop either, so on left the connection description can be:

conn sample
        # left security gateway (public-network address)
        left=%defaultroute
        # subnet behind left (omit if there is no subnet)
        leftsubnet=172.16.0.0/24
        # right s.g., subnet behind it
        right=10.12.12.1
        rightsubnet=192.168.0.0/24
        auto=start

On right it is:

conn sample
        # left security gateway (public-network address)
        left=10.0.0.1
        # subnet behind left (omit if there is no subnet)
        leftsubnet=172.16.0.0/24
        # right s.g., subnet behind it
        right=%defaultroute
        rightsubnet=192.168.0.0/24
        auto=start

What next?

At this point, we have covered setup for opportunistic encryption and for simple cases of road warrior and VPN connections. You have several choices for what to look at next:

• more advanced configuration
• FreeS/WAN and firewalls
• more detail on the IPsec protocols

FreeS/WAN quick start on firewalling

This firewalling information supplements our quickstart guide.

It includes tips for firewalling:

• a standalone system with initiator-only opportunism
• incoming opportunistic connections
• an opportunistic gateway

and a list of helpful resources.

Firewalling a standalone system

Firewall rules on a standalone system doing IPsec can be very simple.

The first step is to allow IPsec packets (IKE on UDP port 500 plus ESP, protocol 50) in and out of your gateway. A script to set up iptables(8) rules for this is:

# edit this line to match the interface you use as default route
# ppp0 is correct for many modem, DSL or cable connections
# but perhaps not for you
world=ppp0
#
# allow IPsec
#
# IKE negotiations
iptables -A INPUT  -p udp -i $world --sport 500 --dport 500 -j ACCEPT
iptables -A OUTPUT -p udp -o $world --sport 500 --dport 500 -j ACCEPT
# ESP encryption and authentication
iptables -A INPUT  -p 50 -i $world -j ACCEPT
iptables -A OUTPUT -p 50 -o $world -j ACCEPT

Optionally, you could restrict this, allowing these packets only to and from a list of known gateways.

A second firewalling step -- access controls built into the IPsec protocols -- is automatically applied:

Pluto -- the FreeS/WAN keying daemon -- deals with the IKE packets.

Pluto authenticates its partners during the IKE negotiation, and drops negotiation if authentication fails.

KLIPS -- the FreeS/WAN kernel component -- handles the ESP packets.

KLIPS drops outgoing packets

if they are routed to IPsec, but no tunnel has been negotiated for them

KLIPS drops incoming unencrypted packets

if source and destination addresses match a tunnel; the packets should have been encrypted

KLIPS drops incoming encrypted packets

if source and destination address do not match the negotiated parameters of the tunnel that delivers them

if packet-level authentication fails

These errors are logged. See our troubleshooting document for details.

As an optional third step, you may wish to filter packets emerging from your opportunistic tunnels. These packets arrive on an interface such as ipsec0, rather than eth0, ppp0 or whatever. For example, in an iptables(8) rule set, you would use:

-i ipsec+

to specify packets arriving on any ipsec device

-o ipsec+

to specify packets leaving via any ipsec device

In this way, you can apply whatever additional filtering you like to these packets.

The packets emerging on ipsec0 are likely to be things that a client application on your machine requested: web pages, e-mail, file transfers and so on. However, any time you initiate an opportunistic connection, you open a two-way connection to another machine (or network). It is conceivable that a Bad Guy there could take advantage of your link.

For more information, read the next section.

Firewalling incoming opportunistic connections

The basic firewalling for IPsec does not change when you support incoming connections as well as connections you initiate. You must still allow IKE (UDP port 500) and ESP (protocol 50) packets to and from your machine, as in the rules given above.

However, there is an additional security concern when you allow incoming opportunistic connections. Incoming opportunistic packets enter your machine via an IPSec tunnel. That is, they all appear as ESP (protocol 50) packets, concealing whatever port and protocol characteristics the packet within the tunnel has. Contained in the tunnel as they pass through ppp0 or eth0, these packets can bypass your usual firewall rules on these interfaces.

Consequently, you will want to firewall your ipsec interfaces the way you would any publicly accessible interface.

A simple way to do this is to create one iptables(8) table with all your filtering rules for incoming packets, and apply the entire table to all public interfaces, including ipsec interfaces.

Firewalling for opportunistic gateways

On a gateway, the IPsec-related firewall rules applied for input and output on the Internet side are exactly as shown above. A gateway exchanges exactly the same things -- UDP 500 packets and IPsec packets -- with other gateways that a standalone system does, so it can use exactly the same firewall rules as a standalone system would.

However, on a gateway there are additional things to do:

• you have other interfaces and need rules for them
• packets emerging from ipsec processing must be correctly forwarded

You need additional rules to handle these things. For example, adding some rules to the set shown above we get:

# edit this line to match the interface you use as default route
# ppp0 is correct for many modem, DSL or cable connections
# but perhaps not for you
world=ppp0
#
# edit these lines to describe your internal subnet and interface
localnet=42.42.42.0/24
internal=eth1
#
# allow IPsec
#
# IKE negotiations
iptables -A INPUT  -p udp -i $world --sport 500 --dport 500 -j ACCEPT
iptables -A OUTPUT -p udp -o $world --sport 500 --dport 500 -j ACCEPT
# ESP encryption and authentication
iptables -A INPUT  -p 50 -i $world -j ACCEPT
iptables -A OUTPUT -p 50 -o $world -j ACCEPT
#
# packet forwarding for an IPsec gateway
# simplest possible rules
$ forward everything, with no attempt to filter
#
# handle packets emerging from IPsec
# ipsec+ means any of ipsec0, ipsec1, ...
iptables -A FORWARD -d $localnet -i ipsec+ -j ACCEPT
# simple rule for outbound packets
# let local net send anything
# IPsec will encrypt some of it
iptables -A FORWARD -s $localnet -i $internal -j ACCEPT 

On a production gateway, you would no doubt need tighter rules than the above.

Firewall resources

For more information, see these handy resources:

• netfilter documentation
• books such as:
  • Cheswick and Bellovin, Firewalls and Internet Security
  • Zeigler, Linux Firewalls,
• our firewalls document
• our firewall links

FreeS/WAN quick start examples

These are sample ipsec.conf(5) configuration files for opportunistic encryption, with comments. Much of this configuration will be unnecessary with the new defaults proposed for FreeS/WAN 2.x.

config for initiate-only opportunistic encryption

Full instructions for this setup are in our quickstart guide.

The ipsec.conf file for an initiate-only opportunistic setup is:

# general IPsec setup
config setup
        # Use the default interface
        interfaces=%defaultroute
        # Use auto= parameters in conn descriptions to control startup actions.
        plutoload=%search
        plutostart=%search

# defaults for subsequent connection descriptions
conn %default
        # How to authenticate gateways
        authby=rsasig
        # default is
        # load connection description into Pluto's database
        # so it can respond if another gatway initiates
        # individual connection descriptions may override this
        auto=add

# description for opportunistic connections
conn me-to-anyone
        left=%defaultroute         # all connections should use default route
        right=%opportunistic       # anyone we can authenticate
        rightrsasigkey=%dns        # look up their key in DNS
        auto=route                 # set up for opportunistic
        rekey=no                   # let unused connections die
        leftid=@xy.example.com     # our identity for IPSec negotiations
                                   # must match DNS and ipsec.secrets

Normally, the last line above is the only one that you need to edit. However, some people may need to customize the interfaces= line in the "config setup" section. All other sections are identical for any standalone machine doing opportunistic encryption.

The @ sign in the leftid= makes the ID go "over the wire" as a Fully Qualified Domain Name (FQDN). Without it, an IP address would be used and this won't work.

The conn is not used to supply either public key. Your private key is in ipsec.secrets(5) and, for opportunistic encryption, the public keys for remote gateways are all looked up in DNS.

FreeS/WAN authenticates opportunistic encryption by RSA signature only, so "public key" and "private key" refer to these keys.

While the left and right designations here are arbitrary, we follow a convention of using left for local and right for remote.

Continue configuring initiate-only opportunism.

ipsec.conf for incoming opportunistic encryption

# description for opportunistic connections
conn me-to-anyone
        left=%defaultroute         # all connections should use default route
        right=%opportunistic       # anyone we can authenticate
        rightrsasigkey=%dns        # look up their key in DNS
        auto=route                 # set up for opportunistic
        rekey=no                   # let unused connections die

Note that leftid= has been removed.

Continue configuring full opportunism.

ipsec.conf for road warrior client

Here is our new connection, with comments:

conn us-to-office
        #
        # information obtained from office system admin
        # goes to the right of the = signs in these lines
        # values shown here are just for example
        #
        left=1.2.3.4                # gateway IP address
        leftsubnet=42.42.42.0/24   # the office network
        leftid=@gateway.example.com
        # real keys are much longer than shown here
        leftrsasigkey=0s1LgR7/oUM...
        #
        # our stuff
        #
        # all connections should use our default route
        # also controls the source address on IPsec packets
        right=%defaultroute
        # our identity for IPsec negotiations
        rightid=@xy.example.com

Everything else remains as it was when we had only opportunistic connections.

Return to our quickstart document.

A modular ipsec.conf

Once you have more than one connection, you may want to design your ipsec.conf in a modular fashion. This will help you avoid retyping information. Use also= to include one full or partial connection description within another.

Here is a sample modular ipsec.conf file for our situation. Since the right... information is common to both our connections, we place it in the partial connection our_stuff, which looks like:

conn our_stuff
        # all connections should use our default route
        # also controls the source address on IPsec packets
        right=%defaultroute
        # our identity for IPsec negotiations
        # must match what is in DNS and ipsec.secrets(5)
        rightid=@xy.example.com

We then include this information in other conns with the line:

	also=our_stuff

For this to work, conn our_stuff must come last.

The resulting modular ipsec.conf looks like:

# general IPsec setup
config setup
        # Use the default interface
        interfaces=%defaultroute
        # Use auto= parameters in conn descriptions to control startup actions.
        plutoload=%search
        plutostart=%search

# description for opportunistic connections
conn me-to-anyone
        also=our_stuff             # our system details, stored below
        left=%opportunistic        # anyone we can authenticate
        leftrsasigkey=%dns         # look up their key in DNS
        auto=route                 # set up for opportunistic
        rekey=no                   # let unused connections die

# pre-configured link to office network
# added for this example
conn us-to-office
        also=our_stuff             # our system details, stored below
        #
        # information obtained from office system admin
        # goes to the right of the = signs in these lines
        # values shown here are just for example
        #
        left=1.2.3.4                # gateway IP address
        leftsubnet=42.42.42.0/24   # the office network
        leftid=@gateway.example.com
        # real keys are much longer than shown here
        leftrsasigkey=0s1LgR7/oUM...

# description of our system
# included in other connection descriptions via also= lines
# must come after the lines that use it
conn our_stuff
        # all connections should use our default route
        # also controls the source address on IPsec packets
        right=%defaultroute
        # our identity for IPsec negotiations
        # must match what is in DNS and ipsec.secrets(5)
        rightid=@xy.example.com

Note that you cannot put an auto=start line into an included connection like our_stuff.

Of course, if need be, you can mix modular and nonmodular elements in any ipsec.conf.

Go back to configuring a road warrior.

FreeS/WAN FAQ

This is a collection of questions and answers, mostly taken from the FreeS/WAN mailing list. See the project web site for more information. All the FreeS/WAN documentation is online there.

Contributions to the FAQ are welcome. Please send them to the project mailing list.

Index of FAQ questions

• What is FreeS/WAN?
• How do I report a problem or seek help?
• Can I get ...
  • ... an off-the-shelf system that includes FreeS/WAN?
  • ... contractors or staff who know FreeS/WAN?
  • ... commercial support?
• Release questions
  • What is the current release?
  • When is the next release?
  • Are there known bugs in the current release?
• Modifications and contributions
  • Can I modify FreeS/WAN to ...?
  • Can I contribute to the project?
  • Is there detailed design documentation?
• Will FreeS/WAN work in my environment?
  • Can FreeS/WAN talk to ... ?
  • Can different FreeS/WAN versions talk to each other?
  • Is there a limit on throughput?
  • Is there a limit on number of connections?
  • Is a ... fast enough to handle FreeS/WAN with my loads?
• Will FreeS/WAN work on ...
  • ... my version of Linux?
  • ... non-Intel CPUs?
  • ... multiprocessors?
  • ... an older kernel?
  • ... the latest kernel version?
  • ... unusal network hardware?
• Does FreeS/WAN support ...
  • ... site-to-site VPN applications
  • ... remote users connecting to a LAN
  • ... remote users using shared secret authentication?
  • ... wireless networks
  • ... X.509 or other PKI certificates?
  • ... user authentication (Radius, SecureID, ...)?
  • ... assigning a "virtual identity" to a remote system?
  • ... single DES encryption?
  • ... AES encryption?
  • ... other encryption algorithms?
• Can I ...
  • ... reload connection info without restarting?
  • ... use several masqueraded subnets?
  • ... use subnets masqueraded to the same addresses?
  • ... assign a road warrior an address on my net (a virtual identity)?
  • ... support many road warriors with one gateway?
  • ... have many road warriors using shared secret authentication?
  • ... use Quality of Service routing with FreeS/WAN?
  • ... recognise dead tunnels and shut them down?
  • ... build IPsec tunnels over a demand-dialed link?
  • ... build GRE tunnels over IPsec?
• Life's little mysteries
  • I cannot ping ....
  • It takes forever to ...
  • I send packets to the tunnel with route(8) but they vanish
  • When a tunnel goes down, packets vanish
  • The firewall ate my packets!
  • Dropped connections
  • TCPdump on the gateway shows strange things
  • Traceroute does not show anything between the gateways
• Testing in stages (or .... works but ... doesn't)
  • Manually keyed connections don't work
  • One manual connection works, but second one fails
  • Manual connections work, but automatic keying doesn't
  • IPsec works, but connections using compression fail
  • Small packets work, but large transfers fail
  • Subnet-to-subnet works, but tests from the gateways don't
• Compilation problems
  • gmp.h: No such file or directory
  • ... virtual memory exhausted
• Interpreting error messages
  • route-client (or host) exited with status 7
  • SIOCADDRT:Network is unreachable
  • ipsec_setup: modprobe: Can't locate moduleipsec
  • ipsec_setup: Fatal error, kernel appears to lack KLIPS
  • ipsec_setup: ... failure to fetch key for ... from DNS
  • ipsec_setup: ... interfaces ... and ... share address ...
  • ipsec_setup: Cannot adjust kernel flags
  • Message numbers (MI3, QR1, et cetera) in Pluto messages
  • Connection names in Pluto error messages
  • Pluto: ... can't orient connection
  • ... we have no ipsecN interface for either end of this connection
  • Pluto: ... no connection is known
  • Pluto: ... no suitable connection ...
  • Pluto: ... no connection has been authorized
  • Pluto: ... OAKLEY_DES_CBC is not supported.
  • Pluto: ... no acceptable transform
  • rsasigkey dumps core
  • !Pluto failure!: ... exited with ... signal 4
  • ECONNREFUSED error message
  • klips_debug: ... no eroute!
  • ... trouble writing to /dev/ipsec ... SA already in use
  • ... ignoring ... payload
• Why don't you restrict the mailing lists to reduce spam?

What is FreeS/WAN?

FreeS/WAN is a Linux implementation of the IPsec protocols, providing security services at the IP (Internet Protocol) level of the network.

For more detail, see our introduction document or the FreeS/WAN project web site.

To start setting it up, go to our quickstart guide.

Our web links document has information on IPsec for other systems.

How do I report a problem or seek help?

See our troubleshooting document. It may guide you to a solution. If not, see its problem reporting section.

Basically, what it says is give us the output from ipsec barf from both gateways. Without full information, we cannot diagnose a problem. However, ipsec barf produces a lot of output. If at all possible, please make barfs accessible via the web or FTP rather than sending enormous mail messages.

Use the users mailing list for problem reports, rather than mailing developers directly.

• This gives you access to more expertise, including users who may have encountered and solved the same problems.
• It is more likely to get a quick response. Developers may get behind on email, or even ignore it entirely for a while, but a list message (given a reasonable Subject: line) is certain to be read by a fair number of people within hours.
• It may also be important because of cryptography export laws. A US citizen who provides technical assistance to foreign cryptographic work might be charged under the arms export regulations. Such a charge would be easier to defend if the discussion took place on a public mailing list than if it were done in private mail.

For problems involving interoperation with another IPsec implementation, try our interoperation document . If that does not help, try the mailing list. In this area, the users often know more than the developers.

Support beyond what the mailing list can provide is also available. See the next several questions.

See also these essays on How To Ask Questions The Smart Way and How to Report Bugs Effectively.

Can I get ...

Can I get an off-the-shelf system that includes FreeS/WAN?

There are a number of Linux distributions or firewall products which include FreeS/WAN. See this list. Using one of these, chosen to match your requirements and budget, may save you considerable time and effort.

If you don't know your requirements, start by reading Schneier's Secrets and Lies. That gives the best overview of security issues I have seen. Then consider hiring a consultant (see next question) to help define your requirements.

Can I hire consultants or staff who know FreeS/WAN?

If you want the help of a contractor, or to hire staff with FreeS/WAN expertise, you could:

• check availability in your area through your local Linux User Group (LUG Index)
• try asking on our mailing list

For companies offerring support, see the next question.

Can I get commercial support?

Many of the distributions or firewall products which include FreeS/WAN (see this list) come with commercial support or have it available as an option.

Various companies specialize in commercial support of open source software. Our project leader was a founder of the first such company, Cygnus Support. It has since been bought by Redhat. Another such firm is Linuxcare.

Release questions

What is the current release?

The current release is the highest-numbered tarball on our distribution site. Almost always, any of the mirrors will have the same file, though perhaps not for a day or so after a release.

Unfortunately, the web site is not always updated as quickly as it should be. At time of writing, for example, 1.96 has been on the FTP site for about two weeks, but the web site still lists 1.95 as current, and the 1.96 documentation is not yet on the web site.

We are working on fixing this, but it is complicated with our team in North America, the site in Europe and everyone involved having other tasks as well.

When is the next release?

We try to do a release in the first week of every month except January and August. We might adjust this a week either way because people are away at conferences or whatever.

If pre-release tests fail and the fix appears complex, or more generally if the code does not appear stable when a release is scheduled, we will just skip that release. This appears a better strategy than rushing complex work to produce a late release.

For serious bugs, we may bring out an extra bug-fix release. These get numbers in the normal release series. For example, there was a bug found in FreeS/WAN 1.6, so we did another release less than two weeks later. The bug-fix release was called 1.7, not something like 1.6a or 1.6.1.

Are there known bugs in the current release?

Any problems we are aware of at the time of a release are documented in the BUGS file for that release. You should also look at the CHANGES file.

Bugs discovered after a release are discussed on the mailing lists. The easiest way to check for any problems in the current code would be to peruse Claudia's weekly summaries on the briefs list, archived here.

Modifications and contributions

Can I modify FreeS/WAN to ...?

You are free to modify FreeS/WAN in any way. See the discussion of licensing in our introduction document.

Before investing much energy in any such project, we suggest that you

• check the list of existing patches
• post something about your project to the design mailing list

This may prevent duplicated effort, or lead to interesting collaborations.

Can I contribute to the project?

Users have also contributed heavily to documentation, both by creating their own HowTos and by posting things on the mailing lists which I have quoted in these HTML docs.

There are, however, some caveats.

FreeS/WAN is being implemented in Canada, by Canadians, largely to ensure that is it is entirely free of export restrictions. See this discussion. We cannot accept code contributions from US residents or citizens, not even one-line bugs fixes. The reasons for this were recently discussed extensively on the mailing list, in a thread starting here.

Not all contributions are of interest to us. The project has a set of fairly ambitious and quite specific goals, described in our introduction. Contributions that lead toward these goals are likely to be welcomed enthusiastically. Other contributions may be seen as lower priority, or even as a distraction.

Discussion of possible contributions takes place on the design mailing list.

Is there detailed design documentation?

• RFCs specifying the protocols we implement
• man pages for our utilities, library functions and file formats
• comments in the source code
• HTML documentation written primarily for users
• archived discussions from the mailing lists
• other papers mentioned in our introduction

The only formal design documents are a few papers in the last category above. All the other categories, however, have things to say about design as well.

Will FreeS/WAN work in my environment?

Can FreeS/WAN talk to ...?

The IPsec protocols are designed to support interoperation. In theory, any two IPsec implementations should be able to talk to each other. In practice, it is considerably more complex. We have a whole interoperation document devoted to this problem.

An important part of that document is links to the many user-written HowTos on interoperation between FreeS/WAN and various other implementations. Often the users know more than the developers about these issues (and almost always more than me :-), so these documents may be your best resource.

Can different FreeS/WAN versions talk to each other?

Linux FreeS/WAN can interoperate with many IPsec implementations, including earlier versions of Linux FreeS/WAN itself.

In a few cases, there are some complications. See our interoperation document for details.

Is there a limit on throughput?

There is no hard limit, but see below.

Is there a limit on number of tunnels?

There is no hard limit, but see next question.

Is a ... fast enough to handle FreeS/WAN with my loads?

A quick summary:

Even a limited machine can be useful

A 486 can handle a T1, ADSL or cable link, though the machine may be breathing hard.

A mid-range PC (say 800 MHz with good network cards) can do a lot of IPsec

With up to roughly 50 tunnels and aggregate bandwidth of 20 Megabits per second, it willl have cycles left over for other tasks.

There are limits

Even a high end CPU will not come close to handling a fully loaded 100 Mbit/second Ethernet link.

Beyond about 50 tunnels it needs careful management.

See our FreeS/WAN performance document for details.

Will FreeS/WAN work on ... ?

Will FreeS/WAN run on my version of Linux?

We build and test on Redhat distributions, but FreeS/WAN runs just fine on several other distributions, sometimes with minor fiddles to adapt to the local environment. Details are in our compatibility document. Also, some distributions or products come with FreeS/WAN included.

Will FreeS/WAN run on non-Intel CPUs?

FreeS/WAN is intended to run on all CPUs Linux supports . We know of it being used in production on x86, ARM, Alpha and MIPS. It has also had successful tests on PPC and SPARC, though we don't know of actual use there. Details are in our compatibility document.

Will FreeS/WAN run on multiprocessors?

FreeS/WAN is designed to work on any SMP architecture Linux supports, and has been tested successfully on at least dual processor Intel architecture machines. Details are in our compatibility document.

Will FreeS/WAN work on an older kernel?

It might, but we strongly recommend using a recent 2.2 or 2.4 series kernel. Sometimes the newer versions include security fixes which can be quite important on a gateway.

Also, we use recent kernels for development and testing, so those are better tested and, if you do encounter a problem, more easily supported. If something breaks applying recent FreeS/WAN patches to an older kernel, then "update your kernel" is almost certain to be the first thing we suggest. It may be the only suggestion we have.

The precise kernel versions supported by a particular FreeS/WAN release are given in the README file of that release.

See the following question for more on kernels.

Will FreeS/WAN run on the latest kernel version?

Sometimes yes, but quite often, no.

Kernel versions supported are given in the README file of each FreeS/WAN release. Typically, they are whatever production kernels were current at the time of our release (or shortly before; we might release for kernel n just as Linus releases n+1 ). Often FreeS/WAN will work on slightly later kernels as well, but of course this cannot be guaranteed.

For example, FreeS/WAN 1.91 was released for kernels 2.2.19 or 2.4.5, the current kernels at the time. It also worked on 2.4.6, 2.4.7 and 2.4.8, but 2.4.9 had changes that caused compilation errors if it was patched with FreeS/WAN 1.91.

When such changes appear, we put a fix in the FreeS/WAN snapshots, and distribute it with our next release. However, this is not a high priority for us, and it may take anything from a few days to several weeks for such a problem to find its way to the top of our kernel programmer's To-Do list. In the meanwhile, you have two choices:

• either stick with a slightly older kernel, even if it is not the latest and greatest. This is recommended for production systems; new versions may have new bugs.
• or fix the problem yourself and send us a patch, via the Users mailing list.

We don't even try to keep up with kernel changes outside the main 2.2 and 2.4 branches, such as the 2.4.x-ac patched versions from Alan Cox or the 2.5 series of development kernels. We'd rather work on developing the FreeS/WAN code than on chasing these moving targets. We are, however, happy to get patches for problems discovered there.

See also the Choosing a kernel section of our installation document.

Will FreeS/WAN work on unusual network hardware?

IPsec is designed to work over any network that IP works over, and FreeS/WAN is intended to work over any network interface hardware that Linux supports.

If you have working IP on some unusual interface -- perhaps Arcnet, Token Ring, ATM or Gigabit Ethernet -- then IPsec should "just work".

That said, practice is sometimes less tractable than theory. Our testing is done almost entirely on:

• 10 or 100 Mbit Ethernet
• ADSL or cable connections, with and without PPPoE
• IEEE 802.11 wireless LANs (see below)

If you have some other interface, especially an uncommon one, it is entirely possible you will get bitten either by a FreeS/WAN bug which our testing did not turn up, or by a bug in the driver that shows up only with our loads.

If IP works on your interface and FreeS/WAN doesn't, seek help on the mailing lists.

Another FAQ section describes MTU problems . These are a possibility for some interfaces.

Does FreeS/WAN support ...

For a discussion of which parts of the IPsec specifications FreeS/WAN does and does not implement, see our compatibility document.

For information on some often-requested features, see below.

Does FreeS/WAN support site-to-site VPN applications

Yes, FreeS/WAN can be used to build site-to-site Virtual Private Networks.

This application is discussed in our introduction and an example given in our FreeS/WAN quickstart document.

Does FreeS/WAN support remote users connecting to a LAN?

Yes, FreeS/WAN can be used to connect remote users. In the documentation, we refer to them as "Road Warriors".

This application is discussed in our introduction and an example given in our FreeS/WAN quickstart document.

Road warriors using Windows or Macintosh may need an IPsec client program for their machines.

Does FreeS/WAN support remote users using shared secret authentication?

Yes, but there are severe restrictions, so we strongly recommend using RSA keys for authentication instead.

See this FAQ question.

Does FreeS/WAN support wireless networks?

Yes, it is a common practice to use IPsec over wireless networks because their built-in encryption, WEP, is insecure.

There is some discussion in our advanced configuration document.

Does FreeS/WAN support X.509 or other PKI certificates?

FreeS/WAN, as distributed, does not currently support use of X.509 or other PKI certificates for authentication of gateways. We are concentrating on moving toward authentication via Secure DNS and opportunistic encryption; X.509 support is not (or at least not yet) on the priority list.

On the other hand, it is a priority for some users and user-contributed patches to add X.509 certificate support to FreeS/WAN have been available for some time. From mailing list reports, they seem to be quite widely used and to work well.

See the patches section of our web references document for details.

Does FreeS/WAN support user authentication (Radius, SecureID, ...)?

Not yet. So far, there is no standard way to authenticate users for IPsec, though there is a very active IETF working group looking at the problem, and several vendors have implemented various things already.

In the absence of a standard, user authentication has not been a priority for the FreeS/WAN team, and is unlikely to become one. This would be a good project for a volunteer, perhaps a staff member or contractor at some company that needs the feature. Certainly our team would co-operate with such an effort; we just don't have time to do it.

The patches section of our web links document has links to some user work on this.

Of course, there are various ways to avoid any requirement for user authentication in IPsec. Consider the situation where road warriors build IPsec tunnels to your office net and you are considering requiring user authentication during tunnel negotiation. Alternatives include:

• If you can trust the road warrior machines, then set them up so that only authorised users can create tunnels. If your road warriors use laptops, consider the possibility of theft.
• If the tunnel only provides access to particular servers and you can trust those servers, then set the servers up to require user authentication.

If either of those is trustworthy, it is not clear that you need user authentication in IPsec.

Does FreeS/WAN support assigning a "virtual identity" to a remote system?

Some IPsec implementations allow you to make the source address on packets sent by a Road Warrior machine be something other than the address of its interface to the Internet. This is sometimes described as assigning a virtual identity to that machine.

FreeS/WAN does not directly support this, but it can be done. See this FAQ question.

Does FreeS/WAN support single DES encryption?

No, single DES is not used either at the IKE level for negotiating connections or at the IPsec level for actually building them.

Single DES is insecure. As we see it, it is more important to deliver real security than to comply with a standard which has been subverted into allowing use of inadequate methods. See this discussion.

If you want to interoperate with an IPsec implementation which offers only DES, see our interoperation document.

Does FreeS/WAN support AES encryption?

AES is a new US government block cipher standard to replace the obsolete DES.

At time of writing (March 2002), the FreeS/WAN distribution does not yet support AES but user-written patches are available to add it. Our kernel programmer is working on integrating those patches into the distribution, and there is active discussion of this on the design mailimg list.

Does FreeS/WAN support other encryption algorithms?

Currently triple DES is the only cipher supported. AES will almost certainly be added (see previous question), and it is likely that in the process we will also add the other two AES finalists with open licensing, Twofish and Serpent.

We are extremely reluctant to add other ciphers. This would make both use and maintenance of FreeS/WAN more complex without providing any clear benefit. Complexity is emphatically not desirable in a security product.

Various users have written patches to add other ciphers. We provide links to these.

Can I ...

Can I reload connection info without restarting?

Yes, you can do this. Here are the details, in a mailing list message from Pluto programmer Hugh Redelmeier:

| How can I reload config's without restarting all of pluto and klips?  I am using
| FreeSWAN -> PGPNet in a medium sized production environment, and would like to be
| able to add new connections ( i am using include config/* ) without dropping current
| SA's.
| 
| Can this be done?
| 
| If not, are there plans to add this kind of feature?

        ipsec auto --add whatever
This will look in the usual place (/etc/ipsec.conf) for a conn named
whatever and add it.

If you added new secrets, you need to do
        ipsec auto --rereadsecrets
before Pluto needs to know those secrets.

| I have looked (perhaps not thoroughly enough tho) to see how to do this:

There may be more bits to look for, depending on what you are trying
to do.

Can I use several masqueraded subnets?

Yes. This is done all the time. See the discussion in our setup document. The only restriction is that the subnets on the two ends must not overlap. See the next question.

Here is a mailing list message on the topic. The user incorrectly thinks you need a 2.4 kernel for this -- actually various people have been doing it on 2.0 and 2.2 for quite some time -- but he has it right for 2.4.

Subject: Double NAT and freeswan working :)
   Date: Sun, 11 Mar 2001
   From: Paul Wouters <paul@xtdnet.nl>

Just to share my pleasure, and make an entry for people who are searching
the net on how to do this. Here's the very simple solution to have a double
NAT'ed network working with freeswan. (Not sure if this is old news, but I'm
not on the list (too much spam) and I didn't read this in any HOWTO/FAQ/doc
on the freeswan site yet (Sandy, put it in! :)

10.0.0.0/24 --- 10.0.0.1 a.b.c.d  ---- a.b.c.e {internet} ----+
                                                              |
10.0.1.0/24 --- 10.0.1.1 f.g.h.i  ---- f.g.h.j {internet} ----+

the goal is to have the first network do a VPN to the second one, yet also
have NAT in place for connections not destinated for the other side of the
NAT. Here the two Linux security gateways have one real IP number (cable
modem, dialup, whatever.

The problem with NAT is you don't want packets from 10.*.*.* to 10.*.*.*
to be NAT'ed. While with Linux 2.2, you can't, with Linux 2.4 you can.

(This has been tested and works for 2.4.2 with Freeswan snapshot2001mar8b)

relevant parts of /etc/ipsec.conf:

        left=f.g.h.i
        leftsubnet=10.0.1.0/24
        leftnexthop=f.g.h.j
        leftfirewall=yes
        leftid=@firewall.netone.nl
        leftrsasigkey=0x0........
        right=a.b.c.d
        rightsubnet=10.0.0.0/24
        rightnexthop=a.b.c.e
        rightfirewall=yes
        rightid=@firewall.nettwo.nl
        rightrsasigkey=0x0......
        # To authorize this connection, but not actually start it, at startup,
        # uncomment this.
        auto=add

and now the real trick. Setup the NAT correctly on both sites:

iptables -t nat -F
iptables -t nat -A POSTROUTING -o eth0 -d \! 10.0.0.0/8 -j MASQUERADE

This tells the NAT code to only do NAT for packets with destination other then
10.* networks. note the backslash to mask the exclamation mark to protect it
against the shell.

Happy painting :)

Paul

Can I use subnets masqueraded to the same addresses?

No. The notion that IP addresses are unique is one of the fundamental principles of the IP protocol. Messing with it is exceedingly perilous.

Fairly often a situation comes up where a company has several branches, all using the same non-routable addresses, perhaps 192.168.0.0/24. This works fine as long as those nets are kept distinct. The IP masquerading on their firewalls ensures that packets reaching the Internet carry the firewall address, not the private address.

This can break down when IPsec enters the picture. FreeS/WAN builds a tunnel that pokes through both masquerades and delivers packets from leftsubnet to rightsubnet and vice versa. For this to work, the two subnets must be distinct.

There are several solutions to this problem.

Usually, you re-number the subnets. Perhaps the Vancouver office becomes 192.168.101.0/24, Calgary 192.168.102.0/24 and so on. FreeS/WAN can happily handle this. With, for example leftsubnet=192.168.101.0/24 and rightsubnet=192.168.102.0/24 in a connection description, any machine in Calgary can talk to any machine in Vancouver. If you want to be more restrictive and use something like leftsubnet=192.168.101.128/25 and rightsubnet=192.168.102.240/28 so only certain machines on each end have access to the tunnel, that's fine too.

You could also split the subnet into smaller ones, for example using 192.168.1.0/25 in Vancouver and rightsubnet=192.168.0.128/25 in Calgary.

Alternately, you can just give up routing directly to machines on the subnets. Omit the leftsubnet and rightsubnet parameters from your connection descriptions. Your IPsec tunnels will then run between the public interfaces of the two firewalls. Packets will be masqueraded both before they are put into tunnels and after they emerge. Your Vancouver client machines will see only one Calgary machine, the firewall.

Can I assign a road warrior an address on my net (a virtual identity)?

Often it would be convenient to be able to give a Road Warrior an IP address which appears to be on the local network. Some IPsec implementations have support for this, sometimes calling the feature "virtual identity".

At time of writing (Feb 2002) FreeS/WAN does not support this, and we have no definite plans to add it. The difficulty is that is not yet a standard mechanism for it. There is an Internet Draft for a method of doing it using DHCP which looks promising. FreeS/WAN may support that in a future release.

In the meanwhile, you can do it yourself using the Linux iproute2(8) facilities. Details are in this paper.

Another method has also been discussed on the mailing list.:

• You can use a variant of the extruded subnet procedure.
• You have to avoid having the road warrior's assigned address within the range you actually use at home base. See previous question.
• On the other hand, you want the roadwarrior's address to be within the range that seems to be on your network.

For example, you might have:

leftsubnet=a.b.c.0/25

head office network

rightsubnet=a.b.c.129/32

extruded to a road warrior. Note that this is not in a.b.c.0/25

a.b.c.0/24

whole network, including both the above

You then set up routing so that the office machines use the IPsec gateway as their route to a.b.c.128/25. The leftsubnet parameter tells the road warriors to use tunnels to reach a.b.c.0/25, so you should have two-way communication. Depending or your network and applications, there may be some additional work to do on DNS or Windows configuration

Can I support many road warriors with one gateway?

Yes. This is easily done, using

either RSA authentication

standard in the FreeS/WAN distribution

or X.509 certificates

requires patches to FreeS/WAN

In either case, each Road Warrior must have a different key or certificate.

This cannot be made to work using pre-shared key authentication; see the next question for details.

If you expect to have more than a few dozen Road Warriors connecting simultaneously, you may need a fairly powerful gateway machine. See our document on FreeS/WAN performance.

Can I have many road warriors using shared secret authentication?

No. There is no way to do this securely, and there is no way to fix the problem.

You can have multiple Road Warriors using shared secret authentication only if they all use the same secret. This creates problems:

• If you have many users, it becomes almost certain the secret will leak
• The secret becomes quite valuable to an attacker
• All users authenticate the same way, so the gateway cannot tell them apart for logging or access control purposes
• Changing the secret is difficult. You have to securely notify all users.
• If you find out the secret has been compromised, you can change it, but then what? None of your users can connect without the new secret. How will you notify them all, quickly and securely, without using the VPN?

This is a designed-in limitation of the IKE key negotiation protocol, not a problem with our implementation.

When using shared secrets, the protocol requires that the responding gateway be able to determine which secret to use at a time when all it knows about the initiator is an IP address. This works fine if you know the initiator's address in advance and can use it to look up the appropiriate secret. However, it fails for Road Warriors since the gateway cannot know their IP addresses in advance.

We very strongly recommend that you avoid using shared secret authentication for multiple Road Warriors. Use RSA authentication instead.

With RSA signatures (or certificates) the protocol is slightly different. The initiator provides an identifier early in the exchange and the responder can use that identifier to look up the correct key or certificate. See above.

Can I use Quality of Service routing with FreeS/WAN?

From project technical lead Henry Spencer:

> Do QoS add to FreeS/WAN?
> For example integrating DiffServ and FreeS/WAN?

With a current version of FreeS/WAN, you will have to add hidetos=no to
the config-setup section of your configuration file.  By default, the TOS
field of tunnel packets is zeroed; with hidetos=no, it is copied from the
packet inside.  (This is a modest security hole, which is why it is no
longer the default.)

DiffServ does not interact well with tunneling in general.  Ways of
improving this are being studied.

Copying the TOS (type of service) information from the encapsulated packet to the outer header reveals the TOS information to an eavesdropper. This does not tell him much, but it might be of use in traffic analysis. Since we do not have to give it to him, our default is not to.

See ipsec.conf(5) for more on the hidetos= parameter.

Can I recognise dead tunnels and shut them down?

There is no general mechanism to do this is in the IPsec protocols.

From time to time, there is discussion on the IETF Working Group mailing list of adding a "keep-alive" mechanism (which some say should be called "make-dead"), but it is a fairly complex problem and no consensus has been reached on whether or how it should be done.

The protocol does have optional delete-SA messages which one side can send when it closes a connection in hopes this will cause the other side to do the same. FreeS/WAN does not currently support these. In any case, they would not solve the problem since:

• a gateway that crashes or hangs would not send the messages
• the sender is not required to send them
• they are not authenticated, so any receiver that trusts them leaves itself open to a denial of service attack
• the receiver is not required to do anything about them
• the receiver cannot acknowledge them; the protocol provides no mechanism for that
• since they are not acknowledged, the sender cannot rely on them

However, connections do have limited lifetimes and you can control how many attempts your gateway makes to rekey before giving up. For example, you can set:

conn default
        keyingtries=3
        keylife=30m

With these settings old connections will be cleaned up. Within 30 minutes of the other end dying, rekeying will be attempted. If it succeeds, the new connection replaces the old one. If it fails, no new connection is created. Either way, the old connection is taken down when its lifetime expires.

Here is a mailing list message on the topic from FreeS/WAN tech support person Claudia Schmeing:

You ask how to determine whether a tunnel is redundant:

> Can anybody explain the best way to determine this. Esp when a RW has
> disconnected? I thought 'ipsec auto --status' might be one way.

If a tunnel goes down from one end, Linux FreeS/WAN on the
other end has no way of knowing this until it attempts to rekey.
Once it tries to rekey and fails, it will 'know' that the tunnel is 
down.

Because it doesn't have a way of knowing the state until this point, 
it will also not be able to tell you the state via ipsec auto --status.

> However, comparing output from a working tunnel with that of one that
> was closed 
> did not show clearly show tunnel status.

If your tunnel is down but not 'unrouted' (see man ipsec_auto), you
should not be able to ping the opposite side of the tunnel. You can
use this as an indicator of tunnel status.

On a related note, you may be interested to know that as of 1.7, 
redundant tunnels caused by RW disconnections are likely to be 
less of a pain. From doc/CHANGES:

    There is a new configuration parameter, uniqueids, to control a new Pluto
    option:  when a new connection is negotiated with the same ID as an old
    one, the old one is deleted immediately.  This should help eliminate
    dangling Road Warrior connections when the same Road Warrior reconnects. 
    It thus requires that IDs not be shared by hosts (a previously legal but
    probably useless capability).  NOTE WELL:  the sample ipsec.conf now has
    uniqueids=yes in its config-setup section.


Cheers,

Claudia

Can I build IPsec tunnels over a demand-dialed link?

This is possible, but not easy. FreeS/WAN technical lead Henry Spencer wrote:

> 5. If the ISDN link goes down in between and is reestablished, the SAs
> are still up but the eroute are deleted and the IPsec interface shows
> garbage (with ifconfig)
> 6. Only restarting IPsec will bring the VPN back online.

This one is awkward to solve.  If the real interface that the IPsec
interface is mounted on goes down, it takes most of the IPsec machinery
down with it, and a restart is the only good way to recover. 

The only really clean fix, right now, is to split the machines in two: 

1. A minimal machine serves as the network router, and only it is aware
that the link goes up and down. 

2. The IPsec is done on a separate gateway machine, which thinks it has
a permanent network connection, via the router.

This is clumsy but it does work.  Trying to do both functions within a
single machine is tricky.  There is a software package (diald) which will
give the illusion of a permanent connection for demand-dialed modem
connections; I don't know whether it's usable for ISDN, or whether it can
be made to cooperate properly with FreeS/WAN. 

Doing a restart each time the interface comes up *does* work, although it
is a bit painful.  I did that with PPP when I was running on a modem link;
it wasn't hard to arrange the PPP scripts to bring IPsec up and down at
the right times.  (I'd meant to investigate diald but never found time.)

In principle you don't need to do a complete restart on reconnect, but you
do have to rebuild some things, and we have no nice clean way of doing
only the necessary parts.

In the same thread, one user commented:

Subject: Re: linux-ipsec: IPsec and Dial Up Connections
   Date: Wed, 22 Nov 2000
   From: Andy Bradford <andyb@calderasystems.com>

On Wed, 22 Nov 2000 19:47:11 +0100, Philip Reetz wrote:

> Are there any ideas what might be the cause of the problem and any way
> to work around it.
> Any help is highly appreciated.

On my laptop, when using ppp there is a ip-up script in /etc/ppp that 
will be executed each time that the ppp interface is brought up.  
Likewise there is an ip-down script that is called when it is taken 
down.  You might consider custimzing those to stop and start FreeS/Wan 
with each connection.  I believe that ISDN uses the same files, though 
I could be wrong---there should be something similar though.

Can I build GRE tunnels over IPsec?

This is possible in theory, but we are short on practical details. If you do this, please let us know via the mailing lists.

There is a list message with links to relevant resources.

Life's little mysteries

FreeS/WAN is a fairly complex product. (Neither the networks it runs on nor the protocols it uses are simple, so it could hardly be otherwise.) It therefore sometimes exhibits behaviour which can be somewhat confusing, or has problems which are not easy to diagnose. This section tries to explain those problems.

Setup and configuration of FreeS/WAN are covered in other documentation sections:

• basic setup and configuration
• advanced configuration
• Troubleshooting

However, we also list some of the commonest problems here.

I cannot ping ....

This question is dealt with in the advanced configuration section under the heading multiple tunnels.

The standard subnet-to-subnet tunnel protects traffic only between the subnets. To test it, you must use pings that go from one subnet to the other.

For example, suppose you have:

      subnet a.b.c.0/24
             |
      eth1 = a.b.c.1
         gate1
      eth0 = 1.2.3.4
             |

       ~ internet ~

             |
      eth0 = 4.3.2.1
         gate2
      eth1 = x.y.z.1
              |
       subnet x.y.z.0/24

and the connection description:

conn abc-xyz
     left=1.2.3.4
     leftsubnet=a.b.c.0/24
     right=4.3.2.1
     rightsubnet=x.y.z.0/24

You can test this connection description only by sending a ping that will actually go through the tunnel. Assuming you have machines at addresses a.b.c.2 and x.y.z.2, pings you might consider trying are:

ping from x.y.z.2 to a.b.c.2 or vice versa

Succeeds if tunnel is working. This is the only valid test of the tunnel.

ping from gate2 to a.b.c.2 or vice versa

Does not use tunnel. gate2 is not on protected subnet.

ping from gate1 to x.y.z.2 or vice versa

Does not use tunnel. gate1 is not on protected subnet.

ping from gate1 to gate2 or vice versa

Does not use tunnel. Neither gate is on a protected subnet.

Only the first of these is a useful test of this tunnel. The others do not use the tunnel. Depending on other details of your setup and routing, they:

• either fail, telling you nothing about the tunnel
• or succeed, telling you nothing about the tunnel since these packets use some other route

In some cases, you may be able to get around this. For the example network above, you could use:

        ping -I a.b.c.1 x.y.z.1

Both the adresses given are within protected subnets, so this should go through the tunnel.

If required, you can build additional tunnels so that all the machines involved can talk to all the others. See multiple tunnels in the advanced configuration document for details.

It takes forever to ...

Users fairly often report various problems involving long delays, sometimes on tunnel setup and sometimes on operations done through the tunnel, occasionally on simple things like ping or more often on more complex operations like doing NFS or Samba through the tunnel.

Almost always, these turn out to involve failure of a DNS lookup. The timeouts waiting for DNS are typically set long so that you won't time out when a query involves multiple lookups or long paths. Genuine failures therefore produce long delays before they are detected.

A mailing list message from project technical lead Henry Spencer:

> ... when i run /etc/rc.d/init.d/ipsec start, i get:
> ipsec_setup: Starting FreeS/WAN IPsec 1.5...
> and it just sits there, doesn't give back my bash prompt.

Almost certainly, the problem is that you're using DNS names in your
ipsec.conf, but DNS lookups are not working for some reason.  You will
get your prompt back... eventually.  But the DNS timeouts are long.
Doing something about this is on our list, but it is not easy.

In the meanwhile, we recommend that connection descriptions in ipsec.conf(5) use numeric IP addresses rather than names which will require a DNS lookup.

Names that do not require a lookup are fine. For example:

• a road warrior might use the identity rightid=@lancelot.example.org
• the gateway might use leftid=@camelot.example.org

These are fine. The @ sign prevents any DNS lookup. However, do not attempt to give the gateway address as left=camelot.example.org . That requires a lookup.

A post from one user after solving a problem with long delays:

Subject: Final Answer to Delay!!!
   Date: Mon, 19 Feb 2001
   From: "Felippe Solutions" <felippe@solutionstecnologia.com.br>

Sorry people, but seems like the Delay problem had nothing to do with
freeswan.

The problem was DNS as some people sad from the beginning, but not the way
they thought it was happening. Samba, ssh, telnet and other apps try to
reverse lookup addresses when you use IP numbers (Stupid that ahh).

I could ping very fast because I always ping with "-n" option, but I don't
know the option on the other apps to stop reverse addressing so I don't use
it.

This post is fairly typical. These problems are often tricky and frustrating to diagnose, and most turn out to be DNS-related.

One suggestion for diagnosis: test with both names and addresses if possible. For example, try all of:

• ping address
• ping -n address
• ping name

If these behave differently, the problem must be DNS-related since the three commands do exactly the same thing except for DNS lookups.

I send packets to the tunnel with route(8) but they vanish

IPsec connections are designed to carry only packets travelling between pre-defined connection endpoints. As project technical lead Henry Spencer put it:

IPsec tunnels are not just virtual wires; they are virtual wires with built-in access controls. Negotiation of an IPsec tunnel includes negotiation of access rights for it, which don't include packets to/from other IP addresses. (The protocols themselves are quite inflexible about this, so there are limits to what we can do about it.)

For fairly obvious security reasons, and to comply with the IPsec RFCs, KLIPS drops any packets it receives that are not allowed on the tunnels currently defined. So if you send it packets with route(8), and suitable tunnels are not defined, the packets vanish. Whether this is reported in the logs depends on the setting of klipsdebug in your ipsec.conf(5) file.

To rescue vanishing packets, you must ensure that suitable tunnels for them exist, by editing the connection descriptions in ipsec.conf(5). For example, supposing you have a simple setup:

         leftsubnet -- leftgateway === internet === roadwarrior

If you want to give the roadwarrior access to some resource that is located behind the left gateway but is not in the currently defined left subnet, then the usual procedure is to define an additional tunnel for those packets by creating a new connection description.

In some cases, it may be easier to alter an existing connection description, enlarging the definition of leftsubnet. For example, instead of two connection descriptions with 192.168.8.0/24 and 192.168.9.0/24 as their leftsubnet parameters, you can use a single description with 192.168.8.0/23.

If you have multiple endpoints on each side, you need to ensure that there is a route for each pair of endpoints. See this example.

When a tunnel goes down, packets vanish

This is a special case of the vanishing packet problem described in the previous question. Whenever KLIPS sees packets for which it does not have a tunnel, it drops them.

When a tunnel goes away, either because negotiations with the other gateway failed or because you gave an ipsec auto --down command, the route to its other end is left pointing into KLIPS, and KLIPS will drop packets it has no tunnel for.

This is a documented design decision, not a bug. FreeS/WAN must not automatically adjust things to send packets via another route. The other route might be insecure.

Of course, re-routing may be necessary in many cases. In those cases, you have to do it manually or via scripts. We provide the ipsec auto --unroute command for these cases.

From ipsec_auto(8):

Normally, pluto establishes a route to the destination specified for a connection as part of the --up operation. However, the route and only the route can be established with the --route operation. Until and unless an actual connection is established, this discards any packets sent there, which may be preferable to having them sent elsewhere based on a more general route (e.g., a default route).

Normally, pluto's route to a destination remains in place when a --down operation is used to take the connection down (or if connection setup, or later automatic rekeying, fails). This permits establishing a new connection (perhaps using a different specification; the route is altered as necessary) without having a ``window'' in which packets might go elsewhere based on a more general route. Such a route can be removed using the --unroute operation (and is implicitly removed by --delete).

See also this mailing list message.

The firewall ate my packets!

If firewalls filter out:

• either the UDP port 500 packets used in IKE negotiations
• or the ESP and AH (protocols 50 and 51) packets used to implement the IPsec tunnel

then IPsec cannot work. The first thing to check if packets seem to be vanishing is the firewall rules on the two gateway machines and any other machines along the path that you have access to.

For details, see our document on firewalls .

Some advice from technical lead Henry Spencer on diagnosing such problems:

> > Packets vanishing between the hardware interface and the ipsecN interface
> > is usually the result of firewalls not being configured to let them in...
> 
> Thanks for the suggestion. If only it were that simple! My ipchains startup
> script does take care of that, but just in case I manually inserted rules 
> accepting everything from london on dublin. No difference.

The other thing to check is whether the "RX packets dropped" count on the
ipsecN interface (run "ifconfig ipsecN", for N=1 or whatever, to see the
counts) is rising.  If so, then there's some sort of configuration mismatch
between the two ends, and IPsec itself is rejecting them.  If none of the
ipsecN counts is rising, then the packets are never reaching the IPsec
machinery, and the problem is almost certainly in firewalls etc.

Dropped connections

Networks being what they are, IPsec connections can be broken for any number of reasons, ranging from hardware failures to various software problems such as the path MTU problems discussed elsewhere in the FAQ. Fortunately, various diagnostic tools exist that help you sort out many of the possible problems.

There is one situation, however, where FreeS/WAN (using default settings) may destroy a connection for no readily apparent reason. This occurs when things are misconfigured so that two tunnels from the same gateway expect the same subnet on the far end.

In this situation, the first tunnel comes up fine and works until the second is established. At that point, because of the way we track connections internally, the first tunnel ceases to exist as far as this gateway is concerned. Of course the far end does not know that, and a storm of error messages appears on both systems as it tries to use the tunnel.

If the far end gives up, goes back to square one and negotiates a new tunnel, then that wipes out the second tunnel and ...

The solution is simple. Do not build multiple conn descriptions with the same remote subnet.

This is actually intended to be a feature, rather than a bug. Consider the situation where a single remote system goes down, then comes back up and reconnects to the gateway. It is useful to have the gateway tear down the old tunnel and recover resources when the reconnection is made. It recognises that situation by checking the remote subnet for each tunnel it builds and discarding duplicates. This works fine as long as you don't configure multiple tunnels with the same remote subnet.

If this behaviour is inconvenient for you, you can disable it by setting uniqueids=no in ipsec.conf(5).

TCPdump on the gateway shows strange things

Attempting to look at IPsec packets by running monitoring tools on the IPsec gateway machine can produce silly results. That machine is mangling the packets for IPsec, and possibly for firewall or NAT purposes as well. If the internals of the machine's IP stack are not what the monitoring tool expects, then the tool can misinterpret them and produce nonsense output.

See our testing document for more detail.

Traceroute does not show anything between the gateways

As far as traceroute can see, the two gateways are one hop apart; the data packet goes directly from one to the other through the tunnel. Of course the outer packets that implement the tunnel pass through whatever lies between the gateways, but those packets are built and dismantled by the gateways. Traceroute does not see them and cannot report anything about their path.

Here is a mailing list message with more detail.

Date: Mon, 14 May 2001
To: linux-ipsec@freeswan.org
From: "John S. Denker" <jsd@research.att.com<
Subject: Re: traceroute: one virtual hop

At 02:20 PM 5/14/01 -0400, Claudia Schmeing wrote:
>
>> > A bonus question: traceroute in subnet to subnet enviroment looks like:
>> > 
>> > traceroute to andris.dmz (172.20.24.10), 30 hops max, 38 byte packets
>> > 1  drama (172.20.1.1)  0.716 ms  0.942 ms  0.434 ms
>> > 2  * * *
>> > 3  andris.dmz (172.20.24.10)  73.576 ms  78.858 ms  79.434 ms
>> > 
>> > Why aren't there the other hosts which take part in the delivery during 
>    * * * ?
>
>If there is an ipsec tunnel between GateA and Gate B, this tunnel forms a 
>'virtual wire'.  When it is tunneled, the original packet becomes an inner 
>packet, and new ESP and/or AH headers are added to create an outer packet 
>around it. You can see an example of how this is done for AH at 
>doc/ipsec.html#AH . For ESP it is similar.
>
>Think about the packet's path from the inner packet's perspective.
>It leaves the subnet, goes into the tunnel, and re-emerges in the second
>subnet. This perspective is also the only one available to the
>'traceroute' command when the IPSec tunnel is up.

Claudia got this exactly right.  Let me just expand on a couple of points:

*) GateB is exactly one (virtual) hop away from GateA.  This is how it
would be if there were a physically private wire from A to B.  The
virtually private connection should work the same, and it does.

*) While the information is in transit from GateA to GateB, the hop count
of the outer header (the "envelope") is being decremented.  The hop count
of the inner header (the "contents" of the envelope) is not decremented and
should not be decremented.  The hop count of the outer header is not
derived from and should not be derived from the hop count of the inner header.

Indeed, even if the packets did time out in transit along the tunnel, there
would be no way for traceroute to find out what happened.  Just as
information cannot leak _out_ of the tunnel to the outside, information
cannot leak _into_ the tunnel from outside, and this includes ICMP messages
from routers along the path.

There are some cases where one might wish for information about what is
happening at the IP layer (below the tunnel layer) -- but the protocol
makes no provision for this.  This raises all sorts of conceptual issues.
AFAIK nobody has ever cared enough to really figure out what _should_
happen, let alone implement it and standardize it.

*) I consider the "* * *" to be a slight bug.  One might wish for it to be
replaced by "GateB GateB GateB".  It has to do with treating host-to-subnet
traffic different from subnet-to-subnet traffic (and other gory details).
I fervently hope KLIPS2 will make this problem go away.

*) If you want to ask questions about the link from GateA to GateB at the
IP level (below the tunnel level), you have to ssh to GateA and launch a
traceroute from there.

Testing in stages

It is often useful in debugging to test things one at a time:

• disable IPsec entirely, for example by turning it off with chkconfig(8), and make sure routing works
• Once that works, try a manually keyed connection. This does not require key negotiation between Pluto and the key daemon on the other end.
• Once that works, try automatically keyed connections
• Once IPsec works, add packet compression
• Once everything seems to work, try stress tests with large transfers, many connections, frequent re-keying, ...

FreeS/WAN releases are tested for all of these, so you can be reasonably certain they can do them all. Of course, that does not mean they will on the first try, especially if you have some unusual configuration.

The rest of this section gives information on diagnosing the problem when each of the above steps fails.

Manually keyed connections don't work

Suspect one of:

• mis-configuration of IPsec system in the /etc/ipsec.conf file
  common errors are incorrect interface or next hop information
• mis-configuration of manual connection in the /etc/ipsec.conf file
• routing problems causing IPsec packets to be lost
• bugs in KLIPS
• mismatch between the transforms we support and those another IPsec implementation offers.

One manual connection works, but second one fails

This is a fairly common problem when attempting to configure multiple manually keyed connections from a single gateway.

Each connection must be identified by a unique SPI value. For automatic connections, these values are assigned automatically. For manual connections, you must set them with spi= statements in ipsec.conf(5).

Each manual connection must have a unique SPI value in the range 0x100 to 0x999. Two or more with the same value will fail. For details, see our doc section Using manual keying in production and the man page ipsec.conf(5).

Manual connections work, but automatic keying doesn't

The most common reason for this behaviour is a firewall dropping the UDP port 500 packets used in key negotiation.

Other possibilities:

• mis-configuration of auto connection in the /etc/ipsec.conf file.

One common configuration error is forgetting that you need auto=add to load the connection description on the receiving end so it recognises the connection when the other end asks for it.

• error in shared secret in /etc/ipsec.secrets
• one gateway lacks a route to the other so Pluto's UDP packets are lost
• bugs in Pluto
• incompatibilities between Pluto's IKE implementation and the IKE at the other end of the tunnel.

Some possibile problems are discussed in out interoperation document.

IPsec works, but connections using compression fail

When we first added compression, we saw some problems:

• compatibility issues with other implementations. We followed the RFCs and omitted some extra material that many compression libraries add by default. Some other implementations left the extras in
• bugs in assembler compression routines on non-Intel CPUs. The workaround is to use C code instead of possibly problematic assembler.

We have not seen either problem in some time (at least six months as I write in March 2002), but if you have some unusual configuration then you may see them.

Small packets work, but large transfers fail

If tests with ping(1) and a small packet size succeed, but tests or transfers with larger packet sizes fail, suspect problems with packet fragmentation and perhaps path MTU discovery.

Our troubleshooting document covers these problems. Information on the underlying mechanism is in our background document.

Subnet-to-subnet works, but tests from the gateways don't

This is described under I cannot ping... above.

Compilation problems

gmp.h: No such file or directory

Pluto needs the GMP (GNU

Multi-Precision) library for the large integer calculations it uses in public key cryptography. This error message indicates a failure to find the library. You must install it before Pluto will compile.

The GMP library is included in most Linux distributions. Typically, there are two RPMs, libgmp and libgmp-devel, You need to install both, either from your distribution CDs or from your vendor's web site.

For more information and the latest version, see the GMP home page.

... virtual memory exhausted

We have had several reports of this message appearing, all on SPARC Linux. Here is a mailing message on a solution:

> ipsec_sha1.c: In function `SHA1Transform':
> ipsec_sha1.c:95: virtual memory exhausted

I'm seeing exactly the same problem on an Ultra with 256MB ram and 500
MB swap.  Except I am compiling version 1.5 and its Red Hat 6.2.

I can get around this by using -O instead of -O2 for the optimization
level.  So it is probably a bug in the optimizer on the sparc complier. 
I'll try and chase this down on the sparc lists.

Interpreting error messages

route-client (or host) exited with status 7

Here is a discussion of this error from FreeS/WAN "listress" (mailing list tech support person) Claudia Schmeing. The "FAQ on the network unreachable error" which she refers to is the next question below.

> I reached the point where the two boxes (both on dial-up connections, but
> treated as static IPs by getting the IP and editing ipsec.conf after the
> connection is established) to the point where they exchange some info, but I
> get an error like "route-client command exited with status 7 \n internal
> error".
> Where can I find a description of this error?

In general, if the FAQ doesn't cover it, you can search the mailing list 
archives - I like to use
http://www.sandelman.ottawa.on.ca/linux-ipsec/
but you can see doc/mail.html for different archive formats.


Your error comes from the _updown script, which performs some
routing and firewall functions to help Linux FreeS/WAN. More info
is available at doc/firewall.html and man ipsec.conf. Its routing
is integral to the health of Linux FreeS/WAN; it also provides facility
to insert custom firewall rules to be executed when you create or destroy
a connection.

Yours is, of course, a routing error. You can be fairly sure the routing 
machinery is saying "network is unreachable". There's a FAQ on the 
"network is unreachable" error, but more information is available now; read on.

If your _updown script is recent (for example if it shipped with 
Linux FreeS/WAN 1.91), you will see another debugging line in your logs 
that looks something like this:

> output: /usr/local/lib/ipsec/_updown: `route add -net 128.174.253.83 
> netmask 255.255.255.255 dev ipsec0 gw 66.92.93.161' failed

This is, of course, the system route command that exited with status 7, 
(ie. failed). Man route for details. Seeing the command typed out yields 
more information. If your _updown script is older, you may wish to update 
it to show the command explicitly.

Three parameters fed to the route command: net, netmask and gw [gateway] 
are derived from things you've put in ipsec.conf.

Net and netmask are derived from the peer's IP and mask. In more detail:

You may see a routing error when routing to a client (ie. subnet), or 
to a host (IPSec gateway or freestanding host; a box that does IPSec for
itself). In _updown, the "route-client" section  is responsible to set up 
the route for IPSec'd (usually, read 'tunneled') packets headed to a 
peer subnet. Similarly, route-host routes IPSec'd packets to a peer host
or IPSec gateway.

When routing to a 'client', net and netmask are ipsec.conf's left- or 
rightsubnet (whichever is not local). Similarly, when routing to a 
'host' the net is left or right. Host netmask is always /32, indicating a 
single machine.

Gw is nexthop's value. Again, the value in question is left- or rightnexthop,
whichever is local. Where left/right or left-/rightnexthop has the special 
value %defaultroute (described in man ipsec.conf), gw will automagically get
the value of the next hop on the default route.

Q: "What's a nexthop and why do I need one?"

A: 'nexthop' is a routing kluge; its value is the next hop away
   from the machine that's doing IPSec, and toward your IPSec peer. 
   You need it to get the processed packets out of the local system and 
   onto the wire. While we often route other packets through the machine 
   that's now doing IPSec, and are done with it, this does not suffice here. 
   After packets are processed with IPSec, this machine needs to know where 
   they go next. Of course using the 'IPSec gateway' as their routing gateway 
   would cause an infinite loop! [To visualize this, see the packet flow 
   diagram at doc/firewall.html.] To avoid this, we route packets through 
   the next hop down their projected path.

Now that you know the background, consider:
1. Did you test routing between the gateways in the absence of Linux
   FreeS/WAN, as recommended? You need to ensure the two machines that
   will be running Linux FreeS/WAN can route to one another before trying to 
   make a secure connection.
2. Is there anything obviously wrong with the sense of your route command?

Normally, this problem is caused by an incorrect local nexthop parameter.
Check out the use of %defaultroute, described in man ipsec.conf. This is
a simple way to set nexthop for most people. To figure nexthop out by hand,
traceroute in-the-clear to your IPSec peer. Nexthop is the traceroute's 
first hop after your IPSec gateway.

SIOCADDRT:Network is unreachable

This message is not from FreeS/WAN, but from the Linux IP stack itself. That stack is seeing packets it has no route for, either because your routing was broken before FreeS/WAN started or because FreeS/WAN's changes broke it.

Here is a message from Claudia suggesting ways to diagnose and fix such problems:

You write,
> I have correctly installed freeswan-1.8 on RH7.0 kernel 2.2.17, but when 
> I setup a VPN connection with the other machine(RH5.2 Kernel 2.0.36 
> freeswan-1.0, it works well.) it told me that 
> "SIOCADDRT:Network is unreachable"!  But the network connection is no 
> problem.

Often this error is the result of a misconfiguration. 

Be sure that you can route successfully in the absence of Linux
FreeS/WAN. (You say this is no problem, so proceed to the next step.)

Use a custom copy of the default updownscript. Do not change the route 
commands, but add a diagnostic message revealing the exact text of the 
route command. Is there a problem with the sense of the route command
that you can see? If so, then re-examine those ipsec.conf settings
that are being sent to the route command. 

You may wish to use the ipsec auto --route and --unroute commands to 
troubleshoot the problem. See man ipsec_auto for details.

Since the above message was written, we have modified the updown script to provide a better diagnostic for this problem. Check /var/log/messages.

See also the FAQ question route-client (or host) exited with status 7.

ipsec_setup: modprobe: Can't locate module ipsec

ipsec_setup: Fatal error, kernel appears to lack KLIPS

These messages indicate an installation failure. The kernel you are running does not contain the KLIPS (kernel IPsec) code.

Note that the "modprobe: Can't locate module ipsec" message appears even if you are not using modules. If there is no KLIPS in your kernel, FreeS/WAN tries to load it as a module. If that fails, you get this message.

Commands you can quickly try are:

uname -a

to get details, including compilation date and time, of the currently running kernel

ls /

ls /boot

to ensure a new kernel is where it should be. If kernel compilation puts it in / but lilo wants it in /boot , then you should uncomment the INSTALL_PATH=/boot line in the kernel Makefile.

more /etc/lilo.conf

to see that lilo has correct information

lilo

to ensure that information in /etc/lilo.conf has been transferred to the boot sector

If those don't find the problem, you have to go back and check through the install procedure to see what was missed.

Here is one of Claudia's messages on the topic:

> I tried to install freeswan 1.8 on my mandrake 7.2 test box. ...

> It does show version and some output for whack.

Yes, because the Pluto (daemon) part of ipsec is installed correctly, but
as we see below the kernel portion is not.

> However, I get the following from /var/log/messages:
> 
> Mar 11 22:11:55 pavillion ipsec_setup: Starting FreeS/WAN IPsec 1.8...
> Mar 11 22:12:02 pavillion ipsec_setup: modprobe: Can't locate module ipsec
> Mar 11 22:12:02 pavillion ipsec_setup: Fatal error, kernel appears to lack
> KLIPS.

This is your problem. You have not successfully installed a kernel with
IPSec machinery in it. 

Did you build Linux FreeS/WAN as a module? If so, you need to ensure that 
your new module has been installed in the directory where your kernel 
loader normally finds your modules. If not, you need to ensure
that the new IPSec-enabled kernel is being loaded correctly.

See also doc/install.html, and INSTALL in the distro.

ipsec_setup: ... failure to fetch key for ... from DNS

Quoting Henry:

Note that by default, FreeS/WAN is now set up to
     (a) authenticate with RSA keys, and
     (b) fetch the public key of the far end from DNS.
Explicit attention to  ipsec.conf will be needed if you want
to do something different.

and Claudia, responding to the same user:

You write,

>       My current setup in ipsec.conf is leftrsasigkey=%dns I have 
> commented this and authby=rsasig out. I am able to get ipsec running, 
> but what I find is that the documentation only specifies for %dns are 
> there any other values that can be placed in this variable other than 
> %dns and the key? I am also assuming that this is where I would place 
> my public key for the left and right side as well is this correct?

Valid values for authby= are rsasig and secret, which entail authentication
by RSA signature or by shared secret, respectively. Because you have 
commented authby=rsasig out, you are using the default value of authby=secret. 

When using RSA signatures, there are two ways to get the public key for the
IPSec peer: either copy it directly into *rsasigkey= in ipsec.conf, or
fetch it from dns. The magic value %dns for *rsasigkey parameters says to 
try to fetch the peer's key from dns.

For any parameters, you may find their significance and special values in
man ipsec.conf. If you are setting up keys or secrets, be sure also to
reference man ipsec.secrets.

ipsec_setup: ... interfaces ... and ... share address ...

This is a fatal error. FreeS/WAN cannot cope with two or more interfaces using the same IP address. You must re-configure to avoid this.

A mailing list message on the topic from Pluto developer Hugh Redelmeier:

| I'm trying to get freeswan working between two machine where one has a ppp
| interface.
| I've already suceeded with  two machines with ethernet ports but  the ppp
| interface is causing me problems.
|  basically when I run ipsec start  i get
| ipsec_setup: Starting FreeS/WAN IPsec 1.7...
| ipsec_setup: 003 IP interfaces ppp1 and ppp0 share address 192.168.0.10!
| ipsec_setup: 003 IP interfaces ppp1 and ppp2 share address 192.168.0.10!
| ipsec_setup: 003 IP interfaces ppp0 and ppp2 share address 192.168.0.10!
| ipsec_setup: 003 no public interfaces found
|
| followed by lots of cannot work out interface for connection messages
|
| now I can specify the interface in ipsec.conf to be ppp0 , but this does
| not affect the above behaviour. A quick look in server.c indicates that the
| interfaces value  is not used but some sort of raw detect happens.
|
| I guess I could prevent the formation of the extra ppp interfaces or
| allocate them different ip but I'd  rather not. if at all possible. Any
| suggestions please.

Pluto won't touch an interface that shares an IP address with another.
This will eventually change, but it probably won't happen soon.

For now, you will have to give the ppp1 and ppp2 different addresses.

ipsec_setup: Cannot adjust kernel flags

A mailing list message form technical lead Henry Spencer:

> When FreeS/WAN IPsec 1.7 is starting on my 2.0.38 Linux kernel the following
> error message is generated:
> ipsec_setup: Cannot adjust kernel flags, no /proc/sys/net/ipsec directory!
> What is supposed to create this directory and how can I fix this problem?

I think that directory is a 2.2ism, although I'm not certain (I don't have
a 2.0.xx system handy any more for testing).  Without it, some of the
ipsec.conf config-setup flags won't work, but otherwise things should
function. 

You also need to enable the /proc filesystem in your kernel configuration for these operations to work.

Message numbers (MI3, QR1, et cetera) in Pluto messages

Pluto messages often indicate where Pluto is in the IKE protocols. The letters indicate Main mode or Q uick mode and Initiator or Responder. The numerals are message sequence numbers. For more detail, see our IPsec section.

Connection names in Pluto error messages

From Pluto programmer Hugh Redelmeier:

| Jan 17 16:21:10 remus Pluto[13631]: "jumble" #1: responding to Main Mode from Road Warrior 130.205.82.46
| Jan 17 16:21:11 remus Pluto[13631]: "jumble" #1: no suitable connection for peer @banshee.wittsend.com
| 
|     The connection "jumble" has nothing to do with the incoming
| connection requests, which were meant for the connection "banshee".

You are right.  The message tells you which Connection Pluto is
currently using, which need not be the right one.  It need not be the
right one now for the negotiation to eventually succeed!  This is
described in ipsec_pluto(8) in the section "Road Warrior Support".

There are two times when Pluto will consider switching Connections for
a state object.  Both are in response to receiving ID payloads (one in
Phase 1 / Main Mode and one in Phase 2 / Quick Mode).  The second is
not unique to Road Warriors.  In fact, neither is the first any more
(two connections for the same pair of hosts could differ in Phase 1 ID
payload; probably nobody else has tried this).

Pluto: ... can't orient connection

Older versions of FreeS/WAN used this message. The same error now gives the "we have no ipsecN ..." error described just below.

... we have no ipsecN interface for either end of this connection

Each Pluto needs to know whether it is running on the machine which the connection description calls left or on right . It figures that out by:

• looking at the interfaces given in interfaces= lines in the config setup section
• discovering the IP addresses for those interfaces
• searching for a match between those addresses and the ones given in left= or right= lines.

Normally a match is found. Then Pluto knows where it is and can set up other things (for example, if it is left) using parameters such as leftsubnet and leftnexthop, and sending its outgoing packets to right.

If no match is found, it emits the above error message.

Pluto: ... no connection is known

This error message occurs when a remote system attempts to negotiate a connection and Pluto does not have a connection description that matches what the remote system has requested. The most common cause is a configuration error on one end or the other.

Parameters involved in this match are left, right , leftsubnet and rightsubnet.

The match must be exact. For example, if your left subnet is a.b.c.0/24 then neither a single machine in that net nor a smaller subnet such as a.b.c.64/26 will be considered a match.

The message can also occur when an appropriate description exists but Pluto has not loaded it. Use an auto=add statement in the connection description, or an ipsec auto --add <conn_name> command, to correct this.

An explanation from the Pluto developer:

| Jul 12 15:00:22 sohar58 Pluto[574]: "corp_road" #2: cannot respond to IPsec
| SA request because no connection is known for
| 216.112.83.112/32===216.112.83.112...216.67.25.118

This is the first message from the Pluto log showing a problem.  It
means that PGPnet is trying to negotiate a set of SAs with this
topology:

216.112.83.112/32===216.112.83.112...216.67.25.118
^^^^^^^^^^^^^^^^^   ^^^^^^^^^^^^^^   ^^^^^^^^^^^^^
client on our side  our host         PGPnet host, no client

None of the conns you showed look like this.

Use
        ipsec auto --status
to see a snapshot of what connections are in pluto, what
negotiations are going on, and what SAs are established.

The leftsubnet= (client) in your conn is 216.112.83.64/26.  It must
exactly match what pluto is looking for, and it does not.

Pluto: ... no suitable connection ...

This is similar to the no connection known error, but occurs at a different point in Pluto processing.

Here is one of Claudia's messages explaining the problem:

You write,

> What could be the reason of the following error? 
> "no suitable connection for peer '@xforce'"

When a connection is initiated by the peer, Pluto must choose which entry in 
the conf file best matches the incoming connection. A preliminary choice is 
made on the basis of source and destination IPs, since that information is 
available at that time. 

A payload containing an ID arrives later in the negotiation. Based on this
id and the *id= parameters, Pluto refines its conn selection. ...

The message "no suitable connection" indicates that in this refining step,
Pluto does not find a connection that matches that ID.

Please see "Selecting a connection when responding" in man ipsec_pluto for
more details.

See also Connection names in Pluto error messages.

Pluto: ... no connection has been authorized

Here is one of Claudia's messages discussing this problem:

You write,

>  May 22 10:46:31 debian Pluto[25834]: packet from x.y.z.p:10014: 
>  initial Main Mode message from x.y.z.p:10014 
                            but no connection has been authorized

This error occurs early in the connection negotiation process,
at the first step of IKE negotiation (Main Mode), which is itself the 
first of two negotiation phases involved in creating an IPSec connection.

Here, Linux FreeS/WAN receives a packet from a potential peer, which 
requests that they begin discussing a connection.

The "no connection has been authorized" means that there is no connection 
description in Linux FreeS/WAN's internal database that can be used to 
link your ipsec interface with that peer.

"But of course I configured that connection!" 

It may be that the appropriate connection description exists in ipsec.conf 
but has not been added to the database with ipsec auto --add myconn or the 
auto=add method. Or, the connection description may be misconfigured.

The only parameters that are relevant in this decision are left= and right= .
Local and remote ports are also taken into account -- we see that the port 
is printed in the message above -- but there is no way to control these
in ipsec.conf.


Failure at "no connection has been authorized" is similar to the
"no connection is known for..." error in the FAQ, and the "no suitable
connection" error described in the snapshot's FAQ. In all three cases,
Linux FreeS/WAN is trying to match parameters received in the
negotiation with the connection description in the local config file.

As it receives more information, its matches take more parameters into 
account, and become more precise:  first the pair of potential peers,
then the peer IDs, then the endpoints (including any subnets).

The "no suitable connection for peer *" occurs toward the end of IKE 
(Main Mode) negotiation, when the IDs are matched.

"no connection is known for a/b===c...d" is seen at the beginning of IPSec 
(Quick Mode, phase 2) negotiation, when the connections are matched using
left, right, and any information about the subnets.

Pluto: ... OAKLEY_DES_CBC is not supported.

This message occurs when the other system attempts to negotiate a connection using single DES, which we do not support because it is insecure.

Our interoperation document has suggestions for how to deal with systems that attempt to use single DES.

Pluto: ... no acceptable transform

This message means that the other gateway has made a proposal for connection parameters, but nothing they proposed is acceptable to Pluto. Possible causes include:

• misconfiguration on either end
• policy incompatibilities, for example we require encrypted connections but they are trying to create one with just authentication
• interoperation problems, for example they offer only single DES and FreeS/WAN does not support that. See discussion in our interoperation document.

A more detailed explanation, from Pluto programmer Hugh Redelmeier:

Background:

When one IKE system (for example, Pluto) is negotiating with another
to create an SA, the Initiator proposes a bunch of choices and the
Responder replies with one that it has selected.

The structure of the choices is fairly complicated.  An SA payload
contains a list of lists of "Proposals".  The outer list is a set of
choices: the selection must be from one element of this list.

Each of these elements is a list of Proposals.  A selection must be
made from each of the elements of the inner list.  In other words,
*all* of them apply (that is how, for example, both AH and ESP can
apply at once).

Within each of these Proposals is a list of Transforms.  For each
Proposal selected, one Transform must be selected (in other words,
each Proposal provides a choice of Transforms).

Each Transform is made up of a list of Attributes describing, well,
attributes.  Such as lifetime of the SA.  Such as algorithm to be
used.  All the Attributes apply to a Transform.

You will have noticed a pattern here: layers alternate between being
disjunctions ("or") and conjunctions ("and").

For Phase 1 / Main Mode (negotiating an ISAKMP SA), this structure is
cut back.  There must be exactly one Proposal.  So this degenerates to
a list of Transforms, one of which must be chosen.

In your case, no proposal was considered acceptable to Pluto (the
Responder).  So negotiation ceased.  Pluto logs the reason it rejects
each Transform.  So look back in the log to see what is going wrong.

rsasigkey dumps core

On Fri, 29 Jun 2001, Rodrigo Gruppelli wrote:
> ...Well, it seem that there's
> another problem with it. When I try to generate a pair of RSA keys,
> rsasigkey cores dump...

*That* is a neon sign flashing "GMP LIBRARY IS BROKEN".  Rsasigkey calls
GMP a lot, and our own library a little bit, and that's very nearly all it
does.  Barring bugs in its code or our library -- which have happened, but
not very often -- a problem in rsasigkey is a problem in GMP.

See the next question for how to deal with GMP errors.

!Pluto failure!: ... exited with ... signal 4

Pluto has died. Signal 4 is SIGILL, illegal instruction.

The most likely cause is that your GMP (GNU multi-precision) library is compiled for a different processor than what you are running on. Pluto uses that library for its public key calculations.

Try getting the GMP sources and recompile for your processor type. Most Linux distributions will include this source, or you can download it from the GMP home page.

ECONNREFUSED error message

From John Denker, on the mailing list:

1)  The log message
  some IKE message we sent has been rejected with 
  ECONNREFUSED (kernel supplied no details)
is much more suitable than the previous version.  Thanks.

2) Minor suggestion for further improvement: it might be worth mentioning
that the command
  tcpdump -i eth1 icmp[0] != 8 and icmp[0] != 0
is useful for tracking down the details in question.  We shouldn't expect
all IPsec users to figure that out on their own.  The log message might
even provide a hint as to where to look in the docs.

Reply From Pluto developer Hugh Redelmeier

Good idea.

I've added a bit pluto(8)'s BUGS section along these lines.
I didn't have the heart to lengthen this message.

klips_debug: ... no eroute!

This message means KLIPS has received a packet for which no IPsec tunnel has been defined.

Here is a more detailed duscussion from the team's tech support person Claudia Schmeing, responding to a query on the mailing list:

> Why ipsec reports no eroute! ???? IP Masq... is disabled.

In general, more information is required so that people on the list may
give you informed input. See doc/prob.report.

The document she refers to has since been replaced by a section of the troubleshooting document.

However, I can make some general comments on this type of error.

This error usually looks something like this (clipped from an archived
message):

> ttl:64 proto:1 chk:45459 saddr:192.168.1.2 daddr:192.168.100.1
> ... klips_debug:ipsec_findroute: 192.168.1.2->192.168.100.1
> ... klips_debug:rj_match: * See if we match exactly as a host destination
> ... klips_debug:rj_match: ** try to match a leaf, t=0xc1a260b0
> ... klips_debug:rj_match: *** start searching up the tree, t=0xc1a260b0
> ... klips_debug:rj_match: **** t=0xc1a260c8
> ... klips_debug:rj_match: **** t=0xc1fe5960
> ... klips_debug:rj_match: ***** not found.
> ... klips_debug:ipsec_tunnel_start_xmit: Original head/tailroom: 2, 28
> ... klips_debug:ipsec_tunnel_start_xmit: no eroute!: ts=47.3030, dropping.


What does this mean?
- --------------------

"eroute" stands for "extended route", and is a special type of route 
internal to Linux FreeS/WAN. For more information about this type of route, 
see the section of man ipsec_auto on ipsec auto --route.

"no eroute!" here means, roughly, that Linux FreeS/WAN cannot find an 
appropriate tunnel that should have delivered this packet. Linux 
FreeS/WAN therefore drops the packet, with the message "no eroute! ...
dropping", on the assumption that this packet is not a legitimate 
transmission through a properly constructed tunnel.


How does this situation come about?
- -----------------------------------

Linux FreeS/WAN has a number of connection descriptions defined in 
ipsec.conf. These must be successfully brought "up" to form actual tunnels.
(see doc/setup.html's step 15, man ipsec.conf and man ipsec_auto 
for details).

Such connections are often specific to the endpoints' IPs. However, in 
some cases they may be more general, for example in the case of 
Road Warriors where left or right is the special value %any.

When Linux FreeS/WAN receives a packet, it verifies that the packet has
come through a legitimate channel, by checking that there is an
appropriate tunnel through which this packet might legitimately have
arrived. This is the process we see above.

First, it checks for an eroute that exactly matches the packet. In the 
example above, we see it checking for a route that begins at 192.168.1.2
and ends at 192.168.100.1. This search favours the most specific match that
would apply to the route between these IPs. So, if there is a connection 
description exactly matching these IPs, the search will end there. If not, 
the code will search for a more general description matching the IPs.
If there is no match, either specific or general, the packet will be
dropped, as we see, above.

Unless you are working with Road Warriors, only the first, specific part 
of the matching process is likely to be relevant to you.


"But I defined the tunnel, and it came up, why do I have this error?"
- ---------------------------------------------------------------------

One of the most common causes of this error is failure to specify enough
connection descriptions to cover all needed tunnels between any two 
gateways and their respective subnets. As you have noticed, troubleshooting
this error may be complicated by the use of IP Masq. However, this error is
not limited to cases where IP Masq is used. 

See doc/configuration.html#multitunnel for a detailed example of the 
solution to this type of problem.

The documentation section she refers to is now here.

... trouble writing to /dev/ipsec ... SA already in use

This error message occurs when two manual connections are set up with the same SPI value.

See the FAQ for One manual connection works, but second one fails.

... ignoring ... payload

This message is harmless. The IKE protocol provides for a number of optional messages types:

• delete SA
• initial contact
• vendor ID
• ...

An implementation is never required to send these, but they are allowed to. The receiver is not required to do anything with them. FreeS/WAN ignores them, but notifies you via the logs.

For the "ignoring delete SA Payload" message, see also our discussion of cleaning up dead tunnels.

Why don't you restrict the mailing lists to reduce spam?

As a matter of policy, some of our mailing lists need to be open to non-subscribers. Project management feel strongly that maintaining this openness is more important than blocking spam.

• Users should be able to get help or report bugs without subscribing.
• Even a user who is subscribed may not have access to his or her subscribed account when he or she needs help, miles from home base in the middle of setting up a client's gateway.
• There is arguably a legal requirement for this policy. A US resident or citizen could be charged under munitions export laws for providing technical assistance to a foreign cryptographic project. Such a charge would be more easily defended if the discussion takes place in public, on an open list.

This has been discussed several times at some length on the list. See the list archives. Bringing the topic up again is unlikely to be useful. Please don't. Or at the very least, please don't without reading the archives and being certain that whatever you are about to suggest has not yet been discussed.

Project technical lead Henry Spencer summarised one discussion:

For the third and last time: this list *will* *not* do address-based filtering. This is a policy decision, not an implementation problem. The decision is final, and is not open to discussion. This needs to be communicated better to people, and steps are being taken to do that.

Adding this FAQ section is one of the steps he refers to.

You have various options other than just putting up with the spam, filtering it yourself, or unsubscribing:

• subscribe only to one or both of our lists with restricted posting rules:
  • briefs , weekly list summaries
  • announce , project-related announcements
• read the other lists via the archives

A number of tools are available to filter mail.

• Many mail readers include some filtering capability.
• Many Linux distributions include procmail(8) for server-side filtering.
• The Spam Bouncer is a set of procmail(8) filters designed to combat spam.
• Roaring Penguin have a MIME defanger that removes potentially dangerous attachments.

If you use your ISP's mail server rather than running your own, consider suggesting to the ISP that they tag suspected spam as this ISP does. They could just refuse mail from dubious sources, but that is tricky and runs some risk of losing valuable mail or senselessly annoying senders and their admins. However, they can safely tag and deliver dubious mail. The tags can greatly assist your filtering.

For information on tracking down spammers, see these HowTos, or the Sputum site. Sputum have a Linux anti-spam screensaver available for download.

Here is a more detailed message from Henry:

On Mon, 15 Jan 2001, Jay Vaughan wrote:
> I know I'm flogging a dead horse here, but I'm curious as to the reasons for
> an aversion for a subscriber-only mailing list?

Once again:  for legal reasons, it is important that discussions of these
things be held in a public place -- the list -- and we do not want to
force people to subscribe to the list just to ask one question, because
that may be more than merely inconvenient for them.  There are also real
difficulties with people who are temporarily forced to use alternate
addresses; that is precisely the time when they may be most in need of
help, yet a subscribers-only policy shuts them out.

These issues do not apply to most mailing lists, but for a list that is
(necessarily) the primary user support route for a crypto package, they
are very important.  This is *not* an ordinary mailing list; it has to
function under awkward constraints that make various simplistic solutions
inapplicable or undesirable. 

> We're *ALL* sick of hearing about list management problems, not just you
> old-timers, so why don't you DO SOMETHING EFFECTIVE ABOUT IT...

Because it's a lot harder than it looks, and many existing "solutions"
have problems when examined closely.

> A suggestion for you, based on 10 years of experience with management of my
> own mailing lists would be to use mailman, which includes pretty much every
> feature under the sun that you guys need and want, plus some.  The URL for
> mailman...

I assure you, we're aware of mailman.  Along with a whole bunch of others,
including some you almost certainly have never heard of (I hadn't!).

> As for the argument that the list shouldn't be configured to enforce
> subscription - I contend that it *SHOULD* AT LEAST require manual address
> verification in order for posts to be redirected.

You do realize, I hope, that interposing such a manual step might cause
your government to decide that this is not truly a public forum, and thus
you could go to jail if you don't get approval from them before mailing to
it?  If you think this sounds irrational, your government is noted for
making irrational decisions in this area; we can't assume that they will
suddenly start being sensible.  See above about awkward constraints.  You
may be willing to take the risk, but we can't, in good conscience, insist
that all users with problems do so. 

                                                          Henry Spencer
                                                       henry@spsystems.net

and a message on the topic from project leader John Gilmore:

Subject: Re: The linux-ipsec list's topic
   Date: Sat, 30 Dec 2000
   From: John Gilmore <gnu@toad.com>

I'll post this single message, once only, in this discussion, and then
not burden the list with any further off-topic messages.  I encourage
everyone on the list to restrain themself from posting ANY off-topic
messages to the linux-ipsec list.

The topic of the linux-ipsec mailing list is the FreeS/WAN software.

I frequently see "discussions about spam on a list" overwhelm the
volume of "actual spam" on a list. BOTH kinds of messages are
off-topic messages.  Twenty anti-spam messages take just as long to
detect and discard as twenty spam messages.

The Linux-ipsec list encourages on-topic messages from people who have
not joined the list itself.  We will not censor messages to the list
based on where they originate, or what return address they contain.
In other words, non-subscribers ARE allowed to post, and this will not
change.  My own valid contributions have been rejected out-of-hand by
too many other mailing lists for me to want to impose that censorship
on anybody else's contributions.  And every day I see the damage that
anti-spam zeal is causing in many other ways; that zeal is far more
damaging to the culture of the Internet than the nuisance of spam.

In general, it is the responsibility of recipients to filter,
prioritize, or otherwise manage the handling of email that comes to
them.  It is not the responsibility of the rest of the Internet
community to refrain from sending messages to recipients that they
might not want to see.  If your software infrastructure for managing
your incoming email is insufficient, then improve it.  If you think
the signal-to-noise ratio on linux-ipsec is too poor, then please
unsubscribe.  But don't further increase the noise by posting to the
linux-ipsec list about those topics.

        John Gilmore
        founder & sponsor, FreeS/WAN project

FreeS/WAN manual pages

The various components of Linux FreeS/WAN are of course documented in standard Unix manual pages, accessible via the man(1) command.

Links here take you to an HTML version of the man pages.

Files

ipsec.conf(5)

IPsec configuration and connections

ipsec.secrets(5)

secrets for IKE authentication, either pre-shared keys or RSA private keys

These files are also discussed in the configuration section.

Commands

Many users will never give most of the FreeS/WAN commands directly. Configure the files listed above correctly and everything should be automatic.

The exceptions are commands for mainpulating the RSA keys used in Pluto authentication:

ipsec_rsasigkey(8)

generate keys

ipsec_newhostkey(8)

generate keys in a convenient format

ipsec_showhostkey(8)

extract RSA keys from ipsec.secrets(5) (or optionally, another file) and format them for insertion in ipsec.conf(5) or in DNS records

Note that:

The following commands are fairly likely to be used, if only for testing and status checks:

ipsec(8)

invoke IPsec utilities

ipsec_setup(8)

control IPsec subsystem

ipsec_auto(8)

control automatically-keyed IPsec connections

ipsec_manual(8)

take manually-keyed IPsec connections up and down

ipsec_ranbits(8)

generate random bits in ASCII form

ipsec_look(8)

show minimal debugging information

ipsec_barf(8)

spew out collected IPsec debugging information

The lower-level utilities listed below are normally invoked via scripts listed above, but they can also be used directly when required.

ipsec_eroute(8)

manipulate IPsec extended routing tables

ipsec_klipsdebug(8)

set Klips (kernel IPsec support) debug features and level

ipsec_pluto(8)

IPsec IKE keying daemon

ipsec_spi(8)

manage IPsec Security Associations

ipsec_spigrp(8)

group/ungroup IPsec Security Associations

ipsec_tncfg(8)

associate IPsec virtual interface with real interface

ipsec_whack(8)

control interface for IPsec keying daemon

Library routines

ipsec_atoaddr(3)

ipsec_addrtoa(3)

convert Internet addresses to and from ASCII

ipsec_atosubnet(3)

ipsec_subnettoa(3)

convert subnet/mask ASCII form to and from addresses

ipsec_atoasr(3)

convert ASCII to Internet address, subnet, or range

ipsec_rangetoa(3)

convert Internet address range to ASCII

ipsec_atodata(3)

ipsec_datatoa(3)

convert binary data from and to ASCII formats

ipsec_atosa(3)

ipsec_satoa(3)

convert IPsec Security Association IDs to and from ASCII

ipsec_atoul(3)

ipsec_ultoa(3)

convert unsigned-long numbers to and from ASCII

ipsec_goodmask(3)

is this Internet subnet mask a valid one?

ipsec_masktobits(3)

convert Internet subnet mask to bit count

ipsec_bitstomask(3)

convert bit count to Internet subnet mask

ipsec_optionsfrom(3)

read additional ``command-line'' options from file

ipsec_subnetof(3)

given Internet address and subnet mask, return subnet number

ipsec_hostof(3)

given Internet address and subnet mask, return host part

ipsec_broadcastof(3)

given Internet address and subnet mask, return broadcast address

FreeS/WAN and firewalls

FreeS/WAN, or other IPsec implementations, frequently run on gateway machines, the same machines running firewall or packet filtering code. This document discusses the relation between the two.

The firewall code in 2.4 and later kernels is called Netfilter. The user-space utility to manage a firwewall is iptables(8). See the netfilter/iptables web site for details.

Filtering rules for IPsec packets

The basic constraint is that an IPsec gateway must have packet filters that allow IPsec packets, at least when talking to other IPsec gateways:

• UDP port 500 for IKE negotiations
• protocol 50 if you use ESP encryption and/or authentication (the typical case)
• protocol 51 if you use AH packet-level authentication

Your gateway and the other IPsec gateways it communicates with must be able to exchange these packets for IPsec to work. Firewall rules must allow UDP 500 and at least one of AHor ESP on the interface that communicates with the other gateway.

For nearly all FreeS/WAN applications, you must allow UDP port 500 and the ESP protocol.

There are two ways to set this up:

easier but less flexible

Just set up your firewall scripts at boot time to allow IPsec packets to and from your gateway. Let FreeS/WAN reject any bogus packets.

more work, giving you more precise control

Have the ipsec_pluto(8) daemon call scripts to adjust firewall rules dynamically as required. This is done by naming the scripts in the ipsec.conf(5) variables prepluto=, postpluto= , leftupdown= and rightupdown=.

Both methods are described in more detail below.

Firewall configuration at boot

It is possible to set up both firewalling and IPsec with appropriate scripts at boot and then not use leftupdown= and rightupdown=, or use them only for simple up and down operations.

Basically, the technique is

• allow IPsec packets (typically, IKE on UDP port 500 plus ESP, protocol 50)
  • incoming, if the destination address is your gateway (and optionally, only from known senders)
  • outgoing, with the from address of your gateway (and optionally, only to known receivers)
• let Pluto deal with IKE
• let KLIPS deal with ESP

Since Pluto authenticates its partners during the negotiation, and KLIPS drops packets for which no tunnel has been negotiated, this may be all you need.

A simple set of rules

In simple cases, you need only a few rules, as in this example:

# allow IPsec
#
# IKE negotiations
iptables -A INPUT  -p udp --sport 500 --dport 500 -j ACCEPT
iptables -A OUTPUT -p udp --sport 500 --dport 500 -j ACCEPT
# ESP encrypton and authentication
iptables -A INPUT  -p 50 -j ACCEPT
iptables -A OUTPUT -p 50 -j ACCEPT
# uncomment for AH authentication header
# iptables -A INPUT  -p 51 -j ACCEPT
# iptables -A OUTPUT -p 51 -j ACCEPT

Other rules

However, while it is certainly possible to create an elaborate set of rules yourself (please let us know via the mailing list if you do), it may be both easier and more secure to use a set which has already been published and tested.

The published rule sets we know of are described in the next section.

Adding additional rules

reject IPsec packets that are not to or from known gateways

This possibility is discussed in more detail later

allow systems behind your gateway to build IPsec tunnels that pass through the gateway

This possibility is discussed in more detail later

filter incoming packets emerging from KLIPS.

Firewall rules can recognise packets emerging from IPsec. They are marked as arriving on an interface such as ipsec0, rather than eth0, ppp0 or whatever.

It is therefore reasonably straightforward to filter these packets in whatever way suits your situation.

Modifying existing rules

In some cases rules that work fine before you add IPsec may require modification to work with IPsec.

This is especially likely for rules that deal with interfaces on the Internet side of your system. IPsec adds a new interface; often the rules must change to take account of that.

For example, consider the rules given in this section of the Netfilter documentation:

Most people just have a single PPP connection to the Internet, and don't
want anyone coming back into their network, or the firewall:

    ## Insert connection-tracking modules (not needed if built into kernel).
    # insmod ip_conntrack
    # insmod ip_conntrack_ftp

    ## Create chain which blocks new connections, except if coming from inside.
    # iptables -N block
    # iptables -A block -m state --state ESTABLISHED,RELATED -j ACCEPT
    # iptables -A block -m state --state NEW -i ! ppp0 -j ACCEPT
    # iptables -A block -j DROP

    ## Jump to that chain from INPUT and FORWARD chains.
    # iptables -A INPUT -j block
    # iptables -A FORWARD -j block

On an IPsec gateway, those rules may need to be modified. The above allows new connections from anywhere except ppp0. That means new connections from ipsec0 are allowed.

Do you want to allow anyone who can establish an IPsec connection to your gateway to initiate TCP connections to any service on your network? Almost certainly not if you are using opportunistic encryption. Quite possibly not even if you have only explicitly configured connections.

To disallow incoming connections from ipsec0, change the middle section above to:

    ## Create chain which blocks new connections, except if coming from inside.
    # iptables -N block
    # iptables -A block -m state --state ESTABLISHED,RELATED -j ACCEPT
    # iptables -A block -m state --state NEW -i ppp+ -j DROP
    # iptables -A block -m state --state NEW -i ipsec+ -j DROP
    # iptables -A block -m state --state NEW -i -j ACCEPT
    # iptables -A block -j DROP

The original rules accepted NEW connections from anywhere except ppp0. This version drops NEW connections from any PPP interface (ppp+) and from any ipsec interface (ipsec+), then accepts the survivors.

Of course, these are only examples. You will need to adapt them to your own situation.

Published rule sets

Several sets of firewall rules that work with FreeS/WAN are available.

Scripts based on Ranch's work

One user, Rob Hutton, posted his boot time scripts to the mailing list, and we included them in previous versions of this documentation. They are still available from our web site. However, they were for an earlier FreeS/WAN version so we no longer recommend them. Also, they had some bugs. See this message.

Those scripts were based on David Ranch's scripts for his "Trinity OS" for setting up a secure Linux. Check his home page for the latest version and for information on his book on securing Linux. If you are going to base your firewalling on Ranch's scripts, we recommend using his latest version, and sending him any IPsec modifications you make for incorporation into later versions.

The Seattle firewall

We have had several mailing lists reports of good results using FreeS/WAN with Seawall (the Seattle Firewall). See that project's home page on Sourceforge.

The RCF scripts

Another set of firewall scripts with IPsec support are the RCF or rc.firewall scripts. See their home page.

Asgard scripts

Asgard's Realm has set of firewall scripts with FreeS/WAN support, for 2.4 kernels and iptables.

User scripts from the mailing list

One user gave considerable detail on his scripts, including supporting IPX through the tunnel. His message was too long to conveniently be quoted here, so I've put it in a separate file.

Calling firewall scripts, named in ipsec.conf(5)

The ipsec.conf(5) configuration file has three pairs of parameters used to specify an interface between FreeS/WAN and firewalling code.

Note that using these is not required if you have a static firewall setup. In that case, you just set your firewall up at boot time (in a way that permits the IPsec connections you want) and do not change it thereafter. Omit all the FreeS/WAN firewall parameters and FreeS/WAN will not attempt to adjust firewall rules at all. See above for some information on appropriate scripts.

However, if you want your firewall rules to change when IPsec connections change, then you need to use these parameters.

Scripts called at IPsec start and stop

One pair of parmeters are set in the config setup section of the ipsec.conf(5) file and affect all connections:

prepluto=

script to be called before pluto(8) IKE daemon is started.

postpluto=

script to be called after pluto(8) IKE daemon is stopped.

They can also be used in other ways. For example, you might have prepluto add a module to your kernel for the secure network interface or make a dialup connection, and then have postpluto remove the module or take the connection down.

Scripts called at connection up and down

The other parameters are set in connection descriptions. They can be set in individual connection descriptions, and could even call different scripts for each connection for maximum flexibility. In most applications, however, it makes sense to use only one script and to call it from conn %default section so that it applies to all connections.

You can:

either

set leftfirewall=yes or rightfirewall=yes to use our supplied default script

or

assign a name in a leftupdown= or rightupdown= line to use your own script

Note that only one of these should be used. You cannot sensibly use both. Since our default script is obsolete (designed for firewalls using ipfwadm(8) on 2.0 kernels), most users who need this service will need to write a custom script.

The default script

We supply a default script named _updown.

leftfirewall=

rightfirewall=

indicates that the gateway is doing firewalling and that pluto(8) should poke holes in the firewall as required.

Set these to yes and Pluto will call our default script _updown with appropriate arguments whenever it:

• starts or stops IPsec services
• brings a connection up or down

The supplied default _updown script is appropriate for simple cases using the ipfwadm(8) firewalling package.

User-written scripts

You can also write your own script and have Pluto call it. Just put the script's name in one of these ipsec.conf(5) lines:

leftupdown=

rightupdown=

specifies a script to call instead of our default script _updown.

Your script should take the same arguments and use the same environment variables as _updown. See the "updown command" section of the ipsec_pluto(8) man page for details.

Note that you should not modify our _updown script in place . If you did that, then upgraded FreeS/WAN, the upgrade would install a new default script, overwriting your changes.

Scripts for ipchains or iptables

Our _updown is for firewalls using ipfwadm(8), the firewall code for the 2.0 series of Linux kernels. If you are using the more recent packages ipchains(8) (for 2.2 kernels) or iptables(8) (2.4 kernels), then you must do one of:

• use static firewall rules which are set up at boot time as described above and do not need to be changed by Pluto
• limit yourself to ipchains(8)'s ipfwadm(8) emulation mode in order to use our script
• write your own script and call it with leftupdown and rightupdown.

You can write a script to do whatever you need with firewalling. Specify its name in a [left|right]updown= parameter in ipsec.conf(5) and Pluto will automatically call it for you.

The arguments Pluto passes such a script are the same ones it passes to our default _updown script, so the best way to build yours is to copy ours and modify the copy.

Note, however, that you should not modify our _updown script in place. If you did that, then upgraded FreeS/WAN, the upgrade would install a new default script, overwriting your changes.

A complication: IPsec vs. NAT

Network Address Translation, also known as IP masquerading, is a method of allocating IP addresses dynamically, typically in circumstances where the total number of machines which need to access the Internet exceeds the supply of IP addresses.

Any attempt to perform NAT operations on IPsec packets between the IPsec gateways creates a basic conflict:

• IPsec wants to authenticate packets and ensure they are unaltered on a gateway-to-gateway basis
• NAT rewrites packet headers as they go by
• IPsec authentication fails if packets are rewritten anywhere between the IPsec gateways

For AH, which authenticates parts of the packet header including source and destination IP addresses, this is fatal. If NAT changes those fields, AH authentication fails.

For IKE and ESP it is not necessarily fatal, but is certainly an unwelcome complication.

NAT on or behind the IPsec gateway works

This problem can be avoided by having the masquerading take place on or behind the IPsec gateway.

This can be done physically with two machines, one physically behind the other. A picture, using SG to indicate IPsec S ecurity Gateways, is:

      clients --- NAT ----- SG ---------- SG
                  two machines

In this configuration, the actual client addresses need not be given in the leftsubnet= parameter of the FreeS/WAN connection description. The security gateway just delivers packets to the NAT box; it needs only that machine's address. What that machine does with them does not affect FreeS/WAN.

A more common setup has one machine performing both functions:

      clients ----- NAT/SG ---------------SG
                  one machine

Here you have a choice of techniques depending on whether you want to make your client subnet visible to clients on the other end:

• If you want the single gateway to behave like the two shown above, with your clients hidden behind the NAT, then omit the leftsubnet= parameter. It then defaults to the gateway address. Clients on the other end then talk via the tunnel only to your gateway. The gateway takes packets emerging from the tunnel, applies normal masquerading, and forwards them to clients.
• If you want to make your client machines visible, then give the client subnet addresses as the leftsubnet= parameter in the connection description and

  either

  set leftfirewall=yes to use the default updown script

  or

  use your own script by giving its name in a leftupdown= parameter

  These scripts are described in their own section.

In this case, no masquerading is done. Packets to or from the client subnet are encrypted or decrypted without any change to their client subnet addresses, although of course the encapsulating packets use gateway addresses in their headers. Clients behind the right security gateway see a route via that gateway to the left subnet.

NAT between gateways is problematic

We recommend not trying to build IPsec connections which pass through a NAT machine. This setup poses problems:

      clients --- SG --- NAT ---------- SG

If you must try it, some references are:

• Jean_Francois Nadeau's document on doing IPsec behind NAT
• VPN masquerade patches to make a Linux NAT box handle IPsec packets correctly

Other references on NAT and IPsec

Other documents which may be relevant include:

• an Internet Draft on IPsec and NAT which may eventually evolve into a standard solution for this problem.
• an informational RFC, Security Model with Tunnel-mode IPsec for NAT Domains .
• an article in Cisco's Internet Protocol Journal

Other complications

Of course simply allowing UDP 500 and ESP packets is not the whole story. Various other issues arise in making IPsec and packet filters co-exist and even co-operate. Some of them are summarised below.

IPsec through the gateway

Basic IPsec packet filtering rules deal only with packets addressed to or sent from your IPsec gateway.

It is a separate policy decision whether to permit such packets to pass through the gateway so that client machines can build end-to-end IPsec tunnels of their own. This may not be practical if you are using NAT (IP masquerade) on your gateway, and may conflict with some corporate security policies.

Where possible, allowing this is almost certainly a good idea. Using IPsec on an end-to-end basis is more secure than gateway-to-gateway.

Doing it is quite simple. You just need firewall rules that allow UDP port 500 and protocols 50 and 51 to pass through your gateway. If you wish, you can of course restrict this to certain hosts.

Preventing non-IPsec traffic

One application of this is for the telecommuter who might have:

     Sunset==========West------------------East ================= firewall --- the Internet
         home network      untrusted net        corporate network

The subnet on the right is 0.0.0.0/0, the whole Internet. The West gateway is set up so that it allows only IPsec packets to East in or out.

This configuration is used in AT&T Research's network. For details, see the papers links in our introduction.

Another application would be to set up firewall rules so that an internal machine, such as an employees-only web server, could not talk to the outside world except via specific IPsec tunnels.

Filtering packets from unknown gateways

It is possible to use firewall rules to restrict UDP 500, ESP and AH packets so that these packets are accepted only from known gateways. This is not strictly necessary since FreeS/WAN will discard packets from unknown gateways. You might, however, want to do it for any of a number of reasons. For example:

• Arguably, "belt and suspenders" is the sensible approach to security. If you can block a potential attack in two ways, use both. The only question is whether to look for a third way after implementing the first two.
• Some admins may prefer to use the firewall code this way because they prefer firewall logging to FreeS/WAN's logging.
• You may need it to implement your security policy. Consider an employee working at home, and a policy that says traffic from the home system to the Internet at large must go first via IPsec to the corporate LAN and then out to the Internet via the corporate firewall. One way to do that is to make ipsec0 the default route on the home gateway and provide exceptions only for UDP 500 and ESP to the corporate gateway. Everything else is then routed via the tunnel to the corporate gateway.

It is not possible to use only static firewall rules for this filtering if you do not know the other gateways' IP addresses in advance, for example if you have "road warriors" who may connect from a different address each time or if want to do opportunistic encryption to arbitrary gateways. In these cases, you can accept UDP 500 IKE packets from anywhere, then use the updown script feature of pluto(8) to dynamically adjust firewalling for each negotiated tunnel.

Firewall packet filtering does not much reduce the risk of a denial of service attack on FreeS/WAN. The firewall can drop packets from unknown gateways, but KLIPS does that quite efficiently anyway, so you gain little. The firewall cannot drop otherwise legitmate packets that fail KLIPS authentication, so it cannot protect against an attack designed to exhaust resources by making FreeS/WAN perform many expensive authentication operations.

In summary, firewall filtering of IPsec packets from unknown gateways is possible but not strictly necessary.

Other packet filters

When the IPsec gateway is also acting as your firewall, other packet filtering rules will be in play. In general, those are outside the scope of this document. See our Linux firewall links for information. There are a few types of packet, however, which can affect the operation of FreeS/WAN or of diagnostic tools commonly used with it. These are discussed below.

ICMP filtering

ICMP is the Internet Control Message Protocol. It is used for messages between IP implementations themselves, whereas IP used is used between the clients of those implementations. ICMP is, unsurprisingly, used for control messages. For example, it is used to notify a sender that a desination is not reachable, or to tell a router to reroute certain packets elsewhere.

ICMP handling is tricky for firewalls.

• You definitely want some ICMP messages to get through; things won't work without them. For example, your clients need to know if some destination they ask for is unreachable.
• On the other hand, you do equally definitely do not want untrusted folk sending arbitrary control messages to your machines. Imagine what someone moderately clever and moderately malicious could do to you, given control of your network's routing.

ICMP does not use ports. Messages are distinguished by a "message type" field and, for some types, by an additional "code" field. The definitive list of types and codes is on the IANA site.

One expert uses this definition for ICMP message types to be dropped at the firewall.

# ICMP types which lack socially redeeming value.
#  5     Redirect
#  9     Router Advertisement
# 10     Router Selection
# 15     Information Request
# 16     Information Reply
# 17     Address Mask Request
# 18     Address Mask Reply

badicmp='5 9 10 15 16 17 18'

A more conservative approach would be to make a list of allowed types and drop everything else.

Whichever way you do it, your ICMP filtering rules on a FreeS/WAN gateway should allow at least the following ICMP packet types:

echo (type 8)

echo reply (type 0)

These are used by ping(1). We recommend allowing both types through the tunnel and to or from your gateway's external interface, since ping(1) is an essential testing tool.

It is fairly common for firewalls to drop ICMP echo packets addressed to machines behind the firewall. If that is your policy, please create an exception for such packets arriving via an IPsec tunnel, at least during intial testing of those tunnels.

destination unreachable (type 3)

This is used, with code 4 (Fragmentation Needed and Don't Fragment was Set) in the code field, to control path MTU discovery. Since IPsec processing adds headers, enlarges packets and may cause fragmentation, an IPsec gateway should be able to send and receive these ICMP messages on both inside and outside interfaces.

UDP packets for traceroute

The traceroute(1) utility uses UDP port numbers from 33434 to approximately 33633. Generally, these should be allowed through for troubleshooting.

Some firewalls drop these packets to prevent outsiders exploring the protected network with traceroute(1). If that is your policy, consider creating an exception for such packets arriving via an IPsec tunnel, at least during intial testing of those tunnels.

UDP for L2TP

Windows 2000 does, and products designed for compatibility with it may, build L2TP tunnels over IPsec connections.

For this to work, you must allow UDP protocol 1701 packets coming out of your tunnels to continue to their destination. You can, and probably should, block such packets to or from your external interfaces, but allow them from ipsec0.

See also our Windows 2000 interoperation discussion .

How it all works: IPsec packet details

IPsec uses three main types of packet:

IKE uses the UDP protocol and port 500 .

Unless you are using only (less secure, not recommended) manual keying, you need IKE to negotiate connection parameters, acceptable algorithms, key sizes and key setup. IKE handles everything required to set up, rekey, repair or tear down IPsec connections.

ESP is protocol number 50

This is required for encrypted connections.

AH is protocol number 51

This can be used where only authentication, not encryption, is required.

All of those packets should have appropriate IPsec gateway addresses in both the to and from IP header fields. Firewall rules can check this if you wish, though it is not strictly necessary. This is discussed in more detail later.

IPsec processing of incoming packets authenticates them then removes the ESP or AH header and decrypts if necessary. Successful processing exposes an inner packet which is then delivered back to the firewall machinery, marked as having arrived on an ipsec[0-3] interface. Firewall rules can use that interface label to distinguish these packets from unencrypted packets which are labelled with the physical interface they arrived on (or perhaps with a non-IPsec virtual interface such as ppp0).

One of our users sent a mailing list message with a diagram of the packet flow.

ESP and AH do not have ports

Some protocols, such as TCP and UDP, have the notion of ports. Others protocols, including ESP and AH, do not. Quite a few IPsec newcomers have become confused on this point. There are no ports in the ESP or AH protocols, and no ports used for them. For these protocols, the idea of ports is completely irrelevant.

Header layout

The protocol numbers for ESP or AH are used in the 'next header' field of the IP header. On most non-IPsec packets, that field would have one of:

• 1 for ICMP
• 4 for IP-in-IP encapsulation
• 6 for TCP
• 17 for UDP
• ... or one of about 100 other possibilities listed by IANA

Each header in the sequence tells what the next header will be. IPsec adds headers for ESP or AH near the beginning of the sequence. The original headers are kept and the 'next header' fields adjusted so that all headers can be correctly interpreted.

For example, using [ ] to indicate data protected by ESP and unintelligible to an eavesdropper between the gateways:

• a simple packet might have only IP and TCP headers with:
  • IP header says next header --> TCP
  • TCP header port number --> which process to send data to
  • data
• with ESP transport mode encapsulation, that packet would have:
  • IP header says next header --> ESP
  • ESP header [ says next --> TCP
  • TCP header port number --> which process to send data to
  • data ]
  Note that the IP header is outside ESP protection, visible to an attacker, and that the final destination must be the gateway.
• with ESP in tunnel mode, we might have:
  • IP header says next header --> ESP
  • ESP header [ says next --> IP
  • IP header says next header --> TCP
  • TCP header port number --> which process to send data to
  • data ]
  Here the inner IP header is protected by ESP, unreadable by an attacker. Also, the inner header can have a different IP address than the outer IP header, so the decrypted packet can be routed from the IPsec gateway to a final destination which may be another machine.

Part of the ESP header itself is encrypted, which is why the [ indicating protected data appears in the middle of some lines above. The next header field of the ESP header is protected. This makes traffic analysis more difficult. The next header field would tell an eavesdropper whether your packet was UDP to the gateway, TCP to the gateway, or encapsulated IP. It is better not to give this information away. A clever attacker may deduce some of it from the pattern of packet sizes and timings, but we need not make it easy.

IPsec allows various combinations of these to match local policies, including combinations that use both AH and ESP headers or that nest multiple copies of these headers.

For example, suppose my employer has an IPsec VPN running between two offices so all packets travelling between the gateways for those offices are encrypted. If gateway policies allow it (The admins could block UDP 500 and protocols 50 and 51 to disallow it), I can build an IPsec tunnel from my desktop to a machine in some remote office. Those packets will have one ESP header throughout their life, for my end-to-end tunnel. For part of the route, however, they will also have another ESP layer for the corporate VPN's encapsulation. The whole header scheme for a packet on the Internet might be:

• IP header (with gateway address) says next header --> ESP
• ESP header [ says next --> IP
• IP header (with receiving machine address) says next header --> ESP
• ESP header [ says next --> TCP
• TCP header port number --> which process to send data to
• data ]]

The first ESP (outermost) header is for the corporate VPN. The inner ESP header is for the secure machine-to-machine link.

DHR on the updown script

Here are some mailing list comments from pluto(8) developer Hugh Redelmeier on an earlier draft of this document:

There are many important things left out

- firewalling is important but must reflect (implement) policy.  Since
  policy isn't the same for all our customers, and we're not experts,
  we should concentrate on FW and MASQ interactions with FreeS/WAN.

- we need a diagram to show packet flow WITHIN ONE MACHINE, assuming
  IKE, IPsec, FW, and MASQ are all done on that machine.  The flow is
  obvious if the components are run on different machines (trace the
  cables).

  IKE input:
        + packet appears on public IF, as UDP port 500
        + input firewalling rules are applied (may discard)
        + Pluto sees the packet.

  IKE output:
        + Pluto generates the packet & writes to public IF, UDP port 500
        + output firewalling rules are applied (may discard)
        + packet sent out public IF

  IPsec input, with encapsulated packet, outer destination of this host:
        + packet appears on public IF, protocol 50 or 51.  If this
          packet is the result of decapsulation, it will appear
          instead on the paired ipsec IF.
        + input firewalling rules are applied (but packet is opaque)
        + KLIPS decapsulates it, writes result to paired ipsec IF
        + input firewalling rules are applied to resulting packet
          as input on ipsec IF
        + if the destination of the packet is this machine, the
          packet is passed on to the appropriate protocol handler.
          If the original packet was encapsulated more than once
          and the new outer destination is this machine, that
          handler will be KLIPS.
        + otherwise:
          * routing is done for the resulting packet.  This may well
            direct it into KLIPS for encoding or encrypting.  What
            happens then is described elsewhere.
          * forwarding firewalling rules are applied
          * output firewalling rules are applied
          * the packet is sent where routing specified

 IPsec input, with encapsulated packet, outer destination of another host:
        + packet appears on some IF, protocol 50 or 51
        + input firewalling rules are applied (but packet is opaque)
        + routing selects where to send the packet
        + forwarding firewalling rules are applied (but packet is opaque)
        + packet forwarded, still encapsulated

  IPsec output, from this host or from a client:
        + if from a client, input firewalling rules are applied as the
          packet arrives on the private IF
        + routing directs the packet to an ipsec IF (this is how the
          system decides KLIPS processing is required)
        + if from a client, forwarding firewalling rules are applied
        + KLIPS eroute mechanism matches the source and destination
          to registered eroutes, yielding a SPI group.  This dictates
          processing, and where the resulting packet is to be sent
          (the destinations SG and the nexthop).
        + output firewalling is not applied to the resulting
          encapsulated packet

- Until quite recently, KLIPS would double encapsulate packets that
  didn't strictly need to be.  Firewalling should be prepared for
  those packets showing up as ESP and AH protocol input packets on
  an ipsec IF.

- MASQ processing seems to be done as if it were part of the
  forwarding firewall processing (this should be verified).

- If a firewall is being used, it is likely the case that it needs to
  be adjusted whenever IPsec SAs are added or removed.  Pluto invokes
  a script to do this (and to adjust routing) at suitable times.  The
  default script is only suitable for ipfwadm-managed firewalls.  Under
  LINUX 2.2.x kernels, ipchains can be managed by ipfwadm (emulation),
  but ipchains more powerful if manipulated using the ipchains command.
  In this case, a custom updown script must be used.

  We think that the flexibility of ipchains precludes us supplying an
  updown script that would be widely appropriate.

Linux FreeS/WAN Troubleshooting Guide

Overview

This document covers several general places where you might have a problem:

1. During install.
2. During the negotiation process.
3. Using an established connection.

This document also contains notes which expand on points made in these sections, and tips for problem reporting. If the other end of your connection is not FreeS/WAN, you'll also want to read our interoperation document.

1. During Install

1.1 RPM install gotchas

With the RPM method:

• Be sure you have installed both the userland tools and the kernel components. One will not work without the other. For example, when using FreeS/WAN-produced RPMs for our 1.98 release, you need both:

    freeswan-1.98_2.4.18_3custom-0.i386.rpm
    freeswan-module-1.98_2.4.18_3custom-0.i386.rpm

1.2 Problems installing from source

When installing from source, you may find these problems:

• Missing library. See this FAQ.
• Missing utilities required for compile. See this checklist.
• Kernel version incompatibility. See this FAQ.
• Another compile problem. Find information in the out.* files, ie. out.kpatch, out.kbuild, created at compile time in the top-level Linux FreeS/WAN directory. Error messages generated by KLIPS during the boot sequence are accessible with the dmesg command.
  Check the list archives and the List in Brief to see if this is a known issue. If it is not, report it to the bugs list as described in our problem reporting section. In some cases, you may be asked to provide debugging information using gdb; details below.
• If your kernel compiles but you fail to install your new FreeS/WAN-enabled kernel, review the sections on installing the patched kernel, and testing to see if install succeeded.

1.3 Install checks

ipsec verify checks a number of FreeS/WAN essentials. Here are some hints on what do to when your system doesn't check out:

service ipsec start

2. During Negotiation

When you fail to bring up a tunnel, you'll need to find out:

• what your connection state is, and often
• an error message.

before you can diagnose your problem .

2.1 Determine Connection State

Finding current state

You can see connection states (STATE_MAIN_I1 and so on) when you bring up a connection on the command line. If you have missed this, or brought up your connection automatically, use:

ipsec auto --status

The most relevant state is the last one reached.

What's this supposed to look like?

Negotiations should proceed though various states, in the processes of:

1. IKE negotiations (aka Phase 1, Main Mode, STATE_MAIN_*)
2. IPSEC negotiations (aka Phase 2, Quick Mode, STATE_QUICK_*)

These are done and a connection is established when you see messages like:

    000 #21: "myconn" STATE_MAIN_I4 (ISAKMP SA established)...
    000 #2: "myconn" STATE_QUICK_I2 (sent QI2, IPsec SA established)...

Look for the key phrases are "ISAKMP SA established" and "IPSec SA established", with the relevant connection name. Often, this happens at STATE_MAIN_I4 and STATE_QUICK_I2, respectively.

ipsec auto --status will tell you what states have been achieved, rather than the current state. Since determining the current state is rather more difficult to do, current state information is not available from Linux FreeS/WAN. If you are actively bringing a connection up, the status report's last states for that connection likely reflect its current state. Beware, though, of the case where a connection was correctly brought up but is now downed: Linux FreeS/WAN will not notice this until it attempts to rekey. Meanwhile, the last known state indicates that the connection has been established.

If your connection is stuck at STATE_MAIN_I1, skip straight to here.

2.2 Finding error text

Solving most errors will require you to find verbose error text, either on the command line or in the logs.

Verbose start for more information

Note that you can get more detail from ipsec auto using the --verbose flag:

    ipsec auto --verbose --up west-east

More complete information can be gleaned from the log files.

Debug levels count

The amount of description you'll get here depends on ipsec.conf debug settings, klipsdebug= and plutodebug=. When troubleshooting, set at least one of these to all, and when done, reset it to none so your logs don't fill up. Note that you must have enabled the klipsdebug compile-time option for the klipsdebug configuration switch to work.

For negotiation problems plutodebug is most relevant. klipsdebug applies mainly to attempts to use an already-established connection. See also this description of the division of duties within Linux FreeS/WAN.

After raising your debug levels, restart Linux FreeS/WAN to ensure that ipsec.conf is reread, then recreate the error to generate verbose logs.

ipsec barf for lots of debugging information

ipsec barf (8) collects a bunch of useful debugging information, including these logs Use the command

    ipsec barf > barf.west

to generate one.

Find the error

Search out the failure point in your logs. Are there a handful of lines which succinctly describe how things are going wrong or contrary to your expectation? Sometimes the failure point is not immediately obvious: Linux FreeS/WAN's errors are usually not marked "Error". Have a look in the FAQ for what some common failures look like.

Tip: problems snowball. Focus your efforts on the first problem, which is likely to be the cause of later errors.

Play both sides

Also find error text on the peer IPSec box. This gives you two perspectives on the same failure.

At times you will require information which only one side has. The peer can merely indicate the presence of an error, and its approximate point in the negotiations. If one side keeps retrying, it may be because there is a show stopper on the other side. Have a look at the other side and figure out what it doesn't like.

If the other end is not Linux FreeS/WAN, the principle is the same: replicate the error with its most verbose logging on, and capture the output to a file.

2.3 Interpreting a Negotiation Error

Connection stuck at STATE_MAIN_I1

This error commonly happens because IKE (port 500) packets, needed to negotiate an IPSec connection, cannot travel freely between your IPSec gateways. See our firewall document for details.

Other errors

Other errors require a bit more digging. Use the following resources:

• the FAQ . Since this document is constantly updated, the snapshot's FAQ may have a new entry relevant to your problem.
• our background document . Special considerations which, while not central to Linux FreeS/WAN, are often tripped over. Includes problems with packet fragmentation, and considerations for testing opportunism.
• the list archives. Each of the searchable archives works differently, so it's worth checking each. Use a search term which is generic, but identifies your error, for example "No connection is known for".
  Often, you will find that your question has been answered in the past. Finding an archived answer is quicker than asking the list. You may, however, find similar questions without answers. If you do, send their URLs to the list with your trouble report. The additional examples may help the list tech support person find your answer.
• Look into the code where the error is being generated. The pluto code is nicely documented with comments and meaningful variable names.

If you have failed to solve your problem with the help of these resources, send a detailed problem report to the users list, following these guidelines.

3. Using a Connection

3.1 Orienting yourself

How do I know if it works?

Test your connection by sending packets through it. The simplest way to do this is with ping, but the ping needs to test the correct tunnel. See this example scenario if you don't understand this.

If your ping returns, test any other connections you've brought u all check out, great. You may wish to test with large packets for MTU problems.

ipsec barf is useful again

If your ping fails to return, generate an ipsec barf debugging report on each IPSec gateway. On a non-Linux FreeS/WAN implementation, gather equivalent information. Use this, and the tips in the next sections, to troubleshoot. Are you sure that both endpoints are capable of hearing and responding to ping?

3.2 Those pesky configuration errors

IPSec may be dropping your ping packets since they do not belong in the tunnels you have constructed:

• Your ping may not test the tunnel you intend to test. For details, see our "I can't ping" FAQ.
• Alternately, you may have a configuration error. For example, you may have configured one of the four possible tunnels between two gateways, but not the one required to secure the important traffic you're now testing. In this case, add and start the tunnel, and try again.

In either case, you will often see a message like:

klipsdebug... no eroute

which we discuss in this FAQ.

Note:

• NAT and masquerading may have an effect on which tunnels you need to configure.
• When testing a tunnel that protects a multi-node subnet, try several subnet nodes as ping targets, in case one node is routing incorrectly.

3.3 Check Routing and Firewalling

If you've confirmed your configuration assumptions, the problem is almost certainly with routing or firewalling. Isolate the problem using interface statistics, firewall statistics, or a packet sniffer.

Background:

• Linux FreeS/WAN supplies all the special routing it needs; you need only route packets out through your IPSec gateway. Verify that on the subnetted machines you are using for your ping-test, your routing is as expected. I have seen a tunnel "fail" because the subnet machine sending packets out an alternate gateway (not our IPSec gateway) on their return path.
• Linux FreeS/WAN requires particular firewalling considerations. Check the firewall rules on your IPSec gateways and ensure that they allow IPSec traffic through. Be sure that no other machine - for example a router between the gateways - is blocking your IPSec packets.

View Interface and Firewall Statistics

Interface reports and firewall statistics can help you track down lost packets at a glance.

Check any firewall statistics you may be keeping on your IPSec gateways, for dropped packets.

Both cat /proc/net/dev and ifconfig display interface statistics, and both are included in ipsec barf. Use either to check if any interface has dropped packets. If you find that one has, test whether this is related to your ping. While you ping continuously, print that interface's statistics several times. Does its drop count increase in proportion to the ping? If so, check why the packets are dropped there.

To do this, look at the firewall rules that apply to that interface. If the interface is an IPSec interface, more information may be available in the log. Grep for the word "drop" in a log which was created with klipsdebug=all as the error happened.

See also this discussion on interpreting ifconfig statistics.

3.4 When in doubt, sniff it out

If you have checked configuration assumptions, routing, and firewall rules, and your interface statistics yield no clue, it remains for you to investigate the mystery of the lost packet by the most thorough method: with a packet sniffer (providing, of course, that this is legal where you are working).

In order to detect packets on the ipsec virtual interfaces, you will need an up-to-date sniffer (tcpdump, ethereal, ksnuffle) on your IPSec gateway machines. You may also find it useful to sniff the ping endpoints.

Anticipate your packets' path

Ping, and examine each interface along the projected path, checking for your ping's arrival. If it doesn't get to the the next stop, you have narrowed down where to look for it. In this way, you can isolate a problem area, and narrow your troubleshooting focus.

Within a machine running Linux FreeS/WAN, this packet flow diagram will help you anticipate a packet's path.

Note that:

• from the perspective of the tunneled packet, the entire tunnel is one hop. That's explained in this FAQ.
• an encapsulated IPSec packet will look different, when sniffed, from the plaintext packet which generated it. You can see plaintext packets entering an IPSec interface and the resulting cyphertext packets as they emerge from the corresponding physical interface.

Once you isolate where the packet is lost, take a closer look at firewall rules, routing and configuration assumptions as they affect that specific area. If the packet is lost on an IPSec gateway, comb through klipsdebug output for anomalies.

If the packet goes through both gateways successfully and reaches the ping target, but does not return, suspect routing. Check that the ping target routes packets back to the IPSec gateway.

3.5 Check your logs

Here, too, log information can be useful. Start with the guidelines above.

For connection use problems, set klipsdebug=all. Note that you must have enabled the klipsdebug compile-time option to do this. Restart Linux FreeS/WAN so that it rereads ipsec.conf, then recreate the error condition. When searching through klipsdebug data, look especially for the keywords "drop" (as in dropped packets) and "error".

Often the problem with connection use is not software error, but rather that the software is behaving contrary to expectation.

Interpreting log text

To interpret the Linux FreeS/WAN log text you've found, use the same resources as indicated for troubleshooting connection negotiation: the FAQ , our background document, and the list archives. Looking in the KLIPS code is only for the very brave.

If you are still stuck, send a detailed problem report to the users' list.

3.6 More testing for the truly thorough

Large Packets

If each of your connections passed the ping test, you may wish to test by pinging with large packets (2000 bytes or larger). If it does not return, suspect MTU issues, and see this discussion.

Stress Tests

In most users' view, a simple ping test, and perhaps a large-packet ping test suffice to indicate a working IPSec connection.

Some people might like to do additional stress tests prior to production use. They may be interested in this testing protocol we use at interoperation conferences, aka "bakeoffs". We also have a testing directory that ships with the release.

4. Problem Reporting

4.1 How to ask for help

Ask for troubleshooting help on the users' mailing list, users@lists.freeswan.org. While sometimes an initial query with a quick description of your intent and error will twig someone's memory of a similar problem, it's often necessary to send a second mail with a complete problem report.

The essay How to Report Bugs Effectively contains good guidelines.

When reporting problems to the mailing list(s), please include:

• a brief description of the problem
• if it's a compile problem, the actual output from make, showing the problem. Try to edit it down to only the relevant part, but when in doubt, be as complete as you can. If it's a kernel compile problem, any relevant out.* files
• if it's a run-time problem, pointers to where we can find the complete output from "ipsec barf" from BOTH ENDS (not just one of them). Remember that it's common outside the US and Canada to pay for download volume, so if you can't post barfs on the web and send the URL to the mailing list, at least compress them with tar or gzip.
  If you can, try to simplify the case that is causing the problem. In particular, if you clear your logs, start FreeS/WAN with no other connections running, cause the problem to happen, and then do ipsec barf on both ends immediately, that gives the smallest and least cluttered output.
• any other error messages, complaints, etc. that you saw. Please send the complete text of the messages, not just a summary.
• what your network setup is. Include subnets, gateway addresses, etc. A schematic diagram is a good format for this information.
• exactly what you were trying to do with Linux FreeS/WAN, and exactly what went wrong
• a fix, if you have one. But remember, you are sending mail to people all over the world; US residents and US citizens in particular, please read doc/exportlaws.html before sending code -- even small bug fixes -- to the list or to us.
• When in doubt about whether to include some seemingly-trivial item of information, include it. It is rare for problem reports to have too much information, and common for them to have too little.

4.2 Where to ask

To report a problem, send mail about it to the users' list. If you are certain that you have found a bug, report it to the bugs list. If you encounter a problem while doing your own coding on the Linux FreeS/WAN codebase and think it is of interest to the design team, notify the design list. When in doubt, default to the users' list. More information about the mailing lists is found here.

For a number of reasons -- including export-control regulations affecting almost any private discussion of encryption software -- we prefer that problem reports and discussions go to the lists, not directly to the team. Beware that the list goes worldwide; US citizens, read this important information about your export laws. If you're using this software, you really should be on the lists. To get onto them, visit lists.freeswan.org.

If you do send private mail to our coders or want a private reply from them, please make sure that the return address on your mail (From or Reply-To header) is a valid one. They have more important things to do than to unravel addresses that have been mangled in an attempt to confuse spammers.

5. Additional Notes on Troubleshooting

The following sections supplement the Guide: information available on your system; testing between security gateways; ifconfig reports for KLIPS debugging; using GDB on Pluto.

5.1 Information available on your system

Logs used

Linux FreeS/WAN logs to:

• /var/log/secure (or, on Debian, /var/log/auth.log)
• /var/log/messages

Check both places to get full information. If you find nothing, check your syslogd.conf(5) to see where your /etc/syslog.conf or equivalent is directing authpriv messages.

man pages provided

ipsec.conf(5)

Manual page for IPSEC configuration file.

ipsec(8)

Primary man page for ipsec utilities.

Other man pages are on this list and in

• /usr/local/man/man3
• /usr/local/man/man5
• /usr/local/man/man8/ipsec_*

Status information

ipsec auto --status

Command to get status report from running system. Displays Pluto's state. Includes the list of connections which are currently "added" to Pluto's internal database; lists state objects reflecting ISAKMP and IPsec SAs being negotiated or installed.

ipsec look

Brief status info.

ipsec barf

Copious debugging info.

5.2 Testing between security gateways

Sometimes you need to test a subnet-subnet tunnel. This is a tunnel between two security gateways, which protects traffic on behalf of the subnets behind these gateways. On this network:

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

you might name this tunnel sunset-sunrise. You can test this tunnel by having a machine behind one gateway ping a machine behind the other gateway, but this is not always convenient or even possible.

Simply pinging one gateway from the other is not useful. Such a ping does not normally go through the tunnel. The tunnel handles traffic between the two protected subnets, not between the gateways . Depending on the routing in place, a ping might

• either succeed by finding an unencrypted route
• or fail by finding no route. Packets without an IPSEC eroute are discarded.

Neither event tells you anything about the tunnel. You can explicitly create an eroute to force such packets through the tunnel, or you can create additional tunnels as described in our configuration document, but those may be unnecessary complications in your situation.

The trick is to explicitly test between both gateways' private-side IP addresses. Since the private-side interfaces are on the protected subnets, the resulting packets do go via the tunnel. Use either ping -I or traceroute -i, both of which allow you to specify a source interface. (Note: unsupported on older Linuxes). The same principles apply for a road warrior (or other) case where only one end of your tunnel is a subnet.

5.3 ifconfig reports for KLIPS debugging

When diagnosing problems using ifconfig statistics, you may wonder what type of activity increments a particular counter for an ipsecN device. Here's an index, posted by KLIPS developer Richard Guy Briggs:

Here is a catalogue of the types of errors that can occur for which
statistics are kept when transmitting and receiving packets via klips.
I notice that they are not necessarily logged in the right counter.
. . .

Sources of ifconfig statistics for ipsec devices

rx-errors:
- packet handed to ipsec_rcv that is not an ipsec packet.
- ipsec packet with payload length not modulo 4.
- ipsec packet with bad authenticator length.
- incoming packet with no SA.
- replayed packet.
- incoming authentication failed.
- got esp packet with length not modulo 8.

tx_dropped:
- cannot process ip_options.
- packet ttl expired.
- packet with no eroute.
- eroute with no SA.
- cannot allocate sk_buff.
- cannot allocate kernel memory.
- sk_buff internal error.


The standard counters are:

struct enet_statistics
{
        int        rx_packets;                /* total packets received */
        int        tx_packets;                /* total packets transmitted */
        int        rx_errors;                /* bad packets received */
        int        tx_errors;                /* packet transmit problems */
        int        rx_dropped;                /* no space in linux buffers */
        int        tx_dropped;                /* no space available in linux */
        int        multicast;                /* multicast packets received */
        int        collisions;

        /* detailed rx_errors: */
        int        rx_length_errors;
        int        rx_over_errors;                /* receiver ring buff overflow */
        int        rx_crc_errors;                /* recved pkt with crc error */
        int        rx_frame_errors;        /* recv'd frame alignment error */
        int        rx_fifo_errors;                /* recv'r fifo overrun */
        int        rx_missed_errors;        /* receiver missed packet */

        /* detailed tx_errors */
        int        tx_aborted_errors;
        int        tx_carrier_errors;
        int        tx_fifo_errors;
        int        tx_heartbeat_errors;
        int        tx_window_errors;
};

of which I think only the first 6 are useful.

5.4 Using GDB on Pluto

You may need to use the GNU debugger, gdb(1), on Pluto. This should be necessary only in unusual cases, for example if you encounter a problem which the Pluto developer cannot readily reproduce or if you are modifying Pluto.

Here are the Pluto developer's suggestions for doing this:

Can you get a core dump and use gdb to find out what Pluto was doing
when it died?

To get a core dump, you will have to set dumpdir to point to a
suitable directory (see ipsec.conf(5)).

To get gdb to tell you interesting stuff:
        $ script
        $ cd dump-directory-you-chose
        $ gdb /usr/local/lib/ipsec/pluto core
        (gdb) where
        (gdb) quit
        $ exit

The resulting output will have been captured by the script command in
a file called "typescript".  Send it to the list.

Do not delete the core file.  I may need to ask you to print out some
more relevant stuff.

Note that the dumpdir parameter takes effect only when the IPsec subsystem is restarted -- reboot or ipsec setup restart.

Linux FreeS/WAN Compatibility Guide

Much of this document is quoted directly from the Linux FreeS/WAN mailing list. Thanks very much to the community of testers, patchers and commenters there, especially the ones quoted below but also various contributors we haven't quoted.

Implemented parts of the IPsec Specification

In general, do not expect Linux FreeS/WAN to do everything yet. This is a work-in-progress and some parts of the IPsec specification are not yet implemented.

In Linux FreeS/WAN

Things we do, as of version 1.96:

• key management methods

  manually keyed

  using keys stored in /etc/ipsec.conf

  automatically keyed

  Automatically negotiating session keys as required. All connections are automatically re-keyed periodically. The Pluto daemon implements this using the IKE protocol.

• Methods of authenticating gateways for IKE

  shared secrets

  stored in ipsec.secrets(5)

  RSA signatures

  For details, see pluto(8) .

  looking up RSA authentication keys from DNS.

  Note that this technique cannot be fully secure until secure DNS is widely deployed.

• groups for Diffie-Hellman key negotiation

  group 2, modp 1024-bit

  group 5, modp 1536-bit

  We implement these two groups.

  In negotiating a keying connection (ISAKMP SA, Phase 1) we propose both groups when we are the initiator, and accept either when a peer proposes them. Once the keying connection is made, we propose only the alternative agreed there for data connections (IPsec SA's, Phase 2) negotiated over that keying connection.

• encryption transforms

  DES

  DES is in the source code since it is needed to implement 3DES, but single DES is not made available to users because DES is insecure.

  Triple DES

  implemented, and used as the default encryption in Linux FreeS/WAN.

• authentication transforms

  HMAC using MD5

  implemented, may be used in IKE or by by AH or ESP transforms.

  HMAC using SHA

  implemented, may be used in IKE or by AH or ESP transforms.

In negotiations, we propose both of these and accept either.

• compression transforms

  IPComp

  IPComp as described in RFC 2393 was added for FreeS/WAN 1.6. Note that Pluto becomes confused if you ask it to do IPComp when the kernel cannot.

All combinations of implemented transforms are supported. Note that some form of packet-level authentication is required whenever encryption is used. Without it, the encryption will not be secure.

Deliberately omitted

Things we deliberately omit which are required in the RFCs are:

• null encryption (to use ESP as an authentication-only service)
• single DES
• DH group 1, a 768-bit modp group

Since these are the only encryption algorithms and DH group the RFCs require, it is possible in theory to have a standards-conforming implementation which will not interpoperate with FreeS/WAN. Such an implementation would be inherently insecure, so we do not consider this a problem.

Anyway, most implementations sensibly include more secure options as well, so dropping null encryption, single DES and Group 1 does not greatly hinder interoperation in practice.

We also do not implement some optional features allowed by the RFCs:

• aggressive mode for negotiation of the keying channel or ISAKMP SA. This mode is a little faster than main mode, but exposes more information to an eavesdropper.

In theory, this should cause no interoperation problems since all implementations are required to support the more secure main mode, whether or not they also allow aggressive mode.

In practice, it does sometimes produce problems with implementations such as Windows 2000 where aggressive mode is the default. Typically, these are easily solved with a configuration change that overrides that default.

Not (yet) in Linux FreeS/WAN

Things we don't yet do, as of version 1.96:

• key management methods
  • authenticate key negotiations via local PKI server, but see links to user patches
  • authenticate key negotiations via secure DNS
  • unauthenticated key management, using Diffie-Hellman key agreement protocol without authentication. Arguably, this would be worth doing since it is secure against all passive attacks. On the other hand, it is vulnerable to an active man-in-the-middle attack.
• encryption transforms

Currently Triple DES is the only encryption method Pluto will negotiate.

No additional encryption transforms are implemented, though the RFCs allow them and some other IPsec implementations support various of them. We are not eager to add more. See this FAQ question.

AES, the successor to the DES standard, is an excellent candidate for inclusion in FreeS/WAN, see links to user patches.

• authentication transforms

No optional additional authentication transforms are currently implemented. Likely SHA-256, SHA-384 and SHA-512 will be added when AES is.

• Policy checking on decrypted packets

To fully comply with the RFCs, it is not enough just to accept only packets which survive any firewall rules in place to limit what IPsec packets get in, and then pass KLIPS authentication. That is what FreeS/WAN currently does.

We should also apply additional tests, for example ensuring that all packets emerging from a particular tunnel have source and destination addresses that fall within the subnets defined for that tunnel, and that packets with those addresses that did not emerge from the appropriate tunnel are disallowed.

This will be done as part of a KLIPS rewrite. See these links and the design mailing list for discussion.

Our PF-Key implementation

We use PF-key Version Two for communication between the KLIPS kernel code and the Pluto Daemon. PF-Key v2 is defined by RFC 2367.

The "PF" stands for Protocol Family. PF-Inet defines a kernel/userspace interface for the TCP/IP Internet protocols (TCP/IP), and other members of the PF series handle Netware, Appletalk, etc. PF-Key is just a PF for key-related matters.

PF-Key portability

PF-Key came out of Berkeley Unix work and is used in the various BSD IPsec implementations, and in Solaris. This means there is some hope of porting our Pluto(8) to one of the BSD distributions, or of running their photurisd(8) on Linux if you prefer Photuris key management over IKE.

It is, however, more complex than that. The PK-Key RFC deliberately deals only with keying, not policy management. The three PF-Key implementations we have looked at -- ours, OpenBSD and KAME -- all have extensions to deal with security policy, and the extensions are different. There have been discussions aimed at sorting out the differences, perhaps for a version three PF-Key spec. All players are in favour of this, but everyone involved is busy and it is not clear whether or when these discussions might bear fruit.

Kernels other than the latest 2.2.x and 2.4.y

We develop and test on Redhat Linux using the most recent kernel in the 2.2 and 2.4 series. In general, we recommend you use the latest kernel in one of those series. Complications and caveats are discussed below.

2.0.x kernels

Consider upgrading to the 2.2 kernel series. If you want to stay with the 2.0 series, then we strongly recommend 2.0.39. Some useful security patches were added in 2.0.38.

Various versions of the code have run at various times on most 2.0.xx kernels, but the current version is only lightly tested on 2.0.39, and not at all on older kernels.

Some of our patches for older kernels are shipped in 2.0.37 and later, so they are no longer provided in FreeS/WAN. This means recent versions of FreeS/WAN will probably not compile on anything earlier than 2.0.37.

2.2 and 2.4 kernels

FreeS/WAN 1.0

ran only on 2.0 kernels

FreeS/WAN 1.1 to 1.8

ran on 2.0 or 2.2 kernels
ran on some development kernels, 2.3 or 2.4-test

FreeS/WAN 1.9 to 1.96

runs on 2.0, 2.2 or 2.4 kernels

In general, we suggest the latest 2.2 kernel or 2.4 for production use.

Of course no release can be guaranteed to run on kernels more recent than it is, so quite often there will be no stable FreeS/WAN for the absolute latest kernel. See the FAQ for discussion.

Intel Linux distributions other than Redhat

We develop and test on Redhat 6.1 for 2.2 kernels, and on Redhat 7.1 or 7.2 for 2.4, so minor changes may be required for other distributions.

Redhat 7.0

There are some problems with FreeS/WAN on Redhat 7.0. They are soluble, but we recommend you upgrade to a later Redhat instead..

Redhat 7 ships with two compilers.

• Their gcc is version 2.96. Various people, including the GNU compiler developers and Linus, have said fairly emphatically that using this was a mistake. 2.96 is a development version, not intended for production use. In particular, it will not compile a Linux kernel.
• Redhat therefore also ship a separate compiler, which they call kgcc, for compiling kernels.

Kernel Makefiles have gcc as a default, and must be adjusted to use kgcc before a kernel will compile on 7.0. This mailing list message gives details:

Subject: Re: AW: Installing IPsec on Redhat 7.0
   Date: Thu, 1 Feb 2001 14:32:52 -0200 (BRST)
  From: Mads Rasmussen <mads@cit.com.br>
 
> From www.redhat.com/support/docs/gotchas/7.0/gotchas-7-6.html#ss6.1

cd to /usr/src/linux and open the Makefile in your favorite editor. You
will need to look for a line similar to this:

CC = $(CROSS_COMPILE)gcc -D__KERNEL__ -I$(HPATH)

This line specifies which C compiler to use to build the kernel. It should
be changed to:

CC = $(CROSS_COMPILE)kgcc -D__KERNEL__ -I$(HPATH)

for Red Hat Linux 7. The kgcc compiler is egcs 2.91.66. From here you can
proceed with the typical compiling steps.

Check the mailing list archive for more recent news.

SuSE Linux

SuSE 6.3 and later versions, at least in Europe, ship with FreeS/WAN included.

Here are some notes for an earlier SuSE version.

SuSE Linux 5.3

Date: Mon, 30 Nov 1998
From: Peter Onion <ponion@srd.bt.co.uk>

... I got Saturdays snapshot working between my two SUSE5.3 machines at home.

The mods to the install process are quite simple.  From memory and looking at
the files on the SUSE53 machine here at work....

And extra link in each of the /etc/init.d/rc?.d directories called K35ipsec
which SUSE use to shut a service down.

A few mods in /etc/init.d/ipsec  to cope with the different places that SUSE
put config info, and remove the inculsion of /etc/rc.d/init.d/functions and .
/etc/sysconfig/network as they don't exists and 1st one isn't needed anyway.

insert ". /etc/rc.config" to pick up the SUSE config info and use 

  if test -n "$NETCONFIG" -a "$NETCONFIG" != "YAST_ASK" ; then

to replace 

  [ ${NETWORKING} = "no" ] && exit 0

Create /etc/sysconfig  as SUSE doesn't have one.

I think that was all (but I prob forgot something)....

You may also need to fiddle initialisation scripts to ensure that /var/run/pluto.pid is removed when rebooting. If this file is present, Pluto does not come up correctly.

Slackware

Subject: Re: linux-IPsec: Slackware distribution
  Date:  Thu, 15 Apr 1999 12:07:01 -0700
  From:  Evan Brewer <dmessiah@silcon.com>

> Very shortly, I will be needing to install IPsec on at least gateways that
> are running Slackware. . . .

The only trick to getting it up is that on the slackware dist there is no
init.d directory in /etc/rc.d .. so create one.  Then, what I do is take the
IPsec startup script which normally gets put into the init.d directory, and
put it in /etc/rc.d and name ir rc.ipsec .. then I symlink it to the file
in init.d.  The only file in the dist you need to really edit is the
utils/Makefile, setup4:

Everything else should be just fine.

A year or so later:

Subject: Re: HTML Docs- Need some cleanup?
   Date: Mon, 8 Jan 2001
   From: Jody McIntyre <jodym@oeone.com>

I have successfully installed FreeS/WAN on several Slackware 7.1 machines.
FreeS/WAN installed its rc.ipsec file in /etc/rc.d.  I had to manually call
this script from rc.inet2.  This seems to be an easier method than Evan
Brewer's.

Debian

A recent (Nov 2001) mailing list points to a web page on setting up several types of tunnel, including IPsec, on Debian.

Some older information:

Subject: FreeS/WAN 1.0 on Debian 2.1
   Date: Tue, 20 Apr 1999
  From:  Tim Miller <cerebus+counterpane@haybaler.sackheads.org>

        Compiled and installed without error on a Debian 2.1 system
with kernel-source-2.0.36 after pointing RCDIR in utils/Makefile to
/etc/init.d.

        /var/lock/subsys/ doesn't exist on Debian boxen, needs to be
created; not a fatal error.

        Finally, IPsec scripts appear to be dependant on GNU awk
(gawk); the default Debian awk (mawk-1.3.3-2) had fatal difficulties.
With gawk installed and /etc/alternatives/awk linked to /usr/bin/gawk
operation appears flawless.

The scripts in question have been modified since this was posted. Awk versions should no longer be a problem.

Caldera

Subject: Re: HTML Docs- Need some cleanup?
   Date: Mon, 08 Jan 2001
   From: Andy Bradford <andyb@calderasystems.com>

On Sun, 07 Jan 2001 22:59:05 EST, Sandy Harris wrote:

>     Intel Linux distributions other than Redhat 5.x and 6.x 
>         Redhat 7.0 
>         SuSE Linux 
>             SuSE Linux 5.3 
>         Slackware 
>         Debian 

Can you please include Caldera in this list?  I have tested it since 
FreeS/Wan 1.1 and it works great with our systems---provided one 
follows the FreeS/Wan documentation. :-)

Thank you,
Andy

CPUs other than Intel

FreeS/WAN has been run sucessfully on a number of different CPU architectures. If you have tried it on one not listed here, please post to the mailing list.

Corel Netwinder (StrongARM CPU)

Subject: linux-ipsec: Netwinder diffs
Date: Wed, 06 Jan 1999
From: rhatfield@plaintree.com

I had a mistake in my IPsec-auto, so I got things working this morning.

Following are the diffs for my changes.  Probably not the best and cleanest way 
of doing it, but it works. . . . 

These diffs are in the 0.92 and later distributions, so these should work out-of-the-box on Netwinder.

Yellow Dog Linux on Power PC

Subject:  Compiling FreeS/WAN 1.1 on YellowDog Linux (PPC)
   Date:  11 Dec 1999
   From:  Darron Froese <darron@fudgehead.com>

I'm summarizing here for the record - because it's taken me many hours to do
this (multiple times) and because I want to see IPsec on more linuxes than
just x86.

Also, I can't remember if I actually did summarize it before... ;-) I'm
working too many late hours.

That said - here goes.

1. Get your linux kernel and unpack into /usr/src/linux/ - I used 2.2.13.
<http://www.kernel.org/pub/linux/kernel/v2.2/linux-2.2.13.tar.bz2>

2. Get FreeS/WAN and unpack into /usr/src/freeswan-1.1
<ftp://ftp.xs4all.nl/pub/crypto/freeswan/freeswan-1.1.tar.gz>

3. Get the gmp src rpm from here:
<ftp://ftp.yellowdoglinux.com//pub/yellowdog/champion-1.1/SRPMS/SRPMS/gmp-2.0.2-9a.src.rpm>

4. Su to root and do this: rpm --rebuild gmp-2.0.2-9a.src.rpm

You will see a lot of text fly by and when you start to see the rpm
recompiling like this:

Executing: %build
+ umask 022
+ cd /usr/src/redhat/BUILD
+ cd gmp-2.0.2
+ libtoolize --copy --force
Remember to add `AM_PROG_LIBTOOL' to `configure.in'.
You should add the contents of `/usr/share/aclocal/libtool.m4' to
`aclocal.m4'.
+ CFLAGS=-O2 -fsigned-char
+ ./configure --prefix=/usr

Hit Control-C to stop the rebuild. NOTE: We're doing this because for some
reason the gmp source provided with FreeS/WAN 1.1 won't build properly on
ydl.

cd /usr/src/redhat/BUILD/
cp -ar gmp-2.0.2 /usr/src/freeswan-1.1/
cd /usr/src/freeswan-1.1/
rm -rf gmp
mv gmp-2.0.2 gmp

5. Open the freeswan Makefile and change the line that says:
KERNEL=$(b)zimage (or something like that) to
KERNEL=vmlinux

6. cd ../linux/

7. make menuconfig
Select an option or two and then exit - saving your changes.

8. cd ../freeswan-1.1/ ; make menugo

That will start the whole process going - once that's finished compiling,
you have to install your new kernel and reboot.

That should build FreeS/WAN on ydl (I tried it on 1.1).

Subject: Re: FreeS/WAN, PGPnet and E-mail
   Date: Sat, 22 Jan 2000
   From: Darron Froese <darron@fudgehead.com>

on 1/22/00 6:47 PM, Philip Trauring at philip@trauring.com wrote:

> I have a PowerMac G3 ...

The PowerMac G3 can run YDL 1.1 just fine. It should also be able to run
FreeS/WAN 1.2patch1 with a couple minor modifications:

1. In the Makefile it specifies a bzimage for the kernel compile - you have
to change that to vmlinux for the PPC.

2. The gmp source that comes with FreeS/WAN (for whatever reason) fails to
compile. I have gotten around this by getting the gmp src rpm from here:

ftp://ftp.yellowdoglinux.com//pub/yellowdog/champion-1.1/SRPMS/SRPMS/gmp-2.0.2-9a.src.rpm

If you rip the source out of there - and place it where the gmp source
resides it will compile just fine.

FreeS/WAN no longer includes GMP source.

Mklinux

One user reports success on the Mach-based micro kernel Linux.

Subject: Smiles on sparc and ppc
   Date: Fri, 10 Mar 2000
   From: Jake Hill <jah@alien.bt.co.uk>

You may or may not be interested to know that I have successfully built
FreeS/WAN on a number of non intel alpha architectures; namely on ppc
and sparc and also on osfmach3/ppc (MkLinux). I can report that it just
works, mostly, with few changes.

Alpha 64-bit processors

Subject: IT WORKS (again) between intel & alpha :-)))))
   Date: Fri, 29 Jan 1999
   From: Peter Onion <ponion@srd.bt.co.uk>

Well I'm happy to report that I've got an IPsec connection between by intel & alpha machines again :-))

If you look back on this list to 7th of December I wrote...

-On 07-Dec-98 Peter Onion wrote:
-> 
-> I've about had enuf of wandering around inside the kernel trying to find out
-> just what is corrupting outgoing packets...
-
-Its 7:30 in the evening .....
-
-I FIXED IT  :-))))))))))))))))))))))))))))))))
-
-It was my own fault :-((((((((((((((((((
-
-If you ask me very nicly I'll tell you where I was a little too over keen to
-change unsigned long int __u32 :-)  OPSE ...
-
-So tomorrow it will full steam ahead to produce a set of diffs/patches against
-0.91 
-
-Peter Onion.

In general (there have been some glitches), FreeS/WAN has been running on Alphas since then.

Sun SPARC processors

Several users have reported success with FreeS/WAN on SPARC Linux. Here is one mailing list message:

Subject: Smiles on sparc and ppc
   Date: Fri, 10 Mar 2000
   From: Jake Hill <jah@alien.bt.co.uk>

You may or may not be interested to know that I have successfully built
FreeS/WAN on a number of non intel alpha architectures; namely on ppc
and sparc and also on osfmach3/ppc (MkLinux). I can report that it just
works, mostly, with few changes.

I have a question, before I make up some patches. I need to hack
gmp/mpn/powerpc32/*.s to build them. Is this ok? The changes are
trivial, but could I also use a different version of gmp? Is it vanilla
here?

I guess my only real headache is from ipchains, which appears to stop
running when IPsec has been started for a while. This is with 2.2.14 on
sparc.

This message, from a different mailing list, may be relevant for anyone working with FreeS/WAN on Suns:

Subject: UltraSPARC DES assembler
   Date: Thu, 13 Apr 2000
   From: svolaf@inet.uni2.dk (Svend Olaf Mikkelsen)
     To: coderpunks@toad.com

An UltraSPARC assembler version of the LibDES/SSLeay/OpenSSL des_enc.c
file is available at http://inet.uni2.dk/~svolaf/des.htm.

This brings DES on UltraSPARC from slower than Pentium at the same
clock speed to significantly faster.

MIPS processors

We know FreeS/WAN runs on at least some MIPS processors because Lasat manufacture an IPsec box based on an embedded MIPS running Linux with FreeS/WAN. We have no details.

Transmeta Crusoe

The Merilus Firecard, a Linux firewall on a PCI card, is based on a Crusoe processor and supports FreeS/WAN.

Motorola Coldfire

Subject: Re: Crypto hardware support
   Date: Mon, 03 Jul 2000
   From: Dan DeVault <devault@tampabay.rr.com>

.... I have been running
uClinux with FreeS/WAN 1.4 on a system built by Moreton Bay  (
http://www.moretonbay.com )  and it was using a Coldfire processor
and was able to do the Triple DES encryption at just about
1 mbit / sec rate.......  they put a Hi/Fn 7901 hardware encryption
chip on their board and now their system does over 25 mbit of 3DES
encryption........ pretty significant increase if you ask me.

Multiprocessor machines

FreeS/WAN is designed to work on SMP (symmetric multi-processing) Linux machines and is regularly tested on dual processor x86 machines.

We do not know of any testing on multi-processor machines with other CPU architectures or with more than two CPUs. Anyone who does test this, please report results to the mailing list .

The current design does not make particularly efficient use of multiprocessor machines; some of the kernel work is single-threaded.

Support for crypto hardware

Supporting hardware cryptography accelerators has not been a high priority for the development team because it raises a number of fairly complex issues:

• Can you trust the hardware? If it is not Open Source, how do you audit its security? Even if it is, how do you check that the design has no concealed traps?
• If an interface is added for such hardware, can that interface be subverted or misused?
• Is hardware acceleration actually a performance win? It clearly is in many cases, but on a fast machine it might be better to use the CPU for the encryption than to pay the overheads of moving data to and from a crypto board.
• the current KLIPS code does not provide a clean interface for hardware accelerators

That said, we have a report of FreeS/WAN working with one crypto accelerator and some work is going on to modify KLIPS to create a clean generic interface to such products. See this web page for some of the design discussion.

More recently, a patch to support some hardware accelerators has been posted:

Subject: [Design] [PATCH] H/W acceleration patch
   Date: Tue, 18 Sep 2001
   From: "Martin Gadbois" <martin.gadbois@colubris.com>
 
Finally!!
Here's a web site with H/W acceleration patch for FreeS/WAN 1.91, including
S/W and Hifn 7901 crypto support.

http://sources.colubris.com/

Martin Gadbois

Hardware accelerators could take performance well beyond what FreeS/WAN can do in software (discussed here ). Here is some discussion off the IETF IPsec list, October 2001:

 ... Currently shipping chips deliver, 600 mbps throughput on a single
 stream of 3DES IPsec traffic.  There are also chips that use multiple
 cores to do 2.4 gbps.  We (Cavium) and others have announced even faster
 chips. ... Mid 2002 versions will handle at line rate (OC48 and OC192)
 IPsec and SSL/TLS traffic not only 3DES CBC but also AES and arc4.

The patches to date support chips that have been in production for some time, not the state-of-the-art latest-and-greatest devices described in that post. However, they may still outperform software and they almost certainly reduce CPU overhead.

IP version 6 (IPng)

The Internet currently runs on version four of the IP protocols. IPv4 is what is in the standard Linux IP stack, and what FreeS/WAN was built for. In IPv4, IPsec is an optional feature.

The next version of the IP protocol suite is version six, usually abbreviated either as "IPv6" or as "IPng" for "IP: the next generation". For IPv6, IPsec is a required feature. Any machine doing IPv6 is required to support IPsec, much as any machine doing (any version of) IP is required to support ICMP.

There is a Linux implementation of IPv6 in Linux kernels 2.2 and above. For details, see the FAQ. It does not yet support IPsec. The USAGI project are also working on IPv6 for Linux.

FreeS/WAN was originally built for the current standard, IPv4, but we are interested in seeing it work with IPv6. Some progress has been made, and a patched version with IPv6 support is available. For more recent information, check the mailing list.

IPv6 background

IPv6 has been specified by an IETF working group. The group's page lists over 30 RFCs to date, and many Internet Drafts as well. The overview is RFC 2460. Major features include:

• expansion of the address space from 32 to 128 bits,
• changes to improve support for
  • mobile IP
  • automatic network configuration
  • quality of service routing
  • ...
• improved security via IPsec

A number of projects are working on IPv6 implementation. A prominent Open Source effort is KAME, a collaboration among several large Japanese companies to implement IPv6 for Berkeley Unix. Other major players are also working on IPv6. For example, see pages at:

• Sun
• Cisco
• Microsoft

The 6bone (IPv6 backbone) testbed network has been up for some time. There is an active IPv6 user group.

One of the design goals for IPv6 was that it must be possible to convert from v4 to v6 via a gradual transition process. Imagine the mess if there were a "flag day" after which the entire Internet used v6, and all software designed for v4 stopped working. Almost every computer on the planet would need major software changes! There would be huge costs to replace older equipment. Implementers would be worked to death before "the day", systems administrators and technical support would be completely swamped after it. The bugs in every implementation would all bite simultaneously. Large chunks of the net would almost certainly be down for substantial time periods. ...

Fortunately, the design avoids any "flag day". It is therefore a little tricky to tell how quickly IPv6 will take over. The transition has certainly begun. For examples, see announcements from NTT and Nokia. However, it is not yet clear how quickly the process will gain momentum, or when it will be completed. Likely large parts of the Internet will remain with IPv4 for years to come.

Interoperation with other IPsec implementations

The IPsec protocols are designed to allow interoperation between different implementations. Other sections of this documentation have more detail on:

• the IPsec protocol specifications
• parts of the protocols implemented or omitted in FreeS/WAN
• other implementations

FreeS/WAN does interoperate successfully with many other implementations. The ones we know about are listed below.

Of course "the devil is in the details" and the IPsec protocols have a lot of details. At least one critique has argued that the protocols should be simplified. Various of those details can and do cause difficulties for interoperation. Should you encounter such problems, please let us know via the mailing list. We will likely be able to help you, and your report may be useful both to other users and to the implementation teams.

Note: This file is updated often, whenever I notice an interesting interop report on the mailing list. If you are reading the version that ships with a FreeS/WAN release or is posted on the web, and what you need isn't here, consider downloading the latest snapshot to get the latest version of the doc. Perhaps I've added what you need since the last release.

There is additional information on interoperability testing in our web links section.

Interoperability problems

The IPsec RFCs are complex and include a number of optional features. There is considerable opportunity for even two correct, standard-conforming, implementations to disagree on details in a way that blocks interoperation. Errors in either implementation -- either misinterpretations of the standards or just bugs -- can also foul things up.

The commonest cause of problems, however, seems to be configuration errors. Any IPsec implementation is somewhat complex. It has to be; neither the networks it runs on nor the protocols it implements are simple. When you have two of them to deal with, the problem you face is not trivial.

That said, FreeS/WAN interoperates successfully with many other implementations. There is a list below, with configuration details provided by various users who have already solved these problems.

Possible problem areas

Known areas where problems may appear are:

• FreeS/WAN does not implement single DES because DES is insecure. Suggestions on what to do if the device you want to talk to has only DES are below.
• FreeS/WAN does not implement Diffie-Hellman group 1 (768-bit) because it is not clear that this is secure.
• The RFCs define two modes for IKE negotiations -- main mode and aggressive mode. Aggressive mode is slightly faster, but reveals more information to an eavesdropper. Specifically, it lets an eavesdropper know what identities are in use. FreeS/WAN does not implement aggressive mode, so any negotiation another implementation tries that way will fail.

In principle this should not be a problem since main mode support is required in all implementations and aggressive mode is optional. In practice, it is sometimes a problem. Some implementations default to aggressive mode unless you configure them for main mode.

• For automatic keying, the FreeS/WAN default is to provide perfect forward secrecy. We see no reason not to; this is more secure and costs little. Some other implementations, however, turn PFS off by default.

The PFS settings on the two ends must match. There is no provision in the protocol for negotiating whether to use PFS; you need to either set both ends to use it or set them both not to. For communication between FreeS/WAN and an implementation that has PFS off by default, you will have to change the setting on one end.

You can turn PFS off in FreeS/WAN with the pfs=no setting in ipsec.conf(5), but if possible we suggest you enable PFS on the other end instead. That is more secure.

• The IKE protocol allows several types of optional message. Two things happen which are allowed by the RFCs:
  • Some implementations send various optional messages.
  • FreeS/WAN ignores them.
  However, problems may arise if the other end relies on some expected effect of these messages. There are two FAQ questions dealing with this, one on the log message FreeS/WAN gives when ignoring optional payloads and one on the delete SA payload.
• IKE also allows an optional "commit bit" to be set on some messages. Some uses of this, especially by Windows 2000, have caused interoperation problems with FreeS/WAN. As of version 1.92, we have changed our handling of this -- we now ignore the bit instead of dropping the packet -- which should reduce such problems.

The general rule is that to interoperate with FreeS/WAN, the other implementation should be configured for:

• main mode
• triple DES encryption
• Diffie-Hellman Group 2 (1024-bit) or Group 5 (1536-bit)
• Perfect Forward Secrecy

This is possible for most implementations.

For a more detailed discussion of which parts of the IPsec specification FreeS/WAN implements, and reasons for that, see our compatibility document.

Documentation and terminology problems

Documentation can also pose problems for interoperation. The two implementations may use different terms for the same thing, or one may have features that the other does not support and therefore does not document. This can be quite confusing for the poor user who has to deal with both.

Known examples are:

• What I call a "shared secret" (e.g. in this section), the documentation for another implementation might call a "passphrase" or "pre-shared key".
• Some implementations specify a subnet as a range of IP addresses, for example 192.168.1.0-192.168.1.255 where we would use a subnet mask, e.g. 192.168.1.0/24 or 192.168.1.0/255.255.255.0. See our discussion of subnets.

If you encounter such problems, please report them to the users mailing list and I'll try to add some clarifying text on the FreeS/WAN side.

If it only works in one direction

A few users have encountered situations in which interoperation is fine when one end initiates, but fails if the other end starts the negotiation.

In such cases, you can set rekey=no in the FreeS/WAN connection description. This prevents FreeS/WAN from initiating re-keying of that connection, but it will still respond if the partner initiates.

Even if that trick solves your problem, please report the difficulty to the users mailing list. It is definitely supposed to work no matter who initiates.

"Clients" and "servers"

IPsec is a peer-to-peer protocol. The gateways on the two ends of an IPsec connection are peers, both doing the same thing. They could use identical software.

Despite this, various vendors produce products they call "clients" and others they call "servers". Typically, the "clients" do not support a subnet behind them. They are designed only to let a single remote machine connect. To get full IPsec with subnet support, you pay more for the "server version".

For example, the free version of PGPnet is only a "client"; for subnet support you need to purchase the product. Also, Windows 2000 Professional has only "client" IPsec. For subnet support you need to purchase the server version, or put Linux and FreeS/WAN on your gateways.

This difference does not cause interoperation problems as such. FreeS/WAN will happily interoperate with either a "client" or a "server" product, and will happily play either role itself, depending on how it is configured. In their marketing terms, FreeS/WAN acts as a "server" if you define a subnet behind the gateway, and as a "client" if you do not.

It does, however, often complicate things when users discover that the product they have will not do what they need because it is "only a client". Usually the only solutions are to upgrade to the "sever version" or to switch to a different product.

Systems that want to use single DES

Linux FreeS/WAN does not support single DES transforms. Neither Pluto's IKE connections nor KLIPS' IPsec connections can use DES. Since DES is insecure we do not, and will not at any future time, provide it.

DES is, unfortunately, a mandatory part of the IPsec standard. Despite that, we will not implement DES. We believe it is more important to provide security than to comply with a standard which has been subverted into allowing weak algorithms. See our history and politics section for discussion.

Some implementations may offer DES as the default. In such cases we urge you to change them to Triple DES. If this is not possible, for example because export laws prevent your vendor from offerring you adequate crytography, we urge you to complain vigorously to one or more of:

• your government, especially any department concerned with protecting citizens' privacy or your nation's communication infrastructure
• the vendor
• the embassy of the nation whose laws are problematic for you

Consider using FreeS/WAN instead. PCs are cheap and we deliver 3DES now.

FreeS/WAN does have DES code in it as a sort of historical accident, since we need it to implement our default (currently, our only) block cipher, Triple DES. However, since DES is insecure, we do not provide any interface to that code.

As a matter of project policy, we will not help anyone subvert FreeS/WAN to provide insecure DES encryption .

Patches to extend interoperability

Sometimes interoperation requires user-contributed patches or add-ons on the FreeS/WAN end. See this list of available patches.

In many cases, no patches to the actual IPsec code are required. The problem is to make FreeS/WAN recognise RSA keys stored in formats other than ours. Each such format needs either a patch to make FreeS/WAN understand that format or a utility to translate it to the FreeS/WAN format. For example, unmodified FreeS/WAN cannot use RSA keys generated by PGP or keys stored in X.509 certificates, but patches or utilities are available for both those formats.

Other patches do change the IPsec code, for example to add the AES cipher. Likely this patch will be incorporated into FreeS/WAN long before AES becomes important as an interoperaibility issue.

Note that with some patches, you might be giving up some security in exchange for interoperability. There are a number of "features" of IPsec which we do not implement (details) either because they directly reduce security or because they unnecessarily complicate things, thereby adding to security risks. Adding these "features" is not recommended..

Interop HowTo documents

The FreeS/WAN team does not have the resources to test with anything like the full range of other IPsec implementations out there. Fortunately, some of our users are doing a fine job of filling the gap by providing HowTo information:

• Hans-Jorg Hoxer's HowTo covering interoperation between any two of:
  • FreeS/WAN
  • Open BSD IPsec
  • Windows 98 with PGPnet
• Jean-Francois Nadeau's practical configurations document covers FreeS/WAN interoperation with
  • Windows 2000 IPsec
  • NAI PGPnet
  • IRE Safenet SoftPK.
• Oscar Delgado's page has a PDF document covering interop using X.509 certificates between FreeS/WAN and:
  • Windows 2000
  • PGPnet
• HowTo in German covering interoperation with:
  • Windows 2000
  • PGPnet
  • SSH Sentinel
• Terrandon Communications provide a PDF HowTO on using FreeS/WAN with IRE SafeNet
• Telenor provide a HowTo on FreeS/WAN and Windows 2000
• ForSite Solutions have a document in their GRIP (Guide for reasonably intelligent people) series covering FreeS/WAN, IRE on 98, and Windows 2000 IPsec. When I looked at it (July 2001), it was seriously incomplete, but had some good stuff.
• Ryan's HowTo for getting PGPnet to connect with FreeS/WAN using x509 certs through a Linksys router, with IPSec passthru enabled
• Nate Carlson has a HowTo document for FreeS/WAN with X.509 patch and Windows 2000

See also our lists of:

• available patches and add-ons.
• user-writtten FreeS/WAN-to-FreeS/WAN HowTo documents

Interop info from the IPsec 2001 conference

From a mailing list report:

     Subject: IPsec 2001 interop demo data available
        Date: Tue, 13 Nov 2001
        From: Ghislaine Labouret <Ghislaine.Labouret@hsc.fr>
Organization: HSC (Herve Schauer Consultants)

During the IPsec 2001 conference held in Paris last month, an
interoperability demonstration including FreeS/WAN was set up.

FreeS/WAN 1.91 + X.509 patch 0.9.3 was tested with the following
devices: 6WINDGate, Cisco IOS, Cisco PIX, Cisco VPN 3000, Netasq F100,
Netcelo VPN gateway, NetScreen NS100, Nortel Contivity, OpenBSD 3.0.

The results and configuration files are now available online:
http://www.hsc.fr/ipsec/ipsec2001/

Interoperation with specific products

Most of the information in this section is gleaned from the mailing list. For additional information, search one of the list archives.

A large thank you is in order to all the list contributors. This document would not exist without you.

Anyone who has tested with an implementation not listed here, please report results to the mailing list . I generally include the sender's email address when I quote list messages here; "credit where credit is due". If you would prefer that I not do that with yours, please mention that.

Older versions of FreeS/WAN

However, if you do encounter a problem involving an older version, we are likely to suggest you upgrade. We do not have the resources to support multiple versions.

Using your old config files

In general, new versions will use existing configuration files, at least until the next major version number change. For example, 1.8 can use files created for 1.7, 1.6, even back to 1.0, but not from 0.92. This behaviour will continue until we release 2.0.

As of 1.8, however, conf file checking has become stricter, so that an error that may have slipped past the checks in an earlier version may be caught in a later one. From 1.8's doc/CHANGES:

      The internal configuration-file reader is progressively getting 
      fussier about what it will accept, which may cause problems for 
      illegal ipsec.conf files whose sins previously passed unnoticed.  
      IN PARTICULAR, the "auto" parameter's values are now checked for 
      legality everywhere.

OpenBSD

Two user-written HowTos we know of cover interoperation between FreeS/WAN and Open BSD IPsec:

• Hans-Jorg Hoxer's HowTo
• Skyper's guide

The OpenBSD FAQ includes information on their IPsec implementation.

This report is from one of the OpenBSD IPsec developers, a regular participant on our mailing list:

Subject: spi.c bug
   Date: Tue, 23 Feb 1999
   From: Niklas Hallqvist <niklas@appli.se>

PS.  I don't know if you have an interop list anywhere, but you should
know FreeS/WAN interops with OpenBSD both at the IPSec level and at
the IKE level.

There is one known problem with FreeS/WAN-OpenBSD IKE interoperation. Here is a mailing message from our Pluto implementer, discussing that with the user who discovered it:

Subject: Re: [Bugs] Interoperability with OpenBSD
   Date: Sun, 30 Sep 2001

| Yes, the problem was the pre-shared key.  It seems that it cannot be
| more than 64 characters long.  I was using a longer key.
|
| Is this documented behaviour for either FreeS/WAN or isakmpd?  (Anyway
| a reasonable error message would not hurt.)

The limit is not in FreeS/WAN, so we don't document it :-)

I guess we could mention this on our interop pages.  Claudia?

The error message from isakmpd was not very helpful (I realize that
I'm in a glass house when I throw this stone).

- isamkpd documentation should state the limit

- isakmpd should diagnose that the PSK was too long

- isakmpd should suggest that this type of problem (undigestable
  message) might be caused by mis-matched PSK

I hope that you would have gotten a better message from Pluto.  So if
you had initiated from the isakmpd side, the resulting diagnostic from
Pluto might have lead you to the problem more quickly.

When Pluto cannot parse the first encrypted IKE message, it prints a
diagnosis of the parse failure (just like isakmpd did), but it prefixes it
with
        probable authentication (preshared secret) failure:

I just noticed that it will print this even if authentication is via
RSA Sig -- I will fix that.  I'll reword the prefix too:
        probable authentication failure (mismatch of preshared secrets?):

FreeBSD

FreeBSD uses the KAME IPsec and IPv6 code.

Here is a mailing list message on FreeBSD interoperation:

Subject: Re: Interop with [Free|Open|Net]BSD
   Date: Fri, 29 Dec 2000
   From: Ghislaine Labouret <Ghislaine.Labouret@hsc.fr>

On Thu, 28 Dec 2000 13:53:01 -0500, Sandy Harris wrote:

> FreeBSD:
> 
> For FreeBSD, I find list discussion of 3DES key formats, presumably for manual
> keying. We have 192-bit, 3 64-bit keys including parity bits, while FreeBSD 4.0
> used 168-bit, 3 56-bit keys without the parity bits. Has FreeBSD changed this?

I still don't understand what made Spike Gronim say that KAME wants a
168 bits key; I have always been using 192 bits keys with KAME and had
no interoperability problem between KAME and FreeS/WAN using manual
keying.

> For auto keying, I find reports of sucessful use of pre-shared secrets, but
> nothing on RSA authentication.

I had KAME (20001023 snapshot) and FreeS/WAN 1.6 successfully
interoperate using both PSK and RSA-sig authentication. The config
files, certificates and test keys used are available online:
http://www.hsc.fr/ipsec/ipsec2000/kame/
http://www.hsc.fr/ipsec/ipsec2000/freeswan/
Not much details though, as this is just a report and not a how-to. Will
improve it if I can find spare time.

> Does FreeBSD support that? 

KAME can use RSA-sig and can either exchange certificates online or get
them from a file. I tested the latter. No test with the X.509 patch for
FreeS/WAN yet, though that's in my short term plans too.

> Are the key formats compatible, or has anyone written translation code?

KAME wants the keys inside certificates, in PEM format. To extract the
keys for FreeS/WAN I used the fswcert utility, but it can be done "by
hand" using openssl.

NetBSD

NetBSD has an IPsec implementation based on KAME. It is described in this FAQ.

Cisco Routers

Information from Cisco

Useful pages on Cisco sites include:

• VPN support
• IPsec

To work with FreeS/WAN, a Cisco router must have 3DES software. A page on Cisco's site gives this list:

| Triple DES Encryption for IPSec
|
| ...
|
| This feature is supported only on the following platforms:
|
|     1720
|     2600 Series
|     3600 Series
|     4000 Series
|     4500 Series
|     AS5300 Series
|     7200 Series
|     7500 Series

From our mailing list

Our first Cisco interop success reports were from Ian Calderbank in 1999. They included configuration information for his Cisco 3640. These messages can be found in the mailing list archives or in older versions of this document, still available on the web. We no longer include them here.

Several other pages have possibly useful information:

• configuration files for FreeS/WAN 1.91, Cisco PIX and Cisco 2611 router
• mailing list message with subject "FreeS/WAN and Cisco 3030 VPN Concentrator" with an attached MS-Word document on the setup.
• A sample FreeS/WAN configuration, used in testing with Cisco at an interop conference, is in another list message. Unfortunately, it does not give the matching Cisco configuration.
• a short HowTo for interop between a Cisco 3360 and FreeS/WAN, using shared secrets

Shared secrets work

Several users report successful interoperation using shared secrets. Here is one such message:

Subject: [Users] cisco - freeswan summary
   Date: Fri, 31 Aug 2001 
   From: mcferren@colltech.com

I finally got a vpn linked up between a 3000 series cisco router and a
redhat linux box using shared secrets.  The linux box is running 2.2.19 with
freeswan 1.9. The shared secret has no spaces in it, as I read somewhere
that it might break the connection.

Several people have asked me the configuration that I have used to
make this happen, so I thought I should publish it here.  

Here is the network...

          host 172.11.251.34
             |
           -------------------  172.11.251.0/24
                   |
                linux router
                   |
           -------------------  172.11.252.0/24
                   |
                   |    172.11.252.2
              freeswan linux
                   |    xxx.xxx.xxx.85
                   |
                   |    xxx.xxx.xxx.1
                router
                   |
                INTERNET
                   |.
                router
                   |    yyy.yyy.yyy.1
                   |
                   |    yyy.yyy.yyy.21
               cisco router
                   |    10.25.5.1
                   |
           -------------------   10.25.5.0
             |
           host 10.25.5.44
           

My ipsec.conf looks like this...

config setup
        # THIS SETTING MUST BE CORRECT or almost nothing will work;
        # %defaultroute is okay for most simple cases.
        interfaces="ipsec0=eth0"
        # Debug-logging controls:  "none" for (almost) none, "all" for lots.
        klipsdebug=all
        plutodebug=none
        plutoload=%search
        plutostart=%search
        # Close down old connection when new one using same ID shows up.
        uniqueids=yes
 
# defaults for subsequent connection descriptions
conn %default
        # How persistent to be in (re)keying negotiations (0 means very).
        keyingtries=0
 
conn cisco1
        left=xxx.xxx.xxx.85
        leftnexthop=xxx.xxx.xxx.1
        leftsubnet=172.11.251.0/24
        right=yyy.yyy.yyy.21
        rightnexthop=yyy.yyy.yyy.1
        rightsubnet=10.25.5.0/24
        lifetime=8h
        auto=start

My cisco configuration looks like this...


crypto map VPN 30 ipsec-isakmp   
 set peer xxx.xxx.xxx.85
 set transform-set 3des-md5 
 match address 130

crypto ipsec transform-set 3des-md5 esp-3des esp-md5-hmac 

crypto isakmp key ******** address xxx.xxx.xxx.85 


crypto isakmp policy 3
 encr 3des
 hash md5
 authentication pre-share
 group 2

access-list 130 permit ip 10.25.5.0 0.0.0.255 172.11.251.0 0.0.0.255

Sorry it took so long to send this out, but there is apparently an ipchains
firewall on the host behind the cisco, and it took some time to get
these rules straight.

I hope this helps someone....

Subject: [Users] freeswan <--$gt; Cisco: success!
   Date: Thu, 20 Sep 2001
   From: "Wolfgang Tremmel" <w.tremmel@vianetworks.de>

I have seen several requests on the list for example
configurations for connection of Freeswan to Cisco, since
about 1 hour ago I had success, here my example configuration.

Background: My router is a 80486, connecting to the internet using
                PPPoE via DSL. Kernel is 2.4.9, Freeswan is snap2001sep13b
                And yes, I get a dynamic IP address

                Router is a Cisco 4700, running IOS 12.2(2)T1 with 3DES

ipsec.conf:
config setup
        interfaces="ipsec0=ppp0"
        klipsdebug=none
        plutodebug=none
        plutoload=%search
        plutostart=%search
        uniqueids=yes

conn %default
        keyingtries=0
        disablearrivalcheck=no

conn cisco
        type=tunnel
        left=%defaultroute
        leftsubnet=my.net.work.athome/29
        right=x.x.x.x                   # fastEthernet0 of ciscorouter
        rightnexthop=1.2.3.4            # next hop of ppp0
        rightsubnet=0.0.0.0/0           # defaultroute via ipsec
        keyexchange=ike
        authby=secret
        lifetime=8h
        pfs=yes

ipsec.secret:
%any x.x.x.x: PSK "thisisatestkey"

- ---- thats all on the linux router
- ---- now for the Cisco:

crypto isakmp policy 100
 encr 3des
 authentication pre-share
 group 2
 lifetime 3600
crypto isakmp key diesisteintest address y.y.0.0 255.255.0.0  !
network and mask of any possible address your ppp0 can have

crypto ipsec transform-set linuxbox esp-3des esp-sha-hmac

crypto dynamic-map linuxbox 100
 set transform-set linuxbox
 match address linuxbox

crypto map linuxbox local-address FastEthernet0
crypto map linuxbox isakmp authorization list linuxbox          ! not sure if
that is really needed
crypto map linuxbox 100 ipsec-isakmp dynamic linuxbox discover

interface FastEthernet0
 ip address x.x.x.x 255.255.255.192
 full-duplex
 crypto map linuxbox

ip access-list extended wtremmel
 permit ip host x.x.x.x my.net.work.athome mask


Wolfgang

RSA keys are tricky

A message from another user about using RSA keys with Cisco:

From: jrussi@uol.com.br
Subject: Re: [Users] RSA public key and Cisco (3640)
Date: Sat, 2 Jun 2001

We use Cisco IOS 12.1.5(T) and freeswan 1.8

Here an example on how I copied the key from cisco:

Key Data:
  117C311E 16192D86 8886C71D 11111115 11138B11 31881241 11C7E23B D6DB22 
  18DEC1BD....

Will become

0x117C311E16192D868886C71D1111111511138B113188124111C7E23BD6DB2218DEC1BD...  

We used at least 1024 bits long keys.

But it doesn´t matter. The problem is that cisco doesn´t agree with the RSA
schema from freeswan, I think. In Cisco, rsasig is to use with a CA, and
rsaencript did not work as well. 

My case is worse than it. My first intention was to use freeswan in a road
warrior config. I really need to use CA, as Cisco needs a fix address to
use rsa public key. The public key to cisco is always associated to an IP
address ou FQDN. I quit. Will try the X509 patch and the Open CA software.

Deyvi
>>(off list)
>
>Yes, I was just going to mention that the Cisco's key should be in
>ipsec.conf (just received your correction).
>
>I think that I have the Cisco side configured correctly ( I can't be sure
>because I can't test against the Freeswan).
>
>Starting from having the IPsec tunnel working with pre-share, I did the
>following on the Cisco side:
>
>#config t
>(config)# crypto key pubkey-chain rsa
>(config-pubkey-chain)# addressed-key 


>(config-pubkey-key)# key-string
>(config-pubkey-key)# 


>(config-pubkey-key)#quit
>(config-pubkey-chain)#exit
>
># config t
>(config)# crypto isakmp policy 1
>(config-isakmp)# no authentication pre-share
>(config-isakmp)# authentication rsa-sig
>(config-isakmp)# exit
>
>How long is your RSA key that was generated on the Cisco? I tried copying
>the key out of the 3640 and pasting it into ipsec.conf, removing the spaces
>and adding a '0x' in the front. I get the 'key too small' error still. What
>version of freeswan are you using?
>
>I'm using Freeswan 1.9 w/ IOS 12.1(6).

Cisco VPN Concentrator

Another mailing list thread discussed using FreeS/WAN with the Cisco VPN Concentrator. Here is one user describing his problem:

Subject: [Users] FreeSWAN and Cisco VPN CONCENTRATOR
   Date: Thu, 25 Oct 2001
   From: "M. Sticki" <msticki@web.de>

i have to establish a vpn tunnel between two companies.
one of the company is using the cisco vpn concentrator
and the other company is using redhat 7.1 and freeswan.

it is no a problem to estblish the tunnel between two freeswan
gateways or between a cisco vpn-client and the concentrator.

but the companies don't want to change their equipment.
and with this constellation i can't establish the tunnel.

the responce from cisco is: "THAT IS NOT SUPPORTED"

so this mailing list is my last chance, because i don't know how to go on

and another user's answer:

Subject: Re: [Users] FreeSWAN and Cisco VPN CONCENTRATOR
   Date: Thu, 25 Oct 2001 14:21:17 +0200
   From: Ghislaine Labouret <Ghislaine.Labouret@hsc.fr>

> i have to establish a vpn tunnel between two companies.
> one of the company is using the cisco vpn concentrator
> and the other company is using redhat 7.1 and freeswan.
[...]
> the responce from cisco is: "THAT IS NOT SUPPORTED"

At the IPsec 2001 conference which is behing held right now, we have
set up an interop demo platform which includes those two devices.
They are successfully interoperating using certificates.

Later in the same thread:

Subject: Re: [Users] FreeSWAN and Cisco VPN CONCENTRATOR
   Date: Thu, 25 Oct 2001
   From: Ghislaine Labouret <Ghislaine.Labouret@hsc.fr>
Organization: HSC (Herve Schauer Consultants)

Juri Jensen wrote:

> I've been trying to get those two to interoperate with certificates, but
> I have only succeeded with PSK. Can you shed some light on how you did
> it....?

I will put the config files and different tests results from the demo on
http://www.hsc.fr/ipsec/ipsec2001/ next week.

With VPN3000, we had a problem with the DN comparison because of
encoding issues. The solution was to specify the VPN 3000 DN in binary
format in ipsec.conf. I leave it to Andreas Steffen to explain the exact
issue, as he is the one who solved it.

Nortel (Bay Networks) Contivity switch

There is one known issue in FreeS/WAN-to-Contivity interoperation. Recent versions of FreeS/WAN no longer support DH group 1 for key exchange. Older versions of Contivity software support nothing else. Group 2 was added in more recent releases. So:

• older FreeS/WANs, such as 1.5, will work with any Contivity software. Key exchange will be done using DH Group 1. This may not be secure.
• current FreeS/WANs will work only with recent Contivity releases supporting DH Group 2. Contivity 3.5 is one such release.

We recommend using a current software on both ends.

Some messages from the mailing list:

Subject: Contivity Extranet Switch
   Date: Fri, 11 Jun 1999
   From: Matthias David Siebler <msiebler@nortelnetworks.com>
Reply-To: msiebler@alum.mit.edu
Organization: Nortel Networks

More interoperability results:

I successfully established a tunnel with a Nortel (formerly Bay (formerly New Oak)) Contivity
Extranet Switch running the latest release versions.

The CES is running V2.50 of the software and the Linux server is running V1.0.0 of the Free/SWAN
code on a RedHat 5.2 unit with the kernel upgraded to 2.0.36-3

I am using IKE with 3DES-HMAC-MD5

Note however, that tunnels cannot yet be configured as client tunnels since Free/SWAN does not yet
support aggressive mode.  Hopefully, that will arrive soon, which would allow remote users to
connect to a CES using the Free/SWAN code as clients.

and apparently Nortel want their product to work with FreeS/WAN:

Subject: Is FreeSwan 3.1 a legitamate ipsec implementation when compared to its commercial competitors?
   Date: Tue, 02 May 2000
   From: Bill Stewart <bill.stewart@pobox.com>

Nortel's Contivity IPsec server has a formal policy of interoperability
with FreeS/WAN.   I was quite pleased to hear it when they last talked to us,
and it makes sense in their business environment, since they let you use
their WinXX client software free, so this gives them support for Linux
clients.

A more recent mailing list report is:

Subject: Nortel Contivity and Free-S/WAN
   Date: Wed, 7 Mar 2001
   From:  "JJ Streicher-Bremer" <jj@digisle.net>

OK, here is a very brief nuts and bolts breakdown on how to get this
combo working.  I want to thank everyone at Free-S/WAN and everyone on
the list for your help in getting this to work.

Connecting FreeS/WAN to the Nortel Networks Contivity Extranet Switch:

What you need:
FreeS/WAN v1.5 and Contivity ver 2.5 - 3.5 (might work with earlier
versions, but I have not tested it with this config)
or
FreeS/WAN v1.8 and COntivity ver 3.5 (the 3.5 version supports Diffe
Hilman group 2 key exchange)

What to do:
1 - Configure the Contivity:
   Set up a branch office tunnel group with the following settings:
        
        Connectivity:
        Nailed Up: Disabled
        Access Hours: Anytime
        Call Admission Priority: Highest Priority
        Forwarding Priority: Low Priority
        Idle Timeout: 00:00:00
        Forced Logoff: 00:00:00
        RSVP: Disabled
        RSVP: Token Bucket Depth: 3000 Bytes
        RSVP: Token Bucket Rate: 28 Kbps
        Branch Office Bandwidth Policy: 
        - Committed Rate: 56 Kbps
        - Excess Rate: 128 Kbps
        - Excess Action: Mark

        Encryption: 
        - ESP - Triple DES with SHA1 Integrity: Enabled
        - ESP - Triple DES with MD5 Integrity: Enabled
        - ESP - 56-bit DES with SHA1 Integrity: Disabled
        - ESP - 56-bit DES with MD5 Integrity: Disabled
        *IKE Encryption and Diffie-Hellman Group: Triple DES with Group
2 (1024-bit prime)
        Vendor ID: Disabled
        Perfect Forward Secrecy: Enabled
        Compression: Disabled
        Rekey Timeout: 08:00:00
        Rekey Data Count:  (None) 
        *ISAKMP Retransmission Interval: 16
        *ISAKMP Retransmission Max Attempts: 4

        Set up a branch office tunnel inside this new group with the
following settings:
        
        Endpoint Addresses
        Local - Public address of your COntivity
        Remote - Your Free-S/WAN interface Address
                Tunnel Type - IPSEC
        IPSEC Authentication - Text Pre-Shared Key
                One note here, I have had some trouble trying to use HEX
or Non alphanumeric chars in this key.
        
        Under IP:
        Static Routing
        Local - networks you want to be able to access through the
tunnel
        Remote - networks that will be allowed through the tunnel
        NAT - None

   Get routing setup on your office network:
        You will need to get a routing entry that will point all traffic
bound for your home network (the one that will be acciessible through
the tunnel) to the internal interface of the contivity system.

   Configure Free-S/WAN:
        Install, compile, and test Free-S/WAN
        Edit ipsec.conf for your new tunnel:
--------------------------------------------------------        
ipsec.conf --
config setup
        interfaces="ipsec0=eth1"
        forwardcontrol=no
        klipsdebug=none
        plutodebug=none
        manualstart=
        plutoload=%search
        plutostart=%search
        plutowait=no
conn net1
        type=tunnel
        auto=start
        auth=esp
        authby=secret
        keyexchange=ike
        keylife=1h
        keyingtries=1
        pfs=yes
        left=10.0.0.2
        leftnexthop=10.0.0.1
        leftsubnet=10.0.1.0/24
        right=172.16.0.2
        rightsubnet=172.16.1.0/24
conn net2
        type=tunnel
        auto=start
        auth=esp
        authby=secret
        keyexchange=ike
        keylife=1h
        keyingtries=1
        pfs=yes
        left=10.0.0.2
        leftnexthop=10.0.0.1
        leftsubnet=10.0.1.0/24
        right=172.16.0.2
        rightsubnet=172.16.2.0/24

ipsec.secrets --
10.0.0.2 172.16.0.2 "Your big secret"
---------------------------------------------

The above config is for this imaginary network:

         +------+
10.0.1.1 |      |10.0.0.2   10.0.0.1++ Internet  
---------|      |-------------------++===========
         +------+            Home Router         
         Free-S/WAN host


Internet ++    172.16.0.2####         172.16.1.0/24 These
=========++--------------####---------172.16.2.0/24 are here somewhere
   Office Router       Contivity
   
   
   This has worked for me.  I am still having trouble with the tunnels
dying after about 30-40 minutes of non-use.  Don't know what that is
about, but I'll keep you posted.

Raptor Firewall

Raptor 5 on NT (old info)

   Subject: Interoperability with Raptor 5 (Success!)
   Date: Wed, 06 Jan 1999 16:19:27 -0500
   From: Chuck Bushong <chuckb@chandler-group.com>

I don't know if this is useful information for anyone, but I have
successfully established a VPN between RedHat 5.1 (kernel 2.0.34) running
FreeS/WAN 0.91 and NT4 running Raptor 5.  However, Pluto does not appear
compatible with the Raptor IKE implementation. . . .

Subject: RE: Interoperability with Raptor 5 (Success!)
Date: Thu, 28 Jan 1999 17:22:55 -0500
From: Chuck Bushong <chuckb@chandler-group.com> 

... this VPN (at least the klips end) has been up under minimal
utilization for three weeks plus without interruption.  The
machine seems very stable.  Pat yourself on the back, gentlemen.
Your beta release is more stable than certain companies' shipping
product.

Keep up the good work.

Raptor 6 on Solaris

Subject: Re: successful interop. with Raptor 6.02 
   From: "Charles G. Griebel" <cggrieb@biw.com> 
   Date: Tue, 25 Jul 2000

On Thu, Jul 20, 2000 at 12:04:40PM -0700, Kevin Traas wrote:
> Great!  I'm just about to start looking into this as well, so any
> docs/info you can provide would be *greatly* appreciated.  Immortalize
> yourself!  Get something written and added to the compatibility.html
> file.  Many will thank you.

Can't be that hard.  I'm just a freeswan newbie who hasn't even done a FS

FS
tunnel yet :)

Anyway, I hope you find this helpful.

Chock

-------------------------------------------------------------------------------

Automatically keyed 3DES VPN between Raptor 6.02 on Solaris 2.6 (left) and
   FreeS/WAN 1.5 on 2.2.16 Intel (right)

FreeS/WAN (right) information:
-----------------------------

ipsec.conf
----------
config setup
        interfaces="ipsec0=ppp0"    # change to suite
        klipsdebug=
        plutodebug=
        plutoload=sample
        plutostart=sample

conn sample
        left=10.0.0.1
        leftnexthop=10.0.0.2
        leftsubnet=192.168.0.0/24
        right=10.1.1.1
        rightnexthop=10.1.1.1
        rightsubnet=172.16.1.0/24
        auto=add
        keyexchange=ike
        pfs=no
        lifetime=8h
        esp=3des-md5-96

ipsec.secrets
-------------
# note I haven't verified that underscores will actually work
10.0.0.1 10.1.1.1: PSK "some_long_secret_with_plenty_of_chars"

Raptor 6.02 (left) information:
------------------------------
Key Profiles:
    Name: left-external-kp-dynamic
    Type: Dynamic
    Profile Describing: local entity
    Gateway: 10.1.1.1
    Identification Type: Address
    Identification: 10.1.1.1
    ISAKMP Hash Method: MD5
    ISAKMP Authentication: Shared_Key
    Shared Secret: some_long_secret_with_plenty_of_chars
    Time Expiration: 1080

    Name: right-external-kp-dynamic
    Type: Dynamic
    Profile Describing: remote entity
    Gateway: 10.0.0.1
    Identification Type: Address
    Identification: 10.0.0.1

Secure Subnets:
    Name: left-ss-dynamic
    Address: 192.168.0.0
    Netmask: 255.255.255.0
    Key Profile: left-ss-dynamic

    Name: right-ss-dynamic
    Address: 172.16.1.0
    Netmask: 255.255.255.0
    Key Profile: right-ss-dynamic

Secure Tunnel:
    Name: left-to-right-tunnel
    Entity A: right-ss-dynamic
    Entity B: left-ss-dynamic
    Encapsulation: ISAKMP
    Filter: [none]
    Pass traffic through proxies: [unchecked]
    Use Authentication Header: [unchecked]
    Use Encryption Header: [checked]
    Data Integrity Algorithm: MD5
    Data Privacy Algorithm: 3DES

    [Advanced settings]
    Data volume timeout: 2100000
    Lifetime timeout: 480
    Inactivity timeout: 0
    Transport mode: [unchecked]
    Perfect forward secrecy: [unchecked]
    Proxy: [checked]

----
Notes: 
I made the addresses fictitious RFC1918 addresses.
I haven't tried PFS.
I had problems getting an SA with manual keying -- I think it may be with the
 SPI's.

Raptor manual keying

A mailing list suggestion from FreeS/WAN technical lead Henry Spencer:

> In the Raptor settings, there are 2 sets of data (1 for each end). Each set
> contains an SPI, 3 DES Keys and 1 MD5 hash. I only know how to include one
> set, how do I include the other set? Is the other set needed?

They may be using different keys for each direction, which is a bit
unusual for manual keying, but not impossible.  The simplest thing is
probably to just give it two identical sets of data -- that should work.
FreeS/WAN has provisions for asymmetric keys etc. in manual keying, but
that stuff is lightly documented and lightly tested.

Gauntlet firewall GVPN

Subject:  Successful interop: FreeS/WAN 1.7 

 Gauntlet Firewall GVPN 5.5
   Date: Tue, 21 Nov 2000

Sending the following to the list, at Hugh's request.

-----Original Message-----
From: Reiner, Richard 
Sent: Tuesday, November 21, 2000 11:34 AM
To: 'hugh@mimosa.com'

Hugh,

> Good.  But we don't think that you should be using our IPCOMP just
> yet.  It is flaky :-(

I've seen no anomalies, although "allow ipcomp" is on at the Gauntlet 
end.  Looking at my ipsec.conf I actually find no refereence to ipcomp. 
 I presume it is disabled by default.  In addition, reviewing my logs 
both on the Gauntlet end and the Linux end, I see nothing I can 
interpret as an indication that ipcomp was enabled during negotiation.  
So I have to correct my previous posting - I believe the link is *not* 
using ipcomp.

> This is interesting and we'd love a more complete writeup.  It should
> get incorporated into our interop documentation.

Here are the relevant bits from ipsec.conf:

config setup
        interfaces=%defaultroute
        klipsdebug=none
        plutodebug=none
        plutoload=%search
        plutostart=%search
        uniqueids=yes

conn freeswan17-gauntlet55
        auto=start
        type=tunnel
        left=1.1.1.1
        leftnexthop=1.1.1.2
        leftsubnet=10.0.1.0/24
        right=3.3.3.3
        rightnexthop=3.3.3.4
        rightsubnet=10.0.2.0/24
        authby=secret
        keyexchange=ike
        ikelifetime=480m
        auth=esp
        esp=3des-md5-96
        keylife=480m
        keyingtries=8
        pfs=no
        rekeymargin=9m
        rekeyfuzz=25%

All settings on the Gauntlet side are the same (not shown here, as GUI 
screenshots are hard to show in ASCII... and the textual format that is 
generated by the Gauntlet GUI is ugly in the extreme).

Note that ikelifetime is 1440m by default on the Gauntlet end, but 
freeswan does not support this value (max appears to be 480m), thus the 
Gauntlet end is also set to 480m to match freeswan's value.

Also worth noting: I am using the excellent Seawall scripts to manage 
ipchains configuration on the freeswan end.  It automatically generates 
a correct set of firewall rules for the link (along with doing many 
other convenient things).

Checkpoint Firewall-1

A PDF HowTo for connecting FreeS/WAN and this product can be downloaded from the vendor's site or browsed at a VPN mailing list site.

A resource page full of Firewall-1 information.

The mailing list reports success with this combination, but also some problems. Search the archives for the full story.

Here is one message, about what seems to be the biggest problem:

Subject: Re: Pb establishing connection from FW1/3DES/SP2 with freeswan 1.5 - ACTE 2
   Date: Tue, 6 Feb 2001
   From: Claudia Schmeing <claudia@freeswan.org>
 
> Thanx to Michael and Claudia, but this doesn't work from VPN1 to linux (as
> linux to VPN1 is OK).
...

> I think that VPN1 doesn't send "192.168.1.0/24" but "192.168.1.20/32" and,
> as Claudia said, IPSEC SA need to match Exactly. 

I don't know about the rules on the VPN-1. You'll have to rely on people 
with applicable experience there...

> Is it possible that freeswan doesn't do the inclusion process (ie if he
> receive 192.168.1.20/32, i doesn't match that this is include in
> 192.168.1.0/24) ?

Yes, that's correct. It needs to match exactly, and inclusion is not
part of this process.
 
> Btw why VPN/1 send 192.168.1.20/32 and not 192.168.1.20/24 (the value that
> Freeswan is waiting for)? A bug?

I think Michael may be able to help you with this.

> Have i a way to force Freeswan to do the "inclusion" (ie accept 
> 192.168.1.20/32 as a part of 192.160.1.20/24, even if the 2 IPSEC Sa 
> doesn't match exactly) ?

No, but...
Another strategy is to accept the fact that the Checkpoint 
proposes separate connections for each machine. If you define 
and add each of these connections on the Linux FreeS/WAN side, then 
Linux FreeS/WAN ought to accept the Checkpoint's proposals.

The only possible difficulty with this strategy is that I don't know 
how Linux FreeS/WAN handles the concept of overlapping tunnels. I
believe, though, that these tunnels can coexist, and if for any 
packet there are two options, a more general and a less general, the
packet will be handled by the more specific tunnel. You would need
to do a little testing to ensure you understand the behaviour and
that this does actually solve your problem.

I think it would be simplest to try to get the Checkpoint to propose the 
more general tunnel. Since I don't recall having seen this problem before, 
I suspect the simpler solution is doable.

Redcreek Ravlin

We have reports of successful interoperation at an interop conference, but there is also a mailing list thread discussing difficulties some users have encountered.

SSH Sentinel

The vendor's web site has configuration examples for use with FreeS/WAN.

One user reports:

Subject: [Users] Very Useful document, can a link to it be put on the FreeS/WAN web site?
   Date: Fri, 19 Oct 2001
   From: Simon Matthews <simon@paxonet.com>

This is a very useful document on getting SSH Sentinel to work with 
FreeS/WAN using x509 certificates.
http://www.ssh.com/download_files/openssl_mini-ca.pdf

Perhaps a link to it could be put on the web site.

There is also another document on FreeS/WAN <> SSH Sentinel interoperability: http://www.ssh.com/products/sentinel/SSH_Sentinel_Config_Examples.pdf Simon 

The vendor seems serious about interop with us. Here is a message one of their staff posted on our list:

From: Jussi Torhonen <jt@ssh.com>
Organization: SSH Communications Security Corp - http://www.ssh.com
Subject: [Users] SSH Sentinel VPN client public beta #3 now available
Date: Thu, 31 May 2001

Hello, FreeS/WAN community !

SSH Communications Security Corp has released a new public beta #3
version of SSH Sentinel VPN client for Windows. We've got a lot of
reports also from FreeS/WAN community and with that feedback we've
improved interoperability and stability. 

For example PFS (Perfect Forward Secrecy in IKE rekey) can now be used
between SSH Sentinel and FreeSWAN, and if using that user contributed
X.509 patch and exporting the certificate from SSH Sentinel, now those
-----[BEGIN|END] CERTIFICATE----- headers/footers are properly included
in the exported PEM formatted certificate, so it can be imported to
FreeSWAN with fswcert utility and OpenSSL tools. 

Thank you a lot for your feedback, colleagues !

You can get that new public beta #3 and PDF formatted User Manual from
ftp://ftp.ssh.com/pub/sentinel/ or via website
http://www.ipsec.com/products/sentinel/beta/register.html

For more information about the product, please check our website
http://www.ipsec.com

We eagerly want to make SSH Sentinel as the best VPN client on the
market. If you want to contact our support, please send e-mail to
sentinel-support@ssh.com or fill up our feedback form at
http://www.ipsec.com/support/sentinel/beta_report.html

Best regards,
Jussi Torhonen, SSH Sentinel Team
Kuopio, Finland

There is one known problem withh SSH-FreeS/WAN interoperation, described in this message:

Subject: Re: [Users] Any plans for AES / Rijndael support ?
   Date: Tue, 11 Dec 2001
   From: Jussi Torhonen 


Organization: SSH Communications Security Corp - http://www.ssh.com

Markus Weber wrote:

> ... the installation
> of Sentinel don't let you set 3DES as the default!
> And when your want to add a connection the first
> diagnostic-test goes wrong ! :-( ...

In current SSH Sentinel release you can select 'Legacy proposal' option, 
  when setting up a VPN Connection profile. That causes it to use 3DES 
as a default cipher and DES as a alternative one. The option was added 
there just to improve interoperability with legacy systems supporting 
3DES or even DES only.

If no selecting Legacy Proposal option, SSH Sentinel sends quite a huge 
proposal list to the responder to find automatically one common cipher 
supported to be used for the connection. That proposal list is known to 
be problematic for some VPN gateway implementations like FreeSWAN. 
Typically the long proposal list itself may the a problem or fragmented 
packets of the long proposal list may be a probem.

Now we've been living in a world of DES and 3DES, but hopefully in a 
near future the use of AES/Rijndael will increase. ...

FreeS/WAN does not yet support AES.

F-Secure VPN for Windows

   Subject: Identification through other than IP number
   Date: Tue, 13 Apr 1999
   From: Thomas Bellman <bellman@signum.se>

... Currently we are trying to interop FreeS/WAN
with F-Secure VPN+ Client 4.0 (for MS Windows), and as long as
the Windows machine has a fix IP address, and are initiating the
IKE negotiations, things are working well.  However, when the IP
address is changing, it doesn't work. ...
(I'll try to write something up about the problems we are having
when Pluto is initiatior in another message.)

Watchguard

Watchguard make a Linux-based firewall product. Ipchains author Rusty Russell thanks them for support and recommends them in one of his HowTos. On the other hand, some comments on our mailing list about the Watchguard product have been quite unfavourable. See, for example, this archive message.

Watchguard do not use FreeS/WAN in their product. They have their own IPsec implementation.

We have had mailing list reports of successful interoperation between FreeS/WAN and the Watchguard firewall, using manually keyed connections. The user could not get automatically keyed connections to work; the message below explains this.

Here is some mail from a Watchguard employee about interoperation:

Subject: FreeS/WAN and WatchGuard Firebox interop
   Date: Mon, 18 Dec 2000
   From: Max Enders <menders@watchguard.com>

I was recently given the task of testing IPSec interoperability
with our product, the Firebox. I just wanted to let you know that
I had success with a manual keyed tunnel. Here's what I used for
my test:

RedHat Linux 6.2
Linux 2.2.18 i686 unknown
Linux FreeS/WAN 1.8
"Trusted" interface: 192.168.0.1/24
"External" interface: 192.168.1.1/24

Firebox II FastVPN
WatchGuard Live Security System v4.5
Trusted interface: 192.168.2.1/24
External interface: 192.168.1.2/24

Because FreeS/WAN does not implement single DES, a dynamic keyed
tunnel will not work. Our product strictly uses DES for main mode.
We hope to address this in a future release. Here are instructions
for configuring the Firebox:

Open the Policy Manager and create a new IPSec gateway. Set the Key
Negotiation Type to manual and enter the FreeS/WAN box's external
IP address for the Remote Gateway IP. Configure a new tunnel with
a unique SPI. Select 3DES-CBC for Encryption and MD5-HMAC for
Authentication. Make an Encryption Key and Authentication Key.
Copy the values and save them for configuration of the FreeS/WAN box.
Configure a routing policy and any necessary services as you normally
would.

Here's how I configured FreeS/WAN:

Modifications to /etc/ipsec.conf:

Under the "config setup" section, add:

manualstart=firebox

At the end of the file, add the following connection:

conn firebox
left=192.168.1.1
leftsubnet=192.168.0.0/24
right=192.168.1.2
rightsubnet=192.168.2.0/24
spi=0x101
esp=3des-md5-96
espenckey=0x515b0875793e3708517c3d4554012f7c0273375e51572a31
espauthkey=0x072649041c2c0d452f7c15407576522f

The spi used here should match the Firebox's. Note that the Policy Manager
expects an SPI in decimal, not hexadecimal. The espenckey value should be
0x and the Encryption Key you're using on the Firebox. Likewise for
espauthkey and the Authentication Key on the Firebox.

Subject: RE: Freeswan
   Date: Wed, 7 Feb 2001
   From: "Patrick Poncet" <pponcet@vaxxine.com>

It's working!!!

Voila...  I wish to thank all the FreeS/WAN for putting out such a great
product out!  And also Philippe PAULEAU who pioneered interoperability
between FreeS/WAN and Watchguard Firebox II and therefore showed me that my
efforts would not be wasted!...

Yes indeed FreeS/WAN to WatchGuard Firebox only works in manual keying mode
and the best way to generate keys is to have the firebox generate the keys,
then copy and paste into the ipsec.conf file on the FreeS/WAN side (don't
forget to prefix the keys with '0x' in your ipsec.conf file.

Also keep in mind that the SPI is in decimal on the Firebox side and HEX on
the FreeS/WAN side!!!  We spent 4 hours on fixing this HEX-DEC issue only :)

Xedia Access Point/QVPN

   Subject: Interoperability result
   Date: Mon, 15 Mar 1999 18:08:12 -0500
  From: Paul Koning <pkoning@xedia.com>

Here's another datapoint for the "FreeS/WAN interoperability
database".

I tested 0.92 against the Xedia Access Point/QVPN product, using
dynamic keying (i.e., Pluto at work).

Results: it works fine so long as you ask for 3DES.  DES and no-crypto 
modes don't work when Pluto is involved.

I did limited data testing, which seemed to be fine.  No performance
numbers yet, could do that if people are interested.

Any questions, please ask.

        paul

PGP Mac and Windows IPsec client (PGPnet)

McAfee VPN Client

From version 6.5 (1999) on, the PGP products from PGP Inc. included an IPsec client program called PGPnet.

The parent company, NAI, have since re-organised their product line. They no longer sell PGP (it was put into maintenance in February 2002) and the IPsec product is now called McAfee VPN Client

Here is the first message about PGPnet to our mailing list, from a senior PGP employee:

   Subject: PGPnet interoperable with FreeSWAN
   Date: Mon, 05 Apr 1999 18:06:13 -0700
   From: Will Price <wprice@cyphers.net>

Network Associates announced PGP 6.5 today.  It includes a new product
PGPnet which is a full IKE/IPSec client implementation.  This product
is for Windows and Macintosh.  I just wanted to send a brief note to
this list that the product was compatibility tested with FreeSWAN
prior to its release, and the tests were successful!
[snip]
- -- 
Will Price, Architect/Sr. Mgr., PGP Client Products
Total Network Security Division
Network Associates, Inc.

One version is downloadable at no cost for non-commercial use. See our links. That version does not support subnets.

Several of the user-written HowTos mentioned above cover interoperation between PGPnet and FreeS/WAN.

A more recent post from the same PGP Inc staff member pointed out:

Make sure you're using PGP 7.0 or later as the key parser was improved
in that release.  (PGP 7.0.1 was just released)

Various users have reported various successes and problems talking to PGPnet with FreeS/WAN. There has also been a fairly complex discussion of some fine points of RFC interpretation between the implementers of the two systems. Check an archive of our mailing list for details.

A post summarising some of this, from our Pluto programmer:

   Subject: PGPnet 6.5 and freeswan
   Date: Sun, 16 Jan 2000
   From: "D. Hugh Redelmeier" <hugh@mimosa.com>

| From: Yan Seiner
|
| OK, I'm stumped.  I am trying to configure IPSEC to support road
| warriors using PGPnet 6.5.
| 
| I've set up everything as per the man pages on the ipsec side.
| 
| I've set up everything on the PGPnet side per the docs for that package.
| 
| Pluto fails with this:
| 
| Jan 16 08:14:11 aphrodite Pluto[26401]: "homeusers" #8: no acceptable
| Oakley Transform
| 
| and then it terminates the connection.

As far as I can tell/remember, there are three common ways that PGPnet
and FreeS/WAN don't get along.

1. PGPnet proposes a longer lifetime for an SA than Pluto is willing
   to accept.

2. After rekeying (i.e. after building a new SA bundle because the old
   one is about to expire), FreeS/WAN immediately switches to the new
   one while PGPnet continues using the old

3. FreeS/WAN defaults to expecting Perfect Forward Secrecy and PGPnet
   does not.

Perhaps you are bumping into the first.  In any case, look back
in the log to see why Pluto rejected each transform

Some advice from the mailing list:

   Subject: Re: Secure Gate Fails- PGPNet & FreeSwan
   Date: Wed, 28 Jun 2000
   From: Andreas Haumer <andreas@xss.co.at>

I have a PGPnet setup running with FreeS/WAN working as secure 
gateway. It works quite fine, except for a re-negotiation problem 
I'm currently investigating, and in fact I have it running on some
test equipment here right now!

As I tried _several_ different non-working configuration settings 
I think I know the exact _one_ which works... :-)

Here's my short "HOWTO":

FreeS/WAN version: snap1000jun25b
PGPnet: PGP Personal Privacy, Version 6.5.3
Linux: 2.2.16 with some patches

Network setup:
=============

internal subnet [192.168.x.0/24]
|
|        [192.168.x.1]
secure gateway with FreeS/WAN
|        [a.b.c.x]
|
|        [a.b.c.y]
router to internet
|
|   Internet
|
|        [dynamically assigned IP address]
road-warrior with PGPnet


Configuration of FreeS/WAN:
==========================

a) /etc/ipsec.conf

config setup
        interfaces=%defaultroute
        klipsdebug=none
        plutodebug=none
        plutoload=%search
        plutostart=%search

conn %default
        keyingtries=1
        authby=secret
        left=a.b.c.x
        leftnexthop=a.b.c.y

conn gw-rw
        right=0.0.0.0
        auto=add

conn subnet-rw
        leftsubnet=192.168.x.0/24
        right=0.0.0.0
        auto=add                          


b) /etc/ipsec.secrets

a.b.c.x 0.0.0.0: "my very secret secret"   


Note: If you are running ipchains on your secure gateway,
you have to open the firewall for all the IPsec packets 
and also for traffic from your ipsec interface!
Don't masquerade the IPsec traffic!

Check your logfiles if the firewall is blocking some 
important packets!


Configuration of PGPnet:
=======================

(note that there is an excellent description, including
screenshots of PGPnet, on <http://jixen.tripod.com/>)

In short, do the following:

Launch the PGPnet configuration tool and set defaults options
=============================================================

Start - Program - PGP - PGPnet
View - Options
General Panel :
  Expert Mode
  Allow communications with unconfigured hosts
  Require valid authentication key
  Cache passphrases between logins
  IKE Duration : 6h
  IPsec : 6h
Advanced panel :
  Selected options :
    Ciphers : Tripple DES
    Hashes : MD5
    Diffie-Hellman : 1024 and 1536
    Compression : LZS and Deflate
  Make the IKE proposal :
    Shared-Key - MD5 - 3DES -1024 bits on top of the list (move up)
  Make the IPSec proposal :
    NONE - MD5-TrippleDES -NONE on top of the list (move up)
  Select Perfect Forward Secrecy = 1024 bits
Press OK


Create the connection's definition.
==================================

In the Hosts panel, ADD
  Name : Enter a name for the right gateway
  IPaddress : Enter its IP address visible to the internet (a.b.c.x)
  Select Secure Gateway
  Set shared Paraphrase : enter you preshared key
  Identity type : select IP address
  Identity : enter 0.0.0.0
  Remote Authentication : select Any valid key
Press Ok
  Select the newly created entry for the right gateway and click ADD,
YES
  Name : Enter a name for the central subnet
  IP address : Enter its network IP address (192.168.x.0)
  Select Insecure Subnet
  Subnet Mask : enter its subnetmask (255.255.255.0)
Press OK, YES, YES                             


This should be it. Note that with this configuration there is
still this re-keying problem: after 6 hours, the SA is expired
and the connection fails. You have to re-connect your connection
with PGPnet.

and a note from the team's tech support person:

Date: Thu, 29 Jun 2000
From: Claudia Schmeing 

There is a known issue with PGPNet which I don't see mentioned in the docs.
It's likely related to this one, that you note on the site:

>2. After rekeying (i.e. after building a new SA bundle because the old
>   one is about to expire), FreeS/WAN immediately switches to the new
>   one while PGPnet continues using the old

The issue is: When taking down and subsequently recreating a connection, 
it can appear to come up, but it is unusable because PGPNet continues
to use an old SA, which Linux FreeS/WAN no longer recognizes. The solution is
to take down the old connection using PGPNet, so that it will then
use the most recently generated SA.

IRE Safenet/SoftPK

IRE have an extensive line of IPsec products, including firewall software with IPsec, and hardware encryption devices for LAN or modem links. Their Soft-PK is a Win 98 and NT client. Quite a few people have used this with FreeS/WAN and, judging by mailing list reports, have had good results.

SoftRemote is newer product integrating the IPsec client with personal firewall software. As yet, we have few reports on this. One is quoted below.

SoftPK

Several documents are available:

• PDF HowTo titled FreeS/WAN 1.8 <--> IRE Safenet SoftPK 5.1.0 Road-Warrior VPN Configuration Guide from Terradon Communications.
• PDF document from Red Baron Consulting.
• IRE-to-FreeS/WAN section of Jean-Francois Nadeau's configuration document

Some messages from the mailing list:

Subject: Re: Identification through other than IP number
Date:  Fri, 23 Apr 1999
From:  Tim Miller <cerebus+counterpane@haybaler.sackheads.org>

Randy Dees writes:

 > Anyone know of a low-cost MS-Win client that interoperates and does not
 > require purchasing a server license to get it?  

        SafeNet/Soft-PK from IRE (http://www.ire.com) is a low-cost
client (though I don't have the exact cost available at the moment).
I've got it running on an NT4 workstation and it interoperates nicely
(in transport mode, will try tunnel later) with FreeS/WAN.  It's also
ICSA IPsec certified.

A later report with some setup details:

Subject: RE: PGPnet and Freeswan one more time...
   Date: Sat, 16 Dec 2000
  From: "Tim Wilson" <timwilson@mediaone.net>

Here are some details about using the IRE SafeNet Soft/PK client with a
FreeSwan gateway.

I applied the x509 patch to Pluto according to the instructions. I use the
"leftcert" and "rightcert" keywords in the ipsec.conf file. This causes
FreeSwan to read the public keys and identities from the cert files. The
identities wanted and used by FreeSwan will then be the DNs in the certs.

I used OpenSSL to generate keys and certs and to sign certs. When generating
the gateway cert, you should *not* enter an e-mail address because it turns
out that confuses Soft/PK. Also, Andreas Steffan tells me that you want to
keep the cert short to avoid fragmentation, so use a 1024-bit RSA key and
succinct names.

The FreeSwan gateway cert goes in /etc/ipsec.d/, the gateway private key is
extracted from the key file using fswcert (part of the x509 patch) and
pasted into /etc/ipsec.secrets, and a DER version of the gateway cert goes
in /etc/x509cert.der. This is all according to the instructions that
accompany the x509 patch.

The Windows client is of course running Soft/PK in this case. I generated a
private key and cert for the client on the Linux machine using OpenSSL. I
created a pkcs12 file containing the client's private key and cert, which I
put on a floppy and imported into Soft/PK. I also imported the gateway cert
into Soft/PK (you can either import a self-signed cert for the gateway or
the self-signed cert for the CA that signed the gateway cert--either works).

Soft/PK allows you to configure practically everything for the connection.
Here are the main points to watch for:

On the first panel you have to set the peer identities. The gateway will
identify itself using the DN in the gateway cert. So of course you have to
configure Soft/PK to look for the correct DN. There's no problem with this
as long as you didn't enter an e-mail address in the gateway cert. Just
check "Connect using Secure Gateway tunnel", set ID type to "Distinguished
Name", and enter the correct info in the dialog box.

In "My identity" just select the client cert that you imported in pcks12
format. Soft/PK apparently identifies itself with the DN from the cert,
which is exactly what FreeSwan is looking for.

In "Security Policy", you want Main mode and make the PFS setting agree with
whatever FreeSwan is doing (FreeSwan uses PFS by default). If you use PFS I
believe you must use DH group 2 as FreeSwan doesn't like group 1.

Phase 1 Authentication must be "RSA signatures" and 3DES plus either MD5 or
SHA-1 (I used MD5 but I believe FreeSwan accepts either). I left the
lifetime unspecified. Also you must select DH group 2 because I believe that
FreeSwan will not accept group 1.

Phase 2 also must use 3DES and MD5 or SHA-1. I used no compression and only
ESP and no AH, haven't tried other choices.

Hope this helps.

SoftRemote

Here is a mailing list message reporting experience with the newer SoftRemote product.

From: Whit Blauvelt <whit@transpect.com>
Subject: Re: [Users] RE: SafeNet SoftRemote 6.1 - FS 1.91 - HOW?
Date: Fri, 16 Nov 2001

Things I've learned in getting SoftRemote working with FreeS/WAN:

Using SoftRemote on dial-in, if there is any configuration adjustment for
which you stop and start FreeS/WAN, SoftRemote is totally lost until you
disconnect and dial in again. The SoftRemote "Disconnect All" and subsequent
"Reload Polilcies" options that show when right-clicking its icon in the
tray do not fix this - the only thing I've found that works is hanging up
and then redialing. This makes debugging a total pain, especially if you
think you're testing your changes, because you're not. 

Not sure if this affects fixed IP connections from SoftRemote, or what the
effective equivalent to hanging up and dialing in again would be to clear
the problem there if it exists.

Also, as I noted before: In configuring SoftRemote, there are a couple of
new menu options that Soft-PK didn't have, just in case you're following
examples given for that. Importantly, in setting the "Remote Party Identity
and Addressing" choose "IP subnet" rather than "IP", and be sure to provide
a mask which matches the subnet mask for that conn in ipsec.conf (e.g.
255.255.255.0 and /24). 

Much of the infornation available above for the earlier SoftPK product should also apply to SoftRemote.

Borderware

Freegate

Subject: ipsec interoperability FYI
   Date: Sun, 02 May 1999
   From: Sean Rooney <sean@coldstream.ca>

we've been doing some basic interoperability testing of the following; 

PGP NT VPN 6.5 and freeswan both seem to work reasonably well with 
Borderware 6.0 and freegate 1.3 beta. [as well as eachother] 

more details coming soon.

Timestep

   Subject: TimeStep Permit/Gate interop works!
   Date: Thu, 10 Jun 1999
   From: Derick Cassidy <dcthebrain@geek.com>

Just a quick note of success.  TimeStep Permit/Gate (2520) and
Free/Swan (June 4th snapshot) interoperate!

I have them working in AUTO mode, with IKE.  IPSec SA's are negotiated
with 3DES and MD5.

Here are the configs and a diagram for both configs.

left subnet---| Timestep | --- internet --- | Linux box |

The left subnet is defined as the red side of the timestep box.
 This network definition MUST exist in the Secure Map.

On the Linux box:

ipsec.conf

conn timestep
        type=tunnel
        left=209.yyy.xxx.6
        leftnexthop=209.yyy.xxx.1
        leftsubnet=209.yyy.xxx.128/25
        right=24.aaa.bbb.203
        rightnexthop=24.aaa.bbb.1
        rightsubnet=24.aaa.bbb.203/32
        keyexchange=ike
        keylife=8h
        keyingtries=0

In the TimeStep permit/gate Secure Map

begin static-map
        target "209.yyy.xxx.128/255.255.255.128"
        mode   "ISAKMP-Shared"
        tunnel "209.yyy.xxx.6"
end

In the TimeStep Security Descriptor file

begin security-descriptor
        Name    "High"
        IPSec   "ESP 3DES MINUTES 300 or ESP 3DES HMAC MD5 MINUTES 300"
        ISAKMP  "IDENTITY PFS 3DES MD5 MINUTES 1440
                                or DES MD5 MINUTES 1440"
end

The timestep has a shared secret for 24.aaa.bbb.203/255.255.255.255
set in the Shared Secret Authentication tab of Permit/Config.

Shiva/Intel LANrover

A web page with Shiva compatibility information.

Sun Solaris

   Subject: Re: FreeS/WAN and Solaris
   Date: Tue, 11 Jan 2000
   From: Peter Onion <Peter.Onion@btinternet.com>

Slowaris 8 has a native (in kernel) IPSEC implementation.

I've not done much interop testing yet, but I seem to rememeber we got a manual
keyed connection between it and FreeSwan a few months ago.

Sonicwall

Subject: Re: FreeS/WAN and SonicWall
     Date: Mon, 5 Feb 2001
     From: "Dilan Arumainathan" <dilan_a@impark.com>

***************************************************
I know I HAVE TO write the mini-howto - but here is the beginning
***************************************************

Here is my Sonicwall configuration for my working connection:

conn testauto
        left=x.x.x.x
        leftnexthop=x.x.x.x
        right=y.y.y.y
        rightnexthop=y.y.y.y
        rightsubnet=10.1.20.0/24
#You need to set the Unique Firewall Identifier to the parameter that you
#use as the rightid. <------IMPORTANT
        rightid=sw@sonicwall.com
        authby=secret
        auth=esp
        esp=3des-hmac-md5
        ikelifetime=6h
        keylife=5h

Your /etc/ipsec.secrets should be like this:
x.x.x.x y.y.y.y sw@sonicwall.com : PSK "opensesame"

On the Sonicwall create a new connection:

Name: testauto
IPSec Gateway address: 0.0.0.0
SA life time: 18000
Encryption Method: Strong Encrypt and Authenticate( EPS 3DES HMAC MD5)
Shared Secret: opensesame

Radguard

Here are some mailing list comments from FreeS/WAN tech support person Claudia Schmeing on this:

It certainly has been possible to interop between Radguard VPN gateways and
past Linux FreeS/WAN versions, as is evidenced by 
http://www.opus1.com/vpn/atl99display.html, as well as my own interop results
from San Diego this year. There have been no major changes since SD that 
I would foresee affecting this.

The Radguard team said that their VPN gateway will not respond to a peer 
request with PFS (Perfect Forward Secrecy) on, but it *will* successfully 
establish such a connection with Linux FreeS/WAN when Radguard is the
initiator. Since PFS is a desirable feature in terms of cryptographic
security, this asymmetry may frustrate efforts to provide a connection that 
is both as reliable as secure as possible.

While it's not clear that rekeying will present a problem, I suspect that 
some fine tuning of the key life parameters may be needed. Unfortunately 
I was unable to do additional tests on this topic.

Due to the PFS issue, when trying to maintain a connection with PFS,
you may need to set the rekeying times shorter on the radguard side,
in order to ensure that it is always the initiator.

IBM System 390

IBM offer IPsec for their big mainframes. See this PDF document.

We do not know of any tests of this with FreeS/WAN. If you do any, please tell us.

IBM AS 400

From the mailing list:

Subject: [Users] AS/400 <-> FreeS/WAN connection
   Date: Mon, 24 Sep 2001 10:28:54 -0600
   From: "Brandon Peterson" <bsp@MCINTOSHSOFTWARE.COM>

All,

FYI, I got a connection working between my Linux box & AS/400. I had to make
two adjustments to the code...

1) Ignore the commit flag. (There were some patches floating on the list
last week)

2) Make FreeS/WAN start with proposal # 1
To do this, I modified connections.c and inserted after line 1006...
/* Hack to make AS/400 happy */
if (c->policy == 0) c->policy = 1;

Since that was written, FreeS/WAN has been changed to ignore the commit bit, so that adjustment should no longer be necessary.

Windows or Mac clients

If you have Windows 2000 or XP, then you should be able to use the IPsec built into those systems. As far as we know, for all other Windows versions,, you will need a client program.

I am a little confused about IPsec for Mac OS X. Before the release, there were reports it would include IPsec, but more recent information seems to indicate that it doesn't. If anyone knows more, please post to our users mailing list. For other Mac OSs, and perhaps for OS X, you will need a client program.

Quite a number of client programs for IPsec on Windows are available. Some of the same vendors have Macintosh versions.

Some of the user-written HowTos have details of configuration for particular clients.

Most of the relevant vendors are listed in this piece of list mail:

 Subject: Re: Searching Windows95/98 and NT4.0 Clients for FreeS/WAN 
    From: Claudia Schmeing <claudia@coldstream.ca> 
    Date: Wed, 12 Jul 2000

F-Secure VPN+
-------------
for Win 95, 98 and NT 4.0
http://www.datafellows.com/products/vpnplus


Checkpoint SecureRemote VPN-1 4.1
---------------------------------
for Win 95, 98 and NT
http://www.checkpoint.com/techsupport/freedownloads.html


Raptor Firewall, Raptor MobileNT 5.0
-------------------------------------
Mobile NT is a "Client"* for Win 95, 98 (except SE), & First Edition Windows NT 
up to Service Pack 4. It ships with DES; triple DES may be available as an 
add-on depending on your location.

Firewall is for Win NT 4.0 or Win 2000.
http://www.axent.com


IRE SafeNet SoftPK
------------------
a "Client" for Win 95, 98 and NT 4.0 *
http://www.ire.com


Xedia's AccessPoint QVPN "Client" or "Builder"
----------------------------------------------
"Builder" is for NT
"Client" is for Win 98 *
http://www.xedia.com

* "Client" in this context indicates software that does not support a subnet
behind its end of the connection.

That mail omits the PGPnet client because the user asking the question already knew of it. The SSH Sentinel client, released since the above message, is another possibility. Both of those have members of the vendor's staff active on our mailing list, an excellent sign for both interoperability and support.

We also know of some other Windows IPsec clients:

• Lucent
• Ashleylaurent

No doubt there are others we don't know of.

NT domains vs. tunnels

There has been some mailing list discussion of making NT domains work across FreeS/WAN tunnels.

Robert Cotran asked:

> I have a VPN setup between two subnets (192.168.1.x and 192.168.2.x).  I
> would like to be able to join the NT domain on 192.168.1.x from the
> 192.168.2.x subnet.  Is this possible?  Do I have to forward specific ports
> to do this?  I've already set up WINS entries for all the machines, so
> accessing computers by their NetBIOS names works perfectly.  Please let me
> know about this domain thing.  Thanks!

All you need to do is to:

1. Enable NetBIOS over TCP.
2. Create a "lmhosts" file and enter the address of a BDC or a PDC like
    192.168.1.[x]  [Your PDC/BDC servername] #PRE #DOM:[Your Domain Name]
    eg. 192.168.1.1 MYOWNPDC #PRE #DOM:DENSI-NT

3. Reboot if necessary.

For a trust relationship to work between NT domains in different
(sub)nets all domain controllers of the 1st domain have to know about
all controllers of the other domain.
Either you use the described LMHOSTS entry for every domain controller
of both domains or consider setting up WINS service(s).

Windows 2000

Windows 2000 ships with an IPsec implementation built in.

There are restrictions. We have had mailing list reports that only the server version will act as a gateway, working with a subnet behind it, and other versions offer only "client" functionality, with no subnet. We have some comment on this "client/server" distinction in an earlier section.

Some versions of Windows 2000 ship with only weak encryption. You need to upgrade them with the strong encryption pack, available either via the Windows 2000 update service or from Microsoft's web site.

Windows 2000 IPsec sometimes exhibits remarkably odd behaviour. It will allow you to configure it for 3DES only, then ignore your settings and fall back to single DES in some circumstances. Microsoft have said they will fix this. See this Wired article.

Other Linux services related to Win 2000

Windows 2000 also uses a number of other security mechanisms which have Linux equivalents. To integrate well with Windows 2000, you may need to look at several open source projects other than FreeS/WAN:

• Windows 2000 builds L2TP tunnels over (some of?) its IPsec connections. There is some older code for a a Linux L2TP Daemon and a Sourceforge project.
• Kerberos authentication is used in Windows 2000.
  • MIT Kerberos site
  • "'Moron's Guide"
  • Kerberos links page

The Windows 2000 Kerberos implementation includes proprietary modifications. This is a security worry since it is by no means clear that the modified version remains secure. It also creates interoperation problems. Microsoft have released documentation on their modifications, but only under a license that hampers attempts either to audit their code for security flaws or to build other implementations that interoperate with it.

• Samba is a Linux implementation of the Windows SMB protocol, allowing disk sharing and other network services
• tipxd, the Tunelling IPX Daemon, encapsulates IPX for transport over IP.

Here is a mailing list message, from FreeS/WAN team tech support person Claudia Schmeing, discussing Windows 2000 and L2TP:

You write,

> I want some information about IPsec with L2TP.
> I'm going to build the IPsec tunnel on the L2TP tunnel.
> Is it strange?
> Is there any case like this already implemented?

It's used, but rarely. In many cases, IPSec alone is sufficient. 

In this thread, Timo Teras reports that he configured the L2TP/IPSec 
hybrid with Win2k. He gives some pointers.
http://www.sandelman.ottawa.on.ca/linux-ipsec/html/2000/11/msg00545.html

See also John P. Eisenmenger's report on his own experiences at:
http://www.sandelman.ottawa.on.ca/linux-ipsec/html/2001/02/msg00195.html

FreeS/WAN-to-Win2000 interop

As for IPsec interoperation between Windows 2000 and FreeS/WAN, there are several web sites listed under Interop HowTo documents above.

This Microsoft page on Windows 2000 IPsec troubleshooting may also be helpful.

One user has written a tool to simplify the setup. Here is his description from the mailing list:

Subject: [Users] Win2K
   Date: Tue, 2 Oct 2001
   From: Marcus Müller <marcus@ebootis.de>

I've written a small Tool for freeswan-win2k Interaction.
Using this tool you can use a roadwarrior running Win2K
to connect to Freeswan 1.91 with X509 patch.

The tool has the following features:

- FreeSwan like Configuration File
- It sets up the complete Win2k configuration
- It reads dynamic RAS/DHCP adresses and updates the IPSec Config

You only need the following items:
1. Win2k Client
2. Win2k Service Pack 2 (for high encryption)
3. Microsoft ipsecpol tool (included in the resource kit / Downloadable
from Microsoft)
4. FreeSwan with working X.509 Patch and X.509 Certificates for your
Clients
5. FreeSwan like Config-File
6. The small "ipsec.exe" Tool

I have tested it on several Client PCs in different environment

I am planning to offer it as Open Source. Right now I don't know the
right way of distributing my work. Because of the widespread interest,
I would like to place it on the FreeSwan homepage.

Rightnow anyone interested should mail me for a Copy, so I get some
more testers.

Thank you for the great FreeSwan System !!!

This tool is now available from the author's web page.

Performance of FreeS/WAN

In normal operation, the main concern is the overhead for encryption, decryption and authentication of the actual IPsec (ESP and/or AH) data packets. Tunnel setup and rekeying occur so much less frequently than packet processing that, in general, their overheads are not worth worrying about.

At startup, however, tunnel setup overheads may be significant. If you reboot a gateway and it needs to establish many tunnels, expect some delay. This and other issues for large gateways are discussed below.

Published material

The University of Wales at Aberystwyth has done quite detailed speed tests and put their results on the web.

Davide Cerri's thesis (in Italian) includes performance results for FreeS/WAN and for TLS. He posted an English summary on the mailing list.

Steve Bellovin used one of AT&T Research's FreeS/WAN gateways as his data source for an analysis of the cache sizes required for key swapping in IPsec. Available as text or PDF slides for a talk on the topic.

See also the NAI work mentioned in the next section.

Estimating CPU overheads

We can come up with a formula that roughly relates CPU speed to the rate of IPsec processing possible. It is far from exact, but should be usable as a first approximation.

An analysis of authentication overheads for high-speed networks, including some tests using FreeS/WAN, is on the NAI Labs site. In particular, see figure 3 in this PDF document. Their estimates of overheads, measured in Pentium II cycles per byte processed are:

Overheads for IPsec with encryption were not tested in the NAI work, but Antoon Bosselaers' web page gives cost for his optimised Triple DES implementation as 928 Pentium cycles per block, or 116 per byte. Adding that to the 24 above, we get 140 cycles per byte for IPsec with encryption.

At 140 cycles per byte, a 140 MHz machine can handle a megabyte -- 8 megabits -- per second. Speeds for other machines will be proportional to this. To saturate a link with capacity C megabits per second, you need a machine running at C * 140/8 = C * 17.5 MHz.

However, that estimate is not precise. It ignores the differences between:

• NAI's test packets and real traffic
• NAI's Pentium II cycles, Bosselaers' Pentium cycles, and your machine's cycles
• different 3DES implementations
• SHA-1 and MD5

and does not account for some overheads you will almost certainly have:

• communication on the client-side interface
• switching between multiple tunnels -- re-keying, cache reloading and so on

so we suggest using C * 25 to get an estimate with a bit of a built-in safety factor.

This covers only IP and IPsec processing. If you have other loads on your gateway -- for example if it is also working as a firewall -- then you will need to add your own safety factor atop that.

This estimate matches empirical data reasonably well. For example, Metheringham's tests, described below, show a 733 topping out between 32 and 36 Mbit/second, pushing data as fast as it can down a 100 Mbit link. Our formula suggests you need at least an 800 to handle a fully loaded 32 Mbit link. The two results are consistent.

Some examples using this estimation method:

Such an estimate is far from exact, but should be usable as minimum requirement for planning. The key observations are:

• older surplus machines are fine for IPsec gateways at loads up to 5 megabits per second or so
• a mid-range new machine can handle IPsec at rates up to 20 megabits per second or more

Higher performance alternatives

AES is a new US government block cipher standard, designed to replace the obsolete DES. If FreeS/WAN using 3DES is not fast enough for your application, the AES patch may help.

To date (March 2002) we have had only one mailing list report of measurements with the patch applied. It indicates that, at least for the tested load on that user's network, AES roughly doubles IPsec throughput. If further testing confirms this, it may prove possible to saturate an OC3 link in software on a high-end box.

Also, some work is being done toward support of hardware IPsec acceleration which might extend the range of requirements FreeS/WAN could meet.

Other considerations

CPU speed may be the main issue for IPsec performance, but of course it isn't the only one.

You need good ethernet cards or other network interface hardware to get the best performance. See this ethernet information page and this Linux network driver page.

The current FreeS/WAN kernel code is largely single-threaded. It is SMP safe, and will run just fine on a multiprocessor machine ( discussion), but the load within the kernel is not shared effectively. This means that, for example to saturate a T3 -- which needs about a 1200 MHz machine -- you cannot expect something like a dual 800 to do the job.

On the other hand, SMP machines do tend to share loads well so -- provided one CPU is fast enough for the IPsec work -- a multiprocessor machine may be ideal for a gateway with a mixed load.

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.

A gateway that does a lot of rekeying -- many tunnels and/or low settings for tunnel lifetimes -- will also need a lot of random numbers from the random(4) driver.

Low-end systems

Even a 486 can handle a T1 line, according to this mailing list message:

Subject: Re: linux-ipsec: IPSec Masquerade
   Date: Fri, 15 Jan 1999 11:13:22 -0500
   From: Michael Richardson 

. . . A 486/66 has been clocked by Phil Karn to do
10Mb/s encryption.. that uses all the CPU, so half that to get some CPU,
and you have 5Mb/s. 1/3 that for 3DES and you get 1.6Mb/s....

and a piece of mail from project technical lead Henry Spencer:

Oh yes, and a new timing point for Sandy's docs...  A P60 -- yes, a 60MHz
Pentium, talk about antiques -- running a host-to-host tunnel to another
machine shows an FTP throughput (that is, end-to-end results with a real
protocol) of slightly over 5Mbit/s either way.  (The other machine is much
faster, the network is 100Mbps, and the ether cards are good ones... so
the P60 is pretty definitely the bottleneck.)

From the above, and from general user experience as reported on the list, it seems clear that a cheap surplus machine -- a reasonable 486, a minimal Pentium box, a Sparc 5, ... -- can easily handle a home office or a small company connection using any of:

• ADSL service
• cable modem
• T1
• E1

If available, we suggest using a Pentium 133 or better. This should ensure that, even under maximum load, IPsec will use less than half the CPU cycles. You then have enough left for other things you may want on your gateway -- firewalling, web caching, DNS and such.

Measuring KLIPS

Here is some additional data from the mailing list.

Subject: FreeSWAN (specically KLIPS) performance measurements
   Date: Thu, 01 Feb 2001
   From: Nigel Metheringham <Nigel.Metheringham@intechnology.co.uk>

I've spent a happy morning attempting performance tests against KLIPS 
(this is due to me not being able to work out the CPU usage of KLIPS so 
resorting to the crude measurements of maximum throughput to give a 
baseline to work out loading of a box).

Measurements were done using a set of 4 boxes arranged in a line, each 
connected to the next by 100Mbit duplex ethernet.  The inner 2 had an 
ipsec tunnel between them (shared secret, but I was doing measurements 
when the tunnel was up and running - keying should not be an issue 
here).  The outer pair of boxes were traffic generators or traffic sink.

The crypt boxes are Compaq DL380s - Uniprocessor PIII/733 with 256K 
cache.  They have 128M main memory.  Nothing significant was running on 
the boxes other than freeswan.  The kernel was a 2.2.19pre7 patched 
with freeswan and ext3.

Without an ipsec tunnel in the chain (ie the 2 inner boxes just being 
100BaseT routers), throughput (measured with ttcp) was between 10644 
and 11320 KB/sec

With an ipsec tunnel in place, throughput was between 3268 and 3402 
KB/sec

These measurements are for data pushed across a TCP link, so the 
traffic on the wire between the 2 ipsec boxes would have been higher 
than this....

vmstat (run during some other tests, so not affecting those figures) on 
the encrypting box shows approx 50% system & 50% idle CPU - which I 
don't believe at all.  Interactive feel of the box was significantly 
sluggish.

I also tried running the kernel profiler (see man readprofile) during 
test runs.

A box doing primarily decrypt work showed basically nothing happening - 
I assume interrupts were off.
A box doing encrypt work showed the following:-
 Ticks Function                                   Load
 ~~~~~ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~    ~~~~~~
   956 total                                      0.0010
   532 des_encrypt2                               0.1330
   110 MD5Transform                               0.0443
    97 kmalloc                                    0.1880
    39 des_encrypt3                               0.1336
    23 speedo_interrupt                           0.0298
    14 skb_copy_expand                            0.0250
    13 ipsec_tunnel_start_xmit                    0.0009
    13 Decode                                     0.1625
    11 handle_IRQ_event                           0.1019
    11 .des_ncbc_encrypt_end                      0.0229
    10 speedo_start_xmit                          0.0188
     9 satoa                                      0.0225
     8 kfree                                      0.0118
     8 ip_fragment                                0.0121
     7 ultoa                                      0.0365
     5 speedo_rx                                  0.0071
     5 .des_encrypt2_end                          5.0000
     4 _stext                                     0.0140
     4 ip_fw_check                                0.0035
     2 rj_match                                   0.0034
     2 ipfw_output_check                          0.0200
     2 inet_addr_type                             0.0156
     2 eth_copy_and_sum                           0.0139
     2 dev_get                                    0.0294
     2 addrtoa                                    0.0143
     1 speedo_tx_buffer_gc                        0.0024
     1 speedo_refill_rx_buf                       0.0022
     1 restore_all                                0.0667
     1 number                                     0.0020
     1 net_bh                                     0.0021
     1 neigh_connected_output                     0.0076
     1 MD5Final                                   0.0083
     1 kmem_cache_free                            0.0016
     1 kmem_cache_alloc                           0.0022
     1 __kfree_skb                                0.0060
     1 ipsec_rcv                                  0.0001
     1 ip_rcv                                     0.0014
     1 ip_options_fragment                        0.0071
     1 ip_local_deliver                           0.0023
     1 ipfw_forward_check                         0.0139
     1 ip_forward                                 0.0011
     1 eth_header                                 0.0040
     1 .des_encrypt3_end                          0.0833
     1 des_decrypt3                               0.0034
     1 csum_partial_copy_generic                  0.0045
     1 call_out_firewall                          0.0125

Hope this data is helpful to someone... however the lack of visibility 
into the decrypt side makes things less clear

Speed with compression

Another user reported some results for connections with and without IP compression:

Subject: [Users] Speed with compression
   Date: Fri, 29 Jun 2001
   From: John McMonagle <johnm@advocap.org>

Did a couple tests with compression using the new 1.91 freeswan.

Running between 2 sites with cable modems.  Both  using approximately
130 mhz pentium.

Transferred files with ncftp.

Compressed file was a 6mb compressed  installation file.
Non compressed was 18mb /var/lib/rpm/packages.rpm

                            Compressed vpn          regular vpn
Compress file                42.59 kBs               42.08 kBs
regular file                110.84 kBs               41.66 kBs

Load  was about 0 either way.
Ping times were very similar  a bit above 9 ms.

Compression looks attractive to me.

> is there a reason not to switch compression on?  I have large gateway boxes
> connecting 3 connections, one of them with a measly DS1 link...

Run some timing tests with and without, with data and loads representative
of what you expect in production.  That's the definitive way to decide. 
If compression is a net loss, then obviously, leave it turned off.  If it
doesn't make much difference, leave it off for simplicity and hence
robustness.  If there's a substantial gain, by all means turn it on. 

If both ends support compression and can successfully negotiate a
compressed connection (trivially true if both are FreeS/WAN 1.91), then
the crucial question is CPU cycles. 

Compression has some overhead, so one question is whether *your* data
compresses well enough to save you more CPU cycles (by reducing the volume
of data going through CPU-intensive encryption/decryption) than it costs
you.  Last time I ran such tests on data that was reasonably compressible
but not deliberately contrived to be so, this generally was not true --
compression cost extra CPU cycles -- so compression was worthwhile only if
the link, not the CPU, was the bottleneck.  However, that was before the
slow-compression bug was fixed.  I haven't had a chance to re-run those
tests yet, but it sounds like I'd probably see a different result. 

Methods of measuring

If you want to measure the loads FreeS/WAN puts on a system, note that tools such as top or measurements such as load average are more-or-less useless for this. They are not designed to measure something that does most of its work inside the kernel.

Here is a message from FreeS/WAN kernel programmer Richard Guy Briggs on this:

> I have a batch of boxes doing Freeswan stuff.
> I want to measure the CPU loading of the Freeswan tunnels, but am 
> having trouble seeing how I get some figures out...
> 
>  - Keying etc is in userspace so will show up on the per-process
>    and load average etc (ie pluto's load)

Correct.

>  - KLIPS is in the kernel space, and does not show up in load average
>    I think also that the KLIPS per-packet processing stuff is running
>    as part of an interrupt handler so it does not show up in the
>    /proc/stat system_cpu or even idle_cpu figures

It is not running in interrupt handler.  It is in the bottom half.
This is somewhere between user context (careful, this is not
userspace!) and hardware interrupt context.

> Is this correct, and is there any means of instrumenting how much the 
> cpu is being loaded - I don't like the idea of a system running out of 
> steam whilst still showing 100% idle CPU :-)

vmstat seems to do a fairly good job, but use a running tally to get a
good idea.  A one-off call to vmstat gives different numbers than a
running stat.  To do this, put an interval on your vmstat command
line.

Subject: Re: Measuring the CPU usage of Freeswan
   Date: Mon, 29 Jan 2001
   From: Patrick Michael Kane <modus@pr.es.to>
 
The only truly accurate way to accurately track FreeSWAN CPU usage is to use
a CPU soaker. You run it on an unloaded system as a benchmark, then start up
FreeSWAN and take the difference to determine how much FreeSWAN is eating.
I believe someone has done this in the past, so you may find something in
the FreeSWAN archives.  If not, someone recently posted a URL to a CPU
soaker benchmark tool on linux-kernel.

Testing FreeS/WAN

Not all types of testing are described here. Other parts of the documentation describe some tests:

installation document

testing for a successful install

configuration document

basic tests for a working configuration

web links document

General information on tests for interoperability between various IPsec implementations. This includes links to several test sites.

interoperation document.

More specific information on FreeS/WAN interoperation with other implementations.

performance document

performance measurements

The test setups and procedures described here can also be used in other testing, but this document focuses on testing the IPsec functionality of FreeS/WAN.

Testing with User Mode Linux

User Mode Linux allows you to run Linux as a user process on another Linux machine.

As of 1.92, the distribution has a new directory named testing. It contains a collection of test scripts and sample configurations. Using these, you can bring up several copies of Linux in user mode and have them build tunnels to each other. This lets you do some testing of a FreeS/WAN configuration on a single machine.

You need a moderately well-endowed machine for this to work well. Each UML wants about 16 megs of memory by default, which is plenty for FreeS/WAN usage. Typical regression testing only occasionally uses as many as 4 UMLs. If one is doing nothing else with the machine (in particular, not running X on it), then 128 megs and a 500MHz CPU are fine.

Configuration for a testbed network

A common test setup is to put a machine with dual Ethernet cards in between two gateways under test. You need at least five machines; two gateways, two clients and a testing machine in the middle.

The central machine both routes packets and provides a place to run diagnostic software for checking IPsec packets. See next section for discussion of using tcpdump(8) for this.

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.

What you end up with looks like:

Testbed network

      subnet a.b.c.0/24
             |
      eth1 = a.b.c.1
         gate1
      eth0 = 192.168.p.1
             |
             |
      eth0 = 192.168.p.2
         route/monitor box
      eth1 = 192.168.q.2
             |
             |
      eth0 = 192.168.q.1
         gate2
      eth1 = x.y.z.1
              |
       subnet x.y.z.0/24

Where p and q are any convenient values that do not interfere with other
routes you may have. The ipsec.conf(5) file then has, among other things:

conn abc-xyz
      left=192.168.p.1
      leftnexthop=192.168.p.2
      right=192.168.q.1
      rightnexthop=192.168.q.2

Once that works, you can remove the "route/monitor box", and connect the two gateways to the Internet. The only parameters in ipsec.conf(5) that need to change are the four shown above. You replace them with values appropriate for your Internet connection, and change the eth0 IP addresses and the default routes on both gateways.

Note that nothing on either subnet needs to change. This lets you test most of your IPsec setup before connecting to the insecure Internet.

Using packet sniffers in testing

A number of tools are available for looking at packets. We will discuss using tcpdump(8), a common Linux tool included in most distributions. Alternatives offerring more-or-less the same functionality include:

Ethereal

Several people on our mailing list report a preference for this over tcpdump.

windump

a Windows version of tcpdump(8), possibly handy if you have Windows boxes in your network

Sniffit

A linux sniffer that we don't know much about. If you use it, please comment on our mailing list.

See also this index of packet sniffers.

tcpdump(8) may 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.

At one point, the problem was quite severe. Recent versions of tcpdump, however, understand IPsec well enough to be usable on a gateway. You can get the latest version from tcpdump.org.

Even with a recent tcpdump, some care is required. Here is part of a post from Henry on the topic:

> a) data from sunset to sunrise or the other way is not being
> encrypted (I am using tcpdump (ver. 3.4) -x/ping -p to check
> packages) 

What *interface* is tcpdump being applied to?  Use the -i option to
control this.  It matters!  If tcpdump is looking at the ipsecN
interfaces, e.g. ipsec0, then it is seeing the packets before they are
encrypted or after they are decrypted, so of course they don't look
encrypted.  You want to have tcpdump looking at the actual hardware
interfaces, e.g. eth0. 

Actually, the only way to be *sure* what you are sending on the wire is to
have a separate machine eavesdropping on the traffic.  Nothing you can do
on the machines actually running IPsec is 100% guaranteed reliable in this
area (although tcpdump is a lot better now than it used to be).

The most certain way to examine IPsec packets is to look at them on the wire. For security, you need to be certain, so we recommend doing that. To do so, you need a separate sniffer machine located between the two gateways. This machine can be routing IPsec packets, but it must not be an IPsec gateway. Network configuration for such testing is discussed above.

Here's another mailing list message with advice on using tcpdump(8):

Subject: RE: [Users] Encrypted???
   Date: Thu, 29 Nov 2001
   From: "Joe Patterson" <jpatterson@asgardgroup.com>

tcpdump -nl -i $EXT-IF proto 50

-nl tells it not to buffer output or resolve names (if you don't do that it
may confuse you by not outputing anything for a while), -i $EXT-IF (replace
with your external interface) tells it what interface to listen on, and
proto 50 is ESP.  Use "proto 51" if for some odd reason you're using AH, and
"udp port 500" if you want to see the isakmp key exchange/tunnel setup
packets.

You can also run `tcpdump -nl -i ipsec0` to see what traffic is on that
virtual interface.  Anything you see there *should* be either encrypted or
dropped (unless you've turned on some strange options in your ipsec.conf
file)

Another very handy thing is ethereal (http://www.ethereal.com/) which runs
on just about anything, has a nice gui interface (or a nice text-based
interface), and does a great job of protocol  breakdown.  For ESP and AH
it'll basically just tell you that there's a packet of that protocol, and
what the spi is, but for isakmp it'll actually show you a lot of the tunnel
setup information (until it gets to the point in the protocol where isakmp
is encrypted....)

Verifying encryption

The question of how to verify that messages are actually encrypted has been extensively discussed on the mailing list. See this thread.

If you just want to verify that packets are encrypted, look at them with a packet sniffer (see previous section ) located between the gateways. The packets should, except for some of the header information, be utterly unintelligible. The output of good encryption looks exactly like random noise.

A packet sniffer can only tell you that the data you looked at was encrypted. If you have stronger requirements -- for example if your security policy requires verification that plaintext is not leaked during startup or under various anomolous conditions -- then you will need to devise much more thorough tests. If you do that, please post any results or methodological details which your security policy allows you to make public.

You can put recognizable data into 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 other protocols, you may 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.

One thing to watch for: the output of good compression, like that of good encryption, looks just like random noise. You cannot tell just by looking at a data stream whether it has been compressed, encrypted, or both. You need a little care not to mistake compressed data for encrypted data in your testing.

Note also that weak encryption also produces random-looking output. You cannot tell whether the encryption is strong by looking at the output. To be sure of that, you would need to have both the algorithms and the implementation examined by experts.

For IPsec, you can get partial assurance from interoperability tests. See our interop document. When twenty products all claim to implement 3DES, and they all talk to each other, you can be fairly sure they have it right. Of course, you might wonder whether all the implementers are consipring to trick you or, more plausibly, whether some implementations might have "back doors" so they can get also it wrong when required.. If you're seriously worried about things like that, you need to get the code you use audited (good luck if it is not Open Source), or perhaps to talk to a psychiatrist about treatments for paranoia.

Mailing list pointers

Additional information on testing can be found in 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"

Kernel configuration for FreeS/WAN

This section lists many of the options available when configuring a Linux kernel, and explains how they should be set on a FreeS/WAN IPsec gateway.

Not everyone needs to worry about kernel configuration

Note that in many cases you do not need to mess with these.

You may have a Linux distribution which comes with FreeS/WAN installed (see this list). In that case, you need not do a FreeS/WAN installation or a kernel configuration. Of course, you might still want to configure and rebuild your kernel to improve performance or security. This can be done with standard tools described in the Kernel HowTo.

If you need to install FreeS/WAN, then you do need to configure a kernel. However, you may choose to do that using the simplest procedure:

• Configure, build and test a kernel for your system before adding FreeS/WAN. See the Kernel HowTo for details. This step cannot be skipped . FreeS/WAN needs the results of your configuration.
• Then use FreeS/WAN's make oldgo command. This sets everything FreeS/WAN needs and retains your values everywhere else.

This document is for those who choose to configure their FreeS/WAN kernel themselves.

Assumptions and notation

Help text for most kernel options is included with the kernel files, and is accessible from within the configuration utilities. We assume you will refer to that, and to the Kernel HowTo, as necessary. This document covers only the FreeS/WAN-specific aspects of the problem.

To avoid duplication, this document section does not cover settings for the additional IPsec-related kernel options which become available after you have patched your kernel with FreeS/WAN patches. There is help text for those available from within the configuration utility.

We assume a common configuration in which the FreeS/WAN IPsec gateway is also doing ipchains(8) firewalling for a local network, and possibly masquerading as well.

Some suggestions below are labelled as appropriate for "a true paranoid". By this we mean they may cause inconvenience and it is not entirely clear they are necessary, but they appear to be the safest choice. Not using them might entail some risk. Of course one suggested mantra for security administrators is: "I know I'm paranoid. I wonder if I'm paranoid enough."

Labels used

Six labels are used to indicate how options should be set. We mark the labels with [square brackets]. For two of these labels, you have no choice:

[required]

essential for FreeS/WAN operation.

[incompatible]

incompatible with FreeS/WAN.

those must be set correctly or FreeS/WAN will not work

FreeS/WAN should work with any settings of the others, though of course not all combinations have been tested. We do label these in various ways, but these labels are only suggestions.

[recommended]

useful on most FreeS/WAN gateways

[disable]

an unwelcome complication on a FreeS/WAN gateway.

[optional]

Your choice. We outline issues you might consider.

[anything]

This option has no direct effect on FreeS/WAN and related tools, so you should be able to set it as you please.

Of course complexity is an enemy in any effort to build secure systems. For maximum security, any feature that can reasonably be turned off should be. "If in doubt, leave it out."

Kernel options for FreeS/WAN

Indentation is based on the nesting shown by 'make menuconfig' with a 2.2.16 kernel for the i386 architecture.

Code maturity and level options

Prompt for development ... code/drivers

[optional] If this is no, experimental drivers are not shown in later menus.

For most FreeS/WAN work, no is the preferred setting. Using new or untested components is too risky for a security gateway.

However, for some hardware (such as the author's network cards) the only drivers available are marked new/experimental. In such cases, you must enable this option or your cards will not appear under "network device support". A true paranoid would leave this option off and replace the cards.

Processor type and features

[anything]

Loadable module support

Enable loadable module support

[optional] A true paranoid would disable this. An attacker who has root access to your machine can fairly easily install a bogus module that does awful things, provided modules are enabled. A common tool for attackers is a "rootkit", a set of tools the attacker uses once he or she has become root on your system. The kit introduces assorted additional compromises so that the attacker will continue to "own" your system despite most things you might do to recovery the situation. For Linux, there is a tool called knark which is basically a rootkit packaged as a kernel module.

With modules disabled, an attacker cannot install a bogus module. The only way he can achieve the same effects is to install a new kernel and reboot. This is considerably more likely to be noticed.

Many FreeS/WAN gateways run with modules enabled. This simplifies some administrative tasks and some ipchains features are available only as modules. Once an enemy has root on your machine your security is nil, so arguably defenses which come into play only in that situation are pointless.

Set version information ....

[optional] This provides a check to prevent loading modules compiled for a different kernel.

Kernel module loader

[disable] It gives little benefit on a typical FreeS/WAN gate and entails some risk.

It should be possible to use IPv4 FreeS/WAN on a machine which also does IPv6. This combination is not yet well tested. We would be quite interested in hearing results from anyone expermenting with it, via the mailing list.

We do not recommend using IPv6 on production FreeS/WAN gateways until more testing has been done.

We do not recommend this. Keep the software on your gateway as simple as possible. If you need a Linux-based Appletalk or IPX server, use a separate machine.

The development team test almost entirely on 10 or 100 megabit Ethernet and modems. In principle, any device that can do IP should be just fine for IPsec, but in the real world any device that has not been well-tested is somewhat risky. By all means try it, but don't bet your project on it until you have solid test results.

If you disabled experimental drivers in the Code maturity section above, then those drivers will not be shown here. Check that option before going off to hunt for missing drivers.

If you want Linux to automatically find more than one ethernet interface at boot time, you need to:

• compile the appropriate driver(s) into your kernel. Modules will not work for this
• add a line such as

   append="ether=0,0,eth0 ether=0,0,eth1"

to your /etc/lilo.conf file. In some cases you may need to specify parameters such as IRQ or base address. The example uses "0,0" for these, which tells the system to search. If the search does not succeed on your hardware, then you should retry with explicit parameters. See the lilo.conf(5) man page for details.
• run lilo(8)

Other configuration possibilities

This document describes various options for FreeS/WAN configuration which are less used or more complex (often both) than the standard cases described in our quickstart document.

Some rules of thumb about configuration

Tunnels are cheap

Nearly all of the overhead in IPsec processing is in the encryption and authentication of packets. Our performance document discusses these overheads.

Beside those overheads, the cost of managing additional tunnels is trivial. Whether your gateway supports one tunnel or ten just does not matter. A hundred might be a problem; there is a section on this in the performance document.

So, in nearly all cases, if using multiple tunnels gives you a reasonable way to describe what you need to do, you should describe it that way in your configuration files.

For example, one user recently asked on a mailing list about this network configuration:

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

   netA and B are secured netC not.
   netA and gwA can not access netC

The user had constructed only one tunnel, netA to netB, and wanted to know how to use ip-route to get netC packets into it. This is entirely unnecessary. One of the replies was:

  The simplest way and indeed the right way to
  solve this problem is to set up two connections:

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

Of course another possibility would be to just use one tunnel, with a subnet mask that includes both netB and netC (or B, C, D, ...). See next section.

In general, you can construct as many tunnels as you need. Networks like netC in this example that do not connect directly to the gateway are fine, as long as the gateway can route to them.

The number of tunnels can become an issue if it reaches 50 or so. This is discussed in the performance document. Look there for information on supporting hundreds of Road Warriors from one gateway.

Subnet sizes

The subnets used in leftsubnet and rightsubnet can be of any size that fits your needs, and they need not correspond to physical networks.

You adjust the size by changing the subnet mask , the number after the slash in the subnet description. For example

• in 192.168.100.0/24 the /24 mask says 24 bits are used to designate the network. This leave 8 bits to label machines. This subnet has 256 addresses. .0 and .255 are reserved, so it can have 254 machines.
• A subnet with a /23 mask would be twice as large, 512 addresses.
• A subnet with a /25 mask would be half the size, 128 addresses.
• /0 is the whole Internet
• /32 is a single machine

As an example of using these in connection descriptions, suppose your company's head office has four physical networks using the address ranges:

192.168.100.0/24

development

192.168.101.0/24

production

192.168.102.0/24

marketing

192.168.103.0/24

administration

You can use exactly those subnets in your connection descriptions, or use larger subnets to grant broad access if required:

leftsubnet=192.168.100.0/24

remote hosts can access only development

leftsubnet=192.168.100.0/23

remote hosts can access development or production

leftsubnet=192.168.102.0/23

remote hosts can access marketing or administration

leftsubnet=192.168.100.0/22

remote hosts can access any of the four departments

or use smaller subnets to restrict access:

leftsubnet=192.168.103.0/24

remote hosts can access any machine in administration

leftsubnet=192.168.103.64/28

remote hosts can access only certain machines in administration.

leftsubnet=192.168.103.42/32

remote hosts can access only one particular machine in administration

To be exact, 192.68.103.64/28 means all addresses whose top 28 bits match 192.168.103.64. There are 16 of these because there are 16 possibilities for the remainingg 4 bits. Their addresses are 192.168.103.64 to 192.168.103.79.

Each connection description can use a different subnet if required.

It is possible to use all the examples above on the same FreeS/WAN gateway, each in a different connection description, perhaps for different classes of user or for different remote offices.

It is also possible to have multiple tunnels using different leftsubnet descriptions with the same right. For example, when the marketing manager is on the road he or she might have access to:

leftsubnet=192.168.102.0/24

all machines in marketing

192.168.101.32/29

some machines in production

leftsubnet=192.168.103.42/32

one particular machine in administration

This takes three tunnels, but tunnels are cheap. If the laptop is set up to build all three tunnels automatically, then he or she can access all these machines concurrently, perhaps from different windows.

Other network layouts

Here is the usual network picture for a site-to-site VPN::

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

and for the Road Warrior::

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

Other configurations are also possible.

The Internet as a big subnet

A telecommuter might have:

     Sunset==========West------------------East ================= firewall --- the Internet
         home network      untrusted net        corporate network

This can be described as a special case of the general subnet-to-subnet connection. The subnet on the right is 0.0.0.0/0, the whole Internet.

West (the home gateway) can have its firewall rules set up so that only IPsec packets to East are allowed out. It will then behave as if its only connection to the world was a wire to East.

When machines on the home network need to reach the Internet, they do so via the tunnel, East and the corporate firewall. From the viewpoint of the Internet (perhaps of some EvilDoer trying to break in!), those home office machines are behind the firewall and protected by it.

Wireless

Another possible configuration comes up when you do not trust the local network, either because you have very high security standards or because your are using easily-intercepted wireless signals.

Some wireless networks have built-in encryption called WEP, but its security is dubious. It is a fairly common practice to use IPsec instead.

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

          West-----------------------------East == the rest of your network
     workstation   untrusted wireless net

Of course, there would likely be several wireless workstations, each with its own IPsec tunnel to the East gateway.

The connection descriptions look much like Road Warrior descriptions:

• each workstation should have its own unique
  • identifier for IPsec
  • RSA key
  • connection description.
• on the gateway, use left=%any, or the workstation IP address
• on workstations, left=%defaultroute, or the workstation IP address
• leftsubnet= is not used.

The rightsubnet= parameter might be set in any of several ways:

rightsubnet=0.0.0.0/0

allowing workstations to access the entire Internet (see above)

rightsubnet=a.b.c.0/24

allowing access to your entire local network

rightsubnet=a.b.c.d/32

restricting the workstation to connecting to a particular server

Of course you can mix and match these as required. For example, a university might allow faculty full Internet access while letting student laptops connect only to a group of lab machines.

Choosing connection types

One choice 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 our machine's private key in ipsec.secrets. Public keys for other machines may either be placed in ipsec.conf or provided via DNS.

A third method, using RSA keys embedded in X.509 certtificates, is provided by user patches.

Manually keyed connections provide weaker security than automatically keyed connections. An opponent who reads ipsec.secrets(5) gets your encryption key and can read all data encrypted by it. If he or she has an archive of old messages, all of them back to your last key change are also readable.

With automatically-(re)-keyed connections, an opponent who reads ipsec.secrets(5) gets the key used to authenticate your system in IKE -- the shared secret or your private key, depending what authentication mechanism is in use. However, he or she does not automatically gain access to any encryption keys or any data.

An attacker who has your authentication key can mount a man-in-the-middle attack and, if that succeeds, he or she will get encryption keys and data. This is a serious danger, but it is better than having the attacker read everyting as soon as he or she breaks into ipsec.secrets(5).. Moreover, the keys change often so an opponent who gets one key does not get a large amount of data. To read all your data, he or she would have to do a man-in-the-middle attack at every key change.

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 may also be useful for testing. There is some discussion of this in our FAQ.

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 support two basic methods for this authentication:

• shared secrets, stored in ipsec.secrets(5)
• RSA authentication

There are, howver, several variations on the RSA theme, using different methods of managing the RSA keys:

• our RSA private key in ipsec.secrets(5) with other gateways' public keys

  either

  stored in ipsec.conf(5)

  or

  looked up via DNS

• authentication with x.509 certificates.; See our links section for information on user-contributed patches for this.:

Public keys in ipsec.conf(5 ) give a reasonably straightforward method of specifying keys for explicitly configured connections.

Putting public keys in DNS allows us to support opportunistic encryption. Any two FreeS/WAN gateways can provide secure communication, without either of them having any preset information about the other.

X.509 certificates may be required to interface to various PKIs.

Advantages of public key methods

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

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.

What I call "shared secrets" are sometimes also called "pre-shared keys". They are used only for for authentication, never for encryption. Calling them "pre-shared keys" has confused some users into thinking they were encryption keys, so I prefer to avoid the term..

If you are interoperating with another IPsec implementation, you may find its documentation calling them "passphrases".

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-s hared 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"

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. This is discussed in more detail above.

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

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

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.

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

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

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

        ipsec setup restart

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.

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.

Installing FreeS/WAN from source

Not everyone needs to install from source

Some Linux distributions, listed in the introduction, ship with FreeS/WAN included. If you are using one of them, you need not perform a FreeS/WAN installation. That should all be done for you already. All you have to do is:

• include FreeS/WAN in your installation choices, or add it to your configuration later
• if you install kernel source, be sure to use a version which includes the FreeS/WAN patches. This should be available from your CDs or from the web site for your distribution.

For other distributions, you may be able to find pre-packaged RPMs and use the simple installation we describe in our quickstart document.

If either of those methods works for you, we recommend you use it. Once that is done, continue at enabling FreeS/WAN in our quickstart document.

Some people do need to install from source

Unfortunately, due to export laws restricting distribution of strong cryptography, not all distributions include FreeS/WAN. Moreover, the standard kernel does not include the kernel parts of FreeS/WAN.

Also, if you need to add patches to the FreeS/WAN code (see this list), you need to do that and then install FreeS/WAN from the patched source.

Many people will need to install FreeS/WAN from source, including patching and rebuilding their kernel.

Information on re-installing or un-installing is provided near the end of this document.

Before starting the install

Configure, compile, install, and test a Linux kernel, without FreeS/WAN.

If you have not done this before, you will need to read the Kernel HowTo. You might also look at this magazine article.

Choosing a kernel

The general rule is choose a current release of a production kernel -- the latest 2.2 or 2.4.

For specific information on which kernels a FreeS/WAN release supports, see the README file in that release.

2.2.x for many users

Many users can continue to run kernels from the 2.2 series of Linux production kernels.

We recommend using the latest release in that series. At time of writing (Feb 2002), that is 2.2.20.

If you need to use an older 2.2.x kernel for some reason, be warned that recent versions of FreeS/WAN will not compile out-of-the-box on a kernel earlier than 2.2.19. A workaround is described in the FreeS/WAN 1.91 section of our CHANGES file. See the mailing list archives, around June 2001, for more details if needed.

2.4.x is possible

2.4 has new firewalling code called nefilter. This may provide good reasons to move to 2.4, especially on for gateway machines.

Do not use 2.4.15; it has a bug that causes file system corruption.

2.0.x may still work

If you must use the older 2.0.x kernel series -- for example because you need some driver that has not been ported to later kernels -- you may be in luck. When last tested, FreeS/WAN worked fine on 2.0.39.

On the other hand, you may have problems in the future. Recent versions of FreeS/WAN are not heavily tested on 2.0 kernels -- most of both the development team and the user community are on 2.2, or even 2.4, by now -- and we are almost certain to drop 2.0 support whenever some problem crops up that would mean retaining it required significant work from our team.

Development kernels

Development kernels are not intended for production use . They change often and include new code which has not yet been thoroughly tested. These changes often break things, including FreeS/WAN. The FreeS/WAN team does not have the resources to chase the moving target; our priority is developing FreeS/WAN on stable kernels. If you encounter a problem on a development kernel, please solve it (you are a developer, aren't you?) and send us a patch. Of course, we will happily discuss problems and solutions on the mailing list, but we are unlikely to do much work on actually implementing a solution.

Fortunately we have a user who regularly fixes problems with FreeS/WAN on development kernels (merci, Marc), and we do fix some ourselves. FreeS/WAN often works just fine on a development kernel; it's just that there's no guarantee.

If you are going to test FreeS/WAN with a development kernel, we recommend you use our latest snapshot. This is the FreeS/WAN version most likely to have the patches required to work on a recent development kernel. The released version of FreeS/WAN is likely to be out of date for your purposes.

Things you must have installed

If you have a CD distribution of Linux, it should include everything you need.

Tools and libraries

Use your distribution's tools to load:

• tools
  • a GNU C compiler (gcc or egcs)
  • assembler and linker for your architecture (the bin86 package on PCs)
  • miscellaneous development tools such as make(1) and patch(1)
• libraries, both headers and object modules
  • standard compiler libraries such as glibc
  • the GMP (GNU Multi-P recision) library, required for Pluto's public key calculations.
  • ncurses library if you want to use menuconfig (recommended)

There are some common slips worth avoiding here:

• not installing the GMP library. Pluto will not compile without it. See the FreeS/WAN FAQ for more detail if required.
• not installing patch(1). Our scripts need it to apply our patches to the kernel.

Kernel source code

You need the source code for the kernel because you must patch and re-compile it to install FreeS/WAN. There are several places you can get this:

• off your distribution CDs
• from your ditribution vendor's website
• from kernel.org

Kernel from CD

• kernel source
• kernel headers

Vendor kernels

All the major distribution vendors provide kernel source. See for example:

• Red Hat's list of mirror sites
• SuSE's download page

Using a kernel from your distribution vendor may save you some annoyance later.

Different distributions put the kernel in different places (/vmlinuz, /boot/vmlinuz, /boot/vmlinuz-2.2.15 ...) and set lilo (the Li nux loader) up differently. With a kernel from your distribution vendor, everything should work 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 the kernel Makefile and/or /etc/lilo.conf to solve this problem, but we suggest just avoiding it.

Also, distributions vendors may include patches or drivers which are not part of the standard kernel. If you install a standard kernel, you must either do without those features or download those patches and add them yourself.

Kernels from kernel.org

Once you've found a kernel

Once you have found suitable kernel source, choose a mirror that is close to you and bookmark it.

Kernel source normally resides in /usr/src/linux, whether you load it from a distribution CD or download a tar file into /usr/src and untar it there. Unless you both have unusual requirements and know exactly what you're doing, we recommend you put it there.

Note: Some recent distributions (certainly Redhat 7.2 and Mandrake 8.1, perhaps others) put kernel source code in a directory named linux-2.4 while FreeS/WAN expects to find it in linux, which is where all distributions used to put it and the kernel.org kernels still do. If your distribution uses linux-2.4, then you must create a symbolic link to linux before proceeding with your FreeS/WAN install. See the man page for ln(1) for details of how to do this if required.

Getting FreeS/WAN

You can download FreeS/WAN from our primary site or one of our mirrors.

Put the tarfile under /usr/src and untar it there. The command to use is:

• tar -xzf freeswan*.gz

This will give you a directory /usr/src/freeswan<version>.

Note that these methods don't work:

• putting freeswan under /usr/src/linux. The links become confused.
• untarring in one place, then using cp -R to move it where you want it. Some necessary symbolic links are not copied.

Kernel configuration

The gateway kernel must be configured before FreeS/WAN is added because some of our utilities rely on the results of configuration.

On some distributions, you can get the configuration files for the vendor's standard kernel(s) off the CD, and use that. This allows you to skip this step; you need not configure the kernel if the vendor has and you have the vendor's config file installed. Here is a mailing list message describing the procedure for Redhat:

Subject: Re: [Users] Do I need to recompile kernel 2.2.17-14?
   Date: Wed, 6 Jun 2001 08:38:38 -0500
   From: "Corey J. Steele" <csteele@mtron.com>

if you install the corresponding kernel-source-*.rpm, you can actually find
the config file used to build that kernel in /usr/src/linux/Configs, just
copy the one you want to use (based solely on architecture) to
/usr/src/linux/.config, and proceed!  It should work.

If the kernel has not been configured, do that now. This is done by giving one of the following commands in /usr/src/linux:

make config

command-line interface

make menuconfig

text menus (requires curses(3) libraries)

make xconfig

using the X window system (requires X, not recommended for gateways)

Any of these wiil do the job. If you have no established preference, we suggest trying menuconfig.

For more information on configuring your kernel, see our section on that topic.

Install and test a kernel before adding FreeS/WAN

You should compile, install and test the kernels as you have configured them, so that you have a known stable starting point. The series of commands involved is usually something like:

make menuconfig

choose kernel options, set up a kernel for your machine

make dep

find dependencies between files

make bzImage

build a loadable kernel image, compressed with bzip(1)

make install

install it

make modules

build modules which can be added to a running kernel

make modules_install

install them

lilo

ensure that the boot loader sees your changes

Doing this first means that 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 Linux web references. The most directly relevant document is the Kernel HowTo.

Building and installing the software

There are several ways to build and install the software. All require that you have kernel source, correctly configured for your machine, as a starting point. If you don't have that yet, see the previous section

Whatever method you choose, it will do all of the following:

• add FreeS/WAN code to the kernel
  • insert patches into standard kernel code to provide an interface
  • add additional files which use that interface
• re-configure and re-compile the kernel to activate that code
• install the new kernel
• build the non-kernel FreeS/WAN programs and install them
  • ipsec(8) in /usr/local/sbin
  • others in /usr/local/lib/ipsec
• install FreeS/WAN man pages under /usr/local/man
• create the configuration file ipsec.conf(5). Editing this file to configure your IPsec gateway is described in the next section.
• create an RSA public/private key pair for your system and place it in ipsec.secrets(5)
• install the initialisation script /etc/rc.d/init.d/ipsec
• create links to that script from the /etc/rc.d/rc[0-6].d directories so that each run level starts or stops IPsec. (If the previous sentence makes no sense to you, try the From Power-up to Bash Prompt HowTo).

You can do the whole install with two commands (recommended in most cases) or get into as much of the detail as you like.

Building RPMs

Go to the FreeS/WAN directory and do whichever of the following commands you prefer:

make orpm

uses command-line kernel configuration

make menurpm

uses menu kernel configuration (requires ncurses library)

make xrpm

use X Window kernel configuration (requires X)

After the Makefile does the software and kernel build, it will make some RPMs and leave them in the rpms directory. The RPMs are:

freeswan

the userland utilities

freeswan-module

the ipsec.o kernel module, built only if your kernel configuration sets klips as a module

freeswan-kernel

the Linux kernel and its modules

freeswan-userkernel

all of the above

Once you have the RPMs, you can install FreeS/WAN from them with rpm -i commands. For a more detailed procedure, go to our quickstart document.

This makes it much easier to build FreeS/WAN on one system for installation on another.

This facility is based on work by Paul Lahaie at Steamballoon.

Building IPsec as a module

With the full procedure described in the next section, you can either build the kernel parts of FreeS/WAN into your kernel or build them as a kernel module, depending on how you set the kernel configuration options.

Since 1.91, we also provide an option to build only the FreeS/WAN module, without re-compiling the rest of your kernel.

Note, however, that this requires:

• kernel source in /usr/src/linux
• kernel has been configured
• source matches the kernel you are actually running

To do the module install, give two commands in the FreeS/WAN directory:

• one of make omod, make menumod or make xmod
• make minstall

You can now start FreeS/WAN with

service ipsec start

then choose what to do next.

N.B.: This is relatively new code and not yet tested on a wide range of systems. If it does not work for you, please report the problem. In the meanwhile, fall back to the older procedure described next..

Installing directly from source

There are two steps here. First you do everything else, then you install the new FreeS/WAN-enabled kernel.

Everything but kernel installation

To do everything except install the new kernel, cd into the freeswan directory and become root. Give any one of the following commands:

make oldgo

Uses FreeS/WAN's default settings for some kernel configuration options. Leaves all other options unchanged from your last kernel configuration.

make ogo

Invokes config so you can configure the kernel from the command line.

make menugo

Invokes menuconfig so you can configure the kernel with text-mode menus.

make xgo

Invokes xconfig so you can configure the kernel in an X window.

You must save the new configuration even if you make no changes. This ensures that the FreeS/WAN changes are actually seen by the system.

There are few options in the FreeS/WAN part of kernel configuration. For most of them, we recommend that you make no changes.

• In particular, please do not disable FreeS/WAN debugging during kernel configuration. This code has no effect unless you turn it on with klipsdebug in your ipsec.conf(5) file, and therefore no cost other than a modest increase in kernel size. However, if you disable it and then run into problems, we may not be able to help you.
• One thing you can change is whether KLIPS is compiled into the kernel or as a module. The FreeS/WAN intialisation scripts work with either configuration, automatically loading the module if required, so it is your choice.

Our scripts save the output of make commands they call in files with names like out.kbuild or out.kinstall. The last command of each script checks the appropriate out.* file for error messages.

• If the last output you see is make saying it is calling our errcheck script, then all is well. There were no errors.
• If not, an error has occurred. Check the appropriate out.* file for details.

For the above commands, the error files are out.kpatch and out.kbuild.

These scripts automatically build an RSA authentication key pair (a public key and the matching private key) for you, and put the result in /etc/ipsec.secrets. For information on using RSA authentication, see our configuration section. Here, we need only note that generating the key uses random(4) quite heavily and if random(4) runs out of randomness, it will block until it has enough input. You may need to provide input by moving the mouse around a lot, or going to another window and typing random characters, or using some command such as du -s /usr to generate disk activity.

Installing the new kernel

To install the kernel the easy way, just give this command in the FreeS/WAN directory:

make kinstall

Installs the new kernel and, if required, the modules to go with it. Errors, if any, are reported in out.kinstall

Using make kinstall from the FreeS/WAN directory is equivalent to giving the following sequence of commands in /usr/src/linux:

• make
• make install
• make modules
• make modules_install

If you prefer that sequence, use it instead.

Reboot to enable your new FreeS/WAN-enabled kernel.

If you have some unusual setup such that the above sequence of commands won't work on your system, then our make kinstall will not work either. Use whatever method does work on your system. See our implementation notes file for additional information that may help in such situations.

Where to go from here

At this point, you are finished the install. Go to the quickstart document section on testing your FreeS/WAN install and continue from there.

Alternately, you might want to look at background material on the protocols used before trying configuration.

Re-install or un-install

If you have FreeS/WAN installed from source on this machine, and need to install a newer version or un-install FreeS/WAN, this section is for you.

If you have FreeS/WAN installed from RPMs, use rpm -e or rpm -u to uninstall or upgrade.

Re-install

The scripts are designed so that a re-install -- to upgrade to a later FreeS/WAN version or to a later kernel version -- can be done in exactly the same way as an original install.

The scripts know enough, for example, not to apply the same kernel patch twice and not to overwrite your ipsec.conf or ipsec.secrets files. However, they will overwrite the _updown script. If you have modified that, save your version under another name before doing the install.

Also, they may not always work exactly as designed. Check the BUGS file for any caveats in the current version.

to install a new version of FreeS/WAN, with your current kernel

Download and untar the new FreeS/WAN. Since kernel source has already been installed and configured, you can skip a few steps in the procedure below. Go to Building FreeS/WAN, and follow normal install-from-source procedures from there.

to install a new kernel, on a machine which already has FreeS/WAN installed

Download and untar the new kernel source. Since this kernel is not yet configured, that is the next thing to do.Go to Kernel configuration, and follow normal procedures from there.

to upgrade both kernel and FreeS/WAN

You need both new kernel source and new FreeS/WAN source. Follow the full FreeS/WAN install procedure. See above.

Un-install

Disabling FreeS/WAN

In many Linux distributions, you can easily disable FreeS/WAN with the command:

    chkconfig --del ipsec

This removes the symlinks in /etc/rc.d/rc?.d which cause ipsec(8) to be called at boot time or when switching run levels. If the kernel part of IPsec, KLIPS, has been compiled as a module, then this also prevents loading that module, so IPsec is completely disabled.

Other distributions may use another version of init(8), or may not provide the chkconfig(8) command. For these, you will have to use other tools, or manually edit the init scripts, to achieve the same effect.

Removing FreeS/WAN files

If you installed FreeS/WAN from RPMs, then just use rpm -e to uninstall it. This section is for those who have installed from source.

To entirely remove the user-level FreeS/WAN components from your system, go to the FreeS/WAN install directory and give the command:

     make uninstall_freeswan

If that doesn't work for you -- for example, if FreeS/WAN was built on another system and copied here -- then you can do it manually. First disable FreeS/WAN as described above (to avoid problems with symlinks pointing to things you are about to remove), and then use these commands:

        rm -f /etc/ipsec.* /usr/local/sbin/ipsec /etc/rc.d/init.d/ipsec
        rm -rf /usr/local/lib/ipsec
        rm -f /usr/local/man/man?/ipsec[._]*

You may need to vary the commands slightly if you, or whoever packaged your distribution, changed the install directories when building FreeS/WAN.

Removing FreeS/WAN from the kernel

If you compiled KLIPS as a module, then just disabling FreeS/WAN as described above prevents loading the module.

If KLIPS is compiled into your kernel, then you can disable it by turning off IPsec in your kernel configuration (or by making it a module) and recompiling.

You can remove the FreeS/WAN patches from your kernel source by going to the FreeS/WAN install directory and giving the command:

     make unpatch

This does not remove all FreeS/WAN changes; some are not done with patch(1) and cannot be reversed in this way.

To remove all trace of IPsec in your kernel, you should revert to an unpatched version, or download fresh kernel source.

Configuration

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

This document is almost obsolete. It is being replaced by our new Quickstart Guide. We recommend that most users use that.

There are separate documents on testbed configurations and performance measurement which some users may want to consult along with this one. If you just want to get a few connections up, this document should have everything you need.

Before attempting this, you should:

• look at our introduction section. We assume here that you understand concepts and terms described there.
• ensure that FreeS/WAN is installed on your system. See these links:
  • testing whether FreeS/WAN is installed
  • performing an installation

You also need to set up and test IP networking on all the machines you plan to install FreeS/WAN on or to use in testing, before trying to set up FreeS/WAN.

Our example networks

In our examples, we describe a setup with three networks -- two that want to talk to each other plus the Internet in the middle. The idea is to build an encrypted tunnel across the Internet so the two networks can talk securely.

We'll call the two gateways East and West. We'll have a client machine on each net: Sunrise in the East and Sunset in the West.

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

Of course one does not always have a security gateway separate from the client machine. It is also quite common to use IPsec on a network that looks like this:

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

We treat this setup as degenerate cases of the network-to-network link. The East computer is a gateway for a one-client subnet, and it is also the client.

Our goal here is to tell you how to set up the two gateways, East and West. We assume your goal is to ensure that East and West encrypt all traffic between them.

More complicated network configurations are described later.

Set up and test networking

Before trying to get FreeS/WAN working, you should configure and test IP networking on both gateways and on at least one client machine behind each of them. IPsec cannot work without a working IP network beneath it.

Many reported "FreeS/WAN problems" turn out to actually be problems with routing or firewalling. If any actual IPsec problems turn up, you often cannot even recognise them (much less debug them) unless the underlying network is right.

If you need advice on this, your best sources are likely:

• the Networking Howto
• the Network Administrator's Guide.
• the Linux Networking-concepts HOWTO from Rusty Russell, author of most of the Linux firewalling code

See also our bibliography.

Here is our network diagram again:

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

The client machines, Sunrise and Sunset in our example, may have assigned routable IP addresses, or they may be using private non-routable addresses (as defined in RFC 1918 ) with the gateways doing IP masquerade. It doesn't matter which, as long as whatever it is works correctly. Note, however, that the two client subnets must have distinct addresses. You cannot have them both masqueraded to the same range of RFC 1918 addresses.

You must have a working IP network before you try to add IPsec:

• If Sunrise and Sunset have routable IP addresses, test that they can ping each other.
• If IP masquerading is in use, test as far as you can. Even with masquerading on both ends, Sunset should be able to ping East and Sunrise able to ping West.

It is not enough to just test that your gateways (East and West in the example) can communicate. You need to test routing to the clients (Sunrise and Sunset) as well.

If you want to run some service encapsulated in IP -- perhaps to use Novell protocols encapsulated in IPX or to make Windows file sharing or NT domains work across the IPsec tunnel -- then please build and test what you need for that service on plain IP before trying it over IPsec. It can be a real nightmare trying to debug such things when you don't know if the problem is in IPsec, firewall rules, routing, or the configuration of the service itself. Some advice on making such things work with IPsec is in our interoperation section.

Enabling packet forwarding

Some systems turn off packet forwarding by default. This is the safe default. You don't want systems forwarding packets in uncontrolled ways.

There are three places where you can enable or disable IP forwarding:

in kernel configuration, before compiling the kernel

for FreeS/WAN use, forwarding must always be enabled here. If forwarding is not compiled into your kernel, attempts to enable or use it will fail.

in the standard boot scripts.

If your kernel has forwarding, you can have it turned on automatically by the standard boot scripts. The exact method varies from distribution to distribution:

Older Redhat

in the file /etc/sysconfig/network, set FORWARD_IPV4=yes

Redhat 6.x and 7.0

in the file /etc/sysconfig/network, set net.ipv4.ip_forward=1

Debian r2.2 systems (and most likely Debian r2.2 derived systems):

in the file /etc/network/options, set ip_forward=yes

From the command line or your own scripts

use the command:

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

You need root privileges to write to that file.

A gateway machine needs forwarding enabled or it will not route packets between the two networks it is attached to. The simplest way to ensure this is to enable forwarding using your distribution's standard boot scripts. See above.

A more conservative approach is to disable forwarding in your system configuration, and only enable it after appropriate firewall rules and IPsec tunnels are in place. This reduces the risk of something slipping past your defenses before they are fully set up. On most systems, this can conveniently be done by adding a line to /etc/rc.d/rc.local , which is usually the last script run at boot time.

Other software

Configure and test any other software you will want to use for testing once IPsec is up. For example, you might put an HTTP daemon on Sunset and a browser on Sunrise. Make sure these work without IPsec.

If these tests fail, figure out why and fix it. Do not proceed until it works.

Setting up RSA authentication keys

To build a connection, the two gateway machines must be able to authenticate each other. For FreeS/WAN, the default is public key authentication based on the RSA algorithm. IPsec does allow several other authentication methods; using some of them with FreeS/WAN is discussed in our advanced configuration section.

This section covers setting up RSA keys. The example connections to follow (VPN, road warrior and opportunistic) all use RSA.

How RSA works

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

• a public key which need not be kept secure. Everyone you plan to communicate with must be able to get a copy of this. It does not matter if an enemy gets it as well.
• a private key which must be kept secure. No-one but you should have access to it.

For FreeS/WAN, both keys for your system are in the ipsec.secrets(5) file. Maintaining security of this file is essential since it holds your private key.

Public keys for the gateways you communicate with must be made available to your gateway. There are several ways to do this:

• arrange for the administrators of those gateways to place their public keys in their DNS records so your gateway can look them up as required
• collect the public keys for the gateways you talk to, and place them in the connection descriptions for those gateways in ipsec.conf(5).
• if you are using the X.509 patches, collect X.509 certificates for the other gateways, and place them in the appropriate file

The first two methods are described in more detail below. See the X.509 patch documentation for details of the third, if required.

Remember that public key systems are designed so that it does not matter if an enemy knows the public keys. However, the private keys must be scrupulously protected.

Generating an RSA key pair

If you installed FreeS/WAN yourself, then the installation process has already generated an RSA key pair for you and placed it in the ipsec.secrets(5) file. If not, then you need to generate an RSA key pair (private and public).

If you have the common simple situation where:

• the gateway needs only one RSA private key
• the output of the hostname command is a suitable identifier

then you can just give these commands as root:

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

For other options, for example if you want to use different identities with different partners, see the ipsec.secrets(5) and ipsec_newhostkey(8) man pages.

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

for a VPN

each gateway administrator needs public keys for all the other gateways his or her machine talks to

for a Road Warrior

the gateway needs public keys for all Warriors that connect to it, and each Warrior needs the gateway public key

for opportunistic encryption

no explicit key exchange is needed, but you must put your public key in DNS so others can find it when they need it

You need to extract the public part in a suitable suitable format. This done with the ipsec_showhostkey(8) command. For VPN or Road Warrior applications, use one of:

        ipsec showhostkey --left
        ipsec showhostkey --right

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

For opportunistic encryption, just use:

        ipsec showhostkey

Public keys need not be protected as fanatically as private keys. They are intended to be made public; the system is designed to work even if an enemy knows all the public keys used. You can safely make them publicly accessible -- for example, put a gateway key on a web page, make in available in DNS or via finger(1) -- or transmit it with an insecure method such as email. However, the recipient must be able to authenticate them, as described in the next section.

Authenticating public key exchange

For example, consider the fellow who wants to communicate with his mistress, keeping messages secret from his wife.

• If the wife obtains the mistress' public key, that is not a problem. As long as she does not get the private key, she can neither read things sent to the mistress nor authenticate herself as the mistress.
• If the mistress has any sense, she protects her private key carefully. So long as she does that, and the husband encrypts his messages correctly, there should be no (cryptographic!) problem.
• Imagine that the wife is somewhat devious. She generates a public/private key pair and sends the husband that public key, forging the message to look as if it came from the mistress. Of course this fails if the husband has enough sense to check the key's validity before using it.
• However, if the husband blindly accepts that key without verification, it is extremely unlikely that he will be pleased with the results.
• If he accepts that key, the wife can read every message he sends to it. The mistress cannot.
• The wife can also pose as the mistress and send him whatever bogus messages she likes. As long as he trusts that key, he will believe these came from the mistress.

The minute he begins to trust a bogus key, the cryptography does not just stop working for him. Instead, it becomes a powerful weapon against him.

You must authenticate any public keys received before using them. For remote sites, the simplest method is to exchange them using PGP-signed email (taking appropriate steps to authenticate the signing keys). Keys posted on the web or made available for finger(1) should also be PGP-signed. Keys in DNS should be protected by DNS Security. For nearby machines, a floppy disk or trusted network is fine.

Using RSA signatures for authentication

For each system you will communicate with, you need an RSA public key and an identifier associated with it. The identifiers go in the leftid= and rightid= lines of connection descriptions in ipsec.conf(5). They are the names the systems use to identify themselves during connection negotiation.

The syntax rules allow four types of identifier:

• an IP address in dotted quad notation, four numbers separated by periods (10.1.19.32).
• a domain name, which will be resolved immediately (bad.example.com).
• a fully qualified domain name (FQDN) with a leading "@" to indicate that it should not be resolved (@good.example.com)
• user@FQDN (fred@example.com)

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

• IP addresses make remarkably uninteresting names
• Resolving a name to an IP address is not useful. Why pay the overheads just to get something that, in this context, is less interesting than the name you started with? Also, the attempt to resolve it may cause long delays if DNS is down or may cause security problems if someone subverts a DNS server which you rely on.
• fred@example.com has no advantage over @fred.example.com

If your domain is example.com, the gateway identifiers you use should be all be of the form "@something.example.com" with some convenient string replacing something.

In order to facilitate distributing keys through DNS, we recommend avoiding

• names from non-existent domains
• names from other people's domains
• names which conflict with machine names in your domain
• user@FQDN

For example, if you have a server alice.example.com, then you should not use "@alice.example.com" to identify Alice's laptop for IPsec.

One convenient scheme is to

use DNS names for your gateways

their IPsec identifiers are things like @firewall.example.com or @toronto.example.com

add a "road" label in the identifiers for your remote users ("Road Warriors")

Alice's laptop uses the identifier @alice.road.example.com.

The configuration file

FreeS/WAN uses a configuration file, ipsec.conf(5).

config setup section

describes machine configuration

conn default section

default parameters which apply to all connections

and gives an introduction to the parts of the file that specify the actual connections. The following section covers setting up three common types of connection, all using automatic keying with RSA authentication of the gateways:

conventional VPN

two security gateways, each with a known fixed IP address and with a network of client machines behind it

Road Warrior

one player has a dynamically-assigned address

opportunistic encryption

the two machines have no prior knowledge of each other, but are set up to secure connections whenever possible

Setup is quite similar for each of these, but details differ.

Other types of connections are covered in later sections.

The easiest way to create a connection is by editing one of our examples. Here we will use the one in the installation ipsec.conf file. You could also start with one from our doc/examples file if one of those is closer to what you need to do.

General comments on ipsec.conf

• the '#' character marks a comment
• the first uncommented line of a section must be at the margin, not indented
• all other non-comment lines of a section must be indented
• blank lines separate sections
• you cannot put a blank line within a section; use a lone '#' instead

For more detail, see the man page.

Which is which?

The confguration file uses left and right to refer to the two gateways involved in a connection, and has other parameters which come in left/right pairs. For example, leftsubnet is the subnet behind left.

Which gateway is left and which is right is arbitrary, entirely up to you.

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

To simplify administration, we recommend that you use the same names in the ipsec.conf(5) files on both ends. The name reno , for example, should refer to the machine in Reno, no matter which city the file is in.

Then when you copy the file from one machine to the other, the only change you need to make on the second machine is changing the interfaces= line to match the interface that machine uses for IPsec.

Of course the software does not actually require this. The names are just arbitrary strings to it. If your administrator in Reno wants to refer to the machines as "Phobos" and "Demios" while the Vancouver admin calls them "George" and "Gracie", things should still work.

The setup section of ipsec.conf(5)

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

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

The variables set here are:

interfaces

Tells the KLIPS IPsec code in the Linux kernel which network interface to use. The interfaces specified here are the only ones this gateway machine will use to communicate with other IPsec gateways. If this is not correct, nothing works.

In many cases, the appropriate interface is just your default connection to the world (the Internet, or your corporate network). In these cases, you can use the default setting:

• interfaces=%defaultroute

To check what FreeS/WAN sees as the default route, you can use the command ipsec showdefaults. You may need to compare this with the output from route -n to get a more complete picture.

In other cases, you can name one or more specific interfaces to be used by FreeS/WAN. For example:

• interfaces="ipsec0=eth0"
• interfaces="ipsec0=eth0 ipsec1=ppp0"

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

Note that

• Multiple tunnels do not require multiple interfaces. It is possible, and even common, to have one ipsec interface carrying traffic for many tunnels.
• For PPP connections, you specify the virtual PPP interface (for example ppp0) here, not the underlying physical interface.

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

              ifconfig
      

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

klipsdebug

Debugging setting for the KLIPS kernel code

plutodebug

Debugging setting for the Pluto key and connection negotiation daemon.

klipsdebug and plutodebug can each be set to "none" or to "all" in most circumstances. There are other options; see the relevant man pages.

plutoload

List of connections to be automatically loaded into memory when Pluto starts.

plutostart

List of connections to be automatically negotiated when Pluto starts.

plutoload and plutostart can be quoted lists of connection names, but are often set to %search as in our example. Any connection with auto=add in its connection definition is then loaded, and any connection with auto=start is started.

In most cases, you want plutostart=%search here and auto=start in your connection descriptions. That way when a connection is broken, for example if one machine crashes or is taken down for some reason, it will be reliably rebuilt. If only one end is told to start the connection, then if the other end crashes, you may lose the connection for a long time. The end that could rebuild does not know it needs to.

The exception to the above is when you have many road warriors connecting to a single gateway. Having the gateway trying to rebuild tunnels to systems which are offline can waste considerable resources. In this case, the gateway should have auto=add for all connections, and let the remote systems start negotiations.

uniqueids

Controls whether two connections with the same subnet on the remote end are allowed. Normally this is set to yes so that when a remote system disconnects and reconnects, Pluto will automatically take the old connection down.

Connection defaults

There is a special name %default that lets you define things that apply to all connections.

You can also set general defaults here but override them later for specific connections. If both the %default section and the actual connection description set the same variable, then the connection description takes precedence.

Our example file has:

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

Variables set here are:

keyingtries

How persistent to be in (re)keying negotiations (0 means very).

For testing, you might wish to set this to some small number, perhaps even to 1, to avoid wasting resources on incorrectly set up connections. In production, it is often set to zero (retry forever). Keeping the connection up is what machine resources are for, so if a connection is down you might as well waste resources retrying as waste them by sitting idle. Of course some caution should be exercised with this, since it can waste network resources as well.

authby=rsasig

authenticate gateways using RSA signatures. This is the preferred method and is what we will use in this section's examples. An alternate method is to use shared secrets.

auto=add

automatically add connections descriptions to Pluto's in-memory database at startup. This is required before Pluto can recognise incoming requests for that connection, so we suggest making it the default here.

To actually start negotiations for a given connection, you need auto=start. You could make that the default here or leave auto=add as the default and override it where needed with auto=start in individual connection descriptions.

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

Editing a connection description

Edit our example connection to match what you want to do. Rename it appropriately for the connection you would like to build: "fred-susan", "reno-van" or whatever. The name is the second string in the line that begins with "conn", for example in:

        conn snt

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

        conn reno-van

A sample connection description is:

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

We omit here the variables we have shown as set in the default connection above. All of them could also be set here. If they are set in both places, settings here take precedence. Defaults are used only if the specific connection description has no value set.

The network described above looks like this:

         subnet 172.16.0.0/24              =leftsubnet
                |
                |                          [whatever]
                |
         inside interface
            left gateway machine
         interface 10.0.0.1                =left
                 |
         interface 10.44.55.66             =leftnexthop
              router
         interface we don't know
                 |
            INTERNET
                 |
         interface we don't know
              router
         interface 10.88.77.66             =rightnexthop
                 |
         interface 10.12.12.1              =right
            right gateway machine
         inside interface
                 |
                 |                         [whatever]
                 |
         subnet 192.168.0.0/24             =rightsubnet

The [whatever]s above indicate places where all that matters is routing.

• in simple cases, the inside interface is directly connected to the protected subnet and has an address on that subnet
• in a large organisation, there might be several routers between gateway and subnet

You do not need to tell FreeS/WAN anything about the inside interfaces. In fact, there is no parameter you could use to do that. What you do have to do is make sure the gateway can route to its client subnet.

In most cases, you should use numeric IP addresses, not names, here. The file syntax allows names to be used, but this creates an additional risk. If someone can subvert the DNS service, then they can redirect packets whose addresses are looked up via that service.

Many of the variables in this file come in pairs such as "leftsubnet: and "rightsubnet", one for each end of the connection. The variables on the left side are:

left

The gateway's external interface, the one it uses to talk to the other gateway. This can be left=%defaultroute.

leftnexthop

Where left should send packets whose destination is right, typically the first router in the appropriate direction.

This need not always be set.

• If the two gateways are directly linked (packets can go from one to the other without IP routing by any intermediate device) then you need not set either leftnexthop or rightnexthop.
• a connection with left=%defaultroute or right=%defaultroute must not have the corresponding nexthop parameter set

However, in all other cases, you must provide nexthop information. KLIPS (Kernel IP Security) bypasses the normal routing machinery, so you must give KLIPS the information even though routing already knows it.

(Yes, we know that design is not ideal, and we plan to change it. See extensive discussions on the mailing list, mostly with "routing" or "KLIPS 2" in the subject lines.)

leftsubnet

Addresses for the machines which left is protecting.

• Often something like 101.202.203.0/24 to indicate that a subnet resides behind left. Often this subnet will be directly connected to left, but this not necessary. The only requirement is that left must be able to route to it.
• If you omit the leftsubnet line, then left is both the security gateway and the only client on that end.

For some applications, you may want to create two connections, one to protect traffic from the subnet behind left and another to protect traffic from the left gateway itself. This takes two connection descriptions. See below.

auto

If the conn setup section has plutoload=%search , then all connections marked auto=add are loaded when Pluto starts.

If the conn setup section has plutostart=%search , then all connections marked auto=start are started when Pluto starts.

Initially, we suggest using auto=add on all connections. This lets you start them manually during testing. Once they are tested, you can change many of them to auto=start.

For each left* parameter, there is a corresponding right* parameter.

Note that a connection to a subnet behind left does not include left itself. The tunnel described above protects packets going from one subnet to the other. It does not apply to packets which either begin or end their journey on one of the gateways. If you need to protect those packets, you must build separate tunnel descriptions for them.

It is a common error to attempt testing a subnet-to-subnet connection by pinging from one of the gateways to the far end or vice versa. This does not work, even if the connection is functioning perfectly, because traffic to or from the gateway itself is not sent on that connection. If you want to protect traffic originating or terminating on the gateway, then you need a separate tunnel for that in addition to the subnet's tunnel. See the section on multiple tunnels.

Example setups

In this section we show examples of three common setups:

• a VPN connection
• road warrior support
• opportunistic encryption

We use a, b, c ... to indicate components of IP addresses. Each letter is some number in the range 0 to 255, inclusive.

For additional examples, see our examples file.

VPN

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

which we describe in our config files as:

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

In most cases, we also have to provide next hop information. A more detailed diagram might look like this:
(using a, b, c, ... to refer to arbitrary numbers 0 to 255)

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

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

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

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

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

For more on the use of the firewalling parameters -- leftfirewall, rightfirewall, leftupdown and rightupdown -- see our IPsec and firewalls section.

The versions of this file at the two ends should be identical, except that each must have an interfaces= line appropriate for the local machine.

Routable and non-routable addresses

RFC 1918 reserves three groups of addresses for use on private networks:

• 10.0.0.0/8
• 172.16.0.0/12
• 192.168.0.0/16

Addresses in these ranges will never be assigned to anything on the Internet. Many routers automatically drop any packet with one of these addresses as either source or destination.

You can use FreeS/WAN to:

• make such a network visible to remote clients. For example, with the above description, any of the client machines on the leftsubnet can talk to machines on rightsubnet=192.168.0.0/24.
• route between two such networks, using for example leftsubnet=192.168.1.0/24 and rightsubnet=192.168.0.0/24 .

If you do this, the non-routable addresses still do not appear on the Internet. They are encapsulated inside IPsec packets which have the gateways' external addresses (from the left and right parameters of the connection description) in their headers.

Of course FreeS/WAN can also tunnel packets between subnets with normal routable IP address.

Road Warrior

For our purposes, a "road warrior" is any machine that does not have a fixed IP address. This includes:

• a traveller who might connect from anywhere
• any machine that has a dynamic IP address -- nearly all dialup connections and most DSL or cable modem connections, at least in North America
• most home machines connecting to the office. If you have a home firewall that is always left on and has a static IP address, then you can use the VPN configuration described above. Otherwise, consider yourself a road warrior.

The configuration for road warrior support looks slightly different from a VPN configuration. We cannot use the road warrior's IP address in the configuration file since we don't know it, and we don't want to have our server retrying connections to road warriors that are no longer online.

Some machines, such as home firewalls, may have a dynamic IP address and have a protected subnet behind them. For this example, however, we assume the Road Warrior is a standalone machine:

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

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

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

Here the ipsec.conf(5) files on the two ends are slightly different. The one at the office might have exactly the same config setup and conn %default sections as in the VPN example.

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

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

Then add a description for the road warrior connection:

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

On the gateway end we use the values shown above:

• right=%any so we have no preset idea of right's IP address and will accept whatever arrives on the packets
• auto=add so we accept connections but don't initiate
• keyingtries=1 so we do not retry to excess when the partner disconnects or changes IP address

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

• interfaces=%defaultroute to handle the dynamic IP address.
• right=%defaultroute
• auto=start to start the connection
• keyingtries=0 to try to maintain the connection

Because we are using right=%defaultroute, we omit the rightnexthop parameter.

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

If necessary, a single road warrior can have multiple connections, all with the same rightid and rightrsasigkey, but with different values for leftsubnet to give access to different parts of the office network.

Jean-Francois Nadeau's Practical Configurations document also has an example of using RSA authentication for road warriors.

Opportunistic encryption

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 main documentation items so far are:

• an Opportunism HowTo by Pluto programmer Hugh Redelmeier
• the project's internal opportunism design document by Hugh and technical lead Henry Spencer.
• an Internet Draft by Michael Richardson, Hugh and Henry. This is largely a rewrite of the internal document, a first step toward getting the protocol standardised so there can be multiple implementations of it.

We do not yet recommend this code for production use . You should still protect your critical data with explicitly configured IPsec tunnels, rather than relying on opportunistic for everything at this stage.

ipsec.conf entries for opportunism

The relevant lines in the config file might look like this:

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

The public key, in our format, must be in a KEY record of the appropriate DNS entry for this to work. We provide some background information on DNS in another file.

Each opportunistic connection supports a single source/destination pair of IP addresses. There is no way to build an opportunistic connection for a larger subnet. Specifying a subnet in the connection description, as in the example above, just means that any host in that subnet may have opportunistic connections.

Putting IPsec information in DNS

• 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

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

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.

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"

42.42.42.10.in-addr.arpa. IN PTR deepthought.example.com.
                          IN TXT "X-IPsec-Server(10)=10.20.30.40 AQNJjkKlIk9...nYyUkKK8"

DNS records for gateway systems

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

If you don't control the gateway's reverse map

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"

something.example.org. IN A 10.20.30.40
something.example.org. IN KEY 0x4200 4 1 AQNJjkKlIk9...nYyUkKK8

With this arrangement, the remote gateway receives an ID payload early in IKE with your (bogus) gateway name "something.example.org". Then it looks up that name to get the IP address and key for the gateway.

Going beyond the examples

If your network is simple enough that one of the examples had all you need, then you can skip ahead to firewall setup .

Simplifying ipsec.conf files

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

• a conn %default connection description for information common to all connections
• also= lines allow a piece of a description to be defined in one place and used in several (the definition must be after all references)
• include directives allow information to be stored in separate files but used as part of the configuration

These can be combined in whatever way suits your application. One example is this ipsec.conf file for a gateway supporting multiple road warriors, all using RSA authentication:

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

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

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

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

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

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

Be careful with the order of sections in ipsec.conf(5) and any included files. The parser requires that a definition comes after the also= line which uses it. In our example, the include inserts the files with the also=leftstuff lines before the definition of conn leftstuff so things are parsed in the correct order.

The above method, using conn leftstuff and also= , is only one alternative. In simple cases, you can just put all the information about the left gateway in the conn default section instead and use no also= lines.

Is there a firewall in play?

If firewall packet filtering is being done on either of the FreeS/WAN gateway machines, or on any machine on the path between them, then you will probably need to adjust the filters before FreeS/WAN can work. The filters must allow:

• UDP packets between port 500 on one gateway and port 500 on the other, used by the automatic keying daemon Pluto.
• at least one of protocol 50 (ESP) and 51 (AH). Most applications want ESP since AH does only authentication, not encryption.

For more detail, see our IPsec and firewalls document.

Testing the installation

This section covers testing connections once you have FreeS/WAN installed and your ipsec.conf(5) file set up. A separate testing document has more information if required.

We assume all your connection descriptions use auto=add so that ipsec_pluto(8) loads the descriptions into its internal database at startup but does not attempt to start the connections until you tell it to.

Matching numbers

It is important that the numbers in your connection descriptions match the network configuration. FreeS/WAN is almost certain to fail if they do not.

Suppose you are at the Reno office and your ipsec.conf file now has, among others, these lines:

config setup
        interfaces="ipsec0=eth0"

conn reno-van
        left=101.101.101.101
        right=202.202.202.202

When you tell FreeS/WAN to start the reno-van connection, it doesn't automagically know that it is in Reno, or that it is left in the configuration. It discovers that by comparing the IP address for ipsec0 (and, if it is set, for ipsec1) to the addresses for left and right. ipsec0 inherits its address from the underlying device, eth0 in our example.

So in our example, if eth0 has IP address 101.101.101.101 then ipsec0 inherits that address, the correct match is found, and this FreeS/WAN discovers that it is left. (If no match is found, Pluto reports "unable to orient connection".) It then sets itself up with any other left* parameters in use -- some of leftnexthop , leftsubnet, and leftid.

Once it has these parameters, FreeS/WAN sets things so that

• packets from leftsubnet addressed to rightsubnet are routed through a tunnel to right.
• packets for leftsubnet can be received on the tunnel and delivered.

All should be well.

Of course, there must also be interfaces and routes set up so that this machine can exchange IP packets both with the right gateway and with clients on leftsubnet. This is done with standard Linux utilities such as ifconfig(8) and route(8). Also, things must be correct on right in Vancouver. It takes two to tunnel.

A data mismatch anywhere in this configuration will cause FreeS/WAN to fail and to log various error messages. Depending on just how confused FreeS/WAN is and about what, the error messages may be somewhat confusing. See our troubleshooting section and the FAQ section om error messages to get help interpreting them if required.

We recommend double-checking for consistency here before starting actual tests..

Sanity checking

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

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

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

• ipsec_eroute
• ipsec_spi
• ipsec_spigrp
• ipsec_spinew
• ipsec_tncfg
• ipsec_version

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

        cat /proc/net/ipsec_tncfg

You should see at least device ipsec0, and each ipsec device should point to a physical device, eg. 'ipsec0 -> eth0 mtu=16260 -> 1500'.

Routing connections through these ipsec pseudo-devices causes the data to be encrypted before being delivered to the underlying network interface. This can be done manually with our eroute(8) utility, but in most cases you do not need to use that utility directly. Just bring the connections up and down and the scripts call it as required.

Don't be surprised when you cannot find /dev/ipsec0 or /dev/ipsec1. They do not exist. Other network pseudo-devices such as eth0 and eth1 do not have entries in /dev either. In general, network devices do not need such entries.

Starting a connection

On one gateway, start IPsec with:

        ipsec auto --up name

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

Note that to shut down a connection, you must do:

        ipsec auto --down name

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

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

        ipsec look

and see if the output looks something like this:

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

If it does, you're probably in business.

This example shows:

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

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

The routing is:

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

This routes all traffic to the protected network 11.0.1.0/24 through an IPsec tunnel to the gateway 11.0.0.1.

Ping tests

If that works, test whether Sunrise can ping Sunset and vice versa. Our example setup again is:

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

There is no point in testing to or from the gateways themselves; the goal is to secure traffic between the subnets, not between the security gateways themselves.

In general, pings or other tests using the public interfaces of East and/or West are entirely useless. The IPsec tunnel is for packets between the two protected subnets and the outside interfaces are not on those subnets. Depending on your routing configuration, test packets sent via those interfaces will be:

• either transmitted in the clear, bypassing the tunnel,
• or discarded because there is no tunnel in place to handle them

In either case, they tell you nothing about the tunnel .

Sometimes it will be inconvenient to use the client machines (Sunrise and Sunset in our example) for testing. In these cases, use a command such as:

     traceroute -i eth0 -f 20 192.168.7.1

where each of the interfaces specified (eth0 and 192.168.7.1 in the example) are on one of the protected subnets, eth0 being the local gateway's interface on that side and 192.168.7.1 the remote gateway's subnet interface. This forces the packets through the IPsec tunnel you want to test.

For information on setting things up so that gateways can do IPsec to each other or to remote subnets, see below.

If you have other software set up, test with it as well. Telnet from Sunrise to Sunset, browse a web server on the remote net and so on.

Testing with tcpdump

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

This is most easily done from a third machine, rather than from one of the gateways. On the gateways you may see packets at intermediate stages of processing and the result may be confusing.

If the results make no sense at all, or you see "bad physical medium" error messages, you probably have an outdated version of tcpdump(8) that does not handle IPsec at all. See this discussion.

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

Shutting down connections

To shut down a connection, you must do:

        ipsec auto --down name

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

Again, you can verify with the same commands. Repeat the ping test. Repeat the tcpdump test.

If everything succeeds, congratulations. You now have a working Linux FreeS/WAN installation.

What next?

At this point you should have a working FreeS/WAN setup. If not, you could go back and doublecheck various things above or try:

• our FAQ
• our troubleshooting section
• additional configuration examples

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

• more detail on the IPsec protocols
• history and politics of cryptography
• advanced configuration, other ways to configure FreeS/WAN connections
• interoperating with other IPsec implementations

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

Linux FreeS/WAN background

This section discusses a number of issues which have three things in common:

• They are not specifically FreeS/WAN problems
• You may have to understand them to get FreeS/WAN working right
• They are not simple questions

Grouping them here lets us provide the explanations some users will need without unduly complicating the main text.

The explanations here are intended to be adequate for FreeS/WAN purposes (please comment to the users mailing list if you don't find them so), but they are not trying to be complete or definitive. If you need more information, see the references provided in each section.

Some DNS background

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

Much good reference material is available for DNS, including:

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

We give only a brief overview here, intended to help you use DNS for FreeS/WAN purposes.

Forward and reverse maps

Although the implementation is distributed, it is often useful to speak of DNS as if it were just two enormous tables:

• the forward map: look up a name, get an IP address
• the reverse map: look up an IP address, get a name

Both maps can optionally contain additional data. For opportunistic encryption, we insert the data need for IPsec authentication.

A system named gateway.example.com with IP address 10.20.30.40 should have at least two DNS records, one in each map:

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.

Hierarchy and delegation

For both maps there is a hierarchy of DNS servers and a system of delegating authority so that, for example:

• the DNS administrator for example.com can create entries of the form name.example.com
• the example.com admin cannot create an entry for counterexample.com; only someone with authority for .com can do that
• an admin might have authority for 20.10.in-addr.arpa.
• in either map, authority can be delegated
  • the example.com admin could give you authority for westcoast.example.com
  • the 20.10.in-addr.arpa admin could give you authority for 30.20.10.in-addr.arpa

DNS zones are the units of delegation. There is a hierarchy of zones.

Syntax of DNS records

Returning to the example records:

        gateway.example.com. IN A 10.20.30.40
        40.30.20.10.in-addr.arpa. IN PTR gateway.example.com.

some syntactic details are:

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

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

• Address, for forward lookups
• PoinTeR, for reverse lookups
• Canonical NAME, records to support aliasing, multiple names for one address
• Mail eXchange, used in mail routing
• SIGnature, used in secure DNS
• KEY, used in secure DNS
• TeXT, a multi-purpose record type