# Introduction to FreeS/WAN

# Table of Contents

Introduction

- IPSEC, Security for the Internet Protocol

- Interoperating with other IPSEC implementations
- Applications of IPSEC
- The need to authenticate gateways

- The FreeS/WAN project

- Project goals
- Project team
- Information on the web
- Distribution sites
- Archives of the project mailing list

- Products containing FreeS/WAN

- Full Linux distributions
- Firewall distributions
- Firewall and VPN products

- Documentation

- This HowTo, in multiple formats
- Other documents in the distribution
- User-written HowTo information
- Papers on FreeS/WAN
- Test results

- License and copyright information
- Links to other sections

Installing FreeS/WAN

- Who needs to perform an installation?
- Re-installs
- Before starting the install

- Choosing a kernel
- Things you must have installed
- Getting FreeS/WAN
- Kernel configuration
- Install and test a kernel before adding FreeS/WAN

- Building and installing the software

- Everything but kernel installation
- Installing the new kernel
- Make sure Lilo knows about the new kernel

- Testing to see if install succeeded
- Where to go from here

Configuration

- Our example networks
- Configuration for a testbed network
- Set up and test networking

- Enabling packet forwarding
- Other software

- RTFM (please Read The Fine Manuals)
- Setting up RSA authentication keys

- Generating an RSA key pair
- Exchanging authentication keys
- Using RSA signatures for authentication

- The configuration file

- The setup section of ipsec.conf(5)
- Connection defaults
- Editing a connection description
- Which is which?

- Example setups

- VPN
- Road Warrior
- Opportunistic encryption

- Simplifying ipsec.conf files
- Is there a firewall in play?
- Testing the installation

- Matching numbers
- Sanity checking
- Starting a connection
- Ping tests
- Testing with tcpdump

- What next?
- Other configuration possibilities

- Choosing connection types
- Using shared secrets in production
- Using manual keying in production
- Setting up connections at boot time
- Multiple tunnels between the same two gateways
- Many tunnels from a single gateway
- Extruded Subnets
- Road Warrior with virtual IP address
- Dynamic Network Interfaces
- Unencrypted tunnels

FreeS/WAN manual pages

- Files
- Commands
- Library routines

FreeS/WAN and firewalls

- IPSEC packets

- ESP and AH do not have ports
- Header layout

- Filtering rules for IPSEC packets

- IPSEC through the gateway
- Preventing non-IPSEC traffic
- Filtering packets from unknown gateways

- Other packet filters

- ICMP filtering
- UDP packets for traceroute
- UDP for L2TP

- IPSEC and NAT

- NAT on or behind the IPSEC gateway works
- NAT between gateways is problematic
- Other references on NAT and IPSEC

- Calling firewall scripts, named in ipsec.conf(5)

- Scripts called at IPSEC start and stop
- Scripts called at connection up and down
- Scripts for ipchains
- DHR on the updown script
- Example updown script for ipchains

- Ipchains firewall configuration at boot

- Scripts based on Ranch's work
- The Seattle firewall
- The RCF scripts

Linux FreeS/WAN Troubleshooting

- Problem Reporting
- Logs used
- Information available on your system

- man pages provided
- Status information

- Pluto problem hints

- Using GDB on Pluto

- ifconfig reports for KLIPS debugging
- Testing between security gateways
- Claudia's guide

Kernel configuration for FreeS/WAN

- Not everyone needs to worry about kernel configuration
- Assumptions and notation

- Labels used

- Kernel options for FreeS/WAN

Distribution Roadmap: What's Where in Linux FreeS/WAN

- Top directory
- Documentation
- KLIPS: kernel IP security
- Pluto key and connection management daemon
- Utils
- Libraries

- FreeS/WAN Library
- Imported Libraries

Linux FreeS/WAN Compatibility Guide

- Implemented parts of the IPSEC Specification

- In Linux FreeS/WAN
- Deliberately ommitted
- Not (yet) in Linux FreeS/WAN

- Our PF-Key implementation

- PF-Key portability

- Kernels other than 2.0.38 and 2.2.18

- Other 2.0.x Intel Kernels
- 2.2 and 2.4 Kernels

- Intel Linux distributions other than Redhat

- Redhat 7.0
- SuSE Linux
- Slackware
- Debian
- Caldera

- CPUs other than Intel

- Corel Netwinder (StrongARM CPU)
- Yellow Dog Linux on Power PC
- Mklinux
- Alpha 64-bit processors
- Sun SPARC processors
- MIPS processors
- Motorola Coldfire

- Multiprocessor machines
- Support for crypto hardware
- IP version 6 (IPng)

- IPv6 background

Interoperation with other IPSEC implementations

- Patches to extend interoperability
- Interoperability problems

- Systems that want to use single DES

- Interop HowTo documents
- Interoperation with specific products

- Older versions of FreeS/WAN
- OpenBSD
- FreeBSD
- NetBSD
- Cisco Routers
- Nortel (Bay Networks) Contivity switch
- Raptor Firewall
- Gauntlet firewall GVPN
- Checkpoint Firewall-1
- Redcreek Ravlin
- SSH Sentinel
- F-Secure VPN for Windows
- Watchguard
- Xedia Access Point/QVPN
- PGP Mac and Windows IPSEC Client
- IRE Safenet/SoftPK
- Borderware
- Freegate
- Timestep
- Shiva/Intel LANrover
- Sun Solaris
- Sonicwall
- Radguard
- Windows clients
- NT domains vs. tunnels
- Windows 2000

History and politics of cryptography

- Introduction

- History
- Politics
- Links
- Outline of this section

- From our project leader

- Swan: Securing the Internet against Wiretapping
- Stopping wholesale monitoring

- Government promotion of weak crypto

- Escrowed encryption
- Limited key lengths

- Cryptography Export Laws

- US Law
- What's wrong with restrictions on cryptography
- The Wassenaar Arrangement
- Export status of Linux FreeS/WAN
- Help spread IPSEC around

- DES is Not Secure

- Dedicated hardware breaks DES in a few days
- Spooks may break DES faster yet
- Networks break DES in a few weeks
- We disable DES
- 40-bits is laughably weak
- Triple DES is almost certainly secure
- AES in IPSEC

- Press coverage of Linux FreeS/WAN:

- FreeS/WAN 1.0 press
- Press release for version 1.0

The IPSEC protocols

- Applying IPSEC

- Advantages of IPSEC
- Limitations of IPSEC
- IPSEC is a general mechanism for securing IP
- Using authentication without encryption
- Encryption without authentication is dangerous
- Multiple layers of IPSEC processing are possible
- Resisting traffic analysis

- Cryptographic components

- Block ciphers
- Hash functions
- Diffie-Hellman key agreement
- RSA authentication

- Structure of IPSEC

- IKE (Internet Key Exchange)
- IPSEC Services, AH and ESP
- The Authentication Header (AH)
- Encapsulated Security Payload (ESP)

- IPSEC modes

- Tunnel mode
- Transport mode

- FreeS/WAN parts

- KLIPS: Kernel IPSEC Support
- The Pluto daemon
- The ipsec(8) command
- Linux FreeS/WAN configuration file

- Key management

- Currently Implemented Methods
- Methods not yet implemented

Mailing lists and newsgroups

- Mailing lists about FreeS/WAN

- The project mailing lists
- Archives of the lists

- Indexes of mailing lists
- Lists for related software and topics

- Linux mailing lists
- Lists for IETF working groups
- Other mailing lists

- Usenet newsgroups

Web links

- The Linux FreeS/WAN Project

- Add-ons and patches for FreeS/WAN
- Distributions including FreeS/WAN
- Things FreeS/WAN uses or could use
- Other approaches to VPNs for Linux

- The IPSEC Protocols

- General IPSEC or VPN information
- IPSEC overview documents or slide sets
- IPSEC information in languages other than English
- RFCs and other reference documents
- Analysis and critiques of IPSEC protocols
- Background information on IP

- IPSEC Implementations

- Linux products
- IPSEC in router products
- IPSEC in firewall products
- Operating systems with IPSEC support
- Open source IPSEC implementations
- Interoperability

- Linux links

- Basic and tutorial Linux information
- General Linux sites
- Documentation
- Advanced routing
- Security for Linux
- Linux firewalls
- Miscellaneous Linux information

- Crypto and security links

- Crypto and security resources
- Cryptography law and policy
- Cryptography technical information
- Computer and network security
- Links to home pages

Glossary for the Linux FreeS/WAN project

- Jump to a letter in the glossary
- Other glossaries
- Definitions

Bibliography for the Linux FreeS/WAN project
IPSEC RFCs and related documents

- The RFCs.tar.gz Distribution File
- Other sources for RFCs & Internet drafts

- RFCs
- Internet Drafts
- FIPS standards
- Document CDs

- What's in the RFCs.tar.gz bundle?

- Overview RFCs
- Basic protocols
- Key management
- Details of various things used
- Older RFCs which may be referenced
- RFCs for secure DNS service, which IPSEC may use
- RFCs labelled "experimental"
- Related RFCs

FreeS/WAN FAQ

- Questions
- What is FreeS/WAN?
- How do I report a problem or seek help?
- Generic questions

- This is too complicated. Isn't there an easier way?
- Can I get commercial support for this product?
- Can I modify FreeS/WAN to ...?
- Can I contribute to the project?
- Is there detailed design documentation?
- Can FreeS/WAN talk to ...?
- Can different FreeS/WAN versions talk to each other?
- Does FreeS/WAN run on my version of Linux?
- Does FreeS/WAN run on the latest kernel version?
- Is a ... fast enough to handle FreeS/WAN with ... connections?

- Compilation problems

- gmp.h: No such file or directory
- ... virtual memory exhausted

- Life's little mysteries

- I cannot ping ....
- It takes forever to ...
- I send packets to the tunnel with route(8) but they vanish
- When a tunnel goes down, packets vanish
- The firewall ate my packets!
- Dropped connections
- TCPdump on the gateway shows strange things
- Traceroute does not show anything between the gateways

- Testing in stages

- Manually keyed connections don't work
- One manual connection works, but second one fails
- Manual connections work, but automatic keying doesn't
- IPSEC works, but connections using compression fail
- Small packets work, but large transfers fail
- Subnet-to-subnet works, but tests from the gateways don't

- Interpreting error messages

- SIOCADDRT:Network is unreachable
- ipsec_setup: Fatal error, kernel appears to lack KLIPS
- ipsec_setup: ... failure to fetch key for ... from DNS
- ipsec_setup: ... interfaces ... and ... share address ...
- ipsec_setup: Cannot adjust kernel flags
- Connection names in Pluto error messages
- Pluto: ... can't orient connection
- Pluto: ... no connection is known
- Pluto: ... no suitable connection ...
- Pluto: ... no connection has been authorized
- Pluto: ... OAKLEY_DES_CBC is not supported.
- Pluto: ... no acceptable transform
- ECONNREFUSED error message
- ... trouble writing to /dev/ipsec ... SA already in use
- ... ignoring ... payload

- Can I ...

- Can I reload connection info without restarting?
- Can I use several masqueraded subnets?
- Can I use subnets masqueraded to the same addresses?
- Can I assign a road warrior an address on my net?
- Can I use Quality of Service routing with FreeS/WAN?
- Can I recognise dead tunnels and shut them down?
- Can I build IPSEC tunnels over a demand-dialed link?
- Can I build GRE tunnels over IPSEC?
- Does FreeS/WAN support X.509 or other PKI certificates?
- Does FreeS/WAN support Radius or other user authentication?
- Does FreeS/WAN support single DES encryption?

- Why don't you restrict the mailing lists to reduce spam?

Performance of FreeS/WAN

- Methods of mesasuring

# 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

# Installing FreeS/WAN

## Who needs to perform an installation?

Some Linux distributions, listed in the introduction, ship with FreeS/WAN included. If you are using one of them, you need not perform a FreeS/WAN installation. That should all be done for you already. All you have to do is:

- include FreeS/WAN in your installation choices, or add it to your configuration later
- if you install kernel source, be sure to use a version which includes the FreeS/WAN patches. This should be available from your CDs or from the web site for your distribution.

Users of such distributions can skip ahead to our section on setting up FreeS/WAN.

Unfortunately, due to export laws restricting distribution of strong cryptography, not all distributions include FreeS/WAN. Moreover, the standard kernel does not include the kernel parts of FreeS/WAN. Many people will need to install FreeS/WAN, including patching and rebuilding their kernel.

## Re-installs

If this is the first FreeS/WAN install on this machine, skip this section.

The scripts are designed so that a re-install -- to upgrade to a later FreeS/WAN version or to a later kernel version -- can be done in exactly the same way as an original install.

The scripts know enough, for example, not to apply the same kernel patch twice and not to overwrite your ipsec.conf or ipsec.secrets files. However, they will overwrite the _updown script. If you have modified that, save your version under another name before doing the install.

Also, they may not always work exactly as designed. Check the BUGS file for any caveats in the current version.

to install a new version of FreeS/WAN, with your current kernel
  Download and untar the new FreeS/WAN. Since kernel source has already been installed and configured, you can skip a few steps in the procedure below. Go to Building FreeS/WAN, and follow normal FreeS/WAN procedures from there.
to install a new kernel, on a machine which already has FreeS/WAN installed
  Download and untar the new kernel source. Since this kernel is not yet configured, that is the next thing to do.Go to Kernel configuration, and follow normal FreeS/WAN procedures from there.
to upgrade both kernel and FreeS/WAN
  You need both new kernel source and new FreeS/WAN source. Follow the full FreeS/WAN install procedure.

## Before starting the install

Configure, compile, install, and test a Linux kernel, without FreeS/WAN.

If you have not done this before, you will need to read the Kernel HowTo.

### Choosing a kernel

#### 2.2.19 for many users

Many users can continue to run kernels from the 2.2 series of Linux production kernels.

At time of writing (June 2001), the latest version is 2.2.19. If you are going to use a 2.2 kernel, we strongly recommend 2.2.19 since:

- It has a number of small security fixes not found in earlier kernels.
- There have been changes in some kernel file formats that make it difficult to compile a current FreeS/WAN with earlier kernels.

If you really need to use an older 2.2.x kernel for some reason, see the note in the FreeS/WAN 1.91 release CHANGES file for a workaround for the compile difficulty, and the mailing list archives for more details if needed.

#### 2.4.x is possible

The new 2.4 series of kernels began in January 2001 and are currently (early June) at 2.4.5. FreeS/WAN is known to work on 2.4.5.

2.4 has new firewalling code called netfilter. This may provide good reasons to move to 2.4, especially on for gateway machines.

#### 2.0.x should still work

In the older 2.0.x kernel series, we no longer support versions earlier than 2.0.38. 2.0.38 has fixes for a number of small security-related glitches, worth having on a security gateway machine. FreeS/WAN has been tested on 2.0.39, and does work there.

Recent versions of FreeS/WAN are not heavily tested on 2.0 kernels. Most of both the development team and the user community are on 2.2, or even 2.4, by now.

We are likely to drop 2.0 support entirely if some problem crops up that would mean retaining it required significant work from our team.

#### Development kernels

Development kernels are a separate series, work-in-progress versions for use by kernel developers. By convention, production kernels have an even second digit in the version number (2.0, 2.2, 2.4) and development kernels have an odd digit there (2.1, 2.3, 2.5).

At time of writing, no more 2.3 kernels are being produced and the 2.5 series has not been started yet, so just now development kernels are not an issue. No doubt a 2.5 series will be started in the next few months.

Development kernels are not intended for production use . They change often and include new code which has not yet been thoroughly tested. This regularly breaks things, including FreeS/WAN. The FreeS/WAN team does not have the resources to chase the moving target; our priority is developing FreeS/WAN on stable kernels. If you encounter a problem on a development kernel, please solve it (you are a developer, aren't you?) and send us a patch. Of course, we will happily discuss problems and solutions on the mailing list, but we are unlikely to do much work on actually implementing a solution.

Fortunately we have a user who regularly fixes problems with FreeS/WAN on development kernels (merci, Marc), and we do fix some ourselves. FreeS/WAN often works just fine on a development kernel; it's just that there's no guarantee.

If you are going to test FreeS/WAN with a development kernel, we recommend you use our latest snapshot. This is the FreeS/WAN version most likely to have the patches required to work on a recent development kernel. The released version of FreeS/WAN is likely to be out of date for your purposes.

### Things you must have installed

If you have a CD distribution of Linux, it should include everything you need.

#### Tools and libraries

Use your distribution's tools to load:

- tools
  - a GNU C compiler (gcc or egcs)
  - assembler and linker for your architecture (the bin86 package on PCs)
  - miscellaneous development tools such as make(1) and patch(1)
- libraries, both headers and object modules
  - standard compiler libraries such as glibc
  - the GMP (GNU Multi-P recision) library, required for Pluto's public key calculations.
  - ncurses library if you want to use menuconfig (recommended)

There are some common slips worth avoiding here:

- not installing the GMP library. Pluto will not compile without it. See the FreeS/WAN FAQ for more detail if required.
- not installing patch(1). Our scripts need it to apply our patches to the kernel.

#### Kernel source code

You need the source code for the kernel because you must patch and re-compile it to install FreeS/WAN. There are several places you can get this:

- off your distribution CDs
- from your ditribution vendor's website
- from kernel.org

##### Kernel from CD

You can install the kernel from your distribution CD. It may be in two packages.

- kernel source
- kernel headers

However, if your CD is not recent, it may have an older kernel, in which case we suggest getting more recent kernel source from the net.

##### Vendor kernels

All the major distribution vendors provide kernel source. See for example:

- Red Hat's list of mirror sites
- SuSE's download page

Using a kernel from your distribution vendor may save you some annoyance later.

Different distributions put the kernel in different places (/vmlinuz, /boot/vmlinuz, /boot/vmlinuz-2.2.15 ...) and set lilo (the Linux loader) up differently. With a kernel from your distribution vendor, everything should work right. With other combinations, a newly compiled kernel may be installed in one place while lilo is looking in another. You can of course adjust the kernel Makefile and/or /etc/lilo.conf to solve this problem, but we suggest just avoiding it.

Also, distributions vendors may include patches or drivers which are not part of the standard kernel. If you install a standard kernel, you must either do without those features or download those patches and add them yourself.

##### Kernels from kernel.org

For kernels direct from Linus, without any distribution vendor's modifications, see the kernel.org mirror list, or go directly to ftp.<country>.kernel.org, with the appropriate two-letter country code inserted.

#### Once you've found a kernel

Once you have found suitable kernel source, choose a mirror that is close to you and bookmark it.

Kernel source normally resides in /usr/src/linux, whether you load it from a distribution CD or download a tar file into /usr/src and untar it there. Unless you both have unusual requirements and know exactly what you're doing, we recommend you put it there.

### Getting FreeS/WAN

You can download FreeS/WAN from our primary site or one of our mirrors.

Put the tarfile under /usr/src and untar it there. The command to use is:

- tar -xzf freeswan*.gz

This will give you a directory /usr/src/freeswan<version> .

Note that these methods don't work:

- putting freeswan under /usr/src/linux. The links become confused.
- untarring in one place, then using cp -R to move it where you want it. Some necessary symbolic links are not copied.

### Kernel configuration

The gateway kernel must be configured before FreeS/WAN is added because some of our utilities rely on the results of configuration.

Note for Redhat 7.1 users: If you are using the Redhat-supplied kernel, then you must do a make mrproper command before starting the kernel configuration. This prevents some unpleasant interactions between Redhat's config and our patches.

On some distributions, you can get the configuration files for the vendor's standard kernel(s) off the CD, and use that. This allows you to skip this step; you need not configure the kernel if the vendor has and you have the vendor's config file installed. Here is a mailing list message describing the procedure for Redhat:

    Subject: Re: [Users] Do I need to recompile kernel 2.2.17-14?
       Date: Wed, 6 Jun 2001 08:38:38 -0500
       From: "Corey J. Steele" <csteele@mtron.com>

    if you install the corresponding kernel-source-*.rpm, you can actually find
    the config file used to build that kernel in /usr/src/linux/Configs, just
    copy the one you want to use (based solely on architecture) to
    /usr/src/linux/.config, and proceed!  It should work.

If you have ever configured the kernel yourself on this machine, you can also skip this step.

If the kernel has not been configured, do that now. This is done by giving one of the following commands in /usr/src/linux:

make config
  command-line interface
make menuconfig
  text menus (requires curses(3) libraries)
make xconfig
  using the X window system (requires X, not recommended for gateways)

Any of these wiil do the job. If you have no established preference, we suggest trying menuconfig.

For more information on configuring your kernel, see our section on that topic.

### Install and test a kernel before adding FreeS/WAN

You should compile, install and test the kernels as you have configured them, so that you have a known stable starting point. The series of commands involved is usually something like:

make menuconfig
  choose kernel options, set up a kernel for your machine
make dep
  find dependencies between files
make bzImage
  build a loadable kernel image, compressed with bzip(1)
make install
  install it
make modules
  build modules which can be added to a running kernel
make modules_install
  install them
lilo
  ensure that the boot loader sees your changes

Doing this first means that if there is a problem after you add FreeS/WAN, tracking it down is much simpler.

If you need advice on this process, or general Linux background information, try our Linux web references. The most directly relevant document is the Kernel HowTo.

## Building and installing the software

There are several ways to build and install the software. All require that you have kernel source, correctly configured for your machine, as a starting point. If you don't have that yet, see the previous section

Whatever method you choose, it will do all of the following:

- add FreeS/WAN code to the kernel
  - insert patches into standard kernel code to provide an interface
  - add additional files which use that interface
- re-configure and re-compile the kernel to activate that code
- install the new kernel
- build the non-kernel FreeS/WAN programs and install them
  - ipsec(8) in /usr/local/sbin
  - others in /usr/local/lib/ipsec
- install FreeS/WAN man pages under /usr/local/man
- create the configuration file ipsec.conf(5). Editing this file to configure your IPSEC gateway is described in the next section.
- create an RSA public/private key pair for your system and place it in ipsec.secrets(5)
- install the initialisation script /etc/rc.d/init.d/ipsec
- create links to that script from the /etc/rc.d/rc[0-6].d directories so that each run level starts or stops IPSEC. (If the previous sentence makes no sense to you, try the From Power-up to Bash Prompt HowTo).

You can do the whole install with two commands (recommended in most cases) or get into as much of the detail as you like.

### Everything but kernel installation

To do everything except install the new kernel, cd into the freeswan directory and become root. Give any one of the following commands:

make oldgo
  Uses FreeS/WAN's default settings for some kernel configuration options. Leaves all other options unchanged from your last kernel configuration.
make ogo
  Invokes config so you can configure the kernel from the command line.
make menugo
  Invokes menuconfig so you can configure the kernel with text-mode menus.
make xgo
  Invokes xconfig so you can configure the kernel in an X window.

You must save the new configuration even if you make no changes. This ensures that the FreeS/WAN changes are actually seen by the system.

Our scripts save the output of make commands they call in files with names like out.kbuild or out.kinstall . The last command of each script checks the appropriate out.* file for error messages.

- If the last output you see is make saying it is calling our errcheck script, then all is well. There were no errors.
- If not, an error has occurred. Check the appropriate out.* file for details.

For the above commands, the error files are out.kpatch and out.kbuild.

These scripts automatically build an RSA authentication key pair (a public key and the matching private key) for you, and put the result in /etc/ipsec.secrets. For information on using RSA authentication, see our configuration section. Here, we need only note that generating the key uses random(4) quite heavily and if random(4) runs out of randomness, it will block until it has enough input. You may need to provide input by moving the mouse around a lot, or going to another window and typing random characters, or using some command such as du -s /usr to generate disk activity.

### Installing the new kernel

To install the kernel the easy way, just give this command in the FreeS/WAN directory:

make kinstall
  Installs the new kernel and, if required, the modules to go with it. Errors, if any, are reported in out.kinstall

Using make kinstall from the FreeS/WAN directory is equivalent to giving the following sequence of commands in /usr/src/linux:

- make
- make install
- make modules
- make modules_install

If you prefer that sequence, use it instead.

If you have some unusual setup such that the above sequence of commands won't work on your system, then our make kinstall will not work either. Use whatever method does work on your system. See our implementation notes file for additional information that may help in such situations.

### Make sure Lilo knows about the new kernel

Check your lilo.conf(5) file to ensure it points to the right kernel, then run lilo(8) to read lilo.conf(5) and set up the bootloader.

## Testing to see if install succeeded

To check that you have a sucessful install, you can reboot and check (by watching messages during boot or by looking at them later with dmesg(8)) that:

- the kernel reports the right version. If not, you are likely still running your old kernel. Check your lilo.conf(5) file and the installation directory (defined in the kernel make file, often /boot but the default is /), then rerun lilo(8).
- KLIPS initialisation messages appear
- Pluto reports that it is starting

You can also try the commands:

- ipsec --version, to test whether /usr/local/bin is in your path so you can use IPSEC administration commands
- ipsec whack --status, using ipsec_whack(8) to ask Pluto for status information

Of course any status information at this point should be uninteresting since you have not yet configured connections.

## Where to go from here

See the following section for information on configuring connections.

Alternately, you might want to look at background material on the protocols used before trying configuration.

# Configuration

This section describes setting up and testing Linux FreeS/WAN.

Before attempting this, you should:

- look at our introduction section. We assume here that you understand concepts and terms described there.
- ensure that FreeS/WAN is installed on your system. See these links:
  - testing whether FreeS/WAN is installed
  - performing an installation

You also need to set up and test IP networking on all the machines you plan to install FreeS/WAN on or to use in testing, before trying to set up FreeS/WAN. This is discussed in more detail after the description of our example networks.

## Our example networks

For our examples, we assume that there are only three networks involved, two that want to talk to each other plus the Internet in the middle. The idea is to build an encrypted tunnel across the Internet so the two networks can talk securely. Once you have this working between two network gateways, extending it to three or more is straightforward.

In our examples, we'll call the two gateways East and West. We'll have only one client machine on each net: Sunrise in the East and Sunset in the West.

A diagram:

         Sunset==========West------------------East=========Sunrise
               local net       untrusted net       local net

Our goal here is to tell you how to set up the two gateways, East and West. We assume your goal is to ensure that East and West encrypt all traffic between them, or at least all that your security policies require them to encrypt.

Of course one does not always have a security gateway separate from the client machine. Especially for road warriors, a network that looks like this is common:

                                               telecommuter's PC or
           corporate LAN                       traveller's laptop
         Sunset==========West------------------East
               local net       untrusted net

and this is possible:

                         West------------------East
                               untrusted net

In our configuration files, and in this discussion, we treat the two simpler setups as degenerate cases of the network-to-network link. For all the diagrams above, for example, we speak of "the subnet behind East". In two of the diagrams, of course, that "subnet" is just the machine itself.

This may take some getting used to, but we hope it is less confusing than continually having to say things like "the subnet behind East (or the East machine itself if there is no client subnet)".

## Configuration for a testbed network

Many users just want to get IPSEC installed on a few machines. They can skip this section.

Others may want to build a testbed network, for any of a number of reasons. For them, we have some suggestions.

The ideal test setup for IPSEC is something like:

            Sunset==========West-----eth0    eth1-----East=========Sunrise
                  local net          test machine         local net

The test machine routes packets between the two gateways. This makes things more complicated than if you just connected the two gateway machines directly to each other, but it also makes your test setup much more like the environment you actually use IPSEC in. Those environments nearly always involve routing, and quite a few apparent IPSEC failures turn out to be problems with routing or with firewalls dropping packets. This approach lets you deal with those problems on your test setup.

Also, the test machine is in the ideal position to run diagnostic software (such as tcpdump(8)) for checking IPSEC packets. Such software is likely to misbehave if run on the gateways themselves. It is designed to look into a normal IP stack and may become confused if you ask it to display data from a stack which has IPSEC in play.

For more detailed testbed information see these mailing list messages:

- a user's detailed setup diary for his testbed network
- a FreeS/WAN team member's notes from testing at an IPSEC interop "bakeoff"

## Set up and test networking

Before trying to get FreeS/WAN working, you should configure and test IP networking on both gateways and on at least one client machine behind each of them. IPSEC cannot work without a working IP network beneath it. Many reported "FreeS/WAN problems" turn out to actually be problems with routing or firewalling. If any actual IPSEC problems turn up, you often cannot even recognise them (much less debug them) unless the underlying network is right.

If you need advice on this, your best sources are likely:

- the Networking Howto
- the Network Administrator's Guide.
- the Linux Networking-concepts HOWTO from Rusty Russell, author of most of the Linux firewalling code

See also our bibliography.

Here is our network diagram again:

            Sunset==========West------------------East=========Sunrise
                  local net       untrusted net       local net

The client machines, Sunrise and Sunset in our example, may have assigned routable IP addresses, or they may be using private non-routable addresses (as defined in RFC 1918) with the gateways doing IP masquerade. It doesn't matter which, as long as whatever it is works correctly.

Note, however, that the two subnets must have distinct addresses. You cannot have them both masqueraded to the same range of RFC 1918 addresses.

- If Sunrise and Sunset have routable IP addresses, test that they can ping each other.
- If IP masquerading is in use, test as far as you can. For example, if Sunset is masqueraded behind West then Sunrise cannot ping Sunset but should be able to ping West. Whether Sunset can ping Sunrise, assuming Sunrise is not masqueraded, would depend on whether West's rules let ICMP packets through. If not, you should adjust those rules.

In any case, it is not enough to just test that East and West can communicate.

### Enabling packet forwarding

Some systems turn off packet forwarding by default, even for kernels in which it has been enabled. This is the safe default. You don't want systems forwarding packets in uncontrolled ways.

To turn forwarding on temporarily, use the following command as root:

             echo "1" > /proc/sys/net/ipv4/ip_forward

Turning it on permanently is also possible. The exact method varies from distribution to distribution:

Older Readhat
  in the file /etc/sysconfig/network, set FORWARD_IPV4=yes
Redhat 6.x and 7.0
  in the file /etc/sysconfig/network, set net.ipv4.ip_forward=1
Debian r2.2 systems (and most likely Debian r2.2 derived systems):
  in the file /etc/network/options, set ip_forward=yes

A gateway machine needs forwarding enabled or it will not route packets between the two networks it is attached to. The simplest way to ensure this is to enable forwarding using whatever method your distribution provides. See list above.

A more conservative approach is to disable forwarding in your system configuration, then enable from your boot scripts after appropriate firewall scripts are in place.

### Other software

Configure and test any other software you will want to use for testing once IPSEC is up. For example, you might put an HTTP daemon on Sunset and a browser on Sunrise. Make sure these work without IPSEC.

If these tests fail, figure out why and fix it. Do not proceed until it works.

## RTFM (please Read The Fine Manuals)

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

The man pages describing configuration files are:

- ipsec.conf(5)
- ipsec.secrets(5)

Man pages for commands used in this document include:

- ipsec(8)
- ipsec_pluto(8)
- ipsec_rsasigkey(8)
- ipsec_auto(8)
- ipsec_manual(8)

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

## Setting up RSA authentication keys

RSA keys come in matched pairs. Each pair includes:

- a public key which need not be kept secure. Everyone you plan to communicate with must be able to get a copy of this. It does not matter if an enemy gets it as well.
- a private key which must be kept secure. No-one but you should have access to it.

For FreeS/WAN, both keys for your system are in the ipsec.secrets(5) file. Maintaining security of this file is essential since it holds your private key.

Public keys for systems you communicate with are placed in ipsec.conf(5). Security here is less vital (unless you are using manual keying as well, in which case the file may have secret keys). It does not matter if an enemy knows the public keys, as long as the private keys are protected.

### Generating an RSA key pair

If you installed FreeS/WAN yourself, then the installation process has already generated an RSA key pair for you and placed it in the ipsec.secrets(5) file.

If not, you need to:

- Generate an RSA key pair (private and public) using ipsec_rsasigkey(8).
- Put the private key in ipsec.secrets, with a wrapper. The result looks like this:

    : RSA {
          <stuff generated by rsasigkey>

          }

Note that:

- the ":" must be unindented (at the margin)
- the other lines, including the "}", must be indented (not at the margin)
- spaces are needed to separate tokens so, for example, ":RSA{" won't work.

This means "always use this as my private RSA key". For other options, for example if you want to use different keys with different partners, see the man pages.

The RSA keys we generate are suitable only for authentication, not for encryption. IPSEC uses them only for authentication. See our IPSEC section for details.

It is also possible to use keys in other formats, not generated by FreeS/WAN. This may be necessary for interoperation with other IPSEC implementations. See our links to patches which add support for keys generated by PGP or embedded in X.509 certificates.

### Exchanging authentication keys

The next step is to send your public key to everyone you need to set up connections with, and collect their public keys. The public key is the line in the output of rsasigkey starting "#pubkey=0x".

Public keys need not be protected as fanatically as private keys. They are intended to be made public; the system is designed to work even if an enemy knows all the public keys used.

Note, however, that authentication of public keys is critical. It does not matter if an enemy knows your public keys, but if you can be tricked into trusting a public key supplied by an enemy, you are in deep trouble.

For example, consider the fellow who wants to communicate with his mistress, keeping messages secret from his wife.

- If the wife obtains the mistress' public key, that is not a problem. As long as she does not get the private key, she can neither read things sent to the mistress nor authenticate herself as the mistress.
- If the mistress has any sense, she protects her private key carefully. So long as she does that, and the husband encrypts his messages correctly, there should be no (cryptographic!) problem.
- However, imagine that the wife is somewhat devious. She generates a public/private key pair and sends the husband that public key, forging the message to look as if it came from the mistress. Of course this fails if the husband has enough sense to check the key's validity before using it.
- However, if the husband blindly accepts that key without verification, it is extremely unlikely that he will be pleased with the results.
- If he accepts that key, the wife can read every message he sends to it.
- She can also pose as the mistress and send him whatever messages she likes.

You must authenticate any public keys received before using them. For remote sites, the simplest method is to exchange them using PGP-signed email (taking appropriate steps to authenticate the signing keys). For nearby machines, a floppy disk or trusted network is fine.

### Using RSA signatures for authentication

For each system you will communicate with, you need an RSA public key and an identifier associated with it. The identifiers go in the leftid= and rightid= lines of connection descriptions in ipsec.conf(5). They are the names the systems use to identify themselves during connection negotiation.

There are four possible forms for these identifiers:

- an IP address in dotted quad notation, four numbers separated by periods (10.1.19.32).
- a domain name, which will be resolved immediately (bad.example.com).
- a fully qualified domain name (FQDN) with a leading "@" to indicate that it should not be resolved (@good.example.com)
- user@FQDN (fred@example.com)

We recommend that only the @FQDN form be used in most applications. IP addresses make remarkably uninteresting names. Resolving a name to an IP address is not interesting in this context, and attempting to resolve it may cause problems if DNS is down or if someone subverts a DNS server which you rely on.

If your domain is example.com, the names you use should be of three types:

- machine names such as "@firewall.example.com".
- names for other resources, chosen not to conflict, such as "@fireplug.example.com"
- identifiers for people (actually for their road warrior machines), such as "@alice.example.com" or, if she prefers, "@cleopatra.example.com".

In order to facilitate distributing keys through DNS, we recommend avoiding

- names from non-existent domains
- names from other people's domains
- names which conflict with machine names in your domain
- user@FQDN

For example, if you have a server alice.example.com, then you should not use "@alice.example.com" to identify Alice's laptop for IPSEC.

## The configuration file

FreeS/WAN uses a configuration file, ipsec.conf(5).

This section describes setting up the parts of that file that apply to all connections:

config setup section
  describes machine configuration
conn default section
  default parameters which apply to all connections

and gives an introduction to the parts of the file that specify the actual connections. The following section covers setting up three common types of connection, all using automatic keying with RSA authentication of the gateways:

conventional VPN
  two security gateways, each with a known fixed IP address and with a network of client machines behind it
Road Warrior
  one player has a dynamically-assigned address
opportunistic encryption
  the two machines have no prior knowledge of each other, but are set up to secure connections whenever possible

Setup is quite similar for each of these, but details differ.

Other types of connections are covered in later sections.

The easiest way to create a connection is by editing one of our examples. Here we will use the one in the installation ipsec.conf file. You could also start with one from our doc/examples file if one of those is closer to what you need to do.

### The setup section of ipsec.conf(5)

The first section of ipsec.conf(5) contains overall setup parameters for IPSEC, which apply to all connections. In our example file, it is:

    # basic configuration
    config setup
            # THIS SETTING MUST BE CORRECT or almost nothing will work;
            # %defaultroute is okay for most simple cases.
            interfaces=%defaultroute
            # Debug-logging controls:  "none" for (almost) none, "all" for lots.
            klipsdebug=none
            plutodebug=none
            # Use auto= parameters in conn descriptions to control startup actions.
            plutoload=%search
            plutostart=%search
            # Close down old connection when new one using same ID shows up.
            uniqueids=yes

The variables set here are:

interfaces
  Tells the KLIPS IPSEC code in the Linux kernel which network interface to use. The interfaces specified here are the only ones this gateway machine will use to communicate with other IPSEC gateways. If this is not correct, nothing works.

In many cases, the appropriate interface is just your default connection to the world (the Internet, or your corporate network). In these cases, you can use the default setting:

- interfaces=%defaultroute

To check what FreeS/WAN sees as the default route, you can use the command ipsec showdefaults. You may need to compare this with the output from route -n to get a more complete picture.

In other cases, you can name one or more specific interfaces to be used by FreeS/WAN. For example:

- interfaces="ipsec0=eth0"
- interfaces="ipsec0=eth0 ipsec1=ppp0"

Both tell KLIPS to use eth0 as ipsec0. The second one also supports IPSEC over PPP.

Note that

- Multiple tunnels do not require multiple interfaces. It is possible, and even common, to have one ipsec interface carrying traffic for many tunnels.
- For PPP connections, you specify the virtual PPP interface (for example ppp0) here, not the underlying physical interface.

If you need to discover interface names, use the command:

            ifconfig

If you have PCMCIA or other interfaces that are not available at boot time, special measures are required. See our section on that.
klipsdebug
  Debugging setting for the KLIPS kernel code
plutodebug
  Debugging setting for the Pluto key and connection negotiation daemon.

klipsdebug and plutodebug can each be set to "none" or to "all" in most circumstances. There are other options; see the relevant man pages.

plutoload
  List of connections to be automatically loaded into memory when Pluto starts.
plutostart
  List of connections to be automatically negotiated when Pluto starts.

plutoload and plutostart can be quoted lists of connection names, but are often set to %search as in our example. Any connection with auto=add in its connection definition is then loaded, and any connection with auto=start is started.

In most cases, you want plutostart=%search here and auto=start in your connection descriptions. That way when a connection is broken, for example if one machine crashes or is taken down for some reason, it will be reliably rebuilt. If only one end is told to start the connection, then if the other end crashes, you may lose the connection for a long time. The end that could rebuild does not know it needs to.

The exception to the above is when you have many road warriors connecting to a single gateway. Having the gateway trying to rebuild tunnels to systems which are offline can waste considerable resources. In this case, the gateway should have auto=add for all connections, and let the remote systems start negotiations.

uniqueids
  Controls whether two connections with the same subnet on the remote end are allowed. Normally this is set to yes so that when a remote system disconnects and reconnects, Pluto will automatically take the old connection down.

### Connection defaults

There is a special name %default that lets you define things that apply to all connections. e.g. our example file has:

    # defaults for subsequent connection descriptions
    conn %default
            # How persistent to be in (re)keying negotiations (0 means very).
            keyingtries=0
            # How to authenticate gateways
            authby=rsasig

Variables set here are:

keyingtries
  How persistent to be in (re)keying negotiations (0 means very).

For testing, you might wish to set this to some small number, perhaps even to 1, to avoid wasting resources on incorrectly set up connections. In production, it is often set to zero (retry forever). Keeping the connection up is what machine resources are for, so if a connection is down you night as well waste resources retrying as waste them by sitting idle. Of course some caution should be exercised with this, since it can waste network resources as well.

authby=rsasig
  authenticate gateways using RSA signatures. This is the preferred method and is what we will use in this section's examples. An alternate method is to use shared secrets.

Once you are finished testing, you can edit these defaults, adding anything that is standard for all gateways in your organisation.

Previous versions of this document said:

> Note, however, that setting the auto= parameter in the default connection description does not work. You cannot use auto=start here to get all connections started automatically or auto=add to get them all loaded. You must set that in the individual connection descriptions.

This restriction has been removed in FreeS/WAN 1.9. However, if the other end of the tunnel is an older version, the restriction will still apply there, so some caution is still required.

### Editing a connection description

Edit our example connection to match what you want to do. Rename it appropriately for the connection you would like to build: "fred-susan", "reno-van" or whatever. The name is the second string in the line that begins with "conn", for example in:

            conn snt

The connection name is "snt" (subn et tunnel) and to define another connection you make a copy with a new name such as:

            conn reno-van

A sample connection description is:

    # 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

We omit here the variables we have shown as set in the default connection above. All of them could also be set here. If they are set in both places, settings here take precedence. Defaults are used only if the specific connection description has no value set.

The network described above looks like this:

             subnet 172.16.0.0/24              =leftsubnet
                    |
             interface 172.16.0.something
                left gateway machine
             interface 10.0.0.1                =left
                     |
             interface 10.44.55.66             =leftnexthop
                  router
             interface we don't know
                     |
                INTERNET
                     |
             interface we don't know
                  router
             interface 10.88.77.66             =rightnexthop
                     |
             interface 10.12.12.1              =right
                right gateway machine
             interface 192.168.0.something
                     |
             subnet 192.168.0.0/24             =rightsubnet

You need to edit the connection description, inserting appropriate IP addresses and subnet descriptions so that it describes your network.

In most cases, you should use numeric IP addresses, not names, here. The file syntax allows names to be used, but this creates an additional risk. If someone can subvert the DNS service, then they can redirect packets whose addresses are looked up via that service.

Many of the variables in this file come in pairs such as "leftsubnet: and "rightsubnet", one for each end of the connection. The variables on the left side are:

left
  The gateway's external interface, the one it uses to talk to the other gateway. This can be left=%defaultroute.
leftnexthop
  Where left should send packets whose destination is right, typically the first router in the appropriate direction.

This need not always be set.

- If the two gateways are directly linked (packets can go from one to the other without IP routing by any intermediate device) then you need not set either leftnexthop or rightnexthop.
- a connection with left=%defaultroute or right=%defaultroute must not have the corresponding nexthop parameter set

However, in all other cases, you must provide nexthop information. KLIPS (Kernel IP Security) bypasses the normal routing machinery, so you must give KLIPS the information even though routing already knows it.

(Yes, we know that design is not ideal, and we plan to change it. See extensive discussions on the mailing list, mostly with "routing" or "KLIPS 2" in the subject lines.)

leftsubnet
  Addresses for the machines which left is protecting.
  - Often something like 101.202.203.0/24 to indicate that a subnet resides behind left. Often this subnet will be directly connected to left, but this not necessary. The only requirement is that left must be able to route to it.
  - If you omit the leftsubnet line, then left is both the security gateway and the only client on that end.
  For some applications, you may want to create two connections, one to protect traffic from the subnet behind left and another to protect traffic from the left gateway itself. This takes two connection descriptions. See below.
leftfirewall
  Set to "yes" if there is a firewall in play that suppresses forwarding, for example if a subnet behind left uses non-routable addresses and left does IP masquerade for them. This will cause Pluto to invoke our default script to adjust the firewall as required.

For more detail, including ways to invoke your own customised script instead, see our FreeS/WAN and firewalls section.

auto
  If the conn setup section has plutoload=%search , then all connections marked auto=add are loaded when Pluto starts.

If the conn setup section has plutostart=%search , then all connections marked auto=start are started when Pluto starts.

Initially, we suggest using auto=add on all connections. This lets you start them manually during testing. Once they are tested, you can change many of them to auto=start.

For each left* parameter, there is a corresponding right* parameter.

Note that a connection to a subnet behind left does not include left itself. The tunnel described above protects packets going from one subnet to the other. It does not apply to packets which either begin or end their journey on one of the gateways. If you need to protect those packets, you must build separate tunnel descriptions for them.

It is a common error to attempt testing a subnet-to-subnet connection by pinging from one of the gateways to the far end or vice versa. This does not work, even if the connection is functioning perfectly, because traffic to or from the gateway itself is not sent on that connection. If you want to protect traffic originating or terminating on the gateway, then you need a separate tunnel for that in addition to the subnet's tunnel. See the section on multiple tunnels below.

### Which is which?

Which security gateway is "left" and which is "right" is arbitrary.

We suggest that you name connections by their ends. For example, name the link between Fred and Susan's machines "fred-susan" or the link between your Reno and Vancouver offices "reno-van". You can then let "left" refer to the left half of the name, "fred" or "reno" in our examples, and "right" to the other half.

To simplify administration, we recommend that you use the same names in the ipsec.conf files on both ends. The name "reno", for example, should refer to the machine in Reno, no matter which city the file is in, and if "reno" is "left" in the reno-van description in Reno, then "reno" should be "left" in that description on the Vancouver machine as well.

Then when you copy the file from one machine to the other, the only change you should make on the second machine is changing the interfaces= line to match the interface that machine uses for IPSEC.

Of course the software does not actually require this. The names are just arbitrary strings to it. If your administrator in Reno wants to refer to the machines as "Phobos" and "Demios" while the Vancouver admin calls them "George" and "Gracie", things should still work.

## Example setups

In this section we show examples of three common setups:

- a VPN connection
- road warrior support
- opportunistic encryption

We use a, b, c ... to indicate components of IP addresses. Each letter is some number in the range 0 to 255, inclusive.

For additional examples, see our examples file.

### VPN

In this example, the network looks like this:

             subnet a.b.c.0/24                 =leftsubnet
                    |          (head office has routable IP addresses)
             interface a.b.c.d
                left gateway machine
             interface e.f.g.h                 =left
                     |         (external address outside a.b.c.0 subnet)
             interface e.f.g.i               =leftnexthop
                  router
             interface we don't know
                     |
                INTERNET
                     |
             interface we don't know
                  router
             interface j.k.l.m                =rightnexthop
                     |
             interface j.k.l.n                =right
                right gateway machine
             interface 192.168.0.something
                     |        (branch office uses private IP addresses)
             subnet 192.168.0.0/24             =rightsubnet

The ipsec.conf(5) file might look like this (with RSA keys shortened for easy display):

    # basic configuration
    config setup
            interfaces=eth0
            klipsdebug=none
            plutodebug=none
            plutoload=%search
            plutostart=%search

    # defaults that apply to all connection descriptions
    conn %default
            # How persistent to be in (re)keying negotiations (0 means very).
            keyingtries=0
            # How to authenticate gatways
            authby=rsasig

    # VPN connection for head office and branch office
    conn head-branch
            # identity we use in authentication exchanges
            leftid=@head.example.com
            leftrsasigkey=0x175cffc641f...
            # left security gateway (public-network address)
            left=e.f.g.h
            # next hop to reach right
            leftnexthop=e.f.g.i
            # subnet behind left (omit if there is no subnet)
            leftsubnet=a.b.c.0/24
            # right s.g., subnet behind it, and next hop to reach left
            rightid=@branch.example.com
            rightrsasigkey=0xfc641fd6d9a24...
            right=j.k.l.n
            rightnexthop=j.k.l.m
            rightsubnet=192.168.0.0/24
            # right is masquerading
            rightfirewall=yes
            auto=start

The versions of this file at the two ends should be identical, except that each must have an interfaces= line appropriate for the local machine.

#### Routable and non-routable addresses

RFC 1918 reserves three groups of addresses for use on private networks:

- 10.0.0.0/8
- 172.16.0.0/12
- 192.168.0.0/16

Addresses in these ranges will never be assigned to anything on the Internet. Many routers automatically drop any packet with one of these addresses as either source or destination.

You can use FreeS/WAN to route between two such networks, using for example leftsubnet=192.168.47.0/24 and rightsubnet=192.168.48.0/24. These addresses still do not appear on the Internet; they are encapsulated inside IPSEC packets which have the gateways' external addresses (from the left and right parameters of the connection description) in their headers.

### Road Warrior

For our purposes, a "road warrior" is any machine that does not have a fixed IP address where it can normally be expected to be on line. This includes:

- a traveller who might connect from anywhere
- any machine that has a dynamic IP address -- nearly all dialup connections and most DSL or cable modem connections, at least in North America
- most home machines connecting to the office. If you have a home firewall that is always left on and has a static IP address, then you can use the VPN configuration described above. Otherwise, consider yourself a road warrior.

The configuration for road warrior support looks slightly different from a VPN configuration. We cannot use the road warrior's IP address in the configuration file since we don't know it, and we don't want to have our server retrying connections to road warriors that are no longer online.

In this example, the network looks like this:

             subnet a.b.c.0/24               =leftsubnet
                    |          (head office has routable IP addresses)
             interface a.b.c.d
                left gateway machine
             interface e.f.g.h               =left
                     |         (external address outside a.b.c.0 subnet)
             interface e.f.g.i               =leftnexthop
                  router
                     |
                INTERNET
                     |
         interface with dynamic IP address
              road warrior machine

Here the ipsec.conf(5) files on the two ends are slightly different. The one at the office might have exactly the same config setuo and conn %default sections as in the VPN example.

    # basic configuration
    config setup
            interfaces=eth0
            klipsdebug=none
            plutodebug=none
            plutoload=%search
            plutostart=%search

    # defaults that apply to all connection descriptions
    conn %default
            # How persistent to be in (re)keying negotiations (0 means very).
            keyingtries=0
            # How to authenticate gatways
            authby=rsasig

Then add a description for the road warrior connection:

    # Connection for road warrior Fred
    conn head-fred
            # identity we use in authentication exchanges
            leftid=@head.example.com
            leftrsasigkey=0x175cffc641f...
            # left security gateway (public-network address)
            left=e.f.g.h
            # next hop to reach right
            leftnexthop=e.f.g.i
            # subnet behind left (omit if there is no subnet)
            leftsubnet=a.b.c.0/24
            # accept any address for right
            right=%any
            # any address, provided authentication works
            rightid=@fred.example.com
            rightrsasigkey=0xd9a24765fe...
            # no subnet for a typical road warrior
            # it is possible, but usually not needed
            # let the road warrior start the connection
            auto=add
            # override the default retry for road warriors
            # we don't want to retry if IP connectivity is gone
            keyingtries=1

On the gateway end we use

- right=%any so we have no preset idea of right's IP address and will accept whatever arrives on the packets
- auto=add so we accept connections but don't initiate
- keyingtries=1 so we do not retry to excess when the partner disconnects or changes IP address

The file on the road warrior end is nearly identical, except that it has:

- interfaces=%defaultroute to handle the dynamic IP address.
- right=%defaultroute
- auto=start to start the connection
- keyingtries=0 to try to maintain the connection

Additional road warriors can be added as required. Each should have his or her own connection description with unique settings for rightid and rightrsasigkey.

Jean-Francois Nadeau's Practical Configurations document also has an example of using RSA authentication for road warriors.

### Opportunistic encryption

We use the term opportunistic encryption for encryption which does not rely on any pre-arranged connection, hence does not require that the administrators of the two gateways involved communicate with each other (for example, to exchange keys) before their systems can create a secure connection.

The idea is that each gateway check the destinations of outgoing packets, see if an encrypted connection is possible and, if so, take the opportuntity to encrypt. The opportunity will exist whenever the admins on both ends have set their systems up for opportunistic encryption.

This makes encryption the default behaviour, and could greatly increase the overall security of the Internet if it were widely enough adopted. See our documents:

history and politics
  for the reasons we want to do this
IPSEC protocols
  for discussion of the general principle of encrypting as much as possible

The gateways must be able to authenticate each other for IPSEC to be secure. For opportunistic encryption, we rely on the domain name system, DNS, to provide the RSA keys needed for this authentication. Note, that currently this is not entirely secure because the DNS mechanism it relies on is not fully secure. Eventually, as secure DNS becomes widely deployed, this will change.

#### Status

The team have been working on this for some time, and testing internally. As of late May, 2001 this code is ready for wider testing. We encourage everyone to try it.

The main documentation items so far are:

- an Opportunism HowTo by Pluto programmer Hugh Redelmeier
- a design document by Hugh and technical lead Henry Spencer.

I am playing catch up. HTML documentation so far is neither complete nor particularly clear, and not all of it has had technical review by the developers, so it may have errors. What I have so far is below.

Note that both software and documentation for this are changing quickly. You may want the latest snapshot for opportunism experiments.

We do not yet recommend this code for production use . You should still protect your critical data with explicitly configured IPSEC tunnels, rather than relying on opportunistic for everything at this stage.

#### ipsec.conf entries for opportunism

The relevant lines in the config file might look like this:

    conn subnet-to-anyone              # for our client subnet
            leftsubnet=10.42.42.0/24   # any single client in our subnet
            left=%defaultroute         # our SG (defaults leftnexthop too)
            right=%opportunistic

The public key, in our format, must be in a KEY record of the appropriate DNS entry for this to work.

Each opportunistic connection supports a single source/destination pair of IP addresses. There is no way to build an opportunistic connection for a larger subnet. Specifying a subnet in the connection description, as in the example above, just means that any host in that subnet may have opportunistic connections.

#### Some DNS background

Opportunism requires that the gateway systems be able to fetch public keys, and other IPSEC-related information, from each other's DNS (domain name service) records.

DNS is a distributed database that maps names to IP addresses and vice versa. A system named gateway.example.com with IP address 10.20.30.40 should have at least two DNS records:

gateway.example.com. IN A 10.20.30.40
  used to look up the name and get an IP address
40.30.20.10.in-addr.arpa. IN PTR gateway.example.com.
  used for reverse lookups, looking up an address to get the associated name. Notice that the digits here are in reverse order; the actual address is 10.20.30.40 but we use 40.30.20.10 here.

Some syntactic details are:

- the IN indicates that these records are for In ternet addresses
- The final periods in '.com.' and '.arpa.' are required. They indicate the root of the domain name system.

For much more detail, see:

- Linux Network Administrator's Guide
- the standard DNS reference book
- BIND overview
- BIND 9 Administrator's Reference

The capitalised strings after IN indicate the type of record. Possible types include:

- Address
- PoinTeR
- Canonical NAME, records to support aliasing, multiple names for one address
- MX, used in mail handling
- SIGnature, used in secure DNS
- KEY, used in secure DNS
- TeXT, a multi-purpose record type

To set up for opportunistic encryption, you add some KEY and TXT records to your DNS data.

#### Putting IPSEC information in DNS

There are two types of DNS record to be added:

- each gateway must have a KEY record which other gateways can query to fetch its RSA authentication key
- any client whose communications are to be protected by a gateway must have a TXT record pointing to that machine as an authorised IPSEC gateway

ipsec_showhostkey(8) provides the key in DNS record format. You will need to put it in the appropriate place in the DNS records.

To be more precise, quoting the Opportunism Design document:

    For reference, the minimum set of DNS records needed to make
    this all work is either:

    1.  TXT in Destination reverse  map,  identifying  Responder
        and providing public key.
    2.  KEY in Initiator reverse map, providing public key.
    3.  TXT  in  Source  reverse  map, verifying relationship to
        Initiator.

    or:

    1.  TXT in Destination reverse map, identifying Responder.
    2.  KEY in Responder reverse map, providing public key.
    3.  KEY in Initiator reverse map, providing public key.
    4.  TXT in Source reverse  map,  verifying  relationship  to
        Initiator.

    Slight  complications  ensue  for dynamic addresses, lack of
    control over reverse maps, etc.

##### DNS records for client systems

You must have control of the reverse maps for your client systems, or opportunistic IPSEC cannot be made to work.

The client systems will be either Source or Destination, so they must have:

    1.  TXT in Destination reverse  map,  identifying  Responder
        and providing public key.
    2.  ...
    3.  TXT  in  Source  reverse  map, verifying relationship to
        Initiator.

    or:

    1.  TXT in Destination reverse map, identifying Responder.
    2.  ...
    3.  ...
    4.  TXT in Source reverse  map,  verifying  relationship  to
        Initiator.

If you control the gateway's reverse map, example client records would look like this:

    42.42.42.10.in-addr.arpa. IN PTR deepthought.example.com.
    42.42.42.10.in-addr.arpa. IN TXT "X-IPsec-Server(10)=10.20.30.40 AQNJjkKlIk9...nYyUkKK8"

which can also be written as just:

    42.42.42.10.in-addr.arpa. IN PTR deepthought.example.com.
                              IN TXT "X-IPsec-Server(10)=10.20.30.40 AQNJjkKlIk9...nYyUkKK8"

This provides the IP address of the security gateway and the public key which the gateway will use to authenticate itself. This is the preferred method.

##### DNS records for gateway systems

The gateways will be either Initiator or Responder so they need:

    1.  ...
    2.  KEY in Initiator reverse map, providing public key.
    3.  ...

    or:

    1.  ...
    2.  KEY in Responder reverse map, providing public key.
    3.  KEY in Initiator reverse map, providing public key.
    4.  ...

If you control the gateway's reverse map, you just add a KEY record there. That is all the gateway reverse map needs, whether it is working as Initiator or Responder.

Here is an example, with many characters of the key itself left out:

    40.30.20.10.in-addr.arpa. IN KEY 0x4200 4 1 AQNJjkKlIk9...nYyUkKK8

This allows lookups on the IP address of the gateway to retrieve the key.

###### If you don't control the gateway's reverse map

The approach must be different if you do not have control over the reverse map for your gateway. Perhaps your ISP controls that, and provides no way for you to put data into their maps. Without that, you cannot set your gateway up to respond to incoming opportunistic requests (short of changing ISPs, which you might consider).

However, suppose a friend over at example.org will let you put things in their maps. That will allow you to set your gateway up to handle opportunistic connections for which it is the initiator.

You still need to be able to put data in the reverse map for your clients. However, that data is slightly different:

    42.42.42.10.in-addr.arpa. IN PTR deepthought.example.com.
                              IN TXT "X-IPsec-Server(10)=something.example.org"

Over at example.org, your friend puts these lines in the DNS data files:

    something.example.org. IN A 10.20.30.40
    something.example.org. IN KEY 0x4200 4 1 AQNJjkKlIk9...nYyUkKK8

Your gateway must identify itself in IKE as something.example.org, not as gateway.example.com. You set that up via leftid= or rightid= entries in ipsec.conf(5).

With this arrangement, the remote gateway receives an ID payload early in IKE with your (bogus) gateway name "something.example.org". Then it looks up that name to get the IP address and key for the gateway.

## Simplifying ipsec.conf files

We provide several features in the syntax of the ipsec.conf(5) file that are intended to simplify the work of managing complex multi-connection setups:

- a conn %default connection description for information common to all connections
- also= lines allow a piece of a description to be defined in one place and used in several (the definition must be after all references)
- include directives allow information to be stored in separate files but used as part of the configuration

These can be combined in whatever way suits your application. One example is this ipsec.conf file for a gateway supporting multiple road warriors, all using RSA authentication:

    conn %default
            type=tunnel
            pfs=yes
            keylife=2h
            authby=rsasig                   # all connections use RSA authentication
            keyingtries=1                   # road warrior can retry, we shouldn't
            # some parameters are common to all remote systems
            right=%any                      # accept from any address

    # pick up all remote system descriptions
    # uses shell wildcards
    include /etc/ipsec/remote.*.conn

    # left side of all connections is the same
    # define it after the descriptions which use it
    conn leftstuff
            left=101.101.101.101
            leftnexthop=101.101.101.1
            leftsubnet=202.202.202.0/24
            leftid=@gateway.example.org

On the left gateway, we can omit leftrsasig. That gateway uses the private key stored in ipsec.secrets(5) and has no need for its own public key. Similarly, the road warriors need not have their own public keys in ipsec.conf(5), only the gateway's public key.

The remote connection descriptions in /etc/ipsec/remote.*.conn need then have only a few lines each:

    conn myname
            # pick up common info for all connections
            also=leftstuff
            # identify the remote machine
            rightid=@myname.example.org
            rightrsasigkey=0xfc641fd6d9a24...
            # we cannot use auto= in default or an also= section
            # so do it here
            auto=add                       # load, but don't start

Note that if auto=add or auto=start parameters are used, they must be in the actual connection descriptions. Neither putting them in the conn default section nor including them via an also= line will work.

Also, be careful with the order of sections in this file. The parser used requires that a definition comes after the also= line which uses it. In our example, the include inserts the files with the also=leftstuff lines before the definition of conn leftstuff so things are parsed in the correct order.

## Is there a firewall in play?

If firewall packet filtering is being done on either of the FreeS/WAN gateway machines, or on any machine on the path between them, then you will probably need to adjust the filters before FreeS/WAN can work. The filters must allow:

- UDP packets between port 500 on one gate and port 500 on the other, used by the automatic keying daemon Pluto.
- at least one of protocol 50 (ESP) and 51 (AH). Most applications want ESP since AH does only authentication, not encryption.

For more detail, see our IPSEC and firewalls document.

## Testing the installation

This section covers testing connections once you have FreeS/WAN installed and your ipsec.conf(5) file set up.

We assume all your connection descriptions use auto=add so that ipsec_pluto(8) loads the descriptions into its internal database at startup but does not attempt to start the connections until you tell it to.

### Matching numbers

It is important that the numbers in your connection descriptions match the network configuration. FreeS/WAN is almost certain to fail if they do not.

Suppose you are at the Reno office and your ipsec.conf file now has, among others, these lines:

    config setup
            interfaces="ipsec0=eth0"

    conn reno-van
            left=101.101.101.101
            right=202.202.202.202

When you tell FreeS/WAN to start the reno-van connection, it doesn't automagically know that it is in Reno, or that it is left in the configuration. It discovers that by comparing the IP address for ipsec0 (and, if it is set, for ipsec1) to the addresses for left and right. ipsec0 inherits its address from the underlying device, eth0 in our example.

So in our example, if eth0 has IP address 101.101.101.101 then ipsec0 inherits that address, the correct match is found, and this FreeS/WAN discovers that it is left. (If no match is found, Pluto reports "unable to orient connection".) It then sets itself up with any other left* parameters in use -- some of leftnexthop, leftsubnet, leftfirewall and leftid.

Once it has these parameters, FreeS/WAN sets things so that

- packets from leftsubnet addressed to rightsubnet are routed through a tunnel to right.
- Packets for leftsubnet can be received on the tunnel and delivered.

All should be well.

Of course, there must also be interfaces and routes set up so that this machine can exchange IP packets both with the right gateway and with clients on leftsubnet. This is done with standard Linux utilities such as ifconfig(8) and route(8). Also, things must be correct on right in Vancouver. It takes two to tunnel.

A data mismatch anywhere in this configuration will cause FreeS/WAN to fail and to log various error messages. Depending on just how confused FreeS/WAN is and about what, the error messages may be somewhat confusing. See our troubleshooting section to get help interpreting them if required.

We recommend double-checking for consistency here before starting actual tests..

### Sanity checking

Reboot both gateways to get FreeS/WAN started. No connections are actually made yet, but the stage is set.

Examine /var/log/messages for any signs of trouble.

On both gateways, the following entries should now exist in the /proc/net/ directory:

- ipsec_eroute
- ipsec_spi
- ipsec_spigrp
- ipsec_spinew
- ipsec_tncfg
- ipsec_version

and the IPSEC interfaces should be attached on top of the specified physical interfaces. Confirm that with:

            cat /proc/net/ipsec_tncfg

You should see at least device ipsec0, and each ipsec device should point to a physical device, eg. 'ipsec0 -> eth0 mtu=16260 -> 1500'. Routing connections through this pseudo-device with our eroute(8) utility causes the data to be encrypted before being delivered to the underlying network interface.

Don't be surprised when you cannot find that /dev/ipsec0 or /dev/ipsec1. They do not exist. Other network pseudo-devices such as eth0 and eth1 do not have entries in /dev either. In general, network devices do not need such entries.

### Starting a connection

On one gateway, start IPSEC with:

            ipsec auto --up name

replacing name with the connection name you used in ipsec.conf(5).

Note that to shut down a connection, you must do:

            ipsec auto --down name

on both gateway machines, even though you only start it from one.

If the ipsec auto --up command doesn't generate any errors, do

            ipsec look

and see if the output looks something like this:

    foo.spsystems.net Wed Nov 25 22:51:45 EST 1998
    -------------------------
    10.0.1.0/24 -> 11.0.1.0/24 => tun0x200@11.0.0.1 esp0x202@11.0.0.1
    -------------------------
    tun0x200@11.0.0.1 IPv4_Encapsulation: dir=out   10.0.0.1 -> 11.0.0.1
    esp0x203@10.0.0.1 3DES-MD5-96_Encryption: dir=in  iv=0xc2cbca5ba42ffbb6  seq=0  bit=0x00000000  win=0  flags=0x0<>
    esp0x202@11.0.0.1 3DES-MD5-96_Encryption: dir=out  iv=0xc2cbca5ba42ffbb6  seq=0  bit=0x00000000  win=0  flags=0x0<>
    Destination     Gateway         Genmask         Flags   MSS Window  irtt Iface
    11.0.0.0        0.0.0.0         255.255.255.0   U      1500 0          0 eth1
    11.0.1.0        11.0.0.1        255.255.255.0   UG     1404 0          0 ipsec0

If it does, you're probably in business.

This example shows:

            a tunnel              tun0x200 going to 11.0.0.1
            outgoing connection   esp0x202
            incoming connection   esp0x203

Both connections use ESP with 3DES encryption and MD5 authentication.

The routing is:

            11.0.0.0    via eth1 and the Internet
            11.0.1.0    via ipsec0 which encrypts and then sends to 11.0.0.1

This routes all traffic to the protected network 11.0.1.0/24 through an IPSEC tunnel to the gateway 11.0.0.1.

### Ping tests

If that works, test whether Sunrise can ping Sunset and vice versa. Our example setup again is:

            Sunset==========West------------------East=========Sunrise
                  local net       untrusted net       local net

There is no point in testing to or from the gateways themselves; the goal is to secure traffic between the subnets, not between the security gateways themselves.

In general, pings or other tests using the public interfaces of East and/or West are entirely useless. The IPSEC tunnel is for packets between the two protected subnets and the outside interfaces are not on those subnets. Depending on your routing configuration, test packets sent via those interfaces will be:

- either transmitted in the clear, bypassing the tunnel,
- or discarded because there is no tunnel in place to handle them

In either case, they tell you nothing about the tunnel .

Sometimes it will be inconvenient to use the client machines (Sunrise and Sunset in our example) for testing. In these cases, use a command such as:

         traceroute -i eth0 -f 20 192.168.7.1

where each of the interfaces specified (eth0 and 192.168.7.1 in the example) are on one of the protected subnets, eth0 being the local gateway's interface on that side and 192.168.7.1 the remote gateway's subnet interface. This forces the packets through the IPSEC tunnel you want to test.

For information on setting things up so that gateways can do IPSEC to each other or to remote subnets, see below .

If you have other software set up, test with it as well. Telnet from Sunrise to Sunset, browse a web server on the remote net and so on.

### Testing with tcpdump

To verify that all is working, run tcpdump(8) on a machine which can listen to the traffic between the gateways.

This is most easily done from a third machine, rather than from one of the gateways. On the gateways you may see packets at intermediate stages of processing and the result may be confusing.

If the results make no sense at all, or you see "bad physical medium" error messages, you probably have an outdated version of tcpdump(8) that does not handle IPSEC at all. See our FAQ.

The packets should, except for some of the header information, be utterly unintelligible. The output of good encryption looks exactly like random noise.

You can put recognizable data in the ping packets with something like:

            ping -p feedfacedeadbeef 11.0.1.1

"feedfacedeadbeef" is a legal hexadecimal pattern that is easy to pick out of hex dumps.

For many other protocols, you need to check if you have encrypted data or ASCII text. Encrypted data has approximately equal frequencies for all 256 possible characters. ASCII text has most characters in the printable range 0x20-0x7f, a few control characters less than 0x20, and none at all in the range 0x80-0xff.

0x20, space, is a good character to look for. In normal English text space occurs about once in seven characters, versus about once in 256 for random or encrypted data. You can put long sequences of spaces in your data and look for 0x20202020 in output, but this is not usually necessary.

If packets look like total garbage, nothing recognizable, all is well.

Note that to shut down a connection, you must do:

            ipsec auto --down name

on both gateway machines, even though you only start it from one.

Again, you can verify with the same commands.

Repeat the ping test. Repeat the tcpdump test.

If everything succeeds, congratulations.

You now have a working Linux FreeS/WAN installation.

## What next?

At this point you should have a working FreeS/WAN setup. If not, you could go back and doublecheck various things above or try:

- our FAQ
- our troubleshooting section

If all is well so far, you could continue with this section to explore other ways to configure FreeS/WAN connections or branch out to:

- more detail on the IPSEC protocols
- interoperating with other IPSEC implementations
- history and politics of cryptography
- additional configuration examples

Of course you might just go off for a beverage or meal at this point as well.

## Other configuration possibilities

The rest of this section describes various less-used options for FreeS/WAN.

### Choosing connection types

The first major decision you need to make before configuring additional connections is what type or types of connections you will use. There are several options, and you can use more than one concurrently.

#### Manual vs. automatic keying

IPSEC allows two types of connections, with manual or automatic keying. FreeS/WAN starts them with commands such as:

            ipsec manual --start name
            ipsec auto --up name

The difference is in how they are keyed.

Manually keyed connections
  use keys stored in ipsec.conf .
Automatically keyed connections
  use keys automatically generated by the Pluto key negotiation daemon. The key negotiation protocol, IKE, must authenticate the other system. (It is vulnerable to a man-in-the-middle attack if used without authentication.) We currently support two authentication methods:
  - using shared secrets stored in ipsec.secrets.
  - RSA public key authentication, with public keys for other machines in ipsec.conf and our machine's private key in ipsec.secrets.

Manually keyed connections provide weaker security than automatically keyed connections. An opponent who gets a key gets all data encrypted by it. We discuss using manual keying in production below, but this is not recommended except in special circumstances, such as needing to communicate with some implementation that offers no auto-keyed mode compatible with FreeS/WAN. Manual keying is useful for testing.

With automatically-(re)-keyed connections, the keys change often so an opponent who gets one key does not get a large amount of data. An opponent who gets a shared secret, or your private key if public key authentication is used, does not automatically gain access to any encryption keys or any data. Once your authentication mechanism has been subverted you have no way to prevent the attacker getting keys and data, but the attacker still has to work for them.

#### Authentication methods for auto-keying

The IKE protocol which Pluto uses to negotiate connections between gateways must use some form of authentication of peers. A gateway must know who it is talking to before it can create a secure connection. We currently support two methods for this authentication:

- shared secrets
- RSA authentication

See our links section for information on user-contributed patches which provide a third mechanism:

- authentication with x.509 certificates

As a long-term goal, FreeS/WAN plans to support distribution of public keys for authentication via secure DNS. This would allow us to support opportunistic encryption . Any two FreeS/WAN gateways could provide secure communication, without either of them having any preset information about the other.

This is not implemented in this release.

#### Advantages of public key methods

Authentication with a public key method such as RSA has some important advantages over using shared secrets.

- no problem of secure transmission of secrets
  - A shared secret must be shared, so you have the problem of transmitting it securely to the other party. If you get this wrong, you have no security.
  - With a public key technique, you transmit only your public key. The system is designed to ensure that it does not matter if an enemy obtains public keys. The private key never leaves your machine.
- easier management
  - Suppose you have 20 branch offices all connecting to one gateway at head office, and all using shared secrets. Then the head office admin has 20 secrets to manage. Each of them must be kept secret not only from outsiders, but also from 19 of the branch office admins. The branch office admins have only one secret each to manage.

  If the branch offices need to talk to each other, this becomes problematic. You need another 20*19/2 = 190 secrets for branch-to-branch communication, each known to exactly two branches. Now all the branch admins have the headache of handling 20 keys, each shared with exactly one other branch or with head office.

  For larger numbers of branches, the number of connections and secrets increases quadratically and managing them becomes a nightmare. A 1000-gateway fully connected network needs 499,500 secrets, each known to exactly two players. There are ways to reduce this problem, for example by introducing a central key server, but these involve additional communication overheads, more administrative work, and new threats that must be carefully guarded against.

- With public key techniques, the only thing you have to keep secret is your private key, and you keep that secret from everyone.

As network size increaes, the number of public keys used increases linearly with the number of nodes. This still requires careful administration in large applications, but is nothing like the disaster of a quadratic increase. On a 1000-gateway network, you have 1000 private keys, each of which must be kept secure on one machine, and 1000 public keys which must be distributed. This is not a trivial problem, but it is manageable.

- does not require fixed IP addresses
  - When shared secrets are used in IPSEC, the responder must be able to tell which secret to use by looking at the IP address on the incoming packets. When the other parties do not have a fixed IP address to be identified by (for example, on nearly all dialup ISP connections and many cable or ADSL links), this does not work well -- all must share the same secret!
  - When RSA authentication is in use, the initiator can identify itself by name before the key must be determined. The responder then checks that the message is signed with the public key corresponding to that name.

There is also a disadvantage:

- your private key is a single point of attack, extremely valuable to an enemy
  - with shared secrets, an attacker who steals your ipsec.secrets file can impersonate you or try man-in-the-middle attacks, but can only attack connections described in that file
  - an attacker who steals your private key gains the chance to attack not only existing connections but also any future connections created using that key

This is partly counterbalanced by the fact that the key is never transmitted and remains under your control at all times. It is likely necessary, however, to take account of this in setting security policy. For example, you should change gateway keys when an administrator leaves the company, and should change them periodically in any case.

Overall, public key methods are more secure, more easily managed and more flexible. We recommend that they be used for all connections, unless there is a compelling reason to do otherwise.

### Using shared secrets in production

Generally, public key methods are preferred for reasons given above, but shared secrets can be used with no loss of security, just more work and perhaps more need to take precautions.

#### Putting secrets in ipsec.secrets(5)

If shared secrets are to be used to authenticate communication for the Diffie-Hellman key exchange in the IKE protocol, then those secrets must be stored in /etc/ipsec.secrets. For details, see the ipsec.secrets(5) man page.

A few considerations are vital:

- make the secrets long and unguessable. Since they need not be remembered by humans, very long ugly strings may be used. We suggest using our ipsec_ranbits(8) utility to generate long (128 bits or more) random strings.
- transmit secrets securely. You have to share them with other systems, but you lose if they are intercepted and used against you. Use PGP, SSH, hand delivery of a floppy disk which is then destroyed, or some other trustworthy method to deliver them.
- store secrets securely, in root-owned files with permissions rw------.
- limit sharing of secrets. Alice, Bob, Carol and Dave may all talk to each other, but only Alice and Bob should know the secret for an Alice-Bob link.
- do not share private keys. The private key for RSA authentication of your system is stored in ipsec.secrets(5), but it is a different class of secret from the pre-shared keys used for the "shared secret" authentication. No-one but you should have the RSA private key.

Each line has the IP addresses of the two gateways plus the secret. It should look something like this:

            10.0.0.1 11.0.0.1 : PSK "jxTR1lnmSjuj33n4W51uW3kTR55luUmSmnlRUuWnkjRj3UuTV4T3USSu23Uk55nWu5TkTUnjT"

PSK indicates the use of a pre-s hared key. The quotes and the whitespace shown are required.

You can use any character string as your secret. For security, it should be both long and extremely hard to guess. We provide a utility to generate such strings, ipsec_ranbits(8).

You want the same secret on the two gateways used, so you create a line with that secret and the two gateway IP addresses. The installation process supplies an example secret, useful only for testing. You must change it for production use.

#### File security

You must deliver this file, or the relevant part of it, to the other gateway machine by some secure means. Don't just FTP or mail the file! It is vital that the secrets in it remain secret. An attacker who knew those could easily have all the data on your "secure" connection.

This file must be owned by root and should have permissions rw-------.

#### Shared secrets for road warriors

You can use a shared secret to support a single road warrior connecting to your gateway, and this is a reasonable thing to do in some circumstances. Public key methods have advantages, discussed above, but they are not critical in this case.

To do this, the line in ipsec.secrets(5) is something like:

            10.0.0.1 0.0.0.0 : PSK "jxTR1lnmSjuj33n4W51uW3kTR55luUmSmnlRUuWnkjRj3UuTV4T3USSu23Uk55nWu5TkTUnjT"

where the 0.0.0.0 means that any IP address is acceptable.

For more than one road warrior, shared secrets are not recommended. If shared secrets are used, then when the responder needs to look up the secret, all it knows about the sender is an IP address. This is fine if the sender is at a fixed IP address specified in the config file. It is also fine if only one road warrior uses the wildcard 0.0.0.0 address. However, if you have more than one road warrior using shared secret authentication, then they must all use that wildcard and therefore all road warriors using PSK autentication must use the same secret. Obviously, this is insecure.

For multiple road warriors, use public key authentication. Each roadwarrior can then have its own identity (our leftid= or rightid= parameters), its own public/private key pair, and its own secure connection.

### Using manual keying in production

Generally, automatic keying is preferred over manual keying for production use because it is both easier to manage and more secure. Automatic keying frees the admin from much of the burden of managing keys securely, and can provide perfect forward secrecy.

However, it is possible to use manual keying in production if that is what you want to do. This might be necessary, for example, in order to interoperate with some device that either does not provide automatic keying or provides it in some version we cannot talk to.

Note that with manual keying all security rests with the keys. If an adversary acquires your keys, you've had it. He or she can read everything ever sent with those keys, including old messages he or she may have archived. You need to be really paranoid about keys if you're going to rely on manual keying for anything important.

- keep keys in files with 600 permissions, owned by root
- be extremely careful about security of your gateway systems. Anyone who breaks into a gateway and gains root privileges can get all your keys and read everything ever encrypted with those keys, both old messages he has archived and any new ones you may send.
- change keys regularly. This can be a considerable bother, (and provides an excellent reason to consider automatic keying instead), but it is absolutely essential for security. Consider a manually keyed system in which you leave the same key in place for months:
  - an attacker can have a very large sample of text sent with that key to work with. This makes various cryptographic attacks much more likely to succeed.
  - The chances of the key being compromised in some non-cryptographic manner -- a spy finds it on a discarded notepad, someone breaks into your server or your building and steals it, a staff member is bribed, tricked, seduced or coerced into revealing it, etc. -- also increase over time.
  - a successful attacker can read everything ever sent with that key. This makes any successful attack extremely damaging.
  It is clear that you must change keys often to have any useful security. The only question is how often.
- use PGP or SSH for all key transfers
- don't edit files with keys in them when someone can look over your shoulder
- worry about network security; could someone get keys by snooping packets on the LAN between your X desktop and the gateway?
- lock up your backup tapes for the gateway system
- ... and so on

Linux FreeS/WAN provides some facilities to help with this. In particular, it is good policy to keep keys in separate files so you can edit configuration information in /etc/ipsec.conf without exposing keys to "shoulder surfers" or network snoops. We support this with the also= and include syntax in ipsec.conf(5).

See the last example in our examples file. In the /etc/ipsec.conf conn samplesep section, it has the line:

            also=samplesep-keys

which tells the "ipsec manual" script to insert the configuration description labelled "samplesep-keys" if it can find it. The /etc/ipsec.conf file must also have a line such as:

    include ipsec.*.conf

which tells it to read other files. One of those other files then might contain the additional data:

    conn samplesep-keys
      spi=0x200
      esp=3des-md5-96
      espenckey=0x01234567_89abcdef_02468ace_13579bdf_12345678_9abcdef0
      espauthkey=0x12345678_9abcdef0_2468ace0_13579bdf

The first line matches the label in the "also=" line, so the indented lines are inserted. The net effect is exactly as if the inserted lines had occurred in the original file in place of the "also=" line.

Variables set here are:

spi
  A number needed by the manual keying code. Any 3-digit hex number will do, but if you have more than one manual connection then spi must be different for each connection.
esp
  Options for ESP (Encapsulated Security Payload), the usual IPSEC encryption mode. Settings here are for encryption using triple DES and authentication using MD5. Note that encryption without authentication should not be used; it is insecure.
espenkey
  Key for ESP encryption. Here, a 192-bit hex number for triple DES.
espauthkey
  Key for ESP authentication. Here, a 128-bit hex number for MD5.

Note that the example keys we supply are intended only for testing. For real use, you should go to automatic keying. If that is not possible, create your own keys for manual mode and keep them secret

Of course, any files containing keys must have 600 permissions and be owned by root.

If you connect in this way to multiple sites, we recommend that you keep keys for each site in a separate file and adopt some naming convention that lets you pick them all up with a single "include" line. This minimizes the risk of losing several keys to one error or attack and of accidentally giving another site admin keys which he or she has no business knowing.

Also note that if you have multiple manually keyed connections on a single machine, then the spi parameter must be different for each one. Any 3-digit hex number is OK, provided they are different for each connection. We reserve the range 0x100 to 0xfff for manual connections. Pluto assigns SPIs from 0x1000 up for automatically keyed connections.

If ipsec.conf(5) contains keys for manual mode connections, then it too must have permissions rw-------. We recommend instead that, if you must manual keying in production, you keep the keys in separate files.

Note also that ipsec.conf is installed with permissions rw-r--r--. If you plan to use manually keyed connections for anything more than initial testing, you must:

- either change permissions to rw-------
- or store keys separately in secure files and access them via include statements in ipsec.conf .

We recommend the latter method for all but the simplest configurations.

#### Creating keys with ranbits

You can create new random keys with the ranbits(8) utility. For example, the commands:

          umask 177
          ipsec ranbits 192  > temp
          ipsec ranbits 128 >> temp

create keys in the sizes needed for our default algorithms:

- 192-bit key for 3DES encryption
  (only 168 bits are used; parity bits are ignored)
- 128-bit key for keyed MD5 authentication

If you want to use SHA instead of MD5, that requires a 160-bit key

Note that any temporary files used must be kept secure since they contain keys. That is the reason for the umask command above. The temporary file should be deleted as soon as you are done with it. You may also want to change the umask back to its default value after you are finished working on keys.

The ranbits utility may pause for a few seconds if not enough entropy is available immediately. See ipsec_ranbits(8) and random(4) for details. You may wish to provide some activity to feed entropy into the system. For example, you might move the mouse around, type random characters, or do du /usr > /dev/null in the background.

### Setting up connections at boot time

You can tell the system to set up connections automatically at boot time by putting suitable stuff in /etc/ipsec.conf on both systems. The relevant section of the file is labelled by a line reading config setup.

Details can be found in the ipsec.conf(5) man page. We also provide a file of example configurations.

The most likely options are something like:

interfaces="ipsec0=eth0 ipsec1=ppp0"
  Tells KLIPS which interfaces to use. Up to four interfaces numbered ipsec[0-3] are supported. Each interface can support an arbitrary number of tunnels.

Note that for PPP, you give the ppp[0-9] device name here, not the underlying device such as modem (or eth1 if you are using PPPoE).

interfaces=%defaultroute
  Alternative setting, useful in simple cases. KLIPS will pick up both its interface and the next hop information from the settings of the Linux default route.
forwardcontrol=no
  Normally "no". Set to "yes" if the IP forwarding option is disabled in your network configuration. (This can be set as a kernel configuration option or later. e.g. on Redhat, it's in /etc/sysconfig/network and on SuSE you can adjust it with Yast.) Linux FreeS/WAN will then enable forwarding when starting up and turn it off when going down. This is used to ensure that no packets will be forwarded before IPSEC comes up and takes control.
syslog=daemon.error
  Used in messages to the system logging daemon (syslogd) to specify what type of software is sending the messages. If the settings are "daemon.error" as in our example, then syslogd treats the messages as error messages from a daemon.

Note that Pluto does not currently pay attention to this variable. The variable controls setup messages only.

klipsdebug=
  Debug settings for KLIPS.
plutodebug=
  Debug settings for Pluto.
... for both the above DEBUG settings
  Normally, leave empty as shown above for no debugging output.
  Use "all" for maximum information.
  See ipsec_klipsdebug(8) and ipsec_pluto(8) man page for other options. Beware that if you set /etc/ipsec.conf to enable debug output, your system's log files may get large quickly.
dumpdir=/safe/directory
  Normally, programs started by ipsec setup don't crash. If they do, by default, no core dump will be produced because such dumps would contain secrets. If you find you need to debug such crashes, you can set dumpdir to the name of a directory in which to collect the core file.
manualstart=
  List of manually keyed connections to be automatically started at boot time. Useful for testing, but not for long term use. Connections which are automatically started should also be automatically re-keyed.
pluto=yes
  Whether to start Pluto when ipsec startup is done.
  This parameter is optional and defaults to "yes" if not present.

"yes" is strongly recommended for production use so that the keying daemon (Pluto) will automatically re-key the connections regularly. The ipsec-auto parameters ikelifetime, ipseclifetime and reykeywindow give you control over frequency of rekeying.

plutoload="reno-van reno-adam reno-nyc"
  List of tunnels (by name, e.g. fred-susan or reno-van in our examples) to be loaded into Pluto's internal database at startup. In this example, Pluto loads three tunnels into its database when it is started.

If plutoload is "%search", Pluto will load any connections whose description includes "auto=add" or "auto=start".

plutostart="reno-van reno-adam reno-nyc"
  List of tunnels to attempt to negotiate when Pluto is started.

If plutostart is "%search", Pluto will start any connections whose description includes "auto=start".

Note that, for a connection intended to be permanent, both gateways should be set try to start the tunnel. This allows quick recovery if either gateway is rebooted or has its IPSEC restarted. If only one gateway is set to start the tunnel and the other gateway restarts, the tunnel may not be rebuilt.

plutowait=no
  Controls whether Pluto waits for one tunnel to be established before starting to negotiate the next. You might set this to "yes"
  - if your gateway is a very limited machine and you need to conserve resources.
  - for debugging; the logs are clearer if only one connection is brought up at a time
  For a busy and resource-laden production gateway, you likely want "no" so that connections are brought up in parallel and the whole process takes less time.

The example assumes you are at the Reno office and will use IPSEC to Vancouver, New York City and Amsterdam.

### Multiple tunnels between the same two gateways

Consider a pair of subnets, each with a security gateway, connected via the Internet:

             192.168.100.0/24           left subnet
                  |
             192.168.100.1
             North Gateway
             101.101.101.101            left
                  |
             101.101.101.1              left next hop
             [Internet]
             202.202.202.1              right next hop
                  |
             202.202.202.202            right
             South gateway
             192.168.200.1
                  |
             192.168.200.0/24           right subnet

A tunnel specification such as:

    conn northnet-southnet
          left=101.101.101.101
          leftnexthop=101.101.101.1
          leftsubnet=192.168.100.0/24
          leftfirewall=yes
          right=202.202.202.202
          rightnexthop=202.202.202.1
          rightsubnet=192.168.200.0/24
          rightfirewall=yes

will allow machines on the two subnets to talk to each other. You might test this by pinging from polarbear (192.168.100.7) to penguin (192.168.200.5).

However, this does not cover other traffic you might want to secure. To handle all the possibilities, you might also want these connection descriptions:

    conn northgate-southnet
          left=101.101.101.101
          leftnexthop=101.101.101.1
          right=202.202.202.202
          rightnexthop=202.202.202.1
          rightsubnet=192.168.200.0/24
          rightfirewall=yes

    conn northnet-southgate
          left=101.101.101.101
          leftnexthop=101.101.101.1
          leftsubnet=192.168.100.0/24
          leftfirewall=yes
          right=202.202.202.202
          rightnexthop=202.202.202.1

Without these, neither gateway can do IPSEC to the remote subnet. There is no IPSEC tunnel or eroute set up for the traffic.

In our example, with the non-routable 192.168.* addresses used, packets would simply be discarded. In a different configuration, with routable addresses for the remote subnet, they would be sent unencrypted since there would be no IPSEC eroute and there would be a normal IP route.

You might also want:

    conn northgate-southgate
          left=101.101.101.101
          leftnexthop=101.101.101.1
          right=202.202.202.202
          rightnexthop=202.202.202.1

This is required if you want the two gateways to speak IPSEC to each other.

This requires a lot of duplication of details. Judicious use of also= and include can reduce this problem.

Note that, while FreeS/WAN supports all four tunnel types, not all implementations do. In particular, some versions of Windows 2000 and the freely downloadable version of PGP provide only "client" functionality. You cannot use them as gateways with a subnet behind them. To get that functionality, you must upgrade to Windows 2000 server or the commercially available PGP products.

#### One tunnel plus advanced routing

It is also possible to use the new routing features in 2.2 and later kernels to avoid most needs for multple tunnels. Here is one mailing list message on the topic:

    Subject: Re: linux-ipsec: IPSec packets not entering tunnel?
       Date: Mon, 20 Nov 2000
       From: Justin Guyett <jfg@sonicity.com>

    On Mon, 20 Nov 2000, Claudia Schmeing wrote:

    > Right                                                         Left
    >                      "home"                "office"
    > 10.92.10.0/24 ---- 24.93.85.110 ========= 216.175.164.91 ---- 10.91.10.24/24
    >
    > I've created all four tunnels, and can ping to test each of them,
    > *except* homegate-officenet.

    I keep wondering why people create all four tunnels.  Why not route
    traffic generated from home to 10.91.10.24/24 out ipsec0 with iproute2?
    And 99% of the time you don't need to access "office" directly, which
    means you can eliminate all but the subnet<->subnet connection.

and FreeS/WAN technical lead Henry Spencer's comment:

    > I keep wondering why people create all four tunnels.  Why not route
    > traffic generated from home to 10.91.10.24/24 out ipsec0 with iproute2?

    This is feasible, given some iproute2 attention to source addresses, but
    it isn't something we've documented yet... (partly because we're still
    making some attempt to support 2.0.xx kernels, which can't do this, but
    mostly because we haven't caught up with it yet).

    > And 99% of the time you don't need to access "office" directly, which
    > means you can eliminate all but the subnet<->subnet connection.

    Correct in principle, but people will keep trying to ping to or from the
    gateways during testing, and sometimes they want to run services on the
    gateway machines too.

### Many tunnels from a single gateway

FreeS/WAN allows a single gateway machine to build tunnels to many others. There may, however, be some problems for large numbers as indicated in this message from the mailing list:

    Subject: Re: Maximum number of ipsec tunnels?
       Date: Tue, 18 Apr 2000
       From: "John S. Denker" <jsd@research.att.com>

    Christopher Ferris wrote:

    >> What are the maximum number ipsec tunnels FreeS/WAN can handle??

    Henry Spencer wrote:

    >There is no particular limit.  Some of the setup procedures currently
    >scale poorly to large numbers of connections, but there are (clumsy)
    >workarounds for that now, and proper fixes are coming.

    1) "Large" numbers means anything over 50 or so.  I routinely run boxes
    with about 200 tunnels.  Once you get more than 50 or so, you need to worry
    about several scalability issues:

    a) You need to put a "-" sign in syslogd.conf, and rotate the logs daily
    not weekly.

    b) Processor load per tunnel is small unless the tunnel is not up, in which
    case a new half-key gets generated every 90 seconds, which can add up if
    you've got a lot of down tunnels.

    c) There's other bits of lore you need when running a large number of
    tunnels.  For instance, systematically keeping the .conf file free of
    conflicts requires tools that aren't shipped with the standard freeswan
    package.

    d) The pluto startup behavior is quadratic.  With 200 tunnels, this eats up
    several minutes at every restart.   I'm told fixes are coming soon.

    2) Other than item (1b), the CPU load depends mainly on the size of the
    pipe attached, not on the number of tunnels.

It is worth noting that item (1b) applies only to repeated attempts to re-key a data connection (IPSEC SA, Phase 2) over an established keying connection (ISAKMP SA, Phase 1). There are two ways to reduce this overhead using settings in ipsec.conf(5):

- set keyingtries to some small value to limit repetitions
- set keylife to a short time so that a failing data connection will be cleaned up when the keying connection is reset.

The overheads for establishing keying connections (ISAKMP SAs, Phase 1) are lower because for these Pluto does not perform expensive operations before receiving a reply from the peer.

### Extruded Subnets

What we call extruded subnets are a special case of VPNs.

If your buddy has some unused IP addresses, in his subnet far off at the other side of the Internet, he can loan them to you... provided that the connection between you and him is fast enough to carry all the traffic between your machines and the rest of the Internet. In effect, he "extrudes" a part of his address space over the network to you, with your Internet traffic appearing to originate from behind his Internet gateway.

Suppose your friend has a.b.c.0/24 and wants to give you a.b.c.240/28. The initial situation is:

        subnet           gateway          Internet
      a.b.c.0/24    a.b.c.1    p.q.r.s

where anything from the Internet destined for any machine in a.b.c.0/24 is routed via p.q.r.s and that gateway knows what to do from there.

Of course it is quite normal for various smaller subnets to exist behind your friend's gateway. For example, your friend's company might have a.b.c.16/28=development, a.b.c.32/28=marketing and so on. The Internet neither knows not cares about this; it just delivers packets to the p.q.r.s and lets the gateway do whatever needs to be done from there.

What we want to do is take a subnet, perhaps a.b.c.240/28, out of your friend's physical location while still having your friend's gateway route to it. As far as the Internet is concerned, you remain behind that gateway.

        subnet           gateway          Internet       your gate  extruded

      a.b.c.0/24   a.b.c.1     p.q.r.s              d.e.f.g         a.b.c.240/28

                               ========== tunnel ==========

The extruded addresses have to be a complete subnet.

In our example, the friend's security gateway is also his Internet gateway, but this is not necessary. As long as all traffic from the Internet to his addresses passes through the Internet gate, the security gate could be a machine behind that. The IG would need to route all traffic for the extruded subnet to the SG, and the SG could handle the rest.

First, configure your subnet using the extruded addresses. Your security gateway's interface to your subnet needs to have an extruded address (possibly using a Linux virtual interface , if it also has to have a different address). Your gateway needs to have a route to the extruded subnet, pointing to that interface. The other machines at your site need to have addresses in that subnet, and default routes pointing to your gateway.

If any of your friend's machines need to talk to the extruded subnet, they need to have a route for the extruded subnet, pointing at his gateway.

Then set up an IPSEC subnet-to-subnet tunnel between your gateway and his, with your subnet specified as the extruded subnet, and his subnet specified as "0.0.0.0/0". Do it with manual keying first for testing, and then with automatic keying for production use.

The tunnel description should be:

    conn extruded
            left=p.q.r.s
            leftsubnet=0.0.0.0/0
            right=d.e.f.g
            rightsubnet=a.b.c.0/28

If either side was doing firewalling for the extruded subnet before the IPSEC connection is set up, ipsec_manual and ipsec_auto need to know about that (via the {left|right}firewall parameters) so that it can be overridden for the duration of the connection.

And it all just works. Your SG routes traffic for 0.0.0.0/0 -- that is, the whole Internet -- through the tunnel to his SG, which then sends it onward as if it came from his subnet. When traffic for the extruded subnet arrives at his SG, it gets sent through the tunnel to your SG, which passes it to the right machine.

Remember that when ipsec_manual or ipsec_auto takes a connection down, it does not undo the route it made for that connection. This lets you take a connection down and bring up a new one, or a modified version of the old one, without having to rebuild the route it uses and without any risk of packets which should use IPSEC accidentally going out in the clear. Because the route always points into KLIPS, the packets will always go there. Because KLIPS temporarily has no idea what to do with them (no eroute for them), they will be discarded.

If you do want to take the route down, this is what the "unroute" operation in manual and auto is for. Just do an unroute after doing the down.

Note that the route for a connection may have replaced an existing non-IPSEC route. Nothing in Linux FreeS/WAN will put that pre-IPSEC route back. If you need it back, you have to create it with the route command.

### Road Warrior with virtual IP address

Here is a mailing list message about another way to configure for road warrior support:

    Subject: Re: linux-ipsec: understanding the vpn
       Date: Thu, 28 Oct 1999 10:43:22 -0400
       From: Irving Reid <irving@nevex.com>

    >  local-------linux------internet------mobile
    >  LAN        box                         user
    >  ...

    >  now when the mobile user connects to the linux box
    >  it is given a virtual IP address, i have configured it to
    >  be in the 10.x.x.x range. mobile user and linux box
    >  have a tunnel between them with these IP addresses.

    >   Uptil this all is fine.

    If it is possible to configure your mobile client software *not* to
    use a virtual IP address, that will make your life easier. It is easier
    to configure FreeS/WAN to use the actual address the mobile user gets
    from its ISP.

    Unfortunately, some Windows clients don't let you choose.

    >  what i would like to know is that how does the mobile
    >  user communicate with other computers on the local
    >  LAN , of course with the vpn ?

    >   what IP address should the local LAN
    >  computers have ? I guess their default gateway
    >  should be the linux box ? and does the linux box need
    >  to be a 2 NIC card box or one is fine.

    As someone else stated, yes, the Linux box would usually be the default
    IP gateway for the local lan.

    However...

    If you mobile user has software that *must* use a virtual IP address,
    the whole picture changes. Nobody has put much effort into getting
    FreeS/WAN to play well in this environment, but here's a sketch of one
    approach:

    Local Lan 1.0.0.0/24
        |
        +- Linux FreeS/WAN 1.0.0.2
        |
        | 1.0.0.1
     Router
        | 2.0.0.1
        |
    Internet
        |
        | 3.0.0.1
    Mobile User
          Virtual Address: 1.0.0.3

    Note that the Local Lan network (1.0.0.x) can be registered, routable
    addresses.

    Now, the Mobile User sets up an IPSec security association with the
    Linux box (1.0.0.2); it should ESP encapsulate all traffic to the
    network 1.0.0.x **EXCEPT** UDP port 500. 500/udp is required for the key
    negotiation, which needs to work outside of the IPSec tunnel.

    On the Linux side, there's a bunch of stuff you need to do by hand (for
    now). FreeS/WAN should correctly handle setting up the IPSec SA and
    routes, but I haven't tested it so this may not work...

    The FreeS/WAN conn should look like:

    conn mobile
            right=1.0.0.2
            rightsubnet=1.0.0.0/24
            rightnexthop=1.0.0.1
            left=0.0.0.0  # The infamous "road warrior"
            leftsubnet=1.0.0.3/32

    Note that the left subnet contains *only* the remote host's virtual
    address.

    Hopefully the routing table on the FreeS/WAN box ends up looking like
    this:

    % netstat -rn
    Kernel IP routing table
    Destination     Gateway      Genmask         Flags   MSS Window  irtt Iface
    1.0.0.0         0.0.0.0      255.255.255.0   U      1500 0          0 eth0
    127.0.0.0       0.0.0.0      255.0.0.0       U      3584 0          0 lo
    0.0.0.0         1.0.0.1      0.0.0.0         UG     1500 0          0 eth0
    1.0.0.3         1.0.0.1      255.255.255.255 UG     1433 0          0 ipsec0

    So, if anybody sends a packet for 1.0.0.3 to the Linux box, it should
    get bundled up and sent through the tunnel. To get the packets for
    1.0.0.3 to the Linux box in the first place, you need to use "proxy
    ARP".

    How this works is: when a host or router on the local Ethernet segment
    wants to send a packet to 1.0.0.3, it sends out an Ethernet level
    broadcast "ARP request". If 1.0.0.3 was on the local LAN, it would
    reply, saying "send IP packets for 1.0.0.3 to my Ethernet address".

    Instead, you need to set up the Linux box so that _it_ answers ARP
    requests for 1.0.0.3, even though that isn't its IP address. That
    convinces everyone else on the lan to send 1.0.0.3 packets to the Linux
    box, where the usual FreeS/WAN processing and routing take over.

    % arp -i eth0 -s 1.0.0.3 -D eth0 pub

    This says, if you see an ARP request on interface eth0 asking for
    1.0.0.3, respond with the Ethernet address of interface eth0.

    Now, as I said at the very beginning, if it is *at all* possible to
    configure your client *not* to use the virtual IP address, you can avoid
    this whole mess.

### Dynamic Network Interfaces

Sometimes you have to cope with a situation where the network interface(s) aren't all there at boot. The common example is notebooks with PCMCIA.

#### Basics

The key issue here is that the config setup section of the /etc/ipsec.conf configuration file lists the connection between ipsecN and hardware interfaces, in the interfaces= variable. At any time when ipsec setup start or ipsec setup restart is run this variable must correspond to the current real situation. More precisely, it must not mention any hardware interfaces which don't currently exist. The difficulty is that an ipsec setup start command is normally run at boot time so interfaces that are not up then are mis-handled.

#### Boot Time

Normally, an ipsec setup start is run at boot time. However, if the hardware situation at boot time is uncertain, one of two things must be done.

- One possibility is simply not to have IPSEC brought up at boot time. To do this:

            chkconfig --level 2345 ipsec off

That's for modern Red Hats or other Linuxes with chkconfig. Systems which lack this will require fiddling with symlinks in /etc/rc.d/rc?.d or the equivalent.
- Another possibility is to bring IPSEC up with no interfaces, which is less aesthetically satisfying but simpler. Just put

            interfaces=

in the configuration file. KLIPS and Pluto will be started, but won't do anything.

#### Change Time

When the hardware *is* in place, IPSEC has to be made aware of it. Someday there may be a nice way to do this.

Right now, the way to do it is to fix the /etc/ipsec.conf file appropriately, so interfaces reflects the new situation, and then restart the IPSEC subsystem. This does break any existing IPSEC connections.

If IPSEC wasn't brought up at boot time, do

            ipsec setup start

while if it was, do

            ipsec setup restart

which won't be as quick.

If some of the hardware is to be taken out, before doing that, amend the configuration file so interfaces no longer includes it, and do

            ipsec setup restart

Again, this breaks any existing connections.

### Unencrypted tunnels

Sometimes you might want to create a tunnel without encryption. Often this is a bad idea, even if you have some data which need not be private. See this discussion.

The IPSEC protocols provide two ways to do build such tunnels:

using ESP with null encryption
  not supported by FreeS/WAN
using AH without ESP
  supported for manually keyed connections
  possible with explicit commands via ipsec_whack(8) (see this list message)
  not supported in the ipsec_auto(8) scripts.

One situation in which this comes up is when otherwise some data would be encrypted twice. Alice wants a secure tunnel from her machine to Bob's. Since she's behind one security gateway and he's behind another, part of the tunnel that they build passes through the tunnel that their site admins have built between the gateways. All of Alice and Bob's messages are encrypted twice.

There are several ways to handle this.

- Just accept the overhead of double encryption. The site admins might choose this if any of the following apply:
  - policy says encrypt everything (usually, it should)
  - they don't entirely trust Alice and Bob (usually, if they don't have to, they shouldn't)
  - if they don't feel the saved cycles are worth the time they'd need to build a non-encrypted tunnel for Alice and Bob's packets (often, they aren't)
- Use a plain IP-in-IP tunnel. These are not well documented. A good starting point is in the Linux kernel source tree, in /usr/src/linux/drivers/net/README.tunnel.
- Use a manually-keyed AH-only tunnel.

Note that if Alice and Bob want end-to-end security, they must build a tunnel end-to-end between their machines or use some other end-to-end tool such as PGP or SSL that suits their data. The only question is whether the admins build some special unencrypted tunnel for those already-encrypted packets.

# FreeS/WAN manual pages

The various components of Linux FreeS/WAN are of course documented in standard Unix manual pages, accessible via the man(1) command.

Links here take you to an HTML version of the man pages.

## Files

ipsec.conf(5)
  IPSEC configuration and connections
ipsec.secrets(5)
  preshared secrets for IKE/IPsec authentication

These files are also discussed in the configuration section.

## Commands

Many users will never give most of the FreeS/WAN commands directly. Configure the files listed above correctly and everything should be automatic.

One exception is:

ipsec_rsasigkey(8)
  generate RSA keys for use in Pluto authentication

Note that:

- These keys are for authentication only. They are not secure for encryption.
- The utility uses random(4) as a source of random numbers. This may block for some time if there is not enough activity on the machine to provide the required entropy. You may want to give it some bogus activity such as random mouse movements or some command such as `du /usr > dev/null`

The following commands are fairly likely to be used, if only for testing and status checks:

ipsec(8)
  invoke IPSEC utilities
ipsec_setup(8)
  control IPSEC subsystem
ipsec_auto(8)
  control automatically-keyed IPSEC connections
ipsec_manual(8)
  take manually-keyed IPSEC connections up and down
ipsec_ranbits(8)
  generate random bits in ASCII form
ipsec_look(8)
  show minimal debugging information
ipsec_barf(8)
  spew out collected IPSEC debugging information

The lower-level utilities listed below are normally invoked via scripts listed above, but they can also be used directly when required.

ipsec_eroute(8)
  manipulate IPSEC extended routing tables
ipsec_klipsdebug(8)
  set Klips (kernel IPSEC support) debug features and level
ipsec_pluto(8)
  IPsec IKE keying daemon
ipsec_spi(8)
  manage IPSEC Security Associations
ipsec_spigrp(8)
  group/ungroup IPSEC Security Associations
ipsec_tncfg(8)
  associate IPSEC virtual interface with real interface
ipsec_whack(8)
  control interface for IPSEC keying daemon

## Library routines

ipsec_atoaddr(3)
ipsec_addrtoa(3)
  convert Internet addresses to and from ASCII
ipsec_atosubnet(3)
ipsec_subnettoa(3)
  convert subnet/mask ASCII form to and from addresses
ipsec_atoasr(3)
  convert ASCII to Internet address, subnet, or range
ipsec_rangetoa(3)
  convert Internet address range to ASCII
ipsec_atodata(3)
ipsec_datatoa(3)
  convert binary data from and to ASCII formats
ipsec_atosa(3)
ipsec_satoa(3)
  convert IPSEC Security Association IDs to and from ASCII
ipsec_atoul(3)
ipsec_ultoa(3)
  convert unsigned-long numbers to and from ASCII
ipsec_goodmask(3)
  is this Internet subnet mask a valid one?
ipsec_masktobits(3)
  convert Internet subnet mask to bit count
ipsec_bitstomask(3)
  convert bit count to Internet subnet mask
ipsec_optionsfrom(3)
  read additional ``command-line'' options from file
ipsec_subnetof(3)
  given Internet address and subnet mask, return subnet number
ipsec_hostof(3)
  given Internet address and subnet mask, return host part
ipsec_broadcastof(3)
  given Internet address and subnet mask, return broadcast address

# FreeS/WAN and firewalls

FreeS/WAN, or other IPSEC implementations, frequently run on gateway machines, the same machines running firewall or packet filtering code. This document discusses the relation between the two.

## IPSEC packets

IPSEC uses three main types of packet:

IKE uses the UDP protocol and port 500 .
  Unless you are using only (less secure, not recommended) manual keying, you need IKE to negotiate connection parameters, acceptable algorithms, key sizes and key setup. IKE handles everything required to set up, rekey, repair or tear down IPSEC connections.
ESP is protocol number 50
  This is required for encrypted connections.
AH is protocol number 51
  This can be used where only authentication, not encryption, is required. That can also be done with ESP and null encryption.

All of those packets should have appropriate IPSEC gateway addresses in both the to and from IP header fields. Firewall rules can check this if you wish, though it is not strictly necessary. This is discussed in more detail later.

IPSEC processing of incoming packets authenticates them then removes the ESP or AH header and decrypts if necessary. Successful processing exposes an inner packet which is then delivered back to the firewall machinery, marked as having arrived on an ipsec[0-3] interface. Firewall rules can use that interface label to distinguish these packets from unencrypted packets which are labelled with the physical interface they arrived on (or perhaps with a non-IPSEC virtual interface such as ppp0).

One of our users sent a mailing list message with a diagram of the packet flow.

### ESP and AH do not have ports

Some protocols, such as TCP and UDP, have the notion of ports. Others protocols, including ESP and AH, do not. Quite a few IPSEC newcomers have become confused on this point. There are no ports in the ESP or AH protocols, and no ports used for them. For these protocols, the idea of ports is completely irrelevant.

### Header layout

The protocol numbers for ESP or AH are used in the 'next header' field of the IP header. On most non-IPSEC packets, that field would have one of:

- 1 for ICMP
- 4 for IP-in-IP encapsulation
- 6 for TCP
- 17 for UDP
- ... or one of about 100 other possibilities listed by IANA

Each header in the sequence tells what the next header will be. IPSEC adds headers for ESP or AH near the beginning of the sequence. The original headers are kept and the 'next header' fields adjusted so that all headers can be correctly interpreted.

For example, using [ ] to indicate data protected by ESP and unintelligible to an eavesdropper between the gateways:

- a simple packet might have only IP and TCP headers with:
  - IP header says next header --> TCP
  - TCP header port number --> which process to send data to
  - data
- with ESP transport mode encapsulation, that packet would have:
  - IP header says next header --> ESP
  - ESP header [ says next --> TCP
  - TCP header port number --> which process to send data to
  - data ]
  Note that the IP header is outside ESP protection, visible to an attacker, and that the final destination must be the gateway.
- with ESP in tunnel mode, we might have:
  - IP header says next header --> ESP
  - ESP header [ says next --> IP
  - IP header says next header --> TCP
  - TCP header port number --> which process to send data to
  - data ]
  Here the inner IP header is protected by ESP, unreadable by an attacker. Also, the inner header can have a different IP address than the outer IP header, so the decrypted packet can be routed from the IPSEC gateway to a final destination which may be another machine.

Part of the ESP header itself is encrypted, which is why the [ indicating protected data appears in the middle of some lines above. The next header field of the ESP header is protected. This makes traffic analysis more difficult. The next header field would tell an eavesdropper whether your packet was UDP to the gateway, TCP to the gateway, or encapsulated IP. It is better not to give this information away. A clever attacker may deduce some of it from the pattern of packet sizes and timings, but we need not make it easy.

IPSEC allows various combinations of these to match local policies, including combinations that use both AH and ESP headers or that nest multiple copies of these headers.

For example, suppose my employer has an IPSEC VPN running between two offices so all packets travelling between the gateways for those offices are encrypted. If gateway policies allow it (The admins could block UDP 500 and protocols 50 and 51 to disallow it), I can build an IPSEC tunnel from my desktop to a machine in some remote office. Those packets will have one ESP header throughout their life, for my end-to-end tunnel. For part of the route, however, they will also have another ESP layer for the corporate VPN's encapsulation. The whole header scheme for a packet on the Internet might be:

- IP header (with gateway address) says next header --> ESP
- ESP header [ says next --> IP
- IP header (with receiving machine address) says next header --> ESP
- ESP header [ says next --> TCP
- TCP header port number --> which process to send data to
- data ]]

The first ESP (outermost) header is for the corporate VPN. The inner ESP header is for the secure machine-to-machine link.

## Filtering rules for IPSEC packets

As a consequence of the above, an IPSEC gateway should have packet filters that allow the following protocols when talking to other IPSEC gateways:

- UDP port 500
- protocol 50 if you use ESP encryption and/or authentication (the typical case)
- protocol 51 if you use AH packet-level authentication

Your gateway and the other IPSEC gateways it communicates with must be able to exchange these packets for IPSEC to work. Firewall rules must allow UDP 500 and at least one of AH or ESP on the interface that communicates with the other gateway.

### IPSEC through the gateway

The preceeding paragraph deals with packets addressed to or sent from your gateway. It is a separate policy decision whether to permit such packets to pass through the gateway so that client machines can build end-to-end IPSEC tunnels of their own. This may not be practical if you are using NAT (IP masquerade) on your gateway, and may conflict with some corporate security policies. Other than that, it is likely a good idea.

### Preventing non-IPSEC traffic

You can of course also filter everything but UDP port 500 and ESP or AH to restrict traffic to IPSEC only, either for anyone communicating with your host or just for specific partners.

### Filtering packets from unknown gateways

It is possible to use firewall rules to restrict UDP 500, ESP and AH packets so that these packets are accepted only from known gateways. This is not strictly necessary since FreeS/WAN will discard packets from unknown gateways. You might, however, want to do it for any of a number of reasons. For example:

- Arguably, "belt and suspenders" is the sensible approach to security. If you can block a potential attack in two ways, use both. The only question is whether to look for a third way after implementing the first two.
- Some admins may prefer to use the firewall code this way because they prefer firewall logging to FreeS/WAN's logging.
- You may need it to implement your security policy. Consider an employee working at home, and a policy that says traffic from the home system to the Internet at large must go first via IPSEC to the corporate LAN and then out to the Internet via the corporate firewall. One way to do that is to make ipsec0 the default route on the home gateway and provide exceptions only for UDP 500 and ESP to the corporate gateway. Everything else is then routed via the tunnel to the corporate gateway.

It is not possible to use only static firewall rules for this filtering if you do not know the other gateways' IP addresses in advance, for example if you have "road warriors" who may connect from a different address each time or if want to do opportunistic encryption to arbitrary gateways. In these cases, you can accept UDP 500 IKE packets from anywhere, then use the updown script feature of pluto(8) to dynamically adjust firewalling for each negotiated tunnel.

Firewall packet filtering does not much reduce the risk of a denial of service attack on FreeS/WAN. The firewall can drop packets from unknown gateways, but KLIPS does that quite efficiently anyway, so you gain little. The firewall cannot drop otherwise legitmate packets that fail KLIPS authentication, so it cannot protect against an attack designed to exhaust resources by making FreeS/WAN perform many expensive authentication operations.

In summary, firewall filtering of IPSEC packets from unknown gateways is possible but not strictly necessary.

## Other packet filters

When the IPSEC gateway is also acting as your firewall, other packet filtering rules will be in play. In general, those are outside the scope of this document. See our Linux firewall links for information. There are a few types of packet, however, which can affect the operation of FreeS/WAN or of diagnostic tools commonly used with it. These are discussed below.

### ICMP filtering

ICMP is the Internet C ontrol Message Protocol. It is used for messages between IP implementations themselves, whereas IP used is used between the clients of those implementations. ICMP is, unsurprisingly, used for control messages. For example, it is used to notify a sender that a desination is not reachable, or to tell a router to reroute certain packets elsewhere.

ICMP handling is tricky for firewalls.

- You definitely want some ICMP messages to get through; things won't work without them. For example, your clients need to know if some destination they ask for is unreachable.
- On the other hand, you do equally definitely do not want untrusted folk sending arbitrary control messages to your machines. Imagine what someone moderately clever and moderately malicious could do to you, given control of your network's routing.

ICMP does not use ports. Messages are distinguished by a "message type" field and, for some types, by an additional "code" field. The definitive list of types and codes is on the IANA site.

One expert uses this definition for ICMP message types to be dropped at the firewall.

    # ICMP types which lack socially redeeming value.
    #  5     Redirect
    #  9     Router Advertisement
    # 10     Router Selection
    # 15     Information Request
    # 16     Information Reply
    # 17     Address Mask Request
    # 18     Address Mask Reply

    badicmp='5 9 10 15 16 17 18'

A more conservative approach would be to make a list of allowed types and drop everything else.

Whichever way you do it, your ICMP filtering rules on a FreeS/WAN gateway should allow at least the following ICMP packet types:

echo (type 8)
echo reply (type 0)
  These are used by ping(1). We recommend allowing both types through the tunnel and to or from your gateway's external interface, since ping(1) is an essential testing tool.

It is fairly common for firewalls to drop ICMP echo packets addressed to machines behind the firewall. If that is your policy, please create an exception for such packets arriving via an IPSEC tunnel, at least during intial testing of those tunnels.

destination unreachable (type 3)
  This is used, with code 4 (Fragmentation Needed and Don't Fragment was Set) in the code field, to control path MTU discovery. Since IPSEC processing adds headers, enlarges packets and may cause fragmentation, an IPSEC gateway should be able to send and receive these ICMP messages on both inside and outside interfaces.

### UDP packets for traceroute

The traceroute(1) utility uses UDP port numbers from 33434 to approximately 33633. Generally, these should be allowed through for troubleshooting.

Some firewalls drop these packets to prevent outsiders exploring the protected network with traceroute(1). If that is your policy, consider creating an exception for such packets arriving via an IPSEC tunnel, at least during intial testing of those tunnels.

### UDP for L2TP

Windows 2000 does, and products designed for compatibility with it may, build L2TP tunnels over IPSEC connections.

For this to work, you must allow UDP protocol 1701 packets coming out of your tunnels to continue to their destination. You can, and probably should, block such packets to or from your external interfaces, but allow them from ipsec0.

See also our Windows 2000 interoperation discussion .

## IPSEC and NAT

Network Address Translation, also known as IP masquerading, is a method of allocating IP addresses dynamically, typically in circumstances where the total number of machines which need to access the Internet exceeds the supply of IP addresses.

Any attempt to perform NAT operations on IPSEC packets between the IPSEC gateways creates a basic conflict:

- IPSEC wants to authenticate packets and ensure they are unaltered on a gateway-to-gateway basis
- NAT rewrites packet headers as they go by
- IPSEC authentication fails if packets are rewritten anywhere between the IPSEC gateways

For AH, which authenticates parts of the packet header including source and destination IP addresses, this is fatal. If NAT changes those fields, AH authentication fails.

For IKE and ESP it is not necessarily fatal, but is certainly an unwelcome complication.

### NAT on or behind the IPSEC gateway works

This problem can be avoided by having the masquerading take place on or behind the IPSEC gateway.

This can be done physically with two machines, one physically behind the other. A picture, using SG to indicate IPSEC S ecurity Gateways, is:

          clients --- NAT ----- SG ---------- SG
                      two machines

In this configuration, the actual client addresses need not be given in the leftsubnet= parameter of the FreeS/WAN connection description. The security gateway just delivers packets to the NAT box; it needs only that machine's address. What that machine does with them does not affect FreeS/WAN.

A more common setup has one machine performing both functions:

          clients ----- NAT/SG ---------------SG
                      one machine

Here you have a choice of techniques depending on whether you want to make your client subnet visible to clients on the other end:

- If you want the single gateway to behave like the two shown above, with your clients hidden behind the NAT, then omit the leftsubnet= parameter. It then defaults to the gateway address. Clients on the other end then talk via the tunnel only to your gateway. The gateway takes packets emerging from the tunnel, applies normal masquerading, and forwards them to clients.
- If you want to make your client machines visible, then give the client subnet addresses as the leftsubnet= parameter in the connection description and
  either
    set leftfirewall=yes to use the default updown script
  or
    use your own script by giving its name in a leftupdown= parameter
  These scripts are described in their own section .

In this case, no masquerading is done. Packets to or from the client subnet are encrypted or decrypted without any change to their client subnet addresses, although of course the encapsulating packets use gateway addresses in their headers. Clients behind the right security gateway see a route via that gateway to the left subnet.

### NAT between gateways is problematic

We recommend not trying to build IPSEC connections which pass through a NAT machine. This setup poses problems:

          clients --- SG --- NAT ---------- SG

If you must try it, some references are:

- Jean_Francois Nadeau's document on doing IPSEC behind NAT
- VPN masquerade patches to make a Linux NAT box handle IPSEC packets correctly

### Other references on NAT and IPSEC

Other documents which may be relevant include:

- an Internet Draft on IPSEC and NAT which may eventually evolve into a standard solution for this problem.
- an informational RFC, Security Model with Tunnel-mode IPsec for NAT Domains .
- an article in Cisco's Internet Protocol Journal

## Calling firewall scripts, named in ipsec.conf(5)

The ipsec.conf configuration file has three pairs of parameters used to specify an interface between FreeS/WAN and firewalling code.

Note that using these is not required if you have a static firewall setup. In that case, you just set your firewall up at boot time (in a way that permits the IPSEC connections you want) and do not change it thereafter. Omit all the FreeS/WAN firewall parameters and FreeS/WAN will not attempt to adjust firewall rules at all. See below for some information on appropriate scripts.

However, if you want your firewall rules to change when IPSEC connections change, then you need to use these parameters.

### Scripts called at IPSEC start and stop

One pair of parmeters are set in the config setup section of the ipsec.conf(5) file and affect all connections:

prepluto=
postpluto=
  specify scripts to be called before our pluto(8) IKE daemon is started and after it is stopped.

These parameters allow you to change firewall parameters whenever IPSEC is started or stopped.

They can also be used in other ways. For example, you might have prepluto add a module to your kernel for the secure network interface or make a dialup connection, and then have postpluto remove the module or take the connection down.

### Scripts called at connection up and down

The other parameters are set in connection descriptions. They can be set in individual connection descriptions, and could even call different scripts for each connection for maximum flexibility. In most applications, however, it makes sense to use only one script and to call it from conn %default section so that it applies to all connections.

You can either set [left|right]firewall=yes to use our supplied default script or assign a name in a [left|right]updown= line to use your own script.

For details of when Pluto calls these scripts, what arguments it passes to them, and what the default script does with those arguments, see the ipsec_pluto(8) man page.

Note that only one of these should be used. You cannot sensibly use both.

#### The default script

We supply a default script named _updown.

leftfirewall=
rightfirewall=
  indicates that the gateway is doing firewalling and that pluto(8) should poke holes in the firewall as required.

Set these to yes and Pluto will call our default script _updown with appropriate arguments whenever it:

- starts or stops IPSEC services
- brings a connection up or down

The supplied default _updown script is appropriate for simple cases using the ipfwadm(8) firewalling package.

#### User-written scripts

You can also write your own script and have Pluto call it. Just put the script's name in one of these ipsec.conf(5) lines:

leftupdown=
rightupdown=
  specifies a script to call instead of our default script _updown.

Your script should take the same arguments and use the same environment variables as _updown. These are described in the pluto(8) man page.

In developing your own script, you can of course use our scripts (either the default _updown or the ipchains-based example given below) as a starting point. Note, however, that you should not modify our _updown script in place. If you did that, then upgraded FreeS/WAN, the upgrade would install a new default script, overwriting your changes.

### Scripts for ipchains

Our _updown is for firewalls using ipfwadm(8) . If you are using the more recent package ipchains(8), you must do one of:

- use static firewall rules which require no change for FreeS/WAN
- limit yourself to ipchains(8)'s ipfwadm(8) emulation mode in order to use our script
- write your own script and call it with leftupdown and rightupdown.

We provide an example script for use with ipchains(8) below.

### DHR on the updown script

Here are some mailing list comments from pluto(8) developer Hugh Redelmeier on an earlier draft of this document:

    There are many important things left out

    - firewalling is important but must reflect (implement) policy.  Since
      policy isn't the same for all our customers, and we're not experts,
      we should concentrate on FW and MASQ interactions with FreeS/WAN.

    - we need a diagram to show packet flow WITHIN ONE MACHINE, assuming
      IKE, IPsec, FW, and MASQ are all done on that machine.  The flow is
      obvious if the components are run on different machines (trace the
      cables).

      IKE input:
            + packet appears on public IF, as UDP port 500
            + input firewalling rules are applied (may discard)
            + Pluto sees the packet.

      IKE output:
            + Pluto generates the packet & writes to public IF, UDP port 500
            + output firewalling rules are applied (may discard)
            + packet sent out public IF

      IPsec input, with encapsulated packet, outer destination of this host:
            + packet appears on public IF, protocol 50 or 51.  If this
              packet is the result of decapsulation, it will appear
              instead on the paired ipsec IF.
            + input firewalling rules are applied (but packet is opaque)
            + KLIPS decapsulates it, writes result to paired ipsec IF
            + input firewalling rules are applied to resulting packet
              as input on ipsec IF
            + if the destination of the packet is this machine, the
              packet is passed on to the appropriate protocol handler.
              If the original packet was encapsulated more than once
              and the new outer destination is this machine, that
              handler will be KLIPS.
            + otherwise:
              * routing is done for the resulting packet.  This may well
                direct it into KLIPS for encoding or encrypting.  What
                happens then is described elsewhere.
              * forwarding firewalling rules are applied
              * output firewalling rules are applied
              * the packet is sent where routing specified

     IPsec input, with encapsulated packet, outer destination of another host:
            + packet appears on some IF, protocol 50 or 51
            + input firewalling rules are applied (but packet is opaque)
            + routing selects where to send the packet
            + forwarding firewalling rules are applied (but packet is opaque)
            + packet forwarded, still encapsulated

      IPsec output, from this host or from a client:
            + if from a client, input firewalling rules are applied as the
              packet arrives on the private IF
            + routing directs the packet to an ipsec IF (this is how the
              system decides KLIPS processing is required)
            + if from a client, forwarding firewalling rules are applied
            + KLIPS eroute mechanism matches the source and destination
              to registered eroutes, yielding a SPI group.  This dictates
              processing, and where the resulting packet is to be sent
              (the destinations SG and the nexthop).
            + output firewalling is not applied to the resulting
              encapsulated packet

    - Until quite recently, KLIPS would double encapsulate packets that
      didn't strictly need to be.  Firewalling should be prepared for
      those packets showing up as ESP and AH protocol input packets on
      an ipsec IF.

    - MASQ processing seems to be done as if it were part of the
      forwarding firewall processing (this should be verified).

    - If a firewall is being used, it is likely the case that it needs to
      be adjusted whenever IPsec SAs are added or removed.  Pluto invokes
      a script to do this (and to adjust routing) at suitable times.  The
      default script is only suitable for ipfwadm-managed firewalls.  Under
      LINUX 2.2.x kernels, ipchains can be managed by ipfwadm (emulation),
      but ipchains more powerful if manipulated using the ipchains command.
      In this case, a custom updown script must be used.

      We think that the flexibility of ipchains precludes us supplying an
      updown script that would be widely appropriate.

We do provide a sample script in the next section. It is essentially a transliteration of the version we supply for ipfwadm. Because it doesn't process the command line argument, it cannot be directly subsituted -- it won't support the semantics of *firewall=no. It can be used in [left|right]updown=.

### Example updown script for ipchains

Here is an example updown script for use with ipchains. It is intended to be called via an updown= statement in ipsec.conf.

    #! /bin/sh
    # sample updown script for ipchains
    # Copyright (C) 2000  D. Hugh Redelmeier, Henry Spencer
    #
    # This program is free software; you can redistribute it and/or modify it
    # under the terms of the GNU General Public License as published by the
    # Free Software Foundation; either version 2 of the License, or (at your
    # option) any later version.  See .
    #
    # This program is distributed in the hope that it will be useful, but
    # WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY
    # or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
    # for more details.
    #
    # RCSID $Id: firewall.html,v 1.20 2001/06/12 05:14:54 sandy Exp $

    # check interface version
    case "$PLUTO_VERSION" in
    1.0)    ;;
    *)      echo "$0: unknown interface version \`$PLUTO_VERSION'" >2        exit 2
            ;;
    esac

    # check parameter(s)
    case "$*" in
    '')     ;;
    *)      echo "$0: parameters unexpected" >2        exit 2
            ;;
    esac

    # utility functions for route manipulation
    # Meddling with this stuff should never be necessary and is most unwise.
    uproute() {
            route add -net $PLUTO_PEER_CLIENT_NET netmask $PLUTO_PEER_CLIENT_MASK \
                    dev $PLUTO_INTERFACE gw $PLUTO_NEXT_HOP
    }
    downroute() {
            route del -net $PLUTO_PEER_CLIENT_NET netmask $PLUTO_PEER_CLIENT_MASK \
                    dev $PLUTO_INTERFACE gw $PLUTO_NEXT_HOP
    }

    # the big choice
    case "$PLUTO_VERB" in
    prepare-host|prepare-client)
            # delete possibly-existing route (preliminary to adding a route)
            oops="`route del -net $PLUTO_PEER_CLIENT_NET \
                                            netmask $PLUTO_PEER_CLIENT_MASK 2>1"
            status="$?"
            if test " $oops" = " " -a " $status" != " 0"
            then
                    oops="silent error in route command, exit status $status"
            fi
            case "$oops" in
            'SIOCDELRT: No such process')
                    # This is what route (currently -- not documented!) gives
                    # for "could not find such a route".
                    status=0
                    ;;
            esac
            exit $status
            ;;
    route-host|route-client)
            # connection to this host or client being routed
            uproute
            ;;
    unroute-host|unroute-client)
            # connection to this host or client being unrouted
            downroute
            ;;
    up-host)
            # connection to this host coming up
            ;;
    down-host)
            # connection to this host going down
            ;;
    up-client)
            # connection to client subnet, through forwarding firewall, coming up
            ipchains -I forward -j ACCEPT -b \
                    -s $PLUTO_MY_CLIENT_NET/$PLUTO_MY_CLIENT_MASK \
                    -d $PLUTO_PEER_CLIENT_NET/$PLUTO_PEER_CLIENT_MASK
            ;;
    down-client)
            # connection to client subnet, through forwarding firewall, going down
            ipchains -D forward -j ACCEPT -b \
                    -s $PLUTO_MY_CLIENT_NET/$PLUTO_MY_CLIENT_MASK \
                    -d $PLUTO_PEER_CLIENT_NET/$PLUTO_PEER_CLIENT_MASK
            ;;
    *)      echo "$0: unknown verb \`$PLUTO_VERB' or parameter \`$1'" >2        exit 1
            ;;
    esac

## Ipchains firewall configuration at boot

It is also possible to set up both firewalling and IPSEC with appropriate scripts at boot and then not use leftupdown= and rightupdown=, or use them only for simple up and down operations.

Basically, the technique is

- allow IPSEC packets (typically, IKE on UDP port 500 plus ESP, protocol 50)
  - incoming, if the destination address is your gateway (and optionally, only from known senders)
  - outgoing, with the from address of your gateway (and optionally, only to known receivers)
- let Pluto deal with IKE
- let KLIPS deal with ESP
- if necessary, filter incoming packets emerging from KLIPS.

Firewall rules can recognise packets emerging from IPSEC. They are marked as arriving on an interface such as ipsec0, rather than eth0, ppp0 or whatever.

While it is possible to create such rules yourself (please let us know via the mailing list if you do), it may be both easier and more secure to use a set which has already been published and tested. Those we know of are described below.

### Scripts based on Ranch's work

One user, Rob Hutton, posted his boot time scripts to the mailing list, and we included them in previous versions of this documentation. They are still available from our web site. However, they were for an earlier FreeS/WAN version so we no longer recommend them. Also, they had some bugs. See this message.

Those scripts were based on David Ranch's scripts for his "Trinity OS" for setting up a secure Linux. Check his home page for the latest version and for information on his book on securing Linux. If you are going to base your firewalling on Ranch's scripts, we recommend using his latest version, and sending him any IPSEC modifications you make for incorporation into later versions.

### The Seattle firewall

We have had several mailing lists reports of good results using FreeS/WAN with Seawall (the Seattle Firewall). See that project's home page on Sourceforge.

### The RCF scripts

Another set of firewall scripts with IPSEC support are the RCF or rc.firewall scripts. See their home page.

# Linux FreeS/WAN Troubleshooting

This is a collection of notes on various aspects of debugging FreeS/WAN setup and connections. Other sources of information are:

- the FAQ covers:
  - common problems
  - common questions
  - interpreting FreeS/WAN error messages
- If the other end of your connection is not FreeS/WAN, see our interoperation document.

## Problem Reporting

For how to report problems, see the file doc/prob.report.

## Logs used

Error messages generated by KLIPS during the boot sequence are accessible with the dmesg command.

Pluto logs to:

- /var/log/secure (or, on Debian, /var/log/auth.log)
- /var/log/messages

Check both places to get full information. If you find nothing, check your syslogd.conf(5) to see where your system is putting things.

## Information available on your system

### man pages provided

ipsec.conf(5)
  Manual page for IPSEC configuration file.
ipsec(8)
  Primary man page for ipsec utilities.

Other man pages are on

this list and in

- /usr/local/man/man3
- /usr/local/man/man5
- /usr/local/man/man8/ipsec_*

### Status information

/proc/net/ipsec*
  Various files reporting the status of IPSEC.
ipsec auto --status
  Command to get status report from running system. Displays Pluto's state: the list of "added" conns and the list of state objects reflecting ISAKMP and IPsec SAs being negotiated or installed.
ipsec look
  Brief status info.
ipsec barf
  Copious debugging info.

## Pluto problem hints

From a message posted to the mailing list Jan 14 2000 by Pluto developer Hugh Redelmeier:

    Until ipsec auto and whack/pluto get fixed:

            When puzzled by Pluto behaviour, always look in
            /var/log/secure -- that's the unadulterated story.

            To get the whole whack output (almost a subset of
            the story from Pluto), give auto the --verbose flag
            on each invocation.  Eg:
                    ipsec auto --verbose --up sadaisy

    Bonus hint: problems snowball.  So look for the first problem first,
    it is likely to be the cause of later problems.

    And a final hint: If one side keeps retrying to no avail, it may be
    because the other is unhappy about something and won't reply.  Go look
    at the other side to figure out what it doesn't like.

Various error messages from Pluto are discussed in the FAQ and the ipsec_pluto(8) man page.

### Using GDB on Pluto

You may need to use the GNU degugger, gdb(1), on Pluto. This should be necessary only in unusal cases, for example if you encounter a problem which the Pluto developer cannot readily reproduce or if you are modifying Pluto.

Here are the Pluto developer's suggestions for doing this:

    Can you get a core dump and use gdb to find out what Pluto was doing
    when it died?

    To get a core dump, you will have to set dumpdir to point to a
    suitable directory (see ipsec.conf(5)).

    To get gdb to tell you interesting stuff:
            $ script
            $ cd dump-directory-you-chose
            $ gdb /usr/local/lib/ipsec/pluto core
            (gdb) where
            (gdb) quit
            $ exit

    The resulting output will have been captured by the script command in
    a file called "typescript".  Send it to the list.

    Do not delete the core file.  I may need to ask you to print out some
    more relevant stuff.

Note that the dumpdir parameter takes effect only when the IPsec subsystem is restarted -- reboot or ipsec setup restart .

## ifconfig reports for KLIPS debugging

From a mail message from our KLIPS developer:

    Here is a catalogue of the types of errors that can occur for which
    statistics are kept when transmitting and receiving packets via klips.
    I notice that they are not necessarily logged in the right counter.
    . . .

    Sources of ifconfig statistics for ipsec devices

    rx-errors:
    - packet handed to ipsec_rcv that is not an ipsec packet.
    - ipsec packet with payload length not modulo 4.
    - ipsec packet with bad authenticator length.
    - incoming packet with no SA.
    - replayed packet.
    - incoming authentication failed.
    - got esp packet with length not modulo 8.

    tx_dropped:
    - cannot process ip_options.
    - packet ttl expired.
    - packet with no eroute.
    - eroute with no SA.
    - cannot allocate sk_buff.
    - cannot allocate kernel memory.
    - sk_buff internal error.

    The standard counters are:

    struct enet_statistics
    {
            int        rx_packets;                /* total packets received */
            int        tx_packets;                /* total packets transmitted */
            int        rx_errors;                /* bad packets received */
            int        tx_errors;                /* packet transmit problems */
            int        rx_dropped;                /* no space in linux buffers */
            int        tx_dropped;                /* no space available in linux */
            int        multicast;                /* multicast packets received */
            int        collisions;

            /* detailed rx_errors: */
            int        rx_length_errors;
            int        rx_over_errors;                /* receiver ring buff overflow */
            int        rx_crc_errors;                /* recved pkt with crc error */
            int        rx_frame_errors;        /* recv'd frame alignment error */
            int        rx_fifo_errors;                /* recv'r fifo overrun */
            int        rx_missed_errors;        /* receiver missed packet */

            /* detailed tx_errors */
            int        tx_aborted_errors;
            int        tx_carrier_errors;
            int        tx_fifo_errors;
            int        tx_heartbeat_errors;
            int        tx_window_errors;
    };

    of which I think only the first 6 are useful.

## Testing between security gateways

Sometimes you need to test the tunnel between two security gateways. This can be done by having a machine behind one gateway ping a machine behind the other gateway, but this is not always convenient or even possible.

Simply pinging one gateway from the other is not useful. Such a ping does not normally go through the tunnel. The tunnel handles trafiic between the two protected subnets, not between the gateways . Depending on the routing in place, a ping might

- either succeed by finding an unencrypted route
- or fail by finding no route. Packets without an IPSEC eroute are discarded.

Neither event tells you anything about the tunnel. You can explicitly create an eroute to force such packets through the tunnel, or you can create additional tunnels as described in our configuration document, but those may be an unnecessary complications in your situation.

The trick is to explicitly use an IP address for the subnet-side interface of one gateway machine, either as the target of a ping or as the origin of a traceroute. Since that interface is on the protected subnet, the resulting packets do go via the tunnel.

From the mailing list:

    >; > ;I have two gateways, SG1 and SG2, with I/Fs i and e (for internal and
    >; > ;external), and two hosts, H1 and H2 set up as:
    >; > ;
    >; > ;     H1-----(i)SG1(e)===========(e)SG2(i)------H2
    >; > ;
    >; > ;And I want to test a tunnel set up between the H1 subnet and the H2
    >; > ;subnet, but the H2 host may not exist yet, or may not be responding.
    >; > ;
    >; > ;If I ping SG2i from H1, all traffic in both directions is encrypted,
    >; > ;testing the tunnel.
    .....
    >; > ;If I understand correctly, this could be accomplished by the 'ping -I'
    >; > ;feature of which you spoke earlier or 'traceroute -i'?
    >;
    >; Indeed,
    >;   traceroute -i eth0 -f 20 otherSG
    >; appears to give me a solution using only N machines, the SGs themselves.
    >; This is very nice.  Note that in this example, eth0 is the *private* (i)
    >; interface.  If you try it with the (e) interface or the ipsec0 interface,
    >; you won't get the desired result.  If you leave off the -f 20, the trace
    >; will hang in some totally bizarre way.

Some older Linux distributions did not support ping -I, according to mailing list comments. More recent comments indicate that this does now work. For example, you can do:

    	ping -I 192.168.10.250 192.168.0.11

to test between the interfaces on the two protected subnets.

## Claudia's guide

FreeS/WAN "listress" (mailing list tech support person) Claudia Schmeing posted this guide to trouble-shooting in early March 2000. It may be worth checking list archives for a more recent version.

    Your mail has inspired me to write a little trouble shooting
    guide to supplement and connect the existing docs on the subject.
    Here's v. 1. Comments are welcome.

    Steps in Troubleshooting Linux FreeS/WAN:
    - -----------------------------------------

    Finding the Error
    - -----------------

    First, try to find verbose text that describes how things are going wrong
    or creating unexpected results. Here's how:

    While the dialog from ipsec auto --up myconn (or whatever) will tell
    you where the process fails, it is often not very specific. And for
    errors that have to do with the use of a conn, you may not even have
    this.

    More information can be gleaned from the log files, usually
    /var/log/messages or /var/log/secure. On some systems, the logfiles
    are differently named. To find your error messages, check where your
    /etc/syslog.conf or equivalent is directing authpriv.

    The amount of your error's description in your logs depends on your debug
    settings, klipsdebug= and plutodebug=, in ipsec.conf. See man ipsec.conf for
    details. Note that usually, either 'none' or 'all' will be what you want;
    you don't need to worry about the nuances of the debug options.

    If you're having an negotiation problem (as you are, above) plutodebug
    is most relevant. If you have a connection established but the
    packets aren't doing what you think they should, play with klipsdebug.
    See also /doc/ipsec.html#parts for the division of duties within
    Linux FreeS/WAN.

    After raising your debug levels, restart Linux FreeS/WAN to ensure that
    the conf file is re-read, then re-create the error to generate
    verbose logs. Proceed to the failure point in the logs and find
    the handful of lines which succinctly describe how things are going
    wrong or contrary to your expectation.

    Interpreting the Error
    - ----------------------

    To interpret this text, use the following resources:

    * the FAQ, doc/faq.html. Since the FAQ is constantly being updated,
    the snapshot may have a new entry relevant to your problem. For example,
    the faq in today's snapshot, addresses several more questions than the
    version on the site.

    * doc/config.html. Instructions for some configurations you can
    make with Linux FreeS/WAN. See especially doc/config.html#multitunnel,
    which is useful in a large proportion of the questions we see on the list.

    * doc/trouble.html.  Debugging instructions and notes. Note that
    most people now test automatic keying only if that's what they're using
    in the field, and only revert to manual testing to test unexpected
    behaviour that seems to be occurring at a very basic level.

    * the list archives. There are three: sandelman nexial, as listed
    at mail.html, and the archive for the filtered list at exim.org:

    http://www.exim.org/pipermail/linux-ipsec/
    (also listed in the upcoming docs).

    Each of them works differently, so it's worth checking each.

    Take a snippet of the text of your error which doesn't include anything
    site specific, ex. "No connection is known for", and search on this.
    It's likely you'll find the same answer to someone else's question
    this way, and it's faster than asking real-time humans ;-)

    * Sometimes a quick peek into the code where the error is being generated
    can be helpful. The pluto code is pretty well documented with comments
    and meaningful variable names.

    Asking for Help
    - ---------------

    A combination of the freeswan.org pages mentioned above and an archive
    search will address nearly every problem. But for those times when
    you've found something unusual, or your forehead is sore from banging
    it on your monitor, there's always the mailing list ;-)

    When writing the list, remember that more is more -- While sometimes
    an initial query with a quick description of your intent and error
    will twig someone's memory of a similar problem, it's often necessary to
    send a second mail with a complete problem report. See doc/prob.report
    for details. Lastly, as a kindness to other list members, you might post
    a link to a website where you've published your barf file rather than
    the entire file, if that option's available to you.

    Happy trouble shooting,

    Claudia

# Kernel configuration for FreeS/WAN

This section lists many of the options available when configuring a Linux kernel, and explains how they should be set on a FreeS/WAN IPSEC gateway.

## Not everyone needs to worry about kernel configuration

Note that in many cases you do not need to mess with these.

You may have a Linux distribution which comes with FreeS/WAN installed (see this list). In that case, you need not do a FreeS/WAN installation or a kernel configuration. Of course, you might still want to configure and rebuild your kernel to improve performance or security. This can be done with standard tools described in the Kernel HowTo.

If you need to install FreeS/WAN, then you do need to configure a kernel. However, you may choose to do that using the simplest procedure:

- Configure, build and test a kernel for your system before adding FreeS/WAN. See the Kernel HowTo for details. This step cannot be skipped . FreeS/WAN needs the results of your configuration.
- Then use FreeS/WAN's make oldgo command. This sets everything FreeS/WAN needs and retains your values everywhere else.

This document is for those who choose to configure their FreeS/WAN kernel themselves.

## Assumptions and notation

Help text for most kernel options is included with the kernel files, and is accessible from within the configuration utilities. We assume you will refer to that, and to the Kernel HowTo, as necessary. This document covers only the FreeS/WAN-specific aspects of the problem.

To avoid duplication, this document section does not cover settings for the additional IPSEC-related kernel options which become available after you have patched your kernel with FreeS/WAN patches. There is help text for those available from within the configuration utility.

We assume a common configuration in which the FreeS/WAN IPSEC gateway is also doing ipchains(8) firewalling for a local network, and possibly masquerading as well.

Some suggestions below are labelled as appropriate for "a true paranoid". By this we mean they may cause inconvenience and it is not entirely clear they are necessary, but they appear to be the safest choice. Not using them might entail some risk. Of course one suggested mantra for security administrators is: "I know I'm paranoid. I wonder if I'm paranoid enough."

### Labels used

Six labels are used to indicate how options should be set. We mark the labels with [square brackets]. For two of these labels, you have no choice:

[required]
  essential for FreeS/WAN operation.
[incompatible]
  incompatible with FreeS/WAN.

those must be set correctly or FreeS/WAN will not work

FreeS/WAN should work with any settings of the others, though of course not all combinations have been tested. We do label these in various ways, but these labels are only suggestions.

[recommended]
  useful on most FreeS/WAN gateways
[disable]
  an unwelcome complication on a FreeS/WAN gateway.
[optional]
  Your choice. We outline issues you might consider.
[anything]
  This option has no direct effect on FreeS/WAN and related tools, so you should be able to set it as you please.

Of course complexity is an enemy in any effort to build secure systems. For maximum security, any feature that can reasonably be turned off should be. "If in doubt, leave it out."

## Kernel options for FreeS/WAN

Indentation is based on the nesting shown by 'make menuconfig' with a 2.2.16 kernel for the i386 architecture.

Code maturity and level options
  Prompt for development ... code/drivers
    [optional] If this is no, experimental drivers are not shown in later menus.

  For most FreeS/WAN work, no is the preferred setting. Using new or untested components is too risky for a security gateway.

  However, for some hardware (such as the author's network cards) the only drivers available are marked new/experimental. In such cases, you must enable this option or your cards will not appear under "network device support". A true paranoid would leave this option off and replace the cards.

Processor type and features
  [anything]
Loadable module support
  Enable loadable module support
    [optional] A true paranoid would disable this. An attacker who has root access to your machine can fairly easily install a bogus module that does awful things, provided modules are enabled. A common tool for attackers is a "rootkit", a set of tools used once they have become root to introduce assorted additional compromises so that they "own" your system despite most recovery efforts. For Linux, there is a tool called knark which is basically a rootkit packaged as a kernel module.

  With modules disabled, an attacker cannot install a bogus module. The only way he can achieve the same effects is to install a new kernel and reboot. This is considerably more likely to be noticed.

  Many FreeS/WAN gateways run with modules enabled. This simplifies some administrative tasks and some ipchains features are available only as modules. Once an enemy has root on your machine your security is nil, so arguably defenses which come into play only in that situation are pointless.

Set version information ....
  [optional] This provides a check to prevent loading modules compiled for a different kernel.
Kernel module loader
  [disable] It gives little benefit on a typical FreeS/WAN gate and entails some risk.
General setup
  We list here only the options that matter for FreeS/WAN.
  Networking support
    [required]
  Sysctl interface
    [optional] If this option is turned on and the /proc filesystem installed, then you can control various system behaviours by writing to files under /proc/sys. For example:

              echo 1 > /proc/sys/net/ipv4/ipforward

  turns IP forwarding on.

  Disabling this option breaks many firewall scripts. A true paranoid would disable it anyway since it might conceivably be of use to an attacker.

Plug and Play support
  [anything]
Block devices
  [anything]
Networking options
  Packet socket
    [optional] This kernel feature supports tools such as tcpdump(8) which communicate directly with network hardware, bypassing kernel protocols. This is very much a two-edged sword:
    - such tools can be very useful to the firewall admin, especially during initial testing
    - should an evildoer breach your firewall, such tools could give him or her a great deal of information about the rest of your network
    We recommend disabling this option on production gateways.
  Kernel/User netlink socket
    [optional] Required if you want to use advanced router features.
  Routing messages
    [optional]
  Netlink device emulation
    [optional]
  Network firewalls
    [recommended] You need this if the IPSEC gateway also functions as a firewall.

  Even if the IPSEC gateway is not your primary firewall, we suggest setting this so that you can protect the gateway with at least basic local packet filters.

Socket filtering
  [disable] This enables an older filtering interface. We suggest using ipchains(8) instead. To do that, set the "Network firewalls" option just above, and not this one.
Unix domain sockets
  [required] These sockets are used for communication between the ipsec(8) commands and the ipsec_pluto(8) daemon.
TCP/IP networking
  [required]
  IP: multicasting
    [anything]
  IP: advanced router
    [optional] This gives you policy routing, which some people have used to good advantage in their scripts for FreeS/WAN gateway management. It is not used in our distributed scripts, so not required unless you want it for custom scripts. It requires the netlink interface between kernel code and the iproute2(8) command.
  IP: kernel level autoconfiguration
    [disable] It gives little benefit on a typical FreeS/WAN gate and entails some risk.
  IP: firewall packet netlink device
    [disable]
  IP: transparent proxy support
    [optional] This is required in some firewall configurations, but should be disabled unless you have a definite need for it.
  IP: masquerading
    [optional] Required if you want to use non-routable private IP addresses for your local network.
  IP: Optimize as router not host
    [recommended]
  IP: tunneling
    [required]
  IP: GRE tunnels over IP
    [anything]
  IP: aliasing support
    [anything]
  IP: ARP daemon support (EXPERIMENTAL)
    Not required on most systems, but might prove useful on heavily-loaded gateways.
  IP: TCP syncookie support
    [recommended] It provides a defense against a denial of service attack which uses bogus TCP connection requests to waste resources on the victim machine.
  IP: Reverse ARP
  IP: large window support
    [recommended] unless you have less than 16 meg RAM
IPv6
  [optional] FreeS/WAN does not currently support IPv6, though work on integrating FreeS/WAN with the Linux IPv6 stack has begun. Details.

It should be possible to use IPv4 FreeS/WAN on a machine which also does IPv6. This combination is not yet well tested. We would be quite interested in hearing results from anyone expermenting with it, via the mailing list.

We do not recommend using IPv6 on production FreeS/WAN gateways until more testing has been done.

Novell IPX
  [disable]
Appletalk
  [disable] Quite a few Linux installations use IP but also have some other protocol, such as Appletalk or IPX, for communication with local desktop machines. In theory it should be possible to configure IPSEC for the IP side of things without interfering with the second protocol.

We do not recommend this. Keep the software on your gateway as simple as possible. If you need a Linux-based Appletalk or IPX server, use a separate machine.

Telephony support
  [anything]
SCSI support
  [anything]
I2O device support
  [anything]
Network device support
  [anything] should work, but there are some points to note.

The development team test almost entirely on 10 or 100 megabit Ethernet and modems. In principle, any device that can do IP should be just fine for IPSEC, but in the real world any device that has not been well-tested is somewhat risky. By all means try it, but don't bet your project on it until you have solid test results.

If you disabled experimental drivers in the Code maturity section above, then those drivers will not be shown here. Check that option before going off to hunt for missing drivers.

If you want Linux to automatically find more than one ethernet interface at boot time, you need to:

- compile the appropriate driver(s) into your kernel. Modules will not work for this
- add a line such as

       append="ether=0,0,eth0 ether=0,0,eth1"

to your /etc/lilo.conf file. In some cases you may need to specify parameters such as IRQ or base address. The example uses "0,0" for these, which tells the system to search. If the search does not succeed on your hardware, then you should retry with explicit parameters. See the lilo.conf(5) man page or the LILO mini-HowTo for details.
- run lilo(8)

Having Linux find the cards this way is not necessary, but is usually more convenient than loading modules in your boot scripts.
Amateur radio support
  [anything]
IrDA (infrared) support
  [anything]
ISDN subsystem
  [anything]
Old CDROM drivers
  [anything]
Character devices
  The only required character device is:
  random(4)
    [required] This is a source of random numbers which are required for many cryptographic protocols, including several used in IPSEC.

  If you are comfortable with C source code, it is likely a good idea to go in and adjust the #define lines in /usr/src/linux/drivers/char/random.c to ensure that all sources of randomness are enabled. Relying solely on keyboard and mouse randomness is dubious procedure for a gateway machine. You could also increase the randomness pool size from the default 512 bytes (128 32-bit words).

Filesystems
  [anything] should work, but we suggest limiting a gateway machine to the standard Linux ext2 filesystem in most cases.
Network filesystems
  [disable] These systems are an unnecessary risk on an IPSEC gateway.
Console drivers
  [anything]
Sound
  [anything] should work, but we suggest enabling sound only if you plan to use audible alarms for firewall problems.
Kernel hacking
  [disable] This might be enabled on test machines, but should not be on production gateways.

# Distribution Roadmap: What's Where in Linux FreeS/WAN

This file is a guide to the locations of files within the FreeS/WAN distribution. Everything described here should be on your system once you download, gunzip, and untar the distribution.

This distribution contains two major subsystems

KLIPS
  the kernel code
Pluto
  the user-level key-management daemon

plus assorted odds and ends.

## Top directory

The top directory has essential information in text files:

README
  introduction to the software
INSTALL
  short experts-only installation procedures. More detalied procedures are in installation and configuration HTML documents.
BUGS
  major known bugs in the current release.
CHANGES
  changes from previous releases
CREDITS
  acknowledgement of contributors
COPYING
  licensing and distribution information

## Documentation

The doc directory contains the bulk of the documentation, most of it in HTML format. See the index file for details.

## KLIPS: kernel IP security

KLIPS is KerneL IP Security. It lives in the klips directory, of course.

klips/doc
  documentation
klips/patches
  patches for existing kernel files
klips/test
  test stuff
klips/utils
  low-level user utilities
klips/net/ipsec
  actual klips kernel files
klips/src
  symbolic link to klips/net/ipsec

The "make insert" step of installation installs the patches and makes a symbolic link from the kernel tree to klips/net/ipsec. The odd name of klips/net/ipsec is dictated by some annoying limitations of the scripts which build the Linux kernel. The symbolic-link business is a bit messy, but all the alternatives are worse.

klips/utils
  Utility programs:

eroute
  manipulate IPSEC extended routing tables
klipsdebug
  set Klips (kernel IPSEC support) debug features and level
spi
  manage IPSEC Security Associations
spigrp
  group/ungroup IPSEC Security Associations
tncfg
  associate IPSEC virtual interface with real interface

These are all normally invoked by ipsec(8) with commands such as

            ipsec tncfg arguments

There are section 8 man pages for all of these; the names have "ipsec_" as a prefix, so your man command should be something like:

            man 8 ipsec_tncfg

## Pluto key and connection management daemon

Pluto is our key management and negotiation daemon. It lives in the pluto directory, along with its low-level user utility, whack.

There are no subdirectories. Documentation is a man page, pluto.8. This covers whack as well.

## Utils

The utils directory contains a growing collection of higher-level user utilities, the commands that administer and control the software. Most of the things that you will actually have to run yourself are in there.

ipsec
  invoke IPSEC utilities

ipsec(8) is normally the only program installed in a standard directory, /usr/local/sbin. It is used to invoke the others, both those listed below and the ones in klips/utils mentioned above.

auto
  control automatically-keyed IPSEC connections
manual
  take manually-keyed IPSEC connections up and down
barf
  generate copious debugging output
look
  generate moderate amounts of debugging output

There are .8 manual pages for these. look is covered in barf.8. The man pages have an "ipsec_" prefix so your man command should be something like:

            man 8 ipsec_auto

Examples are in various files with names utils/*.eg

## Libraries

### FreeS/WAN Library

The lib directory is the FreeS/WAN library, also steadily growing, used by both user-level and kernel code.
It includes section 3 man pages for the library routines.

### Imported Libraries

#### LibDES

The libdes library, originally from SSLeay, is used by both Klips and Pluto for Triple DES encryption. Single DES is not used because it is insecure.

Note that this library has its own license, different from the GPL used for other code in FreeS/WAN.

The library includes its own documentation.

#### GMP

The GMP (GNU multi-precision) library is used for multi-precision arithmetic in Pluto's key-exchange code and public key code.

Older versions (up to 1.7) of FreeS/WAN included a copy of this library in the FreeS/WAN distribution.

Since 1.8, we have begun to rely on the system copy of GMP.

# Linux FreeS/WAN Compatibility Guide

Most of this document is quoted directly from the Linux FreeS/WAN mailing list. Thanks very much to the community of testers, patchers and commenters there, especially the ones quoted below but also various contributors we haven't quoted.

## Implemented parts of the IPSEC Specification

In general, do not expect Linux FreeS/WAN to do everything yet. This is a work-in-progress and some parts of the IPSEC specification are not yet implemented.

### In Linux FreeS/WAN

Things we do, as of version 1.9:

- key management methods
  manually keyed
    using keys stored in /etc/ipsec.conf
  automatically keyed
    Automatically negotiating session keys as required. All connections are automatically re-keyed periodically. The Pluto daemon implements this using the IKE protocol.
- Methods of authenticating gateways for IKE
  shared secrets
    stored in /etc/ipsec.secrets
  RSA signatures
    This was new code in 1.3. For details, see pluto(8).
  looking up RSA authentication keys from DNS.
    This was new code in 1.4, and is not yet heavily tested. Note that this technique cannot be fully secure until secure DNS is widely deployed.
- groups for Diffie-Hellman key negotiation
  group 2, modp 1024-bit
  group 5, modp 1536-bit
    We implement these two groups.

  In negotiating a keying connection (ISAKMP SA, Phase 1) we propose both groups when we are the initiator, and accept either when a peer proposes them. Once the keying connection is made, we propose only the alternative agreed there for data connections (IPSEC SA's, Phase 2) negotiated over that keying connection.

- encryption transforms
  DES
    DES is in the source code since it is needed to implement 3DES, but single DES is not made available to users because DES is insecure.
  Triple DES
    implemented, and used as the default encryption in Linux FreeS/WAN.
- authentication transforms
  keyed MD5
    implemented, may be used in IKE or by by AH or ESP transforms.
  keyed SHA
    implemented, may be used in IKE or by AH or ESP transforms.

In negotiations, we propose both of these and accept either.

- compression transforms
  IPComp
    IPComp as described in RFC 2393 has been added for FreeS/WAN 1.6. It is disabled in the default FreeS/WAN kernel configuration because it is new code, not yet fully trusted. Note that Pluto becomes confused if you ask it to do IPComp when the kernel cannot.

  Some difficulties in interopreation are anticipated with this. The RFC says to leave out some things which many compression libraries put in. We do leave these out, but other implementations may not.

All combinations of implemented transforms are supported. Note that some form of packet-level authentication is required whenever encryption is used. Without it, the encryption will not be secure.

### Deliberately ommitted

We do not implement everything in the RFCs because some of those things are insecure. See our discussions of avoiding bogus security.

Things we deliberately omit which are required in the RFCs are:

- null encryption (to use ESP as an authentication-only service)
- single DES
- DH group 1, a 768-bit modp group

Since these are the only encryption algorithms and DH group the RFCs require, it is possible in theory to have a standards-conforming implementation which will not interpoperate with FreeS/WAN. Such an implementation would be inherently insecure, so we do not consider this a problem. Anyway, most implementations sensibly include more secure options as well, so dropping null encryption, single DES and Group 1 does not greatly hinder interoperation in practice.

We also do not implement some optional features allowed by the RFCs:

- aggressive mode for negotiation of the keying channel or ISAKMP SA. This mode is a little faster than main mode, but exposes more information to an eavesdropper.

In theory, this should cause no interoperation problems since all implementations are required to support the more secure main mode, whether or not they also allow aggressive mode.

In practice, it does sometimes produce problems with implementations such as Windows 2000 where aggressive mode is the default. Typically, these are easily solved with a configuration change that overrides that default.

### Not (yet) in Linux FreeS/WAN

Things we don't yet do, as of version 1.91:

- key management methods
  - authenticate key negotiations via local PKI server, but see links to user patches
  - authenticate key negotiations via secure DNS
  - unauthenticated key management, using Diffie-Hellman key agreement protocol without authentication. Arguably, this would be worth doing since it is secure against all passive attacks. On the other hand, it is vulnerable to an active man-in-the-middle attack.
  - opportunistic IPSEC tunnel creation, in which any two IPSEC aware machines can automatically try to negotiate encryption for any communication, subject of course to their local policies. This is a long-term goal of the Linux FreeS/WAN project, but it requires at least one of:
    - a nearly universal PKI
    - widespread use of secure DNS
    - a decision to take the risks of unauthenticated keying
    None of these are in place yet.

  We expect eventually to do it using DNS. The newer versions of BIND provide much of what we need but they are not yet widespread and our code to communicate with them is not ready.

  Update: As of 1.91, we have beta-testable code for opportunistic encryption. See our configuration document.

- encryption transforms

Currently Triple DES is the only encryption method Pluto will negotiate.

No additional encryption transforms are yet implemented, though the RFCs allow them and some other IPSEC implementations support various of them. We are not eager to add more, since they complicate both our work and that of the gateway administrator without any obvious security improvement. We would certainly not want to incorporate any cryptographic method that had inadequate key length or had not been sujected to intensive review over some time.

Rjindael, which just won the AES competition to choose a successor to the DES standard, is an excellent candidate for inclusion in FreeS/WAN. This might be a good project for a volunteer.

- authentication transforms

No optional additional authentication transforms are currently implemented and we do not forsee a need to add any soon.

- Policy checking on decrypted packets

To fully comply with the RFCs, it is not enough just to accept only packets which survive any firewall rules in place to limit what IPSEC packets get in, and then pass KLIPS authentication. That is what FreeS/WAN currently does.

We should also apply additional tests, for example ensuring that all packets emerging from a particular tunnel have sourcen and destination addresses that fall within the subnets defined for that tunnel, and that packets with those addresses that did not emerge from the appropriate tunnel are disallowed.

This will be done as part of the KLIPS rewrite currently in progress. See these links and the design mailing list for discussion.

## Our PF-Key implementation

We use PF-key Version Two for communication between the KLIPS kernel code and the Pluto Daemon. PF-Key v2 is defined by RFC 2367.

The "PF" stands for Protocol Family. PF-Inet defines a kernel/userspace interface for the TCP/IP Internet protocols (TCP/IP), and other members of the PF series handle Netware, Appletalk, etc. PF-Key is just a PF for key-related matters.

Our PF-Key implementation is not yet (mid-July 2000) complete. In particular, it is mostly one-way, used for Pluto to talk to KLIPS but not yet doing much upward communication from kernel to user space. This will change, but is not at the top of our priority list.

### PF-Key portability

PF-Key came out of Berkeley Unix work and is used in the various BSD IPSEC implementations, and in Solaris. This means there is some hope of porting our Pluto(8) to one of the BSD distributions, or of running their photurisd(8) on Linux if you prefer Photuris key management over IKE.

It is, however, more complex than that. The PK-Key RFC deliberately deals only with keying, not policy management. The three PF-Key implementations we have looked at -- ours, OpenBSD and KAME -- all have extensions to deal with security policy, and the extensions are different. There have been discussions aimed at sorting out the differences, perhaps for a version three PF-Key spec. All players are in favour of this, but everyone involved is busy and it is not clear whether or when these discussions might bear fruit.

## Kernels other than 2.0.38 and 2.2.18

We develop and test on:

- Redhat 6.1 with a 2.2.19 kernel.
- Redhat 7.1 with a 2.4.4 kernel.

This is what we recommend.

### Other 2.0.x Intel Kernels

Consider upgrading to the 2.2 kernel series. If you want to stay with the 2.0 series, then we strongly recommend 2.0.39. Some useful security patches were added in 2.0.38.

Various versions of the code have run at various times on most 2.0.xx kernels, but the current version is only lightly tested on 2.0.39, and not at all on older kernels.

Some of our patches for older kernels are shipped in 2.0.37 and later, so they are no longer provided in FreeS/WAN. This means recent versions of FreeS/WAN will probably not compile om anything earlier than 2.0.37.

### 2.2 and 2.4 Kernels

FreeS/WAN 1.0
  ran only on 2.0 kernels
FreeS/WAN 1.1 to 1.8
  ran on 2.0 or 2.2 kernels
  ran on some development kernels, 2.3 or 2.4-test
FreeS/WAN 1.9
  runs on 2.0, 2.2 or 2.4 kernels

In general, we suggest the latest 2.2 kernel or 2.4 for production use. At time of writing (early June 2001, just before our 1.91 release) these are 2.2.19 and 2.4.5.

Of course no release can be guaranteed to run on kernels more recent than it is, so quite often there will be no stable FreeS/WAN for the absolute latest kernel. See the FAQ for discussion.

## Intel Linux distributions other than Redhat

We develop and test on Redhat 6.1 for 2.2 kernels, and on Redhat 7.1 for 2.4, so minor changes may be required for other distributions.

### Redhat 7.0

There are some problems with FreeS/WAN on Redhat 7.0, but they are soluble.

Redhat 7 ships with two compilers.

- Their gcc is version 2.96. Various people, including the GNU compiler developers and Linus, have said fairly emphatically that using this was a mistake. 2.96 is a development version, not intended for production use. In particular, it will not compile a Linux kernel.
- Redhat therefore also ship a separate compiler, which they call kgcc, for compiling kernels.

Kernel Makefiles have gcc as a default, and must be adjusted to use kgcc before a kernel will compile on 7.0. This mailing list message gives details:

    Subject: Re: AW: Installing IPSEC on Redhat 7.0
       Date: Thu, 1 Feb 2001 14:32:52 -0200 (BRST)
      From: Mads Rasmussen <mads@cit.com.br>

    > From www.redhat.com/support/docs/gotchas/7.0/gotchas-7-6.html#ss6.1

    cd to /usr/src/linux and open the Makefile in your favorite editor. You
    will need to look for a line similar to this:

    CC = $(CROSS_COMPILE)gcc -D__KERNEL__ -I$(HPATH)

    This line specifies which C compiler to use to build the kernel. It should
    be changed to:

    CC = $(CROSS_COMPILE)kgcc -D__KERNEL__ -I$(HPATH)

    for Red Hat Linux 7. The kgcc compiler is egcs 2.91.66. From here you can
    proceed with the typical compiling steps.

Check the mailing list archive for more recent news.

### SuSE Linux

SuSE 6.3 and later versions, at least in Europe, ship with FreeS/WAN included.

Here are some notes for an earlier SuSE version.

#### SuSE Linux 5.3

    Date: Mon, 30 Nov 1998
    From: Peter Onion <ponion@srd.bt.co.uk>

    ... I got Saturdays snapshot working between my two SUSE5.3 machines at home.

    The mods to the install process are quite simple.  From memory and looking at
    the files on the SUSE53 machine here at work....

    And extra link in each of the /etc/init.d/rc?.d directories called K35ipsec
    which SUSE use to shut a service down.

    A few mods in /etc/init.d/ipsec  to cope with the different places that SUSE
    put config info, and remove the inculsion of /etc/rc.d/init.d/functions and .
    /etc/sysconfig/network as they don't exists and 1st one isn't needed anyway.

    insert ". /etc/rc.config" to pick up the SUSE config info and use

      if test -n "$NETCONFIG" -a "$NETCONFIG" != "YAST_ASK" ; then

    to replace

      [ ${NETWORKING} = "no" ] amp; exit 0

    Create /etc/sysconfig  as SUSE doesn't have one.

    I think that was all (but I prob forgot something)....

You may also need to fiddle initialisation scripts to ensure that /var/run/pluto.pid is removed when rebooting. If this file is present, Pluto does not come up correctly.

### Slackware

    Subject: Re: linux-ipsec: Slackware distribution
      Date:  Thu, 15 Apr 1999 12:07:01 -0700
      From:  Evan Brewer <dmessiah@silcon.com>

    > Very shortly, I will be needing to install ipsec on at least gateways that
    > are running Slackware. . . .

    The only trick to getting it up is that on the slackware dist there is no
    init.d directory in /etc/rc.d .. so create one.  Then, what I do is take the
    ipsec startup script which normally gets put into the init.d directory, and
    put it in /etc/rc.d and name ir rc.ipsec .. then I symlink it to the file
    in init.d.  The only file in the dist you need to really edit is the
    utils/Makefile, setup4:

    Everything else should be just fine.

A year or so later:

    Subject: Re: HTML Docs- Need some cleanup?
       Date: Mon, 8 Jan 2001
       From: Jody McIntyre <jodym@oeone.com>

    I have successfully installed FreeS/WAN on several Slackware 7.1 machines.
    FreeS/WAN installed its rc.ipsec file in /etc/rc.d.  I had to manually call
    this script from rc.inet2.  This seems to be an easier method than Evan
    Brewer's.

### Debian

    Subject: FreeS/WAN 1.0 on Debian 2.1
       Date: Tue, 20 Apr 1999
      From:  Tim Miller <cerebus+counterpane@haybaler.sackheads.org>

            Compiled and installed without error on a Debian 2.1 system
    with kernel-source-2.0.36 after pointing RCDIR in utils/Makefile to
    /etc/init.d.

            /var/lock/subsys/ doesn't exist on Debian boxen, needs to be
    created; not a fatal error.

            Finally, ipsec scripts appear to be dependant on GNU awk
    (gawk); the default Debian awk (mawk-1.3.3-2) had fatal difficulties.
    With gawk installed and /etc/alternatives/awk linked to /usr/bin/gawk
    operation appears flawless.

The scripts in question have been modified since this was posted. Awk versions should no longer be a problem.

### Caldera

    Subject: Re: HTML Docs- Need some cleanup?
       Date: Mon, 08 Jan 2001
       From: Andy Bradford <andyb@calderasystems.com>

    On Sun, 07 Jan 2001 22:59:05 EST, Sandy Harris wrote:

    >     Intel Linux distributions other than Redhat 5.x and 6.x
    >         Redhat 7.0
    >         SuSE Linux
    >             SuSE Linux 5.3
    >         Slackware
    >         Debian

    Can you please include Caldera in this list?  I have tested it since
    FreeS/Wan 1.1 and it works great with our systems---provided one
    follows the FreeS/Wan documentation. :-)

    Thank you,
    Andy

## CPUs other than Intel

FreeS/WAN has been run sucessfully on a number of different CPU architectures. If you have tried it on one not listed here, please post to the mailing list.

### Corel Netwinder (StrongARM CPU)

    Subject: linux-ipsec: Netwinder diffs
    Date: Wed, 06 Jan 1999
    From: rhatfield@plaintree.com

    I had a mistake in my ipsec-auto, so I got things working this morning.

    Following are the diffs for my changes.  Probably not the best and cleanest way
    of doing it, but it works. . . .

These diffs are in the 0.92 distribution and any snapshot after Feb 20 1999, so these should work out-of-the-box on Netwinder.

### Yellow Dog Linux on Power PC

    Subject:  Compiling FreeS/WAN 1.1 on YellowDog Linux (PPC)
       Date:  11 Dec 1999
       From:  Darron Froese <darron@fudgehead.com>

    I'm summarizing here for the record - because it's taken me many hours to do
    this (multiple times) and because I want to see IPSEC on more linuxes than
    just x86.

    Also, I can't remember if I actually did summarize it before... ;-) I'm
    working too many late hours.

    That said - here goes.

    1. Get your linux kernel and unpack into /usr/src/linux/ - I used 2.2.13.
    <http://www.kernel.org/pub/linux/kernel/v2.2/linux-2.2.13.tar.bz2>

    2. Get FreeS/WAN and unpack into /usr/src/freeswan-1.1
    <ftp://ftp.xs4all.nl/pub/crypto/freeswan/freeswan-1.1.tar.gz>

    3. Get the gmp src rpm from here:
    <ftp://ftp.yellowdoglinux.com//pub/yellowdog/champion-1.1/SRPMS/SRPMS/gmp-2.0.2-9a.src.rpm>

    4. Su to root and do this: rpm --rebuild gmp-2.0.2-9a.src.rpm

    You will see a lot of text fly by and when you start to see the rpm
    recompiling like this:

    Executing: %build
    + umask 022
    + cd /usr/src/redhat/BUILD
    + cd gmp-2.0.2
    + libtoolize --copy --force
    Remember to add `AM_PROG_LIBTOOL' to `configure.in'.
    You should add the contents of `/usr/share/aclocal/libtool.m4' to
    `aclocal.m4'.
    + CFLAGS=-O2 -fsigned-char
    + ./configure --prefix=/usr

    Hit Control-C to stop the rebuild. NOTE: We're doing this because for some
    reason the gmp source provided with FreeS/WAN 1.1 won't build properly on
    ydl.

    cd /usr/src/redhat/BUILD/
    cp -ar gmp-2.0.2 /usr/src/freeswan-1.1/
    cd /usr/src/freeswan-1.1/
    rm -rf gmp
    mv gmp-2.0.2 gmp

    5. Open the freeswan Makefile and change the line that says:
    KERNEL=$(b)zimage (or something like that) to
    KERNEL=vmlinux

    6. cd ../linux/

    7. make menuconfig
    Select an option or two and then exit - saving your changes.

    8. cd ../freeswan-1.1/ ; make menugo

    That will start the whole process going - once that's finished compiling,
    you have to install your new kernel and reboot.

    That should build FreeS/WAN on ydl (I tried it on 1.1).

And a later message on the same topic:

    Subject: Re: FreeS/WAN, PGPnet and E-mail
       Date: Sat, 22 Jan 2000
       From: Darron Froese <darron@fudgehead.com>

    on 1/22/00 6:47 PM, Philip Trauring at philip@trauring.com wrote:

    > I have a PowerMac G3 ...

    The PowerMac G3 can run YDL 1.1 just fine. It should also be able to run
    FreeS/WAN 1.2patch1 with a couple minor modifications:

    1. In the Makefile it specifies a bzimage for the kernel compile - you have
    to change that to vmlinux for the PPC.

    2. The gmp source that comes with FreeS/WAN (for whatever reason) fails to
    compile. I have gotten around this by getting the gmp src rpm from here:

    ftp://ftp.yellowdoglinux.com//pub/yellowdog/champion-1.1/SRPMS/SRPMS/gmp-2.0.2-9a.src.rpm

    If you rip the source out of there - and place it where the gmp source
    resides it will compile just fine.

### Mklinux

One user reports success on the Mach-based micro kernel Linux.

    Subject: Smiles on sparc and ppc
       Date: Fri, 10 Mar 2000
       From: Jake Hill <jah@alien.bt.co.uk>

    You may or may not be interested to know that I have successfully built
    FreeS/WAN on a number of non intel alpha architectures; namely on ppc
    and sparc and also on osfmach3/ppc (MkLinux). I can report that it just
    works, mostly, with few changes.

### Alpha 64-bit processors

    Subject: IT WORKS (again) between intel & alpha :-)))))
       Date: Fri, 29 Jan 1999
       From: Peter Onion <ponion@srd.bt.co.uk>

    Well I'm happy to report that I've got an IPSEC connection between by intel & alpha machines again :-))

    If you look back on this list to 7th of December I wrote...

    -On 07-Dec-98 Peter Onion wrote:
    ->
    -> I've about had enuf of wandering around inside the kernel trying to find out
    -> just what is corrupting outgoing packets...
    -
    -Its 7:30 in the evening .....
    -
    -I FIXED IT  :-))))))))))))))))))))))))))))))))
    -
    -It was my own fault :-((((((((((((((((((
    -
    -If you ask me very nicly I'll tell you where I was a little too over keen to
    -change unsigned long int __u32 :-)  OPSE ...
    -
    -So tomorrow it will full steam ahead to produce a set of diffs/patches against
    -0.91
    -
    -Peter Onion.

In general (there have been some glitches), FreeS/WAN has been running on Alphas since then.

### Sun SPARC processors

Several users have reported success with FreeS/WAN on SPARC Linux. Here is one mailing list message:

    Subject: Smiles on sparc and ppc
       Date: Fri, 10 Mar 2000
       From: Jake Hill <jah@alien.bt.co.uk>

    You may or may not be interested to know that I have successfully built
    FreeS/WAN on a number of non intel alpha architectures; namely on ppc
    and sparc and also on osfmach3/ppc (MkLinux). I can report that it just
    works, mostly, with few changes.

    I have a question, before I make up some patches. I need to hack
    gmp/mpn/powerpc32/*.s to build them. Is this ok? The changes are
    trivial, but could I also use a different version of gmp? Is it vanilla
    here?

    I guess my only real headache is from ipchains, which appears to stop
    running when IPSec has been started for a while. This is with 2.2.14 on
    sparc.

This message, from a different mailing list, may be relevant for anyone working with FreeS/WAN on Suns:

    Subject: UltraSPARC DES assembler
       Date: Thu, 13 Apr 2000
       From: svolaf@inet.uni2.dk (Svend Olaf Mikkelsen)
         To: coderpunks@toad.com

    An UltraSPARC assembler version of the LibDES/SSLeay/OpenSSL des_enc.c
    file is available at http://inet.uni2.dk/~svolaf/des.htm.

    This brings DES on UltraSPARC from slower than Pentium at the same
    clock speed to significantly faster.

### MIPS processors

We know FreeS/WAN runs on at least some MIPS processors because Lasat (who host our freeswan.org web site) manufacture an IPSEC box based on an embedded MIPS running Linux with FreeS/WAN. We have no details.

### Motorola Coldfire

    Subject: Re: Crypto hardware support
       Date: Mon, 03 Jul 2000
       From: Dan DeVault <devault@tampabay.rr.com>

    .... I have been running
    uClinux with FreeS/WAN 1.4 on a system built by Moreton Bay  (
    http://www.moretonbay.com )  and it was using a Coldfire processor
    and was able to do the Triple DES encryption at just about
    1 mbit / sec rate.......  they put a Hi/Fn 7901 hardware encryption
    chip on their board and now their system does over 25 mbit of 3DES
    encryption........ pretty significant increase if you ask me.

## Multiprocessor machines

FreeS/WAN is designed to work on SMP (symmetric multi-processing) Linux machines and is regularly tested on dual processor x86 machines.

We do not know of any testing on multi-processor machines with other CPU architectures or with more than two CPUs. Anyone who does test this, please report results to the mailing list .

The current design does not make particularly efficient use of multiprocessor machines; some of the kernel work is single-threaded. This issue is being addressed in the KLIPS II redesign.

## Support for crypto hardware

Supporting hardware cryptography accelerators has not been a high priority for the development team because it raises a number of fairly complex issues:

- Can you trust the hardware? If it is not Open Source, how do you audit its security? Even if it is, how do you check that the design has no concealed traps?
- If an interface is added for such hardware, can that interface be subverted or misused?
- Is hardware acceleration actually a performance win? It clearly is in many cases, but on a fast machine it might be better to use the CPU for the encryption than to pay the overheads of moving data to and from a crypto board.
- the current KLIPS code does not provide a clean interface for hardware accelerators

That said, we have a report of FreeS/WAN working with one crypto accelerator and some work is going on to modify KLIPS to create a clean generic interface to such products. See this web page for some of the design discussion.

## IP version 6 (IPng)

The Internet currently runs on version four of the IP protocols. IPv4 is what is in the standard Linux IP stack, and what FreeS/WAN was built for. In IPv4, IPSEC is an optional feature.

The next version of the IP protocol suite is version six, usually abbreviated either as "IPv6" or as "IPng" for "IP: the next generation". For IPv6, IPSEC is a required feature. Any machine doing IPv6 is required to support IPSEC, much as any machine doing (any version of) IP is required to support ICMP.

There is a Linux implementation of IPv6 in Linux kernels 2.2 and above. For details, see the FAQ. It does not yet support IPSEC. The USAGI project are also working on IPv6 for Linux.

FreeS/WAN was originally built for the current standard, IPv4, but we are interested in seeing it work with IPv6. Some progress has been made, but at time of writing (February 2001), the job is not complete. For more recent information, check the mailing list .

The first release of FreeS/WAN (1.8) patched for IPv6 support is now available.

### IPv6 background

IPv6 has been specified by an IETF working group. The group's page lists over 30 RFCs to date, and many Internet Drafts as well. The overview is RFC 2460. Major features include:

- expansion of the address space from 32 to 128 bits,
- changes to improve support for
  - mobile IP
  - automatic network configuration
  - quality of service routing
  - ...
- improved security via IPSEC

A number of projects are working on IPv6 implementation. A prominent Open Source effort is KAME , a collaboration among several large Japanese companies to implement IPv6 for Berkeley Unix. Other major players are also working on IPv6. For example, see pages at Sun, Cisco and Microsoft. The 6bone (IPv6 backbone) testbed network has been up for some time. There is an active IPv6 user group.

One of the design goals for IPv6 was that it must be possible to convert from v4 to v6 via a gradual transition process. Imagine the mess if there were a "flag day" after which the entire Internet used v6, and all software designed for v4 stopped working. Almost every computer on the planet would need major software changes! There would be huge costs to replace older equipment. Implementers would be worked to death before "the day", systems administrators and technical support would be completely swamped after it. The bugs in every implementation would all bite simultaneously. Large chunks of the net would almost certainly be down for substantial time periods. ...

Fortunately, the design avoids any "flag day". It is therefore a little tricky to tell how quickly IPv6 will take over. The transition has certainly begun. For examples, see announcements from NTT and Nokia. However, it is not yet clear how quickly the process will gain momentum, or when it will be completed. Likely large parts of the Internet will remain with IPv4 for years to come.

# Interoperation with other IPSEC implementations

The IPSEC protocols are designed to allow interoperation between different implementations. Other sections of this documentation have more detail on:

- the IPSEC protocol specifications
- parts of the protocols implemented or ommitted in FreeS/WAN
- other implementations

FreeS/WAN does interoperate successfully with many other implementations. The ones we know about are listed below.

Of course "the devil is in the details" and the IPSEC protocols have a lot of details. At least one critique has argued that the protocols should be simplified. Various of those details can and do cause difficulties for interoperation. Should you encounter such problems, please let us know via the mailing list. We will likely be able to help you, and your report may be useful both to other users and to the implementation teams.

Note: This file is updated often, whenever I notice an interesting interop report on the mailing list. If you are reading the version that ships with a FreeS/WAN release or is posted on the web, and what you need isn't here, consider downloading the latest snapshot to get the latest version of the doc. Perhaps I've added what you need since the last release.

There is additional information on interoperability testing in our web links section.

## Patches to extend interoperability

Sometimes interoperation requires user-contributed patches or add-ons on the FreeS/WAN end. In general, no patches to the actual IPSEC code are required. The problem is to make FreeS/WAN recognise RSA keys stored in formats other than ours. Each such format needs either a patch to make FreeS/WAN understand that format or a utility to translate it to the FreeS/WAN format.

For example, unmodified FreeS/WAN cannot use RSA keys generated by PGP or keys stored in X.509 certificates, but patches or utilities are available for both those formats. See this list of patches and add-ons .

## Interoperability problems

The IPSEC RFCs are complex and include a number of optional features. There is considerable opportunity for even two correct, standard-conforming, implementations to disagree on details in a way that blocks interoperation. Of course, misinterpretations of the standards and implementation or configuration errors on either end can also foul things up.

That said, FreeS/WAN interoperates successfully with many other implementations. There is a list below.

Known areas where problems may appear are:

- FreeS/WAN does not implement single DES because DES is insecure. Suggestions on what to do if the device you want to talk to has only DES are below.
- FreeS/WAN does not implement Diffie-Hellman group 1 because it it is not entirely clear that this is secure.
- The RFCs define two modes for IKE negotiations -- main mode and aggressive mode. Aggressive mode is slightly faster, but reveals more information to an eavesdropper. Specifically, it lets an eavesdropper know what identities are in use. FreeS/WAN does not implement aggressive mode, so any negotiation another implementation tries that way will fail.

In principle this should not be a problem since main mode support is required in all implementations and aggressive mode is optional. In practice, it is sometimes a problem. Some implementations default to aggressive mode unless you configure them for main mode.

- For automatic keying, the FreeS/WAN default is to provide perfect forward secrecy. We see no reason not to; this is more secure and costs little. Some other implementations, however, turn PFS off by default.

You can turn PFS off in FreeS/WAN with the pfs=no setting in ipsec.conf(5), but if possible we suggest you enable it on the other end instead. That is more secure.

- The IKE protocol allows several types of optional message. Two things happen which are allowed by the RFCs:
  - Some implementations send various optional messages.
  - FreeS/WAN ignores them.
  However, problems may arise if the other end relies on some expected effect of these messages. There are two FAQ questions dealing with this, one on the log message FreeS/WAN gives when ignoring optional payloads and one on the delete SA payload.

The general rule is that to interoperate with FreeS/WAN, the other implementation should be configured for:

- main mode
- triple DES encryption
- Diffie-Hellman Group 2 or 5

This is possible for most implementations.

### Systems that want to use single DES

Linux FreeS/WAN does not support single DES transforms. Neither Pluto's IKE connections nor KLIPS' IPSEC connections can use DES. Since DES is insecure we do not, and will not at any future time, provide it.

DES is, unfortunately, a mandatory part of the IPSEC standard. Despite that, we will not implement DES. We believe it is more important to provide security than to comply with a standard which has been subverted into allowing weak algorithms. See our history and politics section for discussion.

Some implementations may offer DES as the default. In such cases we urge you to change them to Triple DES. If this is not possible, for example because export laws prevent your vendor from offerring you adequate crytography, we urge you to complain vigorously to one or more of:

- your government, especially any department concerned with protecting citizens' privacy or your nation's communication infrastructure
- the vendor
- the embassy of the nation whose laws are problematic for you

Consider using FreeS/WAN instead. PCs are cheap and we deliver 3DES now.

FreeS/WAN does have DES code in it as a sort of historical accident, since we need it to implement our default (currently, our only) block cipher, Triple DES. However, since DES is insecure, we do not provide any interface to that code.

As a matter of project policy, we will not help anyone subvert FreeS/WAN to provide insecure DES encryption .

## Interop HowTo documents

The FreeS/WAN team does not have the resources to test with anything like the full range of other IPSEC implementations out there. Fortunately, some of our users are doing a fine job of filling the gap by providing HowTo information:

- Hans-Jorg Hoxer's HowTo covering interoperation between any two of:
  - FreeS/WAN
  - Open BSD IPSEC
  - Windows 98 with PGPnet
- Jean-Francois Nadeau's practical configurations document covers FreeS/WAN interoperation with
  - Windows 2000 IPSEC
  - NAI PGPnet
  - IRE Safenet SoftPK.
- Oscar Delgado's page has a PDF document covering interop using X.509 certificates between FreeS/WAN and:
  - Windows 2000
  - PGPnet
- Terrandon Communications provide a PDF HowTO on using FreeS/WAN with IRE SafeNet
- Telenor provide a HowTo on FreeS/WAN and Windows 2000
- Carl's Guide for FreeS/WAN and Windows 2000
- Ryan's HowTo for getting PGPnet to connect with FreeS/WAN using x509 certs through a Linksys router, with IPSec passthru enabled.

See also our list of available patches and add-ons .

## Interoperation with specific products

Most of the information in this section is gleaned from the mailing list. For additional information, search one of the list archives.

A large thank you is in order to all the list contributors. This document would not exist without you.

Anyone who has tested with an implementation not listed here, please report results to the mailing list. I generally include the sender's email address when I quote list messages here; "credit where credit is due". If you would prefer that I not do that with yours, please mention that.

### Older versions of FreeS/WAN

Any two versions of FreeS/WAN should interoperate, and many combinations have been tested doing so successfully. In particular, every release is tested against its predecessor before it goes out.

However, if you do encounter a problem involving an older version, we are likely to suggest you upgrade. We do not have the resources to support multiple versions.

The FAQ also discusses this.

### OpenBSD

Two documents we know of cover interoperation between FreeS/WAN and Open BSD IPSEC:

- Hans-Jorg Hoxer's HowTo
- Skyper's guide

This report is from one of the OpenBSD IPSEC developers, a regular participant on our mailing list:

    Subject: spi.c bug
       Date: Tue, 23 Feb 1999
       From: Niklas Hallqvist <niklas@appli.se>

    PS.  I don't know if you have an interop list anywhere, but you should
    know FreeS/WAN interops with OpenBSD both at the IPSec level and at
    the IKE level.

He has also talked of porting NetBSD's isakmpd(8) to Linux, but has (as of late April '99) made no announcement of availability. This would provide an alternative to our pluto(8) daemon with a somewhat different feature set. Our KLIPS kernel code would still be used.

The OpenBSD FAQ includes information on their IPSEC implementation.

### FreeBSD

The only reference we have to IPSEC for FreeBSD says their code was ported from OpenBSD.

Here is a mailing list message on FreeBSD interoperation:

    Subject: Re: Interop with [Free|Open|Net]BSD
       Date: Fri, 29 Dec 2000
       From: Ghislaine Labouret <Ghislaine.Labouret@hsc.fr>

    On Thu, 28 Dec 2000 13:53:01 -0500, Sandy Harris wrote:

    > FreeBSD:
    >
    > For FreeBSD, I find list discussion of 3DES key formats, presumably for manual
    > keying. We have 192-bit, 3 64-bit keys including parity bits, while FreeBSD 4.0
    > used 168-bit, 3 56-bit keys without the parity bits. Has FreeBSD changed this?

    I still don't understand what made Spike Gronim say that KAME wants a
    168 bits key; I have always been using 192 bits keys with KAME and had
    no interoperability problem between KAME and FreeS/WAN using manual
    keying.

    > For auto keying, I find reports of sucessful use of pre-shared secrets, but
    > nothing on RSA authentication.

    I had KAME (20001023 snapshot) and FreeS/WAN 1.6 successfully
    interoperate using both PSK and RSA-sig authentication. The config
    files, certificates and test keys used are available online:
    http://www.hsc.fr/ipsec/ipsec2000/kame/
    http://www.hsc.fr/ipsec/ipsec2000/freeswan/
    Not much details though, as this is just a report and not a how-to. Will
    improve it if I can find spare time.

    > Does FreeBSD support that?

    KAME can use RSA-sig and can either exchange certificates online or get
    them from a file. I tested the latter. No test with the X.509 patch for
    FreeS/WAN yet, though that's in my short term plans too.

    > Are the key formats compatible, or has anyone written translation code?

    KAME wants the keys inside certificates, in PEM format. To extract the
    keys for FreeS/WAN I used the fswcert utility, but it can be done "by
    hand" using openssl.

### NetBSD

NetBSD has an IPSEC implementation, described in this FAQ.

### Cisco Routers

Useful pages on Cisco sites include:

- VPN support
- sample configurations

Here is a mailing list message with subject "FreeS/WAN and Cisco 3030 VPN Concentrator" and an attached MS-Word document on the setup.

A sample FreeS/WAN configuration, used in testing with Cisco at an interop conference, is in another list message. Unfortunately, it does not give the matching Cisco configuration.

Here is our first interop success report:

    Subject: cisco <-> pluto IKE interop is here........
       Date: Thu, 28 Jan 1999
       From: Ian Calderbank

    Ok, tried todays pluto (28 jan) snapshot against a (wait for it) 3des
    cisco box, one with some more serious grunt for benchmarking when the time
    comes.

    And the good news is that pluto and cisco's IKE seem to interoperate. At
    the end of things both devices seem to be happy that they have IKE and
    IPSEC SA's. I can't send any traffic over it cos klips seems to be broken
    (peter seems to be on the case), but fundamentally, pluto seems to be
    interoperable with cisco for SA negotiation.

    I've attached some ipsec barf output - pluto still complains a few times,
    but it gets there :-)

A later message from Ian:

    This configuration is provided as-is and with no assistance or guarantee
    that it works whatsover. In particular your attention is drawn to the versions
    of operating systems and IPSEC that were used in the test. Configurations
    for later versions of freeswan and cisco IOS may well be different.

    Cisco router: 3640 (R4700 processor), ios 12.0(2a)T1), 3DES IPSEC feature set
    ( you do need the 3des version).
    Linux box: P150, freeswan 29/jan/99 snapshot, Redhat 5.2, kernel 2.0.36.
    Interconnect: 10 Base T.
    Algorithm: ESP 3des/md5

    CPU loadings:
    Cisco 3640 : 98%
    Freeswan P150 : load average: 0.08, 0.06, 0.01

    Throughput: 1.1 Mbit/sec at the application layer, approx 1.2Mbit/sec, 100 packet/sec on
    the external network. There were no chokes present, so the limit would
    appear to be the 3640, given it was running near flat out.

    --------------------------

    Freeswan config:
    /etc/ipsec-auto

    auto    ipsec-router-test
            type=tunnel
            left=x.x.x.x
    # x.x.x.x = linux box public ip address
            right=y.y.y.y
    # y.y.y.y = router public ip address
            rightsubnet=192.168.2.0/24
    # private network behind the router - host to which throughput testing was done is here.
            keyexchange=ike
            encrypt=yes
            authenticate=no
            pfs=no
            lifetime=8h

    ----------------------------

    Cisco Router config:

    crypto isakmp policy 1
     encr 3des
     hash md5
     authentication pre-share
    crypto isakmp key SECRET-VALUE address x.x.x.x
    crypto ipsec transform-set 3DES-MD5 esp-3des esp-md5-hmac
    crypto map TEST 1 ipsec-isakmp
     set peer x.x.x.x
     set transform-set 3DES-MD5
     match address 101
    access-list 101 permit ip 192.168.2.0 0.0.0.255 host x.x.x.x
    interface
    crypto map TEST

A page on Cisco's site gave this list (early Jan 2000, before new US export regulations went into effect):

    | Triple DES Encryption for IPSec
    |
    | ...
    |
    | This feature is supported only on the following platforms:
    |
    |     1720
    |     2600 Series
    |     3600 Series
    |     4000 Series
    |     4500 Series
    |     AS5300 Series
    |     7200 Series
    |     7500 Series

A message from another user about using RSA keys with Cisco:

    From: jrussi@uol.com.br
    Subject: Re:Re: Re:Re: [Users] RSA public key and Cisco (3640)
    Date: Sat, 2 Jun 2001

    We use Cisco IOS 12.1.5(T) and freeswan 1.8

    Here an example on how I copied the key from cisco:

    Key Data:
      117C311E 16192D86 8886C71D 11111115 11138B11 31881241 11C7E23B D6DB22
      18DEC1BD....

    Will become

    0x117C311E16192D868886C71D1111111511138B113188124111C7E23BD6DB2218DEC1BD...

    We used at least 1024 bits long keys.

    But it doesn´t matter. The problem is that cisco doesn´t agree with the RSA schema from freeswan, I think. In Cisco, rsasig is to use with a CA, and rsaencript did not work as well.

    My case is worse than it. My first intention was to use freeswan in a road warrior config. I really need to use CA, as Cisco needs a fix address to use rsa public key. The public key to cisco is always associated to an IP address ou FQDN. I quit. Will try the X509 patch and the Open CA software.

    Deyvi
    >>(off list)
    >
    >Yes, I was just going to mention that the Cisco's key should be in
    >ipsec.conf (just received your correction).
    >
    >I think that I have the Cisco side configured correctly ( I can't be sure
    >because I can't test against the Freeswan).
    >
    >Starting from having the IPsec tunnel working with pre-share, I did the
    >following on the Cisco side:
    >
    >#config t
    >(config)# crypto key pubkey-chain rsa
    >(config-pubkey-chain)# addressed-key

    >(config-pubkey-key)# key-string
    >(config-pubkey-key)#

    >(config-pubkey-key)#quit
    >(config-pubkey-chain)#exit
    >
    ># config t
    >(config)# crypto isakmp policy 1
    >(config-isakmp)# no authentication pre-share
    >(config-isakmp)# authentication rsa-sig
    >(config-isakmp)# exit
    >
    >How long is your RSA key that was generated on the Cisco? I tried copying
    >the key out of the 3640 and pasting it into ipsec.conf, removing the spaces
    >and adding a '0x' in the front. I get the 'key too small' error still. What
    >version of freeswan are you using?
    >
    >I'm using Freeswan 1.9 w/ IOS 12.1(6).
    >
    >
    >----- Original Message -----
    >From:

    >To: "James Rowe"

    ;

    >Cc:

    >Sent: Thursday, May 31, 2001 5:15 PM
    >Subject: Re:Re: [Users] RSA public key and Cisco (3640)
    >
    >
    >> We had no problems with the key. Just be sure to remove the blank spaces
    >from the key (general key) that cisco generates.
    >>
    >> Just remove the blank, put all together as a long line (all the lines to a
    >single line) and add a "0x" at the key that Cisco give to you, and paste to
    >ipsec.secrets.
    >>
    >> The public key from FreeSwan, you just remove the "0x" and paste to the
    >command line at cisco. They will not complain about the keys.
    >>
    >> But my problem is with the proposal configured at Cisco. What to you think
    >to use? I tried "authentication rsasig" and "rsaencrip" with no results.
    >Cisco always sends me an "No proposal choosen" error message.
    >>
    >> I road an old message from someone called Brian here at this list, where
    >he says that FreeSwan will not accept authentication rsaencript from Cisco.
    >But rsasig is to use with a CA certification. So my question is: is it
    >possible to use Cisco with public RSA keying, without a CA? The thread ended
    >without an answer to it.
    >>
    >> Deyvi
    >> >>Hello,
    >> >
    >> >I am working on the same issue. I have pre-shared working, but would like
    >to
    >> >use RSA public keys. It seems that the Cisco key is too short. When
    >starting
    >> >IPsec in init.d, it says that the Cisco key is not secure because it is
    >less
    >> >than 512 bits, even tough the key is really over 768 bits. Claudia thinks
    >> >this is a parsing problem and suggested to take a look at the source
    >code.
    >> >
    >> >Some pointers that I have found while working on this:
    >> >
    >> >You must add a '0x' to the front of the Cisco key when entering it into
    >> >Freeswan, and remove the '0x' when entering the freeswan key into the
    >Cisco
    >> >3640.
    >> >
    >> >The case of the hexadecimal letters in the key does not matter. Thinking
    >> >that freeswan stopped reading the key when it encountered the first
    >> >uppercase letter in the Cisco key (freeswan keys are lowercase, Cisco's
    >are
    >> >uppercase), I changed everything to lowercase. Didn't help.
    >> >
    >> >I'll let you know if I make any progess on this. I'd appreciate if you
    >would
    >> >let me know if you get this working. Thanks.
    >> >
    >> >-- Jim Rowe
    >> >
    >> >----- Original Message -----
    >> >From:

    >> >To:

    >> >Sent: Thursday, May 31, 2001 2:52 PM
    >> >Subject: [Users] RSA public key and Cisco (3640)
    >> >
    >> >
    >> >> Does anyone have a sucessful Cisco config file to use in a
    >freswan-cisco
    >> >conection using RSA public key?
    >> >>
    >> >> We were able to setup a pre-shared conection, but would like to try
    >public
    >> >keying.

### Nortel (Bay Networks) Contivity switch

There is one known issue in FreeS/WAN-to-Contivity interoperation. Recent versions of FreeS/WAN no longer support DH group 1 for key exchange. Older versions of Contivity software support nothing else. Group 2 was added in more recent releases. So:

- older FreeS/WANs, such as 1.5, will work with any Contivity software. Key exchange will be done using DH Group 1. This may not be secure.
- current FreeS/WANs will work only with recent Contivity releases supporting DH Group 2. Contivity 3.5 is one such release.

We recommend using the latest Contivity release.

Some messages from the mailing list:

    Subject: Contivity Extranet Switch
       Date: Fri, 11 Jun 1999
       From: Matthias David Siebler <msiebler@nortelnetworks.com>
    Reply-To: msiebler@alum.mit.edu
    Organization: Nortel Networks

    More interoperability results:

    I successfully established a tunnel with a Nortel (formerly Bay (formerly New Oak)) Contivity
    Extranet Switch running the latest release versions.

    The CES is running V2.50 of the software and the Linux server is running V1.0.0 of the Free/SWAN
    code on a RedHat 5.2 unit with the kernel upgraded to 2.0.36-3

    I am using IKE with 3DES-HMAC-MD5

    Note however, that tunnels cannot yet be configured as client tunnels since Free/SWAN does not yet
    support aggressive mode.  Hopefully, that will arrive soon, which would allow remote users to
    connect to a CES using the Free/SWAN code as clients.

and apparently Nortel want their product to work with FreeS/WAN:

    Subject: Is FreeSwan 3.1 a legitamate ipsec implementation when compared to its commercial competitors?
       Date: Tue, 02 May 2000
       From: Bill Stewart <bill.stewart@pobox.com>

    Nortel's Contivity IPSEC server has a formal policy of interoperability
    with FreeS/WAN.   I was quite pleased to hear it when they last talked to us,
    and it makes sense in their business environment, since they let you use
    their WinXX client software free, so this gives them support for Linux
    clients.

A more recent mailing list report is:

    Subject: Nortel Contivity and Free-S/WAN
       Date: Wed, 7 Mar 2001
       From:  "JJ Streicher-Bremer" <jj@digisle.net>

    OK, here is a very brief nuts and bolts breakdown on how to get this
    combo working.  I want to thank everyone at Free-S/WAN and everyone on
    the list for your help in getting this to work.

    Connecting FreeS/WAN to the Nortel Networks Contivity Extranet Switch:

    What you need:
    FreeS/WAN v1.5 and Contivity ver 2.5 - 3.5 (might work with earlier
    versions, but I have not tested it with this config)
    or
    FreeS/WAN v1.8 and COntivity ver 3.5 (the 3.5 version supports Diffe
    Hilman group 2 key exchange)

    What to do:
    1 - Configure the Contivity:
       Set up a branch office tunnel group with the following settings:

            Connectivity:
            Nailed Up: Disabled
            Access Hours: Anytime
            Call Admission Priority: Highest Priority
            Forwarding Priority: Low Priority
            Idle Timeout: 00:00:00
            Forced Logoff: 00:00:00
            RSVP: Disabled
            RSVP: Token Bucket Depth: 3000 Bytes
            RSVP: Token Bucket Rate: 28 Kbps
            Branch Office Bandwidth Policy:
            - Committed Rate: 56 Kbps
            - Excess Rate: 128 Kbps
            - Excess Action: Mark

            Encryption:
            - ESP - Triple DES with SHA1 Integrity: Enabled
            - ESP - Triple DES with MD5 Integrity: Enabled
            - ESP - 56-bit DES with SHA1 Integrity: Disabled
            - ESP - 56-bit DES with MD5 Integrity: Disabled
            *IKE Encryption and Diffie-Hellman Group: Triple DES with Group
    2 (1024-bit prime)
            Vendor ID: Disabled
            Perfect Forward Secrecy: Enabled
            Compression: Disabled
            Rekey Timeout: 08:00:00
            Rekey Data Count:  (None)
            *ISAKMP Retransmission Interval: 16
            *ISAKMP Retransmission Max Attempts: 4

            Set up a branch office tunnel inside this new group with the
    following settings:

            Endpoint Addresses
            Local - Public address of your COntivity
            Remote - Your Free-S/WAN interface Address
                    Tunnel Type - IPSEC
            IPSEC Authentication - Text Pre-Shared Key
                    One note here, I have had some trouble trying to use HEX
    or Non alphanumeric chars in this key.

            Under IP:
            Static Routing
            Local - networks you want to be able to access through the
    tunnel
            Remote - networks that will be allowed through the tunnel
            NAT - None

       Get routing setup on your office network:
            You will need to get a routing entry that will point all traffic
    bound for your home network (the one that will be acciessible through
    the tunnel) to the internal interface of the contivity system.

       Configure Free-S/WAN:
            Install, compile, and test Free-S/WAN
            Edit ipsec.conf for your new tunnel:
    --------------------------------------------------------
    ipsec.conf --
    config setup
            interfaces="ipsec0=eth1"
            forwardcontrol=no
            klipsdebug=none
            plutodebug=none
            manualstart=
            plutoload=%search
            plutostart=%search
            plutowait=no
    conn net1
            type=tunnel
            auto=start
            auth=esp
            authby=secret
            keyexchange=ike
            keylife=1h
            keyingtries=1
            pfs=yes
            left=10.0.0.2
            leftnexthop=10.0.0.1
            leftsubnet=10.0.1.0/24
            right=172.16.0.2
            rightsubnet=172.16.1.0/24
    conn net2
            type=tunnel
            auto=start
            auth=esp
            authby=secret
            keyexchange=ike
            keylife=1h
            keyingtries=1
            pfs=yes
            left=10.0.0.2
            leftnexthop=10.0.0.1
            leftsubnet=10.0.1.0/24
            right=172.16.0.2
            rightsubnet=172.16.2.0/24

    ipsec.secrets --
    10.0.0.2 172.16.0.2 "Your big secret"
    ---------------------------------------------

    The above config is for this imaginary network:

             +------+
    10.0.1.1 |      |10.0.0.2   10.0.0.1++ Internet
    ---------|      |-------------------++===========
             +------+            Home Router
             Free-S/WAN host

    Internet ++    172.16.0.2####         172.16.1.0/24 These
    =========++--------------####---------172.16.2.0/24 are here somewhere
       Office Router       Contivity

       This has worked for me.  I am still having trouble with the tunnels
    dying after about 30-40 minutes of non-use.  Don't know what that is
    about, but I'll keep you posted.

### Raptor Firewall

#### Raptor 5 on NT (old info)

       Subject: Interoperability with Raptor 5 (Success!)
       Date: Wed, 06 Jan 1999 16:19:27 -0500
       From: Chuck Bushong <chuckb@chandler-group.com>

    I don't know if this is useful information for anyone, but I have
    successfully established a VPN between RedHat 5.1 (kernel 2.0.34) running
    FreeS/WAN 0.91 and NT4 running Raptor 5.  However, Pluto does not appear
    compatible with the Raptor IKE implementation. . . .

    Subject: RE: linux-ipsec: Interoperability with Raptor 5 (Success!)
    Date: Thu, 28 Jan 1999 17:22:55 -0500
    From: Chuck Bushong <chuckb@chandler-group.com>

    ... this VPN (at least the klips end) has been up under minimal
    utilization for three weeks plus without interruption.  The
    machine seems very stable.  Pat yourself on the back, gentlemen.
    Your beta release is more stable than certain companies' shipping
    product.

    Keep up the good work.

#### Raptor 6 on Solaris

    Subject: Re: successful interop. with Raptor 6.02
       From: "Charles G. Griebel" <cggrieb@biw.com>
       Date: Tue, 25 Jul 2000

    On Thu, Jul 20, 2000 at 12:04:40PM -0700, Kevin Traas wrote:
    > Great!  I'm just about to start looking into this as well, so any
    > docs/info you can provide would be *greatly* appreciated.  Immortalize
    > yourself!  Get something written and added to the compatibility.html
    > file.  Many will thank you.

    Can't be that hard.  I'm just a freeswan newbie who hasn't even done a FS

    FS
    tunnel yet :)

    Anyway, I hope you find this helpful.

    Chock

    -------------------------------------------------------------------------------

    Automatically keyed 3DES VPN between Raptor 6.02 on Solaris 2.6 (left) and
       FreeS/WAN 1.5 on 2.2.16 Intel (right)

    FreeS/WAN (right) information:
    -----------------------------

    ipsec.conf
    ----------
    config setup
            interfaces="ipsec0=ppp0"    # change to suite
            klipsdebug=
            plutodebug=
            plutoload=sample
            plutostart=sample

    conn sample
            left=10.0.0.1
            leftnexthop=10.0.0.2
            leftsubnet=192.168.0.0/24
            right=10.1.1.1
            rightnexthop=10.1.1.1
            rightsubnet=172.16.1.0/24
            auto=add
            keyexchange=ike
            pfs=no
            lifetime=8h
            esp=3des-md5-96

    ipsec.secrets
    -------------
    # note I haven't verified that underscores will actually work
    10.0.0.1 10.1.1.1: PSK "some_long_secret_with_plenty_of_chars"

    Raptor 6.02 (left) information:
    ------------------------------
    Key Profiles:
        Name: left-external-kp-dynamic
        Type: Dynamic
        Profile Describing: local entity
        Gateway: 10.1.1.1
        Identification Type: Address
        Identification: 10.1.1.1
        ISAKMP Hash Method: MD5
        ISAKMP Authentication: Shared_Key
        Shared Secret: some_long_secret_with_plenty_of_chars
        Time Expiration: 1080

        Name: right-external-kp-dynamic
        Type: Dynamic
        Profile Describing: remote entity
        Gateway: 10.0.0.1
        Identification Type: Address
        Identification: 10.0.0.1

    Secure Subnets:
        Name: left-ss-dynamic
        Address: 192.168.0.0
        Netmask: 255.255.255.0
        Key Profile: left-ss-dynamic

        Name: right-ss-dynamic
        Address: 172.16.1.0
        Netmask: 255.255.255.0
        Key Profile: right-ss-dynamic

    Secure Tunnel:
        Name: left-to-right-tunnel
        Entity A: right-ss-dynamic
        Entity B: left-ss-dynamic
        Encapsulation: ISAKMP
        Filter: [none]
        Pass traffic through proxies: [unchecked]
        Use Authentication Header: [unchecked]
        Use Encryption Header: [checked]
        Data Integrity Algorithm: MD5
        Data Privacy Algorithm: 3DES

        [Advanced settings]
        Data volume timeout: 2100000
        Lifetime timeout: 480
        Inactivity timeout: 0
        Transport mode: [unchecked]
        Perfect forward secrecy: [unchecked]
        Proxy: [checked]

    ----
    Notes:
    I made the addresses fictitious RFC1918 addresses.
    I haven't tried PFS.
    I had problems getting an SA with manual keying -- I think it may be with the
     SPI's.

#### Raptor manual keying

A mailing list suggestion from FreeS/WAN technical lead Henry Spencer:

    > In the Raptor settings, there are 2 sets of data (1 for each end). Each set
    > contains an SPI, 3 DES Keys and 1 MD5 hash. I only know how to include one
    > set, how do I include the other set? Is the other set needed?

    They may be using different keys for each direction, which is a bit
    unusual for manual keying, but not impossible.  The simplest thing is
    probably to just give it two identical sets of data -- that should work.
    FreeS/WAN has provisions for asymmetric keys etc. in manual keying, but
    that stuff is lightly documented and lightly tested.

### Gauntlet firewall GVPN

    Subject:  Successful interop: FreeS/WAN 1.7

     Gauntlet Firewall GVPN 5.5
       Date: Tue, 21 Nov 2000

    Sending the following to the list, at Hugh's request.

    -----Original Message-----
    From: Reiner, Richard
    Sent: Tuesday, November 21, 2000 11:34 AM
    To: 'hugh@mimosa.com'

    Hugh,

    > Good.  But we don't think that you should be using our IPCOMP just
    > yet.  It is flaky :-(

    I've seen no anomalies, although "allow ipcomp" is on at the Gauntlet
    end.  Looking at my ipsec.conf I actually find no refereence to ipcomp.
     I presume it is disabled by default.  In addition, reviewing my logs
    both on the Gauntlet end and the Linux end, I see nothing I can
    interpret as an indication that ipcomp was enabled during negotiation.
    So I have to correct my previous posting - I believe the link is *not*
    using ipcomp.

    > This is interesting and we'd love a more complete writeup.  It should
    > get incorporated into our interop documentation.

    Here are the relevant bits from ipsec.conf:

    config setup
            interfaces=%defaultroute
            klipsdebug=none
            plutodebug=none
            plutoload=%search
            plutostart=%search
            uniqueids=yes

    conn freeswan17-gauntlet55
            auto=start
            type=tunnel
            left=1.1.1.1
            leftnexthop=1.1.1.2
            leftsubnet=10.0.1.0/24
            right=3.3.3.3
            rightnexthop=3.3.3.4
            rightsubnet=10.0.2.0/24
            authby=secret
            keyexchange=ike
            ikelifetime=480m
            auth=esp
            esp=3des-md5-96
            keylife=480m
            keyingtries=8
            pfs=no
            rekeymargin=9m
            rekeyfuzz=25%

    All settings on the Gauntlet side are the same (not shown here, as GUI
    screenshots are hard to show in ASCII... and the textual format that is
    generated by the Gauntlet GUI is ugly in the extreme).

    Note that ikelifetime is 1440m by default on the Gauntlet end, but
    freeswan does not support this value (max appears to be 480m), thus the
    Gauntlet end is also set to 480m to match freeswan's value.

    Also worth noting: I am using the excellent Seawall scripts to manage
    ipchains configuration on the freeswan end.  It automatically generates
    a correct set of firewall rules for the link (along with doing many
    other convenient things).

For more information on Seawall (the Seattle Firewall), see that project's home page on Sourceforge.

### Checkpoint Firewall-1

A PDF HowTo for connecting FreeS/WAN and this product can be downloaded from the vendor's site or browsed at a VPN mailing list site.

The mailing list reports success with this combination, but also some problems. Search the archives for the full story.

Here is one message, about what seems to be the biggest problem:

    Subject: Re: Pb establishing connection from FW1/3DES/SP2 with freeswan 1.5 - ACTE 2
       Date: Tue, 6 Feb 2001
       From: Claudia Schmeing <claudia@freeswan.org>

    > Thanx to Michael and Claudia, but this doesn't work from VPN1 to linux (as
    > linux to VPN1 is OK).
    ...

    > I think that VPN1 doesn't send "192.168.1.0/24" but "192.168.1.20/32" and,
    > as Claudia said, IPSEC SA need to match Exactly.

    I don't know about the rules on the VPN-1. You'll have to rely on people
    with applicable experience there...

    > Is it possible that freeswan doesn't do the inclusion process (ie if he
    > receive 192.168.1.20/32, i doesn't match that this is include in
    > 192.168.1.0/24) ?

    Yes, that's correct. It needs to match exactly, and inclusion is not
    part of this process.

    > Btw why VPN/1 send 192.168.1.20/32 and not 192.168.1.20/24 (the value that
    > Freeswan is waiting for)? A bug?

    I think Michael may be able to help you with this.

    > Have i a way to force Freeswan to do the "inclusion" (ie accept
    > 192.168.1.20/32 as a part of 192.160.1.20/24, even if the 2 IPSEC Sa
    > doesn't match exactly) ?

    No, but...
    Another strategy is to accept the fact that the Checkpoint
    proposes separate connections for each machine. If you define
    and add each of these connections on the Linux FreeS/WAN side, then
    Linux FreeS/WAN ought to accept the Checkpoint's proposals.

    The only possible difficulty with this strategy is that I don't know
    how Linux FreeS/WAN handles the concept of overlapping tunnels. I
    believe, though, that these tunnels can coexist, and if for any
    packet there are two options, a more general and a less general, the
    packet will be handled by the more specific tunnel. You would need
    to do a little testing to ensure you understand the behaviour and
    that this does actually solve your problem.

    I think it would be simplest to try to get the Checkpoint to propose the
    more general tunnel. Since I don't recall having seen this problem before,
    I suspect the simpler solution is doable.

### Redcreek Ravlin

We have reports of successful interoperation at an interop conference, but there is also a mailing list thread discussing difficulties some users have encountered.

### SSH Sentinel

The vendor's web site has configuration examples for use with FreeS/WAN.

The vendor seems serious about interop with us. Here is a message one of their staff posted on our list:

    From: Jussi Torhonen <jt@ssh.com>
    Organization: SSH Communications Security Corp - http://www.ssh.com
    Subject: [Users] SSH Sentinel VPN client public beta #3 now available
    Date: Thu, 31 May 2001

    Hello, FreeS/WAN community !

    SSH Communications Security Corp has released a new public beta #3
    version of SSH Sentinel VPN client for Windows. We've got a lot of
    reports also from FreeS/WAN community and with that feedback we've
    improved interoperability and stability.

    For example PFS (Perfect Forward Secrecy in IKE rekey) can now be used
    between SSH Sentinel and FreeSWAN, and if using that user contributed
    X.509 patch and exporting the certificate from SSH Sentinel, now those
    -----[BEGIN|END] CERTIFICATE----- headers/footers are properly included
    in the exported PEM formatted certificate, so it can be imported to
    FreeSWAN with fswcert utility and OpenSSL tools.

    Thank you a lot for your feedback, colleagues !

    You can get that new public beta #3 and PDF formatted User Manual from
    ftp://ftp.ssh.com/pub/sentinel/ or via website
    http://www.ipsec.com/products/sentinel/beta/register.html

    For more information about the product, please check our website
    http://www.ipsec.com

    We eagerly want to make SSH Sentinel as the best VPN client on the
    market. If you want to contact our support, please send e-mail to
    sentinel-support@ssh.com or fill up our feedback form at
    http://www.ipsec.com/support/sentinel/beta_report.html

    Best regards,
    Jussi Torhonen, SSH Sentinel Team
    Kuopio, Finland

### F-Secure VPN for Windows

       Subject: linux-ipsec: Identification through other than IP number
       Date: Tue, 13 Apr 1999
       From: Thomas Bellman <bellman@signum.se>

    ... Currently we are trying to interop FreeS/WAN
    with F-Secure VPN+ Client 4.0 (for MS Windows), and as long as
    the Windows machine has a fix IP address, and are initiating the
    IKE negotiations, things are working well.  However, when the IP
    address is changing, it doesn't work. ...
    (I'll try to write something up about the problems we are having
    when Pluto is initiatior in another message.)

### Watchguard

Watchguard make a Linux-based firewall product. Ipchains author Rusty Russell thanks them for support and recommends them in one of his HowTos . On the other hand, some comments on our mailing list about the Watchguard product have been quite unfavourable. See, for example, this archive message.

Watchguard do not use FreeS/WAN in their product. They have their own IPSEC implementation.

We have had mailing list reports of successful interoperation between FreeS/WAN and the Watchguard firewall, using manually keyed connections. The user could not get automatically keyed connections to work; the message below explains this.

Here is some mail from a Watchguard employee about interoperation:

    Subject: FreeS/WAN and WatchGuard Firebox interop
       Date: Mon, 18 Dec 2000
       From: Max Enders <menders@watchguard.com>

    I was recently given the task of testing IPSec interoperability
    with our product, the Firebox. I just wanted to let you know that
    I had success with a manual keyed tunnel. Here's what I used for
    my test:

    RedHat Linux 6.2
    Linux 2.2.18 i686 unknown
    Linux FreeS/WAN 1.8
    "Trusted" interface: 192.168.0.1/24
    "External" interface: 192.168.1.1/24

    Firebox II FastVPN
    WatchGuard Live Security System v4.5
    Trusted interface: 192.168.2.1/24
    External interface: 192.168.1.2/24

    Because FreeS/WAN does not implement single DES, a dynamic keyed
    tunnel will not work. Our product strictly uses DES for main mode.
    We hope to address this in a future release. Here are instructions
    for configuring the Firebox:

    Open the Policy Manager and create a new IPSec gateway. Set the Key
    Negotiation Type to manual and enter the FreeS/WAN box's external
    IP address for the Remote Gateway IP. Configure a new tunnel with
    a unique SPI. Select 3DES-CBC for Encryption and MD5-HMAC for
    Authentication. Make an Encryption Key and Authentication Key.
    Copy the values and save them for configuration of the FreeS/WAN box.
    Configure a routing policy and any necessary services as you normally
    would.

    Here's how I configured FreeS/WAN:

    Modifications to /etc/ipsec.conf:

    Under the "config setup" section, add:

    manualstart=firebox

    At the end of the file, add the following connection:

    conn firebox
    left=192.168.1.1
    leftsubnet=192.168.0.0/24
    right=192.168.1.2
    rightsubnet=192.168.2.0/24
    spi=0x101
    esp=3des-md5-96
    espenckey=0x515b0875793e3708517c3d4554012f7c0273375e51572a31
    espauthkey=0x072649041c2c0d452f7c15407576522f

    The spi used here should match the Firebox's. Note that the Policy Manager
    expects an SPI in decimal, not hexadecimal. The espenckey value should be
    0x and the Encryption Key you're using on the Firebox. Likewise for
    espauthkey and the Authentication Key on the Firebox.

A user comments:

    Subject: RE: Freeswan
       Date: Wed, 7 Feb 2001
       From: "Patrick Poncet" <pponcet@vaxxine.com>

    It's working!!!

    Voila...  I wish to thank all the FreeS/WAN for putting out such a great
    product out!  And also Philippe PAULEAU who pioneered interoperability
    between FreeS/WAN and Watchguard Firebox II and therefore showed me that my
    efforts would not be wasted!...

    Yes indeed FreeS/WAN to WatchGuard Firebox only works in manual keying mode
    and the best way to generate keys is to have the firebox generate the keys,
    then copy and paste into the ipsec.conf file on the FreeS/WAN side (don't
    forget to prefix the keys with '0x' in your ipsec.conf file.

    Also keep in mind that the SPI is in decimal on the Firebox side and HEX on
    the FreeS/WAN side!!!  We spent 4 hours on fixing this HEX-DEC issue only :)

### Xedia Access Point/QVPN

       Subject: linux-ipsec: Interoperability result
       Date: Mon, 15 Mar 1999 18:08:12 -0500
      From: Paul Koning <pkoning@xedia.com>

    Here's another datapoint for the "FreeS/WAN interoperability
    database".

    I tested 0.92 against the Xedia Access Point/QVPN product, using
    dynamic keying (i.e., Pluto at work).

    Results: it works fine so long as you ask for 3DES.  DES and no-crypto
    modes don't work when Pluto is involved.

    I did limited data testing, which seemed to be fine.  No performance
    numbers yet, could do that if people are interested.

    Any questions, please ask.

            paul

### PGP Mac and Windows IPSEC Client

Since version 6.5, the PGP products from PGP Inc. have included an IPSEC client program.

Here is the first message about it to our mailing list, from a senior PGP employee:

       Subject: linux-ipsec: PGPnet interoperable with FreeSWAN
       Date: Mon, 05 Apr 1999 18:06:13 -0700
       From: Will Price <wprice@cyphers.net>
        To:  linux-ipsec@clinet.fi

    Network Associates announced PGP 6.5 today.  It includes a new product
    PGPnet which is a full IKE/IPSec client implementation.  This product
    is for Windows and Macintosh.  I just wanted to send a brief note to
    this list that the product was compatibility tested with FreeSWAN
    prior to its release, and the tests were successful!
    [snip]
    - --
    Will Price, Architect/Sr. Mgr., PGP Client Products
    Total Network Security Division
    Network Associates, Inc.

One version is downloadable at no cost for non-commercial use. See our links. That version does not support subnets.

Several of the user-written HowTos mentioned above cover interoperation between PGPnet and FreeS/WAN.

A more recent post from the same PGP Inc staff member pointed out:

    Make sure you're using PGP 7.0 or later as the key parser was improved
    in that release.  (PGP 7.0.1 was just released)

Various users have reported various successes and problems talking to PGPnet with FreeS/WAN. There has also been a fairly complex discussion of some fine points of RFC interpretation between the implementers of the two systems. Check an archive of our mailing list for details.

A post summarising some of this, from our Pluto programmer:

       Subject: PGPnet 6.5 and freeswan
       Date: Sun, 16 Jan 2000
       From: "D. Hugh Redelmeier" <hugh@mimosa.com>

    | From: Yan Seiner
    |
    | OK, I'm stumped.  I am trying to configure IPSEC to support road
    | warriors using PGPnet 6.5.
    |
    | I've set up everything as per the man pages on the ipsec side.
    |
    | I've set up everything on the PGPnet side per the docs for that package.
    |
    | Pluto fails with this:
    |
    | Jan 16 08:14:11 aphrodite Pluto[26401]: "homeusers" #8: no acceptable
    | Oakley Transform
    |
    | and then it terminates the connection.

    As far as I can tell/remember, there are three common ways that PGPnet
    and FreeS/WAN don't get along.

    1. PGPnet proposes a longer lifetime for an SA than Pluto is willing
       to accept.

    2. After rekeying (i.e. after building a new SA bundle because the old
       one is about to expire), FreeS/WAN immediately switches to the new
       one while PGPnet continues using the old

    3. FreeS/WAN defaults to expecting Perfect Forward Secrecy and PGPnet
       does not.

    Perhaps you are bumping into the first.  In any case, look back
    in the log to see why Pluto rejected each transform

Some advice from the mailing list:

       Subject: Re: Secure Gate Fails- PGPNet & FreeSwan
       Date: Wed, 28 Jun 2000
       From: Andreas Haumer <andreas@xss.co.at>

    I have a PGPnet setup running with FreeS/WAN working as secure
    gateway. It works quite fine, except for a re-negotiation problem
    I'm currently investigating, and in fact I have it running on some
    test equipment here right now!

    As I tried _several_ different non-working configuration settings
    I think I know the exact _one_ which works... :-)

    Here's my short "HOWTO":

    FreeS/WAN version: snap1000jun25b
    PGPnet: PGP Personal Privacy, Version 6.5.3
    Linux: 2.2.16 with some patches

    Network setup:
    =============

    internal subnet [192.168.x.0/24]
    |
    |        [192.168.x.1]
    secure gateway with FreeS/WAN
    |        [a.b.c.x]
    |
    |        [a.b.c.y]
    router to internet
    |
    |   Internet
    |
    |        [dynamically assigned IP address]
    road-warrior with PGPnet

    Configuration of FreeS/WAN:
    ==========================

    a) /etc/ipsec.conf

    config setup
            interfaces=%defaultroute
            klipsdebug=none
            plutodebug=none
            plutoload=%search
            plutostart=%search

    conn %default
            keyingtries=1
            authby=secret
            left=a.b.c.x
            leftnexthop=a.b.c.y

    conn gw-rw
            right=0.0.0.0
            auto=add

    conn subnet-rw
            leftsubnet=192.168.x.0/24
            right=0.0.0.0
            auto=add

    b) /etc/ipsec.secrets

    a.b.c.x 0.0.0.0: "my very secret secret"

    Note: If you are running ipchains on your secure gateway,
    you have to open the firewall for all the IPsec packets
    and also for traffic from your ipsec interface!
    Don't masquerade the IPsec traffic!

    Check your logfiles if the firewall is blocking some
    important packets!

    Configuration of PGPnet:
    =======================

    (note that there is an excellent description, including
    screenshots of PGPnet, on <http://jixen.tripod.com/>)

    In short, do the following:

    Launch the PGPnet configuration tool and set defaults options
    =============================================================

    Start - Program - PGP - PGPnet
    View - Options
    General Panel :
      Expert Mode
      Allow communications with unconfigured hosts
      Require valid authentication key
      Cache passphrases between logins
      IKE Duration : 6h
      IPsec : 6h
    Advanced panel :
      Selected options :
        Ciphers : Tripple DES
        Hashes : MD5
        Diffie-Hellman : 1024 and 1536
        Compression : LZS and Deflate
      Make the IKE proposal :
        Shared-Key - MD5 - 3DES -1024 bits on top of the list (move up)
      Make the IPSec proposal :
        NONE - MD5-TrippleDES -NONE on top of the list (move up)
      Select Perfect Forward Secrecy = 1024 bits
    Press OK

    Create the connection's definition.
    ==================================

    In the Hosts panel, ADD
      Name : Enter a name for the right gateway
      IPaddress : Enter its IP address visible to the internet (a.b.c.x)
      Select Secure Gateway
      Set shared Paraphrase : enter you preshared key
      Identity type : select IP address
      Identity : enter 0.0.0.0
      Remote Authentication : select Any valid key
    Press Ok
      Select the newly created entry for the right gateway and click ADD,
    YES
      Name : Enter a name for the central subnet
      IP address : Enter its network IP address (192.168.x.0)
      Select Insecure Subnet
      Subnet Mask : enter its subnetmask (255.255.255.0)
    Press OK, YES, YES

    This should be it. Note that with this configuration there is
    still this re-keying problem: after 6 hours, the SA is expired
    and the connection fails. You have to re-connect your connection
    with PGPnet.

and a note from the team's tech support person:

    Date: Thu, 29 Jun 2000
    From: Claudia Schmeing

    There is a known issue with PGPNet which I don't see mentioned in the docs.
    It's likely related to this one, that you note on the site:

    >2. After rekeying (i.e. after building a new SA bundle because the old
    >   one is about to expire), FreeS/WAN immediately switches to the new
    >   one while PGPnet continues using the old

    The issue is: When taking down and subsequently recreating a connection,
    it can appear to come up, but it is unusable because PGPNet continues
    to use an old SA, which Linux FreeS/WAN no longer recognizes. The solution is
    to take down the old connection using PGPNet, so that it will then
    use the most recently generated SA.

### IRE Safenet/SoftPK

IRE have an extensive line of IPSEC products, including firewall software with IPSEC, and hardware encryption devices for LAN or modem links. Their Soft-PK is a Win 98 and NT client.

Quite a few people seem to be using this with FreeS/WAN and, judging by mailing list reports, to be getting good results. Several documents are available:

- PDF HowTo titled FreeS/WAN 1.8 <--> IRE Safenet SoftPK 5.1.0 Road-Warrior VPN Configuration Guide from Terradon Communications.
- PDF document from Red Baron Consulting.
- IRE-to-FreeS/WAN section of Jean-Francois Nadeau's configuration document

Some messages from the mailing list:

    Subject: Re: Identification through other than IP number
    Date:  Fri, 23 Apr 1999
    From:  Tim Miller <cerebus+counterpane@haybaler.sackheads.org>

    Randy Dees writes:

     > Anyone know of a low-cost MS-Win client that interoperates and does not
     > require purchasing a server license to get it?

            SafeNet/Soft-PK from IRE (http://www.ire.com) is a low-cost
    client (though I don't have the exact cost available at the moment).
    I've got it running on an NT4 workstation and it interoperates nicely
    (in transport mode, will try tunnel later) with FreeS/WAN.  It's also
    ICSA IPsec certified.

A later report from a different user:

    Subject: Interop.. testing. WIN32 client : Success Story
    Date: Thu, 11 Nov 1999
    From: Jean-Francois Nadeau <jna@microflex.ca>

    You can add IRE's products in the supported, well working (and cheap)
    WIN32 client. I tested it (SafeNet SoftPK 3DES) against Freeswan 1.0
    and 1.1 in both tunnel and transport mode in a RoadWarrior configuration.  No bug.

    The software is light, non-intrusive and transparent for the user.....defenitly,
    thats a good one.

    The tunnel is establish on demand.

    Using shared keys....but hope to use certificates with it soon (well,
    when Freeswan will ;)).

A recent report with some setup details:

    Subject: RE: linux-ipsec: PGPnet and Freeswan one more time...
       Date: Sat, 16 Dec 2000
      From: "Tim Wilson" <timwilson@mediaone.net>

    Here are some details about using the IRE SafeNet Soft/PK client with a
    FreeSwan gateway.

    I applied the x509 patch to Pluto according to the instructions. I use the
    "leftcert" and "rightcert" keywords in the ipsec.conf file. This causes
    FreeSwan to read the public keys and identities from the cert files. The
    identities wanted and used by FreeSwan will then be the DNs in the certs.

    I used OpenSSL to generate keys and certs and to sign certs. When generating
    the gateway cert, you should *not* enter an e-mail address because it turns
    out that confuses Soft/PK. Also, Andreas Steffan tells me that you want to
    keep the cert short to avoid fragmentation, so use a 1024-bit RSA key and
    succinct names.

    The FreeSwan gateway cert goes in /etc/ipsec.d/, the gateway private key is
    extracted from the key file using fswcert (part of the x509 patch) and
    pasted into /etc/ipsec.secrets, and a DER version of the gateway cert goes
    in /etc/x509cert.der. This is all according to the instructions that
    accompany the x509 patch.

    The Windows client is of course running Soft/PK in this case. I generated a
    private key and cert for the client on the Linux machine using OpenSSL. I
    created a pkcs12 file containing the client's private key and cert, which I
    put on a floppy and imported into Soft/PK. I also imported the gateway cert
    into Soft/PK (you can either import a self-signed cert for the gateway or
    the self-signed cert for the CA that signed the gateway cert--either works).

    Soft/PK allows you to configure practically everything for the connection.
    Here are the main points to watch for:

    On the first panel you have to set the peer identities. The gateway will
    identify itself using the DN in the gateway cert. So of course you have to
    configure Soft/PK to look for the correct DN. There's no problem with this
    as long as you didn't enter an e-mail address in the gateway cert. Just
    check "Connect using Secure Gateway tunnel", set ID type to "Distinguished
    Name", and enter the correct info in the dialog box.

    In "My identity" just select the client cert that you imported in pcks12
    format. Soft/PK apparently identifies itself with the DN from the cert,
    which is exactly what FreeSwan is looking for.

    In "Security Policy", you want Main mode and make the PFS setting agree with
    whatever FreeSwan is doing (FreeSwan uses PFS by default). If you use PFS I
    believe you must use DH group 2 as FreeSwan doesn't like group 1.

    Phase 1 Authentication must be "RSA signatures" and 3DES plus either MD5 or
    SHA-1 (I used MD5 but I believe FreeSwan accepts either). I left the
    lifetime unspecified. Also you must select DH group 2 because I believe that
    FreeSwan will not accept group 1.

    Phase 2 also must use 3DES and MD5 or SHA-1. I used no compression and only
    ESP and no AH, haven't tried other choices.

    Hope this helps.

### Borderware

### Freegate

    Subject: ipsec interoperability FYI
       Date: Sun, 02 May 1999
       From: Sean Rooney <sean@coldstream.ca>

    we've been doing some basic interoperability testing of the following;

    PGP NT VPN 6.5 and freeswan both seem to work reasonably well with
    Borderware 6.0 and freegate 1.3 beta. [as well as eachother]

    more details coming soon.

### Timestep

       Subject: TimeStep Permit/Gate interop works!
       Date: Thu, 10 Jun 1999
       From: Derick Cassidy <dcthebrain@geek.com>

    Just a quick note of success.  TimeStep Permit/Gate (2520) and
    Free/Swan (June 4th snapshot) interoperate!

    I have them working in AUTO mode, with IKE.  IPSec SA's are negotiated
    with 3DES and MD5.

    Here are the configs and a diagram for both configs.

    left subnet---| Timestep | --- internet --- | Linux box |

    The left subnet is defined as the red side of the timestep box.
     This network definition MUST exist in the Secure Map.

    On the Linux box:

    ipsec.conf

    conn timestep
            type=tunnel
            left=209.yyy.xxx.6
            leftnexthop=209.yyy.xxx.1
            leftsubnet=209.yyy.xxx.128/25
            right=24.aaa.bbb.203
            rightnexthop=24.aaa.bbb.1
            rightsubnet=24.aaa.bbb.203/32
            keyexchange=ike
            keylife=8h
            keyingtries=0

    In the TimeStep permit/gate Secure Map

    begin static-map
            target "209.yyy.xxx.128/255.255.255.128"
            mode   "ISAKMP-Shared"
            tunnel "209.yyy.xxx.6"
    end

    In the TimeStep Security Descriptor file

    begin security-descriptor
            Name    "High"
            IPSec   "ESP 3DES MINUTES 300 or ESP 3DES HMAC MD5 MINUTES 300"
            ISAKMP  "IDENTITY PFS 3DES MD5 MINUTES 1440
                                    or DES MD5 MINUTES 1440"
    end

    The timestep has a shared secret for 24.aaa.bbb.203/255.255.255.255
    set in the Shared Secret Authentication tab of Permit/Config.

### Shiva/Intel LANrover

A web page with Shiva compatibility information.

### Sun Solaris

       Subject: Re: FreeS/WAN and Solaris
       Date: Tue, 11 Jan 2000
       From: Peter Onion <Peter.Onion@btinternet.com>

    Slowaris 8 has a native (in kernel) IPSEC implementation.

    I've not done much interop testing yet, but I seem to rememeber we got a manual
    keyed connection between it and FreeSwan a few months ago.

### Sonicwall

    Subject: Re: FreeS/WAN and SonicWall
         Date: Mon, 5 Feb 2001
         From: "Dilan Arumainathan" <dilan_a@impark.com>

    ***************************************************
    I know I HAVE TO write the mini-howto - but here is the beginning
    ***************************************************

    Here is my Sonicwall configuration for my working connection:

    conn testauto
            left=x.x.x.x
            leftnexthop=x.x.x.x
            right=y.y.y.y
            rightnexthop=y.y.y.y
            rightsubnet=10.1.20.0/24
    #You need to set the Unique Firewall Identifier to the parameter that you
    #use as the rightid.

### Radguard

Here are some mailing list comments from FreeS/WAN tech support person Claudia Schmeing on this:

    It certainly has been possible to interop between Radguard VPN gateways and
    past Linux FreeS/WAN versions, as is evidenced by
    http://www.opus1.com/vpn/atl99display.html, as well as my own interop results
    from San Diego this year. There have been no major changes since SD that
    I would foresee affecting this.

    The Radguard team said that their VPN gateway will not respond to a peer
    request with PFS (Perfect Forward Secrecy) on, but it *will* successfully
    establish such a connection with Linux FreeS/WAN when Radguard is the
    initiator. Since PFS is a desirable feature in terms of cryptographic
    security, this asymmetry may frustrate efforts to provide a connection that
    is both as reliable as secure as possible.

    While it's not clear that rekeying will present a problem, I suspect that
    some fine tuning of the key life parameters may be needed. Unfortunately
    I was unable to do additional tests on this topic.

    Due to the PFS issue, when trying to maintain a connection with PFS,
    you may need to set the rekeying times shorter on the radguard side,
    in order to ensure that it is always the initiator.

### Windows clients

Quite a number of client programs for IPSEC on Windows are available. Many of them are listed in this piece of list mail:

     Subject: Re: Searching Windows95/98 and NT4.0 Clients for FreeS/WAN
        From: Claudia Schmeing <claudia@coldstream.ca>
        Date: Wed, 12 Jul 2000

    F-Secure VPN+
    -------------
    for Win 95, 98 and NT 4.0
    http://www.datafellows.com/products/vpnplus

    Checkpoint SecureRemote VPN-1 4.1
    ---------------------------------
    for Win 95, 98 and NT
    http://www.checkpoint.com/techsupport/freedownloads.html

    Raptor Firewall, Raptor MobileNT 5.0
    -------------------------------------
    Mobile NT is a "Client"* for Win 95, 98 (except SE), First Edition Windows NT
    up to Service Pack 4. It ships with DES; triple DES may be available as an
    add-on depending on your location.

    Firewall is for Win NT 4.0 or Win 2000.
    http://www.axent.com

    IRE SafeNet SoftPK
    ------------------
    a "Client" for Win 95, 98 and NT 4.0 *
    http://www.ire.com

    Xedia's AccessPoint QVPN "Client" or "Builder"
    ----------------------------------------------
    "Builder" is for NT
    "Client" is for Win 98 *
    http://www.xedia.com

    * "Client" in this context indicates software that does not support a subnet
    behind its end of the connection.

That mail omits the PGPnet client because the user asking the question already knew of it. The SSH Sentinel client, released since the above message, is another possibility. Both of those have members of the vendor's staff active on our mailing list, an excellent sign for both interoperability and support.

We also know of some Windows IPSEC clients not mentioned above:

- Lucent
- Ashleylaurent

No doubt there are others we don't know of.

### NT domains vs. tunnels

There has been some mailing list discussion of making NT domains work across FreeS/WAN tunnels.

Robert Cotran asked:

    > I have a VPN setup between two subnets (192.168.1.x and 192.168.2.x).  I
    > would like to be able to join the NT domain on 192.168.1.x from the
    > 192.168.2.x subnet.  Is this possible?  Do I have to forward specific ports
    > to do this?  I've already set up WINS entries for all the machines, so
    > accessing computers by their NetBIOS names works perfectly.  Please let me
    > know about this domain thing.  Thanks!

Dilan Arumainathan answered:

    All you need to do is to:

    1. Enable NetBIOS over TCP.
    2. Create a "lmhosts" file and enter the address of a BDC or a PDC like
        192.168.1.[x]  [Your PDC/BDC servername] #PRE #DOM:[Your Domain Name]
        eg. 192.168.1.1 MYOWNPDC #PRE #DOM:DENSI-NT

    3. Reboot if necessary.

and Sebastien Pfieffer provided a slightly different answer:

    For a trust relationship to work between NT domains in different
    (sub)nets all domain controllers of the 1st domain have to know about
    all controllers of the other domain.
    Either you use the described LMHOSTS entry for every domain controller
    of both domains or consider setting up WINS service(s).

We suspect that in some cases it may be more complex than that. See the discussion of Linux services and Windows 2000 below and the Interop HowTo documents listed above.

### Windows 2000

Windows 2000 ships with an IPSEC implementation built in. There may be restrictions. We have had mailing list reports that only the server version will act as a gateway, working with a subnet behind it, and other versions offer only "client" functionality, with no subnet. We are unclear on details.

Some versions of Windows 2000 ship with only weak encryption. You need to upgrade them with the strong encryption pack, available either via the Windows 2000 update service or from Microsoft's web site.

Windows 2000 IPSEC sometimes exhibits remarkably odd behaviour. It will allow you to configure it for 3DES only, then ignore your settings and fall back to single DES in some circumstances. Microsoft have said they will fix this. See this Wired article.

#### Other Linux services related to Win 2000

Windows 2000 also uses a number of other security mechanisms which have Linux equivalents. To integrate well with Windows 2000, you may need to look at several open source projects other than FreeS/WAN:

- Windows 2000 builds L2TP tunnels over (some of?) its IPSEC connections. There is a Linux L2TP Daemon.
- Kerberos authentication is used in Windows 2000.
  - MIT Kerberos site
  - introductory document
  - Kerberos links page

The Windows 2000 Kerberos implementation includes proprietary modifications. This is a security worry since it is by no means clear that the modified version remains secure. It also creates interoperation problems. Microsoft have released documentation on their modifications, but only under a license that hampers attempts either to audit their code for security flaws or to build other implementations that interoperate with it.

- Samba is a Linux implementation of the Windows SMB protocol, allowing disk sharing and other network services
- tipxd, the Tunelling IPX Daemon, encapsulates IPX for transport over IP.

Here is a mailing list message, from FreeS/WAN team tech support person Claudia Schmeing, discussing Windows 2000 and L2TP:

    You write,

    > I want some information about IPsec with L2TP.
    > I'm going to build the IPsec tunnel on the L2TP tunnel.
    > Is it strange?
    > Is there any case like this already implemented?

    It's used, but rarely. In many cases, IPSec alone is sufficient.

    In this thread, Timo Teras reports that he configured the L2TP/IPSec
    hybrid with Win2k. He gives some pointers.
    http://www.sandelman.ottawa.on.ca/linux-ipsec/html/2000/11/msg00545.html

    See also John P. Eisenmenger's report on his own experiences at:
    http://www.sandelman.ottawa.on.ca/linux-ipsec/html/2001/02/msg00195.html

#### FreeS/WAN-to-Win2000 interop

As for IPSEC interoperation between Windows 2000 and FreeS/WAN, there are several web sites listed under Interop HowTo documents above.

Here is a discussion from the mailing list:

    From: "Jean-Francois Nadeau" <jna@microflex.ca>
    Subject: Win2000 IPsec  interop. in tunnel mode
    Date: Tue, 29 Feb 2000

    This was a pain.... but it worked. ;)

    Win2000 Server against Freeswan 1.1 in tunnel mode is a success.

    My Setup

    Freeswan :
    Kernel 2.2.12 running Freeswan 1.1
    Using 3DES-MD5 and PreShared Keys.

    Win2000
    M$ Win2000 Advanced server patched for 3DES

    Here's the setup for the Win2000 Server.

    Open an MMC with the IPsec Security policy editor snap-in.
    Create a new IP Security Policy.
    Create 2 IP SECURITY RULES. One for inbound traffic and one for outbound trafic (see below)
    Create 2 IP FILTERS. One for inbound traffic and one for outbound trafic (see below)
    Assign the inbound IP SECURITY RULE to the inbound IP FILTERS, same for outbound.
    Select both IP SECURITY RULES.
    Select your IP Security Policy, right click and ASSIGN.

    We need an example to clarify that !@#! logic :

    In freeswan :

    Conn Interop_Testing
    Left=1.2.3.4
    Leftsubnet=10.0.0.0/8
    Right=9.8.7.6
    Rightsubnet=192.168.0.0/24

    In Win2000

    IP Security Policy : Interop_Testing

    **********
    1st IP Security rule : Left_to_Right
            IP Filter  List : Left_to_Right
                    Source Address = 1.2.3.4
                    Destination Address = A specific Subnet = 192.168.0.0 255.255.255.0
            Filter Action : Request Security
            Connections type : All connections
            Tunnel Settings : Endpoint = 9.8.7.6
            Authentication Method = PreSharedKey=yourkey
    ***********

    **********
    2nd IP Security rule : Right_to_Left
            IP Filter  List : Right_to_Left
                    Source Address = 9.8.7.6
                    Destination Address = A specific Subnet = 10.0.0.0 255.0.0.0
            Filter Action : Request Security
            Connections type : All connections
            Tunnel Settings : Endpoint = 1.2.3.4
            Authentication Method = PreSharedKey=yourkey
    ***********

    HINTS :

    Do not use mirroring in your IP filters.
    Move your main proposal to the top (in my case 3DES-MD5)
    Enable PFS.

    It worked... but a RoadWarrior configuration doesnt seems to be
    possible here (must specify both Endpoints and 0.0.0.0 is not acceptable).

    Jean-Francois Nadeau
    Microlfex.

The RoadWarrior problem has since been solved. RSA authentication has been added to FreeS/WAN since the above message was posted.

# History and politics of cryptography

Cryptography has a long and interesting history, and has been the subject of considerable political controversy.

## Introduction

### History

The classic book on the history of cryptography is David Kahn's The Codebreakers. It traces codes and codebreaking from ancient Egypt to the 20th century.

Diffie and Landau Privacy on the Line: The Politics of Wiretapping and Encryption covers the history from the First World War to the 1990s, with an emphasis on the US.

#### World War II

During the Second World War, the British "Ultra"project achieved one of the greatest intelligence triumphs in the history of warfare, breaking many Axis codes. One major target was the Enigma cipher machine, a German device whose users were convinced it was unbreakable. The American "Magic" project had some similar triumphs against Japanese codes.

There are many books on this period. See our bibliography for a few, or try a (web or library) search on "Ultra" and "Enigma". Two books I particularly like are:

- Andrew Hodges has done a superb biography of Alan Turing, a key player among the Ultra codebreakers. Turing was also an important computer pioneer. The terms Turing test and Turing machine are named for him, as is the ACM's highest technical award.
- Neal Stephenson's Cryptonomicon is a novel with cryptography central to the plot. Parts of it take place during WW II, other parts today.

Bletchley Park, where much of the Ultra work was done, now has a museum and a web site.

The Ultra work introduced three major innovations.

- The first break of Enigma was achieved by Polish Intelligence in 1931. Until then most code-breakers had been linguists, but a different approach was needed to break machine ciphers. Polish Intelligence realised this, recruited some clever young mathematicians, and succeeded in cracking the "unbreakable" Enigma. When war came in 1939, the Poles told their allies about this, putting Britain on the road to Ultra. The British also adopted a mathematical approach.
- Machines were extensively used in the attacks. First the Polish "Bombe" for attacking Enigma, then British versions of it, then machines such as Collosus for attacking other codes. By the end of the war, some of these machines were beginning to closely resemble digital computers. After the war, a team at Manchester University, several old Ultra hands included, built one of the world's first actual general-purpose digital computers.
- Ultra made codebreaking a large-scale enterprise, producing intelligence on an industrial scale. This was not a "black chamber", not a hidden room in some obscure government building with a small crew of code-breakers. The whole operation -- from wholesale interception of enemy communications by stations around the world, through large-scale code-breaking and analysis of the decrypted material (with an enormous set of files for cross-referencing), to delivery of intelligence to field commanders -- was huge, and very carefully managed.

So by the end of the war, Allied code-breakers were expert at large-scale mechanised code-breaking. The payoffs were enormous.

#### Postwar and Cold War

The wartime innovations were enthusiastically adopted by post-war and Cold War signals intelligence agencies. Presumably many nations now have some agency capable of sophisticated attacks on communications security, and quite a few engage in such activity on a large scale.

America's NSA, for example, is said to be both the world's largest employer of mathematicians and the world's largest purchaser of computer equipment. Such claims may be somewhat exaggerated, but beyond doubt the NSA -- and similar agencies in other countries -- have some excellent mathematicians, lots of powerful computers, sophisticated software, and the organisation and funding to apply them on a large scale. Details of the NSA budget are secret, but there are some published estimates.

Changes in the world's communications systems since WW II have provided these agencies with new targets. Cracking the codes used on an enemy's military or diplomatic communications has been common practice for centuries. Extensive use of radio in war made large-scale attacks such as Ultra possible. Modern communications make it possible to go far beyond that. Consider listening in on cell phones, or intercepting electronic mail, or tapping into the huge volumes of data on new media such as fiber optics or satellite links. None of these targets existed in 1950. All of them can be attacked today, and almost certainly are being attacked.

The Ultra story was not made public until the 1970s. Much of the recent history of codes and code-breaking has not been made public, and some of it may never be. Two important books are:

- Bamford's The Puzzle Palace, a history of the NSA
- Hager's Secret Power, about the Echelon system -- the US, UK, Canada, Australia and New Zealand co-operating to monitor much of the world's communications.

Note that these books cover only part of what is actually going on, and then only the activities of nations open and democratic enough that (some of) what they are doing can be discovered. A full picture, including:

- actions of the English-speaking democracies not covered in those books
- actions of other more-or-less sane governments
- the activities of various more-or-less insane governments
- possibilities for unauthorized action by government employees

might be really frightening.

#### Recent history -- the crypto wars

Until quite recently, cryptography was primarily a concern of governments, especially of the military, of spies, and of diplomats. Much of it was extremely secret.

In recent years, that has changed a great deal. With computers and networking becoming ubiquitous, cryptography is now important to almost everyone. Among the developments since the 1970s:

- The US gov't established the Data Encryption Standard, DES standard, a block cipher for cryptographic protection of unclassfied documents. It has also been widely used in industry.
- Public key cryptography was invented by Diffie and Hellman.
- Academic conferences such as Crypto and Eurocrypt began.
- Several companies began offerring cryptographic products: RSA, PGP, the many vendors with PKI products, ...
- Cryptography appeared in other products: operating systems, word processors, ...
- Network protocols based on crypto were developed: SSH, SSL, IPSEC, ...
- Crytography came into widespread use to secure bank cards, terminals, ...
- The US government replaced DES with the much stronger Advanced Encryption Standard, AES

This has led to a complex ongoing battle between various mainly government groups wanting to control the spread of crypto and various others, notably the computer industry and the "cypherpunk" crypto advocates, wanting to encourage widespread use.

Steven Levy has written a fine history of much of this, called Crypto: How the Code rebels Beat the Government -- Saving Privacy in the Digital Age.

The FreeS/WAN project is to a large extent an outgrowth of cypherpunk ideas. Our reasons for doing the project can be seen in these quotes from the Cypherpunk Manifesto:

> Privacy is necessary for an open society in the electronic age. ...

> We cannot expect governments, corporations, or other large, faceless organizations to grant us privacy out of their beneficence. It is to their advantage to speak of us, and we should expect that they will speak. ...

> We must defend our own privacy if we expect to have any. ...

> Cypherpunks write code. We know that someone has to write software to defend privacy, and since we can't get privacy unless we all do, we're going to write it. We publish our code so that our fellow Cypherpunks may practice and play with it. Our code is free for all to use, worldwide. We don't much care if you don't approve of the software we write. We know that software can't be destroyed and that a widely dispersed system can't be shut down.

> Cypherpunks deplore regulations on cryptography, for encryption is fundamentally a private act. ...

> For privacy to be widespread it must be part of a social contract. People must come and together deploy these systems for the common good. ...

To quote project leader John Gilmore:

> We are literally in a race between our ability to build and deploy technology, and their ability to build and deploy laws and treaties. Neither side is likely to back down or wise up until it has definitively lost the race.

If FreeS/WAN reaches its goal of making opportunistic encryption widespread so that secure communication can become the default for a large part of the net, we will have struck a major blow.

### Politics

The political problem is that nearly all governments want to monitor their enemies' communications, and some want to monitor their citizens. They may be very interested in protecting some of their own communications, and often some types of business communication, but not in having everyone able to communicate securely. They therefore attempt to restrict availability of strong cryptography as much as possible.

Things various governments have tried or are trying include:

- Echelon, a monitor-the-world project of the US, UK, NZ, Australian and Canadian signals intelligence agencies. See this collection of links and this story on the French Parliament's reaction.
- Others governments may well have their own Echelon-like projects. To quote the Dutch Minister of Defense, as reported in a German magazine:

  > The government believes not only the governments associated with Echelon are able to intercept communication systems, but that it is an activity of the investigative authorities and intelligence services of many countries with governments of different political signature.

  Even if they have nothing on the scale of Echelon, most intelligence agencies and police forces certainly have some interception capability.
- NSA tapping of submarine communication cables, described in this article
- A proposal for international co-operation on Internet surveillance.
- Alleged sabotage of security products by the NSA (the US signals intelligence agency).
- The German armed forces and some government departments will stop using American software for fear of NSA "back doors", according to this news story.
- The British Regulation of Investigatory Powers bill. See this web page. and perhaps this cartoon.
- A Russian ban on cryptography
- Chinese controls on net use.
- The FBI's carnivore system for covert searches of email. See this news coverage and this risk assessment. The government had an external review of some aspects of this system done. See this analysis of that review. Possible defenses against Carnivore include:
  - PGP for end-to-end mail encryption
  - secure sendmail for server-to-server encryption
  - IPSEC encryption on the underlying IP network
- export laws restricting strong cryptography as a munition. See discussion below.
- various attempts to convince people that fundamentally flawed cryptography, such as encryption with a back door for government access to data or with inadequate key lengths, was adequate for their needs.

Of course governments are by no means the only threat to privacy and security on the net. Other threats include:

- industrial espionage, as for example in this news story
- attacks by organised criminals, as in this large-scale attack
- collection of personal data by various companies.
  - for example, consider the various corporate winners of Privacy International's Big Brother Awards.
  - Zero Knowledge sell tools to defend against this
- individuals may also be a threat in a variety of ways and for a variety of reasons
- in particular, an individual with access to government or industry data collections could do considerable damage using that data in unauthorized ways.

One study enumerates threats and possible responses for small and medium businesses. VPNs are a key part of the suggested strategy.

We consider privacy a human right. Our objective is to help make privacy possible on the Internet using cryptography strong enough not even those well-funded government agencies are likely to break it. If we can do that, the chances of anyone else breaking it are negliible.

### Links

Many groups are working in different ways to defend privacy on the net and elsewhere. Please consider contributing to one or more of these groups:

- the EFF's Privacy Now! campaign
- the Global Internet Liberty Campaign
- Computer Professionals for Social Responsibility

For more on these issues see:

- Steven Levy (Newsweek's chief technology writer and author of the classic "Hackers") new book Crypto: How the Code Rebels Beat the Government--Saving Privacy in the Digital Age
- Simson Garfinkel (Boston Globe columnist and author of books on PGP and Unix Security) book Database Nation: the death of privacy in the 21st century
- an interview with Eblen Morgan (general counsel to the Free Software Foundation and a professor at Columbia Law School) on the "encryption wars".

See also the bibliography and our list of web references on cryptography law and policy.

### Outline of this section

The remainder of this section includes two pieces of writing by our project leader

- his rationale for starting this
- another discussion of project goals

and discussions of:

- why we do not use DES
- cryptography export laws
- why government access to keys is not a good idea
- the myth that short keys are adequate for some security requirements

and a section on press coverage of FreeS/WAN.

## From our project leader

FreeS/WAN project founder John Gilmore wrote a web page about why we are doing this. The version below is slightly edited, to fit this format and to update some links. For a version without these edits, see his home page.

### Swan: Securing the Internet against Wiretapping

My project for 1996 was to secure 5% of the Internet traffic against passive wiretapping. It didn't happen in 1996, so I'm still working on it in 1997, 1998, and 1999! If we get 5% in 1999 or 2000, we can secure 20% the next year, against both active and passive attacks; and 80% the following year. Soon the whole Internet will be private and secure. The project is called S/WAN or S/Wan or Swan for Secure Wide Area Network; since it's free software, we call it FreeSwan to distinguish it from various commercial implementations. RSA came up with the term "S/WAN". Our main web site is at http://www.freeswan.org/. Want to help?

The idea is to deploy PC-based boxes that will sit between your local area network and the Internet (near your firewall or router) which opportunistically encrypt your Internet packets. Whenever you talk to a machine (like a Web site) that doesn't support encryption, your traffic goes out "in the clear" as usual. Whenever you connect to a machine that does support this kind of encryption, this box automatically encrypts all your packets, and decrypts the ones that come in. In effect, each packet gets put into an "envelope" on one side of the net, and removed from the envelope when it reaches its destination. This works for all kinds of Internet traffic, including Web access, Telnet, FTP, email, IRC, Usenet, etc.

The encryption boxes are standard PC's that use freely available Linux software that you can download over the Internet or install from a cheap CDROM.

This wasn't just my idea; lots of people have been working on it for years. The encryption protocols for these boxes are called IPSEC (IP Security). They have been developed by the IP Security Working Group of the Internet Engineering Task Force, and will be a standard part of the next major version of the Internet protocols ( IPv6). For today's (IP version 4) Internet, they are an option.

The Internet Architecture Board and Internet Engineering Steering Group have taken a strong stand that the Internet should use powerful encryption to provide security and privacy. I think these protocols are the best chance to do that, because they can be deployed very easily, without changing your hardware or software or retraining your users. They offer the best security we know how to build, using the Triple-DES, RSA, and Diffie-Hellman algorithms.

This "opportunistic encryption box" offers the "fax effect". As each person installs one for their own use, it becomes more valuable for their neighbors to install one too, because there's one more person to use it with. The software automatically notices each newly installed box, and doesn't require a network administrator to reconfigure it. Instead of "virtual private networks" we have a "REAL private network"; we add privacy to the real network instead of layering a manually-maintained virtual network on top of an insecure Internet.

#### Deployment of IPSEC

The US government would like to control the deployment of IP Security with its crypto export laws. This isn't a problem for my effort, because the cryptographic work is happening outside the United States. A foreign philanthropist, and others, have donated the resources required to add these protocols to the Linux operating system. Linux is a complete, freely available operating system for IBM PC's and several kinds of workstation, which is compatible with Unix. It was written by Linus Torvalds, and is still maintained by a talented team of expert programmers working all over the world and coordinating over the Internet. Linux is distributed under the GNU Public License, which gives everyone the right to copy it, improve it, give it to their friends, sell it commercially, or do just about anything else with it, without paying anyone for the privilege.

Organizations that want to secure their network will be able to put two Ethernet cards into an IBM PC, install Linux on it from a $30 CDROM or by downloading it over the net, and plug it in between their Ethernet and their Internet link or firewall. That's all they'll have to do to encrypt their Internet traffic everywhere outside their own local area network.

Travelers will be able to run Linux on their laptops, to secure their connection back to their home network (and to everywhere else that they connect to, such as customer sites). Anyone who runs Linux on a standalone PC will also be able to secure their network connections, without changing their application software or how they operate their computer from day to day.

There will also be numerous commercially available firewalls that use this technology. RSA Data Security is coordinating the S/Wan (Secure Wide Area Network) project among more than a dozen vendors who use these protocols. There's a compatability chart that shows which vendors have tested their boxes against which other vendors to guarantee interoperatility.

Eventually it will also move into the operating systems and networking protocol stacks of major vendors. This will probably take longer, because those vendors will have to figure out what they want to do about the export controls.

#### Current status

My initial goal of securing 5% of the net by Christmas '96 was not met. It was an ambitious goal, and inspired me and others to work hard, but was ultimately too ambitious. The protocols were in an early stage of development, and needed a lot more protocol design before they could be implemented. As of April 1999, we have released version 1.0 of the software ( freeswan-1.0.tar.gz), which is suitable for setting up Virtual Private Networks using shared secrets for authentication. It does not yet do opportunistic encryption, or use DNSSEC for authentication; those features are coming in a future release.

Protocols
  The low-level encrypted packet formats are defined. The system for publishing keys and providing secure domain name service is defined. The IP Security working group has settled on an NSA-sponsored protocol for key agreement (called ISAKMP/Oakley), but it is still being worked on, as the protocol and its documentation is too complex and incomplete. There are prototype implementations of ISAKMP. The protocol is not yet defined to enable opportunistic encryption or the use of DNSSEC keys.
Linux Implementation
  The Linux implementation has reached its first major release and is ready for production use in manually-configured networks, using Linux kernel version 2.0.36.
Domain Name System Security
  There is now a release of BIND 8.2 that includes most DNS Security features.

The first prototype implementation of Domain Name System Security was funded by DARPA as part of their Information Survivability program. Trusted Information Systems wrote a modified version of BIND, the widely-used Berkeley implementation of the Domain Name System.

TIS, ISC, and I merged the prototype into the standard version of BIND. The first production version that supports KEY and SIG records is bind-4.9.5. This or any later version of BIND will do for publishing keys. It is available from the Internet Software Consortium. This version of BIND is not export-controlled since it does not contain any cryptography. Later releases starting with BIND 8.2 include cryptography for authenticating DNS records, which is also exportable. Better documentation is needed.

#### Why?

Because I can. I have made enough money from several successful startup companies, that for a while I don't have to work to support myself. I spend my energies and money creating the kind of world that I'd like to live in and that I'd like my (future) kids to live in. Keeping and improving on the civil rights we have in the United States, as we move more of our lives into cyberspace, is a particular goal of mine.

#### What You Can Do

Install the latest BIND at your site.
  You won't be able to publish any keys for your domain, until you have upgraded your copy of BIND. The thing you really need from it is the new version of named, the Name Daemon, which knows about the new KEY and SIG record types. So, download it from the Internet Software Consortium and install it on your name server machine (or get your system administrator, or Internet Service Provider, to install it). Both your primary DNS site and all of your secondary DNS sites will need the new release before you will be able to publish your keys. You can tell which sites this is by running the Unix command "dig MYDOMAIN ns" and seeing which sites are mentioned in your NS (name server) records.
Set up a Linux system and run a 2.0.x kernel on it
  Get a machine running Linux (say the 5.2 release from Red Hat). Give the machine two Ethernet cards.
Install the Linux IPSEC (Freeswan) software
  If you're an experienced sysadmin or Linux hacker, install the freeswan-1.0 release, or any later release or snapshot. These releases do NOT provide automated "opportunistic" operation; they must be manually configured for each site you wish to encrypt with.
Get on the linux-ipsec mailing list
  The discussion forum for people working on the project, and testing the code and documentation, is: linux-ipsec@clinet.fi. To join this mailing list, send email to linux-ipsec-REQUEST@clinet.fi containing a line of text that says "subscribe linux-ipsec". (You can later get off the mailing list the same way -- just send "unsubscribe linux-ipsec").

Check back at this web page every once in a while
  I update this page periodically, and there may be new information in it that you haven't seen. My intent is to send email to the mailing list when I update the page in any significant way, so subscribing to the list is an alternative.

Would you like to help? I can use people who are willing to write documentation, install early releases for testing, write cryptographic code outside the United States, sell pre-packaged software or systems including this technology, and teach classes for network administrators who want to install this technology. To offer to help, send me email at gnu@toad.com. Tell me what country you live in and what your citizenship is (it matters due to the export control laws; personally I don't care). Include a copy of your resume and the URL of your home page. Describe what you'd like to do for the project, and what you're uniquely qualified for. Mention what other volunteer projects you've been involved in (and how they worked out). Helping out will require that you be able to commit to doing particular things, meet your commitments, and be responsive by email. Volunteer projects just don't work without those things.

#### Related projects

IPSEC for NetBSD
  This prototype implementation of the IP Security protocols is for another free operating system. Download BSDipsec.tar.gz.
IPSEC for OpenBSD
  This prototype implementation of the IP Security protocols is for yet another free operating system. It is directly integrated into the OS release, since the OS is maintained in Canada, which has freedom of speech in software.

### Stopping wholesale monitoring

From a message project leader John Gilmore posted to the mailing list:

    John Denker wrote:

    > Indeed there are several ways in which the documentation overstates the
    > scope of what this project does -- starting with the name
    > FreeS/WAN.  There's a big difference between having an encrypted IP tunnel
    > versus having a Secure Wide-Area Network.  This software does a fine job of
    > the former, which is necessary but not sufficient for the latter.

    The goal of the project is to make it very hard to tap your wide area
    communications.  The current system provides very good protection
    against passive attacks (wiretapping and those big antenna farms).
    Active attacks, which involve the intruder sending packets to your
    system (like packets that break into sendmail and give them a root
    shell :-) are much harder to guard against.  Active attacks that
    involve sending people (breaking into your house and replacing parts
    of your computer with ones that transmit what you're doing) are also
    much harder to guard against.  Though we are putting effort into
    protecting against active attacks, it's a much bigger job than merely
    providing strong encryption.  It involves general computer security,
    and general physical security, which are two very expensive problems
    for even a site to solve, let alone to build into a whole society.

    The societal benefit of building an infrastructure that protects
    well against passive attacks is that it makes it much harder to do
    undetected bulk monitoring of the population.  It's a defense against
    police-states, not against policemen.

    Policemen can put in the effort required to actively attack sites that
    they have strong suspicions about.  But police states won't be able to
    build systems that automatically monitor everyone's communications.
    Either they will be able to monitor only a small subset of the
    populace (by targeting those who screwed up their passive security),
    or their monitoring activities will be detectable by those monitored
    (active attacks leave packet traces or footprints), which can then be
    addressed through the press and through political means if they become
    too widespread.

    FreeS/WAN does not protect very well against traffic analysis, which
    is a kind of widespread police-state style monitoring that still
    reveals significant information (who's talking to who) without
    revealing the contents of what was said.  Defenses against traffic
    analysis are an open research problem.  Zero Knowledge Systems is
    actively deploying a system designed to thwart it, designed by Ian
    Goldberg.  The jury is out on whether it actually works; a lot more
    experience with it will be needed.

Notes on things mentioned in that message:

- Denker is a co-author of a paper on a large FreeS/WAN application.
- Information on Zero Knowledge is on their web site. Their Freedom product is designed to provide untracable pseudonyms for use on the net.
- Another section of our documentation discusses ways to resist traffic analysis.

## Government promotion of weak crypto

Various groups, especially governments and especially the US government, have a long history of advocating various forms of bogus security.

We regard bogus security as extremely dangerous. If users are deceived into relying on bogus security, then they may be exposed to large risks. They would be better off having no security and knowing it. At least then they would be careful about what they said.

Avoiding bogus security is a key design criterion for everything we do in FreeS/WAN. The most conspicuous example is our refusal to support single DES. Other IPSEC "features" which we do not implement are discussed in our compatibility document.

### Escrowed encryption

Various governments have made persistent attempts to encourage or mandate "escrowed encrytion", also called "key recovery", or GAK for "government access to keys". The idea is that cryptographic keys be held by some third party and turned over to law enforcement or security agencies under some conditions.

      Mary had cryptography
      Her keys were in escrow
      And everything that Mary said
      The feds were sure to know

(If anyone knows the origin of that ditty, let let me know so I can credit the author.)

There is an excellent paper available on Risks of Escrowed Encryption, from a group of cryptographic luminaries which included our project leader.

Like any unnecessary complication, GAK tends to weaken security of any design it infects. For example:

- Matt Blaze found a fatal flaw in the US government's Clipper chip shortly after design information became public. See his paper "Protocol Failure in the Escrowed Encryption Standard" on his papers page.
- a rather nasty bug has recently been found in the "additional decryption keys" "feature" of recent releases of PGP

FreeS/WAN does not support escrowed encryption, and never will.

### Limited key lengths

Various governments, and some vendors, have also made persistent attempts to convince people that:

- weak systems are sufficient for some data
- strong cryptography should be reserved for cases where the extra overheads are justified

This is nonsense.

Weak systems touted include:

- the ludicrously weak (deliberately crippled) 40-bit ciphers that until recently were all various export laws allowed
- 56-bit single DES, discussed below
- 64-bit symmetric ciphers and 512-bit RSA, the maximums for unrestricted export under various current laws

The notion that choice of ciphers or keysize should be determined by a trade-off between security requirements and overheads is pure bafflegab.

- For most symmetric ciphers, it is simply a lie. Any block cipher has some natural maximum keysize inherent in the design -- 128 bits for IDEA or CAST-128, 256 for any of the AES ciphers, 448 for Blowfish and 2048 for RC4 . Using any key size up to that natural limit the overheads are exactly what they would be for the crippled 40-bit or 64-bit version of the cipher.
- For the special case of triple DES there is a grain of truth in the argument. 3DES is indeed three times slower than single DES. Of course it is also fast enough for many applications. In cases where it isn't, the solution is not to use the insecure single DES, but to pick a faster secure cipher. CAST-128 , Blowfish and the AES candidate ciphers are are all considerably faster in software than DES (let alone 3DES), and apparently secure.
- For public key techniques, there are extra overheads for larger keys, but they generally do not affect overall performance significantly. Practical public key applications are usually hybrid systems in which the bulk of the work is done by a symmetric cipher. The effect of increasing the cost of the public key operations is typically negligible because the public key operations use only a tiny fraction of total resources.

For example, suppose public key operations use use 1% of the time in a hybrid system and you triple the cost of public key operations. The cost of symmetric cipher operations is unchanged at 99% of the original total cost, so the overall effect is a jump from 99 + 1 = 100 to 99 + 3 = 102, a 2% rise in system cost.

In short, there has never been any technical reason to use inadequate ciphers. The only reason there has ever been for anyone to use such ciphers is that government agencies want weak ciphers used so that they can crack them. The alleged savings are simply propaganda.

Of course, making systems secure does involve costs, and trade-offs can be made between cost and security. There can be substantial hardware and software costs. There are almost always substantial staff or contracting costs:

- Security takes staff time for planning, implementation and auditing. Some of the issues are subtle; you need good (hence often expensive) people for this.
- You also need people to monitor your systems and respond to problems. The best safe ever built is insecure if an attacker can work on it for days without anyone noticing. Any computer is insecure if the administrator is "too busy" to check the logs.
- Moreover, someone in your organisation (or on contract to it) needs to spend considerable time keeping up with new developments.
  - When some novel attack threatens some program you use, someone should notice.
  - When the vendor provides a patch that fixes the vulnerability, someone should apply it.

  For a fairly awful example, see this report. In that case over a million credit card numbers were taken from e-commerce sites, using security flaws in Windows NT servers. Microsoft had long since released patches for most or all of the flaws, but the site administrators had not applied them.

  - If the vendor does nothing, someone should do at least one of:
    - raise hell with the vendor
    - raise the question of changing vendors
  At an absolute minimum, you must do something about such issues before an exploitation tool is posted to the net for downloading by dozens of "script kiddies". Such a tool might appear at any time from the announcement of the security hole to several months later. Once it appears, anyone with a browser and an attitude can break any system whose administrators have done nothing about the flaw.
- There are often substantial training costs, both to train administrators and to increase user awareness of security issues and procedures.

Compared to those costs, cipher overheads are an insignificant factor in the cost of security. Note, however, that choosing an insecure cipher can cause all your other investment to be wasted.

Our policy in FreeS/WAN is to use only cryptographic components with adequate keylength and no known weaknesses.

- We do not implement single DES because it is clearly insecure, so implemeting it would violate our policy of avoiding bogus security. Our default cipher is 3DES
- Similarly, we do not implement the 768-bit Group 1 for Diffie-Hellman key negotiation. It is not clear that this is secure, so we provide only the 1024-bit Group 2 and 1536-bit Group 5.

These decisions imply that we cannot fully conform to the IPSEC RFCs, since those have DES as the only required cipher and Group 1 as the only required DH group. (In our view, the standards were subverted into offerring bogus security.) Fortunately, we can still interoperate with most other IPSEC implementations since nearly all implementers provide at least 3DES and Group 2 as well.

We hope that eventually the RFCs will catch up with our (and others') current practice and reject dubious components. Some of our team and a number of others are working on this in IETF working groups.

## Cryptography Export Laws

Many nations restrict the export of cryptography and some restrict its use by their citizens or others within their borders.

### US Law

US laws, as currently interpreted by the US government, forbid export of most cryptographic software from the US in machine-readable form without government permission. In general, the restrictions apply even if the software is widely-disseminated or public-domain and even if it came from outside the US originally. Cryptography is legally a munition and export is tightly controlled under the EAR Export Administration Regulations.

If you are a US citizen, your brain is considered US territory no matter where it is physically located at the moment. The US believes that its laws apply to its citizens everywhere, not just within the US. Providing technical assistance or advice to foreign "munitions" projects is illegal. The US government has very little sense of humor about this issue and does not consider good intentions to be sufficient excuse. Beware.

The official website for these regulations is run by the Commerce Department's Bureau of Export Administration (BXA). Information on various challenges to them is indexed in the Cryptography Export Control Archives.

The Bernstein case challenges the export restrictions on Constitutional grounds. Code is speech so restrictions on export of code violate the First Amendment's free speech provisions. This argument has succeeded in two levels of court so far. It is quite likely to go on to the Supreme Court.

The regulations were changed substantially in January 2000, apparently as a government attempt to get off the hook in the Bernstein case. It is now legal to export public domain source code for encryption, provided you notify the BXA.

There are, however, still restrictions in force. See this article. Moreover, the regulations can still be changed again whenever the government chooses to do so. Short of a Supreme Court ruling (in the Berstein case or another) that overturns the regulations completely, the problem of export regulation is not likely to go away in the forseeable future.

#### US contributions to FreeS/WAN

The FreeS/WAN project cannot accept software contributions, not even small bug fixes, from US citizens or residents. We want it to be absolutely clear that our distribution is not subject to US export law. Any contribution from an American might open that question to a debate we'd prefer to avoid. It might also put the contributor at serious legal risk.

Of course Americans can still make valuable contributions (many already have) by reporting bugs, or otherwise contributing to discussions, on the project mailing list. Since the list is public, this is clearly constitutionally protected free speech.

Note, however, that the export laws restrict Americans from providing technical assistance to foreign "munitions" projects. The government might claim that private discussions or correspondence with FreeS/WAN developers were covered by this. It is not clear what the courts would do with such a claim, so we strongly encourage Americans to use the list rather than risk the complications.

### What's wrong with restrictions on cryptography

Some quotes from prominent cryptography experts:

> The real aim of current policy is to ensure the continued effectiveness of US information warfare assets against individuals, businesses and governments in Europe and elsewhere.
> Ross Anderson, Cambridge University

> If the government were honest about its motives, then the debate about crypto export policy would have ended years ago.
> Bruce Schneier, Counterpane Systems

> We should not be building surveillance technology into standards. Law enforcement was not supposed to be easy. Where it is easy, it's called a police state.
> Jeff Schiller of MIT, in a discussion of FBI demands for wiretap capability on the net, as quoted by Wired.

The Internet Architecture Board (IAB) and the Internet Engineering Steering Group (IESG) made a strong statement in favour of worldwide access to strong cryptography. Essentially the same statement is in the appropriately numbered RFC 1984. Two critical paragraphs are:

> We believe that such policies are against the interests of consumers and the business community, are largely irrelevant to issues of military security, and provide only a marginal or illusory benefit to law enforcement agencies, as discussed below.

> The IAB and IESG would like to encourage policies that allow ready access to uniform strong cryptographic technology for all Internet users in all countries.

Our goal in the FreeS/WAN project is to build just such "strong cryptographic technology" and to distribute it "for all Internet users in all countries".

More recently, the same two bodies (IESG and IAB) have issued RFC 2804 on why the IETF should not build wiretapping capabilities into protocols for the convenience of security or law enforcement agenicies.

Our goal is to go beyond that and prevent Internet wiretapping entirely.

### The Wassenaar Arrangement

Restrictions on the export of cryptography are not just US policy, though some consider the US at least partly to blame for the policies of other nations in this area.

A number of countries:

Argentina, Australia, Austria, Belgium, Bulgaria, Canada, Czech Republic, Denmark, Finland, France, Germany, Greece, Hungary, Ireland, Italy, Japan, Luxembourg, Netherlands, New Zealand, Norway, Poland, Portugal, Republic of Korea, Romania, Russian Federation, Slovak Republic, Spain, Sweden, Switzerland, Turkey, Ukraine, United Kingdom and United States

have signed the Wassenaar Arrangement which restricts export of munitions and other tools of war. Cryptographic sofware is covered there.

Wassenaar details are available from the Wassenaar Secretariat, and elsewhere in a more readable HTML version.

For a critique see the GILC site:

> The Global Internet Liberty Campaign (GILC) has begun a campaign calling for the removal of cryptography controls from the Wassenaar Arrangement.

> The aim of the Wassenaar Arrangement is to prevent the build up of military capabilities that threaten regional and international security and stability . . .

> There is no sound basis within the Wassenaar Arrangement for the continuation of any export controls on cryptographic products.

We agree entirely.

An interesting analysis of Wassenaar can be found on the cyber-rights.org site.

### Export status of Linux FreeS/WAN

We believe our software is entirely exempt from these controls since the Wassenaar General Software Note says:

> The Lists do not control "software" which is either:
> 1. Generally available to the public by . . . retail . . . or
> 2. "In the public domain".

There is a note restricting some of this, but it is a sub-heading under point 1, so it appears not to apply to public domain software.

Their glossary defines "In the public domain" as:

> . . . "technology" or "software" which has been made available without restrictions upon its further dissemination.

> N.B. Copyright restrictions do not remove "technology" or "software" from being "in the public domain".

We therefore believe that software freely distributed under the GNU Public License, such as Linux FreeS/WAN, is exempt from Wassenaar restrictions.

Most of the development work is being done in Canada. Our understanding is that the Canadian government accepts this interpretation.

- A web statement of Canadian policy is available from the Department of Foreign Affairs and International Trade.
- Another document from that department states that public domain software is exempt from the export controls.
- A researcher's analysis of Canadian policy is also available.

Recent copies of the freely modifiable and distributable source code exist in many countries. Citizens all over the world participate in its use and evolution, and guard its ongoing distribution. Even if Canadian policy were to change, the software would continue to evolve in countries which do not restrict exports, and would continue to be imported from there into unfree countries. "The Net culture treats censorship as damage, and routes around it."

### Help spread IPSEC around

You can help. If you don't know of a Linux FreeS/WAN archive in your own country, please download it now to your personal machine, and consider making it publicly accessible if that doesn't violate your own laws. If you have the resources, consider going one step further and setting up a mirror site for the whole munitions Linux crypto software archive.

If you make Linux CD-ROMs, please consider including this code, in a way that violates no laws (in a free country, or in a domestic-only CD product).

Please send a note about any new archive mirror sites or CD distributions to linux-ipsec@clinet.fi so we can update the documentation.

Lists of current mirror sites and of distributions which include FreeS/WAN are in our introduction section.

## DES is Not Secure

DES, the Data Encryption S tandard, can no longer be considered secure. While no major flaws in its innards are known, it is fundamentally inadequate because its 56-bit key is too short. It is vulnerable to brute-force search of the whole key space, either by large collections of general-purpose machines or even more quickly by specialized hardware. Of course this also applies to any other cipher with only a 56-bit key. The only reason anyone could have for using a 56 or 64-bit key is to comply with various export laws intended to ensure the use of breakable ciphers.

Non-government cryptologists have been saying DES's 56-bit key was too short for some time -- some of them were saying it in the 70's when DES became a standard -- but the US government has consistently ridiculed such suggestions.

A group of well-known cryptographers looked at key lengths in a 1996 paper. They suggested a minimum of 75 bits to consider an existing cipher secure and a minimum of 90 bits for new ciphers. More recent papers, covering both symmetric and public key systems are at cryptosavvy.com and rsa.com. For all algorithms, the minimum keylengths recommended in such papers are significantly longer than the maximums allowed by various export laws.

In a 1998 ruling, a German court described DES as "out-of-date and not safe enough" and held a bank liable for using it.

### Dedicated hardware breaks DES in a few days

The question of DES security has now been settled once and for all. In early 1998, the Electronic Frontier Foundation built a DES-cracking machine. It can find a DES key in an average of a few days' search. The details of all this, including complete code listings and complete plans for the machine, have been published in Cracking DES, by the Electronic Frontier Foundation.

That machine cost just over $200,000 to design and build. "Moore's Law" is that machines get faster (or cheaper, for the same speed) by roughly a factor of two every 18 months. At that rate, their $200,000 in 1998 becomes $50,000 in 2001.

However, Moore's Law is not exact and the $50,000 estimate does not allow for the fact that a copy based on the published EFF design would of course cost far less than the original. We cannot say exactly what such a cracker would cost today, but it would likely be somewhere between $10,000 and $100,000.

A large corporation could build one of these out of petty cash. The cost is low enough for a senior manager to hide it in a departmental budget and avoid having to announce or justify the project. Any government agency, from a major municipal police force up, could afford one. Or any other group with a respectable budget -- criminal organisations, political groups, labour unions, religious groups, ... Or any millionaire with an obsession or a grudge, or just strange taste in toys.

One might wonder if a private security or detective agency would have one for rent. They wouldn't need many clients to pay off that investment.

### Spooks may break DES faster yet

As for the security and intelligence agencies of various nations, some of them may have had DES crackers for years. Possibly very fast ones! Cipher-cracking is one of the few known applications which is easy to speed up by just adding more processors and memory. Within very broad limits, you can make it as fast as you like if you have the budget. The EFF's $200,000 machine breaks DES in a few days. An aviation website gives the cost of a B1 bomber as $200,000,000. Spending that much, an intelligence agency could expect to break DES in an average time of six and a half minutes.

That estimate assumes they use the EFF's 1998 technology and just spend more money. They may have an attack that is superior to brute force, they quite likely have better chip technology (Moore's law, a bigger budget, and whatever secret advances they may have made) and of course they may have spent the price of an aircraft carrier, not just one aircraft.

In short, we have no idea how quickly these organisations can break DES. Unless they're grossly incompetent, they can certainly do it more quickly than the users of the cipher would like, but beyond that we can't say. Pick any time unit between days and milliseconds. None of these is entirely unbelievable. More to the point, none of them is of any comfort if you don't want such organisations reading your communications.

Note that this may be a concern even if nothing you do is a threat to anyone's national security. An intelligence agency might well consider it to be in their national interest for certain companies to do well. If you're competing against such companies in a world market and that agency can read your secrets, you have a serious problem. For example, see this NBC story or this analysis. The US are the villains in those pieces, but there is no reason to imagine they are the only threat.

One might wonder about technology the former Soviet Union and its allies developed for cracking DES during the Cold War. They must have tried; the cipher was an American standard and widely used. How well did they succeed? Is their technology now for sale or rent?

### Networks break DES in a few weeks

Before the definitive EFF effort, DES had been cracked several times by people using many machines. See this press release for example.

A major corporation, university, or government department could break DES by using spare cycles on their existing collection of computers, by dedicating a group of otherwise surplus machines to the problem, or by combining the two approaches. It might take them weeks or months, rather than the days required for the EFF machine, but they could do it.

What about someone working alone, without the resources of a large organisation? For them, cracking DES will not be easy, but it may be possible. A few thousand dollars buys a lot of surplus workstations. A pile of such machines will certainly heat your garage nicely and might break DES in a few months or years. Or enroll at a university and use their machines. Or use an employer's machines. Or crack security somewhere and steal the resources to crack a DES key. Or write a virus that steals small amounts of resources on many machines. Or . . .

None of these approaches are easy or break DES really quickly, but an attacker only needs to find one that is feasible and breaks DES quickly enough to be dangerous. How much would you care to bet that this will be impossible if the attacker is clever and determined? How valuable is your data? Are you authorised to risk it on a dubious bet?

### We disable DES

In short, it is now absolutely clear that DES is not secure against

- any well-funded opponent
- any opponent (even a penniless one) with access (even stolen access) to enough general purpose computers

That is why Linux FreeS/WAN disables all transforms which use plain DES for encryption.

DES is in the source code, because we need DES to implement our default encryption transform, Triple DES. We urge you not to use single DES. We do not provide any easy way to enable it in FreeS/WAN, and our policy is to provide no assistance to anyone wanting to do so.

### 40-bits is laughably weak

The same is true, in spades, of ciphers -- DES or others -- crippled by 40-bit keys, as many ciphers were required to be until recently under various export laws. A brute force search of such a cipher's keyspace is 216 times faster than a similar search against DES. The EFF's machine can do a brute-force search of a 40-bit key space in seconds. One contest to crack a 40-bit cipher was won by a student using a few hundred idle machines at his university. It took only three and half hours.

We do not, and will not, implement any 40-bit cipher.

### Triple DES is almost certainly secure

Triple DES, usually abbreviated 3DES, applies DES three times, with three different keys. DES seems to be basically an excellent cipher design; it has withstood several decades of intensive analysis without any disastrous flaws being found. It's only major flaw is that the small keyspace allows brute force attacks to succeeed. Triple DES enlarges the key space to 168 bits, making brute-force search a ridiculous impossibility.

3DES is currently the only block cipher implemented in FreeS/WAN. 3DES is, unfortunately, about 1/3 the speed of DES, but modern CPUs still do it at quite respectable speeds. Some speed measurements for our code are available.

### AES in IPSEC

The AES project has recently chosen a replacement for DES, a new standard cipher for use in non-classified US government work and in regulated industries such as banking. This cipher will almost certainly become widely used for many applications, including IPSEC, but perhaps not quickly.

The winner, announced in October 2000 after several years of analysis and discussion, was the Rijndael cipher from two Belgian designers.

It is likely that many IPSEC implementations will add Rijndael support over the next few months or years. FreeS/WAN will almost certainly do so, but it is not high on the priority list. This might be an excellent project for a volunteer.

## Press coverage of Linux FreeS/WAN:

### FreeS/WAN 1.0 press

- Wired "Linux-Based Crypto Stops Snoops", James Glave April 15 1999
- Slashdot
- DGL, Damar Group Limited; looking at FreeS/WAN from a perspective of business computing
- Linux Today
- TBTF , Tasty Bits from the Technology Front
- Salon Magazine "Free Encryption Takes a Big Step"

### Press release for version 1.0

            Strong Internet Privacy Software Free for Linux Users Worldwide

    Toronto, ON, April 14, 1999 -

    The Linux FreeS/WAN project today released free software to protect
    the privacy of Internet communications using strong encryption codes.
    FreeS/WAN automatically encrypts data as it crosses the Internet, to
    prevent unauthorized people from receiving or modifying it.  One
    ordinary PC per site runs this free software under Linux to become a
    secure gateway in a Virtual Private Network, without having to modify
    users' operating systems or application software.  The project built
    and released the software outside the United States, avoiding US
    government regulations which prohibit good privacy protection.
    FreeS/WAN version 1.0 is available immediately for downloading at
    http://www.xs4all.nl/~freeswan/.

    "Today's FreeS/WAN release allows network administrators to build
    excellent secure gateways out of old PCs at no cost, or using a cheap
    new PC," said John Gilmore, the entrepreneur who instigated the
    project in 1996.  "They can build operational experience with strong
    network encryption and protect their users' most important
    communications worldwide."

    "The software was written outside the United States, and we do not
    accept contributions from US citizens or residents, so that it can be
    freely published for use in every country," said Henry Spencer, who
    built the release in Toronto, Canada.  "Similar products based in the
    US require hard-to-get government export licenses before they can be
    provided to non-US users, and can never be simply published on a Web
    site.  Our product is freely available worldwide for immediate
    downloading, at no cost."

    FreeS/WAN provides privacy against both quiet eavesdropping (such as
    "packet sniffing") and active attempts to compromise communications
    (such as impersonating participating computers).  Secure "tunnels" carry
    information safely across the Internet between locations such as a
    company's main office, distant sales offices, and roaming laptops.  This
    protects the privacy and integrity of all information sent among those
    locations, including sensitive intra-company email, financial transactions
    such as mergers and acquisitions, business negotiations, personal medical
    records, privileged correspondence with lawyers, and information about
    crimes or civil rights violations.  The software will be particularly
    useful to frequent wiretapping targets such as private companies competing
    with government-owned companies, civil rights groups and lawyers,
    opposition political parties, and dissidents.

    FreeS/WAN provides privacy for Internet packets using the proposed
    standard Internet Protocol Security (IPSEC) protocols.  FreeS/WAN
    negotiates strong keys using Diffie-Hellman key agreement with 1024-bit
    keys, and encrypts each packet with 168-bit Triple-DES (3DES).  A modern
    $500 PC can set up a tunnel in less than a second, and can encrypt
    6 megabits of packets per second, easily handling the whole available
    bandwidth at the vast majority of Internet sites.  In preliminary testing,
    FreeS/WAN interoperated with 3DES IPSEC products from OpenBSD, PGP, SSH,
    Cisco, Raptor, and Xedia.  Since FreeS/WAN is distributed as source code,
    its innards are open to review by outside experts and sophisticated users,
    reducing the chance of undetected bugs or hidden security compromises.

    The software has been in development for several years.  It has been
    funded by several philanthropists interested in increased privacy on
    the Internet, including John Gilmore, co-founder of the Electronic
    Frontier Foundation, a leading online civil rights group.

    Press contacts:
    Hugh Daniel,   +1 408 353 8124, hugh@toad.com
    Henry Spencer, +1 416 690 6561, henry@spsystems.net

    * FreeS/WAN derives its name from S/WAN, which is a trademark of RSA Data
      Security, Inc; used by permission.

# The IPSEC protocols

This section provides details of the IPSEC protocols which FreeS/WAN implements

The basic idea of IPSEC is to provide security functions, authentication and encryption, at the IP (Internet Protocol) level. This requires a higher-level protocol (IKE) to set things up for the IP-level services (ESP and AH).

Three protocols are used in an IPSEC implementation:

ESP, Encapsulating Security Payload
  Encrypts and/or authenticates data
AH, Authentication Header
  Provides a packet authentication service
IKE, Internet Key Exchange
  Negotiates connection parameters, including keys, for the other two

The term "IPSEC" is slightly ambiguous. In some contexts, it includes all three of the above but in other contexts it refers only to AH and ESP.

## Applying IPSEC

Authentication and encryption functions for network data can, of course, be provided at other levels. Many security protocols work at levels above IP.

- PGP encrypts and authenticates mail messages
- SSH authenticates remote logins and then encrypts the session
- SSL or TLS provides security at the sockets layer, e.g. for secure web browsing

and so on. Other techniques work at levels below IP. For example, data on a communications circuit or an entire network can be encrypted by specialised hardware. This is common practice in high-security applications.

### Advantages of IPSEC

There are, however, advantages to doing it at the IP level instead of, or as well as, at other levels.

IPSEC is the most general way to provide these services for the Internet.

- Higher-level services protect a single protocol; for example PGP protects mail.
- Lower level services protect a single medium; for example a pair of encryption boxes on the ends of a line make wiretaps on that line useless unless the attacker is capable of breaking the encryption.

IPSEC, however, can protect any protocol running above IP and any medium which IP runs over. More to the point, it can protect a mixture of application protocols running over a complex combination of media. This is the normal situation for Internet communication; IPSEC is the only general solution.

IPSEC can also provide some security services "in the background", with no visible impact on users. To use PGP encryption and signatures on mail, for example, the user must at least:

- remember his or her passphrase,
- keep it secure
- follow procedures to validate correspondents' keys

These systems can be designed so that the burden on users is not onerous, but any system will place some requirements on users. No such system can hope to be secure if users are sloppy about meeting those requirements. The author has seen username and password stuck on terminals with post-it notes in an allegedly secure environment, for example.

### Limitations of IPSEC

IPSEC is designed to secure IP links between machines. It does that well, but it is important to remember that there are many things it does not do. Some of the important limitations are:

IPSEC cannot be secure if your system isn't
  System security on IPSEC gateway machines is an essential requirement if IPSEC is to function as designed. No system can be trusted if the underlying machine has been subverted. See books on Unix security such as Garfinkel and Spafford or our web references for Linux security or more general computer security.

Of course, there is another side to this. IPSEC can be a powerful tool for improving system and network security. For example, requiring packet authentication makes various spoofing attacks harder and IPSEC tunnels can be extremely useful for secure remote administration of various things.

IPSEC is not end-to-end
  IPSEC cannot provide the same end-to-end security as systems working at higher levels. IPSEC encrypts an IP connection between two machines, which is quite a different thing than encrypting messages between users or between applications.

For example, if you need mail encrypted from the sender's desktop to the recipient's desktop and decryptable only by the recipient, use PGP or another such system. IPSEC can encrypt any or all of the links involved -- between the two mail servers, or between either server and its clients. It could even be used to secure a direct IP link from the sender's desktop machine to the recipient's, cutting out any sort of network snoop. What it cannot ensure is end-to-end user-to-user security. If only IPSEC is used to secure mail, then anyone with appropriate privileges on any machine where that mail is stored (at either end or on any store-and-forward servers in the path) can read it.

In another common setup, IPSEC encrypts packets at a security gateway machine as they leave the sender's site and decrypts them on arrival at the gateway to the recipient's site. This does not even come close to providing an end-to-end service. In particular, anyone with appropriate privileges on either site's LAN can intercept the message in unencrypted form.

IPSEC cannot do everything
  IPSEC also cannot provide all the functions of systems working at higher levels of the protocol stack. If you need a document electronically signed by a particular person, then you need his or her digital signature and a public key cryptosystem to verify it with.

Note, however, that IPSEC authentication of the underlying communication can make various attacks on higher-level protocols more difficult. In particular, authentication prevents man-in-the-middle attacks.

IPSEC authenticates machines, not users
  IPSEC uses strong authentication mechanisms to control which messages go to which machines, but it does not have the concept of user ID, which is vital to many other security mechansims and policies. This means some care must be taken in fitting the various security mechansims on a network together. For example, if you need to control which users access your database server, you need some non-IPSEC mechansim for that. IPSEC can control which machines connect to the server, and can ensure that data transfer to those machines is done securely, but that is all. Either the machines themselves must control user access or there must be some form of user authentication to the database, independent of IPSEC.
IPSEC does not stop denial of service attacks
  Denial of service attacks aim at causing a system to crash, overload, or become confused so that legitimate users cannot get whatever services the system is supposed to provide. These are quite different from attacks in which the attacker seeks either to use the service himself or to subvert the service into delivering incorrect results.

IPSEC shifts the ground for DoS attacks; the attacks possible against systems using IPSEC are different than those that might be used against other systems. It does not, however, eliminate the possibility of such attacks.

IPSEC does not stop traffic analysis
  Traffic analysis is the attempt to derive intelligence from messages without regard for their contents. In the case of IPSEC, it would mean analysis based on things visible in the unencrypted headers of encrypted packets -- source and destination gateway addresses, packet size, et cetera. Given the resources to acquire such data and some skill in analysing it (both of which any national intelligence agency should have), this can be a very powerful technique.

IPSEC is not designed to defend against this. Partial defenses are certainly possible, and some are described below, but it is not clear that any complete defense can be provided.

### IPSEC is a general mechanism for securing IP

While IPSEC does not provide all functions of a mail encryption package, it can encrypt your mail. In particular, it can ensure that all mail passing between a pair or a group of sites is encrypted. An attacker looking only at external traffic, without access to anything on or behind the IPSEC gateway, cannot read your mail. He or she is stymied by IPSEC just as he or she would be by PGP.

The advantage is that IPSEC can provide the same protection for anything transmitted over IP. In a corporate network example, PGP lets the branch offices exchange secure mail with head office. SSL and SSH allow them to securely view web pages, connect as terminals to machines, and so on. IPSEC can support all those applications, plus database queries, file sharing (NFS or Windows), other protocols encapsulated in IP (Netware, Appletalk, ...), phone-over-IP, video-over-IP, ... anything-over-IP. The only limitation is that IP Multicast is not yet supported, though there are Internet Draft documents for that.

IPSEC creates secure tunnels through untrusted networks . Sites connected by these tunnels form VPNs, Virtual Private Networks.

IPSEC gateways can be installed wherever they are required.

- One organisation might choose to install IPSEC only on firewalls between their LANs and the Internet. This would allow them to create a VPN linking several offices. It would provide protection against anyone outside their sites.
- Another might install IPSEC on departmental servers so everything on the corporate backbone net was encrypted. This would protect messages on that net from everyone except the sending and receiving department.
- Another might be less concerned with information secrecy and more with controlling access to certain resources. They might use IPSEC packet authentication as part of an access control mechanism, with or without also using the IPSEC encryption service.
- It is even possible (assuming adequate processing power and an IPSEC implementation in each node) to make every machine its own IPSEC gateway so that everything on a LAN is encrypted. This protects information from everyone outside the sending and receiving machine.
- These techniques can be combined in various ways. One might, for example, require authentication everywhere on a network while using encryption only for a few links.

Which of these, or of the many other possible variants, to use is up to you. IPSEC provides mechanisms; you provide the policy .

No end user action is required for IPSEC security to be used; they don't even have to know about it. The site administrators, of course, do have to know about it and to put some effort into making it work. Poor administration can compromise IPSEC as badly as the post-it notes mentioned above. It seems reasonable, though, for organisations to hope their system administrators are generally both more security-conscious than end users and more able to follow computer security procedures. If not, at least there are fewer of them to educate or replace.

IPSEC can be, and often should be, used with along with security protocols at other levels. If two sites communicate with each other via the Internet, then IPSEC is the obvious way to protect that communication. If two others have a direct link between them, either link encryption or IPSEC would make sense. Choose one or use both. Whatever you use at and below the IP level, use other things as required above that level. Whatever you use above the IP level, consider what can be done with IPSEC to make attacks on the higher levels harder. For example, man-in-the-middle attacks on various protocols become difficult if authentication at packet level is in use on the potential victims' communication channel.

### Using authentication without encryption

Where appropriate, IPSEC can provide authentication without encryption. One might do this, for example:

- where the data is public but one wants to be sure of getting the right data, for example on some web sites
- where encryption is judged unnecessary, for example on some company or department LANs
- where strong encryption is provided at link level, below IP
- where strong encryption is provided in other protocols, above IP
  Note that IPSEC authentication may make some attacks on those protocols harder.

Authentication has lower overheads than encryption.

The protocols provide four ways to build such connections, using either an AH-only connection or ESP using null encryption, and in either manually or automatically keyed mode. FreeS/WAN supports only one of these, manually keyed AH-only connections, and we do not recommend using that. Our reasons are discussed under Resisting traffic analysis a few sections further along.

### Encryption without authentication is dangerous

Originally, the IPSEC encryption protocol ESP didn't do integrity checking. It only did encryption. Steve Bellovin found many ways to attack ESP used without authentication. See his paper Problem areas for the IP Security Protocols. To make a secure connection, you had to add an AH Authentication Header as well as ESP. Rather than incur the overhead of several layers (and rather than provide an ESP layer that didn't actually protect the traffic), the IPSEC working group built integrity and replay checking directly into ESP.

Today, typical usage is one of:

- ESP for encryption and authentication
- AH for authentication alone

Other variants are allowed by the standard, but not much used:

ESP encryption without authentication
  Bellovin has demonstrated fatal flaws in this. Do not use.
ESP encryption with AH authentication
  This has higher overheads than using the authentication in ESP, and no obvious benefit in most cases. The exception might be a network where AH authentication was widely or universally used. If you're going to do AH to conform with network policy, why authenticate again in the ESP layer?
Authenticate twice, with AH and with ESP
  Why? Of course, some folk consider "belt and suspenders" the sensible approach to security. If you're among them, you might use both protocols here. You might also use both to satisfy different parts of a security policy. For example, an organisation might require AH authentication everywhere but two users within the organisation might use ESP as well.
ESP authentication without encryption
  The standard allows this, calling it "null encryption". FreeS/WAN does not support it. We recommend that you use AH instead if authentication is all you require. AH authenticates parts of the IP header, which ESP-null does not do.

Some of these variants cannot be used with FreeS/WAN because we do not support ESP-null and do not support automatic keying of AH-only connections.

There are fairly frequent suggestions that AH be dropped entirely from the IPSEC specifications since ESP and null encryption can handle that situation. It is not clear whether this will occur. My guess is that it is unlikely.

### Multiple layers of IPSEC processing are possible

The above describes combinations possible on a single IPSEC connection. In a complex network you may have several layers of IPSEC in play, with any of the above combinations at each layer.

For example, a connection from a desktop machine to a database server might require AH authentication. Working with other host, network and database security measures, AH might be just the thing for access control. You might decide not to use ESP encryption on such packets, since it uses resources and might complicate network debugging. Within the site where the server is, then, only AH would be used on those packets.

Users at another office, however, might have their whole connection (AH headers and all) passing over an IPSEC tunnel connecting their office to the one with the database server. Such a tunnel should use ESP encryption and authentication. You need authentication in this layer because without authentication the encryption is vulnerable and the gateway cannot verify the AH authentication. The AH is between client and database server; the gateways aren't party to it.

In this situation, some packets would get multiple layers of IPSEC applied to them, AH on an end-to-end client-to-server basis and ESP from one office's security gateway to the other.

### Resisting traffic analysis

Traffic analysis is the attempt to derive useful intelligence from encrypted traffic without breaking the encryption.

Is your CEO exchanging email with a venture capital firm? With bankruptcy trustees? With an executive recruiting agency? With the holder of some important patents? If an eavesdropper learns that, he has interesting intelligence on your company, whether or not he can read the messages themselves.

Except in the simplest cases, traffic analysis is hard to do well. It requires both considerable resources and considerable analytic skill. However, intelligence agencies of various nations have been doing it for centuries and many of them are likely quite good at it by now. Various commercial organisations, especially those working on "targeted marketing" may also be quite good at analysing certain types of traffic.

In general, defending against traffic analysis is also difficult. Inventing a really good defense could get you a PhD and some interesting job offers.

IPSEC is not designed to stop traffic analysis and we know of no plausible method of extending it to do so. That said, there are ways to make traffic analysis harder. This section describes them.

#### Using "unnecessary" encryption

One might choose to use encryption even where it appears unnecessary in order to make analysis more difficult. Consider two offices which pass a small volume of business data between them using IPSEC and also transfer large volumes of Usenet news. At first glance, it would seem silly to encrypt the newsfeed, except possibly for any newsgroups that are internal to the company. Why encrypt data that is all publicly available from many sites?

However, if we encrypt a lot of news and send it down the same connection as our business data, we make traffic analysis much harder. A snoop cannot now make inferences based on patterns in the volume, direction, sizes, sender, destination, or timing of our business messages. Those messages are hidden in a mass of news messages encapsulated in the same way.

If we're going to do this we need to ensure that keys change often enough to remain secure even with high volumes and with the adversary able to get plaintext of much of the data. We also need to look at other attacks this might open up. For example, can the adversary use a chosen plaintext attack, deliberately posting news articles which, when we receive and encrypt them, will help break our encryption? Or can he block our business data transmission by flooding us with silly news articles? Or ...

Also, note that this does not provide complete protection against traffic analysis. A clever adversary might still deduce useful intelligence from statistical analysis (perhaps comparing the input newsfeed to encrypted output, or comparing the streams we send to different branch offices), or by looking for small packets which might indicate establishment of TCP connections, or ...

As a general rule, though, one can improve resistance to traffic analysis by encrypting as much traffic as possible rather than only as much as seems necessary.

This also applies to using multiple layers of encryption. If you have an IPSEC tunnel between two branch offices, it might appear silly to send PGP-encrypted email through that tunnel. However, if you suspect someone is snooping your traffic, then it does make sense:

- it protects the mail headers; they cannot even see who is mailing who
- it protects against user bungles or software malfunctions that accidentally send messages in the clear
- it makes any attack on the mail encryption much harder; first they have to find the mail

Similar arguments apply for SSL-encrypted web traffic or SSH-encrypted remote login sessions, even for end-to-end IPSEC tunnels between systems in the two offices.

#### Using fewer tunnels

It may also help to use fewer tunnels. For example, if all you actually need encrypted is connections between:

- mail servers at branch and head offices
- a few branch office users and the head office database server

You might build one tunnel per mail server and one per remote database user, restricting traffic to those applications. This gives the traffic analyst some information, however. He or she can distinguish the tunnels by looking at information in the ESP header and, given that distinction and the patterns of tunnel usage, might be able to figure out something useful. Perhaps not, but why take the risk?

We suggest instead that you build one tunnel per branch office, encrypting everything passing from head office to branches. This has a number of advantages:

- it is easier to build and administer
- it resists traffic analysis somewhat better
- it provides security for whatever you forgot. For example, if some user at a remote office browses proprietary company data on some head office web page (that the security people may not even know about!), then that data is encrypted before it reaches the Internet.

Of course you might also want to add additional tunnels. For example, if some of the database data is confidential and should not be exposed even within the company, then you need protection from the user's desktop to the database server. We suggest you do that in whatever way seems appropriate -- IPSEC, SSH or SSL might fit -- but, whatever you choose, pass it between locations via a gateway-to-gateway IPSEC tunnel to provide some resistance to traffic analysis.

## Cryptographic components

IPSEC combines a number of cryptographic techniques, all of them well-known and well-analyzed. The overall design approach was conservative; no new or poorly-understood components were included.

This section gives a brief overview of each technique. It is intended only as an introduction. There is more information, and links to related topics, in our glossary. See also our bibliography and cryptography web links.

### Block ciphers

The encryption in the ESP encapsulation protocol is done with a block cipher .

We do not implement single DES. It is insecure. Our default, and currently only, block cipher is triple DES.

The Rijndael block cipher has just won the AES competition to choose a relacement for DES. It will almost certainly be added to FreeS/WAN and to other IPSEC implementations.

### Hash functions

#### The HMAC construct

IPSEC packet authentication is done with the HMAC construct. This is not just a hash of the packet data, but a more complex operation which uses both a hashing algorithm (MD5 or SHA) and a key. It therefore does more than a simple hash would. A simple hash would only tell you that the packet data was not changed in transit, or that whoever changed it also regenerated the hash. An HMAC also tells you that the sender knew the HMAC key.

For IPSEC HMAC, the output of the hash algorithm is truncated to 96 bits. This saves some space in the packets. More important, it prevents an attacker from seeing all the hash output bits and perhaps creating some sort of attack based on that knowledge.

### Diffie-Hellman key agreement

The Diffie-Hellman key agreement protocol allows two parties (A and B or Alice and Bob) to agree on a key in such a way that an eavesdropper who intercepts the entire conversation cannot learn the key.

The protocol is based on the discrete logarithm problem and is therefore thought to be secure. Mathematicians have been working on that problem for years and seem no closer to a solution, though there is no proof that an efficient solution is impossible.

### RSA authentication

The RSA algorithm (named for its inventors -- Rivest, Shamir and Adleman) is a very widely used public key cryptographic technique. It is used in IPSEC as one method of authenticating gateways for Diffie-Hellman key negotiation.

## Structure of IPSEC

There are three protocols used in an IPSEC implementation:

ESP, Encapsulating Security Payload
  Encrypts and/or authenticates data
AH, Authentication Header
  Provides a packet authentication service
IKE, Internet Key Exchange
  Negotiates connection parameters, including keys, for the other two

The term "IPSEC" is slightly ambiguous. In some contexts, it includes all three of the above but in other contexts it refers only to AH and ESP.

### IKE (Internet Key Exchange)

The IKE protocol sets up IPSEC (ESP or AH) connections after negotiating appropriate parameters (algorithms to be used, keys, connection lifetimes) for them. This is done by exchanging packets on UDP port 500 between the two gateways.

IKE (RFC 2409) was the outcome of a long, complex process in which quite a number of protocols were proposed and debated. Oversimplifying mildly, IKE combines:

ISAKMP (RFC 2408)
  The Internet Security A ssociation and Key Management Protocol manages negotiation of connections and defines SAs (Security Associations) as a means of describing connection properties.
IPSEC DOI for ISAKMP (RFC 2407)
  A Domain Of I nterpretation fills in the details necessary to turn the rather abstract ISAKMP protocol into a more tightly specified protocol, so it becomes applicable in a particular domain.
Oakley key determination protocol (RFC 2412)
  Oakley creates keys using the Diffie-Hellman key agreement protocol.

For all the details, you would need to read the four RFCs just mentioned (over 200 pages) and a number of others. We give a summary below, but it is far from complete.

#### Phases of IKE

IKE negotiations have two phases.

Phase one
  The two gateways negotiate and set up a two-way ISAKMP SA which they can then use to handle phase two negotiations. One such SA between a pair of gateways can handle negotiations for multiple tunnels.
Phase two
  Using the ISAKMP SA, the gateways negotiate IPSEC (ESP and/or AH) SAs as required. IPSEC SAs are unidirectional (a different key is used in each direction) and are always negotiated in pairs to handle two-way traffic. There may be more than one pair defined between two gateways.

Both of these phases use the UDP protocol and port 500 for their negotiations.

After both IKE phases are complete, you have IPSEC SAs to carry your encrypted data. These use the ESP or AH protocols. These protocols do not have ports; ports apply only to UDP or TCP.

The IKE protocol is designed to be extremely flexible. Among the things that can be negotiated (separately for each SA) are:

- SA lifetime before rekeying
- encryption algorithm used. We currently support only triple DES. Single DES is insecure. The RFCs say you MUST do DES, SHOULD do 3DES and MAY do various others. We do not do any of the others.
- authentication algorithms. We support MD5 and SHA. These are the two the RFCs require.
- choice of group for Diffie-Hellman key agreement. We currently support Groups 2 and 5 (which are defined modulo primes of various lengths) and do not support Group 1 (defined modulo a shorter prime, and therefore cryptographically weak) or groups 3 and 4 (defined using elliptic curves). The RFCs require only Group 1.

The protocol also allows implementations to add their own encryption algorithms, authentication algorithms or Diffie-Hellman groups. We do not support any such extensions.

There are a number of complications:

- The gateways must be able to authenticate each other's identities before they can create a secure connection. This host authentication is part of phase one negotiations, and is a required prerequisite for packet authentication used later. Host authentication can be done in a variety of ways. Those supported by FreeS/WAN are discussed in our configuration document.
- Phase one can be done in two ways.
  - Main Mode is required by the RFCs and supported in FreeS/WAN.
  - Aggressive Mode is somewhat faster but reveals more to an eavesdropper. This is optional in the RFCs, not currently supported by FreeS/WAN, and not likely to be.
- Phase two always uses Quick Mode, but there are two variants of that:
  - One variant provides Perfect Forward Secrecy (PFS) . An attacker that obtains your long-term host authentication key does not immediately get any of your short-term packet encryption of packet authentication keys. He must conduct another successful attack each time you rekey to get the short-term keys. Having some short-term keys does not help him learn others. In particular, breaking your system today does not let him read messages he archived yestarday, assuming you've changed short-term keys in the meanwhile. We enable PFS as the default.
  - The other variant disables PFS and is therefore slightly faster. We do not recommend this since it is less secure, but FreeS/WAN does support it. You can enable it with a pfs=no statement in ipsec.conf(5).
- Several types of notification message may be sent by either side during either phase, or later. FreeS/WAN does not currently support these, but they are a likely addition in future releases.
- A new group exchange may take place after phase one but before phase two, defining up an additional group for use in the Diffie-Hellman key agreement part of phase two. FreeS/WAN does not currently support this.
- There is a commit flag which may optionally be set on some messages. The errata page for the RFCs includes two changes related to this, one to clarify the description of its use and one to block a denial of service attack which uses it. We currently do not implement this feature.

These complications can of course lead to problems, particularly when two different implementations attempt to interoperate. For example, we have seen problems such as:

- Some implememtations (often products crippled by export laws) have the insecure DES algorithm as their only supported encryption method. See our DES insecurity comments for the reasons we do not implement single DES, and our FAQ for a discussion of how to cope with crippled products.
- Windows 2000 IPSEC tries to negotiate with FreeS/WAN using Aggressive Mode, which we don't support. Later on, it uses the commit bit, which we also don't support.
- FreeS/WAN's interaction with PGPnet is complicated by their use of notification messages we do not yet support.

Despite this, we do interoperate successfully with many implementations, including both Windows 2000 and PGPnet. Details are in our interoperability document.

#### Structure of IKE messages

Here is our Pluto developer explaining some of this on the mailing list:

    When one IKE system (for example, Pluto) is negotiating with another
    to create an SA, the Initiator proposes a bunch of choices and the
    Responder replies with one that it has selected.

    The structure of the choices is fairly complicated.  An SA payload
    contains a list of lists of "Proposals".  The outer list is a set of
    choices: the selection must be from one element of this list.

    Each of these elements is a list of Proposals.  A selection must be
    made from each of the elements of the inner list.  In other words,
    *all* of them apply (that is how, for example, both AH and ESP can
    apply at once).

    Within each of these Proposals is a list of Transforms.  For each
    Proposal selected, one Transform must be selected (in other words,
    each Proposal provides a choice of Transforms).

    Each Transform is made up of a list of Attributes describing, well,
    attributes.  Such as lifetime of the SA.  Such as algorithm to be
    used.  All the Attributes apply to a Transform.

    You will have noticed a pattern here: layers alternate between being
    disjunctions ("or") and conjunctions ("and").

    For Phase 1 / Main Mode (negotiating an ISAKMP SA), this structure is
    cut back.  There must be exactly one Proposal.  So this degenerates to
    a list of Transforms, one of which must be chosen.

### IPSEC Services, AH and ESP

IPSEC offers two services, authentication and encryption. These can be used separately but are often used together.

Authentication
  Packet-level authentication allows you to be confident that a packet came from a particular machine and that its contents were not altered en route to you. No attempt is made to conceal or protect the contents, only to assure their integrity.

Packet authentication can be provided separately using an Authentication Header, described just below, or it can be included as part of the ESP (Encapsulated Security Payload) service, described in the following section. That service offers encryption as well as authentication.

Encryption
  Encryption allows you to conceal the contents of a message from eavesdroppers.

In IPSEC this is done using a block cipher (normally Triple DES for Linux). In the most used setup, keys are automatically negotiated, and periodically re-negotiated, using the IKE (Internet Key Exchange) protocol. In Linux FreeS/WAN this is handled by the Pluto Daemon.

The IPSEC protocol offering encryption is ESP, Encapsulated Security Payload. It can also include a packet authentication service.

Note that encryption should always be used with some packet authentication service. Unauthenticated encryption is vulnerable to man-in-the-middle attacks. Also note that encryption does not necessarily prevent traffic analysis.

### The Authentication Header (AH)

Packet authentication can be provided separately from encryption by adding an authentication header (AH) after the IP header but before the other headers on the packet. This is the subject of this section. Details are in RFC 2402.

Each of the several headers on a packet header contains a "next protocol" field telling the system what header to look for next. IP headers generally have either TCP or UDP in this field. When IPSEC authentication is used, the packet IP header has AH in this field, saying that an Authentication Header comes next. The AH header then has the next header type -- usually TCP, UDP or encapsulated IP.

IPSEC packet authentication can be added in transport mode, as a modification of standard IP transport. This is shown in this diagram from the RFC:

                      BEFORE APPLYING AH
                ----------------------------
          IPv4  |orig IP hdr  |     |      |
                |(any options)| TCP | Data |
                ----------------------------

                      AFTER APPLYING AH
                ---------------------------------
          IPv4  |orig IP hdr  |    |     |      |
                |(any options)| AH | TCP | Data |
                ---------------------------------
                ||
                     except for mutable fields

Athentication can also be used in tunnel mode, encapsulating the underlying IP packet beneath AH and an additional IP header.

                             ||
    IPv4  | new IP hdr* |    | orig IP hdr*  |    |      |
          |(any options)| AH | (any options) |TCP | Data |
          ------------------------------------------------
          ||
          |           in the new IP hdr                  |

This would normally be used in a gateway-to-gateway tunnel. The receiving gateway then strips the outer IP header and the AH header and forwards the inner IP packet.

The mutable fields referred to are things like the time-to-live field in the IP header. These cannot be included in authentication calculations because they change as the packet travels.

#### Keyed MD5 and Keyed SHA

The actual authentication data in the header is typically 96 bits and depends both on a secret shared between sender and receiver and on every byte of the data being authenticated.

The algorithms involved are the MD5 Message Digest Algorithm or SHA, the Secure Hash Algorithm. For details on their use in this application, see RFCs 2403 and 2404 respectively.

For descriptions of the algorithms themselves, see RFC 1321 for MD5 and FIPS (Federal Information Processing Standard) number 186 from NIST, the US National Institute of Standards and Technology for SHA. Applied Cryptography covers both in some detail, MD5 starting on page 436 and SHA on 442.

These algorithms are intended to make it nearly impossible for anyone to alter the authenticated data in transit. The sender calculates a digest or hash value from that data and includes the result in the authentication header. The recipient does the same calculation and compares results. For unchanged data, the results will be identical. The hash algorithms are designed to make it extremely difficult to change the data in any way and still get the correct hash.

Since the shared secret key is also used in both calculations, an interceptor cannot simply alter the authenticated data and change the hash value to match. Without the key, he or she (or even the dreaded They) cannot produce a usable hash.

#### Sequence numbers

The authentication header includes a sequence number field which the sender is required to increment for each packet. The receiver can ignore it or use it to check that packets are indeed arriving in the expected sequence.

This provides partial protection against replay attacks in which an attacker resends intercepted packets in an effort to confuse or subvert the receiver. Complete protection is not possible since it is necessary to handle legitmate packets which are lost, duplicated, or delivered out of order, but use of sequence numbers makes the attack much more difficult.

The RFCs require that sequence numbers never cycle, that a new key always be negotiated before the sequence number reaches 2^32-1. This protects both against replays attacks using packets from a previous cyclce and against birthday attacks on the the packet authentication algorithm.

In Linux FreeS/WAN, the sequence number is ignored for manually keyed connections and checked for automatically keyed ones. In automatic mode, we do that. In manual mode, there is no way to negotiate a new key, or to recover from a sequence number problem, so we don't use sequence numbers.

### Encapsulated Security Payload (ESP)

The ESP protocol is defined in RFC 2406. It provides one or both of encryption and packet authentication. It may be used with or without AH packet authentication.

Note that some form of packet authentication should always be used whenever data is encrypted. Without authentication, the encryption is vulnerable to active attacks which may allow an enemy to break the encryption. ESP should always either include its own authentication or be used with AH authentication.

The RFCs require support for only two mandatory encryption algorithms -- DES, and null encryption -- and for two authentication methods -- keyed MD5 and keyed SHA. Implementers may choose to support additional algorithms in either category.

The authentication algorithms are the same ones used in the IPSEC authentication header.

We do not implement single DES since DES is insecure. Instead we provide triple DES or 3DES . This is currently the only encryption algorithm supported.

We do not implement null encryption since it is obviously insecure.

## IPSEC modes

IPSEC can connect in two modes. Transport mode is a host-to-host connection involving only two machines. In tunnel mode, the IPSEC machines act as gateways and trafiic for any number of client machines may be carried.

### Tunnel mode

Security gateways are required to support tunnel mode connections. In this mode the gateways provide tunnels for use by client machines behind the gateways. The client machines need not do any IPSEC processing; all they have to do is route things to gateways.

### Transport mode

Host machines (as opposed to security gateways) with IPSEC implementations must also support transport mode. In this mode, the host does its own IPSEC processing and routes some packets via IPSEC.

## FreeS/WAN parts

### KLIPS: Kernel IPSEC Support

KLIPS is KerneL IP SEC Support, the modifications necessary to support IPSEC within the Linux kernel. KILPS does all the actual IPSEC packet-handling, including

- encryption
- packet authentication calculations
- creation of ESP and AH headers for outgoing packets
- interpretation of those headers on incoming packets

KLIPS also checks all non-IPSEC packets to ensure they are not bypassing IPSEC security policies.

### The Pluto daemon

Pluto(8) is a daemon which implements the IKE protocol. It

- handles all the Phase one ISAKMP SAs
- performs host authentication and negotiates with other gateways
- creates IPSEC SAs and passes the data required to run them to KLIPS
- adjust routing and firewall setup to meet IPSEC requirements. See our IPSEC and firewalling document for details.

Pluto is controlled mainly by the ipsec.conf(5) configuration file.

### The ipsec(8) command

The ipsec(8) command is a front end that allows control over IPSEC activity.

### Linux FreeS/WAN configuration file

The configuration file for Linux FreeS/WAN is

            /etc/ipsec.conf

For details see the ipsec.conf(5) manual page and our Configuration section.

## Key management

There are several ways IPSEC can manage keys. Not all are implemented in Linux FreeS/WAN.

### Currently Implemented Methods

#### Manual keying

IPSEC allows keys to be manually set. In Linux FreeS/WAN, such keys are stored with the connection definitions in /etc/ipsec.conf.

Manual keying is useful for debugging since it allows you to test the KLIPS kernel IPSEC code without the Pluto daemon doing key negotiation.

In general, however, automatic keying is preferred because it is more secure.

#### Automatic keying

In automatic keying, the Pluto daemon negotiates keys using the IKE Internet Key Exchange protocol. Connections are automatically re-keyed periodically.

This is considerably more secure than manual keying. In either case an attacker who acquires a key can read every message encrypted with that key, but automatic keys can be changed every few hours or even every few minutes without breaking the connection or requiring intervention by the system administrators. Manual keys can only be changed manually; you need to shut down the connection and have the two admins make changes. Moreover, they have to communicate the new keys securely, perhaps with PGP or SSH . This may be possible in some cases, but as a general solution it is expensive, bothersome and unreliable. Far better to let Pluto handle these chores; no doubt the administrators have enough to do.

Also, automatic keying is inherently more secure against an attacker who manages to subvert your gateway system. If manual keying is in use and an adversary acquires root privilege on your gateway, he reads your keys from /etc/ipsec.conf and then reads all messages encrypted with those keys.

If automatic keying is used, an adversary with the same privileges can read /etc/ipsec.secrets, but this does not contain any keys, only the secrets used to authenticate key exchanges. Having an adversary able to authenticate your key exchanges need not worry you overmuch. Just having the secrets does not give him any keys. You are still secure against passive attacks. This property of automatic keying is called perfect forward secrecy, abbreviated PFS.

Unfortunately, having the secrets does allow an active attack, specifically a man-in-the-middle attack. Losing these secrets to an attacker may not be quite as disastrous as losing the actual keys, but it is still a serious security breach. These secrets should be guarded as carefully as keys.

### Methods not yet implemented

#### Unauthenticated key exchange

It would be possible to exchange keys without authenticating the players. This would support opportunistic encryption -- allowing any two systems to encrypt their communications without requiring a shared PKI or a previously negotiated secret -- and would be secure against passive attacks. It would, however, be highly vulnerable to active man-in-the-middle attacks. RFC 2408 therefore specifies that all ISAKMP key management interactions must be authenticated.

There is room for debate here. Should we provide immediate security against passive attacks and encourage widespread use of encryption, at the expense of risking the more difficult active attacks? Or should we wait until we can implement a solution that can both be widespread and offer security against active attacks?

So far, we have chosen the second course, complying with the RFCs and waiting for secure DNS (see below) so that we can do opportunistic encryption right.

#### Key exchange using DNS

The IPSEC RFCs allow key exchange based on authentication services provided by Secure DNS. Once Secure DNS service becomes widely available, we expect to make this the primary key management method for Linux FreeS/WAN. It is the best way we know of to support opportunistic encryption, allowing two systems without a common PKI or previous negotiation to secure their communication.

As of FreeS/WAN 1.4, we have experimental code to acquire RSA keys from DNS but do not yet have code to validate Secure DNS signatures.

#### Key exchange using a PKI

The IPSEC RFCs allow key exchange based on authentication services provided by a PKI or Public Key Infrastructure. With many vendors selling such products and many large organisations building these infrastructures, this will clearly be an important application of IPSEC and one Linux FreeS/WAN will eventually support.

On the other hand, this is not as high a priority for Linux FreeS/WAN as solutions based on secure DNS. We do not expect any PKI to become as universal as DNS.

Some patches to handle authentication with X.509 certificates, which most PKIs use, are available.

#### Photuris

Photuris is another key management protocol, an alternative to IKE and ISAKMP, described in RFCs 2522 and 2523 which are labelled "experimental". Adding Photuris support to Linux FreeS/WAN might be a good project for a volunteer. The likely starting point would be the OpenBSD photurisd code.

#### SKIP

SKIP is yet another key management protocol, developed by Sun. At one point it was fairly widely used, but our current impression is that it is moribund, displaced by IKE. Sun now (as of Solaris 8.0) ship an IPSEC implementation using IKE. We have no plans to implement SKIP.

# Mailing lists and newsgroups

## Mailing lists about FreeS/WAN

### The project mailing lists

The Linux FreeS/WAN project has several email lists for user support, bug reports and software development discussions.

We had a single list on clinet.fi for several years (Thanks, folks!), then one list on freeswan.org, but now we've split into several lists:

users
  - The general list for discussing use of the software
  - The place for seeking help with problems (but please check the FAQ first).
  - Anyone can post.
bugs
  - For bug reports.
  - If you are not certain what is going on -- could be a bug, a configuration error, a network problem, ... -- please post to the users list instead.
  - Anyone can post.
design
  - Design discussions, for people working on FreeS/WAN development or others with an interest in design and security issues.
  - It would be a good idea to read the existing design papers (see this list) before posting.
  - Anyone can post.
announce
  - A low-traffic list.
  - Announcements about FreeS/WAN and related software.
  - All posts here are also sent to the users list. You need not subscribe to both.
  - Only the FreeS/WAN team can post.
  - If you have something you feel should go on this list, send it to announce-admin@lists.freeswan.org. Unless it is obvious, please include a short note explaining why we should post it.
briefs
  - A low-traffic list.
  - Weekly summaries of activity on the users list.
  - All posts here are also sent to the users list. You need not subscribe to both.
  - Only the FreeS/WAN team can post.

To subscribe to any of these, you can:

- just follow the links above
- use our web interface
- send mail to listname-request@lists.freeswan.org with a one-line message body "subscribe"

Archives of these lists are available via the web interface.

#### List policies

US citizens or residents are asked not to post code to the lists, not even one-line bug fixes. The project cannot accept code which might entangle it in US export restrictions .

Non-subscribers can post to some of these lists. This is necessary; someone working on a gateway install who encounters a problem may not have access to a subscribed account.

Some spam turns up on these lists from time to time. For discussion of why we do not attempt to filter it, see the FAQ. Please do not clutter the lists with complaints about this.

### Archives of the lists

Searchable archives of the old single list have existed for some time. At time of writing, it is not yet clear how they will change for the new multi-list structure.

- Canada
- Holland

Note that these use different search engines. Try both.

Archives of the new lists are available via the web interface.

## Indexes of mailing lists

PAML is the standard reference for Publicly Accessible Mailing Lists. When we last checked, it had over 7500 lists on an amazing variety of topics. It also has FAQ information and a search engine.

There is an index of Linux mailing lists available.

A list of computer security mailing lists, with descriptions.

## Lists for related software and topics

Most links in this section point to subscription addresses for the various lists. Send the one-line message "subscribe list_name " to subscribe to any of them.

### Linux mailing lists

- linux-admin@vger.kernel.org, for Linux system administrators
- ipchains@rustcorp.com, about the IPchains firewall tool
- netfilter@samba.anu.edu.au, about Netfilter, which replaces IPchains in kernels 2.3.15 and later
- securedistros@humbolt.geo.uu.nl, for discussion of issues common to all the half dozen projects working on secure Linux distributions. Each project also has its own mailing list.
  - Bastille Linux scripts to harden Redhat, e.g. by changing permissions and modifying inialisation scripts
  - Immunix take a different approach, using a modified compiler to build kernel and utilities with better resistance to various types of overflow and exploit
- security-audit@ferret.lmh.ox.ac.uk, for people working on security audits of various Linux programs
- the NSA have contractors working on a Security Enhanced Linux, primaily adding stronger access control mechanisms. You can download the current version (which interestingly is under GPL and not export resrtricted) or subscribe to the mailing list from the project web page.

### Lists for IETF working groups

Each IETF working group has an associated mailing list where much of the work takes place.

- ipsec@lists.tislabs.com , the IPSEC working group. This is where the protocols are discussed, new drafts announced, and so on. By now, the IPSEC working group is winding down since the work is essentially complete. A list archive is available.
- IPSEC policy list, and its archive
- IP secure remote access list, and its archive

### Other mailing lists

- ipc-announce@privacy.org a low-traffic list with announcements of developments in privacy, encryption and online civil rights
- a VPN mailing list's home page

## Usenet newsgroups

- sci.crypt
- sci.crypt.research
- comp.dcom.vpn
- talk.politics.crypto

# Web links

## The Linux FreeS/WAN Project

The main project web site is www.freeswan.org.

Links to other project-related sites are provided in our introduction section.

### Add-ons and patches for FreeS/WAN

Some user-contributed patches gave been integrated into the FreeS/WAN distribution. For a variety of reasons, those listed below have not.

Patches believed current at time of writing (March 2001, just before 1.9 release):

- patches and utilities for using FreeS/WAN with PGPnet
- patches for X.509 certificate support, also available from a mirror site
- a series of patches that
  - provide GOST, a Russian gov't. standard cipher, in MMX assembler
  - add GOST to OpenSSL
  - add GOST to the International kernel patch
  - let FreeS/WAN use International kernel patch ciphers
- IPv6 support

Before using these, check the mailing list for news of newer versions and to see whether they have been incorporated into more recent versions of FreeS/WAN.

Note: At one point the way PGP generates RSA keys and the way FreeS/WAN checks them for validity before using them were slightly different, so quite a few PGP-generated keys would be rejected by FreeS/WAN, confusing users no end. This is fixed in 1.9.

A set of PKIX patches were recently announced on the mailing list:

    Subject: a different PKIX patch.
       Date: Mon, 5 Mar 2001
       From: Luc Lanthier <firesoul@netwinder.org>

    I'd like to invite volunteers to use the now-complete PKIX project I've
    been working on since about August. Because of this, the patch is for
    FreeSWAN 1.5, not 1.8... I haven't really felt the need to update it since
    I don't use IPV6 nor DNSSec.

    This is similar, but different than Andreas Steffen's pkix
    implementation. I've based this work on Neil Dunbar's openssl-pkix patch
    for FreeSWAN 1.1. I've updated it to run on FreeSWAN 1.5 correctly, and
    added support for ID_DER_ASN1_DN ID packet support. It will do LDAP
    certificate lookups no problem, as well as local flatfile, directory, or
    DB lookup for testing or speed.

    IE: It's a full CA-compatible client, capable of looking up, checking the
    CRL for expiry and such. It will not only do the classic PSK and RSASIG
    freeswan methods just fine, but also does PKIX's RSASIG, PKE and
    RPKE. I've spent a lot of time adding RoadWarrior support for these last
    IKE exchange methods.

    The patch can be found as:
      ftp://ftp.netwinder.org/users/f/firesoul/freeswan-1.5-pkix_13.patch
    There are also freeswan-1.5 - kernel 2.4 patches for those who need them.

    Let me know. Feedback is appreciated.

Older patches:

- Neil Dunbar's patches for certificate support, using code from Open SSL.
- patches to add Blowfish, IDEA and CAST-128 to FreeS/WAN
- patches for aggressive mode support

These patches are for older versions of FreeS/WAN and will likely not work with the current version. Older versions of FreeS/WAN may be available on some of the distribution sites , but we recommend using the current release.

#### VPN masquerade patches

Finally, there are some patches to other code that may be useful with FreeS/WAN:

- a patch to make IPSEC, PPTP and SSH VPNs work through a Linux firewall with IP masquerade.
- Linux VPN Masquerade HOWTO

Note that this is not required if the same machine does IPSEC and masquerading, only if you want a to locate your IPSEC gateway on a masqueraded network. See our firewalls document for discussion of why this is problematic.

At last report, this patch could not co-exist with FreeS/WAN on the same machine.

### Distributions including FreeS/WAN

The introductory section of our document set lists several Linux distributions which include FreeS/WAN.

### Things FreeS/WAN uses or could use

- /dev/random support page, discussion of and code for the Linux random number driver. Out-of-date when we last checked (January 2000), but still useful.
- other programs related to random numbers:
  - audio entropy daemon to gather noise from a sound card and feed it into /dev/random
  - an entropy-gathering daemon
  - a driver for the random number generator in recent Intel chipsets
- a Linux L2TP Daemon which might be useful for communicating with Windows 2000 which builds L2TP tunnels over its IPSEC connections
- packet spy, a packet sniffer whose author said in a Dec 1999 message "It's very unfinished, especially the filter, but it can give you an ascii and hex dump at the same time. I started it specifically for snooping a FreeS/WAN installation."
- to use opportunistic encryption, you need a recent version of BIND. Get one from the FreeS/WAN site or from the Internet Software Consortium who maintain BIND.

### Other approaches to VPNs for Linux

- other Linux IPSEC implementations
- ENskip, a free implementation of Sun's SKIP protocol
- vpnd, a non-IPSEC VPN daemon for Linux which creates tunnels using Blowfish encryption
- Zebedee, a simple GPLd tunnel-building program with Linux and Win32 versions. The name is from Zlib compression, Blowfish encryption and Diffie-Hellman key exchange.
- LinuxCare's VPS (Virtual Private Server) which builds tunnels using SSH
- Moreton Bay's PoPToP, PPTP for Linux
- CIPE (crypto IP routers) project, using their own lightweight protocol to encrypt between routers
- vtun "virtual tunnels", using Blowfish
- tinc, a VPN Daemon

There is a list of Linux VPN software in the Linux Security Knowledge Base.

## The IPSEC Protocols

### General IPSEC or VPN information

- The VPN Consortium is a group for vendors of IPSEC products. Among other things, they have a good collection of IPSEC white papers.
- A VPN mailing list with a home page, a FAQ, some product comparisons, and many links.
- A list of IPSEC links from Lewis McCarthy at U Mass.
- VPN pointer page
- a collection of VPN links, and some explanation

### IPSEC overview documents or slide sets

- the FreeS/WAN document section on these protocols
- A good introductory article with links to several articles on related topics
- SSH Communications Security
- Timestep Corporation's tutorial: go to their web site, then follow the "VPN Overview" link

### IPSEC information in languages other than English

- German
- Japanese

### RFCs and other reference documents

- Our document listing the RFCs relevant to Linux FreeS/WAN and giving various ways of obtaining both RFCs and Internet Drafts.
- IPSEC standards page maintained by VPNC. This covers both RFCs and Drafts, and classifies them in a fairly helpful way.
- RFC archive
- Internet Drafts related to IPSEC
- US government site with their FIPS standards
- Archives of the ipsec@tis.com mailing list where discussion of drafts takes place.
  - Eastern Canada
  - California.

### Analysis and critiques of IPSEC protocols

- Counterpane's evaluation of the protocols
- Simpson's IKE Considered Dangerous paper. Note that this is a link to an archive of our mailing list. There are several replies in addition to the paper itself.
- Bellovin's papers page including his:
  - Security Problems in the TCP/IP Protocol Suite (1989)
  - Problem Areas for the IP Security Protocols (1996)
  - Probable Plaintext Cryptanalysis of the IP Security Protocols (1997)
- Catherine Meadows of NRL applied the NRL Protocol Analyzer to IKE. Her paper is available in PDF or Postscript.
- An errata list for the IPSEC RFCs.

### Background information on IP

- An introduction to IP addressing from 3Com
- An IP tutorial that seems to be written mainly for Netware or Microsoft LAN admins entering a new world
- IANA, Internet Assigned Numbers Authority
- CIDR, Classless Inter-Domain Routing
- Also see our bibliography

## IPSEC Implementations

### Linux products

Vendors using FreeS/WAN in turnkey firewall or VPN products are listed in our introduction.

Other vendors have Linux IPSEC products which, as far as we know, do not use FreeS/WAN

- Redcreek provide an open source Linux driver for their PCI hardware VPN card. This card has a 100 Mbit Ethernet port, an Intel 960 CPU plus more specialised crypto chips, and claimed encryption performance of 45 Mbit/sec. The PC sees it as an Ethernet board.
- Paktronix offer a Linux-based VPN with hardware encryption
- According to a report on our mailing list, Watchguard use Linux in their Firebox product.
- Entrust offer a developers' toolkit for using their PKI for IPSEC authentication
- According to a report on our mailing list, Axent have a Linux version of their product.

### IPSEC in router products

All the major router vendors support IPSEC, at least in some models.

- Cisco IPSEC information
- Ascend, now part of Lucent, have some IPSEC-based products
- Bay Networks, now part of Nortel, use IPSEC in their Contivity switch product line
- 3Com have a number of VPN products, some using IPSEC

### IPSEC in firewall products

Many firewall vendors offer IPSEC, either as a standard part of their product, or an optional extra. A few we know about are:

- Borderware
- Ashley Laurent
- Watchguard
- Injoy for OS/2

Vendors using FreeS/WAN in turnkey firewall products are listed in our introduction.

### Operating systems with IPSEC support

All the major open source operating systems support IPSEC. See below for details on BSD-derived Unix variants.

Among commercial OS vendors, IPSEC players include:

- Microsoft have put IPSEC in their Windows 2000 products
- Apple's Mac OS X has IPSEC support built in
- IBM announce a release of OS390 with IPSEC support via a crypto co-processor
- Sun include IPSEC in Solaris 8
- Hewlett Packard offer IPSEC for their Unix machines

### Open source IPSEC implementations

#### Other Linux IPSEC implementations

We like to think of FreeS/WAN as the Linux IPSEC implementation, but it is not the only one. Others we know of are:

- pipsecd, a lightweight implementation of IPSEC for Linux. Does not require kernel recompilation.
- Petr Novak's ipnsec, based on the OpenBSD IPSEC code and using Photuris for key management
- A now defunct project at U of Arizona (export controlled)
- NIST Cerebus (export controlled)

#### IPSEC for BSD Unix

- KAME, several large Japanese companies co-operating on IPv6 and IPSEC
- US Naval Research Lab implementation of IPv6 and of IPSEC for IPv4 (export controlled)
- OpenBSD includes IPSEC as a standard part of the distribution
- IPSEC for FreeBSD
- a FAQ on NetBSD's IPSEC implementation

#### IPSEC for other systems

- Helsinki U of Technolgy have implemented IPSEC for Solaris, Java and Macintosh

### Interoperability

The IPSEC protocols are designed so that different implementations should be able to work together. As they say "the devil is in the details". IPSEC has a lot of details, but considerable success has been achieved.

#### Interoperability results

Linux FreeS/WAN has been tested for interoperability with many other IPSEC implementations. Results to date are in our interoperability section.

Various other sites have information on interoperability between various IPSEC implementations:

- interop results from a bakeoff in Atlanta, September 1999.
- a French company, HSC's, interoperability test data covers FreeS/WAN, Open BSD, KAME, Linux pipsecd, Checkpoint, Red Creek Ravlin, and Cisco IOS
- ICSA offer certification programs for various security-related products. See their list of certified IPSEC products. Linux FreeS/WAN is not currently on that list, but several products with which we interoperate are.
- VPNC have a page on why they are not yet doing interoperability testing and a page on the spec conformance testing that they are doning
- a review comparing a dozen commercial IPSEC implemetations. Unfortunately, the reviewers did not look at Open Source implementations such as FreeS/WAN or OpenBSD.
- results from interoperability tests at a conference. FreeS/WAN was not tested there.
- test results from the IPSEC 2000 conference

#### Interoperability test sites

- TAHI, a Japanese IPv6 testing project with free IPSEC validation software
- National Institute of Standards and Technology
- RSA Data Security
- SSH Communications Security
- Internet Devices

## Linux links

### Basic and tutorial Linux information

- Linux Getting Started HOWTO document
- A getting started guide from the U of Oregon
- A large link collection which includes a lot of introductory and tutorial material on Unix, Linux, the net, . . .

### General Linux sites

- Gary's Encyclopedia, several thousand Linux links, over 100 categories
- Freshmeat Linux news
- Slashdot "News for Nerds"
- Linux Online
- Linux HQ
- tux.org

### Documentation

- Linux Documentation Project
  - Meta-FAQ guide to Linux information sources
  - Index of HOWTO documents
  - Kernel HOWTO
  - Security HOWTO
  - Networking Overview HOWTO
  - Net 3 HOWTO
  - System Administrator's Guide
  - Network Adminstrator's Guide
- Open Source Writers' Group, cover the BSD derivatives as well as Linux
  - document index
  - some good essays on open source ideas
- Tucows Linux HowTo collection, mostly a mirror of LDP material

### Advanced routing

The Linux IP stack is getting some new features in 2.4 kernels. Most are already available as experimental code in 2.3 kernels. Some HowTos have been written:

- several HowTos for the netfilter firewall code in newer kernels
- 2.4 networking HowTo
- 2.4 routing HowTo

### Security for Linux

- Security HOWTO
- Linux Security Knowledge Base
- Trinity OS guide to setting up Linux
- Linux Administrator's Security Guide
- Linux security page
- Unix security page
- PPDD encrypting filesystem
- Linux Encryption HowTo This does not cover FreeS/WAN (or didn't when I last checked, April 2000), only gives a pointer to our web site, but does have some good information on other things.

### Linux firewalls

- Linux Firewall page
- IP Masquerade resource page
- IP chains, the firewall code in 2.2 kernels.
- netfilter firewall code in kernels from 2.3.15 on
- Our list of general firewall references on the web
- Mason, a tool for automatically configuring Linux firewalls
- Seattle Firewall tools for building a firewall using ipchains and FreeS?WAN
- the web cache software squid and squidguard which turns Squid into a filtering web proxy

### Miscellaneous Linux information

- List of Linux distribution vendors
- FAQ for the Linux adminstration mailing list
- A web page about PPTP for Linux with a list of other Linux VPN software

## Crypto and security links

### Crypto and security resources

#### The standard link collections

Two enormous collections of links, each the standard reference in its area:

Gene Spafford's COAST hotlist
  Computer and network security.
Peter Gutmann's Encryption and Security-related Resources
  Cryptography.

#### Frequently Asked Question (FAQ) documents

- Cryptography FAQ
- Firewall FAQ
- A FAQ listing computer security mailing lists
- Secure Unix Programming FAQ
- FAQs for specific programs are listed in the tools section below.

#### Tutorials

- Gary Kessler's Overview of Cryptography
- Terry Ritter's introduction
- Kurt Seifried's online introductory book
- Peter Gutman's cryptography tutorial (500 slides in PDF format)
- Amir Herzberg of IBM's sildes for his course Introduction to Cryptography and Electronic Commerce
- the concepts section of the GNU Privacy Guard documentation
- Bruce Schneier's self-study cryptanalysis course

See also the interesting papers section below.

#### Crypto and security standards

- Common Criteria, new international computer and network security standards to replace the "Rainbow" series
- AES Advanced Encryption Standard which will replace DES
- IEEE P-1363 public key standard
- our collection of links for the IPSEC standards
- history of formal evaluation of security policies and implementation

### Cryptography law and policy

#### Surveys of crypto law

- International survey of crypto law.
- International survey of digital signature law

#### Organisations opposing crypto restrictions

- The EFF's archives on privacy and export control.
- Global Internet Liberty Campaign
- Center for Democracy and Technology
- Privacy International, who give out Big Brother Awards to snoopy organisations

#### Other information on crypto policy

- RFC 1984, the IAB and IESG Statement on Cryptographic Technology and the Internet.
- John Young's collection of documents of interest to the cryptography, open government and privacy movements, organized chronologically
- Encryption, Privacy and Security Resource Page with a mainly US focus
- Cryptography Export Control Archive, mainly links to court and govenment documents on various challenges to US law
- A good overview of the issues from Australia.

See also our documentation section on the history and politics of cryptography.

### Cryptography technical information

#### Collections of crypto links

- Counterpane
- Peter Gutman's links
- Helger Lipmaa's links
- PKI links
- Robert Guerra's links

#### Lists of online cryptography papers

- Counterpane
- cryptography.com
- Cryptosoft

#### Particularly interesting papers

These papers emphasize important issues around the use of cryptography, and the design and management of secure systems.

- Key length requirements for security
- Why Cryptosystems Fail
- Risks of escrowed encryption
- Security pitfalls in cryptography
- Reflections on Trusting Trust, Ken Thompson on Trojan horse design
- Security against Compelled Disclosure, how to maintain privacy in the face of legal or other coersion

### Computer and network security

#### Security links

- COAST Hotlist
- DMOZ open directory project computer security links
- Telstra
- Bennet Yee
- Email Security and PKI Documents
- Open SEC, a link farm full of links to freely available security tools
- Mike Fuhr's link collection
- links with an emphasis on intrusion detection

#### Firewall links

- COAST firewalls
- Firewalls Resource page
- Firewall info list
- Ami Levartovsky

#### VPN links

- VPN Consortium
- First VPN's white paper collection
- oddsites.com VPN links

#### Security tools

- Open SEC, a link farm full of links to freely available security tools
- PGP -- mail encryption
  - PGP Inc. (part of NAI) for commercial versions
  - MIT distributes the NAI product for non-commercial use
  - international distribution site
  - GNU Privacy Guard (GPG)
  - PGP FAQ
  A message in our mailing list archive has considerable detail on available versions of PGP and on IPSEC support in them.

Note: A fairly nasty bug exists in all commercial PGP versions from 5.5 through 6.5.3. If you have one of those, read the security advisory and upgrade now.

- SSH -- secure remote login
  - SSH Communications Security, for the original software. It is free for trial, academic and non-commercial use.
  - Open SSH, the Open BSD team's free replacement
  - freessh.org, links to free implementations for many systems
  - SSH FAQ
  - Putty , an SSH client for Windows
- ssmail -- sendmail patched to do opportunistic encryption
  - web page with links to code and to a Usenix paper describing it, in PDF
- COPS Computer Oracle and Password System; tests a system for various weaknesses
- SATAN System Administrators Tool for Analysing Networks
- NMAP Network Mapper
- Internet Traffic Archive , various tools to analyze network traffic, mostly scripts to organise and format tcpdump(8) output for specific purposes
- Wietse Venema's page with various tools
- Crack password cracker
- Tripwire saves message digests of your system files. Re-calculate the digests and compare to saved values to detect any file changes.
- Deception Toolkit, a collection of "honeypot" servers which emulate widely exploited weaknesses while logging the attacks.
- Open CA project to develop a freely distributed Certification Authority for building a open Public Key Infrastructure.
- ISIC, IP stack integrity checker, generates legitmate and bogus packets "to test the stability of an IP Stack and its component stacks (TCP, UDP, ICMP et. al.)"

### Links to home pages

David Wagner at Berkeley provides a set of links to home pages of cryptographers, cypherpunks and computer security people.

# Glossary for the Linux FreeS/WAN project

Entries are in alphabetical order. Some entries are only one line or one paragraph long. Others run to several paragraphs. I have tried to put the essential information in the first paragraph so you can skip the other paragraphs if that seems appropriate.

## Jump to a letter in the glossary

numeric A B C D E F G H I J K L M N O P Q R S T U V W X Y Z

## Other glossaries

Other glossaries which overlap this one include:

- The VPN Consortium's glossary of VPN terms.
- glossary portion of the Cryptography FAQ
- an extensive crytographic glossary on Terry Ritter's page.
- The NSA's glossary of computer security on the SANS Institute site.
- an Internet Draft Crypto Glossary
- a small glossary for Internet Security at PC magazine
- The glossary from Richard Smith's book Internet Cryptography

Three Internet glossaries are available as RFCs:

- Glossary of Networking Terms
- Internet User's Glossary
- Internet Security Glossary

More general glossary or dictionary information:

- Free Online Dictionary of Computing (FOLDOC)
  - North America
  - Europe
  - Japan

There are many more mirrors of this dictionary.

- CRC dictionary of Computer Science
- The Jargon File, the definitive resource for hacker slang and folklore
  - North America
  - Holland
  - home page

There are also many mirrors of this. See the home page for a list.

- A general technology glossary
- An online dictionary resource page with pointers to many dictionaries for many languages
- A search engine that accesses several hundred online dictionaries
- O'Reilly Dictionary of PC Hardware and Data Communications Terms

Internet encyclopedias include:

- Connected
- whatis.com

## Definitions

3DES (Triple DES)
  Using three DES encryptions on a single data block, with at least two different keys, to get higher security than is available from a single DES pass. The three-key version of 3DES is the default encryption algorithm for Linux FreeS/WAN.

IPSEC always does 3DES with three different keys, as required by RFC 2451. For an explanation of the two-key variant, see two key triple DES. Both use an EDE encrypt-decrypt-encrpyt sequence of operations.

Single DES is insecure .

Double DES is ineffective. Using two 56-bit keys, one might expect an attacker to have to do 2112 work to break it. In fact, only 257 work is required with a meet-in-the-middle attack, though a large amount of memory is also required. Triple DES is vulnerable to a similar attack, but that just reduces the work factor from the 2168 one might expect to 2 112. That provides adequate protection against brute force attacks, and no better attack is known.

3DES can be somewhat slow compared to other ciphers. It requires three DES encryptions per block. DES was designed for hardware implementation and includes some operations which are difficult in software. However, the speed we get is quite acceptable for many uses. See benchmarks below for details.

A
Active attack
  An attack in which the attacker does not merely eavesdrop (see passive attack) but takes action to change, delete, reroute, add, forge or divert data. Perhaps the best-known active attack is man-in-the-middle. In general, authentication is a useful defense against active attacks.
AES
  The Advanced Encryption Standard, a new block cipher standard to replace DES being developed by NIST, the US National Institute of Standards and Technology. DES used 64-bit blocks and a 56-bit key. AES ciphers use a 128-bit block and are required to support 128, 192 and 256-bit keys. Some of them support other sizes as well. The larger block size helps resist birthday attacks while the large key size prevents brute force attacks.

Fifteen proposals meeting NIST's basic criteria were submitted in 1998 and subjected to intense discussion and analysis, "round one" evaluation. In August 1999, NIST narrowed the field to five "round two" candidates:

- Mars from IBM
- RC6 from RSA
- Rijndael from two Belgian researchers
- Serpent, a British-Norwegian-Israeli research collaboration
- Twofish from the consulting firm Counterpane

In October 2000, NIST announced the winner -- Rijndael.

Adding one or more AES ciphers to Linux FreeS/WAN would be useful undertaking, and considerable freely available code exists to start from. One complication is that our code is built for a 64-bit block cipher and AES uses a 128-bit block. Volunteers via the mailing lists would be welcome.

For more information, see the NIST AES home page or the Block Cipher Lounge AES page. For code and benchmarks see Brian Gladman's page .

AH
  The IPSEC Authentication Header, added after the IP header. For details, see our IPSEC Overview document and/or RFC 2402.
Alice and Bob
  A and B, the standard example users in writing on cryptography and coding theory. Carol and Dave join them for protocols which require more players.

Bruce Schneier extends these with many others such as Eve the Eavesdropper and Victor the Verifier. His extensions seem to be in the process of becoming standard as well. See page 23 of Applied Cryptography

Alice and Bob have an amusing biography on the web.

ARPA
  see DARPA
ASIO
  Australian Security Intelligence Organisation.
Asymmetric cryptography
  See public key cryptography.
Authentication
  Ensuring that a message originated from the expected sender and has not been altered on route. IPSEC uses authentication in two places:

- peer authentication, authenticating the players in IKE's Diffie-Hellman key exchanges to prevent man-in-the-middle attacks. This can be done in a number of ways. The methods supported by FreeS/WAN are discussed in our configuration document.
- packet authentication, authenticating packets on an established SA, either with a separate authentication header or with the optional authentication in the ESP protocol. In either case, packet authentication uses a hashed message athentication code technique.

Outside IPSEC, passwords are perhaps the most common authentication mechanism. Their function is essentially to authenticate the person's identity to the system. Passwords are generally only as secure as the network they travel over. If you send a cleartext password over a tapped phone line or over a network with a packet sniffer on it, the security provided by that password becomes zero. Sending an encrypted password is no better; the attacker merely records it and reuses it at his convenience. This is called a replay attack.

A common solution to this problem is a challenge-response system. This defeats simple eavesdropping and replay attacks. Of course an attacker might still try to break the cryptographic algorithm used, or the random number generator.

Automatic keying
  A mode in which keys are automatically generated at connection establisment and new keys automaically created periodically thereafter. Contrast with manual keying in which a single stored key is used.

IPSEC uses the Diffie-Hellman key exchange protocol to create keys. An authentication mechansim is required for this. The methods supported by FreeS/WAN are discussed in our configuration document.

Having an attacker break the authentication is emphatically not a good idea. An attacker that breaks authentication, and manages to subvert some other network entities (DNS, routers or gateways), can use a man-in-the middle attack to break the security of your IPSEC connections.

However, having an attacker break the authentication in automatic keying is not quite as bad as losing the key in manual keying.

- An attacker who reads /etc/ipsec.conf and gets the keys for a manually keyed connection can, without further effort, read all messages encrypted with those keys, including any old messages he may have archived.
- Automatic keying has a property called perfect forward secrecy. An attacker who breaks the authentication gets none of the automatically generated keys and cannot immediately read any messages. He has to mount a successful man-in-the-middle attack in real time before he can read anything. He cannot read old archived messages at all and will not be able to read any future messages not caught by man-in-the-middle tricks.

That said, the secrets used for authentication, stored in ipsec.secrets(5), should still be protected as tightly as cryptographic keys.

B
Bay Networks
  A vendor of routers, hubs and related products, now a subsidiary of Nortel. Interoperation between their IPSEC products and Linux FreeS/WAN was problematic at last report; see our interoperation section.
benchmarks
  Our default block cipher, triple DES, is slower than many alternate ciphers that might be used. Speeds achieved, however, seem adequate for many purposes. For example, the assembler code from the LIBDES library we use encrypts 1.6 megabytes per second on a Pentium 200, according to the test program supplied with the library.

For more detail, see our document on FreeS/WAN performance.

BIND
  Berkeley Internet Name Daemon, a widely used implementation of DNS (Domain Name Service). See our bibliography for a useful reference. See the BIND home page for more information and the latest version.
Birthday attack
  A cryptographic attack based on the mathematics exemplified by the birthday paradox. This math turns up whenever the question of two cryptographic operations producing the same result becomes an issue:
  - collisions in message digest functions.
  - identical output blocks from a block cipher
  - repetition of a challenge in a challenge-response system

Resisting such attacks is part of the motivation for:

- hash algorithms such as SHA and RIPEMD-160 giving a 160-bit result rather than the 128 bits of MD4, MD5 and RIPEMD-128.
- AES block ciphers using a 128-bit block instead of the 64-bit block of most current ciphers
- IPSEC using a 32-bit counter for packets sent on an automatically keyed SA and requiring that the connection always be rekeyed before the counter overflows.

Birthday paradox
  Not really a paradox, just a rather counter-intuitive mathematical fact. In a group of 23 people, the chance of a least one pair having the same birthday is over 50%.

The second person has 1 chance in 365 (ignoring leap years) of matching the first. If they don't match, the third person's chances of matching one of them are 2/365. The 4th, 3/365, and so on. The total of these chances grows more quickly than one might guess.

Block cipher
  A symmetric cipher which operates on fixed-size blocks of plaintext, giving a block of ciphertext for each. Contrast with stream cipher. Block ciphers can be used in various modes when multiple block are to be encrypted.

DES is among the the best known and widely used block ciphers, but is now obsolete. Its 56-bit key size makes it highly insecure today. Triple DES is the default transform for Linux FreeS/WAN because it is the only cipher which is both required in the RFCs and apparently secure.

The current generation of block ciphers -- such as Blowfish, CAST-128 and IDEA -- all use 64-bit blocks and 128-bit keys. The next generation, AES, uses 128-bit blocks and supports key sizes up to 256 bits.

The Block Cipher Lounge web site has more information.

Blowfish
  A block cipher using 64-bit blocks and keys of up to 448 bits, designed by Bruce Schneier and used in several products.

This is not required by the IPSEC RFCs and not currently used in Linux FreeS/WAN.

Brute force attack (exhaustive search)
  Breaking a cipher by trying all possible keys. This is always possible in theory (except against a one-time pad), but it becomes practical only if the key size is inadequate. For an important example, see our document on the insecurity of DES with its 56-bit key. For an analysis of key sizes required to resist plausible brute force attacks, see this paper.

Longer keys protect against brute force attacks. Each extra bit in the key doubles the number of possible keys and therefore doubles the work a brute force attack must do. A large enough key defeats any brute force attack.

For example, the EFF's DES Cracker searches a 56-bit key space in an average of a few days. Let us assume an attacker that can find a 64-bit key (256 times harder) by brute force search in a second (a few hundred thousand times faster). For a 96-bit key, that attacker needs 232 seconds, just over a century. Against a 128-bit key, he needs 232 centuries or about 400,000,000,000 years. Your data is then obviously secure against brute force attacks. Even if our estimate of the attacker's speed is off by a factor of a million, it still takes him 400,000 years to crack a message.

This is why

- single DES is now considered dangerously insecure
- all of the current generation of block ciphers use a 128-bit or longer key
- AES ciphers support keysizes 128, 192 and 256 bits
- any cipher we add to Linux FreeS/WAN will have at least a 128-bit key

Cautions:
Inadequate keylength always indicates a weak cipher but it is important to note that adequate keylength does not necessarily indicate a strong cipher. There are many attacks other than brute force, and adequate keylength only guarantees resistance to brute force. Any cipher, whatever its key size, will be weak if design or implementation flaws allow other attacks.

Also, once you have adequate keylength (somewhere around 90 or 100 bits), adding more key bits make no practical difference , even against brute force. Consider our 128-bit example above that takes 400 billion years to break by brute force. Do we care if an extra 16 bits of key put that into the quadrillions? No. What about 16 fewer bits reducing it to the 112-bit security level of Triple DES, which our example attacker could break in just over a billion years? No again, unless we're being really paranoid about safety margins.

There may be reasons of convenience in the design of the cipher to support larger keys. For example Blowfish allows up to 448 bits and RC4 up to 2048, but beyond 100-odd bits it makes no difference to practical security.

Bureau of Export Administration
  see BXA
BXA
  The US Commerce Department's Bureau of Export A dministration which administers the EAR Export Administration Regulations controling the export of, among other things, cryptography.
C
CA
  Certification Authority, an entity in a public key infrastructure that can certify keys by signing them. Usually CAs form a hierarchy. The top of this hierarchy is called the root CA.

See Web of Trust for an alternate model.

CAST-128
  A block cipher using 64-bit blocks and 128-bit keys, described in RFC 2144 and used in products such as Entrust and recent versions of PGP.

This is not required by the IPSEC RFCs and not currently used in Linux FreeS/WAN.

CAST-256
  Entrust's candidate cipher for the AES standard, largely based on the CAST-128 design.
CBC mode
  Cipher Block Chaining mode , a method of using a block cipher in which for each block except the first, the result of the previous encryption is XORed into the new block before it is encrypted. CBC is the mode used in IPSEC.

An initialisation vector (IV) must be provided. It is XORed into the first block before encryption. The IV need not be secret but should be different for each message and unpredictable.

Certification Authority
  see CA
Cipher Modes
  Different ways of using a block cipher when encrypting multiple blocks.

Four standard modes were defined for DES in FIPS 81. They can actually be applied with any block cipher.

| ECB | Electronic CodeBook | encrypt each block independently
| CBC | Cipher Block Chaining | XOR previous block ciphertext into new block plaintext before encrypting new block
| CFB | Cipher FeedBack |
| OFB | Output FeedBack |

IPSEC uses CBC mode since this is only marginally slower than ECB and is more secure. In ECB mode the same plaintext always encrypts to the same ciphertext, unless the key is changed. In CBC mode, this does not occur.

Various other modes are also possible, but none of them are used in IPSEC.

Challenge-response authentication
  An authentication system in which one player generates a random number, encrypts it and sends the result as a challenge. The other player decrypts and sends back the result. If the result is correct, that proves to the first player that the second player knew the appropriate secret, required for the decryption. Variations on this technique exist using public key or symmetric cryptography. Some provide two-way authentication, assuring each player of the other's identity.

This is more secure than passwords against two simple attacks:

- If cleartext passwords are sent across the wire (e.g. for telnet), an eavesdropper can grab them. The attacker may even be able to break into other systems if the user has chosen the same password for them.
- If an encrypted password is sent, an attacker can record the encrypted form and use it later. This is called a replay attack.

A challenge-response system never sends a password, either cleartext or encrypted. An attacker cannot record the response to one challenge and use it as a response to a later challenge. The random number is different each time.

Of course an attacker might still try to break the cryptographic algorithm used, or the random number generator.

Ciphertext
  The encrypted output of a cipher, as opposed to the unencrypted plaintext input.
Cisco
  A vendor of routers, hubs and related products. Their IPSEC products interoperate with Linux FreeS/WAN; see our interop section.
Client
  This term has at least two distinct uses in discussing IPSEC:
  - The clients of an IPSEC gateway are the machines it protects, typically on one or more subnets behind the gateway. In this usage, all the machines on an office network are clients of that office's IPSEC gateway. Laptop or home machines connecting to the office, however, are not clients of that gateway. They are remote gateways, running the other end of an IPSEC connection. Each of them is also its own client.
  - IPSEC client software is used to describe software which runs on various standalone machines to let them connect to IPSEC networks. In this usage, a laptop or home machine connecting to the office is a client machine.

We generally use the term in the first sense. Vendors of Windows IPSEC solutions often use it in the second.

Conventional cryptography
  See symmetric cryptography
Collision resistance
  The property of a message digest algorithm which makes it hard for an attacker to find or construct two inputs which hash to the same output.
Copyleft
  see GNU General Public License
CSE
  Communications Security Establishment, the Canadian organisation for signals intelligence.
D
DARPA (sometimes just ARPA)
  The US government's Defense Advanced Research Projects Agency. Projects they have funded over the years have included the Arpanet which evolved into the Internet, the TCP/IP protocol suite (as a replacement for the original Arpanet suite), the Berkeley 4.x BSD Unix projects, and Secure DNS.

For current information, see their web site.

Denial of service (DoS) attack
  An attack that aims at denying some service to legitimate users of a system, rather than providing a service to the attacker.
  - One variant is a flooding attack, overwhelming the system with too many packets, to much email, or whatever.
  - A closely related variant is a resource exhaustion attack. For example, consider a "TCP SYN flood" attack. Setting up a TCP connection involves a three-packet exchange:
    - Initiator: Connection please (SYN)
    - Responder: OK (ACK)
    - Initiator: OK here too

  If the attacker puts bogus source information in the first packet, such that the second is never delivered, the responder may wait a long time for the third to come back. If responder has already allocated memory for the connection data structures, and if many of these bogus packets arrive, the responder may run out of memory.

  - Another variant is to feed the system undigestible data, hoping to make it sick. For example, IP packets are limited in size to 64K bytes and a fragment carries information on where it starts within that 64K and how long it is. The "ping of death" delivers fragments that say, for example, that they start at 60K and are 20K long. Attempting to re-assemble these without checking for overflow can be fatal.

The two example attacks discussed were both quite effective when first discovered, capable of crashing or disabling many operating systems. They were also well-publicised, and today far fewer systems are vulnerable to them.

DES
  The Data Encryption Standard, a block cipher with 64-bit blocks and a 56-bit key. Probably the most widely used symmetric cipher ever devised. DES has been a US government standard for their own use (only for unclassified data), and for some regulated industries such as banking, since the late 70's.

DES is seriously insecure against current attacks.

Linux FreeS/WAN does not include DES, even though the RFCs specify it. We strongly recommend that single DES not be used.

See also 3DES and DESX, stronger ciphers based on DES.

DESX
  An improved DES suggested by Ron Rivest of RSA Data Security. It XORs extra key material into the text before and after applying the DES cipher.

This is not required by the IPSEC RFCs and not currently used in Linux FreeS/WAN. DESX would be the easiest additional transform to add; there would be very little code to write. It would be much faster than 3DES and almost certainly more secure than DES. However, since it is not in the RFCs other IPSEC implementations cannot be expected to have it.

DH
  see Diffie-Hellman
Diffie-Hellman (DH) key exchange protocol
  A protocol that allows two parties without any initial shared secret to create one in a manner immune to eavesdropping. Once they have done this, they can communicate privately by using that shared secret as a key for a block cipher or as the basis for key exchange.

The protocol is secure against all passive attacks, but it is not at all resistant to active man-in-the-middle attacks. If a third party can impersonate Bob to Alice and vice versa, then no useful secret can be created. Authentication of the participants is a prerequisite for safe Diffie-Hellman key exchange. IPSEC can use any of several authentication mechanisims. Those supported by FreeS/WAN are discussed in our configuration section.

The Diffie-Hellman key exchange is based on the discrete logarithm problem and is secure unless someone finds an efficient solution to that problem.

Given a prime p and generator g (explained under discrete log below), Alice:

- generates a random number a
- calculates A = g^a modulo p
- sends A to Bob

Meanwhile Bob:

- generates a random number b
- calculates B = g^b modulo p
- sends B to Alice

Now Alice and Bob can both calculate the shared secret s = g^(ab). Alice knows a and B, so she calculates s = B^a. Bob knows A and b so he calculates s = A^b.

An eavesdropper will know p and g since these are made public, and can intercept A and B but, short of solving the discrete log problem, these do not let him or her discover the secret s.

Digital signature
  Sender:
  - calculates a message digest of a document
  - encrypts the digest with his or her private key, using some public key cryptosystem.
  - attaches the encrypted digest to the document as a signature

Receiver:

- calculates a digest of the document (not including the signature)
- decrypts the signature with the signer's public key
- verifies that the two results are identical

If the public-key system is secure and the verification succeeds, then the receiver knows

- that the document was not altered between signing and verification
- that the signer had access to the private key

Such an encrypted message digest can be treated as a signature since it cannot be created without both the document and the private key which only the sender should possess. The legal issues are complex, but several countries are moving in the direction of legal recognition for digital signatures.

discrete logarithm problem
  The problem of finding logarithms in a finite field. Given a field defintion (such definitions always include some operation analogous to multiplication) and two numbers, a base and a target, find the power which the base must be raised to in order to yield the target.

The discrete log problem is the basis of several cryptographic systems, including the Diffie-Hellman key exchange used in the IKE protocol. The useful property is that exponentiation is relatively easy but the inverse operation, finding the logarithm, is hard. The cryptosystems are designed so that the user does only easy operations (exponentiation in the field) but an attacker must solve the hard problem (discrete log) to crack the system.

There are several variants of the problem for different types of field. The IKE/Oakley key determination protocol uses two variants, either over a field modulo a prime or over a field defined by an elliptic curve. We give an example modulo a prime below. For the elliptic curve version, consult an advanced text such as Handbook of Applied Cryptography.

Given a prime p, a generator g for the field modulo that prime, and a number x in the field, the problem is to find y such that g^y = x.

For example, let p = 13. The field is then the integers from 0 to 12. Any integer equals one of these modulo 13. That is, the remainder when any integer is divided by 13 must be one of these.

2 is a generator for this field. That is, the powers of two modulo 13 run through all the non-zero numbers in the field. Modulo 13 we have:

              y      x
            2^0  ==  1
            2^1  ==  2
            2^2  ==  4
            2^3  ==  8
            2^4  ==  3 that is, the remainder from 16/13 is 3
            2^5  ==  6          the remainder from 32/13 is 6
            2^6  == 12 and so on
            2^7  == 11
            2^8  ==  9
            2^9  ==  5
            2^10 == 10
            2^11 ==  7
            2^12 ==  1

Exponentiation in such a field is not difficult. Given, say, y = 11, calculating x = 7 is straightforward. One method is just to calculate 2^11 = 2048 , then 2048 mod 13 == 7. When the field is modulo a large prime (say a few 100 digits) you need a silghtly cleverer method and even that is moderately expensive in computer time, but the calculation is still not problematic in any basic way.

The discrete log problem is the reverse. In our example, given x = 7, find the logarithm y = 11. When the field is modulo a large prime (or is based on a suitable elliptic curve), this is indeed problematic. No solution method that is not catastrophically expensive is known. Quite a few mathematicians have tackled this problem. No efficient method has been found and mathematicians do not expect that one will be. It seems likely no efficient solution to either of the main variants the discrete log problem exists.

Note, however, that no-one has proven such methods do not exist. If a solution to either variant were found, the security of any crypto system using that variant would be destroyed. This is one reason IKE supports two variants. If one is broken, we can switch to the other.

DNS
  Domain Name Service, a distributed database through which names are associated with numeric addresses and other information in the Internet Protocol Suite. See also BIND, the Berkeley Internet Name Daemon which implements DNS services and Secure DNS. See our bibliography for a useful reference on both.
DOS attack
  see Denial Of Service attack
E
EAR
  The US government's Export Administration R egulations, administered by the Bureau of Export Administration. These have replaced the earlier ITAR regulations as the controls on export of cryptography.
ECB mode
  Electronic CodeBook mode, the simplest way to use a block cipher. See Cipher Modes.
EDE
  The sequence of operations normally used in either the three-key variant of triple DES used in IPSEC or the two-key variant used in some other systems.

The sequence is:

- Encrypt with key1
- Decrypt with key2
- Encrypt with key3

For the two-key version, key1=key3.

The "advantage" of this EDE order of operations is that it makes it simple to interoperate with older devices offering only single DES. Set key1=key2=key3 and you have the worst of both worlds, the overhead of triple DES with the security of single DES. Since single DES is insecure, this is an extremely dubious "advantage".

The EDE two-key variant can also interoperate with the EDE three-key variant used in IPSEC; just set k1=k3.

Entrust
  A Canadian company offerring enterprise PKI products using CAST-128 symmetric crypto, RSA public key and X.509 directories.
EFF
  Electronic Frontier Foundation, an advocacy group for civil rights in cyberspace.
Encryption
  Techniques for converting a readable message ( plaintext) into apparently random material ( ciphertext) which cannot be read if intercepted. A key is required to read the message.

Major variants include symmetric encryption in which sender and receiver use the same secret key and public key methods in which the sender uses one of a matched pair of keys and the receiver uses the other. Many current systems, including IPSEC, are hybrids combining the two techniques.

ESP
  Encapsulated Security Payload, the IPSEC protocol which provides encryption. It can also provide authentication service and may be used with null encryption (which we do not recommend). For details see our IPSEC Overview document and/or RFC 2406.
Extruded subnet
  A situation in which something IP sees as one network is actually in two or more places.

For example, the Internet may route all traffic for a particular company to that firm's corporate gateway. It then becomes the company's problem to get packets to various machines on their subnets in various departments. They may decide to treat a branch office like a subnet, giving it IP addresses "on" their corporate net. This becomes an extruded subnet.

Packets bound for it are delivered to the corporate gateway, since as far as the outside world is concerned, that subnet is part of the corporate network. However, instead of going onto the corporate LAN (as they would for, say, the accounting department) they are then encapsulated and sent back onto the Internet for delivery to the branch office.

For information on doing this with Linux FreeS/WAN, look in our Configuration file.

Exhaustive search
  See brute force attack.
F
FIPS
  Federal Information Processing S tandard, the US government's standards for products it buys. These are issued by NIST. Among other things, DES and SHA are defined in FIPS documents. NIST have a FIPS home page.
Free Software Foundation (FSF)
  An organisation to promote free software, free in the sense of these quotes from their web pages

  > "Free software" is a matter of liberty, not price. To understand the concept, you should think of "free speech", not "free beer."

  > "Free software" refers to the users' freedom to run, copy, distribute, study, change and improve the software.

See also GNU, GNU General Public License, and the FSF site.

FreeSWAN
  see Linux FreeS/WAN
FSF
  see Free software Foundation
G
GCHQ
  Government Communications Headquarters, the British organisation for signals intelligence.
generator of a prime field
  see discrete logarithm problem
GILC
  Global Internet Liberty Campaign, an international organisation advocating, among other things, free availability of cryptography. They have a campaign to remove cryptographic software from the Wassenaar Arrangement.
Global Internet Liberty Campaign
  see GILC.
Global Trust Register
  An attempt to create something like a root CA for PGP by publishing both as a book and on the web the fingerprints of a set of verified keys for well-known users and organisations.
GMP
  The GNU Multi-Precision library code, used in Linux FreeS/WAN by Pluto for public key calculations.
GNU
  GNU's Not Unix, the Free Software Foundation's project aimed at creating a free system with at least the capabilities of Unix. Linux uses GNU utilities extensively.
GPG
  see GNU Privacy Guard
GNU General Public License(GPL, copyleft)
  The license developed by the Free Software Foundation under which Linux, Linux FreeS/WAN and many other pieces of software are distributed. The license allows anyone to redistribute and modify the code, but forbids anyone from distributing executables without providing access to source code. For more details see the file COPYING included with GPLed source distributions, including ours, or the GNU site's GPL page.
GNU Privacy Guard
  An open source implementation of Open PGP as defined in RFC 2440.
GPL
  see GNU General Public License.
H
Hash
  see message digest
Hashed Message Authentication Code (HMAC)
  using keyed message digest functions to authenticate a message. This differs from other uses of these functions:
  - In normal usage, the hash function's internal variable are initialised in some standard way. Anyone can reproduce the hash to check that the message has not been altered.
  - For HMAC usage, you initialise the internal variables from the key. Only someone with the key can reproduce the hash. A successful check of the hash indicates not only that the message is unchanged but also that the creator knew the key.

The exact techniques used in IPSEC are defined in RFC 2104. They are referred to as HMAC-MD5-96 and HMAC-SHA-96 because they output only 96 bits of the hash. This makes some attacks on the hash functions harder.

HMAC
  see Hashed Message Authentication Code
HMAC-MD5-96
  see Hashed Message Authentication Code
HMAC-SHA-96
  see Hashed Message Authentication Code
Hybrid cryptosystem
  A system using both public key and symmetric cipher techniques. This works well. Public key methods provide key management and digital signature facilities which are not readily available using symmetric ciphers. The symmetric cipher, however, can do the bulk of the encryption work much more efficiently than public key methods.
I
IAB
  Internet Architecture Board.
ICMP
  Internet Control M essage Protocol. This is used for various IP-connected devices to manage the network.
IDEA
  International Data Encrypion Algorithm, developed in Europe as an alternative to exportable American ciphers such as DES which were too weak for serious use. IDEA is a block cipher using 64-bit blocks and 128-bit keys, and is used in products such as PGP.

IDEA is not required by the IPSEC RFCs and not currently used in Linux FreeS/WAN.

IDEA is patented and, with strictly limited exceptions for personal use, using it requires a license from Ascom.

IESG
  Internet Engineering Steering Group .
IETF
  Internet Engineering Task Force, the umbrella organisation whose various working groups make most of the technical decisions for the Internet. The IETF IPSEC working group wrote the RFCs we are implementing.
IKE
  Internet Key Exchange, based on the Diffie-Hellman key exchange protocol. IKE is implemented in Linux FreeS/WAN by the Pluto daemon.
Initialisation Vector (IV)
  Some cipher modes, including the CBC mode which IPSEC uses, require some extra data at the beginning. This data is called the initialisation vector. It need not be secret, but should be different for each message. Its function is to prevent messages which begin with the same text from encrypting to the same ciphertext. That might give an analyst an opening, so it is best prevented.
IP
  Internet Protocol.
IP masquerade
  A method of allowing multiple machines to communicate over the Internet when only one IP address is available for their use. See the Linux masquerade resource page for details.

The client machines are set up with reserved non-routable IP addresses defined in RFC 1918. The masquerading gateway, the machine with the actual link to the Internet, rewrites packet headers so that all packets going onto the Internet appear to come from one IP address, that of its Internet interface. It then gets all the replies, does some table lookups and more header rewriting, and delivers the replies to the appropriate client machines.

For information on using masquerade with Linux FreeS/WAN, see our firewall document and the FAQ and.

IPng
  "IP the Next Generation", see IPv6.
IPv4
  The current version of the Internet protocol suite .
IPv6 (IPng)
  Version six of the Internet protocol suite, currently being developed. It will replace the current version four. IPv6 has IPSEC as a mandatory component.

See this web site for more details, and our compatibility document for information on FreeS/WAN and the Linux implementation of IPv6.

IPSEC
  Internet Protocol SECurity, security functions (authentication and encryption) implemented at the IP level of the protocol stack. It is optional for IPv4 and mandatory for IPv6.

This is the standard Linux FreeS/WAN is implementing. For more details, see our IPSEC Overview. For the standards, see RFCs listed in our RFCs document.

ISAKMP
  Internet Security Association and Key Management Protocol, defined in RFC 2408.
ITAR
  International Traffic in Arms R egulations, US regulations administered by the State Department which until recently limited export of, among other things, cryptographic technology and software. ITAR still exists, but the limits on cryptography have now been transferred to the Export Administration Regulations under the Commerce Department's Bureau of Export Administration.
IV
  see Initialisation vector
J
K
Kernel
  The basic part of an operating system (e.g. Linux) which controls the hardware and provides services to all other programs.

In the Linux release numbering system, an even second digit as in 2. 2.x indicates a stable or production kernel while an odd number as in 2.3.x indicates an experimental or development kernel. Most users should run a recent kernel version from the production series. The development kernels are primarily for people doing kernel development. Others should consider using development kernels only if they have an urgent need for some feature not yet available in production kernels.

Keyed message digest
  See HMAC.
Key length
  see brute force attack
KLIPS
  Kernel IP Security, the Linux FreeS/WAN project's changes to the Linux kernel to support the IPSEC protocols.
L
LDAP
  Lightweight Directory Access Protocol, defined in RFCs 1777 and 1778, a method of accessing information stored in directories. LDAP is used by several PKI implementations, often with X.501 directories and X.509 certificates. It may also be used by IPSEC to obtain key certifications from those PKIs. This is not yet implemented in Linux FreeS/WAN.
LIBDES
  A publicly available library of DES code, written by Eric Young, which Linux FreeS/WAN uses in both KLIPS and Pluto .
Linux
  A freely available Unix-like operating system based on a kernel originally written for the Intel 386 architecture by (then) student Linus Torvalds. Once his 32-bit kernel was available, the GNU utilities made it a usable system and contributions from many others led to explosive growth.

Today Linux is a complete Unix replacement available for several CPU architectures -- Intel, DEC/Compaq Alpha, Power PC, both 32-bit SPARC and the 64-bit UltraSPARC, SrongARM, . . . -- with support for multiple CPUs on some architectures.

Linux FreeS/WAN is intended to run on all CPUs supported by Linux and is known to work on several. See our compatibility section for a list.

Linux FreeS/WAN
  Our implementation of the IPSEC protocols, intended to be freely redistributable source code with a GNU GPL license and no constraints under US or other export laws. Linux FreeS/WAN is intended to interoperate with other IPSEC implementations. The name is partly taken, with permission, from the S/WAN multi-vendor IPSEC compatability effort. Linux FreeS/WAN has two major components, KLIPS (KerneL IPSEC Support) and the Pluto daemon which manages the whole thing.

See our IPSEC Overview for more detail. For the code see our primary distribution site or one of the mirror sites on this list.

M
Mailing list
  The Linux FreeS/WAN project has several public email lists for bug reports and software development discussions. See our document on mailing lists.
Man-in-the-middle attack
  An active attack in which the attacker impersonates each of the legitimate players in a protocol to the other.

For example, if Alice and Bob are negotiating a key via the Diffie-Hellman key agreement, and are not using authentication to be certain they are talking to each other, then an attacker able to insert himself in the communication path can deceive both players.

Call the attacker Mallory. For Bob, he pretends to be Alice. For Alice, he pretends to be Bob. Two keys are then negotiated, Alice-to-Mallory and Bob-to-Mallory. Alice and Bob each think the key they have is Alice-to-Bob.

A message from Alice to Bob then goes to Mallory who decrypts it, reads it and/or saves a copy, re-encrypts using the Bob-to-Mallory key and sends it along to Bob. Bob decrypts successfully and sends a reply which Mallory decrypts, reads, re-encrypts and forwards to Alice.

To make this attack effective, Mallory must

- subvert some part of the network in some way that lets him carry out the deception
  possible targets: DNS, router, Alice or Bob's machine, mail server, ...
- beat any authentication mechanism Alice and Bob use
  strong authentication defeats the attack entirely; this is why IKE requires authentication
- work in real time, delivering messages without introducing a delay large enough to alert the victims
  not hard if Alice and Bob are using email; quite difficult in some situations.

If he manages it, however, it is devastating. He not only gets to read all the messages; he can alter messages, inject his own, forge anything he likes, . . . In fact, he controls the communication completely.

Manual keying
  An IPSEC mode in which the keys are provided by the administrator. In FreeS/WAN, they are stored in /etc/ipsec.conf. The alternative, automatic keying, is preferred in most cases.
MD4
  Message Digest Algorithm Four from Ron Rivest of RSA. MD4 was widely used a few years ago, but is now considered obsolete. It has been replaced by its descendants MD5 and SHA.
MD5
  Message Digest Algorithm Five from Ron Rivest of RSA, an improved variant of his MD4. Like MD4, it produces a 128-bit hash. For details see RFC 1321.

MD5 is one of two message digest algorithms available in IPSEC. The other is SHA. SHA produces a longer hash and is therefore more resistant to birthday attacks, but this is not a concern for IPSEC. The HMAC method used in IPSEC is secure even if the underlying hash is not particularly strong against this attack.

Meet-in-the-middle attack
  A divide-and-conquer attack which breaks a cipher into two parts, works against each separately, and compares results. Probably the best known example is an attack on double DES. This applies in principle to any pair of block ciphers, e.g. to an encryption system using, say, CAST-128 and Blowfish, but we will describe it for double DES.

Double DES encryption and decryption can be written:

            C = E(k2,E(k1,P))
            P = D(k1,D(k2,C))

Where C is ciphertext, P is plaintext, E is encryption, D is decryption, k1 is one key, and k2 is the other key. If we know a P, C pair, we can try and find the keys with a brute force attack, trying all possible k1, k2 pairs. Since each key is 56 bits, there are 2 112 such pairs and this attack is painfully inefficient.

The meet-in-the middle attack re-writes the equations to calculate a middle value M:

            M = E(k1,P)
            M = D(k2,C)

Now we can try some large number of D(k2,C) decryptions with various values of k2 and store the results in a table. Then start doing E(k1,P) encryptions, checking each result to see if it is in the table.

With enough table space, this breaks double DES with 257 work. The memory requirements of such attacks can be prohibitive, but there is a whole body of research literature on methods of reducing them.

Message Digest Algorithm
  An algorithm which takes a message as input and produces a hash or digest of it, a fixed-length set of bits which depend on the message contents in some highly complex manner. Design criteria include making it extremely difficult for anyone to counterfeit a digest or to change a message without altering its digest. One essential property is collision resistance. The main applications are in message authentication and digital signature schemes. Widely used algorithms include MD5 and SHA. In IPSEC, message digests are used for HMAC authentication of packets.
MTU
  Maximum Transmission U nit, the largest size of packet that can be sent over a link. This is determined by the underlying network, but must be taken account of at the IP level.

IP packets, which can be up to 64K bytes each, must be packaged into lower-level packets of the appropriate size for the underlying network(s) and re-assembled on the other end. When a packet must pass over multiple networks, each with its own MTU, and many of the MTUs are unknown to the sender, this becomes a fairly complex problem. See path MTU discovery for details.

Often the MTU is a few hundred bytes on serial links and 1500 on Ethernet. There are, however, serial link protocols which use a larger MTU to avoid fragmentation at the ethernet/serial boundary, and newer (especially gigabit) Ethernet networks sometimes support much larger packets because these are more efficient in some applications.

N
NAI
  Network Associates, a conglomerate formed from PGP Inc., TIS, Macaffee Anti-virus products and several others. Among other things, they offer an IPSEC-based VPN.
NAT
  Network Address Translation.
NIST
  The US National Institute of Standards and Technology, responsible for FIPS standards including DES and its replacement, AES.
Nonce
  A random value used in an authentication protocol.
Non-routable IP address
  An IP address not normally allowed in the "to" or "from" IP address field header of IP packets.

Almost invariably, the phrase "non-routable address" means one of the addresses reserved by RFC 1918 for private networks:

- 10.anything
- 172.x.anything with 16 <= x <= 31
- 192.168.anything

These addresses are commonly used on private networks, e.g. behind a Linux machines doing IP masquerade. Machines within the private network can address each other with these addresses. All packets going outside that network, however, have these addresses replaced before they reach the Internet.

If any packets using these addresses do leak out, they do not go far. Most routers automatically discard all such packets.

Various other addresses -- the 127.0.0.0/8 block reserved for local use, 0.0.0.0, various broadcast and network addresses -- cannot be routed over the Internet, but are not normally included in the meaning when the phrase "non-routable address" is used.

NSA
  The US National Security Agency, the American organisation for signals intelligence , the protection of US government messages and the interception and analysis of other messages. For details, see Bamford's "The Puzzle Palace".

Some history of NSA documents were declassified in response to a FOIA (Freedom of Information Act) request.

O
Oakley
  A key determination protocol, defined in RFC 2412.
Oakley groups
  The groups used as the basis of Diffie-Hellman key exchange in the Oakley protocol, and in IKE. Four were defined in the original RFC, and a fifth has been added since.

Linux FreeS/WAN currently supports the three groups based on finite fields modulo a prime (Groups 1, 2 and 5) and does not support the elliptic curve groups (3 and 4). For a description of the difference of the types, see discrete logarithms.

One time pad
  A cipher in which the key is:
  - as long as the total set of messages to be enciphered
  - absolutely random
  - never re-used

Given those three conditions, it can easily be proved that the cipher is perfectly secure, in the sense that an attacker with intercepted message in hand has no better chance of guessing the message than an attacker who has nt interecepted the message and only knows the message length. No such proof exists for any other cipher.

There are, however, several problems with this "perfect" cipher.

- It is wildly impractical for many applications. Key management is difficult or impossible.
- It is extremely fragile. Small changes which violate the conditions listed above do not just weaken the cipher a bit; quite often they destroy its security completely.
  - Re-using the pad weakens it to the point where it can be broken with pencil and paper. With a computer, the attack is trivially easy.
  - Using computer-generated pseudo-random numbers instead of a really random pad completely invalidates the security proof. Depending on random number generator used, this may also give an extremely weak cipher.
- If an attacker knows the plaintext and has an intercepted message, he can discover the pad. This does not matter if the attacker is just a passive eavesdropper. It gives him no plaintext he didn't already know and we don't care that he learns a pad which we'll never re-use. However, knowing the pad lets an active attacker perform a man-in-the-middle attack, replacing your message with whatever he chooses.

Marketing claims about the "unbreakable" security of various products which somewhat resemble one-time pads are common. Such claims are one of the surest signs of cryptographic snake oil. Systems marketed with such claims are usually completely worthless.

See also the one time pad FAQ.

Opportunistic encryption
  A situation in which any two IPSEC-aware machines can secure their communications, without a pre-shared secret and without a common PKI or previous exchange of public keys. This is one of the goals of the Linux FreeS/WAN project, discussed in our introduction section.

Setting up for opportunistic encryption is described in our configuration document.

P
P1363 standard
  An IEEE standard for public key cryptography.
Passive attack
  An attack in which the attacker only eavesdrops and attempts to analyse intercepted messages, as opposed to an active attack in which he diverts messages or generates his own.
Path MTU discovery
  The process of discovering the largest packet size which all links on a path can handle without fragmentation -- that is, without any router having to break the packet up into smaller pieces to match the MTU of its outgoing link.

This is done as follows:

- originator sends the largest packets allowed by MTU of the first link, setting the DF (don't f ragment) bit in the packet header
- any router which cannot send the packet on (outgoing MTU is too small for it, and DF prevents fragmenting it to match) sends back an ICMP packet reporting the problem
- originator looks at ICMP message and tries a smaller size
- eventually, you settle on a size that can pass all routers
- thereafter, originator just sends that size and no-one has to fragment

Since this requires co-operation of many systems, and since the next packet may travel a different path, this is one of the trickier areas of IP programming. Bugs that have shown up over the years have included:

- malformed ICMP messages
- hosts that ignore or mishandle these ICMP messages
- firewalls blocking the ICMP messages so host does not see them

Since IPSEC adds a header, it increases packet size and may require fragmentation even where incoming and outgoing MTU are equal.

Perfect forward secrecy (PFS)
  A property of systems such as Diffie-Hellman key exchange which use a long-term key (such as the shared secret in IKE) and generate short-term keys as required. If an attacker who acquires the long-term key provably can
  - neither read previous messages which he may have archived
  - nor read future messages without performing additional successful attacks

then the system has PFS. The attacker needs the short-term keys in order to read the trafiic and merely having the long-term key does not allow him to infer those. Of course, it may allow him to conduct another attack (such as man-in-the-middle) which gives him some short-term keys, but he does not automatically get them just by acquiring the long-term key.

PFS
  see Perfect Forward Secrecy
PGP
  Pretty Good Privacy, a personal encryption system for email based on public key technology, written by Phil Zimmerman.

The 2.xx versions of PGP used the RSA public key algorithm and used IDEA as the symmetric cipher. These versions are described in RFC 1991 and in Garfinkel's book. Since version 5, the products from PGP Inc. have used Diffie-Hellman public key methods and CAST-128 symmetric encryption. These can verify signatures from the 2.xx versions, but cannot exchange encryted messages with them.

An IETF working group has issued RFC 2440 for an "Open PGP" standard, similar to the 5.x versions. PGP Inc. staff were among the authors. A free Gnu Privacy Guard based on that standard is now available.

For more information on PGP, including how to obtain it, see our cryptography links.

PGP Inc.
  A company founded by Zimmerman, the author of PGP , now a division of NAI. See the corporate website.

Their PGP 6.5 product includes PGPnet, an IPSEC client for Macintosh or for Windows 95/98/NT.

Photuris
  Another key negotiation protocol, an alternative to IKE, described in RFCs 2522 and 2523.
PPTP
  Point-to-Point Tunneling Protocol. Papers discussing weaknesses in it are on counterpane.com.
PKI
  Public Key Infrastructure, the things an organisation or community needs to set up in order to make public key cryptographic technology a standard part of their operating procedures.

There are several PKI products on the market. Typically they use a hierarchy of Certification Authorities (CAs). Often they use LDAP access to X.509 directories to implement this.

See Web of Trust for a different sort of infrastructure.

PKIX
  PKI eXchange, an IETF standard that allows PKIs to talk to each other.

This is required, for example, when users of a corporate PKI need to communicate with people at client, supplier or government organisations, any of which may have a different PKI in place. I should be able to talk to you securely whenever:

- your organisation and mine each have a PKI in place
- you and I are each set up to use those PKIs
- the two PKIs speak PKIX
- the configuration allows the conversation

At time of writing (March 1999), this is not yet widely implemented but is under quite active development by several groups.

Plaintext
  The unencrypted input to a cipher, as opposed to the encrypted ciphertext output.
Pluto
  The Linux FreeS/WAN daemon which handles key exchange via the IKE protocol, connection negotiation, and other higher-level tasks. Pluto calls the KLIPS kernel code as required. For details, see the manual page ipsec_pluto(8).
Public Key Cryptography
  In public key cryptography, keys are created in matched pairs. Encrypt with one half of a pair and only the matching other half can decrypt it. This contrasts with symmetric or secret key cryptography in which a single key known to both parties is used for both encryption and decryption.

One half of each pair, called the public key, is made public. The other half, called the private key, is kept secret. Messages can then be sent by anyone who knows the public key to the holder of the private key. Encrypt with the public key and you know only someone with the matching private key can decrypt.

Public key techniques can be used to create digital signatures and to deal with key management issues, perhaps the hardest part of effective deployment of symmetric ciphers. The resulting hybrid cryptosystems use public key methods to manage keys for symmetric ciphers.

Many organisations are currently creating PKIs, public key infrastructures to make these benefits widely available.

Public Key Infrastructure
  see PKI
Q
R
Random
  A remarkably tricky term, far too much so for me to attempt a definition here. Quite a few cryptosystems have been broken via attacks on weak random number generators, even when the rest of the system was sound.

See RFC 1750 for the theory. It will be available locally if you have downloaded our RFC bundle (which is described here). Or read it on the net.

See the manual pages for ipsec_ranbits(8) and random(4) for details of what we use.

There has recently been discussion on several mailing lists of the limitations of Linux /dev/random and of whether we are using it correctly. Those discussions are archived on the /dev/random support page.

Raptor
  A firewall product for Windows NT offerring IPSEC-based VPN services. Linux FreeS/WAN interoperates with Raptor; see our Compatibility document for details. Raptor have recently merged with Axent.
RC4
  Rivest Cipher four, designed by Ron Rivest of RSA and widely used. Believed highly secure with adequate key length, but often implemented with inadequate key length to comply with export restrictions.
RC6
  Rivest Cipher six, RSA's AES candidate cipher.
Replay attack
  An attack in which the attacker records data and later replays it in an attempt to deceive the recipient.
RFC
  Request For Comments, an Internet document. Some RFCs are just informative. Others are standards.

Our list of IPSEC and other security-related RFCs is here, along with information on methods of obtaining them.

RIPEMD
  A message digest algorithm. The current version is RIPEMD-160 which gives a 160-bit hash.
Root CA
  The top level Certification Authority in a hierachy of such authorities.
Routable IP address
  Most IP addresses can be used as "to" and "from" addresses in packet headers. These are the routable addresses; we expect routing to be possible for them. If we send a packet to one of them, we expect (in most cases; there are various complications) that it will be delivered if the address is in use and will cause an ICMP error packet to come back to us if not.

There are also several classes of non-routable IP addresses.

RSA algorithm
  Rivest Shamir Adleman public key encryption method, named for its three inventors. The algorithm is widely used and likely to become moreso since it became free of patent encumbrances in September 2000.

For a full explanation of the algorithm, consult one of the standard references such as Applied Cryptography . A simple explanation is:

The great 17th century French mathematician Fermat proved that, for any prime p and number x, 0 x^p == x modulo p x^(p-1) == 1 modulo p, non-zero x From this it follows that if we have a pair of primes p, q and two numbers e, d such that:

    	ed == 1			modulo lcm( p-1, q-1)

where lcm() is least common multiple, then for all x, 0 x^(ed-1) == 1 modulo pq, non-zero x x^ed == x modulo pq So we construct such as set of numbers p, q, e, d and publish the product N=pq and e as the public key. Encryption is then:

    	c = x^e			modulo N

An attacker cannot deduce x from the cyphertext c, short of either factoring N or solving the discrete logarithm problem for this field. If p, q are large primes (hundreds or thousands of bits) no efficient solution to either problem is known.

The receiver, knowing the private key (N and d), can readily find x sixce:

    	c^d == (x^e)^d		modulo N
    	    == x^ed		modulo N
    	    == x		modulo N

This gives an effective public key technique, with only a couple of problems. It uses a good deal of computer time, since calculations with large integers are not cheap, and there is no proof it is necessarily secure since no-one has proven either factoring or discrete log cannot be done efficiently.
RSA Data Security
  A company founded by the inventors of the RSA public key algorithm.
S
SA
  Security Association, the channel negotiated by the higher levels of an IPSEC implementation and used by the lower. SAs are unidirectional; you need a pair of them for two-way communication.

An SA is defined by three things -- the destination, the protocol (AH orESP) and the SPI , security parameters index. It is used to index other things such as session keys and intialisation vectors.

For more detail, see our section on IPSEC and/or RFC 2401.

Secure DNS
  A version of the DNS or Domain Name Service enhanced with authentication services. This is being designed by the IETF DNS security working group. Check the Internet Software Consortium for information on implementation progress and for the latest version of BIND. Another site has more information .

IPSEC can use this plus Diffie-Hellman key exchange to bootstrap itself. This would allow opportunistic encryption. Any pair of machines which could authenticate each other via DNS could communicate securely, without either a pre-existing shared secret or a shared PKI.

Linux FreeS/WAN will support this in a future release.

Secret key cryptography
  See symmetric cryptography
Security Association
  see SA
Sequence number
  A number added to a packet or message which indicates its position in a sequence of packets or messages. This provides some security against replay attacks.

For automatic keying mode, the IPSEC RFCs require that the sender generate sequence numbers for each packet, but leave it optional whether the receiver does anything with them.

SHA
  Secure Hash Algorithm, a message digest algorithm developed by the NSA for use in the Digital Signature standard, FIPS number 186 from NIST. SHA is an improved variant of MD4 producing a 160-bit hash.

SHA is one of two message digest algorithms available in IPSEC. The other is MD5. Some people do not trust SHA because it was developed by the NSA. There is, as far as we know, no cryptographic evidence that SHA is untrustworthy, but this does not prevent that view from being strongly held.

Signals intelligence (SIGINT)
  Activities of government agencies from various nations aimed at protecting their own communications and reading those of others. Cryptography, cryptanalysis, wiretapping, interception and monitoring of various sorts of signals. The players include the American NSA, British GCHQ and Canadian CSE.
SKIP
  Simple Key management for Internet P rotocols, an alternative to IKE developed by Sun and being marketed by their Internet Commerce Group.
Snake oil
  Bogus cryptography. See the Snake Oil FAQ or this paper by Schneier.
SPI
  Security Parameter Index, an index used within IPSEC to keep connections distinct. A Security Association (SA) is defined by destination, protocol and SPI. Without the SPI, two connections to the same gateway using the same protocol could not be distinguished.

For more detail, see our IPSEC Overview and/or RFC 2401.

SSH
  Secure SHell, an encrypting replacement for the insecure Berkeley commands whose names begin with "r" for "remote": rsh, rlogin, etc.

For more information on SSH, including how to obtain it, see our cryptography links.

SSH Communications Security
  A company founded by the authors of SSH. Offices are in Finland and California. They have a toolkit for developers of IPSEC applications.
SSL
  Secure Sockets Layer , a set of encryption and authentication services for web browsers, developed by Netscape. Widely used in Internet commerce. Also known as TLS.
SSLeay
  A free implementation of SSL by Eric Young (eay) and others. Developed in Australia; not subject to US export controls.
Stream cipher
  A symmetric cipher which produces a stream of output which can be combined (often using XOR or bytewise addition) with the plaintext to produce ciphertext. Contrasts with block cipher.

IPSEC does not use stream ciphers. Their main application is link-level encryption, for example of voice, video or data streams on a wire or a radio signal.

subnet
  A group of IP addresses which are logically one network, typically (but not always) assigned to a group of physically connected machines. The range of addresses in a subnet is described using a subnet mask. See next entry.
subnet mask
  A method of indicating the addresses included in a subnet. Here are two equivalent examples:
  - 101.101.101.0/24
  - 101.101.101.0 with mask 255.255.255.0

The '24' is shorthand for a mask with the top 24 bits one and the rest zero. This is exactly the same as 255.255.255.0 which has three all-ones bytes and one all-zeros byte.

These indicate that, for this range of addresses, the top 24 bits are to be treated as naming a network (often referred to as "the 101.101.101.0/24 subnet") while most combinations of the low 8 bits can be used to designate machines on that network. Two addresses are reserved; 101.101.101.0 refers to the subnet rather than a specific machine while 101.101.101.255 is a broadcast address. 1 to 254 are available for machines.

It is common to find subnets arranged in a hierarchy. For example, a large company might have a /16 subnet and allocate /24 subnets within that to departments. An ISP might have a large subnet and allocate /26 subnets (64 addresses, 62 usable) to business customers and /29 subnets (8 addresses, 6 usable) to residential clients.

S/WAN
  Secure Wide Area Network, a project involving RSA Data Security and a number of other companies. The goal was to ensure that all their IPSEC implementations would interoperate so that their customers can communicate with each other securely.
Symmetric cryptography
  Symmetric cryptography, also referred to as conventional or secret key cryptography, relies on a shared secret key, identical for sender and receiver. Sender encrypts with that key, receiver decrypts with it. The idea is that an eavesdropper without the key be unable to read the messages. There are two main types of symmetric cipher, block ciphers and stream ciphers.

Symmetric cryptography contrasts with public key or asymmetric systems where the two players use different keys.

The great difficulty in symmetric cryptography is, of course, key management. Sender and receiver must have identical keys and those keys must be kept secret from everyone else. Not too much of a problem if only two people are involved and they can conveniently meet privately or employ a trusted courier. Quite a problem, though, in other circumstances.

It gets much worse if there are many people. An application might be written to use only one key for communication among 100 people, for example, but there would be serious problems. Do you actually trust all of them that much? Do they trust each other that much? Should they? What is at risk if that key is compromised? How are you going to distribute that key to everyone without risking its secrecy? What do you do when one of them leaves the company? Will you even know?

On the other hand, if you need unique keys for every possible connection between a group of 100, then each user must have 99 keys. You need either 99*100/2 = 4950 secure key exchanges between users or a central authority that securely distributes 100 key packets, each with a different set of 99 keys.

Either of these is possible, though tricky, for 100 users. Either becomes an administrative nightmare for larger numbers. Moreover, keys must be changed regularly, so the problem of key distribution comes up again and again. If you use the same key for many messages then an attacker has more text to work with in an attempt to crack that key. Moreover, one successful crack will give him or her the text of all those messages.

In short, the hardest part of conventional cryptography is key management. Today the standard solution is to build a hybrid system using public key techniques to manage keys.

T
TIS
  Trusted Information Systems, a firewall vendor now part of NAI. Their Gauntlet product offers IPSEC VPN services. TIS implemented the first version of Secure DNS on a DARPA contract.
TLS
  Transport Layer Security, a newer name for SSL.
Traffic analysis
  Deducing useful intelligence from patterns of message traffic, without breaking codes or reading the messages. In one case during World War II, the British knew an attack was coming because all German radio traffic stopped. The "radio silence" order, intended to preserve security, actually gave the game away.

In an industrial espionage situation, one might deduce something interesting just by knowing that company A and company B were talking, especially if one were able to tell which departments were involved, or if one already knew that A was looking for acquisitions and B was seeking funds for expansion.

IPSEC itself does not defend against this, but carefully thought out systems using IPSEC can provide at least partial protection. In particular, one might want to encrypt more traffic than was strictly necessary, route things in odd ways, or even encrypt dummy packets, to confuse the analyst.

Transport mode
  An IPSEC application in which the IPSEC gateway is the destination of the protected packets, a machine acts as its own gateway. Contrast with tunnel mode.
Triple DES
  see 3DES
Tunnel mode
  An IPSEC application in which an IPSEC gateway provides protection for packets to and from other systems. Contrast with transport mode.
Two-key Triple DES
  A variant of triple DES or 3DES in which only two keys are used. As in the three-key version, the order of operations is EDE or encrypt-decrypt-encrypt, but in the two-key variant the first and third keys are the same.

3DES with three keys has 3*56 = 168 bits of key but has only 112-bit strength against a meet-in-the-middle attack, so it is possible that the two key version is just as strong. Last I looked, this was an open question in the research literature.

RFC 2451 defines triple DES for IPSEC as the three-key variant. The two-key variant should not be used and is not implemented directly in Linux FreeS/WAN. It cannot be used in automatically keyed mode without major fiddles in the source code. For manually keyed connections, you could make Linux FreeS/WAN talk to a two-key implementation by setting two keys the same in /etc/ipsec.conf.

U
V
Virtual Interface
  A Linux feature which allows one physical network interface to have two or more IP addresses. See the Linux Network Administrator's Guide in book form or on the web for details.
Virtual Private Network
  see VPN
VPN
  Virtual Private Network, a network which can safely be used as if it were private, even though some of its communication uses insecure connections. All traffic on those connections is encrypted.

IPSEC is not the only technique available for building VPNs, but it is the only method defined by RFCs and supported by many vendors. VPNs are by no means the only thing you can do with IPSEC, but they may be the most important application for many users.

VPNC
  Virtual Private Network Consortium , an association of vendors of VPN products.
W
Wassenaar Arrangement
  An international agreement restricting export of munitions and other tools of war. Unfortunately, cryptographic software is also restricted under the current version of the agreement. Discussion.
Web of Trust
  PGP's method of certifying keys. Any user can sign a key; you decide which signatures or combinations of signatures to accept as certification. This contrasts with the hierarchy of CAs (Certification Authorities) used in many PKIs (Public Key Infrastructures).

See Global Trust Register for an interesting addition to the web of trust.

X
X.509
  A standard from the ITU (International Telecommunication Union), for hierarchical directories with authentication services, used in many PKI implementations.

Use of X.509 services, via the LDAP protocol, for certification of keys is allowed but not required by the IPSEC RFCs. It is not yet implemented in Linux FreeS/WAN.

Xedia
  A vendor of router and Internet access products. Their QVPN products interoperate with Linux FreeS/WAN; see our compatibility document.
Y
Z

# Bibliography for the Linux FreeS/WAN project

For extensive bibliographic links, see the Collection of Computer Science Bibliographies

See our web links for material available online.

Carlisle Adams and Steve Lloyd Understanding Public Key Infrastructure
Macmillan 1999 ISBN 1-57870-166-x
An overview, mainly concentrating on policy and strategic issues rather than the technical details. Both authors work for PKI vendor Entrust.

Albitz, Liu & Loukides DNS & BIND 3rd edition
O'Reilly 1998 ISBN 1-56592-512-2
The standard reference on the Domain Name Service and Berkeley Internet Name Daemon.

Bamford The Puzzle Palace, A report on NSA, Americas's most Secret Agency
Houghton Mifflin 1982 ISBN 0-395-31286-8

David Bander, Linux Security Toolkit
IDG Books, 2000, ISBN: 0764546902
This book has a short section on FreeS/WAN and includes Caldera Linux on CD.

Chapman, Zwicky & Russell Building Internet Firewalls
O'Reilly 1995 ISBN 1-56592-124-0

Cheswick and Bellovin Firewalls and Internet Security: Repelling the Wily Hacker
Addison-Wesley 1994 ISBN 0201633574
A fine book on firewalls in particular and security in general from two of AT&T's system adminstrators.

Bellovin has also done a number of papers on IPSEC and co-authored a paper on a large FreeS/WAN application.

Comer Internetworking with TCP/IP
Prentice Hall

- Vol. I: Principles, Protocols, & Architecture, 3rd Ed. 1995 ISBN:0-13-216987-8
- Vol. II: Design, Implementation, & Intervals, 2nd Ed. 1994 ISBN:0-13-125527-4
- Vol. III: Client/Server Programming & Applications
  - AT&T TLI Version 1994 ISBN:0-13-474230-3
  - BSD Socket Version 1996 ISBN:0-13-260969-X
  - Windows Sockets Version 1997 ISBN:0-13-848714-6

If you need to deal with the details of the network protocols, read either this series or the Stevens and Wright series before you start reading the RFCs.

Diffie and Landau Privacy on the Line: The Politics of Wiretapping and Encryption
MIT press 1998 ISBN 0-262-04167-7 (hardcover) or 0-262-54100-9
An interview with the authors is available on the web.

Doraswamy and Harkins IP Sec: The New Security Standard for the Internet, Intranets and Virtual Private Networks
Prentice Hall 1999 ISBN: 0130118982

Electronic Frontier Foundation Cracking DES: Secrets of Encryption Research, Wiretap Politics and Chip Design
O'Reilly 1998 ISBN 1-56592-520-3
To conclusively demonstrate that DES is inadequate for continued use, the EFF built a machine for just over $200,000 that breaks DES encryption in under five days on average, under nine in the worst case.

The book provides details of their design and, perhaps even more important, discusses why they felt the project was necessary. Recommended for anyone interested in any of the three topics mentioned in the subtitle.

See also the EFF page on this project and our discussion of DES insecurity.

Martin Freiss Protecting Networks with SATAN
O'Reilly 1998 ISBN 1-56592-425-8
translated from a 1996 work in German
SATAN is a Security Administrator's Tool for Analysing Networks. This book is a tutorial in its use.

Gaidosch and Kunzinger A Guide to Virtual Private Networks
Prentice Hall 1999 ISBN: 0130839647

Simson Garfinkel Database Nation: the death of privacy in the 21st century
O'Reilly 2000 ISBN 1-56592-653-6
A thoughtful and rather scary book.

Simson Garfinkel PGP: Pretty Good Privacy
O'Reilly 1995 ISBN 1-56592-098-8
An excellent introduction and user manual for the PGP email-encryption package. PGP is a good package with a complex and poorly-designed user interface. This book or one like it is a must for anyone who has to use it at length.

The book covers using PGP in Unix, PC and Macintosh environments, plus considerable background material on both the technical and political issues around cryptography. The only shortcoming is that it does not cover recent developments such as PGP 5 and Open PGP.

Garfinkel and Spafford Practical Unix Security
O'Reilly 1996 ISBN 1-56592-148-8
A standard reference.
Spafford's web page has an excellent collection of crypto and security links.

David Kahn The Codebreakers: the Comprehensive History of Secret Communications from Ancient Times to the Internet
second edition Scribner 1996 ISBN 0684831309
A history of codes and code-breaking from ancient Egypt to the 20th century. Well-written and exhaustively researched. Highly recommended, even though it does not have much on computer cryptography.

David Kahn Seizing the Enigma, The Race to Break the German U-Boat codes, 1939-1943
Houghton Mifflin 1991 ISBN 0-395-42739-8

Olaf Kirch Linux Network Administrator's Guide
O'Reilly 1995 ISBN 1-56592-087-2
Now becoming somewhat dated in places, but still a good introductory book and general reference.

Pete Lashin Big Book of IPSEC RFCs
Morgan Kaufmann 2000 ISBN: 0-12-455839-9

Steven Levy Crypto: How the Code Rebels Beat the Government -- Saving Privacy in the Digital Age
Penguin 2001, ISBN 0-670--85950-8
Highly recommended. A fine history of recent (about 1970-2000) developments in the field, and the related political controversies. FreeS/WAN project founder and leader John Gilmore appears several times.

The book does not cover IPSEC or FreeS/WAN, but this project is very much another battle in the same war. See our discussion of the politics.

Matyas, Anderson et al. The Global Trust Register
Northgate Consultants Ltd 1998 ISBN: 0953239705
hard cover edition due April 1999 MIT Press ISBN 0262511053
From their web page:

> This book is a register of the fingerprints of the world's most important public keys; it implements a top-level certification authority (CA) using paper and ink rather than in an electronic system.

Menezies, van Oorschot and Vanstone Handbook of Applied Cryptography
CRC Press 1997
ISBN 0-8493-8523-7
An excellent reference. Read Schneier before tackling this.

Gerhard Mourani Get Acquainted with Linux Security and Optimization System
Available online as a PDF file. It did not yet cover IPSEC when we last looked.

Michael Padlipsky Elements of Networking Style
Prentice-Hall 1985 ISBN 0-13-268111-0 or 0-13-268129-3
Probably the funniest technical book ever written , this is a vicious but well-reasoned attack on the OSI "seven layer model" and all that went with it. Several chapters of it are also available as RFCs 871 to 875.

John S. Quarterman The Matrix: Computer Networks and Conferencing Systems Worldwide
Digital Press 1990 ISBN 155558-033-5
Prentice-Hall ISBN 0-13-565607-9
The best general treatment of computer-mediated communication we have seen. It naturally has much to say about the Internet, but also covers UUCP, Fidonet and so on.

David Ranch Securing Linux Step by Step
SANS Institute, 1999
SANS is a respected organisation, this guide is part of a well-known series, and Ranch has previously written the useful Trinity OS guide to securing Linux, so my guess would be this is a pretty good book. I haven't read it yet, so I'm not certain. It can be ordered online from SANS.

Bruce Schneier Applied Cryptography, Second Edition
John Wiley & Sons, 1996
ISBN 0-471-12845-7 hardcover
ISBN 0-471-11709-9 paperback
A standard reference on computer cryptography. For more recent essays, see the author's company's web site.

Bruce Schneier Secrets and Lies
Wiley 2000, ISBN 0-471-25311-1
An interesting discussion of security and privacy issues, written with more of an "executive overview" approach rather than a narrow focus on the technical issues. Highly recommended.

Scott, Wolfe and Irwin Virtual Private Networks
2nd edition, O'Reilly 1999 ISBN: 1-56592-529-7
This is the only O'Reilly book, out of a dozen I own, that I'm disappointed with. It deals mainly with building VPNs with various proprietary tools -- PPTP, SSH, Cisco PIX, ... -- and touches only lightly on IPSEC-based approaches.

That said, it appears to deal competently with what it does cover and it has readable explanations of many basic VPN and security concepts. It may be exactly what some readers require, even if I find the emphasis unfortunate.

Kurt Seifried Linux Administrator's Security Guide
Available online from Security Portal. It has fairly extensive coverage of IPSEC.

Richard E Smith Internet Cryptography
ISBN 0-201-92480-3, Addison Wesley, 1997
See the book's home page

Neal Stephenson Cryptonomicon
Hardcover ISBN -380-97346-4, Avon, 1999.

A novel in which cryptography and the net figure prominently. Highly recommended: I liked it enough I immediately went out and bought all the author's other books.

There is also a paperback edition. Sequels are expected.

Stevens and Wright TCP/IP Illustrated
Addison-Wesley

- Vol. I: The Protocols 1994 ISBN:0-201-63346-9
- Vol. II: The Implementation 1995 ISBN:0-201-63354-X
- Vol. III: TCP for Transactions, HTTP, NNTP, and the UNIX Domain Protocols 1996 ISBN: 0-201-63495-3

If you need to deal with the details of the network protocols, read either this series or the Comer series before you start reading the RFCs.

Rubini Linux Device Drivers
O'Reilly & Associates, Inc. 1998 ISBN 1-56592-292-1

Robert Zeigler Linux Firewalls
Newriders Publishing, 2000 ISBN 0-7537-0900-9

# IPSEC RFCs and related documents

## The RFCs.tar.gz Distribution File

The Linux FreeS/WAN distribution is available from:

our primary distribution site and various mirror sites. To give people more control over their downloads, the RFCs that define IP security are bundled separately in the file RFCs.tar.gz.

The file you are reading is included in the main distribution and is available on the web site. It describes the RFCs included in the RFCs.tar.gz bundle and gives some pointers to other ways to get them.

## Other sources for RFCs & Internet drafts

### RFCs

RFCs are downloadble at many places around the net such as:

- http://www.rfc-editor.org
- NSF.net
- Sunsite in the UK

browsable in HTML form at others such as:

- landfield.com
- Connected Internet Encyclopedia

and some of them are available in translation:

- French

There is also a published Big Book of IPSEC RFCs .

### Internet Drafts

Internet Drafts, working documents which sometimes evolve into RFCs, are also available.

- Overall reference page
- drafts from the IPSEC working group
- drafts from the IPSRA (IPSEC Remote Access) working group

Note: some of these may be obsolete, replaced by later drafts or by RFCs.

### FIPS standards

Some things used by IPSEC, such as DES and SHA, are defined by US government standards called FIPS. The issuing organisation, NIST, have a FIPS home page.

### Document CDs

At least one vendor sells CD-ROMs of RFCs and Internet Drafts:

- Walnut Creek CDROM

Note: The 2401-2412 group of IPSEC RFCs were issued in late November 1998, and the 2535-2539 group on Secure DNS in March 1999, so an older CD may not be particularly useful if these areas are your main concern.

## What's in the RFCs.tar.gz bundle?

All filenames are of the form rfc*.txt, with the * replaced with the RFC number.

    RFC#        Title

### Overview RFCs

    2401        Security Architecture for the Internet Protocol
    2411        IP Security Document Roadmap

### Basic protocols

    2402        IP Authentication Header
    2406        IP Encapsulating Security Payload (ESP)

### Key management

    2367        PF_KEY Key Management API, Version 2
    2407        The Internet IP Security Domain of Interpretation for ISAKMP
    2408        Internet Security Association and Key Management Protocol (ISAKMP)
    2409        The Internet Key Exchange (IKE)
    2412        The OAKLEY Key Determination Protocol
    2528        Internet X.509 Public Key Infrastructure

### Details of various things used

    2085        HMAC-MD5 IP Authentication with Replay Prevention
    2104        HMAC: Keyed-Hashing for Message Authentication
    2202        Test Cases for HMAC-MD5 and HMAC-SHA-1
    2207        RSVP Extensions for IPSEC Data Flows
    2403        The Use of HMAC-MD5-96 within ESP and AH
    2404        The Use of HMAC-SHA-1-96 within ESP and AH
    2405        The ESP DES-CBC Cipher Algorithm With Explicit IV
    2410        The NULL Encryption Algorithm and Its Use With IPsec
    2451        The ESP CBC-Mode Cipher Algorithms
    2521        ICMP Security Failures Messages

### Older RFCs which may be referenced

    1321        The MD5 Message-Digest Algorithm
    1828        IP Authentication using Keyed MD5
    1829        The ESP DES-CBC Transform
    1851        The ESP Triple DES Transform
    1852        IP Authentication using Keyed SHA

### RFCs for secure DNS service, which IPSEC may use

    2137        Secure Domain Name System Dynamic Update
    2230        Key Exchange Delegation Record for the DNS
    2535        Domain Name System Security Extensions
    2536        DSA KEYs and SIGs in the Domain Name System (DNS)
    2537        RSA/MD5 KEYs and SIGs in the Domain Name System (DNS)
    2538        Storing Certificates in the Domain Name System (DNS)
    2539        Storage of Diffie-Hellman Keys in the Domain Name System (DNS)

### RFCs labelled "experimental"

    2521        ICMP Security Failures Messages
    2522        Photuris: Session-Key Management Protocol
    2523        Photuris: Extended Schemes and Attributes

### Related RFCs

    1750        Randomness Recommendations for Security
    1918        Address Allocation for Private Internets
    1984        IAB and IESG Statement on Cryptographic Technology and the Internet
    2144        The CAST-128 Encryption Algorithm

# FreeS/WAN FAQ

This is a collection of questions and answers, mostly taken from the FreeS/WAN mailing list. See the project web site for more information. All the FreeS/WAN documentation is online there.

Contributions to the FAQ are welcome. Please send them to the project mailing list.

## Questions

- What is FreeS/WAN?
- How do I report a problem or seek help?
- Generic questions

- This is too complicated. Isn't there an easier way?
- Can I get commercial support for this product?
- Can I modify FreeS/WAN to ...?
- Can I contribute to the project?
- Is there detailed design documentation?
- Can FreeS/WAN talk to ...?
- Can different FreeS/WAN versions talk to each other?
- Does FreeS/WAN run on my version of Linux?
- Does FreeS/WAN run on the latest kernel version?
- Is a ... fast enough to handle FreeS/WAN with ... connections?

- Compilation problems

- gmp.h: No such file or directory
- ... virtual memory exhausted

- Life's little mysteries

- I cannot ping ....
- It takes forever to ...
- I send packets to the tunnel with route(8) but they vanish
- When a tunnel goes down, packets vanish
- The firewall ate my packets!
- Dropped connections
- TCPdump on the gateway shows strange things
- Traceroute does not show anything between the gateways

- Testing in stages

- Manually keyed connections don't work
- One manual connection works, but second one fails
- Manual connections work, but automatic keying doesn't
- IPSEC works, but connections using compression fail
- Small packets work, but large transfers fail
- Subnet-to-subnet works, but tests from the gateways don't

- Interpreting error messages

- SIOCADDRT:Network is unreachable
- ipsec_setup: Fatal error, kernel appears to lack KLIPS
- ipsec_setup: ... failure to fetch key for ... from DNS
- ipsec_setup: ... interfaces ... and ... share address ...
- ipsec_setup: Cannot adjust kernel flags
- Connection names in Pluto error messages
- Pluto: ... can't orient connection
- Pluto: ... no connection is known
- Pluto: ... no suitable connection ...
- Pluto: ... no connection has been authorized
- Pluto: ... OAKLEY_DES_CBC is not supported.
- Pluto: ... no acceptable transform
- ECONNREFUSED error message
- klips_debug: ... no eroute!
- ... trouble writing to /dev/ipsec ... SA already in use
- ... ignoring ... payload

- Can I ...

- Can I reload connection info without restarting?
- Can I use several masqueraded subnets?
- Can I use subnets masqueraded to the same addresses?
- Can I assign a road warrior an address on my net?
- Can I use Quality of Service routing with FreeS/WAN?
- Can I recognise dead tunnels and shut them down?
- Can I build IPSEC tunnels over a demand-dialed link?
- Can I build GRE tunnels over IPSEC?
- Does FreeS/WAN support X.509 or other PKI certificates?
- Does FreeS/WAN support Radius or other user authentication?
- Does FreeS/WAN support single DES encryption?

- Why don't you restrict the mailing lists to reduce spam?

## What is FreeS/WAN?

FreeS/WAN is a Linux implementation of the IPSEC protocols, providing security services at the IP (Internet Protocol) level of the network.

For more detail, see our introduction document or the FreeS/WAN project web site.

## How do I report a problem or seek help?

See our problem reporting document. Basically, what it says is give us the output from ipsec barf from both gateways. Without full information, we cannot diagnose a problem. However, ipsec barf produces a lot of output. If at all possible, please make barfs accessible via the web or FTP rather than sending enormous mail messages.

Use the mailing list for problem reports, rather than mailing developers directly. This gives you access to more expertise, including users who may have encountered and solved the same problems. In particular, for problems involving interoperation with another IPSEC implementation, the users often know more than the developers.

Using the list may also be important in relation to various cryptography export laws. A US citizen who provides technical assistance to foreign cryptographic work might be charged under the arms export regulations. Such a charge would be easier to defend if the discussion took place on a public mailing list than if it were done in private mail.

## Generic questions

### This is too complicated. Isn't there an easier way?

There are a number of Linux distributions or firewall products which include FreeS/WAN. See this list. Using one of these, chosen to match your requirements and budget, may save you considerable time and effort. (If you don't know your requirements, start by reading Schneier's Secrets and Lies. That gives the best overview of security issues I have seen.)

If you want the help of a contractor, or to hire staff with FreeS/WAN expertise, you could:

- check availability in your area through your local Linux User Group (LUG Index)
- try asking on our mailing list

For companies offerring support, see the next question.

### Can I get commercial support for this product?

Many of the distributions or firewall products which include FreeS/WAN (see this list) come with commercial support or have it available as an option.

Various companies specialize in commercial support of open source software. Our project leader was a founder of the first such company, Cygnus Support. It has since been bought by Redhat. Another such firm is Linuxcare.

### Can I modify FreeS/WAN to ...?

You are free to modify FreeS/WAN in any way. See the discussion of licensing in our introduction document.

### Can I contribute to the project?

In general, we welcome contributions from the community. Various contributed patches, either to fix bugs or to add features, have been incorporated into our distribution. Other patches, not yet included in the distribution, are listed in our web links section.

Users have also contributed heavily to documentation, both by creating their own HowTos and by posting things on the mailing lists which I have quoted in these HTML docs.

There are, however, some caveats.

FreeS/WAN is being implemented in Canada, by Canadians, largely to ensure that is it is entirely free of export restrictions. See this discussion. We cannot accept code contributions from US residents or citizens, not even one-line bugs fixes. The reasons for this were recently discussed extensively on the mailing list, in a thread starting here.

Not all contributions are of interest to us. The project has a set of fairly ambitious and quite specific goals, described in our introduction. Contributions that lead toward these goals are likely to be welcomed enthusiastically. Other contributions may be seen as lower priority, or even as a distraction.

### Is there detailed design documentation?

There are:

- RFCs specifying the protocols we implement
- man pages for our utilities, library functions and file formats
- comments in the source code
- HTML documentation written primarily for users
- archived discussions from the mailing lists
- other papers mentioned in our introduction

The only formal design documents are a few papers in the last category above. All the other categories, however, have things to say about design as well.

### Can FreeS/WAN talk to ...?

The IPSEC protocols are designed to support interoperation. In theory, any two IPSEC implementations should be able to talk to each other.

In practice, it is considerably more complex. We have a whole interop document devoted to it.

### Can different FreeS/WAN versions talk to each other?

Linux FreeS/WAN can interoperate with many IPSEC implementations, including earlier versions of Linux FreeS/WAN itself.

In general, new versions will use existing configuration files, at least until the next major version number change. For example, 1.8 can use files created for 1.7, 1.6, even back to 1.0, but not from 0.92. This behaviour will continue until we release 2.0.

As of 1.8, however, conf file checking has become stricter, so that an error that may have slipped past the checks in an earlier version may be caught in a later one. From 1.8's doc/CHANGES:

          The internal configuration-file reader is progressively getting
          fussier about what it will accept, which may cause problems for
          illegal ipsec.conf files whose sins previously passed unnoticed.
          IN PARTICULAR, the "auto" parameter's values are now checked for
          legality everywhere.

### Does FreeS/WAN run on my version of Linux?

We build and test on Redhat distributions, but FreeS/WAN runs just fine on several other distributions, sometimes with minor fiddles to adapt to the local environment. Details are in our compatibility document. Also, some distributions or products come with FreeS/WAN included.

FreeS/WAN is intended to run on all CPUs Linux supports . As of June 2000, we know of it being used in production on x86, ARM, Alpha and MIPS. It has also had successful tests on PPC and SPARC, though we don't know of actual use there. Details are in our compatibility document.

FreeS/WAN has been tested on multiprocessor Intel Linux and worked there. Note, however, that we do not test this often and have never tested on multiprocessor machines of other architectures.

### Does FreeS/WAN run on the latest kernel version?

Sometimes yes, but quite often, no.

Released versions of FreeS/WAN run on whatever production kernels were current at the time of our release (or shortly before; we might release for kernel n just as Linus releases n+1). For example, FreeS/WAN 1.91 runs on kernel 2.2.19 or 2.4.5. Often they will run on slightly earlier or later kernels as well, but we test on the current production kernels, so those are strongly recommended.

The kernel is under active development and it is not uncommon for changes to appear that cause problems for FreeS/WAN. For example, 2.4.6 or 2.4.7 may have changes that break FreeS/WAN 1.91. Or not; you can't tell in advance. When such changes appear, we put a fix in the FreeS/WAN snapshots, and distribute it with our next release.

However, this is not a high priority for us, and it may take anything from a few days to several weeks for such a problem to find its way to the top of our kernel programmer's To-Do list. In the meanwhile, you have two choices:

- either stick with a slightly older kernel, even if it is not the latest and greatest. This is recommended for production systems; new versions may have new bugs.
- or fix the problem yourself and send us a patch, via the Users mailing list.

We don't even try to keep up with kernel changes outside the main 2.2 and 2.4 branches, such as the 2.4.x-ac patched versions from Alan Cox or (when they appear) the 2.5 series of development kernels. We'd rather work on developing the FreeS/WAN code than on chasing these moving targets. We are, however, happy to get patches for problems discovered there.

See also the Choosing a kernel section of our installation document.

### Is a ... fast enough to handle FreeS/WAN with ... connections?

Certainly FreeS/WAN can run happily on limited machines. Very roughly:

- a 486 machines can handle a T1, ADSL or cable link (but the machine may be breathing hard)
- a current (mid-2001) technology PC can easily handle at least a 10 Mbit/second link

Beyond that, the picture is not clear. Much depends on details of your network, your traffic, and other loads on both machine and net.

See our FreeS/WAN performance document and our discussion of many tunnels for one gateway for more detail.

## Compilation problems

### gmp.h: No such file or directory

Pluto needs the GMP (GNU Multi- Precision) library for the large integer calculations it uses in public key cryptography. This error message indicates a failure to find the library. You must install it before Pluto will compile.

The GMP library is included in most Linux distributions. Typically, there are two RPMs, libgmp and libgmp-devel, You need to install both, either from your distribution CDs or from your vendor's web site.

On Debian, a mailing list message reports that the command to give is apt-get install gmp2.

For more information and the latest version, see the GMP home page.

### ... virtual memory exhausted

We have had several reports of this message appearing, all on SPARC Linux. Here is a mailing message on a solution:

    > ipsec_sha1.c: In function `SHA1Transform':
    > ipsec_sha1.c:95: virtual memory exhausted

    I'm seeing exactly the same problem on an Ultra with 256MB ram and 500
    MB swap.  Except I am compiling version 1.5 and its Red Hat 6.2.

    I can get around this by using -O instead of -O2 for the optimization
    level.  So it is probably a bug in the optimizer on the sparc complier.
    I'll try and chase this down on the sparc lists.

## Life's little mysteries

FreeS/WAN is a fairly complex product. (Neither the networks it runs on nor the protocols it uses are simple, so it could hardly be otherwise.) It therefore sometimes exhibits behaviour which can be somewhat confusing, or has problems which are not easy to diagnose. This section tries to explain those problems.

Setup and configuration of FreeS/WAN are covered in other documentation sections:

- Installation
- Configuration
- Troubleshooting

However, we also list some of the commonest problems here.

### I cannot ping ....

This question is dealt with in the configuration section under the heading multiple tunnels.

The standard subnet-to-subnet tunnel protects traffic only between the subnets. To test it, you must use pings that go from one subnet to the other.

For example, suppose you have:

          subnet a.b.c.0/24
                 |
          eth1 = a.b.c.1
             gate1
          eth0 = 1.2.3.4
                 |

           ~ internet ~

                 |
          eth0 = 4.3.2.1
             gate2
          eth1 = x.y.z.1
                  |
           subnet x.y.z.0/24

and the connection description:

    conn abc-xyz
         left=1.2.3.4
         leftsubnet=a.b.c.0/24
         right=4.3.2.1
         rightsubnet=x.y.z.0/24

You can test this connection description only by sending a ping that will actually go through the tunnel. Assuming you have machines at addresses a.b.c.2 and x.y.z.2, pings you might consider trying are:

ping from x.y.z.2 to a.b.c.2 or vice versa
  Succeeds if tunnel is working. This is the only valid test of the tunnel.
ping from gate2 to a.b.c.2 or vice versa
  Does not use tunnel. gate2 is not on protected subnet.
ping from gate1 to x.y.z.2 or vice versa
  Does not use tunnel. gate1 is not on protected subnet.
ping from gate1 to gate2 or vice versa
  Does not use tunnel. Neither gate is on a protected subnet.

Only the first of these is a useful test of this tunnel. The others do not use the tunnel. Depending on other details of your setup and routing, they:

- either fail, telling you nothing about the tunnel
- or succeed, telling you nothing about the tunnel since these packets use some other route

If required, you can of course build additional tunnels so that all the machines involved can talk to all the others. See multiple tunnels in the configuration document for details.

### It takes forever to ...

Users fairly often report various problems involving long delays, sometimes on tunnel setup and sometimes on operations done through the tunnel, occasionally on simple things like ping or more often on more complex operations like doing NFS or Samba through the tunnel.

Almost always, these turn out to involve failure of a DNS lookup. The timeouts waiting for DNS are typically set long so that you won't time out when a query involves multiple lookups or long paths. Genuine failures therefore produce long delays before they are detected.

A mailing list message from project technical lead Henry Spencer:

    > ... when i run /etc/rc.d/init.d/ipsec start, i get:
    > ipsec_setup: Starting FreeS/WAN IPSEC 1.5...
    > and it just sits there, doesn't give back my bash prompt.

    Almost certainly, the problem is that you're using DNS names in your
    ipsec.conf, but DNS lookups are not working for some reason.  You will
    get your prompt back... eventually.  But the DNS timeouts are long.
    Doing something about this is on our list, but it is not easy.

In the meanwhile, we recommend that connection descriptions in ipsec.conf(5) use numeric IP addresses rather than names which will require a DNS lookup.

Names that do not require a lookup are fine. For example:

- a road warrior might use the identity rightid=@lancelot.example.org
- the gateway might use leftid=@camelot.example.org

These are fine. The @ sign prevents any DNS lookup. However, do not attempt to give the gateway address as left=camelot.example.org . That requires a lookup.

A post from one user after solving a problem with long delays:

    Subject: Final Answer to Delay!!!
       Date: Mon, 19 Feb 2001
       From: "Felippe Solutions" <felippe@solutionstecnologia.com.br>

    Sorry people, but seems like the Delay problem had nothing to do with
    freeswan.

    The problem was DNS as some people sad from the beginning, but not the way
    they thought it was happening. Samba, ssh, telnet and other apps try to
    reverse lookup addresses when you use IP numbers (Stupid that ahh).

    I could ping very fast because I always ping with "-n" option, but I don't
    know the option on the other apps to stop reverse addressing so I don't use
    it.

This post is fairly typical. These problems are often tricky and frustrating to diagnose, and most turn out to be DNS-related.

One suggestion for diagnosis: test with both names and addresses if possible. For example, try all of:

- ping address
- ping -n address
- ping name

If these behave differently, the problem must be DNS-related since the three commands do exactly the same thing except for DNS lookups.

### I send packets to the tunnel with route(8) but they vanish

IPSEC connections are designed to carry only packets travelling between pre-defined connection endpoints. As project technical lead Henry Spencer put it:

> IPsec tunnels are not just virtual wires; they are virtual wires with built-in access controls. Negotiation of an IPsec tunnel includes negotiation of access rights for it, which don't include packets to/from other IP addresses. (The protocols themselves are quite inflexible about this, so there are limits to what we can do about it.)

For fairly obvious security reasons, and to comply with the IPSEC RFCs, KLIPS drops any packets it receives that are not allowed on the tunnels currently defined. So if you send it packets with route(8) , and suitable tunnels are not defined, the packets vanish. Whether this is reported in the logs depends on the setting of klipsdebug in your ipsec.conf(5) file.

To rescue vanishing packets, you must ensure that suitable tunnels for them exist, by editing the connection descriptions in ipsec.conf(5). For example, supposing you have a simple setup:

             leftsubnet -- leftgateway === internet === roadwarrior

If you want to give the roadwarrior access to some resource that is located behind the left gateway but is not in the currently defined left subnet, then the usual procedure is to define an additional tunnel for those packets by creating a new connection description.

In some cases, it may be easier to alter an existing connection description, enlarging the definition of leftsubnet. For example, instead of two connection descriptions with 192.168.8.0/24 and 192.168.9.0/24 as their leftsubnet parameters, you can use a single description with 192.168.8.0/23.

If you have multiple endpoints on each side, you need to ensure that there is a route for each pair of endpoints. See our configuration document for an example.

### When a tunnel goes down, packets vanish

This is a special case of the vanishing packet problem described in the previous question. Whenever KLIPS sees packets for which it does not have a tunnel, it drops them.

When a tunnel goes away, either because negotiations with the other gateway failed or because you gave an ipsec auto --down command, the route to its other end is left pointing into KLIPS, and KLIPS will drop packets it has no tunnel for.

This is a documented design decision, not a bug. FreeS/WAN must not automatically adjust things to send packets via another route. The other route might be insecure.

Of course, re-routing may be necessary in many cases. In those cases, you have to do it manually or via scripts. We provide the ipsec auto --unroute command for these cases.

From ipsec_auto(8):

> Normally, pluto establishes a route to the destination specified for a connection as part of the --up operation. However, the route and only the route can be established with the --route operation. Until and unless an actual connection is established, this discards any packets sent there, which may be preferable to having them sent elsewhere based on a more general route (e.g., a default route).

> Normally, pluto's route to a destination remains in place when a --down operation is used to take the connection down (or if connection setup, or later automatic rekeying, fails). This permits establishing a new connection (perhaps using a different specification; the route is altered as necessary) without having a ``window'' in which packets might go elsewhere based on a more general route. Such a route can be removed using the --unroute operation (and is implicitly removed by --delete).

See also this mailing list message.

### The firewall ate my packets!

If firewalls filter out:

- either the UDP port 500 packets used in IKE negotiations
- or the ESP and AH (protocols 50 and 51) packets used to implement the IPSEC tunnel

then IPSEC cannot work. The first thing to check if packets seem to be vanishing is the firewall rules on the two gateway machines and any other machines along the path that you have access to.

For details, see our document on firewalls .

### Dropped connections

Networks being what they are, IPSEC connections can be broken for any number of reasons, ranging from hardware failures to various software problems such as the path MTU problems discussed elsewhere in the FAQ. Fortunately, various diagnostic tools exist that help you sort out many of the possible problems.

There is one situation, however, where FreeS/WAN (using default settings) may destroy a connection for no readily apparent reason. This occurs when things are misconfigured so that two tunnels from the same gateway expect the same subnet on the far end.

In this situation, the first tunnel comes up fine and works until the second is established. At that point, because of the way we track connections internally, the first tunnel ceases to exist as far as this gateway is concerned. Of course the far end does not know that, and a storm of error messages appears on both systems as it tries to use the tunnel.

If the far end gives up, goes back to square one and negotiates a new tunnel, then that wipes out the second tunnel and ...

The solution is simple. Do not build multiple conn descriptions with the same remote subnet.

This is actually intended to be a feature, rather than a bug. Consider the situation where a single remote system goes down, then comes back up and reconnects to the gateway. It is useful to have the gateway tear down the old tunnel and recover resources when the reconnection is made. It recognises that situation by checking the remote subnet for each tunnel it builds and discarding duplicates. This works fine as long as you don't configure multiple tunnels with the same remote subnet.

If this behaviour is inconvenient for you, you can disable it by setting uniqueids=no in ipsec.conf(5).

### TCPdump on the gateway shows strange things

Attempting to look at IPSEC packets by running monitoring tools on the IPSEC gateway machine can produce silly results. That machine is mangling the packets for IPSEC, and possibly for firewall or NAT purposes as well. If the internals of the machine's IP stack are not what the monitoring tool expects, then the tool can misinterpret them and produce nonsense output.

At one point, this problem was quite severe. On more recent systems, the problem has been solved. The version of tcpdump shipped with Redhat 6.2, for example, understands IPSEC well enough to be usable on a gateway. If in doubt about your version of tcpdump, you can get the latest version from tcpdump.org.

Even if you have a version of tcpdump that works on gateways however, the most certain way to examine IPSEC packets is to look at them on the wire. For security, you need to be certain, so we recommend doing that. To do so, you need a separate sniffer machine located between the two gateways. This machine can be routing IPSEC packets, but it must not be an IPSEC gateway.

A common test setup is to put a machine with dual Ethernet cards in between two gateways under test. The central machine both routes packets and provides a place to safely run tcpdump or other sniffing tools. What you end up with looks like:

#### Testing network

          subnet a.b.c.0/24
                 |
          eth1 = a.b.c.1
             gate1
          eth0 = 192.168.p.1
                 |
                 |
          eth0 = 192.168.p.2
             route/monitor box
          eth1 = 192.168.q.2
                 |
                 |
          eth0 = 192.168.q.1
             gate2
          eth1 = x.y.z.1
                  |
           subnet x.y.z.0/24

With p and q any convenient values that do not interfere with other routes you may have. The ipsec.conf(5) file then has, among other things:

    conn abc=xyz
          left=192.168.p.1
          leftnexthop=192.168.p.2
          right=192.168.q.1
          rightnexthop=192.168.q.2

Once that works, you can remove the "route/monitor box", and connect the two gateways to the Internet. The only parameters in ipsec.conf(5) that need to change are the four shown above. You replace them with values appropriate for your Internet connection, and change the eth0 IP addresses and the default routes on both gateways.

Note that nothing on either subnet needs to change. This lets you test most of your IPSEC setup before connecting to the insecure Internet.

### Traceroute does not show anything between the gateways

As far as traceroute can see, the two gateways are one hop apart; the data packet goes directly from one to the other through the tunnel. Of course the outer packets that implement the tunnel pass through whatever lies between the gateways, but those packets are built and dismantled by the gateways. Traceroute does not see them and cannot report anything about their path.

Here is a mailing list message with more detail.

    Date: Mon, 14 May 2001
    To: linux-ipsec@freeswan.org
    From: "John S. Denker" <jsd@research.att.com<
    Subject: Re: traceroute: one virtual hop

    At 02:20 PM 5/14/01 -0400, Claudia Schmeing wrote:
    >
    >> > A bonus question: traceroute in subnet to subnet enviroment looks like:
    >> >
    >> > traceroute to andris.dmz (172.20.24.10), 30 hops max, 38 byte packets
    >> > 1  drama (172.20.1.1)  0.716 ms  0.942 ms  0.434 ms
    >> > 2  * * *
    >> > 3  andris.dmz (172.20.24.10)  73.576 ms  78.858 ms  79.434 ms
    >> >
    >> > Why aren't there the other hosts which take part in the delivery during
    >    * * * ?
    >
    >If there is an ipsec tunnel between GateA and Gate B, this tunnel forms a
    >'virtual wire'.  When it is tunneled, the original packet becomes an inner
    >packet, and new ESP and/or AH headers are added to create an outer packet
    >around it. You can see an example of how this is done for AH at
    >doc/ipsec.html#AH . For ESP it is similar.
    >
    >Think about the packet's path from the inner packet's perspective.
    >It leaves the subnet, goes into the tunnel, and re-emerges in the second
    >subnet. This perspective is also the only one available to the
    >'traceroute' command when the IPSec tunnel is up.

    Claudia got this exactly right.  Let me just expand on a couple of points:

    *) GateB is exactly one (virtual) hop away from GateA.  This is how it
    would be if there were a physically private wire from A to B.  The
    virtually private connection should work the same, and it does.

    *) While the information is in transit from GateA to GateB, the hop count
    of the outer header (the "envelope") is being decremented.  The hop count
    of the inner header (the "contents" of the envelope) is not decremented and
    should not be decremented.  The hop count of the outer header is not
    derived from and should not be derived from the hop count of the inner header.

    Indeed, even if the packets did time out in transit along the tunnel, there
    would be no way for traceroute to find out what happened.  Just as
    information cannot leak _out_ of the tunnel to the outside, information
    cannot leak _into_ the tunnel from outside, and this includes ICMP messages
    from routers along the path.

    There are some cases where one might wish for information about what is
    happening at the IP layer (below the tunnel layer) -- but the protocol
    makes no provision for this.  This raises all sorts of conceptual issues.
    AFAIK nobody has ever cared enough to really figure out what _should_
    happen, let alone implement it and standardize it.

    *) I consider the "* * *" to be a slight bug.  One might wish for it to be
    replaced by "GateB GateB GateB".  It has to do with treating host-to-subnet
    traffic different from subnet-to-subnet traffic (and other gory details).
    I fervently hope KLIPS2 will make this problem go away.

    *) If you want to ask questions about the link from GateA to GateB at the
    IP level (below the tunnel level), you have to ssh to GateA and launch a
    traceroute from there.

## Testing in stages

It is often useful in debugging to test things one at a time:

- disable IPSEC entirely, e.g. by turning it off with chkconfig(8), and make sure routing works
- Once that works, try a manually keyed connection. This does not require key negotiation between Pluto and the key daemon on the other end.
- Once that works, try automatically keyed connections
- Once IPSEC works, add packet compression
- Once everything seems to work, try stress tests with large transfers, many connections, frequent re-keying, ...

FreeS/WAN releases are tested for all of these, so you can be reasonably certain they can do them all. Of course, that does not mean they will on the first try, especially if you have some unusual configuration.

The rest of this section gives information on diagnosing the problem when each of the above steps fails.

### Manually keyed connections don't work

Suspect one of:

- mis-configuration of IPSEC system in the /etc/ipsec.conf file
  e.g. incorrect interface or next hop information
- mis-configuration of manual connection in the /etc/ipsec.conf file
- routing problems causing IPSEC packets to be lost
- bugs in KLIPS
- mismatch between the transforms we support and those another IPSEC implementation offers.

### One manual connection works, but second one fails

This is fairly common problem when attempting to configure multiple manually keyed connections from a single gateway.

Each connection must be identified by a unique SPI value. For automatic connections, these values are assigned automatically. For manual connections, you must set them with spi= statements in ipsec.conf(5).

Each manual connection must have a unique SPI value in the range 0x100 to 0x999. Two or more with the same value will fail. For details, see our HTML doc section Using manual keying in production and the man page ipsec.conf(5).

### Manual connections work, but automatic keying doesn't

The most common reason for this behaviour is a firewall dropping the UDP port 500 packets used in key negotiation.

Other possibilities:

- mis-configuration of auto connection in the /etc/ipsec.conf file.

One common configuration error is forgetting that you need auto=add to load the connection description on the receiving end so it recognises the connection when the other end asks for it.

- error in shared secret in /etc/ipsec.secrets
- one gateway lacks a route to the other so Pluto's UDP packets are lost
- bugs in Pluto
- incompatibilities between Pluto's IKE implementation and the IKE at the other end of the tunnel.

Some possibile problems are discussed in out interoperation document.

### IPSEC works, but connections using compression fail

Suspect one of:

- (especially if small packets are OK, but large ones fail) compatibility issues with other implementations. We follow the RFCs and omit some extra material that many compression libraries add by default. Others may have the extras left in.
- bugs in the FreeS/WAN IPComp code, which is new for 1.6 and not yet heavily tested

### Small packets work, but large transfers fail

If tests with ping(1) and a small packet size succeed, but tests or transfers with larger packet sizes fail, suspect problems with path MTU discovery.

IPSEC makes packets larger by adding an ESP or AH header. This can tickle assorted bugs in path MTU discovery mechanisms and cause a variety of annoying symptoms. Here is one example of a discussion of this problem off the mailing list:

    Date: Mon, 3 Apr 2000
    From: "Michael H. Warfield" <mhw@wittsend.com>

    Paul Koning wrote:

    >  Chris>  It appears that the Osicom router discards IP
    >  Chris> fragments...

    > Amazing.  A device that discards fragments isn't a router, it's at
    > best a boat anchor.

            It may not be exactly what it appears.  I ran into a similar problem
    with an ISDN link a while ago giving similar symptoms.  Turned out that
    the device was negotiating an MTU that it really couldn't handle and the
    device in front of it (a Linux box with always defragment enabled) was
    defragmenting the huge IPSec datagrams and then refragmenting them into
    hunks that the ISDN PPP thought it could handle but couldn't.  Problem was
    solved by manually capping the MTU on the ISDN link to a smaller value.

            I gave the FreeSwan guys a hard time until tracking it down since
    FreeSwan was the only thing that appeared to be able to tickle the bug.
    Nothing else seemed to be broken.  What it really was that MTU discovery
    was avoiding the problem on normal links and it was only the IPSEC tunnels
    that were creating huge datagrams that went through the defragment/refragment
    process.

            Point here is that it "appeared" as though the ISDN link was
    failing to handle fragments when it was really a configuration error and
    a software bug resulting in a bad MTU that was really the culprit.  So
    it may not be that the router is not handling fragments.  It may be that
    it's missconfigured or has some other bug that only FreeSwan is tripping
    over.

### Subnet-to-subnet works, but tests from the gateways don't

This is described under I cannot ping... above.

## Interpreting error messages

### SIOCADDRT:Network is unreachable

This message is not from FreeS/WAN, but from the Linux IP stack itself. That stack is seeing packets it has no route for, either because your routing was broken before FreeS/WAN started or because FreeS/WAN's changes broke it.

Here is a message from FreeS/WAN "listress" (mailing list tech support person) Claudia Schmeing suggesting ways to diagnose and fix such problems:

    You write,
    > I have correctly installed freeswan-1.8 on RH7.0 kernel 2.2.17, but when
    > I setup a VPN connection with the other machine(RH5.2 Kernel 2.0.36
    > freeswan-1.0, it works well.) it told me that
    > "SIOCADDRT:Network is unreachable"!  But the network connection is no
    > problem.

    Often this error is the result of a misconfiguration.

    Be sure that you can route successfully in the absence of Linux
    FreeS/WAN. (You say this is no problem, so proceed to the next step.)

    Use a custom copy of the default updownscript. Do not change the route
    commands, but add a diagnostic message revealing the exact text of the
    route command. Is there a problem with the sense of the route command
    that you can see? If so, then re-examine those ipsec.conf settings
    that are being sent to the route command.

    You may wish to use the ipsec auto --route and --unroute commands to
    troubleshoot the problem. See man ipsec_auto for details.

Since the above message was written, we have modified the updown script to provide a better diagnostic for this problem. Check /var/log/messages.

### ipsec_setup: Fatal error, kernel appears to lack KLIPS

This message indicates an installation failure. The kernel you are running does not contain the KLIPS (kernel IPSEC) code.

Commands you can quickly try are:

uname -a
  to get details, including compilation date and time, of the currently running kernel
ls /
ls /boot
  to ensure a new kernel is where it should be. If kernel compilation puts it in / but lilo wants it in /boot , then you should uncomment the INSTALL_PATH=/boot line in the kernel Makefile.
more /etc/lilo.conf
  to see that lilo has correct information
lilo
  to ensure that information in /etc/lilo.conf has been transferred to the boot sector

If those don't find the problem, you have to go back and check through the install procedure to see what was missed.

Here is one of Claudia's messages on the topic:

    > I tried to install freeswan 1.8 on my mandrake 7.2 test box. ...

    > It does show version and some output for whack.

    Yes, because the Pluto (daemon) part of ipsec is installed correctly, but
    as we see below the kernel portion is not.

    > However, I get the following from /var/log/messages:
    >
    > Mar 11 22:11:55 pavillion ipsec_setup: Starting FreeS/WAN IPSEC 1.8...
    > Mar 11 22:12:02 pavillion ipsec_setup: modprobe: Can't locate module ipsec
    > Mar 11 22:12:02 pavillion ipsec_setup: Fatal error, kernel appears to lack
    > KLIPS.

    This is your problem. You have not successfully installed a kernel with
    IPSec machinery in it.

    Did you build Linux FreeS/WAN as a module? If so, you need to ensure that
    your new module has been installed in the directory where your kernel
    loader normally finds your modules. If not, you need to ensure
    that the new IPSec-enabled kernel is being loaded correctly.

    See also doc/install.html, and INSTALL in the distro.

### ipsec_setup: ... failure to fetch key for ... from DNS

Quoting Henry:

    Note that by default, FreeS/WAN is now set up to
         (a) authenticate with RSA keys, and
         (b) fetch the public key of the far end from DNS.
    Explicit attention to  ipsec.conf will be needed if you want
    to do something different.

and Claudia, responding to the same user:

    You write,

    >       My current setup in ipsec.conf is leftrsasigkey=%dns I have
    > commented this and authby=rsasig out. I am able to get ipsec running,
    > but what I find is that the documentation only specifies for %dns are
    > there any other values that can be placed in this variable other than
    > %dns and the key? I am also assuming that this is where I would place
    > my public key for the left and right side as well is this correct?

    Valid values for authby= are rsasig and secret, which entail authentication
    by RSA signature or by shared secret, respectively. Because you have
    commented authby=rsasig out, you are using the default value of authby=secret.

    When using RSA signatures, there are two ways to get the public key for the
    IPSec peer: either copy it directly into *rsasigkey= in ipsec.conf, or
    fetch it from dns. The magic value %dns for *rsasigkey parameters says to
    try to fetch the peer's key from dns.

    For any parameters, you may find their significance and special values in
    man ipsec.conf. If you are setting up keys or secrets, be sure also to
    reference man ipsec.secrets.

### ipsec_setup: ... interfaces ... and ... share address ...

This is a fatal error. FreeS/WAN cannot cope with two or more interfaces using the same IP address. You must re-configure to avoid this.

A mailing list message on the topic from Pluto developer Hugh Redelmeier:

    | I'm trying to get freeswan working between two machine where one has a ppp
    | interface.
    | I've already suceeded with  two machines with ethernet ports but  the ppp
    | interface is causing me problems.
    |  basically when I run ipsec start  i get
    | ipsec_setup: Starting FreeS/WAN IPSEC 1.7...
    | ipsec_setup: 003 IP interfaces ppp1 and ppp0 share address 192.168.0.10!
    | ipsec_setup: 003 IP interfaces ppp1 and ppp2 share address 192.168.0.10!
    | ipsec_setup: 003 IP interfaces ppp0 and ppp2 share address 192.168.0.10!
    | ipsec_setup: 003 no public interfaces found
    |
    | followed by lots of cannot work out interface for connection messages
    |
    | now I can specify the interface in ipsec.conf to be ppp0 , but this does
    | not affect the above behaviour. A quick look in server.c indicates that the
    | interfaces value  is not used but some sort of raw detect happens.
    |
    | I guess I could prevent the formation of the extra ppp interfaces or
    | allocate them different ip but I'd  rather not. if at all possible. Any
    | suggestions please.

    Pluto won't touch an interface that shares an IP address with another.
    This will eventually change, but it probably won't happen soon.

    For now, you will have to give the ppp1 and ppp2 different addresses.

### ipsec_setup: Cannot adjust kernel flags

A mailing list message form technical lead Henry Spencer:

    > When FreeS/WAN IPSEC 1.7 is starting on my 2.0.38 Linux kernel the following
    > error message is generated:
    > ipsec_setup: Cannot adjust kernel flags, no /proc/sys/net/ipsec directory!
    > What is supposed to create this directory and how can I fix this problem?

    I think that directory is a 2.2ism, although I'm not certain (I don't have
    a 2.0.xx system handy any more for testing).  Without it, some of the
    ipsec.conf config-setup flags won't work, but otherwise things should
    function.

You also need to enable the /proc filesystem in your kernel configuration for these operations to work.

### Connection names in Pluto error messages

From Pluto programmer Hugh Redelmeier:

    | Jan 17 16:21:10 remus Pluto[13631]: "jumble" #1: responding to Main Mode from Road Warrior 130.205.82.46
    | Jan 17 16:21:11 remus Pluto[13631]: "jumble" #1: no suitable connection for peer @banshee.wittsend.com
    |
    |     The connection "jumble" has nothing to do with the incoming
    | connection requests, which were meant for the connection "banshee".

    You are right.  The message tells you which Connection Pluto is
    currently using, which need not be the right one.  It need not be the
    right one now for the negotiation to eventually succeed!  This is
    described in ipsec_pluto(8) in the section "Road Warrior Support".

    There are two times when Pluto will consider switching Connections for
    a state object.  Both are in response to receiving ID payloads (one in
    Phase 1 / Main Mode and one in Phase 2 / Quick Mode).  The second is
    not unique to Road Warriors.  In fact, neither is the first any more
    (two connections for the same pair of hosts could differ in Phase 1 ID
    payload; probably nobody else has tried this).

### Pluto: ... can't orient connection

Each Pluto needs to know whether it is running on the machine which the connection description calls left or on right . It figures that out by:

- looking at the interfaces given in interfaces= lines in the config setup section
- discovering the IP addresses for those interfaces
- searching for a match between those addresses and the ones given in left= or right= lines.

Normally a match is found. Then Pluto knows where it is and can set up other things (for example, if it is left) using parameters such as leftsubnet and leftnexthop, and sending its outgoing packets to right.

If no match is found, it emits the above error message.

### Pluto: ... no connection is known

This error message occurs when a remote system attempts to negotiate a connection and Pluto does not have a connection description that matches what the remote system has requested. The most common cause is a configuration error on one end or the other.

Parameters involved in this match are left, right , leftsubnet and rightsubnet.

The match must be exact. For example, if your left subnet is a.b.c.0/24 then neither a single machine in that net nor a smaller subnet such as a.b.c.64/26 will be considered a match.

The message can also occur when an appropriate description exists but Pluto has not loaded it. Use an auto=add statement in the connection description, or an ipsec auto --add <conn_name> command, to correct this.

An explanation from the Pluto developer:

    | Jul 12 15:00:22 sohar58 Pluto[574]: "corp_road" #2: cannot respond to IPsec
    | SA request because no connection is known for
    | 216.112.83.112/32===216.112.83.112...216.67.25.118

    This is the first message from the Pluto log showing a problem.  It
    means that PGPnet is trying to negotiate a set of SAs with this
    topology:

    216.112.83.112/32===216.112.83.112...216.67.25.118
    ^^^^^^^^^^^^^^^^^   ^^^^^^^^^^^^^^   ^^^^^^^^^^^^^
    client on our side  our host         PGPnet host, no client

    None of the conns you showed look like this.

    Use
            ipsec auto --status
    to see a snapshot of what connections are in pluto, what
    negotiations are going on, and what SAs are established.

    The leftsubnet= (client) in your conn is 216.112.83.64/26.  It must
    exactly match what pluto is looking for, and it does not.

### Pluto: ... no suitable connection ...

This is similar to the no connection known error, but occurs at a different point in Pluto processing.

Here is one of Claudia's messages explaining the problem:

    You write,

    > What could be the reason of the following error?
    > "no suitable connection for peer '@xforce'"

    When a connection is initiated by the peer, Pluto must choose which entry in
    the conf file best matches the incoming connection. A preliminary choice is
    made on the basis of source and destination IPs, since that information is
    available at that time.

    A payload containing an ID arrives later in the negotiation. Based on this
    id and the *id= parameters, Pluto refines its conn selection. ...

    The message "no suitable connection" indicates that in this refining step,
    Pluto does not find a connection that matches that ID.

    Please see "Selecting a connection when responding" in man ipsec_pluto for
    more details.

See also Connection names in Pluto error messages.

### Pluto: ... no connection has been authorized

Here is one of Claudia's messages discussing this problem:

    You write,

    >  May 22 10:46:31 debian Pluto[25834]: packet from x.y.z.p:10014:
    >  initial Main Mode message from x.y.z.p:10014
                                but no connection has been authorized

    This error occurs early in the connection negotiation process,
    at the first step of IKE negotiation (Main Mode), which is itself the
    first of two negotiation phases involved in creating an IPSec connection.

    Here, Linux FreeS/WAN receives a packet from a potential peer, which
    requests that they begin discussing a connection.

    The "no connection has been authorized" means that there is no connection
    description in Linux FreeS/WAN's internal database that can be used to
    link your ipsec interface with that peer.

    "But of course I configured that connection!"

    It may be that the appropriate connection description exists in ipsec.conf
    but has not been added to the database with ipsec auto --add myconn or the
    auto=add method. Or, the connection description may be misconfigured.

    The only parameters that are relevant in this decision are left= and right= .
    Local and remote ports are also taken into account -- we see that the port
    is printed in the message above -- but there is no way to control these
    in ipsec.conf.

    Failure at "no connection has been authorized" is similar to the
    "no connection is known for..." error in the FAQ, and the "no suitable
    connection" error described in the snapshot's FAQ. In all three cases,
    Linux FreeS/WAN is trying to match parameters received in the
    negotiation with the connection description in the local config file.

    As it receives more information, its matches take more parameters into
    account, and become more precise:  first the pair of potential peers,
    then the peer IDs, then the endpoints (including any subnets).

    The "no suitable connection for peer *" occurs toward the end of IKE
    (Main Mode) negotiation, when the IDs are matched.

    "no connection is known for a/b===c...d" is seen at the beginning of IPSec
    (Quick Mode, phase 2) negotiation, when the connections are matched using
    left, right, and any information about the subnets.

### Pluto: ... OAKLEY_DES_CBC is not supported.

This message occurs when the other system attempts to negotiate a connection using single DES, which we do not support because it is insecure.

Our interoperation document has suggestions for how to deal with systems that attempt to use single DES.

### Pluto: ... no acceptable transform

This message means that the other gateway has made a proposal for connection parameters, but nothing they proposed is acceptable to Pluto. Possible causes include:

- misconfiguration on either end
- policy incompatibilities, for example we require encrypted connections but they are trying to create one with just authentication
- interoperation problems, for example they offer only single DES and FreeS/WAN does not support that. (see below for DES problems)

A more detailed explanation, from Pluto programmer Hugh Redelmeier:

    Background:

    When one IKE system (for example, Pluto) is negotiating with another
    to create an SA, the Initiator proposes a bunch of choices and the
    Responder replies with one that it has selected.

    The structure of the choices is fairly complicated.  An SA payload
    contains a list of lists of "Proposals".  The outer list is a set of
    choices: the selection must be from one element of this list.

    Each of these elements is a list of Proposals.  A selection must be
    made from each of the elements of the inner list.  In other words,
    *all* of them apply (that is how, for example, both AH and ESP can
    apply at once).

    Within each of these Proposals is a list of Transforms.  For each
    Proposal selected, one Transform must be selected (in other words,
    each Proposal provides a choice of Transforms).

    Each Transform is made up of a list of Attributes describing, well,
    attributes.  Such as lifetime of the SA.  Such as algorithm to be
    used.  All the Attributes apply to a Transform.

    You will have noticed a pattern here: layers alternate between being
    disjunctions ("or") and conjunctions ("and").

    For Phase 1 / Main Mode (negotiating an ISAKMP SA), this structure is
    cut back.  There must be exactly one Proposal.  So this degenerates to
    a list of Transforms, one of which must be chosen.

    In your case, no proposal was considered acceptable to Pluto (the
    Responder).  So negotiation ceased.  Pluto logs the reason it rejects
    each Transform.  So look back in the log to see what is going wrong.

### ECONNREFUSED error message

From John Denker, on the mailing list:

    1)  The log message
      some IKE message we sent has been rejected with
      ECONNREFUSED (kernel supplied no details)
    is much more suitable than the previous version.  Thanks.

    2) Minor suggestion for further improvement: it might be worth mentioning
    that the command
      tcpdump -i eth1 icmp[0] != 8 and icmp[0] != 0
    is useful for tracking down the details in question.  We shouldn't expect
    all IPsec users to figure that out on their own.  The log message might
    even provide a hint as to where to look in the docs.

Reply From Pluto developer Hugh Redelmeier

    Good idea.

    I've added a bit pluto(8)'s BUGS section along these lines.
    I didn't have the heart to lengthen this message.

- klips_debug: ... no eroute! This message means KLIPS has received a packet for which no IPSEC tunnel has been defined.

Here is a more detailed duscussion from the team's tech support person Claudia Schmeing, responding to a query on the mailing list:

    > Why ipsec reports no eroute! ???? IP Masq... is disabled.
    In general, more information is required so that people on the list may
    give you informed input. See doc/prob.report.

    However, I can make some general comments on this type of error.

    This error usually looks something like this (clipped from an archived
    message):

    > ttl:64 proto:1 chk:45459 saddr:192.168.1.2 daddr:192.168.100.1
    > ... klips_debug:ipsec_findroute: 192.168.1.2->192.168.100.1
    > ... klips_debug:rj_match: * See if we match exactly as a host destination
    > ... klips_debug:rj_match: ** try to match a leaf, t=0xc1a260b0
    > ... klips_debug:rj_match: *** start searching up the tree, t=0xc1a260b0
    > ... klips_debug:rj_match: **** t=0xc1a260c8
    > ... klips_debug:rj_match: **** t=0xc1fe5960
    > ... klips_debug:rj_match: ***** not found.
    > ... klips_debug:ipsec_tunnel_start_xmit: Original head/tailroom: 2, 28
    > ... klips_debug:ipsec_tunnel_start_xmit: no eroute!: ts=47.3030, dropping.

    What does this mean?
    - --------------------

    "eroute" stands for "extended route", and is a special type of route
    internal to Linux FreeS/WAN. For more information about this type of route,
    see the section of man ipsec_auto on ipsec auto --route.

    "no eroute!" here means, roughly, that Linux FreeS/WAN cannot find an
    appropriate tunnel that should have delivered this packet. Linux
    FreeS/WAN therefore drops the packet, with the message "no eroute! ...
    dropping", on the assumption that this packet is not a legitimate
    transmission through a properly constructed tunnel.

    How does this situation come about?
    - -----------------------------------

    Linux FreeS/WAN has a number of connection descriptions defined in
    ipsec.conf. These must be successfully brought "up" to form actual tunnels.
    (see doc/setup.html's step 15, man ipsec.conf and man ipsec_auto
    for details).

    Such connections are often specific to the endpoints' IPs. However, in
    some cases they may be more general, for example in the case of
    Road Warriors where left or right is the special value %any.

    When Linux FreeS/WAN receives a packet, it verifies that the packet has
    come through a legitimate channel, by checking that there is an
    appropriate tunnel through which this packet might legitimately have
    arrived. This is the process we see above.

    First, it checks for an eroute that exactly matches the packet. In the
    example above, we see it checking for a route that begins at 192.168.1.2
    and ends at 192.168.100.1. This search favours the most specific match that
    would apply to the route between these IPs. So, if there is a connection
    description exactly matching these IPs, the search will end there. If not,
    the code will search for a more general description matching the IPs.
    If there is no match, either specific or general, the packet will be
    dropped, as we see, above.

    Unless you are working with Road Warriors, only the first, specific part
    of the matching process is likely to be relevant to you.

    "But I defined the tunnel, and it came up, why do I have this error?"
    - ---------------------------------------------------------------------

    One of the most common causes of this error is failure to specify enough
    connection descriptions to cover all needed tunnels between any two
    gateways and their respective subnets. As you have noticed, troubleshooting
    this error may be complicated by the use of IP Masq. However, this error is
    not limited to cases where IP Masq is used.

    See doc/configuration.html#multitunnel for a detailed example of the
    solution to this type of problem.

### ... trouble writing to /dev/ipsec ... SA already in use

From the mailing list:

    > When I activate one manual tunnels it works, but when I try to activate
    > another tunnel, it gives an error message...
    > tunnel_2: Had trouble writing to /dev/ipsec SA:tun0x200@202.103.5.63 --
    > SA already in use.  Delete old one first.

    Please read the Using manual keying in production discussion in
    config.html, specifically the part about needing a different spi
    (or spibase) setting for each connection.

This problem is also discussed in this FAQ under the heading One manual connection works, but second one fails.

### ... ignoring ... payload

This message is harmless. The IKE protocol provides for a number of optional messages types:

- delete SA
- initial contact
- vendor ID
- ...

An implementation is never required to send these, but they are allowed to. The receiver is not required to do anything with them. FreeS/WAN ignores them, but notifies you via the logs.

For the "ignoring delete SA Payload" message, see also the discussion below of cleaning up dead tunnels.

## Can I ...

### Can I reload connection info without restarting?

Yes, you can do this. Here are the details, in a mailing list message from Pluto programmer Hugh Redelmeier:

    | How can I reload config's without restarting all of pluto and klips?  I am using
    | FreeSWAN -> PGPNet in a medium sized production environment, and would like to be
    | able to add new connections ( i am using include config/* ) without dropping current
    | SA's.
    |
    | Can this be done?
    |
    | If not, are there plans to add this kind of feature?

            ipsec auto --add whatever
    This will look in the usual place (/etc/ipsec.conf) for a conn named
    whatever and add it.

    If you added new secrets, you need to do
            ipsec auto --rereadsecrets
    before Pluto needs to know those secrets.

    | I have looked (perhaps not thoroughly enough tho) to see how to do this:

    There may be more bits to look for, depending on what you are trying
    to do.

Another useful command here is ipsec auto --replace <conn_name> which re-reads data for a named connection.

### Can I use several masqueraded subnets?

Yes. This is done all the time. See the discussion in our setup document. The only restriction is that the subnets on the two ends must not overlap. See the next question.

Here is a mailing list message on the topic. The user incorrectly thinks you need a 2.4 kernel for this -- actually various people have been doing it on 2.0 and 2.2 for quite some time -- but he has it right for 2.4.

    Subject: Double NAT and freeswan working :)
       Date: Sun, 11 Mar 2001
       From: Paul Wouters <paul@xtdnet.nl>

    Just to share my pleasure, and make an entry for people who are searching
    the net on how to do this. Here's the very simple solution to have a double
    NAT'ed network working with freeswan. (Not sure if this is old news, but I'm
    not on the list (too much spam) and I didn't read this in any HOWTO/FAQ/doc
    on the freeswan site yet (Sandy, put it in! :)

    10.0.0.0/24 --- 10.0.0.1 a.b.c.d  ---- a.b.c.e {internet} ----+
                                                                  |
    10.0.1.0/24 --- 10.0.1.1 f.g.h.i  ---- f.g.h.j {internet} ----+

    the goal is to have the first network do a VPN to the second one, yet also
    have NAT in place for connections not destinated for the other side of the
    NAT. Here the two Linux security gateways have one real IP number (cable
    modem, dialup, whatever.

    The problem with NAT is you don't want packets from 10.*.*.* to 10.*.*.*
    to be NAT'ed. While with Linux 2.2, you can't, with Linux 2.4 you can.

    (This has been tested and works for 2.4.2 with Freeswan snapshot2001mar8b)

    relevant parts of /etc/ipsec.conf:

            left=f.g.h.i
            leftsubnet=10.0.1.0/24
            leftnexthop=f.g.h.j
            leftfirewall=yes
            leftid=@firewall.netone.nl
            leftrsasigkey=0x0........
            right=a.b.c.d
            rightsubnet=10.0.0.0/24
            rightnexthop=a.b.c.e
            rightfirewall=yes
            rightid=@firewall.nettwo.nl
            rightrsasigkey=0x0......
            # To authorize this connection, but not actually start it, at startup,
            # uncomment this.
            auto=add

    and now the real trick. Setup the NAT correctly on both sites:

    iptables -t nat -F
    iptables -t nat -A POSTROUTING -o eth0 -d \! 10.0.0.0/8 -j MASQUERADE

    This tells the NAT code to only do NAT for packets with destination other then
    10.* networks. note the backslash to mask the exclamation mark to protect it
    against the shell.

    Happy painting :)

    Paul

### Can I use subnets masqueraded to the same addresses?

No. The notion that IP addresses are unique is one of the fundamental principles of the IP protocol. Messing with it is exceedingly perilous.

Fairly often a situation comes up where a company has several branches, all using the same non-routable addresses, perhaps 192.168.0.0/24. This works fine as long as those nets are kept distinct. The IP masquerading on their firewalls ensures that packets reaching the Internet carry the firewall address, not the private address.

This can break down when IPSEC enters the picture. FreeS/WAN builds a tunnel that pokes through both masquerades and delivers packets from leftsubnet to rightsubnet and vice versa. For this to work, the two subnets must be distinct.

There are several solutions to this problem.

- Usually, you re-number the subnets. Perhaps the Vancouver office becomes 192.168.101.0/24, Calgary 192.168.102.0/24 and so on. FreeS/WAN can happily handle this. With, for example leftsubnet=192.168.101.0/24 and rightsubnet=192.168.102.0/24 in a connection description, any machine in Calgary can talk to any machine in Vancouver. If you want to be more restrictive and use something like leftsubnet=192.168.101.128/25 and rightsubnet=192.168.102.240/28 so only certain machines on each end have access to the tunnel, that's fine too.
- You could also split the subnet into smaller ones, for example using 192.168.1.0/25 in Vancouver and rightsubnet=192.168.0.128/25 in Calgary.
- Alternately, you can just give up routing directly to machines on the subnets. Omit the leftsubnet and rightsubnet parameters from your connection descriptions. Your IPSEC tunnels will then run between the public interfaces of the two firewalls. Packets will be masqueraded both before they are put into tunnels and after they emerge. Your Vancouver client machines will see only one Calgary machine, the firewall.

### Can I assign a road warrior an address on my net?

Yes, but it is tricky. This has been discussed on the mailing list. The discussion was not entirely clear to me, so I cannot yet document the procedures. At this point, all I know is:

- You can use a variant of the extruded subnet procedure.
- You have to avoid having the road warrior's assigned address within the range you actually use at home base. See previous question.
- On the other hand, you want the roadwarrior's address to be within the range that seems to be on your network.

For example, you might have:

leftsubnet=a.b.c.0/25
  head office network
rightsubnet=a.b.c.240/32
  extruded to a road warrior
a.b.c.0/24
  whole network, including both the above

### Can I use Quality of Service routing with FreeS/WAN?

From project technical lead Henry Spencer:

    > Do QoS add to FreeS/WAN?
    >For example integrating DiffServ and FreeS/WAN?

    With a current version of FreeS/WAN, you will have to add hidetos=no to
    the config-setup section of your configuration file.  By default, the TOS
    field of tunnel packets is zeroed; with hidetos=no, it is copied from the
    packet inside.  (This is a modest security hole, which is why it is no
    longer the default.)

    DiffServ does not interact well with tunneling in general.  Ways of
    improving this are being studied.

Copying the TOS information from the encapsulated packet to the outer header reveals the TOS information to an eavesdropper. It is not clear whether or how an attacker could use this information, but since we do not have to give it to him, our default is not to.

See ipsec.conf(5) for more on the hidetos= parameter.

### Can I recognise dead tunnels and shut them down?

There is no general mechanism to do this is in the IPSEC protocols.

From time to time, there is discussion on the IETF Working Group mailing list of adding a "keep-alive" mechanism (which some say should be called "make-dead"), but it is a fairly complex problem and no consensus has been reached on whether or how it should be done.

The protocol does have optional delete-SA messages which one side can send when it closes a connection in hopes this will cause the other side to do the same. FreeS/WAN does not currently support these. In any case, they would not solve the problem since:

- a gateway that crashes or hangs would not send the messages
- the sender is not required to send them
- they are not authenticated, so any receiver that trusts them leaves itself open to a denial of service attack
- the receiver is not required to do anything about them
- the receiver cannot acknowledge them; the protocol provides no mechanism for that
- since they are not acknowledged, the sender cannot rely on them

However, connections do have limited lifetimes and you can control how many attempts your gateway makes to rekey before giving up. For example, you can set:

    conn default
    	keyingtries=3
    	keylife=30m

With these settings old connections will be cleaned up. Within 30 minutes of the other end dying, rekeying will be attempted. If it succeeds, the new connection replaces the old one. If it fails, no new connection is created. Either way, the old connection is taken down when its lifetime expires.

Here is a mailing list message on the topic from FreeS/WAN tech support person Claudia Schmeing:

    You ask how to determine whether a tunnel is redundant:

    > Can anybody explain the best way to determine this. Esp when a RW has
    > disconnected? I thought 'ipsec auto --status' might be one way.

    If a tunnel goes down from one end, Linux FreeS/WAN on the
    other end has no way of knowing this until it attempts to rekey.
    Once it tries to rekey and fails, it will 'know' that the tunnel is
    down.

    Because it doesn't have a way of knowing the state until this point,
    it will also not be able to tell you the state via ipsec auto --status.

    > However, comparing output from a working tunnel with that of one that
    > was closed
    > did not show clearly show tunnel status.

    If your tunnel is down but not 'unrouted' (see man ipsec_auto), you
    should not be able to ping the opposite side of the tunnel. You can
    use this as an indicator of tunnel status.

    On a related note, you may be interested to know that as of 1.7,
    redundant tunnels caused by RW disconnections are likely to be
    less of a pain. From doc/CHANGES:

        There is a new configuration parameter, uniqueids, to control a new Pluto
        option:  when a new connection is negotiated with the same ID as an old
        one, the old one is deleted immediately.  This should help eliminate
        dangling Road Warrior connections when the same Road Warrior reconnects.
        It thus requires that IDs not be shared by hosts (a previously legal but
        probably useless capability).  NOTE WELL:  the sample ipsec.conf now has
        uniqueids=yes in its config-setup section.

    Cheers,

    Claudia

### Can I build IPSEC tunnels over a demand-dialed link?

This is possible, but not easy. FreeS/WAN technical lead Henry Spencer wrote:

    > 5. If the ISDN link goes down in between and is reestablished, the SAs
    > are still up but the eroute are deleted and the IPSEC interface shows
    > garbage (with ifconfig)
    > 6. Only restarting IPSEC will bring the VPN back online.

    This one is awkward to solve.  If the real interface that the IPsec
    interface is mounted on goes down, it takes most of the IPsec machinery
    down with it, and a restart is the only good way to recover.

    The only really clean fix, right now, is to split the machines in two:

    1. A minimal machine serves as the network router, and only it is aware
    that the link goes up and down.

    2. The IPsec is done on a separate gateway machine, which thinks it has
    a permanent network connection, via the router.

    This is clumsy but it does work.  Trying to do both functions within a
    single machine is tricky.  There is a software package (diald) which will
    give the illusion of a permanent connection for demand-dialed modem
    connections; I don't know whether it's usable for ISDN, or whether it can
    be made to cooperate properly with FreeS/WAN.

    Doing a restart each time the interface comes up *does* work, although it
    is a bit painful.  I did that with PPP when I was running on a modem link;
    it wasn't hard to arrange the PPP scripts to bring IPsec up and down at
    the right times.  (I'd meant to investigate diald but never found time.)

    In principle you don't need to do a complete restart on reconnect, but you
    do have to rebuild some things, and we have no nice clean way of doing
    only the necessary parts.

In the same thread, one user commented:

    Subject: Re: linux-ipsec: IPSEC and Dial Up Connections
       Date: Wed, 22 Nov 2000
       From: Andy Bradford <andyb@calderasystems.com>

    On Wed, 22 Nov 2000 19:47:11 +0100, Philip Reetz wrote:

    > Are there any ideas what might be the cause of the problem and any way
    > to work around it.
    > Any help is highly appreciated.

    On my laptop, when using ppp there is a ip-up script in /etc/ppp that
    will be executed each time that the ppp interface is brought up.
    Likewise there is an ip-down script that is called when it is taken
    down.  You might consider custimzing those to stop and start FreeS/Wan
    with each connection.  I believe that ISDN uses the same files, though
    I could be wrong---there should be something similar though.

### Can I build GRE tunnels over IPSEC?

This is possible in theory, but we are short on practical details. If you do this, please let us know via the mailing lists.

Theere is a list message with links to relevant resources.

### Does FreeS/WAN support X.509 or other PKI certificates?

FreeS/WAN, as distributed, does not currently support use of X.509 or other PKI certificates for authentication of gateways. We are concentrating on moving toward authentication via Secure DNS and opportunistic encryption; X.509 support is not (or at least not yet) on the priority list.

On the other hand, it is a priority for some users and user-contributed patches are available to add X.509 certificate support to FreeS/WAN now. See the patches section of our web references document for details.

### Does FreeS/WAN support Radius or other user authentication?

Not yet. So far, there is no standard way to authenticate users for IPSEC, though there is a very active IETF working group looking at the problem, and several vendors have implemented various things already.

In the absence of a standard, user authentication has not been a priority for the FreeS/WAN team, and is unlikely to become one. This would be a good project for a volunteer, perhaps a staff member or contractor at some company that needs the feature. Certainly our team would co-operate with such an effort; we just don't have time to do it.

Of course, there are various ways to avoid any requirement for user authentication in IPSEC. Consider the situation where road warriors build IPSEC tunnels to your office net and you are considering requiring user authentication during tunnel negotiation. Alternatives include:

- If you can trust the road warrior machines, then set them up so that only authorised users can create tunnels. If your road warriors use laptops, consider the possibility of theft.
- If the tunnel only provides access to particular servers and you can trust those servers, then set the servers up to require user authentication.

If either of those is trustworthy, it is not clear that you need user authentication in IPSEC.

### Does FreeS/WAN support single DES encryption?

No, single DES is not used either at the IKE level for negotiating connections or at the IPSEC level for actually building them.

Single DES is insecure. As we see it, it is more important to deliver real security than to comply with a standard which has been subverted into allowing use of inadequate methods. See this discussion.

If you want to interoperate with an IPSEC implementation which offers only DES, see our interoperation document.

## Why don't you restrict the mailing lists to reduce spam?

As a matter of policy, some of our mailing lists need to be open to non-subscribers. Project management feel strongly that maintaining this openness is more important than blocking spam.

- Users should be able to get help or report bugs without subscribing.
- Even a user who is subscribed may not have access to his or her subscribed account when he or she needs help, miles from home base in the middle of setting up a client's gateway.
- There is arguably a legal requirement for this policy. A US resident or citizen could be charged under munitions export laws for providing technical assistance to a foreign cryptographic project. Such a charge would be more easily defended if the discussion takes place in public, on an open list.

This has been discussed several times at some length on the list. See the list archives. Bringing the topic up again is unlikely to be useful. Please don't. Or at the very least, please don't without reading the archives and being certain that whatever you are about to suggest has not yet been discussed.

Project technical lead Henry Spencer summarised one discussion:

> For the third and last time: this list *will* *not* do address-based filtering. This is a policy decision, not an implementation problem. The decision is final, and is not open to discussion. This needs to be communicated better to people, and steps are being taken to do that.

Adding this FAQ section is one of the steps he refers to.

You have various options other than just putting up with the spam, filtering it yourself, or unsubscribing:

- subscribe only to one or both of our lists with restricted posting rules:
  - briefs , weekly list summaries
  - announce , project-related announcements
- read the other lists via the archives

A number of tools are available to filter mail.

- Many mail readers include some filtering capability.
- Many Linux distributions include procmail(8) for server-side filtering.
- The Spam Bouncer is a set of procmail(8) filters designed to combat spam.
- Roaring Penguin have a MIME defanger that removes potentially dangerous attachments.

If you use your ISP's mail server rather than running your own, consider suggesting to the ISP that they tag suspected spam as this ISP does. They could just refuse mail from dubious sources, but that is tricky and runs some risk of losing valuable mail or senselessly annoying senders and their admins. However, they can safely tag and deliver dubious mail. The tags can greatly assist your filtering.

For information on tracking down spammers, see these HowTos, or the Sputum site. Sputum have a Linux anti-spam screensaver available for download.

Here is a more detailed message from Henry:

    On Mon, 15 Jan 2001, Jay Vaughan wrote:
    > I know I'm flogging a dead horse here, but I'm curious as to the reasons for
    > an aversion for a subscriber-only mailing list?

    Once again:  for legal reasons, it is important that discussions of these
    things be held in a public place -- the list -- and we do not want to
    force people to subscribe to the list just to ask one question, because
    that may be more than merely inconvenient for them.  There are also real
    difficulties with people who are temporarily forced to use alternate
    addresses; that is precisely the time when they may be most in need of
    help, yet a subscribers-only policy shuts them out.

    These issues do not apply to most mailing lists, but for a list that is
    (necessarily) the primary user support route for a crypto package, they
    are very important.  This is *not* an ordinary mailing list; it has to
    function under awkward constraints that make various simplistic solutions
    inapplicable or undesirable.

    > We're *ALL* sick of hearing about list management problems, not just you
    > old-timers, so why don't you DO SOMETHING EFFECTIVE ABOUT IT...

    Because it's a lot harder than it looks, and many existing "solutions"
    have problems when examined closely.

    > A suggestion for you, based on 10 years of experience with management of my
    > own mailing lists would be to use mailman, which includes pretty much every
    > feature under the sun that you guys need and want, plus some.  The URL for
    > mailman...

    I assure you, we're aware of mailman.  Along with a whole bunch of others,
    including some you almost certainly have never heard of (I hadn't!).

    > As for the argument that the list shouldn't be configured to enforce
    > subscription - I contend that it *SHOULD* AT LEAST require manual address
    > verification in order for posts to be redirected.

    You do realize, I hope, that interposing such a manual step might cause
    your government to decide that this is not truly a public forum, and thus
    you could go to jail if you don't get approval from them before mailing to
    it?  If you think this sounds irrational, your government is noted for
    making irrational decisions in this area; we can't assume that they will
    suddenly start being sensible.  See above about awkward constraints.  You
    may be willing to take the risk, but we can't, in good conscience, insist
    that all users with problems do so.

                                                              Henry Spencer
                                                           henry@spsystems.net

and a message on the topic from project leader John Gilmore:

    Subject: Re: The linux-ipsec list's topic
       Date: Sat, 30 Dec 2000
       From: John Gilmore <gnu@toad.com>

    I'll post this single message, once only, in this discussion, and then
    not burden the list with any further off-topic messages.  I encourage
    everyone on the list to restrain themself from posting ANY off-topic
    messages to the linux-ipsec list.

    The topic of the linux-ipsec mailing list is the FreeS/WAN software.

    I frequently see "discussions about spam on a list" overwhelm the
    volume of "actual spam" on a list. BOTH kinds of messages are
    off-topic messages.  Twenty anti-spam messages take just as long to
    detect and discard as twenty spam messages.

    The Linux-ipsec list encourages on-topic messages from people who have
    not joined the list itself.  We will not censor messages to the list
    based on where they originate, or what return address they contain.
    In other words, non-subscribers ARE allowed to post, and this will not
    change.  My own valid contributions have been rejected out-of-hand by
    too many other mailing lists for me to want to impose that censorship
    on anybody else's contributions.  And every day I see the damage that
    anti-spam zeal is causing in many other ways; that zeal is far more
    damaging to the culture of the Internet than the nuisance of spam.

    In general, it is the responsibility of recipients to filter,
    prioritize, or otherwise manage the handling of email that comes to
    them.  It is not the responsibility of the rest of the Internet
    community to refrain from sending messages to recipients that they
    might not want to see.  If your software infrastructure for managing
    your incoming email is insufficient, then improve it.  If you think
    the signal-to-noise ratio on linux-ipsec is too poor, then please
    unsubscribe.  But don't further increase the noise by posting to the
    linux-ipsec list about those topics.

            John Gilmore
            founder sponsor, FreeS/WAN project

# Performance of FreeS/WAN

The performance of FreeS/WAN is adequate for most applications. Perhaps because of that, there are few detailed measurements. Those we know of are below.

The University of Wales at Aberystwyth has done quite detailed tests and put their results on the web.

Even a 486 can handle a T1 line, according to this mailing list message:

    Subject: Re: linux-ipsec: IPSec Masquerade
       Date: Fri, 15 Jan 1999 11:13:22 -0500
       From: Michael Richardson

    . . . A 486/66 has been clocked by Phil Karn to do
    10Mb/s encryption.. that uses all the CPU, so half that to get some CPU,
    and you have 5Mb/s. 1/3 that for 3DES and you get 1.6Mb/s....

and a piece of mail from project technical lead Henry Spencer:

    Oh yes, and a new timing point for Sandy's docs...  A P60 -- yes, a 60MHz
    Pentium, talk about antiques -- running a host-to-host tunnel to another
    machine shows an FTP throughput (that is, end-to-end results with a real
    protocol) of slightly over 5Mbit/s either way.  (The other machine is much
    faster, the network is 100Mbps, and the ether cards are good ones... so
    the P60 is pretty definitely the bottleneck.)

Here is some additional data from the mailing list.

    Subject: FreeSWAN (specically KLIPS) performance measurements
       Date: Thu, 01 Feb 2001
       From: Nigel Metheringham <Nigel.Metheringham@intechnology.co.uk>

    I've spent a happy morning attempting performance tests against KLIPS
    (this is due to me not being able to work out the CPU usage of KLIPS so
    resorting to the crude measurements of maximum throughput to give a
    baseline to work out loading of a box).

    Measurements were done using a set of 4 boxes arranged in a line, each
    connected to the next by 100Mbit duplex ethernet.  The inner 2 had an
    ipsec tunnel between them (shared secret, but I was doing measurements
    when the tunnel was up and running - keying should not be an issue
    here).  The outer pair of boxes were traffic generators or traffic sink.

    The crypt boxes are Compaq DL380s - Uniprocessor PIII/733 with 256K
    cache.  They have 128M main memory.  Nothing significant was running on
    the boxes other than freeswan.  The kernel was a 2.2.19pre7 patched
    with freeswan and ext3.

    Without an ipsec tunnel in the chain (ie the 2 inner boxes just being
    100BaseT routers), throughput (measured with ttcp) was between 10644
    and 11320 KB/sec

    With an ipsec tunnel in place, throughput was between 3268 and 3402
    KB/sec

    These measurements are for data pushed across a TCP link, so the
    traffic on the wire between the 2 ipsec boxes would have been higher
    than this....

    vmstat (run during some other tests, so not affecting those figures) on
    the encrypting box shows approx 50% system 50% idle CPU - which I
    don't believe at all.  Interactive feel of the box was significantly
    sluggish.

    I also tried running the kernel profiler (see man readprofile) during
    test runs.

    A box doing primarily decrypt work showed basically nothing happening -
    I assume interrupts were off.
    A box doing encrypt work showed the following:-
     Ticks Function                                   Load
     ~~~~~ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~    ~~~~~~
       956 total                                      0.0010
       532 des_encrypt2                               0.1330
       110 MD5Transform                               0.0443
        97 kmalloc                                    0.1880
        39 des_encrypt3                               0.1336
        23 speedo_interrupt                           0.0298
        14 skb_copy_expand                            0.0250
        13 ipsec_tunnel_start_xmit                    0.0009
        13 Decode                                     0.1625
        11 handle_IRQ_event                           0.1019
        11 .des_ncbc_encrypt_end                      0.0229
        10 speedo_start_xmit                          0.0188
         9 satoa                                      0.0225
         8 kfree                                      0.0118
         8 ip_fragment                                0.0121
         7 ultoa                                      0.0365
         5 speedo_rx                                  0.0071
         5 .des_encrypt2_end                          5.0000
         4 _stext                                     0.0140
         4 ip_fw_check                                0.0035
         2 rj_match                                   0.0034
         2 ipfw_output_check                          0.0200
         2 inet_addr_type                             0.0156
         2 eth_copy_and_sum                           0.0139
         2 dev_get                                    0.0294
         2 addrtoa                                    0.0143
         1 speedo_tx_buffer_gc                        0.0024
         1 speedo_refill_rx_buf                       0.0022
         1 restore_all                                0.0667
         1 number                                     0.0020
         1 net_bh                                     0.0021
         1 neigh_connected_output                     0.0076
         1 MD5Final                                   0.0083
         1 kmem_cache_free                            0.0016
         1 kmem_cache_alloc                           0.0022
         1 __kfree_skb                                0.0060
         1 ipsec_rcv                                  0.0001
         1 ip_rcv                                     0.0014
         1 ip_options_fragment                        0.0071
         1 ip_local_deliver                           0.0023
         1 ipfw_forward_check                         0.0139
         1 ip_forward                                 0.0011
         1 eth_header                                 0.0040
         1 .des_encrypt3_end                          0.0833
         1 des_decrypt3                               0.0034
         1 csum_partial_copy_generic                  0.0045
         1 call_out_firewall                          0.0125

    Hope this data is helpful to someone... however the lack of visibility
    into the decrypt side makes things less clear

## Methods of mesasuring

If you want to measure the loads FreeS/WAN puts on a system, note that tools such as top or measurements such as load average are more-or-less useless for this. They are not designed to measure something that does most of its work inside the kernel.

Here is a message from FreeS/WAN kernel programmer Richard Guy Briggs on this:

    > I have a batch of boxes doing Freeswan stuff.
    > I want to measure the CPU loading of the Freeswan tunnels, but am
    > having trouble seeing how I get some figures out...
    >
    >  - Keying etc is in userspace so will show up on the per-process
    >    and load average etc (ie pluto's load)

    Correct.

    >  - KLIPS is in the kernel space, and does not show up in load average
    >    I think also that the KLIPS per-packet processing stuff is running
    >    as part of an interrupt handler so it does not show up in the
    >    /proc/stat system_cpu or even idle_cpu figures

    It is not running in interrupt handler.  It is in the bottom half.
    This is somewhere between user context (careful, this is not
    userspace!) and hardware interrupt context.

    > Is this correct, and is there any means of instrumenting how much the
    > cpu is being loaded - I don't like the idea of a system running out of
    > steam whilst still showing 100% idle CPU :-)

    vmstat seems to do a fairly good job, but use a running tally to get a
    good idea.  A one-off call to vmstat gives different numbers than a
    running stat.  To do this, put an interval on your vmstat command
    line.

and another suggestion from the same thread:

    Subject: Re: Measuring the CPU usage of Freeswan
       Date: Mon, 29 Jan 2001
       From: Patrick Michael Kane <modus@pr.es.to>

    The only truly accurate way to accurately track FreeSWAN CPU usage is to use
    a CPU soaker. You run it on an unloaded system as a benchmark, then start up
    FreeSWAN and take the difference to determine how much FreeSWAN is eating.
    I believe someone has done this in the past, so you may find something in
    the FreeSWAN archives.  If not, someone recently posted a URL to a CPU
    soaker benchmark tool on linux-kernel.