Configuration

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
./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>_host_identities.pub.xml 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.

my_host_identities.xml

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:
skadjf;lsj;ldafsadfawerwaerwq123safd
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"?>
<my_host_identities>
  <host_identity alg="RSA" alg_id="5" length="128" anon="no" incoming="yes" r1co
unt="10">
    <name>softball-1024</name>
    <N>A5D840794D4FF9D95A8FDBE7049625D625DB69032ECBD67F6E91F5FE59D0C02DB646EE49A
24231F7F11823F3372C9753CD86FD3258FFB3DAC35A5099F24B1E83AA3972861382697EAE7153B2C
5A0CBB0ABD622E69C9BA32774F0792D39F48384BBA4BD1B8B13D5558EA9C2D5670B28951CEDBA813
2E496107FB70DB6FF0D9B2D</N>
    <E>010001</E>
    <D>18EBBE047C51A041C1120D0151F71E0867F7E877C9F8676B0EBA7034A05A7606687590291
070D201680130A5C38CB7D0A7F9B8E26FED3CA18AE96F6332BD87001401E9F79A501983D3F07DD81
8F81D3B837C1F76493EFB7A6745AAF76C79BAB3CEC21281667E9C13A54BF453AC57041826E66A1A2
98103ED2EFA2136E123F821</D>
    <P>D6B44357A29AC5C9EB5B265AAB824B1F98586CD88347A0D3EB2C928A13288ED8E95AC728A
9D4B88AC88E362CE01F4A060FAE5385446D75C63825F14E758D1A5B</P>
    <Q>C5BE37E0582A4BA2F18EBF8682181A27D447C5CC282A160BED95ACE65663C9E52E4345EC6
83684EC030CF33159199C086C52B7733516E83000410A7F5A034717</Q>
    <dmp1>832D65CBA03C61C5C9774A4AB1690CCF03FC5A9C3A314430D609C88A75C41CEAA8405F
5817D330E11241D915B7E5460BC7FEE16695F52EB4E9CF3CCC8C03A6EB</dmp1>
    <dmq1>138BBFDE2F18CF2D260F6423198CE458F784B8AA7B75DD840451FD2B2F72E1AC03ACA6
A6BD8E5609362BFB85EF36B6D3A6516ECCB67CB32ABB7BB25BF03BCEB5</dmq1>
    <iqmp>9D70C70BC742DDE0845364F6940E5799706FEC2C691AF1C91532A78BC4ECB26218F68D
82A5AC26CDA45BD49A1CFD4F45F4A09020423E930E5EF430199BE6E53E</iqmp>
    <HIT>2001:13:17d5:e802:1e60:6cfb:5b09:d7f0</HIT>
    <LSI>1.9.215.240</LSI>
  </host_identity>
</my_host_identities>

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.

hip.conf

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_configuration>
  <min_lifetime>96</min_lifetime>
  <max_lifetime>255</max_lifetime>
  <reg_type_rvs>1</reg_type_rvs>
  <lifetime>217</lifetime>
  <reg_type>1</reg_type>
  <cookie_difficulty>10</cookie_difficulty>
  <packet_timeout>10</packet_timeout>
  <max_retries>5</max_retries>
  <sa_lifetime>900</sa_lifetime>
  <send_hi_name>yes</send_hi_name>
  <dh_group>3</dh_group>
  <dh_lifetime>900</dh_lifetime>
  <r1_lifetime>300</r1_lifetime>
  <failure_timeout>50</failure_timeout>
  <msl>5</msl>
  <ual>600</ual>
  <hip_sa>
    <transforms>
      <id>1</id>
      <id>2</id>
      <id>3</id>
      <id>4</id>
      <id>5</id>
      <id>6</id>
    </transforms>
  </hip_sa>
  <esp_sa>
    <transforms>
      <id>1</id>
      <id>2</id>
      <id>3</id>
      <id>4</id>
      <id>5</id>
      <id>6</id>
    </transforms>
  </esp_sa>
  <disable_dns_lookups>no</disable_dns_lookups>
  <disable_notify>no</disable_notify>
  <disable_dns_thread>no</disable_dns_thread>
  <enable_broadcast>no</enable_broadcast>
  <lsi_prefix>1.0.0.0</lsi_prefix>
</hip_configuration>

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 1.0.0.0/8; 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.

known_host_identities.xml

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"?>
<known_host_identities>
  <host_identity alg="RSA" alg_id="5" length="128" anon="no" incoming="yes">
    <name>hipserver.mct.phantomworks.org-1024</name>
    <HIT>2001:14:4dcd:2a09:74a:caee:2a0:ec4a</HIT>
    <LSI>1.230.120.200</LSI>
  </host_identity>
</known_host_identities>

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 1.0.0.1), 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 hipserver.mct.phantomworks.org.hip".

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>_host_identities.pub.xml" 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 130.76.43.74, so you can add:

<addr>130.76.43.74</addr>

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 1.2.3.4" will set up a HIP connection to the host corresponding to LSI 1.2.3.4. 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.

Windows

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.

Linux

  • 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
init_hip()
init_tap()
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) 1.195.131.234 softball-1024
Loading Host Identity Tag...(RSA 1024-bit) 1.230.120.200 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 hipserver.mct.phantomworks.org. Try doing the following:

ping 1.230.120.200

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:

ping hipserver.mct.phantomworks.org.hip

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.