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.
Software-only products:
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:
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.
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.
This is a quick guide to
and then setting up some common configurations:
This should cover everything you need to set up
More complex requirements are covered elsewhere:
However, please read this quick start section first, before tackling the others.
There are two easy ways to install FreeS/WAN:
If you are using one of them, just include FreeS/WAN in the choices you make during installation, or add it to your configuration later using the distribution's tools.
If your FreeS/WAN came on your machine, and is pre-1.98, you will need to hand generate an RSA key pair for authentication, using these instructions.
Sources for RPM packages of FreeS/WAN are:
Note that:
You need to download at least two RPMs:
You do not need the kernel header and kernel source RPMs to install FreeS/WAN, but Murphy's Law suggests you should download them so that the kernel source and headers on your system match the kernel actually in use.
Once you have them, install the RPMs with rpm -i commands. You will need to be root to install a module or kernel.
Then, start FreeS/WAN:
service ipsec start
If your distribution does not include FreeS/WAN and no RPMs are available, see our installation from source document.
To check that you have a successful install, run:
ipsec verify
or, on older FreeS/WANs:
ipsec whack --status
ipsec verify(8) checks whether:
It also anticipates future problems. For example, it tests if:
If your checks fail, see our troubleshooting guide.
That's it. FreeS/WAN is installed.
If you are running a firewall, you must now allow FreeS/WAN traffic through. You will also wish to consider how to protect your machine from unwanted traffic which might enter through your FreeS/WAN tunnels. There are three steps to firewalling with FreeS/WAN.
The first step is to allow IPsec packets in and out of your machine. Allow:
If that machine is a gateway, be sure that packets emerging from IPSec processing are correctly forwarded.
A second firewalling step -- access controls built into FreeS/WAN -- is automatically applied. For example, in some situations KLIPS determines that it should not have received a certain packet, and drops it.
Optionally, you may wish to add a third step, to filter packets emerging from your IPSec tunnels. This is a sensible precaution at any time, but becomes more important if you employ full opportunistic encryption, since that can allow strangers to bypass your usual firewall rules.
More detail is here, along with sample firewall scripts.
FreeS/WAN relies on two configuration files:
Note that Mandrake puts them in /etc/freeswan.
The remainder of this document shows you how to configure these common setups:
Opportunistic encryption makes many aspects of the setup and administration of IPsec easier.
For opportunistic encryption, you do not need to communicate with the administrator of a site before establishing secure communications to that site. In particular, you do not have to send them your keys or collect and authenticate theirs. You also do not have to configure IP information for each connection.
Instead, you need to place some information in DNS, and create a simple configuration that will enable your system to connect securely with every other system set up for OE. This presents a clear advantage over manually setting up a large number of VPN connections.
A major goal of the FreeS/WAN project is to get opportunistic encryption widely enough deployed that a "FAX effect" comes into play. Neither a FAX machine nor opportunistic encryption is of much value if there are only a few installed, but both become much more useful as the installed base increases.
Widespread deployment of opportunistic encryption appears to be our best hope for making the Internet more secure. See discussion in our introduction.
Opportunistic encryption relies on DNS:
To set up full opportunistic encryption, you must be able to insert resource records in the DNS reverse maps for:
For a standalone machine or a gateway using NAT, these two IPs will be identical, so you will only need one RR.
This requires a static IP, at least on the machine running IPSec.
Normally the reverse map is controlled by your Internet Service Provider (ISP). Ask your ISP's staff if they are willing to publish a resource record, which you would provide, in your IP's reverse map.
If you cannot, you can still protect connections which you initiate. This requires simply that you can put a record in some domain's forward DNS.
Directions for initiate-only opportunism are just below; those for full opportunism are in the following section .
Because opportunistic encryption relies on DNS:
its authentication is only as strong as your DNS is secure .
Without secure DNS, opportunistic connections protect against passive snooping, but not active man-in-the-middle attacks.
You can make your DNS entries more trustworthy by serving them within your security perimeter. We recommend running a nameserver on your gateway, as described in our opportunism HOWTO ("Getting DNS Through").
Opportunistic encryption is new technology and we are still working out some fine points. Please see this list of known issues.
In the next sections, we will tackle three typical setups for opportunistic encryption:
One example does build on the previous one, but you can skip ahead to get an idea of what your situation entails.
In this section, we the case of opportunistic encryption that has the fewest requirements:
This would apply to a standalone machine, or to a home gateway with some invisible NAT clients.
Given the above conditions, you can set up opportunistic encryption without having to add resource records to the DNS reverse map for your public IP address. Sections after this one cover situations where one or more of the above restrictions do not apply.
There are two steps:
Once this is done, your system will automatically encrypt whenever it can.
You need to put your system's RSA public key in a forward DNS record so that systems you communicate with can find it.
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.
When negotiating a connection, your FreeS/WAN will identify itself by a fully qualified domain name (FQDN) which tells other FreeS/WANs where to find its KEY. Choose a name, within the domain you have access to, that you will use for this purpose.
For example, if you have access to example.com's DNS, you could choose xy.example.com, even if your hostname is xyz.instance.com and the reverse map for your IP points to 12345678-ourtowns-cableco.com.
Note that xy.example.com need not be associated with your current IP address, or any IP for that matter.
You can generate a DNS KEY record containing your system's public key with the command:
ipsec showhostkeyThe result should look like this (with the key data trimmed down for clarity):
; RSA 2048 bits xy.example.com Sat Apr 15 13:53:22 2000 xy.example.com. IN KEY 0x4200 4 1 AQOF8tZ2...+buFuFn/
Change xy.example.com to your FQDN.
Insert the record into DNS, or have a helpful system adminstrator do so for you. Remember that it will take time (up to 48 hours, but often a lot less) for any new DNS information to propagate, so OE won't work immediately.
By default, Linux FreeS/WAN ships with an opportunistic connection, conn me-to-anyone. It's easy to customize this.
Add a line to me-to-anyone which sets the parameter leftid to your FQDN, preceded by an @ sign. In our example:
conn me-to-anyone
...
leftid=@xy.example.com
...
The @ causes FreeS/WAN to identify itself by your FQDN, rather than by an IP which corresponds to that name.
Note that the left and right designations in ipsec.conf are arbitrary. We follow a convention of using left for local and right for remote.
Uncomment the line auto=route to enable the connection.
Normally, this is all the configuration you will need to do. However, if your FreeS/WAN is protecting an interface other than the one on your machine's default route, you will need to adjust the interfaces= line in config setup.
A full ipsec.conf(5) file for this setup is available here.
The quick method is to point a browser to oetest.freeswan.org. A link there will tell you whether or not you have an encrypted connection.
For more detail, take these steps:
You should see a tunnel to the opportunistic host. It will look something like:
1.2.3.4/32 -> 5.6.7.8/32 => tun0x146c@5.6.7.8
When FreeS/WAN cannot set up an opportunistic connection, and no explicit tunnel has been configured, its default is to allow the traffic through in the clear. For the non-opportunistic host, you should see a %pass eroute (IPsec route), the FreeS/WAN mechanism that implements that default. This looks something like:
1.2.3.4/32 -> 9.10.11.12/32 => %pass
To enable full opportunism on your standalone system (or NATting gateway), you need to do a bit more. This will allow others to initiate encrypted connections to your system -- for example, if you run services on your machine and want remote clients to be able to access them securely.
There are two steps in the setup.
Both need to be a little different than in the initiate-only case.
Most people can use the conn me-to-anyone exactly as it ships in the default ipsec.conf(5) file. Just uncomment auto=route to enable it.
Unlike the configuration above, do not set leftid=. By default, FreeS/WAN will use the IP address of your public interface instead of a name as your identity. Once again, if FreeS/WAN is protecting a different interface, you will need to adjust interfaces= in the config setup section.
You can refer to this sample configuration.
FreeS/WAN must also use the secret key from ipsec.secrets(5) that matches this IP address. Normally you have only one RSA key, so there is no need to alter ipsec.secrets.
You need to put two records, a KEY record and a TXT record, in the DNS reverse map for your public IP. They need to be here because the initiating FreeS/WAN must look up your data knowing only your machine's IP address, not its name. As mentioned above, this requires your ISP's co-operation.
The KEY record you need looks like this:
; RSA 2048 bits xy.example.com Sat Apr 15 13:53:22 2000 4.3.2.1.in-addr.arpa. IN KEY 0x4200 4 1 AQOF8tZ2...+buFuFn/
Generate it with
You also need to create a TXT record, to let others know that this machine can receive opportunistic connections. It also lets them know that the machine is authorized to encrypt on its own behalf.
Use the command:
ipsec showhostkey --txt 1.2.3.4
where you replace 1.2.3.4 with your public IP.
The record (with key shortened) looks like this:
; RSA 2048 bits xy.example.com Sat Apr 15 13:53:22 2000
IN TXT "X-IPsec-Server(10)=1.2.3.4 AQOF8tZ2...+buFuFn/"
Send both records to your ISP, to be published in your IP's reverse map.
There is a particular security concern when you allow incoming opportunism.
Incoming opportunistic packets enter your machine via an IPSec tunnel. That is, they all appear as ESP (protocol 50) packets, concealing whatever port and protocol characteristics the packet within the tunnel has. Contained in the tunnel as they pass through ppp0 or eth0, these packets can bypass your usual firewall rules on these interfaces.
Since you will be exchanging opportunistic packets with peers who are not familiar to you, you will want to firewall your ipsec interfaces the way you would any publicly accessible interface.
A simple way to do this is to create one iptables(8) table with all your filtering rules for incoming packets, and apply the entire table to all public interfaces, including ipsec interfaces.
Here's more on firewalling with opportunistic encryption.Next we expand from a standalone system (which protects only its own traffic) to a gateway (which protects traffic for other systems).
There is one special case in which gateway configuration is quite simple -- if all the machines behind the gateway are hidden from the Internet. We describe that first, then go on to describe gateways for visible clients.
If your gateway uses NAT to allow machines to access the Internet without having their own routable IP addresses, then from the point of view of anyone else on the Internet:
For purposes of IPsec across the Internet, your gateway can be treated as a standalone machine. Consequently,
For a more detailed discussion of NAT, see our background section.
Many gateways will need to support client systems that have routable addresses and are thus visible to the Internet. To equip such a gateway with opportunistic encryption, you'll need a co-operative ISP that will allow you to insert resource records into reverse DNS.
Setup for a gateway involves:
You need only make a few additions to in the ipsec.conf(5) file:
In ipsec.conf(5), a new conn is needed for each local subnet to be protected by opportunistic encryption. If you are also protecting the gateway, most of the new conn can be borrowed from the old one. Place this before me-to-anyone:
conn subnet-to-anyone
also=me-to-anyone
leftsubnet=42.42.42.0/24
Note that a subnet described in ipsec.conf(5) need not correspond to a physical network segment. This is discussed in more detail in our advanced configuration document.
If required, a gateway can easily provide this service for more than one subnet. You just add a connection description for each.
We assume you already have a KEY record in the reverse map for your gateway's public IP address, so your gateway can accept incoming connections. This is described above.
For the gateway to provide an opportunistic encryption service for other systems, it must be possible for the initiator of an IPsec connection to:
This is done by adding a TXT record to the reverse map for the endpoint. The record (with key shortened) looks like this:
; RSA 2048 bits gateway.example.com Sat Apr 15 13:53:22 2000
IN TXT "X-IPsec-Server(10)=1.2.3.4 AQOF8tZ2...+buFuFn/"
This record must be generated on the gateway so it can get the key from ipsec.secrets(5). The command is:
ipsec showhostkey --txt 1.2.3.4
You must supply the gateway IP address on the command line.
One of these records is required in the reverse map for each system using this gateway for opportunistic IPsec. You insert it in the reverse map part of the zone file right after the line for that system's IP address, so part of the file might look like this:
1.42.42.42.in-addr.arpa. IN PTR arthur.example.com
; RSA 2048 bits gateway.example.com Sat Apr 15 13:53:22 2000
IN TXT "X-IPsec-Server(10)=1.2.3.4 AQOF8tZ2...+buFuFn/"
2.42.42.42.in-addr.arpa. IN PTR ford.example.com
; RSA 2048 bits gateway.example.com Sat Apr 15 13:53:22 2000
IN TXT "X-IPsec-Server(10)=1.2.3.4 AQOF8tZ2...+buFuFn/"
3.42.42.42.in-addr.arpa. IN PTR trillian.example.com
; RSA 2048 bits gateway.example.com Sat Apr 15 13:53:22 2000
IN TXT "X-IPsec-Server(10)=1.2.3.4 AQOF8tZ2...+buFuFn/"
You need one TXT record per client, but the TXT records can all be identical.
Some circumstances call for pre-configured IPSec connections, also known as VPNs (Virtual Private Networks). In particular, when you need strong authentication, ie. to access an office network, VPN is your best current choice. This may change when secure DNS arrives, since secure DNS will strengthen the authentication system for opportunistic encryption.
Below are instructions for pre-configuring:
as well as tips on:
A common requirement is for pre-configured connections between a specific network and some set of remote machines. For example, an office network will often need to provide remote access services for:
We refer to the remote machines as "road warriors". For purposes of IPsec, anyone with a dynamic IP address is a road warrior.
Of course, if both the warrior and the gateway at the office are set up for opportunistic encryption, then you may not need the pre-configured connection. Here we assume that you do need it. For example:
This section has three sub-sections:
On either end, the opportunistic setup is unaffected by this. You leave it in place so both systems can continue to do opportunistic encryption with everyone but each other.
To set up an explicitly configured connection, you need some information about the system on the other end.
Connection descriptions use left and right to designate the two ends. We adopt the convention that, from the gateway's point of view left=local and right =remote.
The gateway administrator needs to know some things about each road warrior:
To get this information, in a format suitable for insertion directly into the gateway's ipsec.conf(5) file, issue this command on the warrior machine:
ipsec showhostkey --right
The output should look like this (with the key shortened for easy reading):
rightid=@xy.example.com
rightrsasigkey=0s1LgR7/oUM...
The road warrior needs to know:
which can be generated by running ipsec showhostkey --left on the gateway. Each warrior must also know:
This information should be provided in a convenient format, ready for insertion in the warrior's ipsec.conf(5) file. For example:
left=1.2.3.4
leftsubnet=42.42.42.0/24
leftid=@gateway.example.com
leftrsasigkey=0s1LgR7/oUM...
The gateway administrator typically needs to generate this only once. The same file can be given to all warriors.
Of course it is also possible to provide different versions, with access to different subnets, to different groups of warriors. See our advanced configuration document.
To set up a road warrior machine, we start from the opportunistic initiator setup shown above.
Simply add a connection description us-to-office, with the left and right information you gathered above. This might look like:
# pre-configured link to office network
conn us-to-office
# information obtained from office system admin
left=1.2.3.4 # gateway IP address
leftsubnet=42.42.42.0/24 # the office network
leftid=@gateway.example.com
# real keys are much longer than shown here
leftrsasigkey=0s1LgR7/oUM...
# our stuff, same when we are opportunistic initiator
right=%defaultroute
rightid=@xy.example.com
Here's more detail on this configuration.
We could easily add more connections as required, perhaps one each for his office, her office, the kid's school,... The file would grow longer, but nothing already in the file would need to change.
Once you have a number of connections, you may like to make your ipsec.conf modular, to save typing. See these instructions.
Adding road warrior support so people can connect remotely to your office network is straightforward.
We start from the opportunistic gateway setup shown above.
You could put a complete connection description for each warrior in your ipsec.conf(5) file, but this makes for a rather unmanageable file if you have many warriors.
Instead, we suggest you give each warrior its own file, choosing some directory and naming convention that suits your system and style.
For this example, we use the directory /etc/ipsec.road and use filenames based on IPsec ID, so the warrior using ID xy.example.com gets a file named xy.conf.
Using such files, you need add only one line to ipsec.conf(5). With our naming convention, the line is:
include /etc/ipsec.road/*.conf
FreeS/WAN will then read all those files and behave as if they were part of the ipsec.conf(5) file.
We suggest you make your ipsec.conf modular, so that each file does not need to include information for the gateway side. Create a separate connection conn gate_stuff , containing this common information. For example:
conn gate_stuff
left=1.2.3.4
leftsubnet=42.42.42.0/24
leftid=@gateway.example.com
leftrsasigkey=0s1LgR7/oUM...
You will reference this in each road warrior connection.
Your include line needs to be before conn gate_stuff . A convenient place for the line is right after the conn %default section.
Each of the road warrior files then contains a connection description for that warrior. For example:
# connection description for road warrior "xy"
conn gate-xy
# use the gateway description in ipsec.conf(5)
also=gate_stuff
# allow connection attempt from any address
# attempt fails if caller cannot authenticate
right=%any
# authentication information
rightid=@xy.example.com
rightrsasigkey=0s1LgR7/oUM...
With this technique, it becomes fairly simple to administer a gateway that supports many road warriors. For example:
To add a new user, simply add a suitable file.
To disable an account -- for example if a key is compromised -- take any existing connection down and delete it from Pluto's internal database with:
ipsec auto --delete connection
and remove or correct the affected file.
If you have many users, it would be worthwhile to write scripts to automate such tasks.
Often it is useful to have explicitly configured IPsec tunnels between different offices of an organisation, or between organisations that have joint projects.
Of course, if both offices are set up for opportunistic encryption and the security policies in place allow you to use that, explicitly configured tunnels become unnecessary. However, this will not always be the case.
Adding up a network-to-network tunnel does not require any change to the opportunistic or road warrior parts of your ipsec.conf(5). You can keep those parts exactly as shown above.
Of course, a network-to-network tunnel requires its own connection description, so you have to add that. There are two ways to do this.
Choose whichever is more convenient to administer in your environment.
Here is a network-to-network tunnel description from our examples file:
# sample tunnel
# The network here looks like:
# leftsubnet====left----leftnexthop......rightnexthop----right====rightsubnet
# If left and right are on the same Ethernet, omit leftnexthop and rightnexthop.
conn sample
# left security gateway (public-network address)
left=10.0.0.1
# next hop to reach right
leftnexthop=10.44.55.66
# subnet behind left (omit if there is no subnet)
leftsubnet=172.16.0.0/24
# right s.g., subnet behind it, and next hop to reach left
right=10.12.12.1
rightnexthop=10.88.77.66
rightsubnet=192.168.0.0/24
auto=start
If you give an explicit IP address for left (and left and right are not directly connected), then you must specify leftnexthop (the router which left sends packets to in order to get them delivered to right). Similarly, you may need to specify rightnexthop (vice versa).
The *nexthop parameters are needed because of an unfortunate interaction between FreeS/WAN and the kernel routing code. They will be eliminated in a future release, but perhaps not soon. We know they should go, but getting them out is not a simple problem.
This description can be generated on either machine and simply inserted in the ipsec.conf(5) file on the other. No change is required or desired.
Provided both machines do IPsec over the interface that is their default route to the Internet (a common case, but by no means the only one) you can simplify the description somewhat.
When using left=%defaultroute, you do not need to specify leftnexthop. left does not need to know rightnexthop either, so on left the connection description can be:
conn sample
# left security gateway (public-network address)
left=%defaultroute
# subnet behind left (omit if there is no subnet)
leftsubnet=172.16.0.0/24
# right s.g., subnet behind it
right=10.12.12.1
rightsubnet=192.168.0.0/24
auto=start
On right it is:
conn sample
# left security gateway (public-network address)
left=10.0.0.1
# subnet behind left (omit if there is no subnet)
leftsubnet=172.16.0.0/24
# right s.g., subnet behind it
right=%defaultroute
rightsubnet=192.168.0.0/24
auto=start
At this point, we have covered setup for opportunistic encryption and for simple cases of road warrior and VPN connections. You have several choices for what to look at next:
This firewalling information supplements our quickstart guide.
It includes tips for firewalling:
and a list of helpful resources.
Firewall rules on a standalone system doing IPsec can be very simple.
The first step is to allow IPsec packets (IKE on UDP port 500 plus ESP, protocol 50) in and out of your gateway. A script to set up iptables(8) rules for this is:
# edit this line to match the interface you use as default route # ppp0 is correct for many modem, DSL or cable connections # but perhaps not for you world=ppp0 # # allow IPsec # # IKE negotiations iptables -A INPUT -p udp -i $world --sport 500 --dport 500 -j ACCEPT iptables -A OUTPUT -p udp -o $world --sport 500 --dport 500 -j ACCEPT # ESP encryption and authentication iptables -A INPUT -p 50 -i $world -j ACCEPT iptables -A OUTPUT -p 50 -o $world -j ACCEPT
Optionally, you could restrict this, allowing these packets only to and from a list of known gateways.
A second firewalling step -- access controls built into the IPsec protocols -- is automatically applied:
These errors are logged. See our troubleshooting document for details.
As an optional third step, you may wish to filter packets emerging from your opportunistic tunnels. These packets arrive on an interface such as ipsec0, rather than eth0, ppp0 or whatever. For example, in an iptables(8) rule set, you would use:
In this way, you can apply whatever additional filtering you like to these packets.
The packets emerging on ipsec0 are likely to be things that a client application on your machine requested: web pages, e-mail, file transfers and so on. However, any time you initiate an opportunistic connection, you open a two-way connection to another machine (or network). It is conceivable that a Bad Guy there could take advantage of your link.
For more information, read the next section.
The basic firewalling for IPsec does not change when you support incoming connections as well as connections you initiate. You must still allow IKE (UDP port 500) and ESP (protocol 50) packets to and from your machine, as in the rules given above.
However, there is an additional security concern when you allow incoming opportunistic connections. Incoming opportunistic packets enter your machine via an IPSec tunnel. That is, they all appear as ESP (protocol 50) packets, concealing whatever port and protocol characteristics the packet within the tunnel has. Contained in the tunnel as they pass through ppp0 or eth0, these packets can bypass your usual firewall rules on these interfaces.
Consequently, you will want to firewall your ipsec interfaces the way you would any publicly accessible interface.
A simple way to do this is to create one iptables(8) table with all your filtering rules for incoming packets, and apply the entire table to all public interfaces, including ipsec interfaces.
On a gateway, the IPsec-related firewall rules applied for input and output on the Internet side are exactly as shown above. A gateway exchanges exactly the same things -- UDP 500 packets and IPsec packets -- with other gateways that a standalone system does, so it can use exactly the same firewall rules as a standalone system would.
However, on a gateway there are additional things to do:
You need additional rules to handle these things. For example, adding some rules to the set shown above we get:
# edit this line to match the interface you use as default route # ppp0 is correct for many modem, DSL or cable connections # but perhaps not for you world=ppp0 # # edit these lines to describe your internal subnet and interface localnet=42.42.42.0/24 internal=eth1 # # allow IPsec # # IKE negotiations iptables -A INPUT -p udp -i $world --sport 500 --dport 500 -j ACCEPT iptables -A OUTPUT -p udp -o $world --sport 500 --dport 500 -j ACCEPT # ESP encryption and authentication iptables -A INPUT -p 50 -i $world -j ACCEPT iptables -A OUTPUT -p 50 -o $world -j ACCEPT # # packet forwarding for an IPsec gateway # simplest possible rules $ forward everything, with no attempt to filter # # handle packets emerging from IPsec # ipsec+ means any of ipsec0, ipsec1, ... iptables -A FORWARD -d $localnet -i ipsec+ -j ACCEPT # simple rule for outbound packets # let local net send anything # IPsec will encrypt some of it iptables -A FORWARD -s $localnet -i $internal -j ACCEPT
On a production gateway, you would no doubt need tighter rules than the above.
For more information, see these handy resources:
These are sample ipsec.conf(5) configuration files for opportunistic encryption, with comments. Much of this configuration will be unnecessary with the new defaults proposed for FreeS/WAN 2.x.
Full instructions for this setup are in our quickstart guide.
The ipsec.conf file for an initiate-only opportunistic setup is:
# general IPsec setup
config setup
# Use the default interface
interfaces=%defaultroute
# Use auto= parameters in conn descriptions to control startup actions.
plutoload=%search
plutostart=%search
# defaults for subsequent connection descriptions
conn %default
# How to authenticate gateways
authby=rsasig
# default is
# load connection description into Pluto's database
# so it can respond if another gatway initiates
# individual connection descriptions may override this
auto=add
# description for opportunistic connections
conn me-to-anyone
left=%defaultroute # all connections should use default route
right=%opportunistic # anyone we can authenticate
rightrsasigkey=%dns # look up their key in DNS
auto=route # set up for opportunistic
rekey=no # let unused connections die
leftid=@xy.example.com # our identity for IPSec negotiations
# must match DNS and ipsec.secrets
Normally, the last line above is the only one that you need to edit. However, some people may need to customize the interfaces= line in the "config setup" section. All other sections are identical for any standalone machine doing opportunistic encryption.
The @ sign in the leftid= makes the ID go "over the wire" as a Fully Qualified Domain Name (FQDN). Without it, an IP address would be used and this won't work.
The conn is not used to supply either public key. Your private key is in ipsec.secrets(5) and, for opportunistic encryption, the public keys for remote gateways are all looked up in DNS.
FreeS/WAN authenticates opportunistic encryption by RSA signature only, so "public key" and "private key" refer to these keys.
While the left and right designations here are arbitrary, we follow a convention of using left for local and right for remote.
Continue configuring initiate-only opportunism.
# description for opportunistic connections
conn me-to-anyone
left=%defaultroute # all connections should use default route
right=%opportunistic # anyone we can authenticate
rightrsasigkey=%dns # look up their key in DNS
auto=route # set up for opportunistic
rekey=no # let unused connections die
Note that leftid= has been removed.
Continue configuring full opportunism.
Here is our new connection, with comments:
conn us-to-office
#
# information obtained from office system admin
# goes to the right of the = signs in these lines
# values shown here are just for example
#
left=1.2.3.4 # gateway IP address
leftsubnet=42.42.42.0/24 # the office network
leftid=@gateway.example.com
# real keys are much longer than shown here
leftrsasigkey=0s1LgR7/oUM...
#
# our stuff
#
# all connections should use our default route
# also controls the source address on IPsec packets
right=%defaultroute
# our identity for IPsec negotiations
rightid=@xy.example.com
Everything else remains as it was when we had only opportunistic connections.
Return to our quickstart document.
Once you have more than one connection, you may want to design your ipsec.conf in a modular fashion. This will help you avoid retyping information. Use also= to include one full or partial connection description within another.
Here is a sample modular ipsec.conf file for our situation. Since the right... information is common to both our connections, we place it in the partial connection