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.

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.

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.

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.

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.

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.

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.

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:

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.

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.

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.

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

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

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.