naipsec_manual: IPSEC Manually Keyed VPN Example Application

This application demonstrates to configure IPSEC to create a VPN tunnel
between two networks.  The tunnel is manually keyed.

Note that manually keyed VPNs are NOT as secure as ones negotiated with
IKE.  This is because:

1.  The two VPN peers authenticate each other during IKE phase 1.  Since
    this is not done with manually keyed tunnels, it is possible for an
    attacker to masquerade as a VPN peer by using its IP address.
2.  The session keys are hard coded.  When IKE is used, new session keys
    are generated with each new session, and old session keys are
    retired and replaced when their SAs time out.
3.  There is no built in mechanism to create or exchange new session
    keys.

In general, you should avoid using manually keyed VPNs.  IKE negotiated
VPNs are more secure, and easier to set up.  Only use manually keyed
VPNs when the equiptment you are communicating with does not support
IKE.

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() demonstrates how to configure IPSEC and
    manually key a VPN tunnel.
8.  After createVpn() completes, traffic from the local side of
    of the VPN network directed to the remote side will be
    encrypted and sent to the remote VPN peer.

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 to prevent attackers from reading it, and authenticate
it to ensure the identity of the remote partner, and prevent
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 (refered to as
the remote VPN peer).  The two gateways create a connection
between them 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 the 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 eth0
    interface is configured with the address 192.168.2.2.
4.  The eth0:0 interface is configured with the address
    192.168.3.1.  This is the unit's address on the local
    VPN subnet 192.168.3.X.
3.  The encryption and authentication algorithms used to
    protect data sent over the VPN connection.  The defaults
    are to use DES encryption and MD5 authentication.
4.  The encryption and authentication keys.
5.  The Security Parameter Index (SPI) values for each
    Security Association (SA).
6.  Whether the tunnel SAs are permanent.

You can change this set up 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.  You should see your unit send
    an ESP packet to the remote VPN peer.  The remote VPN peer
    should answer back with another ESP packet which contains
    the ping response from the remote station.  The unit
    will decrypt this packet and send the ping response to
    the local PC.


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 the packets
    are directed to, and so will intere 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.  If your unit does not send an ESP
    packet to the remote peer when it receives the ping request
    from the local PC, then routing is probably not enabled.
9.  If the remote VPN peer does not send a ping packet to the
    remote peer, then there is a configuration missmatch between
    the two VPN peers.  The two peers have to be configured
    identically except for the SPI values which should be
    reversed.
10. If you are creating the VPN by running this example on two
    different units, then you must remember to swap the SPI
    values on one of the units.  The local unit's inbound
    SPI is the remote unit's outbound SPI, and vice versa.


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


