               **********************************************
               * IPNSEC for Linux version 0.84 installation *
               **********************************************

0. Introduction

The installation of ipnsec-0.84 is substantially different from all
previous versions of both KLIPS (aka linux-ipsec) and ipnsec versions
0.80 to 0.82 inclusive.

Also, the requirements for the Linux kernel options have
changed as well as the patches required to change the kernel
sources. Please read the following instructions carefuly
even if you have experience with previous versions
of KLIPS or ipnsec.

1. Installation

1.1. Kernel Installation

To run ipnsec, you need to patch the Linux 2.0.33 kernel and
set certain kernel options. The patches and options are different
from previous versions of KLIPS and ipnsec.

The ipnsec module is built separately in the ipnsec home
directory. The sources are not to be copied into the kernel
source tree. Also, there are no IPSec options in the kernel configuration.

1.1.1. Patching the kernel

To patch the kernel, goto /usr/src/linux (or wherever your kernel
is installed) and do:

	# patch -p1 < (ipnsec-0.84 home)/linux-2.0.33-kernel-patch

Check that all patches were successful.

1.1.2. Kernel configuration.

Go to the /usr/src/linux and type "make menuconfig" (or whatever).

The following options are required:
	Loadable module support
		+ Enable loadable module support
	Networking options:
		+ Network firewalls
		+ TCP/IP networking
		+ IP: forwarding/gatewaying
		+ IP: firewalling
		- IP: masquerading (not supported with IPNSec!)
		+ IP: always defragment
		+ IP: optimize as router not host
		+ IP: tunneling
		+ Kernel/User network link driver

Make the new kernel, install it and reboot.

1.1.3. /dev/ipsec installation

The Kernel/User network link driver needs a device entry
for the utilities in sbin directory. You should make the /dev/ipsec
entry with:

	# mknod /dev/ipsec c 36 10

(where 36 is the netlink driver and 10 is the minor code reserved for
IPSec -  this minor code is shared with KLIPS).

1.2. Building of IPNSec

To build IPNSec, you need to have gmp-2.0.2 installed on your system.
This version is known to work with libc-5, not with glibc systems.
My development system is based on RedHat 4.2.

After you change to the ipnsec directory, simply type:

	# make

This should build the ipnsec.o module (in modules/) and several utilities
(in sbin/). There will be some warning messages, but no errors.

2. Operation.

2.1. Loading the ipnsec module

To load the ipnsec module, change to ipnsec directory and type:

	# insmod module/ipnsec.o

This will display certain messages on the console as well as copy
them to the syslog files (provided this is enabled in syslog.conf).

You can remove the ipnsec module with

	# rmmod ipnsec

This does not check for any active SAs, so you may drop your
existing connections if you are not careful.

2.2. Setting the SAs manually

To setup a Securirity Association (SA), you need to define a SPI
(Security Parameter Index) for *BOTH* outgoing and incoming traffic
and setup the IPSec route for the outgoing traffic only.

The tools to do this are ipsecadm (in sbin/ipsecadm) and rt (in
sbin/rt). The manual pages in the respective directories should
be up to date with this ipnsec-0.84 release.

2.2.1. Example

We want to setup manually keyed transport mode SA between
test1 (192.168.1.1) and test2 (192.168.1.2). Both hosts are
running ipnsec-0.84. We want to use the current draft AH
with MD5-HMAC-96 and the key equal to 0x11223344 in both directions.
The SPI should be 0x1234 for both directions.

	test1# # SPI for incoming traffic
	test1# sbin/ipsecadm/ipsecadm new ah -auth md5 -src 192.168.1.2 -dst 192.168.1.1 -spi 1234 -key 11223344 -newpadding
	test1# # SPI for outgoing traffic
	test1# sbin/ipsecadm/ipsecadm new ah -auth md5 -src 192.168.1.1 -dst 192.168.1.2 -spi 1234 -key 11223344 -newpadding
	test1# # IPSec AH route for all traffic from test1 to test2
	test1# sbin/rt/rt 192.168.1.1 255.255.255.255 192.168.1.2 255.255.255.255 -1 -1 -1 192.168.1.2 1234 0

	test2# # SPI for incoming traffic
	test2# sbin/ipsecadm/ipsecadm new ah -auth md5 -src 192.168.1.1 -dst 192.168.1.2 -spi 1234 -key 11223344 -newpadding
	test2# # SPI for outgoing traffic
	test2# sbin/ipsecadm/ipsecadm new ah -auth md5 -src 192.168.1.2 -dst 192.168.1.1 -spi 1234 -key 11223344 -newpadding
	test2# # IPSec AH route for all traffic from test2 to test1
	test2# sbin/rt/rt 192.168.1.2 255.255.255.255 192.168.1.1 255.255.255.255 -1 -1 -1 192.168.1.1 1234 0

You can check the IPSec routes and SPIs by

	# cat /proc/net/ipsec-route
	# cat /proc/net/ipsec-spi

2.3. Using dynamic keying with Photuris

You have to install the configuration files in /etc/photuris.
You can start with the files in sbin/photurisd/config-example.

Once you start sbin/photurisd, any initial exchanges configured will
start immediately.
You can use the sbin/startkey utility to start any additional key exchange.

2.3.1 Example

We want to use a dynamically keyed SA between test1 and test2 (as above).

	test1# sbin/photurisd/photurisd

	test2# sbin/photurisd/photurisd
	test2# sbin/startkey/startkey dst=192.168.1.1

Test the SPI and routing with:

	# cat /proc/net/ipsec-spi
	# cat /proc/net/ipsec-rt

Please note that photurisd by default uses separate SPI for AH and ESP and both
SPIs have the same value. You will therefore see 4 SPI entries for each pair of
hosts. Also, photurisd installs an IPSec route for 0.0.0.0 as source address.
This may be specific to OpenBSD, but should not cause any harm under Linux.

3. When something goes wrong

This is alpha software and thigs will go (badly) wrong.
Do not blame me or anybody else for the failures, you have been warned.

If ipnsec does not do what you expect, you can turn on debugging within
the ipnsec module, or within the photurisd daemon.
The Makefiles contain commented out lines or options to turn debugging on.

In the ipnsec module, you can control the amount of debug output with various
debug_xxx variables. These are bit field variables and you have to browse
through the sources to see what does exactly what. Most of this code is
inherited from previous versions, so do not ask/blame me if you do not know
what all that debugging output means.

At least the e-route debug is known to cause some problems (discovered
by the KLIPS team).

The photurisd does not fork and daemonize itself while in debugging mode.

4. How to report bugs

Please mail me, Petr Novak <pn@i.cz>, if you find any problems or cannot
get this thing to work at all. I will try to respond to e-mail at least
every other day.

