[Openswan dev] First pass README update

[Paul Wouters]

My comments :)

> #########################################################################
> #            Openswan 2.X Release Notes
> #########################################################################
> ************ See docs/RELEASE-NOTES.txt for more information ************
>
> Openswan is an IPsec implementation for Linux. It has support for most
> of the extensions (RFC + IETF drafts) related to IPsec, including
> IKEv2, X.509 Digital Certificates, NAT Traversal, and many others.
>
> Openswan was originally based on FreeS/WAN 2.04 CVS, along with some
> minor bug fixes from 2.05 and 2.06.  See CREDITS for the history.

I would probably say FreeS/WAN 2.04 CVS with the X.509 Patch from Andreas
and the NAT-T patch from Arkoon networks. I know Andreas doesn't like to
credit us for anything, but we try give proper credits.

> Download it from http://www.openswan.org/code

or ftp://ftp.openswan.org/openswan/

> 1. libgmp + libgmp-devel headers.  (GNU Math Precision Library)

Maybe explain this is gmp/gmp-devel on rpm and libgmp3/libgmp3-devel on apt distros?

> 2. gawk, flex and bison (usually included in all distributions)

Perhaps add runtime requirements too? iproute2, iptables, if used on embedded
systems a busybox with enough features enabled to get a mostly full /bin/sh

> #########################################################################
> # HOW TO INSTALL on Kernel 2.6 (And Kernels with 2.6 IPsec backport)
> #########################################################################
>
> NETKEY (Native linux IPsec stack)
> ---------------------------------
>
> To use Openswan with the linux native (builtin) IPsec stack,  then the
> following steps should be all that are needed. Please use at least kernel
> version 2.6.6, as prior versions of the kernel have serious bugs in the

I would say 2.6.9 as the earliest version.

> native IPsec stack.  From the openswan directory:
>
>    make programs
>    sudo make install

This reminds me we should fix not creating man pages as root in the install phase......

> Note: The ipsec-tools package is no longer needed. Instead iproute2 >= 2.6.8
> is required. For backported kernels, setkey and thus ipsec-tools might still
> be required. Run 'ipsec verify' to determine if your system has either one
> of the requirements.

of course "ipsec verify" requires perl (and I'd like to redo it in python)

> KLIPS (Openswan IPsec stack)
> ----------------------------
>
> To use the Openswan KLIPS IPsec stack (ipsec0 devices) for Linux
> Kernels 2.6.23 and higher, the following steps should work.  From the
> openswan directory:
>
>    make programs
>    make KERNELSRC=/lib/modules/`uname -r`/build module
>    sudo make KERNELSRC=/lib/modules/`uname -r`/build install minstall
>
> For Linux 2.6 Kernels before 2.6.23, the kernel requires patching if
> NAT-T support is required.

Perhaps say "including linux 2.4 kernels"

>    Add NAT-T support.
>
>        NAT-T support needs to patch the kernel and build a new bzImage.
>        From the Openswan source directory:
>
>          make KERNELSRC=/lib/modules/`uname -r`/build nattpatch | \
>            (cd /usr/src/linux-2.6 && patch -p1 && make bzImage)

Add the bit about make sarefpatch here for KLIPSNG (Mast) support with SAref tracking?

Premade patches for some (distro kernels) are found in patches/kernel/
Recommended kernel is 2.6.32 and up. Documentation on SAref/MAST can be found in
docs/HACKING/Mast* and doc/klips/mast.xml. To understand what SAref tracking does,
take a look at doc/ipsecsaref.png and the overlapip= entry in the ipsec.conf man page.

>        Note: Build and install kernel as normal, as you have modified
>        the TCP/IP stack in the kernel, so it needs to be recompiled and
>        installed.
>
>          eg: cd /usr/src/linux-2.6 && make dep bzImage install
>
>        See your distribution documentation on how to install a new kernel
>
>    From the openswan directory:
>
>        make programs
>        make KERNELSRC=/lib/modules/`uname -r`/build module
>        sudo make KERNELSRC=/lib/modules/`uname -r`/build install minstall

Stacks can be switched at runtime using protostack=<klips|netkey|mast>

>    For OCF HW offloading support, you need a patched kernel
>    See: http://ocf-linux.sourceforge.net/
>
> #########################################################################
> # HOW TO INSTALL on Linux Kernel 2.4 systems
> #########################################################################
>
> The following instructions assume the kernel source tree is in
> /usr/src/linux-2.4.  If this isn't the case, simply change the
> parameters in the instructions below.
>
> 1)  Uncompress linux-2.#.#.tar.bz2 in /usr/src (or elsewhere), build a
>    normal working kernel.  This ensures any compiliation problems
>    that occur are isolated and resolved *before* any Openswan patches
>    are applied to the kernel.
>
> 2)  If you want NAT-T support, you need to patch your kernel and build
>    a new bzImage.  From the Openswan source directory:
>
>    make KERNELSRC=/usr/src/linux-2.4 nattpatch | \
>        (cd /usr/src/linux-2.4 && patch -p1 && make bzImage)
>
>    Note: Build and install kernel as normal, as you have modified
>    the TCP/IP stack in the kernel, so it needs to be recompiled and
>    installed.
>
>        eg: cd /usr/src/linux-2.4 && make dep bzImage install

The only difference here is the "make dep" step right? Why not integrate in the
text above to avoid repeats?

> 3)  From the openswan source directory, build the userland tools, and
>    ipsec.o kernel module:

well the one other diff is ipsec.o vs ipsec.ko I guess.

> Bugs with the package can be filed into our Mantis system, at
> http://bugs.openswan.org

redmine :)

> #########################################################################
> # SECURITY HOLES
> #########################################################################
>
> Hopefully none :-)  If you find one, please email vuln at xelerance.com with
> details.  Please use GPG (finger vuln at xelerance.com for GPG key) for this.

I'd say:

All security vulnerabilities found that require public disclosure will receive
proper CVE tracking numbers (see http://mitre.org/) and co-ordinated via the
vendor-sec mailing list. A complete list of known security vulnerabilities is
available at: http://www.openswan.org/security/

> #########################################################################
> # DEVELOPMENT
> #########################################################################
>
> Those interested in the development, patches, beta releases of Openswan
> can join the development mailing list (http://lists.openswan.org -
> dev at lists.openswan.org) or join the development team on IRC in
> #openswan-dev on irc.freenode.net

For those who want to track things a bit more closely, the commits@ mailinglist
will mail all the commit messages.

> #########################################################################
> # DOCUMENTATION
> #########################################################################
>
> The most up to date docs are at http://wiki.openswan.org.

No trailing dots on urls please :)

Paul