This section gives an overview of:
This section is intended to cover only the essentials, things you should know before trying to use FreeS/WAN.
For more detailed background information, see the history and politics and IPsec protocols sections.
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
Our implementation has three main parts:
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.
IPsec is designed to let different implementations work together. We provide:
The VPN Consortium fosters cooperation among implementers and interoperability among implementations. Their web site has much more information.
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:
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:
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.
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.
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:
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:
In most situations, however, FreeS/WAN supports road warrior connections just fine.
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:
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.
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:
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:
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.
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.
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:
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.
Two of the team are from the US and can therefore contribute no code:
The rest of the team are Canadians, working in Canada. ( Why Canada?)
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
Additional contributions are welcome. See the FAQ for details.
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.
FreeS/WAN is included in various general-purpose Linux distributions, mostly from countries (shown in brackets) with more sensible laws:
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.
FreeS/WAN is also included in several distributions aimed at the market for turnkey business servers:
Several distributions intended for firewall and router applications include FreeS/WAN:
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.
Several vendors use FreeS/WAN as the IPsec component of a turnkey firewall or VPN product.
Products that include the hardware:
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.
For some distributions which do not include FreeS/WAN, it may be possible to install using RPM (Redhat Package Manager), rather than going through our more complex procedure.
Some caution is required on this. The RPMs are specific to a Linux distribution and an attempt to use them on another distribution is likely to cause problems.
RPMs for FreeS/WAN 1.91 and Red Hat 7.1 or 7.2 are available for download from Steamballoon. Check there for later versions.
As of version 1.93, the FreeS/WAN distribution incorporates some of the Steamballoon work, providing a facility for building your own RPMs. Details are in our installation document.
FreeS/WAN documentation up to version 1.5 was available only in HTML. Now we ship two formats:
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.
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 the man(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.
Text files in the main distribution directory are README, INSTALL, CREDITS, CHANGES, BUGS and COPYING.
The Libdes encryption library we use has its own documentation. You can find it in the library directory..
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:
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.
Until quite recently, there was only one FreeS/WAN mailing list, and archives of it were:
More recently we have expanded to five lists, each with its own archive.
More information on mailing lists.
Various user-written HowTo documents are available. The ones covering FreeS/WAN-to-FreeS/WAN connections are:
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.
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.
Two design documents show team thinking on new developments:
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:
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.
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.
FreeS/WAN is available from a number of sites.
Our primary site, is at xs4all (Thanks, folks!) in Holland:
There are also mirror sites all over the world:
Thanks to those folks as well.
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.
For more detailed background information, see:
To begin working with FreeS/WAN, go to our quickstart guide.