# Introduction

This section gives an overview of:

- what IP Security (IPSEC) does
- how IPSEC works
- why we are implementing it for Linux
- how this implementation works

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.

## IPSEC, Security for the Internet Protocol

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 has both advantages and disadvantages, discussed in 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.

### 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 setup section will show you how to build each of them.

#### Using secure tunnels to create a VPN

A VPN, or Virtual Private Network 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. We hope this will go some distance toward creating a secure Internet, an environment where message privacy is the default. See our history and politics of cryptography section for discussion.

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.

A draft document giving most of the details of how we plan to implement this has been posted to the mailing list. 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

### 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:

- 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)
- 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

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?)

- Henry Spencer: technical lead, script programming
- Hugh Redelmeier: Pluto daemon programmer
- Richard Guy Briggs: KLIPS programmer
- Claudia Schmeing: technical support via the mailing lists
- Sandy Harris: documentation

The project is funded by civil libertarians who consider our goals worthwhile. 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.

### Information on the web

- current site, freeswan.org
- original project site at xs4all.nl

### Distribution sites

FreeS/WAN is available from a number of sites:

- Primary site, in Holland:
  - HTTP
  - FTP
- 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
- Ivan Moore's site
- the Crypto Archive on the Security Portal site

#### 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:

- Germany
- Italy
- Netherlands

Any of those will have a list of other "munitions" mirrors.

### Archives of the project mailing list

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

- Canada
- Holland

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.

## 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.

### Full Linux distributions

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

- European versions of SuSE Linux (Germany)
- Conectiva (Brazil)
- the server edition of Corel Linux (Canada)
- the Polish(ed) Linux Distribution (Poland)
- Trustix Secure Linux (Norway)

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.

We would appreciate hearing of other distributions using FreeS/WAN.

### Firewall distributions

FreeS/WAN is also included in, or available for, more specialised distributions intended for firewall and router applications:

- Gibraltar is based on Debian GNU/Linux. It is bootable directly from CD-ROM, usable on a machine without hard disk.
- The Linux Router Project produces a distribution that will boot from a single floppy. Charles Steinkuehler's LRP site provides FreeS/WAN packaged for LRP.
- Astaro Security Linux includes FreeS/WAN. It has some web-based tools for managing the firewall that include FreeS/WAN configuration management.
- Linuxwall

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.

We would appreciate hearing of other specialised distributions using FreeS/WAN, or other script sets.

### Firewall and VPN products

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

- 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.
- Rebel.com, makers of the Netwinder ARM Linux machine, have a new (mid-2000) division Rebel Networks whose product uses FreeS/WAN.
- 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 and in their Firecard product, 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.
- Linuxcare have "bootable business card" usable as a recovery disk for broken Linux systems.

We would appreciate hearing of other products using FreeS/WAN.

## Documentation

### 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:

- PDF
- Postscript
- ASCII text

The Makefile assumes the htmldoc tool is available. You can download it from Easy Software. You may need to get source code and change some of the limits in #define MAX_<whatever> statements near the end of its config.h.in file. Otherwise it core dumps when those limits are exceeded on large files such as our glossary.html.

All formats should be available at the following websites:

- FreeS/WAN project
- Linux Documentation Project

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.

### Other documents in the distribution

Text files in the main distribution directory are README, INSTALL, CREDITS, CHANGES, BUGS and COPYING.

FreeS/WAN commands and library routines are documented in standard Unix manual pages, accessible via the man(1) command. We also provide them in HTML, accessible from this index. In the event of disagreement between this HowTo 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.

The gmp (GNU multi-precision arithmetic) and Libdes (encryption) libraries which we use each have their own documentation. You can find it in those library directories.

### 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 current team thinking on new developments:

- Opportunistic Encryption by technical lead Henry Spencer and Pluto programmer Hugh Redelemeier
- KLIPS II Design by kernel programmer Richard Guy Briggs

Both documents are works in progress and frequently revised. The most recent versions can be found either in FreeS/WAN snapshots or on the design mailing list. Comments should go to that 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
- Feczak Szabolcs' thesis, in Hungarian

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

### Test results

- Speed test results from a Welsh university.

Interoperability test results are in our web links document.

## 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 has its own license.

## 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:

- installation if you need to install FreeS/WAN
- setup if your distribution came with FreeS/WAN so you just need to configure your IPSEC links