#########################################################################
#            KLIPS Libreswan 3.X Release Notes
#########################################################################

KLIPS is an alternative IPsec stack for the Linux kernel. It features:

- ipsecX devices for easy firewalling and tcpdumping
- OCF support (crypto hardware offload) with many hardware drivers
- SAref tracking for IPsec transport mode connections with NAT.
- First+Last packet caching
- Extensive debugging output (enabled via ipsec klipsdebug)
- Native AES/3DES and MD5/SHA1 support as well as some CryptoAPI support

#########################################################################
# REQUIREMENTS
#########################################################################

A recent Linux distribution based on either Kernel 2.4.x, 2.6.x or 3.x,
with the required tools to compile kernel modules.

#########################################################################
# Compiling KLIPS
#########################################################################

    make module
    sudo make module_install

This builds a module against the running kernel. It is the equivalent of
running:

    make KERNELSRC=/lib/modules/`uname -r`/build module
    sudo make KERNELSRC=/lib/modules/`uname -r`/build module_install

To compile a module for another kernel, one can set KERNELSRC to point to
directory with kernel headers or a full kernel source tree (eg /usr/src/kernels/)

#########################################################################
# NAT TRAVERSAL
#########################################################################

For Linux 2.6 Kernels before 2.6.23, including 2.4 linux systems, the kernel
requires patching if NAT-T support is required. The full kernel source is
required as some of the actual kernel source files need to be patched.

See your distribution documentation on how to build and install a new kernel

    Add NAT-T support (if required).

        From the Libreswan source directory:

          make KERNELSRC=/usr/src/linux nattpatch | patch -d /usr/src/linux -p1

#########################################################################
# SAref tracking support
#########################################################################


Premade patches for some distributions kernels can be found
in patches/kernel/ directory of the libreswan source directory. If there is
no patch for your exact kernel version, pick the version of the patch that matches
your kernel closest - but don't pick a higher version than the kernel you have.

Documentation on SAref/MAST can be found in docs/HACKING/Mast* and
doc/klips/mast.xml. To understand what SAref tracking does, see
doc/ipsecsaref.png and the overlapip= entry in the ipsec.conf man page.

#########################################################################
# OCF support
#########################################################################

For OCF HW offloading support, you need a kernel that has support for an OCF
kernel module, or has been patched with OCF support.
See: http://ocf-linux.sourceforge.net/ for more details.

Compile a module with MODULE_DEFCONFIG= set to packaging/ocf/config-all.h, eg:

    make module MODULE_DEFCONFIG=/opt/build/libreswan/packaging/ocf/config-all.h
    sudo make module_install

To test if KLIPS is properly compiled:

    modprobe ocf
    modprobe ipsec
    dmesg

packaging/ocf/config-all.h can be modified to enable specific hardware crypto
processors. This usually requires vendor source code to compile. The "software
module" works with the NETKEY/XFRM stack as well and can accelerate NETKEY/XFRM
over multiple CPU's. The kernel module ocf_bench can be used for benchmarking.
The ocf_bench module is designed to "fail" loading into the kernel. A benchmark
can be done using:

    modprobe ocf_bench
    dmesg

#########################################################################
# SUPPORT
#########################################################################

Mailing Lists:

    https://lists.libreswan.org is home of the mailing lists

Wiki:

    https://libreswan.org is home to the Libreswan WIKI.  It has the most
    up to date documentation, interop guides and other related information.

IRC:

    Libreswan developers and users can be found on IRC, on #swan
    irc.freenode.net.

#########################################################################
# BUGS
#########################################################################

Bugs with the package can be filed into our bug tracking system, at
https://bugs.libreswan.org

#########################################################################
# SECURITY HOLES
#########################################################################

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 (or successor) mailing list. A complete list of known
security vulnerabilities is available at: https://www.libreswan.org/security/

#########################################################################
# DEVELOPMENT
#########################################################################

Those interested in the development, patches, beta releases of Libreswan
can join the development mailing list (http://lists.libreswan.org -
dev@lists.libreswan.org) or join the development team on IRC in #swan
on irc.freenode.net

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

#########################################################################
# DOCUMENTATION
#########################################################################

The most up to date docs are in the man pages and at https://libreswan.org/

The bulk of this software is under the GNU General Public License; see
LICENSE.  Some parts of it are not; see CREDITS for the details.
