From OpenHIP
Jump to: navigation, search

Main Page - Overview - Installation - Configuration - Usage - Contributing - Doxygen - Links

This section is devoted to some practical use scenarios for HIP.

Note that different extensions may work on or have been tested on only some subset of the possible HIP configurations (e.g., Windows, Linux in kernel, Linux in user-space)... below, we try to clarify what mode of HIP has been tested for each.

What has been tested

The table below is meant to help sort out the different features and on which platforms they are supported. It complements our Release_Notes page.

Testing Status
feature Linux kernel Linux U-M Win XP U-M OS X U-M
IPv4 Base exch + ESP 0.4 0.9 0.9 0.8
IPv6 Base exch + ESP 0.3.4 0.9 X 1
mobility 0.3.4 0.9 0.9 0.3.3?
NAT X 2 0.9 0.9 0.7
RVS 0.3.3? 0.8
DNS X 3 0.8 0.4 0.3.3?
DHT 0.3.1? 0.3.1? 0.3.1?
mobile router X 0.8 X X
endbox X 0.9 X X
IPv6 over IPv4 X 2 0.8 0.3.4
IPv4 over IPv6 X 2 0.6 X 1

Key: 0.3.4 = tested with given version number, X = not supported, ( )(empty space) = not yet tested, CVS = support in CVS version (next release)


  1. Windows disallows an IPv6 socket bound to protocol 50 (ESP)
  2. Limitation due to using built-in Linux kernel implementation
  3. Would require modified resolver or LD_PRELOAD


A HIP test server is available for testing if your software or setup works with the latest version of OpenHIP:

For notes on interoperability with other HIP implementations, see Interoperability.

Automated Testing

Starting with release 0.9, the OpenHIP source features a 'make check' framework for running automated tests within lightweight virtual machines. See the Testing page.

NAT Traversal

As of release 0.7, OpenHIP sends its control (HIP) and data (ESP) packets over UDP. Currently the HIP UDP port 10500 is used for both source and destination UDP ports. (Version 0.7 and earlier used UDP port 50500.) New outbound associations are initiated over UDP by default. Incoming associations are matched with what the initiator chose, UDP or non-UDP.

To turn off the default UDP encapsulation for outbound associations, use the following hip.conf option:


With UDP disabled in the config file, outbound associations will use HIP protocol 139 for control packets and ESP protocol 50 for data. The host will still listen on the UDP port 10500 and respond to any HIP requests on the port using UDP encapsulation.

At this time configuration is global and not available per HIP peer. Support for STUN address detection, TURN servers, and HIP UDP relay servers has not been added yet. This will likely cause problems if you want to initiate to a host behind a NAT, unless you configure port forwarding for port 10500 on the NAT device. Support for IPv6 over UDP has not been added yet.

The NAT traversal support follows this draft:

  • draft-ietf-hip-nat-traversal-08
  • support for STUN and TURN servers has not been added yet

Rendezvous Extension

Starting the Rendezvous Server (RVS)

Start hip in Rendezvous Server mode using the -rvs flag:

  sudo hip -v -rvs

No other special configuration is required. When a host initiates with this server, it will offer the Rendezvous service in the R1 packet, and openhip initiators will register with that RVS server by default. Once a client is registered, I1 packets received having the client's HIT will be forwarded on to the client using its current preferred address. The FROM and RVS_HMAC parameters are added to this relayed I1 packet.

Registering RVS clients

Clients may register with the server by establishing an association with the server. Openhip clients by default will request registration with the Rendezvous service when they see the service offered by the server's R1 packet. One way to establish this association would be pinging the LSI of the RVS.

Base exchange using the RVS

An initiator may use the RVS by configuring the <RVS>a.b.c.d</RVS> IP address in the known_host_identities.xml file:


When the <RVS> tag is included, the initiator sends its I1 packet to the RVS address instead of the destination specified by the <addr> tag. The RVS will look up the receiver HIT and drop the packet if the responder has not already registered with the RVS. If the responder is a valid RVS client, the I1 is forwarded to the responder, and the responder replies directly to the initiator.

This RVS extension follows these specifications:

HIP DNS records

Status: The DNS extensions work for the user mode version in Linux or Windows. For supporting the Linux kernel version, the native Linux resolver library needs to be modified.

HIP DNS Server

In order to serve the HIP DNS records, you need to run a modified BIND 9.x server that understands the HIP RR type. (The HIP patch to BIND will be available from the OpenHIP download site in the near future.) The patch uses RR type 55 for experimentation purposes -- the actual HIP RR type requires IANA allocation.

Here are instructions for patching the BIND server:

  1. Download and unpack the BIND 9.x server
    tar xzf bind-9.3.2.tar.gz
  2. Copy the HIP RR files to the proper directory:
    cp hip_55.c bind-9.3.2/lib/dns/rdata/generic/
    cp hip_55.h bind-9.3.2/lib/dns/rdata/generic/
  3. Compile BIND in the usual fashion (run make clean if recompiling)
    (Below the configure command for Fedora Core 4 is shown. With Fedora, you also need to patch with bind-9.2.0rc3-varrun.patch from the src rpm.)
    ./configure --prefix=/usr --sysconfdir=/etc --localstatedir=/var
    make install 
  4. Use the included hi2dns utility to add HIP RRs to your zone files.

The hi2dns utility reads the my_host_identities.xml file and outputs each Host Identity in the proper RR format for inclusion into the server's zone file.

HIP client-side DNS

If you compile the modified BIND package as shown in the previous section, the successful build results in modified nslookup and dig binaries. You can use the nslookup or dig utilities to test the lookup of HIP records from your modified server.

HIP DNS support is only available in the user-mode version. In the user-mode version, no modifications to the resolver are needed since DNS requests are already intercepted and processed by the hip_dns thread (in a way, this thread implements its own resolver).

The HIP daemon uses DNS as follows:

  1. User application tries to connect to ""
  2. The hip_dns thread intercepts the request and tries to resolve HIP information due to the ".hip" suffix
    • Is ths name "" found in known_host_identities.xml? If so, the LSI is returned to the application. If an LSI has not been specified, the lower 24 bits of the HIT are used to form a 1.x.x.x LSI to return to the application.
    • When the name is not found locally, DNS is consulted. HIP issues a request for the HIP record corresponding to "". This request goes to the server specified by the dns_server option in hip.conf, or, if that option was not specified, the normal DNS server found in resolv.conf (or the Window's registry) is used.
    • If the name is not found locally or in DNS, non-existant domain NXDOMAIN is returned to the application.
  3. The application continues the connection attempt to the provided LSI.
  4. Connecting to an LSI triggers the HIP exchange. The HIT information from known_host_identities.xml or DNS is used to send an I1. If no HIT configured in the known_host_identities.xml file (i.e. an entry containing only name and LSI), an opportunistic I1 may be sent if the opportunistic option is turned on. The destination IP address for the I1 comes from either the known_host_identities.xml file, or an additional DNS lookup of the A/AAAA record. (Only this time, the normal resolver library call is used, so the normal DNS server is consulted.)

Further notes about DNS usage:

  • When the known_host_identities.xml file is loaded, names that have no address configured are resolved for A/AAAA records. To supress this behavior, use the <disable_dns_lookups>yes</disable_dns_lookups> configuration option in hip.conf
  • Having HIP intercept all DNS requests from the system to look for the ".hip" suffix may cause some performance hit. In attempt to minimize any delay, the hip_dns thread will forward legacy (non-".hip") requests to the real DNS server found in /etc/resolv.conf (or Window's registry), and will forward replies back to the application.

    If you are concerned with these performance issues, you can disable the DNS thread entirely with the <disable_dns_thread>yes</disable_dns_thread> configuration option. You will then be able to use HIP by directly specifying 1.x.x.x LSI numbers (but not with ".hip" hostnames.)
  • Currently the list of rendezvous servers optionally found at the end of the HIP record is ignored by the HIP client. TODO: Save the rendezvous servers along with the peer's Host Identity in the peer list, and when attempting a connection, use each server address as the I1 destination address.

The support for HIP DNS records follows this draft:

  • draft-ietf-hip-dns-06

Using a DHT

Status: The DHT extensions have been tested on the user-mode version for Linux and Windows.

Distributed Hash Tables can be used with HIP to provide certain lookup services. The Host Identity namespace is flat and the current DNS system does not provide a suitable lookup mechanism for these flat, random values. DHTs manage such data well by applying a hash function that distributes data across a number of servers. DHTs also feature good support for updating stored values.

These lookup services have been defined:

  1. HIP address lookup: addr = get(HIT)
    Given a HIT, a lookup returns the preferred IP address of the peer.
  2. HIP HIT lookup: HIT = get(LSI)
    Given an LSI, a lookup returns the associated HIT.

HIP DHT server

The DHT server software requires no modifications to support these HIP lookup services. Bamboo DHT is a freely available implementation written in Java (runs on both Linux and Windows) that has been deployed on PlanetLab servers to form a free service named Open DHT. Open DHT uses a well-defined XML RPC interface to put and get values.

You can create your own private ring of DHT servers using the Bamboo software, or just configure one of the PlanetLab Open DHT nodes in your hip.conf file to use the Open DHT service.

DHT Server Installation

  • note that these instructions are really about installing Bamboo DHT, software developed elsewhere that is subject to change
  • first install Sun's JDK, for example: ./jdk-6u2-linux-i586.rpm.bin (for the JDK 1.6.0_02)
  • download, unpack, and build the bamboo software:
 tar xzf bamboo-cvs-2006-03-03.tgz
 export JAVAHOME=/usr/java/jdk1.6.0_02
 cd bamboo
 cd test
 perl -w
  • using the test menu, you can (4) start a node, (1) check its status, and use (2) and (3) to check for errors
  • configure the DHT using the sample location-test-node.cfg
 cp test/location-test-node.cfg hip.cfg
  • edit the .cfg file to customize your server; OpenDHT uses port 5852;
    • for example, if your server's address is, change these lines:
 homedir /tmp/experiment-1772-
 port 5852
  • run the DHT server (make sure JAVAHOME is still set properly):
 bin/run-java bamboo.lss.DustDevil hip.cfg

For more information:

HIP client-side DHT

To start using DHT services, a <dht_server></dht_server> and <dht_server_port></dht_server_port> entries must be configured in the hip.conf file. If no IP address is specified, DHT lookups are effectively disabled.

For the above server example, this would be the client configuration:

 <?xml version="1.0" encoding="UTF-8"?>

The DHT services are used as follows:

  1. upon startup, the HIP client will publish its <HIT, address> pair, so other hosts may determine where it's reachable
  2. when a new preferred address is selected, the address stored in DHT is updated
  3. when a peer HIT is first configured in the known_host_identities.xml file, an address lookup is performed if the normal DNS resolver cannot locate an address
  4. when trying to send an I1 packet but the destination address is not known, an address lookup is performed if the normal DNS resolver cannot locate an address
  5. when a HIP connection is requested for an LSI that has no HIT configured, the HIT lookup service is used to determine the HIT from the LSI


  • Open DHT previously did not support a remove operation, so addresses are added to a list, and only the last address from the list is used. This list would be seemingly ever-growing if the host changed addresses frequently, but every put operation has an associated lifetime. For frequently-moving hosts, this lifetime should be shortened so that old addresses expire more rapidly.
  • Currently the site identifier is not used (as specified by the DHT draft) and instead the base64 struct sockaddr LSI is published

The Distributed Hash Table support follows this draft:

  • draft-ahrenholz-hiprg-dht-00

HIP Mobile Router

This describes how to use the Mobile Router extension in OpenHIP. The HIP Mobile Router is described in draft-melen-hip-mr-02.txt. The OpenHIP implementation does not implement all of the functionality described in the draft. The HIP Mobile Router also uses the Security Parameter Index multiplexed Network Address Translation (SPINAT) described in draft-melen-spinat-01.txt and the Host Identity Protocol (HIP) Registration Extension, RFC 5203.

The Mobile Router and SPINAT functionality in OpenHIP is implemented as a thread in user-mode HIP. It uses the IPTABLES target of QUEUE for HIP and ESP packets in order to send those packet to the Mobile Router thread within HIP for performing the SPINAT. Note that this must be done at the prerouting stage because we allow for the translation between IPv4 and IPv6.

HIP Mobile Router Configuration

The mobile router should be a Linux host, this has not been developed for other platforms. The Netfilter queueing is the main reason you need to use Linux.

Prepare the appropriate iptables rules:

 modprobe ip_queue ip6_queue
 iptables -t mangle -A PREROUTING -p 50 -j QUEUE
 iptables -t mangle -A PREROUTING -p 139 -j QUEUE
 iptables -t mangle -A POSTROUTING -p 50 -j QUEUE
 iptables -t mangle -A POSTROUTING -p 139 -j QUEUE
 ip6tables -t mangle -A PREROUTING -p 50 -j QUEUE
 ip6tables -t mangle -A PREROUTING -p 139 -j QUEUE
 ip6tables -t mangle -A POSTROUTING -p 50 -j QUEUE
 ip6tables -t mangle -A POSTROUTING -p 139 -j QUEUE

(Note: the above rules are now added automatically by the mobile router thread.)

Turn on IP forwarding:

 sudo sysctl -w net.ipv4.conf.all.forwarding=1
 sudo sysctl -w net.ipv6.conf.all.forwarding=1

Add the following to your hip.conf configuration file:


This is the name of the publicly-accessible or outbound-facing interface, having the public IP address(es) that the mobile router will use for rewriting the source address of its SPINATed clients. If "external_interface" is not defined but "preferred_interface" is, HIP will treat the preferred interface as the external interface.

Start hip on the mobile router with the -mr switch:

 sudo hip -v -a -mr

Mobile Node Configuration

Nothing special needs to be configured at the Mobile Node (MN). The MN should first establish a base exchange with the MR to register with the mobile router service. The MN will automatically register if the mobile router service is offered. HIP associations with other hosts (CNs) should automatically be SPINATed at the MR.

Currently the MR SPINAT operates on HIP (protocol 139) and ESP (protocol 50) packets, but not with HIP/ESP encapsulated in UDP. Thus you should turn off UDP encapsulation when initiating from the mobile node by adding this line to your hip.conf:


Correspondent Node Configuration

Nothing special needs to be configured at the Correspondent Node (CN). The CN will send HIP traffic to the MN via the MR.

For interfamily handovers, the CN should initially be configured with both an IPv4 and IPv6 public address. These addresses are included in the R1 packet, so the MR has a set of addresses from each address family that are possible for use. In future versions the CN addresses may be communicated via UPDATE packets.


Configuring and using OpenHIP with endbox mode is documented here: Endbox. This mode, for realizing the Secure Mobile Architecture (SMA), involves using HIP to provide a L2VPN service.


Wireshark is useful for learning about HIP packets and seeing what is happening on your network. The development version 1.3.0 contains support for the HIP protocol. Alternatively, here is a guide for patching a release version, and here is some historical information.

Below is a Wireshark capture filter for capturing only HIP traffic. Under Capture Filter you would click New, enter a Filter name: such as HIP, and use the following for a Filter string:

  proto 139 or proto 50 or port 10500

This restricts Wireshark to capturing only HIP protocol 139, ESP protocol 50, and UDP port 10500 (HIP/ESP over UDP) packets.