[Openswan dev] First pass README update

[Harald Jenny]

On Wed, Oct 13, 2010 at 02:15:52PM -0400, Paul Wouters wrote:
> 
> 
> 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/

Hmmmm but that's rather a little bit unclean...

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

Perhaps a good idea.

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

Sound ok to me too.

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

Why?

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

This is a very good idea!

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

Yes

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

*ggg*

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

Isn't that true for every one?

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

Well it's the end of the sentence... but it may irritate people.

> 
> Paul

Harald