naipsec_ike: IPSEC IKE Example Application

This application demonstrates how to configure IPSEC to create a VPN tunnel
between two networks.  IKE/ISAKMP is used to negotiate the tunnel.

This example should work on all development boards.  You must configure
the BSP to enable routing on all network interfaces.

Note: NET+OS IPSEC does not support NAT traversal.

The application does the following:

1.  The development board is initialized.
2.  The ThreadX kernel is loaded.
3.  The device drivers are loaded.
4.  The TCP/IP stack is loaded.
5.  The function applicationStart() is called.
6.  The applicationStart() function calls createVpn().
7.  The createVpn() function provides an example of how to configure
	IPSEC and IKE.
8.  After createVpn() completes, traffic from the local side of
    of the VPN network directed to the remote side will trigger
    IKE to negotiate a VPN tunnel.

A Virtual Private Network (VPN) is a secure connection between
two networks over an insecure network (such as the Internet).
The security is achieved by using VPN protocols to encrypt
data, preventing attackers from reading it, and to authenticate
it to ensure the identity of the remote partner, preventing
attackers from tampering with data.

This example program will set up your unit to be a VPN gateway
that will communicate with another VPN gateway (referred to as
the remote VPN peer).  The two gateways create a connection
which is encrypted.  Data sent over that connection
is protected from eavesdroppers and tampering.  The connection
bridges two networks.

 |----------|    |-------|                  |--------|    |----------|
 |   local  |    | local |                  | remote |    |  remote  |
 |  network +----+  VPN  +--VPN Connection--+   VPN  +----+  network |
 |          |    |  peer |                  |  peer  |    |          |
 |----------|    |-------|                  |--------|    |----------|

The configuration settings for the VPN are in the file vpn.h.
These settings determine the following:

1.  Which two networks will be bridged together.  The default
    configuration sets the local network to be 192.168.3.0/24
    and the remote network to be 192.168.1.0/24.
2.  The addresses of the two VPN peers.  These are the addresses
    bound to the network interfaces the two peers use to
    communicate with each other.  The default configuration
    sets the address of the local peer to 192.168.2.2, and the
    address of the remote peer to 192.168.2.1. The address of
    the eth0 interface is set to 192.168.2.1, and is the
    interface used to communicate with the remote VPN peer.
3.  The eth0:0 interface is used to communicate with devices
    on the 192.168.3.X subnet, which is the local side of the
    VPN tunnel.  The address of the eth0:0 interface is set
    to 192.168.3.1.  The address is set with the
    OUR_ADDRESS_ON_LOCAL_SUBNET constant in vpn.h.
4.  The preshared key used by the VPN peers to authenticate
    with each other.  The default is "ThePresharedKey123".
5.  The encryption and authentication algorithms used to
    protect data sent over the VPN connection.  The defaults
    are to use DES encryption and MD5 authentication.
6.  The ID of the local peer.  The default is to use the
    peer's IP address.
7.  Other VPN parameters such as the anti-replay setting,
    the diffie-hellman group to use for key generation,
    and whether PFS is desired.

You can change this setup by editing vpn.h.  You must make sure
the local and remote VPN peers are both configured in the same
way.  This example was tested against a Cisco PIX Firewall.  A
dump of the configuration settings for the PIX is in the file
pixsetup.txt.  You do not need a PIX to try this example.  Any
VPN gateway can be used as the remote peer as long as both
the local and remote peers use the same configuration settings.

Note:  This example hard codes the IP settings in appconf.h rather
       than reading them from NVRAM.  This is done because the
       IP settings must match the settings in vpn.h.

Once you have the two VPN peers up and running, you can trigger
the VPN by sending traffic from one network to the other.  One way
to do this using the default settings in vpn.h would be:

1.  Set up a PC on the local side of the network with IP address
    192.168.3.10, subnet mask 255.255.248.0, and gateway
    192.168.3.1 - APP_IP_ADDRESS.
2.  Set up a PC on the remote side of the network with IP address
    192.168.1.10, subnet mask 255.255.255.0, and the gateway address
    set to that of the remote VPN peer (192.168.1.1 with Cisco PIX
    setup).
3.  Ping one PC from the other.  The two VPN peers should start
    negotiating the VPN connection as soon as one of them receives
    a packet (a ping request) that is addressed to the other
    network.  You should be able to capture the negotiation and
    the traffic with an Ethernet capture program such as
    Etherpeek or Ethereal.


Hints:

1.  You might need to disable firewall on PCs or change firewall settings.
2.  Make sure the subnet masks of the two PCs are set up so that
    the PCs cannot communicate with each other directly, but
    must go through the VPN gateways.
3.  Make sure the PCs are configured to use the VPN gateways as
    routers.
4.  Make sure each PC is on the same physical network as the VPN
    peer it must use.
5.  Make sure each PC can route to local VPN peer and a local
    VPN peer can route to a local PC.
6.  If you want to capture the traffic between the PCs and the
    VPN peers, then use dumb hubs instead of smart switches.
    Smart switches will only send packets to the ports to which the packets
    are directed, and so will interfere with packet capture
    programs such as Ethereal and Etherpeek.
7.  Both of the VPN peers and both PCs can all be on the same
    physical network as long as the PCs are configured so they
    must use the VPN peers to communicate with each other.  To
    do this, make sure the network addresses and subnet masks
    used by the PCs do not overlap.  Note that some VPN gateways
    will not work correctly if both of their network interfaces
    are on the same physical network.
8.  Make sure the BSP has been configured to enable routing on
    all network interfaces (default). If your unit does NOT start IKE
    negotiations when the local PC attempts to ping the remote
    PC, and the ping packets are sent to the unit's MAC address,
    then you probably do not have routing enabled.
9.  If you see the two peers start IKE negotiations, but the
    negotiations fail, then the peers have different
    configuration settings.  The two VPN peers must use the same
    IPSEC configuration settings or they will not be able to
    establish a VPN tunnel.


Three Multi build files are provided.  The build file project.gpj
is used to control how application specific files are built.  All
updates to the build should be made to this file.  Project.gpj is
a subproject to the other build files image.gpj and rom.gpj.
Image.gpj is used to generate a debuggable version of the
application, and also creates the file image.gpj that can be written
into ROM if the bootloader is used.  Rom.gpj is used to generate a
ROM image of the application if the bootloader is not used.

One GNU make file is provided.  Build the target 'image' to
generate an image that can be debugged with gdb, and the file
image.bin which can be written to flash if the bootloader is used.
Build the target 'rom.bin' to create the file rom.bin which
can be written to ROM if the bootloader is not used.

The following files are provided in this example.

appconf.h         sets application configuration settings
.\32b\image.gpj   used to build the big endian Green Hills version of the
                  application.  The build script creates a version that
                  can be debugged with Multi, and the file image.bin
                  which can be written into a ROM that uses the bootloader.
.\32b\makefile    Make file for the GNU toolset.
pixsetup.txt      configuration dump of Cisco PIX used as the remote VPN
                  peer in this example.
project.gpj       contains application specific build settings
readme            this file
.\32b\rom.gpj     used to build the big endian ROM image of application
root.c            contains applicationStart() function.
vpn.c             contains the example code which sets up IPSEC
                  to use IKE to negotiate a VPN tunnel with a remote
                  VPN peer.
iamParams.c       Customized IAM parameter settings that configures
                  local VPN address on eth0:0 (or wln0:0 for wireless
                  only board) instead of using this multi-mome address
                  for Auto IP (NET+OS default). This file is linked instead
                  of the file with the same name in src\bsp\customize.
vpn.h             contains the configuration settings for the vpn.




In addition, the following files in the BSP directory are built
as part of this application.

reset.s         contains the reset code
appconf_api.c   contains code used to read settings in appconf.h


