IPsec README for MIPL 2.0

Contents
========

	1. Introduction
	2. Limitation/Requirements
	3. How to Make IPsec Configuration
		3.1 HomeRegBinding
		3.2 MobPfxDisc
		3.3 TunnelHomeTesting
		3.4 TunnelMh
		3.5 TunnelPayload
	4. Manual Operation
		4.1. HA Operation
		4.2. MN Operation
	5. Automated Operation


1. Introduction
===============

Mobile IPv6 uses IPsec to protect mobility signaling messages that are
exchanged between MN and HA.

In MIPL 2.0, mip6d manages the Security Policy (SP) entries required
for Mobile IPv6 operation by itself, while the Security Association
(SA) entries have to be provided by either (a) manual operation or (b)
automated operation (i.e., IKE).  By automated operation, resiliency
against replay attack becomes stronger.

Following is a summary of IPsec usage in MIPv6 operation specified in
RFC 3775.  In MIPL 2.0, configuration of IPsec is specified in
configuration file of mip6d.

	+-------------------------------------------------+
	| Type     | IPsec protocol/mode | Requirements   |
	|=================================================|
	| BU/BA    | ESP/Transport       | Mandatory      |
        |----------+---------------------+----------------|
	| MPS/MPA  | ESP/Transport       | Recommended    |
        |----------+---------------------+----------------|
	| HoTI/HoT | ESP/Tunnel          | Recommended    |
        |----------+---------------------+----------------|
	| Payload  | ESP/Tunnel          | Optional       |
        +-------------------------------------------------+

A tunnel mode IPsec SA established between the MN and HA should hold
the end-point addresses of the tunnel, namely the care-of address
(CoA) of the MN and the HA's address as shown in the figure below.

                                          HA's
            +----+ CoA                    address +----+
            | MN |=========(IPsec tunnel)=========| HA |
            +----+                                +----+

When the MN is at a foreign link and successfully makes the home
registration to its HA, the IPsec tunnel end-point address should be
set as the MN's CoA.  On the other hand, when the MN is at home, the
end-point address (MN side) should be initialized with its home
address (HoA).


2. Limitation/Requirements
==========================

The following are limitations of MIPL 2.0 when IPsec is enabled.

Request ID (reqid) setting -- When there are several IPsec
transport/tunnel mode SPs configured between the MN and HA, (e.g. SP
entries for BU/BA and MPS/MPA) you need to add an identifier called
reqid to both the policies and SAs to make sure that the IPsec stack
can properly maintain association between SP and SA entries.

IPsec tunnel mode and Route Optimization -- When the SP is set in a
way that any payload packet (protocol unspecified) is to be protected
by an IPsec tunnel, route optimization cannot be performed between the
MN and its peer.


3. How to Make the IPsec Configuration
======================================

First of all, in order to activate IPsec the following line should be
included in the configuration file.

	UseMnHaIPsec enabled;

Next, IPsecPolicySet clause needs to be properly configured.  The
following is an example of IPsecPolicySet.  Note that you need to
specify IP addresses according to your home network configuration.
Each IPsecPolicy option enables protection of particular Mobility
Header (MH) messages.  The following is the list of options for
IPsecPolicy:

	HomeRegBinding
	MobPfxDisc
	TunnelHomeTesting
	TunnelMh
	TunnelPayload

Note that in order to enable IPsec tunnel for protecting MH messages,
any one of TunnelHomeTesting, TunnelMh, and TunnelPayload must be
specified.

Each IPsecPolicySet clause can be defined if several HA addresses are
used.

	IPsecPolicySet {
	        HomeAgentAddress 3ffe:501:ffff:100::feed;
	        HomeAddress 3ffe:501:ffff:100::beef/64;

	        IPsecPolicy HomeRegBinding UseESP 1 2;	  # BU/BA
	        IPsecPolicy MobPfxDisc UseESP 3 4;        # MPS/MPA
		IPsecPolicy TunnelHomeTesting UseESP 5 6; # HoTI/HoT
	}


3.1 HomeRegBinding
==================

This option enables protection of BU and BA messages in ESP transport
mode.  When this option is specified along with MobPfxDisc option, a
pair of unique reqid should be specified ("1" and "2" in the example
below).

	IPsecPolicy HomeRegBinding UseESP 1 2;	  # BU/BA

3.2 MobPfxDisc
==============

This option enables protection of MPS and MPA messages in ESP
transport mode.  When this option is specified along with
HomeRegBinding option, a pair of unique reqid should be specified ("3"
and "4" in the example below).

        IPsecPolicy MobPfxDisc UseESP 3 4;        # MPS/MPA

3.3 TunnelHomeTesting
=====================

This options enables protection of HoTI and HoT messages in ESP tunnel
mode.  Note that this configuration conforms to RFC 4877 in the sense
that MH type is specified in the traffic selector of SP entries.  It
is recommended to enable this option for protecting HoTI and HoT
messages.  When this option is specified along with the HomeRegBinding
option and/or the MobPfxDisc option, a pair of unique reqid should be
specified ("5" and "6" in the example below).

	IPsecPolicy TunnelHomeTesting UseESP 5 6; # HoTI/HoT

3.4 TunnelMh
============

This option is EXPERIMENTAL.  This option enables protection of HoTI
and HoT messages in ESP tunnel mode as similar to TunnelHomeTesting.
The difference is that MH type is not specified in the traffic
selector of SP entries.  It should be noted that with this option, the
MN may fail to receive some MH messages sent from its peer to the home
address.  More specifically, the MN would not be able to receive MH
messages that are sent in a route optimized manner.  When this option
is specified along with the HomeRegBinding option and/or the
MobPfxDisc option, a pair of unique reqid should be specified ("5" and
"6" in the example below).

	IPsecPolicy TunnelMh UseESP 5 6;

3.5 TunnelPayload
=================

This option is EXPERIMENTAL.  This option enables protection of all
the user traffic including MH messages.  It should be noted that the
MN may fail to receive some MH messages sent from its peer to the home
address.  There are also some other potential issues.  When this
option is specified along with the HomeRegBinding option and/or the
MobPfxDisc option, a pair of unique reqid should be specified ("5" and
"6" in the example below).

	IPsecPolicy TunnelPayload UseESP 5 6;


4. Manual Operation
===================

After you make the IPsec configuration of the MIPL 2.0 daemon, you
should prepare scripts to manually configure the SAs on both the MN
and HA.  Below is an example of an input file for setkey to manually
configure the SAs.  The input file can be passed to setkey by "setkey
-f sa.conf" with super-user privileges.  For detailed information of
SA configuration, see the ipsec-tools documentation.

sa.conf example:
----------------
# 3ffe:501:ffff:100::beef is home address of MN
# and 3ffe:501:ffff:100::feed is address of HA

# MN -> HA transport SA for BU
add 3ffe:501:ffff:100::beef 3ffe:501:ffff:100::feed esp 2000
	-u 1
        -m transport
        -E des-cbc "TAHITEST"
        -A hmac-sha1 "this is the test key" ;

# HA -> MN transport SA for BA
add 3ffe:501:ffff:100::feed 3ffe:501:ffff:100::beef esp 2001
	-u 2
        -m transport
        -E des-cbc "TAHITEST"
        -A hmac-sha1 "this is the test key" ;

# MN -> HA transport SA for MPS
add 3ffe:501:ffff:100::beef 3ffe:501:ffff:100::feed esp 2002
	-u 3
        -m transport
        -E des-cbc "TAHITEST"
        -A hmac-sha1 "this is the test key" ;

# HA -> MN transport SA for MPA
add 3ffe:501:ffff:100::feed 3ffe:501:ffff:100::beef esp 2003
	-u 3
        -m transport
        -E des-cbc "TAHITEST"
        -A hmac-sha1 "this is the test key" ;

# MN -> HA tunnel SA for HoTI
add 3ffe:501:ffff:100::beef 3ffe:501:ffff:100::feed esp 2004
        -m tunnel
        -E des-cbc "TAHITEST"
        -A hmac-sha1 "this is the test key" ;

# HA -> MN tunnel SA for HoT
add 3ffe:501:ffff:100::feed 3ffe:501:ffff:100::beef esp 2005
        -m tunnel
        -E des-cbc "TAHITEST"
        -A hmac-sha1 "this is the test key" ;

4.1. HA Operation
=================

(1) make sure that you made the IPsec configuration in mip6d.conf properly
(2) manually configure SA with setkey
(3) run mip6d

4.2. MN Operation
=================

(1) make sure that you made the IPsec configuration in mip6d.conf properly
(2) manually configure SA with setkey
(3) run mip6d


5. Automated Operation
======================

In automated operation, SAs are automatically managed by an Internet Key
Exchange (IKE) daemon.  With regard to the mip6d operation, there is
nothing special to be done in automated operation.

However, there is no MIPv6-aware-IKE daemon publicly available yet.
