Host Identity Protocol (HIP) documentation


Copyright 2005, The Boeing Company

Release 0.3, August 2005

Authors:  
Jeff Ahrenholz <jeffrey.m.ahrenholz@boeing.com>
Tom Henderson <thomas.r.henderson@boeing.com>
Jeff Meegan <jeff.r.meegan@boeing.com>

LICENSE  Introduction  Implementation architecture  Compliance with HIP specifications  Interoperability   Files  Installation  Usage  Mobility

1.0  LICENSE

This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

2.0  Introduction

This is a research implementation of the Host Identity Protocol (HIP) for use on Linux or Windows XP.
From the HIP base specification[1]: 
   The Host Identity Protocol (HIP) provides a rapid exchange of Host
   Identities between two hosts.  The exchange also establishes a pair
   IPsec Security Associations (SA), to be used with IPsec Encapsulated
   Security Payload (ESP).  The HIP protocol is designed to be
   resistant to Denial-of-Service (DoS) and Man-in-the-middle (MitM)
   attacks, and when used to enable ESP, provides DoS and MitM
   protection for upper layer protocols, such as TCP and UDP.

   The Host Identity Protocol introduces a new namespace, the Host
   Identity.  The effects of this change are explained in the companion
   document, the HIP architecture [2] specification.
Please refer to the HIP specification [1, 2] for protocol details and further background information.

3.0 Implementation architecture

There are two ways to run this HIP software, depending on your operating system and whether or not you want to patch your kernel:
  1. with kernel support, for Linux only
  2. entirely in userspace, for Linux (user-mode HIP, or UMH) and Windows XP with Cygwin (HIP for Windows service or console app)
Both architectures consist of a user-space HIP daemon (hipd) and patches to IPsec tools. Also included is a hitgen utility used for initial setup and generating Host Identities, and scripts for setting up HIP. The daemon requires the following libraries (the most recently tested version are listed in parenthesis, but these exact versions are not required):

The XML library is used for generating and parsing all of hipd's configuration files. The cryptographic library provides hashing (SHA, MD5, HMAC), encryption (3DES, BLOWFISH, AES), and public key signing/verification (RSA, DSA). Libipsec is used to send PFKEY messages that manage the IPsec security associations.

3.1 Linux Kernel support

If you are running Linux and patch your kernel to support HIP, you will benefit from higher performance. Kernel support adds the requirement:
HIP Architecture

In this release, Linux applications connect to IP addresses and IPsec (SPD) policies control whether or not HIP is used. The ipsec-tools setkey utility is used to set up a policy requiring a HIP ESP tunnel for traffic destined for a specified peer. When packets are sent to that peer and match the policy entry, the kernel notifies hipd, hipd performs the HIP protocol handshake with the peer and sets up the Security Association using the native IPsec support from the 2.6 kernel. (The kernel should hold these first trigger packets, but the IPsec developers have not implemented this yet.) The resulting pair of SAs (incoming and outgoing) is associated with the HIT, so the underlying IP addresses may change without re-establishing the SAs.

3.2 Userspace implementation

The userspace implementation does not require any changes to the kernel, because all of the IPsec processing is done in a user process. A virtual device, the TAP driver, is used to pick packets destined to LSIs and send them to the HIP process. While this makes installation easier, the drawback is reduced performance as each user packet in a HIP association needs to be copied from user memory to the kernel, processed and sent back to the kernel to the real network interface.
HIP Architecture
Unlike the Linux version with kernel support, applications must connect using 32-bit LSIs to use HIP. The LSIs are of the form 1.x.x.x, where the last 24-bits are either the lower 24-bits of the HIT or some value specified in the identities file. A 1.0.0.0/8 route directs packets to the TUN/TAP driver (Linux) or the TAP-32 driver (Windows), where they are sent to a listening socket in the HIP process. The HIP process features multiple threads for handling traffic input and output, and PFKEY and netlink functions that are normally services provided by the Linux kernel. This was designed in a manner such that the HIP daemon code (hipd) can be completely reused, running as a single thread in this HIP userspace process.

The TAP driver is already included in the latest Linux kernels. For Windows, you may need to download and install the TAP-32 driver. Also, Cygwin is required if you want a development environment in which you can compile HIP for Windows.

4.0 Compliance with HIP specifications

This version complies with the base-03 version of the HIP base protocol specification [1] along with esp-00 version of the ESP transform draft [4].
This software implements draft-02 version of the End-Host Mobility and Multi-Homing with HIP draft [3], with the following exceptions and caveats: DHT support is implemented as described in [5] and Hi3 support as described in [6].

5.0  Interoperability

This version was tested with three other implementations in the past:
To verify the operation of your HIP installation, you can visit the Boeing HIP test server at:
http://hipserver.mct.phantomworks.org/
The test server was established to check interoperability among the other implementations. For more information on using the server, please visit the URL shown above.

6.0  Files

These directories can be found in this distribution:

7.0  Installation

Please see the Implementation Architecture section to become familiar with the required packages prior to installation. These are installation instructions for compiling from source code; if you have downloaded a precompiled binary (e.g. Windows installer) version, please instead use instructions that came with that binary package.

7.1.1 Kernel patch

The kernel patch is only required if you want to run HIP in Linux with Linux kernel support as described previously. If you are running HIP for Windows or Usermode HIP (UMH) in Linux, skip this step.

Copy the kernel source tarball to a build area, normally /usr/src. Get the HIP kernel patch and apply it to the kernel source. Configure the kernel (make xconfig) using the following options:
Device Drivers / Networking support / Networking options
   HIP Implementation (CONFIG_HIP=y)
   PF_KEY sockets (CONFIG_NET_KEY=y)
   IP: AH transformation (CONFIG_INET_AH=y)
   IP: ESP transformation (CONFIG_INET_ESP=y)
   IPsec user configuration interface (CONFIG_XFRM_USER=y)
 And for IPv6 support (do not compile as modules):
Code maturity level options
   Prompt for development and/or incomplete code/drivers (CONFIG_EXPERIMENTAL=y)
Device Drivers / Networking support / Networking options
   The IPv6 protocol (CONFIG_IPV6=y)
     IPv6: AH transformation (CONFIG_INET6_AH=y)
     IPv6: ESP transformation (CONFIG_INET6_ESP=y)
 Also add desired cryptographic options:
Cryptographic options
   HMAC support
   Null algorithms (CONFIG_CRYPTO_NULL=y/m)
   MD5 digest algorithm (CONFIG_CRYPTO_MD5=y/m)
   SHA1 digest algorithm (CONFIG_CRYPTO_SHA1=y/m)
   DES and Triple DES EDE cipher algorithms (CONFIG_CRYPTO_DES=y/m)
   BLOWFISH cipher algorithm (CONFIG_CRYPTO_BLOWFISH=y/m)
   AES cipher algorithms (i586) (CONFIG_CRYPTO_AES_586=y/m)
If upgrading from a 2.4.x series kernel, we suggest compiling all the necessary drivers and options into the kernel rather than using the loadable module support; the 2.6 kernel modutils are incompatible with previous (2.4) kernels, so installing them may eliminate booting other kernels on your system. Compile the kernel, which can take quite a bit of time, and install the boot image into your boot loader.
su
cp /mnt/cdrom/packages/linux-2.6.12.5.tar.bz2 /usr/src
cp /mnt/cdrom/kernel/linux-2.6.12.5-hip.patch /usr/src
tar xjf linux-2.6.12.5.tar.bz2
mv linux-2.6.12.5 linux-2.6.12.5-hip cd linux-2.6.12.5-hip
patch -p1 < ../linux-2.6.12.5-hip.patch
make xconfig
After selecting the appropriate options, build the kernel with:
make bzImage
make modules
make modules_install
make install
Or you can manually copy the kernel instead of running 'make install':
cp arch/i386/boot/bzImage /boot/vmlinuz-2.6.12.5-hip
cp System.map /boot/System.map-2.6.12.5-hip

On some systems it may be necessary to set the environment variable ARCH=i386, if the compiler produces errors about missing architecture directories. Make a symbolic link /usr/src/linux to the new kernel directory so that other packages will later build correctly:
ln -s /usr/src/linux-2.6.12.5-hip /usr/src/linux

If you ran 'make install' as shown above, an entry for the new HIP kernel should be already added to your bootloader. Two common bootloaders used in Linux are LILO and GRUB. For LILO, edit /etc/lilo.conf to add an entry for your new HIP kernel, and finally issue the command lilo before rebooting. Here is an example lilo.conf entry:
image=/boot/vmlinuz-2.6.12.5-hip
        label=HIP
        read-only
        append="hdc=ide-scsi root=LABEL=/"
For GRUB, edit /etc/grub.conf and add an entry for your new HIP kernel. Here is an example grub.conf entry:
title HIP (2.6.12.5-hip)
        root (hd0,5)
        kernel /vmlinuz-2.6.12.5-hip ro root=LABEL=/ hdc=ide-scsi
After making necessary changes to your bootloader, you are ready to reboot your machine and select the HIP kernel for booting. Note that it is a good idea to leave your existing kernel intact and leave its GRUB or LILO entry in place just in case there is a problem booting your new HIP kernel.

7.1.2 Cygwin and Windows preparation

Cygwin needs to be installed if you want to compile HIP for Windows. If you are installing to Windows from a binary install/setup package, you do not necessarily need to install Cygwin.

Download and install Cygwin from http://cygwin.com. Run cygwin-setup.exe. Choose "install from Internet" to get the latest packages. This software was tested using Cygwin version 1.5.12-1 to 1.5.18.1 (released 7/2/05). Make sure the following packages are installed:
Base > diffutils
Devel > autoconf, automake, binutils, bison, byacc, flex, gcc, libiconv, libtool, libxml2, make, openssl-devel, patchutils openssl, libxml2, libiconv
Interpreters > Perl
Libs > w32api, crypt
Utils > patch
Get the TAP-Win32 driver. Download OpenVPN 2.0.1 (or newer) from http://openvpn.net/. When running the setup program, you can choose to install only the TAP-Win32 driver. Version 2.0.1 (8/16/05) of OpenVPN can be used to install TAP-Win32 driver version 8.0.0.1 (5/15/04) which appears as "TAP-Win32 Adapter V8".

Setup the TAP-Win32 driver. Click on Start > Control Panel > Network Connections. Right-click on TAP-Win32 (choose View > Details and look under device name) and choose properties; click on "Internet Protocol (TCP/IP)" and click Properties. Select "Use the following IP address:" and enter 1.0.0.1 with a subnet mask of 255.0.0.0; default gateway and DNS should be blank. Click OK and close to apply these IP address changes. Now open the TAP-Win32 properties sheet again, click on the "Configure" button and select the "Advanced" tab. Click on "MTU" and enter 1400 for the value.

Also under Windows XP, make sure that the "IPSEC Services" service is disabled. Look in Start > Control Panel > Administrative Tools > Services. Also, the Windows XP firewall or any other firewall software you may have installed need to allow traffic from the program hip.exe (built later), or specifically allow protocol 99 and 50 (ESP) traffic.

7.2 IPsec Tools

To install the IPsec tools, untar the source tarball to a build area and apply the HIP IPsec tools patch. Configure and build the tools as normal.
cd ~
tar xzvf /mnt/cdrom/packages/ipsec-tools-0.6.tar.gz
cd ipsec-tools-0.6
patch -p1 < /mnt/cdrom/ipsec/ipsec-tools-0.6-hip.patch
./configure
make install

The HIP patch adds some custom messages to libipsec, and for the setkey tool enables the "hip" keyword to be defined in place of "esp", which indicates that a HIP ESP connection is desired for that source, destination pair. The provided config_ipsec_v4.sh script demonstrates this for IPv4:
#!/usr/local/sbin/setkey -f
flush;
spdflush;
 
spdadd 10.0.0.1 10.0.0.2 any -P out ipsec
        hip/transport//require;

This shows the policy setup for hosts 10.0.0.1 and 10.0.0.2. 10.0.0.1 acts as the initiator, and the script only needs to be run on the initiating host to trigger the HIP exchange with outbound traffic.

The config_ipsec_v6.sh script shows example rules for a similar IPv6 network:
#!/usr/local/sbin/setkey -f
flush;
spdflush;
 
spdadd ::/0 ::/0 icmp6 -P in none;
spdadd ::/0 ::/0 icmp6 -P out none;
 
spdadd dead:1::1 dead:1::2 any -P out ipsec
        hip/transport//require;

Here the host with IPv6 address dead:2::1 initiates a connection to the host dead:2::2. Notice the rules which allow ICMPv6 traffic to pass through; this is necessary for the IPv6 neighbor solicitation/advertisement mechanism to work so the peer host may be reached.

Run the command setkey -DP  after running one of the above scripts to display IPsec policies. Note that the "hip" keyword will now be replaced with "esp" in the display, this is normal. The command setkey -D  displays security associations that are in place. After a successful HIP exchange, issuing that command will show the addresses, SPIs, and keying material in use. Finally, use the commands setkey -FP  to flush (erase) all installed policy rules and setkey -F  to flush all installed security associations. When hipd exists normally, it will take care of deleting the associations and policies that it has installed.

In Windows, you will also need ipsec-tools-0.6.hip.win32.patch. The setkey tool is not used, only libipsec. Use the following commands:
cd ~
tar xzvf /mnt/cdrom/packages/ipsec-tools-0.6.tar.gz
cd ipsec-tools-0.6
patch -p1 < /mnt/cdrom/ipsec/ipsec-tools-0.6-hip.patch
patch -p1 < ipsec-tools-0.6-hip.win32.patch
rm -rf src/racoon src/setkey
aclocal
autoconf
./configure --prefix=/usr --with-kernel-headers=kernel-header
make install

7.3 hipd and hitgen

The C source code for hipd and hitgen are provided in the src directory. Copy the source to a build area and use make to compile.
cd ~
mkdir hipd
cd hipd
cp -r /mnt/cdrom/src .
cd src
If building for Linux/kernel or Windows, type:
make
if building Usermode HIP for Linux, use:
make umh
When building, the linker searches for the crypto, libxml2, and libipsec libraries. One requirement is that /usr/src/linux links to or contains the patched 2.6 kernel source:
ln -s /usr/src/linux-2.6.12.5-hip /usr/src/linux

A successful build results in the hitgen binary, and the hipd binary if compiling on Linux with kernel support. For Windows or Usermode HIP in Linux, build the hip.exe or hip binaries from the win32 directory:
cd ../win32
make
You can run the HIP daemon from any directory (there is no 'make install'), and it looks for its configuration in /etc/hip and optionally writes a log to /var/log/hipd.log. In Windows and Usermode HIP, the hip process looks for all of its configuration files in the current (i.e., win32) directory. Please refer to the Configuration section to get HIP up and running.

7.4 Ethereal

This is not required for running hipd, but is a tool for observing the HIP exchange and learning about HIP protocol packets. It is also a good tool to verify that you traffic is being protected by ESP as intended. Patching, compiling and installation follows the same process as IPsec Tools.
cd /usr/local/src
tar xjvf /mnt/cdrom/packages/ethereal-0.10.12.tar.bz2
cd ethereal-0.10.12
patch -p1 < /mnt/cdrom/ethereal/ethereal-0.10.12-hip.patch
./configure
make install
HIP packets are protocol 99 IP datagrams.

7.5 Configuration

The HIP configuration files are in XML format. In Windows and UMH they should be located in the current directory and have the '.xml' extension (the paths listed below are for Linux). Use the hitgen utility to generate these files for you. hitgen generates RSA keys that are used as your Host Identities, and their corresponding HITs.

The /etc/hip/hip.conf file (that was created when hitgen -conf was run) contains various user-configurable parameters. You can edit the file with any text editor. Most items are self-explanatory: the difficulty in bits for K in the cookie, the number of retransmission attempts that should be made, etc. The transforms section contains a list of supported transforms for HIP and for ESP that will be proposed in the R1 packet. Transforms are listed in order of preference, so the initiator that receives an R1 examines the list and picks the first one that it supports. See the HIP or ESP draft for the meaning of the values. For example, the default is to use AES encryption for the encrypted transform of the I2 packet:
  <hip_sa>
    <transforms>
      <id>1</id>
      <id>5</id>
    </transforms>
  </hip_sa>
 ...but if you want to use NULL encryption instead, you would list:
  <hip_sa>
    <transforms>
      <id>5</id>
      <id>1</id>
    </transforms>
  </hip_sa>

Options not included when running higten -conf are:
The /etc/hip/known_host_identities file has other optional parameters:
Other files involved with configuring HIP:
For Windows, you can optionally (this is recommended) install HIP as a Windows service, use "./hip.exe -i". Because the HIP service requires Cygwin to run, you need to append C:\cygwin\bin to your path in the Environment Variables (right click on My Computer > Properties > Advanced tab > Environment Variables) Now you can start and stop the HIP Windows service using this Services list from the Control Panel.

8.0 Usage

Hipd can be run with the following command-line parameters:
  -v     show verbose debugging information. You will want to use this option to observe what is going on during the protocol exchange.
  -q     quiet mode, only errors are shown
  -d     daemon mode, fork and write all output to the logfile
  -r1     show the pre-calculated R1 generation debugging output. Normally this output is suppressed as it can be quite verbose.
  -o     opportunistic (adopt HIT received in R1 and do not require HITs to be pre-configured)
  -p     permissive -- doesn't enforce signature validation, correct checksums, etc. (for debugging).
  -nr    no retransmit mode (for testing)
  -i3    enable Hi3: use the i3 overlay network for control packets
Use either -v or -q to control the amount of console output you want; with neither parameter, hipd defaults to a simple output. If you do not want to pre-share HITs among the hosts, enable opportunistic.

Here are the steps you would take to get two IPv4 hosts to establish HIP-enabled security associations on Linux with kernel support. For Windows or UMH, see the separate text below. Here the hosts have the addresses 10.0.0.1 and 10.0.0.2, with 10.0.0.1 initiating the HIP exchange opportunistically.
  1. Compile and install the HIP-enabled kernel, IPsec tools, and the HIP software.
  2. Boot to the HIP kernel. You can verify the current running kernel by typing uname -a
  3. Run this command on each host, to configure HIP if you don't already have the /etc/hip.conf file:
    ./hitgen -conf
    Also, you will need to create an empty /etc/hip/known_host_identities file, which would need entries for each peer HIT if not running in opportunistic mode (see further instructions later).
  4. Run the config_ipsec_v4.sh script on 10.0.0.1 to set an outbound traffic policy:
    ./config_ipsec_v4.sh
    Any packets sent from 10.0.0.1 to 10.0.0.2 will be trapped by the kernel, with the kernel notifying the hipd process.
  5. Start the hipd process on each host:
    ./hipd -d -v -o
    You can now monitor the daemon's output:
    tail -f /var/log/hipd.log
  6. Run ethereal and begin capturing if desired:
    ./ethereal &
  7. Trigger the hip exchange and establish HIP SAs with some form of traffic originating from 10.0.0.1 destined for 10.0.0.2:
    ssh 10.0.0.2
If successful, you should see an "SA established" message on the screen. If you are capturing the network activity with Ethereal, you can observe that packets traveling between 10.0.0.1 and 10.0.0.2 are now encapsulated in ESP.

Note: when using SSH or other programs to trigger a HIP exchange, you will likely see the message "resource temporarily unavailable". This is a known bug in the 2.6.x kernel IPsec, and is the same behavior experienced when using the ipsec-tools racoon keying daemon. Currently, there is no patch available to properly fix this shortcoming. See this kernel mailing list thread.

If you do not want to run in opportunistic mode (with the -o option shown above), then you need to preconfigure HITs by doing the following:
./hitgen -file myhits -publish
And copy each resulting myhits file to the peer's known_host_identities file; copy the file from 10.0.0.1 to /etc/hip on 10.0.0.2, and vice versa. This gives each host knowledge of the other's Host Identity Tags associated with its hostname or IP address. The peer's hostname as specified by <name> </name> (only the part before any '-' character is used; so the HI with name 'initiator-2048' would give the name 'initiator') must exist in DNS or the /etc/hosts file. Otherwise the peer's address should also be listed with its HI, using the <addr> tag as described in the Configuration section.

You can stop the daemon by typing killall hipd (or use kill on the process ID) when the daemon is forked and running in the background, or by pressing CTRL+C when hipd is running as a foreground application. The HIP daemon will then exit and delete the security associations and policies that it has added. Use the setkey command from IPsec tools to manually modify these.

Note: often a firewall in Linux will drop HIP packets so the HIP exchange never takes place. If you are receiving R1s in Ethereal, but they are not being received by you daemon, chances are that iptables is dropping them. For RedHat Linux you can add appropriate rules to allow protocol 99 traffic to pass through the firewall -- add the following lines to /etc/sysconfig/iptables:
-A RH-Firewall-1-INPUT -p 50 -j ACCEPT
-A RH-Firewall-1-INPUT -p 51 -j ACCEPT
-A RH-Firewall-1-INPUT -p 99 -j ACCEPT
 This allows inbound ESP and protocol 99 traffic. For other Linux systems you could issue the commands:
iptables -A INPUT -p 50 -j ACCEPT
iptables -A INPUT -p 51 -j ACCEPT
iptables -A INPUT -p 99 -j ACCEPT
 For Windows or UMH, you will instead run hip.exe or hip.
  1. Compile HIP as described in the Installation section.
  2. Make sure you have hip.conf, my_host_identities.xml, and known_host_identities.xml files located in the same directory as hip.exe or the hip binary, as described in the Configuration section.
  3. Either start the HIP for Windows service via the control panel, or run hip from the console with:
    .\hip.exe -v (Windows)
    ./hip -v (Linux)
  4. look at the output for "Loading Host Identity Tag..." for the peer you want to communicate with, and note the 32-bit LSI of the form 1.x.x.x. Note that you can override the last 24-bits with the LSI of your choosing in the known_host_identies file -- make an entry <LSI>1.2.3.4</LSI> for the number of your choosing, within the host_identity tag for that peer.
  5. initiate a connection to the peer:
    ping 1.2.3.4
If successful, you should see an "SA established" message. Use Ethereal to see that traffic encapsulated in ESP.

9.0 Mobility

Mobility events are triggered in this implementation by readdressing the interface on which a HIP SA is running:
ifconfig eth0 10.0.0.10
In the example from the Usage section, one of the hosts could issue the ifconfig command and this would cause it to send an UPDATE message with the LOCATOR parameter containing the new address. Upon completion of a readdress procedure, HIP security associations and any open TCP sessions should remain connected since they are based on HITs instead of IP addresses.

Currently, IPv4 ssh does not endure a readdress, resulting in a "connection closed by peer". This occurs when the SSH daemon sshd is listening on both IPv4 and IPv6 sockets. To fix this, edit the sshd configuration file (/etc/ssh/sshd_config) and uncomment the line:
"ListenAddress 0.0.0.0" while leaving the line "ListenAddress ::" commented. Restart sshd (/etc/init.d/sshd restart) and retry the HIP association with mobility. This problem does not occur for IPv6.

IPv6 readdressing is similar to IPv4. The "preferred" address must first be deleted and then a new address added. This can be accomplished via a script such as the readdress6.sh script included in the scripts directory:
ip -6 addr del dead:2::2/128 dev eth1
ip -6 addr add dead:2::7/128 dev eth1
 Note that when you remove the preferred address, you may experience the problem of the proper routing entries being removed as well. This causes an error with hipd when it tries to send an UPDATE packet but has "no route to host". You can either re-add routes from a readdressing script, or add multiple addresses to the interface before deleting one.

Readdressing across address families (i.e., IPv4 to IPv6 address) has not yet been implemented.


References

  1. Host Identity Protocol base specification draft-ietf-hip-base-03.txt
  2. Host Identity Protocol Architecture draft-ietf-hip-arch-02.txt
  3. End-Host Mobility and Multi-Homing draft-ietf-hip-mm-02.txt
  4. ESP transform format with HIPdraft-ietf-hip-esp-00.txt
  5. HIP DHT interfacedraft-ahrenholz-hiprg-dht-00.txt
  6. Host Identity Indirection Infrastructure (Hi3)draft-nikander-hiprg-hi3-00.txt