#
# USAGI Linux/IPsec for IPv6
#
# $USAGI: IPsec,v 1.14 2002/08/05 12:42:58 yoshfuji Exp $
#

USAGI's IPsec for IPv6 is based on FreeS/WAN-1.9 and IABG.

NOTE: We use cryptoapi (patch-int-2.4.17.0.bz2) as implementation
of cipher/digest algorithms.  However, several algorithms are not
included due to the patent/license issue.  If you want to use them,
you can copy it from patch-int-2.4.17.0.bz2 to linux24/crypto/cipher/, 
and comment out related part of cipher/{Config.in, Makefile}.

The files removed:
	cipher-blowfish.c cipher-dfc.c cipher-idea.c 
	cipher-mars.c cipher-serpent.c cipher-twofish.c

Table of Contents

	1. Current Status
	2. Building/Installing USAGI IPsec
	2.1 Building Kernel 
	2.2 Install the pfkey command
	3. Using USAGI IPsec
	3.1 Transport Mode
	3.1.1 Manually keyed
	3.1.2 Using IKEd
	3.2 Tunnel Mode
	3.2.1 Manually keyed
	3.2.2 Using IKEd
	4. Notice
	5. Debug
	6. FAQ
	7. TODOs
	8. References


1. Current status:

	We support Transport mode AH/ESP manually keyed and using IKEd.
	We support Tunnel mode AH/ESP manually keyed.

2. Building/Installing USAGI IPsec

2.1 Building Kernel 

	The recommended kernel configuration for IPsec is as follows:
	("<o>": indicates an optional setting)

	
	Cryptographic options  --->
		<*> Cryptographic API support
		<o> generic loop cryptographic filter (EXPERIMENTAL)
		<*> Cryptographic ciphers
		--- AES Cipher (128 bit blocksize)
		<*>  AES (aka Rijndael) cipher (EXPERIMENTAL)
		--- AES Finalist Ciphers (128 bit blocksize)
		--- Other Ciphers submitted as AES Candidates:
		--- Other ciphers (64 bit blocksize)
		<*>  DES EDE3 cipher (3DES, EXPERIMENTAL)
		<*>  DES cipher (DEPRECATED)
		--- Debugging   
		<o>  DUMMY cipher (DEPRECATED)
		<*> Digest algorithms
		<*>  MD5 digest (EXPERIMENTAL)
		<*>  SHA1 digest (EXPERIMENTAL)
	Networking options  --->
		[*]    The IPsec protocol (EXPERIMENTAL)
		[*]     IPsec: IPsec Debug messages
		[*]     IPsec: IPsec Debug disable Default
		<*/M>   The IPv6 protocol (EXPERIMENTAL)
		...
		[*]     IPv6: IP Security Support (EXPERIMENTAL)
		<M>	IPv6: IPv6 over IPv6 Tunneling (EXPERIMENTAL)


2.2 Install the pfkey command

	% cd ANYWHERE/usagi/usagi/pfkey
	% ./configure --with-linux-kernel=ANYWHERE/usagi/kernel/linux24  (default /usr/src/linux)
	(or if you use USAGI kit, pfkey command will be installed automatically.)
	% make
	% su
	# make install

3. Using USAGI IPsec

	IPsec can be configured manually using the pfkey command or
	it can be configured dynamically through the IKE daemon, pluto.

	(Attention: YOU MUST AVOID TO USE WEAK KEY.)

3.1 Transport Mode

	Example Network Scenario:

	(Host A) ----------------- (Host B)
	3ffe:a:b:c:d::1            3ffe:a:b:c:d::2

	mode		: transport AH/ESP
	AH  algo	: hmac-md5 (key 0x0123456789abcdef0123456789abcdef)
	ESP auth algo	: hmac-md5 (key 0x0123456789abcdef0123456789abcdef)
	ESP enc algo	: 3des-cbc (key 0xa7a36ebd91863edfba763fa7edcba64d89123ace6359eba7)
	SPI 		: A -> B AH:0x1234 ESP:0x5678, B -> A AH:0x9abc ESP:0xdef0
	Protocol	: UDP

3.1.1 Manually keyed

	(SET Host A -> Host B flow at Host A)
	(SA for AH)  
	# pfkey -A sa -s 3ffe:a:b:c:d::1 -d 3ffe:a:b:c:d::2 -T ah -S 0x1234 -p udp \
		--auth hmac-md5 --authkey 0x0123456789abcdef0123456789abcdef
	(SA for ESP) 
	# pfkey -A sa -s 3ffe:a:b:c:d::1 -d 3ffe:a:b:c:d::2 -T esp -S 0x5678 -p udp \
		--auth hmac-md5 --authkey 0x0123456789abcdef0123456789abcdef \
		--esp 3des-cbc --espkey 0xa7a36ebd91863edfba763fa7edcba64d89123ace6359eba7

        (SP for AH) 
	# pfkey -A sp -s 3ffe:a:b:c:d::1 -d 3ffe:a:b:c:d::2 -T ah -S 0x1234 -p udp 
	(SP for ESP) 
	# pfkey -A sp -s 3ffe:a:b:c:d::1 -d 3ffe:a:b:c:d::2 -T esp -S 0x5678 -p udp 

	(SET Host B -> Host A flow at Host A)
	(SA for AH) 
	# pfkey -A sa -d 3ffe:a:b:c:d::1 -s 3ffe:a:b:c:d::2 -T ah -S 0x9abc -p udp \
		--auth hmac-md5 --authkey 0x0123456789abcdef0123456789abcdef
	(SA for ESP)
	# pfkey -A sa -d 3ffe:a:b:c:d::1 -s 3ffe:a:b:c:d::2 -T esp -S 0xdef0 -p udp \
		--auth hmac-md5 --authkey 0x0123456789abcdef0123456789abcdef \
		--esp 3des-cbc --espkey 0xa7a36ebd91863edfba763fa7edcba64d89123ace6359eba7

	# pfkey -A sp -d 3ffe:a:b:c:d::1 -s 3ffe:a:b:c:d::2 -T ah -S 0x9abc -p udp 
	# pfkey -A sp -d 3ffe:a:b:c:d::1 -s 3ffe:a:b:c:d::2 -T esp -S 0xdef0 -p udp 

	Now on Host B do the same as above:
	(SET Host A -> Host B flow at Host B)
	(SET Host B -> Host A flow at Host B)

	You can also use the following options with the pfkey command:

	- "pfkey -L" to display current SA/SP status.
	- "pfkey -F any" to flush all the SAs and SPs.
	- "pfkey -D ..." to delete an SA or SP entry.
	- "pfkey --help" to display more help information.
	(For easy manual testing, we provide a script "ipsec-set" in pfkey directory.)
	We recommend disabling Replay_Window_Check for manual keying.
	e.g. # sysctl -w net.ipsec.replay_window_check=0
	or
	     # echo 0 > /proc/sys/net/ipsec/replay_window_chek


3.1.2 Using IKEd

	IKE(preshared key) CONFIGURATION EXAMPLE:

	Difference between FreeS/WAN's pluto and USAGI's pluto
	- There are not /etc/ipsec.conf and helpful scripts.
	- Default path for ipsec.secrets which is authentication key file is changed to
		/usr/local/v6/etc/ipsec.secrets.
	- Our pluto never calls updown script.

	The two commands to use ike are, "pluto" and "whack".
	pluto is a daemon that runs the IKE protocol.
	whack is a command used to communicate with a running pluto.

	1). See manual for pluto and ipsec.secrets, which is in /usr/local/v6/man/{man5,man8}
	1). To se the man pages for pluto and ipsec.secrets, located
	in /usr/local/v6/man/{man,man8}:
	% man ipsec_pluto
	% man ipsec.secrets

	Start sequence:
	
	2). Define a preshared key of both hosts in /usr/local/v6/etc/ipsec.secrets (default).
	3ffe:a:b:c:d::1 3ffe:a:b:c:d::2 : PSK "hoge"
		...... (in ipsec.secrets)

	3). Run pluto with any option
	# pluto
	for debug, we use --nofork --stderrlog --debug-all
	# pluto --nofork --stderrlog --deubg-all

	4). Check pluto is running or not with ps command or ls /var/run.
	# ls /var/run
	If there is a pluto.pid file, pluto is running.

	5). Configure IKE with whack command. The parameter after --name is the
	name of a configuration. This parameteris used for initiation,
	termination, and delete. The configuration name "test" is used in the 
	following examples.

	-- You use authentication
	# whack --name test --ipv6 --host 3ffe:a:b:c:d::1 --to --host 3ffe:a:b:c:d::2 --authnticate
	-- You use encryption
	# whack --name test --ipv6 --host 3ffe:a:b:c:d::1 --to --host 3ffe:a:b:c:d::2 --encrypt
	-- You use authentication and encryption
	# whack --name test --ipv6 --host 3ffe:a:b:c:d::1 --to --host 3ffe:a:b:c:d::2 --authnticate --encrypt

	*You can use other options but tunnel options. Please see a manual of pluto.
	*You can use other options but tunnel options. Please see man pages for pluto.

	6). Make pluto listen
	# whack --listen
	then pluto checks the interface and reads authentication keys from the file.

	7). Initiate key exchange with configuration name
	# whack --initiate --name test
	pluto begins key exchages and if you get an answer establish, pluto successes key exchange.
	You can see the IPsec information with
	% pfkey -L

	Shutdown sequence from here.

	8). Terminate IPsec between the hosts.
	# whack --terminate --name test

	9). Delete configuration
	# whack --delete --name test

	10). Shutdown pluto
	# whack --shutdown
	
3.2 Tunnel Mode

	Example Network Scenario:

	(SG A) =================== (SG B) --------------------- (Host C)
	   eth0			eth0    eth1			eth0
	   tnl0			tnl0
	3ffe:a:b:c:d::1            3ffe:a:b:c:d::2		
	fec0:0:0:a::10%tnl0	   fec0:0:0:b::20%eth1		fec0:0:0:0:30%eth0
	fe80::a%tnl0		   fe80::b%tnl0

	mode		: tunnel AH/ESP
	AH  algo	: hmac-md5 (key 0x0123456789abcdef0123456789abcdef)
	ESP auth algo	: hmac-md5 (key 0x0123456789abcdef0123456789abcdef)
	ESP enc algo	: 3des-cbc (key 0xa7a36ebd91863edfba763fa7edcba64d89123ace6359eba7)
	SPI 		: A -> B AH:0x1234 ESP:0x5678, B -> A AH:0x9abc ESP:0xdef0

3.2.1 Manually keyed

	set up Tunnel device
	on SG A
	# modprobe ipv6_tunnel
	# ipv6tunnel add tnl0 --tunnel-local-packets encaplimit 0 remote 3ffe:a:b:c:d::2 local 3ffe:a:b:c:d::1
	# ifconfig tnl0 up (or ip link set tnl0 up)
	# ifconfgi tnl0 add fe80::a/64 (or ip addr add fe80::1/64 dev tnl0)
	# ifconfig tnl0 add fec0:0:0:a::10/64 (or ip addr add fec0:0:0:a::10/64 dev tnl0)
	# route -A inet6 fec0:0:0:b::/64 dev tnl0 (or ip route add fec0:0:0:b::/64 dev tnl0)

	on SG B
	# sysctl -w net/ipv6/conf/all/forwarding=1
	# sysctl -w net/ipv6/conf/all/accept_ra=0
	# ifconfig eth0 add 3ffe:a:b:c:d::2/64 (or ip addr add 3ffe:a:b:c:d::2/64 dev eth0)
	# ifconfig eth1 add fec0:0:0:b::20/64 (or ip addr add fec0:0:0:b::20/64 dev eth1)
	# radvd (with proper configuration)
	# modprobe ipv6_tunnel
	# ipv6tunnel add tnl0 --tunnel-local-packets encaplimit 0 remote 3ffe:a:b:c:d::1 local 3ffe:a:b:c:d::2
	# ifconfgi tnl0 up (or ip link set tnl0 up)
	# ifconfig tnl0 add fe80::b/64 (or ip addr add fe80::b/64 dev tnl0)
	# route -A inet6 fec0:0:0:a::10 dev tnl0 (or ip route add fec0:0:0:a::10 dev tnl0)

	set up  IPsec
	(SET SG A -> SG B flow at SG A)
	on Both SG A and SG B
	(for AH)
	# pfkey -A sa -s 3ffe:a:b:c:d::1 -d 3ffe:a:b:c:d::2 -T ah -S 0x1234 \
			 --auth hmac-md5 --authkey 0x0123456789abcdef0123456789abcdef
	(for ESP)
	# pfkey -A sa -s 3ffe:a:b:c:d::1 -d 3ffe:a:b:c:d::2 -T esp -S 0x5678 \
			--esp 3des-cbc --espkey 0xa7a36ebd91863edfba763fa7edcba64d89123ace6359eba7 \
			--auth hmac-md5 --authkey 0x0123456789abcdef0123456789abcdef

	# pfkey -A sp -s fec0:0:0:a::10 -d fec0:0:0:b::20/64 -T ah -S 0x1234 \
			--tunnel --ts 3ffe:a:b:c:d::1 --td 3ffe:a:b:c:d::2

	# pfkey -A sp -s fec0:0:0:a::10 -d fec0:0:0:b::20/64 -T esp -S 0x5678 \
			--tunnel --ts 3ffe:a:b:c:d::1 --td 3ffe:a:b:c:d::2

	(SET SG B -> SG A flow at SG B)
	on Both SG A and SG B
	(for AH)
	# pfkey -A sa -s 3ffe:a:b:c:d::2 -d 3ffe:a:b:c:d::1 -T ah -S 0x9abc \
			 --auth hmac-md5 --authkey 0x0123456789abcdef0123456789abcdef
	(for ESP)
	# pfkey -A sa -s 3ffe:a:b:c:d::2 -d 3ffe:a:b:c:d::1 -T esp -S 0xdef0 \
			--esp 3des-cbc --espkey 0xa7a36ebd91863edfba763fa7edcba64d89123ace6359eba7 \
			--auth hmac-md5 --authkey 0x0123456789abcdef0123456789abcdef

	# pfkey -A sp -s fec0:0:0:b::20/64 -d fec0:0:0:a::10 -T ah -S 0x9abc \
			--tunnel --ts 3ffe:a:b:c:d::2 --td 3ffe:a:b:c:d::1

	# pfkey -A sp -s fec0:0:0:b::20/64 -d fec0:0:0:b::10 -T esp -S 0xdef0 \
			--tunnel --ts 3ffe:a:b:c:d::2 --td 3ffe:a:b:c:d::1

3.2.2 Using IKEd

	(preshared key) CONFIGURATION EXAMPLE:

		sorry, Our IKE have not yet support IPsec tunnel mode.



4. Notice

	If you use 3DES or DES for ESP encryption algorithm, please avoid using the weak key.

5. Debug

	If you want to try to figure out ipsec related strange behavior,
	you can check a message via syslog to set /proc/net/ipsec/debug_*=1.
	(or sysctl -w net.ipsec.debug_{ipv6,pfkey,sadb,spd}=1)

6. FAQ

	(Under construction)

7. TODOs

	- And remove many bugs :-)
	- fix PMTU handling with Tunnel mode.
	- Support IPv4

8. References

	FreeS/WAN	http://www.freeswan.org/
	IABG		http://www.ipv6.iabg.de/
	USAGI		http://www.linux-ipv6.org/
	cryptoapi	ftp://ftp.kernel.org/, http://sourceforge.net/projects/cryptoapi/
   
