#
# USAGI Linux/IPsec for IPv6
#
# $USAGI: IPsec,v 1.7 2002/04/11 01:04:46 yoshfuji Exp $
#

Now we are developing IPsec for IPv6 based on FreeS/WAN-1.9 and IABG.

And we use cryptoapi(patch-int-2.4.17.0.bz2) as cipher/digest algorithm,
but we removed needless crypto algorithm to avoid patent/license issue.
If you want to use removed algorithm, 
you can use it just copy from patch-int-2.4.17.0.bz2 to linux24/crypto/cipher/, 
and comment out related part of cipher/{Config.in, Makefile}.
(removed files:
	cipher-blowfish.c cipher-dfc.c cipher-idea.c 
	cipher-mars.c cipher-serpent.c cipher-twofish.c)

Current status:

	We support Transport mode AH/ESP manually keyed.

Build:
	Our recommendation for ipsec related kernel config is as follows:
	("<o>": as you like)
	
	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)
		[*]     IPv6: Apply IPsec to ICMPv6 packets

How to use:

	install usagi/pfkey

	% 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

	[manual configuration example]

	(Attention: You must avoid to use weak key.)

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

    --MANUAL KEYING--

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

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

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

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

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

	(SET Host A -> Host B flow at Host B)
	(SET Host B -> Host A flow at Host B)
		same as above

	- If you want to display current SA/SP status, use "pfkey -L".
	- If you want to flush SA all, use "pfkey -F any".
	- If you want to delete SA or SP entry, user "pfkey -D ...".
	("pfkey --help" displays more information.)
	(For easy manual testing, we provide a tiny script "ipsec-set" in pfkey_util directory.)

    --WITH IKE(preshared key)--

	Difference from FreeS/WAN'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.

	There are two commands to use ike, "pluto" and "whack".
	pluto is a ike. whack is a command to communicate running pluto.

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

	Start sequence.
	
	2). Define a preshared key of both host 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 pluto.pid, pluto is running.

	5). Configure IKE with whack command. The parameter after --name is name of a conifguration.
	    We use "name" for initiation and termination, delete. I use the name "test" for explanation.

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

	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
	then pluto begins key exchange 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
	
NOTICE:
	If you use 3DES or DES for ESP encryption algorithm, please avoid to use the weak key.

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)
FAQ:
	(Under construction)

TODOs:
	- NS-NA handling
	- SADB_REGISTER for IKE Daemon (We will use Pluto.)
	- Tunnel mode (We have a plan to realize this using generic over IP{v4|v6} tunnel, which we are writing.)
	- And remove many bugs :-)

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/
   
