Introduction to FreeS/WAN

FreeS/WAN is a Linux implementation of the IPsec (IP security) protocols. IPsec provides encryption and authentication services at the IP (Internet Protocol) level of the network protocol stack.

Working at this level, IPsec can protect any traffic carried over IP, unlike other encryption which generally protects only a particular higher-level protocol -- PGP for mail, SSH for remote login, SSL for web work, and so on. This approach has both considerable advantages and some limitations. For discussion, see our IPsec section

IPsec can be used on any machine which does IP networking. Dedicated IPsec gateway machines can be installed wherever required to protect traffic. IPsec can also run on routers, on firewall machines, on various application servers, and on end-user desktop or laptop machines.

Three protocols are used

AH (Authentication Header) provides a packet-level authentication service
ESP (Encapsulating Security Payload) provides encryption plus authentication
IKE (Internet Key Exchange) negotiates connection parameters, including keys, for the other two

Our implementation has three main parts:

KLIPS (kernel IPsec) implements AH, ESP, and packet handling within the kernel
Pluto (an IKE daemon) implements IKE, negotiating connections with other systems
various scripts provide an adminstrator's interface to the machinery

IPsec is optional for the current (version 4) Internet Protocol. FreeS/WAN adds IPsec to the Linux IPv4 network stack. Implementations of IP version 6 are required to include IPsec. Work toward integrating FreeS/WAN into the Linux IPv6 stack has started.

For more information on IPsec, see our IPsec protocols section, our collection of IPsec links or the RFCs which are the official definitions of these protocols.

Interoperating with other IPsec implementations

IPsec is designed to let different implementations work together. We provide:

a list of some other implementations
information on using FreeS/WAN with other implementations

The VPN Consortium fosters cooperation among implementers and interoperability among implementations. Their web site has much more information.

Advantages of IPsec

IPsec has a number of security advantages. Here are some independently written articles which discuss these:

SANS institute papers. See the section on Encryption &VPNs.
Cisco's white papers on "Networking Solutions".
Advantages of ISCS (Linux Integrated Secure Communications System; includes FreeS/WAN and other software).

Applications of IPsec

Because IPsec operates at the network layer, it is remarkably flexible and can be used to secure nearly any type of Internet traffic. Two applications, however, are extremely widespread:

a Virtual Private Network, or VPN, allows multiple sites to communicate securely over an insecure Internet by encrypting all communication between the sites.
"Road Warriors" connect to the office from home, or perhaps from a hotel somewhere

There is enough opportunity in these applications that vendors are flocking to them. IPsec is being built into routers, into firewall products, and into major operating systems, primarily to support these applications. See our list of implementations for details.

We support both of those applications, and various less common IPsec applications as well, but we also add one of our own:

opportunistic encryption, the ability to set up FreeS/WAN gateways so that any two of them can encrypt to each other, and will do so whenever packets pass between them.

This is an extension we are adding to the protocols. FreeS/WAN is the first prototype implementation, though we hope other IPsec implementations will adopt the technique once we demonstrate it. See project goals below for why we think this is important.

A somewhat more detailed description of each of these applications is below. Our quickstart section will show you how to build each of them.

Using secure tunnels to create a VPN

A VPN, or Virtual Private N etwork lets two networks communicate securely when the only connection between them is over a third network which they do not trust.

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

If the cryptography is strong, the implementation is careful, and the administration of the gateways is competent, then one can reasonably trust the security of the tunnel. The two networks then behave like a single large private network, some of whose links are encrypted tunnels through untrusted nets.

Actual VPNs are often more complex. One organisation may have fifty branch offices, plus some suppliers and clients, with whom it needs to communicate securely. Another might have 5,000 stores, or 50,000 point-of-sale devices. The untrusted network need not be the Internet. All the same issues arise on a corporate or institutional network whenever two departments want to communicate privately with each other.

Administratively, the nice thing about many VPN setups is that large parts of them are static. You know the IP addresses of most of the machines involved. More important, you know they will not change on you. This simplifies some of the admin work. For cases where the addresses do change, see the next section.

Road Warriors

The prototypical "Road Warrior" is a traveller connecting to home base from a laptop machine. Administratively, most of the same problems arise for a telecommuter connecting from home to the office, especially if the telecommuter does not have a static IP address.

For purposes of this document:

anyone with a dynamic IP address is a "Road Warrior".
any machine doing IPsec processing is a "gateway". Think of the single-user road warrior machine as a gateway with a degenerate subnet (one machine, itself) behind it.

These require somewhat different setup than VPN gateways with static addresses and with client systems behind them, but are basically not problematic.

There are some difficulties which appear for some road warrior connections:

Road Wariors who get their addresses via DHCP may have a problem. FreeS/WAN can quite happily build and use a tunnel to such an address, but when the DHCP lease expires, FreeS/WAN does not know that. The tunnel fails, and the only recovery method is to tear it down and re-build it.
If Network Address Translation (NAT) is applied between the two IPsec Gateways, this breaks IPsec. IPsec authenticates packets on an end-to-end basis, to ensure they are not altered en route. NAT rewrites packets as they go by. See our firewalls document for details.

In most situations, however, FreeS/WAN supports road warrior connections just fine.

Opportunistic encryption

One of the reasons we are working on FreeS/WAN is that it gives us the opportunity to add what we call opportuntistic encryption. This means that any two FreeS/WAN gateways will be able to encrypt their traffic, even if the two gateway administrators have had no prior contact and neither system has any preset information about the other.

Both systems pick up the authentication information they need from the DNS (domain name service), the service they already use to look up IP addresses. Of course the administrators must put that information in the DNS, and must set up their gateways with opportunistic encryption enabled. Once that is done, everything is automatic. The gateways look for opportunities to encrypt, and encrypt whatever they can. Whether they also accept unencrypted communication is a policy decision the administrator can make.

This technique can give two large payoffs:

It reduces the administrative overhead for IPsec enormously. You configure your gateway and thereafter everything is automatic. The need to configure the system on a per-tunnel basis disappears. Of course, FreeS/WAN allows specifically configured tunnels to co-exist with opportunistic encryption, but we hope to make them unnecessary in most cases.
It moves us toward a more secure Internet, allowing users to create an environment where message privacy is the default. All messages can be encrypted, provided the other end is willing to co-operate. See our history and politics of cryptography section for discussion of why we think this is needed.

Opportunistic encryption is not (yet?) a standard part of the IPsec protocols, but an extension we are proposing and demonstrating. For details of our design, see links below.

Only one current product we know of implements a form of opportunistic encryption. Secure sendmail will automatically encrypt server-to-server mail transfers whenever possible.

The need to authenticate gateways

A complication, which applies to any type of connection -- VPN, Road Warrior or opportunistic -- is that a secure connection cannot be created magically. There must be some mechanism which enables the gateways to reliably identify each other. Without this, they cannot sensibly trust each other and cannot create a genuinely secure link.

Any link they do create without some form of authentication will be vulnerable to a man-in-the-middle attack. If Alice and Bob are the people creating the connection, a villian who can re-route or intercept the packets can pose as Alice while talking to Bob and pose as Bob while talking to Alice. Alice and Bob then both talk to the man in the middle, thinking they are talking to each other, and the villain gets everything sent on the bogus "secure" connection.

There are two ways to build links securely, both of which exclude the man-in-the middle:

with manual keying, Alice and Bob share a secret key (which must be transmitted securely, perhaps in a note or via PGP or SSH) to encrypt their messages. For FreeS/WAN, such keys are stored in the ipsec.conf(5) file. Of course, if an enemy gets the key, all is lost.
with automatic keying, the two systems authenticate each other and negotiate their own secret keys. The keys are automatically changed periodically.

Automatic keying is much more secure, since if an enemy gets one key only messages between the previous re-keying and the next are exposed. It is therefore the usual mode of operation for most IPsec deployment, and the mode we use in our setup examples. FreeS/WAN does support manual keying for special circumstanes. See this section.

For automatic keying, the two systems must authenticate each other during the negotiations. There is a choice of methods for this:

a shared secret provides authentication. If Alice and Bob are the only ones who know a secret and Alice recives a message which could not have been created without that secret, then Alice can safely believe the message came from Bob.
a public key can also provide authentication. If Alice receives a message signed with Bob's private key (which of course only he should know) and she has a trustworthy copy of his public key (so that she can verify the signature), then she can safely believe the message came from Bob.

Public key techniques are much preferable, for reasons discussed later, and will be used in all our setup examples. FreeS/WAN does also support auto-keying with shared secret authentication. See this section.

The FreeS/WAN project

For complete information on the project, see our web site, freeswan.org.

In summary, we are implementing the IPsec protocols for Linux and extending them to do opportunistic encryption.

Project goals

Our overall goal in FreeS/WAN is to make the Internet more secure and more private.

Our IPsec implementation supports VPNs and Road Warriors of course. Those are important applications. Many users will want FreeS/WAN to build corporate VPNs or to provide secure remote access.

However, our goals in building it go beyond that. We are trying to help build security into the fabric of the Internet so that anyone who choses to communicate securely can do so, as easily as they can do anything else on the net.

More detailed objectives are:

extend IPsec to do opportunistic encryption so that
- any two systems can secure their communications without a pre-arranged connection
- secure connections can be the default, falling back to unencrypted connections only if:
  - both the partner is not set up to co-operate on securing the connection
  - and your policy allows insecure connections
- a significant fraction of all Internet traffic is encrypted
- wholesale monitoring of the net (examples) becomes difficult or impossible
help make IPsec widespread by providing an implementation with no restrictions:
- freely available in source code under the GNU General Public License
- running on a range of readily available hardware
- not subject to US or other nations' export restrictions.
  Note that in order to avoid even the appearance of being subject to those laws, the project cannot accept software contributions -- not even one-line bug fixes -- from US residents or citizens.
provide a high-quality IPsec implementation for Linux
- portable to all CPUs Linux supports: (current list)
- interoperable with other IPsec implementations: (current list)

If we can get opportunistic encryption implemented and widely deployed, then it becomes impossible for even huge well-funded agencies to monitor the net.

See also our section on history and politics of cryptography, which includes our project leader's rationale for starting the project.

Project team

Two of the team are from the US and can therefore contribute no code:

John Gilmore: founder and policy-maker ( home page)
Hugh Daniel: project manager, Most Demented Tester, and occasionally Pointy-Haired Boss

The rest of the team are Canadians, working in Canada. ( Why Canada?)

Hugh Redelmeier: Pluto daemon programmer
Richard Guy Briggs: KLIPS programmer
Michael Richardson: hacker without portfolio
Claudia Schmeing: documentation
Sam Sgro: technical support via the mailing lists

The project is funded by civil libertarians who consider our goals worthwhile. Most of the team are paid for this work.

People outside this core team have made substantial contributions. See

our CREDITS file
the patches and add-ons section of our web references file
lists below of user-written HowTos and other papers

Additional contributions are welcome. See the FAQ for details.

Products containing FreeS/WAN

Unfortunately the export laws of some countries restrict the distribution of strong cryptography. FreeS/WAN is therefore not in the standard Linux kernel and not in all CD or web distributions.

FreeS/WAN is, however, quite widely used. Products we know of that use it are listed below. We would appreciate hearing, via the mailing lists, of any we don't know of.

Full Linux distributions

FreeS/WAN is included in various general-purpose Linux distributions, mostly from countries (shown in brackets) with more sensible laws:

SuSE Linux (Germany)
Conectiva (Brazil)
Mandrake (France)
Debian
the Polish(ed) Linux Distribution (Poland)
Best Linux (Finland)

For distributions which do not include FreeS/WAN and are not Redhat (which we develop and test on), there is additional information in our compatibility section.

The server edition of Corel Linux (Canada) also had FreeS/WAN, but Corel have dropped that product line.

Linux kernel distributions

Working Overloaded Linux Kernel (WOLK)

Office server distributions

FreeS/WAN is also included in several distributions aimed at the market for turnkey business servers:

e-Smith (Canada), which has recently been acquired and become the Network Server Solutions group of Mitel Networks (Canada)
ClarkConnect from Point Clark Networks (Canada)
Trustix Secure Linux (Norway)

Firewall distributions

Several distributions intended for firewall and router applications include FreeS/WAN:

The Linux Router Project produces a Linux distribution that will boot from a single floppy. The LEAF firewall project provides several different LRP-based firewall packages. At least one of them, Charles Steinkuehler's Dachstein, includes FreeS/WAN with X.509 patches.
there are several distributions bootable directly from CD-ROM, usable on a machine without hard disk.
- Dachstein (see above) can be used this way
- Gibraltar is based on Debian GNU/Linux.
- at time of writing, Xiloo is available only in Chinese. An English version is expected.
Astaro Security Linux includes FreeS/WAN. It has some web-based tools for managing the firewall that include FreeS/WAN configuration management.
Linuxwall
Smoothwall
Devil Linux
Coyote Linux has a Wolverine firewall/VPN server

There are also several sets of scripts available for managing a firewall which is also acting as a FreeS/WAN IPsec gateway. See this list.

Firewall and VPN products

Several vendors use FreeS/WAN as the IPsec component of a turnkey firewall or VPN product.

Software-only products:

Linux Magic offer a VPN/Firewall product using FreeS/WAN
The Software Group's Sentinet product uses FreeS/WAN
Merilus use FreeS/WAN in their Gateway Guardian firewall product

Products that include the hardware:

The LASAT SafePipe[tm] series. is an IPsec box based on an embedded MIPS running Linux with FreeS/WAN and a web-config front end. This company also host our freeswan.org web site.
Merilus Firecard is a Linux firewall on a PCI card.
Kyzo have a "pizza box" product line with various types of server, all running from flash. One of them is an IPsec/PPTP VPN server
PFN use FreeS/WAN in some of their products

Rebel.com, makers of the Netwinder Linux machines (ARM or Crusoe based), had a product that used FreeS/WAN. The company is in receivership so the future of the Netwinder is at best unclear. PKIX patches for FreeS/WAN developed at Rebel are listed in our web links document.

Information sources

This HowTo, in multiple formats

FreeS/WAN documentation up to version 1.5 was available only in HTML. Now we ship two formats:

as HTML, one file for each doc section plus a global Table of Contents
one big HTML file for easy searching

and provide a Makefile to generate other formats if required:

The Makefile assumes the htmldoc tool is available. You can download it from Easy Software.

All formats should be available at the following websites:

The distribution tarball has only the two HTML formats.

Note: If you need the latest doc version, for example to see if anyone has managed to set up interoperation between FreeS/WAN and whatever, then you should download the current snapshot. What is on the web is documentation as of the last release. Snapshots have all changes I've checked in to date.

RTFM (please Read The Fine Manuals)

As with most things on any Unix-like system, most parts of Linux FreeS/WAN are documented in online manual pages. We provide a list of FreeS/WAN man pages, with links to HTML versions of them.

The man pages describing configuration files are:

Man pages for common commands include:

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

In the event of disagreement between this HTML documentation and the man pages, the man pages are more likely correct since they are written by the implementers. Please report any such inconsistency on the mailing list.

Background material

Throughout this documentation, I write as if the reader had at least a general familiarity with Linux, with Internet Protocol networking, and with the basic ideas of system and network security. Of course that will certainly not be true for all readers, and quite likely not even for a majority.

However, I must limit amount of detail on these topics in the main text. For one thing, I don't understand all the details of those topics myself. Even if I did, trying to explain everything here would produce extremely long and almost completely unreadable documentation.

If one or more of those areas is unknown territory for you, there are plenty of other resources you could look at:

Linux: the Linux Documentation Project or a local Linux User Group and these links
IP networks: Rusty Russell's Networking Concepts HowTo and these links
Security: Schneier's book Secrets and Lies and these links

Also, I do make an effort to provide some background material in these documents. All the basic ideas behind IPsec and FreeS/WAN are explained here. Explanations that do not fit in the main text, or that not everyone will need, are often in the glossary , which is the largest single file in this document set. There is also a background file containing various explanations too long to fit in glossary definitions. All files are heavily sprinkled with links to each other and to the glossary. If some passage makes no sense to you, try the links.

For other reference material, see the bibliography and our collection of web links.

Of course, no doubt I get this (and other things) wrong sometimes. Feedback via the mailing lists is welcome.

Archives of the project mailing list

Until quite recently, there was only one FreeS/WAN mailing list, and archives of it were:

The two archives use completely different search engines. You might want to try both.

More recently we have expanded to five lists, each with its own archive.

More information on mailing lists.

User-written HowTo information

Various user-written HowTo documents are available. The ones covering FreeS/WAN-to-FreeS/WAN connections are:

Jean-Francois Nadeau's practical configurations document
Jens Zerbst's HowTo on Using FreeS/WAN with dynamic IP addresses.
an entry in Kurt Seifried's Linux Security Knowledge Base.
a section of David Ranch's Trinity OS Guide
a section in David Bander's book Linux Security Toolkit

User-wriiten HowTo material may be especially helpful if you need to interoperate with another IPsec implementation. We have neither the equipment nor the manpower to test such configurations. Users seem to be doing an admirable job of filling the gaps.

list of user-written interoperation HowTos in our interop document

Check what version of FreeS/WAN user-written documents cover. The software is under active development and the current version may be significantly different from what an older document describes.

Papers on FreeS/WAN

Two design documents show team thinking on new developments:

Opportunistic Encryption by technical lead Henry Spencer and Pluto programmer Hugh Redelemeier
discussion of KLIPS redesign

Both documents are works in progress and are frequently revised. For the latest version, see the design mailing list. Comments should go to that list.

There is now an Internet Draft on Opportunistic Encryption by Michael Richardson, Hugh Redelmeier and Henry Spencer. This is a first step toward getting the protocol standardised so there can be multiple implementations of it. Discussion of it takes place on the IETF IPsec Working Group mailing list.

A number of papers giving further background on FreeS/WAN, or exploring its future or its applications, are also available:

Both Henry and Richard gave talks on FreeS/WAN at the 2000 Ottawa Linux Symposium.
- Richard's slides
- Henry's paper
- MP3 audio of their talks is available from the conference page
Moat: A Virtual Private Network Appliances and Services Platform is a paper about large-scale (a few 100 links) use of FreeS/WAN in a production application at AT&T Research. It is available in Postscript or PDF from co-author Steve Bellovin's papers list page.
One of the Moat co-authors, John Denker, has also written
- a proposal for how future versions of FreeS/WAN might interact with routing protocols
- a wishlist of possible new features
Bart Trojanowski's web page has a draft design for hardware acceleration of FreeS/WAN

Several of these provoked interesting discussions on the mailing lists, worth searching for in the archives.

There are also several papers in languages other than English, see our web links.

License and copyright information

All code and documentation written for this project is distributed under either the GNU General Public License (GPL) or the GNU Library General Public License. For details see the COPYING file in the distribution.

Not all code in the distribution is ours, however. See the CREDITS file for details. In particular, note that the Libdes library and the version of MD5 that we use each have their own license.

Distribution sites

FreeS/WAN is available from a number of sites.

Primary site

Our primary site, is at xs4all (Thanks, folks!) in Holland:

HTTP
FTP

Mirrors

There are also mirror sites all over the world:

Eastern Canada (limited resouces)
Eastern Canada (has older versions too)
Eastern Canada (has older versions too)
Japan
Hong Kong
Denmark
the UK
Slovak Republic
Australia
technolust
Germany
Ivan Moore's site
the Crypto Archive on the Security Portal site
Wiretapped.net in Australia

Thanks to those folks as well.

The "munitions" archive of Linux crypto software

There is also an archive of Linux crypto software called "munitions", with its own mirrors in a number of countries. It includes FreeS/WAN, though not always the latest version. Some of its sites are:

Any of those will have a list of other "munitions" mirrors. There is also a CD available.

Links to other sections

For more detailed background information, see:

history and politics of cryptography
IPsec protocols

To begin working with FreeS/WAN, go to our quickstart guide.

Upgrading to FreeS/WAN 2.x

New! Built in Opportunistic connections

Out of the box, FreeS/WAN 2.x will attempt to encrypt all your IP traffic. It will try to establish IPsec connections for:

IP traffic from the Linux box on which you have installed FreeS/WAN, and
outbound IP traffic routed through that Linux box (eg. from a protected subnet).

FreeS/WAN 2.x uses hidden, automatically enabledipsec.conf connections to do this.

This behaviour is part of our campaign to get Opportunistic Encryption (OE) widespread in the Linux world, so that any two Linux boxes can encrypt to one another without prearrangement. There's one catch, however: you must set up a few DNS records to distribute RSA public keys and (if applicable) IPsec gateway information.

If you start FreeS/WAN before you have set up these DNS records, your connectivity will be slow, and messages relating to the built in connections will clutter your logs. If you are unable to set up DNS for OE, you will wish to disable the hidden connections.

Upgrading Opportunistic Encryption to 2.01 (or later)

As of FreeS/WAN 2.01, Opportunistic Encryption (OE) uses DNS TXT resource records (RRs) only (rather than TXT with KEY). This change causes a "flag day". Users of FreeS/WAN 2.00 (or earlier) OE who are upgrading may need to post additional resource records.

If you are running initiate-only OE, you must put up a TXT record in any forward domain as per our quickstart instructions. This replaces your old forward KEY.

If you are running full OE, you require no updates. You already have the needed TXT record in the reverse domain. However, to facilitate future features, you may also wish to publish that TXT record in a forward domain as instructed here.

If you are running OE on a gateway (and encrypting on behalf of subnetted boxes) you require no updates. You already have the required TXT record in your gateway's reverse map, and the TXT records for any subnetted boxes require no updating. However, to facilitate future features, you may wish to publish your gateway's TXT record in a forward domain as shown here.

During the transition, you may wish to leave any old KEY records up for some time. They will provide limited backward compatibility.

New! Policy Groups

We want to make it easy for you to declare security policy as it applies to IPsec connections.

Policy Groups make it simple to say:

These are the folks I want to talk to in the clear.
These spammers' domains -- I don't want to talk to them at all.
To talk to the finance department, I must use IPsec.
For any other communication, try to encrypt, but it's okay if we can't.

FreeS/WAN then implements these policies, creating OE connections if and when needed. You can use Policy Groups along with connections you explicitly define in ipsec.conf.

For more information, see our Policy Group HOWTO.

New! Packetdefault Connection

Free/SWAN 2.x ships with the automatically enabled, hidden connection packetdefault. This configures a FreeS/WAN box as an OE gateway for any hosts located behind it. As mentioned above, you must configure some DNS records for OE to work.

As the name implies, this connection functions as a default. If you have more specific connections, such as policy groups which configure your FreeS/WAN box as an OE gateway for a local subnet, these will apply before packetdefault. You can view packetdefault 's specifics in man ipsec.conf .

FreeS/WAN now disables Reverse Path Filtering

FreeS/WAN often doesn't work with reverse path filtering. At start time, FreeS/WAN now turns rp_filter off, and logs a warning.

FreeS/WAN does not turn it back on again. You can do this yourself with a command like:

   echo 1 > /proc/sys/net/ipv4/conf/eth0/rp_filter

For eth0, substitute the interface which FreeS/WAN was affecting.

Revised `ipsec.conf`

No promise of compatibility

The FreeS/WAN team promised config-file compatibility throughout the 1.x series. That means a 1.5 config file can be directly imported into a fresh 1.99 install with no problems.

With FreeS/WAN 2.x, we've given ourselves permission to make the config file easier to use. The cost: some FreeS/WAN 1.x configurations will not work properly. Many of the new features are, however, backward compatible.

Most `ipsec.conf` files will work fine

... so long as you paste this line, with no preceding whitespace, at the top of your config file:

    version 2

Backward compatibility patch

If the new defaults bite you, use thisipsec.conf fragment to simulate the old default values.

Details

We've obsoleted various directives which almost no one was using:

    dump
    plutobackgroundload
    no_eroute_pass
    lifetime
    rekeystart
    rekeytries

For most of these, there is some other way to elicit the desired behaviour. See this post.

We've made some settings, which almost everyone was using, defaults. For example:

    interfaces=%defaultroute
    plutoload=%search
    plutostart=%search
    uniqueids=yes

We've also changed some default values to help with OE and Policy Groups:

    authby=rsasig   ## not secret!!!
    leftrsasigkey=%dnsondemand ## looks up missing keys in DNS when needed.
    rightrsasigkey=%dnsondemand

Of course, you can still override any defaults by explictly declaring something else in your connection.

A post with a list of many ipsec.conf changes.
Current ipsec.conf manual.

Upgrading from 1.x RPMs to 2.x RPMs

Note: When upgrading from 1-series to 2-series RPMs, rpm -U will not work.

You must instead erase the 1.x RPMs, then install the 2.x set:

    rpm -e freeswan

    rpm -e freeswan-module

On erasing, your old ipsec.conf should be moved toipsec.conf.rpmsave. Keep this. You will probably want to copy your existing connections to the end of your new 2.x file.

Install the RPMs suitable for your kernel version, such as:

    rpm -ivh freeswan-module-2.03_2.4.20_20.9-0.i386.rpm

    rpm -ivh freeswan-userland-2.03_2.4.20_20.9-0.i386.rpm

Or, to splice the files:

    cat /etc/ipsec.conf /etc/ipsec.conf.rpmsave > /etc/ipsec.conf.tmp
    mv /etc/ipsec.conf.tmp /etc/ipsec.conf

Then, remove the redundant conn %default andconfig setup sections. Unless you have done any special configuring here, you'll likely want to remove the 1.x versions. Removeconn OEself, if present.

Quickstart Guide to Opportunistic Encryption

Purpose

This page will get you started using Linux FreeS/WAN with opportunistic encryption (OE). OE enables you to set up IPsec tunnels without co-ordinating with another site administrator, and without hand configuring each tunnel. If enough sites support OE, a "FAX effect" occurs, and many of us can communicate without eavesdroppers.

OE "flag day"

As of FreeS/WAN 2.01, OE uses DNS TXT resource records (RRs) only (rather than TXT with KEY). This change causes a "flag day". Users of FreeS/WAN 2.00 (or earlier) OE who are upgrading may require additional resource records, as detailed in our upgrading document. OE setup instructions here are for 2.02 or later.

Requirements

To set up opportunistic encryption, you will need:

a Linux box. For OE to the public Internet, this box must NOT be behind Network Address Translation (NAT).
to install Linux FreeS/WAN 2.02 or later
either control over your reverse DNS (for full opportunism) or the ability to write to some forward domain (for initiator-only). This free DNS service explicitly supports forward TXT records for FreeS/WAN use.
(for full opportunism) a static IP

Note: Currently, only Linux FreeS/WAN supports opportunistic encryption.

RPM install

Our instructions are for a recent Red Hat with a 2.4-series stock or Red Hat updated kernel. For other ways to install, see our install document.

Download RPMs

If we have prebuilt RPMs for your Red Hat system, this command will get them:

    ncftpget ftp://ftp.xs4all.nl/pub/crypto/freeswan/binaries/RedHat-RPMs/`uname -r | tr -d 'a-wy-z'`/\*

If that fails, you will need to try another install method. Our kernel modules will only work on the Red Hat kernel they were built for, since they are very sensitive to small changes in the kernel.

If it succeeds, you will have userland tools, a kernel module, and an RPM signing key:

    freeswan-module-2.03_2.4.20_20.9-0.i386.rpm
    freeswan-userland-2.03_2.4.20_20.9-0.i386.rpm
    freeswan-rpmsign.asc

Check signatures

If you're running RedHat 8.x or later, import the RPM signing key into the RPM database:

    rpm --import freeswan-rpmsign.asc

For RedHat 7.x systems, you'll need to add it to your PGP keyring:

    pgp -ka freeswan-rpmsign.asc

Check the digital signatures on both RPMs using:

    rpm --checksig freeswan*.rpm

You should see that these signatures are good:

    freeswan-module-2.03_2.4.20_20.9-0.i386.rpm: pgp md5 OK
    freeswan-userland-2.03_2.4.20_20.9-0.i386.rpm: pgp md5 OK

Install the RPMs

Become root:

su

Install your RPMs with:

    rpm -ivh freeswan*.rpm

If you're upgrading from FreeS/WAN 1.x RPMs, and have problems with that command, see this note.

Then, start FreeS/WAN:

    service ipsec start

Test

To check that you have a successful install, run:

    ipsec verify

You should see as part of the verify output:

    Checking your system to see if IPsec got installed and started correctly
    Version check and ipsec on-path                             [OK]
    Checking for KLIPS support in kernel                        [OK]
    Checking for RSA private key (/etc/ipsec.secrets)           [OK]
    Checking that pluto is running                              [OK]
    ...

If any of these first four checks fails, see our troubleshooting guide.

Our Opportunistic Setups

Full or partial opportunism?

Determine the best form of opportunism your system can support.

For full opportunism, you'll need a static IP and and either control over your reverse DNS or an ISP that can add the required TXT record for you.
If you have a dynamic IP, and/or write access to forward DNS only, you can do initiate-only opportunism
To protect traffic bound for real IPs behind your gateway, use this form of full opportunism.

Initiate-only setup

Restrictions

When you set up initiate-only Opportunistic Encryption (iOE):

there will be no incoming connection requests; you can initiate all the IPsec connections you need.
only one machine is visible on your end of the connection.
iOE also protects traffic on behalf of NATted hosts behind the iOE box.

You cannot network a group of initiator-only machines if none of these is capable of responding to OE. If one is capable of responding, you may be able to create a hub topology using routing.

Create and publish a forward DNS record

Find a domain you can use

Find a DNS forward domain (e.g. example.com) where you can publish your key. You'll need access to the DNS zone files for that domain. This is common for a domain you own. Some free DNS providers, such as this one, also provide this service.

Dynamic IP users take note: the domain where you place your key need not be associated with the IP address for your system, or even with your system's usual hostname.

Choose your ID

Choose a name within that domain which you will use to identify your machine. It's convenient if this can be the same as your hostname:

    [root@xy root]# hostname --fqdn
    xy.example.com

This name in FQDN (fully-qualified domain name) format will be your ID, for DNS key lookup and IPsec negotiation.

Create a forward TXT record

Generate a forward TXT record containing your system's public key with a command like:

    ipsec showhostkey --txt @xy.example.com

using your chosen ID in place of xy.example.com. This command takes the contents of /etc/ipsec.secrets and reformats it into something usable by ISC's BIND. The result should look like this (with the key data trimmed down for clarity):

    ; RSA 2192 bits   xy.example.com   Thu Jan  2 12:41:44 2003
        IN      TXT     "X-IPsec-Server(10)=@xy.example.com" 
    "AQOF8tZ2... ...+buFuFn/"

Publish the forward TXT record

Insert the record into DNS, or have a system adminstrator do it for you. It may take up to 48 hours for the record to propagate, but it's usually much quicker.

Test that your key has been published

Check your DNS work

    ipsec verify --host xy.example.com

As part of the verify output, you ought to see something like:

    ...
    Looking for TXT in forward map: xy.example.com          [OK]
    ...

For this type of opportunism, only the forward test is relevant; you can ignore the tests designed to find reverse records.

Configure, if necessary

If your ID is the same as your hostname, you're ready to go. FreeS/WAN will use its built-in connections to create your iOE functionality.

If you have chosen a different ID, you must tell FreeS/WAN about it via ipsec.conf:

    config setup
        myid=@myname.freedns.example.com

and restart FreeS/WAN:

    service ipsec restart

The new ID will be applied to the built-in connections.

Note: you can create more complex iOE configurations as explained in our policy groups document, or disable OE using these instructions.

Test

That's it! Test your connections.

Full Opportunism

Full opportunism allows you to initiate and receive opportunistic connections on your machine.

Put a TXT record in a Forward Domain

To set up full opportunism, first set up a forward TXT record as for initiator-only OE , using an ID (for example, your hostname) that resolves to your IP. Do not configure /etc/ipsec.conf, but continue with the instructions for full opportunism, below.

Note that this forward record is not currently necessary for full OE, but will facilitate future features.

Put a TXT record in Reverse DNS

You must be able to publish your DNS RR directly in the reverse domain. FreeS/WAN will not follow a PTR which appears in the reverse, since a second lookup at connection start time is too costly.

Create a Reverse DNS TXT record

This record serves to publicize your FreeS/WAN public key. In addition, it lets others know that this machine can receive opportunistic connections, and asserts that the machine is authorized to encrypt on its own behalf.

Use the command:

    ipsec showhostkey --txt 192.0.2.11

where you replace 192.0.2.11 with your public IP.

The record (with key shortened) looks like:

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

Publish your TXT record

Send these records to your ISP, to be published in your IP's reverse map. It may take up to 48 hours for these to propagate, but usually takes much less time.

Test your DNS record

Check your DNS work with

    ipsec verify --host xy.example.com

As part of the verify output, you ought to see something like:

    ...
    Looking for TXT in reverse map: 11.2.0.192.in-addr.arpa [OK]
    ...

which indicates that you've passed the reverse-map test.

No Configuration Needed

FreeS/WAN 2.x ships with full OE enabled, so you don't need to configure anything. To enable OE out of the box, FreeS/WAN 2.x uses the policy group private-or-clear, which creates IPsec connections if possible (using OE if needed), and allows traffic in the clear otherwise. You can create more complex OE configurations as described in our policy groups document, or disable OE using these instructions .

If you've previously configured for initiator-only opportunism, remove myid= from config setup, so that peer FreeS/WANs will look up your key by IP. Restart FreeS/WAN so that your change will take effect, with

    service ipsec restart

Consider Firewalling

If you are running a default install of RedHat 8.x, take note: you will need to alter your iptables rule setup to allow IPSec traffic through your firewall. See our firewall document for sample iptables rules.

Test

That's it. Now, test your connection.

Test

Instructions are in the next section.

Testing opportunistic connections

Be sure IPsec is running. You can see whether it is with:

    ipsec setup status

If need be, you can restart it with:

    service ipsec restart

Load a FreeS/WAN test website from the host on which you're running FreeS/WAN. Note: the feds may be watching these sites. Type one of:

   links oetest.freeswan.org

   links oetest.freeswan.nl

A positive result looks like this:

   You  seem  to  be  connecting  from:  192.0.2.11 which DNS says is:
   gateway.example.com
     _________________________________________________________________

   Status E-route
   OE    enabled    16    192.139.46.73/32    ->    192.0.2.11/32   =>
   tun0x2097@192.0.2.11
   OE    enabled    176    192.139.46.77/32    ->   192.0.2.11/32   =>
   tun0x208a@192.0.2.11

If you see this, congratulations! Your OE host or gateway will now encrypt its own traffic whenever it can. For more OE tests, please see our testing document. If you have difficulty, see our OE troubleshooting tips.

Now what?

Please see our policy groups document for more ways to set up Opportunistic Encryption.

You may also wish to make some pre-configured connections.

Notes

We assume some facts about your system in order to make Opportunistic Encryption easier to configure. For example, we assume that you wish to have FreeS/WAN secure your default interface.
You may change this, and other settings, by altering theconfig setup section in /etc/ipsec.conf.
Note that the built-in connections used to build policy groups do not inherit from conn default.
If you fail to define your local identity and do not fill in your reverse DNS entry, you will not be able to use OE.

Troubleshooting OE

See the OE troubleshooting hints in our troubleshooting guide.

Known Issues

Please see this list of known issues with Opportunistic Encryption.

How to Configure Linux FreeS/WAN with Policy Groups

What are Policy Groups?

Policy Groups are an elegant general mechanism to configure FreeS/WAN. They are useful for many FreeS/WAN users.

In previous FreeS/WAN versions, you needed to configure each IPsec connection explicitly, on both local and remote hosts. This could become complex.

By contrast, Policy Groups allow you to set local IPsec policy for lists of remote hosts and networks, simply by listing the hosts and networks which you wish to have special treatment in one of several Policy Group files. FreeS/WAN then internally creates the connections needed to implement each policy.

In the next section we describe our five Base Policy Groups, which you can use to configure IPsec in many useful ways. Later, we will show you how to create an IPsec VPN using one line of configuration for each remote host or network.

Built-In Security Options

FreeS/WAN offers these Base Policy Groups:

private: FreeS/WAN only communicates privately with the listed CIDR blocks. If needed, FreeS/WAN attempts to create a connection opportunistically. If this fails, FreeS/WAN blocks communication. Inbound blocking is assumed to be done by the firewall. FreeS/WAN offers firewall hooks but no modern firewall rules to help with inbound blocking.
private-or-clear: FreeS/WAN prefers private communication with the listed CIDR blocks. If needed, FreeS/WAN attempts to create a connection opportunistically. If this fails, FreeS/WAN allows traffic in the clear.
clear-or-private: FreeS/WAN communicates cleartext with the listed CIDR blocks, but also accepts inbound OE connection requests from them. Also known as passive OE (pOE), this policy may be used to create an opportunistic responder.
clear: FreeS/WAN only communicates cleartext with the listed CIDR blocks.
block: FreeS/WAN blocks traffic to and from and the listed CIDR blocks. Inbound blocking is assumed to be done by the firewall. FreeS/WAN offers firewall hooks but no modern firewall rules to help with inbound blocking.

Notes:

Base Policy Groups apply to communication with this host only.
The most specific rule (whether policy or pre-configured connection) applies. This has several practical applications:
- If CIDR blocks overlap, FreeS/WAN chooses the most specific applicable block.
- This decision also takes into account any pre-configured connections you may have.
- If the most specific connection is a pre-configured connection, the following procedure applies. If that connection is up, it will be used. If it is routed, it will be brought up. If it is added, no action will be taken.
Base Policy Groups are created using built-in connections. Details in man ipsec.conf.
All Policy Groups are bidirectional. This chart shows some technical details. FreeS/WAN does not support one-way encryption, since it can give users a false sense of security.

Using Policy Groups

The Base Policy Groups which build IPsec connections rely on Opportunistic Encryption. To use the following examples, you must first become OE-capable, as described in our quickstart guide.

Example 1: Using a Base Policy Group

Simply place CIDR blocks (names, IPs or IP ranges) in /etc/ipsec.d/policies/[groupname], and reread the policy group files.

For example, the private-or-clear policy tells FreeS/WAN to prefer encrypted communication to the listed CIDR blocks. Failing that, it allows talk in the clear.

To make this your default policy, place fullnet in the private-or-clear policy group file:

    [root@xy root]# cat /etc/ipsec.d/policies/private-or-clear
    # This file defines the set of CIDRs (network/mask-length) to which
    # communication should be private, if possible, but in the clear otherwise.
    ....
    0.0.0.0/0

and reload your policies with

    ipsec auto --rereadgroups

Use this test to verify opportunistic connections.

Example 2: Defining IPsec Security Policy with Groups

Defining IPsec security policy with Base Policy Groups is like creating a shopping list: just put CIDR blocks in the appropriate group files. For example:

    [root@xy root]# cd /etc/ipsec.d/policies
    [root@xy policies]# cat private
        192.0.2.96/27              # The finance department
        192.0.2.192/29             # HR
	192.0.2.12                 # HR gateway
        irc.private.example.com    # Private IRC server
  
    [root@xy policies]# cat private-or-clear
        0.0.0.0/0                  # My default policy: try to encrypt.

    [root@xy policies]# cat clear
        192.0.2.18/32              # My POP3 server
        192.0.2.19/32              # My Web proxy

    [root@xy policies]# cat block
        spamsource.example.com

To make these settings take effect, type:

    ipsec auto --rereadgroups

Notes:

For opportunistic connection attempts to succeed, all participating FreeS/WAN hosts and gateways must be configured for OE.
Examples 3 through 5 show how to implement a detailed private policy.
Warning: Using DNS names in policy files and ipsec.conf can be tricky. If the name does not resolve, the policy will not be implemented for that name. It is therefore safer either to use IPs, or to put any critical names in /etc/hosts. We plan to implement periodic DNS retry to help with this.
Names are resolved at FreeS/WAN startup, or when the policies are reloaded. Unfortunately, name lookup can hold up the startup process. If you have fast DNS servers, the problem may be less severe.

Example 3: Creating a Simple IPsec VPN with the`private` Group

You can create an IPsec VPN between several hosts, with only one line of configuration per host, using the private policy group.

First, use our quickstart guide to set up each participating host with a FreeS/WAN install and OE.

In one host's /etc/ipsec.d/policies/private, list the peers to which you wish to protect traffic. For example:

    [root@xy root]# cd /etc/ipsec.d/policies
    [root@xy policies]# cat private
        192.0.2.9              # several hosts at example.com
        192.0.2.11             
        192.0.2.12                 
        irc.private.example.com

Copy the private file to each host. Remove the local host, and add the initial host.

    scp2 /etc/ipsec.d/policies/private root@192.0.2.12:/etc/ipsec.d/policies/private

On each host, reread the policy groups with

    ipsec auto --rereadgroups

That's it! You're configured.

Test by pinging between two hosts. After a second or two, traffic should flow, and

    ipsec eroute

should yield something like

    192.0.2.11/32   -> 192.0.2.8/32  => tun0x149f@192.0.2.8

where your host IPs are substituted for 192.0.2.11 and 192.0.2.8.

If traffic does not flow, there may be an error in your OE setup. Revisit our quickstart guide.

Our next two examples show you how to add subnets to this IPsec VPN.

Example 4: New Policy Groups to Protect a Subnet

To protect traffic to a subnet behind your FreeS/WAN gateway, you'll need additional DNS records, and new policy groups. To set up the DNS, see our quickstart guide. To create five new policy groups for your subnet, copy these connections to/etc/ipsec.conf. Substitute your subnet's IPs for 192.0.2.128/29.

conn private-net
    also=private  # inherits settings (eg. auto=start) from built in conn
    leftsubnet=192.0.2.128/29  # your subnet's IPs here

conn private-or-clear-net
    also=private-or-clear
    leftsubnet=192.0.2.128/29

conn clear-or-private-net
    also=clear-or-private
    leftsubnet=192.0.2.128/29

conn clear-net
    also=clear
    leftsubnet=192.0.2.128/29

conn block-net
    also=block
    leftsubnet=192.0.2.128/29

Copy the gateway's files to serve as the initial policy group files for the new groups:

    cp -p /etc/ipsec.d/policies/private /etc/ipsec.d/policies/private-net
    cp -p /etc/ipsec.d/policies/private-or-clear /etc/ipsec.d/policies/private-or-clear-net
    cp -p /etc/ipsec.d/policies/clear-or-private /etc/ipsec.d/policies/clear-or-private-net
    cp -p /etc/ipsec.d/policies/clear /etc/ipsec.d/policies/clear-net
    cp -p /etc/ipsec.d/policies/block /etc/ipsec.d/policies/block

Tip: Since a missing policy group file is equivalent to a file with no entries, you need only create files for the connections you'll use.

To test one of your new groups, place the fullnet 0.0.0.0/0 inprivate-or-clear-net. Perform the subnet test in our quickstart guide. You should see a connection, and

    ipsec eroute

should include an entry which mentions the subnet node's IP and the OE test site IP, like this:

    192.0.2.131/32   -> 192.139.46.77/32  => tun0x149f@192.0.2.11

Example 5: Adding a Subnet to the VPN

Suppose you wish to secure traffic to a subnet 192.0.2.192/29 behind a FreeS/WAN box 192.0.2.12.

First, add DNS entries to configure 192.0.2.12 as an opportunistic gateway for that subnet. Instructions are in our quickstart guide. Next, create a private-net group on 192.0.2.12 as described in Example 4.

On each other host, add the subnet 192.0.2.192/29 to private , yielding for example

    [root@xy root]# cd /etc/ipsec.d/policies
    [root@xy policies]# cat private
        192.0.2.9              # several hosts at example.com
        192.0.2.11
        192.0.2.12             # HR department gateway
        192.0.2.192/29         # HR subnet
        irc.private.example.com

and reread policy groups with

    ipsec auto --rereadgroups

That's all the configuration you need.

Test your VPN by pinging from a machine on 192.0.2.192/29 to any other host:

    [root@192.0.2.194]# ping 192.0.2.11

After a second or two, traffic should flow, and

    ipsec eroute

should yield something like

    192.0.2.11/32   -> 192.0.2.194/32  => tun0x149f@192.0.2.12

Key:

1.	192.0.2.11/32	Local start point of the protected traffic.
2.	192.0.2.194/32	Remote end point of the protected traffic.
3.	192.0.2.12	Remote FreeS/WAN node (gateway or host). May be the same as (2).
4.	[not shown]	Local FreeS/WAN node (gateway or host), where you've produced the output. May be the same as (1).

For additional assurance, you can verify with a packet sniffer that the traffic is being encrypted.

Note

Because strangers may also connect via OE, this type of VPN may require a stricter firewalling policy than a conventional VPN.

Appendix

Our Hidden Connections

Our Base Policy Groups are created using hidden connections. These are spelled out in man ipsec.conf and defined in /usr/lib/ipsec/_confread.

Custom Policy Groups

A policy group is built using a special connection description inipsec.conf, which:

is generic. It usesright=[%group|%opportunisticgroup] rather than specific IPs. The connection is cloned for every name or IP range listed in its Policy Group file.
often has a failure rule. This rule, writtenfailureshunt=[passthrough|drop|reject|none], tells FreeS/WAN what to do with packets for these CIDRs if it fails to establish the connection. Default is none.

To create a new group:

Create its connection definition in ipsec.conf.
Create a Policy Group file in /etc/ipsec.d/policies with the same name as your connection.
Put a CIDR block in that file.
Reread groups with ipsec auto --rereadgroups.
Test: ping to activate any OE connection, and view results with ipsec eroute.

Disabling Opportunistic Encryption

To disable OE (eg. policy groups and packetdefault), cut and paste the following lines to /etc/ipsec.conf:

conn block
    auto=ignore

conn private
    auto=ignore

conn private-or-clear
    auto=ignore

conn clear-or-private
    auto=ignore

conn clear
    auto=ignore

conn packetdefault
    auto=ignore

Restart FreeS/WAN so that the changes take effect:

    ipsec setup restart

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.