From OpenHIP
Jump to: navigation, search

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

This section assumes that the build process has successfully completed-- that you have successfully built binaries of hip or hipd, and also hitgen stored in your /usr/local/sbin/ directory or other directory specified during the build process.

For the impatient, do the following:

cd /usr/local/sbin/
./hitgen -conf
./hitgen -publish

This will leave you with the following

  • /usr/local/etc/hip/my_host_identities.xml Host Identity and HIT for your machine
  • /usr/local/etc/hip/hip.conf HIP configuration file
  • /usr/local/etc/hip/<hostname> HITs and other information to provide to other hosts (where <hostname> is your Unix hostname)

For more details, please read on. There are a few configuration steps needed before running HIP:

  1. creating and storing the my_host_identities.xml file
  2. editing and storing your hip.conf file
  3. editing and storing the known_host_identities.xml file
  4. configuring your IPsec policies (Linux kernel mode only)
  5. deciding on which options to run

Note: These instructions may be tailored to Linux user mode right now-- consult doc/hipdoc.html for other instructions for the moment.

Local host identity

Like ssh, HIP needs to store keys somewhere on the system. There are two types of keys that must be stored: your own Host Identities (there may be multiple on a system, including public and private key parts) and host identities of peer systems with whom you communicate.

Where to store keys and how to guarantee key security is a detailed subject on which we do not go into great detail right now. By default, we recommend the following, although for experimenting, other solutions are possible:

  • the my_host_identities.xml file containing public and private keys in use by hipd should be stored in /usr/local/etc/hip/my_host_identities.xml (on Linux) and should have the following permissions:
-rw-------   1 root root 5036 2006-01-18 15:47 my_host_identities
  • the known_host_identities.xml file should be stored in the same directory as the my_host_identities.xml file. Since these are public keys, the access control on this file is not as important.


The hitgen program is used to generate host identities. It has the following options:

usage: hitgen   [-v] [-name <string>] [-type DSA|RSA] [-bits|length <NN>] [-anon] [-incoming]
                [-file <file>][-publish] [-conf]
The optional parameters are:
 -v              show verbose debugging information
 -name <string>  is the human-readable handle for the HI
 -type  followed by "DSA" or "RSA" specifies key type
 -bits           specifies the length in bits for (P,G,Y)
 -length         specifies the length in bytes for (P,G,Y)
 -anon           sets the anonymous flag for this HI
 -incoming       sets the allow incoming flag for this HI
 -file <file>    write output to the specified file
 -publish        extract HITs from the '/etc/hip/my_host_identities' file and
                 create a file named 'known_host_identities'
                 in the HIP directory
 -conf           generate a sample conf file to '/etc/hip/hip.conf'
                 (overwrites existing hip.conf file)
 -noinput        don't ask to seed random number generator

Typically, one might run it as follows:

softball:~/hipd/bin> ./hitgen -type RSA -name softball -bits 1024
To seed the random number generator, please type some random text:
Generating a 1024-bit RSA key
Generating RSA keys for HI...
Storing results to file 'my_host_identities.xml'.

resulting in a file looking like the following:

<?xml version="1.0" encoding="UTF-8"?>
  <host_identity alg="RSA" alg_id="5" length="128" anon="no" incoming="yes" r1co

The process of calling "./hitgen" will create this file in the ../etc/hip/my_host_identities.xml" location with the permissions set to "rw" for root only.


A basic hip.conf file is provided by default in the directory ~/hip/conf, or can be generated by running "hitgen -conf" (which deposits it in the /usr/local/etc/hip/ directory on your machine). hip.conf controls the parameters governing your HIP daemon.

Here is a default hip.conf file:

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

hip.conf Options:

  • cookie_difficulty - sets the puzzle difficulty for outgoing puzzles. The difficulty is the puzzle value K indicating the number of lowest order bits that must be zero after the Responder hashes a random number plus other puzzle data.
  • cookie_lifetime - sets the puzzle's valid lifetime, 2^(lifetime-32) seconds; the default value of 39 = 2^(39-32) = 128 seconds.
  • packet_timeout - seconds to wait before retransmitting a HIP packet
  • max_retries - the number of packet retransmissions before failure
  • sa_lifetime - seconds before an SA expires and must be updated; for Linux kernel-mode IPsec, the lifetime is set when adding the SA and the kernel will expire the SA automatically
  • preferred_hi - sets the preferred Host Identity to use from my_host_identities.xml
  • send_hi_name - whether or not to include the Domain Identifier along with the Host Identity in HIP control packets
  • dh_group - sets the default Diffie Hellman group ID to use; possible values 1-6 are defined in the HIP specification; default value of 3 specifies the 1536-bit MODP group.
  • dh_lifetime - number of seconds to cache precomputed Diffie Hellman values
  • r1_lifetime - number of seconds to cache precomputed R1 packets
  • failure_timeout - number of seconds to remain in the state E_FAILED before transitioning to UNASSOCIATED, and how long to remain in the state REKEYING before timing out.
  • msl - maximum segment lifetime - the maximum time in seconds that a TCP segment is expected to spend in the network, used to time out states
  • ual - unused association lifetime - number of seconds after which an active association is brought down due to inactivity (no packets sent or received)
  • hip_sa and esp_sa transforms - specifies the HIP/ESP cryptographic transforms to advertise in the R1 packet; the order they are listed determines the order inserted into the R1 packet; numeric values correspond to Suite-IDs listed in the HIP specification -- e.g. 1 represents AES-CBC with HMAC-SHA1
  • dht_server - IP address specifying a Bamboo DHT server for storing/retrieving HIP information; this is optional -- if no server is specified, the DHT will not be used
  • dht_server_port - XML RPC port for the DHT server
  • dns_server - IP address specifiying the DNS server that stores the HIP RRs; this is optional -- if no server is specified, the system's default DNS server is contacted (as specified in /etc/resolv.conf for Linux or in the Window's registry)
  • disable_dns_lookups - disable address resolution for peers whose IP address is unknown, default is false
  • disable_notify - disable the sending of informational NOTIFY packets, default is false
  • disable_dns_thread - disable the dummy DNS server that listens on a loopback address for requests ending with ".hip"; this will prevent HIP from interfering with the system's normal address resolution, default is false
  • enable_broadcast - Whether broadcast packets are to be replicated and sent over unicast SAs, default is false
  • min_lifetime - Rendevous server parameter: minimum registration lifetime offered by the RVS - 2^(min_lt-64)/8 seconds, default is 96
  • max_lifetime - Rendevous server parameter: minimum registration lifetime offered by the RVS - 2^(min_lt-64)/8 seconds, default is 255
  • reg_type_rvs - Rendevous server parameter: registration type offered by the RVS, default is 1
  • lifetime - lifetime that the client requests during registration, default is 255
  • reg_type - registration type requested by the client during registration, default is 1
  • preferred - Preferred IPv4 or IPv6 address, default is auto-selected
  • preferred_iface - Preferred network interface (if there are multiple to choose from), default is NULL
  • save_known_identities - Whether to save the learned identities to known_host_identities.xml before the daemon exits, default is TRUE
  • lsi_prefix - Specify the n.x.x.x/8 prefix to use, with the default being; note that if this value is changed, the LSI entries in your my_host_identities.xml and known_host_identities.xml files should be manually update to match the given prefix.

Moving your hip.conf file: When you start your hip daemon, the daemon needs to know where to find this file. By default, the path to the hip.conf file is /usr/local/etc/hip/hip.conf. This may be overridden by providing a "-conf" argument when starting the daemon (described below). You as a user need to decide where you want to place this file, and if placed in non-default place, either change the location defined in hip/src/include/hip_types.h and recompile, or run the daemon with the -conf argument specifying where to find the file.

So before proceeding, review the hip.conf file provided in the conf/ directory, make any changes, and decide to move it to /usr/local/etc/hip/hip.conf or else move it somewhere else and later tell the hip daemon where to find it.


This file stores the known HITs of other hosts that you may want to communicate with, and also any other tags needed to resolve the host identity ultimately to an IP address.

These tags include:

  • <LSI> A local scoped identifier </LSI>
  • <name> A hostname </name>
  • <addr> An IP address </addr>

starting with an existing host identity

In the conf/ directory, the HIT for the Boeing hipserver is provided in a known_host_identities.xml file.

<?xml version="1.0" encoding="UTF-8"?>
  <host_identity alg="RSA" alg_id="5" length="128" anon="no" incoming="yes">

You can see that this record contains the HIT, an LSI (here it is derived from the HIT, but it could perhaps be some other 32-bit quantity, such as, and a hostname. When no address is specified, the HIP daemon will attempt to resolve the specified hostname (without the characters including and following "-"). The hostname is also used in the user-mode version when resolving ".hip" names -- the above entry, for example could be seen with "nslookup".

This file will be placed into the /usr/local/etc/hip/ directory when you install HIP (unless you override the target installation directory). It can be added to as described below, and the HIP daemon will also append learned host identities before the process exits each time.

publishing your own host identity

You may want to give your HIT to someone else for use in their known_host_identities.xml file. To do this, you "publish" your HIT to a file using the following command:

su -c "./hitgen -publish"

This will generate a file with the name "<hostname>" in the ../etc/hip/ directory. This file can then be shared with other users.

adding IP address information to host identities

If the peer is not using a DHT or DNS, there needs to be someway to get the IP address binding for the HIT. This can be stored in the known_host_identities.xml file with an <addr></addr> field.

For instance, the Boeing hipserver is at IPv4 address, so you can add:


below the LSI field in the known_host_identities.xml record for hipserver.

how this file is used

In user-mode HIP, there are two ways to invoke HIP:

  1. DNS queries are intercepted for the ".hip" suffix, and the known_host_identities.xml file is consulted. If a matching name is found, the HIP shim returns a spoofed A/AAAA record containing the LSI for the host. If the name is not found, HIP will look for the HIP record in DNS containing to get the Host Identity of the specified host name. The shim also determines the IP address of the host, either written in the known_host_identities.xml, or via DHT or DNS lookup. The socket calls use this LSI, which the HIP shim NATs to the IP addresses.
  2. Alternatively, the LSI can be provided at the socket directly. For example, "ping" will set up a HIP connection to the host corresponding to LSI The hip daemon must be able to resolve the LSI correctly (see the previous subsection).

IPsec configuration

(not applicable for user mode HIP-- for kernel-enabled HIP, see the hipdoc.html file)

Starting the daemon

We are working on a GUI that will allow users to control the service from a desktop application. For now, here are low-level ways to start the service.


The easiest way to start HIP is through the shortcuts available in the Start menu, either the "HIP (console mode)" shortcut (black key icon) or the system tray application "HIP monitor" (green key icon). To use the system tray icon, right click on the red key, and choose "Service" and "Start HIP"; they red key in the system tray should turn green to indicate that the HIP service has started.

Hip can also be run from the console with:

cd \Program Files\OpenHIP
.\hip.exe -v

On Windows 7 and Windows Vista you need to run as administrator:

  • Start > Programs > OpenHIP, right click on "HIP monitor" and choose "properties". Under the "Shortcut" tab, click "Advanced", and check the "Run as administrator" box.
  • Perform the same procedure for the "HIP (console mode)" shortcut, to run it as administrator.
  • When running HIP from a Command Prompt, you need to start the Command Prompt as administrator.

If you just performed a new install of HIP on Windows 7 or Vista, you may experience problems prior to rebooting. You can use the ipconfig /all and route print commands when HIP is running to diagnose TAP-Win32 adapter problems. The 1.x.x.x LSI address should appear under the TAP interface (may be titled "Local Area Connection 2") and a route to the 1.x.x.x/16 network should be included in the routing table.


  • run HIP as root with this command:
/usr/local/sbin/hip -v

You should see a lot of debugging output, such as:

softball:/home/tomh/cvs/hipd/win32 # ./hip -v
Using TAP device hip0.
Initialized TAP device.
hip_pfkey() thread started...
hip_status() thread started...
Thu Jan 19 15:46:04 2006  hipd (18838) started.
Setting options: daemon = no  debug level = 1  permissive = no
                 no_retransmit = no  opportunistic no
Using default (hip.h) hip.conf file location.
Loading Host Identity...(RSA 1024-bit) softball-1024
Loading Host Identity Tag...(RSA 1024-bit) tunreader() thread started (3)...
hip_esp_output() thread started...
hip_esp_input() thread started...
hip_dns() thread started...

You can run the user-mode version in the background and log its output with this command:

/usr/local/sbin/hip -v < /dev/null >& /var/log/hip.log &

If running on a patched kernel in Linux, you can start HIP as a daemon with output logged to /var/log/hipd.log like this:

/usr/local/sbin/hipd -v -d

Testing your configuration

Previously, we talked about remembering the LSI for Try doing the following:


You should see the debugging output of the daemon indicate that an SA was established, and tcpdump or wireshark captures should show ESP over UDP traffic to that server.

Alternatively you can turn on DNS support in the hip.conf file by setting <disable_dns_thread>no</disable_dns_thread>, and then try using the DNS name:


The .hip suffix tells the hip daemon to use HIP for this domain name. If you do not use the .hip suffix, HIP is bypassed.

Firewall issues

If your operating system has a firewall enabled, you should configure it to allow UDP port 50500 packets. The built-in Windows Firewall on Windows systems cannot be configured to allow arbitrary protocols, so you need to use HIP over UDP (the default setting) or disable the firewall.