From aaa0331ecf95ced1e913ac9be50168cf0e7cbb82 Mon Sep 17 00:00:00 2001 From: Rene Mayrhofer Date: Tue, 30 Jan 2007 12:21:07 +0000 Subject: [svn-upgrade] Integrating new upstream version, strongswan (2.8.2) --- CHANGES | 11 + Makefile.inc | 10 +- Makefile.ver | 2 +- doc/.cvsignore | 66 - doc/HowTo.html | 18733 ---------------------------- doc/Makefile | 167 - doc/adv_config.html | 1232 -- doc/background.html | 323 - doc/biblio.html | 274 - doc/compat.html | 707 -- doc/config.html | 308 - doc/faq.html | 2339 ---- doc/firewall.html | 767 -- doc/glossary.html | 2132 ---- doc/index.html | 55 - doc/install.html | 286 - doc/interop.html | 983 -- doc/intro.html | 733 -- doc/ipsec.html | 1040 -- doc/kernel.html | 353 - doc/mail.html | 216 - doc/makecheck.html | 523 - doc/manpages.html | 145 - doc/nightly.html | 125 - doc/oppimpl.txt | 514 - doc/opportunism-spec.txt | 1254 -- doc/opportunism.howto | 415 - doc/opportunism.known-issues | 287 - doc/opportunism.nr | 1115 -- doc/performance.html | 458 - doc/policygroups.html | 341 - doc/politics.html | 1231 -- doc/quickstart.html | 323 - doc/rfc.html | 135 - doc/roadmap.html | 167 - doc/src/.cvsignore | 3 - doc/src/adv_config.html | 1412 --- doc/src/background.html | 376 - doc/src/biblio.html | 354 - doc/src/buildtools.html | 27 - doc/src/compat.html | 795 -- doc/src/config.html | 394 - doc/src/crosscompile.html | 105 - doc/src/faq.html | 2770 ---- doc/src/firewall.html | 895 -- doc/src/forwardingstate.txt | 35 - doc/src/glossary.html | 2257 ---- doc/src/index.html | 55 - doc/src/initiatorstate.txt | 66 - doc/src/install.html | 378 - doc/src/interop.html | 1802 --- doc/src/intro.html | 887 -- doc/src/ipsec.html | 1206 -- doc/src/kernel.html | 392 - doc/src/mail.html | 250 - doc/src/makecheck.html | 684 - doc/src/manpages.html | 155 - doc/src/nightly.html | 164 - doc/src/performance.html | 576 - doc/src/policy-groups-table.html | 297 - doc/src/policygroups.html | 489 - doc/src/politics.html | 1466 --- doc/src/quickstart-configs.html | 144 - doc/src/quickstart-firewall.html | 187 - doc/src/quickstart.html | 458 - doc/src/reference.ESPUDP.xml | 34 - doc/src/reference.KEYRESTRICT.xml | 31 - doc/src/reference.MODPGROUPS.xml | 32 - doc/src/reference.OEspec.xml | 45 - doc/src/reference.RFC.3526.xml | 32 - doc/src/responderstate.txt | 43 - doc/src/rfc.html | 158 - doc/src/roadmap.html | 203 - doc/src/testing.html | 395 - doc/src/testingtools.html | 188 - doc/src/trouble.html | 840 -- doc/src/uml-rhroot-list.txt | 91 - doc/src/uml-rhroot.html | 116 - doc/src/uml-stack-trace.html | 129 - doc/src/umltesting.html | 478 - doc/src/upgrading.html | 260 - doc/src/user_examples.html | 322 - doc/src/web.html | 905 -- doc/testing.html | 332 - doc/toc.html | 1019 -- doc/trouble.html | 706 -- doc/umltesting.html | 313 - doc/upgrading.html | 184 - doc/user_examples.html | 320 - doc/web.html | 749 -- programs/pluto/Makefile | 14 +- programs/pluto/constants.c | 25 +- programs/pluto/constants.h | 29 +- programs/pluto/demux.c | 13 +- programs/pluto/ike_alg.c | 9 +- programs/pluto/modecfg.c | 196 +- programs/pluto/plutomain.c | 23 +- programs/pluto/rcv_info.c | 308 - programs/pluto/rcv_info.h | 18 - programs/pluto/server.c | 65 +- programs/pluto/vendor.c | 6 +- programs/pluto/vendor.h | 4 +- programs/starter/starterwhack.c | 4 +- testing/INSTALL | 4 +- testing/hosts/winnetou/etc/conf.d/apache2 | 2 +- testing/hosts/winnetou/etc/init.d/slapd | 2 +- testing/testing.conf | 4 +- 107 files changed, 251 insertions(+), 65249 deletions(-) delete mode 100644 doc/.cvsignore delete mode 100644 doc/HowTo.html delete mode 100644 doc/Makefile delete mode 100644 doc/adv_config.html delete mode 100644 doc/background.html delete mode 100644 doc/biblio.html delete mode 100644 doc/compat.html delete mode 100644 doc/config.html delete mode 100644 doc/faq.html delete mode 100644 doc/firewall.html delete mode 100644 doc/glossary.html delete mode 100644 doc/index.html delete mode 100644 doc/install.html delete mode 100644 doc/interop.html delete mode 100644 doc/intro.html delete mode 100644 doc/ipsec.html delete mode 100644 doc/kernel.html delete mode 100644 doc/mail.html delete mode 100644 doc/makecheck.html delete mode 100644 doc/manpages.html delete mode 100644 doc/nightly.html delete mode 100644 doc/oppimpl.txt delete mode 100644 doc/opportunism-spec.txt delete mode 100644 doc/opportunism.howto delete mode 100644 doc/opportunism.known-issues delete mode 100644 doc/opportunism.nr delete mode 100644 doc/performance.html delete mode 100644 doc/policygroups.html delete mode 100644 doc/politics.html delete mode 100644 doc/quickstart.html delete mode 100644 doc/rfc.html delete mode 100644 doc/roadmap.html delete mode 100644 doc/src/.cvsignore delete mode 100644 doc/src/adv_config.html delete mode 100644 doc/src/background.html delete mode 100644 doc/src/biblio.html delete mode 100644 doc/src/buildtools.html delete mode 100644 doc/src/compat.html delete mode 100644 doc/src/config.html delete mode 100644 doc/src/crosscompile.html delete mode 100644 doc/src/faq.html delete mode 100644 doc/src/firewall.html delete mode 100644 doc/src/forwardingstate.txt delete mode 100644 doc/src/glossary.html delete mode 100644 doc/src/index.html delete mode 100644 doc/src/initiatorstate.txt delete mode 100644 doc/src/install.html delete mode 100644 doc/src/interop.html delete mode 100644 doc/src/intro.html delete mode 100644 doc/src/ipsec.html delete mode 100644 doc/src/kernel.html delete mode 100644 doc/src/mail.html delete mode 100644 doc/src/makecheck.html delete mode 100644 doc/src/manpages.html delete mode 100644 doc/src/nightly.html delete mode 100755 doc/src/performance.html delete mode 100644 doc/src/policy-groups-table.html delete mode 100644 doc/src/policygroups.html delete mode 100644 doc/src/politics.html delete mode 100644 doc/src/quickstart-configs.html delete mode 100644 doc/src/quickstart-firewall.html delete mode 100644 doc/src/quickstart.html delete mode 100644 doc/src/reference.ESPUDP.xml delete mode 100644 doc/src/reference.KEYRESTRICT.xml delete mode 100644 doc/src/reference.MODPGROUPS.xml delete mode 100644 doc/src/reference.OEspec.xml delete mode 100644 doc/src/reference.RFC.3526.xml delete mode 100644 doc/src/responderstate.txt delete mode 100644 doc/src/rfc.html delete mode 100644 doc/src/roadmap.html delete mode 100644 doc/src/testing.html delete mode 100644 doc/src/testingtools.html delete mode 100644 doc/src/trouble.html delete mode 100644 doc/src/uml-rhroot-list.txt delete mode 100644 doc/src/uml-rhroot.html delete mode 100644 doc/src/uml-stack-trace.html delete mode 100644 doc/src/umltesting.html delete mode 100644 doc/src/upgrading.html delete mode 100755 doc/src/user_examples.html delete mode 100644 doc/src/web.html delete mode 100644 doc/testing.html delete mode 100644 doc/toc.html delete mode 100644 doc/trouble.html delete mode 100644 doc/umltesting.html delete mode 100644 doc/upgrading.html delete mode 100644 doc/user_examples.html delete mode 100644 doc/web.html delete mode 100644 programs/pluto/rcv_info.c delete mode 100644 programs/pluto/rcv_info.h diff --git a/CHANGES b/CHANGES index 5398c0959..2e2d657c8 100644 --- a/CHANGES +++ b/CHANGES @@ -1,3 +1,14 @@ +strongswan-2.8.2 +---------------- + +- strongSwan now interoperates with the NCP Secure Entry Client, + the Shrew Soft VPN Client, and the Cisco VPN client, doing both + XAUTH and Mode Config. + +- UNITY attributes are now recognized and UNITY_BANNER is set + to a default string. + + strongswan-2.8.1 ---------------- diff --git a/Makefile.inc b/Makefile.inc index 8abbbf55c..f09ec409b 100644 --- a/Makefile.inc +++ b/Makefile.inc @@ -11,7 +11,7 @@ # or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License # for more details. # -# RCSID $Id: Makefile.inc,v 1.13 2007/01/11 21:42:11 as Exp $ +# RCSID $Id: Makefile.inc,v 1.14 2007/01/29 08:19:56 as Exp $ # Variables in this file with names starting with INC_ are not for use @@ -244,10 +244,6 @@ USE_IPROUTE2?=true # 2.4 - iptables IPSEC_FIREWALLTYPE=iptables -# whether or not to include ipsec policy code into pluto. -# false for now, since it is still experimental. -USE_IPSECPOLICY?=false - # include IKEPING in the distribution USE_IKEPING?=false @@ -286,9 +282,9 @@ USE_SMARTCARD?=false # Default PKCS11 library # Uncomment this line if using OpenSC <= 0.9.6 -PKCS11_DEFAULT_LIB=\"/usr/lib/pkcs11/opensc-pkcs11.so\" +#PKCS11_DEFAULT_LIB=\"/usr/lib/pkcs11/opensc-pkcs11.so\" # Uncomment this line if using OpenSC >= 0.10.0 -#PKCS11_DEFAULT_LIB=\"/usr/lib/opensc-pkcs11.so\" +PKCS11_DEFAULT_LIB=\"/usr/lib/opensc-pkcs11.so\" # Uncomment and complete this line if using another default library #PKCS11_DEFAULT_LIB=\"/usr/lib/...\" diff --git a/Makefile.ver b/Makefile.ver index 07b052019..f42026a56 100644 --- a/Makefile.ver +++ b/Makefile.ver @@ -1 +1 @@ -IPSECVERSION=2.8.1 +IPSECVERSION=2.8.2 diff --git a/doc/.cvsignore b/doc/.cvsignore deleted file mode 100644 index a523b809d..000000000 --- a/doc/.cvsignore +++ /dev/null @@ -1,66 +0,0 @@ -HowTo.html -HowTo.html -adv_config.html -adv_config.html -background.html -background.html -biblio.html -biblio.html -compat.html -compat.html -config.html -config.html -draft-richardson-ipsec-opportunistic.nr -draft-richardson-ipsec-rr.nr -draft-richardson-ipsec-rr.txt -faq.html -faq.html -firewall.html -firewall.html -glossary.html -glossary.html -index.html -index.html -install.html -install.html -interop.html -interop.html -intro.html -intro.html -ipsec.html -ipsec.html -kernel.html -kernel.html -mail.html -mail.html -makecheck.html -manpage.d -manpage.d -manpages.html -manpages.html -multi_netjig.png -nightly.html -performance.html -performance.html -policygroups.html -politics.html -politics.html -quickstart.html -rfc.html -rfc.html -rfc_pg -roadmap.html -roadmap.html -single_netjig.png -testing.html -testing.html -toc.html -toc.html -trouble.html -trouble.html -umltesting.html -upgrading.html -user_examples.html -user_examples.html -web.html -web.html diff --git a/doc/HowTo.html b/doc/HowTo.html deleted file mode 100644 index a6f92dda9..000000000 --- a/doc/HowTo.html +++ /dev/null @@ -1,18733 +0,0 @@ - - - -Introduction to FreeS/WAN - - - - -

Introduction to FreeS/WAN


-
-
-

Table of Contents

-
-
Introduction - -Upgrading to FreeS/WAN 2.x - -Quickstart Guide to Opportunistic Encryption - - -How to Configure Linux FreeS/WAN with Policy Groups - -FreeS/WAN FAQ - -FreeS/WAN manual pages - -FreeS/WAN and firewalls - -Linux FreeS/WAN Troubleshooting Guide - -Linux FreeS/WAN Compatibility Guide - -Interoperating with FreeS/WAN - -Performance of FreeS/WAN - -Testing FreeS/WAN - -Kernel configuration for FreeS/WAN - -Other configuration possibilities - -Installing FreeS/WAN - -How to configure FreeS/WAN - -Linux FreeS/WAN background - -FreeS/WAN script examples - -How to configure to use "make check" - -How to write a "make check" test - -Current pitfalls -
-
User-Mode-Linux Testing guide - -Debugging the kernel with GDB - -User-Mode-Linux mysteries -
-
Getting more info from uml_netjig -
-
History and politics of cryptography - -The IPsec protocols - -Mailing lists and newsgroups - -Web links - -Glossary for the Linux FreeS/WAN project - -Bibliography for the Linux FreeS/WAN project -
-
IPsec RFCs and related documents - -Distribution Roadmap: What's Where in Linux - FreeS/WAN - -User-Mode-Linux Testing guide - -Debugging the kernel with GDB - -User-Mode-Linux mysteries -
-
Getting more info from uml_netjig -
-
How to configure to use "make check" - -How to write a "make check" test - -Current pitfalls -
-
Nightly regression testing -
-
How to setup the nightly build - -
-

Introduction

-

This section gives an overview of:

- -

This section is intended to cover only the essentials, things you - should know before trying to use FreeS/WAN.

-

For more detailed background information, see the - history and politics and IPsec protocols - sections.

-

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 approach has both considerable advantages and some - limitations. For discussion, see our IPsec section -

-

IPsec can be used on any machine which does IP networking. Dedicated - IPsec gateway machines can be installed wherever required to protect - traffic. IPsec can also run on routers, on firewall machines, on - various application servers, and on end-user desktop or laptop - machines.

-

Three protocols are used

- -

Our implementation has three main parts:

- -

IPsec is optional for the current (version 4) Internet Protocol. - FreeS/WAN adds IPsec to the Linux IPv4 network stack. Implementations - of IP version 6 are required to include - IPsec. Work toward integrating FreeS/WAN into the Linux IPv6 stack has started.

-

For more information on IPsec, see our IPsec - protocols section, our collection of IPsec - links or the RFCs which are the official - definitions of these protocols.

-

Interoperating with other IPsec - implementations

-

IPsec is designed to let different implementations work together. We - provide:

- -

The VPN Consortium fosters cooperation among implementers and - interoperability among implementations. Their - web site has much more information.

-

Advantages of IPsec

-

IPsec has a number of security advantages. Here are some - independently written articles which discuss these:

-

SANS institute papers. See the - section on Encryption &VPNs. -
- Cisco's white papers on "Networking Solutions". -
- Advantages of ISCS (Linux Integrated Secure Communications System; - includes FreeS/WAN and other software).

-

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:

- -

There is enough opportunity in these applications that vendors are - flocking to them. IPsec is being built into routers, into firewall - products, and into major operating systems, primarily to support these - applications. See our list of implementations - for details.

-

We support both of those applications, and various less common IPsec - applications as well, but we also add one of our own:

- -

This is an extension we are adding to the protocols. FreeS/WAN is the - first prototype implementation, though we hope other IPsec - implementations will adopt the technique once we demonstrate it. See - project goals below for why we think this is important.

-

A somewhat more detailed description of each of these applications is - below. Our quickstart section will show you - how to build each of them.

-

Using secure tunnels to create a VPN

-

A VPN, or Virtual Private N -etwork lets two networks communicate securely when the only connection - between them is over a third network which they do not trust.

-

The method is to put a security gateway machine between each of the - communicating networks and the untrusted network. The gateway machines - encrypt packets entering the untrusted net and decrypt packets leaving - it, creating a secure tunnel through it.

-

If the cryptography is strong, the implementation is careful, and the - administration of the gateways is competent, then one can reasonably - trust the security of the tunnel. The two networks then behave like a - single large private network, some of whose links are encrypted tunnels - through untrusted nets.

-

Actual VPNs are often more complex. One organisation may have fifty - branch offices, plus some suppliers and clients, with whom it needs to - communicate securely. Another might have 5,000 stores, or 50,000 - point-of-sale devices. The untrusted network need not be the Internet. - All the same issues arise on a corporate or institutional network - whenever two departments want to communicate privately with each other.

-

Administratively, the nice thing about many VPN setups is that large - parts of them are static. You know the IP addresses of most of the - machines involved. More important, you know they will not change on - you. This simplifies some of the admin work. For cases where the - addresses do change, see the next section.

-

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:

- -

These require somewhat different setup than VPN gateways with static - addresses and with client systems behind them, but are basically not - problematic.

-

There are some difficulties which appear for some road warrior - connections:

- -

In most situations, however, FreeS/WAN supports road warrior - connections just fine.

-

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.

-

Both systems pick up the authentication information they need from - the DNS (domain name service), the service they - already use to look up IP addresses. Of course the administrators must - put that information in the DNS, and must set up their gateways with - opportunistic encryption enabled. Once that is done, everything is - automatic. The gateways look for opportunities to encrypt, and encrypt - whatever they can. Whether they also accept unencrypted communication - is a policy decision the administrator can make.

-

This technique can give two large payoffs:

- -

Opportunistic encryption is not (yet?) a standard part of the IPsec - protocols, but an extension we are proposing and demonstrating. For - details of our design, see links below.

-

Only one current product we know of implements a form of - opportunistic encryption. Secure sendmail will - automatically encrypt server-to-server mail transfers whenever - possible.

-

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:

- -

Automatic keying is much more secure, since if an enemy gets one key - only messages between the previous re-keying and the next are exposed. - It is therefore the usual mode of operation for most IPsec deployment, - and the mode we use in our setup examples. FreeS/WAN does support - manual keying for special circumstanes. See this - section.

-

For automatic keying, the two systems must authenticate each other - during the negotiations. There is a choice of methods for this:

- -

Public key techniques are much preferable, for reasons discussed - later, and will be used in all our setup examples. FreeS/WAN does - also support auto-keying with shared secret authentication. See this - section.

-

The FreeS/WAN project

-

For complete information on the project, see our web site, - freeswan.org.

-

In summary, we are implementing the IPsec - protocols for Linux and extending them to do - opportunistic encryption.

-

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:

- -

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:

- -

The rest of the team are Canadians, working in Canada. ( -Why Canada?)

- -

The project is funded by civil libertarians who consider our goals - worthwhile. Most of the team are paid for this work.

-

People outside this core team have made substantial contributions. - See

- -

Additional contributions are welcome. See the - FAQ for details.

-

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.

-

FreeS/WAN is, however, quite widely used. Products we know of that - use it are listed below. We would appreciate hearing, via the - mailing lists, of any we don't know of.

-

Full Linux distributions

-

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

- -

For distributions which do not include FreeS/WAN and are not Redhat - (which we develop and test on), there is additional information in our compatibility section.

-

The server edition of Corel Linux - (Canada) also had FreeS/WAN, but Corel have dropped that product line.

-

Linux kernel distributions

- -

Office server distributions

-

FreeS/WAN is also included in several distributions aimed at the - market for turnkey business servers:

- -

Firewall distributions

-

Several distributions intended for firewall and router applications - include FreeS/WAN:

- -

There are also several sets of scripts available for managing a - firewall which is also acting as a FreeS/WAN IPsec gateway. See this - list.

-

Firewall and VPN products

-

Several vendors use FreeS/WAN as the IPsec component of a turnkey - firewall or VPN product.

-

Software-only products:

- -

Products that include the hardware:

- -

Rebel.com, makers of the Netwinder Linux - machines (ARM or Crusoe based), had a product that used FreeS/WAN. The - company is in receivership so the future of the Netwinder is at best - unclear. PKIX patches for FreeS/WAN developed at - Rebel are listed in our web links document.

-

Information sources

-

This HowTo, in multiple formats

-

FreeS/WAN documentation up to version 1.5 was available only in HTML. - Now we ship two formats:

- -

and provide a Makefile to generate other formats if required:

- -

The Makefile assumes the htmldoc tool is available. You can download - it from Easy Software.

-

All formats should be available at the following websites:

- -

The distribution tarball has only the two HTML formats.

-

Note: If you need the latest doc version, for - example to see if anyone has managed to set up interoperation between - FreeS/WAN and whatever, then you should download the current snapshot. - What is on the web is documentation as of the last release. Snapshots - have all changes I've checked in to date.

-

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:

- -

Man pages for common commands include:

- -

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

-

In the event of disagreement between this HTML documentation and the - man pages, the man pages are more likely correct since they are written - by the implementers. Please report any such inconsistency on the - mailing list.

-

Other documents in the distribution

-

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

-

The Libdes encryption library we use has its own documentation. You - can find it in the library directory..

-

Background material

-

Throughout this documentation, I write as if the reader had at least - a general familiarity with Linux, with Internet Protocol networking, - and with the basic ideas of system and network security. Of course that - will certainly not be true for all readers, and quite likely not even - for a majority.

-

However, I must limit amount of detail on these topics in the main - text. For one thing, I don't understand all the details of those topics - myself. Even if I did, trying to explain everything here would produce - extremely long and almost completely unreadable documentation.

-

If one or more of those areas is unknown territory for you, there are - plenty of other resources you could look at:

-
-
Linux
-
the Linux Documentation Project - or a local Linux User Group - and these links
-
IP networks
-
Rusty Russell's - Networking Concepts HowTo and these links -
-
Security
-
Schneier's book Secrets and Lies and these - links
-
-

Also, I do make an effort to provide some background material in - these documents. All the basic ideas behind IPsec and FreeS/WAN are - explained here. Explanations that do not fit in the main text, or that - not everyone will need, are often in the glossary -, which is the largest single file in this document set. There is also a background file containing various explanations - too long to fit in glossary definitions. All files are heavily - sprinkled with links to each other and to the glossary. If some - passage makes no sense to you, try the links.

-

For other reference material, see the bibliography - and our collection of web links.

-

Of course, no doubt I get this (and other things) wrong sometimes. - Feedback via the mailing lists is welcome.

-

Archives of the project mailing list

-

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

- - The two archives use completely different search engines. You might - want to try both. -

More recently we have expanded to five lists, each with its own - archive.

-

More information on mailing lists.

-

User-written HowTo information

-

Various user-written HowTo documents are available. The ones covering - FreeS/WAN-to-FreeS/WAN connections are:

- -

User-wriiten HowTo material may be especially helpful if you - need to interoperate with another IPsec implementation. We - have neither the equipment nor the manpower to test such - configurations. Users seem to be doing an admirable job of filling the - gaps.

- -

Check what version of FreeS/WAN user-written documents cover. The - software is under active development and the current version may be - significantly different from what an older document describes.

-

Papers on FreeS/WAN

-

Two design documents show team thinking on new developments:

- -

Both documents are works in progress and are frequently revised. For - the latest version, see the design mailing list. - Comments should go to that list.

-

There is now an - Internet Draft on Opportunistic Encryption by Michael Richardson, - Hugh Redelmeier and Henry Spencer. This is a first step toward getting - the protocol standardised so there can be multiple implementations of - it. Discussion of it takes place on the - IETF IPsec Working Group mailing list.

-

A number of papers giving further background on FreeS/WAN, or - exploring its future or its applications, are also available:

- -

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

-

There are also several papers in languages other than English, see - our web links.

-

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 and the version of MD5 that we use each have - their own license.

-

Distribution sites

-

FreeS/WAN is available from a number of sites.

-

Primary site

-

Our primary site, is at xs4all (Thanks, folks!) in Holland:

- -

Mirrors

-

There are also mirror sites all over the world:

- -

Thanks to those folks as well.

-

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:

- -

Any of those will have a list of other "munitions" mirrors. There is - also a CD available.

-

Links to other sections

-

For more detailed background information, see:

- -

To begin working with FreeS/WAN, go to our - quickstart guide.

-
- -

Upgrading to FreeS/WAN 2.x

-

New! Built in Opportunistic connections

-

Out of the box, FreeS/WAN 2.x will attempt to encrypt all your IP - traffic. It will try to establish IPsec connections for:

- -

FreeS/WAN 2.x uses hidden, automatically enabled - ipsec.conf connections to do this.

-

This behaviour is part of our campaign to get Opportunistic - Encryption (OE) widespread in the Linux world, so that any two Linux - boxes can encrypt to one another without prearrangement. There's one - catch, however: you must set up a few DNS records - to distribute RSA public keys and (if applicable) IPsec gateway - information.

-

If you start FreeS/WAN before you have set up these DNS records, your - connectivity will be slow, and messages relating to the built in - connections will clutter your logs. If you are unable to set up DNS for - OE, you will wish to disable the hidden - connections.

- -

Upgrading Opportunistic Encryption to 2.01 (or - later)

-

As of FreeS/WAN 2.01, Opportunistic Encryption (OE) uses DNS TXT - resource records (RRs) only (rather than TXT with KEY). This change - causes a "flag day". Users of FreeS/WAN 2.00 (or earlier) OE who are - upgrading may need to post additional resource records.

-

If you are running initiate-only OE, you - must put up a TXT record in any forward domain as per our - quickstart instructions. This replaces your old forward KEY.

-

If you are running full OE, you require no updates. You already have - the needed TXT record in the reverse domain. However, to facilitate - future features, you may also wish to publish that TXT record in a - forward domain as instructed here.

-

If you are running OE on a gateway (and encrypting on behalf of - subnetted boxes) you require no updates. You already have the required - TXT record in your gateway's reverse map, and the TXT records for any - subnetted boxes require no updating. However, to facilitate future - features, you may wish to publish your gateway's TXT record in a - forward domain as shown here.

-

During the transition, you may wish to leave any old KEY records up - for some time. They will provide limited backward compatibility. - -

-

New! Policy Groups

-

We want to make it easy for you to declare security policy as it - applies to IPsec connections.

-

Policy Groups make it simple to say:

- -

FreeS/WAN then implements these policies, creating OE connections if - and when needed. You can use Policy Groups along with connections you - explicitly define in ipsec.conf.

-

For more information, see our Policy - Group HOWTO.

-

New! Packetdefault Connection

-

Free/SWAN 2.x ships with the automatically enabled, hidden - connection packetdefault. This configures a - FreeS/WAN box as an OE gateway for any hosts located behind it. As - mentioned above, you must configure some DNS - records for OE to work.

-

As the name implies, this connection functions as a default. If you - have more specific connections, such as policy groups which configure - your FreeS/WAN box as an OE gateway for a local subnet, these will - apply before packetdefault. You can view packetdefault -'s specifics in man ipsec.conf -.

-

FreeS/WAN now disables Reverse Path Filtering

-

FreeS/WAN often doesn't work with reverse path filtering. At start - time, FreeS/WAN now turns rp_filter off, and logs a warning.

-

FreeS/WAN does not turn it back on again. You can do this yourself - with a command like:

-
   echo 1 > /proc/sys/net/ipv4/conf/eth0/rp_filter
-

For eth0, substitute the interface which FreeS/WAN was affecting.

- -

Revised ipsec.conf

-

No promise of compatibility

-

The FreeS/WAN team promised config-file compatibility throughout the - 1.x series. That means a 1.5 config file can be directly imported into - a fresh 1.99 install with no problems.

-

With FreeS/WAN 2.x, we've given ourselves permission to make the - config file easier to use. The cost: some FreeS/WAN 1.x configurations - will not work properly. Many of the new features are, however, backward - compatible.

-

Most ipsec.conf files will work fine

-

... so long as you paste this line, with no preceding - whitespace, at the top of your config file:

-
    version 2
-

Backward compatibility patch

-

If the new defaults bite you, use this - ipsec.conf fragment to simulate the old default values.

-

Details

-

We've obsoleted various directives which almost no one was using:

-
    dump
-    plutobackgroundload
-    no_eroute_pass
-    lifetime
-    rekeystart
-    rekeytries
-

For most of these, there is some other way to elicit the desired - behaviour. See - this post.

-

We've made some settings, which almost everyone was using, defaults. - For example:

-
    interfaces=%defaultroute
-    plutoload=%search
-    plutostart=%search
-    uniqueids=yes
-

We've also changed some default values to help with OE and Policy - Groups:

-
    authby=rsasig   ## not secret!!!
-    leftrsasigkey=%dnsondemand ## looks up missing keys in DNS when needed.
-    rightrsasigkey=%dnsondemand
-

Of course, you can still override any defaults by explictly - declaring something else in your connection.

-

- A post with a list of many ipsec.conf changes. -
Current ipsec.conf manual. -

- -

Upgrading from 1.x RPMs to 2.x RPMs

-

Note: When upgrading from 1-series to 2-series RPMs, rpm -U - will not work.

-

You must instead erase the 1.x RPMs, then install the 2.x set:

-
    rpm -e freeswan
-
    rpm -e freeswan-module
-

On erasing, your old ipsec.conf should be moved to - ipsec.conf.rpmsave. Keep this. You will probably want to copy - your existing connections to the end of your new 2.x file.

-

Install the RPMs suitable for your kernel version, such as:

-
    rpm -ivh freeswan-module-2.04_2.4.20_20.9-0.i386.rpm
-
    rpm -ivh freeswan-userland-2.04_2.4.20_20.9-0.i386.rpm
-

Or, to splice the files:

-
    cat /etc/ipsec.conf /etc/ipsec.conf.rpmsave > /etc/ipsec.conf.tmp
-    mv /etc/ipsec.conf.tmp /etc/ipsec.conf
-

Then, remove the redundant conn %default and config - setup sections. Unless you have done any special configuring - here, you'll likely want to remove the 1.x versions. Remove conn - OEself, if present.

-
-

Quickstart Guide to Opportunistic Encryption -

- -

Purpose

-

This page will get you started using Linux FreeS/WAN with - opportunistic encryption (OE). OE enables you to set up IPsec tunnels - without co-ordinating with another site administrator, and without hand - configuring each tunnel. If enough sites support OE, a "FAX effect" - occurs, and many of us can communicate without eavesdroppers.

-

OE "flag day"

-

As of FreeS/WAN 2.01, OE uses DNS TXT resource records (RRs) only - (rather than TXT with KEY). This change causes a - "flag day". Users of FreeS/WAN 2.00 (or earlier) OE who are - upgrading may require additional resource records, as detailed in our - upgrading document. OE setup instructions here are for 2.02 or - later.

-

Requirements

-

To set up opportunistic encryption, you will need:

- -

Note: Currently, only Linux FreeS/WAN supports opportunistic - encryption.

-

RPM install

-

Our instructions are for a recent Red Hat with a 2.4-series stock or - Red Hat updated kernel. For other ways to install, see our - install document.

-

Download RPMs

-

If we have prebuilt RPMs for your Red Hat system, this command will - get them:

-
    ncftpget ftp://ftp.xs4all.nl/pub/crypto/freeswan/binaries/RedHat-RPMs/`uname -r | tr -d 'a-wy-z'`/\*
-

If that fails, you will need to try another - install method. Our kernel modules will only work on the Red Hat - kernel they were built for, since they are very sensitive to small - changes in the kernel.

-

If it succeeds, you will have userland tools, a kernel module, and an - RPM signing key:

-
    freeswan-module-2.04_2.4.20_20.9-0.i386.rpm
-    freeswan-userland-2.04_2.4.20_20.9-0.i386.rpm
-    freeswan-rpmsign.asc
-

Check signatures

-

If you're running RedHat 8.x or later, import the RPM signing key - into the RPM database:

-
    rpm --import freeswan-rpmsign.asc
-

For RedHat 7.x systems, you'll need to add it to your - PGP keyring:

-
    pgp -ka freeswan-rpmsign.asc
-

Check the digital signatures on both RPMs using:

-
    rpm --checksig freeswan*.rpm
-

You should see that these signatures are good:

-
    freeswan-module-2.04_2.4.20_20.9-0.i386.rpm: pgp md5 OK
-    freeswan-userland-2.04_2.4.20_20.9-0.i386.rpm: pgp md5 OK
-

Install the RPMs

-

Become root:

-
    su
-

Install your RPMs with:

-

-
    rpm -ivh freeswan*.rpm
-

If you're upgrading from FreeS/WAN 1.x RPMs, and have problems with - that command, see this note.

-

Then, start FreeS/WAN:

-
    service ipsec start
-

Test

-

To check that you have a successful install, run:

-
    ipsec verify
-

You should see as part of the verify output:

-
-    Checking your system to see if IPsec got installed and started correctly
-    Version check and ipsec on-path                             [OK]
-    Checking for KLIPS support in kernel                        [OK]
-    Checking for RSA private key (/etc/ipsec.secrets)           [OK]
-    Checking that pluto is running                              [OK]
-    ...
-

If any of these first four checks fails, see our - troubleshooting guide.

-

Our Opportunistic Setups

-

Full or partial opportunism?

-

Determine the best form of opportunism your system can support.

- -

Initiate-only setup

-

Restrictions

-

When you set up initiate-only Opportunistic Encryption (iOE):

- -

You cannot network a group of initiator-only machines if none of - these is capable of responding to OE. If one is capable of responding, - you may be able to create a hub topology using routing.

-

Create and publish a forward DNS record

-

Find a domain you can use

-

Find a DNS forward domain (e.g. example.com) where you can publish - your key. You'll need access to the DNS zone files for that domain. - This is common for a domain you own. Some free DNS providers, such as - this one, also provide this service.

-

Dynamic IP users take note: the domain where you place your key need - not be associated with the IP address for your system, or even with - your system's usual hostname.

-

Choose your ID

-

Choose a name within that domain which you will use to identify your - machine. It's convenient if this can be the same as your hostname:

-
    [root@xy root]# hostname --fqdn
-    xy.example.com
-

This name in FQDN (fully-qualified domain name) format will be your - ID, for DNS key lookup and IPsec negotiation.

-

Create a forward TXT record

-

Generate a forward TXT record containing your system's public key - with a command like:

-
    ipsec showhostkey --txt @xy.example.com
-

using your chosen ID in place of xy.example.com. This command takes - the contents of /etc/ipsec.secrets and reformats it into something - usable by ISC's BIND. The result should look like this (with the key - data trimmed down for clarity):

-
-    ; RSA 2192 bits   xy.example.com   Thu Jan  2 12:41:44 2003
-        IN      TXT     "X-IPsec-Server(10)=@xy.example.com" 
-    "AQOF8tZ2... ...+buFuFn/"
-
-

Publish the forward TXT record

-

Insert the record into DNS, or have a system adminstrator do it for - you. It may take up to 48 hours for the record to propagate, but it's - usually much quicker.

-

Test that your key has been published

-

Check your DNS work

-
    ipsec verify --host xy.example.com
-

As part of the verify output, you ought to see something - like:

-
    ...
-    Looking for TXT in forward map: xy.example.com          [OK]
-    ...
-

For this type of opportunism, only the forward test is relevant; you - can ignore the tests designed to find reverse records.

-

Configure, if necessary

-

If your ID is the same as your hostname, you're ready to go. - FreeS/WAN will use its built-in connections - to create your iOE functionality.

-

If you have chosen a different ID, you must tell FreeS/WAN about it - via ipsec.conf:

-
    config setup
-        myid=@myname.freedns.example.com
-

and restart FreeS/WAN:

-
    service ipsec restart
-

The new ID will be applied to the built-in connections.

-

Note: you can create more complex iOE configurations as explained in - our policy groups document, or disable OE - using these instructions.

-

Test

-

That's it! Test your connections.

- -

Full Opportunism

-

Full opportunism allows you to initiate and receive opportunistic - connections on your machine.

- -

Put a TXT record in a Forward Domain

-

To set up full opportunism, first set up a - forward TXT record as for initiator-only OE -, using an ID (for example, your hostname) that resolves to your IP. Do - not configure /etc/ipsec.conf, but continue with the - instructions for full opportunism, below.

-

Note that this forward record is not currently necessary for full OE, - but will facilitate future features.

- -

Put a TXT record in Reverse DNS

-

You must be able to publish your DNS RR directly in the reverse - domain. FreeS/WAN will not follow a PTR which appears in the reverse, - since a second lookup at connection start time is too costly.

-

Create a Reverse DNS TXT record

-

This record serves to publicize your FreeS/WAN public key. In - addition, it lets others know that this machine can receive - opportunistic connections, and asserts that the machine is authorized - to encrypt on its own behalf.

-

Use the command:

-
    ipsec showhostkey --txt 192.0.2.11
-

where you replace 192.0.2.11 with your public IP.

-

The record (with key shortened) looks like:

-
    ; RSA 2048 bits  xy.example.com   Sat Apr 15 13:53:22 2000
-    IN TXT  "X-IPsec-Server(10)=192.0.2.11" " AQOF8tZ2...+buFuFn/"
-

Publish your TXT record

-

Send these records to your ISP, to be published in your IP's reverse - map. It may take up to 48 hours for these to propagate, but usually - takes much less time.

-

Test your DNS record

-

Check your DNS work with

-
    ipsec verify --host xy.example.com
-

As part of the verify output, you ought to see something - like:

-
    ...
-    Looking for TXT in reverse map: 11.2.0.192.in-addr.arpa [OK]
-    ...
-

which indicates that you've passed the reverse-map test.

-

No Configuration Needed

-

FreeS/WAN 2.x ships with full OE enabled, so you don't need to - configure anything. To enable OE out of the box, FreeS/WAN 2.x uses the - policy group private-or-clear, which creates IPsec - connections if possible (using OE if needed), and allows traffic in the - clear otherwise. You can create more complex OE configurations as - described in our policy groups document, or - disable OE using these instructions -.

-

If you've previously configured for initiator-only opportunism, - remove myid= from config setup, so that peer - FreeS/WANs will look up your key by IP. Restart FreeS/WAN so that your - change will take effect, with

-
    service ipsec restart
-

Consider Firewalling

-

If you are running a default install of RedHat 8.x, take note: you - will need to alter your iptables rule setup to allow IPSec traffic - through your firewall. See our firewall - document for sample iptables rules.

-

Test

-

That's it. Now, test your connection.

-

Test

-

Instructions are in the next section.

-

Testing opportunistic connections

-

Be sure IPsec is running. You can see whether it is with:

-
    ipsec setup status
-

If need be, you can restart it with:

-
    service ipsec restart
-

Load a FreeS/WAN test website from the host on which you're running - FreeS/WAN. Note: the feds may be watching these sites. Type one of:

-

-
   links oetest.freeswan.org
-
   links oetest.freeswan.nl
- - -

A positive result looks like this:

-
-   You  seem  to  be  connecting  from:  192.0.2.11 which DNS says is:
-   gateway.example.com
-     _________________________________________________________________
-
-   Status E-route
-   OE    enabled    16    192.139.46.73/32    ->    192.0.2.11/32   =>
-   tun0x2097@192.0.2.11
-   OE    enabled    176    192.139.46.77/32    ->   192.0.2.11/32   =>
-   tun0x208a@192.0.2.11
-
-

If you see this, congratulations! Your OE host or gateway will now - encrypt its own traffic whenever it can. For more OE tests, please see - our testing document. If you have difficulty, - see our OE troubleshooting tips.

-

Now what?

-

Please see our policy groups document - for more ways to set up Opportunistic Encryption.

-

You may also wish to make some pre-configured - connections.

-

Notes

- - -

Troubleshooting OE

-

See the OE troubleshooting hints in our - troubleshooting guide.

- -

Known Issues

-

Please see this list of known - issues with Opportunistic Encryption.

-
-

How to Configure Linux FreeS/WAN with Policy Groups

- -

What are Policy Groups?

-

Policy Groups are an elegant general mechanism to - configure FreeS/WAN. They are useful for many FreeS/WAN users.

-

In previous FreeS/WAN versions, you needed to configure each IPsec - connection explicitly, on both local and remote hosts. This could - become complex.

-

By contrast, Policy Groups allow you to set local IPsec policy for - lists of remote hosts and networks, simply by listing the hosts and - networks which you wish to have special treatment in one of several - Policy Group files. FreeS/WAN then internally creates the connections - needed to implement each policy.

-

In the next section we describe our five Base Policy Groups, which - you can use to configure IPsec in many useful ways. Later, we will show - you how to create an IPsec VPN using one line of configuration for each - remote host or network.

- -

Built-In Security Options

-

FreeS/WAN offers these Base Policy Groups:

-
-
private
-
FreeS/WAN only communicates privately with the listed - CIDR blocks. If needed, FreeS/WAN attempts to create a connection - opportunistically. If this fails, FreeS/WAN blocks communication. - Inbound blocking is assumed to be done by the firewall. FreeS/WAN - offers firewall hooks but no modern firewall rules to help with inbound - blocking.
-
private-or-clear
-
FreeS/WAN prefers private communication with the listed CIDR - blocks. If needed, FreeS/WAN attempts to create a connection - opportunistically. If this fails, FreeS/WAN allows traffic in the - clear.
-
clear-or-private
-
FreeS/WAN communicates cleartext with the listed CIDR blocks, but - also accepts inbound OE connection requests from them. Also known as - passive OE (pOE), this policy may be used to create an - opportunistic responder.
-
clear
-
FreeS/WAN only communicates cleartext with the listed CIDR blocks.
-
block
-
FreeS/WAN blocks traffic to and from and the listed CIDR blocks. - Inbound blocking is assumed to be done by the firewall. FreeS/WAN - offers firewall hooks but no modern firewall rules to help with inbound - blocking. - -
-
- -

Notes:

- -

Using Policy Groups

-

The Base Policy Groups which build IPsec connections rely on - Opportunistic Encryption. To use the following examples, you must first - become OE-capable, as described in our quickstart - guide.

-

Example 1: Using a Base Policy Group

-

Simply place CIDR blocks (names, IPs or IP - ranges) in /etc/ipsec.d/policies/[groupname], and reread the - policy group files.

-

For example, the private-or-clear policy tells FreeS/WAN - to prefer encrypted communication to the listed CIDR blocks. Failing - that, it allows talk in the clear.

-

To make this your default policy, place fullnet - in the private-or-clear policy group file:

-
    [root@xy root]# cat /etc/ipsec.d/policies/private-or-clear
-    # This file defines the set of CIDRs (network/mask-length) to which
-    # communication should be private, if possible, but in the clear otherwise.
-    ....
-    0.0.0.0/0
-

and reload your policies with

-
    ipsec auto --rereadgroups
-

Use this test to verify opportunistic - connections.

- -

Example 2: Defining IPsec Security Policy with - Groups

-

Defining IPsec security policy with Base Policy Groups is like - creating a shopping list: just put CIDR blocks in the appropriate group - files. For example:

-
    [root@xy root]# cd /etc/ipsec.d/policies
-    [root@xy policies]# cat private
-        192.0.2.96/27              # The finance department
-        192.0.2.192/29             # HR
-	192.0.2.12                 # HR gateway
-        irc.private.example.com    # Private IRC server
-  
-    [root@xy policies]# cat private-or-clear
-        0.0.0.0/0                  # My default policy: try to encrypt.
-
-    [root@xy policies]# cat clear
-        192.0.2.18/32              # My POP3 server
-        192.0.2.19/32              # My Web proxy
-
-    [root@xy policies]# cat block
-        spamsource.example.com
-

To make these settings take effect, type:

-
    ipsec auto --rereadgroups
-

Notes:

- - -

Example 3: Creating a Simple IPsec VPN with the - private Group

-

You can create an IPsec VPN between several hosts, with only one line - of configuration per host, using the private policy group.

-

First, use our quickstart guide to set - up each participating host with a FreeS/WAN install and OE.

-

In one host's /etc/ipsec.d/policies/private, list the - peers to which you wish to protect traffic. For example:

-
    [root@xy root]# cd /etc/ipsec.d/policies
-    [root@xy policies]# cat private
-        192.0.2.9              # several hosts at example.com
-        192.0.2.11             
-        192.0.2.12                 
-        irc.private.example.com 
-
-

Copy the private file to each host. Remove the local host, - and add the initial host.

-
    scp2 /etc/ipsec.d/policies/private root@192.0.2.12:/etc/ipsec.d/policies/private
-

On each host, reread the policy groups with

-
    ipsec auto --rereadgroups
-

That's it! You're configured.

-

Test by pinging between two hosts. After a second or two, traffic - should flow, and

-
    ipsec eroute
-

should yield something like

-
    192.0.2.11/32   -> 192.0.2.8/32  => tun0x149f@192.0.2.8
-

where your host IPs are substituted for 192.0.2.11 and 192.0.2.8.

-

If traffic does not flow, there may be an error in your OE setup. - Revisit our quickstart guide.

-

Our next two examples show you how to add subnets to this IPsec VPN.

- -

Example 4: New Policy Groups to Protect a Subnet

-

To protect traffic to a subnet behind your FreeS/WAN gateway, you'll - need additional DNS records, and new policy groups. To set up the DNS, - see our quickstart guide. To create five new - policy groups for your subnet, copy these connections to - /etc/ipsec.conf. Substitute your subnet's IPs for 192.0.2.128/29.

-
-conn private-net
-    also=private  # inherits settings (eg. auto=start) from built in conn
-    leftsubnet=192.0.2.128/29  # your subnet's IPs here
-
-conn private-or-clear-net
-    also=private-or-clear
-    leftsubnet=192.0.2.128/29
-
-conn clear-or-private-net
-    also=clear-or-private
-    leftsubnet=192.0.2.128/29
-
-conn clear-net
-    also=clear
-    leftsubnet=192.0.2.128/29
-
-conn block-net
-    also=block
-    leftsubnet=192.0.2.128/29
-
-

Copy the gateway's files to serve as the initial policy group files - for the new groups:

-
-    cp -p /etc/ipsec.d/policies/private /etc/ipsec.d/policies/private-net
-    cp -p /etc/ipsec.d/policies/private-or-clear /etc/ipsec.d/policies/private-or-clear-net
-    cp -p /etc/ipsec.d/policies/clear-or-private /etc/ipsec.d/policies/clear-or-private-net
-    cp -p /etc/ipsec.d/policies/clear /etc/ipsec.d/policies/clear-net
-    cp -p /etc/ipsec.d/policies/block /etc/ipsec.d/policies/block
-
-

Tip: Since a missing policy group file is equivalent to a - file with no entries, you need only create files for the connections - you'll use.

-

To test one of your new groups, place the fullnet 0.0.0.0/0 in - private-or-clear-net. Perform the subnet test in - our quickstart guide. You should see a connection, and

-
    ipsec eroute
-

should include an entry which mentions the subnet node's IP and the - OE test site IP, like this:

-
    192.0.2.131/32   -> 192.139.46.77/32  => tun0x149f@192.0.2.11
- -

Example 5: Adding a Subnet to the VPN

-

Suppose you wish to secure traffic to a subnet 192.0.2.192/29 behind - a FreeS/WAN box 192.0.2.12.

-

First, add DNS entries to configure 192.0.2.12 as an opportunistic - gateway for that subnet. Instructions are in our - quickstart guide. Next, create a private-net group on - 192.0.2.12 as described in Example 4.

-

On each other host, add the subnet 192.0.2.192/29 to private -, yielding for example

-
    [root@xy root]# cd /etc/ipsec.d/policies
-    [root@xy policies]# cat private
-        192.0.2.9              # several hosts at example.com
-        192.0.2.11
-        192.0.2.12             # HR department gateway
-        192.0.2.192/29         # HR subnet
-        irc.private.example.com
-
-

and reread policy groups with

-
    ipsec auto --rereadgroups
-

That's all the configuration you need.

-

Test your VPN by pinging from a machine on 192.0.2.192/29 to any - other host:

-
    [root@192.0.2.194]# ping 192.0.2.11
-

After a second or two, traffic should flow, and

-
    ipsec eroute
-

should yield something like

-
    192.0.2.11/32   -> 192.0.2.194/32  => tun0x149f@192.0.2.12
-
-

Key:

- - - - - -
1.192.0.2.11/32Local start point of the - protected traffic.
2.192.0.2.194/32Remote end point of the - protected traffic.
3.192.0.2.12Remote FreeS/WAN node (gateway or - host). May be the same as (2).
4.[not shown]Local FreeS/WAN node (gateway or - host), where you've produced the output. May be the same as (1).
-

For additional assurance, you can verify with a packet sniffer that - the traffic is being encrypted.

-

Note

- -

Appendix

- -

Our Hidden Connections

-

Our Base Policy Groups are created using hidden connections. These - are spelled out in man ipsec.conf - and defined in /usr/local/lib/ipsec/_confread.

- -

Custom Policy Groups

-

A policy group is built using a special connection description in - ipsec.conf, which:

- -

To create a new group:

-
    -
  1. Create its connection definition in ipsec.conf.
    2. -
  2. Create a Policy Group file in /etc/ipsec.d/policies with - the same name as your connection.
    3. -
  3. Put a CIDR block in that file.
    4. -
  4. Reread groups with ipsec auto --rereadgroups.
    5. -
  5. Test: ping to activate any OE connection, and view - results with ipsec eroute.
    6. -
- -

Disabling Opportunistic Encryption

-

To disable OE (eg. policy groups and packetdefault), cut and paste - the following lines to /etc/ipsec.conf:

-
conn block
-    auto=ignore
-
-conn private
-    auto=ignore
-
-conn private-or-clear
-    auto=ignore
-
-conn clear-or-private
-    auto=ignore
-
-conn clear
-    auto=ignore
-
-conn packetdefault
-    auto=ignore
-

Restart FreeS/WAN so that the changes take effect:

-
    ipsec setup restart
-
-

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.

-
-

Index of FAQ questions

- -
-

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.

-

To start setting it up, go to our - quickstart guide.

-

Our web links document has information on - IPsec for other systems.

-

How do I report a problem or seek help?

-
-
Read our troubleshooting document.
-
-

It may guide you to a solution. If not, see its - problem reporting section.

-

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 users 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.
    • -
  • It is more likely to get a quick response. Developers may get behind - on email, or even ignore it entirely for a while, but a list message - (given a reasonable Subject: line) is certain to be read by a fair - number of people within hours.
    • -
  • It may also be important because of 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.
    • -
-
-
Try irc.freenode.net#freeswan.
-
-

FreeS/WAN developers, volunteers and users can often be found there. - Be patient and be prepared to provide lots of information to support - your question.

-

If your question was really interesting, and you found an answer, - please share that with the class by posting to the - users mailing list. That way others with the same problem can find - your answer in the archives.

-
-
Premium support is also available.
-
-

See the next several questions.

-
-
-

Can I get ...

-

Can I get an off-the-shelf system that includes - FreeS/WAN?

-

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. Then consider hiring a consultant (see next question) to - help define your requirements.

-

Can I hire consultants or staff who know - FreeS/WAN?

-

If you want the help of a contractor, or to hire staff with FreeS/WAN - expertise, you could:

- -

For companies offerring support, see the next question.

-

Can I get commercial support?

-

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.

-

Release questions

-

What is the current release?

-

The current release is the highest-numbered tarball on our - distribution site. Almost always, any of the - mirrors will have the same file, though perhaps not for a day or so - after a release.

-

Unfortunately, the web site is not always updated as quickly as it - should be.

-

When is the next release?

-

We try to do a release approximately every six to eight weeks.

-

If pre-release tests fail and the fix appears complex, or more - generally if the code does not appear stable when a release is - scheduled, we will just skip that release.

-

For serious bugs, we may bring out an extra bug-fix release. These - get numbers in the normal release series. For example, there was a bug - found in FreeS/WAN 1.6, so we did another release less than two weeks - later. The bug-fix release was called 1.7.

-

Are there known bugs in the current release?

-

Any problems we are aware of at the time of a release are documented - in the BUGS file for that release. You should - also look at the CHANGES file.

-

Bugs discovered after a release are discussed on the - mailing lists. The easiest way to check for any problems in the - current code would be to peruse the - List In Brief.

-

Modifications and contributions

-

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.

-

Before investing much energy in any such project, we suggest that you

- -

This may prevent duplicated effort, or lead to interesting - collaborations.

-

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.

-

Discussion of possible contributions takes place on the - design mailing list.

-

Is there detailed design documentation?

- There are: - -

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.

-

Will FreeS/WAN work in my environment?

-

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 - interoperation document devoted to this problem.

-

An important part of that document is links to the many - user-written HowTos on interoperation between FreeS/WAN and various - other implementations. Often the users know more than the developers - about these issues (and almost always more than me :-), so these - documents may be your best resource.

-

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 a few cases, there are some complications. See our - interoperation document for details.

-

Is there a limit on throughput?

-

There is no hard limit, but see below.

-

Is there a limit on number of tunnels?

-

There is no hard limit, but see next question.

-

Is a ... fast enough to handle FreeS/WAN with my - loads?

-

A quick summary:

-
-
Even a limited machine can be useful
-
A 486 can handle a T1, ADSL or cable link, though the machine may be - breathing hard.
-
A mid-range PC (say 800 MHz with good network cards) can do a lot of - IPsec
-
With up to roughly 50 tunnels and aggregate bandwidth of 20 Megabits - per second, it willl have cycles left over for other tasks.
-
There are limits
-
Even a high end CPU will not come close to handling a fully loaded - 100 Mbit/second Ethernet link. -

Beyond about 50 tunnels it needs careful management.

-
-
-

See our FreeS/WAN performance document - for details.

-

Will FreeS/WAN work on ... ?

-

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

-

Will FreeS/WAN run on non-Intel CPUs?

-

FreeS/WAN is intended to run on all CPUs Linux supports -. 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.

-

Will FreeS/WAN run on multiprocessors?

-

FreeS/WAN is designed to work on any SMP architecture Linux supports, - and has been tested successfully on at least dual processor Intel - architecture machines. Details are in our - compatibility document.

-

Will FreeS/WAN work on an older kernel?

-

It might, but we strongly recommend using a recent 2.2 or 2.4 series - kernel. Sometimes the newer versions include security fixes which can - be quite important on a gateway.

-

Also, we use recent kernels for development and testing, so those are - better tested and, if you do encounter a problem, more easily - supported. If something breaks applying recent FreeS/WAN patches to an - older kernel, then "update your kernel" is almost certain to be the - first thing we suggest. It may be the only suggestion we have.

-

The precise kernel versions supported by a particular FreeS/WAN - release are given in the README file of that release.

-

See the following question for more on kernels.

-

Will FreeS/WAN run on the latest kernel - version?

-

Sometimes yes, but quite often, no.

-

Kernel versions supported are given in the README - file of each FreeS/WAN release. Typically, they are 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 -). Often FreeS/WAN will work on slightly later kernels as well, but of - course this cannot be guaranteed.

-

For example, FreeS/WAN 1.91 was released for kernels 2.2.19 or 2.4.5, - the current kernels at the time. It also worked on 2.4.6, 2.4.7 and - 2.4.8, but 2.4.9 had changes that caused compilation errors if it was - patched with FreeS/WAN 1.91.

-

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:

- -

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

-

Will FreeS/WAN work on unusual network - hardware?

-

IPsec is designed to work over any network that IP works over, and - FreeS/WAN is intended to work over any network interface hardware that - Linux supports.

-

If you have working IP on some unusual interface -- perhaps Arcnet, - Token Ring, ATM or Gigabit Ethernet -- then IPsec should "just work".

-

That said, practice is sometimes less tractable than theory. Our - testing is done almost entirely on:

- -

If you have some other interface, especially an uncommon one, it is - entirely possible you will get bitten either by a FreeS/WAN bug which - our testing did not turn up, or by a bug in the driver that shows up - only with our loads.

-

If IP works on your interface and FreeS/WAN doesn't, seek help on the mailing lists.

-

Another FAQ section describes MTU problems -. These are a possibility for some interfaces.

-

Will FreeS/WAN work on a VLAN (802.1q) network?

-

Yes, FreeSwan works fine, though some network drivers have problems - with jumbo sized ethernet frames. If you used interfaces=%defaultroute - you do not need to change anything, but if you specified an interface - (eg eth0) then remember you must change that to reflect the VLAN - interface (eg eth0.2 for VLAN ID 2).

-

The "eepro100" module is known to be broken, use the e100 driver for - those cards instead (included in 2.4 as 'alternative driver' for the - Intel EtherExpressPro/100.

-

You do not need to change any MTU setting (those are workarounds - that are only needed for buggy drivers)

-

This FAQ contributed by Paul Wouters.

-

Does FreeS/WAN support ...

-

For a discussion of which parts of the IPsec specifications FreeS/WAN - does and does not implement, see our compatibility - document.

-

For information on some often-requested features, see below.

-

Does FreeS/WAN support site-to-site VPN ( -Virtual Private Network) applications?

-

Absolutely. See this FreeS/WAN-FreeS/WAN - configuration example. If only one site is using FreeS/WAN, there - may be a relevant HOWTO on our interop page.

-

Does FreeS/WAN support remote users connecting - to a LAN?

-

Yes. We call the remote users "Road Warriors". Check out our - FreeS/WAN-FreeS/WAN Road Warrior Configuration - Example.

-

If your Road Warrior is a Windows or Mac PC, you may need to install - an IPsec implementation on that machine. Our - interop page lists many available brands, and features links to - several HOWTOs.

-

Does FreeS/WAN support remote users - using shared secret authentication?

-

Yes, but there are severe restrictions, so - we strongly recommend using RSA - keys for - authentication instead.

-

See this FAQ question.

-

Does FreeS/WAN support wireless networks?

-

Yes, it is a common practice to use IPsec over wireless networks - because their built-in encryption, WEP, is insecure.

-

There is some discussion in our - advanced configuration document. See also the - WaveSEC site.

-

Does FreeS/WAN support X.509 or other PKI - certificates?

-

Vanilla FreeS/WAN does not support X.509, but Andreas Steffen and - others have provided a popular, well-supported X.509 patch.

- -

Linux FreeS/WAN features Opportunistic - Encryption, an alternative Public Key Infrastructure based on - Secure DNS.

-

Does FreeS/WAN support user authentication (Radius, - SecureID, Smart Card...)?

-

Andreas Steffen's X.509 - patch (v. 1.42+) supports Smart Cards. The patch does not ship with - vanilla FreeS/WAN, but will be incorporated into - Super FreeS/WAN 2.01+. The patch implements the PCKS#15 - Cryptographic Token Information Format Standard, using the OpenSC - smartcard library functions.

-

Older news:

-

A user-supported patch to FreeS/WAN 1.3, for smart card style - authentication, is available on - Bastiaan's site. It supports skeyid and ibutton. This patch is not - part of Super FreeS/WAN.

-

For a while progress on this front was impeded by a lack of standard. - The IETF - working group has now nearly completed its recommended solution to - the problem; meanwhile several vendors have implemented various things.

- - -

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 either of those is trustworthy, it is not clear that you need user - authentication in IPsec.

-

Does FreeS/WAN support NAT traversal?

-

Vanilla FreeS/WAN does not, but thanks to Mathieu Lafon and Arkoon - Network Security, there's a patch to support this.

- -

The NAT traversal patch has some issues with PSKs, so you may wish to - authenticate with RSA keys, or X.509 (requires a patch which is also - included in Super FreeS/WAN). Doing the latter also has advantages when - dealing with large numbers of clients who may be behind NAT; instead of - having to make an individual Roadwarrior connection for each virtual - IP, you can use the "rightsubnetwithin" parameter to specify a range. - See - these rightsubnetwithin instructions.

-

Does FreeS/WAN support assigning a "virtual - identity" to a remote system?

-

Some IPsec implementations allow you to make the source address on - packets sent by a Road Warrior machine be something other than the - address of its interface to the Internet. This is sometimes described - as assigning a virtual identity to that machine.

-

FreeS/WAN does not directly support this, but it can be done. See - this FAQ question.

-

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.

-

Does FreeS/WAN support AES encryption?

-

AES is a new US government block - cipher standard to replace the obsolete DES.

-

At time of writing (March 2002), the FreeS/WAN distribution does not - yet support AES but user-written patches are - available to add it. Our kernel programmer is working on integrating - those patches into the distribution, and there is active discussion of - this on the design mailimg list.

-

Does FreeS/WAN support other encryption - algorithms?

-

Currently triple DES is the only cipher - supported. AES will almost certainly be added (see previous question), - and it is likely that in the process we will also add the other two AES - finalists with open licensing, Twofish and Serpent.

-

We are extremely reluctant to add other ciphers. This would make both - use and maintenance of FreeS/WAN more complex without providing any - clear benefit. Complexity is emphatically not desirable in a security - product.

-

Various users have written patches to add other ciphers. We provide - links to these.

-

Can I ...

-

Can I use policy groups along with - explicitly configured connections?

-

Yes, you can, so long as you pay attention to the selection rule, - which can be summarized "the most specific connection wins". We - describe the rule in our policy groups - document, and provide a more technical explanation in - man ipsec.conf.

-

A good guideline: If you have a regular connection defined in - ipsec.conf, ensure that a subset of that connection is not listed - in a less restrictive policy group. Otherwise, FreeS/WAN will use the - subset, with its more specific source/destination pair.

-

Here's an example. Suppose you are the system administrator at - 192.0.2.2. You have this connection in ipsec.conf: ipsec.conf -:

-
conn net-to-net
-    left=192.0.2.2           # you are here
-    right=192.0.2.8
-    rightsubnet=192.0.2.96/27
-    ....
-
-

If you then place a host or net within rightsubnet, (let's - say 192.0.2.98) in private-or-clear, you may find that - 192.0.2.2 at times communicates in the clear with 192.0.2.98. That's - consistent with the rule, but may be contrary to your expectations.

-

On the other hand, it's safe to put a larger subnet in a less - restrictive policy group file. If private-or-clear contains - 192.0.2.0/24, then the more specific net-to-net connection - is used for any communication to 192.0.2.96/27. The more general policy - applies only to communication with hosts or subnets in 192.0.2.0/24 - without a more specific policy or connection.

-

Can I turn off policy groups?

-

Yes. Use these instructions.

- - -

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 - (a virtual identity)?

-

Often it would be convenient to be able to give a Road Warrior an IP - address which appears to be on the local network. Some IPsec - implementations have support for this, sometimes calling the feature - "virtual identity".

-

Currently (Sept 2002) FreeS/WAN does not support this, and we have no - definite plans to add it. The difficulty is that is not yet a standard - mechanism for it. There is an Internet Draft for a method of doing it - using DHCP which looks promising. FreeS/WAN may - support that in a future release.

-

In the meanwhile, you can do it yourself using the Linux iproute2(8) - facilities. Details are in - this paper.

-

Another method has also been discussed on the mailing list.:

- -

For example, you might have:

-
-
leftsubnet=a.b.c.0/25
-
head office network
-
rightsubnet=a.b.c.129/32
-
extruded to a road warrior. Note that this is not in a.b.c.0/25
-
a.b.c.0/24
-
whole network, including both the above
-
-

You then set up routing so that the office machines use the IPsec - gateway as their route to a.b.c.128/25. The leftsubnet parameter tells - the road warriors to use tunnels to reach a.b.c.0/25, so you should - have two-way communication. Depending or your network and applications, - there may be some additional work to do on DNS or Windows configuration

-

Can I support many road warriors with one - gateway?

-

Yes. This is easily done, using

-
-
either RSA authentication
-
standard in the FreeS/WAN distribution
-
or X.509 certificates
-
requires Super FreeS/WAN or a patch.
-
-

In either case, each Road Warrior must have a different key or - certificate.

-

It is also possible using pre-shared key authentication, though we - don't recommend this; see the next question for - details.

-

If you expect to have more than a few dozen Road Warriors connecting - simultaneously, you may need a fairly powerful gateway machine. See our - document on FreeS/WAN performance.

-

Can I have many road warriors using shared secret - authentication?

-

Yes, but avoid it if possible.

-

You can have multiple Road Warriors using shared secret - authentication only if they all use the same secret. - You must also set:

-

-
   uniqueids=no
-

in the connection definition.

-

Why it's less secure:

- -

This is a designed-in limitation of the IKE key - negotiation protocol, not a problem with our implementation.

-

We very strongly recommend that you avoid using shared secret - authentication for multiple Road Warriors. Use RSA - authentication instead.

-

The longer story: When using shared secrets, the protocol requires - that the responding gateway be able to determine which secret to use at - a time when all it knows about the initiator is an IP address. This - works fine if you know the initiator's address in advance and can use - it to look up the appropiriate secret. However, it fails for Road - Warriors since the gateway cannot know their IP addresses in advance.

-

With RSA signatures (or certificates) the protocol is slightly - different. The initiator provides an identifier early in the exchange - and the responder can use that identifier to look up the correct key or - certificate. See 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 (type of service) information from - the encapsulated packet to the outer header reveals the TOS information - to an eavesdropper. This does not tell him much, but it might be of use - in traffic analysis. Since we do not have to - give it to him, our default is not to.

-

Even with the TOS hidden, you can still:

- -

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:

- -

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, L2TP or PPTP tunnels over IPsec?

-

Yes. Normally this is not necessary, but it is useful in a few - special cases. For example, if you must route non-IP packets such as - IPX, you will need to use a tunneling protocol that can route these - packets. IPsec can be layered around it for extra security. Another - example: you can provide failover protection for high availability (HA) - environments by combining IPsec with other tools. Ken Bantoft describes - one such setup in Using - FreeS/WAN with Linux-HA, GRE, OSPF and BGP for enterprise grade VPN - solutions.

-

GRE over IPsec is covered as part of - that document. - Here are links to other GRE resources. Jacco de Leuw has created - this page on L2TP over IPsec with instructions for FreeS/WAN and - several other brands of IPsec software.

-

Please let us know of other useful links via the - mailing lists.

-

... use Network Neighborhood (Samba, NetBIOS) over - IPsec?

-

Your local PC needs to know how to translate NetBIOS names to IP - addresses. It may do this either via a local LMHOSTS file, or using a - local or remote WINS server. The WINS server is preferable since it - provides a centralized source of the information to the entire network. - To use a WINS server over the VPN (or any IP-based - network), you must enable "NetBIOS over TCP".

-

Samba can emulate a WINS server on - Linux.

-

See also several discussions in our - September 2002 Users archives

-

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:

- -

However, we also list some of the commonest problems here.

-

I cannot ping ....

-

This question is dealt with in the advanced 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 = 192.0.2.8
-             |
-
-       ~ internet ~
-
-             |
-      eth0 = 192.0.2.11
-         gate2
-      eth1 = x.y.z.1
-              |
-       subnet x.y.z.0/24
-

and the connection description:

-
conn abc-xyz
-     left=192.0.2.8
-     leftsubnet=a.b.c.0/24
-     right=192.0.2.11
-     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:

- -

In some cases, you may be able to get around this. For the example - network above, you could use:

-
        ping -I a.b.c.1 x.y.z.1
-

Both the adresses given are within protected subnets, so this should - go through the tunnel.

-

If required, you can build additional tunnels so that all the - machines involved can talk to all the others. See - multiple tunnels in the advanced 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:

- -

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:

- -

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

- -

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

-

Some advice from technical lead Henry Spencer on diagnosing such - problems:

-
> > Packets vanishing between the hardware interface and the ipsecN interface
-> > is usually the result of firewalls not being configured to let them in...
-> 
-> Thanks for the suggestion. If only it were that simple! My ipchains startup
-> script does take care of that, but just in case I manually inserted rules 
-> accepting everything from london on dublin. No difference.
-
-The other thing to check is whether the "RX packets dropped" count on the
-ipsecN interface (run "ifconfig ipsecN", for N=1 or whatever, to see the
-counts) is rising.  If so, then there's some sort of configuration mismatch
-between the two ends, and IPsec itself is rejecting them.  If none of the
-ipsecN counts is rising, then the packets are never reaching the IPsec
-machinery, and the problem is almost certainly in firewalls etc.
-

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

-

Disappearing %defaultroute

-

When an underlying connection (eg. ppp) goes down, FreeS/WAN will not - recover properly without a little help. Here are the symptoms that - FreeS/WAN user Michael Carmody noticed:

-
-> After about 24 hours the freeswan connection takes over the default route.
-> 
-> i.e instead of deafult gateway pointing to the router via eth0, it becomes a 
-> pointer to the router via ipsec0.
- 
-> All internet access is then lost as all replies (and not just the link I 
-> wanted) are routed out ipsec0 and the router doesn't respond to the ipsec 
-> traffic.
-
-

If you're using a FreeS/WAN 2.x/KLIPS system, simply re-attach the - IPsec virtual interface with ipsec tnconfig command such as:

-
    ipsec tnconfig --attach --virtual ipsec0 --physical ppp0
-

In your command, name the physical and virtual interfaces as they - appear paired on your system during regular uptime. For a system with - several physical/virtual interface pairs on flaky links, you'll need - more than one such command. If you're using FreeS/WAN 1.x, you must - restart FreeS/WAN, which is more time consuming.

-

- Here is a script which can help to automate the process of - FreeS/WAN restart at need. It could easily be adapted to use tnconfig - instead.

-

TCPdump on the gateway shows strange things -

- As another user pointed out, keeping the connect -

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.

-

See our testing document for more detail.

-

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:

- -

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:

- -

One manual connection works, but second one - fails

-

This is a 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 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:

- -

IPsec works, but connections using compression fail -

-

When we first added compression, we saw some problems:

- -

We have not seen either problem in some time (at least six months as - I write in March 2002), but if you have some unusual configuration then - you may see them.

-

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 packet - fragmentation and perhaps path MTU discovery.

-

Our troubleshooting document covers these - problems. Information on the underlying mechanism is in our - background document.

-

Subnet-to-subnet works, but tests from the gateways - don't

-

This is described under I cannot ping... - above.

-

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

Interpreting error messages

-

route-client (or host) exited with status 7 -

-

Here is a discussion of this error from FreeS/WAN "listress" (mailing - list tech support person) Claudia Schmeing. The "FAQ on the network - unreachable error" which she refers to is the next question below.

-
> I reached the point where the two boxes (both on dial-up connections, but
-> treated as static IPs by getting the IP and editing ipsec.conf after the
-> connection is established) to the point where they exchange some info, but I
-> get an error like "route-client command exited with status 7 \n internal
-> error".
-> Where can I find a description of this error?
-
-In general, if the FAQ doesn't cover it, you can search the mailing list 
-archives - I like to use
-http://www.sandelman.ottawa.on.ca/linux-ipsec/
-but you can see doc/mail.html for different archive formats.
-
-
-Your error comes from the _updown script, which performs some
-routing and firewall functions to help Linux FreeS/WAN. More info
-is available at doc/firewall.html and man ipsec.conf. Its routing
-is integral to the health of Linux FreeS/WAN; it also provides facility
-to insert custom firewall rules to be executed when you create or destroy
-a connection.
-
-Yours is, of course, a routing error. You can be fairly sure the routing 
-machinery is saying "network is unreachable". There's a FAQ on the 
-"network is unreachable" error, but more information is available now; read on.
-
-If your _updown script is recent (for example if it shipped with 
-Linux FreeS/WAN 1.91), you will see another debugging line in your logs 
-that looks something like this:
-
-> output: /usr/local/lib/ipsec/_updown: `route add -net 128.174.253.83 
-> netmask 255.255.255.255 dev ipsec0 gw 66.92.93.161' failed
-
-This is, of course, the system route command that exited with status 7, 
-(ie. failed). Man route for details. Seeing the command typed out yields 
-more information. If your _updown script is older, you may wish to update 
-it to show the command explicitly.
-
-Three parameters fed to the route command: net, netmask and gw [gateway] 
-are derived from things you've put in ipsec.conf.
-
-Net and netmask are derived from the peer's IP and mask. In more detail:
-
-You may see a routing error when routing to a client (ie. subnet), or 
-to a host (IPSec gateway or freestanding host; a box that does IPSec for
-itself). In _updown, the "route-client" section  is responsible to set up 
-the route for IPSec'd (usually, read 'tunneled') packets headed to a 
-peer subnet. Similarly, route-host routes IPSec'd packets to a peer host
-or IPSec gateway.
-
-When routing to a 'client', net and netmask are ipsec.conf's left- or 
-rightsubnet (whichever is not local). Similarly, when routing to a 
-'host' the net is left or right. Host netmask is always /32, indicating a 
-single machine.
-
-Gw is nexthop's value. Again, the value in question is left- or rightnexthop,
-whichever is local. Where left/right or left-/rightnexthop has the special 
-value %defaultroute (described in man ipsec.conf), gw will automagically get
-the value of the next hop on the default route.
-
-Q: "What's a nexthop and why do I need one?"
-
-A: 'nexthop' is a routing kluge; its value is the next hop away
-   from the machine that's doing IPSec, and toward your IPSec peer. 
-   You need it to get the processed packets out of the local system and 
-   onto the wire. While we often route other packets through the machine 
-   that's now doing IPSec, and are done with it, this does not suffice here. 
-   After packets are processed with IPSec, this machine needs to know where 
-   they go next. Of course using the 'IPSec gateway' as their routing gateway 
-   would cause an infinite loop! [To visualize this, see the packet flow 
-   diagram at doc/firewall.html.] To avoid this, we route packets through 
-   the next hop down their projected path.
-
-Now that you know the background, consider:
-1. Did you test routing between the gateways in the absence of Linux
-   FreeS/WAN, as recommended? You need to ensure the two machines that
-   will be running Linux FreeS/WAN can route to one another before trying to 
-   make a secure connection.
-2. Is there anything obviously wrong with the sense of your route command?
-
-Normally, this problem is caused by an incorrect local nexthop parameter.
-Check out the use of %defaultroute, described in man ipsec.conf. This is
-a simple way to set nexthop for most people. To figure nexthop out by hand,
-traceroute in-the-clear to your IPSec peer. Nexthop is the traceroute's 
-first hop after your IPSec gateway.
-

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

-

See also the FAQ question route-client (or - host) exited with status 7.

-

ipsec_setup: modprobe: Can't locate module ipsec -

-

ipsec_setup: Fatal error, kernel appears to lack - KLIPS

-

These messages indicate an installation failure. The kernel you are - running does not contain the KLIPS (kernel IPsec) - code.

-

Note that the "modprobe: Can't locate module ipsec" message appears - even if you are not using modules. If there is no KLIPS in your kernel, - FreeS/WAN tries to load it as a module. If that fails, you get this - message.

-

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.

-

Message numbers (MI3, QR1, et cetera) in Pluto - messages

-

Pluto messages often indicate where Pluto is in the IKE protocols. - The letters indicate Main mode or Q -uick mode and Initiator or Responder. - The numerals are message sequence numbers. For more detail, see our - IPsec section.

-

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

-

Older versions of FreeS/WAN used this message. The same error now - gives the "we have no ipsecN ..." error described just below.

-

... we have no ipsecN interface for either - end of this connection

-

Your tunnel has no IP address which matches the IP address of any of - the available IPsec interfaces. Either you've misconfigured the - connection, or you need to define an appropriate IPsec interface - connection. interfaces=%defaultroute works in many cases.

-

A longer story: 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:

- -

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:

- -

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

rsasigkey dumps core

- A comment on this error from Henry: -
On Fri, 29 Jun 2001, Rodrigo Gruppelli wrote:
-> ...Well, it seem that there's
-> another problem with it. When I try to generate a pair of RSA keys,
-> rsasigkey cores dump...
-
-*That* is a neon sign flashing "GMP LIBRARY IS BROKEN".  Rsasigkey calls
-GMP a lot, and our own library a little bit, and that's very nearly all it
-does.  Barring bugs in its code or our library -- which have happened, but
-not very often -- a problem in rsasigkey is a problem in GMP.
-

See the next question for how to deal with GMP errors.

-

!Pluto failure!: ... exited with ... signal 4

-

Pluto has died. Signal 4 is SIGILL, illegal instruction.

-

The most likely cause is that your GMP (GNU - multi-precision) library is compiled for a different processor than - what you are running on. Pluto uses that library for its public key - calculations.

-

Try getting the GMP sources and recompile for your processor type. - Most Linux distributions will include this source, or you can download - it from the GMP home page.

-

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

The document she refers to has since been replaced by a - section of the troubleshooting document.

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

The documentation section she refers to is now - here.

-

... trouble writing to /dev/ipsec ... SA already in - use

-

This error message occurs when two manual connections are set up with - the same SPI value.

-

See the FAQ for 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:

- -

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 our discussion - of cleaning up dead tunnels.

-

unknown parameter name "rightcert"

-

This message can appear when you've upgraded an X.509-enabled Linux - FreeS/WAN with a vanilla Linux FreeS/WAN. To use your X.509 configs you - will need to overwrite the new install with - Super FreeS/WAN, or add the - X.509 patch by hand.

-

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.

- -

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:

- -

A number of tools are available to filter mail.

- -

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

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)
-
secrets for IKE authentication, either pre-shared keys or RSA - private keys
-
-

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.

-

The exceptions are commands for mainpulating the RSA - keys used in Pluto authentication:

-
-
ipsec_rsasigkey(8)
-
generate keys
-
ipsec_newhostkey(8)
-
generate keys in a convenient format
-
ipsec_showhostkey(8) -
-
extract RSA keys from - ipsec.secrets(5) (or optionally, another file) and format them for - insertion in ipsec.conf(5) or - in DNS records
-
-

Note that:

- -

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.

-

The firewall code in 2.4 and later kernels is called Netfilter. The - user-space utility to manage a firewall is iptables(8). See the - netfilter/iptables web site for details.

-

Filtering rules for IPsec packets

-

The basic constraint is that an IPsec gateway must have - packet filters that allow IPsec packets, at least when talking - to other IPsec gateways:

- -

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.

-

For nearly all FreeS/WAN applications, you must allow UDP port 500 - and the ESP protocol.

-

There are two ways to set this up:

-
-
easier but less flexible
-
Just set up your firewall scripts at boot time to allow IPsec - packets to and from your gateway. Let FreeS/WAN reject any bogus - packets.
-
more work, giving you more precise control
-
Have the ipsec_pluto(8) - daemon call scripts to adjust firewall rules dynamically as required. - This is done by naming the scripts in the - ipsec.conf(5) variables prepluto=, postpluto= -, leftupdown= and rightupdown=.
-
-

Both methods are described in more detail below.

-

Firewall configuration at boot

-

It is 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

- -

Since Pluto authenticates its partners during the negotiation, and - KLIPS drops packets for which no tunnel has been negotiated, this may - be all you need.

-

A simple set of rules

-

In simple cases, you need only a few rules, as in this example:

-
# allow IPsec
-#
-# IKE negotiations
-iptables -I INPUT  -p udp --sport 500 --dport 500 -j ACCEPT
-iptables -I OUTPUT -p udp --sport 500 --dport 500 -j ACCEPT
-# ESP encryption and authentication
-iptables -I INPUT  -p 50 -j ACCEPT
-iptables -I OUTPUT -p 50 -j ACCEPT
-
-

This should be all you need to allow IPsec through lokkit, - which ships with Red Hat 9, on its medium security setting. Once you've - tweaked to your satisfaction, save your active rule set with:

-
service iptables save
-

Other rules

- You can add additional rules, or modify existing ones, to work with - IPsec and with your network and policies. We give a some examples in - this section. -

However, while it is certainly possible to create an elaborate set of - 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.

-

The published rule sets we know of are described in the - next section.

-

Adding additional rules

- If necessary, you can add additional rules to: -
-
reject IPsec packets that are not to or from known gateways
-
This possibility is discussed in more detail - later
-
allow systems behind your gateway to build IPsec tunnels that pass - through the gateway
-
This possibility is discussed in more detail - later
-
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.
-
-

It is therefore reasonably straightforward to filter these packets in - whatever way suits your situation.

-

Modifying existing rules

-

In some cases rules that work fine before you add IPsec may require - modification to work with IPsec.

-

This is especially likely for rules that deal with interfaces on the - Internet side of your system. IPsec adds a new interface; often the - rules must change to take account of that.

-

For example, consider the rules given in - this section of the Netfilter documentation:

-
Most people just have a single PPP connection to the Internet, and don't
-want anyone coming back into their network, or the firewall:
-
-    ## Insert connection-tracking modules (not needed if built into kernel).
-    # insmod ip_conntrack
-    # insmod ip_conntrack_ftp
-
-    ## Create chain which blocks new connections, except if coming from inside.
-    # iptables -N block
-    # iptables -A block -m state --state ESTABLISHED,RELATED -j ACCEPT
-    # iptables -A block -m state --state NEW -i ! ppp0 -j ACCEPT
-    # iptables -A block -j DROP
-
-    ## Jump to that chain from INPUT and FORWARD chains.
-    # iptables -A INPUT -j block
-    # iptables -A FORWARD -j block
-

On an IPsec gateway, those rules may need to be modified. The above - allows new connections from anywhere except ppp0. That means - new connections from ipsec0 are allowed.

-

Do you want to allow anyone who can establish an IPsec connection to - your gateway to initiate TCP connections to any service on your - network? Almost certainly not if you are using opportunistic - encryption. Quite possibly not even if you have only explicitly - configured connections.

-

To disallow incoming connections from ipsec0, change the middle - section above to:

-
    ## Create chain which blocks new connections, except if coming from inside.
-    # iptables -N block
-    # iptables -A block -m state --state ESTABLISHED,RELATED -j ACCEPT
-    # iptables -A block -m state --state NEW -i ppp+ -j DROP
-    # iptables -A block -m state --state NEW -i ipsec+ -j DROP
-    # iptables -A block -m state --state NEW -i -j ACCEPT
-    # iptables -A block -j DROP
-

The original rules accepted NEW connections from anywhere except - ppp0. This version drops NEW connections from any PPP interface (ppp+) - and from any ipsec interface (ipsec+), then accepts the survivors.

-

Of course, these are only examples. You will need to adapt them to - your own situation.

-

Published rule sets

-

Several sets of firewall rules that work with FreeS/WAN are - available.

-

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.

-

Asgard scripts

-

Asgard's - Realm has set of firewall scripts with FreeS/WAN support, for 2.4 - kernels and iptables.

-

User scripts from the mailing list

-

One user gave considerable detail on his scripts, including - supporting IPX through the tunnel. His message was - too long to conveniently be quoted here, so I've put it in a - separate file.

-

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

-

The ipsec.conf(5) - 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 - above 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=
-
script to be called before - pluto(8) IKE daemon is started.
-
postpluto=
-
script to be called after - pluto(8) IKE daemon 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 leftfirewall=yes or rightfirewall=yes to - use our supplied default script
-
or
-
assign a name in a leftupdown= or rightupdown= - line to use your own script
-
-

Note that only one of these should be used. You - cannot sensibly use both. Since our default script is obsolete - (designed for firewalls using ipfwadm(8) on 2.0 kernels), - most users who need this service will need to write a custom - script.

-

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:

- -

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. See the "updown command" - section of the ipsec_pluto(8) - man page for details.

-

Note 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 or iptables

-

Our _updown is for firewalls using ipfwadm(8), - the firewall code for the 2.0 series of Linux kernels. If you are using - the more recent packages ipchains(8) (for 2.2 kernels) or - iptables(8) (2.4 kernels), then you must do one of:

- -

You can write a script to do whatever you need with firewalling. - Specify its name in a [left|right]updown= parameter in - ipsec.conf(5) and Pluto will automatically call it for you.

-

The arguments Pluto passes such a script are the same ones it passes - to our default _updown script, so the best way to build yours is to - copy ours and modify the copy.

-

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.

-

A complication: IPsec vs. 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:

- -

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:

- -

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:

- -

Other references on NAT and IPsec

-

Other documents which may be relevant include:

- -

Other complications

-

Of course simply allowing UDP 500 and ESP packets is not the whole - story. Various other issues arise in making IPsec and packet filters - co-exist and even co-operate. Some of them are summarised below.

-

IPsec through the gateway

-

Basic IPsec packet filtering rules deal only with packets addressed - to or sent from your IPsec 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.

-

Where possible, allowing this is almost certainly a good idea. Using - IPsec on an end-to-end basis is more secure than gateway-to-gateway.

-

Doing it is quite simple. You just need firewall rules that allow UDP - port 500 and protocols 50 and 51 to pass through your gateway. If you - wish, you can of course restrict this to certain hosts.

-

Preventing non-IPsec traffic

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

One application of this is for the telecommuter who might have:

-
     Sunset==========West------------------East ================= firewall --- the Internet
-         home network      untrusted net        corporate network
-

The subnet on the right is 0.0.0.0/0, the whole Internet. The West - gateway is set up so that it allows only IPsec packets to East in or - out.

-

This configuration is used in AT&T Research's network. For details, - see the papers links in our introduction.

-

Another application would be to set up firewall rules so that an - internal machine, such as an employees-only web server, could not talk - to the outside world except via specific IPsec tunnels.

-

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:

- -

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

- -

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.

-

How it all works: IPsec packet details

-

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

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:

- -

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:

- -

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:

- -

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

-

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

Linux FreeS/WAN Troubleshooting Guide

-

Overview

-

This document covers several general places where you might have a - problem:

-
    -
  1. During install.
    2. -
  2. During the negotiation process.
    3. -
  3. Using an established connection.
    4. -
-

This document also contains notes which expand - on points made in these sections, and tips for - problem reporting. If the other end of your connection is not - FreeS/WAN, you'll also want to read our - interoperation document.

-

1. During Install

-

1.1 RPM install gotchas

-

With the RPM method:

- -

1.2 Problems installing from source

-

When installing from source, you may find these problems:

- -

1.3 Install checks

-

ipsec verify checks a number of FreeS/WAN essentials. Here - are some hints on what do to when your system doesn't check out:

-

- - - - - - - - - - -
ProblemStatus -Action
ipsec not on-path  -

Add /usr/local/sbin to your PATH.

-
Missing KLIPS supportcritical -See this FAQ.
No RSA private key  -

Follow these instructions to - create an RSA key pair for your host. RSA keys are:

-
    -
  • required for opportunistic encryption, and
    • -
  • our preferred method to authenticate pre-configured connections.
    • -
-
pluto not running -critical -
service ipsec start
-
No port 500 holecritical -Open port 500 for IKE negotiation.
Port 500 check N/A Check that port 500 is open - for IKE negotiation.
Failed DNS checks Opportunistic encryption - requires information from DNS. To set this up, see - our instructions.
No public IP address Check that the interface - which you want to protect with IPSec is up and running.
-

1.3 Troubleshooting OE

-

OE should work with no local configuration, if you have posted DNS - TXT records according to the instructions in our - quickstart guide. If you encounter trouble, try these hints. We - welcome additional hints via the users' mailing - list.

- - - - - - - - - - - - - -
SymptomProblem -Action
You're running FreeS/WAN 2.01 (or later), and initiating a - connection to FreeS/WAN 2.00 (or earlier). In your logs, you see a - message like: -
no RSA public key known for '192.0.2.13';
-DNS search for KEY failed (no KEY record
-for 13.2.0.192.in-addr.arpa.)
- The older FreeS/WAN logs no error.		 - A protocol level incompatibility between 2.01 (or later) and 2.00 - (or earlier) causes this error. It occurs when a FreeS/WAN 2.01 (or - later) box for which no KEY record is posted attempts to initiate an OE - connection to older FreeS/WAN versions (2.00 and earlier). Note that - older versions can initiate to newer versions without this error. -If you control the peer host, upgrade its FreeS/WAN to 2.01 (or later), - and post new style TXT records for it. If not, but if you know its - sysadmin, perhaps a quick note is in order. If neither option is - possible, you can ease the transition by posting an old style KEY - record (created with a command like "ipsec showhostkey --key") to the - reverse map for the FreeS/WAN 2.01 (or later) box.
OE host is very slow to contact other hosts.Slow DNS - service while running OE.It's a good idea to run a caching DNS - server on your OE host, as outlined in - this mailing list message. If your DNS servers are elsewhere, put - their IPs in the clear policy group, and re-read groups with -
ipsec auto --rereadgroups
-
-
Can't Opportunistically initiate for
-192.0.2.2 to 192.0.2.3: no TXT record
-for 13.2.0.192.in-addr.arpa.
-		Peer is not set up for OE. -

None. Plenty of hosts on the Internet do not run OE. If, however, you - have set OE up on that peer, this may indicate that you need to wait up - to 48 hours for its DNS records to propagate.

-
ipsec verify does not find DNS records: -
...
-Looking for TXT in forward map:
-                xy.example.com...[FAILED]
-Looking for TXT in reverse map...[FAILED]
-...
- You also experience authentication failure: -
-
Possible authentication failure:
-no acceptable response to our
-first encrypted message
-		DNS records are not posted or have not propagated.Did - you post the DNS records necessary for OE? If not, do so using the - instructions in our quickstart guide. If so, - wait up to 48 hours for the DNS records to propagate.
ipsec verify does not find DNS records, and you - experience authentication failure.For iOE, your ID does not - match location of forward DNS record.In config setup -, change myid= to match the forward DNS where you posted the - record. Restart FreeS/WAN. For reference, see our - iOE instructions.
ipsec verify finds DNS records, yet there is still - authentication failure. ( ? )DNS records are malformed. -Re-create the records and send new copies to your DNS administrator.
ipsec verify finds DNS records, yet there is still - authentication failure. ( ? )DNS records show different keys - for a gateway vs. its subnet hosts.All TXT records for boxes - protected by an OE gateway must contain the gateway's public key. - Re-create and re-post any incorrect records using - these instructions.
OE gateway loses connectivity to its subnet. The gateway's - routing table shows routes to the subnet through IPsec interfaces. -The subnet is part of the private or block policy - group on the gateway.Remove the subnet from the group, and - reread groups with -
ipsec auto --rereadgroups
-
OE does not work to hosts on the local LAN.This is a - known issue.See this list - of known issues with OE.
FreeS/WAN does not seem to be executing your default policy. In - your logs, you see a message like: -
/etc/ipsec.d/policies/iprivate-or-clear"
-line 14: subnet "0.0.0.0/0",
-source 192.0.2.13/32,
-already "private-or-clear"
-		Fullnet in a policy group file defines - your default policy. Fullnet should normally be present in only one - policy group file. The fine print: you can have two default policies - defined so long as they protect different local endpoints (e.g. the - FreeS/WAN gateway and a subnet). Find all policies which - contain fullnet with: -
-
grep -F 0.0.0.0/0 /etc/ipsec.d/policies/*
- then remove the unwanted occurrence(s).
-

2. During Negotiation

-

When you fail to bring up a tunnel, you'll need to find out:

- -

before you can diagnose your problem -.

-

2.1 Determine Connection State

-

Finding current state

-

You can see connection states (STATE_MAIN_I1 and so on) when you - bring up a connection on the command line. If you have missed this, or - brought up your connection automatically, use:

-
ipsec auto --status
-

The most relevant state is the last one reached.

-

What's this supposed to look like?

-

Negotiations should proceed though various states, in the processes - of:

-
    -
  1. IKE negotiations (aka Phase 1, Main Mode, STATE_MAIN_*)
    2. -
  2. IPSEC negotiations (aka Phase 2, Quick Mode, STATE_QUICK_*)
    3. -
-

These are done and a connection is established when you see messages - like:

-
    000 #21: "myconn" STATE_MAIN_I4 (ISAKMP SA established)...
-    000 #2: "myconn" STATE_QUICK_I2 (sent QI2, IPsec SA established)...
-

Look for the key phrases are "ISAKMP SA established" and "IPSec SA - established", with the relevant connection name. Often, this happens at - STATE_MAIN_I4 and STATE_QUICK_I2, respectively.

-

ipsec auto --status will tell you what states have - been achieved, rather than the current state. Since - determining the current state is rather more difficult to do, current - state information is not available from Linux FreeS/WAN. If you are - actively bringing a connection up, the status report's last states for - that connection likely reflect its current state. Beware, though, of - the case where a connection was correctly brought up but is now downed: - Linux FreeS/WAN will not notice this until it attempts to rekey. - Meanwhile, the last known state indicates that the connection has been - established.

-

If your connection is stuck at STATE_MAIN_I1, skip straight to - here.

-

2.2 Finding error text

-

Solving most errors will require you to find verbose error text, - either on the command line or in the logs.

-

Verbose start for more information

-

Note that you can get more detail from ipsec auto using - the --verbose flag:

-
    ipsec auto --verbose --up west-east
-

More complete information can be gleaned from the - log files.

-

Debug levels count

-

The amount of description you'll get here depends on ipsec.conf debug - settings, klipsdebug= and plutodebug=. When - troubleshooting, set at least one of these to all, and when - done, reset it to none so your logs don't fill up. Note that - you must have enabled the klipsdebug - compile-time option for the klipsdebug configuration - switch to work.

-

For negotiation problems plutodebug is most relevant. - klipsdebug applies mainly to attempts to use an - already-established connection. See also this - description of the division of duties within Linux FreeS/WAN.

-

After raising your debug levels, restart Linux FreeS/WAN to ensure - that ipsec.conf is reread, then recreate the error to generate verbose - logs.

-

ipsec barf for lots of debugging - information

-

ipsec barf (8) - collects a bunch of useful debugging information, including these logs - Use the command

-
-    ipsec barf > barf.west
-
-

to generate one.

-

Find the error

-

Search out the failure point in your logs. Are there a handful of - lines which succinctly describe how things are going wrong or contrary - to your expectation? Sometimes the failure point is not immediately - obvious: Linux FreeS/WAN's errors are usually not marked "Error". Have - a look in the FAQ for what some common failures - look like.

-

Tip: problems snowball. Focus your efforts on the first problem, - which is likely to be the cause of later errors.

-

Play both sides

-

Also find error text on the peer IPSec box. This gives you two - perspectives on the same failure.

-

At times you will require information which only one side has. The - peer can merely indicate the presence of an error, and its approximate - point in the negotiations. If one side keeps retrying, it may be - because there is a show stopper on the other side. Have a look at the - other side and figure out what it doesn't like.

-

If the other end is not Linux FreeS/WAN, the principle is the same: - replicate the error with its most verbose logging on, and capture the - output to a file.

-

2.3 Interpreting a Negotiation - Error

-

Connection stuck at STATE_MAIN_I1

-

This error commonly happens because IKE (port 500) packets, needed to - negotiate an IPSec connection, cannot travel freely between your IPSec - gateways. See our firewall document for details.

-

Other errors

-

Other errors require a bit more digging. Use the following resources:

- -

If you have failed to solve your problem with the help of these - resources, send a detailed problem report to the users list, following - these guidelines.

-

3. Using a Connection

-

3.1 Orienting yourself

-

How do I know if it works?

-

Test your connection by sending packets through it. The simplest way - to do this is with ping, but the ping needs to test the correct - tunnel. See this example scenario if - you don't understand this.

-

-

If your ping returns, test any other connections you've brought u all - check out, great. You may wish to test with large - packets for MTU problems.

-

ipsec barf is useful again

-

If your ping fails to return, generate an ipsec barf debugging report - on each IPSec gateway. On a non-Linux FreeS/WAN implementation, gather - equivalent information. Use this, and the tips in the next sections, to - troubleshoot. Are you sure that both endpoints are capable of hearing - and responding to ping?

-

3.2 Those pesky configuration errors

-

IPSec may be dropping your ping packets since they do not belong in - the tunnels you have constructed:

- -

In either case, you will often see a message like:

-
klipsdebug... no eroute
-

which we discuss in this FAQ.

-

Note:

- -

3.3 Check Routing and Firewalling

-

If you've confirmed your configuration assumptions, the problem is - almost certainly with routing or firewalling. Isolate the problem using - interface statistics, firewall statistics, or a packet sniffer.

-

Background:

- -

View Interface and Firewall Statistics

-

Interface reports and firewall statistics can help you track down - lost packets at a glance. Check any firewall statistics you may be - keeping on your IPSec gateways, for dropped packets.

-

Tip: You can take a snapshot of the packets - processed by your firewall with:

-
    iptables -L -n -v
-

You can get creative with "diff" to find out what happens to a - particular packet during transmission.

-

Both cat /proc/net/dev and ifconfig display - interface statistics, and both are included in ipsec barf. - Use either to check if any interface has dropped packets. If you find - that one has, test whether this is related to your ping. While you ping - continuously, print that interface's statistics several times. Does its - drop count increase in proportion to the ping? If so, check why the - packets are dropped there.

-

To do this, look at the firewall rules that apply to that interface. - If the interface is an IPSec interface, more information may be - available in the log. Grep for the word "drop" in a log which was - created with klipsdebug=all as the error happened.

-

See also this discussion on interpreting - ifconfig statistics.

-

3.4 When in doubt, sniff it out

-

If you have checked configuration assumptions, routing, and firewall - rules, and your interface statistics yield no clue, it remains for you - to investigate the mystery of the lost packet by the most thorough - method: with a packet sniffer (providing, of course, that this is legal - where you are working).

-

In order to detect packets on the ipsec virtual interfaces, you will - need an up-to-date sniffer (tcpdump, ethereal, ksnuffle) on your IPSec - gateway machines. You may also find it useful to sniff the ping - endpoints.

-

Anticipate your packets' path

-

Ping, and examine each interface along the projected path, checking - for your ping's arrival. If it doesn't get to the the next stop, you - have narrowed down where to look for it. In this way, you can isolate a - problem area, and narrow your troubleshooting focus.

-

Within a machine running Linux FreeS/WAN, this - packet flow diagram will help you anticipate a packet's path.

-

Note that:

- -

Once you isolate where the packet is lost, take a closer look at - firewall rules, routing and configuration assumptions as they affect - that specific area. If the packet is lost on an IPSec gateway, comb - through klipsdebug output for anomalies.

-

If the packet goes through both gateways successfully and reaches the - ping target, but does not return, suspect routing. Check that the ping - target routes packets back to the IPSec gateway.

-

3.5 Check your logs

-

Here, too, log information can be useful. Start with the - guidelines above.

-

For connection use problems, set klipsdebug=all. Note that - you must have enabled the klipsdebug - compile-time option to do this. Restart Linux FreeS/WAN so that it - rereads ipsec.conf, then recreate the error condition. When - searching through klipsdebug data, look especially for the - keywords "drop" (as in dropped packets) and "error".

-

Often the problem with connection use is not software error, but - rather that the software is behaving contrary to expectation.

-

Interpreting log text

-

To interpret the Linux FreeS/WAN log text you've found, use the same - resources as indicated for troubleshooting connection negotiation: - the FAQ , our background document, - and the list archives. Looking in the KLIPS code - is only for the very brave.

-

If you are still stuck, send a detailed - problem report to the users' list.

-

3.6 More testing for the truly thorough

-

Large Packets

-

If each of your connections passed the ping test, you may wish to - test by pinging with large packets (2000 bytes or larger). If it does - not return, suspect MTU issues, and see this - discussion.

-

Stress Tests

-

In most users' view, a simple ping test, and perhaps a large-packet - ping test suffice to indicate a working IPSec connection.

-

Some people might like to do additional stress tests prior to - production use. They may be interested in this - testing protocol we use at interoperation conferences, aka - "bakeoffs". We also have a testing directory that ships with - the release.

-

4. Problem Reporting

-

4.1 How to ask for help

-

Ask for troubleshooting help on the users' mailing list, - users@lists.freeswan.org. 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.

-

When reporting problems to the mailing list(s), please include:

- -

Here are some good general guidelines on bug reporting: - How To Ask Questions The Smart Way and - How to Report Bugs Effectively.

-

4.2 Where to ask

-

To report a problem, send mail about it to the users' list. If you - are certain that you have found a bug, report it to the bugs list. If - you encounter a problem while doing your own coding on the Linux - FreeS/WAN codebase and think it is of interest to the design team, - notify the design list. When in doubt, default to the users' list. More - information about the mailing lists is found here.

-

For a number of reasons -- including export-control regulations - affecting almost any private discussion of encryption - software -- we prefer that problem reports and discussions go to the - lists, not directly to the team. Beware that the list goes worldwide; - US citizens, read this important information about your - export laws. If you're using this software, you really should be on - the lists. To get onto them, visit - lists.freeswan.org.

-

If you do send private mail to our coders or want a private reply - from them, please make sure that the return address on your mail (From - or Reply-To header) is a valid one. They have more important things to - do than to unravel addresses that have been mangled in an attempt to - confuse spammers.

-

5. Additional Notes on Troubleshooting

-

The following sections supplement the Guide: - information available on your system; testing - between security gateways; ifconfig reports - for KLIPS debugging; using GDB on Pluto.

-

5.1 Information available on your system

-

Logs used

-

Linux FreeS/WAN logs to:

- -

Check both places to get full information. If you find nothing, check - your syslogd.conf(5) to see where your /etc/syslog.conf or - equivalent is directing authpriv messages.

-

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

- -

Status information

-
-
ipsec auto --status
-
Command to get status report from running system. Displays Pluto's - state. Includes the list of connections which are currently "added" to - Pluto's internal database; lists state objects reflecting ISAKMP and - IPsec SAs being negotiated or installed.
-
ipsec look
-
Brief status info.
-
ipsec barf
-
Copious debugging info.
-
-

5.2 Testing between security gateways

-

Sometimes you need to test a subnet-subnet tunnel. This is a tunnel - between two security gateways, which protects traffic on behalf of the - subnets behind these gateways. On this network:

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

you might name this tunnel sunset-sunrise. You can test this tunnel - 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 - traffic between the two protected subnets, not between the gateways - . Depending on the routing in place, a ping might

- -

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 unnecessary complications - in your situation.

-

The trick is to explicitly test between both gateways' - private-side IP addresses. Since the private-side interfaces - are on the protected subnets, the resulting packets do go via the - tunnel. Use either ping -I or traceroute -i, both of which allow you to - specify a source interface. (Note: unsupported on older Linuxes). The - same principles apply for a road warrior (or other) case where only one - end of your tunnel is a subnet.

-

5.3 ifconfig reports for KLIPS debugging

-

When diagnosing problems using ifconfig statistics, you may wonder - what type of activity increments a particular counter for an ipsecN - device. Here's an index, posted by KLIPS developer Richard Guy Briggs:

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

5.4 Using GDB on Pluto

-

You may need to use the GNU debugger, gdb(1), on Pluto. This should - be necessary only in unusual 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.

-

-
-

-
-

Linux FreeS/WAN Compatibility Guide

-

Much 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.96:

- -

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 omitted

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

- -

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:

- -

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

- -

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.

-

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 the latest 2.2.x and 2.4.y

-

We develop and test on Redhat Linux using the most recent kernel in - the 2.2 and 2.4 series. In general, we recommend you use the latest - kernel in one of those series. Complications and caveats are discussed - below.

-

2.0.x 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 on 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 to 1.96
-
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.

-

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 - or 7.2 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. They are - soluble, but we recommend you upgrade to a later Redhat instead..

-

Redhat 7 ships with two compilers.

- -

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.

-

FreeS/WAN packages distributed for SuSE 7.0-7.2 were somehow - miscompiled. You can find fixed packages on - Kurt Garloff's page.

-

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" ] && 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

-

A recent (Nov 2001) mailing list points to a - web page on setting up several types of tunnel, including IPsec, on - Debian.

-

Some older information:

-
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 and later distributions, 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.
-

FreeS/WAN no longer includes GMP source.

-

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 manufacture an IPsec box based on an embedded MIPS running - Linux with FreeS/WAN. We have no details.

-

Transmeta Crusoe

-

The Merilus - Firecard, a Linux firewall on a PCI card, is based on a Crusoe - processor and supports FreeS/WAN.

-

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.

-

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:

- -

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.

-

More recently, a patch to support some hardware accelerators has been - posted:

-
Subject: [Design] [PATCH] H/W acceleration patch
-   Date: Tue, 18 Sep 2001
-   From: "Martin Gadbois" <martin.gadbois@colubris.com>
- 
-Finally!!
-Here's a web site with H/W acceleration patch for FreeS/WAN 1.91, including
-S/W and Hifn 7901 crypto support.
-
-http://sources.colubris.com/
-
-Martin Gadbois
-

Hardware accelerators could take performance well beyond what - FreeS/WAN can do in software (discussed here -). Here is some discussion off the IETF IPsec list, October 2001:

-
 ... Currently shipping chips deliver, 600 mbps throughput on a single
- stream of 3DES IPsec traffic.  There are also chips that use multiple
- cores to do 2.4 gbps.  We (Cavium) and others have announced even faster
- chips. ... Mid 2002 versions will handle at line rate (OC48 and OC192)
- IPsec and SSL/TLS traffic not only 3DES CBC but also AES and arc4.
-

The patches to date support chips that have been in production for - some time, not the state-of-the-art latest-and-greatest devices - described in that post. However, they may still outperform software and - they almost certainly reduce CPU overhead.

-

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, and a patched version with IPv6 support is - available. For more recent information, check the - mailing list.

-

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:

- -

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:

- -

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.

-
- -

Interoperating with FreeS/WAN

-

The FreeS/WAN project needs you! We rely on the user community to - keep up to date. Mail users@lists.freeswan.org with your interop - success stories.

-

Please note: Most of our interop examples feature - Linux FreeS/WAN 1.x config files. You can convert them to 2.x files - fairly easily with the patch in our Upgrading - Guide.

-

Interop at a Glance

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
 FreeS/WAN VPNRoad Warrior -OE
 PSKRSA SecretX.509 -
(requires patch)		 -NAT-Traversal -
(requires patch)		 -Manual -
Keying		  
More Compatible
FreeS/WAN   -YesYes -Yes -YesYes -YesYes
isakmpd (OpenBSD)   -Yes  -Yes Yes  -No    
Kame (FreeBSD, -
NetBSD, MacOSX) -
aka racoon  		YesYes -Yes  -Yes No
McAfee VPN -
was PGPNet  		YesYes -Yes   -YesNo
Microsoft -
Windows 2000/XP  		 -Yes Yes  - Yes -No
SSH Sentinel  Yes Yes -Maybe  -YesNo
Safenet SoftPK -
/SoftRemote  		 -Yes Yes  - Yes -No
Other
6Wind    - Yes    -No
Alcatel Timestep   -Yes    -  No
Apple Macintosh -
System 10+  		 -MaybeYes -Maybe Maybe - No
AshleyLaurent -
VPCom  		 -Yes     No
Borderware   -Yes    - No -No
Check Point FW-1/VPN-1 -  Yes  -Yes  Yes -No
Cisco with 3DES   -YesMaybe - Maybe  - No
Equinux VPN Tracker -
(for Mac OS X)  		 -YesYes -Yes Maybe - No
F-Secure   -Yes   -MaybeYes -YesNo
Gauntlet GVPN   -Yes  -Yes    -No
IBM AIX   -Yes Maybe -   No
IBM AS/400  Yes     - No
Intel Shiva -
LANRover/Net Structure  		 -Yes     No
LanCom (formerly ELSA) -  Yes   -   No
Linksys   -Maybe  -No  Yes -No
Lucent  Partial     - No
Netasq   -  Yes   - No
netcelo   -  Yes   - No
Netgear fvs318   -Yes    -  No
Netscreen 100 -
or 5xp  		 -Yes     -MaybeNo
Nortel Contivity   -Partial  -YesMaybe  - No
RadGuard   -Yes     - No
Raptor  Yes    -Yes No
Redcreek Ravlin   -Yes/Partial -      -No
SonicWall   -Yes   MaybeNo -No
Sun Solaris  Yes Yes - Yes No
Symantec   -Yes     - No
Watchguard -
Firebox  		 -Yes    -Yes No
Xedia Access Point -
/QVPN  		 -Yes     No
Zyxel Zywall -
/Prestige  		 -Yes     No
 PSKRSA SecretX.509 -
(requires patch)		 -NAT-Traversal -
(requires patch)		 -Manual -
Keying		  
 FreeS/WAN VPNRoad Warrior -OE
-

Key

- - - - - - - -
YesPeople report that this - works for them.
[Blank]We don't know.
NoWe have reason to - believe it was, at some point, not possible to get this to work.
PartialPartial success. - For example, a connection can be created from one end only.
Yes/Partial -Mixed reports.
MaybeWe think the answer - is "yes", but need confirmation.
- -

Basic Interop Rules

-

Vanilla FreeS/WAN implements these parts of the - IPSec specifications. You can add more with - Super FreeS/WAN, but what we offer may be enough for many users.

- -

We offer a set of proposals which is not user-adjustable, but covers - all combinations that we can offer. FreeS/WAN always proposes triple - DES encryption and Perfect Forward Secrecy (PFS). In addition, we - propose Diffie Hellman groups 5 and 2 (in that order), and MD5 and - SHA-1 hashes. We accept the same proposals, in the same order of - preference.

-

Other interop notes:

- -

Longer Stories

-

For More Compatible Implementations

-

FreeS/WAN

-

See our documentation at - freeswan.org and the Super FreeS/WAN docs at - freeswan.ca. Some user-written HOWTOs for FreeS/WAN-FreeS/WAN - connections are listed in our Introduction.

-

See also:

- -

Back to chart

-

isakmpd (OpenBSD)

-

OpenBSD FAQ: Using - IPsec -
- Hans-Joerg Hoexer's interop Linux-OpenBSD (PSK) -
Skyper's configuration - (PSK) -
- French page with configs (X.509)

-

Back to chart

-

Kame

- -

Kame homepage, with FAQ -
- NetBSD's IPSec FAQ -
- Ghislaine's post explaining some interop peculiarities

-

- Itojun's Kame-FreeS/WAN interop tips (PSK) -
Ghislaine - Labouret's French page with links to matching FreeS/WAN and Kame - configs (RSA) -
Markus - Wernig's HOWTO (X.509, BSD gateway) -
- Frodo's Kame-FreeS/WAN interop (X.509) -
Kame as a WAVEsec - client.

-

Back to chart

-

PGPNet/McAfee

-

- -

Tim Carr's - Windows Interop Guide (X.509) -
- Hans-Joerg Hoexer's Guide for Linux-PGPNet (PSK) -
- Kai Martius' instructions using RSA Key-Extractor Tool (RSA) -
    Christian - Zeng's page (RSA) based on Kai's work. English or German. -
- Oscar Delgado's PDF (X.509, no configs) -
Ryan's HOWTO - for FreeS/WAN-PGPNet (X.509). Through a Linksys Router with IPsec - Passthru enabled. -
Jean-Francois - Nadeau's Practical Configuration (Road Warrior with PSK) -
Wouter - Prins' HOWTO (Road Warrior with X.509) -

-

- Rekeying problem with FreeS/WAN and older PGPNets -

-

DHCP - over IPSEC HOWTO for FreeS/WAN (requires X.509 and dhcprelay patches) -

-

Back to chart

-

Microsoft Windows 2000/XP

- -

Tim Carr's - Windows Interop Guide (X.509) -
James - Carter's instructions (X.509, NAT-T) -
Jean-Francois - Nadeau's Net-net Configuration (PSK) -
Telenor's - Node-node Config (Transport-mode PSK) -
Marcus Mueller's HOWTO using his - VPN config tool (X.509). Tool also works with PSK. -
- Nate Carlson's HOWTO using same tool (Road Warrior with X.509). - Unusually, FreeS/WAN is the Road Warrior here. -
- Oscar Delgado's PDF (X.509, no configs) -
- Tim Scannell's Windows XP Additional Checklist (X.509) -

- - -

- Microsoft's page on Win2k TCP/IP security features -
- Microsoft's Win2k IPsec debugging tips -
- - - MS VPN may fall back to 1DES

-

Back to chart

-

SSH Sentinel

- -

SSH's - Sentinel-FreeSWAN interop PDF (X.509) -
- Nadeem Hassan's SUSE-to-Sentinel article (Road warrior with X.509) -
- O-Zone's Italian HOWTO (Road Warrior, X.509, DHCP) -

-

Back to chart

-

Safenet SoftPK/SoftRemote

- -

- Whit Blauvelt's SoftRemote tips -
- Tim Wilson's tips (X.509) - Workaround for a "gotcha"

-

Jean-Francois - Nadeau's Practical Configuration (Road Warrior with PSK) -
- Terradon Communications' PDF (Road Warrior with PSK) -
- Seaan.net's PDF (Road Warrior to Subnet, with PSK) -
- Red Baron Consulting's PDF (Road Warrior with X.509)

-

Back to chart

-

For Other Implementations

-

6Wind

-

- French page with configs (X.509)

-

Back to chart

-

Alcatel Timestep

-

- Alain Sabban's settings (PSK or PSK road warrior; through static NAT) -
- Derick Cassidy's configs (PSK) -
- David Kerry's Timestep settings (PSK) -
- Kevin Gerbracht's ipsec.conf (X.509)

-

Back to chart

-

Apple Macintosh System 10+

- -

James - Carter's instructions (X.509, NAT-T)

-

Back to chart

-

AshleyLaurent VPCom

-

- Successful interop report, no details

-

Back to chart

-

Borderware

- -

- Philip Reetz' configs (PSK) -
- Borderware server does not support FreeS/WAN road warriors -
- Older Borderware may not support Diffie Hellman groups 2, 5 -

-

Back to chart

-

Check Point VPN-1 or FW-1

- -

- AERAsec's Firewall-1 NG site (PSK, X.509, Road Warrior with X.509, - other algorithms) -
     - AERAsec's detailed Check Point-FreeS/WAN support matrix -
- Checkpoint.com PDF: Linux as a VPN Client to FW-1 (PSK) -
PhoneBoy's Check Point FAQ (on - Check Point only, not FreeS/WAN) -

-

- Chris Harwell's tips FreeS/WAN configs (PSK) -
- Daniel Tombeil's configs (PSK)

-

Back to chart

-

Cisco

- -

SANS - Institute HOWTO (PSK). Detailed, with extensive references. -
Short HOWTO - (PSK) -
- French page with configs for Cisco IOS, PIX and VPN 3000 (X.509) -
- Dave McFerren's sample configs (PSK) -
- Wolfgang Tremmel's sample configs (PSK road warrior) -
- Old doc from Pete Davis, with William Watson's updated Tips (PSK) -

-

Some PIX specific information: -
Waikato Linux - Users' Group HOWTO. Nice detail (PSK) -
- John Leach's configs (PSK) -
Greg - Robinson's settings (PSK) -
- Scott's ipsec.conf for PIX (PSK, FreeS/WAN side only) -
- Rick Trimble's PIX and FreeS/WAN settings (PSK) -

-

Cisco VPN support - page -
- Cisco IPsec information page

-

Back to chart

-

Equinux VPN tracker (for Mac OS X)

- -

Equinux provides - this excellent interop PDF (PSK, RSA, X.509).

-

Back to chart

-

F-Secure

- -

pingworks.de's - "Connecting F-Secure's VPN+ to Linux FreeS/WAN" (PSK road warrior) -
    Same thing - as PDF -
- Success report, no detail (PSK) -
- Success report, no detail (Manual)

- - -

Back to chart

-

Gauntlet GVPN

-

- Richard Reiner's ipsec.conf (PSK) -
- Might work without that pesky firewall... (PSK) -
- - In late July, 2003 Alexandar Antik reported success interoperating - with Gauntlet 6.0 for Solaris (X.509). Unfortunately the message is not - properly archived at this time.

-

Back to chart

-

IBM AIX

-

- IBM's "Built-In Network Security with AIX" (PSK, X.509) -
- IBM's tip: importing Linux FreeS/WAN settings into AIX's ikedb - (PSK)

-

Back to chart

-

IBM AS/400

- -

- Richard Welty's tips and tricks -

-

Back to chart

-

Intel Shiva LANRover / Net Structure

- -

Snowcrash's configs - (PSK) -
Old configs from an - interop (PSK) -
- The day Shiva tickled a Pluto bug (PSK) -
     - Follow up: success!

-

Back to chart

-

LanCom (formerly ELSA)

- -

Jakob Curdes successfully created a PSK connection with the LanCom - 1612 in August 2003. - -

-

Back to chart

-

Linksys

- -
As tunnel endpoint
-

Ken Bantoft's - instructions (Road Warrior with PSK) -
- Nate Carlson's caveats

-
In IPsec passthrough mode
-

Sample HOWTO - through a Linksys Router -
- Nadeem Hasan's configs -
- Brock Nanson's tips -

-

Back to chart

-

Lucent

-

- Partial success report; see also the next message in thread

- - -

Back to chart

-

Netasq

-

- French page with configs (X.509)

- - -

Back to chart

-

Netcelo

-

- French page with configs (X.509) - -

-

Back to chart

-

Netgear fvs318

- -

- John Morris' setup (PSK)

-

Back to chart

-

Netscreen 100 or 5xp

-

- Errol Neal's settings (PSK) -
- Corey Rogers' configs (PSK, no PFS) -
- Jordan Share's configs (PSK, 2 subnets, through static NAT) -
- Set src proxy_id to your protected subnet/mask -
- French page with ipsec.conf, Netscreen screen shots (X.509, may need to - revert to PSK...)

-

- A report of a company using Netscreen with FreeS/WAN on a large scale - (FreeS/WAN road warriors?)

-

Back to chart

-

Nortel Contivity

- -

- JJ Streicher-Bremer's mini HOWTO for old new software. (PSK with two - subnets) -
- French page with configs (X.509). This succeeds using the above - X.509 tip.

- - -

Back to chart

-

Radguard

-

- Marko Hausalo's configs (PSK). Note: These do create a connection, - as you can see by "IPsec SA established". -
- Claudia Schmeing's comments

-

Back to chart

-

Raptor (NT or Solaris)

-

- -

- Peter Mazinger's settings (PSK) -
- Peter Gerland's configs (PSK) -
- Charles Griebel's configs (PSK). -
- Lumir Srch's tips (PSK)

-

- John Hardy's configs (Manual) -
- Older Raptors want 3DES keys in 3 parts (Manual). -
- Different keys for each direction? (Manual) -

-

Back to chart

-

Redcreek Ravlin

- -

Back to chart

-

SonicWall

- -

Paul Wouters' - config (PSK) -
- Dilan Arumainathan's configuration (PSK) -
Dariush's setup... - only opens one way (PSK) -
- Andreas Steffen's tips (X.509) -

-

Back to chart

-

Sun Solaris

- -

- Reports of some successful interops from a fellow @sun.com. See - also - these follow up posts. -
- Aleks Shenkman's configs (Manual in transport mode) -
- -

-

Back to chart

-

Symantec

- -

- Andreas Steffen's configs for Symantec 200R (PSK)

-

Back to chart

-

Watchguard Firebox

- -

- WatchGuard's HOWTO (PSK) -
- Ronald C. Riviera's Settings (PSK) -
- Walter Wickersham's Notes (PSK) -
- Max Enders' Configs (Manual)

-

- Old known issue with auto keying -
- Tips on key generation and format (Manual) -

-

Back to chart

-

Xedia Access Point/QVPN

-

- Hybrid IPsec/L2TP connection settings (X.509) -
- Xedia's LAN-LAN links don't use multiple tunnels -
     - That explanation, continued

-

Back to chart

-

Zyxel

- -

- Zyxel's Zywall to FreeS/WAN instructions (PSK) -
- Zyxel's Prestige to FreeS/WAN instructions (PSK). Note: not all - Prestige versions include VPN software. -
Fabrice - Cahen's HOWTO (PSK) -
    

-

Back to chart

- - -
-

Performance of FreeS/WAN

- The performance of FreeS/WAN is adequate for most applications. -

In normal operation, the main concern is the overhead for encryption, - decryption and authentication of the actual IPsec (ESP - and/or AH) data packets. Tunnel setup and rekeying - occur so much less frequently than packet processing that, in general, - their overheads are not worth worrying about.

-

At startup, however, tunnel setup overheads may be significant. If - you reboot a gateway and it needs to establish many tunnels, expect - some delay. This and other issues for large gateways are discussed - below.

-

Published material

-

The University of Wales at Aberystwyth has done quite detailed speed - tests and put - their results on the web.

-

Davide Cerri's thesis (in - Italian) includes performance results for FreeS/WAN and for - TLS. He posted an - English summary on the mailing list.

-

Steve Bellovin used one of AT&T Research's FreeS/WAN gateways as his - data source for an analysis of the cache sizes required for key - swapping in IPsec. Available as - text or - PDF slides for a talk on the topic.

-

See also the NAI work mentioned in the next section.

-

Estimating CPU overheads

-

We can come up with a formula that roughly relates CPU speed to the - rate of IPsec processing possible. It is far from exact, but should be - usable as a first approximation.

-

An analysis of authentication overheads for high-speed networks, - including some tests using FreeS/WAN, is on the - NAI Labs site. In particular, see figure 3 in this - PDF document. Their estimates of overheads, measured in Pentium II - cycles per byte processed are:

- - - - - - -
IPsecauthenticationencryption -cycles/byte
Linux IP stack alonenonono -5
IPsec without cryptoyesnono -11
IPsec, authentication onlyyesSHA-1no24
IPsec with encryptionyesyesyesnot tested
-

Overheads for IPsec with encryption were not tested in the NAI work, - but Antoon Bosselaers' - web page gives cost for his optimised Triple DES implementation as - 928 Pentium cycles per block, or 116 per byte. Adding that to the 24 - above, we get 140 cycles per byte for IPsec with encryption.

-

At 140 cycles per byte, a 140 MHz machine can handle a megabyte -- 8 - megabits -- per second. Speeds for other machines will be proportional - to this. To saturate a link with capacity C megabits per second, you - need a machine running at C * 140/8 = C * 17.5 MHz.

-

However, that estimate is not precise. It ignores the differences - between:

- -

and does not account for some overheads you will almost certainly - have:

- -

so we suggest using C * 25 to get an estimate with a bit - of a built-in safety factor.

-

This covers only IP and IPsec processing. If you have other loads on - your gateway -- for example if it is also working as a firewall -- then - you will need to add your own safety factor atop that.

-

This estimate matches empirical data reasonably well. For example, - Metheringham's tests, described below, show - a 733 topping out between 32 and 36 Mbit/second, pushing data as fast - as it can down a 100 Mbit link. Our formula suggests you need at least - an 800 to handle a fully loaded 32 Mbit link. The two results are - consistent.

-

Some examples using this estimation method:

- - - - - - - - - - - - - - -
InterfaceMachine speed in MHz
TypeMbit per -
second		Estimate -
Mbit*25		Minimum IPSEC gatewayMinimum with other - load -

(e.g. firewall)

-
DSL125 MHz -whatever you have133, or better if you have it
cable modem375 MHz
any link, light load -5125 MHz133200+, - almost any surplus machine
Ethernet10250 MHz -surplus 266 or 300500+
fast link, moderate load -20500 MHz500800+, - any current off-the-shelf PC
T3 or E3451125 MHz -12001500+
fast Ethernet100 -2500 MHz// not feasible - with 3DES in software on current machines //
OC31553875 MHz
-

Such an estimate is far from exact, but should be usable as minimum - requirement for planning. The key observations are:

- -

Higher performance alternatives

-

AES is a new US government block cipher standard, - designed to replace the obsolete DES. If FreeS/WAN - using 3DES is not fast enough for your application, - the AES patch may help.

-

To date (March 2002) we have had only one - mailing list report of measurements with the patch applied. It - indicates that, at least for the tested load on that user's network, - AES roughly doubles IPsec throughput. If further testing - confirms this, it may prove possible to saturate an OC3 link in - software on a high-end box.

-

Also, some work is being done toward support of - hardware IPsec acceleration which might extend the range of - requirements FreeS/WAN could meet.

-

Other considerations

-

CPU speed may be the main issue for IPsec performance, but of course - it isn't the only one.

-

You need good ethernet cards or other network interface hardware to - get the best performance. See this - ethernet information page and this - Linux network driver page.

-

The current FreeS/WAN kernel code is largely single-threaded. It is - SMP safe, and will run just fine on a multiprocessor machine ( -discussion), but the load within the kernel is not shared - effectively. This means that, for example to saturate a T3 -- which - needs about a 1200 MHz machine -- you cannot expect something like a - dual 800 to do the job.

-

On the other hand, SMP machines do tend to share loads well so -- - provided one CPU is fast enough for the IPsec work -- a multiprocessor - machine may be ideal for a gateway with a mixed load.

-

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

- -

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.

-

A gateway that does a lot of rekeying -- many tunnels and/or low - settings for tunnel lifetimes -- will also need a lot of - random numbers from the random(4) driver.

-

Low-end systems

-

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

From the above, and from general user experience as reported on the - list, it seems clear that a cheap surplus machine -- a reasonable 486, - a minimal Pentium box, a Sparc 5, ... -- can easily handle a home - office or a small company connection using any of:

- -

If available, we suggest using a Pentium 133 or better. This should - ensure that, even under maximum load, IPsec will use less than half the - CPU cycles. You then have enough left for other things you may want on - your gateway -- firewalling, web caching, DNS and such.

-

Measuring KLIPS

-

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
-

Speed with compression

-

Another user reported some results for connections with and without - IP compression:

-
Subject: [Users] Speed with compression
-   Date: Fri, 29 Jun 2001
-   From: John McMonagle <johnm@advocap.org>
-
-Did a couple tests with compression using the new 1.91 freeswan.
-
-Running between 2 sites with cable modems.  Both  using approximately
-130 mhz pentium.
-
-Transferred files with ncftp.
-
-Compressed file was a 6mb compressed  installation file.
-Non compressed was 18mb /var/lib/rpm/packages.rpm
-
-                            Compressed vpn          regular vpn
-Compress file                42.59 kBs               42.08 kBs
-regular file                110.84 kBs               41.66 kBs
-
-Load  was about 0 either way.
-Ping times were very similar  a bit above 9 ms.
-
-Compression looks attractive to me.
- Later in the same thread, project technical lead Henry Spencer added: -
> is there a reason not to switch compression on?  I have large gateway boxes
-> connecting 3 connections, one of them with a measly DS1 link...
-
-Run some timing tests with and without, with data and loads representative
-of what you expect in production.  That's the definitive way to decide. 
-If compression is a net loss, then obviously, leave it turned off.  If it
-doesn't make much difference, leave it off for simplicity and hence
-robustness.  If there's a substantial gain, by all means turn it on. 
-
-If both ends support compression and can successfully negotiate a
-compressed connection (trivially true if both are FreeS/WAN 1.91), then
-the crucial question is CPU cycles. 
-
-Compression has some overhead, so one question is whether *your* data
-compresses well enough to save you more CPU cycles (by reducing the volume
-of data going through CPU-intensive encryption/decryption) than it costs
-you.  Last time I ran such tests on data that was reasonably compressible
-but not deliberately contrived to be so, this generally was not true --
-compression cost extra CPU cycles -- so compression was worthwhile only if
-the link, not the CPU, was the bottleneck.  However, that was before the
-slow-compression bug was fixed.  I haven't had a chance to re-run those
-tests yet, but it sounds like I'd probably see a different result.
- The bug he refers to was a problem with the compression libraries that - had us using C code, rather than assembler, for compression. It was - fixed before 1.91. -

Methods of measuring

-

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

Testing FreeS/WAN

- This document discusses testing FreeS/WAN. -

Not all types of testing are described here. Other parts of the - documentation describe some tests:

-
-
installation document
-
testing for a successful install
-
configuration document
-
basic tests for a working configuration
-
web links document
-
General information on tests for interoperability between various - IPsec implementations. This includes links to several test sites.
-
interoperation document.
-
More specific information on FreeS/WAN interoperation with other - implementations.
-
performance document
-
performance measurements
-
-

The test setups and procedures described here can also be used in - other testing, but this document focuses on testing the IPsec - functionality of FreeS/WAN.

-

Testing opportunistic connections

-

This section teaches you how to test your opportunistically encrypted - (OE) connections. To set up OE, please see the easy instructions in our quickstart guide.

-

Basic OE Test

-

This test is for basic OE functionality. - - For additional tests, keep - reading.

-

Be sure IPsec is running. You can see whether it is with:

-
    ipsec setup status
-

If need be, you can restart it with:

-
    service ipsec restart
-

Load a FreeS/WAN test website from the host on which you're running - FreeS/WAN. Note: the feds may be watching these sites. Type one of:

-

-
   links oetest.freeswan.org
-
   links oetest.freeswan.nl
- - -

A positive result looks like this:

-
-   You  seem  to  be  connecting  from:  192.0.2.11 which DNS says is:
-   gateway.example.com
-     _________________________________________________________________
-                                                                                
-   Status E-route
-   OE    enabled    16    192.139.46.73/32    ->    192.0.2.11/32   =>
-   tun0x2097@192.0.2.11
-   OE    enabled    176    192.139.46.77/32    ->   192.0.2.11/32   =>
-   tun0x208a@192.0.2.11
-
-

If you see this, congratulations! Your OE box will now encrypt its - own traffic whenever it can. If you have difficulty, see our - OE troubleshooting tips.

-

OE Gateway Test

-

If you've set up FreeS/WAN to protect a subnet behind your gateway, - you'll need to run another simple test, which can be done from a - machine running any OS. That's right, your Windows box can be protected - by opportunistic encryption without any FreeS/WAN install or - configuration on that box. From each protected subnet node -, load the FreeS/WAN website with:

-
   links oetest.freeswan.org
-
   links oetest.freeswan.nl
-

A positive result looks like this:

-
-   You  seem  to  be  connecting  from:  192.0.2.98 which DNS says is:
-   box98.example.com
-     _________________________________________________________________
-                                                                                
-   Status E-route
-   OE    enabled    16    192.139.46.73/32    ->    192.0.2.98/32   =>
-   tun0x134ed@192.0.2.11
-   OE    enabled    176    192.139.46.77/32    ->   192.0.2.11/32   =>
-   tun0x134d2@192.0.2.11
-
-

If you see this, congratulations! Your OE gateway will now encrypt - traffic for this subnet node whenever it can. If you have difficulty, - see our OE troubleshooting tips.

-

Additional OE tests

-

When testing OE, you will often find it useful to execute this - command on the FreeS/WAN host:

-
   ipsec eroute
-

If you have established a connection (either for or for a subnet - node) you will see a result like:

-
    192.0.2.11/32   -> 192.139.46.73/32  => tun0x149f@192.139.46.38
-
-

Key:

- - - - - -
1.192.0.2.11/32Local start point of the - protected traffic.
2.192.0.2.194/32Remote end point of the - protected traffic.
3.192.0.48.38Remote FreeS/WAN node (gateway or - host). May be the same as (2).
4.[not shown]Local FreeS/WAN node (gateway or - host), where you've produced the output. May be the same as (1).
-

For extra assurance, you may wish to use a packet sniffer such as - tcpdump to verify that packets are being encrypted. You should see - output that indicates ESP encrypted data, for example:

-
    02:17:47.353750 PPPoE  [ses 0x1e12] IP 154: xy.example.com > oetest.freeswan.org: ESP(spi=0x87150d16,seq=0x55)
-

Testing with User Mode Linux

-

User Mode Linux - allows you to run Linux as a user process on another Linux machine.

-

As of 1.92, the distribution has a new directory named testing. It - contains a collection of test scripts and sample configurations. Using - these, you can bring up several copies of Linux in user mode and have - them build tunnels to each other. This lets you do some testing of a - FreeS/WAN configuration on a single machine.

-

You need a moderately well-endowed machine for this to work well. - Each UML wants about 16 megs of memory by default, which is plenty for - FreeS/WAN usage. Typical regression testing only occasionally uses as - many as 4 UMLs. If one is doing nothing else with the machine (in - particular, not running X on it), then 128 megs and a 500MHz CPU are - fine.

- Documentation on these scripts is here. - There is also documentation on automated testing - here. -

Configuration for a testbed network

-

A common test setup is to put a machine with dual Ethernet cards in - between two gateways under test. You need at least five machines; two - gateways, two clients and a testing machine in the middle.

-

The central machine both routes packets and provides a place to run - diagnostic software for checking IPsec packets. See next section for - discussion of using tcpdump(8) for this.

-

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.

-

What you end up with looks like:

-

Testbed 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
-
Where p and q are 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.

-

Using packet sniffers in testing

-

A number of tools are available for looking at packets. We will - discuss using tcpdump(8), a - common Linux tool included in most distributions. Alternatives - offerring more-or-less the same functionality include:

-
-
Ethereal
-
Several people on our mailing list report a preference for this over - tcpdump.
-
windump
-
a Windows version of tcpdump(8), possibly handy if you have Windows - boxes in your network
-
-Sniffit
-
A linux sniffer that we don't know much about. If you use it, please - comment on our mailing list.
-
-

See also this - index of packet sniffers.

-

tcpdump(8) may 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.

-

At one point, the problem was quite severe. Recent versions of - tcpdump, however, understand IPsec well enough to be usable on a - gateway. You can get the latest version from - tcpdump.org.

-

Even with a recent tcpdump, some care is required. Here is part of a - post from Henry on the topic:

-
> a) data from sunset to sunrise or the other way is not being
-> encrypted (I am using tcpdump (ver. 3.4) -x/ping -p to check
-> packages) 
-
-What *interface* is tcpdump being applied to?  Use the -i option to
-control this.  It matters!  If tcpdump is looking at the ipsecN
-interfaces, e.g. ipsec0, then it is seeing the packets before they are
-encrypted or after they are decrypted, so of course they don't look
-encrypted.  You want to have tcpdump looking at the actual hardware
-interfaces, e.g. eth0. 
-
-Actually, the only way to be *sure* what you are sending on the wire is to
-have a separate machine eavesdropping on the traffic.  Nothing you can do
-on the machines actually running IPsec is 100% guaranteed reliable in this
-area (although tcpdump is a lot better now than it used to be).
-

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. Network configuration for - such testing is discussed above.

-

Here's another mailing list message with advice on using tcpdump(8):

-
Subject: RE: [Users] Encrypted???
-   Date: Thu, 29 Nov 2001
-   From: "Joe Patterson" <jpatterson@asgardgroup.com>
-
-tcpdump -nl -i $EXT-IF proto 50
-
--nl tells it not to buffer output or resolve names (if you don't do that it
-may confuse you by not outputing anything for a while), -i $EXT-IF (replace
-with your external interface) tells it what interface to listen on, and
-proto 50 is ESP.  Use "proto 51" if for some odd reason you're using AH, and
-"udp port 500" if you want to see the isakmp key exchange/tunnel setup
-packets.
-
-You can also run `tcpdump -nl -i ipsec0` to see what traffic is on that
-virtual interface.  Anything you see there *should* be either encrypted or
-dropped (unless you've turned on some strange options in your ipsec.conf
-file)
-
-Another very handy thing is ethereal (http://www.ethereal.com/) which runs
-on just about anything, has a nice gui interface (or a nice text-based
-interface), and does a great job of protocol  breakdown.  For ESP and AH
-it'll basically just tell you that there's a packet of that protocol, and
-what the spi is, but for isakmp it'll actually show you a lot of the tunnel
-setup information (until it gets to the point in the protocol where isakmp
-is encrypted....)
-

Verifying encryption

-

The question of how to verify that messages are actually encrypted - has been extensively discussed on the mailing list. See this - thread.

-

If you just want to verify that packets are encrypted, look at them - with a packet sniffer (see previous section -) located between the gateways. The packets should, except for some of - the header information, be utterly unintelligible. The output - of good encryption looks exactly like random noise.

-

A packet sniffer can only tell you that the data you looked at was - encrypted. If you have stronger requirements -- for example if your - security policy requires verification that plaintext is not leaked - during startup or under various anomolous conditions -- then you will - need to devise much more thorough tests. If you do that, please post - any results or methodological details which your security policy allows - you to make public.

-

You can put recognizable data into 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 other protocols, you may 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.

-

One thing to watch for: the output of good compression, like that of - good encryption, looks just like random noise. You cannot tell just by - looking at a data stream whether it has been compressed, encrypted, or - both. You need a little care not to mistake compressed data for - encrypted data in your testing.

-

Note also that weak encryption also produces random-looking output. - You cannot tell whether the encryption is strong by looking at the - output. To be sure of that, you would need to have both the algorithms - and the implementation examined by experts.

-

For IPsec, you can get partial assurance from interoperability tests. - See our interop document. When twenty - products all claim to implement 3DES, and they all - talk to each other, you can be fairly sure they have it right. Of - course, you might wonder whether all the implementers are consipring to - trick you or, more plausibly, whether some implementations might have - "back doors" so they can get also it wrong when required.. If you're - seriously worried about things like that, you need to get the code you - use audited (good luck if it is not Open Source), or perhaps to talk to - a psychiatrist about treatments for paranoia.

-

Mailing list pointers

-

Additional information on testing can be found in these - mailing list messages:

- -
-

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:

- -

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 the attacker uses once he or - she has become root on your system. The kit introduces assorted - additional compromises so that the attacker will continue to "own" your - system despite most things you might do to recovery the situation. 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 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.
-
-
-
-
-

Other configuration possibilities

-

This document describes various options for FreeS/WAN configuration - which are less used or more complex (often both) than the standard - cases described in our config and - quickstart documents.

-

Some rules of thumb about configuration

-

Tunnels are cheap

-

Nearly all of the overhead in IPsec processing is in the encryption - and authentication of packets. Our - performance document discusses these overheads.

-

Beside those overheads, the cost of managing additional tunnels is - trivial. Whether your gateway supports one tunnel or ten just does not - matter. A hundred might be a problem; there is a - section on this in the performance document.

-

So, in nearly all cases, if using multiple tunnels gives you a - reasonable way to describe what you need to do, you should describe it - that way in your configuration files.

-

For example, one user recently asked on a mailing list about this - network configuration:

-
        netA---gwA---gwB---netB
-                            |----netC
-
-   netA and B are secured netC not.
-   netA and gwA can not access netC
-

The user had constructed only one tunnel, netA to netB, and wanted to - know how to use ip-route to get netC packets into it. This is entirely - unnecessary. One of the replies was:

-
  The simplest way and indeed the right way to
-  solve this problem is to set up two connections:
-
-        leftsubnet=NetA
-        left=gwA
-        right=gwB
-        rightsubnet=NetB
-  and
-        leftsubnet=NetA
-        left=gwA
-        right=gwB
-        rightsubnet=NetC
-

This would still be correct even if we added nets D, E, F, ... to the - above diagram and needed twenty tunnels.

-

Of course another possibility would be to just use one tunnel, with a - subnet mask that includes both netB and netC (or B, C, D, ...). See - next section.

-

In general, you can construct as many tunnels as you need. Networks - like netC in this example that do not connect directly to the gateway - are fine, as long as the gateway can route to them.

-

The number of tunnels can become an issue if it reaches 50 or so. - This is discussed in the performance document. - Look there for information on supporting hundreds of Road Warriors from - one gateway.

-

If you find yourself with too many tunnels for some reason like - having eight subnets at one location and nine at another so you end up - with 9*8=72 tunnels, read the next section here.

-

Subnet sizes

-

The subnets used in leftsubnet and rightsubnet - can be of any size that fits your needs, and they need not correspond - to physical networks.

-

You adjust the size by changing the subnet mask -, the number after the slash in the subnet description. For example

- -

As an example of using these in connection descriptions, suppose your - company's head office has four physical networks using the address - ranges:

-
-
192.168.100.0/24
-
development
-
192.168.101.0/24
-
production
-
192.168.102.0/24
-
marketing
-
192.168.103.0/24
-
administration
-
-

You can use exactly those subnets in your connection descriptions, or - use larger subnets to grant broad access if required:

-
-
leftsubnet=192.168.100.0/24
-
remote hosts can access only development
-
leftsubnet=192.168.100.0/23
-
remote hosts can access development or production
-
leftsubnet=192.168.102.0/23
-
remote hosts can access marketing or administration
-
leftsubnet=192.168.100.0/22
-
remote hosts can access any of the four departments
-
-

or use smaller subnets to restrict access:

-
-
leftsubnet=192.168.103.0/24
-
remote hosts can access any machine in administration
-
leftsubnet=192.168.103.64/28
-
remote hosts can access only certain machines in administration.
-
leftsubnet=192.168.103.42/32
-
remote hosts can access only one particular machine in - administration
-
-

To be exact, 192.68.103.64/28 means all addresses whose top 28 bits - match 192.168.103.64. There are 16 of these because there are 16 - possibilities for the remainingg 4 bits. Their addresses are - 192.168.103.64 to 192.168.103.79.

-

Each connection description can use a different subnet if required.

-

It is possible to use all the examples above on the same FreeS/WAN - gateway, each in a different connection description, perhaps for - different classes of user or for different remote offices.

-

It is also possible to have multiple tunnels using different - leftsubnet descriptions with the same right. For - example, when the marketing manager is on the road he or she might have - access to:

-
-
leftsubnet=192.168.102.0/24
-
all machines in marketing
-
192.168.101.32/29
-
some machines in production
-
leftsubnet=192.168.103.42/32
-
one particular machine in administration
-
-

This takes three tunnels, but tunnels are cheap. If the laptop is set - up to build all three tunnels automatically, then he or she can access - all these machines concurrently, perhaps from different windows.

-

Other network layouts

-

Here is the usual network picture for a site-to-site VPN::

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

and for the Road Warrior::

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

Other configurations are also possible.

-

The Internet as a big subnet

-

A telecommuter might have:

-
     Sunset==========West------------------East ================= firewall --- the Internet
-         home network      untrusted net        corporate network
-

This can be described as a special case of the general - subnet-to-subnet connection. The subnet on the right is 0.0.0.0/0, the - whole Internet.

-

West (the home gateway) can have its firewall rules set up so that - only IPsec packets to East are allowed out. It will then behave as if - its only connection to the world was a wire to East.

-

When machines on the home network need to reach the Internet, they do - so via the tunnel, East and the corporate firewall. From the viewpoint - of the Internet (perhaps of some EvilDoer trying to break in!), those - home office machines are behind the firewall and protected by it.

-

Wireless

-

Another possible configuration comes up when you do not trust the - local network, either because you have very high security standards or - because your are using easily-intercepted wireless signals.

-

Some wireless networks have built-in encryption called - WEP, but its security is dubious. It is a fairly common practice to - use IPsec instead.

-

In this case, part of your network may look like this:

-
          West-----------------------------East == the rest of your network
-     workstation   untrusted wireless net
-

Of course, there would likely be several wireless workstations, each - with its own IPsec tunnel to the East gateway.

-

The connection descriptions look much like Road Warrior descriptions:

- -

The rightsubnet= parameter might be set in any of several - ways:

-
-
rightsubnet=0.0.0.0/0
-
allowing workstations to access the entire Internet (see - above)
-
rightsubnet=a.b.c.0/24
-
allowing access to your entire local network
-
rightsubnet=a.b.c.d/32
-
restricting the workstation to connecting to a particular server
-
-

Of course you can mix and match these as required. For example, a - university might allow faculty full Internet access while letting - student laptops connect only to a group of lab machines.

-

Choosing connection types

-

One choice 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 --up 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: - -

A third method, using RSA keys embedded in X.509 - certtificates, is provided by user patches.

-
-
-

Manually keyed connections provide weaker - security than automatically keyed connections. An - opponent who reads ipsec.secrets(5) gets your encryption key and can - read all data encrypted by it. If he or she has an archive of old - messages, all of them back to your last key change are also readable.

-

With automatically-(re)-keyed connections, an opponent who reads - ipsec.secrets(5) gets the key used to authenticate your system in IKE - -- the shared secret or your private key, depending what authentication - mechanism is in use. However, he or she does not automatically gain - access to any encryption keys or any data.

-

An attacker who has your authentication key can mount a - man-in-the-middle attack and, if that succeeds, he or she will get - encryption keys and data. This is a serious danger, but it is better - than having the attacker read everyting as soon as he or she breaks - into ipsec.secrets(5).. Moreover, the keys change often so an opponent - who gets one key does not get a large amount of data. To read all your - data, he or she would have to do a man-in-the-middle attack at every - key change.

-

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 may also be useful for testing. There is some - discussion of this in our FAQ.

-

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 - support two basic methods for this authentication:

- -

There are, howver, several variations on the RSA theme, using - different methods of managing the RSA keys:

- -

Public keys in ipsec.conf(5 -) give a reasonably straightforward method of specifying keys for - explicitly configured connections.

-

Putting public keys in DNS allows us to support - opportunistic encryption. Any two FreeS/WAN gateways can provide - secure communication, without either of them having any preset - information about the other.

-

X.509 certificates may be required to interface to various - PKIs.

-

Advantages of public key methods

-

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

- -

There is also a disadvantage:

- -

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.

-

What I call "shared secrets" are sometimes also called "pre-shared - keys". They are used only for for authentication, never for encryption. - Calling them "pre-shared keys" has confused some users into thinking - they were encryption keys, so I prefer to avoid the term..

-

If you are interoperating with another IPsec implementation, you may - find its documentation calling them "passphrases".

-

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:

- -

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. This is discussed in more detail - above.

-

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.

- -

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:

- -

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:

- -

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

An Opportunistic Gateway

-

Start from full opportunism

-

Full opportunism allows you to initiate and receive opportunistic - connections on your machine. The remaining instructions in this section - assume you have first set up full opportunism on your gateway using - these instructions. Both sets of instructions require mailing DNS - records to your ISP. Collect DNS records for both the gateway (above) - and the subnet nodes (below) before contacting your ISP.

-

Reverse DNS TXT records for each protected machine -

-

You need these so that your Opportunistic peers can:

- -

On the gateway, generate a TXT record with:

-
    ipsec showhostkey --txt 192.0.2.11
-

Use your gateway address in place of 192.0.2.11.

-

You should see (keys are trimmed for clarity throughout our example):

-
    ; RSA 2048 bits  gateway.example.com   Sat Apr 15 13:53:22 2000
-    IN TXT  "X-IPsec-Server(10)=192.0.2.11" " AQOF8tZ2...+buFuFn/"
-

This MUST BE the same key as in your gateway's TXT record, or - nothing will work.

-

In a text file, make one copy of this TXT record for each subnet - node:

-
    ; RSA 2048 bits  gateway.example.com   Sat Apr 15 13:53:22 2000
-    IN TXT  "X-IPsec-Server(10)=192.0.2.11" " AQOF8tZ2...+buFuFn/"
-                                                                                
-    ; RSA 2048 bits  gateway.example.com   Sat Apr 15 13:53:22 2000
-    IN TXT  "X-IPsec-Server(10)=192.0.2.11" " AQOF8tZ2...+buFuFn/"
-                                                                                
-    ; RSA 2048 bits  gateway.example.com   Sat Apr 15 13:53:22 2000
-    IN TXT  "X-IPsec-Server(10)=192.0.2.11" " AQOF8tZ2...+buFuFn/"
-

Above each entry, insert a line like this:

-
    98.2.0.192.in-addr.arpa. IN PTR arthur.example.com.
-

It must include:

- -

The result will be a file of TXT records, like this:

-
    98.2.0.192.in-addr.arpa. IN PTR arthur.example.com.
-    ; RSA 2048 bits  gateway.example.com   Sat Apr 15 13:53:22 2000
-    IN TXT  "X-IPsec-Server(10)=192.0.2.11" " AQOF8tZ2...+buFuFn/"
-                                                                                
-    99.2.0.192.in-addr.arpa. IN PTR ford.example.com.
-    ; RSA 2048 bits  gateway.example.com   Sat Apr 15 13:53:22 2000
-    IN TXT  "X-IPsec-Server(10)=192.0.2.11" " AQOF8tZ2...+buFuFn/"
-                                                                                
-    100.2.0.192.in-addr.arpa. IN PTR trillian.example.com.
-    ; RSA 2048 bits  gateway.example.com   Sat Apr 15 13:53:22 2000
-    IN TXT  "X-IPsec-Server(10)=192.0.2.11" " AQOF8tZ2...+buFuFn/"
-

Publish your records

-

Ask your ISP to publish all the reverse DNS records you have - collected. There may be a delay of up to 48 hours as the records - propagate.

-

...and test them

-

Check a couple of records with commands like this one:

-
    ipsec verify --host ford.example.com
-    ipsec verify --host trillian.example.com
-

The verify command checks for TXT records for both the - subnet host and its gateway. You should see output like:

-
    ...
-    Looking for TXT in reverse map: 99.2.0.192.in-addr.arpa [OK]
-    ...
-    Looking for TXT in reverse map: 11.2.0.192.in-addr.arpa   [OK]
-    ...
-    Looking for TXT in reverse map: 100.2.0.192.in-addr.arpa [OK]
-    ...
-    Looking for TXT in reverse map: 11.2.0.192.in-addr.arpa   [OK]
-    ...
-

No Configuration Needed

-

FreeS/WAN 2.x ships with a built-in, automatically enabled OE - connection conn packetdefault which applies OE, if possible, - to all outbound traffic routed through the FreeS/WAN box. The - ipsec.conf(5) manual describes this connection in detail. While the - effect is much the same as private-or-clear, the - implementation is different: notably, it does not use policy groups.

-

You can create more complex OE configurations for traffic forwarded - through a FreeS/WAN box, as explained in our - policy groups document, or disable OE using - these instructions.

-

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.

-

As far as the Internet is concerned, your new extruded net is behind - your buddy's gateway. You route all your packets for the Internet at - large out his gateway, and receive return packets the same way. You - route your local packets locally.

-

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

-

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, you'll need to poke holes in your - firewall to allow packets through.

-

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

-

Please note that Super - FreeS/WAN now features DHCP-over-IPsec, which is an alternate - procedure for Virtual IP address assignment.

-

-

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.

- -

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.

- -

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.

-
-

Installing FreeS/WAN

-

This document will teach you how to install Linux FreeS/WAN. If your - distribution comes with Linux FreeS/WAN, we offer tips to get you - started.

-

Requirements

-

To install FreeS/WAN you must:

- -

Choose your install method

-

There are three basic ways to get FreeS/WAN onto your system:

- - -

FreeS/WAN ships with some Linuxes

-

FreeS/WAN comes with these distributions.

-

If you're running one of these, include FreeS/WAN in the choices you - make during installation, or add it later using the distribution's - tools.

-

FreeS/WAN may be altered...

-

Your distribution may have integrated extra features, such as Andreas - Steffen's X.509 patch, into FreeS/WAN. It may also use custom startup - script locations or directory names.

-

You might need to create an authentication keypair -

-

If your FreeS/WAN came with your distribution, you may wish to - generate a fresh RSA key pair. FreeS/WAN will use these keys for - authentication.

-

To do this, become root, and type:

-
    ipsec newhostkey --output /etc/ipsec.secrets --hostname xy.example.com
-    chmod 600 /etc/ipsec.secrets
-

where you replace xy.example.com with your machine's fully-qualified - domain name. Generate some randomness, for example by wiggling your - mouse, to speed the process.

-

The resulting ipsec.secrets looks like:

-
: RSA   {
-        # RSA 2192 bits   xy.example.com   Sun Jun 8 13:42:19 2003
-        # for signatures only, UNSAFE FOR ENCRYPTION
-        #pubkey=0sAQOFppfeE3cC7wqJi...
-        Modulus: 0x85a697de137702ef0...
-        # everything after this point is secret
-        PrivateExponent: 0x16466ea5033e807...
-        Prime1: 0xdfb5003c8947b7cc88759065...
-        Prime2: 0x98f199b9149fde11ec956c814...
-        Exponent1: 0x9523557db0da7a885af90aee...
-        Exponent2: 0x65f6667b63153eb69db8f300dbb...
-        Coefficient: 0x90ad00415d3ca17bebff123413fc518...
-        }
-# do not change the indenting of that "}"
-

In the actual file, the strings are much longer.

-

Start and test FreeS/WAN

-

You can now start FreeS/WAN and test whether - it's been successfully installed..

- -

RPM install

-

These instructions are for a recent Red Hat with a stock Red Hat - kernel. We know that Mandrake and SUSE also produce FreeS/WAN RPMs. If - you're running either, install using your distribution's tools.

-

Download RPMs

-

Decide which functionality you need:

- - -

For 2.6 kernels, get the latest FreeS/WAN userland RPM, for example:

-
    freeswan-userland-2.04.9-0.i386.rpm
-

Note: FreeS/WAN's support for 2.6 kernel IPsec is preliminary. Please - see 2.6.known-issues, and the latest - mailing list reports.

-

Change to your new FreeS/WAN directory, and make and install the

-

For 2.4 kernels, get both kernel and userland RPMs. Check your kernel - version with

-
    uname -r
-

Get a kernel module which matches that version. For example:

-
    freeswan-module-2.04_2.4.20_20.9-0.i386.rpm
-

Note: These modules will only work on the Red Hat kernel they were - built for, since they are very sensitive to small changes in the - kernel.

-

Get FreeS/WAN utilities to match. For example:

-
    freeswan-userland-2.04_2.4.20_20.9-0.i386.rpm
-

For freeswan.org RPMs: check signatures

-

While you're at our ftp site, grab the RPM signing key

-
    freeswan-rpmsign.asc
-

If you're running RedHat 8.x or later, import this key into the RPM - database:

-
    rpm --import freeswan-rpmsign.asc
-

For RedHat 7.x systems, you'll need to add it to your - PGP keyring:

-
    pgp -ka freeswan-rpmsign.asc
-

Check the digital signatures on both RPMs using:

-
    rpm --checksig freeswan*.rpm
-

You should see that these signatures are good:

-
    freeswan-module-2.04_2.4.20_20.9-0.i386.rpm: pgp md5 OK
-    freeswan-userland-2.04_2.4.20_20.9-0.i386.rpm: pgp md5 OK
-

Install the RPMs

-

Become root:

-
    su
-

For a first time install, use:

-
    rpm -ivh freeswan*.rpm
-

To upgrade existing RPMs (and keep all .conf files in place), use:

-
    rpm -Uvh freeswan*.rpm
-

If you're upgrading from FreeS/WAN 1.x to 2.x RPMs, and encounter - problems, see this note.

-

Start and Test FreeS/WAN

-

Now, start FreeS/WAN and test your install.

- -

Install from Source

- - -

Decide what functionality you need

-

Your choices are:

- -

Download FreeS/WAN

-

Download the source tarball you've chosen, along with any patches.

-

For freeswan.org source: check its signature

-

While you're at our ftp site, get our source signing key

-
    freeswan-sigkey.asc
-

Add it to your PGP keyring:

-
    pgp -ka freeswan-sigkey.asc
-

Check the signature using:

-
    pgp freeswan-2.04.tar.gz.sig freeswan-2.04.tar.gz
-

You should see something like:

-
    Good signature from user "Linux FreeS/WAN Software Team (build@freeswan.org)".
-    Signature made 2002/06/26 21:04 GMT using 2047-bit key, key ID 46EAFCE1
- - -

Untar, unzip

-

As root, unpack your FreeS/WAN source into /usr/src.

-
    su
-    mv freeswan-2.04.tar.gz /usr/src
-    cd /usr/src
-    tar -xzf freeswan-2.04.tar.gz
-
-

Patch if desired

-

Now's the time to add any patches. The contributor may have special - instructions, or you may simply use the patch command.

-

... and Make

-

Choose one of the methods below.

-

Userland-only Install for 2.6 kernels

- -

Note: FreeS/WAN's support for 2.6 kernel IPsec is preliminary. Please - see 2.6.known-issues, and the latest - mailing list reports.

-

Change to your new FreeS/WAN directory, and make and install the - FreeS/WAN userland tools.

-
    cd /usr/src/freeswan-2.04
-    make programs
-    make install
-

Now, start FreeS/WAN and test your install.

-

KLIPS install for 2.2, 2.4, or 2.6 kernels

- -

To make a modular version of KLIPS, along with other FreeS/WAN - programs you'll need, use the command sequence below. This will change - to your new FreeS/WAN directory, make the FreeS/WAN module (and other - stuff), and install it all.

-
    cd /usr/src/freeswan-2.04
-    make oldmod
-    make minstall
-

Start FreeS/WAN and test your install.

-

To link KLIPS statically into your kernel (using your old kernel - settings), and install other FreeS/WAN components, do:

-
    cd /usr/src/freeswan-2.04
-    make oldmod
-    make minstall
-

Reboot your system and test your install.

-

For other ways to compile KLIPS, see our Makefile.

- -

Start FreeS/WAN and test your install

-

Bring FreeS/WAN up with:

-
    service ipsec start
-

This is not necessary if you've rebooted.

- -

Test your install

-

To check that you have a successful install, run:

-
    ipsec verify
-

You should see at least:

-
-    Checking your system to see if IPsec got installed and started correctly
-    Version check and ipsec on-path                             [OK]
-    Checking for KLIPS support in kernel                        [OK]
-    Checking for RSA private key (/etc/ipsec.secrets)           [OK]
-    Checking that pluto is running                              [OK]
-
-

If any of these first four checks fails, see our - troubleshooting guide.

-

Making FreeS/WAN play well with others

-

There are at least a couple of things on your system that might - interfere with FreeS/WAN, and now's a good time to check these:

- -

Configure for your needs

-

You'll need to configure FreeS/WAN for your local site. Have a look - at our opportunism quickstart guide to - see if that easy method is right for your needs. Or, see how to - configure a network-to-network or Road Warrior style VPN.

-
-

How to configure FreeS/WAN

-

This page will teach you how to configure a simple network-to-network - link or a Road Warrior connection between two Linux FreeS/WAN boxes.

-

See also these related documents:

- -

The network-to-network setup allows you to connect two office - networks into one Virtual Private Network, while the Road Warrior - connection secures a laptop's telecommute to work. Our examples also - show the basic procedure on the Linux FreeS/WAN side where another - IPsec peer is in play.

-

Shortcut to net-to-net. -
Shortcut to Road Warrior.

-

Requirements

-

To configure the network-to-network connection you must have:

- -

For the Road Warrior you need:

- -

If both IPs are dynamic, your situation is a bit trickier. Your best - bet is a variation on the Road Warrior, as - described in - this mailing list message.

-

Net-to-Net connection

-

Gather information

-

For each gateway, compile the following information:

- -

Get your leftrsasigkey

-

On your local Linux FreeS/WAN gateway, print your IPsec public key:

-
    ipsec showhostkey --left
-

The output should look like this (with the key shortened for easy - reading):

-
    # RSA 2048 bits   xy.example.com   Fri Apr 26 15:01:41 2002
-    leftrsasigkey=0sAQOnwiBPt...
-

Don't have a key? Use - ipsec newhostkey to create one.

-

...and your rightrsasigkey

-

Get a console on the remote side:

-
    ssh2 ab.example.com
-

In that window, type:

-
    ipsec showhostkey --right
-

You'll see something like:

-
    # RSA 2192 bits   ab.example.com   Thu May 16 15:26:20 2002
-    rightrsasigkey=0sAQOqH55O...
-

Edit /etc/ipsec.conf

-

Back on the local gate, copy our template to /etc/ipsec.conf -. (on Mandrake, /etc/freeswan/ipsec.conf). Substitute the - information you've gathered for our example data.

-
conn net-to-net
-    left=192.0.2.2                 # Local vitals
-    leftsubnet=192.0.2.128/29      # 
-    leftid=@xy.example.com         #   
-    leftrsasigkey=0s1LgR7/oUM...   #
-    leftnexthop=%defaultroute      # correct in many situations 
-    right=192.0.2.9                # Remote vitals
-    rightsubnet=10.0.0.0/24        #
-    rightid=@ab.example.com        # 
-    rightrsasigkey=0sAQOqH55O...   #
-    rightnexthop=%defaultroute     # correct in many situations
-    auto=add                       # authorizes but doesn't start this 
-                                   # connection at startup
-

"Left" and "right" should represent the machines that have FreeS/WAN - installed on them, and "leftsubnet" and "rightsubnet" machines that are - being protected. /32 is assumed for left/right and left/rightsubnet - parameters.

-

Copy conn net-to-net to the remote-side /etc/ipsec.conf. - If you've made no other modifications to either ipsec.conf, - simply:

-
    scp2 ipsec.conf root@ab.example.com:/etc/ipsec.conf
-

Start your connection

-

Locally, type:

-
    ipsec auto --up net-to-net
-

You should see:

-
    104 "net-net" #223: STATE_MAIN_I1: initiate
-    106 "net-net" #223: STATE_MAIN_I2: sent MI2, expecting MR2
-    108 "net-net" #223: STATE_MAIN_I3: sent MI3, expecting MR3
-    004 "net-net" #223: STATE_MAIN_I4: ISAKMP SA established
-    112 "net-net" #224: STATE_QUICK_I1: initiate
-    004 "net-net" #224: STATE_QUICK_I2: sent QI2, IPsec SA established
-

The important thing is IPsec SA established. If you're - unsuccessful, see our troubleshooting tips.

-

Do not MASQ or NAT packets to be tunneled

-

If you are using IP masquerade or - Network Address Translation (NAT) on either gateway, you must now - exempt the packets you wish to tunnel from this treatment. For example, - if you have a rule like:

-
iptables -t nat -A POSTROUTING -o eth0 -s 10.0.0.0/24 -j MASQUERADE
-
-

change it to something like:

-
iptables -t nat -A POSTROUTING -o eth0 -s 10.0.0.0/24 -d \! 192.0.2.128/29 -j MASQUERADE
-

This may be necessary on both gateways.

-

Test your connection

-

Sit at one of your local subnet nodes (not the gateway), and ping a - subnet node on the other (again, not the gateway).

-
    ping fileserver.toledo.example.com
-

While still pinging, go to the local gateway and snoop your outgoing - interface, for example:

-
    tcpdump -i ppp0
-

You want to see ESP (Encapsulating Security Payload) packets moving - back and forth between the two gateways at the same frequency as - your pings:

-
    19:16:32.046220 192.0.2.2 > 192.0.2.9: ESP(spi=0x3be6c4dc,seq=0x3)
-    19:16:32.085630 192.0.2.9 > 192.0.2.2: ESP(spi=0x5fdd1cf8,seq=0x6)
-

If you see this, congratulations are in order! You have a tunnel - which will protect any IP data from one subnet to the other, as it - passes between the two gates. If not, go and - troubleshoot.

-

Note: your new tunnel protects only net-net traffic, not - gateway-gateway, or gateway-subnet. If you need this (for example, if - machines on one net need to securely contact a fileserver on the IPsec - gateway), you'll need to create extra connections -.

-

Finishing touches

-

Now that your connection works, name it something sensible, like:

-
conn winstonnet-toledonet
-

To have the tunnel come up on-boot, replace

-
    auto=add
-

with:

-
    auto=start
-

Copy these changes to the other side, for example:

-
    scp2 ipsec.conf root@ab.example.com:/etc/ipsec.conf
-

Enjoy!

-

Road Warrior Configuration

-

Gather information

-

You'll need to know:

- -

Get your leftrsasigkey...

-

On your laptop, print your IPsec public key:

-
    ipsec showhostkey --left
-

The output should look like this (with the key shortened for easy - reading):

-
    # RSA 2192 bits   road.example.com   Sun Jun  9 02:45:02 2002
-    leftrsasigkey=0sAQPIPN9uI...
-

Don't have a key? See these - instructions.

-

...and your rightrsasigkey

-

Get a console on the gateway:

-
    ssh2 xy.example.com
-

View the gateway's public key with:

-
    ipsec showhostkey --right
-

This will yield something like

-
    # RSA 2048 bits   xy.example.com   Fri Apr 26 15:01:41 2002
-    rightrsasigkey=0sAQOnwiBPt...
-

Customize /etc/ipsec.conf

-

On your laptop, copy this template to /etc/ipsec.conf. (on - Mandrake, /etc/freeswan/ipsec.conf). Substitute the - information you've gathered for our example data.

-
conn road
-    left=%defaultroute             # Picks up our dynamic IP 
-    leftnexthop=%defaultroute      # 
-    leftid=@road.example.com       # Local information
-    leftrsasigkey=0sAQPIPN9uI...   #
-    right=192.0.2.10               # Remote information
-    rightsubnet=10.0.0.0/24        #
-    rightid=@xy.example.com        # 
-    rightrsasigkey=0sAQOnwiBPt...  #
-    auto=add                       # authorizes but doesn't start this
-                                   # connection at startup
-

The template for the gateway is different. Notice how it reverses - left and right, in keeping with our convention that - Left is Local, Right - Remote. Be sure to switch your rsasigkeys in keeping with - this.

-
    ssh2 xy.example.com
-    vi /etc/ipsec.conf
-

and add:

-
conn road
-    left=192.0.2.2                 # Gateway's information
-    leftid=@xy.example.com         #
-    leftsubnet=192.0.2.128/29      #
-    leftrsasigkey=0sAQOnwiBPt...   #
-    rightnexthop=%defaultroute     # correct in many situations
-    right=%any                     # Wildcard: we don't know the laptop's IP
-    rightid=@road.example.com      #
-    rightrsasigkey=0sAQPIPN9uI...  #
-    auto=add                       # authorizes but doesn't start this
-                                   # connection at startup
-

Start your connection

-

You must start the connection from the Road Warrior side. On your - laptop, type:

-
    ipsec auto --start net-to-net
-

You should see:

-
104 "net-net" #223: STATE_MAIN_I1: initiate
-106 "road" #301: STATE_MAIN_I2: sent MI2, expecting MR2
-108 "road" #301: STATE_MAIN_I3: sent MI3, expecting MR3
-004 "road" #301: STATE_MAIN_I4: ISAKMP SA established
-112 "road" #302: STATE_QUICK_I1: initiate
-004 "road" #302: STATE_QUICK_I2: sent QI2, IPsec SA established
-

Look for IPsec SA established. If you're unsuccessful, see - our troubleshooting tips.

-

Do not MASQ or NAT packets to be tunneled

-

If you are using IP masquerade or - Network Address Translation (NAT) on either gateway, you must now - exempt the packets you wish to tunnel from this treatment. For example, - if you have a rule like:

-
iptables -t nat -A POSTROUTING -o eth0 -s 10.0.0.0/24 -j MASQUERADE
-
-

change it to something like:

-
iptables -t nat -A POSTROUTING -o eth0 -s 10.0.0.0/24 -d \! 192.0.2.128/29 -j MASQUERADE
-

Test your connection

-

From your laptop, ping a subnet node behind the remote gateway. Do - not choose the gateway itself for this test.

-
    ping ns.winston.example.com
-

Snoop the packets exiting the laptop, with a command like:

-
    tcpdump -i wlan0
-

You have success if you see (Encapsulating Security Payload) packets - travelling in both directions:

-
    19:16:32.046220 192.0.2.2 > 192.0.2.9: ESP(spi=0x3be6c4dc,seq=0x3)
-    19:16:32.085630 192.0.2.9 > 192.0.2.2: ESP(spi=0x5fdd1cf8,seq=0x6)
-

If you do, great! Traffic between your Road Warrior and the net - behind your gateway is protected. If not, see our - troubleshooting hints.

-

Your new tunnel protects only traffic addressed to the net, not to - the IPsec gateway itself. If you need the latter, you'll want to make - an extra tunnel..

-

Finishing touches

-

On both ends, name your connection wisely, like:

-
conn mike-to-office
-

On the laptop only, replace

-
    auto=add
-

with:

-
    auto=start
-

so that you'll be connected on-boot.

-

Happy telecommuting!

-

Multiple Road Warriors

-

If you're using RSA keys, as we did in this example, you can add as - many Road Warriors as you like. The left/rightid parameter lets Linux - FreeS/WAN distinguish between multiple Road Warrior peers, each with - its own public key.

-

The situation is different for shared secrets (PSK). During a PSK - negotiation, ID information is not available at the time Pluto is - trying to determine which secret to use, so, effectively, you can only - define one Roadwarrior connection. All your PSK road warriors must - therefore share one secret.

-

What next?

-

Using the principles illustrated here, you can try variations such - as:

- -

Or, look at some of our more complex - configuration examples..

-
-

Linux FreeS/WAN background

-

This section discusses a number of issues which have three things in - common:

- -

Grouping them here lets us provide the explanations some users will - need without unduly complicating the main text.

-

The explanations here are intended to be adequate for FreeS/WAN - purposes (please comment to the users mailing list - if you don't find them so), but they are not trying to be complete or - definitive. If you need more information, see the references provided - in each section.

-

Some DNS background

-

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

-

Much good reference material is available for DNS, including:

- -

We give only a brief overview here, intended to help you use DNS for - FreeS/WAN purposes.

-

Forward and reverse maps

-

Although the implementation is distributed, it is often useful to - speak of DNS as if it were just two enormous tables:

- -

Both maps can optionally contain additional data. For opportunistic - encryption, we insert the data need for IPsec authentication.

-

A system named gateway.example.com with IP address 10.20.30.40 should - have at least two DNS records, one in each map:

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

Hierarchy and delegation

-

For both maps there is a hierarchy of DNS servers and a system of - delegating authority so that, for example:

- -

DNS zones are the units of delegation. There is a hierarchy of zones.

-

Syntax of DNS records

-

Returning to the example records:

-
        gateway.example.com. IN A 10.20.30.40
-        40.30.20.10.in-addr.arpa. IN PTR gateway.example.com.
-

some syntactic details are:

- -

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

- -

To set up for opportunistic encryption, you add some TXT records to - your DNS data. Details are in our quickstart - document.

-

Cacheing, TTL and propagation delay

-

DNS information is extensively cached. With no caching, a lookup by - your system of "www.freeswan.org" might involve:

- -

However, this can be a bit inefficient. For example, if you are in - the Phillipines, the closest a root server is in Japan. That might send - you to a .org server in the US, and then to freeswan.org in Holland. If - everyone did all those lookups every time they clicked on a web link, - the net would grind to a halt.

-

Nameservers therefore cache information they look up. When you click - on another link at www.freeswan.org, your local nameserver has the IP - address for that server in its cache, and no further lookups are - required.

-

Intermediate results are also cached. If you next go to - lists.freeswan.org, your nameserver can just ask the freeswan.org - nameserver for that address; it does not need to query the root or .org - nameservers because it has a cached address for the freeswan.org zone - server.

-

Of course, like any cacheing mechanism, this can create problems of - consistency. What if the administrator for freeswan.org changes the IP - address, or the authentication key, for www.freeswan.org? If you use - old information from the cache, you may get it wrong. On the other - hand, you cannot afford to look up fresh information every time. Nor - can you expect the freeswan.org server to notify you; that isn't in the - protocols.

-

The solution that is in the protocols is fairly simple. Cacheable - records are marked with Time To Live (TTL) information. When the time - expires, the caching server discards the record. The next time someone - asks for it, the server fetches a fresh copy. Of course, a server may - also discard records before their TTL expires if it is running out of - cache space.

-

This implies that there will be some delay before the new version of - a changed record propagates around the net. Until the TTLs on all - copies of the old record expire, some users will see it because that is - what is in their cache. Other users may see the new record immediately - because they don't have an old one cached.

-

Problems with packet fragmentation

-

It seems, from mailing list reports, to be moderately common for - problems to crop up in which small packets pass through the IPsec - tunnels just fine but larger packets fail.

-

These problems are caused by various devices along the way - mis-handling either packet fragments or path MTU - discovery.

-

IPsec makes packets larger by adding an ESP or AH header. This can - tickle assorted bugs in fragment handling in routers and firewalls, or - in path MTU discovery mechanisms, and cause a variety of symptoms which - are both annoying and, often, quite hard to diagnose.

-

An explanation from project technical lead Henry Spencer:

-
The problem is IP fragmentation; more precisely, the problem is that the
-second, third, etc. fragments of an IP packet are often difficult for
-filtering mechanisms to classify.
-
-Routers cannot rely on reassembling the packet, or remembering what was in
-earlier fragments, because the fragments may be out of order or may even
-follow different routes.  So any general, worst-case filtering decision
-pretty much has to be made on each fragment independently.  (If the router
-knows that it is the only route to the destination, so all fragments
-*must* pass through it, reassembly would be possible... but most routers
-don't want to bother with the complications of that.)
-
-All fragments carry roughly the original IP header, but any higher-level
-header is (for IP purposes) just the first part of the packet data... so
-only the first fragment carries that.  So, for example, on examining the
-second fragment of a TCP packet, you could tell that it's TCP, but not
-what port number it is destined for -- that information is in the TCP
-header, which appears in the first fragment only. 
-
-The result of this classification difficulty is that stupid routers and
-over-paranoid firewalls may just throw fragments away.  To get through
-them, you must reduce your MTU enough that fragmentation will not occur.
-(In some cases, they might be willing to attempt reassembly, but have very
-limited resources to devote to it, meaning that packets must be small and
-fragments few in number, leading to the same conclusion:  smaller MTU.)
-

In addition to the problem Henry describes, you may also have trouble - with path MTU discovery.

-

By default, FreeS/WAN uses a large MTU for the - ipsec device. This avoids some problems, but may complicate others. - Here's an explanation from Claudia:

-
Here are a couple of pieces of background information. Apologies if you
-have seen these already. An excerpt from one of my old posts:
-
-    An MTU of 16260 on ipsec0 is usual. The IPSec device defaults to this 
-    high MTU so that it does not fragment incoming packets before encryption 
-    and encapsulation. If after IPSec processing packets are larger than 1500,
-    [ie. the mtu of eth0] then eth0 will fragment them. 
-
-    Adding IPSec headers adds a certain number of bytes to each packet. 
-    The MTU of the IPSec interface refers to the maximum size of the packet
-    before the IPSec headers are added. In some cases, people find it helpful 
-    to set ipsec0's MTU to 1500-(IPSec header size), which IIRC is about 1430.
-
-    That way, the resulting encapsulated packets don't exceed 1500. On most 
-    networks, packets less than 1500 will not need to be fragmented.
-
-and... (from Henry Spencer)
-
-    The way it *ought* to work is that the MTU advertised by the ipsecN
-    interface should be that of the underlying hardware interface, less a
-    pinch for the extra headers needed. 
-
-    Unfortunately, in certain situations this breaks many applications.
-    There is a widespread implicit assumption that the smallest MTUs are 
-    at the ends of paths, not in the middle, and another that MTUs are 
-    never less than 1500.  A lot of code is unprepared to handle paths 
-    where there is an "interior minimum" in the MTU, especially when it's 
-    less than 1500. So we advertise a big MTU and just let the resulting 
-    big packets fragment.
-
-This usually works, but we do get bitten in cases where some intermediate
-point can't handle all that fragmentation.  We can't win on this one.
-

The MTU can be changed with an overridemtu= statement in - the config setup section of - ipsec.conf.5.

-

For a discussion of MTU issues and some possible solutions using - Linux advanced routing facilities, see the - Linux 2.4 Advanced Routing HOWTO. For a discussion of MTU and NAT - (Network Address Translation), see - James Carter's MTU notes.

-

Network address translation (NAT)

-

Network Address T -ranslation is a service provided by some gateway machines. Calling it - NAPT (adding the word Port) would be more precise, but - we will follow the widespread usage.

-

A gateway doing NAT rewrites the headers of packets it is forwarding, - changing one or more of:

- -

On Linux 2.4, NAT services are provided by the - netfilter(8) firewall code. There are several - Netfilter HowTos including one on NAT.

-

For older versions of Linux, this was referred to as "IP masquerade" - and different tools were used. See this - resource page.

-

Putting an IPsec gateway behind a NAT gateway is not recommended. See - our firewalls document.

-

NAT to non-routable addresses

-

The most common application of NAT uses private - non-routable addresses.

-

Often a home or small office network will have:

- -

Of course this poses a problem since several machines cannot use one - address. The best solution might be to obtain more addresses, but often - this is impractical or uneconomical.

-

A common solution is to have:

- -

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.

-

As far as anyone else on the Internet is concerned, the systems - behind the gateway are completely hidden. Only one machine with one IP - address is visible.

-

For IPsec on such a gateway, you can entirely ignore the NAT in:

- -

Those can be set up exactly as they would be if your gateway had no - other systems behind it.

-

You do, however, have to take account of the NAT in firewall rules - which affect packet forwarding.

-

NAT to routable addresses

-

NAT to routable addresses is also possible, but is less common and - may make for rather tricky routing problems. We will not discuss it - here. See the - Netfilter HowTos.

-
-

FreeS/WAN script examples

- This file is intended to hold a collection of user-written example - scripts or configuration files for use with FreeS/WAN. -

So far it has only one entry.

-

Poltorak's Firewall script

-
-From: Poltorak Serguei <poltorak@dataforce.net>
-Subject: [Users] Using FreeS/WAN
-Date: Tue, 16 Oct 2001
-
-Hello.
-
-I'm using FreeS/WAN IPsec for half a year. I learned a lot of things about
-it and I think it would be interesting for someone to see the result of my
-experiments and usage of FreeS/WAN. If you find a mistake in this
-file, please e-mail me. And excuse me for my english... I'm learning.. :)
-
-I'll talk about vary simple configuration:
-
-addresses prefix = 192.168
-
-    lan1          sgw1     .0.0/24 (Internet)       sgw2            lan2
-  .1.0/24---[ .1.1 ; .0.1 ]===================[ .0.10 ; . 2.10 ]---.2.0/24
-
-
-We need to let lan1 see lan2 across Internet like it is behind sgw1. The
-same for lan2. And we need to do IPX bridge for Novel Clients and NDS
-synchronization.
-
-my config:
-------------------- ipsec.conf -------------------
-conn lan1-lan2
-        type=tunnel
-        compress=yes
-        #-------------------
-        left=192.168.0.1
-        leftsubnet=192.168.1.0/24
-        #-------------------
-        right=192.168.0.10
-        rightsubnet=192.168.2.0/24
-        #-------------------
-        auth=esp
-        authby=secret
---------------- end of ipsec.conf ----------------
-
-ping .2.x from .1.y   (y != 1)
-It works?? Fine. Let's continue...
-
-Why y != 1 ?? Because kernel of sgw1 have 2 IP addresses and it will choose
-the first IP (which is used to go to Internet) .0.1 and the packet won't go
-through IPsec tunnel :(  But if do ping on .1.1 kernel will respond from
-that address (.1.1) and the packet will be tunneled. The same problem occurred then
-.2.x sends a packet to .1.2 which is down at the moment. What happens? .1.1
-sends ARP requesting .1.2... after 3 tries it send to .2.x an destunreach,
-but from his "natural" IP or .0.1 . So the error message won't be delivered!
-It's a big problem...
-
-Resolution... One can manipulate with ipsec0 or ipsec0:0 to solve the
-problem (if ipsec0 has .1.1 kernel will send packets correctly), but there
-are powerful and elegant iproute2 :) We simply need to change source address
-of packet that goes to other secure lan. This is done with
-
-ip route replace 192.168.2.0/24 via 192.168.0.10 dev ipsec0 src 192.168.1.1
-
-Cool!! Now it works!!
-
-The second step. We want install firewall on sgw1 and sgw2. Encryption of 
-traffic without security isn't a good idea. I don't use {left|right}firewall, 
-because I'm running firewall from init scripts.
-
-We want IPsec data between lan1-lan2, some ICMP errors (destination
-unreachable, TTL exceeded, parameter problem and source quench), replying on 
-pings from both lans and Internet, ipxtunnel data for IPX and of course SSH
-between sgw1 and sgw2 and from/to one specified host.
-
-I'm using ipchains. With iptables there are some changes.
-
----------------- rc.firewall ---------------------
-#!/bin/sh
-#
-# Firewall for IPsec lan1-lan2
-#
-
-IPC=/sbin/ipchains
-ANY=0.0.0.0/0
-
-# left
-SGW1_EXT=192.168.0.1
-SGW1_INT=192.168.1.1
-LAN1=192.168.1.0/24
-
-# right
-SGW2_EXT=192.168.0.10
-SGW2_INT=192.168.2.10
-LAN2=192.168.2.0/24
-
-# SSH from and to this host
-SSH_PEER_HOST=_SOME_HOST_
-
-# this is for left. exchange these values for right.
-MY_EXT=$SGW1_EXT
-MY_INT=$SGW1_INT
-PEER_EXT=$SGW2_EXT
-PEER_INT=$SGW2_INT
-INT_IF=eth1
-EXT_IF=eth0
-IPSEC_IF=ipsec0
-MY_LAN=$LAN1
-PEER_LAN=$LAN2
-
-$IPC -F
-$IPC -P input DENY
-$IPC -P forward DENY
-$IPC -P output DENY
-
-# Loopback traffic
-$IPC -A input -i lo -j ACCEPT
-$IPC -A output -i lo -j ACCEPT
-
-# for IPsec SGW1-SGW2
-## IKE
-$IPC -A input -p udp -s $PEER_EXT 500 -d $MY_EXT 500 -i $EXT_IF -j ACCEPT
-$IPC -A output -p udp -s $MY_EXT 500 -d $PEER_EXT 500 -i $EXT_IF -j ACCEPT
-## ESP
-$IPC -A input -p 50 -s $PEER_EXT -d $MY_EXT -i $EXT_IF -j ACCEPT
-### we don't need this line ### $IPC -A output -p 50 -s $MY_EXT -d $PEER_EXT -i $EXT_IF -j ACCEPT
-## forward LAN1-LAN2
-$IPC -A forward -s $MY_LAN -d $PEER_LAN -i $IPSEC_IF -j ACCEPT
-$IPC -A forward -s $PEER_LAN -d $MY_LAN -i $INT_IF -j ACCEPT
-$IPC -A output -s $PEER_LAN -d $MY_LAN -i $INT_IF -j ACCEPT
-$IPC -A input -s $PEER_LAN -d $MY_LAN -i $IPSEC_IF -j ACCEPT
-$IPC -A input -s $MY_LAN -d $PEER_LAN -i $INT_IF -j ACCEPT
-$IPC -A output -s $MY_LAN -d $PEER_LAN -i $IPSEC_IF -j ACCEPT
-
-# ICMP
-#
-## Dest unreachable
-### from/to Internet
-$IPC -A input -p icmp --icmp-type destination-unreachable -s $ANY -d $MY_EXT -i $EXT_IF -j ACCEPT
-$IPC -A output -p icmp --icmp-type destination-unreachable -s $MY_EXT -d $ANY -i $EXT_IF -j ACCEPT
-### from/to Lan
-$IPC -A input -p icmp --icmp-type destination-unreachable -s $ANY -d $MY_INT -i $INT_IF -j ACCEPT
-$IPC -A output -p icmp --icmp-type destination-unreachable -s $MY_INT -d $ANY -i $INT_IF -j ACCEPT
-### from/to Peer Lan
-$IPC -A input -p icmp --icmp-type destination-unreachable -s $ANY -d $MY_INT -i $IPSEC_IF -j ACCEPT
-$IPC -A output -p icmp --icmp-type destination-unreachable -s $MY_INT -d $ANY -i $IPSEC_IF -j ACCEPT
-#
-## Source quench
-### from/to Internet
-$IPC -A input -p icmp --icmp-type source-quench -s $ANY -d $MY_EXT -i $EXT_IF -j ACCEPT
-$IPC -A output -p icmp --icmp-type source-quench -s $MY_EXT -d $ANY -i $EXT_IF -j ACCEPT
-### from/to Lan
-$IPC -A input -p icmp --icmp-type source-quench -s $ANY -d $MY_INT -i $INT_IF -j ACCEPT
-$IPC -A output -p icmp --icmp-type source-quench -s $MY_INT -d $ANY -i $INT_IF -j ACCEPT
-### from/to Peer Lan
-$IPC -A input -p icmp --icmp-type source-quench -s $ANY -d $MY_INT -i $IPSEC_IF -j ACCEPT
-$IPC -A output -p icmp --icmp-type source-quench -s $MY_INT -d $ANY -i $IPSEC_IF -j ACCEPT
-#
-## Parameter problem
-### from/to Internet
-$IPC -A input -p icmp --icmp-type parameter-problem -s $ANY -d $MY_EXT -i $EXT_IF -j ACCEPT
-$IPC -A output -p icmp --icmp-type parameter-problem -s $MY_EXT -d $ANY -i $EXT_IF -j ACCEPT
-### from/to Lan
-$IPC -A input -p icmp --icmp-type parameter-problem -s $ANY -d $MY_INT -i $INT_IF -j ACCEPT
-$IPC -A output -p icmp --icmp-type parameter-problem -s $MY_INT -d $ANY -i $INT_IF -j ACCEPT
-### from/to Peer Lan
-$IPC -A input -p icmp --icmp-type parameter-problem -s $ANY -d $MY_INT -i $IPSEC_IF -j ACCEPT
-$IPC -A output -p icmp --icmp-type parameter-problem -s $MY_INT -d $ANY -i $IPSEC_IF -j ACCEPT
-#
-## Time To Live exceeded
-### from/to Internet
-$IPC -A input -p icmp --icmp-type time-exceeded -s $ANY -d $MY_EXT -i $EXT_IF -j ACCEPT
-$IPC -A output -p icmp --icmp-type time-exceeded -s $MY_EXT -d $ANY -i $EXT_IF -j ACCEPT
-### to Lan
-$IPC -A input -p icmp --icmp-type time-exceeded -s $ANY -d $MY_INT -i $INT_IF -j ACCEPT
-$IPC -A output -p icmp --icmp-type time-exceeded -s $MY_INT -d $ANY -i $INT_IF -j ACCEPT
-### to Peer Lan
-$IPC -A input -p icmp --icmp-type time-exceeded -s $ANY -d $MY_INT -i $IPSEC_IF -j ACCEPT
-$IPC -A output -p icmp --icmp-type time-exceeded -s $MY_INT -d $ANY -i $IPSEC_IF -j ACCEPT
-
-# ICMP PINGs
-## from Internet
-$IPC -A input -p icmp -s $ANY -d $MY_EXT --icmp-type echo-request  -i $EXT_IF -j ACCEPT
-$IPC -A output -p icmp -s $MY_EXT -d $ANY --icmp-type echo-reply  -i $EXT_IF -j ACCEPT
-## from LAN
-$IPC -A input -p icmp -s $ANY -d $MY_INT --icmp-type echo-request -i $INT_IF -j ACCEPT
-$IPC -A output -p icmp -s $MY_INT -d $ANY --icmp-type echo-reply  -i $INT_IF -j ACCEPT
-## from Peer LAN
-$IPC -A input -p icmp -s $ANY -d $MY_INT --icmp-type echo-request -i $IPSEC_IF -j ACCEPT
-$IPC -A output -p icmp -s $MY_INT -d $ANY --icmp-type echo-reply  -i $IPSEC_IF -j ACCEPT
-
-# SSH
-## from SSH_PEER_HOST
-$IPC -A input -p tcp -s $SSH_PEER_HOST -d $MY_EXT 22 -i $EXT_IF -j ACCEPT
-$IPC -A output -p tcp \! -y -s $MY_EXT 22 -d $SSH_PEER_HOST -i $EXT_IF -j ACCEPT
-## to SSH_PEER_HOST
-$IPC -A input -p tcp \! -y -s $SSH_PEER_HOST 22 -d $MY_EXT -i $EXT_IF -j ACCEPT
-$IPC -A output -p tcp -s $MY_EXT -d $SSH_PEER_HOST 22 -i $EXT_IF -j ACCEPT
-## from PEER
-$IPC -A input -p tcp -s $PEER_EXT -d $MY_EXT 22 -i $EXT_IF -j ACCEPT
-$IPC -A output -p tcp \! -y -s $MY_EXT 22 -d $PEER_EXT -i $EXT_IF -j ACCEPT
-## to PEER
-$IPC -A input -p tcp \! -y -s $PEER_EXT 22 -d $MY_EXT -i $EXT_IF -j ACCEPT
-$IPC -A output -p tcp -s $MY_EXT -d $PEER_EXT 22 -i $EXT_IF -j ACCEPT
-
-# ipxtunnel
-$IPC -A input -p udp -s $PEER_INT 2005 -d $MY_INT 2005 -i $IPSEC_IF -j ACCEPT
-$IPC -A output -p udp -s $MY_INT 2005 -d $PEER_INT 2005 -i $IPSEC_IF -j ACCEPT
-
----------------- end of rc.firewall ----------------------
-
-To understand this we need to look on this scheme:
-
-           ++-----------------------<----------------------------+
-           || ipsec0                                             |
-           \/                                                    |
- eth0  +--------+    /---------/ yes  /---------/ yes +-----------------------+
------->| INPUT  |-->/ ?local? /----->/ ?IPsec? /----->| decrypt decapsulate |
- eth1  +--------+  /---------/      /---------/       +-----------------------+
-                       || no            || no
-                       \/               \/
-                  +----------+      +---------+        +-------+
-                  | routing  |      |  local  |        | local |
-                  | decision |      | deliver |        | send  |
-                  +----------+      +---------+        +-------+
-                       ||                                 ||
-                       \/                                 \/
-                   +---------+                       +----------+
-                   | forward |                       | routing  |
-                   +---------+                       | decision |
-                       ||                            +----------+
-                       ||                                  ||
-                       ++----------------<-----------------++
-                       ||
-                       \/
-                   +--------+ eth0
-                   | OUTPUT | eth1
-                   +--------+ ipsec0
-                       ||
-                       \/
-                   /---------/ yes +-----------------------+
-                  / ?IPsec? /----->| encrypt encapsulate |
-                 /---------/       +-----------------------+
-                      || no                    ||
-                      ||                       ||
-                      ||                       \/   eth0, eth1
-                      ++-----------------------++-------------->
-
-This explain how a packet traverse TCP/IP stack in IPsec capable kernel.
-
-FIX ME, please, if there are any errors
-
-Test the new firewall now.
-
-
-Now about IPX. I tried 3 programs for tunneling IPX: tipxd, SIB and ipxtunnel
-
-tipxd didn't send packets.. :(
-SIB and ipxtunnel worked fine :)
-With ipxtunnel there was a little problem. In sources there are an error.
-
---------------------- in main.c ------------------------
-<       bytes += p.len;
----
->       bytes += len;
---------------------------------------------------------
-
-After this FIX everything goes right...
-
-------------------- /etc/ipxtunnel.conf ----------------
-port    2005
-remote  192.168.101.97    2005
-interface eth1
---------------- end of /etc/ipxtunnel.conf -------------
-
-I use IPX tunnel between .1.1 and .2.10 so we don't need to encrypt nor
-authenticate encapsulated IPX packets, it is done with IPsec.
-
-If you don't wont to use iproute2 to change source IP you need to use SIB
-(it is able to bind local address) or establish tunnel between .0.1 and
-.0.10 (external IPs, you need to do encryption in the program, but it isn't
-strong).
-
-For now I'm using ipxtunnel.
-
-I think that's all for the moment. If there are any error, please e-mail me: 
-poltorak@df.ru . It would be cool if someone puts the scheme of TCP/IP in
-kernel and firewall example on FreeS/WAN's manual pages.
-
-PoltoS
-
-
-

How to configure to use "make check"

-

What is "make check"

-

"make check" is a target in the top level makefile. It takes care of - running a number of unit and system tests to confirm that FreeSWAN has - been compiled correctly, and that no new bugs have been introduced.

-

As FreeSWAN contains both kernel and userspace components, doing - testing of FreeSWAN requires that the kernel be simulated. This is - typically difficult to do as a kernel requires that it be run on bare - hardware. A technology has emerged that makes this simpler. This is - User Mode Linux.

-

User-Mode Linux is a way to build a Linux kernel such that it can - run as a process under another Linux (or in the future other) kernel. - Presently, this can only be done for 2.4 guest kernels. The host kernel - can be 2.2 or 2.4.

-

"make check" expects to be able to build User-Mode Linux kernels - with FreeSWAN included. To do this it needs to have some files - downloaded and extracted prior to running "make check". This is - described in the UML testing document.

-

After having run the example in the UML testing document and - successfully brought up the four machine combination, you are ready to - use "make check"

-

Running "make check"

-

"make check" works by walking the FreeSWAN source tree invoking the - "check" target at each node. At present there are tests defined only - for the klips directory. These tests will use the UML - infrastructure to test out pieces of the klips code.

-

The results of the tests can be recorded. If the environment - variable $REGRESSRESULTS is non-null, then the results of - each test will be recorded. This can be used as part of a nightly - regression testing system, see Nightly testing - for more details.

-

"make check" otherwise prints a minimal amount of output for each - test, and indicates pass/fail status of each test as they are run. - Failed tests do not cause failure of the target in the form of exit - codes.

-

How to write a "make check" test

-

Structure of a test

-

Each test consists of a set of directories under testing/ -. There are directories for klips, pluto, -packaging and libraries. Each directory has a list - of tests to run is stored in a file called TESTLIST in - that directory. e.g. testing/klips/TESTLIST.

-

The TESTLIST

-

This isn't actually a shell script. It just looks like one. Some - tools other than /bin/sh process it. Lines that start with # are - comments.

-
-# test-kind     directory-containing-test       expectation     [PR#]
-
-

The first word provides the test type, detailed below.

-

The second word is the name of the test to run. This the directory - in which the test case is to be found..

-

The third word may be one of:

-
-
blank/good
-
the test is believed to function, report failure
-
bad
-
the test is known to fail, report unexpected success
-
suspended
-
the test should not be run
-
-

The fourth word may be a number, which is a PR# if the test is - failing.

-

Test kinds

- The test types are: -
-
skiptest
-
means run no test.
-
ctltest
-
means run a single system without input/output.
-
klipstest
-
means run a single system with input/output networks
-
umlplutotest
-
means run a pair of systems
-
umlXhost
-
run an arbitrary number of systems
-
suntest (TBD)
-
means run a quad of east/west/sunrise/sunset
-
roadtest (TBD)
-
means run a trio of east-sunrise + warrior
-
extrudedtest (TBD)
-
means run a quad of east-sunrise + warriorsouth + park
-
mkinsttest
-
a test of the "make install" machinery.
-
kernel_test_patch
-
a test of the "make kernelpatch" machinery.
-
- Tests marked (TBD) have yet to be fully defined. -

Each test directory has a file in it called testparams.sh -. This file sets a number of environment variables to define the - parameters of the test.

-

Common parameters

-
-
TESTNAME
-
the name of the test (repeated for checking purposes)
-
TEST_TYPE
-
the type of the test (repeat of type type above)
-
TESTHOST
-
the name of the UML machine to run for the test, typically "east" or - "west"
-
TEST_PURPOSE
-
The purpose of the test is one of: -
-
goal
-
The goal purpose is where a test is defined for code that is not yet - finished. The test indicates when the goals have in fact been reached.
-
regress
-
This is a test to determine that a previously existing bug has been - repaired. This test will initially be created to reproduce the bug in - isolation, and then the bug will be fixed.
-
exploit
-
This is a set of packets/programs that causes a vulnerability to be - exposed. It is a specific variation of the regress option.
-
-
-
TEST_GOAL_ITEM
-
-
in the case of a goal test, this is a reference to the requirements - document
-
TEST_PROB_REPORT
-
in the case of regression test, this the problem report number from - GNATS
-
TEST_EXPLOIT_URL
-
in the case of an exploit, this is a URL referencing the paper - explaining the origin of the test and the origin of exploit software
-
REF_CONSOLE_OUTPUT
-
a file in the test directory that contains the sanitized console - output against which to compare the output of the actual test.
-
REF_CONSOLE_FIXUPS
-
a list of scripts (found in klips/test/fixups) to apply - to sanitize the console output of the machine under test. These are - typically perl, awk or sed scripts that remove things in the kernel - output that change each time the test is run and/or compiled.
-
INIT_SCRIPT
-
-

a file of commands that is fed into the virtual machine's console in - single user mode prior to starting the tests. This file will usually - set up any eroute's and SADB entries that are required for the test.

-

Lines beginning with # are skipped. Blank lines are skipped. - Otherwise, a shell prompted is waited for each time (consisting of -\n#) and then the command is sent. Note that the prompt is waited - for before the command and not after, so completion of the last command - in the script is not required. This is often used to invoke a program - to monitor the system, e.g. ipsec pf_key.

-
-
RUN_SCRIPT
-
-

a file of commands that is fed into the virtual machine's console in - single user mode, before the packets are sent. On single machine tests, - this script doesn't provide any more power than INIT_SCRIPT, but is - implemented for consistency's sake.

-
-
FINAL_SCRIPT
-
-

a file of commands that is fed into the virtual machine's console in - single user mode after the final packet is sent. Similar to - INIT_SCRIPT, above. If not specified, then the single command "halt" is - sent. If specified, then the script should end with a halt command to - nicely shutdown the UML.

-
-
CONSOLEDIFFDEBUG
-
If set to "true" then the series of console fixups (see - REF_CONSOLE_FIXUPS) will be output after it is constructed. (It should - be set to "false", or unset otherwise)
-
NETJIGDEBUG
-
If set to "true" then the series of console fixups (see - REF_CONSOLE_FIXUPS) will be output after it is constructed. (It should - be set to "false", or unset otherwise)
-
NETJIGTESTDEBUG
-
If set to "netjig", then the results of talking to the -uml_netjig will be printed to stderr during the test. In - addition, the jig will be invoked with --debug, which causes it to log - its process ID, and wait 60 seconds before continuing. This can be used - if you are trying to debug the uml_netjig program itself.
-
HOSTTESTDEBUG
-
If set to "hosttest", then the results of taling to the consoles of - the UMLs will be printed to stderr during the test.
-
NETJIGWAITUSER
-
If set to "waituser", then the scripts will wait forever for user - input before they shut the tests down. Use this is if you are debugging - through the kernel.
-
PACKETRATE
-
A number, in miliseconds (default is 500ms) at which packets will - be replayed by the netjig.
-
-

KLIPStest paramaters

-

The klipstest function starts a program ( -testing/utils/uml_netjig/uml_netjig) to setup a bunch of I/O - sockets (that simulate network interfaces). It then exports the - references to these sockets to the environment and invokes (using - system()) a given script. It waits for the script to finish.

- - -

The script invoked (testing/utils/host-test.tcl) is a - TCL expect script that arranges - to start the UML and configure it appropriately for the test. The - configuration is done with the script given above for INIT_SCRIPT -. The TCL script then forks, leaves the UML in the background and exits. - uml_netjig continues. It then starts listening to the simulated network - answering ARPs and inserting packets as appropriate.

-

The klipstest function invokes uml_netjig with - arguments to capture output from network interface(s) and insert - packets as appropriate:

-
-
PUB_INPUT
-
a pcap file to feed in on the - public (encrypted) interface. (typically, eth1)
-
PRIV_INPUT
-
a pcap file to feed in on the private (plain-text) interface - (typically, eth0).
-
REF_PUB_OUTPUT
-
a text file containing tcpdump output. Packets on the public (eth1) - interface are captured to a pcap - file by uml_netjig. The klipstest function then uses - tcpdump on the file to produce text output, which is compared to the - file given.
-
REF_PUB_FILTER
-
a program that will filter the TCPDUMP output to do further - processing. Defaults to "cat".
-
REF_PRIV_OUTPUT
-
a text file containing tcpdump output. Packets on the private (eth0) - interface are captured and compared after conversion by tcpdump, as - with REFPUBOUTPUT.
-
REF_PRIV_FILTER
-
a program that will filter the TCPDUMP output to do further - processing. Defaults to "cat".
-
EXITONEMPTY
-
a flag for uml_netjig. It should contain - "--exitonempty" of uml_netjig should exit when all of the input ( -PUBINPUT,PRIVINPUT) packets have been injected.
-
ARPREPLY
-
a flag for uml_netjig. It should contain "--arpreply" - if uml_netjig should reply to ARP requests. One will - typically set this to avoid having to fudge the ARP cache manually.
-
TCPDUMPFLAGS
-
a set of flags for the tcpdump used when converting captured output. - Typical values will include "-n" to turn off DNS, and often "-E" to set - the decryption key (tcpdump 3.7.1 and higher only) for ESP packets. The - "-t" flag (turn off timestamps) is provided automatically
-
NETJIG_EXTRA
-
additional comments to be sent to the netjig. This may arrange to - record or create additional networks, or may toggle options.
-
-

mkinsttest paramaters

-

The basic concept of the mkinsttest test type is that - it performs a "make install" to a temporary $DESTDIR. The resulting - tree can then be examined to determine if it was done properly. The - files can be uninstalled to determine if the file list was correct, or - the contents of files can be examined more precisely.

-
-
INSTALL_FLAGS
-
If set, then an install will be done. This provides the set of flags - to provide for the install. The target to be used (usually "install") - must be among the flags.
-
POSTINSTALL_SCRIPT
-
If set, a script to run after initial "make install". Two arguments - are provided: an absolute path to the root of the FreeSWAN src tree, - and an absolute path to the temporary installation area.
-
INSTALL2_FLAGS
-
If set, a second install will be done using these flags. Similarly - to INSTALL_FLAGS, the target must be among the flags.
-
UNINSTALL_FLAGS
-
If set, an uninstall will be done using these flags. Similarly to - INSTALL_FLAGS, the target (usually "uninstall") must be among the - flags.
-
REF_FIND_f_l_OUTPUT
-
If set, a find $ROOT ( -type f -or -type -l ) will be - done to get a list of a real files and symlinks. The resulting file - will be compared to the file listed by this option.
-
REF_FILE_CONTENTS
-
If set, it should point to a file containing records for the form: -
-  
-
-reffile   
-
-samplefile
-
- one record per line. A diff between the provided reference file, and - the sample file (located in the temporary installation root) will be - done for each record.
-
-

rpm_build_install_test paramaters

-

The rpm_build_install_test type is to verify that the - proper packing list is produced by "make rpm", and that the mechanisms - for building the kernel modules produce consistent results.

-
-
RPM_KERNEL_SOURCE
-
Point to an extracted copy of the RedHat kernel source code. - Variables from the environment may be used.
-
REF_RPM_CONTENTS
-
This is a file containing one record per line. Each record consists - of a RPM name (may contain wildcards) and a filename to compare the - contents to. The RPM will be located and a file list will be produced - with rpm2cpio.
-
-

libtest paramaters

-

The libtest test is for testing library routines. The library file - is expected to provided an #ifdef by the name of - library - -. The libtest type invokes the C compiler to compile this - file, links it against libfreeswan.a (to resolve any other - dependancies) and runs the test with the -r argument to - invoke a regression test.

-

The library test case is expected to do a self-test, exiting with - status code 0 if everything is okay, and with non-zero otherwise. A - core dump (exit code greater than 128) is noted specifically.

-

Unlike other tests, there are no subdirectories required, or other - parameters to set.

-

umlplutotest paramaters

-

The umlplutotest function starts a pair of user mode line processes. - This is a 2-host version of umlXhost. The "EAST" and "WEST" slots are - defined.

-

umlXhost parameters

-

The umlXtest function starts an arbitrary number of user mode line - processes.

- - -

The script invoked (testing/utils/Xhost-test.tcl) is a - TCL expect script that arranges - to start each UML and configure it appropriately for the test. It then - starts listening (using uml_netjig) to the simulated network answering - ARPs and inserting packets as appropriate.

-

umlXtest has a series of slots, each of which should be filled by a - host. The list of slots is controlled by the variable, XHOST_LIST. This - variable should be set to a space seperated list of slots. The former - umlplutotest is now implemented as a variation of the umlXhost test, - with XHOST_LIST="EAST WEST".

-

For each host slot that is defined, a series of variables should be - filled in, defining what configuration scripts to use for that host.

-

The following are used to control the console input and output to - the system. Where the string ${host} is present, the host slot should - be filled in. I.e. for the two host system with XHOST_LIST="EAST WEST", - then the variables: EAST_INIT_SCRIPT and WEST_INIT_SCRIPT will exist.

-
-
${host}HOST
-
The name of the UML host which will fill this slot
-
${host}_INIT_SCRIPT
-
-

a file of commands that is fed into the virtual machine's console in - single user mode prior to starting the tests. This file will usually - set up any eroute's and SADB entries that are required for the test. - Similar to INIT_SCRIPT, above.

-
-
${host}_RUN_SCRIPT
-
-

a file of commands that is fed into the virtual machine's console in - single user mode, before the packets are sent. This set of commands is - run after all of the virtual machines are initialized. I.e. after - EAST_INIT_SCRIPT AND WEST_INIT_SCRIPT. This script can therefore - do things that require that all machines are properly configured.

-
-
${host}_RUN2_SCRIPT
-
-

a file of commands that is fed into the virtual machine's console in - single user mode, after the packets are sent. This set of commands is - run before any of the virtual machines have been shut down. (I.e. - before EAST_FINAL_SCRIPT AND WEST_FINAL_SCRIPT.) This script can - therefore catch post-activity status reports.

-
-
${host}_FINAL_SCRIPT
-
-

a file of commands that is fed into the virtual machine's console in - single user mode after the final packet is sent. Similar to - INIT_SCRIPT, above. If not specified, then the single command "halt" is - sent. Note that when this script is run, the other virtual machines may - already have been killed. If specified, then the script should end with - a halt command to nicely shutdown the UML.

-
-
REF_${host}_CONSOLE_OUTPUT
-
Similar to REF_CONSOLE_OUTPUT, above.
-
-

Some additional flags apply to all hosts:

-
-
REF_CONSOLE_FIXUPS
-
a list of scripts (found in klips/test/fixups) to apply - to sanitize the console output of the machine under test. These are - typically perl, awk or sed scripts that remove things in the kernel - output that change each time the test is run and/or compiled.
-
-

In addition to input to the console, the networks may have input fed - to them:

-
-
EAST_INPUT/WEST_INPUT
-
a pcap file to feed in on the - private network side of each network. The "EAST" and "WEST" here refer - to the networks, not the hosts.
-
REF_PUB_FILTER
-
a program that will filter the TCPDUMP output to do further - processing. Defaults to "cat".
-
REF_EAST_FILTER/REF_WEST_FILTER
-
a program that will filter the TCPDUMP output to do further - processing. Defaults to "cat".
-< -
TCPDUMPFLAGS
-
a set of flags for the tcpdump used when converting captured output. - Typical values will include "-n" to turn off DNS, and often "-E" to set - the decryption key (tcpdump 3.7.1 and higher only) for ESP packets. The - "-t" flag (turn off timestamps) is provided automatically
-
REF_EAST_OUTPUT/REF_WEST_OUTPUT
-
a text file containing tcpdump output. Packets on the private (eth0) - interface are captured and compared after conversion by tcpdump, as - with REF_PUB_OUTPUT.
-

There are two additional environment variables that may be set on - the command line:

-
-
NETJIGVERBOSE=verbose export NETJIGVERBOSE
-
If set, then the test output will be "chatty", and let you know - what commands it is running, and as packets are sent. Without it set, - the output is limited to success/failure messages.
-
NETJIGTESTDEBUG=netjig export NETJIGTESTDEBUG
-
This will enable debugging of the communication with uml_netjig, - and turn on debugging in this utility. This does not imply - NETJIGVERBOSE.
-
-
HOSTTESTDEBUG=hosttest export HOSTTESTDEBUG
-
This will show all interactions with the user-mode-linux consoles
-
-

kernel_patch_test paramaters

-

The kernel_patch_test function takes some kernel source, copies it - with lndir, and then applies the patch as produced by "make - kernelpatch".

-

The following are used to control the input and output to the - system:

-
-
KERNEL_NAME
-
the kernel name, typically something like "linus" or "rh"
-
KERNEL_VERSION
-
the kernel version number, as in "2.2" or "2.4".
-
KERNEL_${KERNEL_NAME}${KERNEL_VERSION}_SRC
-
This variable should set in the environment, probably in - ~/freeswan-regress-env.sh. Examples of this variables would be - KERNEL_LINUS2_0_SRC or KERNEL_RH7_3_SRC. This variable should point to - an extracted copy of the kernel source in question.
-
REF_PATCH_OUTPUT
-
a copy of the patch output to compare against
-
KERNEL_PATCH_LEAVE_SOURCE
-
If set to a non-empty string, then the patched kernel source is not - removed at the end of the test. This will typically be set in the - environment while debugging.
-
-

module_compile paramaters

-

The module_compile test attempts to build the KLIPS module against a - given set of kernel source. This is also done by the RPM tests, but in - a very specific manner.

-

There are two variations of this test - one where the kernel either - doesn't need to be configured, or is already done, and tests were there - is a local configuration file.

-

Where the kernel doesn't need to be configured, the kernel source - that is found is simply used. It may be a RedHat-style kernel, where - one can cause it to configure itself via rhconfig.h-style definitions. - Or, it may just be a kernel tree that has been configured.

-

If the variable KERNEL_CONFIG_FILE is set, then a new directory is - created for the kernel source. It is populated with lndir(1). The - referenced file is then copied in as .config, and "make oldconfig" is - used to configure the kernel. This resulting kernel is then used as the - reference source.

-

In all cases, the kernel source is found the same was for the - kernelpatch test, i.e. via KERNEL_VERSION/KERNEL_NAME and - KERNEL_${KERNEL_NAME}${KERNEL_VERSION}_SRC.

-

Once there is kernel source, the module is compiled using the - top-level "make module" target.

-

The test is considered successful if an executable is found in - OUTPUT/module/ipsec.o at the end of the test.

-
-
KERNEL_NAME
-
the kernel name, typically something like "linus" or "rh"
-
KERNEL_VERSION
-
the kernel version number, as in "2.2" or "2.4".
-
KERNEL_${KERNEL_NAME}${KERNEL_VERSION}_SRC
-
This variable should set in the environment, probably in - ~/freeswan-regress-env.sh. Examples of this variables would be - KERNEL_LINUS2_0_SRC or KERNEL_RH7_3_SRC. This variable should point to - an extracted copy of the kernel source in question.
-
KERNEL_CONFIG_FILE
-
The configuration file for the kernel.
-
KERNEL_PATCH_LEAVE_SOURCE
-
If set to a non-empty string, then the configured kernel source is - not removed at the end of the test. This will typically be set in the - environment while debugging.
-
MODULE_DEF_INCLUDE
-
The include file that will be used to configure the KLIPS module, - and possibly the kernel source.
-
-

Current pitfalls

-
-
"tcpdump dissector" not available.
-
This is a non-fatal warning. If uml_netjig is invoked with the -t - option, then it will attempt to use tcpdump's dissector to decode each - packet that it processes. The dissector is presently not available, so - this option it normally turned off at compile time. The dissector - library will be released with tcpdump version 4.0.
-
-
-

User-Mode-Linux Testing guide

-

User mode linux is a way to compile a linux kernel such that it can - run as a process in another linux system (potentially as a *BSD or - Windows process later). See - http://user-mode-linux.sourceforge.net/

-

UML is a good platform for testing and experimenting with FreeS/WAN. - It allows several network nodes to be simulated on a single machine. - Creating, configuring, installing, monitoring, and controling these - nodes is generally easier and easier to script with UML than real - hardware.

-

You'll need about 500Mb of disk space for a full - sunrise-east-west-sunset setup. You can possibly get this down by 130Mb - if you remove the sunrise/sunset kernel build. If you just want to run, - then you can even remove the east/west kernel build.

-

Nothing need be done as super user. In a couple of steps, we note - where super user is required to install commands in system-wide - directories, but ~/bin could be used instead. UML seems to use a - system-wide /tmp/uml directory so different users may interfere with - one another. Later UMLs use ~/.uml instead, so multiple users running - UML tests should not be a problem, but note that a single user running - the UML tests will only be able run one set. Further, UMLs sometimes - get stuck and hang around. These "zombies" (most will actually be in - the "T" state in the process table) will interfere with subsequent - tests.

-

Preliminary Notes on BIND

-

As of 2003/3/1, the Light-Weight Resolver is used by pluto. This - requires that BIND9 be running. It also requires that BIND9 development - libraries be present in the build environment. The DNSSEC code is only - truly functional in BIND9 snapshots. The library code could be 9.2.2, - we believe. We are using BIND9 20021115 snapshot code from - ftp://ftp.isc.org/isc/bind9/snapshots.

-

FreeS/WAN may well require a newer BIND than is on your system. Many - distributions have moved to BIND9.2.2 recently due to a security - advisory. BIND is five components.

-
    -
  1. named
    2. -
  2. dnssec-*
    3. -
  3. client side resolver libraries
    4. -
  4. client side utility libraries I thought there were lib and named - parts to dnsssec...
    5. -
  5. dynamic DNS update utilities
    6. -
-

The only piece that we need for *building* is #4. That's the only - part that has to be on the build host. What is the difference between - resolver and util libs? If you want to edit - testing/baseconfigs/all/etc/bind, you'll need a snapshot version. The - resolver library contains the resolver. FreeS/WAN has its own copy of - that in lib/liblwres.

-

Steps to Install UML for FreeS/WAN

-
    -
  1. Get the following files: -
      -
    1. from - http://www.sandelman.ottawa.on.ca/freeswan/uml/ - umlfreeroot-15.1.tar.gz (or highest numbered one). This is a debian - potato root file system. You can use this even on a Redhat host, as it - has the newer GLIBC2.2 libraries as well. - - - -
      2. -
    2. From - ftp://ftp.xs4all.nl/pub/crypto/freeswan/ a snapshot or release - (1.92 or better)
      3. -
    3. From a - http://www.kernel.org mirror, the virgin 2.4.19 kernel. Please - realize that we have defaults in our tree for kernel configuration. We - try to track the latest UML kernels. If you use a newer kernel, you may - have faults in the kernel build process. You can see what the latest - that is being regularly tested by visiting - freeswan-regress-env.sh.
      4. -
    4. - - Get - http://ftp.nl.linux.org/uml/ uml-patch-2.4.19-47.bz2 or the one - associated with your kernel. As of 2003/03/05, uml-patch-2.4.19-47.bz2 - works for us. More recent versions of the patch have not been - tested by us.
      5. -
    5. You'll probably want to visit - http://user-mode-linux.sourceforge.net and get the UML utilities. - These are not needed for the build or interactive use (but - recommended). They are necessary for the regression testing procedures - used by "make check". We currently use uml_utilities_20020212.tar.bz2.
      6. -
    6. You need tcpdump version 3.7.1 or better. This is newer than the - version included in most LINUX distributions. You can check the version - of an installed tcpdump with the --version flag. If you need a newer - tcpdump fetch both tcpdump and libpcap source tar files from - http://www.tcpdump.org/ or a mirror.
      7. -
    -
    2. -
  2. Pick a suitable place, and extract the following files: -
      -
    1. - - 2.4.19 kernel. For instance: -
      -            cd /c2/kernel
-           tar xzvf ../download/pub/linux/kernel/v2.4/linux-2.4.19.tar.gz
-
-
      -
      2. -
    2. extract the umlfreeroot file - - -
      -            mkdir -p /c2/user-mode-linux/basic-root
-           cd /c2/user-mode-linux/basic-root
-           tar xzvf ../download/umlfreeroot-15.1.tar.gz
-
-
      -
      3. -
    3. FreeSWAN itself (or checkout "all" from CVS) -
      -            mkdir -p /c2/freeswan/sandbox
-           cd /c2/freeswan/sandbox
-           tar xzvf ../download/snapshot.tar.gz
-
-
      -
      4. -
    -
    3. -
  3. If you need to build a newer tcpdump: -
      -
    • Make sure you have OpenSSL installed -- it is needed for - cryptographic routines.
      • -
    • Unpack libpcap and tcpdump source in parallel directories (the - tcpdump build procedures look for libpcap next door).
      • -
    • Change directory into the libpcap source directory and then build - the library: -
      - 	./configure
-	make
-
-
      -
      • -
    • Change into the tcpdump source directory, build tcpdump, and - install it. -
      - 	./configure
-	make
-	# Need to be superuser to install in system directories.
-	# Installing in ~/bin would be an alternative.
-	su -c "make install"
-
-
      -
      • -
    -
    4. -
  4. If you need the uml utilities, unpack them somewhere then build and - install them: -
    - 	cd tools
-	make all
-	# Need to be superuser to install in system directories.
-	# Installing in ~/bin would be an alternative.
-	su -c "make install BIN_DIR=/usr/local/bin"
-
-
    -
    5. -
  5. set up the configuration file -
      -
    • cd /c2/freeswan/sandbox/freeswan-1.97/testing/utils
      • -
    • copy umlsetup-sample.sh to ../../umlsetup.sh: cp - umlsetup-sample.sh ../../umlsetup.sh
      • -
    • open up ../../umlsetup.sh in your favorite editor.
      • -
    • change POOLSPACE= to point to the place with at least 500Mb of - disk. Best if it is on the same partition as the "umlfreeroot" - extraction, as it will attempt to use hard links if possible to save - disk space.
      • -
    • Set TESTINGROOT if you intend to run the script outside of the - sandbox/snapshot/release directory. Otherwise, it will configure - itself.
      • -
    • KERNPOOL should point to the directory with your 2.4.19 kernel - tree. This tree should be unconfigured! This is the directory you used - in step 2a.
      • -
    • UMLPATCH should point at the bz2 file you downloaded at 1d. If - using a kernel that already includes the patch, set this to /dev/null.
      • -
    • FREESWANDIR should point at the directory where you unpacked the - snapshot/release. Include the "freeswan-snap2001sep16b" or whatever in - it. If you are running from CVS, then you point at the directory where - top, klips, etc. are. The script will fix up the directory so that it - can be used.
      • -
    • BASICROOT should be set to the directory used in 2b, or to the - directory that you created with RPMs.
      • -
    • SHAREDIR should be set to the directory used in 2c, to /usr/share - for Debian potato users, or to $BASICROOT/usr/share.
      • -
    -
    6. -
  6. -
     cd $TESTINGROOT/utils
-sh make-uml.sh
-
    - It will grind for awhile. If there are errors it will bail. If so, run - it under "script" and send the output to bugs@lists.freeswan.org.
    7. -
  7. You will have a bunch of stuff under $POOLSPACE. Open four xterms: -
         for i in sunrise sunset east west
-    do
-        xterm -name $i -title $i -e $POOLSPACE/$i/start.sh     done
-
    -
    8. -
  8. Login as root. Password is "root" (Note, these virtual machines are - networked together, but are not configured to talk to the rest of the - world.)
    9. -
  9. verify that pluto started on east/west, run "ipsec look"
    10. -
  10. login to sunrise. run "ping sunset"
    11. -
  11. login to west. run "tcpdump -p -i eth1 -n" (tcpdump must be version - 3.7.1 or newer)
    12. -
  12. Closing a console xterm will shut down that UML.
    13. -
  13. You can "make check", if you want to. It is run from - /c2/freeswan/sandbox/freeswan-1.97.
    14. -
-

Debugging the kernel with GDB

-

With User-Mode-Linux, you can debug the kernel using GDB. See - - - http://user-mode-linux.sourceforge.net/debugging.html.

-

Typically, one will want to address a test case for a failing - situation. Running GDB from Emacs, or from other front ends is - possible. First start GDB.

-

Tell it to open the UMLPOOL/swan/linux program.

-

Note the PID of GDB:

-
-marajade-[projects/freeswan/mgmt/planning] mcr 1029 %ps ax | grep gdb
- 1659 pts/9    SN     0:00 /usr/bin/gdb -fullname -cd /mara4/freeswan/kernpatch/UMLPOOL/swan/ linux
-
-

Set the following in the environment:

-
-UML_east_OPT="debug gdb-pid=1659"
-
-

Then start the user-mode-linux in the test scheme you wish:

-
-marajade-[kernpatch/testing/klips/east-icmp-02] mcr 1220 %../../utils/runme.sh
-
- The user-mode-linux will stop on boot, giving you a chance to attach to - the process: -
-(gdb) file linux
-Reading symbols from linux...done.
-(gdb) attach 1
-Attaching to program: /mara4/freeswan/kernpatch/UMLPOOL/swan/linux, process 1
-0xa0118bc1 in kill () at hostfs_kern.c:770
-
-

At this point, break points should be created as appropriate.

-

Other notes about debugging

-

If you are running a standard test, after all the packets are sent, - the UML will be shutdown. This can cause problems, because the UML may - get terminated while you are debugging.

-

The environment variable NETJIGWAITUSER can be set to - "waituser". If so, then the testing system will prompt before exiting - the test.

-

User-Mode-Linux mysteries

- -

Getting more info from uml_netjig

-

uml_netjig can be compiled with a built-in tcpdump. This uses - not-yet-released code from - www.tcpdump.org. Please see the instructions in -testing/utils/uml_netjig/Makefile.

-
-

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 - several. Two I particularly like are:

- -

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.

- -

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:

- -

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:

- -

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:

- -

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:

- -

Of course governments are by no means the only threat to privacy and - security on the net. Other threats include:

- -

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. See the UN's - Universal Declaration of Human Rights, article twelve:

-
No one shall be subjected to arbitrary interference with - his privacy, family, home or correspondence, nor to attacks upon his - honor and reputation. Everyone has the right to the protection of the - law against such interference or attacks.
-

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:

- -

For more on these issues see:

- -

There are several collections of crypto quotes - on the net.

-

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

- -

and discussions of:

- -

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:

- -

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 a little key - she kept it in escrow,
-  and every thing that Mary said,
-  the feds were sure to know.
-

A crypto quotes page attributes this to - Sam Simpson.

-

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:

- -

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:

- -

This is utter nonsense.

-

Weak systems touted include:

- -

The notion that choice of ciphers or keysize should be determined by - a trade-off between security requirements and overheads is pure - bafflegab.

- -

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.

-
   Mary had a little key (It's all she could export),
-   and all the email that she sent was opened at the Fort.
-

A crypto quotes page attributes this to - Ron Rivest. NSA headquarters is at Fort Meade, Maryland.

-

Our policy in FreeS/WAN is to use only cryptographic components with - adequate keylength and no known weaknesses.

- -

Detailed discussion of which IPsec features we implement or omit is - in out compatibility document.

-

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.

-

Some real trade-offs

-

Of course, making systems secure does involve costs, and trade-offs - can be made between cost and security. However, the real trade-offs - have nothing to do with using weaker ciphers.

-

There can be substantial hardware and software costs. There are often - substantial training costs, both to train administrators and to - increase user awareness of security issues and procedures. There are - almost always substantial staff or contracting costs.

-

Security takes staff time for planning, implementation, testing 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. EvilDoers - will know about new attacks shortly after they are found. You need - to know about them before your systems are attacked. If your vendor - provides a patch, you need to apply it. If the vendor does nothing, you - need to complain or start looking for another vendor.

-

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.

-

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.

-

Compared to those costs, cipher overheads are an insignificant factor - in the cost of security.

-

The only thing using a weak cipher can do for you is to cause all - your other investment to be wasted.

-

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

-

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. 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
The NSA regularly lies to people - who ask it for advice on export control. They have no reason not to; - accomplishing their goal by any legal means is fine by them. Lying by - government employees is legal. -
John Gilmore.
-

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:

-
... various governments have actual or proposed policies on - access to cryptographic technology ... -

(a) ... export controls ... -
(b) ... short cryptographic keys ... -
(c) ... keys should be in the hands of the government or ... -
(d) prohibit the use of cryptology ...

-

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

-

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. The abstract from that document is:

-
The Internet Engineering Task Force (IETF) has been asked - to take a position on the inclusion into IETF standards-track documents - of functionality designed to facilitate wiretapping. -

This memo explains what the IETF thinks the question means, why its - answer is "no", and what that answer means.

-
A quote from the debate leading up to that RFC:
- 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 Raven - mailing list was set up for this IETF discussion.

-

Our goal is to go beyond that RFC 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. -
  2. "In the public domain".
    3. -
-
-

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.

- -

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 - 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, - they may have had DES crackers for years, and theirs may be much - faster. It is difficult to make most computer applications work well on - parallel machines, or to design specialised hardware to accelerate - them. Cipher-cracking is one of the very few exceptions. It is entirely - straightforward to speed up cracking by just adding hardware. 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 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 spectacularly incompetent or horribly - underfunded, they can certainly break it, but we cannot guess how - quickly. Pick any time unit between days and milliseconds; none 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.

-

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. Certainly - those countries have some fine mathematicians, and those agencies had - budget. 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

- -

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

-

The winner, announced in October 2000 after several years of analysis - and discussion, was the - Rijndael cipher from two Belgian designers.

-

It is almost certain that FreeS/WAN will add AES support. - AES patches are already available.

-

Press coverage of Linux FreeS/WAN:

-

FreeS/WAN 1.0 press

- -

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 information on the IPsec protocols which - FreeS/WAN implements. For more detail, see the RFCs -.

-

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

-

Protocols and phases

-

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" (also written as 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.

-

There is more detail below, but a quick summary of how the whole - thing works is:

-
-
Phase one IKE (main mode exchange)
-
sets up a keying channel (ISAKMP SA) between the two gateways
-
Phase two IKE (quick mode exchange)
-
sets up data channels (IPsec SAs)
-
IPsec proper
-
exchanges data using AH or ESP
-
-

Both phases of IKE are repeated periodically to automate re-keying.

-

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.

- -

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.

- -

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:

- -

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 provide a useful - security service -- only encrypted data is passed over the Internet -- - but it 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.

- -

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:

- -

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:

- -

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 about any - of those, then he has interesting intelligence on your company, whether - or not he can read the messages themselves.

-

Even just knowing that there is network traffic between two sites may - tell an analyst something useful, especially when combined with - whatever other information he or she may have. For example, if you know - Company A is having cashflow problems and Company B is looking for - aquisitions, then knowing that packets are passing between the two is - interesting. It is more interesting if you can tell it is email, and - perhaps yet more if you know the sender and recipient.

-

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, to improve resistance to traffic analysis, - you should encrypt as much traffic as possible, not just as - much as seems necessary.

-

Using multiple encryption

-

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:

- -

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:

- -

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:

- -

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 won the - AES competition to choose a relacement for DES. It will almost - certainly be added to FreeS/WAN and to other IPsec implementations. - Patches are already available.

-

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

-

Choice of hash algorithm

-

The IPsec RFCs require two hash algorithms -- MD5 - and SHA-1 -- both of which FreeS/WAN implements.

-

Various other algorithms -- such as RIPEMD and Tiger -- are listed in - the RFCs as optional. None of these are in the FreeS/WAN distribution, - or are likely to be added, although user patches - exist for several of them.

-

Additional hash algorithms -- SHA-256, SHA-384 and - SHA-512 -- may be required to give hash strength matching the - strength of AES. These are likely to be added to - FreeS/WAN along with AES.

-

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:

- -

The protocol also allows implementations to add their own encryption - algorithms, authentication algorithms or Diffie-Hellman groups. We do - not support any such extensions, but there are some - patches that do.

-

There are a number of complications:

- -

These complications can of course lead to problems, particularly when - two different implementations attempt to interoperate. For example, we - have seen problems such as:

- -

Despite this, we do interoperate successfully with many - implementations, including both Windows 2000 and PGPnet. Details are in - our interoperability document.

-

Sequence of messages in IKE

-

Each phase (see previous section)of IKE - involves a series of messages. In Pluto error messages, these are - abbreviated using:

-
-
M
-
Main mode, settting up the keying channel (ISAKMP - SA)
-
Q
-
Quick mode, setting up the data channel (IPsec SA)
-
I
-
Initiator, the machine that starts the negotiation
-
R
-
Responder
-
-

For example, the six messages of a main mode negotiation, in - sequence, are labelled:

-
       MI1 ---------->
-           <---------- MR1
-       MI2 ----------> 
-           <---------- MR2
-       MI3 ---------->
-           <---------- MR3
-

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. In - either case, the HMAC construct is used as the - authentication mechanism. -

There is a separate authentication operation at the IKE level, in - which each gateway authenticates the other. This can be done in a - variety of ways.

-
-
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 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 technique used is - HMAC, defined in RFC 2104.

-

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

- -

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

- -

Pluto is controlled mainly by the - ipsec.conf(5) configuration file.

-

The ipsec(8) command

-

The ipsec(8) command is a front - end shellscript 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 .

-

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.

-

We currently have 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 it now - seems moribund, displaced by IKE. Sun now (as of Solaris 8.0) ship an - IPsec implementation using IKE. We have no plans to implement SKIP. If - a user were to implement it, we would almost certainly not want to add - the code to our distribution.

-
-

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:

- -

Archives of these lists are available via the - web interface.

-

Which list should I use?

-

For most questions, please check the FAQ - first, and if that does not have an answer, ask on the users list. "My - configuration doesn't work." does not belong on the bugs list, and "Can - FreeS/WAN do such-and-such" or "How do I configure it to..." do not - belong in design discussions.

-

Cross-posting the same message to two or more of these lists is - discouraged. Quite a few people read more than one list and getting - multiple copies is annoying.

-

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.

- -

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.

-

Products that include FreeS/WAN

-

Our introduction document gives a list of - products that include FreeS/WAN. If you have, or are considering, - one of those, check the supplier's web site for information on mailing - lists for their users.

-

Linux mailing lists

- -

Each of the scure distribution projects also has its own web site and - mailing list. Some of the sites are:

- -

Lists for IETF working groups

-

Each IETF working group has an associated mailing - list where much of the work takes place.

- -

Other mailing lists

- -

Usenet newsgroups

- -
-

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 have been integrated into the FreeS/WAN - distribution. For a variety of reasons, those listed below have not.

-

Note that not all patches are a good idea.

- -

This is not to say that patches are necessarily bad, only that using - them requires some deliberation. For example, there might be perfectly - good reasons to add a specific cipher in your application: perhaps GOST - to comply with government standards in Eastern Europe, or AES for - performance benefits.

-

Current patches

-

Patches believed current::

- -

There is also one add-on that takes the form of a modified FreeS/WAN - distribution, rather than just patches to the standard distribution:

- -

Before using any of the above,, check the mailing - lists for news of newer versions and to see whether they have been - incorporated into more recent versions of FreeS/WAN.

-

Older patches

- -

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:

- -

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

- -

Other approaches to VPNs for Linux

- -

There is a list of - Linux VPN software in the - Linux Security Knowledge Base.

-

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

-

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

- -

IPsec in router products

-

All the major router vendors support IPsec, at least in some models.

- -

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:

- -

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:

- -

IPsec on network cards

-

Network cards with built-in IPsec acceleration are available from at - least Intel, 3Com and Redcreek.

-

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:

- -

IPsec for BSD Unix

- -

IPsec for other systems

- -

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:

- -

Interoperability test sites

- -

Linux links

-

Basic and tutorial Linux information

- -

General Linux sites

- -

Documentation

-

Nearly any Linux documentation you are likely to want can be found at - the Linux Documentation Project - or LDP.

- -

You may not need to go to the LDP to get this material. Most Linux - distributions include the HowTos on their CDs and several include the - Guides as well. Also, most of the Guides and some collections of HowTos - are available in book form from various publishers.

-

Much of the LDP material is also available in languages other than - English. See this - LDP page.

-

Advanced routing

-

The Linux IP stack has some new features in 2.4 kernels. Some HowTos - have been written:

- -

Security for Linux

-

See also the LDP material above.

- -

Linux firewalls

-

Our FreeS/WAN and firewalls document - includes links to several sets of scripts - known to work with FreeS/WAN.

-

Other information sources:

- -

Miscellaneous Linux information

- -

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

- -

Tutorials

- -

See also the interesting papers section - below.

-

Crypto and security standards

- -

Crypto quotes

-

There are several collections of cryptographic quotes on the net:

- -

Cryptography law and policy

-

Surveys of crypto law

- -

Organisations opposing crypto restrictions

- -

Other information on crypto policy

- -

See also our documentation section on the - history and politics of cryptography.

-

Cryptography technical information

-

Collections of crypto links

- -

Lists of online cryptography papers

- -

Particularly interesting papers

-

These papers emphasize important issues around the use of - cryptography, and the design and management of secure systems.

- -

Computer and network security

-

Security links

- -

Firewall links

- -

VPN links

- -

Security tools

- -

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:

- -

Several Internet glossaries are available as RFCs:

- -

More general glossary or dictionary information:

- -
-

Definitions

-
-
0
-
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 our performance document 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 -- - 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 128, 192 or 256-bit keys. 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:

- -

Three of the five finalists -- Rijndael, Serpent and Twofish -- have - completely open licenses.

-

In October 2000, NIST announced the winner -- Rijndael.

-

For more information, see:

- -

AES will be added to a future release of Linux - FreeS/WAN. Likely we will add all three of the finalists with good - licenses. User-written AES patches are already - available.

-

Adding AES may also require adding stronger hashes, - SHA-256, SHA-384 and SHA-512.

-
-
AH
-
The IPsec Authentication Header, - added after the IP header. For details, see our - IPsec 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: - -

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. FreeS/WAN normally uses - RSA for this. Other methods supported are discussed in our - advanced 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: - -

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 block cipher for Linux FreeS/WAN.

-

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, about 135 years. Against a - 128-bit key, he needs 232 times that, over 500,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 over 500,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 500,000,000,000 years to break by brute force. We really don't - care how many zeroes there are on the end of that, as long as the - number remains ridiculously large. That is, we don't care exactly how - large the key is as long as it is large enough.

-

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.

-
-
CIDR
-
Classless Inter-Domain Routing, an - addressing scheme used to describe networks not restricted to the old - Class A, B, and C sizes. A CIDR block is written address/ -mask, where address is a 32-bit Internet address. The - first mask bits of address are part of the - gateway address, while the remaining bits designate other host - addresses. For example, the CIDR block 192.0.2.96/27 describes a - network with gateway 192.0.2.96, hosts 192.0.2.96 through 192.0.2.126 - and broadcast 192.0.2.127. -

FreeS/WAN policy group files accept CIDR blocks of the format - address/[mask], where address may take the - form name.domain.tld. An absent mask is assumed - to be /32.

-
-
Certification Authority
-
see CA
-
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.

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

- - - - - -
ECBElectronic CodeBook -encrypt each block independently
CBCCipher Block Chaining -
XOR previous block ciphertext into new block plaintext - before encrypting new block
CFBCipher FeedBack
OFBOutput 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.

-
-
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, and the office gateway is the server.
    • -
-

We generally use the term in the first sense. Vendors of Windows - IPsec solutions often use it in the second. See this - discussion.

-
-
Common Criteria
-
A set of international security classifications which are replacing - the old US Rainbow Book standards and similar - standards in other countries. -

Web references include this US - government site and this - global home page.

-
-
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. It is now being replaced by AES -. -

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
-
DHCP
-
Dynamic Host C -onfiguration Protocol, a method of assigning - dynamic IP addresses, and providing additional information such as - addresses of DNS servers and of gateways. See this - DHCP resource page.
-
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: - -

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

-
-
discretionary access control
-
access control mechanisms controlled by the user, for example Unix - rwx file permissions. These contrast with - mandatory access controls.
-
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 the - DNS background section of our documentation.
-
DOS attack
-
see Denial Of Service attack
-
dynamic IP address
-
an IP address which is automatically assigned, either by - DHCP or by some protocol such as PPP or - PPPoE which the machine uses to connect to the Internet. This is - the opposite of a static IP address, pre-set on - the machine itself.
-
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 both the - security of single DES and the overheads of triple DES are - seriously inferior to many other ciphers, this is a spectacularly - dubious "advantage".

-
-
Entrust
-
A Canadian company offerring enterprise PKI - products using CAST-128 symmetric crypto, - RSA public key and X.509 directories. - Web site
-
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 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 - advanced configuration section.

-
-
Exhaustive search
-
See brute force attack.
-
F
-
FIPS
-
Federal Information Processing Standard, - 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.

-
-
FreeS/WAN
-
see Linux FreeS/WAN
-
Fullnet
-
The CIDR block containing all IPs of its IP version. The - IPv4 fullnet is written 0.0.0.0/0. Also known as "all" and - "default", fullnet may be used in a routing table to specify a default - route, and in a FreeS/WAN policy group file - to specify a default IPsec policy.
-
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. See the - GMP home page.
-
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.
-
GOST
-
a Soviet government standard block cipher. - Applied Cryptography has details.
-
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. See their web site -
-
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.

-
-
IEEE
-
Institute of Electrical and Electronic - Engineers, a professional association which, among other things, - sets some technical standards
-
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. For details, see RFC 2409 and - our IPsec document. IKE is implemented in - Linux FreeS/WAN by the Pluto daemon.
-
IKE v2
-
A proposed replacement for IKE. There are other - candidates, such as JFK, and at time of writing - (March 2002) the choice between them has not yet been made and does not - appear imminent.
-
iOE
-
See Initiate-only opportunistic encryption -.
-
IP
-
Internet Protocol.
-
IP masquerade
-
A mostly obsolete term for a method of allowing multiple machines to - communicate over the Internet when only one IP address is available for - their use. The more current term is Network Address Translation or - NAT.
-
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 or 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.

-
-
IPX
-
Novell's Netware protocol tunnelled over an IP link. Our - firewalls document includes an example of using this through an - IPsec tunnel.
-
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
-
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.
-
Initiate-only opportunistic encryption (iOE) -
-
A form of opportunistic encryption (OE) in - which a host proposes opportunistic connections, but lacks the reverse - DNS records necessary to support incoming opportunistic connection - requests. Common among hosts on cable or pppoe connections where the - system administrator does not have write access to the DNS reverse map - for the host's external IP. -

Configuring for initiate-only opportunistic encryption is described - in our quickstart document.

-
-
J
-
JFK
-
Just Fast Keying, - a proposed simpler replacement for IKE.
-
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 section for more detail. For - the code see our primary site or one - of the mirror sites on this list.

-
-
Linux Security Modules (LSM)
-
a project to create an interface in the Linux kernel that supports - plug-in modules for various security policies. -

This allows multiple security projects to take different approaches - to security enhancement without tying the kernel down to one particular - approach. As I understand the history, several projects were pressing - Linus to incorporate their changes, the various sets of changes were - incompatible, and his answer was more-or-less "a plague on all your - houses; I'll give you an interface, but I won't incorporate anything".

-

It seems to be working. There is a fairly active - LSM mailing list, and several projects are already using the - interface.

-
-
LSM
-
see Linux Security Modules
-
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.

-
-
mandatory access control
-
access control mechanisims which are not settable by the user (see - discretionary access control), but are enforced by the system. -

For example, a document labelled "secret, zebra" might be readable - only by someone with secret clearance working on Project Zebra. - Ideally, the system will prevent any transfer outside those boundaries. - For example, even if you can read it, you should not be able to e-mail - it (unless the recipient is appropriately cleared) or print it (unless - certain printers are authorised for that classification).

-

Mandatory access control is a required feature for some levels of - Rainbow Book or Common Criteria classification, - but has not been widely used outside the military and government. There - is a good discussion of the issues in Anderson's - Security Engineering.

-

The Security Enhanced Linux project is adding - mandatory access control to Linux.

-
-
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. See this - discussion.
-
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.

-

Hans Dobbertin found a weakness in MD5, and people often ask whether - this means MD5 is unsafe for IPsec. It doesn't. The IPsec RFCs discuss - Dobbertin's attack and conclude that it does not affect MD5 as used for - HMAC in IPsec.

-
-
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 256 - + 256 = 257work. Against triple DES, you need - 256 + 2112 ~= 2112.

-

The memory requirements for 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 (Trusted Information - Systems, a firewall vendor) and McAfee anti-virus products. Among other - things, they offer an IPsec-based VPN product.
-
NAT
-
Network Address Translation, a process by which - firewall machines may change the addresses on packets as they go - through. For discussion, see our background - section.
-
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 not intercepted 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.

-

First, it is wildly impractical for most - applications. Key management is at best difficult, often completely - impossible.

-

Second, it is extremely fragile. Small changes which - violate the conditions listed above do not just weaken the cipher - liitle. Quite often they destroy its security completely.

-
    -
  • Re-using the pad weakens the cipher to the point where it can be - broken with pencil and paper. With a computer, the attack is trivially - easy.
    • -
  • Using anything less than truly random - numbers completely invalidates the security proof.
    • -
  • In particular, using computer-generated pseudo-random numbers may - give an extremely weak cipher. It might also produce a good stream - cipher, if the pseudo-random generator is both well-designed and - properely seeded.
    • -
-

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; - most systems marketed with such claims are worthless.

-

Finally, even if the system is implemented and used correctly, it is - highly vulnerable to a substitution attack. If an attacker - knows some 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 will never re-use.
    • -
  • However, an active attacker who knows the - plaintext can recover the pad, then use it to encode with whatever he - chooses. If he can get his version delivered instead of yours, this may - be a disaster. If you send "attack at dawn", the delivered message can - be anything the same length -- perhaps "retreat to east" or "shoot - generals".
    • -
  • An active attacker with only a reasonable guess at the plaintext can - try the same attack. If the guess is correct, this works and the - attacker's bogus message is delivered. If the guess is wrong, a garbled - message is delivered.
    • -
-

In general then, despite its theoretical perfection, the one-time-pad - has very limited practical application.

-

See also the one - time pad FAQ.

-
-
Opportunistic encryption (OE)
-
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 - quickstart document.

-
-
Opportunistic responder
-
A host which accepts, but does not initiate, requests for - opportunistic encryption (OE). An opportunistic responder has - enabled OE in its passive form (pOE) only. A - web server or file server may be usefully set up as an opportunistic - responder. -

Configuring passive OE is described in our - policy groups document.

-
-
Orange book
-
the most basic and best known of the US government's - Rainbow Book series of computer security standards.
-
P
-
P1363 standard
-
An IEEE standard for public key cryptography. - Web page.
-
pOE
-
See Passive opportunistic encryption.
-
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.
-
Passive opportunistic encryption (pOE)
-
A form of opportunistic encryption (OE) in - which the host will accept opportunistic connection requests, but will - not initiate such requests. A host which runs OE in its passive form - only is known as an opportunistic responder. -

Configuring passive OE is described in our - policy groups document.

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

-

See also - Phil Karn's definition.

-
-
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. Zimmerman left in 2001, and early in 2002 NAI - announced that they would no longer sell PGP.. -

Versions 6.5 and later of the PGP product include PGPnet, an IPsec - client for Macintosh or for Windows 95/98/NT. See our - interoperation document.

-
-
Photuris
-
Another key negotiation protocol, an alternative to - IKE, described in RFCs 2522 and 2523.
-
PPP
-
Point-to-Point Protocol, originally a method of - connecting over modems or serial lines, but see also PPPoE.
-
PPPoE
-
PPP over Ethernet, a somewhat odd protocol that - makes Ethernet look like a point-to-point serial link. It is widely - used for cable or ADSL Internet services, apparently mainly because it - lets the providers use access control and address assignmment - mechanisms developed for dialup networks. - Roaring Penguin provide a widely used Linux implementation.
-
PPTP
-
Point-to-Point Tunneling Protocol, used - in some Microsoft VPN implementations. Papers discussing weaknesses in - it are on - counterpane.com. It is now largely obsolete, replaced by L2TP.
-
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 that 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
-
Rainbow books
-
A set of US government standards for evaluation of "trusted computer - systems", of which the best known was the Orange Book -. One fairly often hears references to "C2 security" or a product - "evaluated at B1". The Rainbow books define the standards referred to - in those comments. -

See this reference - page.

-

The Rainbow books are now mainly obsolete, replaced by the - international Common Criteria standards.

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

-

See the manual pages for - ipsec_ranbits(8) and ipsec_prng(3) for more on FreeS/WAN's use of - randomness. Both depend on the random(4) device driver..

-

A couple of years ago, there was extensive mailing list discussion - (archived here -)of Linux /dev/random and FreeS/WAN. Since then, the design of the - random(4) driver has changed considerably. Linux 2.4 kernels have the - new driver..

-
-
Raptor
-
A firewall product for Windows NT offerring IPsec-based VPN - services. Linux FreeS/WAN interoperates with Raptor; see our - interop 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.
-
Reverse map
-
In DNS, a table where IP addresses can be used as - the key for lookups which return a system name and/or other - information.
-
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.

-
-
Rijndael
-
a block cipher designed by two Belgian - cryptographers, winner of the US government's AES - contest to pick a replacement for DES. See the - Rijndael home page.
-
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 algorithm, named for its three inventors. It is widely used and - likely to become moreso since it became free of patent encumbrances in - September 2000. -

RSA can be used to provide either encryption - or digital signatures. In IPsec, it is used - only for signatures. These provide gateway-to-gateway - authentication for IKE negotiations.

-

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^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 < pq: -
      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. Using c for - ciphertext and i for the input plaintext, - encryption is then:

-
        c = i^e           modulo N
-
-

An attacker cannot deduce i 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 recover - the plaintext p since:

-
        c^d == (i^e)^d    modulo N
-            == i^ed       modulo N
-            == i          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. Quite a few good mathematicians have tried both - problems, and no-one has announced success, but there is no proof they - are insoluble.

-
-
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 ( -IKE) and used by the lower (ESP and - AH). 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 as an index to look up other things such - as session keys and intialisation vectors.

-

For more detail, see our section on IPsec - and/or RFC 2401.

-
-
SE Linux
-
Security Enhanced Linux, an - NSA-funded project to add mandatory access - control to Linux. See the - project home page. -

According to their web pages, this work will include extending - mandatory access controls to IPsec tunnels.

-

Recent versions of SE Linux code use the Linux - Security Module interface.

-
-
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 allows - opportunistic encryption. Any pair of machines which can - authenticate each other via DNS can communicate securely, without - either a pre-existing shared secret or a shared PKI.

-
-
Secret key cryptography
-
See symmetric cryptography
-
Security Association
-
see SA
-
Security Enhanced Linux
-
see SE Linux
-
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
-
SHA-1
-
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.

-

The NSA made one small change after the release of the original SHA. - They did not give reasons. Iit may be a defense against some attack - they found and do not wish to disclose. Technically the modified - algorithm should be called SHA-1, but since it has replaced the - original algorithm in nearly all applications, it is generally just - referred to as SHA..

-
-
SHA-256
-
SHA-384
-
SHA-512
-
Newer variants of SHA designed to match the strength of the 128, 192 - and 256-bit keys of AES. The work to break an - encryption algorithm's strength by brute force is - 2 - - - - - - keylength operations but a - birthday attack on a hash needs only 2 - - - - - - - - hashlength - - / - - - 2 , so as a general rule you need a - hash twice the size of the key to get similar strength. SHA-256, - SHA-384 and SHA-512 are designed to match the 128, 192 and 256-bit key - sizes of AES, respectively.
-
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 section - 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.
-
static IP address
-
an IP adddress which is pre-set on the machine itself, as opposed to - a dynamic address which is assigned by a - DHCP server or obtained as part of the process of establishing a - PPP or PPPoE connection
-
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.
-
TOS field
-
The Type Of S -ervice field in an IP header, used to control qualkity of service - routing.
-
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 guessed 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.

-

In general, traffic analysis by itself is not very useful. However, - in the context of a larger intelligence effort where quite a bit is - already known, it can be very useful. When you are solving a complex - puzzle, every little bit helps.

-

IPsec itself does not defend against traffic - analysis, 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. We discuss this - here.

-
-
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
-
TTL
-
Time To Live, - used to control DNS caching. Servers discard cached - records whose TTL expires
-
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.

-
-
WEP (Wired Equivalent Privacy)
-
The cryptographic part of the IEEE standard for - wireless LANs. As the name suggests, this is designed to be only as - secure as a normal wired ethernet. Anyone with a network conection can - tap it. Its advocates would claim this is good design, refusing to - build in complex features beyond the actual requirements. -

Critics refer to WEP as "Wiretap Equivalent Privacy", and - consider it a horribly flawed design based on bogus "requirements". You - do not control radio waves as you might control your wires, so the - metaphor in the rationale is utterly inapplicable. A security policy - that chooses not to invest resources in protecting against certain - attacks which can only be conducted by people physically plugged into - your LAN may or may not be reasonable. The same policy is completely - unreasonable when someone can "plug in" from a laptop half a block - away..

-

There has been considerable analysis indicating that WEP is seriously - flawed. A FAQ on attacks against WEP is available. Part of it reads:

-
... attacks are practical to mount using only inexpensive - off-the-shelf equipment. We recommend that anyone using an 802.11 - wireless network not rely on WEP for security, and employ other - security measures to protect their wireless network. Note that our - attacks apply to both 40-bit and the so-called 128-bit versions of WEP - equally well.
-

WEP appears to be yet another instance of governments, and - unfortunately some vendors and standards bodies, deliberately promoting - hopelessly flawed "security" products, apparently mainly for the - benefit of eavesdropping agencies. See this discussion -.

-
-
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, now part of Lucent. - Their QVPN products interoperate with Linux FreeS/WAN; see our - interop 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.

-
Ross Anderson, Security Engineering - - a Guide to Building Dependable Distributed Systems -
Wiley, 2001, ISBN 0471389226 -

Easily the best book for the security professional I have seen. - Highly recommended. See the - book web page.

-

This is quite readable, but Schneier's Secrets and - Lies might be an easier introduction.

-
Bamford The Puzzle Palace, A report on NSA, - Americas's most Secret Agency -
Houghton Mifflin 1982 ISBN 0-395-31286-8 -
Bamford Body of Secrets -

The sequel.

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

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 -
-
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 book is now seriously out of date. It does not cover recent - developments such as commercial versions since PGP 5, the Open PGP - standard or GNU PG..

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

-
Kolesnikov and Hatch, Building Linux - Virtual Private Networks (VPNs) -
New Riders 2002 -

This has had a number of favorable reviews, including - this one on Slashdot. The book has a - web site.

-
Pete Loshin 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 MIT Press 1999 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.

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

-

Note (Mar 1, 2002): a new edition with different editors in the - works. Expect it this year.

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

-

This is worth reading even if you already understand security issues, - or think you do. To go deeper, follow it with Anderson's - Security Engineering.

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

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 -

A good book, with detailed coverage of ipchains(8) firewalls and of - many related issues.

-
-

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:

- -

browsable in HTML form at others such as:

- -

and some of them are available in translation:

- -

There is also a published Big Book of IPSEC RFCs.

-

Internet Drafts

-

Internet Drafts, working documents which sometimes evolve into RFCs, - are also available.

- -

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.

-

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

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.

-
-

User-Mode-Linux Testing guide

-

User mode linux is a way to compile a linux kernel such that it can - run as a process in another linux system (potentially as a *BSD or - Windows process later). See - http://user-mode-linux.sourceforge.net/

-

UML is a good platform for testing and experimenting with FreeS/WAN. - It allows several network nodes to be simulated on a single machine. - Creating, configuring, installing, monitoring, and controling these - nodes is generally easier and easier to script with UML than real - hardware.

-

You'll need about 500Mb of disk space for a full - sunrise-east-west-sunset setup. You can possibly get this down by 130Mb - if you remove the sunrise/sunset kernel build. If you just want to run, - then you can even remove the east/west kernel build.

-

Nothing need be done as super user. In a couple of steps, we note - where super user is required to install commands in system-wide - directories, but ~/bin could be used instead. UML seems to use a - system-wide /tmp/uml directory so different users may interfere with - one another. Later UMLs use ~/.uml instead, so multiple users running - UML tests should not be a problem, but note that a single user running - the UML tests will only be able run one set. Further, UMLs sometimes - get stuck and hang around. These "zombies" (most will actually be in - the "T" state in the process table) will interfere with subsequent - tests.

-

Preliminary Notes on BIND

-

As of 2003/3/1, the Light-Weight Resolver is used by pluto. This - requires that BIND9 be running. It also requires that BIND9 development - libraries be present in the build environment. The DNSSEC code is only - truly functional in BIND9 snapshots. The library code could be 9.2.2, - we believe. We are using BIND9 20021115 snapshot code from - ftp://ftp.isc.org/isc/bind9/snapshots.

-

FreeS/WAN may well require a newer BIND than is on your system. Many - distributions have moved to BIND9.2.2 recently due to a security - advisory. BIND is five components.

-
    -
  1. named
    2. -
  2. dnssec-*
    3. -
  3. client side resolver libraries
    4. -
  4. client side utility libraries I thought there were lib and named - parts to dnsssec...
    5. -
  5. dynamic DNS update utilities
    6. -
-

The only piece that we need for *building* is #4. That's the only - part that has to be on the build host. What is the difference between - resolver and util libs? If you want to edit - testing/baseconfigs/all/etc/bind, you'll need a snapshot version. The - resolver library contains the resolver. FreeS/WAN has its own copy of - that in lib/liblwres.

-

Steps to Install UML for FreeS/WAN

-
    -
  1. Get the following files: -
      -
    1. from - http://www.sandelman.ottawa.on.ca/freeswan/uml/ - umlfreeroot-15.1.tar.gz (or highest numbered one). This is a debian - potato root file system. You can use this even on a Redhat host, as it - has the newer GLIBC2.2 libraries as well. - - - -
      2. -
    2. From - ftp://ftp.xs4all.nl/pub/crypto/freeswan/ a snapshot or release - (1.92 or better)
      3. -
    3. From a - http://www.kernel.org mirror, the virgin 2.4.19 kernel. Please - realize that we have defaults in our tree for kernel configuration. We - try to track the latest UML kernels. If you use a newer kernel, you may - have faults in the kernel build process. You can see what the latest - that is being regularly tested by visiting - freeswan-regress-env.sh.
      4. -
    4. - - Get - http://ftp.nl.linux.org/uml/ uml-patch-2.4.19-47.bz2 or the one - associated with your kernel. As of 2003/03/05, uml-patch-2.4.19-47.bz2 - works for us. More recent versions of the patch have not been - tested by us.
      5. -
    5. You'll probably want to visit - http://user-mode-linux.sourceforge.net and get the UML utilities. - These are not needed for the build or interactive use (but - recommended). They are necessary for the regression testing procedures - used by "make check". We currently use uml_utilities_20020212.tar.bz2.
      6. -
    6. You need tcpdump version 3.7.1 or better. This is newer than the - version included in most LINUX distributions. You can check the version - of an installed tcpdump with the --version flag. If you need a newer - tcpdump fetch both tcpdump and libpcap source tar files from - http://www.tcpdump.org/ or a mirror.
      7. -
    -
    2. -
  2. Pick a suitable place, and extract the following files: -
      -
    1. - - 2.4.19 kernel. For instance: -
      -            cd /c2/kernel
-           tar xzvf ../download/pub/linux/kernel/v2.4/linux-2.4.19.tar.gz
-
-
      -
      2. -
    2. extract the umlfreeroot file - - -
      -            mkdir -p /c2/user-mode-linux/basic-root
-           cd /c2/user-mode-linux/basic-root
-           tar xzvf ../download/umlfreeroot-15.1.tar.gz
-
-
      -
      3. -
    3. FreeSWAN itself (or checkout "all" from CVS) -
      -            mkdir -p /c2/freeswan/sandbox
-           cd /c2/freeswan/sandbox
-           tar xzvf ../download/snapshot.tar.gz
-
-
      -
      4. -
    -
    3. -
  3. If you need to build a newer tcpdump: -
      -
    • Make sure you have OpenSSL installed -- it is needed for - cryptographic routines.
      • -
    • Unpack libpcap and tcpdump source in parallel directories (the - tcpdump build procedures look for libpcap next door).
      • -
    • Change directory into the libpcap source directory and then build - the library: -
      - 	./configure
-	make
-
-
      -
      • -
    • Change into the tcpdump source directory, build tcpdump, and - install it. -
      - 	./configure
-	make
-	# Need to be superuser to install in system directories.
-	# Installing in ~/bin would be an alternative.
-	su -c "make install"
-
-
      -
      • -
    -
    4. -
  4. If you need the uml utilities, unpack them somewhere then build and - install them: -
    - 	cd tools
-	make all
-	# Need to be superuser to install in system directories.
-	# Installing in ~/bin would be an alternative.
-	su -c "make install BIN_DIR=/usr/local/bin"
-
-
    -
    5. -
  5. set up the configuration file -
      -
    • cd /c2/freeswan/sandbox/freeswan-1.97/testing/utils
      • -
    • copy umlsetup-sample.sh to ../../umlsetup.sh: cp - umlsetup-sample.sh ../../umlsetup.sh
      • -
    • open up ../../umlsetup.sh in your favorite editor.
      • -
    • change POOLSPACE= to point to the place with at least 500Mb of - disk. Best if it is on the same partition as the "umlfreeroot" - extraction, as it will attempt to use hard links if possible to save - disk space.
      • -
    • Set TESTINGROOT if you intend to run the script outside of the - sandbox/snapshot/release directory. Otherwise, it will configure - itself.
      • -
    • KERNPOOL should point to the directory with your 2.4.19 kernel - tree. This tree should be unconfigured! This is the directory you used - in step 2a.
      • -
    • UMLPATCH should point at the bz2 file you downloaded at 1d. If - using a kernel that already includes the patch, set this to /dev/null.
      • -
    • FREESWANDIR should point at the directory where you unpacked the - snapshot/release. Include the "freeswan-snap2001sep16b" or whatever in - it. If you are running from CVS, then you point at the directory where - top, klips, etc. are. The script will fix up the directory so that it - can be used.
      • -
    • BASICROOT should be set to the directory used in 2b, or to the - directory that you created with RPMs.
      • -
    • SHAREDIR should be set to the directory used in 2c, to /usr/share - for Debian potato users, or to $BASICROOT/usr/share.
      • -
    -
    6. -
  6. -
     cd $TESTINGROOT/utils
-sh make-uml.sh
-
    - It will grind for awhile. If there are errors it will bail. If so, run - it under "script" and send the output to bugs@lists.freeswan.org.
    7. -
  7. You will have a bunch of stuff under $POOLSPACE. Open four xterms: -
         for i in sunrise sunset east west
-    do
-        xterm -name $i -title $i -e $POOLSPACE/$i/start.sh     done
-
    -
    8. -
  8. Login as root. Password is "root" (Note, these virtual machines are - networked together, but are not configured to talk to the rest of the - world.)
    9. -
  9. verify that pluto started on east/west, run "ipsec look"
    10. -
  10. login to sunrise. run "ping sunset"
    11. -
  11. login to west. run "tcpdump -p -i eth1 -n" (tcpdump must be version - 3.7.1 or newer)
    12. -
  12. Closing a console xterm will shut down that UML.
    13. -
  13. You can "make check", if you want to. It is run from - /c2/freeswan/sandbox/freeswan-1.97.
    14. -
-

Debugging the kernel with GDB

-

With User-Mode-Linux, you can debug the kernel using GDB. See - - - http://user-mode-linux.sourceforge.net/debugging.html.

-

Typically, one will want to address a test case for a failing - situation. Running GDB from Emacs, or from other front ends is - possible. First start GDB.

-

Tell it to open the UMLPOOL/swan/linux program.

-

Note the PID of GDB:

-
-marajade-[projects/freeswan/mgmt/planning] mcr 1029 %ps ax | grep gdb
- 1659 pts/9    SN     0:00 /usr/bin/gdb -fullname -cd /mara4/freeswan/kernpatch/UMLPOOL/swan/ linux
-
-

Set the following in the environment:

-
-UML_east_OPT="debug gdb-pid=1659"
-
-

Then start the user-mode-linux in the test scheme you wish:

-
-marajade-[kernpatch/testing/klips/east-icmp-02] mcr 1220 %../../utils/runme.sh
-
- The user-mode-linux will stop on boot, giving you a chance to attach to - the process: -
-(gdb) file linux
-Reading symbols from linux...done.
-(gdb) attach 1
-Attaching to program: /mara4/freeswan/kernpatch/UMLPOOL/swan/linux, process 1
-0xa0118bc1 in kill () at hostfs_kern.c:770
-
-

At this point, break points should be created as appropriate.

-

Other notes about debugging

-

If you are running a standard test, after all the packets are sent, - the UML will be shutdown. This can cause problems, because the UML may - get terminated while you are debugging.

-

The environment variable NETJIGWAITUSER can be set to - "waituser". If so, then the testing system will prompt before exiting - the test.

-

User-Mode-Linux mysteries

- -

Getting more info from uml_netjig

-

uml_netjig can be compiled with a built-in tcpdump. This uses - not-yet-released code from - www.tcpdump.org. Please see the instructions in -testing/utils/uml_netjig/Makefile.

-
-

How to configure to use "make check"

-

What is "make check"

-

"make check" is a target in the top level makefile. It takes care of - running a number of unit and system tests to confirm that FreeSWAN has - been compiled correctly, and that no new bugs have been introduced.

-

As FreeSWAN contains both kernel and userspace components, doing - testing of FreeSWAN requires that the kernel be simulated. This is - typically difficult to do as a kernel requires that it be run on bare - hardware. A technology has emerged that makes this simpler. This is - User Mode Linux.

-

User-Mode Linux is a way to build a Linux kernel such that it can - run as a process under another Linux (or in the future other) kernel. - Presently, this can only be done for 2.4 guest kernels. The host kernel - can be 2.2 or 2.4.

-

"make check" expects to be able to build User-Mode Linux kernels - with FreeSWAN included. To do this it needs to have some files - downloaded and extracted prior to running "make check". This is - described in the UML testing document.

-

After having run the example in the UML testing document and - successfully brought up the four machine combination, you are ready to - use "make check"

-

Running "make check"

-

"make check" works by walking the FreeSWAN source tree invoking the - "check" target at each node. At present there are tests defined only - for the klips directory. These tests will use the UML - infrastructure to test out pieces of the klips code.

-

The results of the tests can be recorded. If the environment - variable $REGRESSRESULTS is non-null, then the results of - each test will be recorded. This can be used as part of a nightly - regression testing system, see Nightly testing - for more details.

-

"make check" otherwise prints a minimal amount of output for each - test, and indicates pass/fail status of each test as they are run. - Failed tests do not cause failure of the target in the form of exit - codes.

-

How to write a "make check" test

-

Structure of a test

-

Each test consists of a set of directories under testing/ -. There are directories for klips, pluto, -packaging and libraries. Each directory has a list - of tests to run is stored in a file called TESTLIST in - that directory. e.g. testing/klips/TESTLIST.

-

The TESTLIST

-

This isn't actually a shell script. It just looks like one. Some - tools other than /bin/sh process it. Lines that start with # are - comments.

-
-# test-kind     directory-containing-test       expectation     [PR#]
-
-

The first word provides the test type, detailed below.

-

The second word is the name of the test to run. This the directory - in which the test case is to be found..

-

The third word may be one of:

-
-
blank/good
-
the test is believed to function, report failure
-
bad
-
the test is known to fail, report unexpected success
-
suspended
-
the test should not be run
-
-

The fourth word may be a number, which is a PR# if the test is - failing.

-

Test kinds

- The test types are: -
-
skiptest
-
means run no test.
-
ctltest
-
means run a single system without input/output.
-
klipstest
-
means run a single system with input/output networks
-
umlplutotest
-
means run a pair of systems
-
umlXhost
-
run an arbitrary number of systems
-
suntest (TBD)
-
means run a quad of east/west/sunrise/sunset
-
roadtest (TBD)
-
means run a trio of east-sunrise + warrior
-
extrudedtest (TBD)
-
means run a quad of east-sunrise + warriorsouth + park
-
mkinsttest
-
a test of the "make install" machinery.
-
kernel_test_patch
-
a test of the "make kernelpatch" machinery.
-
- Tests marked (TBD) have yet to be fully defined. -

Each test directory has a file in it called testparams.sh -. This file sets a number of environment variables to define the - parameters of the test.

-

Common parameters

-
-
TESTNAME
-
the name of the test (repeated for checking purposes)
-
TEST_TYPE
-
the type of the test (repeat of type type above)
-
TESTHOST
-
the name of the UML machine to run for the test, typically "east" or - "west"
-
TEST_PURPOSE
-
The purpose of the test is one of: -
-
goal
-
The goal purpose is where a test is defined for code that is not yet - finished. The test indicates when the goals have in fact been reached.
-
regress
-
This is a test to determine that a previously existing bug has been - repaired. This test will initially be created to reproduce the bug in - isolation, and then the bug will be fixed.
-
exploit
-
This is a set of packets/programs that causes a vulnerability to be - exposed. It is a specific variation of the regress option.
-
-
-
TEST_GOAL_ITEM
-
-
in the case of a goal test, this is a reference to the requirements - document
-
TEST_PROB_REPORT
-
in the case of regression test, this the problem report number from - GNATS
-
TEST_EXPLOIT_URL
-
in the case of an exploit, this is a URL referencing the paper - explaining the origin of the test and the origin of exploit software
-
REF_CONSOLE_OUTPUT
-
a file in the test directory that contains the sanitized console - output against which to compare the output of the actual test.
-
REF_CONSOLE_FIXUPS
-
a list of scripts (found in klips/test/fixups) to apply - to sanitize the console output of the machine under test. These are - typically perl, awk or sed scripts that remove things in the kernel - output that change each time the test is run and/or compiled.
-
INIT_SCRIPT
-
-

a file of commands that is fed into the virtual machine's console in - single user mode prior to starting the tests. This file will usually - set up any eroute's and SADB entries that are required for the test.

-

Lines beginning with # are skipped. Blank lines are skipped. - Otherwise, a shell prompted is waited for each time (consisting of -\n#) and then the command is sent. Note that the prompt is waited - for before the command and not after, so completion of the last command - in the script is not required. This is often used to invoke a program - to monitor the system, e.g. ipsec pf_key.

-
-
RUN_SCRIPT
-
-

a file of commands that is fed into the virtual machine's console in - single user mode, before the packets are sent. On single machine tests, - this script doesn't provide any more power than INIT_SCRIPT, but is - implemented for consistency's sake.

-
-
FINAL_SCRIPT
-
-

a file of commands that is fed into the virtual machine's console in - single user mode after the final packet is sent. Similar to - INIT_SCRIPT, above. If not specified, then the single command "halt" is - sent. If specified, then the script should end with a halt command to - nicely shutdown the UML.

-
-
CONSOLEDIFFDEBUG
-
If set to "true" then the series of console fixups (see - REF_CONSOLE_FIXUPS) will be output after it is constructed. (It should - be set to "false", or unset otherwise)
-
NETJIGDEBUG
-
If set to "true" then the series of console fixups (see - REF_CONSOLE_FIXUPS) will be output after it is constructed. (It should - be set to "false", or unset otherwise)
-
NETJIGTESTDEBUG
-
If set to "netjig", then the results of talking to the -uml_netjig will be printed to stderr during the test. In - addition, the jig will be invoked with --debug, which causes it to log - its process ID, and wait 60 seconds before continuing. This can be used - if you are trying to debug the uml_netjig program itself.
-
HOSTTESTDEBUG
-
If set to "hosttest", then the results of taling to the consoles of - the UMLs will be printed to stderr during the test.
-
NETJIGWAITUSER
-
If set to "waituser", then the scripts will wait forever for user - input before they shut the tests down. Use this is if you are debugging - through the kernel.
-
PACKETRATE
-
A number, in miliseconds (default is 500ms) at which packets will - be replayed by the netjig.
-
-

KLIPStest paramaters

-

The klipstest function starts a program ( -testing/utils/uml_netjig/uml_netjig) to setup a bunch of I/O - sockets (that simulate network interfaces). It then exports the - references to these sockets to the environment and invokes (using - system()) a given script. It waits for the script to finish.

- - -

The script invoked (testing/utils/host-test.tcl) is a - TCL expect script that arranges - to start the UML and configure it appropriately for the test. The - configuration is done with the script given above for INIT_SCRIPT -. The TCL script then forks, leaves the UML in the background and exits. - uml_netjig continues. It then starts listening to the simulated network - answering ARPs and inserting packets as appropriate.

-

The klipstest function invokes uml_netjig with - arguments to capture output from network interface(s) and insert - packets as appropriate:

-
-
PUB_INPUT
-
a pcap file to feed in on the - public (encrypted) interface. (typically, eth1)
-
PRIV_INPUT
-
a pcap file to feed in on the private (plain-text) interface - (typically, eth0).
-
REF_PUB_OUTPUT
-
a text file containing tcpdump output. Packets on the public (eth1) - interface are captured to a pcap - file by uml_netjig. The klipstest function then uses - tcpdump on the file to produce text output, which is compared to the - file given.
-
REF_PUB_FILTER
-
a program that will filter the TCPDUMP output to do further - processing. Defaults to "cat".
-
REF_PRIV_OUTPUT
-
a text file containing tcpdump output. Packets on the private (eth0) - interface are captured and compared after conversion by tcpdump, as - with REFPUBOUTPUT.
-
REF_PRIV_FILTER
-
a program that will filter the TCPDUMP output to do further - processing. Defaults to "cat".
-
EXITONEMPTY
-
a flag for uml_netjig. It should contain - "--exitonempty" of uml_netjig should exit when all of the input ( -PUBINPUT,PRIVINPUT) packets have been injected.
-
ARPREPLY
-
a flag for uml_netjig. It should contain "--arpreply" - if uml_netjig should reply to ARP requests. One will - typically set this to avoid having to fudge the ARP cache manually.
-
TCPDUMPFLAGS
-
a set of flags for the tcpdump used when converting captured output. - Typical values will include "-n" to turn off DNS, and often "-E" to set - the decryption key (tcpdump 3.7.1 and higher only) for ESP packets. The - "-t" flag (turn off timestamps) is provided automatically
-
NETJIG_EXTRA
-
additional comments to be sent to the netjig. This may arrange to - record or create additional networks, or may toggle options.
-
-

mkinsttest paramaters

-

The basic concept of the mkinsttest test type is that - it performs a "make install" to a temporary $DESTDIR. The resulting - tree can then be examined to determine if it was done properly. The - files can be uninstalled to determine if the file list was correct, or - the contents of files can be examined more precisely.

-
-
INSTALL_FLAGS
-
If set, then an install will be done. This provides the set of flags - to provide for the install. The target to be used (usually "install") - must be among the flags.
-
POSTINSTALL_SCRIPT
-
If set, a script to run after initial "make install". Two arguments - are provided: an absolute path to the root of the FreeSWAN src tree, - and an absolute path to the temporary installation area.
-
INSTALL2_FLAGS
-
If set, a second install will be done using these flags. Similarly - to INSTALL_FLAGS, the target must be among the flags.
-
UNINSTALL_FLAGS
-
If set, an uninstall will be done using these flags. Similarly to - INSTALL_FLAGS, the target (usually "uninstall") must be among the - flags.
-
REF_FIND_f_l_OUTPUT
-
If set, a find $ROOT ( -type f -or -type -l ) will be - done to get a list of a real files and symlinks. The resulting file - will be compared to the file listed by this option.
-
REF_FILE_CONTENTS
-
If set, it should point to a file containing records for the form: -
-  
-
-reffile   
-
-samplefile
-
- one record per line. A diff between the provided reference file, and - the sample file (located in the temporary installation root) will be - done for each record.
-
-

rpm_build_install_test paramaters

-

The rpm_build_install_test type is to verify that the - proper packing list is produced by "make rpm", and that the mechanisms - for building the kernel modules produce consistent results.

-
-
RPM_KERNEL_SOURCE
-
Point to an extracted copy of the RedHat kernel source code. - Variables from the environment may be used.
-
REF_RPM_CONTENTS
-
This is a file containing one record per line. Each record consists - of a RPM name (may contain wildcards) and a filename to compare the - contents to. The RPM will be located and a file list will be produced - with rpm2cpio.
-
-

libtest paramaters

-

The libtest test is for testing library routines. The library file - is expected to provided an #ifdef by the name of - library - -. The libtest type invokes the C compiler to compile this - file, links it against libfreeswan.a (to resolve any other - dependancies) and runs the test with the -r argument to - invoke a regression test.

-

The library test case is expected to do a self-test, exiting with - status code 0 if everything is okay, and with non-zero otherwise. A - core dump (exit code greater than 128) is noted specifically.

-

Unlike other tests, there are no subdirectories required, or other - parameters to set.

-

umlplutotest paramaters

-

The umlplutotest function starts a pair of user mode line processes. - This is a 2-host version of umlXhost. The "EAST" and "WEST" slots are - defined.

-

umlXhost parameters

-

The umlXtest function starts an arbitrary number of user mode line - processes.

- - -

The script invoked (testing/utils/Xhost-test.tcl) is a - TCL expect script that arranges - to start each UML and configure it appropriately for the test. It then - starts listening (using uml_netjig) to the simulated network answering - ARPs and inserting packets as appropriate.

-

umlXtest has a series of slots, each of which should be filled by a - host. The list of slots is controlled by the variable, XHOST_LIST. This - variable should be set to a space seperated list of slots. The former - umlplutotest is now implemented as a variation of the umlXhost test, - with XHOST_LIST="EAST WEST".

-

For each host slot that is defined, a series of variables should be - filled in, defining what configuration scripts to use for that host.

-

The following are used to control the console input and output to - the system. Where the string ${host} is present, the host slot should - be filled in. I.e. for the two host system with XHOST_LIST="EAST WEST", - then the variables: EAST_INIT_SCRIPT and WEST_INIT_SCRIPT will exist.

-
-
${host}HOST
-
The name of the UML host which will fill this slot
-
${host}_INIT_SCRIPT
-
-

a file of commands that is fed into the virtual machine's console in - single user mode prior to starting the tests. This file will usually - set up any eroute's and SADB entries that are required for the test. - Similar to INIT_SCRIPT, above.

-
-
${host}_RUN_SCRIPT
-
-

a file of commands that is fed into the virtual machine's console in - single user mode, before the packets are sent. This set of commands is - run after all of the virtual machines are initialized. I.e. after - EAST_INIT_SCRIPT AND WEST_INIT_SCRIPT. This script can therefore - do things that require that all machines are properly configured.

-
-
${host}_RUN2_SCRIPT
-
-

a file of commands that is fed into the virtual machine's console in - single user mode, after the packets are sent. This set of commands is - run before any of the virtual machines have been shut down. (I.e. - before EAST_FINAL_SCRIPT AND WEST_FINAL_SCRIPT.) This script can - therefore catch post-activity status reports.

-
-
${host}_FINAL_SCRIPT
-
-

a file of commands that is fed into the virtual machine's console in - single user mode after the final packet is sent. Similar to - INIT_SCRIPT, above. If not specified, then the single command "halt" is - sent. Note that when this script is run, the other virtual machines may - already have been killed. If specified, then the script should end with - a halt command to nicely shutdown the UML.

-
-
REF_${host}_CONSOLE_OUTPUT
-
Similar to REF_CONSOLE_OUTPUT, above.
-
-

Some additional flags apply to all hosts:

-
-
REF_CONSOLE_FIXUPS
-
a list of scripts (found in klips/test/fixups) to apply - to sanitize the console output of the machine under test. These are - typically perl, awk or sed scripts that remove things in the kernel - output that change each time the test is run and/or compiled.
-
-

In addition to input to the console, the networks may have input fed - to them:

-
-
EAST_INPUT/WEST_INPUT
-
a pcap file to feed in on the - private network side of each network. The "EAST" and "WEST" here refer - to the networks, not the hosts.
-
REF_PUB_FILTER
-
a program that will filter the TCPDUMP output to do further - processing. Defaults to "cat".
-
REF_EAST_FILTER/REF_WEST_FILTER
-
a program that will filter the TCPDUMP output to do further - processing. Defaults to "cat".
-< -
TCPDUMPFLAGS
-
a set of flags for the tcpdump used when converting captured output. - Typical values will include "-n" to turn off DNS, and often "-E" to set - the decryption key (tcpdump 3.7.1 and higher only) for ESP packets. The - "-t" flag (turn off timestamps) is provided automatically
-
REF_EAST_OUTPUT/REF_WEST_OUTPUT
-
a text file containing tcpdump output. Packets on the private (eth0) - interface are captured and compared after conversion by tcpdump, as - with REF_PUB_OUTPUT.
-

There are two additional environment variables that may be set on - the command line:

-
-
NETJIGVERBOSE=verbose export NETJIGVERBOSE
-
If set, then the test output will be "chatty", and let you know - what commands it is running, and as packets are sent. Without it set, - the output is limited to success/failure messages.
-
NETJIGTESTDEBUG=netjig export NETJIGTESTDEBUG
-
This will enable debugging of the communication with uml_netjig, - and turn on debugging in this utility. This does not imply - NETJIGVERBOSE.
-
-
HOSTTESTDEBUG=hosttest export HOSTTESTDEBUG
-
This will show all interactions with the user-mode-linux consoles
-
-

kernel_patch_test paramaters

-

The kernel_patch_test function takes some kernel source, copies it - with lndir, and then applies the patch as produced by "make - kernelpatch".

-

The following are used to control the input and output to the - system:

-
-
KERNEL_NAME
-
the kernel name, typically something like "linus" or "rh"
-
KERNEL_VERSION
-
the kernel version number, as in "2.2" or "2.4".
-
KERNEL_${KERNEL_NAME}${KERNEL_VERSION}_SRC
-
This variable should set in the environment, probably in - ~/freeswan-regress-env.sh. Examples of this variables would be - KERNEL_LINUS2_0_SRC or KERNEL_RH7_3_SRC. This variable should point to - an extracted copy of the kernel source in question.
-
REF_PATCH_OUTPUT
-
a copy of the patch output to compare against
-
KERNEL_PATCH_LEAVE_SOURCE
-
If set to a non-empty string, then the patched kernel source is not - removed at the end of the test. This will typically be set in the - environment while debugging.
-
-

module_compile paramaters

-

The module_compile test attempts to build the KLIPS module against a - given set of kernel source. This is also done by the RPM tests, but in - a very specific manner.

-

There are two variations of this test - one where the kernel either - doesn't need to be configured, or is already done, and tests were there - is a local configuration file.

-

Where the kernel doesn't need to be configured, the kernel source - that is found is simply used. It may be a RedHat-style kernel, where - one can cause it to configure itself via rhconfig.h-style definitions. - Or, it may just be a kernel tree that has been configured.

-

If the variable KERNEL_CONFIG_FILE is set, then a new directory is - created for the kernel source. It is populated with lndir(1). The - referenced file is then copied in as .config, and "make oldconfig" is - used to configure the kernel. This resulting kernel is then used as the - reference source.

-

In all cases, the kernel source is found the same was for the - kernelpatch test, i.e. via KERNEL_VERSION/KERNEL_NAME and - KERNEL_${KERNEL_NAME}${KERNEL_VERSION}_SRC.

-

Once there is kernel source, the module is compiled using the - top-level "make module" target.

-

The test is considered successful if an executable is found in - OUTPUT/module/ipsec.o at the end of the test.

-
-
KERNEL_NAME
-
the kernel name, typically something like "linus" or "rh"
-
KERNEL_VERSION
-
the kernel version number, as in "2.2" or "2.4".
-
KERNEL_${KERNEL_NAME}${KERNEL_VERSION}_SRC
-
This variable should set in the environment, probably in - ~/freeswan-regress-env.sh. Examples of this variables would be - KERNEL_LINUS2_0_SRC or KERNEL_RH7_3_SRC. This variable should point to - an extracted copy of the kernel source in question.
-
KERNEL_CONFIG_FILE
-
The configuration file for the kernel.
-
KERNEL_PATCH_LEAVE_SOURCE
-
If set to a non-empty string, then the configured kernel source is - not removed at the end of the test. This will typically be set in the - environment while debugging.
-
MODULE_DEF_INCLUDE
-
The include file that will be used to configure the KLIPS module, - and possibly the kernel source.
-
-

Current pitfalls

-
-
"tcpdump dissector" not available.
-
This is a non-fatal warning. If uml_netjig is invoked with the -t - option, then it will attempt to use tcpdump's dissector to decode each - packet that it processes. The dissector is presently not available, so - this option it normally turned off at compile time. The dissector - library will be released with tcpdump version 4.0.
-
-
-

Nightly regression testing

-

The nightly regression testing system consists of several shell - scripts and some perl scripts. The goal is to check out a fresh tree, - run "make check" on it, record the results and summarize the results to - the team and to the web site.

-

Output can be found on adams -, although the tests are actually run on another project machine.

-

How to setup the nightly build

-

The best way to do nightly testing is to setup a new account. We - call the account "build" - you could call it something else, but there - may still be some references to ~build in the scripts.

-

Files you need to know about

-

As few files as possible need to be extracted from the source tree - - files are run from the source tree whenever possible. However, there - are some bootstrap and configuration files that are necessary.

-

There are 7 files in testing/utils that are involved:

-
-
nightly-sample.sh
-
This is the root of the build process. This file should be copied - out of the CVS tree, to $HOME/bin/nightly.sh of the build account. This - file should be invoked from cron.
-
freeswan-regress-env-sample.sh
-
This file should be copied to $HOME/freeswan-regress-env.sh. It - should be edited to localize the values. See below.
-
regress-cleanup.pl
-
This file needs to be copied to $HOME/bin/regress-cleanup.pl. It is - invoked by the nightly file before doing anything else. It removes - previous nights builds in order to free up disk space for the build - about to be done.
-
teammail-sample.sh
-
A script used to send results email to the "team". This sample - script could be copied to $HOME/bin/teammail.sh. This version will PGP - encrypt all the output to the team members. If this script is used, - then PGP will have to be properly setup to have the right keys.
-
regress-nightly.sh
-
This is the first stage of the nightly build. This stage will call - other scripts as appropriate, and will extract the source code from - CVS. This script should be copied to $HOME/bin/regress-nightly.sh
-
regress-stage2.sh
-
This is the second stage of the nightly build. It is called in - place. It essentially sets up the UML setup in umlsetup.sh, and calls - "make check".
-
regress-summarize-results.pl
-
This script will summarize the results from the tests to a - permanent directory set by $REGRESSRESULTS. It is invoked from the - stage2 nightly script.
-
regress-chart.sh
-
This script is called at the end of the build process, and will - summarize each night's results (as saved into $REGRESSRESULTS by - regress-summarize-results.pl) as a chart using gnuplot. Note that this - requires at least gnuplot 3.7.2.
-
-

Configuring freeswan-regress-env.sh

-

For more info on KERNPOOL, UMLPATCH, BASICROOT and SHAREDIR, see - User-Mode-Linux testing guide.

-
-
KERNPOOL
-
Extract copy of some kernel source to be used for UML builds
-
UMLPATCH
-
matching User-Mode-Linux patch.
-
BASICROOT
-
the root file system image (see - User-Mode-Linux testing guide).
-
SHAREDIR=${BASICROOT}/usr/share
-
The /usr/share to use.
-
REGRESSTREE
-
A directory in which to store the nightly regression results. - Directories will be created by date in this tree.
-
TCPDUMP=tcpdump-3.7.1
-
The path to the tcpdump to - use. This must have crypto compiled in, and must be at least 3.7.1
-
KERNEL_RH7_2_SRC=/a3/kernel_sources/linux-2.4.9-13/
-
An extracted copy of the RedHat 7.2. kernel source. If set, then - the packaging/rpm-rh72-install-01 test will be run, and an RPM will be - built as a test.
-
KERNEL_RH7_3_SRC=/a3/kernel_sources/rh/linux-2.4.18-5
-
An extracted copy of the RedHat 7.3. kernel source. If set, then - the packaging/rpm-rh73-install-01 test will be run, and an RPM will be - built as a test.
-
NIGHTLY_WATCHERS="userid,userid,userid"
-
The list of people who should receive nightly output. This is used - by teammail.sh
-
FAILLINES=128
-
How many lines of failed test output to include in the nightly - output
-
PATH=$PATH:/sandel/bin export PATH
-
You can also override the path if necessary here.
-
CVSROOT=:pserver:anoncvs@ip212.xs4net.freeswan.org:/freeswan/MASTER
-
The CVSROOT to use. This example may work for anonymous CVS, but - will be 12 hours behind the primary, and is still experimental
-
SNAPSHOTSIGDIR=$HOME/snapshot-sig
-
For the release tools, where to put the generated per-snapshot - signature keys
-
LASTREL=1.97
-
the name of the last release branch (to find the right per-snapshot - signature
-
-
- - diff --git a/doc/Makefile b/doc/Makefile deleted file mode 100644 index f8209b3a8..000000000 --- a/doc/Makefile +++ /dev/null @@ -1,167 +0,0 @@ -# Makefile to generate various formats from HTML source -# -# Assumes the htmldoc utility is available. -# This can be downloaded from www.easysw.com -# -# Also needs lynx(1) for HTML-to-text conversion - -.SUFFIXES: .png .fig - -FREESWANSRCDIR=.. -include ${FREESWANSRCDIR}/Makefile.inc - -# Format arguments for htmldoc -F="--toclevels 4 --header 1cd" - -# source files in subdirectory -# basic stuff -a=src/intro.html src/upgrading.html src/quickstart.html \ - src/policygroups.html src/faq.html - -# related -b=src/manpages.html src/firewall.html src/trouble.html - -# more advanced -c=src/compat.html src/interop.html src/performance.html \ - src/testing.html src/kernel.html src/adv_config.html \ - src/install.html src/config.html \ - src/background.html src/user_examples.html \ - src/makecheck.html src/umltesting.html \ - -# background and reference material -d=src/politics.html src/ipsec.html \ - src/mail.html src/web.html src/glossary.html src/biblio.html \ - src/rfc.html src/roadmap.html - -# build and release related -e=src/umltesting.html src/makecheck.html src/nightly.html - -sections=$a $b $c $d $e - -# separate HTML files built in current directory -separate=intro.html install.html config.html manpages.html \ - firewall.html trouble.html kernel.html roadmap.html \ - compat.html interop.html politics.html ipsec.html \ - mail.html performance.html testing.html web.html \ - glossary.html biblio.html rfc.html faq.html \ - adv_config.html user_examples.html background.html \ - quickstart.html umltesting.html makecheck.html nightly.html \ - upgrading.html policygroups.html - -# various one-big-file formats -howto=HowTo.html HowTo.ps HowTo.pdf HowTo.txt - -alldocs=${seperate} ${howto} index.html toc.html - -srcdir=.. -# where are scripts -SCRIPTDIR=utils - -# where -TESTINGDIR=${srcdir}/testing - -# where do we put HTML manpages? -HMANDIR=manpage.d - -# default, build HTML only -# dependencies build most of it -# then we add index -index.html: toc.html HowTo.html manpages src/index.html - cp src/index.html index.html - -# separate files plus table of contents -# and then remove HTML formatting added by htmldoc -toc.html : $(sections) - @htmldoc -t html --path ".;${TESTINGDIR}/doc" -d . $(sections) - @$(SCRIPTDIR)/cleanhtml.sh $(SCRIPTDIR)/cleanhtml.sed $(separate) - -# one big HTML file -HowTo.html : $(sections) - @htmldoc -t html --toclevels 4 --header ' cf' -f $@ $(sections) - -# other HowTo formats -HowTo.txt: HowTo.html - lynx -dump $< > $@ - -HowTo.ps : $(sections) - htmldoc -f $@ $(sections) - -HowTo.pdf : $(sections) - @htmldoc -f $@ $(sections) - -manpages: manp - -manp: $(SCRIPTDIR)/mkhtmlman - @$(SCRIPTDIR)/mkhtmlman $(HMANDIR) `find ../programs ../lib ../linux -type f -name '*.[1-8]' -print | grep -v lwres | grep -v CVS` - -programs: - -all: #$(howto) $(manpages) index.html - -clean: - @rm -f $(howto) $(separate) toc.html index.html - @rm -rf $(HMANDIR) - -install: -#install: ${alldocs} manpages -# @mkdir -p ${DOCDIR} -# @$(foreach f, $(alldocs), \ -# $(INSTALL) $f ${DOCDIR} || exit 1;\ -# ) -# @find ${HMANDIR} -type f -name "*.html" -print | while read file; \ -# do \ -# $(INSTALL) $$file ${DOCDIR} || exit 1;\ -# done; - -install_file_list: - @$(foreach f, $(alldocs), \ - echo ${DOCDIR}/$f; \ - ) - @if [ -d ${HMANDIR} ]; then find ${HMANDIR} -type f -name "*.html" -print | while read file; \ - do \ - echo ${DOCDIR}/$$file; \ - done; fi; - -checkprograms: ; - -check: ; - -# not enabled by default, because xml2rfc must be installed first. -drafts: draft-richardson-ipsec-opportunistic.txt src/draft-richardson-ipsec-opportunistic.html \ - draft-richardson-ipsec-rr.txt src/draft-richardson-ipsec-rr.html - -draft-richardson-ipsec-opportunistic.txt: src/draft-richardson-ipsec-opportunistic.xml - XML_LIBRARY=$(XML_LIBRARY):./src xml2rfc xml2rfc $? $@ - -draft-richardson-ipsec-rr.txt: src/draft-richardson-ipsec-rr.xml - XML_LIBRARY=$(XML_LIBRARY):./src xml2rfc xml2rfc $? $@ - -draft-%.nr: src/draft-%.xml - XML_LIBRARY=$(XML_LIBRARY):./src xml2rfc xml2nroff $? $@ - -draft-%.html: draft-%.xml - XML_LIBRARY=$(XML_LIBRARY):./src xml2rfc xml2html $? $@ - - -.fig.eps: - fig2dev -L ps $< $@ - -.fig.png: - fig2dev -L png $< $@ - -single_netjig.png: testing/single_netjig.fig -multi_netjig.png: testing/multi_netjig.fig - -makecheck.html: single_netjig.png multi_netjig.png - -# -# DocBook based documentation -# -xmldocs: mast.html klips/mast.4 - -mast.html: klips/mast.xml - xmlto html klips/mast.xml - -klips/mast.4: klips/mast.xml - xmlto -o klips man klips/mast.xml - diff --git a/doc/adv_config.html b/doc/adv_config.html deleted file mode 100644 index 4b779c753..000000000 --- a/doc/adv_config.html +++ /dev/null @@ -1,1232 +0,0 @@ - - - -Introduction to FreeS/WAN - - - - -Contents -Previous -Next -
-

Other configuration possibilities

-

This document describes various options for FreeS/WAN configuration - which are less used or more complex (often both) than the standard - cases described in our config and - quickstart documents.

-

Some rules of thumb about configuration

-

Tunnels are cheap

-

Nearly all of the overhead in IPsec processing is in the encryption - and authentication of packets. Our - performance document discusses these overheads.

-

Beside those overheads, the cost of managing additional tunnels is - trivial. Whether your gateway supports one tunnel or ten just does not - matter. A hundred might be a problem; there is a - section on this in the performance document.

-

So, in nearly all cases, if using multiple tunnels gives you a - reasonable way to describe what you need to do, you should describe it - that way in your configuration files.

-

For example, one user recently asked on a mailing list about this - network configuration:

-
        netA---gwA---gwB---netB
-                            |----netC
-
-   netA and B are secured netC not.
-   netA and gwA can not access netC
-

The user had constructed only one tunnel, netA to netB, and wanted to - know how to use ip-route to get netC packets into it. This is entirely - unnecessary. One of the replies was:

-
  The simplest way and indeed the right way to
-  solve this problem is to set up two connections:
-
-        leftsubnet=NetA
-        left=gwA
-        right=gwB
-        rightsubnet=NetB
-  and
-        leftsubnet=NetA
-        left=gwA
-        right=gwB
-        rightsubnet=NetC
-

This would still be correct even if we added nets D, E, F, ... to the - above diagram and needed twenty tunnels.

-

Of course another possibility would be to just use one tunnel, with a - subnet mask that includes both netB and netC (or B, C, D, ...). See - next section.

-

In general, you can construct as many tunnels as you need. Networks - like netC in this example that do not connect directly to the gateway - are fine, as long as the gateway can route to them.

-

The number of tunnels can become an issue if it reaches 50 or so. - This is discussed in the performance - document. Look there for information on supporting hundreds of Road - Warriors from one gateway.

-

If you find yourself with too many tunnels for some reason like - having eight subnets at one location and nine at another so you end up - with 9*8=72 tunnels, read the next section here.

-

Subnet sizes

-

The subnets used in leftsubnet and rightsubnet - can be of any size that fits your needs, and they need not correspond - to physical networks.

-

You adjust the size by changing the - subnet mask, the number after the slash in the subnet description. - For example

- -

As an example of using these in connection descriptions, suppose your - company's head office has four physical networks using the address - ranges:

-
-
192.168.100.0/24
-
development
-
192.168.101.0/24
-
production
-
192.168.102.0/24
-
marketing
-
192.168.103.0/24
-
administration
-
-

You can use exactly those subnets in your connection descriptions, or - use larger subnets to grant broad access if required:

-
-
leftsubnet=192.168.100.0/24
-
remote hosts can access only development
-
leftsubnet=192.168.100.0/23
-
remote hosts can access development or production
-
leftsubnet=192.168.102.0/23
-
remote hosts can access marketing or administration
-
leftsubnet=192.168.100.0/22
-
remote hosts can access any of the four departments
-
-

or use smaller subnets to restrict access:

-
-
leftsubnet=192.168.103.0/24
-
remote hosts can access any machine in administration
-
leftsubnet=192.168.103.64/28
-
remote hosts can access only certain machines in administration.
-
leftsubnet=192.168.103.42/32
-
remote hosts can access only one particular machine in - administration
-
-

To be exact, 192.68.103.64/28 means all addresses whose top 28 bits - match 192.168.103.64. There are 16 of these because there are 16 - possibilities for the remainingg 4 bits. Their addresses are - 192.168.103.64 to 192.168.103.79.

-

Each connection description can use a different subnet if required.

-

It is possible to use all the examples above on the same FreeS/WAN - gateway, each in a different connection description, perhaps for - different classes of user or for different remote offices.

-

It is also possible to have multiple tunnels using different - leftsubnet descriptions with the same right. For - example, when the marketing manager is on the road he or she might have - access to:

-
-
leftsubnet=192.168.102.0/24
-
all machines in marketing
-
192.168.101.32/29
-
some machines in production
-
leftsubnet=192.168.103.42/32
-
one particular machine in administration
-
-

This takes three tunnels, but tunnels are cheap. If the laptop is set - up to build all three tunnels automatically, then he or she can access - all these machines concurrently, perhaps from different windows.

-

Other network layouts

-

Here is the usual network picture for a site-to-site VPN::

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

and for the Road Warrior::

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

Other configurations are also possible.

-

The Internet as a big subnet

-

A telecommuter might have:

-
     Sunset==========West------------------East ================= firewall --- the Internet
-         home network      untrusted net        corporate network
-

This can be described as a special case of the general - subnet-to-subnet connection. The subnet on the right is 0.0.0.0/0, the - whole Internet.

-

West (the home gateway) can have its firewall rules set up so that - only IPsec packets to East are allowed out. It will then behave as if - its only connection to the world was a wire to East.

-

When machines on the home network need to reach the Internet, they do - so via the tunnel, East and the corporate firewall. From the viewpoint - of the Internet (perhaps of some EvilDoer trying to break in!), those - home office machines are behind the firewall and protected by it.

-

Wireless

-

Another possible configuration comes up when you do not trust the - local network, either because you have very high security standards or - because your are using easily-intercepted wireless signals.

-

Some wireless networks have built-in encryption called - WEP, but its security is dubious. It is a fairly common practice to - use IPsec instead.

-

In this case, part of your network may look like this:

-
          West-----------------------------East == the rest of your network
-     workstation   untrusted wireless net
-

Of course, there would likely be several wireless workstations, each - with its own IPsec tunnel to the East gateway.

-

The connection descriptions look much like Road Warrior descriptions:

- -

The rightsubnet= parameter might be set in any of several - ways:

-
-
rightsubnet=0.0.0.0/0
-
allowing workstations to access the entire Internet (see - above)
-
rightsubnet=a.b.c.0/24
-
allowing access to your entire local network
-
rightsubnet=a.b.c.d/32
-
restricting the workstation to connecting to a particular server
-
-

Of course you can mix and match these as required. For example, a - university might allow faculty full Internet access while letting - student laptops connect only to a group of lab machines.

-

Choosing connection types

-

One choice 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 --up 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: - -

A third method, using RSA keys embedded in - X.509 certtificates, is provided by user - patches.

-
-
-

Manually keyed connections provide - weaker security than automatically keyed - connections. An opponent who reads ipsec.secrets(5) gets your - encryption key and can read all data encrypted by it. If he or she has - an archive of old messages, all of them back to your last key change - are also readable.

-

With automatically-(re)-keyed connections, an opponent who reads - ipsec.secrets(5) gets the key used to authenticate your system in IKE - -- the shared secret or your private key, depending what authentication - mechanism is in use. However, he or she does not automatically gain - access to any encryption keys or any data.

-

An attacker who has your authentication key can mount a - man-in-the-middle attack and, if that succeeds, he or she will get - encryption keys and data. This is a serious danger, but it is better - than having the attacker read everyting as soon as he or she breaks - into ipsec.secrets(5).. Moreover, the keys change often so an opponent - who gets one key does not get a large amount of data. To read all your - data, he or she would have to do a man-in-the-middle attack at every - key change.

-

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 may also be useful for testing. There is some - discussion of this in our FAQ.

-

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 - support two basic methods for this authentication:

- -

There are, howver, several variations on the RSA theme, using - different methods of managing the RSA keys:

- -

Public keys in ipsec.conf(5 -) give a reasonably straightforward method of specifying keys for - explicitly configured connections.

-

Putting public keys in DNS allows us to support - opportunistic encryption. Any two FreeS/WAN gateways can provide - secure communication, without either of them having any preset - information about the other.

-

X.509 certificates may be required to interface to various - PKIs.

-

Advantages of public key methods

-

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

- -

There is also a disadvantage:

- -

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.

-

What I call "shared secrets" are sometimes also called "pre-shared - keys". They are used only for for authentication, never for encryption. - Calling them "pre-shared keys" has confused some users into thinking - they were encryption keys, so I prefer to avoid the term..

-

If you are interoperating with another IPsec implementation, you may - find its documentation calling them "passphrases".

-

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:

- -

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. This is discussed in more detail - above.

-

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.

- -

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:

- -

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:

- -

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

An Opportunistic Gateway

-

Start from full opportunism

-

Full opportunism allows you to initiate and receive opportunistic - connections on your machine. The remaining instructions in this section - assume you have first set up full opportunism on your gateway using - these instructions. Both sets of instructions require mailing DNS - records to your ISP. Collect DNS records for both the gateway (above) - and the subnet nodes (below) before contacting your ISP.

-

Reverse DNS TXT records for each protected machine -

-

You need these so that your Opportunistic peers can:

- -

On the gateway, generate a TXT record with:

-
    ipsec showhostkey --txt 192.0.2.11
-

Use your gateway address in place of 192.0.2.11.

-

You should see (keys are trimmed for clarity throughout our example):

-
    ; RSA 2048 bits  gateway.example.com   Sat Apr 15 13:53:22 2000
-    IN TXT  "X-IPsec-Server(10)=192.0.2.11" " AQOF8tZ2...+buFuFn/"
-

This MUST BE the same key as in your gateway's TXT record, or - nothing will work.

-

In a text file, make one copy of this TXT record for each subnet - node:

-
    ; RSA 2048 bits  gateway.example.com   Sat Apr 15 13:53:22 2000
-    IN TXT  "X-IPsec-Server(10)=192.0.2.11" " AQOF8tZ2...+buFuFn/"
-                                                                                
-    ; RSA 2048 bits  gateway.example.com   Sat Apr 15 13:53:22 2000
-    IN TXT  "X-IPsec-Server(10)=192.0.2.11" " AQOF8tZ2...+buFuFn/"
-                                                                                
-    ; RSA 2048 bits  gateway.example.com   Sat Apr 15 13:53:22 2000
-    IN TXT  "X-IPsec-Server(10)=192.0.2.11" " AQOF8tZ2...+buFuFn/"
-

Above each entry, insert a line like this:

-
    98.2.0.192.in-addr.arpa. IN PTR arthur.example.com.
-

It must include:

- -

The result will be a file of TXT records, like this:

-
    98.2.0.192.in-addr.arpa. IN PTR arthur.example.com.
-    ; RSA 2048 bits  gateway.example.com   Sat Apr 15 13:53:22 2000
-    IN TXT  "X-IPsec-Server(10)=192.0.2.11" " AQOF8tZ2...+buFuFn/"
-                                                                                
-    99.2.0.192.in-addr.arpa. IN PTR ford.example.com.
-    ; RSA 2048 bits  gateway.example.com   Sat Apr 15 13:53:22 2000
-    IN TXT  "X-IPsec-Server(10)=192.0.2.11" " AQOF8tZ2...+buFuFn/"
-                                                                                
-    100.2.0.192.in-addr.arpa. IN PTR trillian.example.com.
-    ; RSA 2048 bits  gateway.example.com   Sat Apr 15 13:53:22 2000
-    IN TXT  "X-IPsec-Server(10)=192.0.2.11" " AQOF8tZ2...+buFuFn/"
-

Publish your records

-

Ask your ISP to publish all the reverse DNS records you have - collected. There may be a delay of up to 48 hours as the records - propagate.

-

...and test them

-

Check a couple of records with commands like this one:

-
    ipsec verify --host ford.example.com
-    ipsec verify --host trillian.example.com
-

The verify command checks for TXT records for both the - subnet host and its gateway. You should see output like:

-
    ...
-    Looking for TXT in reverse map: 99.2.0.192.in-addr.arpa [OK]
-    ...
-    Looking for TXT in reverse map: 11.2.0.192.in-addr.arpa   [OK]
-    ...
-    Looking for TXT in reverse map: 100.2.0.192.in-addr.arpa [OK]
-    ...
-    Looking for TXT in reverse map: 11.2.0.192.in-addr.arpa   [OK]
-    ...
-

No Configuration Needed

-

FreeS/WAN 2.x ships with a built-in, automatically enabled OE - connection conn packetdefault which applies OE, if possible, - to all outbound traffic routed through the FreeS/WAN box. The - ipsec.conf(5) manual describes this connection in detail. While the - effect is much the same as private-or-clear, the - implementation is different: notably, it does not use policy groups.

-

You can create more complex OE configurations for traffic forwarded - through a FreeS/WAN box, as explained in our - policy groups document, or disable OE using - these instructions.

-

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.

-

As far as the Internet is concerned, your new extruded net is behind - your buddy's gateway. You route all your packets for the Internet at - large out his gateway, and receive return packets the same way. You - route your local packets locally.

-

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

-

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, you'll need to poke holes in your - firewall to allow packets through.

-

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

-

Please note that Super - FreeS/WAN now features DHCP-over-IPsec, which is an alternate - procedure for Virtual IP address assignment.

-

-

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.

- -

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.

- -

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.

-
-Contents -Previous -Next - - diff --git a/doc/background.html b/doc/background.html deleted file mode 100644 index 8f24cad4a..000000000 --- a/doc/background.html +++ /dev/null @@ -1,323 +0,0 @@ - - - -Introduction to FreeS/WAN - - - - -Contents -Previous -Next -
-

Linux FreeS/WAN background

-

This section discusses a number of issues which have three things in - common:

- -

Grouping them here lets us provide the explanations some users will - need without unduly complicating the main text.

-

The explanations here are intended to be adequate for FreeS/WAN - purposes (please comment to the users mailing list - if you don't find them so), but they are not trying to be complete or - definitive. If you need more information, see the references provided - in each section.

-

Some DNS background

-

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

-

Much good reference material is available for DNS, including:

- -

We give only a brief overview here, intended to help you use DNS for - FreeS/WAN purposes.

-

Forward and reverse maps

-

Although the implementation is distributed, it is often useful to - speak of DNS as if it were just two enormous tables:

- -

Both maps can optionally contain additional data. For opportunistic - encryption, we insert the data need for IPsec authentication.

-

A system named gateway.example.com with IP address 10.20.30.40 should - have at least two DNS records, one in each map:

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

Hierarchy and delegation

-

For both maps there is a hierarchy of DNS servers and a system of - delegating authority so that, for example:

- -

DNS zones are the units of delegation. There is a hierarchy of zones.

-

Syntax of DNS records

-

Returning to the example records:

-
        gateway.example.com. IN A 10.20.30.40
-        40.30.20.10.in-addr.arpa. IN PTR gateway.example.com.
-

some syntactic details are:

- -

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

- -

To set up for opportunistic encryption, you add some TXT records to - your DNS data. Details are in our quickstart - document.

-

Cacheing, TTL and propagation delay

-

DNS information is extensively cached. With no caching, a lookup by - your system of "www.freeswan.org" might involve:

- -

However, this can be a bit inefficient. For example, if you are in - the Phillipines, the closest a root server is in Japan. That might send - you to a .org server in the US, and then to freeswan.org in Holland. If - everyone did all those lookups every time they clicked on a web link, - the net would grind to a halt.

-

Nameservers therefore cache information they look up. When you click - on another link at www.freeswan.org, your local nameserver has the IP - address for that server in its cache, and no further lookups are - required.

-

Intermediate results are also cached. If you next go to - lists.freeswan.org, your nameserver can just ask the freeswan.org - nameserver for that address; it does not need to query the root or .org - nameservers because it has a cached address for the freeswan.org zone - server.

-

Of course, like any cacheing mechanism, this can create problems of - consistency. What if the administrator for freeswan.org changes the IP - address, or the authentication key, for www.freeswan.org? If you use - old information from the cache, you may get it wrong. On the other - hand, you cannot afford to look up fresh information every time. Nor - can you expect the freeswan.org server to notify you; that isn't in the - protocols.

-

The solution that is in the protocols is fairly simple. Cacheable - records are marked with Time To Live (TTL) information. When the time - expires, the caching server discards the record. The next time someone - asks for it, the server fetches a fresh copy. Of course, a server may - also discard records before their TTL expires if it is running out of - cache space.

-

This implies that there will be some delay before the new version of - a changed record propagates around the net. Until the TTLs on all - copies of the old record expire, some users will see it because that is - what is in their cache. Other users may see the new record immediately - because they don't have an old one cached.

-

Problems with packet fragmentation

-

It seems, from mailing list reports, to be moderately common for - problems to crop up in which small packets pass through the IPsec - tunnels just fine but larger packets fail.

-

These problems are caused by various devices along the way - mis-handling either packet fragments or - path MTU discovery.

-

IPsec makes packets larger by adding an ESP or AH header. This can - tickle assorted bugs in fragment handling in routers and firewalls, or - in path MTU discovery mechanisms, and cause a variety of symptoms which - are both annoying and, often, quite hard to diagnose.

-

An explanation from project technical lead Henry Spencer:

-
The problem is IP fragmentation; more precisely, the problem is that the
-second, third, etc. fragments of an IP packet are often difficult for
-filtering mechanisms to classify.
-
-Routers cannot rely on reassembling the packet, or remembering what was in
-earlier fragments, because the fragments may be out of order or may even
-follow different routes.  So any general, worst-case filtering decision
-pretty much has to be made on each fragment independently.  (If the router
-knows that it is the only route to the destination, so all fragments
-*must* pass through it, reassembly would be possible... but most routers
-don't want to bother with the complications of that.)
-
-All fragments carry roughly the original IP header, but any higher-level
-header is (for IP purposes) just the first part of the packet data... so
-only the first fragment carries that.  So, for example, on examining the
-second fragment of a TCP packet, you could tell that it's TCP, but not
-what port number it is destined for -- that information is in the TCP
-header, which appears in the first fragment only. 
-
-The result of this classification difficulty is that stupid routers and
-over-paranoid firewalls may just throw fragments away.  To get through
-them, you must reduce your MTU enough that fragmentation will not occur.
-(In some cases, they might be willing to attempt reassembly, but have very
-limited resources to devote to it, meaning that packets must be small and
-fragments few in number, leading to the same conclusion:  smaller MTU.)
-

In addition to the problem Henry describes, you may also have trouble - with path MTU discovery.

-

By default, FreeS/WAN uses a large MTU - for the ipsec device. This avoids some problems, but may complicate - others. Here's an explanation from Claudia:

-
Here are a couple of pieces of background information. Apologies if you
-have seen these already. An excerpt from one of my old posts:
-
-    An MTU of 16260 on ipsec0 is usual. The IPSec device defaults to this 
-    high MTU so that it does not fragment incoming packets before encryption 
-    and encapsulation. If after IPSec processing packets are larger than 1500,
-    [ie. the mtu of eth0] then eth0 will fragment them. 
-
-    Adding IPSec headers adds a certain number of bytes to each packet. 
-    The MTU of the IPSec interface refers to the maximum size of the packet
-    before the IPSec headers are added. In some cases, people find it helpful 
-    to set ipsec0's MTU to 1500-(IPSec header size), which IIRC is about 1430.
-
-    That way, the resulting encapsulated packets don't exceed 1500. On most 
-    networks, packets less than 1500 will not need to be fragmented.
-
-and... (from Henry Spencer)
-
-    The way it *ought* to work is that the MTU advertised by the ipsecN
-    interface should be that of the underlying hardware interface, less a
-    pinch for the extra headers needed. 
-
-    Unfortunately, in certain situations this breaks many applications.
-    There is a widespread implicit assumption that the smallest MTUs are 
-    at the ends of paths, not in the middle, and another that MTUs are 
-    never less than 1500.  A lot of code is unprepared to handle paths 
-    where there is an "interior minimum" in the MTU, especially when it's 
-    less than 1500. So we advertise a big MTU and just let the resulting 
-    big packets fragment.
-
-This usually works, but we do get bitten in cases where some intermediate
-point can't handle all that fragmentation.  We can't win on this one.
-

The MTU can be changed with an overridemtu= statement in - the config setup section of - ipsec.conf.5.

-

For a discussion of MTU issues and some possible solutions using - Linux advanced routing facilities, see the - Linux 2.4 Advanced Routing HOWTO. For a discussion of MTU and NAT - (Network Address Translation), see - James Carter's MTU notes.

-

Network address translation (NAT)

-

Network Address T -ranslation is a service provided by some gateway machines. Calling it - NAPT (adding the word Port) would be more precise, but - we will follow the widespread usage.

-

A gateway doing NAT rewrites the headers of packets it is forwarding, - changing one or more of:

- -

On Linux 2.4, NAT services are provided by the - netfilter(8) firewall code. There are several - Netfilter HowTos including one on NAT.

-

For older versions of Linux, this was referred to as "IP masquerade" - and different tools were used. See this - resource page.

-

Putting an IPsec gateway behind a NAT gateway is not recommended. See - our firewalls document.

-

NAT to non-routable addresses

-

The most common application of NAT uses private - non-routable addresses.

-

Often a home or small office network will have:

- -

Of course this poses a problem since several machines cannot use one - address. The best solution might be to obtain more addresses, but often - this is impractical or uneconomical.

-

A common solution is to have:

- -

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.

-

As far as anyone else on the Internet is concerned, the systems - behind the gateway are completely hidden. Only one machine with one IP - address is visible.

-

For IPsec on such a gateway, you can entirely ignore the NAT in:

- -

Those can be set up exactly as they would be if your gateway had no - other systems behind it.

-

You do, however, have to take account of the NAT in firewall rules - which affect packet forwarding.

-

NAT to routable addresses

-

NAT to routable addresses is also possible, but is less common and - may make for rather tricky routing problems. We will not discuss it - here. See the - Netfilter HowTos.

-
-Contents -Previous -Next - - diff --git a/doc/biblio.html b/doc/biblio.html deleted file mode 100644 index d54af5cbf..000000000 --- a/doc/biblio.html +++ /dev/null @@ -1,274 +0,0 @@ - - - -Introduction to FreeS/WAN - - - - -Contents -Previous -Next -
-

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.

-
Ross Anderson, Security Engineering - - a Guide to Building Dependable Distributed Systems -
Wiley, 2001, ISBN 0471389226 -

Easily the best book for the security professional I have seen. - Highly recommended. See the - book web page.

-

This is quite readable, but Schneier's Secrets and - Lies might be an easier introduction.

-
Bamford The Puzzle Palace, A report on NSA, - Americas's most Secret Agency -
Houghton Mifflin 1982 ISBN 0-395-31286-8 -
Bamford Body of Secrets -

The sequel.

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

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 -
-
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 book is now seriously out of date. It does not cover recent - developments such as commercial versions since PGP 5, the Open PGP - standard or GNU PG..

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

-
Kolesnikov and Hatch, Building Linux - Virtual Private Networks (VPNs) -
New Riders 2002 -

This has had a number of favorable reviews, including - this one on Slashdot. The book has a - web site.

-
Pete Loshin 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 MIT Press 1999 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.

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

-

Note (Mar 1, 2002): a new edition with different editors in the - works. Expect it this year.

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

-

This is worth reading even if you already understand security issues, - or think you do. To go deeper, follow it with Anderson's - Security Engineering.

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

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 -

A good book, with detailed coverage of ipchains(8) firewalls and of - many related issues.

-
-Contents -Previous -Next - - diff --git a/doc/compat.html b/doc/compat.html deleted file mode 100644 index f01efa64c..000000000 --- a/doc/compat.html +++ /dev/null @@ -1,707 +0,0 @@ - - - -Introduction to FreeS/WAN - - - - -Contents -Previous -Next -
-

Linux FreeS/WAN Compatibility Guide

-

Much 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.96:

- -

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 omitted

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

- -

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:

- -

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

- -

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.

-

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 the latest 2.2.x and 2.4.y

-

We develop and test on Redhat Linux using the most recent kernel in - the 2.2 and 2.4 series. In general, we recommend you use the latest - kernel in one of those series. Complications and caveats are discussed - below.

-

2.0.x 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 on 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 to 1.96
-
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.

-

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 - or 7.2 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. They are - soluble, but we recommend you upgrade to a later Redhat instead..

-

Redhat 7 ships with two compilers.

- -

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.

-

FreeS/WAN packages distributed for SuSE 7.0-7.2 were somehow - miscompiled. You can find fixed packages on - Kurt Garloff's page.

-

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" ] && 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

-

A recent (Nov 2001) mailing list points to a - web page on setting up several types of tunnel, including IPsec, on - Debian.

-

Some older information:

-
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 and later distributions, 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.
-

FreeS/WAN no longer includes GMP source.

-

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 manufacture an IPsec box based on an embedded MIPS running - Linux with FreeS/WAN. We have no details.

-

Transmeta Crusoe

-

The Merilus - Firecard, a Linux firewall on a PCI card, is based on a Crusoe - processor and supports FreeS/WAN.

-

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.

-

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:

- -

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.

-

More recently, a patch to support some hardware accelerators has been - posted:

-
Subject: [Design] [PATCH] H/W acceleration patch
-   Date: Tue, 18 Sep 2001
-   From: "Martin Gadbois" <martin.gadbois@colubris.com>
- 
-Finally!!
-Here's a web site with H/W acceleration patch for FreeS/WAN 1.91, including
-S/W and Hifn 7901 crypto support.
-
-http://sources.colubris.com/
-
-Martin Gadbois
-

Hardware accelerators could take performance well beyond what - FreeS/WAN can do in software (discussed here -). Here is some discussion off the IETF IPsec list, October 2001:

-
 ... Currently shipping chips deliver, 600 mbps throughput on a single
- stream of 3DES IPsec traffic.  There are also chips that use multiple
- cores to do 2.4 gbps.  We (Cavium) and others have announced even faster
- chips. ... Mid 2002 versions will handle at line rate (OC48 and OC192)
- IPsec and SSL/TLS traffic not only 3DES CBC but also AES and arc4.
-

The patches to date support chips that have been in production for - some time, not the state-of-the-art latest-and-greatest devices - described in that post. However, they may still outperform software and - they almost certainly reduce CPU overhead.

-

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, and a patched version with IPv6 support is - available. For more recent information, check the - mailing list.

-

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:

- -

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:

- -

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.

-
-Contents -Previous -Next - - diff --git a/doc/config.html b/doc/config.html deleted file mode 100644 index 4e9f0a513..000000000 --- a/doc/config.html +++ /dev/null @@ -1,308 +0,0 @@ - - - -Introduction to FreeS/WAN - - - - -Contents -Previous -Next -
-

How to configure FreeS/WAN

-

This page will teach you how to configure a simple network-to-network - link or a Road Warrior connection between two Linux FreeS/WAN boxes.

-

See also these related documents:

- -

The network-to-network setup allows you to connect two office - networks into one Virtual Private Network, while the Road Warrior - connection secures a laptop's telecommute to work. Our examples also - show the basic procedure on the Linux FreeS/WAN side where another - IPsec peer is in play.

-

Shortcut to net-to-net. -
Shortcut to Road Warrior.

-

Requirements

-

To configure the network-to-network connection you must have:

- -

For the Road Warrior you need:

- -

If both IPs are dynamic, your situation is a bit trickier. Your best - bet is a variation on the Road Warrior, as - described in - this mailing list message.

-

Net-to-Net connection

-

Gather information

-

For each gateway, compile the following information:

- -

Get your leftrsasigkey

-

On your local Linux FreeS/WAN gateway, print your IPsec public key:

-
    ipsec showhostkey --left
-

The output should look like this (with the key shortened for easy - reading):

-
    # RSA 2048 bits   xy.example.com   Fri Apr 26 15:01:41 2002
-    leftrsasigkey=0sAQOnwiBPt...
-

Don't have a key? Use - ipsec newhostkey to create one.

-

...and your rightrsasigkey

-

Get a console on the remote side:

-
    ssh2 ab.example.com
-

In that window, type:

-
    ipsec showhostkey --right
-

You'll see something like:

-
    # RSA 2192 bits   ab.example.com   Thu May 16 15:26:20 2002
-    rightrsasigkey=0sAQOqH55O...
-

Edit /etc/ipsec.conf

-

Back on the local gate, copy our template to /etc/ipsec.conf -. (on Mandrake, /etc/freeswan/ipsec.conf). Substitute the - information you've gathered for our example data.

-
conn net-to-net
-    left=192.0.2.2                 # Local vitals
-    leftsubnet=192.0.2.128/29      # 
-    leftid=@xy.example.com         #   
-    leftrsasigkey=0s1LgR7/oUM...   #
-    leftnexthop=%defaultroute      # correct in many situations 
-    right=192.0.2.9                # Remote vitals
-    rightsubnet=10.0.0.0/24        #
-    rightid=@ab.example.com        # 
-    rightrsasigkey=0sAQOqH55O...   #
-    rightnexthop=%defaultroute     # correct in many situations
-    auto=add                       # authorizes but doesn't start this 
-                                   # connection at startup
-

"Left" and "right" should represent the machines that have FreeS/WAN - installed on them, and "leftsubnet" and "rightsubnet" machines that are - being protected. /32 is assumed for left/right and left/rightsubnet - parameters.

-

Copy conn net-to-net to the remote-side /etc/ipsec.conf. - If you've made no other modifications to either ipsec.conf, - simply:

-
    scp2 ipsec.conf root@ab.example.com:/etc/ipsec.conf
-

Start your connection

-

Locally, type:

-
    ipsec auto --up net-to-net
-

You should see:

-
    104 "net-net" #223: STATE_MAIN_I1: initiate
-    106 "net-net" #223: STATE_MAIN_I2: sent MI2, expecting MR2
-    108 "net-net" #223: STATE_MAIN_I3: sent MI3, expecting MR3
-    004 "net-net" #223: STATE_MAIN_I4: ISAKMP SA established
-    112 "net-net" #224: STATE_QUICK_I1: initiate
-    004 "net-net" #224: STATE_QUICK_I2: sent QI2, IPsec SA established
-

The important thing is IPsec SA established. If you're - unsuccessful, see our troubleshooting - tips.

-

Do not MASQ or NAT packets to be tunneled

-

If you are using IP masquerade or - Network Address Translation (NAT) on either gateway, you must now - exempt the packets you wish to tunnel from this treatment. For example, - if you have a rule like:

-
iptables -t nat -A POSTROUTING -o eth0 -s 10.0.0.0/24 -j MASQUERADE
-
-

change it to something like:

-
iptables -t nat -A POSTROUTING -o eth0 -s 10.0.0.0/24 -d \! 192.0.2.128/29 -j MASQUERADE
-

This may be necessary on both gateways.

-

Test your connection

-

Sit at one of your local subnet nodes (not the gateway), and ping a - subnet node on the other (again, not the gateway).

-
    ping fileserver.toledo.example.com
-

While still pinging, go to the local gateway and snoop your outgoing - interface, for example:

-
    tcpdump -i ppp0
-

You want to see ESP (Encapsulating Security Payload) packets moving - back and forth between the two gateways at the same frequency as - your pings:

-
    19:16:32.046220 192.0.2.2 > 192.0.2.9: ESP(spi=0x3be6c4dc,seq=0x3)
-    19:16:32.085630 192.0.2.9 > 192.0.2.2: ESP(spi=0x5fdd1cf8,seq=0x6)
-

If you see this, congratulations are in order! You have a tunnel - which will protect any IP data from one subnet to the other, as it - passes between the two gates. If not, go and - troubleshoot.

-

Note: your new tunnel protects only net-net traffic, not - gateway-gateway, or gateway-subnet. If you need this (for example, if - machines on one net need to securely contact a fileserver on the IPsec - gateway), you'll need to create - extra connections.

-

Finishing touches

-

Now that your connection works, name it something sensible, like:

-
conn winstonnet-toledonet
-

To have the tunnel come up on-boot, replace

-
    auto=add
-

with:

-
    auto=start
-

Copy these changes to the other side, for example:

-
    scp2 ipsec.conf root@ab.example.com:/etc/ipsec.conf
-

Enjoy!

-

Road Warrior Configuration

-

Gather information

-

You'll need to know:

- -

Get your leftrsasigkey...

-

On your laptop, print your IPsec public key:

-
    ipsec showhostkey --left
-

The output should look like this (with the key shortened for easy - reading):

-
    # RSA 2192 bits   road.example.com   Sun Jun  9 02:45:02 2002
-    leftrsasigkey=0sAQPIPN9uI...
-

Don't have a key? See these - instructions.

-

...and your rightrsasigkey

-

Get a console on the gateway:

-
    ssh2 xy.example.com
-

View the gateway's public key with:

-
    ipsec showhostkey --right
-

This will yield something like

-
    # RSA 2048 bits   xy.example.com   Fri Apr 26 15:01:41 2002
-    rightrsasigkey=0sAQOnwiBPt...
-

Customize /etc/ipsec.conf

-

On your laptop, copy this template to /etc/ipsec.conf. (on - Mandrake, /etc/freeswan/ipsec.conf). Substitute the - information you've gathered for our example data.

-
conn road
-    left=%defaultroute             # Picks up our dynamic IP 
-    leftnexthop=%defaultroute      # 
-    leftid=@road.example.com       # Local information
-    leftrsasigkey=0sAQPIPN9uI...   #
-    right=192.0.2.10               # Remote information
-    rightsubnet=10.0.0.0/24        #
-    rightid=@xy.example.com        # 
-    rightrsasigkey=0sAQOnwiBPt...  #
-    auto=add                       # authorizes but doesn't start this
-                                   # connection at startup
-

The template for the gateway is different. Notice how it reverses - left and right, in keeping with our convention that - Left is Local, Right - Remote. Be sure to switch your rsasigkeys in keeping with - this.

-
    ssh2 xy.example.com
-    vi /etc/ipsec.conf
-

and add:

-
conn road
-    left=192.0.2.2                 # Gateway's information
-    leftid=@xy.example.com         #
-    leftsubnet=192.0.2.128/29      #
-    leftrsasigkey=0sAQOnwiBPt...   #
-    rightnexthop=%defaultroute     # correct in many situations
-    right=%any                     # Wildcard: we don't know the laptop's IP
-    rightid=@road.example.com      #
-    rightrsasigkey=0sAQPIPN9uI...  #
-    auto=add                       # authorizes but doesn't start this
-                                   # connection at startup
-

Start your connection

-

You must start the connection from the Road Warrior side. On your - laptop, type:

-
    ipsec auto --start net-to-net
-

You should see:

-
104 "net-net" #223: STATE_MAIN_I1: initiate
-106 "road" #301: STATE_MAIN_I2: sent MI2, expecting MR2
-108 "road" #301: STATE_MAIN_I3: sent MI3, expecting MR3
-004 "road" #301: STATE_MAIN_I4: ISAKMP SA established
-112 "road" #302: STATE_QUICK_I1: initiate
-004 "road" #302: STATE_QUICK_I2: sent QI2, IPsec SA established
-

Look for IPsec SA established. If you're unsuccessful, see - our troubleshooting tips.

-

Do not MASQ or NAT packets to be tunneled

-

If you are using IP masquerade or - Network Address Translation (NAT) on either gateway, you must now - exempt the packets you wish to tunnel from this treatment. For example, - if you have a rule like:

-
iptables -t nat -A POSTROUTING -o eth0 -s 10.0.0.0/24 -j MASQUERADE
-
-

change it to something like:

-
iptables -t nat -A POSTROUTING -o eth0 -s 10.0.0.0/24 -d \! 192.0.2.128/29 -j MASQUERADE
-

Test your connection

-

From your laptop, ping a subnet node behind the remote gateway. Do - not choose the gateway itself for this test.

-
    ping ns.winston.example.com
-

Snoop the packets exiting the laptop, with a command like:

-
    tcpdump -i wlan0
-

You have success if you see (Encapsulating Security Payload) packets - travelling in both directions:

-
    19:16:32.046220 192.0.2.2 > 192.0.2.9: ESP(spi=0x3be6c4dc,seq=0x3)
-    19:16:32.085630 192.0.2.9 > 192.0.2.2: ESP(spi=0x5fdd1cf8,seq=0x6)
-

If you do, great! Traffic between your Road Warrior and the net - behind your gateway is protected. If not, see our - troubleshooting hints.

-

Your new tunnel protects only traffic addressed to the net, not to - the IPsec gateway itself. If you need the latter, you'll want to make - an extra tunnel..

-

Finishing touches

-

On both ends, name your connection wisely, like:

-
conn mike-to-office
-

On the laptop only, replace

-
    auto=add
-

with:

-
    auto=start
-

so that you'll be connected on-boot.

-

Happy telecommuting!

-

Multiple Road Warriors

-

If you're using RSA keys, as we did in this example, you can add as - many Road Warriors as you like. The left/rightid parameter lets Linux - FreeS/WAN distinguish between multiple Road Warrior peers, each with - its own public key.

-

The situation is different for shared secrets (PSK). During a PSK - negotiation, ID information is not available at the time Pluto is - trying to determine which secret to use, so, effectively, you can only - define one Roadwarrior connection. All your PSK road warriors must - therefore share one secret.

-

What next?

-

Using the principles illustrated here, you can try variations such - as:

- -

Or, look at some of our more - complex configuration examples..

-
-Contents -Previous -Next - - diff --git a/doc/faq.html b/doc/faq.html deleted file mode 100644 index b0fed502e..000000000 --- a/doc/faq.html +++ /dev/null @@ -1,2339 +0,0 @@ - - - -Introduction to FreeS/WAN - - - - -Contents -Previous -Next -
-

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.

-
-

Index of FAQ questions

- -
-

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.

-

To start setting it up, go to our - quickstart guide.

-

Our web links document has information on - IPsec for other systems.

-

How do I report a problem or seek help?

-
-
Read our troubleshooting document.
-
-

It may guide you to a solution. If not, see its - problem reporting section.

-

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 users 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.
    • -
  • It is more likely to get a quick response. Developers may get behind - on email, or even ignore it entirely for a while, but a list message - (given a reasonable Subject: line) is certain to be read by a fair - number of people within hours.
    • -
  • It may also be important because of - 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.
    • -
-
-
Try irc.freenode.net#freeswan.
-
-

FreeS/WAN developers, volunteers and users can often be found there. - Be patient and be prepared to provide lots of information to support - your question.

-

If your question was really interesting, and you found an answer, - please share that with the class by posting to the - users mailing list. That way others with the same problem can find - your answer in the archives.

-
-
Premium support is also available.
-
-

See the next several questions.

-
-
-

Can I get ...

-

Can I get an off-the-shelf system that includes - FreeS/WAN?

-

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. Then consider hiring a consultant (see next question) to - help define your requirements.

-

Can I hire consultants or staff who know - FreeS/WAN?

-

If you want the help of a contractor, or to hire staff with FreeS/WAN - expertise, you could:

- -

For companies offerring support, see the next question.

-

Can I get commercial support?

-

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.

-

Release questions

-

What is the current release?

-

The current release is the highest-numbered tarball on our - distribution site. Almost always, any of - the mirrors will have the same file, though perhaps not for a day - or so after a release.

-

Unfortunately, the web site is not always updated as quickly as it - should be.

-

When is the next release?

-

We try to do a release approximately every six to eight weeks.

-

If pre-release tests fail and the fix appears complex, or more - generally if the code does not appear stable when a release is - scheduled, we will just skip that release.

-

For serious bugs, we may bring out an extra bug-fix release. These - get numbers in the normal release series. For example, there was a bug - found in FreeS/WAN 1.6, so we did another release less than two weeks - later. The bug-fix release was called 1.7.

-

Are there known bugs in the current release?

-

Any problems we are aware of at the time of a release are documented - in the BUGS file for that release. You should - also look at the CHANGES file.

-

Bugs discovered after a release are discussed on the - mailing lists. The easiest way to check for any problems in the - current code would be to peruse the - List In Brief.

-

Modifications and contributions

-

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.

-

Before investing much energy in any such project, we suggest that you

- -

This may prevent duplicated effort, or lead to interesting - collaborations.

-

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.

-

Discussion of possible contributions takes place on the - design mailing list.

-

Is there detailed design documentation?

- There are: - -

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.

-

Will FreeS/WAN work in my environment?

-

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 - interoperation document devoted to this problem.

-

An important part of that document is links to the many - user-written HowTos on interoperation between FreeS/WAN and various - other implementations. Often the users know more than the developers - about these issues (and almost always more than me :-), so these - documents may be your best resource.

-

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 a few cases, there are some complications. See our - interoperation document for details.

-

Is there a limit on throughput?

-

There is no hard limit, but see below.

-

Is there a limit on number of tunnels?

-

There is no hard limit, but see next question.

-

Is a ... fast enough to handle FreeS/WAN with my - loads?

-

A quick summary:

-
-
Even a limited machine can be useful
-
A 486 can handle a T1, ADSL or cable link, though the machine may be - breathing hard.
-
A mid-range PC (say 800 MHz with good network cards) can do a lot of - IPsec
-
With up to roughly 50 tunnels and aggregate bandwidth of 20 Megabits - per second, it willl have cycles left over for other tasks.
-
There are limits
-
Even a high end CPU will not come close to handling a fully loaded - 100 Mbit/second Ethernet link. -

Beyond about 50 tunnels it needs careful management.

-
-
-

See our FreeS/WAN performance document - for details.

-

Will FreeS/WAN work on ... ?

-

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

-

Will FreeS/WAN run on non-Intel CPUs?

-

FreeS/WAN is intended to run on all CPUs Linux supports -. 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.

-

Will FreeS/WAN run on multiprocessors?

-

FreeS/WAN is designed to work on any SMP architecture Linux supports, - and has been tested successfully on at least dual processor Intel - architecture machines. Details are in our - compatibility document.

-

Will FreeS/WAN work on an older kernel?

-

It might, but we strongly recommend using a recent 2.2 or 2.4 series - kernel. Sometimes the newer versions include security fixes which can - be quite important on a gateway.

-

Also, we use recent kernels for development and testing, so those are - better tested and, if you do encounter a problem, more easily - supported. If something breaks applying recent FreeS/WAN patches to an - older kernel, then "update your kernel" is almost certain to be the - first thing we suggest. It may be the only suggestion we have.

-

The precise kernel versions supported by a particular FreeS/WAN - release are given in the README file of that release.

-

See the following question for more on kernels.

-

Will FreeS/WAN run on the latest kernel - version?

-

Sometimes yes, but quite often, no.

-

Kernel versions supported are given in the README - file of each FreeS/WAN release. Typically, they are 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 -). Often FreeS/WAN will work on slightly later kernels as well, but of - course this cannot be guaranteed.

-

For example, FreeS/WAN 1.91 was released for kernels 2.2.19 or 2.4.5, - the current kernels at the time. It also worked on 2.4.6, 2.4.7 and - 2.4.8, but 2.4.9 had changes that caused compilation errors if it was - patched with FreeS/WAN 1.91.

-

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:

- -

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

-

Will FreeS/WAN work on unusual network - hardware?

-

IPsec is designed to work over any network that IP works over, and - FreeS/WAN is intended to work over any network interface hardware that - Linux supports.

-

If you have working IP on some unusual interface -- perhaps Arcnet, - Token Ring, ATM or Gigabit Ethernet -- then IPsec should "just work".

-

That said, practice is sometimes less tractable than theory. Our - testing is done almost entirely on:

- -

If you have some other interface, especially an uncommon one, it is - entirely possible you will get bitten either by a FreeS/WAN bug which - our testing did not turn up, or by a bug in the driver that shows up - only with our loads.

-

If IP works on your interface and FreeS/WAN doesn't, seek help on the mailing lists.

-

Another FAQ section describes MTU problems -. These are a possibility for some interfaces.

-

Will FreeS/WAN work on a VLAN (802.1q) network?

-

Yes, FreeSwan works fine, though some network drivers have problems - with jumbo sized ethernet frames. If you used interfaces=%defaultroute - you do not need to change anything, but if you specified an interface - (eg eth0) then remember you must change that to reflect the VLAN - interface (eg eth0.2 for VLAN ID 2).

-

The "eepro100" module is known to be broken, use the e100 driver for - those cards instead (included in 2.4 as 'alternative driver' for the - Intel EtherExpressPro/100.

-

You do not need to change any MTU setting (those are workarounds - that are only needed for buggy drivers)

-

This FAQ contributed by Paul Wouters.

-

Does FreeS/WAN support ...

-

For a discussion of which parts of the IPsec specifications FreeS/WAN - does and does not implement, see our - compatibility document.

-

For information on some often-requested features, see below.

-

Does FreeS/WAN support site-to-site VPN ( -Virtual Private Network) applications?

-

Absolutely. See this FreeS/WAN-FreeS/WAN - configuration example. If only one site is using FreeS/WAN, there - may be a relevant HOWTO on our interop page.

-

Does FreeS/WAN support remote users connecting - to a LAN?

-

Yes. We call the remote users "Road Warriors". Check out our - FreeS/WAN-FreeS/WAN Road Warrior - Configuration Example.

-

If your Road Warrior is a Windows or Mac PC, you may need to install - an IPsec implementation on that machine. Our - interop page lists many available brands, and features links to - several HOWTOs.

-

Does FreeS/WAN support remote users - using shared secret authentication?

-

Yes, but there are severe restrictions, so - we strongly recommend using - RSA keys for - authentication instead.

-

See this FAQ question.

-

Does FreeS/WAN support wireless networks?

-

Yes, it is a common practice to use IPsec over wireless networks - because their built-in encryption, WEP, - is insecure.

-

There is some discussion - in our advanced configuration document. See also the - WaveSEC site.

-

Does FreeS/WAN support X.509 or other PKI - certificates?

-

Vanilla FreeS/WAN does not support X.509, but Andreas Steffen and - others have provided a popular, well-supported X.509 patch.

- -

Linux FreeS/WAN features Opportunistic - Encryption, an alternative Public Key Infrastructure based on - Secure DNS.

-

Does FreeS/WAN support user authentication (Radius, - SecureID, Smart Card...)?

-

Andreas Steffen's X.509 - patch (v. 1.42+) supports Smart Cards. The patch does not ship with - vanilla FreeS/WAN, but will be incorporated into - Super FreeS/WAN 2.01+. The patch implements the PCKS#15 - Cryptographic Token Information Format Standard, using the OpenSC - smartcard library functions.

-

Older news:

-

A user-supported patch to FreeS/WAN 1.3, for smart card style - authentication, is available on - Bastiaan's site. It supports skeyid and ibutton. This patch is not - part of Super FreeS/WAN.

-

For a while progress on this front was impeded by a lack of standard. - The IETF - working group has now nearly completed its recommended solution to - the problem; meanwhile several vendors have implemented various things.

- - -

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 either of those is trustworthy, it is not clear that you need user - authentication in IPsec.

-

Does FreeS/WAN support NAT traversal?

-

Vanilla FreeS/WAN does not, but thanks to Mathieu Lafon and Arkoon - Network Security, there's a patch to support this.

- -

The NAT traversal patch has some issues with PSKs, so you may wish to - authenticate with RSA keys, or X.509 (requires a patch which is also - included in Super FreeS/WAN). Doing the latter also has advantages when - dealing with large numbers of clients who may be behind NAT; instead of - having to make an individual Roadwarrior connection for each virtual - IP, you can use the "rightsubnetwithin" parameter to specify a range. - See - these rightsubnetwithin instructions.

-

Does FreeS/WAN support assigning a "virtual - identity" to a remote system?

-

Some IPsec implementations allow you to make the source address on - packets sent by a Road Warrior machine be something other than the - address of its interface to the Internet. This is sometimes described - as assigning a virtual identity to that machine.

-

FreeS/WAN does not directly support this, but it can be done. See - this FAQ question.

-

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.

-

Does FreeS/WAN support AES encryption?

-

AES is a new US government - block cipher standard to replace the obsolete - DES.

-

At time of writing (March 2002), the FreeS/WAN distribution does not - yet support AES but user-written patches - are available to add it. Our kernel programmer is working on - integrating those patches into the distribution, and there is active - discussion of this on the design mailimg list.

-

Does FreeS/WAN support other encryption - algorithms?

-

Currently triple DES is the only - cipher supported. AES will almost certainly be added (see previous - question), and it is likely that in the process we will also add the - other two AES finalists with open licensing, Twofish and Serpent.

-

We are extremely reluctant to add other ciphers. This would make both - use and maintenance of FreeS/WAN more complex without providing any - clear benefit. Complexity is emphatically not desirable in a security - product.

-

Various users have written patches to add other ciphers. We provide - links to these.

-

Can I ...

-

Can I use policy groups along with - explicitly configured connections?

-

Yes, you can, so long as you pay attention to the selection rule, - which can be summarized "the most specific connection wins". We - describe the rule in our - policy groups document, and provide a more technical explanation in man ipsec.conf.

-

A good guideline: If you have a regular connection defined in - ipsec.conf, ensure that a subset of that connection is not listed - in a less restrictive policy group. Otherwise, FreeS/WAN will use the - subset, with its more specific source/destination pair.

-

Here's an example. Suppose you are the system administrator at - 192.0.2.2. You have this connection in ipsec.conf: ipsec.conf -:

-
conn net-to-net
-    left=192.0.2.2           # you are here
-    right=192.0.2.8
-    rightsubnet=192.0.2.96/27
-    ....
-
-

If you then place a host or net within rightsubnet, (let's - say 192.0.2.98) in private-or-clear, you may find that - 192.0.2.2 at times communicates in the clear with 192.0.2.98. That's - consistent with the rule, but may be contrary to your expectations.

-

On the other hand, it's safe to put a larger subnet in a less - restrictive policy group file. If private-or-clear contains - 192.0.2.0/24, then the more specific net-to-net connection - is used for any communication to 192.0.2.96/27. The more general policy - applies only to communication with hosts or subnets in 192.0.2.0/24 - without a more specific policy or connection.

-

Can I turn off policy groups?

-

Yes. Use these - instructions.

- - -

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 - (a virtual identity)?

-

Often it would be convenient to be able to give a Road Warrior an IP - address which appears to be on the local network. Some IPsec - implementations have support for this, sometimes calling the feature - "virtual identity".

-

Currently (Sept 2002) FreeS/WAN does not support this, and we have no - definite plans to add it. The difficulty is that is not yet a standard - mechanism for it. There is an Internet Draft for a method of doing it - using DHCP which looks promising. - FreeS/WAN may support that in a future release.

-

In the meanwhile, you can do it yourself using the Linux iproute2(8) - facilities. Details are in - this paper.

-

Another method has also been discussed on the mailing list.:

- -

For example, you might have:

-
-
leftsubnet=a.b.c.0/25
-
head office network
-
rightsubnet=a.b.c.129/32
-
extruded to a road warrior. Note that this is not in a.b.c.0/25
-
a.b.c.0/24
-
whole network, including both the above
-
-

You then set up routing so that the office machines use the IPsec - gateway as their route to a.b.c.128/25. The leftsubnet parameter tells - the road warriors to use tunnels to reach a.b.c.0/25, so you should - have two-way communication. Depending or your network and applications, - there may be some additional work to do on DNS or Windows configuration

-

Can I support many road warriors with one - gateway?

-

Yes. This is easily done, using

-
-
either RSA authentication
-
standard in the FreeS/WAN distribution
-
or X.509 certificates
-
requires Super FreeS/WAN or a patch.
-
-

In either case, each Road Warrior must have a different key or - certificate.

-

It is also possible using pre-shared key authentication, though we - don't recommend this; see the next question for - details.

-

If you expect to have more than a few dozen Road Warriors connecting - simultaneously, you may need a fairly powerful gateway machine. See our - document on FreeS/WAN performance.

-

Can I have many road warriors using shared secret - authentication?

-

Yes, but avoid it if possible.

-

You can have multiple Road Warriors using shared secret - authentication only if they all use the same secret. - You must also set:

-

-
   uniqueids=no
-

in the connection definition.

-

Why it's less secure:

- -

This is a designed-in limitation of the - IKE key negotiation protocol, not a problem with our - implementation.

-

We very strongly recommend that you avoid using shared secret - authentication for multiple Road Warriors. Use RSA - authentication instead.

-

The longer story: When using shared secrets, the protocol requires - that the responding gateway be able to determine which secret to use at - a time when all it knows about the initiator is an IP address. This - works fine if you know the initiator's address in advance and can use - it to look up the appropiriate secret. However, it fails for Road - Warriors since the gateway cannot know their IP addresses in advance.

-

With RSA signatures (or certificates) the protocol is slightly - different. The initiator provides an identifier early in the exchange - and the responder can use that identifier to look up the correct key or - certificate. See 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 (type of service) - information from the encapsulated packet to the outer header reveals - the TOS information to an eavesdropper. This does not tell him much, - but it might be of use in traffic - analysis. Since we do not have to give it to him, our default is - not to.

-

Even with the TOS hidden, you can still:

- -

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:

- -

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, L2TP or PPTP tunnels over IPsec?

-

Yes. Normally this is not necessary, but it is useful in a few - special cases. For example, if you must route non-IP packets such as - IPX, you will need to use a tunneling protocol that can route these - packets. IPsec can be layered around it for extra security. Another - example: you can provide failover protection for high availability (HA) - environments by combining IPsec with other tools. Ken Bantoft describes - one such setup in Using - FreeS/WAN with Linux-HA, GRE, OSPF and BGP for enterprise grade VPN - solutions.

-

GRE over IPsec is covered as part of - that document. - Here are links to other GRE resources. Jacco de Leuw has created - this page on L2TP over IPsec with instructions for FreeS/WAN and - several other brands of IPsec software.

-

Please let us know of other useful links via the - mailing lists.

-

... use Network Neighborhood (Samba, NetBIOS) over - IPsec?

-

Your local PC needs to know how to translate NetBIOS names to IP - addresses. It may do this either via a local LMHOSTS file, or using a - local or remote WINS server. The WINS server is preferable since it - provides a centralized source of the information to the entire network. - To use a WINS server over the VPN (or - any IP-based network), you must enable "NetBIOS over TCP".

-

Samba can emulate a WINS server on - Linux.

-

See also several discussions in our - September 2002 Users archives

-

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:

- -

However, we also list some of the commonest problems here.

-

I cannot ping ....

-

This question is dealt with in the advanced 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 = 192.0.2.8
-             |
-
-       ~ internet ~
-
-             |
-      eth0 = 192.0.2.11
-         gate2
-      eth1 = x.y.z.1
-              |
-       subnet x.y.z.0/24
-

and the connection description:

-
conn abc-xyz
-     left=192.0.2.8
-     leftsubnet=a.b.c.0/24
-     right=192.0.2.11
-     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:

- -

In some cases, you may be able to get around this. For the example - network above, you could use:

-
        ping -I a.b.c.1 x.y.z.1
-

Both the adresses given are within protected subnets, so this should - go through the tunnel.

-

If required, you can build additional tunnels so that all the - machines involved can talk to all the others. See - multiple tunnels in the advanced 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:

- -

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:

- -

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

- -

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

-

Some advice from technical lead Henry Spencer on diagnosing such - problems:

-
> > Packets vanishing between the hardware interface and the ipsecN interface
-> > is usually the result of firewalls not being configured to let them in...
-> 
-> Thanks for the suggestion. If only it were that simple! My ipchains startup
-> script does take care of that, but just in case I manually inserted rules 
-> accepting everything from london on dublin. No difference.
-
-The other thing to check is whether the "RX packets dropped" count on the
-ipsecN interface (run "ifconfig ipsecN", for N=1 or whatever, to see the
-counts) is rising.  If so, then there's some sort of configuration mismatch
-between the two ends, and IPsec itself is rejecting them.  If none of the
-ipsecN counts is rising, then the packets are never reaching the IPsec
-machinery, and the problem is almost certainly in firewalls etc.
-

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

-

Disappearing %defaultroute

-

When an underlying connection (eg. ppp) goes down, FreeS/WAN will not - recover properly without a little help. Here are the symptoms that - FreeS/WAN user Michael Carmody noticed:

-
-> After about 24 hours the freeswan connection takes over the default route.
-> 
-> i.e instead of deafult gateway pointing to the router via eth0, it becomes a 
-> pointer to the router via ipsec0.
- 
-> All internet access is then lost as all replies (and not just the link I 
-> wanted) are routed out ipsec0 and the router doesn't respond to the ipsec 
-> traffic.
-
-

If you're using a FreeS/WAN 2.x/KLIPS system, simply re-attach the - IPsec virtual interface with ipsec tnconfig command such as:

-
    ipsec tnconfig --attach --virtual ipsec0 --physical ppp0
-

In your command, name the physical and virtual interfaces as they - appear paired on your system during regular uptime. For a system with - several physical/virtual interface pairs on flaky links, you'll need - more than one such command. If you're using FreeS/WAN 1.x, you must - restart FreeS/WAN, which is more time consuming.

-

- Here is a script which can help to automate the process of - FreeS/WAN restart at need. It could easily be adapted to use tnconfig - instead.

-

TCPdump on the gateway shows strange things -

- As another user pointed out, keeping the connect -

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.

-

See our testing document for - more detail.

-

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:

- -

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:

- -

One manual connection works, but second one - fails

-

This is a 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 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:

- -

IPsec works, but connections using compression fail -

-

When we first added compression, we saw some problems:

- -

We have not seen either problem in some time (at least six months as - I write in March 2002), but if you have some unusual configuration then - you may see them.

-

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 packet - fragmentation and perhaps path MTU - discovery.

-

Our troubleshooting document - covers these problems. Information on the underlying mechanism is in - our background document.

-

Subnet-to-subnet works, but tests from the gateways - don't

-

This is described under I cannot ping... - above.

-

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

Interpreting error messages

-

route-client (or host) exited with status 7 -

-

Here is a discussion of this error from FreeS/WAN "listress" (mailing - list tech support person) Claudia Schmeing. The "FAQ on the network - unreachable error" which she refers to is the next question below.

-
> I reached the point where the two boxes (both on dial-up connections, but
-> treated as static IPs by getting the IP and editing ipsec.conf after the
-> connection is established) to the point where they exchange some info, but I
-> get an error like "route-client command exited with status 7 \n internal
-> error".
-> Where can I find a description of this error?
-
-In general, if the FAQ doesn't cover it, you can search the mailing list 
-archives - I like to use
-http://www.sandelman.ottawa.on.ca/linux-ipsec/
-but you can see doc/mail.html for different archive formats.
-
-
-Your error comes from the _updown script, which performs some
-routing and firewall functions to help Linux FreeS/WAN. More info
-is available at doc/firewall.html and man ipsec.conf. Its routing
-is integral to the health of Linux FreeS/WAN; it also provides facility
-to insert custom firewall rules to be executed when you create or destroy
-a connection.
-
-Yours is, of course, a routing error. You can be fairly sure the routing 
-machinery is saying "network is unreachable". There's a FAQ on the 
-"network is unreachable" error, but more information is available now; read on.
-
-If your _updown script is recent (for example if it shipped with 
-Linux FreeS/WAN 1.91), you will see another debugging line in your logs 
-that looks something like this:
-
-> output: /usr/local/lib/ipsec/_updown: `route add -net 128.174.253.83 
-> netmask 255.255.255.255 dev ipsec0 gw 66.92.93.161' failed
-
-This is, of course, the system route command that exited with status 7, 
-(ie. failed). Man route for details. Seeing the command typed out yields 
-more information. If your _updown script is older, you may wish to update 
-it to show the command explicitly.
-
-Three parameters fed to the route command: net, netmask and gw [gateway] 
-are derived from things you've put in ipsec.conf.
-
-Net and netmask are derived from the peer's IP and mask. In more detail:
-
-You may see a routing error when routing to a client (ie. subnet), or 
-to a host (IPSec gateway or freestanding host; a box that does IPSec for
-itself). In _updown, the "route-client" section  is responsible to set up 
-the route for IPSec'd (usually, read 'tunneled') packets headed to a 
-peer subnet. Similarly, route-host routes IPSec'd packets to a peer host
-or IPSec gateway.
-
-When routing to a 'client', net and netmask are ipsec.conf's left- or 
-rightsubnet (whichever is not local). Similarly, when routing to a 
-'host' the net is left or right. Host netmask is always /32, indicating a 
-single machine.
-
-Gw is nexthop's value. Again, the value in question is left- or rightnexthop,
-whichever is local. Where left/right or left-/rightnexthop has the special 
-value %defaultroute (described in man ipsec.conf), gw will automagically get
-the value of the next hop on the default route.
-
-Q: "What's a nexthop and why do I need one?"
-
-A: 'nexthop' is a routing kluge; its value is the next hop away
-   from the machine that's doing IPSec, and toward your IPSec peer. 
-   You need it to get the processed packets out of the local system and 
-   onto the wire. While we often route other packets through the machine 
-   that's now doing IPSec, and are done with it, this does not suffice here. 
-   After packets are processed with IPSec, this machine needs to know where 
-   they go next. Of course using the 'IPSec gateway' as their routing gateway 
-   would cause an infinite loop! [To visualize this, see the packet flow 
-   diagram at doc/firewall.html.] To avoid this, we route packets through 
-   the next hop down their projected path.
-
-Now that you know the background, consider:
-1. Did you test routing between the gateways in the absence of Linux
-   FreeS/WAN, as recommended? You need to ensure the two machines that
-   will be running Linux FreeS/WAN can route to one another before trying to 
-   make a secure connection.
-2. Is there anything obviously wrong with the sense of your route command?
-
-Normally, this problem is caused by an incorrect local nexthop parameter.
-Check out the use of %defaultroute, described in man ipsec.conf. This is
-a simple way to set nexthop for most people. To figure nexthop out by hand,
-traceroute in-the-clear to your IPSec peer. Nexthop is the traceroute's 
-first hop after your IPSec gateway.
-

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

-

See also the FAQ question route-client (or - host) exited with status 7.

-

ipsec_setup: modprobe: Can't locate module ipsec -

-

ipsec_setup: Fatal error, kernel appears to lack - KLIPS

-

These messages indicate an installation failure. The kernel you are - running does not contain the KLIPS - (kernel IPsec) code.

-

Note that the "modprobe: Can't locate module ipsec" message appears - even if you are not using modules. If there is no KLIPS in your kernel, - FreeS/WAN tries to load it as a module. If that fails, you get this - message.

-

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.

-

Message numbers (MI3, QR1, et cetera) in Pluto - messages

-

Pluto messages often indicate where Pluto is in the IKE protocols. - The letters indicate Main mode or Q -uick mode and Initiator or Responder. - The numerals are message sequence numbers. For more detail, see our - IPsec section.

-

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

-

Older versions of FreeS/WAN used this message. The same error now - gives the "we have no ipsecN ..." error described just below.

-

... we have no ipsecN interface for either - end of this connection

-

Your tunnel has no IP address which matches the IP address of any of - the available IPsec interfaces. Either you've misconfigured the - connection, or you need to define an appropriate IPsec interface - connection. interfaces=%defaultroute works in many cases.

-

A longer story: 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:

- -

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:

- -

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

rsasigkey dumps core

- A comment on this error from Henry: -
On Fri, 29 Jun 2001, Rodrigo Gruppelli wrote:
-> ...Well, it seem that there's
-> another problem with it. When I try to generate a pair of RSA keys,
-> rsasigkey cores dump...
-
-*That* is a neon sign flashing "GMP LIBRARY IS BROKEN".  Rsasigkey calls
-GMP a lot, and our own library a little bit, and that's very nearly all it
-does.  Barring bugs in its code or our library -- which have happened, but
-not very often -- a problem in rsasigkey is a problem in GMP.
-

See the next question for how to deal with GMP errors.

-

!Pluto failure!: ... exited with ... signal 4

-

Pluto has died. Signal 4 is SIGILL, illegal instruction.

-

The most likely cause is that your GMP - (GNU multi-precision) library is compiled for a different processor - than what you are running on. Pluto uses that library for its public - key calculations.

-

Try getting the GMP sources and recompile for your processor type. - Most Linux distributions will include this source, or you can download - it from the GMP home page.

-

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

The document she refers to has since been replaced by a - section of the troubleshooting document.

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

The documentation section she refers to is now - here.

-

... trouble writing to /dev/ipsec ... SA already in - use

-

This error message occurs when two manual connections are set up with - the same SPI value.

-

See the FAQ for 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:

- -

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 our discussion - of cleaning up dead tunnels.

-

unknown parameter name "rightcert"

-

This message can appear when you've upgraded an X.509-enabled Linux - FreeS/WAN with a vanilla Linux FreeS/WAN. To use your X.509 configs you - will need to overwrite the new install with - Super FreeS/WAN, or add the - X.509 patch by hand.

-

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.

- -

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:

- -

A number of tools are available to filter mail.

- -

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
-
-Contents -Previous -Next - - diff --git a/doc/firewall.html b/doc/firewall.html deleted file mode 100644 index 0747ab83d..000000000 --- a/doc/firewall.html +++ /dev/null @@ -1,767 +0,0 @@ - - - -Introduction to FreeS/WAN - - - - -Contents -Previous -Next -
-

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.

-

The firewall code in 2.4 and later kernels is called Netfilter. The - user-space utility to manage a firewall is iptables(8). See the - netfilter/iptables web site for details.

-

Filtering rules for IPsec packets

-

The basic constraint is that an IPsec gateway must have - packet filters that allow IPsec packets, at least when talking - to other IPsec gateways:

- -

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.

-

For nearly all FreeS/WAN applications, you must allow UDP port 500 - and the ESP protocol.

-

There are two ways to set this up:

-
-
easier but less flexible
-
Just set up your firewall scripts at boot time to allow IPsec - packets to and from your gateway. Let FreeS/WAN reject any bogus - packets.
-
more work, giving you more precise control
-
Have the ipsec_pluto(8) - daemon call scripts to adjust firewall rules dynamically as required. - This is done by naming the scripts in the - ipsec.conf(5) variables prepluto=, postpluto= -, leftupdown= and rightupdown=.
-
-

Both methods are described in more detail below.

-

Firewall configuration at boot

-

It is 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

- -

Since Pluto authenticates its partners during the negotiation, and - KLIPS drops packets for which no tunnel has been negotiated, this may - be all you need.

-

A simple set of rules

-

In simple cases, you need only a few rules, as in this example:

-
# allow IPsec
-#
-# IKE negotiations
-iptables -I INPUT  -p udp --sport 500 --dport 500 -j ACCEPT
-iptables -I OUTPUT -p udp --sport 500 --dport 500 -j ACCEPT
-# ESP encryption and authentication
-iptables -I INPUT  -p 50 -j ACCEPT
-iptables -I OUTPUT -p 50 -j ACCEPT
-
-

This should be all you need to allow IPsec through lokkit, - which ships with Red Hat 9, on its medium security setting. Once you've - tweaked to your satisfaction, save your active rule set with:

-
service iptables save
-

Other rules

- You can add additional rules, or modify existing ones, to work with - IPsec and with your network and policies. We give a some examples in - this section. -

However, while it is certainly possible to create an elaborate set of - 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.

-

The published rule sets we know of are described in the - next section.

-

Adding additional rules

- If necessary, you can add additional rules to: -
-
reject IPsec packets that are not to or from known gateways
-
This possibility is discussed in more detail - later
-
allow systems behind your gateway to build IPsec tunnels that pass - through the gateway
-
This possibility is discussed in more detail - later
-
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.
-
-

It is therefore reasonably straightforward to filter these packets in - whatever way suits your situation.

-

Modifying existing rules

-

In some cases rules that work fine before you add IPsec may require - modification to work with IPsec.

-

This is especially likely for rules that deal with interfaces on the - Internet side of your system. IPsec adds a new interface; often the - rules must change to take account of that.

-

For example, consider the rules given in - this section of the Netfilter documentation:

-
Most people just have a single PPP connection to the Internet, and don't
-want anyone coming back into their network, or the firewall:
-
-    ## Insert connection-tracking modules (not needed if built into kernel).
-    # insmod ip_conntrack
-    # insmod ip_conntrack_ftp
-
-    ## Create chain which blocks new connections, except if coming from inside.
-    # iptables -N block
-    # iptables -A block -m state --state ESTABLISHED,RELATED -j ACCEPT
-    # iptables -A block -m state --state NEW -i ! ppp0 -j ACCEPT
-    # iptables -A block -j DROP
-
-    ## Jump to that chain from INPUT and FORWARD chains.
-    # iptables -A INPUT -j block
-    # iptables -A FORWARD -j block
-

On an IPsec gateway, those rules may need to be modified. The above - allows new connections from anywhere except ppp0. That means - new connections from ipsec0 are allowed.

-

Do you want to allow anyone who can establish an IPsec connection to - your gateway to initiate TCP connections to any service on your - network? Almost certainly not if you are using opportunistic - encryption. Quite possibly not even if you have only explicitly - configured connections.

-

To disallow incoming connections from ipsec0, change the middle - section above to:

-
    ## Create chain which blocks new connections, except if coming from inside.
-    # iptables -N block
-    # iptables -A block -m state --state ESTABLISHED,RELATED -j ACCEPT
-    # iptables -A block -m state --state NEW -i ppp+ -j DROP
-    # iptables -A block -m state --state NEW -i ipsec+ -j DROP
-    # iptables -A block -m state --state NEW -i -j ACCEPT
-    # iptables -A block -j DROP
-

The original rules accepted NEW connections from anywhere except - ppp0. This version drops NEW connections from any PPP interface (ppp+) - and from any ipsec interface (ipsec+), then accepts the survivors.

-

Of course, these are only examples. You will need to adapt them to - your own situation.

-

Published rule sets

-

Several sets of firewall rules that work with FreeS/WAN are - available.

-

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.

-

Asgard scripts

-

Asgard's - Realm has set of firewall scripts with FreeS/WAN support, for 2.4 - kernels and iptables.

-

User scripts from the mailing list

-

One user gave considerable detail on his scripts, including - supporting IPX through the tunnel. His - message was too long to conveniently be quoted here, so I've put it in - a separate file.

-

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

-

The ipsec.conf(5) - 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 - above 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=
-
script to be called before - pluto(8) IKE daemon is started.
-
postpluto=
-
script to be called after - pluto(8) IKE daemon 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 leftfirewall=yes or rightfirewall=yes to - use our supplied default script
-
or
-
assign a name in a leftupdown= or rightupdown= - line to use your own script
-
-

Note that only one of these should be used. You - cannot sensibly use both. Since our default script is obsolete - (designed for firewalls using ipfwadm(8) on 2.0 kernels), - most users who need this service will need to write a custom - script.

-

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:

- -

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. See the "updown command" - section of the ipsec_pluto(8) - man page for details.

-

Note 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 or iptables

-

Our _updown is for firewalls using ipfwadm(8), - the firewall code for the 2.0 series of Linux kernels. If you are using - the more recent packages ipchains(8) (for 2.2 kernels) or - iptables(8) (2.4 kernels), then you must do one of:

- -

You can write a script to do whatever you need with firewalling. - Specify its name in a [left|right]updown= parameter in - ipsec.conf(5) and Pluto will automatically call it for you.

-

The arguments Pluto passes such a script are the same ones it passes - to our default _updown script, so the best way to build yours is to - copy ours and modify the copy.

-

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.

-

A complication: IPsec vs. 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:

- -

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:

- -

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:

- -

Other references on NAT and IPsec

-

Other documents which may be relevant include:

- -

Other complications

-

Of course simply allowing UDP 500 and ESP packets is not the whole - story. Various other issues arise in making IPsec and packet filters - co-exist and even co-operate. Some of them are summarised below.

-

IPsec through the gateway

-

Basic IPsec packet filtering rules deal only with packets addressed - to or sent from your IPsec 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.

-

Where possible, allowing this is almost certainly a good idea. Using - IPsec on an end-to-end basis is more secure than gateway-to-gateway.

-

Doing it is quite simple. You just need firewall rules that allow UDP - port 500 and protocols 50 and 51 to pass through your gateway. If you - wish, you can of course restrict this to certain hosts.

-

Preventing non-IPsec traffic

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

One application of this is for the telecommuter who might have:

-
     Sunset==========West------------------East ================= firewall --- the Internet
-         home network      untrusted net        corporate network
-

The subnet on the right is 0.0.0.0/0, the whole Internet. The West - gateway is set up so that it allows only IPsec packets to East in or - out.

-

This configuration is used in AT&T Research's network. For details, - see the papers links in our - introduction.

-

Another application would be to set up firewall rules so that an - internal machine, such as an employees-only web server, could not talk - to the outside world except via specific IPsec tunnels.

-

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:

- -

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 I -nternet Control Message P -rotocol. 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.

- -

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.

-

How it all works: IPsec packet details

-

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

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:

- -

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:

- -

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:

- -

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

-

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.
-
-Contents -Previous -Next - - diff --git a/doc/glossary.html b/doc/glossary.html deleted file mode 100644 index 3ca33810f..000000000 --- a/doc/glossary.html +++ /dev/null @@ -1,2132 +0,0 @@ - - - -Introduction to FreeS/WAN - - - - -Contents -Previous -Next -
-

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:

- -

Several Internet glossaries are available as RFCs:

- -

More general glossary or dictionary information:

- -
-

Definitions

-
-
0
-
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 our performance document 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 -- 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 128, 192 or 256-bit - keys. 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:

- -

Three of the five finalists -- Rijndael, Serpent and Twofish -- have - completely open licenses.

-

In October 2000, NIST announced the winner -- Rijndael.

-

For more information, see:

- -

AES will be added to a future release of - Linux FreeS/WAN. Likely we will add all three of the finalists with - good licenses. User-written AES patches - are already available.

-

Adding AES may also require adding stronger hashes, - SHA-256, SHA-384 and SHA-512.

-
-
AH
-
The IPsec Authentication Header, - added after the IP header. For details, see our - IPsec 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: - -

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. FreeS/WAN normally uses - RSA for this. Other methods supported are discussed in our - advanced 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: - -

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 block cipher for Linux FreeS/WAN -.

-

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, about 135 years. Against a - 128-bit key, he needs 232 times that, over 500,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 over 500,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 500,000,000,000 years to break by brute force. We really don't - care how many zeroes there are on the end of that, as long as the - number remains ridiculously large. That is, we don't care exactly how - large the key is as long as it is large enough.

-

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.

-
-
CIDR
-
Classless Inter-Domain Routing, an - addressing scheme used to describe networks not restricted to the old - Class A, B, and C sizes. A CIDR block is written address/ -mask, where address is a 32-bit Internet address. The - first mask bits of address are part of the - gateway address, while the remaining bits designate other host - addresses. For example, the CIDR block 192.0.2.96/27 describes a - network with gateway 192.0.2.96, hosts 192.0.2.96 through 192.0.2.126 - and broadcast 192.0.2.127. -

FreeS/WAN policy group files accept CIDR blocks of the format - address/[mask], where address may take the - form name.domain.tld. An absent mask is assumed - to be /32.

-
-
Certification Authority
-
see CA
-
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.

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

- - - - - -
ECBElectronic CodeBook -encrypt each block independently
CBCCipher Block Chaining -
XOR previous block ciphertext into new block plaintext - before encrypting new block
CFBCipher FeedBack
OFBOutput 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.

-
-
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, and the office gateway is the server.
    • -
-

We generally use the term in the first sense. Vendors of Windows - IPsec solutions often use it in the second. See this - discussion.

-
-
Common Criteria
-
A set of international security classifications which are replacing - the old US Rainbow Book standards and similar - standards in other countries. -

Web references include this US - government site and this - global home page.

-
-
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. It is now being replaced by AES -. -

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
-
DHCP
-
Dynamic Host C -onfiguration Protocol, a method of assigning - dynamic IP addresses, and providing additional information such as - addresses of DNS servers and of gateways. See this - DHCP resource page.
-
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: - -

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

-
-
discretionary access control
-
access control mechanisms controlled by the user, for example Unix - rwx file permissions. These contrast with - mandatory access controls.
-
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 the - DNS background section of our documentation.
-
DOS attack
-
see Denial Of Service attack
-
dynamic IP address
-
an IP address which is automatically assigned, either by - DHCP or by some protocol such as PPP or - PPPoE which the machine uses to connect to the Internet. This is - the opposite of a static IP address, pre-set on - the machine itself.
-
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 both the - security of single DES and the overheads of triple DES are - seriously inferior to many other ciphers, this is a spectacularly - dubious "advantage".

-
-
Entrust
-
A Canadian company offerring enterprise PKI - products using CAST-128 symmetric crypto, - RSA public key and X.509 directories. - Web site
-
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 - 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 - advanced configuration section.

-
-
Exhaustive search
-
See brute force attack.
-
F
-
FIPS
-
Federal Information Processing Standard, - 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.

-
-
FreeS/WAN
-
see Linux FreeS/WAN
-
Fullnet
-
The CIDR block containing all IPs of its IP version. The - IPv4 fullnet is written 0.0.0.0/0. Also known as "all" and - "default", fullnet may be used in a routing table to specify a default - route, and in a FreeS/WAN - policy group file to specify a default IPsec policy.
-
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. See the - GMP home page.
-
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.
-
GOST
-
a Soviet government standard block cipher. - Applied Cryptography has details.
-
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. See their web site -
-
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.

-
-
IEEE
-
Institute of Electrical and Electronic - Engineers, a professional association which, among other things, - sets some technical standards
-
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. For details, see RFC 2409 and - our IPsec document. IKE is implemented in - Linux FreeS/WAN by the Pluto daemon.
-
IKE v2
-
A proposed replacement for IKE. There are other - candidates, such as JFK, and at time of writing - (March 2002) the choice between them has not yet been made and does not - appear imminent.
-
iOE
-
See Initiate-only opportunistic encryption -.
-
IP
-
Internet Protocol.
-
IP masquerade
-
A mostly obsolete term for a method of allowing multiple machines to - communicate over the Internet when only one IP address is available for - their use. The more current term is Network Address Translation or - NAT.
-
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 or 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.

-
-
IPX
-
Novell's Netware protocol tunnelled over an IP link. Our - firewalls document includes an example of using this through an - IPsec tunnel.
-
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
-
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.
-
Initiate-only opportunistic encryption (iOE) -
-
A form of opportunistic encryption (OE) in - which a host proposes opportunistic connections, but lacks the reverse - DNS records necessary to support incoming opportunistic connection - requests. Common among hosts on cable or pppoe connections where the - system administrator does not have write access to the DNS reverse map - for the host's external IP. -

Configuring for initiate-only opportunistic encryption is described - in our quickstart document.

-
-
J
-
JFK
-
Just Fast Keying, - a proposed simpler replacement for IKE.
-
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 section for more detail. For - the code see our primary site or one - of the mirror sites on this list.

-
-
Linux Security Modules (LSM)
-
a project to create an interface in the Linux kernel that supports - plug-in modules for various security policies. -

This allows multiple security projects to take different approaches - to security enhancement without tying the kernel down to one particular - approach. As I understand the history, several projects were pressing - Linus to incorporate their changes, the various sets of changes were - incompatible, and his answer was more-or-less "a plague on all your - houses; I'll give you an interface, but I won't incorporate anything".

-

It seems to be working. There is a fairly active - LSM mailing list, and several projects are already using the - interface.

-
-
LSM
-
see Linux Security Modules
-
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.

-
-
mandatory access control
-
access control mechanisims which are not settable by the user (see - discretionary access control), but are enforced by the system. -

For example, a document labelled "secret, zebra" might be readable - only by someone with secret clearance working on Project Zebra. - Ideally, the system will prevent any transfer outside those boundaries. - For example, even if you can read it, you should not be able to e-mail - it (unless the recipient is appropriately cleared) or print it (unless - certain printers are authorised for that classification).

-

Mandatory access control is a required feature for some levels of - Rainbow Book or Common Criteria classification, - but has not been widely used outside the military and government. There - is a good discussion of the issues in Anderson's - Security Engineering.

-

The Security Enhanced Linux project is adding - mandatory access control to Linux.

-
-
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. See this - discussion.
-
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.

-

Hans Dobbertin found a weakness in MD5, and people often ask whether - this means MD5 is unsafe for IPsec. It doesn't. The IPsec RFCs discuss - Dobbertin's attack and conclude that it does not affect MD5 as used for - HMAC in IPsec.

-
-
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 256 - + 256 = 257work. Against triple DES, you need - 256 + 2112 ~= 2112.

-

The memory requirements for 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 (Trusted Information - Systems, a firewall vendor) and McAfee anti-virus products. Among other - things, they offer an IPsec-based VPN product.
-
NAT
-
Network Address Translation, a process by which - firewall machines may change the addresses on packets as they go - through. For discussion, see our - background section.
-
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 not intercepted 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.

-

First, it is wildly impractical for most - applications. Key management is at best difficult, often completely - impossible.

-

Second, it is extremely fragile. Small changes which - violate the conditions listed above do not just weaken the cipher - liitle. Quite often they destroy its security completely.

-
    -
  • Re-using the pad weakens the cipher to the point where it can be - broken with pencil and paper. With a computer, the attack is trivially - easy.
    • -
  • Using anything less than truly random - numbers completely invalidates the security proof.
    • -
  • In particular, using computer-generated pseudo-random numbers may - give an extremely weak cipher. It might also produce a good stream - cipher, if the pseudo-random generator is both well-designed and - properely seeded.
    • -
-

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; - most systems marketed with such claims are worthless.

-

Finally, even if the system is implemented and used correctly, it is - highly vulnerable to a substitution attack. If an attacker - knows some 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 will never re-use.
    • -
  • However, an active attacker who knows the - plaintext can recover the pad, then use it to encode with whatever he - chooses. If he can get his version delivered instead of yours, this may - be a disaster. If you send "attack at dawn", the delivered message can - be anything the same length -- perhaps "retreat to east" or "shoot - generals".
    • -
  • An active attacker with only a reasonable guess at the plaintext can - try the same attack. If the guess is correct, this works and the - attacker's bogus message is delivered. If the guess is wrong, a garbled - message is delivered.
    • -
-

In general then, despite its theoretical perfection, the one-time-pad - has very limited practical application.

-

See also the one - time pad FAQ.

-
-
Opportunistic encryption (OE)
-
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 - quickstart document.

-
-
Opportunistic responder
-
A host which accepts, but does not initiate, requests for - opportunistic encryption (OE). An opportunistic responder has - enabled OE in its passive form (pOE) only. A - web server or file server may be usefully set up as an opportunistic - responder. -

Configuring passive OE is described in our - policy groups document.

-
-
Orange book
-
the most basic and best known of the US government's - Rainbow Book series of computer security standards.
-
P
-
P1363 standard
-
An IEEE standard for public key cryptography. - Web page.
-
pOE
-
See Passive opportunistic encryption.
-
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.
-
Passive opportunistic encryption (pOE)
-
A form of opportunistic encryption (OE) in - which the host will accept opportunistic connection requests, but will - not initiate such requests. A host which runs OE in its passive form - only is known as an opportunistic responder. -

Configuring passive OE is described in our - policy groups document.

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

-

See also - Phil Karn's definition.

-
-
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. Zimmerman left in 2001, and early in 2002 NAI - announced that they would no longer sell PGP.. -

Versions 6.5 and later of the PGP product include PGPnet, an IPsec - client for Macintosh or for Windows 95/98/NT. See our - interoperation document.

-
-
Photuris
-
Another key negotiation protocol, an alternative to - IKE, described in RFCs 2522 and 2523.
-
PPP
-
Point-to-Point Protocol, originally a method of - connecting over modems or serial lines, but see also PPPoE.
-
PPPoE
-
PPP over Ethernet, a somewhat odd protocol that - makes Ethernet look like a point-to-point serial link. It is widely - used for cable or ADSL Internet services, apparently mainly because it - lets the providers use access control and address assignmment - mechanisms developed for dialup networks. - Roaring Penguin provide a widely used Linux implementation.
-
PPTP
-
Point-to-Point Tunneling Protocol, used - in some Microsoft VPN implementations. Papers discussing weaknesses in - it are on - counterpane.com. It is now largely obsolete, replaced by L2TP.
-
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 that 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
-
Rainbow books
-
A set of US government standards for evaluation of "trusted computer - systems", of which the best known was the Orange Book -. One fairly often hears references to "C2 security" or a product - "evaluated at B1". The Rainbow books define the standards referred to - in those comments. -

See this reference - page.

-

The Rainbow books are now mainly obsolete, replaced by the - international Common Criteria standards.

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

-

See the manual pages for - ipsec_ranbits(8) and ipsec_prng(3) for more on FreeS/WAN's use of - randomness. Both depend on the random(4) device driver..

-

A couple of years ago, there was extensive mailing list discussion - (archived here -)of Linux /dev/random and FreeS/WAN. Since then, the design of the - random(4) driver has changed considerably. Linux 2.4 kernels have the - new driver..

-
-
Raptor
-
A firewall product for Windows NT offerring IPsec-based VPN - services. Linux FreeS/WAN interoperates with Raptor; see our - interop 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.
-
Reverse map
-
In DNS, a table where IP addresses can - be used as the key for lookups which return a system name and/or other - information.
-
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.

-
-
Rijndael
-
a block cipher designed by two Belgian - cryptographers, winner of the US government's AES - contest to pick a replacement for DES. See the - Rijndael home page.
-
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 algorithm, named for its three inventors. It is widely used and - likely to become moreso since it became free of patent encumbrances in - September 2000. -

RSA can be used to provide either encryption - or digital signatures. In IPsec, it is used - only for signatures. These provide gateway-to-gateway - authentication for IKE negotiations.

-

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^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 < pq: -
      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. Using c for - ciphertext and i for the input plaintext, - encryption is then:

-
        c = i^e           modulo N
-
-

An attacker cannot deduce i 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 recover - the plaintext p since:

-
        c^d == (i^e)^d    modulo N
-            == i^ed       modulo N
-            == i          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. Quite a few good mathematicians have tried both - problems, and no-one has announced success, but there is no proof they - are insoluble.

-
-
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 ( -IKE) and used by the lower (ESP and - AH). 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 as an index to look up other things such - as session keys and intialisation vectors.

-

For more detail, see our section on IPsec - and/or RFC 2401.

-
-
SE Linux
-
Security Enhanced Linux, an - NSA-funded project to add mandatory access - control to Linux. See the - project home page. -

According to their web pages, this work will include extending - mandatory access controls to IPsec tunnels.

-

Recent versions of SE Linux code use the Linux - Security Module interface.

-
-
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 allows - opportunistic encryption. Any pair of machines which can - authenticate each other via DNS can communicate securely, without - either a pre-existing shared secret or a shared PKI.

-
-
Secret key cryptography
-
See symmetric cryptography
-
Security Association
-
see SA
-
Security Enhanced Linux
-
see SE Linux
-
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
-
SHA-1
-
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.

-

The NSA made one small change after the release of the original SHA. - They did not give reasons. Iit may be a defense against some attack - they found and do not wish to disclose. Technically the modified - algorithm should be called SHA-1, but since it has replaced the - original algorithm in nearly all applications, it is generally just - referred to as SHA..

-
-
SHA-256
-
SHA-384
-
SHA-512
-
Newer variants of SHA designed to match the strength of the 128, 192 - and 256-bit keys of AES. The work to break an - encryption algorithm's strength by brute force is - 2 - - - - - - keylength operations but a - birthday attack on a hash needs only 2 - - - - - - - - hashlength - - / - - - 2 , so as a general rule you need a - hash twice the size of the key to get similar strength. SHA-256, - SHA-384 and SHA-512 are designed to match the 128, 192 and 256-bit key - sizes of AES, respectively.
-
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 section - 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.
-
static IP address
-
an IP adddress which is pre-set on the machine itself, as opposed to - a dynamic address which is assigned by a - DHCP server or obtained as part of the process of establishing a - PPP or PPPoE connection
-
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.
-
TOS field
-
The Type Of S -ervice field in an IP header, used to control qualkity of service - routing.
-
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 guessed 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.

-

In general, traffic analysis by itself is not very useful. However, - in the context of a larger intelligence effort where quite a bit is - already known, it can be very useful. When you are solving a complex - puzzle, every little bit helps.

-

IPsec itself does not defend against traffic - analysis, 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. We discuss this - here.

-
-
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
-
TTL
-
Time To Live, - used to control DNS caching. Servers - discard cached records whose TTL expires
-
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.

-
-
WEP (Wired Equivalent Privacy)
-
The cryptographic part of the IEEE standard for - wireless LANs. As the name suggests, this is designed to be only as - secure as a normal wired ethernet. Anyone with a network conection can - tap it. Its advocates would claim this is good design, refusing to - build in complex features beyond the actual requirements. -

Critics refer to WEP as "Wiretap Equivalent Privacy", and - consider it a horribly flawed design based on bogus "requirements". You - do not control radio waves as you might control your wires, so the - metaphor in the rationale is utterly inapplicable. A security policy - that chooses not to invest resources in protecting against certain - attacks which can only be conducted by people physically plugged into - your LAN may or may not be reasonable. The same policy is completely - unreasonable when someone can "plug in" from a laptop half a block - away..

-

There has been considerable analysis indicating that WEP is seriously - flawed. A FAQ on attacks against WEP is available. Part of it reads:

-
... attacks are practical to mount using only inexpensive - off-the-shelf equipment. We recommend that anyone using an 802.11 - wireless network not rely on WEP for security, and employ other - security measures to protect their wireless network. Note that our - attacks apply to both 40-bit and the so-called 128-bit versions of WEP - equally well.
-

WEP appears to be yet another instance of governments, and - unfortunately some vendors and standards bodies, deliberately promoting - hopelessly flawed "security" products, apparently mainly for the - benefit of eavesdropping agencies. See this - discussion.

-
-
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, now part of Lucent. - Their QVPN products interoperate with Linux FreeS/WAN; see our - interop document.
-
Y
-
Z
-
-
-Contents -Previous -Next - - diff --git a/doc/index.html b/doc/index.html deleted file mode 100644 index 427ed7ea7..000000000 --- a/doc/index.html +++ /dev/null @@ -1,55 +0,0 @@ - - - - FreeS/WAN index - - - - - -

FreeS/WAN documentation

- - - - - - - -

For technical support and other questions, use our mailing lists.

- -
        This index last changed:    $Date: 2004/03/15 20:35:21 $
- - - diff --git a/doc/install.html b/doc/install.html deleted file mode 100644 index 6cd55535e..000000000 --- a/doc/install.html +++ /dev/null @@ -1,286 +0,0 @@ - - - -Introduction to FreeS/WAN - - - - -Contents -Previous -Next -
-

Installing FreeS/WAN

-

This document will teach you how to install Linux FreeS/WAN. If your - distribution comes with Linux FreeS/WAN, we offer tips to get you - started.

-

Requirements

-

To install FreeS/WAN you must:

- -

Choose your install method

-

There are three basic ways to get FreeS/WAN onto your system:

- - -

FreeS/WAN ships with some Linuxes

-

FreeS/WAN comes with these - distributions.

-

If you're running one of these, include FreeS/WAN in the choices you - make during installation, or add it later using the distribution's - tools.

-

FreeS/WAN may be altered...

-

Your distribution may have integrated extra features, such as Andreas - Steffen's X.509 patch, into FreeS/WAN. It may also use custom startup - script locations or directory names.

-

You might need to create an authentication keypair -

-

If your FreeS/WAN came with your distribution, you may wish to - generate a fresh RSA key pair. FreeS/WAN will use these keys for - authentication.

-

To do this, become root, and type:

-
    ipsec newhostkey --output /etc/ipsec.secrets --hostname xy.example.com
-    chmod 600 /etc/ipsec.secrets
-

where you replace xy.example.com with your machine's fully-qualified - domain name. Generate some randomness, for example by wiggling your - mouse, to speed the process.

-

The resulting ipsec.secrets looks like:

-
: RSA   {
-        # RSA 2192 bits   xy.example.com   Sun Jun 8 13:42:19 2003
-        # for signatures only, UNSAFE FOR ENCRYPTION
-        #pubkey=0sAQOFppfeE3cC7wqJi...
-        Modulus: 0x85a697de137702ef0...
-        # everything after this point is secret
-        PrivateExponent: 0x16466ea5033e807...
-        Prime1: 0xdfb5003c8947b7cc88759065...
-        Prime2: 0x98f199b9149fde11ec956c814...
-        Exponent1: 0x9523557db0da7a885af90aee...
-        Exponent2: 0x65f6667b63153eb69db8f300dbb...
-        Coefficient: 0x90ad00415d3ca17bebff123413fc518...
-        }
-# do not change the indenting of that "}"
-

In the actual file, the strings are much longer.

-

Start and test FreeS/WAN

-

You can now start FreeS/WAN and test - whether it's been successfully installed..

- -

RPM install

-

These instructions are for a recent Red Hat with a stock Red Hat - kernel. We know that Mandrake and SUSE also produce FreeS/WAN RPMs. If - you're running either, install using your distribution's tools.

-

Download RPMs

-

Decide which functionality you need:

- - -

For 2.6 kernels, get the latest FreeS/WAN userland RPM, for example:

-
    freeswan-userland-2.04.9-0.i386.rpm
-

Note: FreeS/WAN's support for 2.6 kernel IPsec is preliminary. Please - see 2.6.known-issues, and the latest - mailing list reports.

-

Change to your new FreeS/WAN directory, and make and install the

-

For 2.4 kernels, get both kernel and userland RPMs. Check your kernel - version with

-
    uname -r
-

Get a kernel module which matches that version. For example:

-
    freeswan-module-2.04_2.4.20_20.9-0.i386.rpm
-

Note: These modules will only work on the Red Hat kernel they were - built for, since they are very sensitive to small changes in the - kernel.

-

Get FreeS/WAN utilities to match. For example:

-
    freeswan-userland-2.04_2.4.20_20.9-0.i386.rpm
-

For freeswan.org RPMs: check signatures

-

While you're at our ftp site, grab the RPM signing key

-
    freeswan-rpmsign.asc
-

If you're running RedHat 8.x or later, import this key into the RPM - database:

-
    rpm --import freeswan-rpmsign.asc
-

For RedHat 7.x systems, you'll need to add it to your - PGP keyring:

-
    pgp -ka freeswan-rpmsign.asc
-

Check the digital signatures on both RPMs using:

-
    rpm --checksig freeswan*.rpm
-

You should see that these signatures are good:

-
    freeswan-module-2.04_2.4.20_20.9-0.i386.rpm: pgp md5 OK
-    freeswan-userland-2.04_2.4.20_20.9-0.i386.rpm: pgp md5 OK
-

Install the RPMs

-

Become root:

-
    su
-

For a first time install, use:

-
    rpm -ivh freeswan*.rpm
-

To upgrade existing RPMs (and keep all .conf files in place), use:

-
    rpm -Uvh freeswan*.rpm
-

If you're upgrading from FreeS/WAN 1.x to 2.x RPMs, and encounter - problems, see this note.

-

Start and Test FreeS/WAN

-

Now, start FreeS/WAN and test your - install.

- -

Install from Source

- - -

Decide what functionality you need

-

Your choices are:

- -

Download FreeS/WAN

-

Download the source tarball you've chosen, along with any patches.

-

For freeswan.org source: check its signature

-

While you're at our ftp site, get our source signing key

-
    freeswan-sigkey.asc
-

Add it to your PGP keyring:

-
    pgp -ka freeswan-sigkey.asc
-

Check the signature using:

-
    pgp freeswan-2.04.tar.gz.sig freeswan-2.04.tar.gz
-

You should see something like:

-
    Good signature from user "Linux FreeS/WAN Software Team (build@freeswan.org)".
-    Signature made 2002/06/26 21:04 GMT using 2047-bit key, key ID 46EAFCE1
- - -

Untar, unzip

-

As root, unpack your FreeS/WAN source into /usr/src.

-
    su
-    mv freeswan-2.04.tar.gz /usr/src
-    cd /usr/src
-    tar -xzf freeswan-2.04.tar.gz
-
-

Patch if desired

-

Now's the time to add any patches. The contributor may have special - instructions, or you may simply use the patch command.

-

... and Make

-

Choose one of the methods below.

-

Userland-only Install for 2.6 kernels

- -

Note: FreeS/WAN's support for 2.6 kernel IPsec is preliminary. Please - see 2.6.known-issues, and the latest - mailing list reports.

-

Change to your new FreeS/WAN directory, and make and install the - FreeS/WAN userland tools.

-
    cd /usr/src/freeswan-2.04
-    make programs
-    make install
-

Now, start FreeS/WAN and test your - install.

-

KLIPS install for 2.2, 2.4, or 2.6 kernels

- -

To make a modular version of KLIPS, along with other FreeS/WAN - programs you'll need, use the command sequence below. This will change - to your new FreeS/WAN directory, make the FreeS/WAN module (and other - stuff), and install it all.

-
    cd /usr/src/freeswan-2.04
-    make oldmod
-    make minstall
-

Start FreeS/WAN and test your - install.

-

To link KLIPS statically into your kernel (using your old kernel - settings), and install other FreeS/WAN components, do:

-
    cd /usr/src/freeswan-2.04
-    make oldmod
-    make minstall
-

Reboot your system and test your - install.

-

For other ways to compile KLIPS, see our Makefile.

- -

Start FreeS/WAN and test your install

-

Bring FreeS/WAN up with:

-
    service ipsec start
-

This is not necessary if you've rebooted.

- -

Test your install

-

To check that you have a successful install, run:

-
    ipsec verify
-

You should see at least:

-
-    Checking your system to see if IPsec got installed and started correctly
-    Version check and ipsec on-path                             [OK]
-    Checking for KLIPS support in kernel                        [OK]
-    Checking for RSA private key (/etc/ipsec.secrets)           [OK]
-    Checking that pluto is running                              [OK]
-
-

If any of these first four checks fails, see our - troubleshooting guide.

-

Making FreeS/WAN play well with others

-

There are at least a couple of things on your system that might - interfere with FreeS/WAN, and now's a good time to check these:

- -

Configure for your needs

-

You'll need to configure FreeS/WAN for your local site. Have a look - at our opportunism quickstart guide to - see if that easy method is right for your needs. Or, see how to - configure a network-to-network or Road Warrior style VPN.

-
-Contents -Previous -Next - - diff --git a/doc/interop.html b/doc/interop.html deleted file mode 100644 index 1cd7b9e78..000000000 --- a/doc/interop.html +++ /dev/null @@ -1,983 +0,0 @@ - - - -Introduction to FreeS/WAN - - - - -Contents -Previous -Next -
- -

Interoperating with FreeS/WAN

-

The FreeS/WAN project needs you! We rely on the user community to - keep up to date. Mail users@lists.freeswan.org with your interop - success stories.

-

Please note: Most of our interop examples feature - Linux FreeS/WAN 1.x config files. You can convert them to 2.x files - fairly easily with the patch in our - Upgrading Guide.

-

Interop at a Glance

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
 FreeS/WAN VPNRoad Warrior -OE
 PSKRSA SecretX.509 -
(requires patch)		 -NAT-Traversal -
(requires patch)		 -Manual -
Keying		  
More Compatible
FreeS/WAN -  Yes -YesYes -YesYes -YesYes
isakmpd (OpenBSD)   -Yes  -Yes Yes  -No    
Kame (FreeBSD, -
NetBSD, MacOSX) -
aka racoon  		YesYes -Yes  -Yes No
McAfee VPN -
was PGPNet  		YesYes -Yes   -YesNo
Microsoft -
Windows 2000/XP  		 -Yes Yes  - Yes -No
SSH Sentinel   -Yes  -YesMaybe YesNo
Safenet SoftPK -
/SoftRemote  		 -Yes Yes  - Yes -No
Other
6Wind    - Yes    -No
Alcatel Timestep   -Yes    -  No
Apple Macintosh -
System 10+  		 -MaybeYes -Maybe Maybe - No
AshleyLaurent -
VPCom  		 -Yes     No
Borderware   -Yes    - No -No
Check Point FW-1/VPN-1 -  Yes  -Yes  Yes -No
Cisco with 3DES   -YesMaybe - Maybe  - No
Equinux VPN Tracker -
(for Mac OS X)  		 -YesYes -Yes Maybe - No
F-Secure   -Yes   -MaybeYes -YesNo
Gauntlet GVPN   -Yes  -Yes    -No
IBM AIX   -Yes Maybe -   No
IBM AS/400  Yes     - No
Intel Shiva -
LANRover/Net Structure  		 -Yes     No
LanCom (formerly ELSA) -  Yes   -   No
Linksys   -Maybe  -No  Yes -No
Lucent  Partial     - No
Netasq   -  Yes   - No
netcelo   -  Yes   - No
Netgear fvs318   -Yes    -  No
Netscreen 100 -
or 5xp  		 -Yes     -MaybeNo
Nortel Contivity   -Partial  -YesMaybe  - No
RadGuard   -Yes     - No
Raptor  Yes    -Yes No
Redcreek Ravlin   -Yes/Partial -      -No
SonicWall   -Yes   MaybeNo -No
Sun Solaris  Yes Yes - Yes No
Symantec   -Yes     - No
Watchguard -
Firebox  		 -Yes    -Yes No
Xedia Access Point -
/QVPN  		 -Yes     No
Zyxel Zywall -
/Prestige  		 -Yes     No
 PSKRSA SecretX.509 -
(requires patch)		 -NAT-Traversal -
(requires patch)		 -Manual -
Keying		  
 FreeS/WAN VPNRoad Warrior -OE
-

Key

- - - - - - - -
YesPeople report that this - works for them.
[Blank]We don't know.
NoWe have reason to - believe it was, at some point, not possible to get this to work.
PartialPartial success. - For example, a connection can be created from one end only.
Yes/Partial -Mixed reports.
MaybeWe think the answer - is "yes", but need confirmation.
- -

Basic Interop Rules

-

Vanilla FreeS/WAN implements these parts - of the IPSec specifications. You can add more with - Super FreeS/WAN, but what we offer may be enough for many users.

- -

We offer a set of proposals which is not user-adjustable, but covers - all combinations that we can offer. FreeS/WAN always proposes triple - DES encryption and Perfect Forward Secrecy (PFS). In addition, we - propose Diffie Hellman groups 5 and 2 (in that order), and MD5 and - SHA-1 hashes. We accept the same proposals, in the same order of - preference.

-

Other interop notes:

- -

Longer Stories

-

For More Compatible Implementations

-

FreeS/WAN

-

See our documentation at - freeswan.org and the Super FreeS/WAN docs at - freeswan.ca. Some user-written HOWTOs for FreeS/WAN-FreeS/WAN - connections are listed in our Introduction -.

-

See also:

- -

Back to chart

-

isakmpd (OpenBSD)

-

OpenBSD FAQ: Using - IPsec -
- Hans-Joerg Hoexer's interop Linux-OpenBSD (PSK) -
Skyper's configuration - (PSK) -
- French page with configs (X.509)

-

Back to chart

-

Kame

- -

Kame homepage, with FAQ -
- NetBSD's IPSec FAQ -
- Ghislaine's post explaining some interop peculiarities

-

- Itojun's Kame-FreeS/WAN interop tips (PSK) -
Ghislaine - Labouret's French page with links to matching FreeS/WAN and Kame - configs (RSA) -
Markus - Wernig's HOWTO (X.509, BSD gateway) -
- Frodo's Kame-FreeS/WAN interop (X.509) -
Kame as a WAVEsec - client.

-

Back to chart

-

PGPNet/McAfee

-

- -

Tim Carr's - Windows Interop Guide (X.509) -
- Hans-Joerg Hoexer's Guide for Linux-PGPNet (PSK) -
- Kai Martius' instructions using RSA Key-Extractor Tool (RSA) -
    Christian - Zeng's page (RSA) based on Kai's work. English or German. -
- Oscar Delgado's PDF (X.509, no configs) -
Ryan's HOWTO - for FreeS/WAN-PGPNet (X.509). Through a Linksys Router with IPsec - Passthru enabled. -
Jean-Francois - Nadeau's Practical Configuration (Road Warrior with PSK) -
Wouter - Prins' HOWTO (Road Warrior with X.509) -

-

- Rekeying problem with FreeS/WAN and older PGPNets -

-

DHCP - over IPSEC HOWTO for FreeS/WAN (requires X.509 and dhcprelay patches) -

-

Back to chart

-

Microsoft Windows 2000/XP

- -

Tim Carr's - Windows Interop Guide (X.509) -
James - Carter's instructions (X.509, NAT-T) -
Jean-Francois - Nadeau's Net-net Configuration (PSK) -
Telenor's - Node-node Config (Transport-mode PSK) -
Marcus Mueller's HOWTO using his - VPN config tool (X.509). Tool also works with PSK. -
- Nate Carlson's HOWTO using same tool (Road Warrior with X.509). - Unusually, FreeS/WAN is the Road Warrior here. -
- Oscar Delgado's PDF (X.509, no configs) -
- Tim Scannell's Windows XP Additional Checklist (X.509) -

- - -

- Microsoft's page on Win2k TCP/IP security features -
- Microsoft's Win2k IPsec debugging tips -
- - - MS VPN may fall back to 1DES

-

Back to chart

-

SSH Sentinel

- -

SSH's - Sentinel-FreeSWAN interop PDF (X.509) -
- Nadeem Hassan's SUSE-to-Sentinel article (Road warrior with X.509) -
- O-Zone's Italian HOWTO (Road Warrior, X.509, DHCP) -

-

Back to chart

-

Safenet SoftPK/SoftRemote

- -

- Whit Blauvelt's SoftRemote tips -
- Tim Wilson's tips (X.509) - Workaround for a "gotcha"

-

Jean-Francois - Nadeau's Practical Configuration (Road Warrior with PSK) -
- Terradon Communications' PDF (Road Warrior with PSK) -
- Seaan.net's PDF (Road Warrior to Subnet, with PSK) -
- Red Baron Consulting's PDF (Road Warrior with X.509)

-

Back to chart

-

For Other Implementations

-

6Wind

-

- French page with configs (X.509)

-

Back to chart

-

Alcatel Timestep

-

- Alain Sabban's settings (PSK or PSK road warrior; through static NAT) -
- Derick Cassidy's configs (PSK) -
- David Kerry's Timestep settings (PSK) -
- Kevin Gerbracht's ipsec.conf (X.509)

-

Back to chart

-

Apple Macintosh System 10+

- -

James - Carter's instructions (X.509, NAT-T)

-

Back to chart

-

AshleyLaurent VPCom

-

- Successful interop report, no details

-

Back to chart

-

Borderware

- -

- Philip Reetz' configs (PSK) -
- Borderware server does not support FreeS/WAN road warriors -
- Older Borderware may not support Diffie Hellman groups 2, 5 -

-

Back to chart

-

Check Point VPN-1 or FW-1

- -

- AERAsec's Firewall-1 NG site (PSK, X.509, Road Warrior with X.509, - other algorithms) -
     - AERAsec's detailed Check Point-FreeS/WAN support matrix -
- Checkpoint.com PDF: Linux as a VPN Client to FW-1 (PSK) -
PhoneBoy's Check Point FAQ (on - Check Point only, not FreeS/WAN) -

-

- Chris Harwell's tips FreeS/WAN configs (PSK) -
- Daniel Tombeil's configs (PSK)

-

Back to chart

-

Cisco

- -

SANS - Institute HOWTO (PSK). Detailed, with extensive references. -
Short HOWTO - (PSK) -
- French page with configs for Cisco IOS, PIX and VPN 3000 (X.509) -
- Dave McFerren's sample configs (PSK) -
- Wolfgang Tremmel's sample configs (PSK road warrior) -
- Old doc from Pete Davis, with William Watson's updated Tips (PSK) -

-

Some PIX specific information: -
Waikato Linux - Users' Group HOWTO. Nice detail (PSK) -
- John Leach's configs (PSK) -
Greg - Robinson's settings (PSK) -
- Scott's ipsec.conf for PIX (PSK, FreeS/WAN side only) -
- Rick Trimble's PIX and FreeS/WAN settings (PSK) -

-

Cisco VPN support - page -
- Cisco IPsec information page

-

Back to chart

-

Equinux VPN tracker (for Mac OS X)

- -

Equinux provides - this excellent interop PDF (PSK, RSA, X.509).

-

Back to chart

-

F-Secure

- -

pingworks.de's - "Connecting F-Secure's VPN+ to Linux FreeS/WAN" (PSK road warrior) -
    Same thing - as PDF -
- Success report, no detail (PSK) -
- Success report, no detail (Manual)

- - -

Back to chart

-

Gauntlet GVPN

-

- Richard Reiner's ipsec.conf (PSK) -
- Might work without that pesky firewall... (PSK) -
- - In late July, 2003 Alexandar Antik reported success interoperating - with Gauntlet 6.0 for Solaris (X.509). Unfortunately the message is not - properly archived at this time.

-

Back to chart

-

IBM AIX

-

- IBM's "Built-In Network Security with AIX" (PSK, X.509) -
- IBM's tip: importing Linux FreeS/WAN settings into AIX's ikedb - (PSK)

-

Back to chart

-

IBM AS/400

- -

- Richard Welty's tips and tricks -

-

Back to chart

-

Intel Shiva LANRover / Net Structure

- -

Snowcrash's configs - (PSK) -
Old configs from an - interop (PSK) -
- The day Shiva tickled a Pluto bug (PSK) -
     - Follow up: success!

-

Back to chart

-

LanCom (formerly ELSA)

- -

Jakob Curdes successfully created a PSK connection with the LanCom - 1612 in August 2003. - -

-

Back to chart

-

Linksys

- -
As tunnel endpoint
-

Ken Bantoft's - instructions (Road Warrior with PSK) -
- Nate Carlson's caveats

-
In IPsec passthrough mode
-

Sample HOWTO - through a Linksys Router -
- Nadeem Hasan's configs -
- Brock Nanson's tips -

-

Back to chart

-

Lucent

-

- Partial success report; see also the next message in thread

- - -

Back to chart

-

Netasq

-

- French page with configs (X.509)

- - -

Back to chart

-

Netcelo

-

- French page with configs (X.509) - -

-

Back to chart

-

Netgear fvs318

- -

- John Morris' setup (PSK)

-

Back to chart

-

Netscreen 100 or 5xp

-

- Errol Neal's settings (PSK) -
- Corey Rogers' configs (PSK, no PFS) -
- Jordan Share's configs (PSK, 2 subnets, through static NAT) -
- Set src proxy_id to your protected subnet/mask -
- French page with ipsec.conf, Netscreen screen shots (X.509, may need to - revert to PSK...)

-

- A report of a company using Netscreen with FreeS/WAN on a large scale - (FreeS/WAN road warriors?)

-

Back to chart

-

Nortel Contivity

- -

- JJ Streicher-Bremer's mini HOWTO for old new software. (PSK with two - subnets) -
- French page with configs (X.509). This succeeds using the above - X.509 tip.

- - -

Back to chart

-

Radguard

-

- Marko Hausalo's configs (PSK). Note: These do create a connection, - as you can see by "IPsec SA established". -
- Claudia Schmeing's comments

-

Back to chart

-

Raptor (NT or Solaris)

-

- -

- Peter Mazinger's settings (PSK) -
- Peter Gerland's configs (PSK) -
- Charles Griebel's configs (PSK). -
- Lumir Srch's tips (PSK)

-

- John Hardy's configs (Manual) -
- Older Raptors want 3DES keys in 3 parts (Manual). -
- Different keys for each direction? (Manual) -

-

Back to chart

-

Redcreek Ravlin

- -

Back to chart

-

SonicWall

- -

Paul Wouters' - config (PSK) -
- Dilan Arumainathan's configuration (PSK) -
Dariush's setup... - only opens one way (PSK) -
- Andreas Steffen's tips (X.509) -

-

Back to chart

-

Sun Solaris

- -

- Reports of some successful interops from a fellow @sun.com. See - also - these follow up posts. -
- Aleks Shenkman's configs (Manual in transport mode) -
- -

-

Back to chart

-

Symantec

- -

- Andreas Steffen's configs for Symantec 200R (PSK)

-

Back to chart

-

Watchguard Firebox

- -

- WatchGuard's HOWTO (PSK) -
- Ronald C. Riviera's Settings (PSK) -
- Walter Wickersham's Notes (PSK) -
- Max Enders' Configs (Manual)

-

- Old known issue with auto keying -
- Tips on key generation and format (Manual) -

-

Back to chart

-

Xedia Access Point/QVPN

-

- Hybrid IPsec/L2TP connection settings (X.509) -
- Xedia's LAN-LAN links don't use multiple tunnels -
     - That explanation, continued

-

Back to chart

-

Zyxel

- -

- Zyxel's Zywall to FreeS/WAN instructions (PSK) -
- Zyxel's Prestige to FreeS/WAN instructions (PSK). Note: not all - Prestige versions include VPN software. -
Fabrice - Cahen's HOWTO (PSK) -
    

-

Back to chart

- - -
-Contents -Previous -Next - - diff --git a/doc/intro.html b/doc/intro.html deleted file mode 100644 index 3afc3e324..000000000 --- a/doc/intro.html +++ /dev/null @@ -1,733 +0,0 @@ - - - -Introduction to FreeS/WAN - - - - -Contents -Next -
-

Introduction

-

This section gives an overview of:

- -

This section is intended to cover only the essentials, things you - should know before trying to use FreeS/WAN.

-

For more detailed background information, see the - history and politics and IPsec - protocols sections.

-

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 approach has both considerable - advantages and some limitations. For discussion, see our - IPsec section

-

IPsec can be used on any machine which does IP networking. Dedicated - IPsec gateway machines can be installed wherever required to protect - traffic. IPsec can also run on routers, on firewall machines, on - various application servers, and on end-user desktop or laptop - machines.

-

Three protocols are used

- -

Our implementation has three main parts:

- -

IPsec is optional for the current (version 4) Internet Protocol. - FreeS/WAN adds IPsec to the Linux IPv4 network stack. Implementations - of IP version 6 are required to - include IPsec. Work toward integrating FreeS/WAN into the Linux IPv6 - stack has started.

-

For more information on IPsec, see our - IPsec protocols section, our collection of - IPsec links or the RFCs which are the - official definitions of these protocols.

-

Interoperating with other IPsec - implementations

-

IPsec is designed to let different implementations work together. We - provide:

- -

The VPN Consortium fosters cooperation among implementers and - interoperability among implementations. Their - web site has much more information.

-

Advantages of IPsec

-

IPsec has a number of security advantages. Here are some - independently written articles which discuss these:

-

SANS institute papers. See the - section on Encryption &VPNs. -
- Cisco's white papers on "Networking Solutions". -
- Advantages of ISCS (Linux Integrated Secure Communications System; - includes FreeS/WAN and other software).

-

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:

- -

There is enough opportunity in these applications that vendors are - flocking to them. IPsec is being built into routers, into firewall - products, and into major operating systems, primarily to support these - applications. See our list of - implementations for details.

-

We support both of those applications, and various less common IPsec - applications as well, but we also add one of our own:

- -

This is an extension we are adding to the protocols. FreeS/WAN is the - first prototype implementation, though we hope other IPsec - implementations will adopt the technique once we demonstrate it. See - project goals below for why we think this is important.

-

A somewhat more detailed description of each of these applications is - below. Our quickstart section - will show you how to build each of them.

-

Using secure tunnels to create a VPN

-

A VPN, or Virtual Private N -etwork lets two networks communicate securely when the only connection - between them is over a third network which they do not trust.

-

The method is to put a security gateway machine between each of the - communicating networks and the untrusted network. The gateway machines - encrypt packets entering the untrusted net and decrypt packets leaving - it, creating a secure tunnel through it.

-

If the cryptography is strong, the implementation is careful, and the - administration of the gateways is competent, then one can reasonably - trust the security of the tunnel. The two networks then behave like a - single large private network, some of whose links are encrypted tunnels - through untrusted nets.

-

Actual VPNs are often more complex. One organisation may have fifty - branch offices, plus some suppliers and clients, with whom it needs to - communicate securely. Another might have 5,000 stores, or 50,000 - point-of-sale devices. The untrusted network need not be the Internet. - All the same issues arise on a corporate or institutional network - whenever two departments want to communicate privately with each other.

-

Administratively, the nice thing about many VPN setups is that large - parts of them are static. You know the IP addresses of most of the - machines involved. More important, you know they will not change on - you. This simplifies some of the admin work. For cases where the - addresses do change, see the next section.

-

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:

- -

These require somewhat different setup than VPN gateways with static - addresses and with client systems behind them, but are basically not - problematic.

-

There are some difficulties which appear for some road warrior - connections:

- -

In most situations, however, FreeS/WAN supports road warrior - connections just fine.

-

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.

-

Both systems pick up the authentication information they need from - the DNS (domain name service), the - service they already use to look up IP addresses. Of course the - administrators must put that information in the DNS, and must set up - their gateways with opportunistic encryption enabled. Once that is - done, everything is automatic. The gateways look for opportunities to - encrypt, and encrypt whatever they can. Whether they also accept - unencrypted communication is a policy decision the administrator can - make.

-

This technique can give two large payoffs:

- -

Opportunistic encryption is not (yet?) a standard part of the IPsec - protocols, but an extension we are proposing and demonstrating. For - details of our design, see links below.

-

Only one current product we know of implements a form of - opportunistic encryption. Secure sendmail - will automatically encrypt server-to-server mail transfers whenever - possible.

-

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:

- -

Automatic keying is much more secure, since if an enemy gets one key - only messages between the previous re-keying and the next are exposed. - It is therefore the usual mode of operation for most IPsec deployment, - and the mode we use in our setup examples. FreeS/WAN does support - manual keying for special circumstanes. See this - section.

-

For automatic keying, the two systems must authenticate each other - during the negotiations. There is a choice of methods for this:

- -

Public key techniques are much preferable, for reasons discussed - later, and will be used in all our setup examples. FreeS/WAN does - also support auto-keying with shared secret authentication. See this - section.

-

The FreeS/WAN project

-

For complete information on the project, see our web site, - freeswan.org.

-

In summary, we are implementing the - IPsec protocols for Linux and extending them to do - opportunistic encryption.

-

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:

- -

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:

- -

The rest of the team are Canadians, working in Canada. ( -Why Canada?)

- -

The project is funded by civil libertarians who consider our goals - worthwhile. Most of the team are paid for this work.

-

People outside this core team have made substantial contributions. - See

- -

Additional contributions are welcome. See the - FAQ for details.

-

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.

-

FreeS/WAN is, however, quite widely used. Products we know of that - use it are listed below. We would appreciate hearing, via the - mailing lists, of any we don't know of.

-

Full Linux distributions

-

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

- -

For distributions which do not include FreeS/WAN and are not Redhat - (which we develop and test on), there is additional information in our compatibility section.

-

The server edition of Corel Linux - (Canada) also had FreeS/WAN, but Corel have dropped that product line.

-

Linux kernel distributions

- -

Office server distributions

-

FreeS/WAN is also included in several distributions aimed at the - market for turnkey business servers:

- -

Firewall distributions

-

Several distributions intended for firewall and router applications - include FreeS/WAN:

- -

There are also several sets of scripts available for managing a - firewall which is also acting as a FreeS/WAN IPsec gateway. See this - list.

-

Firewall and VPN products

-

Several vendors use FreeS/WAN as the IPsec component of a turnkey - firewall or VPN product.

-

Software-only products:

- -

Products that include the hardware:

- -

Rebel.com, makers of the Netwinder Linux - machines (ARM or Crusoe based), had a product that used FreeS/WAN. The - company is in receivership so the future of the Netwinder is at best - unclear. PKIX patches for FreeS/WAN - developed at Rebel are listed in our web links document.

-

Information sources

-

This HowTo, in multiple formats

-

FreeS/WAN documentation up to version 1.5 was available only in HTML. - Now we ship two formats:

- -

and provide a Makefile to generate other formats if required:

- -

The Makefile assumes the htmldoc tool is available. You can download - it from Easy Software.

-

All formats should be available at the following websites:

- -

The distribution tarball has only the two HTML formats.

-

Note: If you need the latest doc version, for - example to see if anyone has managed to set up interoperation between - FreeS/WAN and whatever, then you should download the current snapshot. - What is on the web is documentation as of the last release. Snapshots - have all changes I've checked in to date.

-

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:

- -

Man pages for common commands include:

- -

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

-

In the event of disagreement between this HTML documentation and the - man pages, the man pages are more likely correct since they are written - by the implementers. Please report any such inconsistency on the - mailing list.

-

Other documents in the distribution

-

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

-

The Libdes encryption library we use has its own documentation. You - can find it in the library directory..

-

Background material

-

Throughout this documentation, I write as if the reader had at least - a general familiarity with Linux, with Internet Protocol networking, - and with the basic ideas of system and network security. Of course that - will certainly not be true for all readers, and quite likely not even - for a majority.

-

However, I must limit amount of detail on these topics in the main - text. For one thing, I don't understand all the details of those topics - myself. Even if I did, trying to explain everything here would produce - extremely long and almost completely unreadable documentation.

-

If one or more of those areas is unknown territory for you, there are - plenty of other resources you could look at:

-
-
Linux
-
the Linux Documentation Project - or a local Linux User Group - and these links
-
IP networks
-
Rusty Russell's - Networking Concepts HowTo and these - links
-
Security
-
Schneier's book Secrets and Lies - and these links
-
-

Also, I do make an effort to provide some background material in - these documents. All the basic ideas behind IPsec and FreeS/WAN are - explained here. Explanations that do not fit in the main text, or that - not everyone will need, are often in the - glossary, which is the largest single file in this document set. - There is also a background - file containing various explanations too long to fit in glossary - definitions. All files are heavily sprinkled with links to each other - and to the glossary. If some passage makes no sense to you, try - the links.

-

For other reference material, see the - bibliography and our collection of web - links.

-

Of course, no doubt I get this (and other things) wrong sometimes. - Feedback via the mailing lists is - welcome.

-

Archives of the project mailing list

-

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

- - The two archives use completely different search engines. You might - want to try both. -

More recently we have expanded to five lists, each with its own - archive.

-

More information on mailing lists.

-

User-written HowTo information

-

Various user-written HowTo documents are available. The ones covering - FreeS/WAN-to-FreeS/WAN connections are:

- -

User-wriiten HowTo material may be especially helpful if you - need to interoperate with another IPsec implementation. We - have neither the equipment nor the manpower to test such - configurations. Users seem to be doing an admirable job of filling the - gaps.

- -

Check what version of FreeS/WAN user-written documents cover. The - software is under active development and the current version may be - significantly different from what an older document describes.

-

Papers on FreeS/WAN

-

Two design documents show team thinking on new developments:

- -

Both documents are works in progress and are frequently revised. For - the latest version, see the design mailing - list. Comments should go to that list.

-

There is now an - Internet Draft on Opportunistic Encryption by Michael Richardson, - Hugh Redelmeier and Henry Spencer. This is a first step toward getting - the protocol standardised so there can be multiple implementations of - it. Discussion of it takes place on the - IETF IPsec Working Group mailing list.

-

A number of papers giving further background on FreeS/WAN, or - exploring its future or its applications, are also available:

- -

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

-

There are also several papers in languages other than English, see - our web links.

-

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 and the version of MD5 - that we use each have their own license.

-

Distribution sites

-

FreeS/WAN is available from a number of sites.

-

Primary site

-

Our primary site, is at xs4all (Thanks, folks!) in Holland:

- -

Mirrors

-

There are also mirror sites all over the world:

- -

Thanks to those folks as well.

-

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:

- -

Any of those will have a list of other "munitions" mirrors. There is - also a CD available.

-

Links to other sections

-

For more detailed background information, see:

- -

To begin working with FreeS/WAN, go to our - quickstart guide.

-
-Contents -Next - - diff --git a/doc/ipsec.html b/doc/ipsec.html deleted file mode 100644 index 4fb27b92b..000000000 --- a/doc/ipsec.html +++ /dev/null @@ -1,1040 +0,0 @@ - - - -Introduction to FreeS/WAN - - - - -Contents -Previous -Next -
-

The IPsec protocols

-

This section provides information on the IPsec protocols which - FreeS/WAN implements. For more detail, see the RFCs -.

-

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

-

Protocols and phases

-

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" (also written as 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.

-

There is more detail below, but a quick summary of how the whole - thing works is:

-
-
Phase one IKE (main mode exchange)
-
sets up a keying channel (ISAKMP SA) between the two gateways
-
Phase two IKE (quick mode exchange)
-
sets up data channels (IPsec SAs)
-
IPsec proper
-
exchanges data using AH or ESP
-
-

Both phases of IKE are repeated periodically to automate re-keying.

-

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.

- -

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.

- -

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:

- -

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 provide a useful - security service -- only encrypted data is passed over the Internet -- - but it 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.

- -

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:

- -

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:

- -

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 about any - of those, then he has interesting intelligence on your company, whether - or not he can read the messages themselves.

-

Even just knowing that there is network traffic between two sites may - tell an analyst something useful, especially when combined with - whatever other information he or she may have. For example, if you know - Company A is having cashflow problems and Company B is looking for - aquisitions, then knowing that packets are passing between the two is - interesting. It is more interesting if you can tell it is email, and - perhaps yet more if you know the sender and recipient.

-

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, to improve resistance to traffic analysis, - you should encrypt as much traffic as possible, not just as - much as seems necessary.

-

Using multiple encryption

-

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:

- -

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:

- -

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:

- -

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 - won the AES competition to choose a - relacement for DES. It will almost certainly be added to FreeS/WAN and - to other IPsec implementations. Patches - are already available.

-

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

-

Choice of hash algorithm

-

The IPsec RFCs require two hash algorithms -- - MD5 and SHA-1 -- both of which - FreeS/WAN implements.

-

Various other algorithms -- such as RIPEMD and Tiger -- are listed in - the RFCs as optional. None of these are in the FreeS/WAN distribution, - or are likely to be added, although user - patches exist for several of them.

-

Additional hash algorithms -- - SHA-256, SHA-384 and SHA-512 -- may be required to give hash - strength matching the strength of AES. - These are likely to be added to FreeS/WAN along with AES.

-

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:

- -

The protocol also allows implementations to add their own encryption - algorithms, authentication algorithms or Diffie-Hellman groups. We do - not support any such extensions, but there are some - patches that do.

-

There are a number of complications:

- -

These complications can of course lead to problems, particularly when - two different implementations attempt to interoperate. For example, we - have seen problems such as:

- -

Despite this, we do interoperate successfully with many - implementations, including both Windows 2000 and PGPnet. Details are in - our interoperability document.

-

Sequence of messages in IKE

-

Each phase (see previous section)of IKE - involves a series of messages. In Pluto error messages, these are - abbreviated using:

-
-
M
-
Main mode, settting up the keying channel (ISAKMP - SA)
-
Q
-
Quick mode, setting up the data channel (IPsec SA)
-
I
-
Initiator, the machine that starts the negotiation
-
R
-
Responder
-
-

For example, the six messages of a main mode negotiation, in - sequence, are labelled:

-
       MI1 ---------->
-           <---------- MR1
-       MI2 ----------> 
-           <---------- MR2
-       MI3 ---------->
-           <---------- MR3
-

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. In either case, the HMAC - construct is used as the authentication mechanism. -

There is a separate authentication operation at the IKE level, in - which each gateway authenticates the other. This can be done in a - variety of ways.

-
-
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 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 technique used is - HMAC, defined in RFC 2104.

-

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

- -

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

- -

Pluto is controlled mainly by the - ipsec.conf(5) configuration file.

-

The ipsec(8) command

-

The ipsec(8) command is a front - end shellscript 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 .

-

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.

-

We currently have 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 - it now seems moribund, displaced by IKE. Sun now (as of Solaris 8.0) - ship an IPsec implementation using IKE. We have no plans to implement - SKIP. If a user were to implement it, we would almost certainly not - want to add the code to our distribution.

-
-Contents -Previous -Next - - diff --git a/doc/kernel.html b/doc/kernel.html deleted file mode 100644 index de305683a..000000000 --- a/doc/kernel.html +++ /dev/null @@ -1,353 +0,0 @@ - - - -Introduction to FreeS/WAN - - - - -Contents -Previous -Next -
-

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:

- -

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 the attacker uses once he or - she has become root on your system. The kit introduces assorted - additional compromises so that the attacker will continue to "own" your - system despite most things you might do to recovery the situation. 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 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.
-
-
-
-
-Contents -Previous -Next - - diff --git a/doc/mail.html b/doc/mail.html deleted file mode 100644 index 68b5d8cd8..000000000 --- a/doc/mail.html +++ /dev/null @@ -1,216 +0,0 @@ - - - -Introduction to FreeS/WAN - - - - -Contents -Previous -Next -
-

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:

- -

Archives of these lists are available via the - web interface.

-

Which list should I use?

-

For most questions, please check the FAQ - first, and if that does not have an answer, ask on the users list. "My - configuration doesn't work." does not belong on the bugs list, and "Can - FreeS/WAN do such-and-such" or "How do I configure it to..." do not - belong in design discussions.

-

Cross-posting the same message to two or more of these lists is - discouraged. Quite a few people read more than one list and getting - multiple copies is annoying.

-

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.

- -

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.

-

Products that include FreeS/WAN

-

Our introduction document gives a list - of products that include FreeS/WAN. If you have, or are - considering, one of those, check the supplier's web site for - information on mailing lists for their users.

-

Linux mailing lists

- -

Each of the scure distribution projects also has its own web site and - mailing list. Some of the sites are:

- -

Lists for IETF working groups

-

Each IETF working group has an - associated mailing list where much of the work takes place.

- -

Other mailing lists

- -

Usenet newsgroups

- -
-Contents -Previous -Next - - diff --git a/doc/makecheck.html b/doc/makecheck.html deleted file mode 100644 index e77631782..000000000 --- a/doc/makecheck.html +++ /dev/null @@ -1,523 +0,0 @@ - - - -Introduction to FreeS/WAN - - - - -Contents -Previous -Next -
-

How to configure to use "make check"

-

What is "make check"

-

"make check" is a target in the top level makefile. It takes care of - running a number of unit and system tests to confirm that FreeSWAN has - been compiled correctly, and that no new bugs have been introduced.

-

As FreeSWAN contains both kernel and userspace components, doing - testing of FreeSWAN requires that the kernel be simulated. This is - typically difficult to do as a kernel requires that it be run on bare - hardware. A technology has emerged that makes this simpler. This is - User Mode Linux.

-

User-Mode Linux is a way to build a Linux kernel such that it can - run as a process under another Linux (or in the future other) kernel. - Presently, this can only be done for 2.4 guest kernels. The host kernel - can be 2.2 or 2.4.

-

"make check" expects to be able to build User-Mode Linux kernels - with FreeSWAN included. To do this it needs to have some files - downloaded and extracted prior to running "make check". This is - described in the UML testing document.

-

After having run the example in the UML testing document and - successfully brought up the four machine combination, you are ready to - use "make check"

-

Running "make check"

-

"make check" works by walking the FreeSWAN source tree invoking the - "check" target at each node. At present there are tests defined only - for the klips directory. These tests will use the UML - infrastructure to test out pieces of the klips code.

-

The results of the tests can be recorded. If the environment - variable $REGRESSRESULTS is non-null, then the results of - each test will be recorded. This can be used as part of a nightly - regression testing system, see Nightly testing - for more details.

-

"make check" otherwise prints a minimal amount of output for each - test, and indicates pass/fail status of each test as they are run. - Failed tests do not cause failure of the target in the form of exit - codes.

-

How to write a "make check" test

-

Structure of a test

-

Each test consists of a set of directories under testing/ -. There are directories for klips, pluto, -packaging and libraries. Each directory has a list - of tests to run is stored in a file called TESTLIST in - that directory. e.g. testing/klips/TESTLIST.

-

The TESTLIST

-

This isn't actually a shell script. It just looks like one. Some - tools other than /bin/sh process it. Lines that start with # are - comments.

-
-# test-kind     directory-containing-test       expectation     [PR#]
-
-

The first word provides the test type, detailed below.

-

The second word is the name of the test to run. This the directory - in which the test case is to be found..

-

The third word may be one of:

-
-
blank/good
-
the test is believed to function, report failure
-
bad
-
the test is known to fail, report unexpected success
-
suspended
-
the test should not be run
-
-

The fourth word may be a number, which is a PR# if the test is - failing.

-

Test kinds

- The test types are: -
-
skiptest
-
means run no test.
-
ctltest
-
means run a single system without input/output.
-
klipstest
-
means run a single system with input/output networks
-
umlplutotest
-
means run a pair of systems
-
umlXhost
-
run an arbitrary number of systems
-
suntest (TBD)
-
means run a quad of east/west/sunrise/sunset
-
roadtest (TBD)
-
means run a trio of east-sunrise + warrior
-
extrudedtest (TBD)
-
means run a quad of east-sunrise + warriorsouth + park
-
mkinsttest
-
a test of the "make install" machinery.
-
kernel_test_patch
-
a test of the "make kernelpatch" machinery.
-
- Tests marked (TBD) have yet to be fully defined. -

Each test directory has a file in it called testparams.sh -. This file sets a number of environment variables to define the - parameters of the test.

-

Common parameters

-
-
TESTNAME
-
the name of the test (repeated for checking purposes)
-
TEST_TYPE
-
the type of the test (repeat of type type above)
-
TESTHOST
-
the name of the UML machine to run for the test, typically "east" or - "west"
-
TEST_PURPOSE
-
The purpose of the test is one of: -
-
goal
-
The goal purpose is where a test is defined for code that is not yet - finished. The test indicates when the goals have in fact been reached.
-
regress
-
This is a test to determine that a previously existing bug has been - repaired. This test will initially be created to reproduce the bug in - isolation, and then the bug will be fixed.
-
exploit
-
This is a set of packets/programs that causes a vulnerability to be - exposed. It is a specific variation of the regress option.
-
-
-
TEST_GOAL_ITEM
-
-
in the case of a goal test, this is a reference to the requirements - document
-
TEST_PROB_REPORT
-
in the case of regression test, this the problem report number from - GNATS
-
TEST_EXPLOIT_URL
-
in the case of an exploit, this is a URL referencing the paper - explaining the origin of the test and the origin of exploit software
-
REF_CONSOLE_OUTPUT
-
a file in the test directory that contains the sanitized console - output against which to compare the output of the actual test.
-
REF_CONSOLE_FIXUPS
-
a list of scripts (found in klips/test/fixups) to apply - to sanitize the console output of the machine under test. These are - typically perl, awk or sed scripts that remove things in the kernel - output that change each time the test is run and/or compiled.
-
INIT_SCRIPT
-
-

a file of commands that is fed into the virtual machine's console in - single user mode prior to starting the tests. This file will usually - set up any eroute's and SADB entries that are required for the test.

-

Lines beginning with # are skipped. Blank lines are skipped. - Otherwise, a shell prompted is waited for each time (consisting of -\n#) and then the command is sent. Note that the prompt is waited - for before the command and not after, so completion of the last command - in the script is not required. This is often used to invoke a program - to monitor the system, e.g. ipsec pf_key.

-
-
RUN_SCRIPT
-
-

a file of commands that is fed into the virtual machine's console in - single user mode, before the packets are sent. On single machine tests, - this script doesn't provide any more power than INIT_SCRIPT, but is - implemented for consistency's sake.

-
-
FINAL_SCRIPT
-
-

a file of commands that is fed into the virtual machine's console in - single user mode after the final packet is sent. Similar to - INIT_SCRIPT, above. If not specified, then the single command "halt" is - sent. If specified, then the script should end with a halt command to - nicely shutdown the UML.

-
-
CONSOLEDIFFDEBUG
-
If set to "true" then the series of console fixups (see - REF_CONSOLE_FIXUPS) will be output after it is constructed. (It should - be set to "false", or unset otherwise)
-
NETJIGDEBUG
-
If set to "true" then the series of console fixups (see - REF_CONSOLE_FIXUPS) will be output after it is constructed. (It should - be set to "false", or unset otherwise)
-
NETJIGTESTDEBUG
-
If set to "netjig", then the results of talking to the -uml_netjig will be printed to stderr during the test. In - addition, the jig will be invoked with --debug, which causes it to log - its process ID, and wait 60 seconds before continuing. This can be used - if you are trying to debug the uml_netjig program itself.
-
HOSTTESTDEBUG
-
If set to "hosttest", then the results of taling to the consoles of - the UMLs will be printed to stderr during the test.
-
NETJIGWAITUSER
-
If set to "waituser", then the scripts will wait forever for user - input before they shut the tests down. Use this is if you are debugging - through the kernel.
-
PACKETRATE
-
A number, in miliseconds (default is 500ms) at which packets will - be replayed by the netjig.
-
-

KLIPStest paramaters

-

The klipstest function starts a program ( -testing/utils/uml_netjig/uml_netjig) to setup a bunch of I/O - sockets (that simulate network interfaces). It then exports the - references to these sockets to the environment and invokes (using - system()) a given script. It waits for the script to finish.

- - -

The script invoked (testing/utils/host-test.tcl) is a - TCL expect script that arranges - to start the UML and configure it appropriately for the test. The - configuration is done with the script given above for INIT_SCRIPT -. The TCL script then forks, leaves the UML in the background and exits. - uml_netjig continues. It then starts listening to the simulated network - answering ARPs and inserting packets as appropriate.

-

The klipstest function invokes uml_netjig with - arguments to capture output from network interface(s) and insert - packets as appropriate:

-
-
PUB_INPUT
-
a pcap file to feed in on the - public (encrypted) interface. (typically, eth1)
-
PRIV_INPUT
-
a pcap file to feed in on the private (plain-text) interface - (typically, eth0).
-
REF_PUB_OUTPUT
-
a text file containing tcpdump output. Packets on the public (eth1) - interface are captured to a pcap - file by uml_netjig. The klipstest function then uses - tcpdump on the file to produce text output, which is compared to the - file given.
-
REF_PUB_FILTER
-
a program that will filter the TCPDUMP output to do further - processing. Defaults to "cat".
-
REF_PRIV_OUTPUT
-
a text file containing tcpdump output. Packets on the private (eth0) - interface are captured and compared after conversion by tcpdump, as - with REFPUBOUTPUT.
-
REF_PRIV_FILTER
-
a program that will filter the TCPDUMP output to do further - processing. Defaults to "cat".
-
EXITONEMPTY
-
a flag for uml_netjig. It should contain - "--exitonempty" of uml_netjig should exit when all of the input ( -PUBINPUT,PRIVINPUT) packets have been injected.
-
ARPREPLY
-
a flag for uml_netjig. It should contain "--arpreply" - if uml_netjig should reply to ARP requests. One will - typically set this to avoid having to fudge the ARP cache manually.
-
TCPDUMPFLAGS
-
a set of flags for the tcpdump used when converting captured output. - Typical values will include "-n" to turn off DNS, and often "-E" to set - the decryption key (tcpdump 3.7.1 and higher only) for ESP packets. The - "-t" flag (turn off timestamps) is provided automatically
-
NETJIG_EXTRA
-
additional comments to be sent to the netjig. This may arrange to - record or create additional networks, or may toggle options.
-
-

mkinsttest paramaters

-

The basic concept of the mkinsttest test type is that - it performs a "make install" to a temporary $DESTDIR. The resulting - tree can then be examined to determine if it was done properly. The - files can be uninstalled to determine if the file list was correct, or - the contents of files can be examined more precisely.

-
-
INSTALL_FLAGS
-
If set, then an install will be done. This provides the set of flags - to provide for the install. The target to be used (usually "install") - must be among the flags.
-
POSTINSTALL_SCRIPT
-
If set, a script to run after initial "make install". Two arguments - are provided: an absolute path to the root of the FreeSWAN src tree, - and an absolute path to the temporary installation area.
-
INSTALL2_FLAGS
-
If set, a second install will be done using these flags. Similarly - to INSTALL_FLAGS, the target must be among the flags.
-
UNINSTALL_FLAGS
-
If set, an uninstall will be done using these flags. Similarly to - INSTALL_FLAGS, the target (usually "uninstall") must be among the - flags.
-
REF_FIND_f_l_OUTPUT
-
If set, a find $ROOT ( -type f -or -type -l ) will be - done to get a list of a real files and symlinks. The resulting file - will be compared to the file listed by this option.
-
REF_FILE_CONTENTS
-
If set, it should point to a file containing records for the form: -
-  
-
-reffile   
-
-samplefile
-
- one record per line. A diff between the provided reference file, and - the sample file (located in the temporary installation root) will be - done for each record.
-
-

rpm_build_install_test paramaters

-

The rpm_build_install_test type is to verify that the - proper packing list is produced by "make rpm", and that the mechanisms - for building the kernel modules produce consistent results.

-
-
RPM_KERNEL_SOURCE
-
Point to an extracted copy of the RedHat kernel source code. - Variables from the environment may be used.
-
REF_RPM_CONTENTS
-
This is a file containing one record per line. Each record consists - of a RPM name (may contain wildcards) and a filename to compare the - contents to. The RPM will be located and a file list will be produced - with rpm2cpio.
-
-

libtest paramaters

-

The libtest test is for testing library routines. The library file - is expected to provided an #ifdef by the name of - library - -. The libtest type invokes the C compiler to compile this - file, links it against libfreeswan.a (to resolve any other - dependancies) and runs the test with the -r argument to - invoke a regression test.

-

The library test case is expected to do a self-test, exiting with - status code 0 if everything is okay, and with non-zero otherwise. A - core dump (exit code greater than 128) is noted specifically.

-

Unlike other tests, there are no subdirectories required, or other - parameters to set.

-

umlplutotest paramaters

-

The umlplutotest function starts a pair of user mode line processes. - This is a 2-host version of umlXhost. The "EAST" and "WEST" slots are - defined.

-

umlXhost parameters

-

The umlXtest function starts an arbitrary number of user mode line - processes.

- - -

The script invoked (testing/utils/Xhost-test.tcl) is a - TCL expect script that arranges - to start each UML and configure it appropriately for the test. It then - starts listening (using uml_netjig) to the simulated network answering - ARPs and inserting packets as appropriate.

-

umlXtest has a series of slots, each of which should be filled by a - host. The list of slots is controlled by the variable, XHOST_LIST. This - variable should be set to a space seperated list of slots. The former - umlplutotest is now implemented as a variation of the umlXhost test, - with XHOST_LIST="EAST WEST".

-

For each host slot that is defined, a series of variables should be - filled in, defining what configuration scripts to use for that host.

-

The following are used to control the console input and output to - the system. Where the string ${host} is present, the host slot should - be filled in. I.e. for the two host system with XHOST_LIST="EAST WEST", - then the variables: EAST_INIT_SCRIPT and WEST_INIT_SCRIPT will exist.

-
-
${host}HOST
-
The name of the UML host which will fill this slot
-
${host}_INIT_SCRIPT
-
-

a file of commands that is fed into the virtual machine's console in - single user mode prior to starting the tests. This file will usually - set up any eroute's and SADB entries that are required for the test. - Similar to INIT_SCRIPT, above.

-
-
${host}_RUN_SCRIPT
-
-

a file of commands that is fed into the virtual machine's console in - single user mode, before the packets are sent. This set of commands is - run after all of the virtual machines are initialized. I.e. after - EAST_INIT_SCRIPT AND WEST_INIT_SCRIPT. This script can therefore - do things that require that all machines are properly configured.

-
-
${host}_RUN2_SCRIPT
-
-

a file of commands that is fed into the virtual machine's console in - single user mode, after the packets are sent. This set of commands is - run before any of the virtual machines have been shut down. (I.e. - before EAST_FINAL_SCRIPT AND WEST_FINAL_SCRIPT.) This script can - therefore catch post-activity status reports.

-
-
${host}_FINAL_SCRIPT
-
-

a file of commands that is fed into the virtual machine's console in - single user mode after the final packet is sent. Similar to - INIT_SCRIPT, above. If not specified, then the single command "halt" is - sent. Note that when this script is run, the other virtual machines may - already have been killed. If specified, then the script should end with - a halt command to nicely shutdown the UML.

-
-
REF_${host}_CONSOLE_OUTPUT
-
Similar to REF_CONSOLE_OUTPUT, above.
-
-

Some additional flags apply to all hosts:

-
-
REF_CONSOLE_FIXUPS
-
a list of scripts (found in klips/test/fixups) to apply - to sanitize the console output of the machine under test. These are - typically perl, awk or sed scripts that remove things in the kernel - output that change each time the test is run and/or compiled.
-
-

In addition to input to the console, the networks may have input fed - to them:

-
-
EAST_INPUT/WEST_INPUT
-
a pcap file to feed in on the - private network side of each network. The "EAST" and "WEST" here refer - to the networks, not the hosts.
-
REF_PUB_FILTER
-
a program that will filter the TCPDUMP output to do further - processing. Defaults to "cat".
-
REF_EAST_FILTER/REF_WEST_FILTER
-
a program that will filter the TCPDUMP output to do further - processing. Defaults to "cat".
-< -
TCPDUMPFLAGS
-
a set of flags for the tcpdump used when converting captured output. - Typical values will include "-n" to turn off DNS, and often "-E" to set - the decryption key (tcpdump 3.7.1 and higher only) for ESP packets. The - "-t" flag (turn off timestamps) is provided automatically
-
REF_EAST_OUTPUT/REF_WEST_OUTPUT
-
a text file containing tcpdump output. Packets on the private (eth0) - interface are captured and compared after conversion by tcpdump, as - with REF_PUB_OUTPUT.
-

There are two additional environment variables that may be set on - the command line:

-
-
NETJIGVERBOSE=verbose export NETJIGVERBOSE
-
If set, then the test output will be "chatty", and let you know - what commands it is running, and as packets are sent. Without it set, - the output is limited to success/failure messages.
-
NETJIGTESTDEBUG=netjig export NETJIGTESTDEBUG
-
This will enable debugging of the communication with uml_netjig, - and turn on debugging in this utility. This does not imply - NETJIGVERBOSE.
-
-
HOSTTESTDEBUG=hosttest export HOSTTESTDEBUG
-
This will show all interactions with the user-mode-linux consoles
-
-

kernel_patch_test paramaters

-

The kernel_patch_test function takes some kernel source, copies it - with lndir, and then applies the patch as produced by "make - kernelpatch".

-

The following are used to control the input and output to the - system:

-
-
KERNEL_NAME
-
the kernel name, typically something like "linus" or "rh"
-
KERNEL_VERSION
-
the kernel version number, as in "2.2" or "2.4".
-
KERNEL_${KERNEL_NAME}${KERNEL_VERSION}_SRC
-
This variable should set in the environment, probably in - ~/freeswan-regress-env.sh. Examples of this variables would be - KERNEL_LINUS2_0_SRC or KERNEL_RH7_3_SRC. This variable should point to - an extracted copy of the kernel source in question.
-
REF_PATCH_OUTPUT
-
a copy of the patch output to compare against
-
KERNEL_PATCH_LEAVE_SOURCE
-
If set to a non-empty string, then the patched kernel source is not - removed at the end of the test. This will typically be set in the - environment while debugging.
-
-

module_compile paramaters

-

The module_compile test attempts to build the KLIPS module against a - given set of kernel source. This is also done by the RPM tests, but in - a very specific manner.

-

There are two variations of this test - one where the kernel either - doesn't need to be configured, or is already done, and tests were there - is a local configuration file.

-

Where the kernel doesn't need to be configured, the kernel source - that is found is simply used. It may be a RedHat-style kernel, where - one can cause it to configure itself via rhconfig.h-style definitions. - Or, it may just be a kernel tree that has been configured.

-

If the variable KERNEL_CONFIG_FILE is set, then a new directory is - created for the kernel source. It is populated with lndir(1). The - referenced file is then copied in as .config, and "make oldconfig" is - used to configure the kernel. This resulting kernel is then used as the - reference source.

-

In all cases, the kernel source is found the same was for the - kernelpatch test, i.e. via KERNEL_VERSION/KERNEL_NAME and - KERNEL_${KERNEL_NAME}${KERNEL_VERSION}_SRC.

-

Once there is kernel source, the module is compiled using the - top-level "make module" target.

-

The test is considered successful if an executable is found in - OUTPUT/module/ipsec.o at the end of the test.

-
-
KERNEL_NAME
-
the kernel name, typically something like "linus" or "rh"
-
KERNEL_VERSION
-
the kernel version number, as in "2.2" or "2.4".
-
KERNEL_${KERNEL_NAME}${KERNEL_VERSION}_SRC
-
This variable should set in the environment, probably in - ~/freeswan-regress-env.sh. Examples of this variables would be - KERNEL_LINUS2_0_SRC or KERNEL_RH7_3_SRC. This variable should point to - an extracted copy of the kernel source in question.
-
KERNEL_CONFIG_FILE
-
The configuration file for the kernel.
-
KERNEL_PATCH_LEAVE_SOURCE
-
If set to a non-empty string, then the configured kernel source is - not removed at the end of the test. This will typically be set in the - environment while debugging.
-
MODULE_DEF_INCLUDE
-
The include file that will be used to configure the KLIPS module, - and possibly the kernel source.
-
-

Current pitfalls

-
-
"tcpdump dissector" not available.
-
This is a non-fatal warning. If uml_netjig is invoked with the -t - option, then it will attempt to use tcpdump's dissector to decode each - packet that it processes. The dissector is presently not available, so - this option it normally turned off at compile time. The dissector - library will be released with tcpdump version 4.0.
-
-
-Contents -Previous -Next - - diff --git a/doc/manpages.html b/doc/manpages.html deleted file mode 100644 index 81ca11ae0..000000000 --- a/doc/manpages.html +++ /dev/null @@ -1,145 +0,0 @@ - - - -Introduction to FreeS/WAN - - - - -Contents -Previous -Next -
-

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)
-
secrets for IKE authentication, either pre-shared keys or RSA - private keys
-
-

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.

-

The exceptions are commands for mainpulating the - RSA keys used in Pluto authentication:

-
-
ipsec_rsasigkey(8)
-
generate keys
-
ipsec_newhostkey(8)
-
generate keys in a convenient format
-
ipsec_showhostkey(8) -
-
extract RSA keys from - ipsec.secrets(5) (or optionally, another file) and format them for - insertion in ipsec.conf(5) or - in DNS records
-
-

Note that:

- -

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
-
-
-Contents -Previous -Next - - diff --git a/doc/nightly.html b/doc/nightly.html deleted file mode 100644 index 580fc0fc5..000000000 --- a/doc/nightly.html +++ /dev/null @@ -1,125 +0,0 @@ - - - -Introduction to FreeS/WAN - - - - -Contents -Previous -
-

Nightly regression testing

-

The nightly regression testing system consists of several shell - scripts and some perl scripts. The goal is to check out a fresh tree, - run "make check" on it, record the results and summarize the results to - the team and to the web site.

-

Output can be found on adams -, although the tests are actually run on another project machine.

-

How to setup the nightly build

-

The best way to do nightly testing is to setup a new account. We - call the account "build" - you could call it something else, but there - may still be some references to ~build in the scripts.

-

Files you need to know about

-

As few files as possible need to be extracted from the source tree - - files are run from the source tree whenever possible. However, there - are some bootstrap and configuration files that are necessary.

-

There are 7 files in testing/utils that are involved:

-
-
nightly-sample.sh
-
This is the root of the build process. This file should be copied - out of the CVS tree, to $HOME/bin/nightly.sh of the build account. This - file should be invoked from cron.
-
freeswan-regress-env-sample.sh
-
This file should be copied to $HOME/freeswan-regress-env.sh. It - should be edited to localize the values. See below.
-
regress-cleanup.pl
-
This file needs to be copied to $HOME/bin/regress-cleanup.pl. It is - invoked by the nightly file before doing anything else. It removes - previous nights builds in order to free up disk space for the build - about to be done.
-
teammail-sample.sh
-
A script used to send results email to the "team". This sample - script could be copied to $HOME/bin/teammail.sh. This version will PGP - encrypt all the output to the team members. If this script is used, - then PGP will have to be properly setup to have the right keys.
-
regress-nightly.sh
-
This is the first stage of the nightly build. This stage will call - other scripts as appropriate, and will extract the source code from - CVS. This script should be copied to $HOME/bin/regress-nightly.sh
-
regress-stage2.sh
-
This is the second stage of the nightly build. It is called in - place. It essentially sets up the UML setup in umlsetup.sh, and calls - "make check".
-
regress-summarize-results.pl
-
This script will summarize the results from the tests to a - permanent directory set by $REGRESSRESULTS. It is invoked from the - stage2 nightly script.
-
regress-chart.sh
-
This script is called at the end of the build process, and will - summarize each night's results (as saved into $REGRESSRESULTS by - regress-summarize-results.pl) as a chart using gnuplot. Note that this - requires at least gnuplot 3.7.2.
-
-

Configuring freeswan-regress-env.sh

-

For more info on KERNPOOL, UMLPATCH, BASICROOT and SHAREDIR, see - User-Mode-Linux testing guide.

-
-
KERNPOOL
-
Extract copy of some kernel source to be used for UML builds
-
UMLPATCH
-
matching User-Mode-Linux patch.
-
BASICROOT
-
the root file system image (see - User-Mode-Linux testing guide).
-
SHAREDIR=${BASICROOT}/usr/share
-
The /usr/share to use.
-
REGRESSTREE
-
A directory in which to store the nightly regression results. - Directories will be created by date in this tree.
-
TCPDUMP=tcpdump-3.7.1
-
The path to the tcpdump to - use. This must have crypto compiled in, and must be at least 3.7.1
-
KERNEL_RH7_2_SRC=/a3/kernel_sources/linux-2.4.9-13/
-
An extracted copy of the RedHat 7.2. kernel source. If set, then - the packaging/rpm-rh72-install-01 test will be run, and an RPM will be - built as a test.
-
KERNEL_RH7_3_SRC=/a3/kernel_sources/rh/linux-2.4.18-5
-
An extracted copy of the RedHat 7.3. kernel source. If set, then - the packaging/rpm-rh73-install-01 test will be run, and an RPM will be - built as a test.
-
NIGHTLY_WATCHERS="userid,userid,userid"
-
The list of people who should receive nightly output. This is used - by teammail.sh
-
FAILLINES=128
-
How many lines of failed test output to include in the nightly - output
-
PATH=$PATH:/sandel/bin export PATH
-
You can also override the path if necessary here.
-
CVSROOT=:pserver:anoncvs@ip212.xs4net.freeswan.org:/freeswan/MASTER
-
The CVSROOT to use. This example may work for anonymous CVS, but - will be 12 hours behind the primary, and is still experimental
-
SNAPSHOTSIGDIR=$HOME/snapshot-sig
-
For the release tools, where to put the generated per-snapshot - signature keys
-
LASTREL=1.97
-
the name of the last release branch (to find the right per-snapshot - signature
-
-
-
-Contents -Previous - - diff --git a/doc/oppimpl.txt b/doc/oppimpl.txt deleted file mode 100644 index fe4527d4e..000000000 --- a/doc/oppimpl.txt +++ /dev/null @@ -1,514 +0,0 @@ -Implementing Opportunistic Encryption - -Henry Spencer & D. Hugh Redelmeier - -Version 4+, 15 Dec 2000 - - - -Updates - -Major changes since last version: "Negotiation Issues" section discussing -some interoperability matters, plus some wording cleanup. Some issues -arising from discussions at OLS are not yet resolved, so there will almost -certainly be another version soon. - -xxx incoming could be opportunistic or RW. xxx any way of saving unaware -implementations??? xxx compression needs mention. - - - -Introduction - -A major long-term goal of the FreeS/WAN project is opportunistic -encryption: a security gateway intercepts an outgoing packet aimed at a -new remote host, and quickly attempts to negotiate an IPsec tunnel to that -host's security gateway, so that traffic can be encrypted and -authenticated without changes to the host software. (This generalizes -trivially to the end-to-end case where host and security gateway are one -and the same.) If the attempt fails, the packet (or a retry thereof) -passes through in clear or is dropped, depending on local policy. -Prearranged tunnels bypass all this, so static VPNs can coexist with -opportunistic encryption. - -xxx here Although significant intelligence about all this is necessary at the -initiator end, it's highly desirable for little or no special machinery -to be needed at the responder end. In particular, if none were needed, -then a security gateway which knows nothing about opportunistic encryption -could nevertheless participate in some opportunistic connections. - -IPSEC gives us the low-level mechanisms, and the key-exchange machinery, -but there are some vague spots (to put it mildly) at higher levels. - -One constraint which deserves comment is that the process of tunnel setup -should be quick. Moreover, the decision that no tunnel can be created -should also be quick, since that will be a common case, at least in the -beginning. People will be reluctant to use opportunistic encryption if it -causes gross startup delays on every connection, even connections which see -no benefit from it. Win or lose, the process must be rapid. - -There's nothing much we can do to speed up the key exchange itself. (The -one thing which conceivably might be done is to use Aggressive Mode, which -involves fewer round trips, but it has limitations and possible security -problems, and we're reluctant to touch it.) What we can do, is to make the -other parts of the setup process as quick as possible. This desire will -come back to haunt us below. :-) - -A further note is that we must consider the processing at the responder -end as well as the initiator end. - -Several pieces of new machinery are needed to make this work. Here's a -brief list, with details considered below. - -+ Outgoing Packet Interception. KLIPS needs to intercept packets which -likely would benefit from tunnel setup, and bring them to Pluto's -attention. There needs to be enough memory in the process that the same -tunnel doesn't get proposed too often (win or lose). - -+ Smart Connection Management. Not only do we need to establish tunnels -on request, once a tunnel is set up, it needs to be torn down eventually -if it's not in use. It's also highly desirable to detect the fact that it -has stopped working, and do something useful. Status changes should be -coordinated between the two security gateways unless one has crashed, -and even then, they should get back into sync eventually. - -+ Security Gateway Discovery. Given a packet destination, we must decide -who to attempt to negotiate a tunnel with. This must be done quickly, win -or lose, and reliably even in the presence of diverse network setups. - -+ Authentication Without Prearrangement. We need to be sure we're really -talking to the intended security gateway, without being able to prearrange -any shared information. He needs the same assurance about us. - -+ More Flexible Policy. In particular, the responding Pluto needs a way -to figure out whether the connection it is being asked to make is okay. -This isn't as simple as just searching our existing conn database -- we -probably have to specify *classes* of legitimate connections. - -Conveniently, we have a three-letter acronym for each of these. :-) - -Note on philosophy: we have deliberately avoided providing six different -ways to do each step, in favor of specifying one good one. Choices are -provided only when they appear to be necessary. (Or when we are not yet -quite sure yet how best to do something...) - - - -OPI, SCM - -Smart Connection Management would be quite useful even by itself, -requiring manual triggering. (Right now, we do the manual triggering, but -not the other parts of SCM.) Outgoing Packet Interception fits together -with SCM quite well, and improves its usefulness further. Going through a -connection's life cycle from the start... - -OPI itself is relatively straightforward, aside from the nagging question -of whether the intercepted packet is put on hold and then released, or -dropped. Putting it on hold is preferable; the alternative is to rely on -the application or the transport layer re-trying. The downside of packet -hold is extra resources; the downside of packet dropping is that IPSEC -knows *when* the packet can finally go out, and the higher layers don't. -Either way, life gets a little tricky because a quickly-retrying -application may try more than once before we know for sure whether a -tunnel can be set up, and something has to detect and filter out the -duplications. Some ARP implementations use the approach of keeping one -packet for an as-yet-unresolved address, and throwing away any more that -appear; that seems a reasonable choice. - -(Is it worth intercepting *incoming* packets, from the outside world, and -attempting tunnel setup based on them? Perhaps... if, and only if, we -organize AWP so that non-opportunistic SGs can do it somehow. Otherwise, -if the other end has not initiated tunnel setup itself, it will not be -prepared to do so at our request.) - -Once a tunnel is up, packets going into it naturally are not intercepted -by OPI. However, we need to do something about the flip side of this too: -after deciding that we *cannot* set up a tunnel, either because we don't -have enough information or because the other security gateway is -uncooperative, we have to remember that for a while, so we don't keep -knocking on the same locked door. One plausible way of doing that is to -set up a bypass "tunnel" -- the equivalent of our current %passthrough -connection -- and have it managed like a real SCM tunnel (finite lifespan -etc.). This sounds a bit heavyweight, but in practice, the alternatives -all end up doing something very similar when examined closely. Note that -we need an extra variant of this, a block rather than a bypass, to cover -the case where local policy dictates that packets *not* be passed through; -we still have to remember the fact that we can't set up a real tunnel. - -When to tear tunnels down is a bit problematic, but if we're setting up a -potentially unbounded number of them, we have to tear them down *somehow* -*sometime*. It seems fairly obvious that we set a tentative lifespan, -probably fairly short (say 1min), and when it expires, we look to see if -the tunnel is still in use (say, has had traffic in the last half of the -lifespan). If so, we assign it a somewhat longer lifespan (say 10min), -after which we look again. If not, we close it down. (This lifespan is -independent of key lifetime; it is just the time when the tunnel's future -is next considered. This should happen reasonably frequently, unlike -rekeying, which is costly and shouldn't be too frequent.) Multi-step -backoff algorithms probably are not worth the trouble; looking every -10min doesn't seem onerous. - -For the tunnel-expiry decision, we need to know how long it has been since -the last traffic went through. A more detailed history of the traffic -does not seem very useful; a simple idle timer (or last-traffic timestamp) -is both necessary and sufficient. And KLIPS already has this. - -As noted, default initial lifespan should be short. However, Pluto should -keep a history of recently-closed tunnels, to detect cases where a tunnel -is being repeatedly re-established and should be given a longer lifespan. -(Not only is tunnel setup costly, but it adds user-visible delay, so -keeping a tunnel alive is preferable if we have reason to suspect more -traffic soon.) Any tunnel re-established within 10min of dying should have -10min added to its initial lifespan. (Just leaving all tunnels open longer -is unappealing -- adaptive lifetimes which are sensitive to the behavior -of a particular tunnel are wanted. Tunnels are relatively cheap entities -for us, but that is not necessarily true of all implementations, and there -may also be administrative problems in sorting through large accumulations -of idle tunnels.) - -It might be desirable to have detailed information about the initial -packet when determining lifespans. HTTP connections in particular are -notoriously bursty and repetitive. - -Arguably it would be nice to monitor TCP connection status. A still-open -TCP connection is almost a guarantee that more traffic is coming, while -the closing of the only TCP connection through a tunnel is a good hint -that none is. But the monitoring is complex, and it doesn't seem worth -the trouble. - -IKE connections likewise should be torn down when it appears the need has -passed. They should linger longer than the last tunnel they administer, -just in case they are needed again; the cost of retaining them is low. An -SG with only a modest number of them open might want to simply retain each -until rekeying time, with more aggressive management cutting in only when -the number gets large. (They should be torn down eventually, if only to -minimize the length of a status report, but rekeying is the only expensive -event for them.) - -It's worth remembering that tunnels sometimes go down because the other -end crashes, or disconnects, or has a network link break, and we don't get -any notice of this in the general case. (Even in the event of a crash and -successful reboot, we won't hear about it unless the other end has -specific reason to talk IKE to us immediately.) Of course, we have to -guard against being too quick to respond to temporary network outages, -but it's not quite the same issue for us as for TCP, because we can tear -down and then re-establish a tunnel without any user-visible effect except -a pause in traffic. And if the other end does go down and come back up, -we and it can't communicate *at all* (except via IKE) until we tear down -our tunnel. - -So... we need some kind of heartbeat mechanism. Currently there is none -in IKE, but there is discussion of changing that, and this seems like the -best approach. Doing a heartbeat at the IP level will not tell us about a -crash/reboot event, and sending heartbeat packets through tunnels has -various complications (they should stop at the far mouth of the tunnel -instead of going on to a subnet; they should not count against idle -timers; etc.). Heartbeat exchanges obviously should be done only when -there are tunnels established *and* there has been no recent incoming -traffic through them. It seems reasonable to do them at lifespan ends, -subject to appropriate rate limiting when more than one tunnel goes to the -same other SG. When all traffic between the two ends is supposed to go -via the tunnel, it might be reasonable to do a heartbeat -- subject to a -rate limiter to avoid DOS attacks -- if the kernel sees a non-tunnel -non-IKE packet from the other end. - -If a heartbeat gets no response, try a few (say 3) pings to check IP -connectivity; if one comes back, try another heartbeat; if it gets no -response, the other end has rebooted, or otherwise been re-initialized, -and its tunnels should be torn down. If there's no response to the pings, -note the fact and try the sequence again at the next lifespan end; if -there's nothing then either, declare the tunnels dead. - -Finally... except in cases where we've decided that the other end is dead -or has rebooted, tunnel teardown should always be coordinated with the -other end. This means interpreting and sending Delete notifications, and -also Initial-Contacts. Receiving a Delete for the other party's tunnel -SAs should lead us to tear down our end too -- SAs (SA bundles, really) -need to be considered as paired bidirectional entities, even though the -low-level protocols don't think of them that way. - - - -SGD, AWP - -Given a packet destination, how do we decide who to (attempt to) negotiate -a tunnel with? And as a related issue, how do the negotiating parties -authenticate each other? DNSSEC obviously provides the tools for the -latter, but how exactly do we use them? - -Having intercepted a packet, what we know is basically the IP addresses of -source and destination (plus, in principle, some information about the -desired communication, like protocol and port). We might be able to map -the source address to more information about the source, depending on how -well we control our local networks, but we know nothing further about the -destination. - -The obvious first thing to do is a DNS reverse lookup on the destination -address; that's about all we can do with available data. Ideally, we'd -like to get all necessary information with this one DNS lookup, because -DNS lookups are time-consuming -- all the more so if they involve a DNSSEC -signature-checking treewalk by the name server -- and we've got to hurry. -While it is unusual for a reverse lookup to yield records other than PTR -records (or possibly CNAME records, for RFC 2317 classless delegation), -there's no reason why it can't. - -(For purposes like logging, a reverse lookup is usually followed by a -forward lookup, to verify that the reverse lookup wasn't lying about the -host name. For our purposes, this is not vital, since we use stronger -authentication methods anyway.) - -While we want to get as much data as possible (ideally all of it) from one -lookup, it is useful to first consider how the necessary information would -be obtained if DNS lookups were instantaneous. Two pieces of information -are absolutely vital at this point: the IP address of the other end's -security gateway, and the SG's public key*. - -(* Actually, knowledge of the key can be postponed slightly -- it's not -needed until the second exchange of the negotiations, while we can't even -start negotiations without knowing the IP address. The SG is not -necessarily on the plain-IP route to the destination, especially when -multiple SGs are present.) - -Given instantaneous DNS lookups, we would: - -+ Start with a reverse lookup to turn the address into a name. - -+ Look for something like RFC-2782 SRV records using the name, to find out -who provides this particular service. If none comes back, we can abandon -the whole process. - -+ Select one SRV record, which gives us the name of a target host (plus -possibly one or more addresses, if the name server has supplied address -records as Additional Data for the SRV records -- this is recommended -behavior but is not required). - -+ Use the target name to look up a suitable KEY record, and also address -record(s) if they are still needed. - -This gives us the desired address(es) and key. However, it requires three -lookups, and we don't even find out whether there's any point in trying -until after the second. - -With real DNS lookups, which are far from instantaneous, some optimization -is needed. At the very least, typical cases should need fewer lookups. - -So when we do the reverse lookup on the IP address, instead of asking for -PTR, we ask for TXT. If we get none, we abandon opportunistic -negotiation, and set up a bypass/block with a relatively long life (say -6hr) because it's not worth trying again soon. (Note, there needs to be a -way to manually force an early retry -- say, by just clearing out all -memory of a particular address -- to cover cases where a configuration -error is discovered and fixed.) - -xxx need to discuss multi-string TXTs - -In the results, we look for at least one TXT record with content -"X-IPsec-Server(nnn)=a.b.c.d kkk", following RFC 1464 attribute/value -notation. (The "X-" indicates that this is tentative and experimental; -this design will probably need modification after initial experiments.) -Again, if there is no such record, we abandon opportunistic negotiation. - -"nnn" and the parentheses surrounding it are optional. If present, it -specifies a priority (low number high priority), as for MX records, to -control the order in which multiple servers are tried. If there are no -priorities, or there are ties, pick one randomly. - -"a.b.c.d" is the dotted-decimal IP address of the SG. (Suitable extensions -for IPv6, when the time comes, are straightforward.) - -"kkk" is either an RSA-MD5 public key in base-64 notation, as in the text -form of an RFC 2535 KEY record, or "@hhh". In the latter case, hhh is a -DNS name, under which one Host/Authentication/IPSEC/RSA-MD5 KEY record is -present, giving the server's authentication key. (The delay of the extra -lookup is undesirable, but practical issues of key management may make it -advisable not to duplicate the key itself in DNS entries for many -clients.) - -It unfortunately does appear that the authentication key has to be -associated with the server, not the client behind it. At the time when -the responder has to authenticate our SG, it does not know which of its -clients we are interested in (i.e., which key to use), and there is no -good way to tell it. (There are some bad ways; this decision may merit -re-examination after experimental use.) - -The responder authenticates our SG by doing a reverse lookup on its IP -address to get a Host/Authentication/IPSEC/RSA-MD5 KEY record. He can -attempt this in parallel with the early parts of the negotiation (since he -knows our SG IP address from the first negotiation packet), at the risk of -having to abandon the attempt and do a different lookup if we use -something different as our ID (see below). Unfortunately, he doesn't yet -know what client we will claim to represent, so he'll need to do another -lookup as part of phase 2 negotiation (unless the client *is* our SG), to -confirm that the client has a TXT X-IPsec-Server record pointing to our -SG. (Checking that the record specifies the same key is not important, -since the responder already has a trustworthy key for our SG.) - -Also unfortunately, opportunistic tunnels can only have degenerate subnets -(/32 subnets, containing one host) at their ends. It's superficially -attractive to negotiate broader connections... but without prearrangement, -you don't know whether you can trust the other end's claim to have a -specific subnet behind it. Fixing this would require a way to do a -reverse lookup on the *subnet* (you cannot trust information in DNS -records for a name or a single address, which may be controlled by people -who do not control the whole subnet) with both the address and the mask -included in the name. Except in the special case of a subnet masked on a -byte boundary (in which case RFC 1035's convention of an incomplete -in-addr.arpa name could be used), this would need extensions to the -reverse-map name space, which is awkward, especially in the presence of -RFC 2317 delegation. (IPv6 delegation is more flexible and it might be -easier there.) - -There is a question of what ID should be used in later steps of -negotiation. However, the desire not to put more DNS lookups in the -critical path suggests avoiding the extra complication of varied IDs, -except in the Road Warrior case (where an extra lookup is inevitable). -Also, figuring out what such IDs *mean* gets messy. To keep things simple, -except in the RW case, all IDs should be IP addresses identical to those -used in the packet headers. - -For Road Warrior, the RW must be the initiator, since the home-base SG has -no idea what address the RW will appear at. Moreover, in general the RW -does not control the DNS entries for his address. This inherently denies -the home base any authentication of the RW's IP address; the most it can -do is to verify an identity he provides, and perhaps decide whether it -wishes to talk to someone with that identity, but this does not verify his -right to use that IP address -- nothing can, really. - -(That may sound like it would permit some man-in-the-middle attacks, but -the RW can still do full authentication of the home base, so a man in the -middle cannot successfully impersonate home base. Furthermore, a man in -the middle must impersonate both sides for the DH exchange to work. So -either way, the IKE negotiation falls apart.) - -A Road Warrior provides an FQDN ID, used for a forward lookup to obtain a -Host/Authentication/IPSEC/RSA-MD5 KEY record. (Note, an FQDN need not -actually correspond to a host -- e.g., the DNS data for it need not -include an A record.) This suffices, since the RW is the initiator and -the responder knows his address from his first packet. - -Certain situations where a host has a more-or-less permanent IP address, -but does not control its DNS entries, must be treated essentially like -Road Warrior. It is unfortunate that DNS's old inverse-query feature -cannot be used (nonrecursively) to ask the initiator's local DNS server -whether it has a name for the address, because the address will almost -always have been obtained from a DNS name lookup, and it might be a lookup -of a name whose DNS entries the host *does* control. (Real examples of -this exist: the host has a preferred name whose host-controlled entry -includes an A record, but a reverse lookup on the address sends you to an -ISP-controlled name whose entry has an A record but not much else.) Alas, -inverse query is long obsolete and is not widely implemented now. - -There are some questions in failure cases. If we cannot acquire the info -needed to set up a tunnel, this is the no-tunnel-possible case. If we -reach an SG but negotiation fails, this too is the no-tunnel-possible -case, with a relatively long bypass/block lifespan (say 1hr) since -fruitless negotiations are expensive. (In the multiple-SG case, it seems -unlikely to be worthwhile to try other SGs just in case one of them might -have a configuration permitting successful negotiation.) - -Finally, there is a sticky problem with timeouts. If the other SG is down -or otherwise inaccessible, in the worst case we won't hear about this -except by not getting responses. Some other, more pathological or even -evil, failure cases can have the same result. The problem is that in the -case where a bypass is permitted, we want to decide whether a tunnel is -possible quickly. It gets even worse if there are multiple SGs, in which -case conceivably we might want to try them all (since some SGs being up -when others are down is much more likely than SGs differing in policy). - -The patience setting needs to be configurable policy, with a reasonable -default (to be determined by experiment). If it expires, we simply have -to declare the attempt a failure, and set up a bypass/block. (Setting up -a tentative bypass/block, and replacing it with a real tunnel if remaining -attempts do produce one, looks attractive at first glance... but exposing -the first few seconds of a connection is often almost as bad as exposing -the whole thing!) Such a bypass/block should have a short lifespan, say -10min, because the SG(s) might be only temporarily unavailable. - -The flip side of IKE waiting for a timeout is that all other forms of -feedback, e.g. "host not reachable", should be *ignored*, because you -cannot trust them! This may need kernel changes. - -Can AWP be done by non-opportunistic SGs? Probably not; existing SG -implementations generally aren't prepared to do anything suitable, except -perhaps via the messy business of certificates. There is one borderline -exception: some implementations rely on LDAP for at least some of their -information fetching, and it might be possible to substitute a custom LDAP -server which does the right things for them. Feasibility of this depends -on details, which we don't know well enough. - -[This could do with a full example, a complete packet by packet walkthrough -including all DNS and IKE traffic.] - - - -MFP - -Our current conn database simply isn't flexible enough to cover all this -properly. In particular, the responding Pluto needs a way to figure out -whether the connection it is being asked to make is legitimate. - -This is more subtle than it sounds, given the problem noted earlier, that -there's no clear way to authenticate claims to represent a non-degenerate -subnet. Our database has to be able to say "a connection to any host in -this subnet is okay" or "a connection to any subnet within this subnet is -okay", rather than "a connection to exactly this subnet is okay". (There -is some analogy to the Road Warrior case here, which may be relevant.) -This will require at least a re-interpretation of ipsec.conf. - -Interim stages of implementation of this will require a bit of thought. -Notably, we need some way of dealing with the lack of fully signed DNSSEC -records. Without user interaction, probably the best we can do is to -remember the results of old fetches, compare them to the results of new -fetches, and complain and disbelieve all of it if there's a mismatch. -This does mean that somebody who gets fake data into our very first fetch -will fool us, at least for a while, but that seems an acceptable tradeoff. - - - -Negotiation Issues - -There are various options which are nominally open to negotiation as part -of setup, but which have to be nailed down at least well enough that -opportunistic SGs can reliably interoperate. Somewhat arbitrarily and -tentatively, opportunistic SGs must support Main Mode, Oakley group 5 for -D-H, 3DES encryption and MD5 authentication for both ISAKMP and IPsec SAs, -RSA digital-signature authentication with keys between 2048 and 8192 bits, -and ESP doing both encryption and authentication. They must do key PFS -in Quick Mode, but not identity PFS. - - - -What we need from DNS - -Fortunately, we don't need any new record types or suchlike to make this -all work. We do, however, need attention to a couple of areas in DNS -implementation. - -First, size limits. Although the information we directly need from a -lookup is not enormous -- the only potentially-big item is the KEY record, -and there should be only one of those -- there is still a problem with -DNSSEC authentication signatures. With a 2048-bit key and assorted -supporting information, we will fill most of a 512-byte DNS UDP packet... -and if the data is to have DNSSEC authentication, at least one quite large -SIG record will come too. Plus maybe a TSIG signature on the whole -response, to authenticate it to our resolver. So: DNSSEC-capable name -servers must fix the 512-byte UDP limit. We're told there are provisions -for this; implementation of them is mandatory. - -Second, interface. It is unclear how the resolver interface will let us -ask for DNSSEC authentication. We would prefer to ask for "authentication -where possible", and get back the data with each item flagged by whether -authentication was available (and successful!) or not available. Having -to ask separately for authenticated and non-authenticated data would -probably be acceptable, *provided* both will be cached on the first -request, so the two requests incur only one set of (non-local) network -traffic. Either way, we want to see the name server and resolver do this -for us; that makes sense in any case, since it's important that -verification be done somewhere where it can be cached, the more centrally -the better. - -Finally, a wistful note: the ability to do a limited form of inverse -queries (an almost forgotten feature), to ask the local name server which -hostname it recently mapped to a particular address, would be quite -helpful. Note, this is *NOT* the same as a reverse lookup, and crude -fakes like putting a dotted-decimal address in brackets do not suffice. diff --git a/doc/opportunism-spec.txt b/doc/opportunism-spec.txt deleted file mode 100644 index fbe319a57..000000000 --- a/doc/opportunism-spec.txt +++ /dev/null @@ -1,1254 +0,0 @@ - - - - - - - - - - Opportunistic Encryption - - Henry Spencer - D. Hugh Redelmeier - henry@spsystems.net - hugh@mimosa.com - Linux FreeS/WAN Project - - - - Opportunistic encryption permits secure - (encrypted, authenticated) communication via IPsec - without connection-by-connection prearrangement, - either explicitly between hosts (when the hosts - are capable of it) or transparently via packet- - intercepting security gateways. It uses DNS - records (authenticated with DNSSEC) to provide the - necessary information for gateway discovery and - gateway authentication, and constrains negotiation - enough to guarantee success. - - Substantive changes since draft 3: write off - inverse queries as a lost cause; use Invalid-SPI - rather than Delete as notification of unknown SA; - minor wording improvements and clarifications. - This document takes over from the older ``Imple- - menting Opportunistic Encryption'' document. - - -1. Introduction - -A major goal of the FreeS/WAN project is opportunistic -encryption: a (security) gateway intercepts an outgoing -packet aimed at a remote host, and quickly attempts to nego- -tiate an IPsec tunnel to that host's security gateway. If -the attempt succeeds, traffic can then be secure, transpar- -ently (without changes to the host software). If the -attempt fails, the packet (or a retry thereof) passes -through in clear or is dropped, depending on local policy. -Prearranged tunnels bypass the packet interception etc., so -static VPNs can coexist with opportunistic encryption. - -This generalizes trivially to the end-to-end case: host and -security gateway simply are one and the same. Some opti- -mizations are possible in that case, but the basic scheme -need not change. - -The objectives for security systems need to be explicitly -stated. Opportunistic encryption is meant to achieve secure -communication, without prearrangement of the individual con- -nection (although some prearrangement on a per-host basis is - - - -Draft 4 3 May 2001 1 - - - - - - Opportunistic Encryption - - -required), between any two hosts which implement the proto- -col (and, if they act as security gateways, between hosts -behind them). Here ``secure'' means strong encryption and -authentication of packets, with authentication of partici- -pants--to prevent man-in-the-middle and impersonation -attacks--dependent on several factors. The biggest factor -is the authentication of DNS records, via DNSSEC or equiva- -lent means. A lesser factor is which exact variant of the -setup procedure (see section 2.2) is used, because there is -a tradeoff between strong authentication of the other end -and ability to negotiate opportunistic encryption with hosts -which have limited or no control of their reverse-map DNS -records: without reverse-map information, we can verify that -the host has the right to use a particular FQDN (Fully Qual- -ified Domain Name), but not whether that FQDN is authorized -to use that IP address. Local policy must decide whether -authentication or connectivity has higher priority. - -Apart from careful attention to detail in various areas, -there are three crucial design problems for opportunistic -encryption. It needs a way to quickly identify the remote -host's security gateway. It needs a way to quickly obtain -an authentication key for the security gateway. And the -numerous options which can be specified with IKE must be -constrained sufficiently that two independent implementa- -tions are guaranteed to reach agreement, without any -explicit prearrangement or preliminary negotiation. The -first two problems are solved using DNS, with DNSSEC ensur- -ing that the data obtained is reliable; the third is solved -by specifying a minimum standard which must be supported. - -A note on philosophy: we have deliberately avoided providing -six different ways to do each job, in favor of specifying -one good one. Choices are provided only when they appear to -be necessary, or at least important. - -A note on terminology: to avoid constant circumlocutions, an -ISAKMP/IKE SA, possibly recreated occasionally by rekeying, -will be referred to as a ``keying channel'', and a set of -IPsec SAs providing bidirectional communication between two -IPsec hosts, possibly recreated occasionally by rekeying, -will be referred to as a ``tunnel'' (it could conceivably -use transport mode in the host-to-host case, but we advocate -using tunnel mode even there). The word ``connection'' is -here used in a more generic sense. The word ``lifetime'' -will be avoided in favor of ``rekeying interval'', since -many of the connections will have useful lives far shorter -than any reasonable rekeying interval, and hence the two -concepts must be separated. - -A note on document structure: Discussions of why things were -done a particular way, or not done a particular way, are -broken out in paragraphs headed ``Rationale:'' (to preserve -the flow of the text, many such paragraphs are deferred to - - - -Draft 4 3 May 2001 2 - - - - - - Opportunistic Encryption - - -the ends of sections). Paragraphs headed ``Ahem:'' are dis- -cussions of where the problem is being made significantly -harder by problems elsewhere, and how that might be cor- -rected. Some meta-comments are enclosed in []. - -Rationale: The motive is to get the Internet encrypted. -That requires encryption without connection-by-connection -prearrangement: a system must be able to reliably negotiate -an encrypted, authenticated connection with a total -stranger. While end-to-end encryption is preferable, doing -opportunistic encryption in security gateways gives enormous -leverage for quick deployment of this technology, in a world -where end-host software is often primitive, rigid, and out- -dated. - -Rationale: Speed is of the essence in tunnel setup: a con- -nection-establishment delay longer than about 10 seconds -begins to cause problems for users and applications. Thus -the emphasis on rapidity in gateway discovery and key fetch- -ing. - -Ahem: Host-to-host opportunistic encryption would be utterly -trivial if a fast public-key encryption/signature algorithm -was available. You would do a reverse lookup on the desti- -nation address to obtain a public key for that address, and -simply encrypt all packets going to it with that key, sign- -ing them with your own private key. Alas, this is impracti- -cal with current CPU speeds and current algorithms (although -as noted later, it might be of some use for limited pur- -poses). Nevertheless, it is a useful model. - -2. Connection Setup - -For purposes of discussion, the network is taken to look -like this: - - Source----Initiator----...----Responder----Destination - -The intercepted packet comes from the Source, bound for the -Destination, and is intercepted at the Initiator. The Ini- -tiator communicates over the insecure Internet to the -Responder. The Source and the Initiator might be the same -host, or the Source might be an end-user host and the Ini- -tiator a security gateway (SG). Likewise for the Responder -and the Destination. - -Given an intercepted packet, whose useful information (for -our purposes) is essentially only the Destination's IP -address, the Initiator must quickly determine the Responder -(the Destination's SG) and fetch everything needed to -authenticate it. The Responder must do likewise for the -Initiator. Both must eventually also confirm that the other -is authorized to act on behalf of the client host behind it -(if any). - - - -Draft 4 3 May 2001 3 - - - - - - Opportunistic Encryption - - -An important subtlety here is that if the alternative to an -IPsec tunnel is plaintext transmission, negative results -must be obtained quickly. That is, the decision that no -tunnel can be established must also be made rapidly. - -2.1. Packet Interception - -Interception of outgoing packets is relatively straightfor- -ward in principle. It is preferable to put the intercepted -packet on hold rather than dropping it, since higher-level -retries are not necessarily well-timed. There is a problem -of hosts and applications retrying during negotiations. ARP -implementations, which face the same problem, use the -approach of keeping the most recent packet for an as-yet- -unresolved address, and throwing away older ones. (Incre- -menting of request numbers etc. means that replies to older -ones may no longer be accepted.) - -Is it worth intercepting incoming packets, from the outside -world, and attempting tunnel setup based on them? No, -unless and until a way can be devised to initiate oppor- -tunistic encryption to a non-opportunistic responder, -because if the other end has not initiated tunnel setup -itself, it will not be prepared to do so at our request. - -Rationale: Note, however, that most incoming packets will -promptly be followed by an outgoing packet in response! -Conceivably it might be useful to start early stages of -negotiation, at least as far as looking up information, in -response to an incoming packet. - -Rationale: If a plaintext incoming packet indicates that the -other end is not prepared to do opportunistic encryption, it -might seem that this fact should be noted, to avoid consum- -ing resources and delaying traffic in an attempt at oppor- -tunistic setup which is doomed to fail. However, this would -be a major security hole, since the plaintext packet is not -authenticated; see section 2.5. - -2.2. Algorithm - -For clarity, the following defers most discussion of error -handling to the end. - -Step 1. Initiator does a DNS reverse lookup on the Destina- - tion address, asking not for the usual PTR records, - but for TXT records. Meanwhile, Initiator also - sends a ping to the Destination, to cause any other - dynamic setup actions to start happening. (Ping - replies are disregarded; the host might not be - reachable with plaintext pings.) - -Step 2A. If at least one suitable TXT record (see section - 2.3) comes back, each contains a potential - - - -Draft 4 3 May 2001 4 - - - - - - Opportunistic Encryption - - - Responder's IP address and that Responder's public - key (or where to find it). Initiator picks one TXT - record, based on priority (see 2.3), thus picking a - Responder. If there was no public key in the TXT - record, the Initiator also starts a DNS lookup (as - specified by the TXT record) to get KEY records. - -Step 2B. If no suitable TXT record is available, and policy - permits, Initiator designates the Destination - itself as the Responder (see section 2.4). If pol- - icy does not permit, or the Destination is unre- - sponsive to the negotiation, then opportunistic - encryption is not possible, and Initiator gives up - (see section 2.5). - -Step 3. If there already is a keying channel to the Respon- - der's IP address, the Initiator uses the existing - keying channel; skip to step 10. Otherwise, the - Initiator starts an IKE Phase 1 negotiation (see - section 2.7 for details) with the Responder. The - address family of the Responder's IP address dic- - tates whether the keying channel and the outside of - the tunnel should be IPv4 or IPv6. - -Step 4. Responder gets the first IKE message, and responds. - It also starts a DNS reverse lookup on the Initia- - tor's IP address, for KEY records, on speculation. - -Step 5. Initiator gets Responder's reply, and sends first - message of IKE's D-H exchange (see 2.4). - -Step 6. Responder gets Initiator's D-H message, and - responds with a matching one. - -Step 7. Initiator gets Responder's D-H message; encryption - is now established, authentication remains to be - done. Initiator sends IKE authentication message, - with an FQDN identity if a reverse lookup on its - address will not yield a suitable KEY record. - (Note, an FQDN need not actually correspond to a - host--e.g., the DNS data for it need not include an - A record.) - -Step 8. Responder gets Initiator's authentication message. - If there is no identity included, Responder waits - for step 4's speculative DNS lookup to finish; it - should yield a suitable KEY record (see 2.3). If - there is an FQDN identity, responder discards any - data obtained from step 4's DNS lookup; does a for- - ward lookup on the FQDN, for a KEY record; waits - for that lookup to return; it should yield a suit- - able KEY record. Either way, Responder uses the - KEY data to verify the message's hash. Responder - replies with an authentication message, with an - - - -Draft 4 3 May 2001 5 - - - - - - Opportunistic Encryption - - - FQDN identity if a reverse lookup on its address - will not yield a suitable KEY record. - -Step 9A. (If step 2A was used.) The Initiator gets the - Responder's authentication message. Step 2A has - provided a key (from the TXT record or via DNS - lookup). Verify message's hash. Encrypted and - authenticated keying channel established, man-in- - middle attack precluded. - -Step 9B. (If step 2B was used.) The Initiator gets the - Responder's authentication message, which must con- - tain an FQDN identity (if the Responder can't put a - TXT in his reverse map he presumably can't do a KEY - either). Do forward lookup on the FQDN, get suit- - able KEY record, verify hash. Encrypted keying - channel established, man-in-middle attack pre- - cluded, but authentication weak (see 2.4). - -Step 10. Initiator initiates IKE Phase 2 negotiation (see - 2.7) to establish tunnel, specifying Source and - Destination identities as IP addresses (see 2.6). - The address family of those addresses also deter- - mines whether the inside of the tunnel should be - IPv4 or IPv6. - -Step 11. Responder gets first Phase 2 message. Now the - Responder finally knows what's going on! Unless - the specified Source is identical to the Initiator, - Responder initiates DNS reverse lookup on Source IP - address, for TXT records; waits for result; gets - suitable TXT record(s) (see 2.3), which should con- - tain either the Initiator's IP address or an FQDN - identity identical to that supplied by the Initia- - tor in step 7. This verifies that the Initiator is - authorized to act as SG for the Source. Responder - replies with second Phase 2 message, selecting - acceptable details (see 2.7), and establishes tun- - nel. - -Step 12. Initiator gets second Phase 2 message, establishes - tunnel (if he didn't already), and releases the - intercepted packet into it, finally. - -Step 13. Communication proceeds. See section 3 for what - happens later. - -As additional information becomes available, notably in -steps 1, 2, 4, 8, 9, 11, and 12, there is always a possibil- -ity that local policy (e.g., access limitations) might pre- -vent further progress. Whenever possible, at least attempt -to inform the other end of this. - - - - - -Draft 4 3 May 2001 6 - - - - - - Opportunistic Encryption - - -At any time, there is a possibility of the negotiation fail- -ing due to unexpected responses, e.g. the Responder not -responding at all or rejecting all Initiator's proposals. -If multiple SGs were found as possible Responders, the Ini- -tiator should try at least one more before giving up. The -number tried should be influenced by what the alternative -is: if the traffic will otherwise be discarded, trying the -full list is probably appropriate, while if the alternative -is plaintext transmission, it might be based on how long the -tries are taking. The Initiator should try as many as it -reasonably can, ideally all of them. - -There is a sticky problem with timeouts. If the Responder -is down or otherwise inaccessible, in the worst case we -won't hear about this except by not getting responses. Some -other, more pathological or even evil, failure cases can -have the same result. The problem is that in the case where -plaintext is permitted, we want to decide whether a tunnel -is possible quickly. There is no good solution to this, -alas; we just have to take the time and do it right. (Pass- -ing plaintext meanwhile looks attractive at first glance... -but exposing the first few seconds of a connection is often -almost as bad as exposing the whole thing. Worse, if the -user checks the status of the connection, after that brief -window it looks secure!) - -The flip side of waiting for a timeout is that all other -forms of feedback, e.g. ``host not reachable'', arguably -should be ignored, because in the absence of authenticated -ICMP, you cannot trust them! - -Rationale: An alternative, sometimes suggested, to the use -of explicit DNS records for SG discovery is to directly -attempt IKE negotiation with the destination host, and -assume that any relevant SG will be on the packet path, will -intercept the IKE packets, and will impersonate the destina- -tion host for the IKE negotiation. This is superficially -attractive but is a very bad idea. It assumes that routing -is stable throughout negotiation, that the SG is on the -plaintext-packets path, and that the destination host is -routable (yes, it is possible to have (private) DNS data for -an unroutable host). Playing extra games in the plaintext- -packet path hurts performance and can be expected to be -unpopular. Various difficulties ensue when there are multi- -ple SGs along the path (there is already bad experience with -this, in RSVP), and the presence of even one can make it -impossible to do IKE direct to the host when that is what's -wanted. Worst of all, such impersonation breaks the IP net- -work model badly, making problems difficult to diagnose and -impossible to work around (and there is already bad experi- -ence with this, in areas like web caching). - -Rationale: (Step 1.) Dynamic setup actions might include -establishment of demand-dialed links. These might be - - - -Draft 4 3 May 2001 7 - - - - - - Opportunistic Encryption - - -present anywhere along the path, so one cannot rely on out- -of-band communication at the Initiator to trigger them. -Hence the ping. - -Rationale: (Step 2.) In many cases, the IP address on the -intercepted packet will be the result of a name lookup just -done. Inverse queries, an obscure DNS feature from the dis- -tant past, in theory can be used to ask a DNS server to -reverse that lookup, giving the name that produced the -address. This is not the same as a reverse lookup, and the -difference can matter a great deal in cases where a host -does not control its reverse map (e.g., when the host's IP -address is dynamically assigned). Unfortunately, inverse -queries were never widely implemented and are now considered -obsolete. Phooey. - -Ahem: Support for a small subset of this admittedly-obscure -feature would be useful. Unfortunately, it seems unlikely. - -Rationale: (Step 3.) Using only IP addresses to decide -whether there is already a relevant keying channel avoids -some difficult problems. In particular, it might seem that -this should be based on identities, but those are not known -until very late in IKE Phase 1 negotiations. - -Rationale: (Step 4.) The DNS lookup is done on speculation -because the data will probably be useful and the lookup can -be done in parallel with IKE activity, potentially speeding -things up. - -Rationale: (Steps 7 and 8.) If an SG does not control its -reverse map, there is no way it can prove its right to use -an IP address, but it can nevertheless supply both an iden- -tity (as an FQDN) and proof of its right to use that iden- -tity. This is somewhat better than nothing, and may be -quite useful if the SG is representing a client host which -can prove its right to its IP address. (For example, a -fixed-address subnet might live behind an SG with a dynami- -cally-assigned address; such an SG has to be the Initiator, -not the Responder, so the subnet's TXT records can contain -FQDN identities, but with that restriction, this works.) It -might sound like this would permit some man-in-the-middle -attacks in important cases like Road Warrior, but the RW can -still do full authentication of the home base, so a man in -the middle cannot successfully impersonate home base, and -the D-H exchange doesn't work unless the man in the middle -impersonates both ends. - -Rationale: (Steps 7 and 8.) Another situation where proof -of the right to use an identity can be very useful is when -access is deliberately limited. While opportunistic encryp- -tion is intended as a general-purpose connection mechanism -between strangers, it may well be convenient for prearranged -connections to use the same mechanism. - - - -Draft 4 3 May 2001 8 - - - - - - Opportunistic Encryption - - -Rationale: (Steps 7 and 8.) FQDNs as identities are avoided -where possible, since they can involve synchronous DNS -lookups. - -Rationale: (Step 11.) Note that only here, in Phase 2, does -the Responder actually learn who the Source and Destination -hosts are. This unfortunately demands a synchronous DNS -lookup to verify that the Initiator is authorized to repre- -sent the Source, unless they are one and the same. This and -the initial TXT lookup are the only synchronous DNS lookups -absolutely required by the algorithm, and they appear to be -unavoidable. - -Rationale: While it might seem unlikely that a refusal to -cooperate from one SG could be remedied by trying another-- -presumably they all use the same policies--it's conceivable -that one might be misconfigured. Preferably they should all -be tried, but it may be necessary to set some limits on this -if alternatives exist. - -2.3. DNS Records - -Gateway discovery and key lookup are based on TXT and KEY -DNS records. The TXT record specifies IP address or other -identity of a host's SG, and possibly supplies its public -key as well, while the KEY record supplies public keys not -found in TXT records. - -2.3.1. TXT - -Opportunistic-encryption SG discovery uses TXT records with -the content: - - X-IPsec-Gateway(nnn)=iii kkk - -following RFC 1464 attribute/value notation. Records which -do not contain an ``='', or which do not have exactly the -specified form to the left of it, are ignored. (Near misses -perhaps should be reported.) - -The nnn is an unsigned integer which will fit in 16 bits, -specifying an MX-style preference (lower number = stronger -preference) to control the order in which multiple SGs are -tried. If there are ties, pick one, randomly enough that -the choice will probably be different each time. The pref- -erence field is not optional; use ``0'' if there is no mean- -ingful preference ordering. - -The iii part identifies the SG. Normally this is a dotted- -decimal IPv4 address or a colon-hex IPv6 address. The sole -exception is if the SG has no fixed address (see 2.4) but -the host(s) behind it do, in which case iii is of the form -``@fqdn'', where fqdn is the FQDN that the SG will use to -identify itself (in step 7 of section 2.2); such a record - - - -Draft 4 3 May 2001 9 - - - - - - Opportunistic Encryption - - -cannot be used for SG discovery by an Initiator, but can be -used for SG verification (step 11 of 2.2) by a Responder. - -The kkk part is optional. If it is present, it is an RSA- -MD5 public key in base-64 notation, as in the text form of -an RFC 2535 KEY record. If it is not present, this speci- -fies that the public key can be found in a KEY record -located based on the SG's identification: if iii is an IP -address, do a reverse lookup on that address, else do a for- -ward lookup on the FQDN. - -Rationale: While it is unusual for a reverse lookup to go -for records other than PTR records (or possibly CNAME -records, for RFC 2317 classless delegation), there's no rea- -son why it can't. The TXT record is a temporary stand-in -for (we hope, someday) a new DNS record for SG identifica- -tion and keying. Keeping the setup process fast requires -minimizing the number of DNS lookups, hence the desire to -put all the information in one place. - -Rationale: The use of RFC 1464 notation avoids collisions -with other uses of TXT records. The ``X-'' in the attribute -name indicates that this format is tentative and experimen- -tal; this design will probably need modification after ini- -tial experiments. The format is chosen with an eye on even- -tual binary encoding. Note, in particular, that the TXT -record normally contains the address of the SG, not (repeat, -not) its name. Name-to-address conversion is the job of -whatever generates the TXT record, which is expected to be a -program, not a human--this is conceptually a binary record, -temporarily using a text encoding. The ``@fqdn'' form of -the SG identity is for specialized uses and is never mapped -to an address. - -Ahem: A DNS TXT record contains one or more character -strings, but RFC 1035 does not describe exactly how a multi- -string TXT record is interpreted. This is relevant because -a string can be at most 255 characters, and public keys can -exceed this. Empirically, the standard pattern is that each -string which is both less than 255 characters and not the -final string of the record should have a blank appended to -it, and the strings of the record should then be concate- -nated. (This observation is based on how BIND 8 transforms -a TXT record from text to DNS binary.) - -2.3.2. KEY - -An opportunistic-encryption KEY record is an Authentication- -permitted, Entity (host), non-Signatory, IPsec, RSA/MD5 -record (that is, its first four bytes are 0x42000401), as -per RFCs 2535 and 2537. KEY records with other flags, pro- -tocol, or algorithm values are ignored. - - - - - -Draft 4 3 May 2001 10 - - - - - - Opportunistic Encryption - - -Rationale: Unfortunately, the public key has to be associ- -ated with the SG, not the client host behind it. The -Responder does not know which client it is supposed to be -representing, or which client the Initiator is representing, -until far too late. - -Ahem: Per-client keys would reduce vulnerability to key com- -promise, and simplify key changes, but they would require -changes to IKE Phase 1, to separately identify the SG and -its initial client(s). (At present, the client identities -are not known to the Responder until IKE Phase 2.) While -the current IKE standard does not actually specify (!) who -is being identified by identity payloads, the overwhelming -consensus is that they identify the SG, and as seen earlier, -this has important uses. - -2.3.3. Summary - -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. - -2.3.4. Implementation - -In the long run, we need either a tree of trust or a web of -trust, so we can trust our DNS data. The obvious approach -for DNS is a tree of trust, but there are various practical -problems with running all of this through the root servers, -and a web of trust is arguably more robust anyway. This is -logically independent of opportunistic encryption, and a -separate design proposal will be prepared. - - - - - -Draft 4 3 May 2001 11 - - - - - - Opportunistic Encryption - - -Interim stages of implementation of this will require a bit -of thought. Notably, we need some way of dealing with the -lack of fully signed DNSSEC records right away. Without -user interaction, probably the best we can do is to remember -the results of old fetches, compare them to the results of -new fetches, and complain and disbelieve all of it if -there's a mismatch. This does mean that somebody who gets -fake data into our very first fetch will fool us, at least -for a while, but that seems an acceptable tradeoff. (Obvi- -ously there needs to be a way to manually flush the remem- -bered results for a specific host, to permit deliberate -changes.) - -2.4. Responders Without Credentials - -In cases where the Destination simply does not control its -DNS reverse-map entries, there is no verifiable way to -determine a suitable SG. This does not make communication -utterly impossible, though. - -Simply attempting negotiation directly with the host is a -last resort. (An aggressive implementation might wish to -attempt it in parallel, rather than waiting until other -options are known to be unavailable.) In particular, in -many cases involving dynamic addresses, it will work. It -has the disadvantage of delaying the discovery that oppor- -tunistic encryption is entirely impossible, but the case -seems common enough to justify the overhead. - -However, there are policy issues here either way, because it -is possible to impersonate such a host. The host can supply -an FQDN identity and verify its right to use that identity, -but except by prearrangement, there is no way to verify that -the FQDN is the right one for that IP address. (The data -from forward lookups may be controlled by people who do not -own the address, so it cannot be trusted.) The encryption -is still solid, though, so in many cases this may be useful. - -2.5. Failure of Opportunism - -When there is no way to do opportunistic encryption, a pol- -icy issue arises: whether to put in a bypass (which allows -plaintext traffic through) or a block (which discards it, -perhaps with notification back to the sender). The choice -is very much a matter of local policy, and may depend on -details such as the higher-level protocol being used. For -example, an SG might well permit plaintext HTTP but forbid -plaintext Telnet, in which case both a block and a bypass -would be set up if opportunistic encryption failed. - -A bypass/block must, in practice, be treated much like an -IPsec tunnel. It should persist for a while, so that high- -overhead processing doesn't have to be done for every -packet, but should go away eventually to return resources. - - - -Draft 4 3 May 2001 12 - - - - - - Opportunistic Encryption - - -It may be simplest to treat it as a degenerate tunnel. It -should have a relatively long lifetime (say 6h) to keep the -frequency of negotiation attempts down, except in the case -where the other SG simply did not respond to IKE packets, -where the lifetime should be short (say 10min) because the -other SG is presumably down and might come back up again. -(Cases where the other SG responded to IKE with unauthenti- -cated error reports like ``port unreachable'' are border- -line, and might deserve to be treated as an intermediate -case: while such reports cannot be trusted unreservedly, in -the absence of any other response, they do give some reason -to suspect that the other SG is unable or unwilling to par- -ticipate in opportunistic encryption.) - -As noted in section 2.1, one might think that arrival of a -plaintext incoming packet should cause a bypass/block to be -set up for its source host: such a packet is almost always -followed by an outgoing reply packet; the incoming packet is -clear evidence that opportunistic encryption is not avail- -able at the other end; attempting it will waste resources -and delay traffic to no good purpose. Unfortunately, this -means that anyone out on the Internet who can forge a source -address can prevent encrypted communication! Since their -source addresses are not authenticated, plaintext packets -cannot be taken as evidence of anything, except perhaps that -communication from that host is likely to occur soon. - -There needs to be a way for local administrators to remove a -bypass/block ahead of its normal expiry time, to force a -retry after a problem at the other end is known to have been -fixed. - -2.6. Subnet Opportunism - -In principle, when the Source or Destination host belongs to -a subnet and the corresponding SG is willing to provide tun- -nels to the whole subnet, this should be done. There is no -extra overhead, and considerable potential for avoiding -later overhead if similar communication occurs with other -members of the subnet. Unfortunately, at the moment, oppor- -tunistic tunnels can only have degenerate subnets (single -hosts) at their ends. (This does, at least, set up the key- -ing channel, so that negotiations for tunnels to other hosts -in the same subnets will be considerably faster.) - -The crucial problem is step 11 of section 2.2: the Responder -must verify that the Initiator is authorized to represent -the Source, and this is impossible for a subnet because -there is no way to do a reverse lookup on it. Information -in DNS records for a name or a single address cannot be -trusted, because they may be controlled by people who do not -control the whole subnet. - - - - - -Draft 4 3 May 2001 13 - - - - - - Opportunistic Encryption - - -Ahem: Except in the special case of a subnet masked on a -byte boundary (in which case RFC 1035's convention of an -incomplete in-addr.arpa name could be used), subnet lookup -would need extensions to the reverse-map name space, perhaps -along the lines of that commonly done for RFC 2317 delega- -tion. IPv6 already has suitable name syntax, as in RFC -2874, but has no specific provisions for subnet entries in -its reverse maps. Fixing all this is is not conceptually -difficult, but is logically independent of opportunistic -encryption, and will be proposed separately. - -A less-troublesome problem is that the Initiator, in step 10 -of 2.2, must know exactly what subnet is present on the -Responder's end so he can propose a tunnel to it. This -information could be included in the TXT record of the Des- -tination (it would have to be verified with a subnet lookup, -but that could be done in parallel with other operations). -The Initiator presumably can be configured to know what sub- -net(s) are present on its end. - -2.7. Option Settings - -IPsec and IKE have far too many useless options, and a few -useful ones. IKE negotiation is quite simplistic, and can- -not handle even simple discrepancies between the two SGs. -So it is necessary to be quite specific about what should be -done and what should be proposed, to guarantee interoper- -ability without prearrangement or other negotiation proto- -cols. - -Rationale: The prohibition of other negotiations is simply -because there is no time. The setup algorithm (section 2.2) -is lengthy already. - -[Open question: should opportunistic IKE use a different -port than normal IKE?] - -Somewhat arbitrarily and tentatively, opportunistic SGs must -support Main Mode, Oakley group 5 for D-H, 3DES encryption -and MD5 authentication for both ISAKMP and IPsec SAs, -RSA/MD5 digital-signature authentication with keys between -2048 and 8192 bits, and ESP doing both encryption and -authentication. They must do key PFS in Quick Mode, but not -identity PFS. They may support IPComp, preferably using -Deflate, but must not insist on it. They may support AES as -an alternative to 3DES, but must not insist on it. - -Rationale: Identity PFS essentially requires establishing a -complete new keying channel for each new tunnel, but key PFS -just does a new Diffie-Hellman exchange for each rekeying, -which is relatively cheap. - -Keying channels must remain in existence at least as long as -any tunnel created with them remains (they are not costly, - - - -Draft 4 3 May 2001 14 - - - - - - Opportunistic Encryption - - -and keeping the management path up and available simplifies -various issues). See section 3.1 for related issues. Given -the use of key PFS, frequent rekeying does not seem critical -here. In the absence of strong reason to do otherwise, the -Initiator should propose rekeying at 8hr-or-1MB. The -Responder must accept any proposal which specifies a rekey- -ing time between 1hr and 24hr inclusive and a rekeying vol- -ume between 100KB and 10MB inclusive. - -Given the short expected useful life of most tunnels (see -section 3.1), very few of them will survive long enough to -be rekeyed. In the absence of strong reason to do other- -wise, the Initiator should propose rekeying at 1hr-or-100MB. -The Responder must accept any proposal which specifies a -rekeying time between 10min and 8hr inclusive and a rekeying -volume between 1MB and 1000MB inclusive. - -It is highly desirable to add some random jitter to the -times of actual rekeying attempts, to break up ``convoys'' -of rekeying events; this and certain other aspects of robust -rekeying practice will be the subject of a separate design -proposal. - -Rationale: The numbers used here for rekeying intervals are -chosen quite arbitrarily and should be re-assessed after -some implementation experience is gathered. - -3. Renewal and Teardown - -3.1. Aging - -When to tear tunnels down is a bit problematic, but if we're -setting up a potentially unbounded number of them, we have -to tear them down somehow sometime. - -Set a short initial tentative lifespan, say 1min, since most -net flows in fact last only a few seconds. When that -expires, look to see if the tunnel is still in use (defini- -tion: has had traffic, in either direction, in the last half -of the tentative lifespan). If so, assign it a somewhat -longer tentative lifespan, say 20min, after which, look -again. If not, close it down. (This tentative lifespan is -independent of rekeying; it is just the time when the tun- -nel's future is next considered. This should happen reason- -ably frequently, unlike rekeying, which is costly and -shouldn't be too frequent.) Multi-step backoff algorithms -are not worth the trouble; looking every 20min doesn't seem -onerous. - -If the security gateway and the client host are one and the -same, tunnel teardown decisions might wish to pay attention -to TCP connection status, as reported by the local TCP -layer. A still-open TCP connection is almost a guarantee -that more traffic is coming, while the demise of the only - - - -Draft 4 3 May 2001 15 - - - - - - Opportunistic Encryption - - -TCP connection through a tunnel is a strong hint that none -is. If the SG and the client host are separate machines, -though, tracking TCP connection status requires packet -snooping, which is complicated and probably not worthwhile. - -IKE keying channels likewise are torn down when it appears -the need has passed. They always linger longer than the -last tunnel they administer, in case they are needed again; -the cost of retaining them is low. Other than that, unless -the number of keying channels on the SG gets large, the SG -should simply retain all of them until rekeying time, since -rekeying is the only costly event. When about to rekey a -keying channel which has no current tunnels, note when the -last actual keying-channel traffic occurred, and close the -keying channel down if it wasn't in the last, say, 30min. -When rekeying a keying channel (or perhaps shortly before -rekeying is expected), Initiator and Responder should re- -fetch the public keys used for SG authentication, against -the possibility that they have changed or disappeared. - -See section 2.7 for discussion of rekeying intervals. - -Given the low user impact of tearing down and rebuilding a -connection (a tunnel or a keying channel), rekeying attempts -should not be too persistent: one can always just rebuild -when needed, so heroic efforts to preserve an existing con- -nection are unnecessary. Say, try every 10s for a minute -and every minute for 5min, and then give up and declare the -connection (and all other connections to that IKE peer) -dead. - -Rationale: In future, more sophisticated, versions of this -protocol, examining the initial packet might permit a more -intelligent guess at the tunnel's useful life. HTTP connec- -tions in particular are notoriously bursty and repetitive. - -Rationale: Note that rekeying a keying connection basically -consists of building a new keying connection from scratch, -using IKE Phase 1, and abandoning the old one. - -3.2. Teardown and Cleanup - -Teardown should always be coordinated with the other end. -This means interpreting and sending Delete notifications. - -On receiving a Delete for the outbound SAs of a tunnel (or -some subset of them), tear down the inbound ones too, and -notify the other end with a Delete. Tunnels need to be con- -sidered as bidirectional entities, even though the low-level -protocols don't think of them that way. - -When the deletion is initiated locally, rather than as a -response to a received Delete, send a Delete for (all) the -inbound SAs of a tunnel. If no responding Delete is - - - -Draft 4 3 May 2001 16 - - - - - - Opportunistic Encryption - - -received for the outbound SAs, try re-sending the original -Delete. Three tries spaced 10s apart seems a reasonable -level of effort. (Indefinite persistence is not necessary; -whether the other end isn't cooperating because it doesn't -feel like it, or because it is down/disconnected/etc., the -problem will eventually be cleared up by other means.) - -After rekeying, transmission should switch to using the new -SAs (ISAKMP or IPsec) immediately, and the old leftover SAs -should be cleared out promptly (and Deletes sent) rather -than waiting for them to expire. This reduces clutter and -minimizes confusion. - -Since there is only one keying channel per remote IP -address, the question of whether a Delete notification has -appeared on a ``suitable'' keying channel does not arise. - -Rationale: The pairing of Delete notifications effectively -constitutes an acknowledged Delete, which is highly desir- -able. - -3.3. Outages and Reboots - -Tunnels sometimes go down because the other end crashes, or -disconnects, or has a network link break, and there is no -notice of this in the general case. (Even in the event of a -crash and successful reboot, other SGs don't hear about it -unless the rebooted SG has specific reason to talk to them -immediately.) Over-quick response to temporary network out- -ages is undesirable... but note that a tunnel can be torn -down and then re-established without any user-visible effect -except a pause in traffic, whereas if one end does reboot, -the other end can't get packets to it at all (except via -IKE) until the situation is noticed. So a bias toward quick -response is appropriate, even at the cost of occasional -false alarms. - -Heartbeat mechanisms are somewhat unsatisfactory for this. -Unless they are very frequent, which causes other problems, -they do not detect the problem promptly. - -Ahem: What is really wanted is authenticated ICMP. This -might be a case where public-key encryption/authentication -of network packets is the right thing to do, despite the -expense. - -In the absence of that, a two-part approach seems warranted. - -First, when an SG receives an IPsec packet that is addressed -to it, and otherwise appears healthy, but specifies an -unknown SA and is from a host that the receiver currently -has no keying channel to, the receiver must attempt to -inform the sender via an IKE Initial-Contact notification -(necessarily sent in plaintext, since there is no suitable - - - -Draft 4 3 May 2001 17 - - - - - - Opportunistic Encryption - - -keying channel). This must be severely rate-limited on both -ends; one notification per SG pair per minute seems ample. - -Second, there is an obvious difficulty with this: the Ini- -tial-Contact notification is unauthenticated and cannot be -trusted. So it must be taken as a hint only: there must be -a way to confirm it. - -What is needed here is something that's desirable for debug- -ging and testing anyway: an IKE-level ping mechanism. Ping- -ing direct at the IP level instead will not tell us about a -crash/reboot event. Sending pings through tunnels has vari- -ous complications (they should stop at the far mouth of the -tunnel instead of going on to a subnet; they should not -count against idle timers; etc.). What is needed is a con- -tinuity check on a keying channel. (This could also be used -as a heartbeat, should that seem useful.) - -IKE Ping delivery need not be reliable, since the whole -point of a ping is simply to provoke an acknowledgement. -They should preferably be authenticated, but it is not clear -that this is absolutely necessary, although if they are not -they need encryption plus a timestamp or a nonce, to foil -replay mischief. How they are implemented is a secondary -issue, and a separate design proposal will be prepared. - -Ahem: Some existing implementations are already using (pri- -vate) notify value 30000 (``LIKE_HELLO'') as ping and (pri- -vate) notify value 30002 (``SHUT_UP'') as ping reply. - -If an IKE Ping gets no response, try some (say 8) IP pings, -spaced a few seconds apart, to check IP connectivity; if one -comes back, try another IKE Ping; if that gets no response, -the other end probably has rebooted, or otherwise been re- -initialized, and its tunnels and keying channel(s) should be -torn down. - -In a similar vein, giving limited rekeying persistence, a -short network outage could take some tunnels down without -disrupting others. On receiving a packet for an unknown SA -from a host that a keying channel is currently open to, send -that host a Invalid-SPI notification for that SA. The other -host can then tear down the half-torn-down tunnel, and nego- -tiate a new tunnel for the traffic it presumably still wants -to send. - -Finally, it would be helpful if SGs made some attempt to -deal intelligently with crashes and reboots. A deliberate -shutdown should include an attempt to notify all other SGs -currently connected by keying channels, using Deletes, that -communication is about to fail. (Again, these will be taken -as teardowns; attempts by the other SGs to negotiate new -tunnels as replacements should be ignored at this point.) -And when possible, SGs should attempt to preserve - - - -Draft 4 3 May 2001 18 - - - - - - Opportunistic Encryption - - -information about currently-connected SGs in non-volatile -storage, so that after a crash, an Initial-Contact can be -sent to previous partners to indicate loss of all previ- -ously-established connections. - -4. Conclusions - -This design appears to achieve the objective of setting up -encryption with strangers. The authentication aspects also -seem adequately addressed if the destination controls its -reverse-map DNS entries and the DNS data itself can be reli- -ably authenticated as having originated from the legitimate -administrators of that subnet/FQDN. The authentication sit- -uation is less satisfactory when DNS is less helpful, but it -is difficult to see what else could be done about it. - -5. References - -[TBW] - -6. Appendix: Separate Design Proposals TBW - -o How can we build a web of trust with DNSSEC? (See sec- - tion 2.3.4.) - -o How can we extend DNS reverse lookups to permit reverse - lookup on a subnet? (Both address and mask must appear - in the name to be looked up.) (See section 2.6.) - -o How can rekeying be done as robustly as possible? (At - least partly, this is just documenting current FreeS/WAN - practice.) (See section 2.7.) - -o How should IKE Pings be implemented? (See section 3.3.) - - - - - - - - - - - - - - - - - - - - - - - -Draft 4 3 May 2001 19 - - diff --git a/doc/opportunism.howto b/doc/opportunism.howto deleted file mode 100644 index 14b5ed5a2..000000000 --- a/doc/opportunism.howto +++ /dev/null @@ -1,415 +0,0 @@ -FreeS/WAN Opportunism HowTo -=========================== - -RCSID $Id: opportunism.howto,v 1.1 2004/03/15 20:35:21 as Exp $ - -D. Hugh Redelmeier - - -FreeS/WAN, the LINUX IPSEC implementation, is intended to allow -systems to connect through secure tunnels with or without prearrangement. -We use the term "Opportunism" to describe tunnels set up without -prearrangement. This HowTo will show you how to set your system up -for Opportunism. - -You are expected to already have built and used FreeS/WAN. Much more -information about FreeS/WAN is provided at http://www.freeswan.org. -This document is only intended to describe the support for -opportunism. The features described here are available in FreeS/WAN -version 1.91 or later (there were important bugs up until 1.95). - -For a more complete description of the design of Opportunism, see our -paper "Opportunistic Encryption" (available as opportunism.spec in -the same directory as this document). - - -Steps -===== - -- Understand what you are attempting. Security requires care. - Problems are hard to untangle. Be sure to read the last section - "Important Limitations". - -- Install FreeS/WAN (version 1.91 or later). - -- Add appropriate DNS records to your reverse-map domains. - -- Add suitable conns to /etc/ipsec.conf. - -- Try it out: start it, monitor it, fix it. - -- Now you understand the system better, reread "Important Limitations" - -These steps are also an outline of this document. - - -Theory -====== - -FreeS/WAN runs on a machine that we will call a "Security Gateway". -Usually this machine is a gateway to the internet. It may be that the -only machine for which it provides gateway services is itself, but -that is just a special case -- we will still call it a Security -Gateway. - -A FreeS/WAN Security Gateway implements secure tunnels to other -Security Gateways. One problem is to arrange for these tunnels to be -created and used. If opportunism is enabled, a Security Gateway -running FreeS/WAN will intercept the first outbound packet to a -particular destination (IP address), and try to negotiate a security -tunnel suitable for traffic to that destination. - -To make this work going the other way, the Security Gateway must be -willing to negotiate with peers trying to protect traffic initiated -from their side. - -The first novel problem is that our Security Gateway needs to discover -the IP address of the other Security Gateway for the packet that -prompted the negotiation. Oh, and quickly discover if there is none --- that negotiation will be impossible. - -The second novel problem is that our Security Gateway needs to -authenticate the other Security Gateway. This authentication needs to -ensure that the other Security Gateway is who it claims to be AND that -it is authorized to represent the client for which it claims to be the -gateway. - -The roles in a particular negotiation are: - Source----Initiator----...----Responder----Destination - -The Source and Destination are endpoints of the traffic that is to be -protected. The Source is the one that happened to send the first -packet of traffic. Neither needs to be aware of IPSEC or FreeS/WAN. -That is the job of their respective Security Gateways, Initiator and -Responder. The names "Initiator" and "Responder" match those used in -the IPSEC standards for IKE negotiation. Remember that Source and -Initiator could be the same machine; similarly, Destination and -Responder could be the same. All traffic from Source or Destination -must flow through their Security Gateways if it is to be considered -for protection. These roles are fluid -- they can be different for -each negotiation. - -We use the DNS (the Domain Name System) as a distributed database to -publish the required information. - - -DNS Records Required -==================== - -See section 2.3 of "Opportunistic Encryption" for a fuller -explanation. - -Generally, we need to add records to the reverse-map DNS entries for -the client machine and its Security Gateway machine. There are -special cases that are exceptions. - -A Security Gateway that is going to initiate an Opportunistic -negotiation needs to provide a way for the Responding SG to find a -public key for the Initiator to allow authentication. This is -accomplished by putting the public key in a KEY record in the -reverse-map of the Initiator. Conveniently, the KEY record can -be generated by the ipsec_showhostkey(8) command. - - ipsec showhostkey - -Here is an example of the output, with many characters of the key -itself left out: - - ; RSA 2048 bits xy.example.com Sat Apr 15 13:53:22 2000 - xy.example.com. IN KEY 0x4200 4 1 AQOF8tZ2...+buFuFn/ - -=> Copy the output of the command into the zone information for the - reverse-map of the Security Gateway's public interface. - -Each client that is to be protected by Opportunistic Encryption must -include a special TXT record in its reverse-map. The -ipsec_showhostkey(8) command can create this too. Remember: this -command must be run on the Security Gateway where the ipsec.secrets -file resides. You must tell the command what IP address to put in the -TXT record. The IP address is that of the Security Gateway. - - ipsec showhostkey --txt 10.11.12.13 - -This command might produce the output: - - ; RSA 2048 bits xy.example.com Sat Apr 15 13:53:22 2000 - IN TXT "X-IPsec-Server(10)=10.11.12.13 AQOF8tZ2...+buFuFn/" - -- The quotes matter: this is a single string, as far as DNS is - concerned. - -- The X-IPsec-Server is a prefix that signifies that the TXT record - contains Opportunism configuration information. - -- The (10) specifies a precedence for this record. This is similar - to MX record preferences. Lower numbers have stronger preference. - -- 10.11.12.13 specifies the IP address of the Security Gateway for - this machine. - -- AQOF8tZ2...+buFuFn/ is the (shortened) encoding of the RSA Public - key of the Security Gateway. - -=> Added this output to the zone information for the reverse-map for - each client machine. This gets a bit dull and repetitive. - -Unfortunately, not every administrator has control over the contents -of the reverse-map. The only case where we can work around this is -where the Initiator has no suitable reverse map. In this case, the -Source's TXT record gives @FQDN ("Fully Qualified Domain Name") in -place of its Security Gateway's IP address. This FQDN must match the -ID-payload used by the Initiator. Furthermore, a forward lookup for a -KEY record on the FQDN must yield the Initiator's public key. - -If the Source's IP address is the same as the Initiator's IP address, -the Responder will assume that the Initiator is authorized to talk for -the Source (itself!). In this case, the Responder won't try to fetch -the Source's TXT record from the reverse map for the Source's IP -address. - -These two features can be combined. If the Source and the Initiator -are the same (i.e. the Security Gateway is protecting itself), and the -Initiator uses a @FQDN ID (leftid=@example.com), then the -administrator of that machine need only have installed a KEY record in -the FQDN domain -- he need not control any reverse map. - -Obscure fact: the forward lookup is only done by a Responder, and then -only when the Initiator's ID payload specifies the FQDN. There is no -provision for a Responder with no control over its reverse-map. - -Beware: DNS changes sometimes take a long time to propagate. - - -Configuring FreeS/WAN -===================== - -To enable opportunism, you must include a suitable conn in -/etc/ipsec.conf and you must enable it. - -A suitable conn looks roughly like an ordinary conn. It more closely -resembles a Road Warrior conn (a Road Warrior conn is one that has a -wildcard %any specified as the other Security Gateway). But in the -Opportunistic case, both the other Security Gateway AND its client are -unknown ahead of time. - -conn client-to-anyone # for our client subnet - leftsubnet=10.3.2.1.0/24 # any single client in our subnet - also=sg-to-anyone # rest is same as for SG - -conn sg-to-anyone # for our Security Gateway - left=%defaultroute # our SG (defaults leftnexthop too) - right=%opportunistic - authby=rsasig # almost always the right choice - keyingtries=2 # don't be persistent -- peer might disappear - auto=route # enable at ipsec startup - -(%defaultroute only works if you have specified -interfaces=%defaultroute. Since this isn't the topic of the howto, -you will have to look at the other documentation to find out how to -handle other cases.) - -You can have any number of opportunistic conns, but generally it only -makes sense to have one for each client subnet and one for the -Security Gateway itself. - -Currently only one interface may be used for opportunism: Pluto knows -nothing about routing, so would be unable to choose amongst several. -Almost certainly our side's nexthop must be predetermined -(%defaultroute will do that). - -Note: the routing done for outbound Opportunism will catch any packets -not covered by a more specific route. This is what you want for -packets that are also covered by an eroute. But packets caught by the -route and not an eroute will be subject to the no-eroute policy of -KLIPS, which defaults to %drop. Remember that routing ignores the -packet's source address, but erouting pays attention to it. So if -Opportunism is enabled, it is best to provide for it covering all IP -addresses behind or on the Security Gateway. - -To enable these conns for inbound opportunistic negotiation, they must be ---added. auto=add would accomplish this at ipsec startup, but if you cannot -wait: - ipsec auto --add sg-to-anyone - ipsec auto --add client-to-anyone - -To enable these conns for outbound opportunistic negotiation, they must -be both --added and --routed. Outbound packets will then be trapped -and will trigger negotiation. auto=route would cause this to happen -at startup, but if you wish to do this at another time: - ipsec auto --add sg-to-anyone - ipsec auto --add client-to-anyone - ipsec auto --route sg-to-anyone - ipsec auto --route client-to-anyone - - -Getting DNS Through -=================== - -There is a serious chicken-and-egg problem. Outbound Opportunism blocks -communication with an IP address until Pluto discovers whether that IP -address can have an IPSEC connection negotiated. This discovery takes -DNS queries. These DNS queries might involve communicating with -arbitrary IP addresses. Thus we require DNS queries to succeed before -any communication succeeds, including those same DNS queries! The way -out of this conundrum is to exempt at least some DNS query IP traffic -from Opportunism. - -There are several possible solutions, all of which have advantages and -disadvantages. - -1. If you use a single machine, outside your Security Gateway, as DNS -server, you can build a clear path (or even an IPSEC tunnel, but not -opportunistically) directly to that machine. - -- you could use a type=passthrough conn to provide a clear path - between your machine and the DNS machine. - -- better still, you could explicitly create an IPSEC connection to - your DNS server. Just be sure that Pluto does not need to access - DNS to find the IP addresses or RSA public keys for that connection! - -- you could install an explicit route to the DNS machine through - your public interface (not ipsecN). This will bypass KLIPS - processing. You might have to adjust your firewall. For example: - - route add host -net ns.example.com gw gw.example.com dev eth1 - -2. Generally, it is better to run DNS on your Security Gateway. This -leads to a need for non-opportunistic paths to an arbitrary number of -DNS servers in the internet. One way to accomplish this is to NOT -have outbound opportunism cover the SG itself, but only the subnet -behind it. In other words, leave out the - ipsec auto --route sg-to-anyone -You must also add a type=passthrough eroute specifically for -sg-to-anyone (without this, the traffic will be handled by the KLIPS -no-eroute policy). - -3. It is actually possible to use a single machine inside your client -subnet as a DNS server. The techniques listed in 1 could be used to -let it communicate with other DNS servers without interference. This -might have advantages over 1 if the DNS machine *only* did DNS. -Another technique (not often possible or reasonable) is to give this -machine another route to the internet, one that avoids the SG. - -4. DNS queries will eventually time out and then Pluto will give up -and establish %pass eroutes. So communications should start flowing. - -We would like to have better solutions. Perhaps we will in the -future. Suggestions are welcome. - - -Figuring out what is going on -============================= - -Since Opportunism lets your SG operate with less supervision, you may -be puzzled by what it is up to. The usual tools exist, but their use -is more important. To look at what Pluto is doing, use: - ipsec auto --status -To look at what KLIPS is doing, use - ipsec look - -To just see the kernel's eroute table, look at the "file" -/proc/net/ipsec_eroute. It contains a description of all the eroutes -in the kernel. Here is an example: - -10 10.2.1.0/24 -> 0.0.0.0/0 => %trap -259 10.2.1.115/32 -> 10.19.75.161/32 => tun0x1002@10.19.75.145 -71 10.44.73.97/32 -> 0.0.0.0/0 => %trap -4119 10.44.73.97/32 -> 10.114.121.41/32 => %pass - -You read each line as: a packet from within the first subnet, destined -for the second subnet, will be processed by the Security Association -Identity (SAID) specified last. The first column is the number of -(outbound) packets processed by this eroute. - -For shunt eroutes, the SAID is printed as just the type of shunt: -%pass pass the packet through with no processing -%drop discard the packet -%reject discard the packet and notify sender -%hold keep the last packet; discard others -%trap cause any trapped packet to generate a PF_KEY ACQUIRE - to request negotiation; install a corresponding %hold - shunt and attach this packet to the %hold - -For other eroutes, the SAID is printed as a triple: protocol (three -letters), SPI (32-bit number in hex), and destination IP address. -Protocols include: - -tun IP in IP encapsulation (used for most tunnels) -esp ESP encapsulation -- part of an IPSEC SA group -ah AH packet authentication -- part of an IPSEC SA group - -So, looking at our sample eroutes: - -10 10.2.1.0/24 -> 0.0.0.0/0 => %trap - - This is a TRAP (int0x104) shunt eroute. It was installed by - Pluto so that it can catch all traffic from its client subnet - to the world at large. Ten outbound packets have been trapped. - -259 10.2.1.115/32 -> 10.19.75.161/32 => tun0x1002@10.19.75.145 - - This is a tunnel eroute: packets from 10.2.1.115 (within - our client subnet) going to 10.19.75.161 will be encrypted - and sent to the peer SG 10.19.75.145. This was the product - of an Opportunistic negotiation (a hint is that each client - subnet has only one member). 259 packets have been sent - through this tunnel. - -71 10.44.73.97/32 -> 0.0.0.0/0 => %trap - - This is another TRAP shunt eroute. It is to catch traffic - from the Security Gateway to the world. It has caught - 71 outbound packets. - -4119 10.44.73.97/32 -> 10.114.121.41/32 => %pass - - This is a %pass (0x100) shunt eroute. It was installed when an - attempted Opportunistic negotiation failed because the reverse - domain of 10.114.121.41 had no suitable TXT record. 4119 - outbound packets have been passed. - - -Important Limitations -===================== - -Pluto's DNS lookup is synchronous (single-threaded). Not only does -this slow things down, but it turns out that in extreme cases where -there are a lot of ACQUIRE messages from KLIPS at once, some of those -messages can be lost and communications will be blocked by the %hold -eroute that Pluto doesn't know about. Pluto now looks every 2 minutes -for any %holds that it missed. - -DNS lookup is not verified -- we don't use Secure DNS. A spoofed DNS -could compromise Opportunism. - -There are several new opportunities for Denial of Service attacks. -For example, a Bad Guy could spray our system with pings with forged -source addresses. For each unique source address, our system would do -a (synchronous!) DNS lookup. - -Once a %pass eroute is added for a failed negotiation, it will stay -until it has been inactive for about 15 minutes. The only activity -that counts is outbound -- not surprising since a %pass only affects -outbound traffic. - -If a destination's DNS entry specifies the information we need for -negotiation, Pluto will not let communications proceed without -negotiating a Security Tunnel. - -There is currently no way to tear down a tunnel that is no longer in -use. To add insult to injury, when the lifetime is about to be -exceeded, the initiating Pluto will rekey! Restarting will clear -these out. rekey=no doesn't solve this since SA expiry would be -uncoordinated and hence cause packets to be lost. - -If one side of a Security Tunnel restarts, but doesn't initiate -negotiation with its peer, the peer will not be able to communicate -with it until the peer thinks the tunnel needs rekeying due to -lifetime, or the restarted Security Gateway decides to negotiate for -its own reasons. - -It isn't clear what firewall policies make sense with Opportunism. - -If VPN and Opportunism connections coexist, security policies -implemented via a firewall can only distinguish traffic by IP address. diff --git a/doc/opportunism.known-issues b/doc/opportunism.known-issues deleted file mode 100644 index 90752dee3..000000000 --- a/doc/opportunism.known-issues +++ /dev/null @@ -1,287 +0,0 @@ -Known issues with Opportunistic Encryption Claudia Schmeing ------------------------------------------- - - -This is an overview of known issues with OE. - - -This document supplements: - - -FreeS/WAN Quickstart Guide doc/quickstart.html - -Opportunism HOWTO doc/opportunism.howto - -Opportunism spec doc/opportunism.spec - -Internet Draft doc/draft-richardson-ipsec-opportunistic.txt - - - -* Use the most recent Linux FreeS/WAN 2.x release from ftp.xs4all.nl - to try OE. - - -DESIGN LIMITATIONS - - -* Because Opportunistic Encryption relies on DNS: - - to authenticate one FreeS/WAN to another, and - - to prove that we have the right to protect traffic for a given IP, - this authentication/authorization is only as strong as your DNS is - secure. - - Without secure DNS, OE protects against passive snooping only. - Because the public key and gateway information that FreeS/WAN gets from - DNS is not authenticated, a man-in-the-middle attack is still possible. - We hope that as DNSsec is widely adopted, OE with strong authentication - will become more widespread. - - However, our software does not yet distinguish between strongly and weakly - authenticated OE. This information might be useful for defining local - security policy. - - -* Denial of service attacks are possible against OE. If you rely on OE rather - than VPN to connect several offices, a determined attacker could prevent you - from communicating securely. - - -* OE challenges the notion that all IPsec peers are "friends". With OE, - strangers can potentially tunnel IPsec packets _through_ your defenses - against cleartext packets. This may call for a re-visit to firewall policy. - - -* FreeS/WAN only creates OE connections when it traps an outgoing packet. - Since most traffic is two-way, for most traffic, FreeS/WAN 2.x may soon - trap an outgoing packet and create an IPsec connection to - protect both incoming and outgoing traffic. However, if a local - FreeS/WAN box accepts inbound traffic from a remote peer but - generates no outbound traffic in response, the local FreeS/WAN will not - attempt to initiate OE. Of course, the peer may also initiate OE upon - trapping its own outbound traffic. - - -* OE is only as reliable as your DNS is. - - If your DNS service is flaky, you will not be able to reliably establish - OE connections to known OE-capable peers. - - If you ping a peer, but your FreeS/WAN does not find a TXT record signifying - the peer's ability to respond to OE negotiation), FreeS/WAN will not try to - opportunistically initiate, and communication will fallback to clear. - - For more secure and reliable DNS, we recommend that you run DNS - within your security perimeter, either on your security gateway, or - on a machine to which you have a VPN connection. It is also possible - to have your DNS server located elsewhere on your LAN, though this may - cause lag on startup. - - This mailing list message explains how to run a local caching name server: - http://lists.freeswan.org/pipermail/design/2003-January/004205.html - - See also "Getting DNS through" in opportunism.howto - http://lists.freeswan.org/pipermail/design/2002-April/002285.html . - - - -CURRENT ISSUES - -* There are several special issues re: using OE when running FreeS/WAN with - kernel native IPsec, introduced in the 2.6 kernel. Please see - doc/2.6.known-issues. - -* If A and B have an OE connection, but A is rebooted, normally A will try to - re-connect to B and (if it has no DNS-related failures) it will succeed. - But, if A is set up for responder-only OE, you will have a one-way - connection until B notices that its original tunnel has expired. For details - see: - - http://lists.freeswan.org/pipermail/design/2002-May/002582.html - http://lists.freeswan.org/pipermail/design/2002-June/002610.html - - TIP: If an OE connection isn't behaving, you can recreate it with - - ipsec whack --oppohere sourceIPaddress --oppothere targetIPaddress - - -* There is no good clean facility to delete OE connections. - Available are: - - ipsec auto --status to list connections - ipsec whack --deletestate to delete by state#. - - -* You may experience seeming gaps at rekey time. Once you generate traffic, - you will find that the OE connection returns. - - By default, OE connections are not rekeyed; if they were we'd have a - mountain of useless connections. As a consequence, if your OE connection is - idle at rekey time, it will go down until you generate further traffic. - To ensure prompt rekeying, you can run a ping thorough the OE tunnel. - - -* At the moment, you can only run active OE on one physical interface. - - Active means --routed, to trap outbound packets. It is this route - that is a problem. - - Untested theory: you can have multiple active OE conns, for different - source addresses, but they all have to point their traffic out the single - interface. - - When responding: you can only define one OE connection (per host or subnet) - in ipsec.conf, and that conn will apply to one interface. Normally this - will be the public interface which your default route uses; it is, however, - configurable. - - Theoretically, it might make sense to select between multiple OE conns - based on some criterion, such as address ranges. This might be useful for - local OE, or in a complex routing scenario. - - Currently, Pluto expects only one OE connection. If you add another, - Pluto may choose randomly between them, producing unpredictable results. - - -* Building OE conns between nodes on a LAN is not possible. - - This is a side effect of conflicts about ARP entries - in the rt_cache and our "stupid routing tricks". - There is no known workaround at this time. - - "Stupid routing tricks" are an ongoing issue, and should - go away in a future software revision. - - See these explanations: - http://lists.freeswan.org/pipermail/design/2002-April/002285.html - http://lists.freeswan.org/pipermail/design/2002-August/003249.html - - -* FreeS/WAN may not correctly follow a CNAME (Canonical Name) trail resulting - from reverse DNS delegation. - - Solution: Use a recent Bind 9 (we tested with Bind snap-pre9.3) for the - DNS services which the FreeS/WAN box relies on. - - Reason: This Bind correctly implements "implied helper support" for - traditional DNS records, and so can follow a properly constructed CNAME - record trail which ends in a TXT record. Thus, in cases where a reverse - domain has been delegated, FreeS/WAN + Bind 9 can find a TXT record and - create an OE connection. - - For more on the problem, see "OLD ISSUES", below. - - -* To make OE operation smoother, we may need a script that runs and warns - if we have the reverse DNS records, but not the software running. - The reverse records advertise that we can do OE, but when the software is - not running this is false advertising. - - - -OLD ISSUES - -* Coterminal OE doesn't work in practise. This includes OE-in-WAVEsec. - Solved in 2.02. - - Old diagnosis: - - If you have coterminal OE connections (two OE connections which share - one endpoint), you should have use of one of the encrypted links, but it - is not clear which one KLIPS will prefer. In particular, the behaviour - may not be symmetrical. - - Worse yet, it just seems to trip over itself and be generally - unworkable. - - Weird but predictable: - - If you have both a gateway and a host who advertise (via DNS) an - ability to do OE you need to be serious about doing host-based - OE, or you will be stuck in initiator-only mode. If your host - advertises but does not run OE, then when a peer tries to connect to - your host, it will fail to clear. The peer will then not try to encrypt - traffic bound for that host as it travels to the gateway. To remedy - the situation, restart ipsec on the peer (or otherwise flush out - the %pass eroute), and ping the peer from your host to initiate - OE. - - -* One-way connection was created on rekey. Solved in 2.0. - - If one side (A) has a shorter _keylife_ than the other, - and that side also has _rekey=no_, then when the keylife has - expired, it will expect that its peer (B) will make a new conn to replace - the existing one. Unfortunately, B has no idea. - - B continues to send out encrypted packets on the original connection, - while A passes the return packets along in the clear. - - There is a proposed patch for (A) here: - http://lists.freeswan.org/pipermail/design/2002-July/003114.html - - -* Failure to look up own host name is a show stopper. - Solved in 1.98 and 1.98b. - - Solution: new setting %dnsondemand. Usage: - - leftrsasigkey=%dnsondemand # now in sample ipsec.conf - rightrsasigkey=%dnsondemand. - - From man ipsec.conf: - - The value %dnsondemand means the key is to fetched from DNS - at the time it is needed. - - If Linux FreeS/WAN can't get the key for your public interface from - DNS, it will not keep trying, and you will not be able to do OE. - - The error message is: - - May 14 09:40:24 road Pluto[21210]: failure to fetch key for 193.110.157.18 - from DNS: failure querying DNS for KEY of 18.157.110.193.in-addr.arpa.: - Host name lookup failure - - Workaround: 1 or 2 - 1. Supply a key in the conn. leftrsasigkey=0s... - 2. Fix the KEY lookup failure and try again. - - -* Assertion failure at OE rekey time. Fixed in 2.0pre0. Patch for 1.98b posted - at http://lists.freeswan.org/pipermail/design/2002-August/003347.html - - -* 1.91 to 1.94 have serious problems with %trap and %hold bugs. These bugs, - introduced while coding the support structure for OE, affect both OE and VPN - connections. - - -* OE may not work with reverse delegation (CNAMEs). This problem was once - capable of being a show stopper. - - When relying on Bind versions before 9 for local DNS services, FreeS/WAN - could not follow a well constructed CNAME trail that ended in a TXT or KEY - record. Although OE required both record types, in practise we noticed the - problem with the more common TXT lookups, rather than the rarer KEY lookups. - Bind 9 largely solves the problem, by correctly seeking TXT records in - delegated reverse domains. In addition, OE between two FreeS/WAN 2.02 or - later boxes no longer relies on KEY records. - - Old symptoms: - - When a DNS server queried by Linux FreeS/WAN follows a CNAME, - it seems to forget what record type it is looking for, and it - returns a PTR, despite the fact that another record type was requested. - - Workaround: - - Send your provider KEY and TXT records for direct insertion into the - reverse ZONE files, rather than asking your provider to delegate authority - using CNAME. - - People who own IP blocks, rather than leasing them, may not - experience this problem. If you were assigned IPs more than - five years ago, you may own your IPs. - - diff --git a/doc/opportunism.nr b/doc/opportunism.nr deleted file mode 100644 index c5cae757a..000000000 --- a/doc/opportunism.nr +++ /dev/null @@ -1,1115 +0,0 @@ -.DA "3 May 2001" -.ds LH " -.ds CH "Opportunistic Encryption -.ds RH " -.ds LF "Draft 4+ -.ds CF "\\*(DY -.ds RF % -.de P -.LP -.. -.de R -.LP -\fBRationale:\fR -.. -.de A -.LP -\fBAhem:\fR -.. -.TL -Opportunistic Encryption -.AU -Henry Spencer -D. Hugh Redelmeier -.AI -henry@spsystems.net -hugh@mimosa.com -Linux FreeS/WAN Project -.AB no -xxx cases where reverses not controlled, all possibilities. -xxx DHR suggests okay if gateway doesn't control reverse but destination does. -xxx level of patience where Responder just doesn't answer the phone. -xxx IKE finger to get basic keying info, to be confirmed via DNSSEC? -xxx packets from some OE connections might get special status, -if the other end is definitely someone we trust. -Opportunistic encryption permits secure (encrypted, authenticated) -communication via IPsec without connection-by-connection prearrangement, -either explicitly between hosts (when the hosts are capable of it) or -transparently via packet-intercepting security gateways. -It uses DNS records (authenticated with DNSSEC) to provide -the necessary information for gateway discovery and gateway authentication, -and constrains negotiation enough to guarantee success. -.sp -Substantive changes since draft 3: -write off inverse queries as a lost cause; -use Invalid-SPI rather than Delete as notification of unknown SA; -minor wording improvements and clarifications. -This document takes over from the older ``Implementing Opportunistic -Encryption'' document. -.AE -.NH 1 -Introduction -.P -A major goal of the FreeS/WAN project is opportunistic encryption: -a (security) gateway intercepts an outgoing packet aimed at a -remote host, and quickly attempts to negotiate an IPsec tunnel to that -host's security gateway. -If the attempt succeeds, traffic can then be secure, -transparently (without changes to the host software). -If the attempt fails, -the packet (or a retry thereof) passes through in clear or is dropped, -depending on local policy. -Prearranged tunnels bypass the packet interception etc., so static VPNs -can coexist with opportunistic encryption. -.P -This generalizes trivially to the end-to-end case: -host and security gateway simply are one and the same. -Some optimizations are possible in that case, -but the basic scheme need not change. -.P -The objectives for security systems need to be explicitly stated. -Opportunistic encryption is meant to achieve secure communication, -without prearrangement of the individual connection -(although some prearrangement on a per-host basis is required), -between any two hosts which implement the protocol -(and, if they act as security gateways, -between hosts behind them). -Here ``secure'' means strong encryption and authentication of packets, -with authentication of participants\(emto prevent man-in-the-middle -and impersonation attacks\(emdependent on several factors. -The biggest factor is the authentication of DNS records, -via DNSSEC or equivalent means. -A lesser factor is which exact variant -of the setup procedure (see section 2.2) is used, -because there is a tradeoff between strong authentication of the other end -and ability -to negotiate opportunistic encryption with hosts which have limited -or no control of their reverse-map DNS records: -without reverse-map information, -we can verify that the host has the right to use a particular FQDN -(Fully Qualified Domain Name), -but not whether that FQDN is authorized to use that IP address. -Local policy must decide whether authentication -or connectivity has higher priority. -.P -Apart from careful attention to detail in various areas, -there are three crucial design problems for opportunistic encryption. -It needs a way to quickly identify the remote host's security gateway. -It needs a way to quickly obtain an authentication key for the -security gateway. -And the numerous options which can be specified with IKE -must be constrained sufficiently that two independent implementations are -guaranteed to reach agreement, -without any explicit prearrangement or preliminary negotiation. -The first two problems are solved using DNS, -with DNSSEC ensuring that the data obtained is reliable; -the third is solved by specifying a minimum standard which must be supported. -.P -A note on philosophy: -we have deliberately avoided providing six different -ways to do each job, in favor of specifying one good one. -Choices are -provided only when they appear to be necessary, -or at least important. -.P -A note on terminology: -to avoid constant circumlocutions, -an ISAKMP/IKE SA, possibly recreated occasionally by rekeying, -will be referred to as a ``keying channel'', -and a set of IPsec SAs providing bidirectional communication between -two IPsec hosts, -possibly recreated occasionally by rekeying, -will be referred to as a ``tunnel'' -(it could conceivably use transport mode in the host-to-host case, -but we advocate using tunnel mode even there). -The word ``connection'' is here used in a more generic sense. -The word ``lifetime'' will be avoided in favor of ``rekeying interval'', -since many of the connections will have useful lives far shorter -than any reasonable rekeying interval, -and hence the two concepts must be separated. -.P -A note on document structure: -Discussions of \fIwhy\fR things were done a particular way, -or not done a particular way, -are broken out in paragraphs headed ``Rationale:'' -(to preserve the flow of the text, many such paragraphs are deferred -to the ends of sections). -Paragraphs headed ``Ahem:'' are discussions of where the problem is being -made significantly harder by problems elsewhere, -and how that might be corrected. -Some meta-comments are enclosed in []. -.R -The motive is to get the Internet encrypted. -That requires encryption without connection-by-connection prearrangement: -a system must be able to -reliably negotiate an encrypted, authenticated -connection with a total stranger. -While end-to-end encryption is preferable, -doing opportunistic encryption in security gateways -gives enormous leverage for quick deployment of this technology, -in a world where end-host software is often primitive, rigid, and outdated. -.R -Speed is of the essence in tunnel setup: -a connection-establishment delay longer than about 10 seconds -begins to cause problems for users and applications. -Thus the emphasis on rapidity in gateway discovery and key fetching. -.A -Host-to-host opportunistic encryption -would be utterly trivial if a fast public-key -encryption/signature -algorithm was available. -You would do a reverse lookup on the destination address to obtain a -public key for that address, -and simply encrypt all packets going to it with that key, -signing them with your own private key. -Alas, this is impractical with current CPU speeds and current algorithms -(although as noted later, it might be of some use for limited purposes). -Nevertheless, it is a useful model. -.NH 1 -Connection Setup -.P -For purposes of discussion, the network is taken to look like this: -.DS -Source----Initiator----...----Responder----Destination -.DE -The intercepted packet comes from the Source, -bound for the Destination, -and is intercepted at the Initiator. -The Initiator communicates over the insecure Internet to the Responder. -The Source and the Initiator might be the same host, -or the Source might be an end-user host and the Initiator a -security gateway (SG). -Likewise for the Responder and the Destination. -.P -Given an intercepted packet, -whose useful information (for our purposes) -is essentially only the Destination's IP address, -the Initiator -must quickly determine the Responder (the Destination's SG) and -fetch everything needed to authenticate it. -The Responder must do likewise for the Initiator. -Both must eventually also confirm that the other is authorized to act -on behalf of the client host behind it (if any). -.P -An important subtlety here is that if the alternative to an IPsec tunnel -is plaintext transmission, negative results must be obtained quickly. -That is, -the decision that \fIno\fR tunnel can be established must also be made rapidly. -.NH 2 -Packet Interception -.P -Interception of outgoing packets is relatively straightforward -in principle. -It is preferable to put the intercepted packet on hold rather than -dropping it, since higher-level retries are not necessarily well-timed. -There is a problem of hosts and applications retrying during negotiations. -ARP implementations, which face the same problem, -use the approach of keeping the \fImost recent\fR -packet for an as-yet-unresolved address, -and throwing away older ones. -(Incrementing of request numbers etc. means that replies to older ones may no -longer be accepted.) -.P -Is it worth intercepting \fIincoming\fR packets, from the outside world, and -attempting tunnel setup based on them? -No, unless and until a way can be devised to initiate opportunistic encryption -to a non-opportunistic responder, -because -if the other end has not initiated tunnel setup itself, it will not be -prepared to do so at our request. -.R -Note, however, that most incoming packets will promptly be followed by -an outgoing packet in response! -Conceivably it might be useful to start early stages of negotiation, -at least as far as looking up information, -in response to an incoming packet. -.R -If a plaintext incoming packet indicates that the other -end is not prepared to do opportunistic encryption, -it might seem that this fact should be noted, to -avoid consuming resources and delaying -traffic in an attempt at opportunistic setup which is doomed to fail. -However, this would be a major security hole, -since the plaintext packet is not authenticated; -see section 2.5. -.NH 2 -Algorithm -.P -For clarity, -the following defers most discussion of error handling to the end. -.nr x \w'Step 3A.'u+1n -.de S -.IP "Step \\$1." \nxu -.. -.S 1 -Initiator does a DNS reverse lookup on the Destination address, -asking not for the usual PTR records, -but for TXT records. -Meanwhile, Initiator also sends a ping to the Destination, -to cause any other dynamic setup actions to start happening. -(Ping replies are disregarded; -the host might not be reachable with plaintext pings.) -.S 2A -If at least one suitable TXT record (see section 2.3) comes back, -each contains a potential Responder's IP address -and that Responder's public key (or where to find it). -Initiator picks one TXT record, based on priority (see 2.3), -thus picking a Responder. -If there was no public key in the TXT record, -the Initiator also starts a DNS lookup (as specified by the TXT record) -to get KEY records. -.S 2B -If no suitable TXT record is available, -and policy permits, -Initiator designates the Destination itself as the Responder -(see section 2.4). -If policy does not permit, -or the Destination is unresponsive to the negotiation, -then opportunistic encryption is not possible, -and Initiator gives up (see section 2.5). -.S 3 -If there already is a keying channel to the Responder's IP address, -the Initiator uses the existing keying channel; -skip to step 10. -Otherwise, the Initiator starts an IKE Phase 1 negotiation -(see section 2.7 for details) -with the Responder. -The address family of the Responder's IP address dictates whether -the keying channel and the outside of the tunnel should be IPv4 or IPv6. -.S 4 -Responder gets the first IKE message, -and responds. -It also starts a DNS reverse lookup on the Initiator's IP address, -for KEY records, on speculation. -.S 5 -Initiator gets Responder's reply, -and sends first message of IKE's D-H exchange (see 2.4). -.S 6 -Responder gets Initiator's D-H message, -and responds with a matching one. -.S 7 -Initiator gets Responder's D-H message; -encryption is now established, authentication remains to be done. -Initiator sends IKE authentication message, -with an FQDN identity if a reverse lookup on its address will not yield a -suitable KEY record. -(Note, an FQDN need not -actually correspond to a host\(eme.g., the DNS data for it need not -include an A record.) -.S 8 -Responder gets Initiator's authentication message. -If there is no identity included, -Responder waits for step 4's speculative DNS lookup to finish; -it should yield a suitable KEY record (see 2.3). -If there is an FQDN identity, -responder discards any data obtained from step 4's DNS lookup; -does a forward lookup on the FQDN, for a KEY record; -waits for that lookup to return; -it should yield a suitable KEY record. -Either way, Responder uses the KEY data to verify the message's hash. -Responder replies with an authentication message, -with an FQDN identity if a reverse lookup on its address will not yield a -suitable KEY record. -.S 9A -(If step 2A was used.) -The Initiator gets the Responder's authentication message. -Step 2A has provided a key (from the TXT record or via DNS lookup). -Verify message's hash. -Encrypted and authenticated keying channel established, -man-in-middle attack precluded. -.S 9B -(If step 2B was used.) -The Initiator gets the Responder's authentication message, -which must contain an FQDN identity (if the Responder can't put a TXT in his -reverse map he presumably can't do a KEY either). -Do forward lookup on the FQDN, -get suitable KEY record, verify hash. -Encrypted keying channel established, -man-in-middle attack precluded, -but authentication weak (see 2.4). -.S 10 -Initiator initiates IKE Phase 2 negotiation (see 2.7) to establish tunnel, -specifying Source and Destination identities as IP addresses (see 2.6). -The address family of those addresses also determines whether the inside -of the tunnel should be IPv4 or IPv6. -.S 11 -Responder gets first Phase 2 message. -Now the Responder finally knows what's going on! -Unless the specified Source is identical to the Initiator, -Responder initiates DNS reverse lookup on Source IP address, -for TXT records; -waits for result; -gets suitable TXT record(s) (see 2.3), -which should contain either the Initiator's IP address -or an FQDN identity identical to that supplied by the Initiator in step 7. -This verifies that the Initiator is authorized -to act as SG for the Source. -Responder replies with second Phase 2 message, -selecting acceptable details (see 2.7), -and establishes tunnel. -.S 12 -Initiator gets second Phase 2 message, -establishes tunnel (if he didn't already), -and releases the intercepted packet into it, finally. -.S 13 -Communication proceeds. -See section 3 for what happens later. -.P -As additional information becomes available, -notably in steps 1, 2, 4, 8, 9, 11, and 12, -there is always a possibility that local policy -(e.g., access limitations) might prevent further progress. -Whenever possible, -at least attempt to inform the other end of this. -.P -At any time, there is a possibility of the negotiation failing due to -unexpected responses, e.g. the Responder not responding at all -or rejecting all Initiator's proposals. -If multiple SGs were found as possible Responders, -the Initiator should try at least one more before giving up. -The number tried should be influenced by what the alternative is: -if the traffic will otherwise be discarded, trying the full list is -probably appropriate, -while if the alternative is plaintext transmission, -it might be based on how long the tries are taking. -The Initiator should try as many as it reasonably can, -ideally all of them. -.P -There is a sticky problem with timeouts. -If the Responder is down -or otherwise inaccessible, in the worst case we won't hear about this -except by not getting responses. -Some other, more pathological or even -evil, failure cases can have the same result. -The problem is that in the -case where plaintext is permitted, we want to decide whether a tunnel is -possible quickly. -There is no good solution to this, alas; -we just have to take the time and do it right. -(Passing plaintext meanwhile -looks attractive at first glance... but exposing -the first few seconds of a connection is often almost as bad as exposing -the whole thing. -Worse, if the user checks the status of the connection, -after that brief window it looks secure!) -.P -The flip side of waiting for a timeout is that all other forms of -feedback, e.g. ``host not reachable'', -arguably should be \fIignored\fR, -because in the absence of authenticated ICMP, -you cannot trust them! -.R -An alternative, sometimes suggested, to the use of explicit DNS records -for SG discovery is to directly attempt IKE negotiation with the -destination host, -and assume that any relevant SG will be on the packet path, -will intercept the IKE packets, -and will impersonate the destination host for the IKE negotiation. -This is superficially attractive but is a very bad idea. -It assumes that routing is stable throughout negotiation, -that the SG is on the plaintext-packets path, -and that the destination host is routable -(yes, it is possible to have (private) DNS data for an unroutable host). -Playing extra games in the plaintext-packet path hurts performance and -can be expected to be unpopular. -Various difficulties ensue when there are multiple SGs along the path -(there is already bad experience with this, in RSVP), -and the presence of even one can make it impossible -to do IKE direct to the host when that is what's wanted. -Worst of all, such impersonation breaks the IP network model badly, -making problems difficult to diagnose and impossible to work around -(and there is already bad experience with this, in areas like web caching). -.R -(Step 1.) -Dynamic setup actions might include establishment of demand-dialed links. -These might be present anywhere along the path, -so one cannot rely on out-of-band communication at the Initiator to -trigger them. -Hence the ping. -.R -(Step 2.) -In many cases, the IP address on the intercepted packet will be the -result of a name lookup just done. -Inverse queries, an obscure DNS feature from the distant past, -in theory can be used to ask a DNS server to reverse that lookup, -giving the name that produced the address. -This is not the same as a reverse lookup, -and the difference can matter a great deal in cases where a host -does not control its reverse map -(e.g., when the host's IP address is dynamically assigned). -Unfortunately, inverse queries were never widely implemented and -are now considered obsolete. -Phooey. -.A -Support for a small subset of this admittedly-obscure feature -would be useful. -Unfortunately, it seems unlikely. -.R -(Step 3.) -Using only IP addresses to decide whether there is already a relevant -keying channel avoids some -difficult problems. -In particular, it might seem that this should be based on identities, -but those are not known until very late in IKE Phase 1 negotiations. -.R -(Step 4.) -The DNS lookup is done on speculation -because the data will probably be useful and the lookup can be done -in parallel with IKE activity, -potentially speeding things up. -.R -(Steps 7 and 8.) -If an SG does not control its reverse map, -there is no way it can prove its right to use an IP address, -but it can nevertheless supply both an identity (as an FQDN) and -proof of its right to use that identity. -This is somewhat better than nothing, -and may be quite useful if the SG is representing a client host -which \fIcan\fR prove its right to \fIits\fR IP address. -(For example, a fixed-address subnet might live behind an SG with -a dynamically-assigned address; -such an SG has to be the Initiator, not the Responder, -so the subnet's TXT records can contain FQDN identities, -but with that restriction, this works.) -It might sound like this would permit some man-in-the-middle attacks -in important cases like Road Warrior, -but the RW can still do full authentication of the home base, -so a man in the middle cannot successfully impersonate home base, -and the D-H exchange doesn't work unless the man in the middle -impersonates \fIboth\fR ends. -.R -(Steps 7 and 8.) -Another situation where proof of the right to use an identity can be -very useful is when access is deliberately limited. -While opportunistic encryption is intended as a general-purpose -connection mechanism between strangers, -it may well be convenient for prearranged connections to use -the same mechanism. -.R -(Steps 7 and 8.) -FQDNs as identities are avoided where possible, -since they can involve synchronous DNS lookups. -.R -(Step 11.) -Note that only here, in Phase 2, -does the Responder actually learn who the -Source and Destination hosts are. -This unfortunately demands a synchronous DNS lookup to verify that the -Initiator is authorized to represent the Source, -unless they are one and the same. -This and the initial TXT lookup are the only synchronous DNS lookups -absolutely required by the algorithm, -and they appear to be unavoidable. -.R -While it might seem unlikely that a refusal to cooperate from one SG -could be remedied by trying another\(empresumably they all use the -same policies\(emit's conceivable that one might be misconfigured. -Preferably they should all be tried, -but it may be necessary to set some limits on this -if alternatives exist. -.NH 2 -DNS Records -.P -Gateway discovery and key lookup are based on TXT and KEY DNS records. -The TXT record specifies IP address or other identity of a host's SG, -and possibly supplies its public key as well, -while the KEY record supplies public keys not found in TXT records. -.NH 3 -TXT -.P -Opportunistic-encryption SG discovery uses TXT records with the content: -.DS -X-IPsec-Gateway(\fInnn\fR)=\fIiii\fR\ \fIkkk\fR -.DE -following RFC 1464 attribute/value -notation. -Records which -do not contain an ``='', -or which do not have exactly the specified form to the left of it, -are ignored. -(Near misses perhaps should be reported.) -.P -The \fInnn\fR is an unsigned integer which will fit in 16 bits, -specifying an MX-style preference -(lower number = stronger preference) to -control the order in which multiple SGs are tried. -If there are ties, pick one, -randomly enough that the choice will probably be different each time. -xxx rollover. -The preference field is not optional; -use ``0'' if there is no meaningful preference ordering. -.P -The \fIiii\fR part identifies the SG. -Normally this is a dotted-decimal IPv4 address or -a colon-hex IPv6 address. -The sole exception is if the SG has no fixed address (see 2.4) but -the host(s) behind it do, -in which case \fIiii\fR is of the form ``@fqdn'', -where \fIfqdn\fR is the FQDN that the SG will use to -identify itself (in step 7 of section 2.2); -such a record cannot be used for SG discovery by an Initiator, -but can be used for -SG verification (step 11 of 2.2) by a Responder. -.P -The \fIkkk\fR part is optional. -If it is present, -it is an RSA-MD5 public key in base-64 notation, as in the text -form of an RFC 2535 KEY record. -If it is not present, -this specifies that the public key can be found in a KEY -record located based on the SG's identification: -if \fIiii\fR is an IP address, -do a reverse lookup on that address, -else do a forward lookup on the FQDN. -.R -While it is unusual for a reverse lookup to go for records other than PTR -records (or possibly CNAME records, for RFC 2317 classless delegation), -there's no reason why it can't. -The TXT record is a temporary stand-in -for (we hope, someday) a new DNS record for SG identification and keying. -Keeping the setup process fast requires minimizing the number of DNS -lookups, hence the desire to put all the information in one place. -.R -The use of RFC 1464 notation avoids collisions with other uses of TXT -records. -The ``X-'' in the attribute name -indicates that this format is tentative and experimental; -this design will probably need modification after initial experiments. -The format is chosen with an eye on eventual binary encoding. -Note, in particular, -that the TXT record normally contains the \fIaddress\fR of the SG, -not (repeat, not) its name. -Name-to-address conversion is the job of -whatever generates the TXT record, -which is expected to be a program, not a human\(emthis is conceptually -a \fIbinary\fR record, temporarily using a text encoding. -The ``@fqdn'' form of the SG identity is -for specialized uses and is never mapped to an address. -.A -A DNS TXT record contains one or more character strings, -but RFC 1035 does not describe exactly how -a multi-string TXT record is interpreted. -This is relevant because a string can be at most 255 characters, -and public keys can exceed this. -Empirically, the standard pattern is that -each string which is -both less than 255 characters \fIand\fR not the final string of the -record should have a blank appended to it, -and the strings of the record -should then be concatenated. -(This observation is based on how BIND 8 transforms a TXT record -from text to DNS binary.) -.NH 3 -KEY -.P -An opportunistic-encryption KEY record -is an Authentication-permitted, -Entity (host), -non-Signatory, -IPsec, -RSA/MD5 record -(that is, its first four bytes are 0x42000401), -as per RFCs 2535 and 2537. -KEY records with other \fIflags\fR, \fIprotocol\fR, or \fIalgorithm\fR -values are ignored. -.R -Unfortunately, the public key has to be -associated with the SG, not the client host behind it. -The Responder does not know which client it is supposed to be representing, -or which client the Initiator is representing, -until far too late. -.A -Per-client keys would reduce vulnerability to key compromise, -and simplify key changes, -but they would require changes to IKE Phase 1, to separately identify -the SG and its initial client(s). -(At present, the client identities are not known to the Responder -until IKE Phase 2.) -While the current IKE standard does not actually specify (!) who is -being identified by identity payloads, -the overwhelming consensus is that they identify the SG, -and as seen earlier, -this has important uses. -.NH 3 -Summary -.P -For reference, the minimum set of DNS records needed to make this -all work is either: -.IP 1. \w'1.'u+2n -TXT in Destination reverse map, identifying Responder and providing public key. -.IP 2. -KEY in Initiator reverse map, providing public key. -.IP 3. -TXT in Source reverse map, verifying relationship to Initiator. -.P -or: -.IP 1. \w'1.'u+2n -TXT in Destination reverse map, identifying Responder. -.IP 2. -KEY in Responder reverse map, providing public key. -.IP 3. -KEY in Initiator reverse map, providing public key. -.IP 4. -TXT in Source reverse map, verifying relationship to Initiator. -.P -Slight complications ensue for dynamic addresses, -lack of control over reverse maps, etc. -.NH 3 -Implementation -.P -In the long run, we need either a tree of trust or a web of trust, -so we can trust our DNS data. -The obvious approach for DNS is a tree of trust, -but there are various practical problems with running all of this -through the root servers, -and a web of trust is arguably more robust anyway. -This is logically independent of opportunistic encryption, -and a separate design proposal will be prepared. -.P -Interim stages of implementation of this will require a bit of thought. -Notably, we need some way of dealing with the lack of fully signed DNSSEC -records right away. -Without user interaction, probably the best we can do is to -remember the results of old fetches, compare them to the results of new -fetches, and complain and disbelieve all of it if there's a mismatch. -This does mean that somebody who gets fake data into our very first fetch -will fool us, at least for a while, but that seems an acceptable tradeoff. -(Obviously there needs to be a way to manually flush the remembered results -for a specific host, to permit deliberate changes.) -.NH 2 -Responders Without Credentials -.P -In cases where the Destination simply does not control its -DNS reverse-map entries, -there is no verifiable way to determine a suitable SG. -This does not make communication utterly impossible, though. -.P -Simply attempting negotiation directly with the host is a last resort. -(An aggressive implementation might wish to attempt it in parallel, -rather than waiting until other options are known to be unavailable.) -In particular, in many cases involving dynamic addresses, it will work. -It has the disadvantage of delaying the discovery that opportunistic -encryption is entirely impossible, -but the case seems common enough to justify the overhead. -.P -However, there are policy issues here either way, because -it is possible to impersonate such a host. -The host can supply an FQDN identity and verify its right to use that -identity, -but except by prearrangement, -there is no way to verify that the FQDN is the right one for that -IP address. -(The data from forward lookups may be controlled by people -who do not own the address, so it cannot be trusted.) -The encryption is still solid, though, -so in many cases this may be useful. -.NH 2 -Failure of Opportunism -.P -When there is no way to do opportunistic encryption, a policy issue arises: -whether to put in a bypass (which allows plaintext traffic through) -or a block (which discards it, perhaps with notification back to the sender). -The choice is very much a matter of local policy, -and may depend on details such as the higher-level protocol being used. -For example, -an SG might well permit plaintext HTTP but forbid plaintext Telnet, -in which case \fIboth\fR a block and a bypass would be set up if -opportunistic encryption failed. -.P -A bypass/block must, in practice, -be treated much like an IPsec tunnel. -It should persist for a while, -so that high-overhead processing doesn't have to be done for every packet, -but should go away eventually to return resources. -It may be simplest to treat it as a degenerate tunnel. -It should have a relatively long lifetime (say 6h) to keep the frequency -of negotiation attempts down, -except in the case where the other SG simply did not respond to IKE packets, -where the lifetime should be short (say 10min) because -the other SG is presumably down and might come back up again. -(Cases where the other SG responded to IKE with unauthenticated error -reports like ``port unreachable'' are borderline, -and might deserve to be treated as an intermediate case: -while such reports cannot be trusted unreservedly, -in the absence of any other response, -they do give some reason to suspect that the other SG is unable or -unwilling to participate in opportunistic encryption.) -.P -As noted in section 2.1, one might think that -arrival of a plaintext incoming packet should cause a -bypass/block to be set up for its source host: -such a packet is almost always followed by an outgoing reply packet; -the incoming packet is clear evidence that opportunistic encryption is -not available at the other end; -attempting it will waste resources and delay traffic to no good purpose. -Unfortunately, this means that anyone out on the Internet -who can forge a source address can prevent encrypted communication! -Since their source addresses are not authenticated, -plaintext packets cannot be taken as evidence of anything, -except perhaps that communication from that host is likely to occur soon. -.P -There needs to be a way for local administrators to remove a bypass/block -ahead of its normal expiry time, -to force a retry after a problem at the other end is known to have been fixed. -.NH 2 -Subnet Opportunism -.P -In principle, when the Source or Destination host belongs to a subnet -and the corresponding SG is willing to provide tunnels to the whole subnet, -this should be done. -There is no extra overhead, -and considerable potential for avoiding later overhead if -similar communication occurs with other members of the subnet. -Unfortunately, -at the moment, -opportunistic tunnels can only have degenerate subnets (single hosts) -at their ends. -(This does, at least, set up the keying channel, -so that negotiations for tunnels to other hosts in the same subnets -will be considerably faster.) -.P -The crucial problem is step 11 of section 2.2: -the Responder must verify that the Initiator is authorized to represent -the Source, -and this is impossible for a subnet because -there is no way to do a reverse lookup on it. -Information in DNS -records for a name or a single address cannot be trusted, -because they may be controlled by people who do not control the whole subnet. -.A -Except in the special case of a subnet masked on a -byte boundary (in which case RFC 1035's convention of an incomplete -in-addr.arpa name could be used), subnet lookup would need extensions to the -reverse-map name space, perhaps along the lines of that commonly done for -RFC 2317 delegation. -IPv6 already has suitable name syntax, as in RFC 2874, -but has no specific provisions for subnet entries in its reverse maps. -Fixing all this is is not conceptually difficult, -but is logically independent of opportunistic encryption, -and will be proposed separately. -.P -A less-troublesome problem is that the Initiator, -in step 10 of 2.2, -must know exactly what subnet is present on the Responder's end -so he can propose a tunnel to it. -This information could be included in the TXT record -of the Destination -(it would have to be verified with a subnet lookup, -but that could be done in parallel with other operations). -The Initiator presumably -can be configured to know what subnet(s) are present on its end. -.NH 2 -Option Settings -.P -IPsec and IKE have far too many useless options, and a few useful ones. -IKE negotiation is quite simplistic, and cannot handle even simple -discrepancies between the two SGs. -So it is necessary to be quite specific about what should be done and -what should be proposed, -to guarantee interoperability without prearrangement or -other negotiation protocols. -.R -The prohibition of other negotiations is simply because there is no time. -The setup algorithm (section 2.2) is lengthy already. -.P -[Open question: -should opportunistic IKE use a different port than normal IKE?] -.P -Somewhat arbitrarily and -tentatively, opportunistic SGs must support Main Mode, Oakley group 5 for -D-H, 3DES encryption and MD5 authentication for both ISAKMP and IPsec SAs, -RSA/MD5 digital-signature authentication with keys between 2048 and 8192 bits, -and ESP doing both encryption and authentication. -They must do key PFS -in Quick Mode, but not identity PFS. -They may support IPComp, preferably using Deflate, -but must not insist on it. -They may support AES as an alternative to 3DES, -but must not insist on it. -.R -Identity PFS essentially requires establishing -a complete new keying channel for each new tunnel, -but key PFS just does a new Diffie-Hellman exchange for each rekeying, -which is relatively cheap. -.P -Keying channels must remain in existence at least as long as any -tunnel created with them remains (they are not costly, and keeping -the management path up and available simplifies various issues). -See section 3.1 for related issues. -Given the use of key PFS, -frequent rekeying does not seem critical here. -In the absence of strong reason to do otherwise, -the Initiator should propose rekeying at 8hr-or-1MB. -The Responder must accept any proposal which specifies -a rekeying time between 1hr and 24hr inclusive -and a rekeying volume between 100KB and 10MB inclusive. -.P -Given the short expected useful life of most tunnels (see section 3.1), -very few of them will survive long enough to be rekeyed. -In the absence of strong reason to do otherwise, -the Initiator should propose rekeying at 1hr-or-100MB. -The Responder must accept any proposal which specifies -a rekeying time between 10min and 8hr inclusive -and a rekeying volume between 1MB and 1000MB inclusive. -.P -It is highly desirable to add some random jitter -to the times of actual rekeying attempts, -to break up ``convoys'' of rekeying events; -this and certain other aspects of robust rekeying practice will be the subject -of a separate design proposal. -.R -The numbers used here for rekeying intervals are chosen quite arbitrarily -and should be re-assessed after some implementation experience is gathered. -.NH 1 -Renewal and Teardown -.NH 2 -Aging -.P -When to tear tunnels down is a bit problematic, but if we're setting up a -potentially unbounded number of them, -we have to tear them down \fIsomehow sometime\fR. -.P -Set a short initial tentative lifespan, say 1min, -since most net flows in fact last only a few seconds. -When that expires, look to see if -the tunnel is still in use (definition: -has had traffic, in either direction, -in the last half of the tentative lifespan). -If so, assign it a somewhat longer tentative lifespan, say 20min, -after which, look again. -If not, close it down. -(This tentative lifespan is -independent of rekeying; it is just the time when the tunnel's future -is next considered. -This should happen reasonably frequently, unlike -rekeying, which is costly and shouldn't be too frequent.) -Multi-step backoff algorithms are not worth the trouble; looking every -20min doesn't seem onerous. -.P -If the security gateway and the client host are one and the same, -tunnel teardown decisions might wish to pay attention to TCP connection status, -as reported by the local TCP layer. -A still-open -TCP connection is almost a guarantee that more traffic is coming, while -the demise of the only TCP connection through a tunnel is a strong hint -that none is. -If the SG and the client host are separate machines, -though, tracking TCP connection status requires packet snooping, -which is complicated and probably not worthwhile. -.P -IKE keying channels likewise are torn down when it appears the need has -passed. -They always linger longer than the last tunnel they administer, -in case they are needed again; the cost of retaining them is low. -Other than that, -unless the number of keying channels on the SG gets large, -the SG should simply retain all of them until rekeying time, -since rekeying is the only costly event. -When about to rekey a keying channel which has no current tunnels, -note when the last actual keying-channel traffic occurred, -and close the keying channel down if it wasn't in the last, say, 30min. -When rekeying a keying channel (or perhaps shortly before rekeying is expected), -Initiator and Responder should re-fetch the public keys used for -SG authentication, -against the possibility that they have changed or disappeared. -.P -See section 2.7 for discussion of rekeying intervals. -.P -Given the low user impact of tearing down and rebuilding a connection -(a tunnel or a keying channel), -rekeying attempts should not be too persistent: -one can always just rebuild when needed, -so heroic efforts to preserve an existing connection are unnecessary. -Say, try every 10s for a minute and every minute for 5min, -and then give up and declare the connection -(and all other connections to that IKE peer) dead. -.R -In future, more sophisticated, versions of this protocol, -examining the initial packet might permit a more intelligent guess at -the tunnel's useful life. -HTTP connections in particular are -notoriously bursty and repetitive. -.R -Note that rekeying a keying connection basically consists of building a -new keying connection from scratch, -using IKE Phase 1, -and abandoning the old one. -.NH 2 -Teardown and Cleanup -.P -Teardown should always be coordinated with the other end. -This means interpreting and sending Delete notifications. -.P -On receiving a Delete for the outbound SAs of a tunnel -(or some subset of them), -tear down the inbound ones too, and notify the other end -with a Delete. -Tunnels need to be considered as bidirectional entities, -even though the low-level protocols don't think of them that way. -.P -When the deletion is initiated locally, -rather than as a response to a received Delete, -send a Delete for (all) the inbound SAs of a tunnel. -If no responding Delete is received for the outbound SAs, -try re-sending the original Delete. -Three tries spaced 10s apart seems a reasonable level of effort. -(Indefinite persistence is not necessary; -whether the other end isn't cooperating because it doesn't feel like -it, or because it is down/disconnected/etc., -the problem will eventually be cleared up by other means.) -.P -After rekeying, -transmission should switch to using the new SAs (ISAKMP or IPsec) -immediately, -and the old leftover SAs should be cleared out promptly -(and Deletes sent) rather than waiting for them to expire. -This reduces clutter and minimizes confusion. -.P -Since there is only one keying channel per remote IP address, -the question of whether a Delete notification has appeared on a -``suitable'' keying channel does not arise. -.R -The pairing of Delete notifications effectively constitutes an -acknowledged Delete, which is highly desirable. -.NH 2 -Outages and Reboots -.P -Tunnels sometimes go down because the other -end crashes, or disconnects, or has a network link break, -and there is no notice of this in the general case. -(Even in the event of a crash and -successful reboot, other SGs don't hear about it unless the -rebooted SG has specific reason to talk to them immediately.) -Over-quick response to temporary network outages is undesirable... -but note that a tunnel can be torn -down and then re-established without any user-visible effect except -a pause in traffic, -whereas if one end does reboot, -the other end can't get packets to it \fIat all\fR (except via IKE) -until the situation is noticed. -So a bias toward quick response is appropriate, -even at the cost of occasional false alarms. -.P -Heartbeat mechanisms are somewhat unsatisfactory for this. -Unless they are very frequent, which causes other problems, -they do not detect the problem promptly. -.A -What is really wanted is authenticated ICMP. -This might be a case where public-key encryption/authentication -of network packets is the right thing to do, -despite the expense. -.P -In the absence of that, a two-part approach seems warranted. -.P -First, -when an SG receives an IPsec packet that is addressed to it, -and otherwise appears healthy, -but specifies an unknown SA and is from a host that the receiver currently -has no keying channel to, -the receiver must attempt to inform the sender -via an IKE Initial-Contact notification -(necessarily sent in plaintext, -since there is no suitable keying channel). -This must be severely rate-limited on \fIboth\fR ends; -one notification per SG pair per minute seems ample. -.P -Second, there is an obvious difficulty with this: -the Initial-Contact notification is unauthenticated -and cannot be trusted. -So it must be taken as a hint only: -there must be a way to confirm it. -.P -What is needed here is something that's desirable for -debugging and testing anyway: -an IKE-level ping mechanism. -Pinging direct at the IP level instead will not tell us about a -crash/reboot event. -Sending pings through tunnels has -various complications (they should stop at the far mouth of the tunnel -instead of going on to a subnet; they should not count against idle -timers; etc.). -What is needed is a continuity check on a keying channel. -(This could also be used as a heartbeat, -should that seem useful.) -.P -IKE Ping delivery need not be reliable, since the whole point of a ping is -simply to provoke an acknowledgement. -They should preferably be authenticated, -but it is not clear that this is absolutely necessary, -although if they are not they need -encryption plus a timestamp or a nonce, -to foil replay mischief. -How they are implemented is a secondary issue, -and a separate design proposal will be prepared. -.A -Some existing implementations are already using -(private) notify value 30000 (``LIKE_HELLO'') as ping -and (private) notify value 30002 (``SHUT_UP'') as ping reply. -.P -If an IKE Ping gets no response, try some (say 8) IP pings, -spaced a few seconds apart, to check IP connectivity; -if one comes back, try another IKE Ping; -if that gets no response, -the other end probably has rebooted, or otherwise been re-initialized, -and its tunnels and keying channel(s) should be torn down. -.P -In a similar vein, -giving limited rekeying persistence, -a short network outage could take some tunnels down without -disrupting others. -On receiving a packet for an unknown SA from a host that a keying -channel is currently open to, -send that host a Invalid-SPI notification for that SA. -xxx that's not what Invalid-SPI is for. -The other host can then tear down the half-torn-down tunnel, -and negotiate a new tunnel for the traffic -it presumably still wants to send. -.P -Finally, -it would be helpful if SGs made some attempt to deal intelligently -with crashes and reboots. -A deliberate shutdown should include an attempt to notify all other SGs -currently connected by keying channels, -using Deletes, -that communication is about to fail. -(Again, these will be taken as teardowns; -attempts by the other SGs to negotiate new tunnels as replacements -should be ignored at this point.) -And when possible, SGs should attempt to preserve information -about currently-connected SGs in non-volatile storage, -so that after a crash, -an Initial-Contact can be sent to previous partners to -indicate loss of all previously-established connections. -.NH 1 -Conclusions -.P -This design appears to achieve the objective of setting up encryption -with strangers. -The authentication aspects also seem adequately addressed if the -destination controls its reverse-map DNS entries -and the DNS data itself can be reliably authenticated -as having originated from the legitimate administrators of that -subnet/FQDN. -The authentication situation is less satisfactory when DNS is less helpful, -but it is difficult to see what else could be done about it. -.NH 1 -References -.P -[TBW] -.NH 1 -Appendix: Separate Design Proposals TBW -.IP \(bu \w'\(bu'u+2n -How can we build a web of trust with DNSSEC? -(See section 2.3.4.) -.IP \(bu -How can we extend DNS reverse lookups to permit reverse lookup -on a subnet? -(Both address and mask must appear in the name to be looked up.) -(See section 2.6.) -.IP \(bu -How can rekeying be done as robustly as possible? -(At least partly, this is just documenting current FreeS/WAN practice.) -(See section 2.7.) -.IP \(bu -How should IKE Pings be implemented? -(See section 3.3.) diff --git a/doc/performance.html b/doc/performance.html deleted file mode 100644 index 2258eeeda..000000000 --- a/doc/performance.html +++ /dev/null @@ -1,458 +0,0 @@ - - - -Introduction to FreeS/WAN - - - - -Contents -Previous -Next -
-

Performance of FreeS/WAN

- The performance of FreeS/WAN is adequate for most applications. -

In normal operation, the main concern is the overhead for encryption, - decryption and authentication of the actual IPsec ( -ESP and/or AH) data packets. Tunnel - setup and rekeying occur so much less frequently than packet processing - that, in general, their overheads are not worth worrying about.

-

At startup, however, tunnel setup overheads may be significant. If - you reboot a gateway and it needs to establish many tunnels, expect - some delay. This and other issues for large gateways are discussed - below.

-

Published material

-

The University of Wales at Aberystwyth has done quite detailed speed - tests and put - their results on the web.

-

Davide Cerri's thesis (in - Italian) includes performance results for FreeS/WAN and for - TLS. He posted an - English summary on the mailing list.

-

Steve Bellovin used one of AT&T Research's FreeS/WAN gateways as his - data source for an analysis of the cache sizes required for key - swapping in IPsec. Available as - text or - PDF slides for a talk on the topic.

-

See also the NAI work mentioned in the next section.

-

Estimating CPU overheads

-

We can come up with a formula that roughly relates CPU speed to the - rate of IPsec processing possible. It is far from exact, but should be - usable as a first approximation.

-

An analysis of authentication overheads for high-speed networks, - including some tests using FreeS/WAN, is on the - NAI Labs site. In particular, see figure 3 in this - PDF document. Their estimates of overheads, measured in Pentium II - cycles per byte processed are:

- - - - - - -
IPsecauthenticationencryption -cycles/byte
Linux IP stack alonenonono -5
IPsec without cryptoyesnono -11
IPsec, authentication onlyyesSHA-1no24
IPsec with encryptionyesyesyesnot tested
-

Overheads for IPsec with encryption were not tested in the NAI work, - but Antoon Bosselaers' - web page gives cost for his optimised Triple DES implementation as - 928 Pentium cycles per block, or 116 per byte. Adding that to the 24 - above, we get 140 cycles per byte for IPsec with encryption.

-

At 140 cycles per byte, a 140 MHz machine can handle a megabyte -- 8 - megabits -- per second. Speeds for other machines will be proportional - to this. To saturate a link with capacity C megabits per second, you - need a machine running at C * 140/8 = C * 17.5 MHz.

-

However, that estimate is not precise. It ignores the differences - between:

- -

and does not account for some overheads you will almost certainly - have:

- -

so we suggest using C * 25 to get an estimate with a bit - of a built-in safety factor.

-

This covers only IP and IPsec processing. If you have other loads on - your gateway -- for example if it is also working as a firewall -- then - you will need to add your own safety factor atop that.

-

This estimate matches empirical data reasonably well. For example, - Metheringham's tests, described below, show - a 733 topping out between 32 and 36 Mbit/second, pushing data as fast - as it can down a 100 Mbit link. Our formula suggests you need at least - an 800 to handle a fully loaded 32 Mbit link. The two results are - consistent.

-

Some examples using this estimation method:

- - - - - - - - - - - - - - -
InterfaceMachine speed in MHz
TypeMbit per -
second		Estimate -
Mbit*25		Minimum IPSEC gatewayMinimum with other - load -

(e.g. firewall)

-
DSL125 MHz -whatever you have133, or better if you have it
cable modem375 MHz
any link, light load -5125 MHz133200+, - almost any surplus machine
Ethernet10250 MHz -surplus 266 or 300500+
fast link, moderate load -20500 MHz500800+, - any current off-the-shelf PC
T3 or E3451125 MHz -12001500+
fast Ethernet100 -2500 MHz// not feasible - with 3DES in software on current machines //
OC31553875 MHz
-

Such an estimate is far from exact, but should be usable as minimum - requirement for planning. The key observations are:

- -

Higher performance alternatives

-

AES is a new US government block - cipher standard, designed to replace the obsolete - DES. If FreeS/WAN using 3DES is - not fast enough for your application, the AES - patch may help.

-

To date (March 2002) we have had only one - mailing list report of measurements with the patch applied. It - indicates that, at least for the tested load on that user's network, - AES roughly doubles IPsec throughput. If further testing - confirms this, it may prove possible to saturate an OC3 link in - software on a high-end box.

-

Also, some work is being done toward support of - hardware IPsec acceleration which might extend the range of - requirements FreeS/WAN could meet.

-

Other considerations

-

CPU speed may be the main issue for IPsec performance, but of course - it isn't the only one.

-

You need good ethernet cards or other network interface hardware to - get the best performance. See this - ethernet information page and this - Linux network driver page.

-

The current FreeS/WAN kernel code is largely single-threaded. It is - SMP safe, and will run just fine on a multiprocessor machine ( -discussion), but the load within the kernel is not shared - effectively. This means that, for example to saturate a T3 -- which - needs about a 1200 MHz machine -- you cannot expect something like a - dual 800 to do the job.

-

On the other hand, SMP machines do tend to share loads well so -- - provided one CPU is fast enough for the IPsec work -- a multiprocessor - machine may be ideal for a gateway with a mixed load.

-

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

- -

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.

-

A gateway that does a lot of rekeying -- many tunnels and/or low - settings for tunnel lifetimes -- will also need a lot of - random numbers from the random(4) driver.

-

Low-end systems

-

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

From the above, and from general user experience as reported on the - list, it seems clear that a cheap surplus machine -- a reasonable 486, - a minimal Pentium box, a Sparc 5, ... -- can easily handle a home - office or a small company connection using any of:

- -

If available, we suggest using a Pentium 133 or better. This should - ensure that, even under maximum load, IPsec will use less than half the - CPU cycles. You then have enough left for other things you may want on - your gateway -- firewalling, web caching, DNS and such.

-

Measuring KLIPS

-

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
-

Speed with compression

-

Another user reported some results for connections with and without - IP compression:

-
Subject: [Users] Speed with compression
-   Date: Fri, 29 Jun 2001
-   From: John McMonagle <johnm@advocap.org>
-
-Did a couple tests with compression using the new 1.91 freeswan.
-
-Running between 2 sites with cable modems.  Both  using approximately
-130 mhz pentium.
-
-Transferred files with ncftp.
-
-Compressed file was a 6mb compressed  installation file.
-Non compressed was 18mb /var/lib/rpm/packages.rpm
-
-                            Compressed vpn          regular vpn
-Compress file                42.59 kBs               42.08 kBs
-regular file                110.84 kBs               41.66 kBs
-
-Load  was about 0 either way.
-Ping times were very similar  a bit above 9 ms.
-
-Compression looks attractive to me.
- Later in the same thread, project technical lead Henry Spencer added: -
> is there a reason not to switch compression on?  I have large gateway boxes
-> connecting 3 connections, one of them with a measly DS1 link...
-
-Run some timing tests with and without, with data and loads representative
-of what you expect in production.  That's the definitive way to decide. 
-If compression is a net loss, then obviously, leave it turned off.  If it
-doesn't make much difference, leave it off for simplicity and hence
-robustness.  If there's a substantial gain, by all means turn it on. 
-
-If both ends support compression and can successfully negotiate a
-compressed connection (trivially true if both are FreeS/WAN 1.91), then
-the crucial question is CPU cycles. 
-
-Compression has some overhead, so one question is whether *your* data
-compresses well enough to save you more CPU cycles (by reducing the volume
-of data going through CPU-intensive encryption/decryption) than it costs
-you.  Last time I ran such tests on data that was reasonably compressible
-but not deliberately contrived to be so, this generally was not true --
-compression cost extra CPU cycles -- so compression was worthwhile only if
-the link, not the CPU, was the bottleneck.  However, that was before the
-slow-compression bug was fixed.  I haven't had a chance to re-run those
-tests yet, but it sounds like I'd probably see a different result.
- The bug he refers to was a problem with the compression libraries that - had us using C code, rather than assembler, for compression. It was - fixed before 1.91. -

Methods of measuring

-

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.
-
-Contents -Previous -Next - - diff --git a/doc/policygroups.html b/doc/policygroups.html deleted file mode 100644 index 6a507b1f6..000000000 --- a/doc/policygroups.html +++ /dev/null @@ -1,341 +0,0 @@ - - - -Introduction to FreeS/WAN - - - - -Contents -Previous -Next -
-

How to Configure Linux FreeS/WAN with Policy Groups

- -

What are Policy Groups?

-

Policy Groups are an elegant general mechanism to - configure FreeS/WAN. They are useful for many FreeS/WAN users.

-

In previous FreeS/WAN versions, you needed to configure each IPsec - connection explicitly, on both local and remote hosts. This could - become complex.

-

By contrast, Policy Groups allow you to set local IPsec policy for - lists of remote hosts and networks, simply by listing the hosts and - networks which you wish to have special treatment in one of several - Policy Group files. FreeS/WAN then internally creates the connections - needed to implement each policy.

-

In the next section we describe our five Base Policy Groups, which - you can use to configure IPsec in many useful ways. Later, we will show - you how to create an IPsec VPN using one line of configuration for each - remote host or network.

- -

Built-In Security Options

-

FreeS/WAN offers these Base Policy Groups:

-
-
private
-
FreeS/WAN only communicates privately with the listed - CIDR blocks. If needed, FreeS/WAN attempts to create a connection - opportunistically. If this fails, FreeS/WAN blocks communication. - Inbound blocking is assumed to be done by the firewall. FreeS/WAN - offers firewall hooks but no modern firewall rules to help with inbound - blocking.
-
private-or-clear
-
FreeS/WAN prefers private communication with the listed CIDR - blocks. If needed, FreeS/WAN attempts to create a connection - opportunistically. If this fails, FreeS/WAN allows traffic in the - clear.
-
clear-or-private
-
FreeS/WAN communicates cleartext with the listed CIDR blocks, but - also accepts inbound OE connection requests from them. Also known as - passive OE (pOE), this policy may be used to create an - opportunistic responder.
-
clear
-
FreeS/WAN only communicates cleartext with the listed CIDR blocks.
-
block
-
FreeS/WAN blocks traffic to and from and the listed CIDR blocks. - Inbound blocking is assumed to be done by the firewall. FreeS/WAN - offers firewall hooks but no modern firewall rules to help with inbound - blocking. - -
-
- -

Notes:

- -

Using Policy Groups

-

The Base Policy Groups which build IPsec connections rely on - Opportunistic Encryption. To use the following examples, you must first - become OE-capable, as described in our - quickstart guide.

-

Example 1: Using a Base Policy Group

-

Simply place CIDR blocks (names, IPs or IP - ranges) in /etc/ipsec.d/policies/[groupname], and reread the - policy group files.

-

For example, the private-or-clear policy tells FreeS/WAN - to prefer encrypted communication to the listed CIDR blocks. Failing - that, it allows talk in the clear.

-

To make this your default policy, place - fullnet in the private-or-clear policy group file:

-
    [root@xy root]# cat /etc/ipsec.d/policies/private-or-clear
-    # This file defines the set of CIDRs (network/mask-length) to which
-    # communication should be private, if possible, but in the clear otherwise.
-    ....
-    0.0.0.0/0
-

and reload your policies with

-
    ipsec auto --rereadgroups
-

Use this test to verify - opportunistic connections.

- -

Example 2: Defining IPsec Security Policy with - Groups

-

Defining IPsec security policy with Base Policy Groups is like - creating a shopping list: just put CIDR blocks in the appropriate group - files. For example:

-
    [root@xy root]# cd /etc/ipsec.d/policies
-    [root@xy policies]# cat private
-        192.0.2.96/27              # The finance department
-        192.0.2.192/29             # HR
-	192.0.2.12                 # HR gateway
-        irc.private.example.com    # Private IRC server
-  
-    [root@xy policies]# cat private-or-clear
-        0.0.0.0/0                  # My default policy: try to encrypt.
-
-    [root@xy policies]# cat clear
-        192.0.2.18/32              # My POP3 server
-        192.0.2.19/32              # My Web proxy
-
-    [root@xy policies]# cat block
-        spamsource.example.com
-

To make these settings take effect, type:

-
    ipsec auto --rereadgroups
-

Notes:

- - -

Example 3: Creating a Simple IPsec VPN with the - private Group

-

You can create an IPsec VPN between several hosts, with only one line - of configuration per host, using the private policy group.

-

First, use our quickstart guide to set - up each participating host with a FreeS/WAN install and OE.

-

In one host's /etc/ipsec.d/policies/private, list the - peers to which you wish to protect traffic. For example:

-
    [root@xy root]# cd /etc/ipsec.d/policies
-    [root@xy policies]# cat private
-        192.0.2.9              # several hosts at example.com
-        192.0.2.11             
-        192.0.2.12                 
-        irc.private.example.com 
-
-

Copy the private file to each host. Remove the local host, - and add the initial host.

-
    scp2 /etc/ipsec.d/policies/private root@192.0.2.12:/etc/ipsec.d/policies/private
-

On each host, reread the policy groups with

-
    ipsec auto --rereadgroups
-

That's it! You're configured.

-

Test by pinging between two hosts. After a second or two, traffic - should flow, and

-
    ipsec eroute
-

should yield something like

-
    192.0.2.11/32   -> 192.0.2.8/32  => tun0x149f@192.0.2.8
-

where your host IPs are substituted for 192.0.2.11 and 192.0.2.8.

-

If traffic does not flow, there may be an error in your OE setup. - Revisit our quickstart guide.

-

Our next two examples show you how to add subnets to this IPsec VPN.

- -

Example 4: New Policy Groups to Protect a Subnet

-

To protect traffic to a subnet behind your FreeS/WAN gateway, you'll - need additional DNS records, and new policy groups. To set up the DNS, - see our quickstart guide. To - create five new policy groups for your subnet, copy these connections - to /etc/ipsec.conf. Substitute your subnet's IPs for - 192.0.2.128/29.

-
-conn private-net
-    also=private  # inherits settings (eg. auto=start) from built in conn
-    leftsubnet=192.0.2.128/29  # your subnet's IPs here
-
-conn private-or-clear-net
-    also=private-or-clear
-    leftsubnet=192.0.2.128/29
-
-conn clear-or-private-net
-    also=clear-or-private
-    leftsubnet=192.0.2.128/29
-
-conn clear-net
-    also=clear
-    leftsubnet=192.0.2.128/29
-
-conn block-net
-    also=block
-    leftsubnet=192.0.2.128/29
-
-

Copy the gateway's files to serve as the initial policy group files - for the new groups:

-
-    cp -p /etc/ipsec.d/policies/private /etc/ipsec.d/policies/private-net
-    cp -p /etc/ipsec.d/policies/private-or-clear /etc/ipsec.d/policies/private-or-clear-net
-    cp -p /etc/ipsec.d/policies/clear-or-private /etc/ipsec.d/policies/clear-or-private-net
-    cp -p /etc/ipsec.d/policies/clear /etc/ipsec.d/policies/clear-net
-    cp -p /etc/ipsec.d/policies/block /etc/ipsec.d/policies/block
-
-

Tip: Since a missing policy group file is equivalent to a - file with no entries, you need only create files for the connections - you'll use.

-

To test one of your new groups, place the fullnet 0.0.0.0/0 in - private-or-clear-net. Perform the subnet test in - our quickstart guide. You should see a connection, and

-
    ipsec eroute
-

should include an entry which mentions the subnet node's IP and the - OE test site IP, like this:

-
    192.0.2.131/32   -> 192.139.46.77/32  => tun0x149f@192.0.2.11
- -

Example 5: Adding a Subnet to the VPN

-

Suppose you wish to secure traffic to a subnet 192.0.2.192/29 behind - a FreeS/WAN box 192.0.2.12.

-

First, add DNS entries to configure 192.0.2.12 as an opportunistic - gateway for that subnet. Instructions are in our - quickstart guide. Next, create a private-net group on - 192.0.2.12 as described in Example 4.

-

On each other host, add the subnet 192.0.2.192/29 to private -, yielding for example

-
    [root@xy root]# cd /etc/ipsec.d/policies
-    [root@xy policies]# cat private
-        192.0.2.9              # several hosts at example.com
-        192.0.2.11
-        192.0.2.12             # HR department gateway
-        192.0.2.192/29         # HR subnet
-        irc.private.example.com
-
-

and reread policy groups with

-
    ipsec auto --rereadgroups
-

That's all the configuration you need.

-

Test your VPN by pinging from a machine on 192.0.2.192/29 to any - other host:

-
    [root@192.0.2.194]# ping 192.0.2.11
-

After a second or two, traffic should flow, and

-
    ipsec eroute
-

should yield something like

-
    192.0.2.11/32   -> 192.0.2.194/32  => tun0x149f@192.0.2.12
-
-

Key:

- - - - - -
1.192.0.2.11/32Local start point of the - protected traffic.
2.192.0.2.194/32Remote end point of the - protected traffic.
3.192.0.2.12Remote FreeS/WAN node (gateway or - host). May be the same as (2).
4.[not shown]Local FreeS/WAN node (gateway or - host), where you've produced the output. May be the same as (1).
-

For additional assurance, you can verify with a packet sniffer that - the traffic is being encrypted.

-

Note

- -

Appendix

- -

Our Hidden Connections

-

Our Base Policy Groups are created using hidden connections. These - are spelled out in man ipsec.conf - and defined in /usr/local/lib/ipsec/_confread.

- -

Custom Policy Groups

-

A policy group is built using a special connection description in - ipsec.conf, which:

- -

To create a new group:

-
    -
  1. Create its connection definition in ipsec.conf.
    2. -
  2. Create a Policy Group file in /etc/ipsec.d/policies with - the same name as your connection.
    3. -
  3. Put a CIDR block in that file.
    4. -
  4. Reread groups with ipsec auto --rereadgroups.
    5. -
  5. Test: ping to activate any OE connection, and view - results with ipsec eroute.
    6. -
- -

Disabling Opportunistic Encryption

-

To disable OE (eg. policy groups and packetdefault), cut and paste - the following lines to /etc/ipsec.conf:

-
conn block
-    auto=ignore
-
-conn private
-    auto=ignore
-
-conn private-or-clear
-    auto=ignore
-
-conn clear-or-private
-    auto=ignore
-
-conn clear
-    auto=ignore
-
-conn packetdefault
-    auto=ignore
-

Restart FreeS/WAN so that the changes take effect:

-
    ipsec setup restart
-
-Contents -Previous -Next - - diff --git a/doc/politics.html b/doc/politics.html deleted file mode 100644 index 5dd1e9f96..000000000 --- a/doc/politics.html +++ /dev/null @@ -1,1231 +0,0 @@ - - - -Introduction to FreeS/WAN - - - - -Contents -Previous -Next -
-

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 - several. Two I particularly like are:

- -

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.

- -

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:

- -

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:

- -

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:

- -

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:

- -

Of course governments are by no means the only threat to privacy and - security on the net. Other threats include:

- -

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. See the UN's - Universal Declaration of Human Rights, article twelve:

-
No one shall be subjected to arbitrary interference with - his privacy, family, home or correspondence, nor to attacks upon his - honor and reputation. Everyone has the right to the protection of the - law against such interference or attacks.
-

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:

- -

For more on these issues see:

- -

There are several collections of crypto - quotes on the net.

-

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

- -

and discussions of:

- -

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:

- -

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 a little key - she kept it in escrow,
-  and every thing that Mary said,
-  the feds were sure to know.
-

A crypto quotes page attributes this to Sam Simpson.

-

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:

- -

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:

- -

This is utter nonsense.

-

Weak systems touted include:

- -

The notion that choice of ciphers or keysize should be determined by - a trade-off between security requirements and overheads is pure - bafflegab.

- -

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.

-
   Mary had a little key (It's all she could export),
-   and all the email that she sent was opened at the Fort.
-

A crypto quotes page attributes this to Ron Rivest. NSA - headquarters is at Fort Meade, Maryland.

-

Our policy in FreeS/WAN is to use only cryptographic components with - adequate keylength and no known weaknesses.

- -

Detailed discussion of which IPsec features we implement or omit is - in out compatibility document.

-

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.

-

Some real trade-offs

-

Of course, making systems secure does involve costs, and trade-offs - can be made between cost and security. However, the real trade-offs - have nothing to do with using weaker ciphers.

-

There can be substantial hardware and software costs. There are often - substantial training costs, both to train administrators and to - increase user awareness of security issues and procedures. There are - almost always substantial staff or contracting costs.

-

Security takes staff time for planning, implementation, testing 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. EvilDoers - will know about new attacks shortly after they are found. You need - to know about them before your systems are attacked. If your vendor - provides a patch, you need to apply it. If the vendor does nothing, you - need to complain or start looking for another vendor.

-

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.

-

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.

-

Compared to those costs, cipher overheads are an insignificant factor - in the cost of security.

-

The only thing using a weak cipher can do for you is to cause all - your other investment to be wasted.

-

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

-

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. 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
The NSA regularly lies to people - who ask it for advice on export control. They have no reason not to; - accomplishing their goal by any legal means is fine by them. Lying by - government employees is legal. -
John Gilmore.
-

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:

-
... various governments have actual or proposed policies on - access to cryptographic technology ... -

(a) ... export controls ... -
(b) ... short cryptographic keys ... -
(c) ... keys should be in the hands of the government or ... -
(d) prohibit the use of cryptology ...

-

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

-

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. The abstract from that document is:

-
The Internet Engineering Task Force (IETF) has been asked - to take a position on the inclusion into IETF standards-track documents - of functionality designed to facilitate wiretapping. -

This memo explains what the IETF thinks the question means, why its - answer is "no", and what that answer means.

-
A quote from the debate leading up to that RFC:
- 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 Raven - mailing list was set up for this IETF discussion.

-

Our goal is to go beyond that RFC 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. -
  2. "In the public domain".
    3. -
-
-

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.

- -

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 - 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, - they may have had DES crackers for years, and theirs may be much - faster. It is difficult to make most computer applications work well on - parallel machines, or to design specialised hardware to accelerate - them. Cipher-cracking is one of the very few exceptions. It is entirely - straightforward to speed up cracking by just adding hardware. 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 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 spectacularly incompetent or horribly - underfunded, they can certainly break it, but we cannot guess how - quickly. Pick any time unit between days and milliseconds; none 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.

-

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. Certainly - those countries have some fine mathematicians, and those agencies had - budget. 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

- -

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

-

The winner, announced in October 2000 after several years of analysis - and discussion, was the - Rijndael cipher from two Belgian designers.

-

It is almost certain that FreeS/WAN will add AES support. - AES patches are already available.

-

Press coverage of Linux FreeS/WAN:

-

FreeS/WAN 1.0 press

- -

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.
-
-Contents -Previous -Next - - diff --git a/doc/quickstart.html b/doc/quickstart.html deleted file mode 100644 index 44d73abc5..000000000 --- a/doc/quickstart.html +++ /dev/null @@ -1,323 +0,0 @@ - - - -Introduction to FreeS/WAN - - - - -Contents -Previous -Next -
-

Quickstart Guide to Opportunistic Encryption -

- -

Purpose

-

This page will get you started using Linux FreeS/WAN with - opportunistic encryption (OE). OE enables you to set up IPsec tunnels - without co-ordinating with another site administrator, and without hand - configuring each tunnel. If enough sites support OE, a "FAX effect" - occurs, and many of us can communicate without eavesdroppers.

-

OE "flag day"

-

As of FreeS/WAN 2.01, OE uses DNS TXT resource records (RRs) only - (rather than TXT with KEY). This change causes a - "flag day". Users of FreeS/WAN 2.00 (or earlier) OE who are - upgrading may require additional resource records, as detailed in our - upgrading document. OE setup instructions here are for 2.02 or - later.

-

Requirements

-

To set up opportunistic encryption, you will need:

- -

Note: Currently, only Linux FreeS/WAN supports opportunistic - encryption.

-

RPM install

-

Our instructions are for a recent Red Hat with a 2.4-series stock or - Red Hat updated kernel. For other ways to install, see our - install document.

-

Download RPMs

-

If we have prebuilt RPMs for your Red Hat system, this command will - get them:

-
    ncftpget ftp://ftp.xs4all.nl/pub/crypto/freeswan/binaries/RedHat-RPMs/`uname -r | tr -d 'a-wy-z'`/\*
-

If that fails, you will need to try another - install method. Our kernel modules will only work on the Red Hat - kernel they were built for, since they are very sensitive to small - changes in the kernel.

-

If it succeeds, you will have userland tools, a kernel module, and an - RPM signing key:

-
    freeswan-module-2.04_2.4.20_20.9-0.i386.rpm
-    freeswan-userland-2.04_2.4.20_20.9-0.i386.rpm
-    freeswan-rpmsign.asc
-

Check signatures

-

If you're running RedHat 8.x or later, import the RPM signing key - into the RPM database:

-
    rpm --import freeswan-rpmsign.asc
-

For RedHat 7.x systems, you'll need to add it to your - PGP keyring:

-
    pgp -ka freeswan-rpmsign.asc
-

Check the digital signatures on both RPMs using:

-
    rpm --checksig freeswan*.rpm
-

You should see that these signatures are good:

-
    freeswan-module-2.04_2.4.20_20.9-0.i386.rpm: pgp md5 OK
-    freeswan-userland-2.04_2.4.20_20.9-0.i386.rpm: pgp md5 OK
-

Install the RPMs

-

Become root:

-
    su
-

Install your RPMs with:

-

-
    rpm -ivh freeswan*.rpm
-

If you're upgrading from FreeS/WAN 1.x RPMs, and have problems with - that command, see this note -.

-

Then, start FreeS/WAN:

-
    service ipsec start
-

Test

-

To check that you have a successful install, run:

-
    ipsec verify
-

You should see as part of the verify output:

-
-    Checking your system to see if IPsec got installed and started correctly
-    Version check and ipsec on-path                             [OK]
-    Checking for KLIPS support in kernel                        [OK]
-    Checking for RSA private key (/etc/ipsec.secrets)           [OK]
-    Checking that pluto is running                              [OK]
-    ...
-

If any of these first four checks fails, see our - troubleshooting guide.

-

Our Opportunistic Setups

-

Full or partial opportunism?

-

Determine the best form of opportunism your system can support.

- -

Initiate-only setup

-

Restrictions

-

When you set up initiate-only Opportunistic Encryption (iOE):

- -

You cannot network a group of initiator-only machines if none of - these is capable of responding to OE. If one is capable of responding, - you may be able to create a hub topology using routing.

-

Create and publish a forward DNS record

-

Find a domain you can use

-

Find a DNS forward domain (e.g. example.com) where you can publish - your key. You'll need access to the DNS zone files for that domain. - This is common for a domain you own. Some free DNS providers, such as - this one, also provide this service.

-

Dynamic IP users take note: the domain where you place your key need - not be associated with the IP address for your system, or even with - your system's usual hostname.

-

Choose your ID

-

Choose a name within that domain which you will use to identify your - machine. It's convenient if this can be the same as your hostname:

-
    [root@xy root]# hostname --fqdn
-    xy.example.com
-

This name in FQDN (fully-qualified domain name) format will be your - ID, for DNS key lookup and IPsec negotiation.

-

Create a forward TXT record

-

Generate a forward TXT record containing your system's public key - with a command like:

-
    ipsec showhostkey --txt @xy.example.com
-

using your chosen ID in place of xy.example.com. This command takes - the contents of /etc/ipsec.secrets and reformats it into something - usable by ISC's BIND. The result should look like this (with the key - data trimmed down for clarity):

-
-    ; RSA 2192 bits   xy.example.com   Thu Jan  2 12:41:44 2003
-        IN      TXT     "X-IPsec-Server(10)=@xy.example.com" 
-    "AQOF8tZ2... ...+buFuFn/"
-
-

Publish the forward TXT record

-

Insert the record into DNS, or have a system adminstrator do it for - you. It may take up to 48 hours for the record to propagate, but it's - usually much quicker.

-

Test that your key has been published

-

Check your DNS work

-
    ipsec verify --host xy.example.com
-

As part of the verify output, you ought to see something - like:

-
    ...
-    Looking for TXT in forward map: xy.example.com          [OK]
-    ...
-

For this type of opportunism, only the forward test is relevant; you - can ignore the tests designed to find reverse records.

-

Configure, if necessary

-

If your ID is the same as your hostname, you're ready to go. - FreeS/WAN will use its built-in connections - to create your iOE functionality.

-

If you have chosen a different ID, you must tell FreeS/WAN about it - via ipsec.conf:

-
    config setup
-        myid=@myname.freedns.example.com
-

and restart FreeS/WAN:

-
    service ipsec restart
-

The new ID will be applied to the built-in connections.

-

Note: you can create more complex iOE configurations as explained in - our policy groups document -, or disable OE using - these instructions.

-

Test

-

That's it! Test your connections.

- -

Full Opportunism

-

Full opportunism allows you to initiate and receive opportunistic - connections on your machine.

- -

Put a TXT record in a Forward Domain

-

To set up full opportunism, first set up a - forward TXT record as for initiator-only OE -, using an ID (for example, your hostname) that resolves to your IP. Do - not configure /etc/ipsec.conf, but continue with the - instructions for full opportunism, below.

-

Note that this forward record is not currently necessary for full OE, - but will facilitate future features.

- -

Put a TXT record in Reverse DNS

-

You must be able to publish your DNS RR directly in the reverse - domain. FreeS/WAN will not follow a PTR which appears in the reverse, - since a second lookup at connection start time is too costly.

-

Create a Reverse DNS TXT record

-

This record serves to publicize your FreeS/WAN public key. In - addition, it lets others know that this machine can receive - opportunistic connections, and asserts that the machine is authorized - to encrypt on its own behalf.

-

Use the command:

-
    ipsec showhostkey --txt 192.0.2.11
-

where you replace 192.0.2.11 with your public IP.

-

The record (with key shortened) looks like:

-
    ; RSA 2048 bits  xy.example.com   Sat Apr 15 13:53:22 2000
-    IN TXT  "X-IPsec-Server(10)=192.0.2.11" " AQOF8tZ2...+buFuFn/"
-

Publish your TXT record

-

Send these records to your ISP, to be published in your IP's reverse - map. It may take up to 48 hours for these to propagate, but usually - takes much less time.

-

Test your DNS record

-

Check your DNS work with

-
    ipsec verify --host xy.example.com
-

As part of the verify output, you ought to see something - like:

-
    ...
-    Looking for TXT in reverse map: 11.2.0.192.in-addr.arpa [OK]
-    ...
-

which indicates that you've passed the reverse-map test.

-

No Configuration Needed

-

FreeS/WAN 2.x ships with full OE enabled, so you don't need to - configure anything. To enable OE out of the box, FreeS/WAN 2.x uses the - policy group private-or-clear, which creates IPsec - connections if possible (using OE if needed), and allows traffic in the - clear otherwise. You can create more complex OE configurations as - described in our policy groups - document, or disable OE using - these instructions.

-

If you've previously configured for initiator-only opportunism, - remove myid= from config setup, so that peer - FreeS/WANs will look up your key by IP. Restart FreeS/WAN so that your - change will take effect, with

-
    service ipsec restart
-

Consider Firewalling

-

If you are running a default install of RedHat 8.x, take note: you - will need to alter your iptables rule setup to allow IPSec traffic - through your firewall. See our - firewall document for sample iptables rules.

-

Test

-

That's it. Now, test your connection.

-

Test

-

Instructions are in the next section.

-

Testing opportunistic connections

-

Be sure IPsec is running. You can see whether it is with:

-
    ipsec setup status
-

If need be, you can restart it with:

-
    service ipsec restart
-

Load a FreeS/WAN test website from the host on which you're running - FreeS/WAN. Note: the feds may be watching these sites. Type one of:

-

-
   links oetest.freeswan.org
-
   links oetest.freeswan.nl
- - -

A positive result looks like this:

-
-   You  seem  to  be  connecting  from:  192.0.2.11 which DNS says is:
-   gateway.example.com
-     _________________________________________________________________
-
-   Status E-route
-   OE    enabled    16    192.139.46.73/32    ->    192.0.2.11/32   =>
-   tun0x2097@192.0.2.11
-   OE    enabled    176    192.139.46.77/32    ->   192.0.2.11/32   =>
-   tun0x208a@192.0.2.11
-
-

If you see this, congratulations! Your OE host or gateway will now - encrypt its own traffic whenever it can. For more OE tests, please see - our testing document. If you have - difficulty, see our OE troubleshooting tips.

-

Now what?

-

Please see our policy groups document - for more ways to set up Opportunistic Encryption.

-

You may also wish to make some pre-configured - connections.

-

Notes

- - -

Troubleshooting OE

-

See the OE troubleshooting hints in our - troubleshooting guide.

- -

Known Issues

-

Please see this list of known - issues with Opportunistic Encryption.

-
-Contents -Previous -Next - - diff --git a/doc/rfc.html b/doc/rfc.html deleted file mode 100644 index 29785d8de..000000000 --- a/doc/rfc.html +++ /dev/null @@ -1,135 +0,0 @@ - - - -Introduction to FreeS/WAN - - - - -Contents -Previous -Next -
-

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:

- -

browsable in HTML form at others such as:

- -

and some of them are available in translation:

- -

There is also a published Big Book of - IPSEC RFCs.

-

Internet Drafts

-

Internet Drafts, working documents which sometimes evolve into RFCs, - are also available.

- -

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

-

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
-
-Contents -Previous -Next - - diff --git a/doc/roadmap.html b/doc/roadmap.html deleted file mode 100644 index ce547582c..000000000 --- a/doc/roadmap.html +++ /dev/null @@ -1,167 +0,0 @@ - - - -Introduction to FreeS/WAN - - - - -Contents -Previous -Next -
-

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

-
-Contents -Previous -Next - - diff --git a/doc/src/.cvsignore b/doc/src/.cvsignore deleted file mode 100644 index 3ed29bc59..000000000 --- a/doc/src/.cvsignore +++ /dev/null @@ -1,3 +0,0 @@ -foo.xml -foobar.html -makecheck-2.html diff --git a/doc/src/adv_config.html b/doc/src/adv_config.html deleted file mode 100644 index ab6901b5e..000000000 --- a/doc/src/adv_config.html +++ /dev/null @@ -1,1412 +0,0 @@ - - - - Advanced FreeS/WAN configuration - - - - - -

Other configuration possibilities

- -

This document describes various options for FreeS/WAN configuration which -are less used or more complex (often both) than the standard cases described -in our config and -quickstart documents.

- -

Some rules of thumb about configuration

- -

Tunnels are cheap

- -

Nearly all of the overhead in IPsec processing is in the encryption and -authentication of packets. Our performance -document discusses these overheads.

- -

Beside those overheads, the cost of managing additional tunnels is -trivial. Whether your gateway supports one tunnel or ten just does not -matter. A hundred might be a problem; there is a section on this in the performance -document.

- -

So, in nearly all cases, if using multiple tunnels gives you a reasonable -way to describe what you need to do, you should describe it that way in your -configuration files.

- -

For example, one user recently asked on a mailing list about this network -configuration:

-
        netA---gwA---gwB---netB
-                            |----netC
-
-   netA and B are secured netC not.
-   netA and gwA can not access netC
- -

The user had constructed only one tunnel, netA to netB, and wanted to know -how to use ip-route to get netC packets into it. This is entirely -unnecessary. One of the replies was:

-
  The simplest way and indeed the right way to
-  solve this problem is to set up two connections:
-
-        leftsubnet=NetA
-        left=gwA
-        right=gwB
-        rightsubnet=NetB
-  and
-        leftsubnet=NetA
-        left=gwA
-        right=gwB
-        rightsubnet=NetC
- -

This would still be correct even if we added nets D, E, F, -... to the above diagram and needed twenty tunnels.

- -

Of course another possibility would be to just use one tunnel, with a -subnet mask that includes both netB and netC (or B, C, D, ...). See next -section.

- -

In general, you can construct as many tunnels as you need. Networks like -netC in this example that do not connect directly to the gateway are fine, as -long as the gateway can route to them.

- -

The number of tunnels can become an issue if it reaches 50 or so. This is -discussed in the performance document. -Look there for information on supporting hundreds of Road Warriors from one -gateway.

- -

If you find yourself with too many tunnels for some reason like having -eight subnets at one location and nine at another so you end up with -9*8=72 tunnels, read the next section here.

- -

Subnet sizes

- -

The subnets used in leftsubnet and rightsubnet can -be of any size that fits your needs, and they need not correspond to physical -networks.

- -

You adjust the size by changing the subnet -mask, the number after the slash in the subnet description. For -example

- - -

As an example of using these in connection descriptions, suppose your -company's head office has four physical networks using the address ranges:

-
-
192.168.100.0/24
-
development
-
192.168.101.0/24
-
production
-
192.168.102.0/24
-
marketing
-
192.168.103.0/24
-
administration
-
- -

You can use exactly those subnets in your connection descriptions, or use -larger subnets to grant broad access if required:

-
-
leftsubnet=192.168.100.0/24
-
remote hosts can access only development
-
leftsubnet=192.168.100.0/23
-
remote hosts can access development or production
-
leftsubnet=192.168.102.0/23
-
remote hosts can access marketing or administration
-
leftsubnet=192.168.100.0/22
-
remote hosts can access any of the four departments
-
- -

or use smaller subnets to restrict access:

-
-
leftsubnet=192.168.103.0/24
-
remote hosts can access any machine in administration
-
leftsubnet=192.168.103.64/28
-
remote hosts can access only certain machines in administration.
-
leftsubnet=192.168.103.42/32
-
remote hosts can access only one particular machine in - administration
-
- -

To be exact, 192.68.103.64/28 means all addresses whose top 28 bits match -192.168.103.64. There are 16 of these because there are 16 possibilities for -the remainingg 4 bits. Their addresses are 192.168.103.64 to -192.168.103.79.

- -

Each connection description can use a different subnet if required.

- -

It is possible to use all the examples above on the same FreeS/WAN -gateway, each in a different connection description, perhaps for different -classes of user or for different remote offices.

- -

It is also possible to have multiple tunnels using different -leftsubnet descriptions with the same right. For -example, when the marketing manager is on the road he or she might have -access to:

-
-
leftsubnet=192.168.102.0/24
-
all machines in marketing
-
192.168.101.32/29
-
some machines in production
-
leftsubnet=192.168.103.42/32
-
one particular machine in administration
-
- -

This takes three tunnels, but tunnels are cheap. If the laptop is set up -to build all three tunnels automatically, then he or she can access all these -machines concurrently, perhaps from different windows.

- -

Other network layouts

- -

Here is the usual network picture for a site-to-site VPN::

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

and for the Road Warrior::

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

Other configurations are also possible.

- -

The Internet as a big subnet

- -

A telecommuter might have:

-
     Sunset==========West------------------East ================= firewall --- the Internet
-         home network      untrusted net        corporate network
- -

This can be described as a special case of the general subnet-to-subnet -connection. The subnet on the right is 0.0.0.0/0, the whole Internet.

- -

West (the home gateway) can have its firewall rules set up so that only -IPsec packets to East are allowed out. It will then behave as if its only -connection to the world was a wire to East.

- -

When machines on the home network need to reach the Internet, they do so -via the tunnel, East and the corporate firewall. From the viewpoint of the -Internet (perhaps of some EvilDoer trying to break in!), those home office -machines are behind the firewall and protected by it.

- -

Wireless

- -

Another possible configuration comes up when you do not trust the local -network, either because you have very high security standards or because your -are using easily-intercepted wireless signals.

- -

Some wireless networks have built-in encryption called WEP, but its security is dubious. It is a fairly -common practice to use IPsec instead.

- -

In this case, part of your network may look like this:

-
          West-----------------------------East == the rest of your network
-     workstation   untrusted wireless net
- -

Of course, there would likely be several wireless workstations, each with -its own IPsec tunnel to the East gateway.

- -

The connection descriptions look much like Road Warrior descriptions:

- - -

The rightsubnet= parameter might be set in any of several -ways:

-
-
rightsubnet=0.0.0.0/0
-
allowing workstations to access the entire Internet (see above)
-
rightsubnet=a.b.c.0/24
-
allowing access to your entire local network
-
rightsubnet=a.b.c.d/32
-
restricting the workstation to connecting to a particular server
-
- -

Of course you can mix and match these as required. For example, a -university might allow faculty full Internet access while letting student -laptops connect only to a group of lab machines.

- -

Choosing connection types

- -

One choice 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 --up 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: - -

A third method, using RSA keys embedded in X.509 certtificates, is provided by - user patches.

-
-
- -

Manually keyed connections provide -weaker security than automatically keyed -connections. An opponent who reads ipsec.secrets(5) gets your encryption key -and can read all data encrypted by it. If he or she has an archive of old -messages, all of them back to your last key change are also readable.

- -

With automatically-(re)-keyed connections, an opponent who reads -ipsec.secrets(5) gets the key used to authenticate your system in IKE -- the -shared secret or your private key, depending what authentication mechanism is -in use. However, he or she does not automatically gain access to any -encryption keys or any data.

- -

An attacker who has your authentication key can mount a man-in-the-middle attack and, if that -succeeds, he or she will get encryption keys and data. This is a serious -danger, but it is better than having the attacker read everyting as soon as -he or she breaks into ipsec.secrets(5).. Moreover, the keys change often so -an opponent who gets one key does not get a large amount of data. To read all -your data, he or she would have to do a man-in-the-middle attack at every key -change.

- -

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 may also be useful for testing. There is some discussion of -this in our FAQ.

- -

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 support two -basic methods for this authentication:

- - -

There are, howver, several variations on the RSA theme, using different -methods of managing the RSA keys:

- - -

Public keys in ipsec.conf(5) -give a reasonably straightforward method of specifying keys for explicitly -configured connections.

- -

Putting public keys in DNS allows us to support opportunistic encryption. Any two -FreeS/WAN gateways can provide secure communication, without either of them -having any preset information about the other.

- -

X.509 certificates may be required to interface to various PKIs.

- -

Advantages of public key methods

- -

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

- - -

There is also a disadvantage:

- - -

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.

- -

What I call "shared secrets" are sometimes also called "pre-shared keys". -They are used only for for authentication, never for encryption. Calling them -"pre-shared keys" has confused some users into thinking they were encryption -keys, so I prefer to avoid the term..

- -

If you are interoperating with another IPsec implementation, you may find -its documentation calling them "passphrases".

- -

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:

- - -

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-shared 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. This is discussed in -more detail above.

- -

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.

- - -

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:

- - -

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:

- - -

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

An Opportunistic Gateway

- -

Start from full opportunism

- -

Full opportunism -allows you to initiate and receive opportunistic connections on your -machine. The remaining instructions in this section assume -you have first set up full opportunism on your gateway using -these instructions. -Both sets of instructions require mailing DNS records to your ISP. Collect -DNS records for both the gateway (above) and the -subnet nodes (below) before contacting your ISP.

- - -

Reverse DNS TXT records for each protected machine

- -

You need these so that your Opportunistic peers can: -

- -

On the gateway, generate a TXT record with: -

    ipsec showhostkey --txt 192.0.2.11
-

Use your gateway address in place of 192.0.2.11.

- -

You should see (keys are trimmed for clarity throughout our example):

-
    ; RSA 2048 bits  gateway.example.com   Sat Apr 15 13:53:22 2000
-    IN TXT  "X-IPsec-Server(10)=192.0.2.11" " AQOF8tZ2...+buFuFn/"
- -

This MUST BE the same key as in your gateway's TXT record, or nothing -will work.

- -

In a text file, make one copy of this TXT record for each subnet - node:

-
    ; RSA 2048 bits  gateway.example.com   Sat Apr 15 13:53:22 2000
-    IN TXT  "X-IPsec-Server(10)=192.0.2.11" " AQOF8tZ2...+buFuFn/"
-                                                                                
-    ; RSA 2048 bits  gateway.example.com   Sat Apr 15 13:53:22 2000
-    IN TXT  "X-IPsec-Server(10)=192.0.2.11" " AQOF8tZ2...+buFuFn/"
-                                                                                
-    ; RSA 2048 bits  gateway.example.com   Sat Apr 15 13:53:22 2000
-    IN TXT  "X-IPsec-Server(10)=192.0.2.11" " AQOF8tZ2...+buFuFn/"
- -

Above each entry, insert a line like this:

-
    98.2.0.192.in-addr.arpa. IN PTR arthur.example.com.
- -

It must include:

- - -

The result will be a file of TXT records, like this:

-
    98.2.0.192.in-addr.arpa. IN PTR arthur.example.com.
-    ; RSA 2048 bits  gateway.example.com   Sat Apr 15 13:53:22 2000
-    IN TXT  "X-IPsec-Server(10)=192.0.2.11" " AQOF8tZ2...+buFuFn/"
-                                                                                
-    99.2.0.192.in-addr.arpa. IN PTR ford.example.com.
-    ; RSA 2048 bits  gateway.example.com   Sat Apr 15 13:53:22 2000
-    IN TXT  "X-IPsec-Server(10)=192.0.2.11" " AQOF8tZ2...+buFuFn/"
-                                                                                
-    100.2.0.192.in-addr.arpa. IN PTR trillian.example.com.
-    ; RSA 2048 bits  gateway.example.com   Sat Apr 15 13:53:22 2000
-    IN TXT  "X-IPsec-Server(10)=192.0.2.11" " AQOF8tZ2...+buFuFn/"
- - -

Publish your records

- -

Ask your ISP to publish all the reverse DNS records you have collected. -There may be a delay of up to 48 hours as the records propagate.

- - -

...and test them

- -

Check a couple of records with commands like this one:

- -
    ipsec verify --host ford.example.com
-    ipsec verify --host trillian.example.com
- -

The verify command checks for TXT records for both the -subnet host and its gateway. You should see output like:

-
    ...
-    Looking for TXT in reverse map: 99.2.0.192.in-addr.arpa [OK]
-    ...
-    Looking for TXT in reverse map: 11.2.0.192.in-addr.arpa   [OK]
-    ...
-    Looking for TXT in reverse map: 100.2.0.192.in-addr.arpa [OK]
-    ...
-    Looking for TXT in reverse map: 11.2.0.192.in-addr.arpa   [OK]
-    ...
-

No Configuration Needed

- -

FreeS/WAN 2.x ships with a built-in, automatically -enabled OE connection conn packetdefault -which applies OE, if possible, to all outbound traffic routed -through the FreeS/WAN box. - -The -ipsec.conf(5) manual -describes this connection in detail. -While the effect is much the same as private-or-clear, -the implementation is different: notably, it does not use policy -groups.

- -

You can create more complex OE configurations -for traffic forwarded through a FreeS/WAN box, as explained in our -policy groups document, -or disable OE using -these instructions.

- - - -

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.

- -

As far as the Internet is concerned, your new extruded net is behind your -buddy's gateway. You route all your packets for the Internet at large -out his gateway, and receive return packets the same way. You route your -local packets locally.

- -

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

- -

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, you'll need to poke holes in your -firewall to allow packets through. -

- -

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

- -

Please note that Super -FreeS/WAN now features DHCP-over-IPsec, which is an alternate procedure -for Virtual IP address assignment. -

- -

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.

- - -

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.

- - -

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.

- - diff --git a/doc/src/background.html b/doc/src/background.html deleted file mode 100644 index e25b9da03..000000000 --- a/doc/src/background.html +++ /dev/null @@ -1,376 +0,0 @@ - - - - FreeS/WAN background - - - - - -

Linux FreeS/WAN background

- -

This section discusses a number of issues which have three things in -common:

- - -

Grouping them here lets us provide the explanations some users will need -without unduly complicating the main text.

- -

The explanations here are intended to be adequate for FreeS/WAN purposes -(please comment to the users mailing list if you -don't find them so), but they are not trying to be complete or definitive. If -you need more information, see the references provided in each section.

- -

Some DNS background

- -

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

- -

Much good reference material is available for DNS, including:

- - -

We give only a brief overview here, intended to help you use DNS for -FreeS/WAN purposes.

- -

Forward and reverse maps

- -

Although the implementation is distributed, it is often useful to speak of -DNS as if it were just two enormous tables:

- - -

Both maps can optionally contain additional data. For opportunistic -encryption, we insert the data need for IPsec authentication.

- -

A system named gateway.example.com with IP address 10.20.30.40 should have -at least two DNS records, one in each map:

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

Hierarchy and delegation

- -

For both maps there is a hierarchy of DNS servers and a system of -delegating authority so that, for example:

- - -

DNS zones are the units of delegation. There is a hierarchy of zones.

- -

Syntax of DNS records

- -

Returning to the example records:

-
        gateway.example.com. IN A 10.20.30.40
-        40.30.20.10.in-addr.arpa. IN PTR gateway.example.com.
- -

some syntactic details are:

- - -

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

- - -

To set up for opportunistic encryption, you add some TXT records -to your DNS data. Details are in our quickstart -document.

- -

Cacheing, TTL and propagation delay

- -

DNS information is extensively cached. With no caching, a lookup by your -system of "www.freeswan.org" might involve:

- - -

However, this can be a bit inefficient. For example, if you are in the -Phillipines, the closest a root server is in Japan. That might send you to a -.org server in the US, and then to freeswan.org in Holland. If everyone did -all those lookups every time they clicked on a web link, the net would grind -to a halt.

- -

Nameservers therefore cache information they look up. When you click on -another link at www.freeswan.org, your local nameserver has the IP address -for that server in its cache, and no further lookups are required.

- -

Intermediate results are also cached. If you next go to -lists.freeswan.org, your nameserver can just ask the freeswan.org nameserver -for that address; it does not need to query the root or .org nameservers -because it has a cached address for the freeswan.org zone server.

- -

Of course, like any cacheing mechanism, this can create problems of -consistency. What if the administrator for freeswan.org changes the IP -address, or the authentication key, for www.freeswan.org? If you use old -information from the cache, you may get it wrong. On the other hand, you -cannot afford to look up fresh information every time. Nor can you expect the -freeswan.org server to notify you; that isn't in the protocols.

- -

The solution that is in the protocols is fairly simple. Cacheable records -are marked with Time To Live (TTL) information. When the time expires, the -caching server discards the record. The next time someone asks for it, the -server fetches a fresh copy. Of course, a server may also discard records -before their TTL expires if it is running out of cache space.

- -

This implies that there will be some delay before the new version of a -changed record propagates around the net. Until the TTLs on all copies of the -old record expire, some users will see it because that is what is in their -cache. Other users may see the new record immediately because they don't have -an old one cached.

- -

Problems with packet fragmentation

- -

It seems, from mailing list reports, to be moderately common for problems -to crop up in which small packets pass through the IPsec tunnels just fine -but larger packets fail.

- -

These problems are caused by various devices along the way mis-handling -either packet fragments or path MTU -discovery.

- -

IPsec makes packets larger by adding an ESP or AH header. This can tickle -assorted bugs in fragment handling in routers and firewalls, or in path MTU -discovery mechanisms, and cause a variety of symptoms which are both annoying -and, often, quite hard to diagnose.

- -

An explanation from project technical lead Henry Spencer:

-
The problem is IP fragmentation; more precisely, the problem is that the
-second, third, etc. fragments of an IP packet are often difficult for
-filtering mechanisms to classify.
-
-Routers cannot rely on reassembling the packet, or remembering what was in
-earlier fragments, because the fragments may be out of order or may even
-follow different routes.  So any general, worst-case filtering decision
-pretty much has to be made on each fragment independently.  (If the router
-knows that it is the only route to the destination, so all fragments
-*must* pass through it, reassembly would be possible... but most routers
-don't want to bother with the complications of that.)
-
-All fragments carry roughly the original IP header, but any higher-level
-header is (for IP purposes) just the first part of the packet data... so
-only the first fragment carries that.  So, for example, on examining the
-second fragment of a TCP packet, you could tell that it's TCP, but not
-what port number it is destined for -- that information is in the TCP
-header, which appears in the first fragment only. 
-
-The result of this classification difficulty is that stupid routers and
-over-paranoid firewalls may just throw fragments away.  To get through
-them, you must reduce your MTU enough that fragmentation will not occur.
-(In some cases, they might be willing to attempt reassembly, but have very
-limited resources to devote to it, meaning that packets must be small and
-fragments few in number, leading to the same conclusion:  smaller MTU.)
- -

In addition to the problem Henry describes, you may also have trouble with -path MTU discovery.

- -

By default, FreeS/WAN uses a large MTU for -the ipsec device. This avoids some problems, but may complicate others. -Here's an explanation from Claudia:

-
Here are a couple of pieces of background information. Apologies if you
-have seen these already. An excerpt from one of my old posts:
-
-    An MTU of 16260 on ipsec0 is usual. The IPSec device defaults to this 
-    high MTU so that it does not fragment incoming packets before encryption 
-    and encapsulation. If after IPSec processing packets are larger than 1500,
-    [ie. the mtu of eth0] then eth0 will fragment them. 
-
-    Adding IPSec headers adds a certain number of bytes to each packet. 
-    The MTU of the IPSec interface refers to the maximum size of the packet
-    before the IPSec headers are added. In some cases, people find it helpful 
-    to set ipsec0's MTU to 1500-(IPSec header size), which IIRC is about 1430.
-
-    That way, the resulting encapsulated packets don't exceed 1500. On most 
-    networks, packets less than 1500 will not need to be fragmented.
-
-and... (from Henry Spencer)
-
-    The way it *ought* to work is that the MTU advertised by the ipsecN
-    interface should be that of the underlying hardware interface, less a
-    pinch for the extra headers needed. 
-
-    Unfortunately, in certain situations this breaks many applications.
-    There is a widespread implicit assumption that the smallest MTUs are 
-    at the ends of paths, not in the middle, and another that MTUs are 
-    never less than 1500.  A lot of code is unprepared to handle paths 
-    where there is an "interior minimum" in the MTU, especially when it's 
-    less than 1500. So we advertise a big MTU and just let the resulting 
-    big packets fragment.
-
-This usually works, but we do get bitten in cases where some intermediate
-point can't handle all that fragmentation.  We can't win on this one.
- -

The MTU can be changed with an overridemtu= statement in the -config setup section of ipsec.conf.5.

- -

For a discussion of MTU issues and some possible solutions using Linux -advanced routing facilities, see the Linux -2.4 Advanced Routing HOWTO. - -For a discussion of MTU and NAT (Network Address Translation), see -James Carter's MTU -notes.

- -

Network address translation (NAT)

- -

Network Address -Translation is a service provided by some gateway machines. -Calling it NAPT (adding the word Port) would be more -precise, but we will follow the widespread usage.

- -

A gateway doing NAT rewrites the headers of packets it is forwarding, -changing one or more of:

- - -

On Linux 2.4, NAT services are provided by the netfilter(8) firewall code. There are -several Netfilter -HowTos including one on NAT.

- -

For older versions of Linux, this was referred to as "IP masquerade" and -different tools were used. See this resource page.

- -

Putting an IPsec gateway behind a NAT gateway is not recommended. See our -firewalls document.

- -

NAT to non-routable addresses

- -

The most common application of NAT uses private non-routable addresses.

- -

Often a home or small office network will have:

- - -

Of course this poses a problem since several machines cannot use one -address. The best solution might be to obtain more addresses, but often this -is impractical or uneconomical.

- -

A common solution is to have:

- - -

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.

- -

As far as anyone else on the Internet is concerned, the systems behind the -gateway are completely hidden. Only one machine with one IP address is -visible.

- -

For IPsec on such a gateway, you can entirely ignore the NAT in:

- - -

Those can be set up exactly as they would be if your gateway had no other -systems behind it.

- -

You do, however, have to take account of the NAT in firewall rules which -affect packet forwarding.

- -

NAT to routable addresses

- -

NAT to routable addresses is also possible, but is less common and may -make for rather tricky routing problems. We will not discuss it here. See the -Netfilter -HowTos.

- - diff --git a/doc/src/biblio.html b/doc/src/biblio.html deleted file mode 100644 index d84e4c2cb..000000000 --- a/doc/src/biblio.html +++ /dev/null @@ -1,354 +0,0 @@ - - - - FreeS/WAN bibliography - - - - - -

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.

-
-Ross Anderson, Security Engineering - a Guide to -Building Dependable Distributed Systems
-Wiley, 2001, ISBN 0471389226 - -

Easily the best book for the security professional I have seen. -Highly recommended. See the book web page.

- -

This is quite readable, but Schneier's Secrets and -Lies might be an easier introduction.

-
-Bamford The Puzzle Palace, A report on NSA, Americas's -most Secret Agency
-Houghton Mifflin 1982 ISBN 0-395-31286-8 -
-Bamford Body of Secrets - -

The sequel.

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

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
- -
-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 book is now seriously out of date. It does not cover recent -developments such as commercial versions since PGP 5, the Open PGP standard -or GNU PG..

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

-
-Kolesnikov and Hatch, Building Linux Virtual -Private Networks (VPNs)
-New Riders 2002 - -

This has had a number of favorable reviews, including this -one on Slashdot. The book has a web site.

-
-Pete Loshin 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 MIT Press 1999 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.

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

- -

Note (Mar 1, 2002): a new edition with different editors in the works. -Expect it this year.

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

- -

This is worth reading even if you already understand security issues, or -think you do. To go deeper, follow it with Anderson's Security Engineering.

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

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

A good book, with detailed coverage of ipchains(8) firewalls and of many -related issues.

- - diff --git a/doc/src/buildtools.html b/doc/src/buildtools.html deleted file mode 100644 index c8cfa1fc8..000000000 --- a/doc/src/buildtools.html +++ /dev/null @@ -1,27 +0,0 @@ - - - - Tools used to build FreeSWAN releases (08-Mar-2002) - - - - - -

Tools used to build FreeSWAN releases

- -

man2html

- -

-If you are not running RedHat, you will need man2html. This is part of the -"man" RPM on RedHat, whose sources can be found at ftp://ftp.win.tue.nl/pub/linux-local/utils/man/. -

- -

-Note that the Debian package man2html -and the one listed on Freshmeat at -man2html will -not work. -

- - - \ No newline at end of file diff --git a/doc/src/compat.html b/doc/src/compat.html deleted file mode 100644 index a8e1455bf..000000000 --- a/doc/src/compat.html +++ /dev/null @@ -1,795 +0,0 @@ - - - - FreeS/WAN compatibility guide - - - - - -

Linux FreeS/WAN Compatibility Guide

- -

Much 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.96:

- - -

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 omitted

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

- - -

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:

- - -

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

- - -

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.

- -

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 the latest 2.2.x and 2.4.y

- -

We develop and test on Redhat Linux using the most recent kernel in the -2.2 and 2.4 series. In general, we recommend you use the latest kernel in one -of those series. Complications and caveats are discussed below.

- -

2.0.x 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 on 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 to 1.96
-
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.

- -

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 or -7.2 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. They are soluble, -but we recommend you upgrade to a later Redhat instead..

- -

Redhat 7 ships with two compilers.

- - -

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.

- -

FreeS/WAN packages distributed for SuSE 7.0-7.2 were somehow -miscompiled. You can find fixed packages on - -Kurt Garloff's page.

- -

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" ] && 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

- -

A recent (Nov 2001) mailing list points to a web page on setting up -several types of tunnel, including IPsec, on Debian.

- -

Some older information:

-
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 and later distributions, 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.
- -

FreeS/WAN no longer includes GMP source.

- -

Mklinux

- -

One user reports success on the Mach-based -microkernel 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 manufacture an IPsec box based on an -embedded MIPS running Linux with FreeS/WAN. We have no details.

- -

Transmeta Crusoe

- -

The Merilus Firecard, a Linux -firewall on a PCI card, is based on a Crusoe processor and supports -FreeS/WAN.

- -

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.

- -

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:

- - -

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.

- -

More recently, a patch to support some hardware accelerators has been -posted:

-
Subject: [Design] [PATCH] H/W acceleration patch
-   Date: Tue, 18 Sep 2001
-   From: "Martin Gadbois" <martin.gadbois@colubris.com>
- 
-Finally!!
-Here's a web site with H/W acceleration patch for FreeS/WAN 1.91, including
-S/W and Hifn 7901 crypto support.
-
-http://sources.colubris.com/
-
-Martin Gadbois
- -

Hardware accelerators could take performance well beyond what FreeS/WAN -can do in software (discussed here). Here is -some discussion off the IETF IPsec list, October 2001:

-
 ... Currently shipping chips deliver, 600 mbps throughput on a single
- stream of 3DES IPsec traffic.  There are also chips that use multiple
- cores to do 2.4 gbps.  We (Cavium) and others have announced even faster
- chips. ... Mid 2002 versions will handle at line rate (OC48 and OC192)
- IPsec and SSL/TLS traffic not only 3DES CBC but also AES and arc4.
- -

The patches to date support chips that have been in production for some -time, not the state-of-the-art latest-and-greatest devices described in that -post. However, they may still outperform software and they almost certainly -reduce CPU overhead.

- -

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, and a -patched version with IPv6 support is available. For -more recent information, check the mailing list.

- -

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:

- - -

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:

- - -

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.

- - diff --git a/doc/src/config.html b/doc/src/config.html deleted file mode 100644 index b98e452db..000000000 --- a/doc/src/config.html +++ /dev/null @@ -1,394 +0,0 @@ - - - - FreeS/WAN configuration - - - - -

How to configure FreeS/WAN

- -

This page will teach you how to configure a simple network-to-network -link or a Road Warrior connection between two Linux FreeS/WAN boxes. -

- -

See also these related documents:

- -

-The network-to-network setup allows you to connect two office -networks into one Virtual Private Network, while the Road Warrior -connection secures a laptop's telecommute to work. -Our examples also show the basic procedure on the Linux FreeS/WAN side where -another IPsec peer is in play.

- -

-Shortcut to net-to-net.
-Shortcut to Road Warrior. -

- -

Requirements

- -

To configure the network-to-network connection you must have:

- -

For the Road Warrior you need:

- - -

If both IPs are dynamic, your situation is a bit trickier. Your best bet -is a variation on the Road Warrior, as described -in this mailing list message. - -

Net-to-Net connection

- - -

Gather information

- -

For each gateway, compile the following information:

- - - -

Get your leftrsasigkey

-

On your local Linux FreeS/WAN gateway, print your IPsec public key:

-
    ipsec showhostkey --left
-

The output should look like this (with the key shortened for easy - reading):

-
    # RSA 2048 bits   xy.example.com   Fri Apr 26 15:01:41 2002
-    leftrsasigkey=0sAQOnwiBPt...
- -

Don't have a key? Use -ipsec newhostkey -to create one. - -

...and your rightrsasigkey

-

Get a console on the remote side:

-
    ssh2 ab.example.com
-

In that window, type:

-
    ipsec showhostkey --right
-

You'll see something like:

-
    # RSA 2192 bits   ab.example.com   Thu May 16 15:26:20 2002
-    rightrsasigkey=0sAQOqH55O...
- -

Edit /etc/ipsec.conf

- -

Back on the local gate, copy our template to /etc/ipsec.conf. -(on Mandrake, /etc/freeswan/ipsec.conf). -Substitute the information you've gathered for our example data.

-
conn net-to-net
-    left=192.0.2.2                 # Local vitals
-    leftsubnet=192.0.2.128/29      # 
-    leftid=@xy.example.com         #   
-    leftrsasigkey=0s1LgR7/oUM...   #
-    leftnexthop=%defaultroute      # correct in many situations 
-    right=192.0.2.9                # Remote vitals
-    rightsubnet=10.0.0.0/24        #
-    rightid=@ab.example.com        # 
-    rightrsasigkey=0sAQOqH55O...   #
-    rightnexthop=%defaultroute     # correct in many situations
-    auto=add                       # authorizes but doesn't start this 
-                                   # connection at startup
- -

-"Left" and "right" should represent the machines that have FreeS/WAN installed -on them, and "leftsubnet" and "rightsubnet" machines that are being protected. -/32 is assumed for left/right and left/rightsubnet parameters. -

- -

Copy conn net-to-net to the remote-side /etc/ipsec.conf. -If you've made no other modifications to either ipsec.conf, -simply:

-
    scp2 ipsec.conf root@ab.example.com:/etc/ipsec.conf
- -

Start your connection

- -

Locally, type:

-
    ipsec auto --up net-to-net
- -

You should see:

-
    104 "net-net" #223: STATE_MAIN_I1: initiate
-    106 "net-net" #223: STATE_MAIN_I2: sent MI2, expecting MR2
-    108 "net-net" #223: STATE_MAIN_I3: sent MI3, expecting MR3
-    004 "net-net" #223: STATE_MAIN_I4: ISAKMP SA established
-    112 "net-net" #224: STATE_QUICK_I1: initiate
-    004 "net-net" #224: STATE_QUICK_I2: sent QI2, IPsec SA established
- -

The important thing is IPsec SA established. If you're -unsuccessful, see our -troubleshooting tips.

- - -

Do not MASQ or NAT packets to be tunneled

- -

If you are using IP masquerade or -Network Address Translation (NAT) -on either gateway, -you must now exempt the packets you wish to tunnel from this treatment. -For example, if you have a rule like:

- -
iptables -t nat -A POSTROUTING -o eth0 -s 10.0.0.0/24 -j MASQUERADE
-
- -

change it to something like:

-
iptables -t nat -A POSTROUTING -o eth0 -s 10.0.0.0/24 -d \! 192.0.2.128/29 -j MASQUERADE
- -

This may be necessary on both gateways.

- - -

Test your connection

- -

Sit at one of your local subnet nodes (not the gateway), and ping a subnet -node on the other (again, not the gateway).

- -
    ping fileserver.toledo.example.com
- -

While still pinging, go to the local gateway and snoop your outgoing -interface, for example:

-
    tcpdump -i ppp0
-

You want to see ESP (Encapsulating Security Payload) packets moving -back and forth between the two gateways at the same frequency as -your pings:

-
    19:16:32.046220 192.0.2.2 > 192.0.2.9: ESP(spi=0x3be6c4dc,seq=0x3)
-    19:16:32.085630 192.0.2.9 > 192.0.2.2: ESP(spi=0x5fdd1cf8,seq=0x6)
- -

If you see this, congratulations are in order! You have a tunnel which -will protect any IP data from one subnet -to the other, as it passes between the two gates. -If not, go and troubleshoot.

- -

Note: your new tunnel protects only net-net traffic, not -gateway-gateway, or gateway-subnet. If you need this (for example, if -machines on one net need to securely contact a fileserver on the -IPsec gateway), you'll need to create -extra connections.

- - -

Finishing touches

- -

Now that your connection works, name it something sensible, like:

-
conn winstonnet-toledonet
-

To have the tunnel come up on-boot, replace

-
    auto=add
-

with:

-
    auto=start
-

Copy these changes to the other side, for example:

-
    scp2 ipsec.conf root@ab.example.com:/etc/ipsec.conf
-

Enjoy!

- - - -

Road Warrior Configuration

- -

Gather information

- -

You'll need to know:

- - -

Get your leftrsasigkey...

-

On your laptop, print your IPsec public key:

-
    ipsec showhostkey --left
-

The output should look like this (with the key shortened for easy - reading):

-
    # RSA 2192 bits   road.example.com   Sun Jun  9 02:45:02 2002
-    leftrsasigkey=0sAQPIPN9uI...
- -

Don't have a key? See -these instructions. - - -

...and your rightrsasigkey

-

Get a console on the gateway:

-
    ssh2 xy.example.com
-

View the gateway's public key with:

-
    ipsec showhostkey --right
-

This will yield something like

-
    # RSA 2048 bits   xy.example.com   Fri Apr 26 15:01:41 2002
-    rightrsasigkey=0sAQOnwiBPt...
- - -

Customize /etc/ipsec.conf

- -

On your laptop, copy this template to /etc/ipsec.conf. -(on Mandrake, /etc/freeswan/ipsec.conf). -Substitute the information you've gathered for our example data.

-
conn road
-    left=%defaultroute             # Picks up our dynamic IP 
-    leftnexthop=%defaultroute      # 
-    leftid=@road.example.com       # Local information
-    leftrsasigkey=0sAQPIPN9uI...   #
-    right=192.0.2.10               # Remote information
-    rightsubnet=10.0.0.0/24        #
-    rightid=@xy.example.com        # 
-    rightrsasigkey=0sAQOnwiBPt...  #
-    auto=add                       # authorizes but doesn't start this
-                                   # connection at startup
- -

The template for the gateway is different. Notice how it -reverses left and right, in keeping with our -convention that Left is Local, -Right Remote. Be sure to switch your -rsasigkeys in keeping with this.

- -
    ssh2 xy.example.com
-    vi /etc/ipsec.conf
- -

and add:

- -
conn road
-    left=192.0.2.2                 # Gateway's information
-    leftid=@xy.example.com         #
-    leftsubnet=192.0.2.128/29      #
-    leftrsasigkey=0sAQOnwiBPt...   #
-    rightnexthop=%defaultroute     # correct in many situations
-    right=%any                     # Wildcard: we don't know the laptop's IP
-    rightid=@road.example.com      #
-    rightrsasigkey=0sAQPIPN9uI...  #
-    auto=add                       # authorizes but doesn't start this
-                                   # connection at startup
- - - -

Start your connection

- -

You must start the connection from the Road Warrior side. On your laptop, -type:

-
    ipsec auto --start net-to-net
- -

You should see:

-
104 "net-net" #223: STATE_MAIN_I1: initiate
-106 "road" #301: STATE_MAIN_I2: sent MI2, expecting MR2
-108 "road" #301: STATE_MAIN_I3: sent MI3, expecting MR3
-004 "road" #301: STATE_MAIN_I4: ISAKMP SA established
-112 "road" #302: STATE_QUICK_I1: initiate
-004 "road" #302: STATE_QUICK_I2: sent QI2, IPsec SA established
- -

Look for IPsec SA established. If you're -unsuccessful, see our -troubleshooting tips.

- - - -

Do not MASQ or NAT packets to be tunneled

- -

If you are using IP masquerade or -Network Address Translation (NAT) -on either gateway, -you must now exempt the packets you wish to tunnel from this treatment. -For example, if you have a rule like:

- -
iptables -t nat -A POSTROUTING -o eth0 -s 10.0.0.0/24 -j MASQUERADE
-
- -

change it to something like:

-
iptables -t nat -A POSTROUTING -o eth0 -s 10.0.0.0/24 -d \! 192.0.2.128/29 -j MASQUERADE
- - -

Test your connection

- -

From your laptop, ping a subnet node behind the remote gateway. Do not -choose the gateway itself for this test.

- -
    ping ns.winston.example.com
- -

Snoop the packets exiting the laptop, with a command like:

-
    tcpdump -i wlan0
-

You have success if you see (Encapsulating Security Payload) packets -travelling in both directions:

- -
    19:16:32.046220 192.0.2.2 > 192.0.2.9: ESP(spi=0x3be6c4dc,seq=0x3)
-    19:16:32.085630 192.0.2.9 > 192.0.2.2: ESP(spi=0x5fdd1cf8,seq=0x6)
- - -

If you do, great! Traffic between your Road Warrior and the net -behind your gateway is protected. -If not, see our -troubleshooting hints.

- -

Your new tunnel protects only traffic addressed to the net, not to -the IPsec gateway itself. If you need the latter, you'll want to make an -extra tunnel..

- -

Finishing touches

- -

On both ends, name your connection wisely, like:

-
conn mike-to-office
-

On the laptop only, replace

-
    auto=add
-

with:

-
    auto=start
-

so that you'll be connected on-boot.

-

Happy telecommuting!

- -

Multiple Road Warriors

- -

If you're using RSA keys, as we did in this example, you can add -as many Road Warriors as you like. The left/rightid -parameter lets Linux FreeS/WAN distinguish between multiple Road Warrior -peers, each with its own public key.

- -

The situation is different for shared secrets (PSK). During a -PSK negotiation, ID information is not available at the time Pluto -is trying to determine which secret to use, so, effectively, you can -only define one Roadwarrior connection. All your PSK road warriors -must therefore share one secret.

- - -

What next?

- -

Using the principles illustrated here, you can try variations such as: -

-

Or, look at some of our more complex configuration examples..

- - diff --git a/doc/src/crosscompile.html b/doc/src/crosscompile.html deleted file mode 100644 index c488957c8..000000000 --- a/doc/src/crosscompile.html +++ /dev/null @@ -1,105 +0,0 @@ - - - Cross Compiling FreeS/WAN - - - - - - -

Linux FreeS/WAN Cross Compiling Guide

- -

Overview

- -

-This document provides general instructions on how to cross compile -FreeS/WAN, -that is - compile it for another architecture (eg: StrongARM)

-
    -
  1. Setting up your environment.
    2. -
  2. Building.
    3. -
  3. Common Problems.
    4. -
-

Setting up your Environment

-

Enviroment Variables

-

There are a number of environment variables you can set to help facilitate -cross compiling FreeS/WAN. All examples will are using the bash shell. -

-

The following is an example of the how to set the environment variables if -you were cross compiling using the Embedix ARM toolchain, to build for an embedded -device like the Sharp Zaurus. Set these while you are in the FreeS/WAN directory. -It is often simpler to put the entire list into a script (eg: cross-setup.sh), and -then "source cross-setup.sh" or similar. -

-export ARCH=arm
-export CC=/opt/Embedix/tools/bin/arm-linux-gcc
-export LD=/opt/Embedix/tools/bin/arm-linux-ld
-export RANLIB=/opt/Embedix/tools/bin/arm-linux-ranlib 
-export AR=/opt/Embedix/tools/bin/arm-linux-ar 
-export AS=/opt/Embedix/tools/bin/arm-linux-as 
-export STRIP=/opt/Embedix/tools/bin/arm-linux-strip 
-export KERNELSRC=/zaurus/kernel-2.4.6
-export LD_LIBRARY_PATH=/opt/Embedix/tools/lib/gcc-lib/arm-linux/2.95.2/
-export PATH=$PATH:/opt/Embedix/tools/bin
-export DESTDIR=/zaurus/binaries
-
-In the example above, we setup all of the usual gcc + bin-utils programs, -as well as setting the LD_LIBRARY_PATH to our cross-compiled system libraries, -and DESTDIR to our output directory. -

- -

Kernel Source

-

Place a copy of the kernel source, setup for your target device somewhere on -your filesystem and set KERNELSRC= to this directory. You will need to prepare -your kernel source treefirst, by running "make menuconfig && make dep && make -modules". Once this is done, you can move on to building FreeS/WAN

- -

Building

-

The Make Process

-

There are two parts to building FreeS/WAN - the userland programs and utilities, -and the ipsec.o kernel module. Each can be built seperatly, making debugging the -build process simpler. -

-

Step 1 is to run "make programs". This will build the required libs -(libfreeswan.a) as well as all of the userland tools (pluto, whack, etc...). -Provided your environment variables are set correctly, you should see the output -using your specified gcc (arm-linux-gcc for our example), ld, as, ar and -ranlib.

-

If this completes successfully, you can run "make install" to install a copy of -all of the binaries, man pages and other documentation to DESTDIR.

-

Step 2 is to build the ipsec.o module. This is done with "make oldmod", which -should change into the KERNELSRC directory and then compile and link the required -files to generate an ipsec.o file. If this is successful, you will end up with an -ipsec.o file in your FreeS/WAN directory, under linux/net/ipsec/.

-

Remember to install this to /lib/modules/$kernelversion/kernel/net/ipsec/ on -your target machine.

- - - -

Common Problems Building

-

Here is a list of common problems/errors you may run into when cross compiling -FreeS/WAN.

- - -



-

- - diff --git a/doc/src/faq.html b/doc/src/faq.html deleted file mode 100644 index f62fc1c88..000000000 --- a/doc/src/faq.html +++ /dev/null @@ -1,2770 +0,0 @@ - - - - FreeS/WAN FAQ - - - - - -

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.

-
- -

Index of FAQ questions

- -
- -

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.

- -

To start setting it up, go to our quickstart -guide.

- -

Our web links document has information on IPsec for other systems.

- -

How do I report a problem or seek help?

- -
-
Read our troubleshooting document.
-

It may guide you to a solution. If not, see its -problem reporting section.

- -

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 users 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.
    • -
  • It is more likely to get a quick response. Developers may get behind on - email, or even ignore it entirely for a while, but a list message (given - a reasonable Subject: line) is certain to be read by a fair number of - people within hours.
    • -
  • It may also be important because of 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.
    • -
-
- -
Try irc.freenode.net#freeswan.
- -
-

FreeS/WAN developers, volunteers and users can often be found there. -Be patient and be -prepared to provide lots of information to support your question.

- -

If your question was really interesting, and you found an answer, -please share that with the class by posting to the -users mailing list. That way others with the -same problem can find your answer in the archives.

-
- -
Premium support is also available.
-
-

See the next several questions.

-
-
- -

Can I get ...

- -

Can I get an off-the-shelf system that includes -FreeS/WAN?

- -

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. Then consider hiring a consultant (see next -question) to help define your requirements.

- -

Can I hire consultants or staff who know -FreeS/WAN?

- -

If you want the help of a contractor, or to hire staff with FreeS/WAN -expertise, you could:

- - -

For companies offerring support, see the next question.

- -

Can I get commercial support?

- -

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.

- -

Release questions

- -

What is the current release?

- -

The current release is the highest-numbered tarball on our distribution site. Almost -always, any of the mirrors will have the -same file, though perhaps not for a day or so after a release.

- -

Unfortunately, the web site is not always updated as quickly as it should -be.

- -

When is the next release?

- -

We try to do a release approximately every six to eight weeks. -

- -

If pre-release tests fail and the fix appears complex, or more generally -if the code does not appear stable when a release is scheduled, we will just -skip that release.

- -

For serious bugs, we may bring out an extra bug-fix release. These get -numbers in the normal release series. For example, there was a bug found in -FreeS/WAN 1.6, so we did another release less than two weeks later. The -bug-fix release was called 1.7.

- -

Are there known bugs in the current release?

- -

Any problems we are aware of at the time of a release are documented in -the BUGS file for that release. You should also look at -the CHANGES file.

- -

Bugs discovered after a release are discussed on the mailing lists. The easiest way to check for any problems -in the current code would be to peruse the -List In Brief.

- -

Modifications and contributions

- -

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.

- -

Before investing much energy in any such project, we suggest that you

- - -

This may prevent duplicated effort, or lead to interesting -collaborations.

- -

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.

- -

Discussion of possible contributions takes place on the design mailing list.

- -

Is there detailed design documentation?

-There are: - - -

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.

- -

Will FreeS/WAN work in my environment?

- -

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 interoperation document devoted to this problem.

- -

An important part of that document is links to the many user-written HowTos on interoperation -between FreeS/WAN and various other implementations. Often the users know -more than the developers about these issues (and almost always more than me -:-), so these documents may be your best resource.

- -

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 a few cases, there are some complications. See our interoperation document for details.

- -

Is there a limit on throughput?

- -

There is no hard limit, but see below.

- -

Is there a limit on number of tunnels?

- -

There is no hard limit, but see next question.

- -

Is a ... fast enough to handle FreeS/WAN with my -loads?

- -

A quick summary:

-
-
Even a limited machine can be useful
-
A 486 can handle a T1, ADSL or cable link, though the machine may be - breathing hard.
-
A mid-range PC (say 800 MHz with good network cards) can do a lot of - IPsec
-
With up to roughly 50 tunnels and aggregate bandwidth of 20 Megabits - per second, it willl have cycles left over for other tasks.
-
There are limits
-
Even a high end CPU will not come close to handling a fully loaded - 100 Mbit/second Ethernet link. -

Beyond about 50 tunnels it needs careful management.

-
-
- -

See our FreeS/WAN performance document for -details.

- -

Will FreeS/WAN work on ... ?

- -

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

- -

Will FreeS/WAN run on non-Intel CPUs?

- -

FreeS/WAN is intended to run on all CPUs Linux supports. -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.

- -

Will FreeS/WAN run on multiprocessors?

- -

FreeS/WAN is designed to work on any SMP architecture Linux supports, and -has been tested successfully on at least dual processor Intel architecture -machines. Details are in our compatibility document.

- -

Will FreeS/WAN work on an older kernel?

- -

It might, but we strongly recommend using a recent 2.2 or 2.4 series -kernel. Sometimes the newer versions include security fixes which can be -quite important on a gateway.

- -

Also, we use recent kernels for development and testing, so those are -better tested and, if you do encounter a problem, more easily supported. If -something breaks applying recent FreeS/WAN patches to an older kernel, then -"update your kernel" is almost certain to be the first thing we suggest. It -may be the only suggestion we have.

- -

The precise kernel versions supported by a particular FreeS/WAN release -are given in the README file of that release.

- -

See the following question for more on kernels.

- -

Will FreeS/WAN run on the latest kernel -version?

- -

Sometimes yes, but quite often, no.

- -

Kernel versions supported are given in the README -file of each FreeS/WAN release. Typically, they are 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). Often -FreeS/WAN will work on slightly later kernels as well, but of course this -cannot be guaranteed.

- -

For example, FreeS/WAN 1.91 was released for kernels 2.2.19 or 2.4.5, the -current kernels at the time. It also worked on 2.4.6, 2.4.7 and 2.4.8, but -2.4.9 had changes that caused compilation errors if it was patched with -FreeS/WAN 1.91.

- -

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:

- - -

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

- -

Will FreeS/WAN work on unusual network -hardware?

- -

IPsec is designed to work over any network that IP works over, and -FreeS/WAN is intended to work over any network interface hardware that Linux -supports.

- -

If you have working IP on some unusual interface -- perhaps Arcnet, Token -Ring, ATM or Gigabit Ethernet -- then IPsec should "just work".

- -

That said, practice is sometimes less tractable than theory. Our testing -is done almost entirely on:

- - -

If you have some other interface, especially an uncommon one, it is -entirely possible you will get bitten either by a FreeS/WAN bug which our -testing did not turn up, or by a bug in the driver that shows up only with -our loads.

- -

If IP works on your interface and FreeS/WAN doesn't, seek help on the mailing lists.

- -

Another FAQ section describes MTU problems. -These are a possibility for some interfaces.

- -

Will FreeS/WAN work on a VLAN (802.1q) network?

- -

- Yes, FreeSwan works fine, though some network drivers have problems - with jumbo sized ethernet frames. If you used interfaces=%defaultroute - you do not need to change anything, but if you specified an interface - (eg eth0) then remember you must change that to reflect the VLAN - interface (eg eth0.2 for VLAN ID 2). -

-

- The "eepro100" module is known to be broken, use the e100 driver - for those cards instead (included in 2.4 as 'alternative driver' for - the Intel EtherExpressPro/100. -

-

- You do not need to change any MTU setting (those are workarounds - that are only needed for buggy drivers) -

- -

This FAQ contributed by Paul Wouters.

- -

Does FreeS/WAN support ...

- -

For a discussion of which parts of the IPsec specifications FreeS/WAN does -and does not implement, see our compatibility -document.

- -

For information on some often-requested features, see below.

- -

Does FreeS/WAN support site-to-site VPN -(Virtual Private Network) -applications?

- -

Absolutely. See this FreeS/WAN-FreeS/WAN -configuration example. -If only one site is using FreeS/WAN, there may be a relevant HOWTO on our -interop page. -

- -

Does FreeS/WAN support remote users connecting to a -LAN?

- -

Yes. We call the remote users "Road Warriors". Check out our -FreeS/WAN-FreeS/WAN -Road Warrior Configuration Example.

- -

If your Road Warrior is a Windows or Mac PC, you may need to -install an IPsec implementation on that machine. -Our interop page lists many available brands, -and features links to several HOWTOs. - - -

Does FreeS/WAN support remote users using -shared secret authentication?

- -

Yes, but there are severe restrictions, so we -strongly recommend using RSA keys for - authentication - -instead.

- -

See this FAQ question.

- -

Does FreeS/WAN support wireless networks?

- -

Yes, it is a common practice to use IPsec over wireless networks because -their built-in encryption, WEP, is -insecure.

- -

There is some discussion in -our advanced configuration document. See also the -WaveSEC site.

- -

Does FreeS/WAN support X.509 or other PKI -certificates?

- -

Vanilla FreeS/WAN does not support X.509, but Andreas Steffen -and others have provided a popular, well-supported X.509 patch.

- - - -

-Linux FreeS/WAN features -Opportunistic Encryption, an alternative -Public Key Infrastructure based on Secure DNS. -

- -

Does FreeS/WAN support user authentication (Radius, -SecureID, Smart Card...)?

- -

Andreas Steffen's X.509 patch (v. 1.42+) supports Smart Cards. The patch -does not ship with vanilla FreeS/WAN, but will be incorporated into -Super FreeS/WAN -2.01+. The patch implements the PCKS#15 -Cryptographic Token Information Format Standard, using the OpenSC smartcard -library functions.

- -

Older news:

- -

A user-supported patch to FreeS/WAN 1.3, for smart card style -authentication, is available on -Bastiaan's site. -It supports skeyid and ibutton. -This patch is not part of Super FreeS/WAN.

- -

For a while progress on this front was impeded by a lack of standard. -The IETF working group -has now nearly completed its recommended solution to the problem; meanwhile -several vendors have implemented various things.

- - - -

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 either of those is trustworthy, it is not clear that you need user -authentication in IPsec.

- - -

Does FreeS/WAN support NAT traversal?

- -

Vanilla FreeS/WAN does not, but thanks to Mathieu Lafon and -Arkoon Network Security, there's a patch to support this.

- - - -

The NAT traversal patch has some issues with PSKs, so you may wish to -authenticate with RSA keys, or X.509 (requires a patch which is also -included in Super FreeS/WAN). Doing the latter also has -advantages when dealing with large numbers of clients who may be behind NAT; -instead of having to make an individual Roadwarrior connection for each -virtual IP, you can use the "rightsubnetwithin" parameter to specify a range. -See -these -rightsubnetwithin instructions. -

- - -

Does FreeS/WAN support assigning a "virtual identity" to -a remote system?

- -

Some IPsec implementations allow you to make the source address on packets -sent by a Road Warrior machine be something other than the address of its -interface to the Internet. This is sometimes described as assigning a virtual -identity to that machine.

- -

FreeS/WAN does not directly support this, but it can be done. See this FAQ question.

- -

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.

- -

Does FreeS/WAN support AES encryption?

- -

AES is a new US government block cipher standard to replace the obsolete -DES.

- -

At time of writing (March 2002), the FreeS/WAN distribution does not yet -support AES but user-written patches are -available to add it. Our kernel programmer is working on integrating those -patches into the distribution, and there is active discussion of this on the -design mailimg list.

- -

Does FreeS/WAN support other encryption -algorithms?

- -

Currently triple DES is the only cipher -supported. AES will almost certainly be added (see previous question), and it -is likely that in the process we will also add the other two AES finalists -with open licensing, Twofish and Serpent.

- -

We are extremely reluctant to add other ciphers. This would make both use -and maintenance of FreeS/WAN more complex without providing any clear -benefit. Complexity is emphatically not desirable in a security product.

- -

Various users have written patches to add other ciphers. We provide links to these.

- -

Can I ...

- - -

Can I use policy groups along with -explicitly configured connections?

- -

Yes, you can, so long as you pay attention to the selection rule, -which can be summarized "the most specific -connection wins". We describe the rule in our -policy groups document, -and provide a more technical explanation in -man ipsec.conf. -

- -

A good guideline: If you have a regular connection defined in -ipsec.conf, ensure that a subset of that connection -is not listed in a less restrictive policy group. Otherwise, -FreeS/WAN will use the subset, with its more specific source/destination -pair.

- -

Here's an example. Suppose you are the system administrator at 192.0.2.2. -You have this connection in ipsec.conf: -ipsec.conf: - -

conn net-to-net
-    left=192.0.2.2           # you are here
-    right=192.0.2.8
-    rightsubnet=192.0.2.96/27
-    ....
-
- -

If you then place a host or net within rightsubnet, -(let's say 192.0.2.98) in private-or-clear, you may find -that 192.0.2.2 at times communicates in the -clear with 192.0.2.98. That's consistent with the rule, but may be -contrary to your expectations.

- -

On the other hand, it's safe to put a larger subnet in a less -restrictive policy group file. If private-or-clear -contains 192.0.2.0/24, then the more specific net-to-net -connection is used for any communication to 192.0.2.96/27. The -more general policy applies only to communication with hosts or subnets in -192.0.2.0/24 without a more specific policy or connection.

- - -

Can I turn off policy groups?

- -

Yes. Use these -instructions.

- - - -

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 (a -virtual identity)?

- -

Often it would be convenient to be able to give a Road Warrior an IP -address which appears to be on the local network. Some IPsec implementations -have support for this, sometimes calling the feature "virtual identity".

- -

Currently (Sept 2002) FreeS/WAN does not support this, and we have -no definite plans to add it. The difficulty is that is not yet a standard -mechanism for it. There is an Internet Draft for a method of doing it using -DHCP which looks promising. FreeS/WAN may support that in -a future release.

- -

In the meanwhile, you can do it yourself using the Linux iproute2(8) -facilities. Details are in this -paper.

- -

Another method has also been discussed on the mailing list.:

- - -

For example, you might have:

-
-
leftsubnet=a.b.c.0/25
-
head office network
-
rightsubnet=a.b.c.129/32
-
extruded to a road warrior. Note that this is not in a.b.c.0/25
-
a.b.c.0/24
-
whole network, including both the above
-
- -

You then set up routing so that the office machines use the IPsec gateway -as their route to a.b.c.128/25. The leftsubnet parameter tells the road -warriors to use tunnels to reach a.b.c.0/25, so you should have two-way -communication. Depending or your network and applications, there may be some -additional work to do on DNS or Windows configuration

- -

Can I support many road warriors with one -gateway?

- -

Yes. This is easily done, using

-
-
either RSA authentication
-
standard in the FreeS/WAN distribution
-
or X.509 certificates
-
requires Super FreeS/WAN or a patch.
-
- -

In either case, each Road Warrior must have a different key or -certificate.

- -

It is also possible using pre-shared key authentication, -though we don't recommend this; see the -next question for details.

- -

If you expect to have more than a few dozen Road Warriors connecting -simultaneously, you may need a fairly powerful gateway machine. See our -document on FreeS/WAN performance.

- -

Can I have many road warriors using shared secret -authentication?

- -

Yes, but avoid it if possible.

- -

You can have multiple Road Warriors using shared secret authentication -only if they all use the same secret. You must also -set:

- -

   uniqueids=no
- -

in the connection definition.

- - -

Why it's less secure:

- - -

This is a designed-in limitation of the IKE key negotiation protocol, not a problem with -our implementation.

- -

We very strongly recommend that you avoid using shared secret -authentication for multiple Road Warriors. Use RSA authentication -instead.

- -

The longer story: When using shared secrets, the protocol requires -that the responding -gateway be able to determine which secret to use at a time when all it knows -about the initiator is an IP address. This works fine if you know the -initiator's address in advance and can use it to look up the appropiriate -secret. However, it fails for Road Warriors since the gateway cannot know -their IP addresses in advance.

- -

With RSA signatures (or certificates) the protocol is slightly different. -The initiator provides an identifier early in the exchange and the responder -can use that identifier to look up the correct key or certificate. See 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 (type of service) -information from the encapsulated packet to the outer header reveals the TOS -information to an eavesdropper. This does not tell him much, but it might be -of use in traffic analysis. Since we do -not have to give it to him, our default is not to.

- -

Even with the TOS hidden, you can still:

- - -

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:

- - -

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, L2TP or PPTP tunnels over IPsec?

- -

Yes. Normally this is not necessary, but it is useful in a few special -cases. For example, if you must route non-IP packets such as IPX, you -will need to use a tunneling protocol that can route these packets. IPsec -can be layered around it for extra security. Another example: you -can provide failover protection for high availability (HA) environments by -combining IPsec with other tools. Ken Bantoft describes one such setup in -Using FreeS/WAN with Linux-HA, GRE, -OSPF and BGP for enterprise grade VPN solutions.

- -

GRE over IPsec is covered as part of -that document. - -Here are links to other GRE resources. - -Jacco de Leuw has created -this page on L2TP over IPsec -with instructions for FreeS/WAN and several other brands of IPsec software. -

- -

Please let us know of other useful links via the -mailing lists. - - -

... use Network Neighborhood (Samba, NetBIOS) over IPsec?

- -

Your local PC needs to know how to translate NetBIOS names to IP addresses. -It may do this either via a local LMHOSTS file, or using a local or remote -WINS server. The WINS server is preferable since it provides a centralized -source of the information to the entire network. To use a WINS server over -the VPN -(or any IP-based network), you must enable "NetBIOS over TCP".

- -

Samba can emulate a WINS server -on Linux.

- -

-See also several discussions in our -September -2002 Users archives

- - -

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:

- - -

However, we also list some of the commonest problems here.

- -

I cannot ping ....

- -

This question is dealt with in the advanced 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 = 192.0.2.8
-             |
-
-       ~ internet ~
-
-             |
-      eth0 = 192.0.2.11
-         gate2
-      eth1 = x.y.z.1
-              |
-       subnet x.y.z.0/24
- -

and the connection description:

-
conn abc-xyz
-     left=192.0.2.8
-     leftsubnet=a.b.c.0/24
-     right=192.0.2.11
-     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:

- - -

In some cases, you may be able to get around this. For the example network -above, you could use:

-
        ping -I a.b.c.1 x.y.z.1
- -

Both the adresses given are within protected subnets, so this should go -through the tunnel.

- -

If required, you can build additional tunnels so that all the machines -involved can talk to all the others. See multiple tunnels in the advanced -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:

- - -

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:

- - -

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

- - -

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.

- -

Some advice from technical lead Henry Spencer on diagnosing such -problems:

-
> > Packets vanishing between the hardware interface and the ipsecN interface
-> > is usually the result of firewalls not being configured to let them in...
-> 
-> Thanks for the suggestion. If only it were that simple! My ipchains startup
-> script does take care of that, but just in case I manually inserted rules 
-> accepting everything from london on dublin. No difference.
-
-The other thing to check is whether the "RX packets dropped" count on the
-ipsecN interface (run "ifconfig ipsecN", for N=1 or whatever, to see the
-counts) is rising.  If so, then there's some sort of configuration mismatch
-between the two ends, and IPsec itself is rejecting them.  If none of the
-ipsecN counts is rising, then the packets are never reaching the IPsec
-machinery, and the problem is almost certainly in firewalls etc.
- -

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

- - -

Disappearing %defaultroute

- -

When an underlying connection (eg. ppp) goes down, FreeS/WAN will not -recover properly without a little help. Here are the symptoms that FreeS/WAN -user Michael Carmody noticed: -

-> After about 24 hours the freeswan connection takes over the default route.
-> 
-> i.e instead of deafult gateway pointing to the router via eth0, it becomes a 
-> pointer to the router via ipsec0.
- 
-> All internet access is then lost as all replies (and not just the link I 
-> wanted) are routed out ipsec0 and the router doesn't respond to the ipsec 
-> traffic.
-
- -

If you're using a -FreeS/WAN 2.x/KLIPS system, simply re-attach the IPsec virtual -interface with ipsec tnconfig command such as:

-
    ipsec tnconfig --attach --virtual ipsec0 --physical ppp0
-

In your command, name the physical and virtual interfaces as they -appear paired on your system during regular uptime. For a system with several -physical/virtual interface pairs on flaky links, you'll need more than -one such command. -If you're using FreeS/WAN 1.x, you must restart FreeS/WAN, which is more time -consuming.

- -

-Here -is a script which can help to automate the process of FreeS/WAN restart at -need. -It could easily be adapted to use tnconfig instead.

- -

TCPdump on the gateway shows strange things

- -As another user pointed out, keeping the connect -

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.

- -

See our testing document for more -detail.

- -

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:

- - -

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:

- - -

One manual connection works, but second one -fails

- -

This is a 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 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:

- - -

IPsec works, but connections using compression -fail

- -

When we first added compression, we saw some problems:

- - -

We have not seen either problem in some time (at least six months as I -write in March 2002), but if you have some unusual configuration then you may -see them.

- -

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 packet -fragmentation and perhaps path MTU -discovery.

- -

Our troubleshooting document covers -these problems. Information on the underlying mechanism is in our background document.

- -

Subnet-to-subnet works, but tests from the gateways -don't

- -

This is described under I cannot ping... above.

- -

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

Interpreting error messages

- -

route-client (or host) exited with status -7

- -

Here is a discussion of this error from FreeS/WAN "listress" (mailing list -tech support person) Claudia Schmeing. The "FAQ on the network unreachable -error" which she refers to is the next question below.

-
> I reached the point where the two boxes (both on dial-up connections, but
-> treated as static IPs by getting the IP and editing ipsec.conf after the
-> connection is established) to the point where they exchange some info, but I
-> get an error like "route-client command exited with status 7 \n internal
-> error".
-> Where can I find a description of this error?
-
-In general, if the FAQ doesn't cover it, you can search the mailing list 
-archives - I like to use
-http://www.sandelman.ottawa.on.ca/linux-ipsec/
-but you can see doc/mail.html for different archive formats.
-
-
-Your error comes from the _updown script, which performs some
-routing and firewall functions to help Linux FreeS/WAN. More info
-is available at doc/firewall.html and man ipsec.conf. Its routing
-is integral to the health of Linux FreeS/WAN; it also provides facility
-to insert custom firewall rules to be executed when you create or destroy
-a connection.
-
-Yours is, of course, a routing error. You can be fairly sure the routing 
-machinery is saying "network is unreachable". There's a FAQ on the 
-"network is unreachable" error, but more information is available now; read on.
-
-If your _updown script is recent (for example if it shipped with 
-Linux FreeS/WAN 1.91), you will see another debugging line in your logs 
-that looks something like this:
-
-> output: /usr/local/lib/ipsec/_updown: `route add -net 128.174.253.83 
-> netmask 255.255.255.255 dev ipsec0 gw 66.92.93.161' failed
-
-This is, of course, the system route command that exited with status 7, 
-(ie. failed). Man route for details. Seeing the command typed out yields 
-more information. If your _updown script is older, you may wish to update 
-it to show the command explicitly.
-
-Three parameters fed to the route command: net, netmask and gw [gateway] 
-are derived from things you've put in ipsec.conf.
-
-Net and netmask are derived from the peer's IP and mask. In more detail:
-
-You may see a routing error when routing to a client (ie. subnet), or 
-to a host (IPSec gateway or freestanding host; a box that does IPSec for
-itself). In _updown, the "route-client" section  is responsible to set up 
-the route for IPSec'd (usually, read 'tunneled') packets headed to a 
-peer subnet. Similarly, route-host routes IPSec'd packets to a peer host
-or IPSec gateway.
-
-When routing to a 'client', net and netmask are ipsec.conf's left- or 
-rightsubnet (whichever is not local). Similarly, when routing to a 
-'host' the net is left or right. Host netmask is always /32, indicating a 
-single machine.
-
-Gw is nexthop's value. Again, the value in question is left- or rightnexthop,
-whichever is local. Where left/right or left-/rightnexthop has the special 
-value %defaultroute (described in man ipsec.conf), gw will automagically get
-the value of the next hop on the default route.
-
-Q: "What's a nexthop and why do I need one?"
-
-A: 'nexthop' is a routing kluge; its value is the next hop away
-   from the machine that's doing IPSec, and toward your IPSec peer. 
-   You need it to get the processed packets out of the local system and 
-   onto the wire. While we often route other packets through the machine 
-   that's now doing IPSec, and are done with it, this does not suffice here. 
-   After packets are processed with IPSec, this machine needs to know where 
-   they go next. Of course using the 'IPSec gateway' as their routing gateway 
-   would cause an infinite loop! [To visualize this, see the packet flow 
-   diagram at doc/firewall.html.] To avoid this, we route packets through 
-   the next hop down their projected path.
-
-Now that you know the background, consider:
-1. Did you test routing between the gateways in the absence of Linux
-   FreeS/WAN, as recommended? You need to ensure the two machines that
-   will be running Linux FreeS/WAN can route to one another before trying to 
-   make a secure connection.
-2. Is there anything obviously wrong with the sense of your route command?
-
-Normally, this problem is caused by an incorrect local nexthop parameter.
-Check out the use of %defaultroute, described in man ipsec.conf. This is
-a simple way to set nexthop for most people. To figure nexthop out by hand,
-traceroute in-the-clear to your IPSec peer. Nexthop is the traceroute's 
-first hop after your IPSec gateway.
- -

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

- -

See also the FAQ question route-client (or host) -exited with status 7.

- -

ipsec_setup: modprobe: Can't locate module -ipsec

- -

ipsec_setup: Fatal error, kernel appears to lack -KLIPS

- -

These messages indicate an installation failure. The kernel you are -running does not contain the KLIPS (kernel -IPsec) code.

- -

Note that the "modprobe: Can't locate module ipsec" message appears even -if you are not using modules. If there is no KLIPS in your kernel, FreeS/WAN -tries to load it as a module. If that fails, you get this message.

- -

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.

- -

Message numbers (MI3, QR1, et cetera) in Pluto -messages

- -

Pluto messages often indicate where Pluto is in the IKE protocols. The -letters indicate Main mode or Quick mode -and Initiator or Responder. The numerals -are message sequence numbers. For more detail, see our IPsec section.

- -

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

- -

Older versions of FreeS/WAN used this message. The same error now gives -the "we have no ipsecN ..." error described just below.

- -

... we have no ipsecN interface for either end of -this connection

- -

Your tunnel has no IP address which matches the IP -address of any of the available IPsec interfaces. Either you've -misconfigured the connection, or you need to define an appropriate -IPsec interface connection. interfaces=%defaultroute works -in many cases.

- -

A longer story: 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:

- - -

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:

- - -

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

rsasigkey dumps core

-A comment on this error from Henry: -
On Fri, 29 Jun 2001, Rodrigo Gruppelli wrote:
-> ...Well, it seem that there's
-> another problem with it. When I try to generate a pair of RSA keys,
-> rsasigkey cores dump...
-
-*That* is a neon sign flashing "GMP LIBRARY IS BROKEN".  Rsasigkey calls
-GMP a lot, and our own library a little bit, and that's very nearly all it
-does.  Barring bugs in its code or our library -- which have happened, but
-not very often -- a problem in rsasigkey is a problem in GMP.
- -

See the next question for how to deal with GMP errors.

- -

!Pluto failure!: ... exited with ... signal 4

- -

Pluto has died. Signal 4 is SIGILL, illegal instruction.

- -

The most likely cause is that your GMP -(GNU multi-precision) library is compiled for a different processor than what -you are running on. Pluto uses that library for its public key -calculations.

- -

Try getting the GMP sources and recompile for your processor type. Most -Linux distributions will include this source, or you can download it from the -GMP home page.

- -

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

The document she refers to has since been replaced by a section of the troubleshooting -document.

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

The documentation section she refers to is now here.

- -

... trouble writing to /dev/ipsec ... SA already in -use

- -

This error message occurs when two manual connections are set up with the -same SPI value.

- -

See the FAQ for 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:

- - -

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 our discussion of -cleaning up dead tunnels.

- -

unknown parameter name "rightcert"

- -

This message can appear when you've upgraded an X.509-enabled -Linux FreeS/WAN with a vanilla Linux FreeS/WAN. To use your X.509 configs -you will need to overwrite the new install with -Super FreeS/WAN, or add the -X.509 patch by hand. -

- -

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.

- - -

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:

- - -

A number of tools are available to filter mail.

- - -

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
- - diff --git a/doc/src/firewall.html b/doc/src/firewall.html deleted file mode 100644 index 5051b458d..000000000 --- a/doc/src/firewall.html +++ /dev/null @@ -1,895 +0,0 @@ - - - - FreeS/WAN and firewalls - - - - - -

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.

- -

The firewall code in 2.4 and later kernels is called Netfilter. The -user-space utility to manage a firewall is iptables(8). See the netfilter/iptables web site for -details.

- -

Filtering rules for IPsec packets

- -

The basic constraint is that an IPsec gateway must have packet -filters that allow IPsec packets, at least when talking to other -IPsec gateways:

- - -

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.

- -

For nearly all FreeS/WAN applications, you must allow UDP port 500 and the -ESP protocol.

- -

There are two ways to set this up:

-
-
easier but less flexible
-
Just set up your firewall scripts at boot time to allow IPsec packets - to and from your gateway. Let FreeS/WAN reject any bogus packets.
-
more work, giving you more precise control
-
Have the ipsec_pluto(8) - daemon call scripts to adjust firewall rules dynamically as required. - This is done by naming the scripts in the ipsec.conf(5) variables - prepluto=, postpluto=, leftupdown= and - rightupdown=.
-
- -

Both methods are described in more detail below.

- -

Firewall configuration at boot

- -

It is 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

- - -

Since Pluto authenticates its partners during the negotiation, and KLIPS -drops packets for which no tunnel has been negotiated, this may be all you -need.

- -

A simple set of rules

- -

In simple cases, you need only a few rules, as in this example:

-
# allow IPsec
-#
-# IKE negotiations
-iptables -I INPUT  -p udp --sport 500 --dport 500 -j ACCEPT
-iptables -I OUTPUT -p udp --sport 500 --dport 500 -j ACCEPT
-# ESP encryption and authentication
-iptables -I INPUT  -p 50 -j ACCEPT
-iptables -I OUTPUT -p 50 -j ACCEPT
-
- -

This should be all you need to allow IPsec through lokkit, -which ships with Red Hat 9, on its medium security setting. -Once you've tweaked to your satisfaction, save your active rule set with:

-
service iptables save
- -

Other rules

-You can add additional rules, or modify existing ones, to work with IPsec and -with your network and policies. We give a some examples in this section. - -

However, while it is certainly possible to create an elaborate set of -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.

- -

The published rule sets we know of are described in the next section.

- -

Adding additional rules

-If necessary, you can add additional rules to: -
-
reject IPsec packets that are not to or from known gateways
-
This possibility is discussed in more detail later
-
allow systems behind your gateway to build IPsec tunnels that pass - through the gateway
-
This possibility is discussed in more detail later
-
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.
-
- -

It is therefore reasonably straightforward to filter these packets in -whatever way suits your situation.

- -

Modifying existing rules

- -

In some cases rules that work fine before you add IPsec may require -modification to work with IPsec.

- -

This is especially likely for rules that deal with interfaces on the -Internet side of your system. IPsec adds a new interface; often the rules -must change to take account of that.

- -

For example, consider the rules given in this -section of the Netfilter documentation:

-
Most people just have a single PPP connection to the Internet, and don't
-want anyone coming back into their network, or the firewall:
-
-    ## Insert connection-tracking modules (not needed if built into kernel).
-    # insmod ip_conntrack
-    # insmod ip_conntrack_ftp
-
-    ## Create chain which blocks new connections, except if coming from inside.
-    # iptables -N block
-    # iptables -A block -m state --state ESTABLISHED,RELATED -j ACCEPT
-    # iptables -A block -m state --state NEW -i ! ppp0 -j ACCEPT
-    # iptables -A block -j DROP
-
-    ## Jump to that chain from INPUT and FORWARD chains.
-    # iptables -A INPUT -j block
-    # iptables -A FORWARD -j block
- -

On an IPsec gateway, those rules may need to be modified. The above allows -new connections from anywhere except ppp0. That means new -connections from ipsec0 are allowed.

- -

Do you want to allow anyone who can establish an IPsec connection to your -gateway to initiate TCP connections to any service on your network? Almost -certainly not if you are using opportunistic encryption. Quite possibly not -even if you have only explicitly configured connections.

- -

To disallow incoming connections from ipsec0, change the middle section -above to:

-
    ## Create chain which blocks new connections, except if coming from inside.
-    # iptables -N block
-    # iptables -A block -m state --state ESTABLISHED,RELATED -j ACCEPT
-    # iptables -A block -m state --state NEW -i ppp+ -j DROP
-    # iptables -A block -m state --state NEW -i ipsec+ -j DROP
-    # iptables -A block -m state --state NEW -i -j ACCEPT
-    # iptables -A block -j DROP
- -

The original rules accepted NEW connections from anywhere except ppp0. -This version drops NEW connections from any PPP interface (ppp+) and from any -ipsec interface (ipsec+), then accepts the survivors.

- -

Of course, these are only examples. You will need to adapt them to your -own situation.

- -

Published rule sets

- -

Several sets of firewall rules that work with FreeS/WAN are available.

- -

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.

- -

Asgard scripts

- -

Asgard's -Realm has set of firewall scripts with FreeS/WAN support, for 2.4 kernels -and iptables.

- -

User scripts from the mailing list

- -

One user gave considerable detail on his scripts, including supporting IPX through the tunnel. His message was too long -to conveniently be quoted here, so I've put it in a separate file.

- -

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

- -

The ipsec.conf(5) 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 above 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=
-
script to be called before pluto(8) IKE daemon is - started.
-
postpluto=
-
script to be called after pluto(8) IKE daemon 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 leftfirewall=yes or rightfirewall=yes to - use our supplied default script
-
or
-
assign a name in a leftupdown= or rightupdown= - line to use your own script
-
- -

Note that only one of these should be used. You cannot -sensibly use both. Since our default script is obsolete -(designed for firewalls using ipfwadm(8) on 2.0 kernels), most -users who need this service will need to write a custom -script.

- -

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:

- - -

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. See the "updown command" section of the ipsec_pluto(8) man page for -details.

- -

Note 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 or iptables

- -

Our _updown is for firewalls using ipfwadm(8), the -firewall code for the 2.0 series of Linux kernels. If you are using the more -recent packages ipchains(8) (for 2.2 kernels) or -iptables(8) (2.4 kernels), then you must do one of:

- - -

You can write a script to do whatever you need with firewalling. Specify -its name in a [left|right]updown= parameter in ipsec.conf(5) and Pluto will -automatically call it for you.

- -

The arguments Pluto passes such a script are the same ones it passes to -our default _updown script, so the best way to build yours is to copy ours -and modify the copy.

- -

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.

- -

A complication: IPsec vs. 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:

- - -

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

- - -

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:

- - -

Other references on NAT and IPsec

- -

Other documents which may be relevant include:

- - -

Other complications

- -

Of course simply allowing UDP 500 and ESP packets is not the whole story. -Various other issues arise in making IPsec and packet filters co-exist and -even co-operate. Some of them are summarised below.

- -

IPsec through the gateway

- -

Basic IPsec packet filtering rules deal only with packets addressed to or -sent from your IPsec 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.

- -

Where possible, allowing this is almost certainly a good idea. Using IPsec -on an end-to-end basis is more secure than gateway-to-gateway.

- -

Doing it is quite simple. You just need firewall rules that allow UDP port -500 and protocols 50 and 51 to pass through your gateway. If you wish, you -can of course restrict this to certain hosts.

- -

Preventing non-IPsec traffic

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

One application of this is for the telecommuter who might have:

-
     Sunset==========West------------------East ================= firewall --- the Internet
-         home network      untrusted net        corporate network
- -

The subnet on the right is 0.0.0.0/0, the whole Internet. The West gateway -is set up so that it allows only IPsec packets to East in or out.

- -

This configuration is used in AT&T Research's network. For details, -see the papers links in our introduction.

- -

Another application would be to set up firewall rules so that an internal -machine, such as an employees-only web server, could not talk to the outside -world except via specific IPsec tunnels.

- -

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:

- - -

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

- - -

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.

- -

How it all works: IPsec packet details

- -

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

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:

- - -

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:

- - -

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:

- - -

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

- -

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.
- - diff --git a/doc/src/forwardingstate.txt b/doc/src/forwardingstate.txt deleted file mode 100644 index 8853ac84e..000000000 --- a/doc/src/forwardingstate.txt +++ /dev/null @@ -1,35 +0,0 @@ - - - .--------------. - | non-existant | - | policy | - `--------------' - | - | PF_ACQUIRE - | - |<---------. - V | new packet - .--------------. | (maybe resend PF_ACQUIRE) - | hold policy |--' - | |--. - `--------------' \ pass - | | \ msg .---------. - | | \ V | forward - | | .-------------. | packet - create | | | pass policy |--' - IPsec | | `-------------' - SA | | - | \ - | \ - V \ deny - .---------. \ msg - | encrypt | \ - | policy | \ ,---------. - `---------' \ | | discard - \ V | packet - .-------------. | - | deny policy |--' - '-------------' - - -$Id: forwardingstate.txt,v 1.1 2004/03/15 20:35:24 as Exp $ diff --git a/doc/src/glossary.html b/doc/src/glossary.html deleted file mode 100644 index 38d0db7bb..000000000 --- a/doc/src/glossary.html +++ /dev/null @@ -1,2257 +0,0 @@ - - - - - FreeS/WAN glossary - - - - - -

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:

- - -

Several Internet glossaries are available as RFCs:

- - -

More general glossary or dictionary information:

- -
- -

Definitions

-
-
0
-
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 2112. 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 our performance document 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 -- 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 128, 192 or 256-bit keys. 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:

- -

Three of the five finalists -- Rijndael, Serpent and Twofish -- have - completely open licenses.

-

In October 2000, NIST announced the winner -- Rijndael.

-

For more information, see:

- -

AES will be added to a future release of Linux - FreeS/WAN. Likely we will add all three of the finalists with good - licenses. User-written AES patches are - already available.

-

Adding AES may also require adding stronger hashes, SHA-256, SHA-384 and SHA-512.

-
-
AH
-
The IPsec Authentication Header, - added after the IP header. For details, see our IPsec 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: - -

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. FreeS/WAN normally uses RSA for this. Other - methods supported are discussed in our advanced 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: - -

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 block cipher for Linux - FreeS/WAN.

-

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, about 135 years. Against a - 128-bit key, he needs 232 times that, over 500,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 over 500,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 500,000,000,000 years to break by brute force. We - really don't care how many zeroes there are on the end of that, as long - as the number remains ridiculously large. That is, we don't care - exactly how large the key is as long as it is large enough.

-

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

-
-
CIDR
-
Classless Inter-Domain Routing, - an addressing scheme used to describe networks not - restricted to the old Class A, B, and C sizes. - A CIDR block is written - address/mask, where address is - a 32-bit Internet address. - The first mask bits of address - are part of the gateway address, while the remaining bits designate - other host addresses. - For example, the CIDR block 192.0.2.96/27 describes a network with - gateway - 192.0.2.96, hosts 192.0.2.96 through 192.0.2.126 and broadcast - 192.0.2.127. -

FreeS/WAN policy group files accept CIDR blocks of the format - address/[mask], where address may - take the form name.domain.tld. An absent mask - is assumed to be /32. -

-
- -
Certification Authority
-
see CA
-
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.

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

- - - - - - - - - - - - - - - - - - - - - - - - - - - - -
ECBElectronic CodeBookencrypt each block independently
CBCCipher Block Chaining
- 		XOR previous block ciphertext into new block plaintext before - encrypting new block
CFBCipher FeedBack
OFBOutput 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.

-
-
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, and the office gateway is the - server.
    • -
-

We generally use the term in the first sense. Vendors of Windows - IPsec solutions often use it in the second. See this discussion.

-
-
Common Criteria
-
A set of international security classifications which are replacing - the old US Rainbow Book standards and similar - standards in other countries. -

Web references include this US - government site and this global home page.

-
-
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. It is now being replaced by AES. -

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
-
DHCP
-
Dynamic Host - Configuration Protocol, a method of - assigning dynamic IP addresses, and providing - additional information such as addresses of DNS servers and of - gateways. See this DHCP resource - page.
-
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 = - 7is 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.

-
-
discretionary access control
-
access control mechanisms controlled by the user, for example Unix - rwx file permissions. These contrast with mandatory access controls.
-
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 the DNS background section of our - documentation.
-
DOS attack
-
see Denial Of Service attack
-
dynamic IP address
-
an IP address which is automatically assigned, either by DHCP or by some protocol such as PPP or PPPoE which the machine - uses to connect to the Internet. This is the opposite of a static IP address, pre-set on the machine - itself.
-
E
-
EAR
-
The US government's Export Administration - Regulations, 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 both the security of single DES and the - overheads of triple DES are seriously inferior to many other ciphers, - this is a spectacularly dubious "advantage".

-
-
Entrust
-
A Canadian company offerring enterprise PKI - products using CAST-128 symmetric crypto, RSA public key and X.509 - directories. Web site
-
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 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 advanced configuration - section.

-
-
Exhaustive search
-
See brute force attack.
-
F
-
FIPS
-
Federal Information Processing Standard, - 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.

-
-
FreeS/WAN
-
see Linux FreeS/WAN
-
Fullnet
-
The CIDR block containing all IPs of its IP version. - The IPv4 fullnet is written 0.0.0.0/0. - Also known as "all" and "default", - fullnet may be used in a routing table - to specify a default route, - and in a FreeS/WAN - policy group file to - specify a default IPsec policy.
-
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. See the GMP home page.
-
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.
-
GOST
-
a Soviet government standard block cipher. Applied Cryptography has details.
-
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. See their web - site
-
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 - Message 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.

-
-
IEEE
-
Institute of Electrical and Electronic - Engineers, a professional association which, among other things, - sets some technical standards
-
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. For details, see - RFC 2409 and our IPsec document. IKE is - implemented in Linux FreeS/WAN by the Pluto daemon.
-
IKE v2
-
A proposed replacement for IKE. There are other - candidates, such as JFK, and at time of writing - (March 2002) the choice between them has not yet been made and does not - appear imminent.
-
iOE
-
See Initiate-only opportunistic - encryption.
-
IP
-
Internet Protocol.
-
IP masquerade
-
A mostly obsolete term for a method of allowing multiple machines to - communicate over the Internet when only one IP address is available for - their use. The more current term is Network Address Translation or NAT.
-
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 or 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.

-
-
IPX
-
Novell's Netware protocol tunnelled over an IP link. Our firewalls document includes an - example of using this through an IPsec tunnel.
-
ISAKMP
-
Internet Security Association and Key - Management Protocol, defined in RFC 2408.
-
ITAR
-
International Traffic in Arms - Regulations, 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
-
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.
-
Initiate-only opportunistic - encryption (iOE)
-
A form of - opportunistic encryption (OE) in which - a host proposes opportunistic connections, but lacks the reverse DNS - records necessary to support incoming opportunistic connection requests. - Common among hosts on cable or pppoe connections where the system - administrator does not have write access to the DNS reverse map - for the host's external IP. -

Configuring for initiate-only opportunistic encryption - is described in our - quickstart document.

-
-
J
-
JFK
-
Just Fast Keying, - a proposed simpler replacement for IKE.
-
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 section for more detail. For - the code see our primary site or one - of the mirror sites on this list.

-
-
Linux Security Modules (LSM)
-
a project to create an interface in the Linux kernel that supports - plug-in modules for various security policies. -

This allows multiple security projects to take different approaches - to security enhancement without tying the kernel down to one particular - approach. As I understand the history, several projects were pressing - Linus to incorporate their changes, the various sets of changes were - incompatible, and his answer was more-or-less "a plague on all your - houses; I'll give you an interface, but I won't incorporate - anything".

-

It seems to be working. There is a fairly active LSM - mailing list, and several projects are already using the - interface.

-
-
LSM
-
see Linux Security Modules
-
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.

-
-
mandatory access control
-
access control mechanisims which are not settable by the user (see discretionary access control), but are - enforced by the system. -

For example, a document labelled "secret, zebra" might be readable - only by someone with secret clearance working on Project Zebra. - Ideally, the system will prevent any transfer outside those boundaries. - For example, even if you can read it, you should not be able to e-mail - it (unless the recipient is appropriately cleared) or print it (unless - certain printers are authorised for that classification).

-

Mandatory access control is a required feature for some levels of Rainbow Book or Common Criteria - classification, but has not been widely used outside the military and - government. There is a good discussion of the issues in Anderson's Security Engineering.

-

The Security Enhanced Linux project is adding - mandatory access control to Linux.

-
-
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. See this - discussion.
-
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.

-

Hans Dobbertin found a weakness in MD5, and people often ask whether - this means MD5 is unsafe for IPsec. It doesn't. The IPsec RFCs discuss - Dobbertin's attack and conclude that it does not affect MD5 as used for - HMAC in IPsec.

-
-
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 - 2112 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 - 256 + 256 = 257work. - Against triple DES, you need 256 + 2112 ~= - 2112.

-

The memory requirements for 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 - Unit, 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 (Trusted Information - Systems, a firewall vendor) and McAfee anti-virus products. Among other - things, they offer an IPsec-based VPN product.
-
NAT
-
Network Address Translation, a process by which - firewall machines may change the addresses on packets as they go - through. For discussion, see our background section.
-
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 not intercepted 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.

-

First, it is wildly impractical for most - applications. Key management is at best difficult, often completely - impossible.

-

Second, it is extremely fragile. Small changes - which violate the conditions listed above do not just weaken the cipher - liitle. Quite often they destroy its security completely.

-
    -
  • Re-using the pad weakens the cipher to the point where it can be - broken with pencil and paper. With a computer, the attack is - trivially easy.
    • -
  • Using anything less than truly random numbers completely invalidates - the security proof.
    • -
  • In particular, using computer-generated pseudo-random numbers may - give an extremely weak cipher. It might also produce a good stream - cipher, if the pseudo-random generator is both well-designed and - properely seeded.
    • -
-

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; most systems marketed with such claims are worthless.

-

Finally, even if the system is implemented and used correctly, it is - highly vulnerable to a substitution attack. If an - attacker knows some 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 will never re-use.
    • -
  • However, an active attacker who knows the - plaintext can recover the pad, then use it to encode with whatever - he chooses. If he can get his version delivered instead of yours, - this may be a disaster. If you send "attack at dawn", the delivered - message can be anything the same length -- perhaps "retreat to - east" or "shoot generals".
    • -
  • An active attacker with only a reasonable guess at the plaintext - can try the same attack. If the guess is correct, this works and - the attacker's bogus message is delivered. If the guess is wrong, a - garbled message is delivered.
    • -
-

In general then, despite its theoretical perfection, the - one-time-pad has very limited practical application.

-

See also the one - time pad FAQ.

-
-
Opportunistic encryption (OE)
-
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 quickstart document.

-
-
Opportunistic responder
-
A host which accepts, but does not initiate, requests for - opportunistic encryption (OE). - An opportunistic responder has enabled OE in its - passive form (pOE) only. - A web server or file server may be usefully set up as an opportunistic - responder. -

Configuring passive OE is described in our - policy groups document.

-
-
Orange book
-
the most basic and best known of the US government's Rainbow Book series of computer security - standards.
-
P
-
P1363 standard
-
An IEEE standard for public key cryptography. Web page.
-
pOE
-
See Passive opportunistic encryption.
-
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.
-
Passive opportunistic encryption (pOE)
-
A form of - opportunistic encryption (OE) in which the - host will accept opportunistic connection requests, but will not - initiate such requests. A host which runs OE in its passive form only - is known as an opportunistic responder. -

Configuring passive OE is described in our - policy groups document.

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

-

See also -Phil -Karn's definition. -

-
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. Zimmerman left in - 2001, and early in 2002 NAI announced that they would no longer sell - PGP.. -

Versions 6.5 and later of the PGP product include PGPnet, an IPsec - client for Macintosh or for Windows 95/98/NT. See our interoperation document.

-
-
Photuris
-
Another key negotiation protocol, an alternative to IKE, described in RFCs 2522 and 2523.
-
PPP
-
Point-to-Point Protocol, originally a method of - connecting over modems or serial lines, but see also PPPoE.
-
PPPoE
-
PPP over Ethernet, a somewhat odd protocol that - makes Ethernet look like a point-to-point serial link. It is widely - used for cable or ADSL Internet services, apparently mainly because it - lets the providers use access control and address assignmment - mechanisms developed for dialup networks. Roaring Penguin provide a - widely used Linux implementation.
-
PPTP
-
Point-to-Point Tunneling Protocol, used - in some Microsoft VPN implementations. Papers discussing weaknesses in - it are on counterpane.com. It - is now largely obsolete, replaced by L2TP.
-
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 that 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
-
Rainbow books
-
A set of US government standards for evaluation of "trusted computer - systems", of which the best known was the Orange - Book. One fairly often hears references to "C2 security" or a - product "evaluated at B1". The Rainbow books define the standards - referred to in those comments. -

See this reference - page.

-

The Rainbow books are now mainly obsolete, replaced by the - international Common Criteria standards.

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

-

See the manual pages for ipsec_ranbits(8) and - ipsec_prng(3) for more on FreeS/WAN's use of randomness. Both depend on - the random(4) device driver..

-

A couple of years ago, there was extensive mailing list discussion - (archived here)of Linux - /dev/random and FreeS/WAN. Since then, the design of the random(4) - driver has changed considerably. Linux 2.4 kernels have the new - driver..

-
-
Raptor
-
A firewall product for Windows NT offerring IPsec-based VPN services. - Linux FreeS/WAN interoperates with Raptor; see our interop 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.
-
Reverse map
-
In DNS, a table where IP addresses can be used as - the key for lookups which return a system name and/or other - information.
-
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.

-
-
Rijndael
-
a block cipher designed by two Belgian - cryptographers, winner of the US government's AES - contest to pick a replacement for DES. See the Rijndael home - page.
-
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 algorithm, named for its three inventors. It is widely used and - likely to become moreso since it became free of patent encumbrances in - September 2000. -

RSA can be used to provide either encryption or digital - signatures. In IPsec, it is used only for signatures. These provide - gateway-to-gateway authentication for IKE negotiations.

-

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^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 < pq: - 
      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. Using c for ciphertext and i for the input plaintext, encryption is then:

- 
        c = i^e           modulo N
-
-

An attacker cannot deduce i 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 recover - the plaintext p since:

- 
        c^d == (i^e)^d    modulo N
-            == i^ed       modulo N
-            == i          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. Quite a few good mathematicians have tried both - problems, and no-one has announced success, but there is no proof they - are insoluble.

-
-
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 (IKE) and used by the lower (ESP and - AH). 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 as an index - to look up other things such as session keys and intialisation - vectors.

-

For more detail, see our section on IPsec - and/or RFC 2401.

-
-
SE Linux
-
Security Enhanced Linux, an NSA-funded project to add mandatory access control to Linux. See the project home page. -

According to their web pages, this work will include extending - mandatory access controls to IPsec tunnels.

-

Recent versions of SE Linux code use the Linux - Security Module interface.

-
-
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 - allows opportunistic encryption. Any pair of - machines which can authenticate each other via DNS can communicate - securely, without either a pre-existing shared secret or a shared PKI.

-
-
Secret key cryptography
-
See symmetric cryptography
-
Security Association
-
see SA
-
Security Enhanced Linux
-
see SE Linux
-
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
-
SHA-1
-
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.

-

The NSA made one small change after the release of the original SHA. - They did not give reasons. Iit may be a defense against some attack - they found and do not wish to disclose. Technically the modified - algorithm should be called SHA-1, but since it has replaced the - original algorithm in nearly all applications, it is generally just - referred to as SHA..

-
-
SHA-256
-
SHA-384
-
SHA-512
-
Newer variants of SHA designed to match the strength of the 128, 192 - and 256-bit keys of AES. The work to break an - encryption algorithm's strength by brute force is - 2 - - - keylength - - - operations but a birthday attack on a hash - needs only 2 - - - - hashlength - / - 2 - - - - , so as a general rule you need a hash twice the size of the key to - get similar strength. SHA-256, SHA-384 and SHA-512 are designed to - match the 128, 192 and 256-bit key sizes of AES, respectively.
-
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 - Protocols, 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 section - 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.
-
static IP address
-
an IP adddress which is pre-set on the machine itself, as opposed to - a dynamic address which is assigned by a DHCP server or obtained as part of the process of - establishing a PPP or PPPoE - connection
-
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.
-
TOS field
-
The Type Of - Service field in an IP header, used to control - qualkity of service routing.
-
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 guessed 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.

-

In general, traffic analysis by itself is not very useful. However, - in the context of a larger intelligence effort where quite a bit is - already known, it can be very useful. When you are solving a complex - puzzle, every little bit helps.

-

IPsec itself does not defend against traffic - analysis, 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. We discuss this here.

-
-
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
-
TTL
-
Time To Live, used - to control DNS caching. Servers discard cached - records whose TTL expires
-
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.

-
-
WEP (Wired Equivalent Privacy)
-
The cryptographic part of the IEEE standard for - wireless LANs. As the name suggests, this is designed to be only as - secure as a normal wired ethernet. Anyone with a network conection can - tap it. Its advocates would claim this is good design, refusing to - build in complex features beyond the actual requirements. -

Critics refer to WEP as "Wiretap Equivalent Privacy", and - consider it a horribly flawed design based on bogus "requirements". You - do not control radio waves as you might control your wires, so the - metaphor in the rationale is utterly inapplicable. A security policy - that chooses not to invest resources in protecting against certain - attacks which can only be conducted by people physically plugged into - your LAN may or may not be reasonable. The same policy is completely - unreasonable when someone can "plug in" from a laptop half a block - away..

-

There has been considerable analysis indicating that WEP is - seriously flawed. A FAQ on attacks against WEP is available. Part of it - reads:

- -
- ... attacks are practical to mount using only inexpensive - off-the-shelf equipment. We recommend that anyone using an 802.11 - wireless network not rely on WEP for security, and employ other - security measures to protect their wireless network. Note that our - attacks apply to both 40-bit and the so-called 128-bit versions of - WEP equally well.
-

WEP appears to be yet another instance of governments, and - unfortunately some vendors and standards bodies, deliberately promoting - hopelessly flawed "security" products, apparently mainly for the - benefit of eavesdropping agencies. See this discussion.

-
-
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, now part of Lucent. - Their QVPN products interoperate with Linux FreeS/WAN; see our interop document.
-
Y
-
Z
-
- - diff --git a/doc/src/index.html b/doc/src/index.html deleted file mode 100644 index e2530d711..000000000 --- a/doc/src/index.html +++ /dev/null @@ -1,55 +0,0 @@ - - - - FreeS/WAN index - - - - - -

FreeS/WAN documentation

- - - - - - - -

For technical support and other questions, use our mailing lists.

- -
        This index last changed:    $Date: 2004/03/15 20:35:24 $
- - - diff --git a/doc/src/initiatorstate.txt b/doc/src/initiatorstate.txt deleted file mode 100644 index 315f6da4c..000000000 --- a/doc/src/initiatorstate.txt +++ /dev/null @@ -1,66 +0,0 @@ - - | - | PF_ACQUIRE - | - V - .---------------. - | non-existant | - | connection | - `---------------' - | | | - send , | \ -expired pass / | \ send -conn. msg / | \ deny - ^ / | \ msg - | V | do \ -.---------------. | DNS \ .---------------. -| clear-text | | lookup `->| deny |---> expired -| connection | | for | connection | connection -`---------------' | destination `---------------' - ^ ^ | ^ - | | no record | | - | | OE-permissive V | no record - | | .---------------. | OE-paranoid - | `------------| potential OE |---------' - | | connection | ^ - | `---------------' | - | | | - | | got TXT record | DNSSEC failure - | | reply | - | V | wrong - | .---------------. | failure - | | authenticate |---------' - | | & parse TXT RR| ^ - | repeated `---------------' | - | ICMP | | - | failures | initiate IKE to | - | (short-timeout) | responder | - | V | - | phase-2 .---------------. | failure - | failure | pending |---------' - | (normal | OE | ^ - | timeout) | |invalid | phase-2 failure (short-timeout) - | | |<--.SPI | ICMP failures (normal timeout) - | | | | | - | | +=======+ |---' | - | | | IKE | | ^ | - `--------------| | states|---------------' - | +=======+ | | - `---------------' | - | | invalid SPI - | | - V | rekey time - .--------------. | - | keyed |<---|-------------------------------. - | connection |----' | - `--------------' | - | | - | | - V | - .--------------. connection still active | - clear-text----->| expired |------------------------------------' - deny----->| connection | - `--------------' - - -$Id: initiatorstate.txt,v 1.1 2004/03/15 20:35:24 as Exp $ diff --git a/doc/src/install.html b/doc/src/install.html deleted file mode 100644 index 09d7c5a67..000000000 --- a/doc/src/install.html +++ /dev/null @@ -1,378 +0,0 @@ - - - - Installing FreeS/WAN - - - - -

Installing FreeS/WAN

- -

This document will teach you how to install Linux FreeS/WAN. -If your distribution comes with Linux FreeS/WAN, we offer - tips to get you started.

- -

Requirements

- -

To install FreeS/WAN you must:

- - -

Choose your install method

- -

There are three basic ways to get FreeS/WAN onto your system:

- - -

FreeS/WAN ships with some Linuxes

- -

FreeS/WAN comes with these distributions. - -

If you're running one of these, include FreeS/WAN in the choices you -make during installation, or add it later using the distribution's tools. -

- -

FreeS/WAN may be altered...

-

Your distribution may have integrated extra features, such as Andreas -Steffen's X.509 patch, into FreeS/WAN. It may also use custom -startup script locations or directory names.

- -

You might need to create an authentication keypair

- -

If your FreeS/WAN came with your distribution, you may wish to - generate a fresh RSA key pair. FreeS/WAN will use these keys - for authentication. - -

-To do this, become root, and type: -

- -
    ipsec newhostkey --output /etc/ipsec.secrets --hostname xy.example.com
-    chmod 600 /etc/ipsec.secrets
- -

where you replace xy.example.com with your machine's fully-qualified -domain name. Generate some randomness, for example by wiggling your mouse, -to speed the process. -

- -

The resulting ipsec.secrets looks like:

-
: RSA   {
-        # RSA 2192 bits   xy.example.com   Sun Jun 8 13:42:19 2003
-        # for signatures only, UNSAFE FOR ENCRYPTION
-        #pubkey=0sAQOFppfeE3cC7wqJi...
-        Modulus: 0x85a697de137702ef0...
-        # everything after this point is secret
-        PrivateExponent: 0x16466ea5033e807...
-        Prime1: 0xdfb5003c8947b7cc88759065...
-        Prime2: 0x98f199b9149fde11ec956c814...
-        Exponent1: 0x9523557db0da7a885af90aee...
-        Exponent2: 0x65f6667b63153eb69db8f300dbb...
-        Coefficient: 0x90ad00415d3ca17bebff123413fc518...
-        }
-# do not change the indenting of that "}"
- -

In the actual file, the strings are much longer.

- - -

Start and test FreeS/WAN

- -

You can now start FreeS/WAN and -test whether it's been successfully installed..

- - -

RPM install

- -

These instructions are for a recent Red Hat with a stock Red Hat kernel. -We know that Mandrake and SUSE also produce FreeS/WAN RPMs. If you're -running either, install using your distribution's tools.

- -

Download RPMs

- -

Decide which functionality you need:

- - - -

For 2.6 kernels, get the latest FreeS/WAN userland RPM, for example:

-
    freeswan-userland-2.04.9-0.i386.rpm
- -

Note: FreeS/WAN's support for 2.6 kernel IPsec is preliminary. Please see -2.6.known-issues, and the latest -mailing list reports.

-

Change to your new FreeS/WAN directory, and make and install the - -

For 2.4 kernels, get both kernel and userland RPMs. -Check your kernel version with

-
    uname -r
- -

Get a kernel module which matches that version. For example:

-
    freeswan-module-2.04_2.4.20_20.9-0.i386.rpm
-

Note: These modules -will only work on the Red Hat kernel they were built for, -since they are very sensitive to small changes in the kernel.

- - -

Get FreeS/WAN utilities to match. For example:

-
    freeswan-userland-2.04_2.4.20_20.9-0.i386.rpm
- - -

For freeswan.org RPMs: check signatures

- -

While you're at our ftp site, grab the RPM signing key

-
    freeswan-rpmsign.asc
- -

If you're running RedHat 8.x or later, import this key into the RPM -database:

-
    rpm --import freeswan-rpmsign.asc
- -

For RedHat 7.x systems, you'll need to add it to your -PGP keyring:

-
    pgp -ka freeswan-rpmsign.asc
- - -

Check the digital signatures on both RPMs using:

-
    rpm --checksig freeswan*.rpm
- -

You should see that these signatures are good:

-
    freeswan-module-2.04_2.4.20_20.9-0.i386.rpm: pgp md5 OK
-    freeswan-userland-2.04_2.4.20_20.9-0.i386.rpm: pgp md5 OK
- - -

Install the RPMs

- -

Become root:

-
    su
- -

For a first time install, use:

-
    rpm -ivh freeswan*.rpm
- -

To upgrade existing RPMs (and keep all .conf files in place), use:

-
    rpm -Uvh freeswan*.rpm
- -

If you're upgrading from FreeS/WAN 1.x to 2.x RPMs, and encounter problems, -see this note.

- - -

Start and Test FreeS/WAN

- -

Now, start FreeS/WAN and test your -install.

- - -

Install from Source

- - -

Decide what functionality you need

- -

Your choices are:

- - -

Download FreeS/WAN

- -

Download the source tarball you've chosen, along with any patches.

- -

For freeswan.org source: check its signature

- -

While you're at our ftp site, get our source signing key

-
    freeswan-sigkey.asc
- -

Add it to your PGP keyring:

-
    pgp -ka freeswan-sigkey.asc
- - -

Check the signature using:

-
    pgp freeswan-2.04.tar.gz.sig freeswan-2.04.tar.gz
-

You should see something like:

-
    Good signature from user "Linux FreeS/WAN Software Team (build@freeswan.org)".
-    Signature made 2002/06/26 21:04 GMT using 2047-bit key, key ID 46EAFCE1
- - -

Untar, unzip

- -

As root, unpack your FreeS/WAN source into /usr/src.

-
    su
-    mv freeswan-2.04.tar.gz /usr/src
-    cd /usr/src
-    tar -xzf freeswan-2.04.tar.gz
-
- -

Patch if desired

- -

Now's the time to add any patches. The contributor may have special -instructions, or you may simply use the patch command.

- -

... and Make

- -

Choose one of the methods below.

- -

Userland-only Install for 2.6 kernels

- - -

Note: FreeS/WAN's support for 2.6 kernel IPsec is preliminary. Please see -2.6.known-issues, and the latest -mailing list reports.

-

Change to your new FreeS/WAN directory, and make and install the -FreeS/WAN userland tools.

-
    cd /usr/src/freeswan-2.04
-    make programs
-    make install
- -

Now, start FreeS/WAN and -test your install.

- - - -

KLIPS install for 2.2, 2.4, or 2.6 kernels

- - - -

To make a modular version of KLIPS, along with other FreeS/WAN programs -you'll need, use the command sequence below. This will -change to your new FreeS/WAN directory, make the FreeS/WAN module (and other -stuff), and install it all.

-
    cd /usr/src/freeswan-2.04
-    make oldmod
-    make minstall
- -

Start FreeS/WAN and -test your install.

- - - -

To link KLIPS statically into your kernel (using your old kernel settings), -and install other FreeS/WAN components, do: -

-
    cd /usr/src/freeswan-2.04
-    make oldmod
-    make minstall
- - -

Reboot your system and test your -install.

- -

For other ways to compile KLIPS, see our Makefile.

- - - -

Start FreeS/WAN and test your install

- -

Bring FreeS/WAN up with:

-
    service ipsec start
- -

This is not necessary if you've rebooted.

- -

Test your install

- -

To check that you have a successful install, run:

-
    ipsec verify
- -

You should see at least:

-
-    Checking your system to see if IPsec got installed and started correctly
-    Version check and ipsec on-path                             [OK]
-    Checking for KLIPS support in kernel                        [OK]
-    Checking for RSA private key (/etc/ipsec.secrets)           [OK]
-    Checking that pluto is running                              [OK]
-
- -

If any of these first four checks fails, see our -troubleshooting guide. -

- - -

Making FreeS/WAN play well with others

- -

There are at least a couple of things on your system that might -interfere with FreeS/WAN, and now's a good time to check these:

- - - -

Configure for your needs

- -

You'll need to configure FreeS/WAN for your local site. Have a look at our -opportunism quickstart guide to see if that -easy method is right for your needs. Or, see how to -configure a network-to-network or Road Warrior style VPN. -

- - - - - - diff --git a/doc/src/interop.html b/doc/src/interop.html deleted file mode 100644 index dd4f8c577..000000000 --- a/doc/src/interop.html +++ /dev/null @@ -1,1802 +0,0 @@ - - - - FreeS/WAN interoperation Grid - - - - - -

Interoperating with FreeS/WAN

- - -

The FreeS/WAN project needs you! We rely on the user community to keep -up to date. Mail users@lists.freeswan.org with your -interop success stories.

- -

Please note: Most of our interop examples feature -Linux FreeS/WAN 1.x config files. You can convert them to 2.x files fairly -easily with the patch in our -Upgrading Guide. -

- -

Interop at a Glance

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
 FreeS/WAN VPNRoad WarriorOE
 PSKRSA SecretX.509
(requires patch)		NAT-Traversal
(requires patch)		Manual
Keying		  
More Compatible
FreeS/WAN - YesYesYesYesYesYesYes
isakmpd (OpenBSD) - Yes Yes Yes No    
Kame (FreeBSD, -
NetBSD, MacOSX) -
aka racoon - 		YesYesYes Yes No
McAfee VPN
was PGPNet - 		YesYesYes  YesNo
Microsoft
Windows 2000/XP - 		Yes Yes  YesNo
SSH Sentinel - Yes YesMaybe YesNo
Safenet SoftPK
/SoftRemote - 		Yes Yes  YesNo
Other
6Wind -   Yes   No
Alcatel Timestep - Yes     No
Apple Macintosh
System 10+ - 		MaybeYesMaybe Maybe No
AshleyLaurent
VPCom - 		Yes     No
Borderware - Yes    NoNo
Check Point FW-1/VPN-1 - Yes Yes  YesNo
Cisco with 3DES - YesMaybe Maybe  No
Equinux VPN Tracker
-(for Mac OS X) - - 		YesYesYes Maybe No
F-Secure - Yes  MaybeYesYesNo
Gauntlet GVPN - Yes Yes   No
IBM AIX - Yes Maybe   No
IBM AS/400 - Yes     No
Intel Shiva
LANRover/Net Structure - 		Yes     No
LanCom (formerly ELSA) - Yes     No
Linksys - Maybe No  YesNo
Lucent - Partial     No
Netasq -   Yes   No
netcelo -   Yes   No
Netgear fvs318 - Yes     No
Netscreen 100
or 5xp - 		Yes    MaybeNo
Nortel Contivity - Partial YesMaybe  No
RadGuard - Yes     No
Raptor - Yes   Yes No
Redcreek Ravlin - Yes/Partial     No
SonicWall - Yes   MaybeNoNo
Sun Solaris - Yes Yes Yes No
Symantec - Yes     No
Watchguard
Firebox - 		Yes   Yes No
Xedia Access Point
/QVPN - 		Yes     No
Zyxel Zywall
/Prestige - 		Yes     No
 PSKRSA SecretX.509
(requires patch)		NAT-Traversal
(requires patch)		Manual
Keying		  
 FreeS/WAN VPNRoad WarriorOE
- - - - -

Key

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
YesPeople report that this works for them.
[Blank]We don't know.
NoWe have reason to believe -it was, at some point, not possible to get this to work.
PartialPartial success. For example, a connection can be -created from one end only.
Yes/PartialMixed reports.
MaybeWe think the answer is "yes", but need confirmation.
- -

Basic Interop Rules

- -

Vanilla -FreeS/WAN implements these parts of the -IPSec specifications. You can add more with -Super FreeS/WAN, -but what we offer may be enough for many users.

- - - -

We offer a set of proposals which is not user-adjustable, but covers -all combinations that we can offer. -FreeS/WAN always proposes triple DES encryption and -Perfect Forward Secrecy (PFS). -In addition, we propose Diffie Hellman groups 5 and 2 -(in that order), and MD5 and SHA-1 hashes. -We accept the same proposals, in the same order of preference. -

- -

Other interop notes:

- - -

Longer Stories

- - -

For More Compatible Implementations

- - -

FreeS/WAN

- -

-See our documentation at freeswan.org -and the Super FreeS/WAN docs at -freeswan.ca. -Some user-written HOWTOs for FreeS/WAN-FreeS/WAN connections -are listed in our Introduction. -

- -

See also:

- - - - -

Back to chart

- - -

isakmpd (OpenBSD)

- -

OpenBSD FAQ: Using IPsec
-Hans-Joerg Hoexer's interop Linux-OpenBSD (PSK)
-Skyper's configuration (PSK) -
- -French page with configs (X.509) - - -

- -

Back to chart

- - -

Kame

- - - -

Kame homepage, with FAQ
-NetBSD's IPSec FAQ
-Ghislaine's post explaining some interop peculiarities -

-

-Itojun's Kame-FreeS/WAN interop tips (PSK)
-Ghislaine Labouret's French page with links to matching FreeS/WAN and Kame configs (RSA)
-Markus Wernig's -HOWTO (X.509, BSD gateway)
-Frodo's Kame-FreeS/WAN interop (X.509)
-Kame as a WAVEsec client. -

- -

Back to chart

- - -

PGPNet/McAfee

- -

-

-

-Tim Carr's Windows Interop Guide (X.509)
-Hans-Joerg Hoexer's Guide for Linux-PGPNet (PSK)
-Kai Martius' instructions using RSA Key-Extractor Tool (RSA)
-    Christian Zeng's page (RSA) based on Kai's work. English or German.
- -Oscar Delgado's PDF (X.509, no configs)
-Ryan's HOWTO for FreeS/WAN-PGPNet (X.509). Through a Linksys Router with IPsec Passthru enabled.
-Jean-Francois Nadeau's Practical Configuration (Road Warrior with PSK)
-Wouter Prins' HOWTO (Road Warrior with X.509)
-

-

-Rekeying problem with FreeS/WAN and older PGPNets
-

- -

-DHCP over IPSEC HOWTO for FreeS/WAN (requires X.509 and dhcprelay patches) - -

- -

Back to chart

- - -

Microsoft Windows 2000/XP

- - - -

-Tim Carr's Windows Interop Guide (X.509)
- -James Carter's -instructions (X.509, NAT-T)
- - -Jean-Francois Nadeau's Net-net Configuration (PSK)
- - -Telenor's Node-node Config (Transport-mode PSK)
- -Marcus Mueller's HOWTO using his VPN config tool (X.509). Tool also works with PSK.
- - -Nate Carlson's HOWTO using same tool (Road Warrior with X.509). Unusually, -FreeS/WAN is the Road Warrior here.
- - -Oscar Delgado's PDF (X.509, no configs)
- -Tim Scannell's Windows XP Additional Checklist (X.509)
-

- - - -

- -Microsoft's page on Win2k TCP/IP security features
- - -Microsoft's Win2k IPsec debugging tips
- - - -MS VPN may fall back to 1DES -

- -

Back to chart

- - -

SSH Sentinel

- - - -

-SSH's Sentinel-FreeSWAN interop PDF (X.509)
-Nadeem Hassan's -SUSE-to-Sentinel article (Road warrior with X.509)
-O-Zone's Italian HOWTO (Road Warrior, X.509, DHCP)
-

- - -

Back to chart

- - - -

Safenet SoftPK/SoftRemote

- - - -

- -Whit Blauvelt's SoftRemote tips
- -Tim Wilson's tips (X.509) -Workaround for a "gotcha" -

- -

-Jean-Francois Nadeau's -Practical Configuration (Road Warrior with PSK)
- -Terradon Communications' PDF (Road Warrior with PSK)
- -Seaan.net's PDF (Road Warrior to Subnet, with PSK) -
- -Red Baron Consulting's PDF (Road Warrior with X.509) -

- -

Back to chart

- - - - - - - - -

For Other Implementations

- - - -

6Wind

- -

- - -French page with configs (X.509) - -

- -

Back to chart

- - - -

Alcatel Timestep

- -

- -Alain Sabban's settings (PSK or PSK road warrior; through static NAT)
- -Derick Cassidy's configs (PSK)
- -David Kerry's Timestep settings (PSK) -
- -Kevin Gerbracht's ipsec.conf (X.509) -

- -

Back to chart

- - - -

Apple Macintosh System 10+

- - - - -

-James Carter's -instructions (X.509, NAT-T) -

- - -

Back to chart

- - - - - - -

AshleyLaurent VPCom

- -

- -Successful interop report, no details -

- -

Back to chart

- - -

Borderware

- - - -

- -Philip Reetz' configs (PSK)
- - -Borderware server does not support FreeS/WAN road warriors
- -Older Borderware may not support Diffie Hellman groups 2, 5
-

- - -

Back to chart

- - - -

Check Point VPN-1 or FW-1

- - - -

- -AERAsec's Firewall-1 NG site (PSK, X.509, Road Warrior with X.509, -other algorithms)
-     - -AERAsec's detailed Check Point-FreeS/WAN support matrix
-Checkpoint.com PDF: Linux as a VPN Client to FW-1 (PSK)
- -PhoneBoy's Check Point FAQ (on Check Point -only, not FreeS/WAN)
- -

- -

-Chris -Harwell's tips & FreeS/WAN configs (PSK)
- -Daniel -Tombeil's configs (PSK) - -

- -

Back to chart

- - -

Cisco

- - - - -

-SANS Institute HOWTO (PSK). Detailed, with extensive references.
-Short HOWTO (PSK)
- -French page with configs for Cisco IOS, PIX and VPN 3000 (X.509) -
- -Dave -McFerren's sample configs (PSK)
-Wolfgang -Tremmel's sample configs (PSK road warrior)
- -Old doc from Pete Davis, with William Watson's updated Tips (PSK)
-

- -

Some PIX specific information:
- - -Waikato Linux Users' Group HOWTO. Nice detail (PSK) -
- -John Leach's configs (PSK) -
- -Greg Robinson's settings (PSK) -
- -Scott's ipsec.conf for PIX (PSK, FreeS/WAN side only)
-Rick -Trimble's PIX and FreeS/WAN settings (PSK)
-

- - - -

-Cisco VPN support page
- -Cisco IPsec information page -

- -

Back to chart

- - - - -

Equinux VPN tracker (for Mac OS X)

- - - - -

-Equinux provides this -excellent interop PDF (PSK, RSA, X.509). -

- -

Back to chart

- - -

F-Secure

- - - -

pingworks.de's - "Connecting F-Secure's VPN+ to Linux FreeS/WAN" (PSK road warrior)
-    Same thing as PDF
-Success report, no detail (PSK)
-Success report, no detail (Manual) -

- - - -

Back to chart

- - - -

Gauntlet GVPN

- -

-Richard Reiner's ipsec.conf (PSK) -
- -Might work without that pesky firewall... (PSK)
- -In late July, 2003 Alexandar Antik reported success interoperating -with Gauntlet 6.0 for Solaris (X.509). Unfortunately the message is not -properly archived at this time. -

- -

Back to chart

- - - -

IBM AIX

- -

-IBM's "Built-In Network Security with AIX" (PSK, X.509)
- -IBM's tip: importing Linux FreeS/WAN settings into AIX's ikedb -(PSK) -

- -

Back to chart

- - - -

IBM AS/400

- - - -

-Richard Welty's tips and tricks
-

- -

Back to chart

- - - -

Intel Shiva LANRover / Net Structure

- - - -

- -Snowcrash's configs (PSK)
- - -Old configs from an interop (PSK)
- - -The day Shiva tickled a Pluto bug (PSK)
- -     - -Follow up: success! -

- -

Back to chart

- - - -

LanCom (formerly ELSA)

- - - -

-Jakob Curdes successfully created a PSK connection with the LanCom 1612 in -August 2003. - -

- -

Back to chart

- - - -

Linksys

- - - -
As tunnel endpoint
-

- -Ken Bantoft's instructions (Road Warrior with PSK)
- -Nate Carlson's caveats -

- -
In IPsec passthrough mode
-

- -Sample HOWTO through a Linksys Router
- -Nadeem Hasan's configs
- -Brock Nanson's tips
-

- -

Back to chart

- - -

Lucent

- -

- -Partial success report; see also the next message in thread -

- - -

Back to chart

- - -

Netasq

- -

- -French page with configs (X.509) - -

- - -

Back to chart

- - - -

Netcelo

- -

- -French page with configs (X.509) - - - -

- -

Back to chart

- - - -

Netgear fvs318

- - - -

- -John Morris' setup (PSK) -

- -

Back to chart

- - - -

Netscreen 100 or 5xp

- -

- -Errol Neal's settings (PSK)
- -Corey Rogers' configs (PSK, no PFS)
- -Jordan Share's configs (PSK, 2 subnets, through static NAT)
- -Set src proxy_id to your protected subnet/mask
- - -French page with ipsec.conf, Netscreen screen shots (X.509, may -need to revert to PSK...) - -

-

- -A report of a company using Netscreen with FreeS/WAN on a large scale -(FreeS/WAN road warriors?) -

- -

Back to chart

- - - -

Nortel Contivity

- - - -

- -JJ Streicher-Bremer's mini HOWTO for old & new software. (PSK with two subnets) -
- -French page with configs (X.509). This succeeds using the above X.509 tip. -

- - - -

Back to chart

- - -

Radguard

- -

- -Marko Hausalo's configs (PSK). Note: These do create a connection, -as you can see by "IPsec SA established".
- - -Claudia Schmeing's comments -

- -

Back to chart

- - -

Raptor (NT or Solaris)

- -

- -

- -

- -Peter Mazinger's settings (PSK)
- - -Peter Gerland's configs (PSK)
- - -Charles Griebel's configs (PSK).
- - -Lumir Srch's tips (PSK) - -

- -

- -John Hardy's configs (Manual)
- - -Older Raptors want 3DES keys in 3 parts (Manual).
- - -Different keys for each direction? (Manual)
- -

- -

Back to chart

- - - -

Redcreek Ravlin

- - - -

Back to chart

- - - -

SonicWall

- - - -

-Paul Wouters' config (PSK)
- -Dilan Arumainathan's configuration (PSK)
-Dariush's setup... only opens -one way (PSK)
- -Andreas Steffen's tips (X.509)
- -

- -

Back to chart

- - - -

Sun Solaris

- - -

- -Reports of some successful interops from a fellow @sun.com. -See also these follow up posts.
- -Aleks Shenkman's configs (Manual in transport mode) -
- -

- -

Back to chart

- - - -

Symantec

- - - -

-Andreas Steffen's configs for Symantec 200R (PSK) -

- -

Back to chart

- - - - -

Watchguard Firebox

- - - -

- -WatchGuard's HOWTO (PSK)
- -Ronald C. Riviera's Settings (PSK)
- -Walter Wickersham's Notes (PSK)
- - -Max Enders' Configs (Manual) -

- -

- -Old known issue with auto keying
- - -Tips on key generation and format (Manual)
-

- -

Back to chart

- - - -

Xedia Access Point/QVPN

- -

- -Hybrid IPsec/L2TP connection settings (X.509) -
- - Xedia's LAN-LAN links don't use multiple tunnels -
-     - - That explanation, continued - -

- -

Back to chart

- - - -

Zyxel

- - -

- -Zyxel's Zywall to FreeS/WAN instructions (PSK)
- -Zyxel's Prestige to FreeS/WAN instructions (PSK). Note: not all Prestige -versions include VPN software.
- -Fabrice Cahen's - HOWTO (PSK)
-     -

- -

Back to chart

- - - - - - diff --git a/doc/src/intro.html b/doc/src/intro.html deleted file mode 100644 index 09c352c00..000000000 --- a/doc/src/intro.html +++ /dev/null @@ -1,887 +0,0 @@ - - - - Introduction to FreeS/WAN - - - - - -

Introduction

- -

This section gives an overview of:

- - -

This section is intended to cover only the essentials, things you -should know before trying to use FreeS/WAN.

- -

For more detailed background information, see the history and politics and -IPsec protocols sections.

- -

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 approach has -both considerable advantages and some limitations. For discussion, see our IPsec section

- -

IPsec can be used on any machine which does IP networking. Dedicated IPsec -gateway machines can be installed wherever required to protect traffic. IPsec -can also run on routers, on firewall machines, on various application -servers, and on end-user desktop or laptop machines.

- -

Three protocols are used

- - -

Our implementation has three main parts:

- - -

IPsec is optional for the current (version 4) Internet Protocol. FreeS/WAN -adds IPsec to the Linux IPv4 network stack. Implementations of IP version 6 are required to include -IPsec. Work toward integrating FreeS/WAN into the Linux IPv6 stack has started.

- -

For more information on IPsec, see our -IPsec protocols section, -our collection of IPsec -links or the RFCs which are the official -definitions of these protocols.

- -

Interoperating with other IPsec -implementations

- -

IPsec is designed to let different implementations work together. We -provide:

- - -

The VPN Consortium fosters cooperation among implementers and -interoperability among implementations. Their web site has much more information.

- -

Advantages of IPsec

- -

IPsec has a number of security advantages. Here are some independently -written articles which discuss these:

- -

-SANS institute papers. See the section -on Encryption &VPNs. -
-Cisco's -white papers on "Networking Solutions". -
- -Advantages of ISCS (Linux Integrated Secure Communications System; -includes FreeS/WAN and other software). - -

- - -

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:

- - -

There is enough opportunity in these applications that vendors are -flocking to them. IPsec is being built into routers, into firewall products, -and into major operating systems, primarily to support these applications. -See our list of implementations for -details.

- -

We support both of those applications, and various less common IPsec -applications as well, but we also add one of our own:

- - -

This is an extension we are adding to the protocols. FreeS/WAN is the -first prototype implementation, though we hope other IPsec implementations -will adopt the technique once we demonstrate it. See project -goals below for why we think this is important.

- -

A somewhat more detailed description of each of these applications is -below. Our quickstart section will -show you how to build each of them.

- -

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:

- - -

These require somewhat different setup than VPN gateways with static -addresses and with client systems behind them, but are basically not -problematic.

- -

There are some difficulties which appear for some road warrior -connections:

- - -

In most situations, however, FreeS/WAN supports road warrior connections -just fine.

- -

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.

- -

Both systems pick up the authentication information they need from the DNS (domain name service), the service they -already use to look up IP addresses. Of course the administrators must put -that information in the DNS, and must set up their gateways with -opportunistic encryption enabled. Once that is done, everything is automatic. -The gateways look for opportunities to encrypt, and encrypt whatever they -can. Whether they also accept unencrypted communication is a policy decision -the administrator can make.

- -

This technique can give two large payoffs:

- - -

Opportunistic encryption is not (yet?) a standard part of the IPsec -protocols, but an extension we are proposing and demonstrating. For details -of our design, see links below.

- -

Only one current product we know of implements a form of opportunistic -encryption. Secure sendmail will automatically -encrypt server-to-server mail transfers whenever possible.

- -

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:

- - -

Automatic keying is much more secure, since if an enemy gets one key only -messages between the previous re-keying and the next are exposed. It is -therefore the usual mode of operation for most IPsec deployment, and the mode -we use in our setup examples. FreeS/WAN does support manual keying for -special circumstanes. See this section.

- -

For automatic keying, the two systems must authenticate each other during -the negotiations. There is a choice of methods for this:

- - -

Public key techniques are much preferable, for reasons discussed later, and will be used in all our setup -examples. FreeS/WAN does also support auto-keying with shared secret -authentication. See this section.

- -

The FreeS/WAN project

- -

For complete information on the project, see our web site, freeswan.org.

- -

In summary, we are implementing the IPsec protocols for Linux and extending them -to do opportunistic encryption.

- -

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:

- - -

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:

- - -

The rest of the team are Canadians, working in Canada. (Why Canada?)

- - -

The project is funded by civil libertarians who consider our goals -worthwhile. Most of the team are paid for this work.

- -

People outside this core team have made substantial contributions. See

- - -

Additional contributions are welcome. See the FAQ for details.

- -

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.

- -

FreeS/WAN is, however, quite widely used. Products we know of that use it -are listed below. We would appreciate hearing, via the mailing lists, of any we don't know of.

- -

Full Linux distributions

- -

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

- - -

For distributions which do not include FreeS/WAN and are not Redhat (which -we develop and test on), there is additional information in our compatibility section.

- -

The server edition of Corel Linux -(Canada) also had FreeS/WAN, but Corel have dropped that product line.

- -

Linux kernel distributions

- - - - -

Office server distributions

- -

FreeS/WAN is also included in several distributions aimed at the market -for turnkey business servers:

- - -

Firewall distributions

- -

Several distributions intended for firewall and router applications -include FreeS/WAN:

- - -

There are also several sets of scripts available for managing a firewall -which is also acting as a FreeS/WAN IPsec gateway. See this list.

- -

Firewall and VPN products

- -

Several vendors use FreeS/WAN as the IPsec component of a turnkey firewall -or VPN product.

- -

Software-only products:

- - -

Products that include the hardware:

- - -

Rebel.com, makers of the Netwinder Linux -machines (ARM or Crusoe based), had a product that used FreeS/WAN. The -company is in receivership so the future of the Netwinder is at best unclear. -PKIX patches for FreeS/WAN developed at Rebel -are listed in our web links document.

- - -

Information sources

- -

This HowTo, in multiple formats

- -

FreeS/WAN documentation up to version 1.5 was available only in HTML. Now -we ship two formats:

- - -

and provide a Makefile to generate other formats if required:

- - -

The Makefile assumes the htmldoc tool is available. You can download it -from Easy Software.

- -

All formats should be available at the following websites:

- - -

The distribution tarball has only the two HTML formats.

- -

Note: If you need the latest doc version, for example to -see if anyone has managed to set up interoperation between FreeS/WAN and -whatever, then you should download the current snapshot. What is on the web -is documentation as of the last release. Snapshots have all changes I've -checked in to date.

- -

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:

- - -

Man pages for common commands include:

- - -

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

- -

In the event of disagreement between this HTML documentation and the man -pages, the man pages are more likely correct since they are written by the -implementers. Please report any such inconsistency on the mailing list.

- -

Other documents in the distribution

- -

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

- -

The Libdes encryption library we use has its own documentation. You can -find it in the library directory..

- -

Background material

- -

Throughout this documentation, I write as if the reader had at least a -general familiarity with Linux, with Internet Protocol networking, and with -the basic ideas of system and network security. Of course that will certainly -not be true for all readers, and quite likely not even for a majority.

- -

However, I must limit amount of detail on these topics in the main text. -For one thing, I don't understand all the details of those topics myself. -Even if I did, trying to explain everything here would produce extremely long -and almost completely unreadable documentation.

- -

If one or more of those areas is unknown territory for you, there are -plenty of other resources you could look at:

-
-
Linux
-
the Linux Documentation Project - or a local Linux User Group - and these links
-
IP networks
-
Rusty Russell's Networking - Concepts HowTo and these links
-
Security
-
Schneier's book Secrets and Lies - and these links
-
- -

Also, I do make an effort to provide some background material in these -documents. All the basic ideas behind IPsec and FreeS/WAN are explained here. -Explanations that do not fit in the main text, or that not everyone will -need, are often in the glossary, which is -the largest single file in this document set. There is also a background file containing various -explanations too long to fit in glossary definitions. All files are heavily -sprinkled with links to each other and to the glossary. If some passage -makes no sense to you, try the links.

- -

For other reference material, see the bibliography and our collection of web links.

- -

Of course, no doubt I get this (and other things) wrong sometimes. -Feedback via the mailing lists is welcome.

- -

Archives of the project mailing list

- -

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

- -The two archives use completely different search engines. You might want to -try both. - -

More recently we have expanded to five lists, each with its own -archive.

- -

More information on mailing lists.

- -

User-written HowTo information

- -

Various user-written HowTo documents are available. The ones covering -FreeS/WAN-to-FreeS/WAN connections are:

- - -

User-wriiten HowTo material may be especially helpful if you need -to interoperate with another IPsec implementation. We have neither -the equipment nor the manpower to test such configurations. Users seem to be -doing an admirable job of filling the gaps.

- - -

Check what version of FreeS/WAN user-written documents cover. The software -is under active development and the current version may be significantly -different from what an older document describes.

- -

Papers on FreeS/WAN

- -

Two design documents show team thinking on new developments:

- - -

Both documents are works in progress and are frequently revised. For the -latest version, see the design mailing list. Comments -should go to that list.

- -

There is now an Internet -Draft on Opportunistic Encryption by Michael Richardson, Hugh Redelmeier -and Henry Spencer. This is a first step toward getting the protocol -standardised so there can be multiple implementations of it. Discussion of it -takes place on the IETF IPsec -Working Group mailing list.

- -

A number of papers giving further background on FreeS/WAN, or exploring -its future or its applications, are also available:

- - -

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

- -

There are also several papers in languages other than English, see our web links.

- -

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 and the version of MD5 that we use each have their own license.

- -

Distribution sites

- -

FreeS/WAN is available from a number of sites.

- -

Primary site

- -

Our primary site, is at xs4all (Thanks, folks!) in Holland:

- - -

Mirrors

- -

There are also mirror sites all over the world:

- - -

Thanks to those folks as well.

- -

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:

- - -

Any of those will have a list of other "munitions" mirrors. There is also -a CD available.

- -

Links to other sections

- -

For more detailed background information, see:

- - -

To begin working with FreeS/WAN, go to our quickstart guide.

- - diff --git a/doc/src/ipsec.html b/doc/src/ipsec.html deleted file mode 100644 index 4647eaf66..000000000 --- a/doc/src/ipsec.html +++ /dev/null @@ -1,1206 +0,0 @@ - - - - IPsec protocols - - - - - -

The IPsec protocols

- -

This section provides information on the IPsec protocols which FreeS/WAN -implements. For more detail, see the RFCs.

- -

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

- -

Protocols and phases

- -

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" (also written as 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.

- -

There is more detail below, but a quick summary of how the whole thing -works is:

-
-
Phase one IKE (main mode exchange)
-
sets up a keying channel (ISAKMP SA) between the two gateways
-
Phase two IKE (quick mode exchange)
-
sets up data channels (IPsec SAs)
-
IPsec proper
-
exchanges data using AH or ESP
-
- -

Both phases of IKE are repeated periodically to automate re-keying.

- -

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.

- - -

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.

- - -

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:

- - -

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 provide a - useful security service -- only encrypted data is passed over the - Internet -- but it 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.

- - -

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:

- - -

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:

- - -

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 about any of those, then he has -interesting intelligence on your company, whether or not he can read the -messages themselves.

- -

Even just knowing that there is network traffic between two sites may tell -an analyst something useful, especially when combined with whatever other -information he or she may have. For example, if you know Company A is having -cashflow problems and Company B is looking for aquisitions, then knowing that -packets are passing between the two is interesting. It is more interesting if -you can tell it is email, and perhaps yet more if you know the sender and -recipient.

- -

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, to improve resistance to traffic analysis, you -should encrypt as much traffic as possible, not just as much as seems -necessary.

- -

Using multiple encryption

- -

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:

- - -

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:

- - -

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:

- - -

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 won the -AES competition to choose a relacement for -DES. It will almost certainly be added to FreeS/WAN and to other IPsec -implementations. Patches are already -available.

- -

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

- -

Choice of hash algorithm

- -

The IPsec RFCs require two hash algorithms -- MD5 and SHA-1 -- -both of which FreeS/WAN implements.

- -

Various other algorithms -- such as RIPEMD and Tiger -- are listed in the -RFCs as optional. None of these are in the FreeS/WAN distribution, or are -likely to be added, although user patches exist -for several of them.

- -

Additional hash algorithms -- SHA-256, -SHA-384 and SHA-512 -- may be required to give hash strength matching the -strength of AES. These are likely to be added -to FreeS/WAN along with AES.

- -

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 - Association 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 - Interpretation 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:

- - -

The protocol also allows implementations to add their own encryption -algorithms, authentication algorithms or Diffie-Hellman groups. We do not -support any such extensions, but there are some patches that do.

- -

There are a number of complications:

- - -

These complications can of course lead to problems, particularly when two -different implementations attempt to interoperate. For example, we have seen -problems such as:

- - -

Despite this, we do interoperate successfully with many implementations, -including both Windows 2000 and PGPnet. Details are in our interoperability document.

- -

Sequence of messages in IKE

- -

Each phase (see previous section)of IKE involves a -series of messages. In Pluto error messages, these are abbreviated using:

-
-
M
-
Main mode, settting up the keying channel (ISAKMP - SA)
-
Q
-
Quick mode, setting up the data channel (IPsec - SA)
-
I
-
Initiator, the machine that starts the - negotiation
-
R
-
Responder
-
- -

For example, the six messages of a main mode negotiation, in sequence, are -labelled:

-
       MI1 ---------->
-           <---------- MR1
-       MI2 ----------> 
-           <---------- MR2
-       MI3 ---------->
-           <---------- MR3
- -

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. In either case, the HMAC construct is used as the - authentication mechanism. -

There is a separate authentication operation at the IKE level, in - which each gateway authenticates the other. This can be done in a - variety of ways.

-
-
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 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 technique used is HMAC, defined in RFC 2104.

- -

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 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 IPSEC -Support, the modifications necessary to support IPsec within -the Linux kernel. KILPS does all the actual IPsec packet-handling, -including

- - -

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

- - -

Pluto is controlled mainly by the ipsec.conf(5) configuration file.

- -

The ipsec(8) command

- -

The ipsec(8) command is a front end -shellscript 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 .

- -

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.

- -

We currently have 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 it -now seems moribund, displaced by IKE. Sun now (as of Solaris 8.0) ship an -IPsec implementation using IKE. We have no plans to implement SKIP. If a user -were to implement it, we would almost certainly not want to add the code to -our distribution.

- - diff --git a/doc/src/kernel.html b/doc/src/kernel.html deleted file mode 100644 index a4beab417..000000000 --- a/doc/src/kernel.html +++ /dev/null @@ -1,392 +0,0 @@ - - -Kernel configuration for FreeS/WAN - - - - - - - -

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:

- - -

-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 the attacker uses once he or she has become root on your system. - The kit introduces assorted additional compromises so that the attacker - will continue to "own" your system despite most things you might - do to recovery the situation. 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 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.
-
-
- - diff --git a/doc/src/mail.html b/doc/src/mail.html deleted file mode 100644 index e26f025a0..000000000 --- a/doc/src/mail.html +++ /dev/null @@ -1,250 +0,0 @@ - - - - FreeS/WAN mailing lists - - - - - -

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:

- - -

Archives of these lists are available via the web interface.

- -

Which list should I use?

- -

For most questions, please check the FAQ first, and -if that does not have an answer, ask on the users list. "My configuration -doesn't work." does not belong on the bugs list, and "Can FreeS/WAN do -such-and-such" or "How do I configure it to..." do not belong in design -discussions.

- -

Cross-posting the same message to two or more of these lists is -discouraged. Quite a few people read more than one list and getting multiple -copies is annoying.

- -

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.

- - -

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.

- -

Products that include FreeS/WAN

- -

Our introduction document gives a list of -products that include FreeS/WAN. If you have, or are considering, one of -those, check the supplier's web site for information on mailing lists for -their users.

- -

Linux mailing lists

- - -

Each of the scure distribution projects also has its own web site and -mailing list. Some of the sites are:

- - -

Lists for IETF working groups

- -

Each IETF working group has an associated -mailing list where much of the work takes place.

- - -

Other mailing lists

- - -

Usenet newsgroups

- - - diff --git a/doc/src/makecheck.html b/doc/src/makecheck.html deleted file mode 100644 index 7fa3a3bcb..000000000 --- a/doc/src/makecheck.html +++ /dev/null @@ -1,684 +0,0 @@ - - -FreeS/WAN "make check" guide - - - - - - - - -

How to configure to use "make check"

- -

What is "make check"

-

-"make check" is a target in the top level makefile. It takes care of -running a number of unit and system tests to confirm that FreeSWAN has -been compiled correctly, and that no new bugs have been introduced. -

-

-As FreeSWAN contains both kernel and userspace components, doing testing -of FreeSWAN requires that the kernel be simulated. This is typically difficult -to do as a kernel requires that it be run on bare hardware. A technology -has emerged that makes this simpler. This is -User Mode Linux. -

- -

-User-Mode Linux is a way to build a Linux kernel such that it can run as a process -under another Linux (or in the future other) kernel. Presently, this can only be -done for 2.4 guest kernels. The host kernel can be 2.2 or 2.4. -

- -

-"make check" expects to be able to build User-Mode Linux kernels with FreeSWAN included. -To do this it needs to have some files downloaded and extracted prior -to running "make check". This is described in the -UML testing document. -

- -

-After having run the example in the UML testing document and -successfully brought up the four machine combination, you are ready to -use "make check" -

- -

Running "make check"

-

-"make check" works by walking the FreeSWAN source tree invoking the -"check" target at each node. At present there are tests defined only -for the klips directory. These tests will use the UML -infrastructure to test out pieces of the klips code. -

-

-The results of the tests can be recorded. If the environment variable -$REGRESSRESULTS is non-null, then the results of each -test will be recorded. This can be used as part of a nightly -regression testing system, see -Nightly testing for more details. -

-

-"make check" otherwise prints a minimal amount of output for each -test, and indicates pass/fail status of each test as they are run. -Failed tests do not cause failure of the target in the form of exit -codes. -

- -

How to write a "make check" test

- -

Structure of a test

- -

-Each test consists of a set of directories under testing/. -There are directories for klips, pluto, packaging -and libraries. -Each directory has a list of tests to run is stored in a file called TESTLIST in that directory. e.g. testing/klips/TESTLIST. -

- -

The TESTLIST

-

-This isn't actually a shell script. It just looks like one. Some tools other than -/bin/sh process it. Lines that start with # are comments.

- -
-# test-kind     directory-containing-test       expectation     [PR#]
-
- -

The first word provides the test type, detailed below.

-

The second word is the name of the test to run. This the directory -in which the test case is to be found..

-

The third word may be one of: -

-
blank/good
-
the test is believed to function, report failure
-
bad
-
the test is known to fail, report unexpected success
-
suspended
-
the test should not be run
-
- -

-The fourth word may be a number, which is a PR# if the test is -failing. -

- -

Test kinds

-The test types are: - -
-
skiptest
-
means run no test.
-
ctltest
-
means run a single system without input/output.
-
klipstest
-
means run a single system with input/output networks
-
umlplutotest
-
means run a pair of systems
-
umlXhost
-
run an arbitrary number of systems -
suntest (TBD)
-
means run a quad of east/west/sunrise/sunset
-
roadtest (TBD)
-
means run a trio of east-sunrise + warrior
-
extrudedtest (TBD)
-
means run a quad of east-sunrise + warriorsouth + park
-
mkinsttest -
a test of the "make install" machinery.
-
kernel_test_patch -
a test of the "make kernelpatch" machinery.
-
- -Tests marked (TBD) have yet to be fully defined. -

- -

-Each test directory has a file in it called testparams.sh. -This file sets a number of environment variables to define the -parameters of the test. -

- -

Common parameters

-
-
TESTNAME
-
the name of the test (repeated for checking purposes)
- -
TEST_TYPE
-
the type of the test (repeat of type type above)
- -
TESTHOST
-
the name of the UML machine to run for the test, typically "east" - or "west"
- -
TEST_PURPOSE
-
The purpose of the test is one of: - -
-
goal
-
The goal purpose is where a test is defined for code that is not yet -finished. The test indicates when the goals have in fact been reached.
-
regress
-
This is a test to determine that a previously existing bug has been repaired. This -test will initially be created to reproduce the bug in isolation, and then the bug will -be fixed.
-
exploit
-
This is a set of packets/programs that causes a vulnerability to be -exposed. It is a specific variation of the regress option.
-
-
- -
TEST_GOAL_ITEM
-
in the case of a goal test, this is a reference to the requirements document
- -
TEST_PROB_REPORT
-
in the case of regression test, this the problem report number from GNATS
- -
TEST_EXPLOIT_URL
-
in the case of an exploit, this is a URL referencing the paper explaining -the origin of the test and the origin of exploit software
- -
REF_CONSOLE_OUTPUT
-
a file in the test directory that contains the sanitized console - output against which to compare the output of the actual test.
-
REF_CONSOLE_FIXUPS
-
a list of scripts (found in klips/test/fixups) to - apply to sanitize the console output of the machine under test. - These are typically perl, awk or sed scripts that remove things in - the kernel output that change each time the test is run and/or - compiled. -
-
INIT_SCRIPT
-

a file of commands that is fed into the virtual machine's console - in single user mode prior to starting the tests. This file will - usually set up any eroute's and SADB entries that are required for - the test.

-

Lines beginning with # are skipped. Blank lines are - skipped. Otherwise, a shell prompted is waited for each time - (consisting of \n#) and then the command is sent. - Note that the prompt is waited for before the command and not after, - so completion of the last command in the script is not - required. This is often used to invoke a program to monitor the - system, e.g. ipsec pf_key. -

-
RUN_SCRIPT
-

a file of commands that is fed into the virtual machine's console - in single user mode, before the packets are sent. On single machine - tests, this script doesn't provide any more power than INIT_SCRIPT, - but is implemented for consistency's sake.

-
FINAL_SCRIPT
-

a file of commands that is fed into the virtual machine's console - in single user mode after the final packet is sent. Similar to INIT_SCRIPT, - above. If not specified, then the single command "halt" is sent. - If specified, then the script should end with a halt command to - nicely shutdown the UML. -

-
CONSOLEDIFFDEBUG
-
If set to "true" then the series of console fixups (see REF_CONSOLE_FIXUPS) will be output after it is constructed. (It should be set to "false", or unset otherwise)
-
NETJIGDEBUG
-
If set to "true" then the series of console fixups (see REF_CONSOLE_FIXUPS) will be output after it is constructed. (It should be set to "false", or unset otherwise)
-
NETJIGTESTDEBUG
-
If set to "netjig", then the results of talking to the uml_netjig -will be printed to stderr during the test. In addition, the jig will -be invoked with --debug, which causes it to log its process ID, and -wait 60 seconds before continuing. This can be used if you are trying -to debug the uml_netjig program itself. -
HOSTTESTDEBUG
-
If set to "hosttest", then the results of taling to the consoles of the UMLs will -be printed to stderr during the test. -
NETJIGWAITUSER
-
If set to "waituser", then the scripts will wait forever for user - input before they shut the tests down. Use this is if you are - debugging through the kernel.
- -
PACKETRATE
-
A number, in miliseconds (default is 500ms) at which packets will - be replayed by the netjig.
-
- - -

KLIPStest paramaters

-

-The klipstest function starts a program -(testing/utils/uml_netjig/uml_netjig) to -setup a bunch of I/O sockets (that simulate network interfaces). It -then exports the references to these sockets to the environment and -invokes (using system()) a given script. It waits for the script to -finish. -

- - - -

-The script invoked (testing/utils/host-test.tcl) is a TCL -expect script that arranges to start the UML -and configure it appropriately for the test. The configuration is done -with the script given above for INIT_SCRIPT. The TCL script then forks, -leaves the UML in the background and exits. uml_netjig continues. It then -starts listening to the simulated network answering ARPs and inserting -packets as appropriate. -

- -

-The klipstest function invokes uml_netjig with arguments -to capture output from network interface(s) and insert packets as -appropriate: -

-
PUB_INPUT
-
a pcap file to feed in on - the public (encrypted) interface. (typically, eth1)
-
PRIV_INPUT
-
a pcap file to feed in on the private (plain-text) interface - (typically, eth0).
-
REF_PUB_OUTPUT
-
a text file containing tcpdump output. Packets on the public - (eth1) interface are captured to a - pcap file by - uml_netjig. The klipstest function then uses tcpdump on - the file to produce text output, which is compared to the file given.
-
REF_PUB_FILTER
-
a program that will filter the TCPDUMP output to do further processing. Defaults to "cat".
-
REF_PRIV_OUTPUT
-
a text file containing tcpdump output. Packets on the private - (eth0) interface are captured and compared after conversion by - tcpdump, as with REFPUBOUTPUT.
-
REF_PRIV_FILTER
-
a program that will filter the TCPDUMP output to do further processing. Defaults to "cat".
-
EXITONEMPTY
-
a flag for uml_netjig. It should contain - "--exitonempty" of uml_netjig should exit when all of the input - (PUBINPUT,PRIVINPUT) packets have been injected.
-
ARPREPLY
-
a flag for uml_netjig. It should contain "--arpreply" - if uml_netjig should reply to ARP requests. One will - typically set this to avoid having to fudge the ARP cache manually.
-
TCPDUMPFLAGS
-
a set of flags for the tcpdump used when converting captured - output. Typical values will include "-n" to turn off DNS, and often - "-E" to set the decryption key (tcpdump 3.7.1 and higher only) for - ESP packets. The "-t" flag (turn off timestamps) is provided automatically
- -
NETJIG_EXTRA
-
additional comments to be sent to the netjig. This may arrange to - record or create additional networks, or may toggle options. -
- -

mkinsttest paramaters

-

-The basic concept of the mkinsttest test type is that it -performs a "make install" to a temporary $DESTDIR. The resulting tree can then -be examined to determine if it was done properly. The files can be uninstalled -to determine if the file list was correct, or the contents of files can be -examined more precisely. -

- -
-
INSTALL_FLAGS
-
If set, then an install will be done. This provides the set of flags to -provide for the install. The target to be used (usually "install") must be -among the flags.
-
POSTINSTALL_SCRIPT
-
If set, a script to run after initial "make install". Two arguments are provided: an absolute path to the root of the FreeSWAN src tree, and an absolute path to the temporary installation area.
-
INSTALL2_FLAGS
-
If set, a second install will be done using these flags. Similarly to -INSTALL_FLAGS, the target must be among the flags.
-
UNINSTALL_FLAGS
-
If set, an uninstall will be done using these flags. Similarly to -INSTALL_FLAGS, the target (usually "uninstall") must be among the flags.
-
REF_FIND_f_l_OUTPUT
-
If set, a find $ROOT ( -type f -or -type -l ) will be done to get a list of a real files and symlinks. The resulting file will be compared -to the file listed by this option.
-
REF_FILE_CONTENTS
-
If set, it should point to a file containing records for the form: -
-  reffile   samplefile
-
-one record per line. A diff between the provided reference file, and the -sample file (located in the temporary installation root) will be done for -each record. -
-
- -

rpm_build_install_test paramaters

-

-The rpm_build_install_test type is to verify that the proper -packing list is produced by "make rpm", and that the mechanisms for -building the kernel modules produce consistent results. -

- -
-
RPM_KERNEL_SOURCE
-
Point to an extracted copy of the RedHat kernel source code. Variables -from the environment may be used.
-
REF_RPM_CONTENTS
-
This is a file containing one record per line. Each record consists -of a RPM name (may contain wildcards) and a filename to compare the -contents to. The RPM will be located and a file list will be produced with -rpm2cpio.
-
- -

libtest paramaters

-

-The libtest test is for testing library routines. The library file is -expected to provided an #ifdef by the name of -library. -The libtest type invokes the C compiler to compile this file, links it against -libfreeswan.a (to resolve any other dependancies) and runs the -test with the -r argument to invoke a regression test.

-

The library test case is expected to do a self-test, exiting with status code 0 if everything is okay, and with non-zero otherwise. A core dump (exit code greater than 128) is noted specifically. -

-

-Unlike other tests, there are no subdirectories required, or other -parameters to set. -

- -

umlplutotest paramaters

-

-The umlplutotest function starts a pair of user mode line processes. -This is a 2-host version of umlXhost. The "EAST" and "WEST" slots are defined. -

- -

umlXhost parameters

-

-The umlXtest function starts an arbitrary number of user mode line processes. -

- - - -

-The script invoked (testing/utils/Xhost-test.tcl) is a TCL -expect script that arranges to start each -UML -and configure it appropriately for the test. It then starts listening -(using uml_netjig) to the simulated network answering ARPs and -inserting packets as appropriate. -

- -

-umlXtest has a series of slots, each of which should be filled by a host. -The list of slots is controlled by the variable, XHOST_LIST. This variable -should be set to a space seperated list of slots. The former umlplutotest -is now implemented as a variation of the umlXhost test, -with XHOST_LIST="EAST WEST". -

- -

-For each host slot that is defined, a series of variables should be -filled in, defining what configuration scripts to use for that host. -

- -

-The following are used to control the console input and output to the system. -Where the string ${host} is present, the host slot should be filled in. -I.e. for the two host system with XHOST_LIST="EAST WEST", then the -variables: EAST_INIT_SCRIPT and WEST_INIT_SCRIPT will exist. -

-
${host}HOST
-
The name of the UML host which will fill this slot
-
${host}_INIT_SCRIPT
-

a file of commands that is fed into the virtual machine's console - in single user mode prior to starting the tests. This file will - usually set up any eroute's and SADB entries that are required for - the test. Similar to INIT_SCRIPT, above.

-
${host}_RUN_SCRIPT
-

a file of commands that is fed into the virtual machine's console - in single user mode, before the packets are sent. This set of - commands is run after all of the virtual machines are initialized. - I.e. after EAST_INIT_SCRIPT AND WEST_INIT_SCRIPT. This script - can therefore do things that require that all machines are properly - configured.

-
${host}_RUN2_SCRIPT
-

a file of commands that is fed into the virtual machine's console - in single user mode, after the packets are sent. This set of - commands is run before any of the virtual machines have been shut - down. (I.e. before EAST_FINAL_SCRIPT AND WEST_FINAL_SCRIPT.) - This script can therefore catch post-activity status reports.

-
${host}_FINAL_SCRIPT
-

a file of commands that is fed into the virtual machine's console - in single user mode after the final packet is sent. Similar to INIT_SCRIPT, - above. If not specified, then the single command "halt" is sent. Note that - when this script is run, the other virtual machines may already have been killed. - If specified, then the script should end with a halt command to nicely - shutdown the UML. -

-
REF_${host}_CONSOLE_OUTPUT
-
Similar to REF_CONSOLE_OUTPUT, above. -
-

- -

Some additional flags apply to all hosts: -

-
REF_CONSOLE_FIXUPS
-
a list of scripts (found in klips/test/fixups) to - apply to sanitize the console output of the machine under test. - These are typically perl, awk or sed scripts that remove things in - the kernel output that change each time the test is run and/or - compiled. -
-
-

- -

In addition to input to the console, the networks may have input -fed to them: -

-
EAST_INPUT/WEST_INPUT
-
a pcap file to feed in on - the private network side of each network. The "EAST" and "WEST" here -refer to the networks, not the hosts.
-
REF_PUB_FILTER
-
a program that will filter the TCPDUMP output to do further processing. Defaults to "cat".
-
REF_EAST_FILTER/REF_WEST_FILTER
-
a program that will filter the TCPDUMP output to do further processing. Defaults to "cat".
< -
TCPDUMPFLAGS
-
a set of flags for the tcpdump used when converting captured - output. Typical values will include "-n" to turn off DNS, and often - "-E" to set the decryption key (tcpdump 3.7.1 and higher only) for - ESP packets. The "-t" flag (turn off timestamps) is provided automatically
-
REF_EAST_OUTPUT/REF_WEST_OUTPUT
-
a text file containing tcpdump output. Packets on the private - (eth0) interface are captured and compared after conversion by - tcpdump, as with REF_PUB_OUTPUT.
-

- -

-There are two additional environment variables that may be set on the -command line: -

-
NETJIGVERBOSE=verbose export NETJIGVERBOSE
-
If set, then the test output will be "chatty", and let you know what - commands it is running, and as packets are sent. Without it set, the - output is limited to success/failure messages.
-
NETJIGTESTDEBUG=netjig export NETJIGTESTDEBUG
-
This will enable debugging of the communication with uml_netjig, - and turn on debugging in this utility. - This does not imply NETJIGVERBOSE.
-
HOSTTESTDEBUG=hosttest export HOSTTESTDEBUG
-
This will show all interactions with the user-mode-linux - consoles
-
-

- -

kernel_patch_test paramaters

-

-The kernel_patch_test function takes some kernel source, copies it with -lndir, and then applies the patch as produced by "make kernelpatch". -

-

-The following are used to control the input and output to the system: -

-
KERNEL_NAME
-
the kernel name, typically something like "linus" or "rh"
-
KERNEL_VERSION
-
the kernel version number, as in "2.2" or "2.4".
-
KERNEL_${KERNEL_NAME}${KERNEL_VERSION}_SRC
-
This variable should set in the environment, probably in - ~/freeswan-regress-env.sh. Examples of this variables would be - KERNEL_LINUS2_0_SRC or KERNEL_RH7_3_SRC. This variable should point - to an extracted copy of the kernel source in question.
-
REF_PATCH_OUTPUT
-
a copy of the patch output to compare against
-
KERNEL_PATCH_LEAVE_SOURCE
-
If set to a non-empty string, then the patched kernel source is not - removed at the end of the test. This will typically be set in the - environment while debugging.
-
-

- -

module_compile paramaters

-

-The module_compile test attempts to build the KLIPS module against a -given set of kernel source. This is also done by the RPM tests, but -in a very specific manner. -

-

-There are two variations of this test - one where the kernel either -doesn't need to be configured, or is already done, and tests were there -is a local configuration file. -

-

-Where the kernel doesn't need to be configured, the kernel source that -is found is simply used. It may be a RedHat-style kernel, where one -can cause it to configure itself via rhconfig.h-style definitions. Or, -it may just be a kernel tree that has been configured. -

-

-If the variable KERNEL_CONFIG_FILE is set, then a new directory is -created for the kernel source. It is populated with lndir(1). The referenced -file is then copied in as .config, and "make oldconfig" is used to configure -the kernel. This resulting kernel is then used as the reference source. -

-

-In all cases, the kernel source is found the same was for the kernelpatch -test, i.e. via KERNEL_VERSION/KERNEL_NAME and KERNEL_${KERNEL_NAME}${KERNEL_VERSION}_SRC.

-

-Once there is kernel source, the module is compiled using the top-level -"make module" target. -

-

-The test is considered successful if an executable is found in OUTPUT/module/ipsec.o at the end of the test. -

-
-
KERNEL_NAME
-
the kernel name, typically something like "linus" or "rh"
-
KERNEL_VERSION
-
the kernel version number, as in "2.2" or "2.4".
-
KERNEL_${KERNEL_NAME}${KERNEL_VERSION}_SRC
-
This variable should set in the environment, probably in - ~/freeswan-regress-env.sh. Examples of this variables would be - KERNEL_LINUS2_0_SRC or KERNEL_RH7_3_SRC. This variable should point - to an extracted copy of the kernel source in question.
-
KERNEL_CONFIG_FILE
-
The configuration file for the kernel.
-
KERNEL_PATCH_LEAVE_SOURCE
-
If set to a non-empty string, then the configured kernel source is not - removed at the end of the test. This will typically be set in the - environment while debugging.
-
MODULE_DEF_INCLUDE
-
The include file that will be used to configure the KLIPS module, and - possibly the kernel source.
-
- -

Current pitfalls

- -
-
"tcpdump dissector" not available.
-
This is a non-fatal warning. If uml_netjig is invoked with the -t - option, then it will attempt to use tcpdump's dissector to decode - each packet that it processes. The dissector is presently not - available, so this option it normally turned off at compile time. - The dissector library will be released with tcpdump version - 4.0.
-
- - - \ No newline at end of file diff --git a/doc/src/manpages.html b/doc/src/manpages.html deleted file mode 100644 index 27a9aa7b3..000000000 --- a/doc/src/manpages.html +++ /dev/null @@ -1,155 +0,0 @@ - - - - FreeS/WAN man pages - - - - - -

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)
-
secrets for IKE authentication, either pre-shared keys or RSA private - keys
-
- -

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.

- -

The exceptions are commands for mainpulating the RSA keys used in Pluto authentication:

-
-
ipsec_rsasigkey(8)
-
generate keys
-
ipsec_newhostkey(8)
-
generate keys in a convenient format
-
ipsec_showhostkey(8)
-
extract RSA keys from ipsec.secrets(5) (or - optionally, another file) and format them for insertion in ipsec.conf(5) or in DNS - records
-
- -

Note that:

- - -

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
-
- - diff --git a/doc/src/nightly.html b/doc/src/nightly.html deleted file mode 100644 index d86037884..000000000 --- a/doc/src/nightly.html +++ /dev/null @@ -1,164 +0,0 @@ - - -FreeS/WAN nightly testing guide - - - - - - - - -

Nightly regression testing

- -

-The nightly regression testing system consists of several shell scripts -and some perl scripts. The goal is to check out a fresh tree, run "make check" on it, -record the results and summarize the results to the team and to the web site. -

- -

-Output can be found on adams, -although the tests are actually run on another project machine.

- -

How to setup the nightly build

- -

-The best way to do nightly testing is to setup a new account. We call the -account "build" - you could call it something else, but there may -still be some references to ~build in the scripts. -

- -

Files you need to know about

-

-As few files as possible need to be extracted from the source tree - -files are run from the source tree whenever possible. However, there -are some bootstrap and configuration files that are necessary. -

- -

-There are 7 files in testing/utils that are involved: -

-
nightly-sample.sh
-
This is the root of the build process. This file should be copied out -of the CVS tree, to $HOME/bin/nightly.sh of the build account. This -file should be invoked from cron.
-
freeswan-regress-env-sample.sh
-
This file should be copied to $HOME/freeswan-regress-env.sh. It - should be edited to localize the values. See below.
-
regress-cleanup.pl
-
This file needs to be copied to $HOME/bin/regress-cleanup.pl. It - is invoked by the nightly file before doing anything else. It - removes previous nights builds in order to free up disk space for - the build about to be done.
-
teammail-sample.sh
-
A script used to send results email to the "team". This sample - script could be copied to $HOME/bin/teammail.sh. This version will - PGP encrypt all the output to the team members. If this script is used, - then PGP will have to be properly setup to have the right keys.
-
regress-nightly.sh
-
This is the first stage of the nightly build. This stage will - call other scripts as appropriate, and will extract the source code - from CVS. This script should be copied to $HOME/bin/regress-nightly.sh
-
regress-stage2.sh
-
This is the second stage of the nightly build. It is called in - place. It essentially sets up the UML setup in umlsetup.sh, and - calls "make check".
-
regress-summarize-results.pl -
This script will summarize the results from the tests to a - permanent directory set by $REGRESSRESULTS. It is invoked from the - stage2 nightly script. -
regress-chart.sh
-
This script is called at the end of the build process, and will - summarize each night's results (as saved into $REGRESSRESULTS by - regress-summarize-results.pl) as a chart using gnuplot. Note that - this requires at least gnuplot 3.7.2.
-
- -

Configuring freeswan-regress-env.sh

- -

For more info on KERNPOOL, UMLPATCH, BASICROOT and SHAREDIR, see - User-Mode-Linux testing guide. -

- -
-
KERNPOOL
-
Extract copy of some kernel source to be used for UML builds
-
UMLPATCH
-
matching User-Mode-Linux patch.
-
BASICROOT
-
the root file system image (see - User-Mode-Linux testing guide).
-
SHAREDIR=${BASICROOT}/usr/share
-
The /usr/share to use.
-
REGRESSTREE
-
A directory in which to store the nightly regression - results. Directories will be created by date in this tree.
- -
TCPDUMP=tcpdump-3.7.1
-
The path to the tcpdump - to use. This must have crypto compiled in, and must be at least 3.7.1 - -
KERNEL_RH7_2_SRC=/a3/kernel_sources/linux-2.4.9-13/
-
An extracted copy of the RedHat 7.2. kernel source. If set, then - the packaging/rpm-rh72-install-01 test will be run, and an RPM will - be built as a test.
- -
KERNEL_RH7_3_SRC=/a3/kernel_sources/rh/linux-2.4.18-5
-
An extracted copy of the RedHat 7.3. kernel source. If set, then - the packaging/rpm-rh73-install-01 test will be run, and an RPM will - be built as a test.
- -
NIGHTLY_WATCHERS="userid,userid,userid"
-
The list of people who should receive nightly output. This is - used by teammail.sh
- -
FAILLINES=128
-
How many lines of failed test output to include in the nightly - output
- -
PATH=$PATH:/sandel/bin export PATH
-
You can also override the path if necessary here.
- -
CVSROOT=:pserver:anoncvs@ip212.xs4net.freeswan.org:/freeswan/MASTER
-
The CVSROOT to use. This example may work for anonymous CVS, but - will be 12 hours behind the primary, and is still experimental
- -
SNAPSHOTSIGDIR=$HOME/snapshot-sig
-
For the release tools, where to put the generated per-snapshot - signature keys
- -
LASTREL=1.97
-
the name of the last release branch (to find the right - per-snapshot signature - -
- -
- - - \ No newline at end of file diff --git a/doc/src/performance.html b/doc/src/performance.html deleted file mode 100755 index 9d90acc62..000000000 --- a/doc/src/performance.html +++ /dev/null @@ -1,576 +0,0 @@ - - - - FreeS/WAN performance - - - - - -

Performance of FreeS/WAN

-The performance of FreeS/WAN is adequate for most applications. - -

In normal operation, the main concern is the overhead for encryption, -decryption and authentication of the actual IPsec (ESP and/or AH) -data packets. Tunnel setup and rekeying occur so much less frequently than -packet processing that, in general, their overheads are not worth worrying -about.

- -

At startup, however, tunnel setup overheads may be significant. If you -reboot a gateway and it needs to establish many tunnels, expect some delay. -This and other issues for large gateways are discussed below.

- -

Published material

- -

The University of Wales at Aberystwyth has done quite detailed speed tests -and put their -results on the web.

- -

Davide Cerri's thesis (in -Italian) includes performance results for FreeS/WAN and for TLS. He posted an English -summary on the mailing list.

- -

Steve Bellovin used one of AT&T Research's FreeS/WAN gateways as his -data source for an analysis of the cache sizes required for key swapping in -IPsec. Available as text -or PDF -slides for a talk on the topic.

- -

See also the NAI work mentioned in the next section.

- -

Estimating CPU overheads

- -

We can come up with a formula that roughly relates CPU speed to the rate -of IPsec processing possible. It is far from exact, but should be usable as a -first approximation.

- -

An analysis of authentication overheads for high-speed networks, including -some tests using FreeS/WAN, is on the NAI -Labs site. In particular, see figure 3 in this PDF -document. Their estimates of overheads, measured in Pentium II cycles per -byte processed are:

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
IPsecauthenticationencryptioncycles/byte
Linux IP stack alonenonono5
IPsec without cryptoyesnono11
IPsec, authentication onlyyesSHA-1no24
IPsec with encryptionyesyesyesnot tested
- -

Overheads for IPsec with encryption were not tested in the NAI work, but -Antoon Bosselaers' web page gives -cost for his optimised Triple DES implementation as 928 Pentium cycles per -block, or 116 per byte. Adding that to the 24 above, we get 140 cycles per -byte for IPsec with encryption.

- -

At 140 cycles per byte, a 140 MHz machine can handle a megabyte -- 8 -megabits -- per second. Speeds for other machines will be proportional to -this. To saturate a link with capacity C megabits per second, you need a -machine running at C * 140/8 = C * 17.5 MHz.

- -

However, that estimate is not precise. It ignores the differences -between:

- - -

and does not account for some overheads you will almost certainly have:

- - -

so we suggest using C * 25 to get an estimate with a bit of a -built-in safety factor.

- -

This covers only IP and IPsec processing. If you have other loads on your -gateway -- for example if it is also working as a firewall -- then you will -need to add your own safety factor atop that.

- -

This estimate matches empirical data reasonably well. For example, -Metheringham's tests, described below, show a 733 -topping out between 32 and 36 Mbit/second, pushing data as fast as it can -down a 100 Mbit link. Our formula suggests you need at least an 800 to handle -a fully loaded 32 Mbit link. The two results are consistent.

- -

Some examples using this estimation method:

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
InterfaceMachine speed in MHz
TypeMbit per
- second		Estimate
- Mbit*25		Minimum IPSEC gatewayMinimum with other load - -

(e.g. firewall)

-
DSL125 MHzwhatever you have133, or better if you have it
cable modem375 MHz
any link, light load5125 MHz133200+, almost any surplus machine
Ethernet10250 MHzsurplus 266 or 300500+
fast link, moderate load20500 MHz500800+, any current off-the-shelf PC
T3 or E3451125 MHz12001500+
fast Ethernet1002500 MHz// not feasible with 3DES in - software on current machines //
OC31553875 MHz
- -

Such an estimate is far from exact, but should be usable as minimum -requirement for planning. The key observations are:

- -

Higher performance alternatives

- -

AES is a new US government block cipher - standard, designed to replace the obsolete DES. If FreeS/WAN using 3DES is not fast enough for your application, - the AES patch may help.

- -

To date (March 2002) we have had only one mailing - list report of measurements with the patch applied. It indicates that, - at least for the tested load on that user's network, AES roughly - doubles IPsec throughput. If further testing confirms this, it may - prove possible to saturate an OC3 link in software on a high-end box.

- -

Also, some work is being done toward support of hardware IPsec acceleration which might - extend the range of requirements FreeS/WAN could meet.

- -

Other considerations

- -

CPU speed may be the main issue for IPsec performance, but of course it - isn't the only one.

- -

You need good ethernet cards or other network interface hardware to get - the best performance. See this ethernet - information page and this Linux - network driver page.

- -

The current FreeS/WAN kernel code is largely single-threaded. It is SMP - safe, and will run just fine on a multiprocessor machine (discussion), but the load within the - kernel is not shared effectively. This means that, for example to saturate - a T3 -- which needs about a 1200 MHz machine -- you cannot expect something - like a dual 800 to do the job.

- -

On the other hand, SMP machines do tend to share loads well so -- - provided one CPU is fast enough for the IPsec work -- a multiprocessor - machine may be ideal for a gateway with a mixed load.

- -

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

- - -

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.

- -

A gateway that does a lot of rekeying -- many tunnels and/or low settings -for tunnel lifetimes -- will also need a lot of random numbers from the random(4) driver.

- -

Low-end systems

- -

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

From the above, and from general user experience as reported on the list, -it seems clear that a cheap surplus machine -- a reasonable 486, a minimal -Pentium box, a Sparc 5, ... -- can easily handle a home office or a small -company connection using any of:

- - -

If available, we suggest using a Pentium 133 or better. This should ensure -that, even under maximum load, IPsec will use less than half the CPU cycles. -You then have enough left for other things you may want on your gateway -- -firewalling, web caching, DNS and such.

- -

Measuring KLIPS

- -

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

Speed with compression

- -

Another user reported some results for connections with and without IP -compression:

-
Subject: [Users] Speed with compression
-   Date: Fri, 29 Jun 2001
-   From: John McMonagle <johnm@advocap.org>
-
-Did a couple tests with compression using the new 1.91 freeswan.
-
-Running between 2 sites with cable modems.  Both  using approximately
-130 mhz pentium.
-
-Transferred files with ncftp.
-
-Compressed file was a 6mb compressed  installation file.
-Non compressed was 18mb /var/lib/rpm/packages.rpm
-
-                            Compressed vpn          regular vpn
-Compress file                42.59 kBs               42.08 kBs
-regular file                110.84 kBs               41.66 kBs
-
-Load  was about 0 either way.
-Ping times were very similar  a bit above 9 ms.
-
-Compression looks attractive to me.
-Later in the same thread, project technical lead Henry Spencer added: -
> is there a reason not to switch compression on?  I have large gateway boxes
-> connecting 3 connections, one of them with a measly DS1 link...
-
-Run some timing tests with and without, with data and loads representative
-of what you expect in production.  That's the definitive way to decide. 
-If compression is a net loss, then obviously, leave it turned off.  If it
-doesn't make much difference, leave it off for simplicity and hence
-robustness.  If there's a substantial gain, by all means turn it on. 
-
-If both ends support compression and can successfully negotiate a
-compressed connection (trivially true if both are FreeS/WAN 1.91), then
-the crucial question is CPU cycles. 
-
-Compression has some overhead, so one question is whether *your* data
-compresses well enough to save you more CPU cycles (by reducing the volume
-of data going through CPU-intensive encryption/decryption) than it costs
-you.  Last time I ran such tests on data that was reasonably compressible
-but not deliberately contrived to be so, this generally was not true --
-compression cost extra CPU cycles -- so compression was worthwhile only if
-the link, not the CPU, was the bottleneck.  However, that was before the
-slow-compression bug was fixed.  I haven't had a chance to re-run those
-tests yet, but it sounds like I'd probably see a different result.
-The bug he refers to was a problem with the compression libraries that had us -using C code, rather than assembler, for compression. It was fixed before -1.91. - -

Methods of measuring

- -

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.
- - diff --git a/doc/src/policy-groups-table.html b/doc/src/policy-groups-table.html deleted file mode 100644 index 8e84809cf..000000000 --- a/doc/src/policy-groups-table.html +++ /dev/null @@ -1,297 +0,0 @@ - - - - - - - - - - - - -Policy Groups Table
-
-This table lists all the policy group combinations and expected packet flows.
-
-
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
policy
- 		noneclearclear-or-privateprivate-or-clearprivateblock

- 		key?noyesnoyesnoyesnoyesnoyesnoyes
nonenoccccccccc,fc,fc,fc,f
yesccccccc,f?c,f?c,fc,fc,fc,f
clearnocccccccc,c(f?)c,fc,fc,fc,f
yesccccccc,f?c,f?c,fc,fc,fc,f
clear-or-privatenoccccccc,f?c,c(f?)c,fc,fc,fc,f
yesccccccc,f?c,ec,fc,ec,fc,f
private-or-clearnot,ct,f?t,ct,f?t,ct,f?t,f?t,f?t,ft,ft,ft,f
yest,ct,f?t,ct,f?t,ct,et,c(f?)t,et,ft,et,ft,f
privatenot,ft,ft,ft,ft,ft,ft,ft,ft,ft,ft,ft,f
yest,ft,ft,ft,ft,ft,et,ft,et,ft,et,ft,f
blocknoffffffffffff
yesffffffffffff
-
-   - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
legendpacket fate
cclear
ffail
eencrypt
ttrap
c,f
- 		first packet clear, then fail
-
c,e
- 		first packet clear, then encrypt
-
t,f
- 		trap, then fail
-
t,c
- 		trap, then clear
-
t,e
- 		trap, then encrypt
-
- - - diff --git a/doc/src/policygroups.html b/doc/src/policygroups.html deleted file mode 100644 index 0425ade39..000000000 --- a/doc/src/policygroups.html +++ /dev/null @@ -1,489 +0,0 @@ - - - - Configuring FreeS/WAN with policy groups - - - - - -

How to Configure Linux FreeS/WAN with Policy Groups

- - - - -

What are Policy Groups?

- - -

Policy Groups are an elegant general mechanism -to configure FreeS/WAN. They are useful for -many FreeS/WAN users.

- -

In previous FreeS/WAN versions, you needed to configure each IPsec -connection explicitly, on both local and remote hosts. - This could become complex.

- -

By contrast, Policy Groups allow you to set local IPsec policy -for lists of remote hosts and networks, -simply by listing the hosts and networks which you wish to -have special treatment in one of several Policy Group files. -FreeS/WAN then internally creates the connections -needed to implement each policy.

- -

In the next section we describe our five Base Policy Groups, which -you can use to configure IPsec in many useful ways. Later, we will -show you how to create an IPsec VPN using one line of configuration for -each remote host or network.

- - -

Built-In Security Options

- -

FreeS/WAN offers these Base Policy Groups:

- -
- -
private
- -
-FreeS/WAN only communicates privately with the listed -CIDR blocks. -If needed, FreeS/WAN attempts to create a connection opportunistically. -If this fails, FreeS/WAN blocks communication. -Inbound blocking is assumed to be done by the firewall. FreeS/WAN offers -firewall hooks but no modern firewall rules to help with inbound blocking. - -
- -
private-or-clear
-
- -FreeS/WAN prefers private communication with the listed CIDR blocks. -If needed, FreeS/WAN attempts to create a connection opportunistically. -If this fails, FreeS/WAN allows traffic in the clear. - -
- -
clear-or-private
- -
-FreeS/WAN communicates cleartext with the listed CIDR blocks, but -also accepts inbound OE connection requests from them. -Also known as passive OE (pOE), -this policy may be used to create an -opportunistic responder. -
- -
clear
-
-FreeS/WAN only communicates cleartext with the listed CIDR blocks. -
- -
block
-
FreeS/WAN blocks traffic to and from and the listed CIDR blocks. -Inbound blocking is assumed to be done by the firewall. FreeS/WAN offers -firewall hooks but no modern firewall rules to help with inbound blocking. - - -
- -
- -

Notes:

- - - - -

Using Policy Groups

- -

The Base Policy Groups which build IPsec connections rely on Opportunistic -Encryption. To use the following examples, you -must first become OE-capable, as described -in our quickstart guide. - -

Example 1: Using a Base Policy Group

- -

Simply place CIDR blocks (names, -IPs or IP ranges) in /etc/ipsec.d/policies/[groupname], -and reread the policy group files.

- -

For example, the private-or-clear policy tells -FreeS/WAN to prefer encrypted communication to the listed CIDR blocks. -Failing that, it allows talk in the clear.

- -

To make this your default policy, place -fullnet -in the private-or-clear policy group file:

- -
    [root@xy root]# cat /etc/ipsec.d/policies/private-or-clear
-    # This file defines the set of CIDRs (network/mask-length) to which
-    # communication should be private, if possible, but in the clear otherwise.
-    ....
-    0.0.0.0/0
- -

and reload your policies with

- -
    ipsec auto --rereadgroups
- -

Use this test to verify -opportunistic connections.

- - - -

Example 2: Defining IPsec Security Policy -with Groups

- -

Defining IPsec security policy with Base Policy Groups is like creating -a shopping list: just put CIDR blocks in the appropriate group files. -For example:

- - -
    [root@xy root]# cd /etc/ipsec.d/policies
-    [root@xy policies]# cat private
-        192.0.2.96/27              # The finance department
-        192.0.2.192/29             # HR
-	192.0.2.12                 # HR gateway
-        irc.private.example.com    # Private IRC server
-  
-    [root@xy policies]# cat private-or-clear
-        0.0.0.0/0                  # My default policy: try to encrypt.
-
-    [root@xy policies]# cat clear
-        192.0.2.18/32              # My POP3 server
-        192.0.2.19/32              # My Web proxy
-
-    [root@xy policies]# cat block
-        spamsource.example.com
- -

To make these settings take effect, type:

-
    ipsec auto --rereadgroups
- - -

Notes:

- - - -

Example 3: Creating a Simple IPsec VPN with the -private Group

- - -

You can create an IPsec VPN between several hosts, with -only one line of configuration per host, using the private -policy group.

- -

First, use our quickstart -guide to set up each participating host -with a FreeS/WAN install and OE.

- -

In one host's /etc/ipsec.d/policies/private, -list the peers to which you wish to protect traffic. -For example:

- -
    [root@xy root]# cd /etc/ipsec.d/policies
-    [root@xy policies]# cat private
-        192.0.2.9              # several hosts at example.com
-        192.0.2.11             
-        192.0.2.12                 
-        irc.private.example.com 
-
- -

Copy the private file to each host. Remove the local host, and -add the initial host.

- -
    scp2 /etc/ipsec.d/policies/private root@192.0.2.12:/etc/ipsec.d/policies/private
- -

On each host, reread the policy groups with

- -
    ipsec auto --rereadgroups
- - -

That's it! You're configured.

- -

Test by pinging between two hosts. After a second or two, -traffic should flow, and

- -
    ipsec eroute
- -

should yield something like

- -
    192.0.2.11/32   -> 192.0.2.8/32  => tun0x149f@192.0.2.8
- -

where your host IPs are substituted for 192.0.2.11 and 192.0.2.8.

- -

If traffic does not flow, there may be an error in your OE setup. -Revisit our quickstart guide.

- - -

Our next two examples show you how to add subnets to this IPsec VPN.

- - -

Example 4: New Policy Groups to Protect a -Subnet

- -

To protect traffic to a subnet behind your FreeS/WAN gateway, -you'll need additional DNS records, and new policy groups. -To set up the DNS, see our quickstart -guide. To create five new policy groups for your subnet, -copy these connections to /etc/ipsec.conf. -Substitute your subnet's IPs for 192.0.2.128/29.

- -
-conn private-net
-    also=private  # inherits settings (eg. auto=start) from built in conn
-    leftsubnet=192.0.2.128/29  # your subnet's IPs here
-
-conn private-or-clear-net
-    also=private-or-clear
-    leftsubnet=192.0.2.128/29
-
-conn clear-or-private-net
-    also=clear-or-private
-    leftsubnet=192.0.2.128/29
-
-conn clear-net
-    also=clear
-    leftsubnet=192.0.2.128/29
-
-conn block-net
-    also=block
-    leftsubnet=192.0.2.128/29
-
- -

Copy the gateway's files to serve as the initial policy group files for the -new groups:

- -
-    cp -p /etc/ipsec.d/policies/private /etc/ipsec.d/policies/private-net
-    cp -p /etc/ipsec.d/policies/private-or-clear /etc/ipsec.d/policies/private-or-clear-net
-    cp -p /etc/ipsec.d/policies/clear-or-private /etc/ipsec.d/policies/clear-or-private-net
-    cp -p /etc/ipsec.d/policies/clear /etc/ipsec.d/policies/clear-net
-    cp -p /etc/ipsec.d/policies/block /etc/ipsec.d/policies/block
-
- -

Tip: Since a missing policy group file is equivalent to a file with -no entries, you need only create files for the connections -you'll use.

- -

To test one of your new groups, place the fullnet 0.0.0.0/0 in -private-or-clear-net. -Perform the subnet test in -our quickstart guide. You should -see a connection, and

- -
    ipsec eroute
- -

should include an entry which mentions the subnet node's IP and the -OE test site IP, like this:

- -
    192.0.2.131/32   -> 192.139.46.77/32  => tun0x149f@192.0.2.11
- - -

Example 5: Adding a Subnet to the VPN

- -

Suppose you wish to secure traffic to a subnet 192.0.2.192/29 -behind a FreeS/WAN box 192.0.2.12.

- -

First, add DNS entries to configure 192.0.2.12 as an opportunistic -gateway for that subnet. Instructions are in - our quickstart guide. -Next, create a private-net group on 192.0.2.12 as described in -Example 4. -

- -

On each other host, add the subnet 192.0.2.192/29 to private, -yielding for example

- -
    [root@xy root]# cd /etc/ipsec.d/policies
-    [root@xy policies]# cat private
-        192.0.2.9              # several hosts at example.com
-        192.0.2.11
-        192.0.2.12             # HR department gateway
-        192.0.2.192/29         # HR subnet
-        irc.private.example.com
-
- - -

and reread policy groups with

- -
    ipsec auto --rereadgroups
- -

That's all the configuration you need.

- -

Test your VPN by pinging from a machine on 192.0.2.192/29 to any other host: -

- -
    [root@192.0.2.194]# ping 192.0.2.11
- - -

After a second or two, traffic should flow, and

- -
    ipsec eroute
- -

should yield something like

- -
    192.0.2.11/32   -> 192.0.2.194/32  => tun0x149f@192.0.2.12
-
- -

Key:

- - - - - - - - - - - - - -
1.192.0.2.11/32Local start point of the protected traffic. -
2.192.0.2.194/32Remote end point of the protected traffic. -
3.192.0.2.12Remote FreeS/WAN node (gateway or host). - May be the same as (2). -
4.[not shown]Local FreeS/WAN node (gateway or host), - where you've produced the output. - May be the same as (1). -
- -

For additional assurance, you can verify with a packet sniffer -that the traffic is being encrypted.

- - -

Note

- - - - -

Appendix

- -

Our Hidden Connections

- - -

Our Base Policy Groups are created using hidden connections. -These are spelled out in -man ipsec.conf - and defined in /usr/local/lib/ipsec/_confread. -

- - -

Custom Policy Groups

- -

A policy group is built using a special connection description -in ipsec.conf, which:

- - - -

To create a new group:

-
    -
  1. Create its connection definition in ipsec.conf.
    2. -
  2. Create a Policy Group file in /etc/ipsec.d/policies -with the same name as your connection. -
    3. -
  3. Put a CIDR block in that file.
    4. -
  4. Reread groups with ipsec auto --rereadgroups.
    5. -
  5. Test: ping to activate any OE connection, and view -results with ipsec eroute.
    6. -
- - -

Disabling Opportunistic Encryption

- -

To disable OE (eg. policy groups and packetdefault), cut and paste the following lines -to /etc/ipsec.conf:

- -
conn block
-    auto=ignore
-
-conn private
-    auto=ignore
-
-conn private-or-clear
-    auto=ignore
-
-conn clear-or-private
-    auto=ignore
-
-conn clear
-    auto=ignore
-
-conn packetdefault
-    auto=ignore
- -

Restart FreeS/WAN so that the changes take effect:

- -
    ipsec setup restart
- - - - - diff --git a/doc/src/politics.html b/doc/src/politics.html deleted file mode 100644 index 9e87d4f05..000000000 --- a/doc/src/politics.html +++ /dev/null @@ -1,1466 +0,0 @@ - - - - History and politics of cryptography - - - - - -

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 several. Two -I particularly like are:

- - -

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.

- - -

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:

- - -

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:

- - -

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:

- - -

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:

- - -

Of course governments are by no means the only threat to privacy and -security on the net. Other threats include:

- - -

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. See the UN's Universal -Declaration of Human Rights, article twelve:

- -
- No one shall be subjected to arbitrary interference with his privacy, - family, home or correspondence, nor to attacks upon his honor and - reputation. Everyone has the right to the protection of the law against - such interference or attacks.
- -

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:

- - -

For more on these issues see:

- - -

There are several collections of crypto -quotes on the net.

- -

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

- - -

and discussions of:

- - -

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:

- - -

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 a little key - she kept it in escrow,
-  and every thing that Mary said,
-  the feds were sure to know.
- -

A crypto quotes page attributes this to Sam Simpson.

- -

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:

- - -

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:

- - -

This is utter nonsense.

- -

Weak systems touted include:

- - -

The notion that choice of ciphers or keysize should be determined by a -trade-off between security requirements and overheads is pure bafflegab.

- - -

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.

-
   Mary had a little key (It's all she could export),
-   and all the email that she sent was opened at the Fort.
- -

A crypto quotes page attributes this to Ron Rivest. NSA headquarters -is at Fort Meade, Maryland.

- -

Our policy in FreeS/WAN is to use only cryptographic components with -adequate keylength and no known weaknesses.

- - -

Detailed discussion of which IPsec features we implement or omit is in out -compatibility document.

- -

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.

- -

Some real trade-offs

- -

Of course, making systems secure does involve costs, and trade-offs can be -made between cost and security. However, the real trade-offs have nothing to -do with using weaker ciphers.

- -

There can be substantial hardware and software costs. There are often -substantial training costs, both to train administrators and to increase user -awareness of security issues and procedures. There are almost always -substantial staff or contracting costs.

- -

Security takes staff time for planning, implementation, testing 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. EvilDoers -will know about new attacks shortly after they are found. You need -to know about them before your systems are attacked. If your vendor provides -a patch, you need to apply it. If the vendor does nothing, you need to -complain or start looking for another vendor.

- -

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.

- -

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.

- -

Compared to those costs, cipher overheads are an insignificant factor in -the cost of security.

- -

The only thing using a weak cipher can do for you is to cause all your -other investment to be wasted.

- -

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

- -

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. - 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
- -
- The NSA regularly lies to people who ask it for advice on export control. - They have no reason not to; accomplishing their goal by any legal means is - fine by them. Lying by government employees is legal.
- John Gilmore.
- -

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:

- -
- ... various governments have actual or proposed policies on access to - cryptographic technology ... - -

(a) ... export controls ...
- (b) ... short cryptographic keys ...
- (c) ... keys should be in the hands of the government or ...
- (d) prohibit the use of cryptology ...

- -

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

- -

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. The abstract from that document -is:

- -
- The Internet Engineering Task Force (IETF) has been asked to take a - position on the inclusion into IETF standards-track documents of - functionality designed to facilitate wiretapping. - -

This memo explains what the IETF thinks the question means, why its - answer is "no", and what that answer means.

-
-A quote from the debate leading up to that RFC: - -
- 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 Raven mailing -list was set up for this IETF discussion.

- -

Our goal is to go beyond that RFC 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. -
  2. "In the public domain".
    3. -
-
- -

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.

- - -

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 -Standard, 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 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, they may -have had DES crackers for years, and theirs may be much faster. It is -difficult to make most computer applications work well on parallel machines, -or to design specialised hardware to accelerate them. Cipher-cracking is one -of the very few exceptions. It is entirely straightforward to speed up -cracking by just adding hardware. 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 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 spectacularly incompetent or horribly underfunded, -they can certainly break it, but we cannot guess how quickly. Pick any time -unit between days and milliseconds; none 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.

- -

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. Certainly those countries -have some fine mathematicians, and those agencies had budget. 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

- - -

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

- -

The winner, announced in October 2000 after several years of analysis and -discussion, was the Rijndael cipher -from two Belgian designers.

- -

It is almost certain that FreeS/WAN will add AES support. AES patches are already available.

- -

Press coverage of Linux FreeS/WAN:

- -

FreeS/WAN 1.0 press

- - -

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.
- - diff --git a/doc/src/quickstart-configs.html b/doc/src/quickstart-configs.html deleted file mode 100644 index b2ad21bcc..000000000 --- a/doc/src/quickstart-configs.html +++ /dev/null @@ -1,144 +0,0 @@ - - - - Quick FreeS/WAN installation and configuration - - - - -

FreeS/WAN quick start examples

-

These are sample -ipsec.conf(5) -configuration files for opportunistic encryption, with comments. Much of -this configuration will be unnecessary with the new defaults proposed -for FreeS/WAN 2.x.

-

Full instructions are in our -quickstart guide. - -

Configuration for Initiate-only Opportunistic Encryption

-

The ipsec.conf file for an initiate-only opportunistic setup is:

-
# general IPsec setup
-config setup
-        # Use the default interface
-        interfaces=%defaultroute
-        # Use auto= parameters in conn descriptions to control startup actions.
-        plutoload=%search
-        plutostart=%search
-        uniqueids=yes
-
-# defaults for subsequent connection descriptions
-conn %default
-        # How to authenticate gateways
-        authby=rsasig
-        # default is
-        # load connection description into Pluto's database
-        # so it can respond if another gatway initiates
-        # individual connection descriptions may override this
-        auto=add
-
-# description for opportunistic connections
-conn me-to-anyone
-        left=%defaultroute         # all connections should use default route
-        right=%opportunistic       # anyone we can authenticate
-        leftrsasigkey=%dnsondemand  # NEW: look up keys in DNS as-needed
-        rightrsasigkey=%dnsondemand # (not at connection load time)
-        rekey=no                   # let unused connections die
-        keylife=1h                 # short
-        auto=route                 # set up for opportunistic
-        leftid=@xy.example.com     # our identity for IPSec negotiations
-                                   # must match DNS and ipsec.secrets
- -

Normally, you need to do only two things:

- -

- However, some people may need to customize the interfaces= line - in the "config setup" section. All other sections are identical for any - standalone machine doing opportunistic encryption.

-

The @ sign in the leftid= makes the ID go "over the wire" - as a Fully Qualified Domain Name (FQDN). Without it, an IP address would - be used and this won't work.

-

The conn is not used to supply either public key. Your private key - is in ipsec.secrets(5) - and, for opportunistic encryption, the public keys for remote gateways - are all looked up in DNS.

-

FreeS/WAN authenticates opportunistic encryption by RSA - signature only, so "public key" and "private key" refer to these keys.

-

While the left and right designations - here are arbitrary, we follow a convention of using left for - local and right for remote.

- -

Continue configuring -initiate-only opportunism. - -

ipsec.conf for Incoming Opportunistic Encryption

-Use the ipsec.conf above, except that the section describing opportunistic -connections is now:

-
-# description for opportunistic connections
-conn me-to-anyone
-        left=%defaultroute         # all connections should use default route
-        right=%opportunistic       # anyone we can authenticate
-        leftrsasigkey=%dnsondemand  # NEW: look up keys in DNS as-needed
-        rightrsasigkey=%dnsondemand # (not at connection load time)
-        rekey=no                   # let unused connections die
-        keylife=1h                 # short
-        auto=route                 # set up for opportunistic
- -

Note that leftid= has been removed. With no explicit setting, -leftid= defaults to the IP of your public interface.

- -

Continue configuring -full opportunism. - - -

ipsec.conf for Opportunistic Gateway

-Use the ipsec.conf above, plus these connections: - -
conn subnet-to-anyone            # must be above me-to-anyone
-       also=me-to-anyone
-       leftsubnet=42.42.42.0/24
-
-conn me-to-anyone                # just like for full opportunism
-        left=%defaultroute
-        right=%opportunistic
-        leftrsasigkey=%dnsondemand
-        rightrsasigkey=%dnsondemand
-        keylife=1h
-        rekey=no
-        auto=route               # be sure this is enabled
-                                 # Note there is NO leftid=
- - -

Note that a subnet described in ipsec.conf(5) need not correspond to a - physical network segment. This is discussed in more detail in our -advanced configuration document.

- -

If required, a gateway can easily provide this service for more than one - subnet. You just add a connection description for each.

- -

Continue configuring an -opportunistic gateway. - - - - - diff --git a/doc/src/quickstart-firewall.html b/doc/src/quickstart-firewall.html deleted file mode 100644 index 53c27b5af..000000000 --- a/doc/src/quickstart-firewall.html +++ /dev/null @@ -1,187 +0,0 @@ - - - - Quick FreeS/WAN installation and configuration - - - - -

FreeS/WAN quick start on firewalling

-

This firewalling information supplements our -quickstart guide.

-

It includes tips for firewalling:

- -

and a list of helpful resources.

-

Firewalling a standalone system

-

Firewall rules on a standalone system doing IPsec can be very simple.

-

The first step is to allow IPsec packets (IKE on UDP port 500 plus - ESP, protocol 50) in and out of your gateway. A script to set up - iptables(8) rules for this is:

-
# edit this line to match the interface you use as default route
-# ppp0 is correct for many modem, DSL or cable connections
-# but perhaps not for you
-world=ppp0
-#
-# allow IPsec
-#
-# IKE negotiations
-iptables -A INPUT  -p udp -i $world --sport 500 --dport 500 -j ACCEPT
-iptables -A OUTPUT -p udp -o $world --sport 500 --dport 500 -j ACCEPT
-# ESP encryption and authentication
-iptables -A INPUT  -p 50 -i $world -j ACCEPT
-iptables -A OUTPUT -p 50 -o $world -j ACCEPT
-

Optionally, you could restrict this, allowing these packets only to - and from a list of known gateways.

-

A second firewalling step -- access controls built into the IPsec - protocols -- is automatically applied:

-
-
Pluto -- the FreeS/WAN keying - daemon -- deals with the IKE packets.
-
Pluto authenticates its partners during the IKE negotiation, and - drops negotiation if authentication fails.
-
KLIPS -- the FreeS/WAN kernel - component -- handles the ESP packets.
-
-
-
KLIPS drops outgoing packets
-
if they are routed to IPsec, but no tunnel has been negotiated for - them
-
KLIPS drops incoming unencrypted packets
-
if source and destination addresses match a tunnel; the packets - should have been encrypted
-
KLIPS drops incoming encrypted packets
-
if source and destination address do not match the negotiated - parameters of the tunnel that delivers them
-
if packet-level authentication fails
-
-
-
-

These errors are logged. See our - troubleshooting document for details.

-

As an optional third step, you may wish to filter packets emerging from - your opportunistic tunnels. - These packets arrive on an interface such as ipsec0, rather than - eth0, ppp0 or whatever. For example, in an iptables(8) - rule set, you would use:

-
-
-i ipsec+
-
to specify packets arriving on any ipsec device
-
-o ipsec+
-
to specify packets leaving via any ipsec device
-
-

In this way, you can apply whatever additional filtering you like to these -packets.

-

The packets emerging on ipsec0 are likely - to be things that a client application on your machine requested: web - pages, e-mail, file transfers and so on. However, any time you initiate - an opportunistic connection, you open a two-way connection to - another machine (or network). It is conceivable that a Bad Guy there - could take advantage of your link.

-

For more information, read the next section.

-

-

Firewalling incoming opportunistic - connections

-

The basic firewalling for IPsec does not change when you support - incoming connections as well as connections you initiate. You must - still allow IKE (UDP port 500) and ESP (protocol 50) packets to and - from your machine, as in the rules given - above.

-

However, there is an additional security concern when you allow - incoming opportunistic connections. Incoming opportunistic packets - enter your machine via an IPSec tunnel. That is, they all appear as - ESP (protocol 50) packets, concealing whatever port and protocol - characteristics the packet within the tunnel has. Contained - in the tunnel as they pass through ppp0 or eth0, - these packets can bypass your usual firewall rules on these interfaces. -

Consequently, you will want to firewall your ipsec interfaces - the way you would any publicly accessible interface.

-

A simple way to do this is to create one iptables(8) table with - all your filtering rules for incoming packets, and apply the entire table to - all public interfaces, including ipsec interfaces.

- -

Firewalling for opportunistic gateways

-

On a gateway, the IPsec-related firewall rules applied for input and - output on the Internet side are exactly as shown -above. A gateway - exchanges exactly the same things -- UDP 500 packets and IPsec packets - -- with other gateways that a standalone system does, so it can use - exactly the same firewall rules as a standalone system would.

-

However, on a gateway there are additional things to do:

- -

You need additional rules to handle these things. For example, adding - some rules to the set shown above we get:

-
# edit this line to match the interface you use as default route
-# ppp0 is correct for many modem, DSL or cable connections
-# but perhaps not for you
-world=ppp0
-#
-# edit these lines to describe your internal subnet and interface
-localnet=42.42.42.0/24
-internal=eth1
-#
-# allow IPsec
-#
-# IKE negotiations
-iptables -A INPUT  -p udp -i $world --sport 500 --dport 500 -j ACCEPT
-iptables -A OUTPUT -p udp -o $world --sport 500 --dport 500 -j ACCEPT
-# ESP encryption and authentication
-iptables -A INPUT  -p 50 -i $world -j ACCEPT
-iptables -A OUTPUT -p 50 -o $world -j ACCEPT
-#
-# packet forwarding for an IPsec gateway
-# simplest possible rules
-$ forward everything, with no attempt to filter
-#
-# handle packets emerging from IPsec
-# ipsec+ means any of ipsec0, ipsec1, ...
-iptables -A FORWARD -d $localnet -i ipsec+ -j ACCEPT
-# simple rule for outbound packets
-# let local net send anything
-# IPsec will encrypt some of it
-iptables -A FORWARD -s $localnet -i $internal -j ACCEPT
-

On a production gateway, you would no doubt need tighter rules than - the above.

-

Firewall resources

-

For more information, see these handy resources:

- -Back to our quickstart guide. - - - - - diff --git a/doc/src/quickstart.html b/doc/src/quickstart.html deleted file mode 100644 index a74c11774..000000000 --- a/doc/src/quickstart.html +++ /dev/null @@ -1,458 +0,0 @@ - - - - Quick FreeS/WAN installation and configuration - - - - -

Quickstart Guide to Opportunistic Encryption

- - -

Purpose

- -

This page will get you started using Linux FreeS/WAN with opportunistic - encryption (OE). OE enables you to set up IPsec tunnels - without co-ordinating with another - site administrator, and without hand configuring each tunnel. - If enough sites support OE, a "FAX effect" occurs, and - many of us can communicate without eavesdroppers.

- -

OE "flag day"

- -

As of FreeS/WAN 2.01, OE uses DNS TXT resource records (RRs) -only (rather than TXT with KEY). -This change causes a -"flag day". -Users of FreeS/WAN 2.00 (or earlier) OE who are upgrading may require -additional resource records, as detailed in our -upgrading document. -OE setup instructions here are for 2.02 or later.

- - -

Requirements

- -

To set up opportunistic encryption, you will need:

- - -

Note: Currently, only Linux FreeS/WAN supports opportunistic -encryption.

- -

RPM install

- -

Our instructions are for a recent Red Hat with a 2.4-series stock or -Red Hat updated kernel. For other ways to install, see our -install document.

- - -

Download RPMs

- -

If we have prebuilt RPMs for your Red Hat system, -this command will get them: -

- -
    ncftpget ftp://ftp.xs4all.nl/pub/crypto/freeswan/binaries/RedHat-RPMs/`uname -r | tr -d 'a-wy-z'`/\*
- -

If that fails, you will need to try another install -method. -Our kernel modules -will only work on the Red Hat kernel they were built for, -since they are very sensitive to small changes in the kernel.

- -

If it succeeds, you will have userland tools, a kernel module, and an -RPM signing key:

- -
    freeswan-module-2.04_2.4.20_20.9-0.i386.rpm
-    freeswan-userland-2.04_2.4.20_20.9-0.i386.rpm
-    freeswan-rpmsign.asc
- - -

Check signatures

- -

If you're running RedHat 8.x or later, import the RPM signing key into the -RPM database:

-
    rpm --import freeswan-rpmsign.asc
- -

For RedHat 7.x systems, you'll need to add it to your -PGP keyring:

-
    pgp -ka freeswan-rpmsign.asc
- -

Check the digital signatures on both RPMs using:

-
    rpm --checksig freeswan*.rpm
- -

You should see that these signatures are good:

-
    freeswan-module-2.04_2.4.20_20.9-0.i386.rpm: pgp md5 OK
-    freeswan-userland-2.04_2.4.20_20.9-0.i386.rpm: pgp md5 OK
- - -

Install the RPMs

- -

Become root:

-
    su
- -

Install your RPMs with:

-

    rpm -ivh freeswan*.rpm
- -

If you're upgrading from FreeS/WAN 1.x RPMs, and have problems with that -command, see -this note.

- -

Then, start FreeS/WAN:

-
    service ipsec start
- - -

Test

-

To check that you have a successful install, run:

-
    ipsec verify
- -

You should see as part of the verify output:

-
-    Checking your system to see if IPsec got installed and started correctly
-    Version check and ipsec on-path                             [OK]
-    Checking for KLIPS support in kernel                        [OK]
-    Checking for RSA private key (/etc/ipsec.secrets)           [OK]
-    Checking that pluto is running                              [OK]
-    ...
- -

If any of these first four checks fails, see our -troubleshooting guide. -

- -

Our Opportunistic Setups

-

Full or partial opportunism?

-

Determine the best form of opportunism your system can support.

- - -

Initiate-only setup

- -

Restrictions

-

When you set up initiate-only Opportunistic Encryption (iOE):

- -

You cannot network a group of initiator-only machines if none -of these is capable of responding to OE. If one is capable of responding, -you may be able to create a hub topology using routing.

- - -

Create and publish a forward DNS record

- -

Find a domain you can use

- -

Find a DNS forward domain (e.g. example.com) where you can publish your key. -You'll need access to the DNS zone files for that domain. -This is common for a domain you own. Some free DNS providers, -such as this one, also provide -this service.

- -

Dynamic IP users take note: the domain where you place your key - need not be associated with the IP address for your system, - or even with your system's usual hostname.

- -

Choose your ID

- -

Choose a name within that domain which you will use to identify your - machine. It's convenient if this can be the same as your hostname:

-
    [root@xy root]# hostname --fqdn
-    xy.example.com
-

This name in FQDN (fully-qualified domain name) -format will be your ID, for DNS key lookup and IPsec -negotiation.

- - -

Create a forward TXT record

- -

Generate a forward TXT record containing your system's public key - with a command like:

-
    ipsec showhostkey --txt @xy.example.com
-

using your chosen ID in place of -xy.example.com. -This command takes the contents of -/etc/ipsec.secrets and reformats it into something usable by ISC's BIND. - The result should look like this (with the key data trimmed down for - clarity):

-
-    ; RSA 2192 bits   xy.example.com   Thu Jan  2 12:41:44 2003
-        IN      TXT     "X-IPsec-Server(10)=@xy.example.com" 
-    "AQOF8tZ2... ...+buFuFn/"
-
- - -

Publish the forward TXT record

- -

Insert the record into DNS, or have a system adminstrator do it -for you. It may take up to 48 hours for the record to propagate, but -it's usually much quicker.

- -

Test that your key has been published

- -

Check your DNS work

- -
    ipsec verify --host xy.example.com
- -

As part of the verify output, you ought to see something -like:

- -
    ...
-    Looking for TXT in forward map: xy.example.com          [OK]
-    ...
- -

For this type of opportunism, only the forward test is relevant; -you can ignore the tests designed to find reverse records.

- - -

Configure, if necessary

- -

-If your ID is the same as your hostname, -you're ready to go. -FreeS/WAN will use its -built-in connections to create -your iOE functionality. -

- -

If you have chosen a different ID, you must tell FreeS/WAN about it via -ipsec.conf: - -

    config setup
-        myid=@myname.freedns.example.com
- -

and restart FreeS/WAN: -

-
    service ipsec restart
-

The new ID will be applied to the built-in connections.

- -

Note: you can create more complex iOE configurations as explained in our -policy groups document, or -disable OE using -these instructions.

- - -

Test

-

That's it! Test your connections.

- -

Full Opportunism

- -

Full opportunism -allows you to initiate and receive opportunistic connections on your -machine.

- -

Put a TXT record in a Forward Domain

- -

To set up full opportunism, first -set up a forward TXT record as for -initiator-only OE, using -an ID (for example, your hostname) that resolves to your IP. Do not -configure /etc/ipsec.conf, but continue with the -instructions for full opportunism, below. -

- -

Note that this forward record is not currently necessary for full OE, -but will facilitate future features.

- - -

Put a TXT record in Reverse DNS

- -

You must be able to publish your DNS RR directly in the reverse domain. -FreeS/WAN will not follow a PTR which appears in the reverse, since -a second lookup at connection start time is too costly.

- - -

Create a Reverse DNS TXT record

- -

This record serves to publicize your FreeS/WAN public key. In - addition, it lets others know that this machine can receive opportunistic -connections, and asserts that the machine is authorized to encrypt on -its own behalf.

- -

Use the command:

-
    ipsec showhostkey --txt 192.0.2.11
-

where you replace 192.0.2.11 with your public IP.

- -

The record (with key shortened) looks like:

-
    ; RSA 2048 bits  xy.example.com   Sat Apr 15 13:53:22 2000
-    IN TXT  "X-IPsec-Server(10)=192.0.2.11" " AQOF8tZ2...+buFuFn/"
- - -

Publish your TXT record

- -

Send these records to your ISP, to be published in your IP's reverse map. -It may take up to 48 hours for these to propagate, but usually takes -much less time.

- - -

Test your DNS record

- -

Check your DNS work with

- -
    ipsec verify --host xy.example.com
- -

As part of the verify output, you ought to see something like:

- -
    ...
-    Looking for TXT in reverse map: 11.2.0.192.in-addr.arpa [OK]
-    ...
- -

which indicates that you've passed the reverse-map test.

- -

No Configuration Needed

- -

FreeS/WAN 2.x ships with full OE enabled, so you don't need to configure -anything. -To enable OE out of the box, FreeS/WAN 2.x uses the policy group -private-or-clear, -which creates IPsec connections if possible (using OE if needed), -and allows traffic in the clear otherwise. You can create more complex -OE configurations as described in our -policy groups document, or -disable OE using -these instructions.

- -

If you've previously configured for initiator-only opportunism, remove - myid= from config setup, so that peer FreeS/WANs -will look up your key by IP. Restart FreeS/WAN so that your change will -take effect, with

- -
    service ipsec restart
- - -

Consider Firewalling

- -

If you are running a default install of RedHat 8.x, take note: you will -need to alter your iptables rule setup to allow IPSec traffic through your -firewall. See our firewall document -for sample iptables rules.

- - -

Test

- -

That's it. Now, test your connection. - - - - -

Test

- -

Instructions are in the next section.

- - -

Testing opportunistic connections

- -

Be sure IPsec is running. You can see whether it is with:

-
    ipsec setup status
-

If need be, you can restart it with:

-
    service ipsec restart
- -

Load a FreeS/WAN test website from the host on which you're running -FreeS/WAN. Note: the feds may be watching these sites. Type one of:

-

   links oetest.freeswan.org
-
   links oetest.freeswan.nl
- - -

A positive result looks like this:

- -
-   You  seem  to  be  connecting  from:  192.0.2.11 which DNS says is:
-   gateway.example.com
-     _________________________________________________________________
-
-   Status E-route
-   OE    enabled    16    192.139.46.73/32    ->    192.0.2.11/32   =>
-   tun0x2097@192.0.2.11
-   OE    enabled    176    192.139.46.77/32    ->   192.0.2.11/32   =>
-   tun0x208a@192.0.2.11
-
- -

If you see this, congratulations! Your OE host or gateway will now encrypt -its own traffic whenever it can. For more OE tests, please see our -testing document. If you have difficulty, -see our OE troubleshooting tips. -

- - - -

Now what?

- -

Please see our policy groups document -for more ways to set up Opportunistic Encryption.

- -

You may also wish to make some -pre-configured connections. -

- -

Notes

- - - -

Troubleshooting OE

- -

See the OE troubleshooting hints in our -troubleshooting guide. -

- -

Known Issues

- -

Please see -this list of known issues -with Opportunistic Encryption.

- - - - diff --git a/doc/src/reference.ESPUDP.xml b/doc/src/reference.ESPUDP.xml deleted file mode 100644 index c9b96cef3..000000000 --- a/doc/src/reference.ESPUDP.xml +++ /dev/null @@ -1,34 +0,0 @@ - - - - - - -UDP Encapsulation of IPsec Packets - -F-Secure Corporation -
- -Tammasaarenkatu 7 -FIN-00181 HELSINKI -Finland -Ari.Huttunen@F-Secure.com
 - - -Microsoft -
- -One Microsoft Way -Redmond -WA 98052 -USA -wdixon@microsoft.com
 - - -Security -IP security protocol -IPSEC -security - - - diff --git a/doc/src/reference.KEYRESTRICT.xml b/doc/src/reference.KEYRESTRICT.xml deleted file mode 100644 index 62aa1ef96..000000000 --- a/doc/src/reference.KEYRESTRICT.xml +++ /dev/null @@ -1,31 +0,0 @@ - - - - - - -Limiting the Scope of the KEY Resource Record - -USC/ISI -
- -USC Informational Sciences Institute -3811 North Fairfax Drive, Suite 200 -Arlington, VA 22203 -USA -masseyd@isi.edu
 - - -National Institute for Standards and Technology -
- -Gaithersburg, MD -USA -scott.rose@nist.gov
 - - -Internet - - - - diff --git a/doc/src/reference.MODPGROUPS.xml b/doc/src/reference.MODPGROUPS.xml deleted file mode 100644 index 5eaf83f89..000000000 --- a/doc/src/reference.MODPGROUPS.xml +++ /dev/null @@ -1,32 +0,0 @@ - - - - - - -More MODP Diffie-Hellman groups for IKE - -SSH Communications Security -
- -Fredrikinkatu 42 -FIN-00100 HELSINKI -Finland -kivinen@ssh.fi
 - - -University of Helsinki -
- -HELSINKI -Finland -mrskojo@cc.helsinki.fi
 - - -Security -IP security protocol -IPSEC -security - - - diff --git a/doc/src/reference.OEspec.xml b/doc/src/reference.OEspec.xml deleted file mode 100644 index 29c6d6efd..000000000 --- a/doc/src/reference.OEspec.xml +++ /dev/null @@ -1,45 +0,0 @@ - - - - - - -Opportunistic Encryption - - - Mimosa -
- - Somewhere - Toronto - ON - CA - - hugh@mimosa.com -
- - - - SP Systems -
- - Box 280 Station A - Toronto - ON - M5W 1B2 - Canada - - henry@spsystems.net -
- - - -IP security protocol -IPSEC -security - - - - diff --git a/doc/src/reference.RFC.3526.xml b/doc/src/reference.RFC.3526.xml deleted file mode 100644 index 54fed705a..000000000 --- a/doc/src/reference.RFC.3526.xml +++ /dev/null @@ -1,32 +0,0 @@ - - - - - - -More MODP Diffie-Hellman groups for IKE - -SSH Communications Security -
- -Fredrikinkatu 42 -FIN-00100 HELSINKI -Finland -kivinen@ssh.fi
 - - -University of Helsinki -
- -HELSINKI -Finland -mrskojo@cc.helsinki.fi
 - - -Security -IP security protocol -IPSEC -security - - - diff --git a/doc/src/responderstate.txt b/doc/src/responderstate.txt deleted file mode 100644 index f64b82983..000000000 --- a/doc/src/responderstate.txt +++ /dev/null @@ -1,43 +0,0 @@ - | - | IKE main mode - | phase 1 - V - .-----------------. - | unauthenticated | - | OE peer | - `-----------------' - | - | lookup KEY RR in in-addr.arpa - | (if ID_IPV4_ADDR) - | lookup KEY RR in forward - | (if ID_FQDN) - V - .-----------------. RR not found - | received DNS |---------------> log failure - | reply | - `----+--------+---' - phase 2 | \ misformatted - proposal | `------------------> log failure - V - .----------------. - | authenticated | identical initiator - | OE peer |--------------------> initiator - `----------------' connection found state machine - | - | look for TXT record for initiator - | - V - .---------------. - | authorized |---------------------> log failure - | OE peer | - `---------------' - | - | - V - potential OE - connection in - initiator state - machine - - -$Id: responderstate.txt,v 1.1 2004/03/15 20:35:24 as Exp $ diff --git a/doc/src/rfc.html b/doc/src/rfc.html deleted file mode 100644 index 762c66c6e..000000000 --- a/doc/src/rfc.html +++ /dev/null @@ -1,158 +0,0 @@ - - - - IPsec RFCs - - - - - -

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:

- - -

browsable in HTML form at others such as:

- - -

and some of them are available in translation:

- - -

There is also a published Big Book of IPSEC -RFCs.

- -

Internet Drafts

- -

Internet Drafts, working documents which sometimes evolve into RFCs, are -also available.

- - -

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.

- -

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
- - diff --git a/doc/src/roadmap.html b/doc/src/roadmap.html deleted file mode 100644 index c9d85047c..000000000 --- a/doc/src/roadmap.html +++ /dev/null @@ -1,203 +0,0 @@ - - -FreeS/WAN roadmap - - - - - - -

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

- - - - diff --git a/doc/src/testing.html b/doc/src/testing.html deleted file mode 100644 index 8ffcca604..000000000 --- a/doc/src/testing.html +++ /dev/null @@ -1,395 +0,0 @@ - - -Testing FreeS/WAN - - - - - - - -

Testing FreeS/WAN

-This document discusses testing FreeS/WAN. - -

Not all types of testing are described here. Other parts of the -documentation describe some tests:

-
-
installation document
-
testing for a successful install
-
configuration document
-
basic tests for a working configuration
-
web links document
-
General information on tests for interoperability between various - IPsec implementations. This includes links to several test sites.
-
interoperation document.
-
More specific information on FreeS/WAN interoperation with other - implementations.
-
performance document
-
performance measurements
-
- -

The test setups and procedures described here can also be used in other -testing, but this document focuses on testing the IPsec functionality of -FreeS/WAN.

- -

Testing opportunistic connections

- -

This section teaches you how to test your opportunistically encrypted (OE) -connections. To set up OE, please see the easy instructions in our -quickstart guide.

- -

Basic OE Test

- - -

This test is for basic OE functionality. - -For additional tests, keep reading.

- -

Be sure IPsec is running. You can see whether it is with:

-
    ipsec setup status
-

If need be, you can restart it with:

-
    service ipsec restart
- -

Load a FreeS/WAN test website from the host on which you're running -FreeS/WAN. Note: the feds may be watching these sites. Type one of:

-

   links oetest.freeswan.org
-
   links oetest.freeswan.nl
- - -

A positive result looks like this:

- -
-   You  seem  to  be  connecting  from:  192.0.2.11 which DNS says is:
-   gateway.example.com
-     _________________________________________________________________
-                                                                                
-   Status E-route
-   OE    enabled    16    192.139.46.73/32    ->    192.0.2.11/32   =>
-   tun0x2097@192.0.2.11
-   OE    enabled    176    192.139.46.77/32    ->   192.0.2.11/32   =>
-   tun0x208a@192.0.2.11
-
- -

If you see this, congratulations! Your OE box will now encrypt -its own traffic whenever it can. If you have difficulty, -see our OE troubleshooting tips. -

- -

OE Gateway Test

-

If you've set up FreeS/WAN to protect a subnet behind your gateway, -you'll need to run another simple test, which can be done from a machine -running any OS. That's right, your Windows box can be protected by -opportunistic encryption without any FreeS/WAN install or configuration -on that box. From each protected subnet node, -load the FreeS/WAN website with:

- -
   links oetest.freeswan.org
-
   links oetest.freeswan.nl
- -

A positive result looks like this:

-
-   You  seem  to  be  connecting  from:  192.0.2.98 which DNS says is:
-   box98.example.com
-     _________________________________________________________________
-                                                                                
-   Status E-route
-   OE    enabled    16    192.139.46.73/32    ->    192.0.2.98/32   =>
-   tun0x134ed@192.0.2.11
-   OE    enabled    176    192.139.46.77/32    ->   192.0.2.11/32   =>
-   tun0x134d2@192.0.2.11
-
- -

If you see this, congratulations! Your OE gateway will now encrypt -traffic for this subnet node whenever it can. If you have difficulty, see our -OE troubleshooting tips. -

- - -

Additional OE tests

- -

When testing OE, you will often find it useful to execute this command -on the FreeS/WAN host:

-
   ipsec eroute
- -

If you have established a connection (either for or for a subnet node) -you will see a result like:

- -
    192.0.2.11/32   -> 192.139.46.73/32  => tun0x149f@192.139.46.38
-
- -

Key:

- - - - - - - - - - - - - -
1.192.0.2.11/32Local start point of the protected traffic. -
2.192.0.2.194/32Remote end point of the protected traffic. -
3.192.0.48.38Remote FreeS/WAN node (gateway or host). - May be the same as (2). -
4.[not shown]Local FreeS/WAN node (gateway or host), where you've produced the output. - May be the same as (1). -
- - -

For extra assurance, you may wish to use a packet sniffer such as -tcpdump to verify that packets -are being encrypted. You should see output that indicates -ESP encrypted data, - for example:

- -
    02:17:47.353750 PPPoE  [ses 0x1e12] IP 154: xy.example.com > oetest.freeswan.org: ESP(spi=0x87150d16,seq=0x55)
- - - -

Testing with User Mode Linux

- -

User Mode Linux -allows you to run Linux as a user process on another Linux machine.

- -

As of 1.92, the distribution has a new directory named testing. It -contains a collection of test scripts and sample configurations. Using these, -you can bring up several copies of Linux in user mode and have them build -tunnels to each other. This lets you do some testing of a FreeS/WAN -configuration on a single machine.

- -

You need a moderately well-endowed machine for this to work well. Each UML -wants about 16 megs of memory by default, which is plenty for FreeS/WAN -usage. Typical regression testing only occasionally uses as many as 4 UMLs. -If one is doing nothing else with the machine (in particular, not running X -on it), then 128 megs and a 500MHz CPU are fine.

- -Documentation on these -scripts is here. There is also documentation -on automated testing here. - -

Configuration for a testbed network

- -

A common test setup is to put a machine with dual Ethernet cards in -between two gateways under test. You need at least five machines; two -gateways, two clients and a testing machine in the middle.

- -

The central machine both routes packets and provides a place to run -diagnostic software for checking IPsec packets. See next section for -discussion of using tcpdump(8) for this.

- -

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.

- -

What you end up with looks like:

- -

Testbed 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
-
Where p and q are 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.

- -

Using packet sniffers in testing

- -

A number of tools are available for looking at packets. We will discuss -using tcpdump(8), a common Linux tool -included in most distributions. Alternatives offerring more-or-less the same -functionality include:

-
-
Ethereal
-
Several people on our mailing list report a preference for this over - tcpdump.
-
windump
-
a Windows version of tcpdump(8), possibly handy if you have Windows - boxes in your network
-
Sniffit
-
A linux sniffer that we don't know much about. If you use it, please - comment on our mailing list.
-
- -

See also this index of packet -sniffers.

- -

tcpdump(8) may 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.

- -

At one point, the problem was quite severe. Recent versions of tcpdump, -however, understand IPsec well enough to be usable on a gateway. You can get -the latest version from tcpdump.org.

- -

Even with a recent tcpdump, some care is required. Here is part of a post -from Henry on the topic:

-
> a) data from sunset to sunrise or the other way is not being
-> encrypted (I am using tcpdump (ver. 3.4) -x/ping -p to check
-> packages) 
-
-What *interface* is tcpdump being applied to?  Use the -i option to
-control this.  It matters!  If tcpdump is looking at the ipsecN
-interfaces, e.g. ipsec0, then it is seeing the packets before they are
-encrypted or after they are decrypted, so of course they don't look
-encrypted.  You want to have tcpdump looking at the actual hardware
-interfaces, e.g. eth0. 
-
-Actually, the only way to be *sure* what you are sending on the wire is to
-have a separate machine eavesdropping on the traffic.  Nothing you can do
-on the machines actually running IPsec is 100% guaranteed reliable in this
-area (although tcpdump is a lot better now than it used to be).
- -

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. Network configuration for such testing is discussed above.

- -

Here's another mailing list message with advice on using tcpdump(8):

-
Subject: RE: [Users] Encrypted???
-   Date: Thu, 29 Nov 2001
-   From: "Joe Patterson" <jpatterson@asgardgroup.com>
-
-tcpdump -nl -i $EXT-IF proto 50
-
--nl tells it not to buffer output or resolve names (if you don't do that it
-may confuse you by not outputing anything for a while), -i $EXT-IF (replace
-with your external interface) tells it what interface to listen on, and
-proto 50 is ESP.  Use "proto 51" if for some odd reason you're using AH, and
-"udp port 500" if you want to see the isakmp key exchange/tunnel setup
-packets.
-
-You can also run `tcpdump -nl -i ipsec0` to see what traffic is on that
-virtual interface.  Anything you see there *should* be either encrypted or
-dropped (unless you've turned on some strange options in your ipsec.conf
-file)
-
-Another very handy thing is ethereal (http://www.ethereal.com/) which runs
-on just about anything, has a nice gui interface (or a nice text-based
-interface), and does a great job of protocol  breakdown.  For ESP and AH
-it'll basically just tell you that there's a packet of that protocol, and
-what the spi is, but for isakmp it'll actually show you a lot of the tunnel
-setup information (until it gets to the point in the protocol where isakmp
-is encrypted....)
- -

Verifying encryption

- -

The question of how to verify that messages are actually encrypted has -been extensively discussed on the mailing list. See this thread.

- -

If you just want to verify that packets are encrypted, look at them with a -packet sniffer (see previous section) located -between the gateways. The packets should, except for some of the header -information, be utterly unintelligible. The output of good encryption -looks exactly like random noise.

- -

A packet sniffer can only tell you that the data you looked at was -encrypted. If you have stronger requirements -- for example if your security -policy requires verification that plaintext is not leaked during startup or -under various anomolous conditions -- then you will need to devise much more -thorough tests. If you do that, please post any results or methodological -details which your security policy allows you to make public.

- -

You can put recognizable data into 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 other protocols, you may 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.

- -

One thing to watch for: the output of good compression, like that of good -encryption, looks just like random noise. You cannot tell just by looking at -a data stream whether it has been compressed, encrypted, or both. You need a -little care not to mistake compressed data for encrypted data in your -testing.

- -

Note also that weak encryption also produces random-looking output. You -cannot tell whether the encryption is strong by looking at the output. To be -sure of that, you would need to have both the algorithms and the -implementation examined by experts.

- -

For IPsec, you can get partial assurance from interoperability tests. See -our interop document. When twenty products all -claim to implement 3DES, and they all talk -to each other, you can be fairly sure they have it right. Of course, you -might wonder whether all the implementers are consipring to trick you or, -more plausibly, whether some implementations might have "back doors" so they -can get also it wrong when required.. If you're seriously worried about -things like that, you need to get the code you use audited (good luck if it -is not Open Source), or perhaps to talk to a psychiatrist about treatments -for paranoia.

- -

Mailing list pointers

- -

Additional information on testing can be found in these mailing list messages:

- - - diff --git a/doc/src/testingtools.html b/doc/src/testingtools.html deleted file mode 100644 index 491b1956c..000000000 --- a/doc/src/testingtools.html +++ /dev/null @@ -1,188 +0,0 @@ - - -FreeS/WAN survey of testing tools - - - - - - - - -

Survey of testing tools

- -

http://freshmeat.net/projects/apsend

- -

-About: APSEND is a TCP/IP packet sender to test firewalls and other -network applications. It also includes a syn flood option, the land -DoS attack, a DoS attack against tcpdump running on a UNIX-based -system, a UDP-flood attack, and a ping flood option. It currently -supports the following protocols: IP, TCP, UDP, ICMP, Ethernet frames -and you can also build any other type of protocol using the generic -option. The scripting language of apsend is already written, but not -yet public. -

- -

-STATUS: The public web site seems to have died -

- -

http://freshmeat.net/projects/hping2

- -

-About: hping2 is a network tool -able to send custom ICMP/UDP/TCP packets and to display target replies -like ping does with ICMP replies. It handles fragmentation and -arbitrary packet body and size, and can be used to transfer files -under supported protocols. Using hping2, you can: test firewall rules, -perform [spoofed] port scanning, test net performance using different -protocols, packet size, TOS (type of service), and fragmentation, do -path MTU discovery, tranfer files (even between really Fascist -firewall rules), perform traceroute-like actions under different -protocols, fingerprint remote OSs, audit a TCP/IP stack, etc. hping2 -is a good tool for learning TCP/IP. -

- -

-This utility has rather complicated usage and no man page at present. -The documentation is supposed to be in HPING2-HOWTO, but that file -seems to be absent. -

- -

http://freshmeat.net/projects/icmpush

- -

-About: ICMPush is a tool that send ICMP packets fully customized from command -line. This release supports the ICMP error types Unreach, Parameter -Problem, Redirect and Source Quench and the ICMP information types -Timestamp, Address Mask Request, Information Request, Router -Solicitation, Router Advertisement and Echo Request. Also supports -ip-spoofing, broadcasting and other useful features. It's really a -powerful program for testing and debugging TCP/IP stacks and networks. -

- -

-

- -

http://freshmeat.net/projects/isic

- -

-ISIC sends randomly generated packets to a target computer. Its -primary uses are to stress-test an IP stack, to find leaks in a -firewall, and to test the implementation of IDSes and firewalls. The -user can specify how often the packets will be frags, have IP options, -TCP options, an urgent pointer, etc. Programs for TCP, UDP, ICMP, -IP w/ random protocols, and random ethernet frames are included. -

- -

http://freshmeat.net/projects/sendpacket

- -

-Send Packet is a small but powerful program to test how your network -responds to specific packet content. Via a config file and/or command -line parameters, you can forge (modify the headers of) your own -TCP/UDP/ICMP/IP packets and send them through your network. Also, -following the Easy Sniffer modular philosophy, you can specify wich -modules you'd like to build. -

- -

http://freshmeat.net/projects/aicmpsend/

- -

-AICMPSEND is an ICMP sender with many features including ICMP -flooding and spoofing. All ICMP flags and codes are implemented. You -can use this program for various DoS attacks, for ICMP flooding and -to test firewalls. -

- -

http://freshmeat.net/projects/sendip/

- -

-SendIP is a command-line tool to send arbitrary IP packets. It has a -large number of options to specify the content of every header of a -RIP, TCP, UDP, ICMP, or raw IPv4/IPv6 packet. It also allows any data -to be added to the packet. Checksums can be calculated automatically, -but if you wish to send out wrong checksums, that is supported too. -

- -

http://laurent.riesterer.free.fr/gasp/index.html

- -

-GASP stands for 'Generator and Analyzer System for Protocols'. It -allows you to decode and encode any protocols you specify. -

- -

-The main use is probably to test networks applications : you can -construct packets by hand and test the behavior of your program when -facing some strange packets. But you can image a lot of other -application : e.g. manipulating graphical file or executable -headers. Just describe the specification of the structured data. -

- -

-GASP is divided in two parts : a compiler which take the specification -of the protocols and generate the code to handle it, this code is a -new Tcl command as GASP in build upon Tcl/Tk and extends the scripting -facilities provided by Tcl. -

- -

http://pdump.lucidx.com/

-

http://freshmeat.net/projects/aps/

-

http://freshmeat.net/projects/netsed/

-

http://www.via.ecp.fr/~bbp/netsh/

-

http://www.elxsi.de/

-

http://www.laurentconstantin.com/us/lcrzo/

-

http://www.joedog.org/libping/index.html

-

http://feynman.mme.wilkes.edu/projects/xNetTools/

-

http://freshmeat.net/projects/pktsrc/

-

http://freshmeat.net/projects/lcrzoex/

-

http://freshmeat.net/projects/rain/

-

-rain is a powerful packet builder for testing the stability of -hardware and software. Its features include support for all IP -protocols and the ability to fully customize the packets it sends. -

- -

(Note, this is not the same as /usr/games/rain)

- -

http://freshmeat.net/projects/libnet

-

http://freshmeat.net/projects/pftp

-

http://freshmeat.net/projects/pung

- -

-pung is a simple server tester. It tries to connect via TCP/IP to a -server but does not transfer any data. It is meant to be used in -scripts that check a list of servers, helping to detect certain common -problems. -

- -

http://freshmeat.net/projects/thesunpacketshell

-

http://freshmeat.net/projects/webperformancetrainer

-

http://sourceforge.net/projects/va-ctcs

-

http://synscan.nss.nu/programs.php

-

http://sourceforge.net/projects/va-ctcs

-

http://freshmeat.net/projects/ettercap/

-

http://www.dtek.chalmers.se/~d3august/xt/index.html

-

http://www.opersys.com/LTT/

-

http://packetstorm.securify.com/DoS/indexdate.shtml

-

TCP/IP noise simulator

diff --git a/doc/src/trouble.html b/doc/src/trouble.html deleted file mode 100644 index 604264c01..000000000 --- a/doc/src/trouble.html +++ /dev/null @@ -1,840 +0,0 @@ - - - FreeS/WAN troubleshooting - - - - - - -

Linux FreeS/WAN Troubleshooting Guide

- -

Overview

- -

-This document covers several general places where you might have a problem:

-
    -
  1. During install.
    2. -
  2. During the negotiation process.
    3. -
  3. Using an established connection.
    4. -
-

This document also contains notes which -expand on points made in these sections, and tips for -problem -reporting. If the other end of your connection is not FreeS/WAN, -you'll also want to read our -interoperation document.

-

1. During Install

-

1.1 RPM install gotchas

-

With the RPM method:

- -

1.2 Problems installing from source

-

When installing from source, you may find these problems:

- -

1.3 Install checks

-

ipsec verify checks a number -of FreeS/WAN essentials. Here are some hints on what do to when your -system doesn't check out:

-

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
ProblemStatusAction
ipsec not on-path 

Add /usr/local/sbin to your PATH.

Missing KLIPS supportcriticalSee this FAQ.
No RSA private key  -

Follow these -instructions to create an RSA key pair for your host. RSA keys are:

-
    -
  • required for opportunistic encryption, and
    • -
  • our preferred method to authenticate pre-configured connections.
    • -
-
pluto not runningcritical
service ipsec start
No port 500 holecriticalOpen port 500 for IKE negotiation.
Port 500 check N/A Check that port 500 is open for IKE negotiation.
Failed DNS checks Opportunistic encryption requires information from DNS. -To set this up, see our instructions. -
No public IP address Check that the interface which you want to protect with IPSec is up and -running.
- - -

1.3 Troubleshooting OE

-

OE should work with no local configuration, if you have posted -DNS TXT records according to the instructions in our -quickstart guide. -If you encounter trouble, try these hints. -We welcome additional hints via the -users' mailing list.

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
SymptomProblemAction
-You're running FreeS/WAN 2.01 (or later), -and initiating a connection to FreeS/WAN -2.00 (or earlier). -In your logs, you see a message like: -
no RSA public key known for '192.0.2.13';
-DNS search for KEY failed (no KEY record
-for 13.2.0.192.in-addr.arpa.)
-The older FreeS/WAN logs no error. -		 - -A protocol level incompatibility between 2.01 (or later) and -2.00 (or earlier) causes this error. It occurs when a FreeS/WAN 2.01 -(or later) box for which no KEY record is posted attempts to initiate an OE -connection to older FreeS/WAN versions (2.00 and earlier). -Note that older versions can initiate to newer versions without this error. -If you control the peer host, upgrade its FreeS/WAN to 2.01 (or later), and -post new style TXT records for it. If not, but if you know its sysadmin, -perhaps a quick note is in order. If neither option is possible, you can -ease the transition by posting an old style KEY record (created with a -command like "ipsec showhostkey --key") to the reverse map for -the FreeS/WAN 2.01 (or later) box.
OE host is very slow to contact other hosts.Slow DNS service while running OE.It's a good idea to run a caching DNS server on your OE host, -as outlined in this -mailing list message. If your DNS servers are elsewhere, -put their IPs -in the clear policy group, and -re-read groups with 
ipsec auto --rereadgroups
-
-
Can't Opportunistically initiate for
-192.0.2.2 to 192.0.2.3: no TXT record
-for 13.2.0.192.in-addr.arpa.
-		Peer is not set up for OE.

None. Plenty of hosts on the Internet -do not run OE. If, however, you have set OE up on that peer, this may -indicate that you need to wait up to 48 hours -for its DNS records to propagate.

ipsec verify does not find DNS records: -
...
-Looking for TXT in forward map:
-                xy.example.com...[FAILED]
-Looking for TXT in reverse map...[FAILED]
-...
- -You also experience authentication failure:
-
Possible authentication failure:
-no acceptable response to our
-first encrypted message
-		DNS records are not posted or have not propagated.Did you post the DNS records necessary for OE? If not, -do so using the instructions in our -quickstart guide. -If so, wait up to 48 hours for the DNS records to propagate.
ipsec verify does not find DNS records, and you experience -authentication failure.For iOE, your ID -does not match location of -forward DNS record.In config setup, change -myid= to match the forward DNS where you posted the record. -Restart FreeS/WAN. - For reference, see our -iOE instructions.
ipsec verify finds DNS records, yet there is -still authentication failure. ( ? )DNS records are malformed.Re-create the records and send new copies to your DNS administrator.
ipsec verify finds DNS records, yet there is -still authentication failure. ( ? )DNS records show different keys for a gateway vs. its subnet hosts.All TXT records for boxes protected by an OE gateway must contain the -gateway's public key. Re-create and re-post any incorrect records using -these instructions.
OE gateway loses connectivity to its subnet. The gateway's -routing table shows routes to the subnet through IPsec interfaces.The subnet is part of the private or block -policy group on the gateway.Remove the subnet from the group, and reread -groups with 
ipsec auto --rereadgroups
OE does not work to hosts on the local LAN.This is a known issue.See this list of known issues -with OE. -
FreeS/WAN does not seem to be executing your default policy. In your -logs, you see a message like: -
/etc/ipsec.d/policies/iprivate-or-clear"
-line 14: subnet "0.0.0.0/0",
-source 192.0.2.13/32,
-already "private-or-clear"
-		Fullnet in a policy group file defines -your default policy. Fullnet should normally be present in only one policy -group file. The fine print: you can have two default policies defined so long -as they protect different local endpoints (e.g. the FreeS/WAN gateway and a -subnet). -Find all policies which contain fullnet with:
-
grep -F 0.0.0.0/0 /etc/ipsec.d/policies/*
-then remove the unwanted occurrence(s). -
- - -

2. During Negotiation

-

When you fail to bring up a tunnel, you'll need to find out:

- -

before you can -diagnose your problem.

-

2.1 Determine Connection State

-

Finding current state

-

You can see connection states (STATE_MAIN_I1 and so on) when you -bring up a connection on the command line. If you have missed this, -or brought up your connection automatically, use: -

-
ipsec auto --status
-

The most relevant state is the last one reached.

-

What's this supposed to look like?

-

Negotiations should proceed though various states, in the processes of:

-
    -
  1. IKE negotiations (aka Phase 1, Main Mode, STATE_MAIN_*)
    2. -
  2. IPSEC negotiations (aka Phase 2, Quick Mode, STATE_QUICK_*)
    3. -
-

These are done and a connection is established when you see messages like:

-
    000 #21: "myconn" STATE_MAIN_I4 (ISAKMP SA established)...
-    000 #2: "myconn" STATE_QUICK_I2 (sent QI2, IPsec SA established)...

-Look for the key phrases are "ISAKMP SA established" and "IPSec -SA established", with the relevant connection name. Often, this happens -at STATE_MAIN_I4 and STATE_QUICK_I2, respectively.

-

ipsec auto --status will tell you what states have -been achieved, rather than the current state. Since -determining the current state is rather more difficult to do, current -state information is not available from Linux FreeS/WAN. If you are -actively bringing a connection up, the status report's last states -for that connection likely reflect its current state. Beware, though, -of the case where a connection was correctly brought up but is now -downed: Linux FreeS/WAN will not notice this until it attempts to -rekey. Meanwhile, the last known state indicates that the connection -has been established.

-

If your connection is stuck at STATE_MAIN_I1, skip straight to -here. - -

2.2 Finding error text

-

Solving most errors will require you to find verbose error text, -either on the command line or in the logs.

-

Verbose start for more information

-

-Note that you can get more detail from ipsec auto using -the --verbose flag:

-
    ipsec auto --verbose --up west-east

-More complete information can be gleaned from the log -files.

- -

Debug levels count

-

The amount of description you'll get here depends on ipsec.conf debug -settings, klipsdebug= and plutodebug=. -When troubleshooting, set at least one of these to all, and -when done, reset it to none so your logs don't fill up. -Note that you must have enabled the klipsdebug -compile-time option for the -klipsdebug configuration switch to work.

-

For negotiation problems plutodebug is most relevant. -klipsdebug applies mainly to attempts to use an -already-established connection. See also this -description of the division of duties within Linux FreeS/WAN.

-

After raising your debug levels, restart Linux FreeS/WAN to ensure -that ipsec.conf is reread, then recreate the error to generate -verbose logs. -

-

ipsec barf for lots of debugging information

-

-ipsec barf (8) -collects a bunch of useful debugging information, including these logs -Use the command

-
-    ipsec barf > barf.west
-
-

to generate one.

-

Find the error

-

Search out the failure point in your logs. - Are there a handful of lines which succinctly describe how -things are going wrong or contrary to your expectation? Sometimes the -failure point is not immediately obvious: Linux FreeS/WAN's errors -are usually not marked "Error". Have a look in the -FAQ -for what some common failures look like.

-

Tip: problems snowball. -Focus your efforts on the first problem, which is likely to be the -cause of later errors.

-

Play both sides

-

Also find error text on the peer IPSec box. -This gives you two perspectives on the same failure.

-

At times you will require information which only one side has. -The peer can merely indicate the presence of an error, and its -approximate point in the negotiations. If one side keeps retrying, -it may be because there is a show stopper on the other side. -Have a look at the other side and figure out what it doesn't like.

-

If the other end is not Linux FreeS/WAN, the principle is the -same: replicate the error with its most verbose logging on, and -capture the output to a file.

-

2.3 Interpreting a Negotiation Error

-

Connection stuck at STATE_MAIN_I1

-

This error commonly happens because IKE (port 500) packets, needed -to negotiate an IPSec connection, cannot travel freely between your IPSec -gateways. See our firewall document -for details.

-

Other errors

-

Other errors require a bit more digging. Use the following resources:

- -

If you have failed to solve your problem with the help of these -resources, send a detailed problem report to the users list, -following these guidelines.

-

3. Using a Connection

-

3.1 Orienting yourself

-

How do I know if it works?

-

Test your connection by sending packets through it. The simplest way -to do this is with ping, but the ping needs to test the correct -tunnel. See this example scenario if -you don't understand this.

-

If your ping returns, test any other connections you've brought -u all check out, great. You may wish to test -with large packets for MTU problems.

-

ipsec barf is useful again

-

If your ping fails to return, generate an ipsec barf debugging -report on each IPSec gateway. On a non-Linux FreeS/WAN -implementation, gather equivalent information. Use this, and the tips -in the next sections, to troubleshoot. Are you sure that both -endpoints are capable of hearing and responding to ping?

-

3.2 Those pesky configuration errors

-

IPSec may be dropping your ping packets since they do not belong in the -tunnels you have constructed:

- -

In either case, you will often see a message like:

-
klipsdebug... no eroute
-

which we discuss in this -FAQ.

-

Note:

- -

3.3 Check Routing and Firewalling

-

If you've confirmed your configuration assumptions, the problem is -almost certainly with routing or firewalling. Isolate the problem -using interface statistics, firewall statistics, or a packet sniffer.

-

Background:

- -

View Interface and Firewall -Statistics

-

Interface reports and firewall statistics can help you track down -lost packets at a glance. Check any firewall statistics you may be keeping -on your IPSec gateways, for dropped packets.

- -

Tip: You can take a snapshot of the packets processed -by your firewall with:

- -
    iptables -L -n -v
- -

You can get creative with "diff" to find out what happens to a -particular packet during transmission.

- -

Both cat /proc/net/dev and ifconfig display -interface statistics, and both are included in ipsec barf. Use -either to check if any interface has dropped packets. If you find -that one has, test whether this is related to your ping. While you -ping continuously, print that interface's statistics several times. -Does its drop count increase in proportion to the ping? If so, check -why the packets are dropped there.

- -

To do this, look at the firewall rules that apply to that interface. If the -interface is an IPSec interface, more information may be available in -the log. Grep for the word "drop" in a log which was -created with klipsdebug=all as the error happened.

-

See also this discussion on interpreting -ifconfig statistics.

-

3.4 When in doubt, sniff it out

-

If you have checked configuration assumptions, routing, and -firewall rules, and your interface statistics yield no clue, it -remains for you to investigate the mystery of the lost packet by the -most thorough method: with a packet sniffer (providing, of course, -that this is legal where you are working). -

In order to detect packets on the ipsec virtual interfaces, -you will need an up-to-date sniffer (tcpdump, ethereal, ksnuffle) on -your IPSec gateway machines. You may also find it useful to sniff the ping -endpoints.

-

Anticipate your packets' path

-

Ping, and examine each interface along the projected path, checking for your -ping's arrival. If it doesn't get to the the next stop, you have narrowed -down where to look for it. In this way, you can isolate a problem area, -and narrow your troubleshooting focus.

-

Within a machine running Linux FreeS/WAN, this -packet flow diagram will help you -anticipate a packet's path. -

Note that:

- -

Once you isolate where the packet is lost, take a closer look at -firewall rules, routing and configuration assumptions as they affect -that specific area. If the packet is lost on an IPSec gateway, comb -through klipsdebug output for anomalies. -

-

If the packet goes through both gateways successfully and reaches -the ping target, but does not return, suspect routing. Check that the -ping target routes packets back to the IPSec gateway.

-

3.5 Check your logs

-

Here, too, log information can be useful. Start with the -guidelines above.

-

For connection use problems, set klipsdebug=all. Note -that you must have enabled the klipsdebug -compile-time option to do this. -Restart Linux FreeS/WAN so that it rereads ipsec.conf, -then recreate the error condition. When searching through -klipsdebug data, look especially for the keywords -"drop" (as in dropped packets) and "error".

-

Often the problem with connection use is not software error, but -rather that the software is behaving contrary to expectation. -

-

Interpreting log text

-

To interpret the Linux FreeS/WAN log text you've found, use the -same resources as indicated for troubleshooting -connection negotiation: -the FAQ , our -background document, and the -list archives. -Looking in the KLIPS code is only for the very brave.

-

If you are still stuck, send a detailed -problem report to the users' list.

-

3.6 More testing for the truly thorough

-

Large Packets

-

If each of your connections passed the ping test, you may wish to -test by pinging with large packets (2000 bytes or larger). If it does -not return, suspect MTU issues, and see this discussion.

-

Stress Tests

-

In most users' view, a simple ping test, and perhaps a -large-packet ping test suffice to indicate a working IPSec -connection.

-

Some people might like to do additional stress tests prior to -production use. They may be interested in this testing -protocol we use at interoperation conferences, aka "bakeoffs". -We also have a testing directory that ships with the -release.

-

4. Problem Reporting

-

4.1 How to ask for help

-

Ask for troubleshooting help on the users' mailing list, -users@lists.freeswan.org. -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. -

- - -

When reporting problems to the mailing list(s), please include: -

- - -

Here are some good general guidelines on bug reporting: -How To Ask Questions -The Smart Way and How to Report -Bugs Effectively.

- - -

4.2 Where to ask

-

To report a problem, send mail about it to the users' list. If you -are certain that you have found a bug, report it to the bugs list. If -you encounter a problem while doing your own coding on the Linux -FreeS/WAN codebase and think it is of interest to the design team, -notify the design list. When in doubt, default to the users' list. -More information about the mailing lists is found here.

-

For a number of reasons -- including export-control regulations -affecting almost any private discussion of -encryption software -- we prefer that problem reports and discussions -go to the lists, not directly to the team. Beware that the list goes -worldwide; US citizens, read this important information about your -export laws. If you're using this -software, you really should be on the lists. To get onto them, visit -lists.freeswan.org.

-

If you do send private mail to our coders or want a private reply -from them, please make sure that the return address on your mail -(From or Reply-To header) is a valid one. They have more important -things to do than to unravel addresses that have been mangled in an -attempt to confuse spammers. -

-

5. Additional Notes on Troubleshooting

-

The following sections supplement the Guide: information -available on your system; testing between -security gateways; ifconfig reports for -KLIPS debugging; using GDB on Pluto.

-

5.1 Information available on your -system

-

Logs used

-

Linux FreeS/WAN logs to:

- -

Check both places to get full information. If you find nothing, -check your syslogd.conf(5) to see where your -/etc/syslog.conf or equivalent is directing authpriv -messages.

-

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

- -

Status information

-
-
ipsec auto --status -
- Command to get status report from running system. Displays Pluto's - state. Includes the list of connections which are currently "added" - to Pluto's internal database; lists state objects reflecting ISAKMP - and IPsec SAs being negotiated or installed. -
- ipsec look -
- Brief status info. -
- ipsec barf -
- Copious debugging info. -
-

-5.2 Testing between security gateways

-

Sometimes you need to test a subnet-subnet tunnel. This is a -tunnel between two security gateways, which protects traffic on -behalf of the subnets behind these gateways. On this network:

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

-you might name this tunnel sunset-sunrise. You can test this tunnel -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 traffic between the two protected subnets, not between the -gateways . Depending on the routing in place, a ping might

- -

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 unnecessary complications in your situation.

-

The trick is to explicitly test between both gateways' -private-side IP addresses. Since the private-side interfaces -are on the protected subnets, the resulting packets do go via the -tunnel. Use either ping -I or traceroute -i, both of which allow you -to specify a source interface. (Note: unsupported on older Linuxes). -The same principles apply for a road warrior (or other) case where -only one end of your tunnel is a subnet.

-

5.3 ifconfig reports for KLIPS debugging

-

When diagnosing problems using ifconfig statistics, you may wonder -what type of activity increments a particular counter for an ipsecN -device. Here's an index, posted by KLIPS developer Richard Guy -Briggs:

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

-5.4 Using GDB on Pluto

-

You may need to use the GNU debugger, gdb(1), on Pluto. This -should be necessary only in unusual 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.

-



-

- - diff --git a/doc/src/uml-rhroot-list.txt b/doc/src/uml-rhroot-list.txt deleted file mode 100644 index 198997032..000000000 --- a/doc/src/uml-rhroot-list.txt +++ /dev/null @@ -1,91 +0,0 @@ -filesystem-2.1.6-2 -glibc-common-2.2.4-13 -slang-1.4.4-4 -newt-0.50.33-1 -mktemp-1.5-11 -syslinux-1.52-2 -which-2.12-3 -zlib-devel-1.1.3-24 -ntsysv-1.2.24-1 -db1-devel-1.85-7 -e2fsprogs-1.23-2 -iputils-20001110-6 -mingetty-0.9.4-18 -pwdb-0.61.1-3 -bash-2.05-8 -bzip2-1.0.1-4 -libstdc++-2.96-98 -logrotate-3.5.9-1 -rootfiles-7.2-1 -bash-doc-2.05-8 -iproute-2.2.4-14 -ncurses-5.2-12 -diffutils-2.7.2-2 -findutils-4.1.7-1 -gzip-1.3-15 -readline-4.2-2 -tmpwatch-2.8-2 -cpio-2.4.2-23 -gawk-3.1.0-3 -less-358-21 -procps-X11-2.0.7-11 -sed-3.02-10 -vim-minimal-5.8-7 -fileutils-4.1-4 -sysklogd-1.4.1-4 -mount-2.11g-5 -rpm-4.0.3-1.03 -glib-devel-1.2.10-5 -bzip2-libs-1.0.1-4 -tar-1.13.19-6 -cracklib-dicts-2.7-12 -passwd-0.64.1-7 -pam-devel-0.75-14 -SysVinit-2.78-19 -krb5-libs-1.2.2-13 -pam_krb5-1.46-1 -krbafs-utils-1.0.9-2 -setup-2.5.7-1 -basesystem-7.0-2 -glibc-2.2.4-13 -popt-1.6.3-1.03 -setuptool-1.8-2 -shadow-utils-20000902-4 -zlib-1.1.3-24 -chkconfig-1.2.24-1 -db1-1.85-7 -db3-3.2.9-4 -file-3.35-2 -losetup-2.11g-5 -net-tools-1.60-3 -netconfig-0.8.11-7 -libtermcap-2.0.8-28 -libtermcap-devel-2.0.8-28 -bzip2-devel-1.0.1-4 -libstdc++-devel-2.96-98 -modutils-2.4.6-4 -crontabs-1.10-1 -MAKEDEV-3.2-5 -grep-2.4.2-7 -psmisc-20.1-2 -readline-devel-4.2-2 -e2fsprogs-devel-1.23-2 -ed-0.2-21 -vim-common-5.8-7 -procps-2.0.7-11 -redhat-release-7.2-1 -time-1.7-14 -cracklib-2.7-12 -console-tools-19990829-36 -textutils-2.0.14-2 -dev-3.2-5 -glib-1.2.10-5 -termcap-11.0.1-10 -info-4.0b-3 -words-2-17 -pam-0.75-14 -util-linux-2.11f-9 -sh-utils-2.0.11-5 -initscripts-6.40-1 -krbafs-1.0.9-2 -krbafs-devel-1.0.9-2 diff --git a/doc/src/uml-rhroot.html b/doc/src/uml-rhroot.html deleted file mode 100644 index ca05a2073..000000000 --- a/doc/src/uml-rhroot.html +++ /dev/null @@ -1,116 +0,0 @@ - - - - Building a RedHat root image - - - - - - -

Building a RedHat root image

- -

-The image required to use User-Mode-Linux is just a normal set of executables. -These can be extracted from a RedHat distribution using the following proceedure. -

- -

-There is a script in testing/utils called uml-rhroot.sh. It takes -two arguments: -

-

- -

The unpacked distribution will take approximately 133Mb. You will - want to locate this on the same partition as your intended root - trees for your User-Mode-Linux's as this will permit hard links to - be used, saving disk space. -

- -

- Because the RPM command used uses the chroot(2) system call and - needs to change ownership of the files that it creates, it must be - run as root. Afterward, you should chown the entire directory to the - userid that you will be using for testing (i.e. probably - yours). It should eventually suffices to make sure that you can read - every file. -

- -

-You should be able to chroot to this directory and run programs. If -you can not at least run ls, then there is a problem. -

-

-Expect a couple of errors about install-info. -

- -

-An example: -

-
-Script started on Thu Nov 22 15:51:15 2001
-cassidy:/c2/user-mode-linux# df
-Filesystem           1k-blocks      Used Available Use% Mounted on
-/dev/hda1              3844408   1673528   1975584  46% /
-/dev/hda3             12495048   1823404  10036884  16% /home
-/dev/hdc1             10325748    805056   8996172   9% /c1
-/dev/hdc2             10325780   4815160   4986100  50% /c2
-/dev/hdc3             10325780   2972480   6828780  31% /c3
-/dev/hdc4              7495084   3059640   4054704  44% /c4
-/distros/redhat/7.2/enigma-i386-disc1.iso
-                        662072    662072         0 100% /distros/redhat/7.2/disc1
-/distros/redhat/7.2/enigma-i386-disc2.iso
-                        653740    653740         0 100% /distros/redhat/7.2/disc2
-cassidy:/c2/user-mode-linux# /c2/freeswan/sandbox-main/testing/utils/uml-rhroot.sh 
-Usage: /c2/freeswan/sandbox-main/testing/utils/uml-rhroot.sh rootdir cdimagedir
-cassidy:/c2/user-mode-linux# /c2/freeswan/sandbox-main/testing/utils/uml-rhroot.sh /c2/user-mode-linux/rpm-root/root /distros/redhat/7.2
-Assuming RH disc1 at /distros/redhat/7.2/disc1/RedHat/RPMS
-        and disc2 at /distros/redhat/7.2/disc2/RedHat/RPMS
-/var/tmp/rpm-tmp.99149: /sbin/install-info: No such file or directory
-error: execution of %post scriptlet from textutils-2.0.14-2 failed, exit status 127
-cat: /proc/mounts: No such file or directory
-warning: /var/lib/rpm/Basenames created as /var/lib/rpm/Basenames.rpmnew
-warning: /var/lib/rpm/Conflictname created as /var/lib/rpm/Conflictname.rpmnew
-warning: /var/lib/rpm/Group created as /var/lib/rpm/Group.rpmnew
-warning: /var/lib/rpm/Name created as /var/lib/rpm/Name.rpmnew
-warning: /var/lib/rpm/Packages created as /var/lib/rpm/Packages.rpmnew
-warning: /var/lib/rpm/Providename created as /var/lib/rpm/Providename.rpmnew
-warning: /var/lib/rpm/Requirename created as /var/lib/rpm/Requirename.rpmnew
-warning: /var/lib/rpm/Triggername created as /var/lib/rpm/Triggername.rpmnew
-You should now chown it to yourself.
-cassidy:/c2/user-mode-linux# chown -R mcr rpm-root/root
-cassidy:/c2/user-mode-linux# ls rpm-root/root
-bin   dev  home    lib	opt   root  tmp  var
-boot  etc  initrd  mnt	proc  sbin  usr
-cassidy:/c2/user-mode-linux# chroot rpm-root/root
-cassidy:/# ls
-bin   dev  home    lib  opt   root  tmp  var
-boot  etc  initrd  mnt  proc  sbin  usr
-cassidy:/# exit
-cassidy:/c2/user-mode-linux# exit
-Script done on Thu Nov 22 15:54:33 2001
-
-
- - - - \ No newline at end of file diff --git a/doc/src/uml-stack-trace.html b/doc/src/uml-stack-trace.html deleted file mode 100644 index 1b08ed7d1..000000000 --- a/doc/src/uml-stack-trace.html +++ /dev/null @@ -1,129 +0,0 @@ -
-To: Michael Richardson 
-Cc: user-mode-linux-devel@lists.sourceforge.net
-From: Jeff Dike 
-Subject: [uml-devel] Re: stack trace
-Date: Mon, 16 Sep 2002 22:36:06 -0500
-
-mcr@sandelman.ottawa.on.ca said:
-> Can you post (on list or web site) a "script" output of you trying to
-> get the right stack out of a stuck uml (tracing myself)...? 
-
-Yup.  Here we go...
-
-Here, I attach to the tracing thread and get the stack of the current thread,
-which happens to be the idle thread.
-
-um 1013: gdb linux 14936
-GNU gdb 5.0rh-5 Red Hat Linux 7.1
-Copyright 2001 Free Software Foundation, Inc.
-GDB is free software, covered by the GNU General Public License, and you are
-welcome to change it and/or distribute copies of it under certain conditions.
-Type "show copying" to see the conditions.
-There is absolutely no warranty for GDB.  Type "show warranty" for details.
-This GDB was configured as "i386-redhat-linux"...
-/home/jdike/linux/2.4/um/14936: No such file or directory.
-Attaching to program: /home/jdike/linux/2.4/um/linux, process 14936
-0xa014efe9 in __wait4 ()
-
-# This is how you get the current task in the tracing thread - get_current()
-# only works in a kernel thread.
-(gdb) p (struct task_struct *)cpu_tasks[0].task
-$2 = (struct task_struct *) 0xa01c0000
-
-# Get the host pid of that task.
-(gdb) p $2.thread.extern_pid
-$3 = 14939
-
-# Get the current ip and sp.
-(gdb) shell cat /proc/14939/stat
-14939 (linux) T 14936 14936 883 34816 14936 64 5 3 806 7 62 12 0 0 9 0 0 2 
-588043 142770176 5008 4294967295 2684358656 2686348640 3221223520 2686205764
-                                                               sp ^^^^^^^^^^ 
-   2685727185 73728 201392128 167776768 268444672 3222308129 0 0 17 0
-ip ^^^^^^^^^^
-
-# the sp and ip are items 4 and 5 after the 4294967295 (on 2.2 hosts, that's
-2^31 - 1 rather than 2^32 - 1).
-
-(gdb) p/x 2686205764
-$4 = 0xa01c3f44
-(gdb) p/x 2685727185
-$5 = 0xa014f1d1
-
-# Where's the ip?
-(gdb) i sym 0xa014f1d1
-nanosleep + 17 in section .text
-
-# look at the stack around the sp
-(gdb) x/32x 0xa01c3f30
-0xa01c3f30 :     0x00000000      0x00000000      0xa01c3f60      0xa00020a8
-0xa01c3f40 :     0x00000004      0xa012e891      0xa01c3f58      0xa01c3f58
-0xa01c3f50 :     0xa01c3f70      0xa0023667      0x00000009      0x3b023380
-0xa01c3f60 :     0xa01c3fa0      0xa012a21d      0x0000000a      0xa01c0000
-0xa01c3f70 :     0xa01c3fa0      0xa012a213      0x00000003      0x00000024
-0xa01c3f80 :     0xa01c3fa0      0xa0011bc4      0xa012b25c      0x00000000
-0xa01c3f90 :     0xa01c3fb0      0x00000000      0xa01c3ffc      0x0000000d
-0xa01c3fa0 :     0xa01c3fb0      0xa000c50e      0xa01812e0      0xa01c3ffc
-
-# The trick here is to locate a frame near the current sp.  You're looking
-# for a consecutive pair of longwords (fp, ip) having the properties that:
-#	fp is on the current kernel stack and points further up it
-#	ip is a text address (if you can't recognize a UML text address by
-# sight, print out &_stext and &_etext)
-#
-# Starting at 0xa01c3f44, the first pair of works satisfying these requirements
-# is at 0xa01c3f50.
-# So, print that pair out as hex.
-(gdb) p/x *((int (*)[2])0xa01c3f50)
-$9 = {0xa01c3f70, 0xa0023667}
-
-# Now, we start climbing the stack.
-(gdb) p/x *((int (*)[2])$[0])
-$10 = {0xa01c3fa0, 0xa012a213}
-(gdb) 
-$11 = {0xa01c3fb0, 0xa000c50e}
-(gdb) 
-$12 = {0xa01c3fc0, 0xa000356d}
-(gdb) 
-$13 = {0xa01c3fd0, 0xa013082f}
-(gdb) 
-$14 = {0xa01c3ff0, 0xa012fbdd}
-# Stop when you see a NULL frame pointer or gdb bitches at you.
-(gdb) 
-$15 = {0x0, 0xa01513aa}
-
-# Now we get the symbolic version of the stack with 'i sym' of the second item
-# in each pair. 
-(gdb) i sym 0xa0023667
-check_pgt_cache + 23 in section .text
-(gdb) i sym 0xa012a213
-cpu_idle + 123 in section .text
-(gdb) i sym 0xa000c50e
-rest_init + 46 in section .text
-(gdb) i sym 0xa000356d
-start_kernel + 361 in section .text.init
-(gdb) i sym 0xa013082f
-start_kernel_proc + 63 in section .text
-(gdb) i sym 0xa012fbdd
-signal_tramp + 209 in section .text
-(gdb) i sym 0xa01513aa
-thread_start + 4 in section .text
-
-# You can also get line number information with 'i line'.
-(gdb) i line *0xa012a213
-Line 488 of "process_kern.c" starts at address 0xa012a213 
-   and ends at 0xa012a21d .
-(gdb) 
-
-
--------------------------------------------------------
-Sponsored by: AMD - Your access to the experts on Hammer Technology! 
-Open Source & Linux Developers, register now for the AMD Developer 
-Symposium. Code: EX8664 http://www.developwithamd.com/developerlab
-_______________________________________________
-User-mode-linux-devel mailing list
-User-mode-linux-devel@lists.sourceforge.net
-https://lists.sourceforge.net/lists/listinfo/user-mode-linux-devel
-
-
\ No newline at end of file diff --git a/doc/src/umltesting.html b/doc/src/umltesting.html deleted file mode 100644 index df62a9ae2..000000000 --- a/doc/src/umltesting.html +++ /dev/null @@ -1,478 +0,0 @@ - - -FreeS/WAN User-Mode-Linux testing guide - - - - - - - - -

User-Mode-Linux Testing guide

- -

-User mode linux is a way to compile a linux kernel such that it can run as a -process in another linux system (potentially as a *BSD or Windows process -later). See http://user-mode-linux.sourceforge.net/ -

- -

-UML is a good platform for testing and experimenting with FreeS/WAN. -It allows several network nodes to be simulated on a single machine. -Creating, configuring, installing, monitoring, and controling these -nodes is generally easier and easier to script with UML than real -hardware. -

- -

-You'll need about 500Mb of disk space for a full sunrise-east-west-sunset -setup. You can possibly get this down by 130Mb if you remove the -sunrise/sunset kernel build. If you just want to run, then you can even -remove the east/west kernel build. -

-

-Nothing need be done as super user. In a couple of steps, we note -where super user is required to install commands in system-wide -directories, but ~/bin could be used instead. UML seems to use a -system-wide /tmp/uml directory so different users may interfere with -one another. Later UMLs use ~/.uml instead, so multiple users running UML -tests should not be a problem, but note that a single user running -the UML tests will only be able run one set. Further, UMLs sometimes -get stuck and hang around. These "zombies" (most will actually be in -the "T" state in the process table) will interfere with subsequent tests. -

-

Preliminary Notes on BIND

- -

-As of 2003/3/1, the Light-Weight Resolver is used by pluto. This requires -that BIND9 be running. It also requires that BIND9 development libraries -be present in the build environment. The DNSSEC code is only truly functional -in BIND9 snapshots. The library code could be 9.2.2, we believe. We are -using BIND9 20021115 snapshot code from -ftp://ftp.isc.org/isc/bind9/snapshots. -

-

-FreeS/WAN may well require a newer BIND than is on your system. -Many distributions have moved to BIND9.2.2 recently due to a security advisory. -BIND is five components. -

-
    -
  1. -named -
    2. -
  2. -dnssec-* -
    3. -
  3. -client side resolver libraries -
    4. -
  4. -client side utility libraries -I thought there were lib and named parts to dnsssec... -
    5. -
  5. -dynamic DNS update utilities -
    6. -
-

-The only piece that we need for *building* is #4. That's the only part that has to be on the build host. -What is the difference between resolver and util libs? -If you want to edit testing/baseconfigs/all/etc/bind, you'll need a snapshot version. -The resolver library contains the resolver. -FreeS/WAN has its own copy of that in lib/liblwres. -

-

Steps to Install UML for FreeS/WAN

-
    -
  1. Get the following files: -
      -
    1. from http://www.sandelman.ottawa.on.ca/freeswan/uml/ -umlfreeroot-15.1.tar.gz (or highest numbered one). This is a - debian potato root file system. You can use this even on a Redhat - host, as it has the newer GLIBC2.2 libraries as well. - - - - - - -
    2. From ftp://ftp.xs4all.nl/pub/crypto/freeswan/ -a snapshot or release (1.92 or better) - -
    3. From a - http://www.kernel.org mirror, - the virgin 2.4.19 kernel. Please realize that we have defaults in our - tree for kernel configuration. We try to track the latest UML - kernels. If you use a newer kernel, you may have faults in the - kernel build process. You can see what the latest that is being regularly tested by visiting freeswan-regress-env.sh. - -
    4. - -Get - http://ftp.nl.linux.org/uml/ - uml-patch-2.4.19-47.bz2 or the one associated with your kernel. - As of 2003/03/05, uml-patch-2.4.19-47.bz2 works for us. -More recent versions of the patch have not been tested by us. -
    5. You'll probably want to visit -http://user-mode-linux.sourceforge.net -and get the UML utilities. These are not needed for the build or interactive use (but recommended). They are necessary for the regression testing procedures used by "make check". -We currently use uml_utilities_20020212.tar.bz2. -
    6. -You need tcpdump version 3.7.1 or better. -This is newer than the version included in most LINUX distributions. -You can check the version of an installed tcpdump with the --version flag. -If you need a newer tcpdump -fetch both tcpdump and libpcap source tar files from -http://www.tcpdump.org/ or a mirror. -
    - -
  2. Pick a suitable place, and extract the following files: -
      -
    1. - -2.4.19 kernel. For instance: -
      -
-           cd /c2/kernel
-           tar xzvf ../download/pub/linux/kernel/v2.4/linux-2.4.19.tar.gz
-
-
      - -
    2. extract the umlfreeroot file - -
      -
-           mkdir -p /c2/user-mode-linux/basic-root
-           cd /c2/user-mode-linux/basic-root
-           tar xzvf ../download/umlfreeroot-15.1.tar.gz
-
-
      - -
    3. FreeSWAN itself (or checkout "all" from CVS) -
      -
-           mkdir -p /c2/freeswan/sandbox
-           cd /c2/freeswan/sandbox
-           tar xzvf ../download/snapshot.tar.gz
-
-
      -
    - -
  3. If you need to build a newer tcpdump: -
      -
    • -Make sure you have OpenSSL installed -- it is needed for cryptographic routines. -
    • -Unpack libpcap and tcpdump source in parallel directories (the tcpdump -build procedures look for libpcap next door). -
    • -Change directory into the libpcap source directory and then build the library: -
      -
-	./configure
-	make
-
-
      -
    • -Change into the tcpdump source directory, build tcpdump, and install it. -
      -
-	./configure
-	make
-	# Need to be superuser to install in system directories.
-	# Installing in ~/bin would be an alternative.
-	su -c "make install"
-
-
      -
    -
  4. If you need the uml utilities, unpack them somewhere then build and install -them: -
    -
-	cd tools
-	make all
-	# Need to be superuser to install in system directories.
-	# Installing in ~/bin would be an alternative.
-	su -c "make install BIN_DIR=/usr/local/bin"
-
-
    -
  5. set up the configuration file -
      -
    • - -cd /c2/freeswan/sandbox/freeswan-1.97/testing/utils - -
    • copy umlsetup-sample.sh to ../../umlsetup.sh: - - cp umlsetup-sample.sh ../../umlsetup.sh - - -
    • open up ../../umlsetup.sh in your favorite editor. -
    • change POOLSPACE= to point to the place with at least 500Mb of -disk. Best if it is on the same partition as the "umlfreeroot" extraction, -as it will attempt to use hard links if possible to save disk space. - -
    • Set TESTINGROOT if you intend to run the script outside of the - sandbox/snapshot/release directory. Otherwise, it will configure itself. - -
    • KERNPOOL should point to the directory with your 2.4.19 kernel - tree. This tree should be unconfigured! This is the directory - you used in step 2a. - -
    • UMLPATCH should point at the bz2 file you downloaded at 1d. - If using a kernel that already includes the patch, set this to /dev/null. - -
    • FREESWANDIR should point at the directory where you unpacked - the snapshot/release. Include the "freeswan-snap2001sep16b" - or whatever in it. If you are running from CVS, then - you point at the directory where top, klips, etc. are. - The script will fix up the directory so that it can be - used. - -
    • BASICROOT should be set to the directory used in 2b, or to the directory - that you created with RPMs. - -
    • SHAREDIR should be set to the directory used in 2c, to /usr/share - for Debian potato users, or to $BASICROOT/usr/share. -
    - -
  6. 
-cd $TESTINGROOT/utils
-sh make-uml.sh
-
    - It will grind for awhile. If there are errors it will bail. - If so, run it under "script" and send the output to bugs@lists.freeswan.org. - -
  7. You will have a bunch of stuff under $POOLSPACE. - Open four xterms: - -
    
-    for i in sunrise sunset east west
-    do
-        xterm -name $i -title $i -e $POOLSPACE/$i/start.sh &
-    done
-
    - -
  8. Login as root. Password is "root" - (Note, these virtual machines are networked together, but are not - configured to talk to the rest of the world.) - -
  9. verify that pluto started on east/west, run "ipsec look" - -
  10. login to sunrise. run "ping sunset" - -
  11. login to west. run "tcpdump -p -i eth1 -n" - (tcpdump must be version 3.7.1 or newer) - -
  12. Closing a console xterm will shut down that UML. - -
  13. You can "make check", if you want to. -It is run from /c2/freeswan/sandbox/freeswan-1.97.
    14. - -
- -

Debugging the kernel with GDB

- -

-With User-Mode-Linux, you can debug the kernel using GDB. -See http://user-mode-linux.sourceforge.net/debugging.html. -

- -

-Typically, one will want to address a test case for a failing situation. -Running GDB from Emacs, or from other front ends is possible. First start GDB. -

-

-Tell it to open the UMLPOOL/swan/linux program. -

-

-Note the PID of GDB: -

-marajade-[projects/freeswan/mgmt/planning] mcr 1029 %ps ax | grep gdb
- 1659 pts/9    SN     0:00 /usr/bin/gdb -fullname -cd /mara4/freeswan/kernpatch/UMLPOOL/swan/ linux
-
-

- -

-Set the following in the environment: -

-UML_east_OPT="debug gdb-pid=1659"
-
-

- -

-Then start the user-mode-linux in the test scheme you wish: -

-marajade-[kernpatch/testing/klips/east-icmp-02] mcr 1220 %../../utils/runme.sh
-
- -The user-mode-linux will stop on boot, giving you a chance to attach to the process: - -
-(gdb) file linux
-Reading symbols from linux...done.
-(gdb) attach 1
-Attaching to program: /mara4/freeswan/kernpatch/UMLPOOL/swan/linux, process 1
-0xa0118bc1 in kill () at hostfs_kern.c:770
-
- -

-At this point, break points should be created as appropriate. -

- -

Other notes about debugging

- -

-If you are running a standard test, after all the packets are sent, the UML will -be shutdown. This can cause problems, because the UML may get terminated while you -are debugging. -

-

-The environment variable NETJIGWAITUSER can be set to "waituser". -If so, then the testing system will prompt before exiting the test. -

- -

User-Mode-Linux mysteries

- - - -

Getting more info from uml_netjig

- -

-uml_netjig can be compiled with a built-in tcpdump. This uses not-yet-released -code from www.tcpdump.org. -Please see the instructions in testing/utils/uml_netjig/Makefile. -

- - - diff --git a/doc/src/upgrading.html b/doc/src/upgrading.html deleted file mode 100644 index 0d6401b96..000000000 --- a/doc/src/upgrading.html +++ /dev/null @@ -1,260 +0,0 @@ - - - - Introduction to FreeS/WAN - - - - - -

Upgrading to FreeS/WAN 2.x

- - -

New! Built in Opportunistic connections

- -

Out of the box, FreeS/WAN 2.x will attempt to encrypt all your IP traffic. -It will try to establish IPsec connections for:

- -

FreeS/WAN 2.x uses hidden, automatically enabled - ipsec.conf connections to do this.

- -

This behaviour is part of our campaign to get Opportunistic -Encryption (OE) widespread in the Linux world, so that any two Linux boxes can -encrypt to one another without prearrangement. -There's one catch, however: you must set -up a few DNS records -to distribute RSA public keys and (if applicable) IPsec gateway -information.

- -

If you start FreeS/WAN before you have set up these DNS -records, your connectivity will be slow, and -messages relating to the built in connections will clutter your logs. -If you are unable to set up DNS for OE, you will wish to -disable the -hidden connections.

- - - -

Upgrading Opportunistic Encryption -to 2.01 (or later)

- -

As of FreeS/WAN 2.01, Opportunistic Encryption (OE) -uses DNS TXT resource records (RRs) only (rather than TXT with KEY). -This change causes a "flag day". -Users of FreeS/WAN 2.00 (or earlier) OE who are upgrading may -need to post additional resource records. -

- -

If you are running -initiate-only OE, -you must put up a TXT record in any forward domain as per our -quickstart instructions. This -replaces your old forward KEY. -

- -

-If you are running full OE, you require no updates. You already have -the needed TXT record in the reverse domain. -However, to facilitate future features, you -may also wish to publish that TXT record in a forward domain as -instructed here. -

- -

If you are running OE on a gateway (and encrypting on behalf of subnetted -boxes) you require no updates. -You already have the required TXT record in your gateway's reverse map, -and the TXT records for any subnetted boxes require no updating. -However, to facilitate future features, you may wish to publish your gateway's - TXT record in a forward domain as shown -here. - - -

-During the transition, you may wish to leave any old KEY records up for -some time. They will provide limited backward compatibility. - -

- -

New! Policy Groups

- -

We want to make it easy for you to declare security policy as it -applies to IPsec connections.

- -

Policy Groups make it simple to say: -

- - - -

FreeS/WAN then implements these policies, creating OE connections -if and when needed. -You can use Policy Groups along with connections you explicitly -define in ipsec.conf.

- -

For more information, see our -Policy Group HOWTO.

- - -

New! Packetdefault Connection

- -

Free/SWAN 2.x ships with the automatically enabled, hidden -connection packetdefault. This configures -a FreeS/WAN box as an OE gateway for any hosts located -behind it. As mentioned above, you must configure some -DNS records for -OE to work.

-

As the name implies, this connection functions as a default. If you -have more specific connections, such as policy groups which configure -your FreeS/WAN box as an OE gateway for a local subnet, these -will apply before packetdefault. You can view -packetdefault's specifics in -man ipsec.conf. -

- - -

FreeS/WAN now disables Reverse Path Filtering

- -

FreeS/WAN often doesn't work with reverse path filtering. At -start time, FreeS/WAN now turns rp_filter off, and logs a warning.

- -

FreeS/WAN does not turn it back on again. -You can do this yourself with a command like:

- -
   echo 1 > /proc/sys/net/ipv4/conf/eth0/rp_filter
- -

For eth0, substitute the interface which FreeS/WAN was affecting.

- - -

Revised ipsec.conf

- -

No promise of compatibility

- -

The FreeS/WAN team promised config-file compatibility throughout -the 1.x series. That means a 1.5 config file can be directly imported into -a fresh 1.99 install with no problems.

- -

With FreeS/WAN 2.x, we've given ourselves permission to make the config -file easier to use. The cost: some FreeS/WAN 1.x configurations will not -work properly. Many of the new features are, however, backward compatible.

- - -

Most ipsec.conf files will work fine

- -

... so long as you paste this line, with no preceding -whitespace, - at the top of your config file: -

- -
    version 2
- -

Backward compatibility patch

- -

If the new defaults bite you, use - -this ipsec.conf fragment to simulate the old default values.

- - -

Details

- -

-We've obsoleted various directives which almost no one was using: -

-
    dump
-    plutobackgroundload
-    no_eroute_pass
-    lifetime
-    rekeystart
-    rekeytries
- -

For most of these, there is some other way to elicit the desired behaviour. -See -this post. - -

-We've made some settings, which almost everyone was using, defaults. -For example: -

- -
    interfaces=%defaultroute
-    plutoload=%search
-    plutostart=%search
-    uniqueids=yes
- -

We've also changed some default values to help with OE and Policy Groups:

- -
    authby=rsasig   ## not secret!!!
-    leftrsasigkey=%dnsondemand ## looks up missing keys in DNS when needed.
-    rightrsasigkey=%dnsondemand
- -

-Of course, you can still override any defaults by explictly declaring something -else in your connection. -

- -

-A post with a list of many ipsec.conf changes.
-Current ipsec.conf manual. -

- - -

Upgrading from 1.x RPMs to 2.x RPMs

- -

Note: When upgrading from 1-series to 2-series RPMs, -rpm -U will not work.

- -

You must instead erase the 1.x RPMs, then install the 2.x set:

-
    rpm -e freeswan
-
    rpm -e freeswan-module
- -

On erasing, your old ipsec.conf should be moved to -ipsec.conf.rpmsave. -Keep this. You will probably want to copy your existing connections to the -end of your new 2.x file.

- -

Install the RPMs suitable for your kernel version, such as:

-
    rpm -ivh freeswan-module-2.04_2.4.20_20.9-0.i386.rpm
-
    rpm -ivh freeswan-userland-2.04_2.4.20_20.9-0.i386.rpm
- - - -

Or, to splice the files:

- -
    cat /etc/ipsec.conf /etc/ipsec.conf.rpmsave > /etc/ipsec.conf.tmp
-    mv /etc/ipsec.conf.tmp /etc/ipsec.conf
- -

Then, remove the redundant conn %default and -config setup -sections. Unless you have done any special configuring here, you'll likely -want to remove the 1.x versions. Remove conn OEself, if -present.

- - - - - diff --git a/doc/src/user_examples.html b/doc/src/user_examples.html deleted file mode 100755 index 5e3784858..000000000 --- a/doc/src/user_examples.html +++ /dev/null @@ -1,322 +0,0 @@ - - -FreeS/WAN examples - - - - - - - -

FreeS/WAN script examples

- -This file is intended to hold a collection of user-written example -scripts or configuration files for use with FreeS/WAN. -

-So far it has only one entry. - -

Poltorak's Firewall script

- -
-From: Poltorak Serguei <poltorak@dataforce.net>
-Subject: [Users] Using FreeS/WAN
-Date: Tue, 16 Oct 2001
-
-Hello.
-
-I'm using FreeS/WAN IPsec for half a year. I learned a lot of things about
-it and I think it would be interesting for someone to see the result of my
-experiments and usage of FreeS/WAN. If you find a mistake in this
-file, please e-mail me. And excuse me for my english... I'm learning.. :)
-
-I'll talk about vary simple configuration:
-
-addresses prefix = 192.168
-
-    lan1          sgw1     .0.0/24 (Internet)       sgw2            lan2
-  .1.0/24---[ .1.1 ; .0.1 ]===================[ .0.10 ; . 2.10 ]---.2.0/24
-
-
-We need to let lan1 see lan2 across Internet like it is behind sgw1. The
-same for lan2. And we need to do IPX bridge for Novel Clients and NDS
-synchronization.
-
-my config:
-------------------- ipsec.conf -------------------
-conn lan1-lan2
-        type=tunnel
-        compress=yes
-        #-------------------
-        left=192.168.0.1
-        leftsubnet=192.168.1.0/24
-        #-------------------
-        right=192.168.0.10
-        rightsubnet=192.168.2.0/24
-        #-------------------
-        auth=esp
-        authby=secret
---------------- end of ipsec.conf ----------------
-
-ping .2.x from .1.y   (y != 1)
-It works?? Fine. Let's continue...
-
-Why y != 1 ?? Because kernel of sgw1 have 2 IP addresses and it will choose
-the first IP (which is used to go to Internet) .0.1 and the packet won't go
-through IPsec tunnel :(  But if do ping on .1.1 kernel will respond from
-that address (.1.1) and the packet will be tunneled. The same problem occurred then
-.2.x sends a packet to .1.2 which is down at the moment. What happens? .1.1
-sends ARP requesting .1.2... after 3 tries it send to .2.x an destunreach,
-but from his "natural" IP or .0.1 . So the error message won't be delivered!
-It's a big problem...
-
-Resolution... One can manipulate with ipsec0 or ipsec0:0 to solve the
-problem (if ipsec0 has .1.1 kernel will send packets correctly), but there
-are powerful and elegant iproute2 :) We simply need to change source address
-of packet that goes to other secure lan. This is done with
-
-ip route replace 192.168.2.0/24 via 192.168.0.10 dev ipsec0 src 192.168.1.1
-
-Cool!! Now it works!!
-
-The second step. We want install firewall on sgw1 and sgw2. Encryption of 
-traffic without security isn't a good idea. I don't use {left|right}firewall, 
-because I'm running firewall from init scripts.
-
-We want IPsec data between lan1-lan2, some ICMP errors (destination
-unreachable, TTL exceeded, parameter problem and source quench), replying on 
-pings from both lans and Internet, ipxtunnel data for IPX and of course SSH
-between sgw1 and sgw2 and from/to one specified host.
-
-I'm using ipchains. With iptables there are some changes.
-
----------------- rc.firewall ---------------------
-#!/bin/sh
-#
-# Firewall for IPsec lan1-lan2
-#
-
-IPC=/sbin/ipchains
-ANY=0.0.0.0/0
-
-# left
-SGW1_EXT=192.168.0.1
-SGW1_INT=192.168.1.1
-LAN1=192.168.1.0/24
-
-# right
-SGW2_EXT=192.168.0.10
-SGW2_INT=192.168.2.10
-LAN2=192.168.2.0/24
-
-# SSH from and to this host
-SSH_PEER_HOST=_SOME_HOST_
-
-# this is for left. exchange these values for right.
-MY_EXT=$SGW1_EXT
-MY_INT=$SGW1_INT
-PEER_EXT=$SGW2_EXT
-PEER_INT=$SGW2_INT
-INT_IF=eth1
-EXT_IF=eth0
-IPSEC_IF=ipsec0
-MY_LAN=$LAN1
-PEER_LAN=$LAN2
-
-$IPC -F
-$IPC -P input DENY
-$IPC -P forward DENY
-$IPC -P output DENY
-
-# Loopback traffic
-$IPC -A input -i lo -j ACCEPT
-$IPC -A output -i lo -j ACCEPT
-
-# for IPsec SGW1-SGW2
-## IKE
-$IPC -A input -p udp -s $PEER_EXT 500 -d $MY_EXT 500 -i $EXT_IF -j ACCEPT
-$IPC -A output -p udp -s $MY_EXT 500 -d $PEER_EXT 500 -i $EXT_IF -j ACCEPT
-## ESP
-$IPC -A input -p 50 -s $PEER_EXT -d $MY_EXT -i $EXT_IF -j ACCEPT
-### we don't need this line ### $IPC -A output -p 50 -s $MY_EXT -d $PEER_EXT -i $EXT_IF -j ACCEPT
-## forward LAN1-LAN2
-$IPC -A forward -s $MY_LAN -d $PEER_LAN -i $IPSEC_IF -j ACCEPT
-$IPC -A forward -s $PEER_LAN -d $MY_LAN -i $INT_IF -j ACCEPT
-$IPC -A output -s $PEER_LAN -d $MY_LAN -i $INT_IF -j ACCEPT
-$IPC -A input -s $PEER_LAN -d $MY_LAN -i $IPSEC_IF -j ACCEPT
-$IPC -A input -s $MY_LAN -d $PEER_LAN -i $INT_IF -j ACCEPT
-$IPC -A output -s $MY_LAN -d $PEER_LAN -i $IPSEC_IF -j ACCEPT
-
-# ICMP
-#
-## Dest unreachable
-### from/to Internet
-$IPC -A input -p icmp --icmp-type destination-unreachable -s $ANY -d $MY_EXT -i $EXT_IF -j ACCEPT
-$IPC -A output -p icmp --icmp-type destination-unreachable -s $MY_EXT -d $ANY -i $EXT_IF -j ACCEPT
-### from/to Lan
-$IPC -A input -p icmp --icmp-type destination-unreachable -s $ANY -d $MY_INT -i $INT_IF -j ACCEPT
-$IPC -A output -p icmp --icmp-type destination-unreachable -s $MY_INT -d $ANY -i $INT_IF -j ACCEPT
-### from/to Peer Lan
-$IPC -A input -p icmp --icmp-type destination-unreachable -s $ANY -d $MY_INT -i $IPSEC_IF -j ACCEPT
-$IPC -A output -p icmp --icmp-type destination-unreachable -s $MY_INT -d $ANY -i $IPSEC_IF -j ACCEPT
-#
-## Source quench
-### from/to Internet
-$IPC -A input -p icmp --icmp-type source-quench -s $ANY -d $MY_EXT -i $EXT_IF -j ACCEPT
-$IPC -A output -p icmp --icmp-type source-quench -s $MY_EXT -d $ANY -i $EXT_IF -j ACCEPT
-### from/to Lan
-$IPC -A input -p icmp --icmp-type source-quench -s $ANY -d $MY_INT -i $INT_IF -j ACCEPT
-$IPC -A output -p icmp --icmp-type source-quench -s $MY_INT -d $ANY -i $INT_IF -j ACCEPT
-### from/to Peer Lan
-$IPC -A input -p icmp --icmp-type source-quench -s $ANY -d $MY_INT -i $IPSEC_IF -j ACCEPT
-$IPC -A output -p icmp --icmp-type source-quench -s $MY_INT -d $ANY -i $IPSEC_IF -j ACCEPT
-#
-## Parameter problem
-### from/to Internet
-$IPC -A input -p icmp --icmp-type parameter-problem -s $ANY -d $MY_EXT -i $EXT_IF -j ACCEPT
-$IPC -A output -p icmp --icmp-type parameter-problem -s $MY_EXT -d $ANY -i $EXT_IF -j ACCEPT
-### from/to Lan
-$IPC -A input -p icmp --icmp-type parameter-problem -s $ANY -d $MY_INT -i $INT_IF -j ACCEPT
-$IPC -A output -p icmp --icmp-type parameter-problem -s $MY_INT -d $ANY -i $INT_IF -j ACCEPT
-### from/to Peer Lan
-$IPC -A input -p icmp --icmp-type parameter-problem -s $ANY -d $MY_INT -i $IPSEC_IF -j ACCEPT
-$IPC -A output -p icmp --icmp-type parameter-problem -s $MY_INT -d $ANY -i $IPSEC_IF -j ACCEPT
-#
-## Time To Live exceeded
-### from/to Internet
-$IPC -A input -p icmp --icmp-type time-exceeded -s $ANY -d $MY_EXT -i $EXT_IF -j ACCEPT
-$IPC -A output -p icmp --icmp-type time-exceeded -s $MY_EXT -d $ANY -i $EXT_IF -j ACCEPT
-### to Lan
-$IPC -A input -p icmp --icmp-type time-exceeded -s $ANY -d $MY_INT -i $INT_IF -j ACCEPT
-$IPC -A output -p icmp --icmp-type time-exceeded -s $MY_INT -d $ANY -i $INT_IF -j ACCEPT
-### to Peer Lan
-$IPC -A input -p icmp --icmp-type time-exceeded -s $ANY -d $MY_INT -i $IPSEC_IF -j ACCEPT
-$IPC -A output -p icmp --icmp-type time-exceeded -s $MY_INT -d $ANY -i $IPSEC_IF -j ACCEPT
-
-# ICMP PINGs
-## from Internet
-$IPC -A input -p icmp -s $ANY -d $MY_EXT --icmp-type echo-request  -i $EXT_IF -j ACCEPT
-$IPC -A output -p icmp -s $MY_EXT -d $ANY --icmp-type echo-reply  -i $EXT_IF -j ACCEPT
-## from LAN
-$IPC -A input -p icmp -s $ANY -d $MY_INT --icmp-type echo-request -i $INT_IF -j ACCEPT
-$IPC -A output -p icmp -s $MY_INT -d $ANY --icmp-type echo-reply  -i $INT_IF -j ACCEPT
-## from Peer LAN
-$IPC -A input -p icmp -s $ANY -d $MY_INT --icmp-type echo-request -i $IPSEC_IF -j ACCEPT
-$IPC -A output -p icmp -s $MY_INT -d $ANY --icmp-type echo-reply  -i $IPSEC_IF -j ACCEPT
-
-# SSH
-## from SSH_PEER_HOST
-$IPC -A input -p tcp -s $SSH_PEER_HOST -d $MY_EXT 22 -i $EXT_IF -j ACCEPT
-$IPC -A output -p tcp \! -y -s $MY_EXT 22 -d $SSH_PEER_HOST -i $EXT_IF -j ACCEPT
-## to SSH_PEER_HOST
-$IPC -A input -p tcp \! -y -s $SSH_PEER_HOST 22 -d $MY_EXT -i $EXT_IF -j ACCEPT
-$IPC -A output -p tcp -s $MY_EXT -d $SSH_PEER_HOST 22 -i $EXT_IF -j ACCEPT
-## from PEER
-$IPC -A input -p tcp -s $PEER_EXT -d $MY_EXT 22 -i $EXT_IF -j ACCEPT
-$IPC -A output -p tcp \! -y -s $MY_EXT 22 -d $PEER_EXT -i $EXT_IF -j ACCEPT
-## to PEER
-$IPC -A input -p tcp \! -y -s $PEER_EXT 22 -d $MY_EXT -i $EXT_IF -j ACCEPT
-$IPC -A output -p tcp -s $MY_EXT -d $PEER_EXT 22 -i $EXT_IF -j ACCEPT
-
-# ipxtunnel
-$IPC -A input -p udp -s $PEER_INT 2005 -d $MY_INT 2005 -i $IPSEC_IF -j ACCEPT
-$IPC -A output -p udp -s $MY_INT 2005 -d $PEER_INT 2005 -i $IPSEC_IF -j ACCEPT
-
----------------- end of rc.firewall ----------------------
-
-To understand this we need to look on this scheme:
-
-           ++-----------------------<----------------------------+
-           || ipsec0                                             |
-           \/                                                    |
- eth0  +--------+    /---------/ yes  /---------/ yes +-----------------------+
------->| INPUT  |-->/ ?local? /----->/ ?IPsec? /----->| decrypt & decapsulate |
- eth1  +--------+  /---------/      /---------/       +-----------------------+
-                       || no            || no
-                       \/               \/
-                  +----------+      +---------+        +-------+
-                  | routing  |      |  local  |        | local |
-                  | decision |      | deliver |        | send  |
-                  +----------+      +---------+        +-------+
-                       ||                                 ||
-                       \/                                 \/
-                   +---------+                       +----------+
-                   | forward |                       | routing  |
-                   +---------+                       | decision |
-                       ||                            +----------+
-                       ||                                  ||
-                       ++----------------<-----------------++
-                       ||
-                       \/
-                   +--------+ eth0
-                   | OUTPUT | eth1
-                   +--------+ ipsec0
-                       ||
-                       \/
-                   /---------/ yes +-----------------------+
-                  / ?IPsec? /----->| encrypt & encapsulate |
-                 /---------/       +-----------------------+
-                      || no                    ||
-                      ||                       ||
-                      ||                       \/   eth0, eth1
-                      ++-----------------------++-------------->
-
-This explain how a packet traverse TCP/IP stack in IPsec capable kernel.
-
-FIX ME, please, if there are any errors
-
-Test the new firewall now.
-
-
-Now about IPX. I tried 3 programs for tunneling IPX: tipxd, SIB and ipxtunnel
-
-tipxd didn't send packets.. :(
-SIB and ipxtunnel worked fine :)
-With ipxtunnel there was a little problem. In sources there are an error.
-
---------------------- in main.c ------------------------
-<       bytes += p.len;
----
->       bytes += len;
---------------------------------------------------------
-
-After this FIX everything goes right...
-
-------------------- /etc/ipxtunnel.conf ----------------
-port    2005
-remote  192.168.101.97    2005
-interface eth1
---------------- end of /etc/ipxtunnel.conf -------------
-
-I use IPX tunnel between .1.1 and .2.10 so we don't need to encrypt nor
-authenticate encapsulated IPX packets, it is done with IPsec.
-
-If you don't wont to use iproute2 to change source IP you need to use SIB
-(it is able to bind local address) or establish tunnel between .0.1 and
-.0.10 (external IPs, you need to do encryption in the program, but it isn't
-strong).
-
-For now I'm using ipxtunnel.
-
-I think that's all for the moment. If there are any error, please e-mail me: 
-poltorak@df.ru . It would be cool if someone puts the scheme of TCP/IP in
-kernel and firewall example on FreeS/WAN's manual pages.
-
-PoltoS
-
- - - \ No newline at end of file diff --git a/doc/src/web.html b/doc/src/web.html deleted file mode 100644 index 19df6ffa6..000000000 --- a/doc/src/web.html +++ /dev/null @@ -1,905 +0,0 @@ - - - - - FreeS/WAN web links - - - - - -

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 have been integrated into the FreeS/WAN -distribution. For a variety of reasons, those listed below have not.

- -

Note that not all patches are a good idea.

- - -

This is not to say that patches are necessarily bad, only that using them -requires some deliberation. For example, there might be perfectly good -reasons to add a specific cipher in your application: perhaps GOST to comply -with government standards in Eastern Europe, or AES for performance -benefits.

- -

Current patches

- -

Patches believed current::

- - -

There is also one add-on that takes the form of a modified FreeS/WAN -distribution, rather than just patches to the standard distribution:

- - -

Before using any of the above,, check the mailing -lists for news of newer versions and to see whether they have been -incorporated into more recent versions of FreeS/WAN.

- -

Older patches

- - -

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:

- - -

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

- - -

Other approaches to VPNs for Linux

- - -

There is a list of Linux -VPN software in the Linux Security -Knowledge Base.

- -

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

- -

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

- - -

IPsec in router products

- -

All the major router vendors support IPsec, at least in some models.

- - -

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:

- - -

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:

- - -

IPsec on network cards

- -

Network cards with built-in IPsec acceleration are available from at least -Intel, 3Com and Redcreek.

- -

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:

- - -

IPsec for BSD Unix

- - -

IPsec for other systems

- - -

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:

- - -

Interoperability test sites

- - -

Linux links

- -

Basic and tutorial Linux information

- - -

General Linux sites

- - -

Documentation

- -

Nearly any Linux documentation you are likely to want can be found at the -Linux Documentation Project or -LDP.

- - -

You may not need to go to the LDP to get this material. Most Linux -distributions include the HowTos on their CDs and several include the Guides -as well. Also, most of the Guides and some collections of HowTos are -available in book form from various publishers.

- -

Much of the LDP material is also available in languages other than -English. See this LDP -page.

- -

Advanced routing

- -

The Linux IP stack has some new features in 2.4 kernels. Some HowTos have -been written:

- - -

Security for Linux

- -

See also the LDP material above.

- - -

Linux firewalls

- -

Our FreeS/WAN and firewalls document includes -links to several sets of scripts known -to work with FreeS/WAN.

- -

Other information sources:

- - -

Miscellaneous Linux information

- - -

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

- - -

Tutorials

- - -

See also the interesting papers section -below.

- -

Crypto and security standards

- - -

Crypto quotes

- -

There are several collections of cryptographic quotes on the net:

- - -

Cryptography law and policy

- -

Surveys of crypto law

- - -

Organisations opposing crypto restrictions

- - -

Other information on crypto policy

- - -

See also our documentation section on the history -and politics of cryptography.

- -

Cryptography technical information

- -

Collections of crypto links

- - -

Lists of online cryptography papers

- - -

Particularly interesting papers

- -

These papers emphasize important issues around the use of cryptography, -and the design and management of secure systems.

- - -

Computer and network security

- -

Security links

- - -

Firewall links

- - -

VPN links

- - -

Security tools

- - -

Links to home pages

- -

David Wagner at Berkeley provides a set of links to home pages of -cryptographers, cypherpunks and computer security people.

- - diff --git a/doc/testing.html b/doc/testing.html deleted file mode 100644 index 77626ba5d..000000000 --- a/doc/testing.html +++ /dev/null @@ -1,332 +0,0 @@ - - - -Introduction to FreeS/WAN - - - - -Contents -Previous -Next -
-

Testing FreeS/WAN

- This document discusses testing FreeS/WAN. -

Not all types of testing are described here. Other parts of the - documentation describe some tests:

-
-
installation document
-
testing for a successful install
-
configuration document
-
basic tests for a working configuration
-
web links document
-
General information on tests for interoperability between various - IPsec implementations. This includes links to several test sites.
-
interoperation document.
-
More specific information on FreeS/WAN interoperation with other - implementations.
-
performance document
-
performance measurements
-
-

The test setups and procedures described here can also be used in - other testing, but this document focuses on testing the IPsec - functionality of FreeS/WAN.

-

Testing opportunistic connections

-

This section teaches you how to test your opportunistically encrypted - (OE) connections. To set up OE, please see the easy instructions in our quickstart guide.

-

Basic OE Test

-

This test is for basic OE functionality. - - For additional tests, keep - reading.

-

Be sure IPsec is running. You can see whether it is with:

-
    ipsec setup status
-

If need be, you can restart it with:

-
    service ipsec restart
-

Load a FreeS/WAN test website from the host on which you're running - FreeS/WAN. Note: the feds may be watching these sites. Type one of:

-

-
   links oetest.freeswan.org
-
   links oetest.freeswan.nl
- - -

A positive result looks like this:

-
-   You  seem  to  be  connecting  from:  192.0.2.11 which DNS says is:
-   gateway.example.com
-     _________________________________________________________________
-                                                                                
-   Status E-route
-   OE    enabled    16    192.139.46.73/32    ->    192.0.2.11/32   =>
-   tun0x2097@192.0.2.11
-   OE    enabled    176    192.139.46.77/32    ->   192.0.2.11/32   =>
-   tun0x208a@192.0.2.11
-
-

If you see this, congratulations! Your OE box will now encrypt its - own traffic whenever it can. If you have difficulty, see our - OE troubleshooting tips.

-

OE Gateway Test

-

If you've set up FreeS/WAN to protect a subnet behind your gateway, - you'll need to run another simple test, which can be done from a - machine running any OS. That's right, your Windows box can be protected - by opportunistic encryption without any FreeS/WAN install or - configuration on that box. From each protected subnet node -, load the FreeS/WAN website with:

-
   links oetest.freeswan.org
-
   links oetest.freeswan.nl
-

A positive result looks like this:

-
-   You  seem  to  be  connecting  from:  192.0.2.98 which DNS says is:
-   box98.example.com
-     _________________________________________________________________
-                                                                                
-   Status E-route
-   OE    enabled    16    192.139.46.73/32    ->    192.0.2.98/32   =>
-   tun0x134ed@192.0.2.11
-   OE    enabled    176    192.139.46.77/32    ->   192.0.2.11/32   =>
-   tun0x134d2@192.0.2.11
-
-

If you see this, congratulations! Your OE gateway will now encrypt - traffic for this subnet node whenever it can. If you have difficulty, - see our OE troubleshooting tips -.

-

Additional OE tests

-

When testing OE, you will often find it useful to execute this - command on the FreeS/WAN host:

-
   ipsec eroute
-

If you have established a connection (either for or for a subnet - node) you will see a result like:

-
    192.0.2.11/32   -> 192.139.46.73/32  => tun0x149f@192.139.46.38
-
-

Key:

- - - - - -
1.192.0.2.11/32Local start point of the - protected traffic.
2.192.0.2.194/32Remote end point of the - protected traffic.
3.192.0.48.38Remote FreeS/WAN node (gateway or - host). May be the same as (2).
4.[not shown]Local FreeS/WAN node (gateway or - host), where you've produced the output. May be the same as (1).
-

For extra assurance, you may wish to use a packet sniffer such as - tcpdump to verify that packets are being encrypted. You should see - output that indicates ESP encrypted data, for example:

-
    02:17:47.353750 PPPoE  [ses 0x1e12] IP 154: xy.example.com > oetest.freeswan.org: ESP(spi=0x87150d16,seq=0x55)
-

Testing with User Mode Linux

-

User Mode Linux - allows you to run Linux as a user process on another Linux machine.

-

As of 1.92, the distribution has a new directory named testing. It - contains a collection of test scripts and sample configurations. Using - these, you can bring up several copies of Linux in user mode and have - them build tunnels to each other. This lets you do some testing of a - FreeS/WAN configuration on a single machine.

-

You need a moderately well-endowed machine for this to work well. - Each UML wants about 16 megs of memory by default, which is plenty for - FreeS/WAN usage. Typical regression testing only occasionally uses as - many as 4 UMLs. If one is doing nothing else with the machine (in - particular, not running X on it), then 128 megs and a 500MHz CPU are - fine.

- Documentation on these scripts is here. - There is also documentation on automated testing - here. -

Configuration for a testbed network

-

A common test setup is to put a machine with dual Ethernet cards in - between two gateways under test. You need at least five machines; two - gateways, two clients and a testing machine in the middle.

-

The central machine both routes packets and provides a place to run - diagnostic software for checking IPsec packets. See next section for - discussion of using tcpdump(8) for - this.

-

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.

-

What you end up with looks like:

-

Testbed 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
-
Where p and q are 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.

-

Using packet sniffers in testing

-

A number of tools are available for looking at packets. We will - discuss using tcpdump(8), a - common Linux tool included in most distributions. Alternatives - offerring more-or-less the same functionality include:

-
-
Ethereal
-
Several people on our mailing list report a preference for this over - tcpdump.
-
windump
-
a Windows version of tcpdump(8), possibly handy if you have Windows - boxes in your network
-
-Sniffit
-
A linux sniffer that we don't know much about. If you use it, please - comment on our mailing list.
-
-

See also this - index of packet sniffers.

-

tcpdump(8) may 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.

-

At one point, the problem was quite severe. Recent versions of - tcpdump, however, understand IPsec well enough to be usable on a - gateway. You can get the latest version from - tcpdump.org.

-

Even with a recent tcpdump, some care is required. Here is part of a - post from Henry on the topic:

-
> a) data from sunset to sunrise or the other way is not being
-> encrypted (I am using tcpdump (ver. 3.4) -x/ping -p to check
-> packages) 
-
-What *interface* is tcpdump being applied to?  Use the -i option to
-control this.  It matters!  If tcpdump is looking at the ipsecN
-interfaces, e.g. ipsec0, then it is seeing the packets before they are
-encrypted or after they are decrypted, so of course they don't look
-encrypted.  You want to have tcpdump looking at the actual hardware
-interfaces, e.g. eth0. 
-
-Actually, the only way to be *sure* what you are sending on the wire is to
-have a separate machine eavesdropping on the traffic.  Nothing you can do
-on the machines actually running IPsec is 100% guaranteed reliable in this
-area (although tcpdump is a lot better now than it used to be).
-

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. Network configuration for - such testing is discussed above.

-

Here's another mailing list message with advice on using tcpdump(8):

-
Subject: RE: [Users] Encrypted???
-   Date: Thu, 29 Nov 2001
-   From: "Joe Patterson" <jpatterson@asgardgroup.com>
-
-tcpdump -nl -i $EXT-IF proto 50
-
--nl tells it not to buffer output or resolve names (if you don't do that it
-may confuse you by not outputing anything for a while), -i $EXT-IF (replace
-with your external interface) tells it what interface to listen on, and
-proto 50 is ESP.  Use "proto 51" if for some odd reason you're using AH, and
-"udp port 500" if you want to see the isakmp key exchange/tunnel setup
-packets.
-
-You can also run `tcpdump -nl -i ipsec0` to see what traffic is on that
-virtual interface.  Anything you see there *should* be either encrypted or
-dropped (unless you've turned on some strange options in your ipsec.conf
-file)
-
-Another very handy thing is ethereal (http://www.ethereal.com/) which runs
-on just about anything, has a nice gui interface (or a nice text-based
-interface), and does a great job of protocol  breakdown.  For ESP and AH
-it'll basically just tell you that there's a packet of that protocol, and
-what the spi is, but for isakmp it'll actually show you a lot of the tunnel
-setup information (until it gets to the point in the protocol where isakmp
-is encrypted....)
-

Verifying encryption

-

The question of how to verify that messages are actually encrypted - has been extensively discussed on the mailing list. See this - thread.

-

If you just want to verify that packets are encrypted, look at them - with a packet sniffer (see previous section -) located between the gateways. The packets should, except for some of - the header information, be utterly unintelligible. The output - of good encryption looks exactly like random noise.

-

A packet sniffer can only tell you that the data you looked at was - encrypted. If you have stronger requirements -- for example if your - security policy requires verification that plaintext is not leaked - during startup or under various anomolous conditions -- then you will - need to devise much more thorough tests. If you do that, please post - any results or methodological details which your security policy allows - you to make public.

-

You can put recognizable data into 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 other protocols, you may 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.

-

One thing to watch for: the output of good compression, like that of - good encryption, looks just like random noise. You cannot tell just by - looking at a data stream whether it has been compressed, encrypted, or - both. You need a little care not to mistake compressed data for - encrypted data in your testing.

-

Note also that weak encryption also produces random-looking output. - You cannot tell whether the encryption is strong by looking at the - output. To be sure of that, you would need to have both the algorithms - and the implementation examined by experts.

-

For IPsec, you can get partial assurance from interoperability tests. - See our interop document. When twenty - products all claim to implement 3DES, - and they all talk to each other, you can be fairly sure they have it - right. Of course, you might wonder whether all the implementers are - consipring to trick you or, more plausibly, whether some - implementations might have "back doors" so they can get also it wrong - when required.. If you're seriously worried about things like that, you - need to get the code you use audited (good luck if it is not Open - Source), or perhaps to talk to a psychiatrist about treatments for - paranoia.

-

Mailing list pointers

-

Additional information on testing can be found in these - mailing list messages:

- -
-Contents -Previous -Next - - diff --git a/doc/toc.html b/doc/toc.html deleted file mode 100644 index 047833020..000000000 --- a/doc/toc.html +++ /dev/null @@ -1,1019 +0,0 @@ - - - -Introduction to FreeS/WAN - - - - -

Table of Contents

-
-
Introduction - -Upgrading to FreeS/WAN 2.x - -Quickstart Guide to - Opportunistic Encryption - -How to Configure Linux FreeS/WAN with - Policy Groups - -FreeS/WAN FAQ - -FreeS/WAN manual pages - -FreeS/WAN and firewalls - -Linux FreeS/WAN Troubleshooting Guide - - -Linux FreeS/WAN Compatibility Guide - -Interoperating with FreeS/WAN - -Performance of FreeS/WAN - -Testing FreeS/WAN - -Kernel configuration for FreeS/WAN - - -Other configuration - possibilities - -Installing FreeS/WAN - -How to configure FreeS/WAN - -Linux FreeS/WAN background - -FreeS/WAN script examples - - -How to configure to use "make - check" - -How to write a "make check" test - -Current pitfalls -
-
User-Mode-Linux Testing - guide - -Debugging the kernel with GDB - -User-Mode-Linux mysteries -
-
Getting more info from uml_netjig - -
-
History and politics of - cryptography - -The IPsec protocols - -Mailing lists and newsgroups - -Web links - -Glossary for the Linux FreeS/WAN - project - -Bibliography for the Linux FreeS/WAN - project -
-
IPsec RFCs and related documents - -Distribution Roadmap: What's Where in - Linux FreeS/WAN - -User-Mode-Linux Testing guide - - -Debugging the kernel with GDB - -User-Mode-Linux mysteries -
-
Getting more info from uml_netjig - -
-
How to configure to use "make - check" - -How to write a "make check" test - -Current pitfalls -
-
Nightly regression testing -
-
How to setup the nightly - build - - - diff --git a/doc/trouble.html b/doc/trouble.html deleted file mode 100644 index 2123f3805..000000000 --- a/doc/trouble.html +++ /dev/null @@ -1,706 +0,0 @@ - - - -Introduction to FreeS/WAN - - - - -Contents -Previous -Next -
-

Linux FreeS/WAN Troubleshooting Guide

-

Overview

-

This document covers several general places where you might have a - problem:

-
    -
  1. During install.
    2. -
  2. During the negotiation process.
    3. -
  3. Using an established connection.
    4. -
-

This document also contains notes which expand - on points made in these sections, and tips for - problem reporting. If the other end of your connection is not - FreeS/WAN, you'll also want to read our - interoperation document.

-

1. During Install

-

1.1 RPM install gotchas

-

With the RPM method:

- -

1.2 Problems installing from source

-

When installing from source, you may find these problems:

- -

1.3 Install checks

-

ipsec verify checks a number of FreeS/WAN essentials. Here - are some hints on what do to when your system doesn't check out:

-

- - - - - - - - - - -
ProblemStatus -Action
ipsec not on-path  -

Add /usr/local/sbin to your PATH.

-
Missing KLIPS supportcritical -See this FAQ.
No RSA private key  -

Follow these instructions to - create an RSA key pair for your host. RSA keys are:

-
    -
  • required for opportunistic encryption, and
    • -
  • our preferred method to authenticate pre-configured connections.
    • -
-
pluto not running -critical -
service ipsec start
-
No port 500 holecritical -Open port 500 for IKE negotiation.
Port 500 check N/A Check that port 500 is open - for IKE negotiation.
Failed DNS checks Opportunistic encryption - requires information from DNS. To set this up, see - our instructions.
No public IP address Check that the interface - which you want to protect with IPSec is up and running.
-

1.3 Troubleshooting OE

-

OE should work with no local configuration, if you have posted DNS - TXT records according to the instructions in our - quickstart guide. If you encounter trouble, try these hints. We - welcome additional hints via the users' mailing - list.

- - - - - - - - - - - - - - -
SymptomProblem -Action
You're running FreeS/WAN 2.01 (or later), and initiating a - connection to FreeS/WAN 2.00 (or earlier). In your logs, you see a - message like: -
no RSA public key known for '192.0.2.13';
-DNS search for KEY failed (no KEY record
-for 13.2.0.192.in-addr.arpa.)
- The older FreeS/WAN logs no error.		 - A protocol level incompatibility between 2.01 (or later) and 2.00 - (or earlier) causes this error. It occurs when a FreeS/WAN 2.01 (or - later) box for which no KEY record is posted attempts to initiate an OE - connection to older FreeS/WAN versions (2.00 and earlier). Note that - older versions can initiate to newer versions without this error. -If you control the peer host, upgrade its FreeS/WAN to 2.01 (or later), - and post new style TXT records for it. If not, but if you know its - sysadmin, perhaps a quick note is in order. If neither option is - possible, you can ease the transition by posting an old style KEY - record (created with a command like "ipsec showhostkey --key") to the - reverse map for the FreeS/WAN 2.01 (or later) box.
OE host is very slow to contact other hosts.Slow DNS - service while running OE.It's a good idea to run a caching DNS - server on your OE host, as outlined in - this mailing list message. If your DNS servers are elsewhere, put - their IPs in the clear policy group, and re-read groups with -
ipsec auto --rereadgroups
-
-
Can't Opportunistically initiate for
-192.0.2.2 to 192.0.2.3: no TXT record
-for 13.2.0.192.in-addr.arpa.
-		Peer is not set up for OE. -

None. Plenty of hosts on the Internet do not run OE. If, however, you - have set OE up on that peer, this may indicate that you need to wait up - to 48 hours for its DNS records to propagate.

-
ipsec verify does not find DNS records: -
...
-Looking for TXT in forward map:
-                xy.example.com...[FAILED]
-Looking for TXT in reverse map...[FAILED]
-...
- You also experience authentication failure: -
-
Possible authentication failure:
-no acceptable response to our
-first encrypted message
-		DNS records are not posted or have not propagated.Did - you post the DNS records necessary for OE? If not, do so using the - instructions in our quickstart - guide. If so, wait up to 48 hours for the DNS records to propagate.
ipsec verify does not find DNS records, and you - experience authentication failure.For iOE, your ID does not - match location of forward DNS record.In config setup -, change myid= to match the forward DNS where you posted the - record. Restart FreeS/WAN. For reference, see our - iOE instructions.
ipsec verify finds DNS records, yet there is still - authentication failure. ( ? )DNS records are malformed. -Re-create the records and send new copies to your DNS administrator.
ipsec verify finds DNS records, yet there is still - authentication failure. ( ? )DNS records show different keys - for a gateway vs. its subnet hosts.All TXT records for boxes - protected by an OE gateway must contain the gateway's public key. - Re-create and re-post any incorrect records using - these instructions.
OE gateway loses connectivity to its subnet. The gateway's - routing table shows routes to the subnet through IPsec interfaces. -The subnet is part of the private or block policy - group on the gateway.Remove the subnet from the group, and - reread groups with -
ipsec auto --rereadgroups
-
OE does not work to hosts on the local LAN.This is a - known issue.See this list - of known issues with OE.
FreeS/WAN does not seem to be executing your default policy. In - your logs, you see a message like: -
/etc/ipsec.d/policies/iprivate-or-clear"
-line 14: subnet "0.0.0.0/0",
-source 192.0.2.13/32,
-already "private-or-clear"
-		Fullnet in a policy group - file defines your default policy. Fullnet should normally be present in - only one policy group file. The fine print: you can have two default - policies defined so long as they protect different local endpoints - (e.g. the FreeS/WAN gateway and a subnet). Find all policies - which contain fullnet with: -
-
grep -F 0.0.0.0/0 /etc/ipsec.d/policies/*
- then remove the unwanted occurrence(s).
-

2. During Negotiation

-

When you fail to bring up a tunnel, you'll need to find out:

- -

before you can diagnose your problem -.

-

2.1 Determine Connection State

-

Finding current state

-

You can see connection states (STATE_MAIN_I1 and so on) when you - bring up a connection on the command line. If you have missed this, or - brought up your connection automatically, use:

-
ipsec auto --status
-

The most relevant state is the last one reached.

-

What's this supposed to look like?

-

Negotiations should proceed though various states, in the processes - of:

-
    -
  1. IKE negotiations (aka Phase 1, Main Mode, STATE_MAIN_*)
    2. -
  2. IPSEC negotiations (aka Phase 2, Quick Mode, STATE_QUICK_*)
    3. -
-

These are done and a connection is established when you see messages - like:

-
    000 #21: "myconn" STATE_MAIN_I4 (ISAKMP SA established)...
-    000 #2: "myconn" STATE_QUICK_I2 (sent QI2, IPsec SA established)...
-

Look for the key phrases are "ISAKMP SA established" and "IPSec SA - established", with the relevant connection name. Often, this happens at - STATE_MAIN_I4 and STATE_QUICK_I2, respectively.

-

ipsec auto --status will tell you what states have - been achieved, rather than the current state. Since - determining the current state is rather more difficult to do, current - state information is not available from Linux FreeS/WAN. If you are - actively bringing a connection up, the status report's last states for - that connection likely reflect its current state. Beware, though, of - the case where a connection was correctly brought up but is now downed: - Linux FreeS/WAN will not notice this until it attempts to rekey. - Meanwhile, the last known state indicates that the connection has been - established.

-

If your connection is stuck at STATE_MAIN_I1, skip straight to - here.

-

2.2 Finding error text

-

Solving most errors will require you to find verbose error text, - either on the command line or in the logs.

-

Verbose start for more information

-

Note that you can get more detail from ipsec auto using - the --verbose flag:

-
    ipsec auto --verbose --up west-east
-

More complete information can be gleaned from the - log files.

-

Debug levels count

-

The amount of description you'll get here depends on ipsec.conf debug - settings, klipsdebug= and plutodebug=. When - troubleshooting, set at least one of these to all, and when - done, reset it to none so your logs don't fill up. Note that - you must have enabled the klipsdebug - compile-time option for the klipsdebug configuration - switch to work.

-

For negotiation problems plutodebug is most relevant. - klipsdebug applies mainly to attempts to use an - already-established connection. See also - this description of the division of duties within Linux FreeS/WAN.

-

After raising your debug levels, restart Linux FreeS/WAN to ensure - that ipsec.conf is reread, then recreate the error to generate verbose - logs.

-

ipsec barf for lots of debugging information

-

ipsec barf (8) - collects a bunch of useful debugging information, including these logs - Use the command

-
-    ipsec barf > barf.west
-
-

to generate one.

-

Find the error

-

Search out the failure point in your logs. Are there a handful of - lines which succinctly describe how things are going wrong or contrary - to your expectation? Sometimes the failure point is not immediately - obvious: Linux FreeS/WAN's errors are usually not marked "Error". Have - a look in the FAQ for what some common failures - look like.

-

Tip: problems snowball. Focus your efforts on the first problem, - which is likely to be the cause of later errors.

-

Play both sides

-

Also find error text on the peer IPSec box. This gives you two - perspectives on the same failure.

-

At times you will require information which only one side has. The - peer can merely indicate the presence of an error, and its approximate - point in the negotiations. If one side keeps retrying, it may be - because there is a show stopper on the other side. Have a look at the - other side and figure out what it doesn't like.

-

If the other end is not Linux FreeS/WAN, the principle is the same: - replicate the error with its most verbose logging on, and capture the - output to a file.

-

2.3 Interpreting a Negotiation - Error

-

Connection stuck at STATE_MAIN_I1

-

This error commonly happens because IKE (port 500) packets, needed to - negotiate an IPSec connection, cannot travel freely between your IPSec - gateways. See our firewall document - for details.

-

Other errors

-

Other errors require a bit more digging. Use the following resources:

- -

If you have failed to solve your problem with the help of these - resources, send a detailed problem report to the users list, following - these guidelines.

-

3. Using a Connection

-

3.1 Orienting yourself

-

How do I know if it works?

-

Test your connection by sending packets through it. The simplest way - to do this is with ping, but the ping needs to test the correct - tunnel. See this example scenario if - you don't understand this.

-

-

If your ping returns, test any other connections you've brought u all - check out, great. You may wish to test with large - packets for MTU problems.

-

ipsec barf is useful again

-

If your ping fails to return, generate an ipsec barf debugging report - on each IPSec gateway. On a non-Linux FreeS/WAN implementation, gather - equivalent information. Use this, and the tips in the next sections, to - troubleshoot. Are you sure that both endpoints are capable of hearing - and responding to ping?

-

3.2 Those pesky configuration errors

-

IPSec may be dropping your ping packets since they do not belong in - the tunnels you have constructed:

- -

In either case, you will often see a message like:

-
klipsdebug... no eroute
-

which we discuss in this FAQ.

-

Note:

- -

3.3 Check Routing and Firewalling

-

If you've confirmed your configuration assumptions, the problem is - almost certainly with routing or firewalling. Isolate the problem using - interface statistics, firewall statistics, or a packet sniffer.

-

Background:

- -

View Interface and Firewall Statistics

-

Interface reports and firewall statistics can help you track down - lost packets at a glance. Check any firewall statistics you may be - keeping on your IPSec gateways, for dropped packets.

-

Tip: You can take a snapshot of the packets - processed by your firewall with:

-
    iptables -L -n -v
-

You can get creative with "diff" to find out what happens to a - particular packet during transmission.

-

Both cat /proc/net/dev and ifconfig display - interface statistics, and both are included in ipsec barf. - Use either to check if any interface has dropped packets. If you find - that one has, test whether this is related to your ping. While you ping - continuously, print that interface's statistics several times. Does its - drop count increase in proportion to the ping? If so, check why the - packets are dropped there.

-

To do this, look at the firewall rules that apply to that interface. - If the interface is an IPSec interface, more information may be - available in the log. Grep for the word "drop" in a log which was - created with klipsdebug=all as the error happened.

-

See also this discussion on interpreting - ifconfig statistics.

-

3.4 When in doubt, sniff it out

-

If you have checked configuration assumptions, routing, and firewall - rules, and your interface statistics yield no clue, it remains for you - to investigate the mystery of the lost packet by the most thorough - method: with a packet sniffer (providing, of course, that this is legal - where you are working).

-

In order to detect packets on the ipsec virtual interfaces, you will - need an up-to-date sniffer (tcpdump, ethereal, ksnuffle) on your IPSec - gateway machines. You may also find it useful to sniff the ping - endpoints.

-

Anticipate your packets' path

-

Ping, and examine each interface along the projected path, checking - for your ping's arrival. If it doesn't get to the the next stop, you - have narrowed down where to look for it. In this way, you can isolate a - problem area, and narrow your troubleshooting focus.

-

Within a machine running Linux FreeS/WAN, this - packet flow diagram will help you anticipate a packet's path.

-

Note that:

- -

Once you isolate where the packet is lost, take a closer look at - firewall rules, routing and configuration assumptions as they affect - that specific area. If the packet is lost on an IPSec gateway, comb - through klipsdebug output for anomalies.

-

If the packet goes through both gateways successfully and reaches the - ping target, but does not return, suspect routing. Check that the ping - target routes packets back to the IPSec gateway.

-

3.5 Check your logs

-

Here, too, log information can be useful. Start with the - guidelines above.

-

For connection use problems, set klipsdebug=all. Note that - you must have enabled the klipsdebug - compile-time option to do this. Restart Linux FreeS/WAN so that it - rereads ipsec.conf, then recreate the error condition. When - searching through klipsdebug data, look especially for the - keywords "drop" (as in dropped packets) and "error".

-

Often the problem with connection use is not software error, but - rather that the software is behaving contrary to expectation.

-

Interpreting log text

-

To interpret the Linux FreeS/WAN log text you've found, use the same - resources as indicated for troubleshooting connection negotiation: - the FAQ , our background document, - and the list archives. Looking in the - KLIPS code is only for the very brave.

-

If you are still stuck, send a detailed - problem report to the users' list.

-

3.6 More testing for the truly thorough

-

Large Packets

-

If each of your connections passed the ping test, you may wish to - test by pinging with large packets (2000 bytes or larger). If it does - not return, suspect MTU issues, and see this - discussion.

-

Stress Tests

-

In most users' view, a simple ping test, and perhaps a large-packet - ping test suffice to indicate a working IPSec connection.

-

Some people might like to do additional stress tests prior to - production use. They may be interested in this - testing protocol we use at interoperation conferences, aka - "bakeoffs". We also have a testing directory that ships with - the release.

-

4. Problem Reporting

-

4.1 How to ask for help

-

Ask for troubleshooting help on the users' mailing list, - users@lists.freeswan.org. 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.

-

When reporting problems to the mailing list(s), please include:

- -

Here are some good general guidelines on bug reporting: - How To Ask Questions The Smart Way and - How to Report Bugs Effectively.

-

4.2 Where to ask

-

To report a problem, send mail about it to the users' list. If you - are certain that you have found a bug, report it to the bugs list. If - you encounter a problem while doing your own coding on the Linux - FreeS/WAN codebase and think it is of interest to the design team, - notify the design list. When in doubt, default to the users' list. More - information about the mailing lists is found - here.

-

For a number of reasons -- including export-control regulations - affecting almost any private discussion of encryption - software -- we prefer that problem reports and discussions go to the - lists, not directly to the team. Beware that the list goes worldwide; - US citizens, read this important information about your - export laws. If you're using this software, you really should be on - the lists. To get onto them, visit - lists.freeswan.org.

-

If you do send private mail to our coders or want a private reply - from them, please make sure that the return address on your mail (From - or Reply-To header) is a valid one. They have more important things to - do than to unravel addresses that have been mangled in an attempt to - confuse spammers.

-

5. Additional Notes on Troubleshooting

-

The following sections supplement the Guide: - information available on your system; testing - between security gateways; ifconfig reports - for KLIPS debugging; using GDB on Pluto.

-

5.1 Information available on your system

-

Logs used

-

Linux FreeS/WAN logs to:

- -

Check both places to get full information. If you find nothing, check - your syslogd.conf(5) to see where your /etc/syslog.conf or - equivalent is directing authpriv messages.

-

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

- -

Status information

-
-
ipsec auto --status
-
Command to get status report from running system. Displays Pluto's - state. Includes the list of connections which are currently "added" to - Pluto's internal database; lists state objects reflecting ISAKMP and - IPsec SAs being negotiated or installed.
-
ipsec look
-
Brief status info.
-
ipsec barf
-
Copious debugging info.
-
-

5.2 Testing between security gateways

-

Sometimes you need to test a subnet-subnet tunnel. This is a tunnel - between two security gateways, which protects traffic on behalf of the - subnets behind these gateways. On this network:

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

you might name this tunnel sunset-sunrise. You can test this tunnel - 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 - traffic between the two protected subnets, not between the gateways - . Depending on the routing in place, a ping might

- -

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 unnecessary complications - in your situation.

-

The trick is to explicitly test between both gateways' - private-side IP addresses. Since the private-side interfaces - are on the protected subnets, the resulting packets do go via the - tunnel. Use either ping -I or traceroute -i, both of which allow you to - specify a source interface. (Note: unsupported on older Linuxes). The - same principles apply for a road warrior (or other) case where only one - end of your tunnel is a subnet.

-

5.3 ifconfig reports for KLIPS debugging

-

When diagnosing problems using ifconfig statistics, you may wonder - what type of activity increments a particular counter for an ipsecN - device. Here's an index, posted by KLIPS developer Richard Guy Briggs:

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

5.4 Using GDB on Pluto

-

You may need to use the GNU debugger, gdb(1), on Pluto. This should - be necessary only in unusual 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.

-

-
-

-
-Contents -Previous -Next - - diff --git a/doc/umltesting.html b/doc/umltesting.html deleted file mode 100644 index 35bcef96d..000000000 --- a/doc/umltesting.html +++ /dev/null @@ -1,313 +0,0 @@ - - - -Introduction to FreeS/WAN - - - - -Contents -Previous -Next -
-

User-Mode-Linux Testing guide

-

User mode linux is a way to compile a linux kernel such that it can - run as a process in another linux system (potentially as a *BSD or - Windows process later). See - http://user-mode-linux.sourceforge.net/

-

UML is a good platform for testing and experimenting with FreeS/WAN. - It allows several network nodes to be simulated on a single machine. - Creating, configuring, installing, monitoring, and controling these - nodes is generally easier and easier to script with UML than real - hardware.

-

You'll need about 500Mb of disk space for a full - sunrise-east-west-sunset setup. You can possibly get this down by 130Mb - if you remove the sunrise/sunset kernel build. If you just want to run, - then you can even remove the east/west kernel build.

-

Nothing need be done as super user. In a couple of steps, we note - where super user is required to install commands in system-wide - directories, but ~/bin could be used instead. UML seems to use a - system-wide /tmp/uml directory so different users may interfere with - one another. Later UMLs use ~/.uml instead, so multiple users running - UML tests should not be a problem, but note that a single user running - the UML tests will only be able run one set. Further, UMLs sometimes - get stuck and hang around. These "zombies" (most will actually be in - the "T" state in the process table) will interfere with subsequent - tests.

-

Preliminary Notes on BIND

-

As of 2003/3/1, the Light-Weight Resolver is used by pluto. This - requires that BIND9 be running. It also requires that BIND9 development - libraries be present in the build environment. The DNSSEC code is only - truly functional in BIND9 snapshots. The library code could be 9.2.2, - we believe. We are using BIND9 20021115 snapshot code from - ftp://ftp.isc.org/isc/bind9/snapshots.

-

FreeS/WAN may well require a newer BIND than is on your system. Many - distributions have moved to BIND9.2.2 recently due to a security - advisory. BIND is five components.

-
    -
  1. named
    2. -
  2. dnssec-*
    3. -
  3. client side resolver libraries
    4. -
  4. client side utility libraries I thought there were lib and named - parts to dnsssec...
    5. -
  5. dynamic DNS update utilities
    6. -
-

The only piece that we need for *building* is #4. That's the only - part that has to be on the build host. What is the difference between - resolver and util libs? If you want to edit - testing/baseconfigs/all/etc/bind, you'll need a snapshot version. The - resolver library contains the resolver. FreeS/WAN has its own copy of - that in lib/liblwres.

-

Steps to Install UML for FreeS/WAN

-
    -
  1. Get the following files: -
      -
    1. from - http://www.sandelman.ottawa.on.ca/freeswan/uml/ - umlfreeroot-15.1.tar.gz (or highest numbered one). This is a debian - potato root file system. You can use this even on a Redhat host, as it - has the newer GLIBC2.2 libraries as well. - - - -
      2. -
    2. From - ftp://ftp.xs4all.nl/pub/crypto/freeswan/ a snapshot or release - (1.92 or better)
      3. -
    3. From a - http://www.kernel.org mirror, the virgin 2.4.19 kernel. Please - realize that we have defaults in our tree for kernel configuration. We - try to track the latest UML kernels. If you use a newer kernel, you may - have faults in the kernel build process. You can see what the latest - that is being regularly tested by visiting - freeswan-regress-env.sh.
      4. -
    4. - - Get - http://ftp.nl.linux.org/uml/ uml-patch-2.4.19-47.bz2 or the one - associated with your kernel. As of 2003/03/05, uml-patch-2.4.19-47.bz2 - works for us. More recent versions of the patch have not been - tested by us.
      5. -
    5. You'll probably want to visit - http://user-mode-linux.sourceforge.net and get the UML utilities. - These are not needed for the build or interactive use (but - recommended). They are necessary for the regression testing procedures - used by "make check". We currently use uml_utilities_20020212.tar.bz2.
      6. -
    6. You need tcpdump version 3.7.1 or better. This is newer than the - version included in most LINUX distributions. You can check the version - of an installed tcpdump with the --version flag. If you need a newer - tcpdump fetch both tcpdump and libpcap source tar files from - http://www.tcpdump.org/ or a mirror.
      7. -
    -
    2. -
  2. Pick a suitable place, and extract the following files: -
      -
    1. - - 2.4.19 kernel. For instance: -
      -            cd /c2/kernel
-           tar xzvf ../download/pub/linux/kernel/v2.4/linux-2.4.19.tar.gz
-
-
      -
      2. -
    2. extract the umlfreeroot file - - -
      -            mkdir -p /c2/user-mode-linux/basic-root
-           cd /c2/user-mode-linux/basic-root
-           tar xzvf ../download/umlfreeroot-15.1.tar.gz
-
-
      -
      3. -
    3. FreeSWAN itself (or checkout "all" from CVS) -
      -            mkdir -p /c2/freeswan/sandbox
-           cd /c2/freeswan/sandbox
-           tar xzvf ../download/snapshot.tar.gz
-
-
      -
      4. -
    -
    3. -
  3. If you need to build a newer tcpdump: -
      -
    • Make sure you have OpenSSL installed -- it is needed for - cryptographic routines.
      • -
    • Unpack libpcap and tcpdump source in parallel directories (the - tcpdump build procedures look for libpcap next door).
      • -
    • Change directory into the libpcap source directory and then build - the library: -
      - 	./configure
-	make
-
-
      -
      • -
    • Change into the tcpdump source directory, build tcpdump, and - install it. -
      - 	./configure
-	make
-	# Need to be superuser to install in system directories.
-	# Installing in ~/bin would be an alternative.
-	su -c "make install"
-
-
      -
      • -
    -
    4. -
  4. If you need the uml utilities, unpack them somewhere then build and - install them: -
    - 	cd tools
-	make all
-	# Need to be superuser to install in system directories.
-	# Installing in ~/bin would be an alternative.
-	su -c "make install BIN_DIR=/usr/local/bin"
-
-
    -
    5. -
  5. set up the configuration file -
      -
    • cd /c2/freeswan/sandbox/freeswan-1.97/testing/utils
      • -
    • copy umlsetup-sample.sh to ../../umlsetup.sh: cp - umlsetup-sample.sh ../../umlsetup.sh
      • -
    • open up ../../umlsetup.sh in your favorite editor.
      • -
    • change POOLSPACE= to point to the place with at least 500Mb of - disk. Best if it is on the same partition as the "umlfreeroot" - extraction, as it will attempt to use hard links if possible to save - disk space.
      • -
    • Set TESTINGROOT if you intend to run the script outside of the - sandbox/snapshot/release directory. Otherwise, it will configure - itself.
      • -
    • KERNPOOL should point to the directory with your 2.4.19 kernel - tree. This tree should be unconfigured! This is the directory you used - in step 2a.
      • -
    • UMLPATCH should point at the bz2 file you downloaded at 1d. If - using a kernel that already includes the patch, set this to /dev/null.
      • -
    • FREESWANDIR should point at the directory where you unpacked the - snapshot/release. Include the "freeswan-snap2001sep16b" or whatever in - it. If you are running from CVS, then you point at the directory where - top, klips, etc. are. The script will fix up the directory so that it - can be used.
      • -
    • BASICROOT should be set to the directory used in 2b, or to the - directory that you created with RPMs.
      • -
    • SHAREDIR should be set to the directory used in 2c, to /usr/share - for Debian potato users, or to $BASICROOT/usr/share.
      • -
    -
    6. -
  6. -
     cd $TESTINGROOT/utils
-sh make-uml.sh
-
    - It will grind for awhile. If there are errors it will bail. If so, run - it under "script" and send the output to bugs@lists.freeswan.org.
    7. -
  7. You will have a bunch of stuff under $POOLSPACE. Open four xterms: -
         for i in sunrise sunset east west
-    do
-        xterm -name $i -title $i -e $POOLSPACE/$i/start.sh     done
-
    -
    8. -
  8. Login as root. Password is "root" (Note, these virtual machines are - networked together, but are not configured to talk to the rest of the - world.)
    9. -
  9. verify that pluto started on east/west, run "ipsec look"
    10. -
  10. login to sunrise. run "ping sunset"
    11. -
  11. login to west. run "tcpdump -p -i eth1 -n" (tcpdump must be version - 3.7.1 or newer)
    12. -
  12. Closing a console xterm will shut down that UML.
    13. -
  13. You can "make check", if you want to. It is run from - /c2/freeswan/sandbox/freeswan-1.97.
    14. -
-

Debugging the kernel with GDB

-

With User-Mode-Linux, you can debug the kernel using GDB. See - - - http://user-mode-linux.sourceforge.net/debugging.html.

-

Typically, one will want to address a test case for a failing - situation. Running GDB from Emacs, or from other front ends is - possible. First start GDB.

-

Tell it to open the UMLPOOL/swan/linux program.

-

Note the PID of GDB:

-
-marajade-[projects/freeswan/mgmt/planning] mcr 1029 %ps ax | grep gdb
- 1659 pts/9    SN     0:00 /usr/bin/gdb -fullname -cd /mara4/freeswan/kernpatch/UMLPOOL/swan/ linux
-
-

Set the following in the environment:

-
-UML_east_OPT="debug gdb-pid=1659"
-
-

Then start the user-mode-linux in the test scheme you wish:

-
-marajade-[kernpatch/testing/klips/east-icmp-02] mcr 1220 %../../utils/runme.sh
-
- The user-mode-linux will stop on boot, giving you a chance to attach to - the process: -
-(gdb) file linux
-Reading symbols from linux...done.
-(gdb) attach 1
-Attaching to program: /mara4/freeswan/kernpatch/UMLPOOL/swan/linux, process 1
-0xa0118bc1 in kill () at hostfs_kern.c:770
-
-

At this point, break points should be created as appropriate.

-

Other notes about debugging

-

If you are running a standard test, after all the packets are sent, - the UML will be shutdown. This can cause problems, because the UML may - get terminated while you are debugging.

-

The environment variable NETJIGWAITUSER can be set to - "waituser". If so, then the testing system will prompt before exiting - the test.

-

User-Mode-Linux mysteries

- -

Getting more info from uml_netjig

-

uml_netjig can be compiled with a built-in tcpdump. This uses - not-yet-released code from - www.tcpdump.org. Please see the instructions in -testing/utils/uml_netjig/Makefile.

-
-Contents -Previous -Next - - diff --git a/doc/upgrading.html b/doc/upgrading.html deleted file mode 100644 index ce9fba3d2..000000000 --- a/doc/upgrading.html +++ /dev/null @@ -1,184 +0,0 @@ - - - -Introduction to FreeS/WAN - - - - -Contents -Previous -Next -
- -

Upgrading to FreeS/WAN 2.x

-

New! Built in Opportunistic connections

-

Out of the box, FreeS/WAN 2.x will attempt to encrypt all your IP - traffic. It will try to establish IPsec connections for:

- -

FreeS/WAN 2.x uses hidden, automatically enabled - ipsec.conf connections to do this.

-

This behaviour is part of our campaign to get Opportunistic - Encryption (OE) widespread in the Linux world, so that any two Linux - boxes can encrypt to one another without prearrangement. There's one - catch, however: you must set up a - few DNS records to distribute RSA public keys and (if applicable) - IPsec gateway information.

-

If you start FreeS/WAN before you have set up these DNS records, your - connectivity will be slow, and messages relating to the built in - connections will clutter your logs. If you are unable to set up DNS for - OE, you will wish to - disable the hidden connections.

- -

Upgrading Opportunistic Encryption to 2.01 (or - later)

-

As of FreeS/WAN 2.01, Opportunistic Encryption (OE) uses DNS TXT - resource records (RRs) only (rather than TXT with KEY). This change - causes a "flag day". Users of FreeS/WAN 2.00 (or earlier) OE who are - upgrading may need to post additional resource records.

-

If you are running - initiate-only OE, you must put up a TXT record in any - forward domain as per our - quickstart instructions. This replaces your old forward KEY.

-

If you are running full OE, you require no updates. You already have - the needed TXT record in the reverse domain. However, to facilitate - future features, you may also wish to publish that TXT record in a - forward domain as instructed - here.

-

If you are running OE on a gateway (and encrypting on behalf of - subnetted boxes) you require no updates. You already have the required - TXT record in your gateway's reverse map, and the TXT records for any - subnetted boxes require no updating. However, to facilitate future - features, you may wish to publish your gateway's TXT record in a - forward domain as shown here -.

-

During the transition, you may wish to leave any old KEY records up - for some time. They will provide limited backward compatibility. - -

-

New! Policy Groups

-

We want to make it easy for you to declare security policy as it - applies to IPsec connections.

-

Policy Groups make it simple to say:

- -

FreeS/WAN then implements these policies, creating OE connections if - and when needed. You can use Policy Groups along with connections you - explicitly define in ipsec.conf.

-

For more information, see our Policy - Group HOWTO.

-

New! Packetdefault Connection

-

Free/SWAN 2.x ships with the automatically enabled, hidden - connection packetdefault. This configures a - FreeS/WAN box as an OE gateway for any hosts located behind it. As - mentioned above, you must configure some DNS - records for OE to work.

-

As the name implies, this connection functions as a default. If you - have more specific connections, such as policy groups which configure - your FreeS/WAN box as an OE gateway for a local subnet, these will - apply before packetdefault. You can view packetdefault -'s specifics in man ipsec.conf -.

-

FreeS/WAN now disables Reverse Path Filtering

-

FreeS/WAN often doesn't work with reverse path filtering. At start - time, FreeS/WAN now turns rp_filter off, and logs a warning.

-

FreeS/WAN does not turn it back on again. You can do this yourself - with a command like:

-
   echo 1 > /proc/sys/net/ipv4/conf/eth0/rp_filter
-

For eth0, substitute the interface which FreeS/WAN was affecting.

- -

Revised ipsec.conf

-

No promise of compatibility

-

The FreeS/WAN team promised config-file compatibility throughout the - 1.x series. That means a 1.5 config file can be directly imported into - a fresh 1.99 install with no problems.

-

With FreeS/WAN 2.x, we've given ourselves permission to make the - config file easier to use. The cost: some FreeS/WAN 1.x configurations - will not work properly. Many of the new features are, however, backward - compatible.

-

Most ipsec.conf files will work fine

-

... so long as you paste this line, with no preceding - whitespace, at the top of your config file:

-
    version 2
-

Backward compatibility patch

-

If the new defaults bite you, use this - ipsec.conf fragment to simulate the old default values.

-

Details

-

We've obsoleted various directives which almost no one was using:

-
    dump
-    plutobackgroundload
-    no_eroute_pass
-    lifetime
-    rekeystart
-    rekeytries
-

For most of these, there is some other way to elicit the desired - behaviour. See - this post.

-

We've made some settings, which almost everyone was using, defaults. - For example:

-
    interfaces=%defaultroute
-    plutoload=%search
-    plutostart=%search
-    uniqueids=yes
-

We've also changed some default values to help with OE and Policy - Groups:

-
    authby=rsasig   ## not secret!!!
-    leftrsasigkey=%dnsondemand ## looks up missing keys in DNS when needed.
-    rightrsasigkey=%dnsondemand
-

Of course, you can still override any defaults by explictly - declaring something else in your connection.

-

- A post with a list of many ipsec.conf changes. -
Current ipsec.conf manual. -

- -

Upgrading from 1.x RPMs to 2.x RPMs

-

Note: When upgrading from 1-series to 2-series RPMs, rpm -U - will not work.

-

You must instead erase the 1.x RPMs, then install the 2.x set:

-
    rpm -e freeswan
-
    rpm -e freeswan-module
-

On erasing, your old ipsec.conf should be moved to - ipsec.conf.rpmsave. Keep this. You will probably want to copy - your existing connections to the end of your new 2.x file.

-

Install the RPMs suitable for your kernel version, such as:

-
    rpm -ivh freeswan-module-2.04_2.4.20_20.9-0.i386.rpm
-
    rpm -ivh freeswan-userland-2.04_2.4.20_20.9-0.i386.rpm
-

Or, to splice the files:

-
    cat /etc/ipsec.conf /etc/ipsec.conf.rpmsave > /etc/ipsec.conf.tmp
-    mv /etc/ipsec.conf.tmp /etc/ipsec.conf
-

Then, remove the redundant conn %default and config - setup sections. Unless you have done any special configuring - here, you'll likely want to remove the 1.x versions. Remove conn - OEself, if present.

-
-Contents -Previous -Next - - diff --git a/doc/user_examples.html b/doc/user_examples.html deleted file mode 100644 index d683c92e1..000000000 --- a/doc/user_examples.html +++ /dev/null @@ -1,320 +0,0 @@ - - - -Introduction to FreeS/WAN - - - - -Contents -Previous -Next -
-

FreeS/WAN script examples

- This file is intended to hold a collection of user-written example - scripts or configuration files for use with FreeS/WAN. -

So far it has only one entry.

-

Poltorak's Firewall script

-
-From: Poltorak Serguei <poltorak@dataforce.net>
-Subject: [Users] Using FreeS/WAN
-Date: Tue, 16 Oct 2001
-
-Hello.
-
-I'm using FreeS/WAN IPsec for half a year. I learned a lot of things about
-it and I think it would be interesting for someone to see the result of my
-experiments and usage of FreeS/WAN. If you find a mistake in this
-file, please e-mail me. And excuse me for my english... I'm learning.. :)
-
-I'll talk about vary simple configuration:
-
-addresses prefix = 192.168
-
-    lan1          sgw1     .0.0/24 (Internet)       sgw2            lan2
-  .1.0/24---[ .1.1 ; .0.1 ]===================[ .0.10 ; . 2.10 ]---.2.0/24
-
-
-We need to let lan1 see lan2 across Internet like it is behind sgw1. The
-same for lan2. And we need to do IPX bridge for Novel Clients and NDS
-synchronization.
-
-my config:
-------------------- ipsec.conf -------------------
-conn lan1-lan2
-        type=tunnel
-        compress=yes
-        #-------------------
-        left=192.168.0.1
-        leftsubnet=192.168.1.0/24
-        #-------------------
-        right=192.168.0.10
-        rightsubnet=192.168.2.0/24
-        #-------------------
-        auth=esp
-        authby=secret
---------------- end of ipsec.conf ----------------
-
-ping .2.x from .1.y   (y != 1)
-It works?? Fine. Let's continue...
-
-Why y != 1 ?? Because kernel of sgw1 have 2 IP addresses and it will choose
-the first IP (which is used to go to Internet) .0.1 and the packet won't go
-through IPsec tunnel :(  But if do ping on .1.1 kernel will respond from
-that address (.1.1) and the packet will be tunneled. The same problem occurred then
-.2.x sends a packet to .1.2 which is down at the moment. What happens? .1.1
-sends ARP requesting .1.2... after 3 tries it send to .2.x an destunreach,
-but from his "natural" IP or .0.1 . So the error message won't be delivered!
-It's a big problem...
-
-Resolution... One can manipulate with ipsec0 or ipsec0:0 to solve the
-problem (if ipsec0 has .1.1 kernel will send packets correctly), but there
-are powerful and elegant iproute2 :) We simply need to change source address
-of packet that goes to other secure lan. This is done with
-
-ip route replace 192.168.2.0/24 via 192.168.0.10 dev ipsec0 src 192.168.1.1
-
-Cool!! Now it works!!
-
-The second step. We want install firewall on sgw1 and sgw2. Encryption of 
-traffic without security isn't a good idea. I don't use {left|right}firewall, 
-because I'm running firewall from init scripts.
-
-We want IPsec data between lan1-lan2, some ICMP errors (destination
-unreachable, TTL exceeded, parameter problem and source quench), replying on 
-pings from both lans and Internet, ipxtunnel data for IPX and of course SSH
-between sgw1 and sgw2 and from/to one specified host.
-
-I'm using ipchains. With iptables there are some changes.
-
----------------- rc.firewall ---------------------
-#!/bin/sh
-#
-# Firewall for IPsec lan1-lan2
-#
-
-IPC=/sbin/ipchains
-ANY=0.0.0.0/0
-
-# left
-SGW1_EXT=192.168.0.1
-SGW1_INT=192.168.1.1
-LAN1=192.168.1.0/24
-
-# right
-SGW2_EXT=192.168.0.10
-SGW2_INT=192.168.2.10
-LAN2=192.168.2.0/24
-
-# SSH from and to this host
-SSH_PEER_HOST=_SOME_HOST_
-
-# this is for left. exchange these values for right.
-MY_EXT=$SGW1_EXT
-MY_INT=$SGW1_INT
-PEER_EXT=$SGW2_EXT
-PEER_INT=$SGW2_INT
-INT_IF=eth1
-EXT_IF=eth0
-IPSEC_IF=ipsec0
-MY_LAN=$LAN1
-PEER_LAN=$LAN2
-
-$IPC -F
-$IPC -P input DENY
-$IPC -P forward DENY
-$IPC -P output DENY
-
-# Loopback traffic
-$IPC -A input -i lo -j ACCEPT
-$IPC -A output -i lo -j ACCEPT
-
-# for IPsec SGW1-SGW2
-## IKE
-$IPC -A input -p udp -s $PEER_EXT 500 -d $MY_EXT 500 -i $EXT_IF -j ACCEPT
-$IPC -A output -p udp -s $MY_EXT 500 -d $PEER_EXT 500 -i $EXT_IF -j ACCEPT
-## ESP
-$IPC -A input -p 50 -s $PEER_EXT -d $MY_EXT -i $EXT_IF -j ACCEPT
-### we don't need this line ### $IPC -A output -p 50 -s $MY_EXT -d $PEER_EXT -i $EXT_IF -j ACCEPT
-## forward LAN1-LAN2
-$IPC -A forward -s $MY_LAN -d $PEER_LAN -i $IPSEC_IF -j ACCEPT
-$IPC -A forward -s $PEER_LAN -d $MY_LAN -i $INT_IF -j ACCEPT
-$IPC -A output -s $PEER_LAN -d $MY_LAN -i $INT_IF -j ACCEPT
-$IPC -A input -s $PEER_LAN -d $MY_LAN -i $IPSEC_IF -j ACCEPT
-$IPC -A input -s $MY_LAN -d $PEER_LAN -i $INT_IF -j ACCEPT
-$IPC -A output -s $MY_LAN -d $PEER_LAN -i $IPSEC_IF -j ACCEPT
-
-# ICMP
-#
-## Dest unreachable
-### from/to Internet
-$IPC -A input -p icmp --icmp-type destination-unreachable -s $ANY -d $MY_EXT -i $EXT_IF -j ACCEPT
-$IPC -A output -p icmp --icmp-type destination-unreachable -s $MY_EXT -d $ANY -i $EXT_IF -j ACCEPT
-### from/to Lan
-$IPC -A input -p icmp --icmp-type destination-unreachable -s $ANY -d $MY_INT -i $INT_IF -j ACCEPT
-$IPC -A output -p icmp --icmp-type destination-unreachable -s $MY_INT -d $ANY -i $INT_IF -j ACCEPT
-### from/to Peer Lan
-$IPC -A input -p icmp --icmp-type destination-unreachable -s $ANY -d $MY_INT -i $IPSEC_IF -j ACCEPT
-$IPC -A output -p icmp --icmp-type destination-unreachable -s $MY_INT -d $ANY -i $IPSEC_IF -j ACCEPT
-#
-## Source quench
-### from/to Internet
-$IPC -A input -p icmp --icmp-type source-quench -s $ANY -d $MY_EXT -i $EXT_IF -j ACCEPT
-$IPC -A output -p icmp --icmp-type source-quench -s $MY_EXT -d $ANY -i $EXT_IF -j ACCEPT
-### from/to Lan
-$IPC -A input -p icmp --icmp-type source-quench -s $ANY -d $MY_INT -i $INT_IF -j ACCEPT
-$IPC -A output -p icmp --icmp-type source-quench -s $MY_INT -d $ANY -i $INT_IF -j ACCEPT
-### from/to Peer Lan
-$IPC -A input -p icmp --icmp-type source-quench -s $ANY -d $MY_INT -i $IPSEC_IF -j ACCEPT
-$IPC -A output -p icmp --icmp-type source-quench -s $MY_INT -d $ANY -i $IPSEC_IF -j ACCEPT
-#
-## Parameter problem
-### from/to Internet
-$IPC -A input -p icmp --icmp-type parameter-problem -s $ANY -d $MY_EXT -i $EXT_IF -j ACCEPT
-$IPC -A output -p icmp --icmp-type parameter-problem -s $MY_EXT -d $ANY -i $EXT_IF -j ACCEPT
-### from/to Lan
-$IPC -A input -p icmp --icmp-type parameter-problem -s $ANY -d $MY_INT -i $INT_IF -j ACCEPT
-$IPC -A output -p icmp --icmp-type parameter-problem -s $MY_INT -d $ANY -i $INT_IF -j ACCEPT
-### from/to Peer Lan
-$IPC -A input -p icmp --icmp-type parameter-problem -s $ANY -d $MY_INT -i $IPSEC_IF -j ACCEPT
-$IPC -A output -p icmp --icmp-type parameter-problem -s $MY_INT -d $ANY -i $IPSEC_IF -j ACCEPT
-#
-## Time To Live exceeded
-### from/to Internet
-$IPC -A input -p icmp --icmp-type time-exceeded -s $ANY -d $MY_EXT -i $EXT_IF -j ACCEPT
-$IPC -A output -p icmp --icmp-type time-exceeded -s $MY_EXT -d $ANY -i $EXT_IF -j ACCEPT
-### to Lan
-$IPC -A input -p icmp --icmp-type time-exceeded -s $ANY -d $MY_INT -i $INT_IF -j ACCEPT
-$IPC -A output -p icmp --icmp-type time-exceeded -s $MY_INT -d $ANY -i $INT_IF -j ACCEPT
-### to Peer Lan
-$IPC -A input -p icmp --icmp-type time-exceeded -s $ANY -d $MY_INT -i $IPSEC_IF -j ACCEPT
-$IPC -A output -p icmp --icmp-type time-exceeded -s $MY_INT -d $ANY -i $IPSEC_IF -j ACCEPT
-
-# ICMP PINGs
-## from Internet
-$IPC -A input -p icmp -s $ANY -d $MY_EXT --icmp-type echo-request  -i $EXT_IF -j ACCEPT
-$IPC -A output -p icmp -s $MY_EXT -d $ANY --icmp-type echo-reply  -i $EXT_IF -j ACCEPT
-## from LAN
-$IPC -A input -p icmp -s $ANY -d $MY_INT --icmp-type echo-request -i $INT_IF -j ACCEPT
-$IPC -A output -p icmp -s $MY_INT -d $ANY --icmp-type echo-reply  -i $INT_IF -j ACCEPT
-## from Peer LAN
-$IPC -A input -p icmp -s $ANY -d $MY_INT --icmp-type echo-request -i $IPSEC_IF -j ACCEPT
-$IPC -A output -p icmp -s $MY_INT -d $ANY --icmp-type echo-reply  -i $IPSEC_IF -j ACCEPT
-
-# SSH
-## from SSH_PEER_HOST
-$IPC -A input -p tcp -s $SSH_PEER_HOST -d $MY_EXT 22 -i $EXT_IF -j ACCEPT
-$IPC -A output -p tcp \! -y -s $MY_EXT 22 -d $SSH_PEER_HOST -i $EXT_IF -j ACCEPT
-## to SSH_PEER_HOST
-$IPC -A input -p tcp \! -y -s $SSH_PEER_HOST 22 -d $MY_EXT -i $EXT_IF -j ACCEPT
-$IPC -A output -p tcp -s $MY_EXT -d $SSH_PEER_HOST 22 -i $EXT_IF -j ACCEPT
-## from PEER
-$IPC -A input -p tcp -s $PEER_EXT -d $MY_EXT 22 -i $EXT_IF -j ACCEPT
-$IPC -A output -p tcp \! -y -s $MY_EXT 22 -d $PEER_EXT -i $EXT_IF -j ACCEPT
-## to PEER
-$IPC -A input -p tcp \! -y -s $PEER_EXT 22 -d $MY_EXT -i $EXT_IF -j ACCEPT
-$IPC -A output -p tcp -s $MY_EXT -d $PEER_EXT 22 -i $EXT_IF -j ACCEPT
-
-# ipxtunnel
-$IPC -A input -p udp -s $PEER_INT 2005 -d $MY_INT 2005 -i $IPSEC_IF -j ACCEPT
-$IPC -A output -p udp -s $MY_INT 2005 -d $PEER_INT 2005 -i $IPSEC_IF -j ACCEPT
-
----------------- end of rc.firewall ----------------------
-
-To understand this we need to look on this scheme:
-
-           ++-----------------------<----------------------------+
-           || ipsec0                                             |
-           \/                                                    |
- eth0  +--------+    /---------/ yes  /---------/ yes +-----------------------+
------->| INPUT  |-->/ ?local? /----->/ ?IPsec? /----->| decrypt decapsulate |
- eth1  +--------+  /---------/      /---------/       +-----------------------+
-                       || no            || no
-                       \/               \/
-                  +----------+      +---------+        +-------+
-                  | routing  |      |  local  |        | local |
-                  | decision |      | deliver |        | send  |
-                  +----------+      +---------+        +-------+
-                       ||                                 ||
-                       \/                                 \/
-                   +---------+                       +----------+
-                   | forward |                       | routing  |
-                   +---------+                       | decision |
-                       ||                            +----------+
-                       ||                                  ||
-                       ++----------------<-----------------++
-                       ||
-                       \/
-                   +--------+ eth0
-                   | OUTPUT | eth1
-                   +--------+ ipsec0
-                       ||
-                       \/
-                   /---------/ yes +-----------------------+
-                  / ?IPsec? /----->| encrypt encapsulate |
-                 /---------/       +-----------------------+
-                      || no                    ||
-                      ||                       ||
-                      ||                       \/   eth0, eth1
-                      ++-----------------------++-------------->
-
-This explain how a packet traverse TCP/IP stack in IPsec capable kernel.
-
-FIX ME, please, if there are any errors
-
-Test the new firewall now.
-
-
-Now about IPX. I tried 3 programs for tunneling IPX: tipxd, SIB and ipxtunnel
-
-tipxd didn't send packets.. :(
-SIB and ipxtunnel worked fine :)
-With ipxtunnel there was a little problem. In sources there are an error.
-
---------------------- in main.c ------------------------
-<       bytes += p.len;
----
->       bytes += len;
---------------------------------------------------------
-
-After this FIX everything goes right...
-
-------------------- /etc/ipxtunnel.conf ----------------
-port    2005
-remote  192.168.101.97    2005
-interface eth1
---------------- end of /etc/ipxtunnel.conf -------------
-
-I use IPX tunnel between .1.1 and .2.10 so we don't need to encrypt nor
-authenticate encapsulated IPX packets, it is done with IPsec.
-
-If you don't wont to use iproute2 to change source IP you need to use SIB
-(it is able to bind local address) or establish tunnel between .0.1 and
-.0.10 (external IPs, you need to do encryption in the program, but it isn't
-strong).
-
-For now I'm using ipxtunnel.
-
-I think that's all for the moment. If there are any error, please e-mail me: 
-poltorak@df.ru . It would be cool if someone puts the scheme of TCP/IP in
-kernel and firewall example on FreeS/WAN's manual pages.
-
-PoltoS
-
-
-Contents -Previous -Next - - diff --git a/doc/web.html b/doc/web.html deleted file mode 100644 index 0c084d289..000000000 --- a/doc/web.html +++ /dev/null @@ -1,749 +0,0 @@ - - - -Introduction to FreeS/WAN - - - - -Contents -Previous -Next -
-

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 have been integrated into the FreeS/WAN - distribution. For a variety of reasons, those listed below have not.

-

Note that not all patches are a good idea.

- -

This is not to say that patches are necessarily bad, only that using - them requires some deliberation. For example, there might be perfectly - good reasons to add a specific cipher in your application: perhaps GOST - to comply with government standards in Eastern Europe, or AES for - performance benefits.

-

Current patches

-

Patches believed current::

- -

There is also one add-on that takes the form of a modified FreeS/WAN - distribution, rather than just patches to the standard distribution:

- -

Before using any of the above,, check the mailing - lists for news of newer versions and to see whether they have been - incorporated into more recent versions of FreeS/WAN.

-

Older patches

- -

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:

- -

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

- -

Other approaches to VPNs for Linux

- -

There is a list of - Linux VPN software in the - Linux Security Knowledge Base.

-

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

-

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

- -

IPsec in router products

-

All the major router vendors support IPsec, at least in some models.

- -

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:

- -

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:

- -

IPsec on network cards

-

Network cards with built-in IPsec acceleration are available from at - least Intel, 3Com and Redcreek.

-

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:

- -

IPsec for BSD Unix

- -

IPsec for other systems

- -

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:

- -

Interoperability test sites

- -

Linux links

-

Basic and tutorial Linux information

- -

General Linux sites

- -

Documentation

-

Nearly any Linux documentation you are likely to want can be found at - the Linux Documentation Project - or LDP.

- -

You may not need to go to the LDP to get this material. Most Linux - distributions include the HowTos on their CDs and several include the - Guides as well. Also, most of the Guides and some collections of HowTos - are available in book form from various publishers.

-

Much of the LDP material is also available in languages other than - English. See this - LDP page.

-

Advanced routing

-

The Linux IP stack has some new features in 2.4 kernels. Some HowTos - have been written:

- -

Security for Linux

-

See also the LDP material above.

- -

Linux firewalls

-

Our FreeS/WAN and firewalls document - includes links to several sets of - scripts known to work with FreeS/WAN.

-

Other information sources:

- -

Miscellaneous Linux information

- -

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

- -

Tutorials

- -

See also the interesting papers section - below.

-

Crypto and security standards

- -

Crypto quotes

-

There are several collections of cryptographic quotes on the net:

- -

Cryptography law and policy

-

Surveys of crypto law

- -

Organisations opposing crypto restrictions

- -

Other information on crypto policy

- -

See also our documentation section on the - history and politics of cryptography.

-

Cryptography technical information

-

Collections of crypto links

- -

Lists of online cryptography papers

- -

Particularly interesting papers

-

These papers emphasize important issues around the use of - cryptography, and the design and management of secure systems.

- -

Computer and network security

-

Security links

- -

Firewall links

- -

VPN links

- -

Security tools

- -

Links to home pages

-

David Wagner at Berkeley provides a set of links to - home pages of cryptographers, cypherpunks and computer security - people.

-
-Contents -Previous -Next - - diff --git a/programs/pluto/Makefile b/programs/pluto/Makefile index a11a755c0..d466d0209 100644 --- a/programs/pluto/Makefile +++ b/programs/pluto/Makefile @@ -12,7 +12,7 @@ # or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License # for more details. # -# RCSID $Id: Makefile,v 1.47 2007/01/11 21:47:13 as Exp $ +# RCSID $Id: Makefile,v 1.49 2007/01/29 08:27:19 as Exp $ # relative path to top directory of FreeS/WAN source # Note: referenced in ${FREESWANSRCDIR}/Makefile.inc @@ -90,13 +90,6 @@ else BINNAMEADNSIFNEEDED=$(BINNAMEADNS) endif -ifeq ($(USE_IPSECPOLICY),true) - IPSECPOLICY_FILES=rcv_info.c - IPSECPOLICY_DEFINES=-DIPSECPOLICY - IPSECPOLICY_LIBS=$(POLICYLIB) - IPSECPOLICY_OBJS=rcv_info.o -endif - ifeq ($(USE_KEYRR),true) KEYRR_DEFINES=-DUSE_KEYRR endif @@ -130,7 +123,7 @@ DEFINES = $(EXTRA_DEFINES) \ # libefence is a free memory allocation debugger # Solaris 2 needs -lsocket -lnsl LIBSPLUTO = $(OBJSGCRYPT) $(LIBDESLITE) $(FREESWANLIB) $(IPSECPOLICY_LIBS) -LIBSPLUTO+= -lgmp -lresolv # -lefence +LIBSPLUTO+= -lgmp -ldl -lresolv # -lefence ifeq ($(USE_VENDORID),true) @@ -167,7 +160,6 @@ ifeq ($(USE_SMARTCARD),true) ifdef PKCS11_DEFAULT_LIB DEFINES+= -DPKCS11_DEFAULT_LIB=$(PKCS11_DEFAULT_LIB) endif - LIBSPLUTO+= -ldl endif # This compile option activates the leak detective @@ -929,6 +921,7 @@ plutomain.o: ipsec_doi.h plutomain.o: ocsp.h plutomain.o: crl.h plutomain.o: fetch.h +plutomain.o: xauth.h plutomain.o: sha1.h plutomain.o: md5.h plutomain.o: crypto.h @@ -982,7 +975,6 @@ server.o: timer.h server.o: packet.h server.o: demux.h server.o: rcv_whack.h -server.o: rcv_info.h server.o: keys.h server.o: adns.h server.o: dnskey.h diff --git a/programs/pluto/constants.c b/programs/pluto/constants.c index f4aa9d5d1..322de74ac 100644 --- a/programs/pluto/constants.c +++ b/programs/pluto/constants.c @@ -11,7 +11,7 @@ * or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License * for more details. * - * RCSID $Id: constants.c,v 1.23 2007/01/10 00:36:19 as Exp $ + * RCSID $Id: constants.c,v 1.24 2007/01/21 08:35:47 as Exp $ */ /* @@ -707,7 +707,7 @@ static const char *const xauth_type_name[] = { }; enum_names xauth_type_names = - { XAUTH_TYPE_GENERIC, XAUTH_TYPE_SKEY, xauth_type_name, NULL}; + { XAUTH_TYPE_GENERIC, XAUTH_TYPE_SKEY, xauth_type_name, NULL}; /* From draft-beaulieu-ike-xauth */ static const char *const xauth_attr_tv_name[] = { @@ -725,6 +725,24 @@ enum_names xauth_attr_tv_names = { XAUTH_TYPE + ISAKMP_ATTR_AF_TV, XAUTH_STATUS + ISAKMP_ATTR_AF_TV, xauth_attr_tv_name, NULL }; +static const char *const unity_attr_name[] = { + "UNITY_BANNER", + "UNITY_SAVE_PASSWD", + "UNITY_DEF_DOMAIN", + "UNITY_SPLITDNS_NAME", + "UNITY_SPLIT_INCLUDE", + "UNITY_NATT_PORT", + "UNITY_LOCAL_LAN", + "UNITY_PFS", + "UNITY_FW_TYPE", + "UNITY_BACKUP_SERVERS", + "UNITY_DDNS_HOSTNAME", +}; + +enum_names unity_attr_names = + { UNITY_BANNER , UNITY_DDNS_HOSTNAME, unity_attr_name , &xauth_attr_tv_names }; + + static const char *const xauth_attr_name[] = { "XAUTH_USER_NAME", "XAUTH_USER_PASSWORD", @@ -738,7 +756,7 @@ static const char *const xauth_attr_name[] = { }; enum_names xauth_attr_names = - { XAUTH_USER_NAME , XAUTH_ANSWER, xauth_attr_name , &xauth_attr_tv_names }; + { XAUTH_USER_NAME , XAUTH_ANSWER, xauth_attr_name , &unity_attr_names }; static const char *const modecfg_attr_name[] = { "INTERNAL_IP4_ADDRESS", @@ -756,7 +774,6 @@ static const char *const modecfg_attr_name[] = { "INTERNAL_IP4_SUBNET", "SUPPORTED_ATTRIBUTES", "INTERNAL_IP6_SUBNET", - NULL }; enum_names modecfg_attr_names = diff --git a/programs/pluto/constants.h b/programs/pluto/constants.h index f18e93fed..cd0d6357d 100644 --- a/programs/pluto/constants.h +++ b/programs/pluto/constants.h @@ -1,3 +1,4 @@ + /* manifest constants * Copyright (C) 1997 Angelos D. Keromytis. * Copyright (C) 1998-2002 D. Hugh Redelmeier. @@ -12,7 +13,7 @@ * or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License * for more details. * - * RCSID $Id: constants.h,v 1.23 2007/01/10 00:36:19 as Exp $ + * RCSID $Id: constants.h,v 1.27 2007/01/29 08:27:53 as Exp $ */ #ifndef _CONSTANTS_H @@ -551,8 +552,8 @@ enum state_kind { #define IS_ISAKMP_SA_ESTABLISHED(s) ( \ (s) == STATE_MAIN_R3 \ || (s) == STATE_MAIN_I4 \ - || (s) == STATE_XAUTH_R3 \ || (s) == STATE_XAUTH_I2 \ + || (s) == STATE_XAUTH_R3 \ || (s) == STATE_MODE_CFG_R1 \ || (s) == STATE_MODE_CFG_I2 \ || (s) == STATE_MODE_CFG_I3 \ @@ -661,9 +662,8 @@ extern enum_names attr_msg_type_names; #define SUPPORTED_ATTRIBUTES 14 #define INTERNAL_IP6_SUBNET 15 -#define MODECFG_ROOF 16 - extern enum_names modecfg_attr_names; + /* XAUTH attribute values */ #define XAUTH_TYPE 16520 #define XAUTH_USER_NAME 16521 @@ -680,12 +680,33 @@ extern enum_names modecfg_attr_names; extern enum_names xauth_attr_names; +/* ISAKMP mode config attributes specific to the Unity vendor Id */ +#define UNITY_BANNER 28672 +#define UNITY_SAVE_PASSWD 28673 +#define UNITY_DEF_DOMAIN 28674 +#define UNITY_SPLITDNS_NAME 28675 +#define UNITY_SPLIT_INCLUDE 28676 +#define UNITY_NATT_PORT 28677 +#define UNITY_LOCAL_LAN 28678 +#define UNITY_PFS 28679 +#define UNITY_FW_TYPE 28680 +#define UNITY_BACKUP_SERVERS 28681 +#define UNITY_DDNS_HOSTNAME 28682 + +#define UNITY_BASE UNITY_BANNER + +extern enum_names unity_attr_names; + /* XAUTH authentication types */ #define XAUTH_TYPE_GENERIC 0 #define XAUTH_TYPE_CHAP 1 #define XAUTH_TYPE_OTP 2 #define XAUTH_TYPE_SKEY 3 +/* Values for XAUTH_STATUS */ +#define XAUTH_STATUS_FAIL 0 +#define XAUTH_STATUS_OK 1 + extern enum_names xauth_type_names; /* Exchange types diff --git a/programs/pluto/demux.c b/programs/pluto/demux.c index 304d790e3..71aa771c7 100644 --- a/programs/pluto/demux.c +++ b/programs/pluto/demux.c @@ -12,7 +12,7 @@ * or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License * for more details. * - * RCSID $Id: demux.c,v 1.17 2007/01/10 00:36:19 as Exp $ + * RCSID $Id: demux.c,v 1.18 2007/01/29 08:27:53 as Exp $ */ /* Ordering Constraints on Payloads @@ -461,7 +461,7 @@ static const struct state_microcode state_microcode_table[] = { , EVENT_RETRANSMIT, xauth_inI0 }, { STATE_XAUTH_R1, STATE_XAUTH_R2 - , SMF_ALL_AUTH | SMF_ENCRYPTED | SMF_REPLY + , SMF_ALL_AUTH | SMF_ENCRYPTED , P(ATTR) | P(HASH), P(VID), PT(HASH) , EVENT_RETRANSMIT, xauth_inR1 }, @@ -1572,6 +1572,15 @@ process_packet(struct msg_digest **mdp) set_cur_state(st); + /* the XAUTH_STATUS message might have a new msgid */ + if (st->st_state == STATE_XAUTH_I1) + { + init_phase2_iv(st, &md->hdr.isa_msgid); + new_iv_set = TRUE; + from_state = st->st_state; + break; + } + if (!IS_ISAKMP_SA_ESTABLISHED(st->st_state)) { loglog(RC_LOG_SERIOUS, "ModeCfg message is unacceptable because" diff --git a/programs/pluto/ike_alg.c b/programs/pluto/ike_alg.c index 456ca3a96..508e4ed2a 100644 --- a/programs/pluto/ike_alg.c +++ b/programs/pluto/ike_alg.c @@ -11,7 +11,7 @@ * or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License * for more details. * - * RCSID $Id: ike_alg.c,v 1.7 2007/01/10 00:36:19 as Exp $ + * RCSID $Id: ike_alg.c,v 1.8 2007/01/15 07:48:01 as Exp $ */ #include @@ -231,11 +231,12 @@ ike_alg_db_new(struct alg_info_ike *ai , lset_t policy) { struct db_context *db_ctx = NULL; struct ike_info *ike_info; - u_int ealg, halg, modp, eklen = 0; struct encrypt_desc *enc_desc; - bool is_xauth_server; + u_int ealg, halg, modp, eklen = 0; int i; + bool is_xauth_server = (policy & POLICY_XAUTH_SERVER) != LEMPTY; + if (!ai) { whack_log(RC_LOG_SERIOUS, "no IKE algorithms " @@ -305,8 +306,6 @@ ike_alg_db_new(struct alg_info_ike *ai , lset_t policy) db_attr_add_values(db_ctx, OAKLEY_GROUP_DESCRIPTION, modp); } - is_xauth_server = (policy & POLICY_XAUTH_SERVER) != LEMPTY; - if (policy & POLICY_XAUTH_RSASIG) { db_trans_add(db_ctx, KEY_IKE); diff --git a/programs/pluto/modecfg.c b/programs/pluto/modecfg.c index 01bab8c6e..620c595fb 100644 --- a/programs/pluto/modecfg.c +++ b/programs/pluto/modecfg.c @@ -2,7 +2,7 @@ * Copyright (C) 2001-2002 Colubris Networks * Copyright (C) 2003 Sean Mathews - Nu Tech Software Solutions, inc. * Copyright (C) 2003-2004 Xelerance Corporation - * Copyright (C) 2006 Andreas Steffen - Hochschule fuer Technik Rapperswil + * Copyright (C) 2006-2007 Andreas Steffen - Hochschule fuer Technik Rapperswil * * 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 @@ -14,7 +14,7 @@ * or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License * for more details. * - * RCSID $Id: modecfg.c,v 1.10 2007/01/10 00:36:19 as Exp $ + * RCSID $Id: modecfg.c,v 1.16 2007/01/29 08:27:54 as Exp $ * * This code originally written by Colubris Networks, Inc. * Extraction of patch and porting to 1.99 codebases by Xelerance Corporation @@ -43,12 +43,17 @@ #define MAX_XAUTH_TRIES 3 -#define SUPPORTED_ATTR_SET ( LELEM(INTERNAL_IP4_ADDRESS) \ - | LELEM(INTERNAL_IP4_NETMASK) \ - | LELEM(INTERNAL_IP4_DNS) \ - | LELEM(INTERNAL_IP4_NBNS) \ +#define SUPPORTED_ATTR_SET ( LELEM(INTERNAL_IP4_ADDRESS) \ + | LELEM(INTERNAL_IP4_NETMASK) \ + | LELEM(INTERNAL_IP4_DNS) \ + | LELEM(INTERNAL_IP4_NBNS) \ + | LELEM(APPLICATION_VERSION) \ ) +#define SUPPORTED_UNITY_ATTR_SET ( LELEM(UNITY_BANNER - UNITY_BASE) ) + +#define UNITY_BANNER_STR "Welcome to strongSwan - the Linux VPN Solution!\n" + /* * Addresses assigned (usually via ModeCfg) to the Initiator */ @@ -57,12 +62,16 @@ typedef struct internal_addr internal_addr_t; struct internal_addr { lset_t attr_set; + lset_t xauth_attr_set; + lset_t unity_attr_set; /* ModeCfg variables */ ip_address ipaddr; ip_address dns[2]; ip_address wins[2]; + char *unity_banner; + /* XAUTH variables */ u_int16_t xauth_type; xauth_t xauth_secret; @@ -76,9 +85,13 @@ static void init_internal_addr(internal_addr_t *ia) { ia->attr_set = LEMPTY; + ia->xauth_attr_set = LEMPTY; ia->xauth_secret.user_name = empty_chunk; ia->xauth_secret.user_password = empty_chunk; - ia->xauth_status = FALSE; + ia->xauth_type = XAUTH_TYPE_GENERIC; + ia->xauth_status = XAUTH_STATUS_FAIL; + ia->unity_attr_set = LEMPTY; + ia->unity_banner = NULL; anyaddr(AF_INET, &ia->ipaddr); anyaddr(AF_INET, &ia->dns[0]); @@ -93,8 +106,6 @@ init_internal_addr(internal_addr_t *ia) static void get_internal_addr(struct connection *c, internal_addr_t *ia) { - init_internal_addr(ia); - if (isanyaddr(&c->spd.that.host_srcip)) { /* not defined in connection - fetch it from LDAP */ @@ -115,10 +126,10 @@ get_internal_addr(struct connection *c, internal_addr_t *ia) c->spd.that.client.maskbits = 32; c->spd.that.has_client = TRUE; - ia->attr_set |= LELEM(INTERNAL_IP4_ADDRESS) | LELEM(INTERNAL_IP4_NETMASK); + ia->attr_set = LELEM(INTERNAL_IP4_ADDRESS) + | LELEM(INTERNAL_IP4_NETMASK); } - if (!isanyaddr(&ia->dns[0])) /* We got DNS addresses, send them */ ia->attr_set |= LELEM(INTERNAL_IP4_DNS); @@ -210,6 +221,8 @@ modecfg_build_msg(struct state *st, pb_stream *rbody int attr_type; int dns_idx, wins_idx; bool dont_advance; + bool is_xauth_attr_set = ia->xauth_attr_set != LEMPTY; + bool is_unity_attr_set = ia->unity_attr_set != LEMPTY; lset_t attr_set = ia->attr_set; attrh.isama_np = ISAKMP_NEXT_NONE; @@ -223,9 +236,26 @@ modecfg_build_msg(struct state *st, pb_stream *rbody dns_idx = 0; wins_idx = 0; - while (attr_set != 0) + while (attr_set != LEMPTY || is_xauth_attr_set || is_unity_attr_set) { + if (attr_set == LEMPTY) + { + if (is_xauth_attr_set) + { + attr_set = ia->xauth_attr_set; + attr_type = XAUTH_BASE; + is_xauth_attr_set = FALSE; + } + else + { + attr_set = ia->unity_attr_set; + attr_type = UNITY_BASE; + is_unity_attr_set = FALSE; + } + } + dont_advance = FALSE; + if (attr_set & 1) { const u_char *byte_ptr; @@ -343,6 +373,14 @@ modecfg_build_msg(struct state *st, pb_stream *rbody break; case XAUTH_STATUS: break; + case UNITY_BANNER: + if (ia->unity_banner != NULL) + { + out_raw(ia->unity_banner + , strlen(ia->unity_banner) + , &attrval, "UNITY_BANNER"); + } + break; default: plog("attempt to send unsupported mode cfg attribute %s." , enum_show(&modecfg_attr_names, attr_type)); @@ -353,10 +391,6 @@ modecfg_build_msg(struct state *st, pb_stream *rbody if (!dont_advance) { attr_type++; - if (attr_type == MODECFG_ROOF) - { - attr_type = XAUTH_BASE; - } attr_set >>= 1; } } @@ -454,28 +488,81 @@ modecfg_parse_attributes(pb_stream *attrs, internal_addr_t *ia) { initaddr((char *)(strattr.cur), 4, AF_INET, &ia->ipaddr); } - /* fall through to set attribute flags */ + /* fall through to set attribute flag */ case INTERNAL_IP4_NETMASK: case INTERNAL_IP4_DNS: case INTERNAL_IP4_SUBNET: case INTERNAL_IP4_NBNS: + case INTERNAL_ADDRESS_EXPIRY: + case INTERNAL_IP4_DHCP: + case INTERNAL_IP6_ADDRESS: + case INTERNAL_IP6_NETMASK: + case INTERNAL_IP6_DNS: + case INTERNAL_IP6_NBNS: + case INTERNAL_IP6_DHCP: + case SUPPORTED_ATTRIBUTES: + case INTERNAL_IP6_SUBNET: + ia->attr_set |= LELEM(attr_type); + break; + case APPLICATION_VERSION: + if (attr_len > 0) + { + DBG(DBG_PARSING, + DBG_log(" '%.*s'", attr_len, strattr.cur) + ) + } ia->attr_set |= LELEM(attr_type); break; case XAUTH_TYPE: ia->xauth_type = attr.isaat_lv; - ia->attr_set |= LELEM(attr_type - XAUTH_BASE + MODECFG_ROOF); + ia->xauth_attr_set |= LELEM(attr_type - XAUTH_BASE); break; case XAUTH_USER_NAME: setchunk(ia->xauth_secret.user_name, strattr.cur, attr_len); - ia->attr_set |= LELEM(attr_type - XAUTH_BASE + MODECFG_ROOF); + ia->xauth_attr_set |= LELEM(attr_type - XAUTH_BASE); break; case XAUTH_USER_PASSWORD: setchunk(ia->xauth_secret.user_password, strattr.cur, attr_len); - ia->attr_set |= LELEM(attr_type - XAUTH_BASE + MODECFG_ROOF); + ia->xauth_attr_set |= LELEM(attr_type - XAUTH_BASE); break; case XAUTH_STATUS: ia->xauth_status = attr.isaat_lv; - ia->attr_set |= LELEM(attr_type - XAUTH_BASE + MODECFG_ROOF); + ia->xauth_attr_set |= LELEM(attr_type - XAUTH_BASE); + break; + case XAUTH_MESSAGE: + if (attr_len > 0) + { + DBG(DBG_PARSING, + DBG_log(" '%.*s'", attr_len, strattr.cur) + ) + } + /* fall through to set attribute flag */ + case XAUTH_PASSCODE: + case XAUTH_CHALLENGE: + case XAUTH_DOMAIN: + case XAUTH_NEXT_PIN: + case XAUTH_ANSWER: + ia->xauth_attr_set |= LELEM(attr_type - XAUTH_BASE); + break; + case UNITY_DDNS_HOSTNAME: + if (attr_len > 0) + { + DBG(DBG_PARSING, + DBG_log(" '%.*s'", attr_len, strattr.cur) + ) + } + /* fall through to set attribute flag */ + case UNITY_BANNER: + case UNITY_SAVE_PASSWD: + case UNITY_DEF_DOMAIN: + case UNITY_SPLITDNS_NAME: + case UNITY_SPLIT_INCLUDE: + case UNITY_NATT_PORT: + case UNITY_LOCAL_LAN: + case UNITY_PFS: + case UNITY_FW_TYPE: + case UNITY_BACKUP_SERVERS: + ia->unity_attr_set |= LELEM(attr_type - UNITY_BASE); break; default: plog("unsupported ModeCfg attribute %s received." @@ -547,6 +634,7 @@ modecfg_send_request(struct state *st) internal_addr_t ia; init_internal_addr(&ia); + ia.attr_set = LELEM(INTERNAL_IP4_ADDRESS) | LELEM(INTERNAL_IP4_NETMASK); @@ -569,14 +657,24 @@ modecfg_inR0(struct msg_digest *md) struct state *const st = md->st; u_int16_t isama_id; internal_addr_t ia; + bool want_unity_banner; stf_status stat, stat_build; stat = modecfg_parse_msg(md, ISAKMP_CFG_REQUEST, &isama_id, &ia); if (stat != STF_OK) return stat; - + + want_unity_banner = (ia.unity_attr_set & LELEM(UNITY_BANNER - UNITY_BASE)) != LEMPTY; + + init_internal_addr(&ia); get_internal_addr(st->st_connection, &ia); + if (want_unity_banner) + { + ia.unity_banner = UNITY_BANNER_STR; + ia.unity_attr_set |= LELEM(UNITY_BANNER - UNITY_BASE); + } + plog("sending ModeCfg reply"); stat_build = modecfg_build_msg(st, &md->rbody @@ -624,9 +722,15 @@ modecfg_send_set(struct state *st) stf_status stat; internal_addr_t ia; + init_internal_addr(&ia); get_internal_addr(st->st_connection, &ia); - plog("sending ModeCfg set"); +#ifdef CISCO_QUIRKS + ia.unity_banner = UNITY_BANNER_STR; + ia.unity_attr_set |= LELEM(UNITY_BANNER - UNITY_BASE); +#endif + + plog("sending ModeCfg set"); st->st_state = STATE_MODE_CFG_R3; stat = modecfg_send_msg(st, ISAKMP_CFG_SET, &ia); if (stat == STF_OK) @@ -645,7 +749,7 @@ modecfg_inI0(struct msg_digest *md) struct state *const st = md->st; u_int16_t isama_id; internal_addr_t ia; - lset_t attr_set; + lset_t attr_set, unity_attr_set; stf_status stat, stat_build; plog("parsing ModeCfg set"); @@ -658,8 +762,10 @@ modecfg_inI0(struct msg_digest *md) /* prepare ModeCfg ack which sends zero length attributes */ attr_set = ia.attr_set; + unity_attr_set = ia.unity_attr_set; init_internal_addr(&ia); ia.attr_set = attr_set & SUPPORTED_ATTR_SET; + ia.unity_attr_set = unity_attr_set & SUPPORTED_UNITY_ATTR_SET; plog("sending ModeCfg ack"); @@ -707,8 +813,8 @@ xauth_send_request(struct state *st) internal_addr_t ia; init_internal_addr(&ia); - ia.attr_set = LELEM(XAUTH_USER_NAME - XAUTH_BASE + MODECFG_ROOF) - | LELEM(XAUTH_USER_PASSWORD - XAUTH_BASE + MODECFG_ROOF); + ia.xauth_attr_set = LELEM(XAUTH_USER_NAME - XAUTH_BASE) + | LELEM(XAUTH_USER_PASSWORD - XAUTH_BASE); plog("sending XAUTH request"); st->st_state = STATE_XAUTH_R1; @@ -730,6 +836,7 @@ xauth_inI0(struct msg_digest *md) u_int16_t isama_id; internal_addr_t ia; stf_status stat, stat_build; + bool xauth_type_present; plog("parsing XAUTH request"); @@ -738,18 +845,19 @@ xauth_inI0(struct msg_digest *md) return stat; /* check XAUTH attributes */ - if ((ia.attr_set & LELEM(XAUTH_TYPE - XAUTH_BASE + MODECFG_ROOF)) != LEMPTY - && ia.xauth_type != XAUTH_TYPE_GENERIC) + xauth_type_present = (ia.xauth_attr_set & LELEM(XAUTH_TYPE - XAUTH_BASE)) != LEMPTY; + + if (xauth_type_present && ia.xauth_type != XAUTH_TYPE_GENERIC) { plog("xauth type %s is not supported", enum_name(&xauth_type_names, ia.xauth_type)); stat = STF_FAIL; } - else if ((ia.attr_set & LELEM(XAUTH_USER_NAME - XAUTH_BASE + MODECFG_ROOF)) == LEMPTY) + else if ((ia.xauth_attr_set & LELEM(XAUTH_USER_NAME - XAUTH_BASE)) == LEMPTY) { plog("user name attribute is missing in XAUTH request"); stat = STF_FAIL; } - else if ((ia.attr_set & LELEM(XAUTH_USER_PASSWORD - XAUTH_BASE + MODECFG_ROOF)) == LEMPTY) + else if ((ia.xauth_attr_set & LELEM(XAUTH_USER_PASSWORD - XAUTH_BASE)) == LEMPTY) { plog("user password attribute is missing in XAUTH request"); stat = STF_FAIL; @@ -779,13 +887,15 @@ xauth_inI0(struct msg_digest *md) , ia.xauth_secret.user_password.len , ia.xauth_secret.user_password.ptr) ) - ia.attr_set = LELEM(XAUTH_USER_NAME - XAUTH_BASE + MODECFG_ROOF) - | LELEM(XAUTH_USER_PASSWORD - XAUTH_BASE + MODECFG_ROOF); + ia.xauth_attr_set = LELEM(XAUTH_USER_NAME - XAUTH_BASE) + | LELEM(XAUTH_USER_PASSWORD - XAUTH_BASE); + if (xauth_type_present) + ia.xauth_attr_set |= LELEM(XAUTH_TYPE - XAUTH_BASE); } else { - ia.attr_set = LELEM(XAUTH_STATUS - XAUTH_BASE + MODECFG_ROOF); - ia.xauth_status = FALSE; + ia.xauth_attr_set = LELEM(XAUTH_STATUS - XAUTH_BASE); + ia.xauth_status = XAUTH_STATUS_FAIL; } plog("sending XAUTH reply"); @@ -800,6 +910,7 @@ xauth_inI0(struct msg_digest *md) if (stat == STF_OK) { st->st_xauth.started = TRUE; + st->st_msgid = 0; return STF_OK; } else @@ -834,7 +945,7 @@ xauth_inR1(struct msg_digest *md) return stat; /* did the client return an XAUTH FAIL status? */ - if ((ia.attr_set & LELEM(XAUTH_STATUS - XAUTH_BASE + MODECFG_ROOF)) != LEMPTY) + if ((ia.xauth_attr_set & LELEM(XAUTH_STATUS - XAUTH_BASE)) != LEMPTY) { plog("received FAIL status in XAUTH reply"); @@ -844,12 +955,12 @@ xauth_inR1(struct msg_digest *md) } /* check XAUTH reply */ - if ((ia.attr_set & LELEM(XAUTH_USER_NAME - XAUTH_BASE + MODECFG_ROOF)) == LEMPTY) + if ((ia.xauth_attr_set & LELEM(XAUTH_USER_NAME - XAUTH_BASE)) == LEMPTY) { plog("user name attribute is missing in XAUTH reply"); st->st_xauth.status = FALSE; } - else if ((ia.attr_set & LELEM(XAUTH_USER_PASSWORD - XAUTH_BASE + MODECFG_ROOF)) == LEMPTY) + else if ((ia.xauth_attr_set & LELEM(XAUTH_USER_PASSWORD - XAUTH_BASE)) == LEMPTY) { plog("user password attribute is missing in XAUTH reply"); st->st_xauth.status = FALSE; @@ -873,16 +984,13 @@ xauth_inR1(struct msg_digest *md) /* prepare XAUTH set which sends the authentication status */ init_internal_addr(&ia); - ia.attr_set = LELEM(XAUTH_STATUS - XAUTH_BASE + MODECFG_ROOF); - ia.xauth_status = st->st_xauth.status; + ia.xauth_attr_set = LELEM(XAUTH_STATUS - XAUTH_BASE); + ia.xauth_status = (st->st_xauth.status)? XAUTH_STATUS_OK : XAUTH_STATUS_FAIL; plog("sending XAUTH status:"); - stat_build = modecfg_build_msg(st, &md->rbody - , ISAKMP_CFG_SET - , &ia - , isama_id); - if (stat_build != STF_OK) + stat_build = modecfg_send_msg(st, ISAKMP_CFG_SET, &ia); + if (stat_build != STF_OK) return stat_build; return STF_OK; } diff --git a/programs/pluto/plutomain.c b/programs/pluto/plutomain.c index 613f8d50f..d7e9d8a2c 100644 --- a/programs/pluto/plutomain.c +++ b/programs/pluto/plutomain.c @@ -12,7 +12,7 @@ * or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License * for more details. * - * RCSID $Id: plutomain.c,v 1.18 2007/01/14 10:11:56 as Exp $ + * RCSID $Id: plutomain.c,v 1.19 2007/01/29 08:27:19 as Exp $ */ #include @@ -531,19 +531,6 @@ main(int argc, char **argv) } } -#ifdef IPSECPOLICY - /* create info socket. */ - { - err_t ugh = init_info_socket(); - - if (ugh != NULL) - { - fprintf(stderr, "pluto: %s", ugh); - exit_pluto(1); - } - } -#endif - /* If not suppressed, do daemon fork */ if (fork_desired) @@ -595,12 +582,10 @@ main(int argc, char **argv) int i; for (i = getdtablesize() - 1; i >= 0; i--) /* Bad hack */ - if ((!log_to_stderr || i != 2) -#ifdef IPSECPOLICY - && i != info_fd -#endif - && i != ctl_fd) + { + if ((!log_to_stderr || i != 2) && i != ctl_fd) close(i); + } /* make sure that stdin, stdout, stderr are reserved */ if (open("/dev/null", O_RDONLY) != 0) diff --git a/programs/pluto/rcv_info.c b/programs/pluto/rcv_info.c deleted file mode 100644 index 1f6127830..000000000 --- a/programs/pluto/rcv_info.c +++ /dev/null @@ -1,308 +0,0 @@ -/* info/policy communicating routines - * Copyright (C) 2003 Michael Richardson - * - * 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: rcv_info.c,v 1.2 2004/04/01 18:44:38 as Exp $ - */ - -#include -#include -#include -#include -#include -#include -#include -#include -#include -#include -#include -#include /* missing from on old systems */ -#include - -#include - -#include "constants.h" -#include "defs.h" -#include "id.h" -#include "connections.h" -#include "foodgroups.h" -#include "whack.h" /* needs connections.h */ -#include "packet.h" -#include "demux.h" /* needs packet.h */ -#include "state.h" -#include "ipsec_doi.h" /* needs demux.h and state.h */ -#include "kernel.h" -#include "rcv_whack.h" -#include "log.h" -#include "keys.h" -#include "adns.h" /* needs */ -#include "dnskey.h" /* needs keys.h and adns.h */ -#include "server.h" - -#include "freeswan/ipsec_policy.h" -#include "rcv_info.h" - -/* global */ -int info_fd = -1; - -static void -info_lookuphostpair(struct ipsec_policy_cmd_query *ipcq) -{ - struct connection *c; - struct state *p1st, *p2st; - - - /* default result: no crypto */ - ipcq->strength = IPSEC_PRIVACY_NONE; - ipcq->bandwidth = IPSEC_QOS_WIRESPEED; - ipcq->credential_count = 0; - -#ifdef DEBUG - { - char sstr[ADDRTOT_BUF], dstr[ADDRTOT_BUF]; - - addrtot(&ipcq->query_local, 0, sstr, sizeof(sstr)); - addrtot(&ipcq->query_remote, 0, dstr, sizeof(dstr)); - DBG_log("info request for %s -> %s", sstr, dstr); - } -#endif - - /* okay, look up what connection handles this ip pair */ - - c = find_connection_for_clients(NULL, - &ipcq->query_local, - &ipcq->query_remote); - if (c == NULL) - { - /* try reversing it */ - c = find_connection_for_clients(NULL, - &ipcq->query_remote, - &ipcq->query_local); - if (c != NULL) - { - ip_address tmp; - tmp = ipcq->query_local; - ipcq->query_local = ipcq->query_remote; - ipcq->query_remote = tmp; - } - } - - if (c == NULL) - { -#ifdef DEBUG - DBG_log("no connection found"); -#endif - return; /* no crypto */ - } - - if (c->newest_ipsec_sa == SOS_NOBODY) - { - ip_subnet us, them; - - DBG_log("connection %s found, no ipsec state, looking again", c->name); - addrtosubnet(&ipcq->query_local, &us); - addrtosubnet(&ipcq->query_remote, &them); - c = find_client_connection(c, &us, &them); - - if (c == NULL) - return; /* no crypto */ - } - - DBG_log("connection %s[%ld] with state %u" - , c->name, c->instance_serial - , (unsigned int)c->newest_ipsec_sa); - - if (c->newest_ipsec_sa == SOS_NOBODY) - return; /* no crypto */ - - /* we found a connection, try to lookup the state */ - p2st = state_with_serialno(c->newest_ipsec_sa); - - p1st = find_phase1_state(c, ISAKMP_SA_ESTABLISHED_STATES); - - if (p1st == NULL || p2st == NULL) - { - DBG_log("connection %s[%ld] has missing states %s %s" - , c->name, c->instance_serial - , (p1st ? "phase1" : "") - , (p2st ? "phase1" : "")); - return; /* no crypto */ - } - - /* if we have AH present, then record minimal info */ - if (p2st->st_ah.present) - { - ipcq->strength = IPSEC_PRIVACY_INTEGRAL; - ipcq->auth_detail = p2st->st_esp.attrs.auth; - } - - if (p2st->st_esp.present) - { - /* - * XXX-mcr Please do not shout at me about relative strengths - * here. I'm not a cryptographer. I just diddle bits. - */ - switch (p2st->st_esp.attrs.transid) - { - case ESP_NULL: - /* actually, do not change it if we set it from AH */ - break; - - case ESP_DES: - case ESP_DES_IV64: - case ESP_DES_IV32: - case ESP_RC4: - ipcq->strength = IPSEC_PRIVACY_ROT13; - break; - - case ESP_RC5: - case ESP_IDEA: - case ESP_CAST: - case ESP_BLOWFISH: - case ESP_3DES: - ipcq->strength = IPSEC_PRIVACY_PRIVATE; - ipcq->bandwidth = IPSEC_QOS_VOIP; - break; - - case ESP_3IDEA: - ipcq->strength = IPSEC_PRIVACY_STRONG; - ipcq->bandwidth = IPSEC_QOS_INTERACTIVE; - break; - - case ESP_AES: - ipcq->strength = IPSEC_PRIVACY_STRONG; - ipcq->bandwidth = IPSEC_QOS_FTP; - break; - } - ipcq->esp_detail = p2st->st_esp.attrs.transid; - } - - if (p2st->st_ipcomp.present) - ipcq->comp_detail = p2st->st_esp.attrs.transid; - - /* now! the credentails that were used */ - /* for the moment we only have 1 credential, the DNS name, - * because the DNS servers do not return the chain of SIGs yet - */ - - if(!c->spd.this.key_from_DNS_on_demand) - { - /* the key didn't come from the DNS in some way, - * so it must have been loaded locally. - */ - ipcq->credential_count = 1; - ipcq->credentials[0].ii_type = c->spd.this.id.kind; - ipcq->credentials[0].ii_format = CERT_RAW_RSA; - } - -#if 0 - switch (c->spd.id.kind) - { - case ID_IPV4_ADDR: - } - if (c->gw_info == NULL) - { - plog("rcv_info: connection %s had NULL gw_info.", c->name); - return - } -#endif - - ipcq->credential_count = 1; - - /* pull credentials out of gw_info */ - - switch (p1st->st_peer_pubkey->dns_auth_level) - { - case DAL_UNSIGNED: - case DAL_NOTSEC: - /* these seem to be the same for this purpose */ - ipcq->credentials[0].ii_type = p1st->st_peer_pubkey->id.kind; - ipcq->credentials[0].ii_type = CERT_NONE; - idtoa(&p1st->st_peer_pubkey->id - , ipcq->credentials[0].ii_credential.ipsec_dns_signed.fqdn - , sizeof(ipcq->credentials[0].ii_credential.ipsec_dns_signed.fqdn)); - break; - - case DAL_SIGNED: - ipcq->credentials[0].ii_type = p1st->st_peer_pubkey->id.kind; - ipcq->credentials[0].ii_format = CERT_DNS_SIGNED_KEY; - idtoa(&p1st->st_peer_pubkey->id - , ipcq->credentials[0].ii_credential.ipsec_dns_signed.fqdn - , sizeof(ipcq->credentials[0].ii_credential.ipsec_dns_signed.fqdn)); - - if (p1st->st_peer_pubkey->dns_sig != NULL) - { - strncat(ipcq->credentials[0].ii_credential.ipsec_dns_signed.dns_sig - , p1st->st_peer_pubkey->dns_sig - , sizeof(ipcq->credentials[0].ii_credential.ipsec_dns_signed.dns_sig)); - } - break; - - case DAL_LOCAL: - ipcq->credentials[0].ii_type = p1st->st_peer_pubkey->id.kind; - ipcq->credentials[0].ii_format = CERT_RAW_RSA; - idtoa(&p1st->st_peer_pubkey->id - , ipcq->credentials[0].ii_credential.ipsec_raw_key.id_name - , sizeof(ipcq->credentials[0].ii_credential.ipsec_raw_key.id_name)); - break; - } -} - -/* - * Handle an info/policy request. - * - * For now, we close the socket after answering the request. - * - */ -void -info_handle(int infoctlfd) -{ - struct sockaddr_un info_client_addr; - int info_addr_len = sizeof(info_client_addr); - /* Note: actual value in n should fit in int. To print, cast to int. */ - int infofd; - err_t err; - struct ipsec_policy_cmd_query ipcq; - - infofd = accept(infoctlfd, (struct sockaddr *)&info_client_addr - , &info_addr_len); - - if (infofd < 0) - { - log_errno((e, "accept() failed in info_handle()")); - return; - } - - err = ipsec_policy_readmsg(infofd, (unsigned char *)&ipcq, sizeof(ipcq)); - - if (err != NULL) - { - log_errno((e, "readmsg said: %s", err)); - close(infofd); - return; - } - - switch (ipcq.head.ipm_msg_type) - { - case IPSEC_CMD_QUERY_HOSTPAIR: - info_lookuphostpair(&ipcq); - write(infofd, &ipcq, ipcq.head.ipm_msg_len); - break; - - default: - plog("got unimplemented msg type: %d", ipcq.head.ipm_msg_type); - break; - } - - /* for now, close the socket */ - close(infofd); -} diff --git a/programs/pluto/rcv_info.h b/programs/pluto/rcv_info.h deleted file mode 100644 index b5eaef219..000000000 --- a/programs/pluto/rcv_info.h +++ /dev/null @@ -1,18 +0,0 @@ -/* whack communicating routines - * Copyright (C) 2003 Michael Richardson - * - * 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: rcv_info.h,v 1.1 2004/03/15 20:35:29 as Exp $ - */ - -#include "freeswan/ipsec_policy.h" -extern void info_handle(int infoctlfd); diff --git a/programs/pluto/server.c b/programs/pluto/server.c index 30251138e..17b70eba4 100644 --- a/programs/pluto/server.c +++ b/programs/pluto/server.c @@ -12,7 +12,7 @@ * or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License * for more details. * - * RCSID $Id: server.c,v 1.9 2005/09/09 14:15:35 as Exp $ + * RCSID $Id: server.c,v 1.10 2007/01/29 08:27:19 as Exp $ */ #include @@ -54,7 +54,6 @@ #include "packet.h" #include "demux.h" /* needs packet.h */ #include "rcv_whack.h" -#include "rcv_info.h" #include "keys.h" #include "adns.h" /* needs */ #include "dnskey.h" /* needs keys.h and adns.h */ @@ -128,50 +127,6 @@ delete_ctl_socket(void) unlink(ctl_addr.sun_path); } -#ifdef IPSECPOLICY -/* Initialize the info socket. - */ -err_t -init_info_socket(void) -{ - err_t failed = NULL; - - delete_info_socket(); /* preventative medicine */ - info_fd = socket(AF_UNIX, SOCK_STREAM, 0); - if (info_fd == -1) - failed = "create"; - else if (fcntl(info_fd, F_SETFD, FD_CLOEXEC) == -1) - failed = "fcntl FD+CLOEXEC"; - else if (setsockopt(info_fd, SOL_SOCKET, SO_REUSEADDR, (const void *)&on, sizeof(on)) < 0) - failed = "setsockopt"; - else - { - /* this socket should be openable by all proceses */ - mode_t ou = umask(0); - - if (bind(info_fd, (struct sockaddr *)&info_addr - , offsetof(struct sockaddr_un, sun_path) + strlen(info_addr.sun_path)) < 0) - failed = "bind"; - umask(ou); - } - - /* 64 might be big enough, and the system may limit us anyway. - */ - if (failed == NULL && listen(info_fd, 64) < 0) - failed = "listen() on"; - - return failed == NULL? NULL : builddiag("could not %s info socket: %d %s" - , failed, errno, strerror(errno)); -} - -void -delete_info_socket(void) -{ - unlink(info_addr.sun_path); -} -#endif /* IPSECPOLICY */ - - bool listening = FALSE; /* should we pay attention to IKE messages? */ struct iface *interfaces = NULL; /* public interfaces */ @@ -885,11 +840,6 @@ call_server(void) FD_ZERO(&readfds); FD_ZERO(&writefds); FD_SET(ctl_fd, &readfds); -#ifdef IPSECPOLICY - FD_SET(info_fd, &readfds); - if (maxfd < info_fd) - maxfd = info_fd; -#endif /* the only write file-descriptor of interest */ if (adns_qfd != NULL_FD && unsent_ADNS_queries) @@ -1039,19 +989,6 @@ call_server(void) ndes--; } -#ifdef IPSECPOLICY - if (FD_ISSET(info_fd, &readfds)) - { - passert(ndes > 0); - DBG(DBG_CONTROL, - DBG_log(BLANK_FORMAT); - DBG_log("*received info message")); - info_handle(info_fd); - passert(GLOBALS_ARE_RESET()); - ndes--; - } -#endif - passert(ndes == 0); } } diff --git a/programs/pluto/vendor.c b/programs/pluto/vendor.c index 3e2e0768a..4ca3adffc 100644 --- a/programs/pluto/vendor.c +++ b/programs/pluto/vendor.c @@ -11,7 +11,7 @@ * or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License * for more details. * - * RCSID $Id: vendor.c,v 1.43 2007/01/10 00:31:36 as Exp $ + * RCSID $Id: vendor.c,v 1.45 2007/01/20 18:01:13 as Exp $ */ #include @@ -208,8 +208,10 @@ static struct vid_struct _vid_tab[] = { DEC_MD5_VID(STRONGSWAN_4_0_4, "strongSwan 4.0.4") DEC_MD5_VID(STRONGSWAN_4_0_5, "strongSwan 4.0.5") DEC_MD5_VID(STRONGSWAN_4_0_6, "strongSwan 4.0.6") + DEC_MD5_VID(STRONGSWAN_4_0_7, "strongSwan 4.0.7") - DEC_MD5_VID(STRONGSWAN, "strongSwan 2.8.1") + DEC_MD5_VID(STRONGSWAN, "strongSwan 2.8.2") + DEC_MD5_VID(STRONGSWAN_2_8_1, "strongSwan 2.8.1") DEC_MD5_VID(STRONGSWAN_2_8_0, "strongSwan 2.8.0") DEC_MD5_VID(STRONGSWAN_2_7_3, "strongSwan 2.7.3") DEC_MD5_VID(STRONGSWAN_2_7_2, "strongSwan 2.7.2") diff --git a/programs/pluto/vendor.h b/programs/pluto/vendor.h index 060311b92..2649c5b2f 100644 --- a/programs/pluto/vendor.h +++ b/programs/pluto/vendor.h @@ -11,7 +11,7 @@ * or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License * for more details. * - * RCSID $Id: vendor.h,v 1.38 2007/01/10 00:31:36 as Exp $ + * RCSID $Id: vendor.h,v 1.40 2007/01/20 18:01:13 as Exp $ */ #ifndef _VENDOR_H_ @@ -82,6 +82,7 @@ enum known_vendorid { VID_STRONGSWAN_2_7_2 = 61, VID_STRONGSWAN_2_7_3 = 62, VID_STRONGSWAN_2_8_0 = 63, + VID_STRONGSWAN_2_8_1 = 64, VID_STRONGSWAN_4_0_0 = 70, VID_STRONGSWAN_4_0_1 = 71, @@ -90,6 +91,7 @@ enum known_vendorid { VID_STRONGSWAN_4_0_4 = 74, VID_STRONGSWAN_4_0_5 = 75, VID_STRONGSWAN_4_0_6 = 76, + VID_STRONGSWAN_4_0_7 = 77, /* 101 - 200 : NAT-Traversal */ VID_NATT_STENBERG_01 =101, diff --git a/programs/starter/starterwhack.c b/programs/starter/starterwhack.c index b4bf2fb9d..cb3e02172 100644 --- a/programs/starter/starterwhack.c +++ b/programs/starter/starterwhack.c @@ -11,13 +11,13 @@ * or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License * for more details. * - * RCSID $Id: starterwhack.c,v 1.19 2006/10/19 15:02:46 as Exp $ + * RCSID $Id: starterwhack.c,v 1.20 2007/01/18 21:16:45 as Exp $ */ #include #include #include -#include +#include #include #include diff --git a/testing/INSTALL b/testing/INSTALL index 033291aa5..8d0dc2a3b 100644 --- a/testing/INSTALL +++ b/testing/INSTALL @@ -71,7 +71,7 @@ are required for the strongSwan testing environment: * The latest strongSwan distribution - http://download.strongswan.org/strongswan-2.8.1.tar.gz + http://download.strongswan.org/strongswan-2.8.2.tar.gz 3. Creating the environment @@ -146,5 +146,5 @@ README document. ----------------------------------------------------------------------------- -This file is RCSID $Id: INSTALL,v 1.44 2007/01/14 12:17:50 as Exp $ +This file is RCSID $Id: INSTALL,v 1.45 2007/01/29 08:29:41 as Exp $ diff --git a/testing/hosts/winnetou/etc/conf.d/apache2 b/testing/hosts/winnetou/etc/conf.d/apache2 index 0c96fe77f..cfb80a7d9 100644 --- a/testing/hosts/winnetou/etc/conf.d/apache2 +++ b/testing/hosts/winnetou/etc/conf.d/apache2 @@ -1,6 +1,6 @@ # Copyright 1999-2004 Gentoo Foundation # Distributed under the terms of the GNU General Public License v2 -# $Header: /root/strongswan/testing/hosts/winnetou/etc/conf.d/apache2,v 1.2 2006/01/06 12:21:21 as Exp $ +# $Header: /var/cvsroot/strongswan/testing/hosts/winnetou/etc/conf.d/apache2,v 1.2 2006/01/06 12:21:21 as Exp $ # Config file for /etc/init.d/apache2 diff --git a/testing/hosts/winnetou/etc/init.d/slapd b/testing/hosts/winnetou/etc/init.d/slapd index 6e3130e90..d4c070b33 100755 --- a/testing/hosts/winnetou/etc/init.d/slapd +++ b/testing/hosts/winnetou/etc/init.d/slapd @@ -1,7 +1,7 @@ #!/sbin/runscript # Copyright 1999-2004 Gentoo Foundation # Distributed under the terms of the GNU General Public License v2 -# $Header: /root/strongswan/testing/hosts/winnetou/etc/init.d/slapd,v 1.2 2005/05/31 14:04:43 as Exp $ +# $Header: /var/cvsroot/strongswan/testing/hosts/winnetou/etc/init.d/slapd,v 1.2 2005/05/31 14:04:43 as Exp $ depend() { need net diff --git a/testing/testing.conf b/testing/testing.conf index d59333cba..3d1228503 100755 --- a/testing/testing.conf +++ b/testing/testing.conf @@ -14,7 +14,7 @@ # or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License # for more details. # -# RCSID $Id: testing.conf,v 1.58 2007/01/14 12:18:31 as Exp $ +# RCSID $Id: testing.conf,v 1.59 2007/01/29 08:29:41 as Exp $ # Root directory of testing UMLTESTDIR=~/strongswan-testing @@ -34,7 +34,7 @@ KERNELCONFIG=$UMLTESTDIR/.config-2.6.18 UMLPATCH=$UMLTESTDIR/uml_jmpbuf-2.6.18.patch.bz2 # Bzipped source of strongSwan -STRONGSWAN=$UMLTESTDIR/strongswan-2.8.1.tar.bz2 +STRONGSWAN=$UMLTESTDIR/strongswan-2.8.2.tar.bz2 # strongSwan compile options (use "yes" or "no") USE_LIBCURL="yes" -- cgit v1.2.3