HIPL User Manual

In addition to the HIPL userspace software, you need a Linux system with BEET IPsec support. You can install BEET IPsec by following one of the following methods:

The HIPL library and header dependencies are not listed here. Read the INSTALL file to see what software you need to install before compilation of HIPL.

Network Requirements

You should allow also HIP related traffic in your firewall. For example:

The last two rules basically allow the whole orchid namespace. You can set up more specific rules for HITs or use the hipfw to filter traffic (as explained in a later section).

SELinux should be disabled with HIPL in /etc/selinux/config (you have to reboot the machine after this). We don't yet have instructions for configuring SELinux. Contributions are welcome. Please note that default installations of AppArmor in Ubuntu work well with HIPL.

The XML documentation is built automatically if xmlto is installed.

After you have successfully compiled and installed the HIP kernel and rebooted both of the hosts, you need to compile the userspace applications in order to use HIP. Start by moving to the top level directory of HIPL:

Next, install HIPL as follows:

make install

Note: the HIP configuration files are located in /etc/hip with the current set of options for configure. In contrast, the prebuilt RPM/DEB binaries store the HIP configuration files in the /etc/hip directory.

Note: you can optionally compile a binary (RPM or DEB) package with "make bin".

Some features are not compiled by default. Run "./configure --enable-FEATURE" to compile those. See "./configure --help" for a full list of options.

It is possible to include measurement code points in the HIPL code with the --enable-performance configuration option. If you want to profile HIPL source code, please refer to http://www.cs.helsinki.fi/u/sklvarjo/gprof.html.

HIPL compiles fine on OpenWrt trunk and Backfire branch versions from the end of 2010 onwards.

To get an OpenWrt tree suitable for compiling HIPL, perform the following steps:

Make sure you have the requirements to compile OpenWrt installed on your system. Details can be found in the OpenWrt documentation.

To modify your OpenWrt tree to contain HIPL you need to

The OpenWrt build process takes a long time. If you just want to test HIPL compilation within OpenWrt quickly without triggering a complete build, run

$ make package/hipl/install
      

If you experience problems during compilation, add V=99 to the make command in order to get more detailed output.

HIPL currently has partial experimental support for the Android platform. The parts that currently work are hipd, the HIP daemon; and hipconf, the configuration tool. hipd does require root privileges, and your running kernel must support the IPSec BEET mode, the dummy network driver and the null crypto algorithm. Often one or more of these are not compiled into your stock kernel, and it is likely that you need to compile and install your own kernel. On our development devices we went ahead and compiled the whole OS; this procedure is documented in doc/hipl_android_preparation_guide.txt

Currently we only support compiling under Linux. We provide a script in tools/prepare_android_toolchain.sh that downloads and extracts the toolchain needed to compile hipd and hipconf and it has been confirmed to work at least on Ubuntu 12.04.

After HIPL source code is downloaded and the toolchain is installed, the steps to compile for Android are almost similar to normal Linux builds. You start with autoreconf --install; then you run the configure script:

CC=(path to android toolchain)/bin/arm-linux-androideabi-gcc
./configure --enable-android --host=arm-linux                      \
            --prefix=/usr    --sysconfdir=/etc
      

and run 'make'. If you are building for an Android version older than 4.1, add '--disable-android-pie' to the configure line.

After the build process completes, open a root privileged shell session on your phone and set up the environment:

adb root
adb shell
mount -o remount,rw /
mount -o remount,rw /system
mkdir -p /var/lock
mkdir    /etc/hip
ln -s /system/lib/libcrypto.so /system/lib/libcrypto.so.1.0.0
      

Afterwards, you can return to your normal terminal and push hipd, hipconf and the configuration in:

adb push hipd/hipd        /system/xbin
adb push hipfw/hipfw      /system/xbin
adb push tools/hipconf    /system/xbin
adb push hipd/hipd.conf   /etc/hip
adb push hipd/relay.conf  /etc/hip
adb push hipfw/hipfw.conf /etc/hip

for file in ${ANDROID_SYSROOT}/usr/lib/lib{netfilter_queue,nfnetlink,mnl}.*; do
  adb push $file /system/lib ;
done
      

On Android, hipd needs to be run with the '-a' parameter. Additionally it supports the same parameters as the normal Linux version does, i.e. '-k' kills an already running instance and '-b' starts hipd in the background. By e.g. running 'hipd -ab' and configuring hosts in /etc/hosts you should be able to use HIP on any program that supports IPv6. If you compiled all the required features into the kernel, instead of as modules, then the '-m' flag makes hipd ignore the fact that loading those modules fails. hipfw supports the same flags as on Linux.

As the root file system on Android typically resides on a ramdisk, the /var/lock folder is removed every time the phone is restarted. For hipd to run, it needs to be recreated by running:

adb root
adb shell mount -o remount,rw /
abd shell mkdir -p /var/lock
      

/system and /etc typically reside in persistent storage, so anything that is stored there should survive rebooting.

The other sections of this document describe technical installation and usage of HIPL software in an elaborate way. This section gives more brief instructions for the brave and impatient.

The quickest way to install HIPL on your Linux system is to use precompiled release packages. Binary packages exist for a number of Debian and Red Hat based Linux distributions. Install the binary packages according to instructions on the download page: http://infrahip.hiit.fi/index.php?index=download

After installing all of the the binaries, you can test the installation by opening your web browser. Type http://crossroads.infrahip.net/ in the address bar, hit enter and wait a few seconds. If the web page tells you that the connection was established using HIP, then you have a successful installation, congratulations!

In November 2009 Linux Journal published on November 2009 an article on basic HIPL installation and usage: http://www.linuxjournal.com/issue/187

There are more test servers listed in the next section. If you have problems, continue reading. You can also ask questions on the hipl-users mailing list. Please include the output of the following commands when reporting bugs:

Below is a list of public InfraHIP test servers. Crossroads and ashenvale are also running HIP rendezvous service which you can use according to the instructions in Chapter 6, Using HIP Rendezvous and HIP Relay Server/Mechanisms.

The servers are running public HTTP service and respond to ICMPv4 and ICMPv6.

To access the servers over HIP behind a NAT box, you have two alternatives. First, you enable the UDP encapsulation using hipconf daemon nat plain-udp. See Chapter 8, HIP NAT Traversal for more information. Second, you can install miredo on your machine and make sure that HIP uses the IPv6 address of the server.

To register with rendezvous servers behind a NAT box, you need to install "miredo" on your machine. Then you register with one of the test servers using its IPv6 address.

You can use the hipconf tool to reset HIP SAs manually. Type hipconf daemon rst all to close all SAs.

This section is oriented towards hackers and developers. We will show how to connect two hosts using HIP to test your HIPL installation. The section starts with IPv6 test applications, continues with IPv4-IPv6 interoperability and concludes with IPv4 test applications.

We assume two machines called crash and oops that are in the same network. Crash is the one that starts communicating with oops. Substitute names and addresses according to your network configuration. It is possible to use IPv4 as well as IPv6 addresses on the wire.

This section is targeted to developers and hackers. If you don't intend to hack some code, move on to the next section.

The handover code is based on RFC5206. Not all of the features are implemented yet and the code quality is still far from bullet proof.

A naive handover test example is below. It assumes that you have already established the base exchange between the hosts. You also need to have the nc6 tool which can be found from e.g. "www.freshmeat.net". The example is based on IPv6 addresses but you can also use IPv4.

You can also trigger the handover message exchange without changing IP addresses by running "hipconf daemon manual-update". Note that this only simulates the message exchange that would normally occur on IP address changes and does not test handover detection.

Do not use link local addresses for the mobility scenarios for the hosts, unless you know what you are doing! For example, you are asking for trouble if you establish HIP SA between the mobile and correspondent node using link local addresses, and move the mobile node to a different network. The readdressing fails, because either node has no way of reaching the other node.

Make sure to add the route for the new address as soon as the new address is added. If the route is missing, the update packets might not get sent at all. The daemon waits for a couple of seconds if a transmit of an update fails for retransmitting it.

The network throughput using IPsec might be unnecessarily slow especially in wired, local-area networking (e.g. within a datacenter). You can tune this higher by enabling jumbograms in your switch and by increase the MTU of the virtual host interface (ip link dev dummy0 set mtu 8950).

1. Run the hipdnsproxy to map hostnames transparently to HITs from hosts files and directory services (DNS). See the section called “DNS Proxy” for more details.

2. Overload your /etc/hosts files by adding HITs or LSIs before the corresponding IP addresses. This method does not require DNS proxy running on the host and works using hostnames.

3. You can also use HITs (or LSIs) directly in the application (DNS proxy is not required for this method). For example, you can execute "ping6 PEER_HIT". However, hipd must know the mapping from the PEER_HIT to the corresponding IP address. Hipd can find this mapping from DNS. Alternatively, this information can be stored in hosts files as follows:

3a. If you want to maintain separate files for HIP identifiers, write the HIT-hostname (or LSI-hostname) pair to /etc/hip/hosts and the IP-hostname pair to /etc/hosts. See also the method (2) for overloading all addresses in /etc/hosts.

3b. Execute "hipconf daemon add map PEER_HIT PEER_IP" and use the HIT directly in the application. You can insert the hipconf command without daemon keyword also to /etc/hip/hipd.conf and restart hipd.

The Linux libc library does not (yet) support look up of HI records from the DNS. As a workaround for this problem, HIPL provides a DNS proxy that intercepts DNS requests and handles the HI record look up. The proxy intercepts the DNS requests by overwriting itself into /etc/resolv.conf file. Then, the DNS proxy forwards all of the DNS requests to the server that was in the file prior to overwriting it. When the proxy encounters HIP records in DNS or hosts files, it returns them instead of the IP addresses to the caller.

The DNS proxy is single threaded, but asynchronous. It polls for changes in resolv.conf, stores the changes and rewrites itself there. The DNS proxy caches the results of DNS requests to reduce delays. To avoid loosing the mapping between a HIT and the corresponding IP address, the DNS proxy always this information to hipd (using hipconf). It sends this information always because there is chance that hipd was restarted or its state was reset.

The DNS proxy is useful especially for client hosts. However, running the DNS proxy on e.g. a SSH server or IRC server has the benefit that it speeds up logins. The server software will try to resolve the HIT of the client to a hostname and introduces an artificial delay to the client if the HIT was not found. Running DNS proxy at the server avoids this delay.

The DNS proxy tries to find host identities from two places, the "hosts" files or HI records in DNS. The /etc/hip/hosts file can be used to isolate all HITs or LSIs, or they can be overloaded all in the /etc/hosts file. If you prefer isolation to /etc/hip/hosts, you may have to change the "hosts" line in /etc/nsswitch.conf so that "dns" occurs before "hosts". In the case of DNS, the DNS proxy converts the HI records automatically to HITs and returns also LSIs to the application when requested. The DNS proxy handles the LSI conversion through hipd.

The DNS proxy can be run with or without resolvconf (in Ubuntu/Debian).

The DNS proxy does not yet autodetect other DNS related software running on the same host. If DNS proxy reports the error "Port 53 already in use. See HOWTO.", you can find out using netstat which process is occupying it. Dnsmasq is the most common problem, as it is started automatically by modern NetworkManager. It can be disabled by removing or commenting out the line "dns=dnsmasq" in /etc/NetworkManager/NetworkManager.conf and restarting NetworkManager. Another case is ISC bind. You should associate bind explicitly with the IP addresses (or HITs) you want to use. The DNS proxy occupies IP address 127.0.0.53 and as long as bind uses different IP address than DNS proxy, both can co-exist on the same host.

If you encounter a bug with DNS proxy and loose your DNS settings, just try to reconnect your machine to the network. If this does not help, try rebooting your host; in case you're running dnsmasq, dnsproxy repairs then /etc/default/dnsmasq file if DNS proxy crashed for some reason.

The DNS proxy has multiple options that you configure e.g. to DNSPROXY_OPTS variable in /etc/init.d/hipdnsproxy file. Remember to run "/etc/init.d/hipdnsproxy restart" to make the changes effective. For example, including --hip-domain-prefix="hip." can speed up the DNS resolution because it tries to resolve HITs only when the host name begins with the "hip." string. Also, the DNS proxy returns HITs or empty DNS responses to the application as an extra security measure when the prefix matches.

The DNS proxy does not return IP addresses when it finds a HIT for a queried host. If you want to see the IP addresses, try "dig -t any hostname". Intentionally, the DNS proxy does not alter ANY requests for diagnostics and debugging purposes.

The tools/hipdnskeyparse directory contains a script which converts public key file contents to different DNS zone file formats. To convert to unpatched BIND9 format, run the following:

hipdnskeyparse < /etc/hip/hip_host_rsa_key_pub.pub hostname.domain.org | sed -n -e '/^9BIND */s///p'
      

This outputs a line which can be inserted to a zone file. Similarly, with sed command:

.... | sed -n -e '/^DJBDNS */s///p'
      

a line for Dan Bernstein's tinydns is output. For further information, please refer to hipdnskeyparse and myasn.py.

The goal of Dynamic DNS extensions is that a local host can establish initial contact with a peer host when the local host knows only the HIT of the peer but not the IP address or domain name. The extensions do not provide hostname-to-HIT look up support (see section the section called “DNS Proxy”), just HIT-to-IP look up.

Currently HIP daemon performs HIP name resolution in the following order:

With "hipconf daemon hit-to-ip on", the HIP daemon uses IP addresses of 5.7.d.1.c.c.8.d.0.6.3.b.a.4.6.2.5.0.5.2.e.4.7.5.e.1.0.0.1.0.0.2.hit-to-ip.infrahip.net. to contact peer host with HIT 2001:1e:574e:2505:264a:b360:d8cc:1d75

Default hit-to-ip.infrahip.net. suffix can be changed with "hipconf daemon hit-to-ip-set <new.hit-to-ip.zone.>. Please note it is independent from HIT_TO_IP_ZONE in /etc/hip/nsupdate.conf"

With "hipconf daemon nsupdate on", the HIP daemon also maintains records in hit-to-ip.infrahip.net. Once you start hipd, it will call nsupdate with HIT and IP address for every HIT of your host. It is executed upon mobility events (i.e. address changes) later on. There is an example of update query:

update delete 5.7.d.1.c.c.8.d.0.6.3.b.a.4.6.2.5.0.5.2.e.4.7.5.e.1.0.0.1.0.0.2.hit-to-ip.infrahip.net
update add 5.7.d.1.c.c.8.d.0.6.3.b.a.4.6.2.5.0.5.2.e.4.7.5.e.1.0.0.1.0.0.2.hit-to-ip.infrahip.net 1 IN A 193.167.187.1
update add 5.7.d.1.c.c.8.d.0.6.3.b.a.4.6.2.5.0.5.2.e.4.7.5.e.1.0.0.1.0.0.2.hit-to-ip.infrahip.net 1 IN AAAA 2001:708:140:220:215:60ff:fe9f:60c4
   

hit-to-ip.infrahip.net used for experiments has HIT in SOA record, therefore updates are sent to HIT and cause HIP base exchange with the master DNS server. Your system should resolve its location by HIT. After the base exchange update is submitted via HIP, which allows DNS server to authenticate the clients and permit updates only of their own location. Changes made to ISC BIND can be found in patches/bind directory.

We also try to assign domain name pointers for HITs. On daemon start nsupdate will query 5.7.d.1.c.c.8.d.0.6.3.b.a.4.6.2.5.0.5.2.e.4.7.5.e.1.0.0.1.0.0.2.ip6.arpa and send update if needed. Unfortunately we modify information in 1.0.0.1.0.0.2.ip6.arpa only on our DNS server as we do not have global delegation yet.

The rendezvous and relay extensions extend HIP and the HIP registration extension for initiating communication between HIP nodes via a HIP rendezvous server or a HIP relay server. The rendezvous server (RVS) and the HIP relay server serve as an initial contact point ("rendezvous point") for its clients. The clients of an RVS / HIP relay server are HIP nodes that use the HIP Registration Protocol to register their HIT to IP address mappings with the server. After this registration, other HIP nodes can initiate a base exchange using the IP address of the server instead of the current IP address of the node they attempt to contact. Essentially, the clients of a server become reachable at the server's IP addresses.

The primary objective of the rendezvous extension is to improve reachability and operation when HIP hosts are mobile or multi-homed. In addition, the rendezvous extension is necessary when a middlebox separates the responder from the public realm. In a Network Address Translator (NAT), session establishment is uni-directional from private address realm to public address realm. Therefore, if a host has detected that it is behind a NAT, the host must first register with the RVS when it is going to act as a responder of a base exchange. The rendezvous extension allows HIP initiators to reach the responder when the NAT devices involved all perform address independent mapping. Such NATs are commonly referred to as "good" NATs.

HIPL has two experimental relay modes serving NAT traversal purposes. In the first mode, the HIP control plane relay supports Native NAT Traversal Mode for HIP which is only partially supported at the moment. The core idea is that two end-points are behind two different NAT boxes and use a HIP control plane relay to be able to contact each other to exchange their locators. Then the hosts "punch holes" to their NAT boxes to establish direct end-to-end connectivity with each other. The second mode, "full-relay" is supported completely and it relays both HIP and ESP traffic. You should use it carefully and whitelist your /etc/hip/relay.conf file. Otherwise you risk your host becoming an open HIP and ESP relay. For additional security measure, you can also use also /etc/hip/hipfw.conf to further restrict the allowed clients and servers by their HITs.

The main difference between the rendezvous server and the HIP relay server is that the RVS only relays I1 packet of the base exchange while the HIP relay server relays all HIP packets. We can summarize the use cases of the RVS and the HIP relay as follows.

The rendezvous server should be used when:

The HIP relay server should be used when:

HIPL supports also initiating connections from behind a NAT. The basic idea is that the initiator encapsulates HIP control packets and ESP data packets within UDP. This way, the packets can traverse the NAT box. However, both the initiator and responder have to support NAT extensions in order to make this work. Currently, the responder cannot be located behind a NAT.

The NAT traversal can be experimented in a similar way as depicted in earlier sections. The only difference is that you have to tell the initiator manually that it is behind a NAT using "hipconf daemon nat on". After this, you can initiate the base exchange according to the previous instructions. The manual configuration is currently required because support for automatic NAT detection (STUN) has not been implemented yet.

If you have problems in even getting I1 triggered using NAT code e.g. with nc6 (occurred on 2.6.16.5 kernel version), you may have to specify the source HIT explicitly. The procedure to initiate a connection behind NAT is as follows:

Three cases of mobility of the initiator have been implemented for the NAT code.

Mobility from behind NAT to behind the same NAT: For this case, the use the standard procedure for update after the base exchange is completed. The update would be UDP encapsulated.

Mobility from public addressable network to behind NAT: Once a hip association is set up between two hosts, both on the public network and one of them wishes to move behind a NAT, then that node should first delete the public ip address, then turn the NAT on using hipconf and then add the ip address behind NAT along with the route to the interface. The update would be done using UDP now and future communications would be UDP encapsulated (both HIP control traffic and ESP packets).

Mobility from behind NAT to publicly addressable network: If a node has setup hip association from behind NAT and now wishes to move to public IP domain, then it should first delete the ip behind NAT, turn off the NAT using hipconf and then add the public IP along with the route to the interface. HIP association then would not use UDP encapsulation and the update would be done using normal HIP packets (without UDP encapsulation).

Teredo is a traversal solution for HIP. You can experiment with Teredo by installing the Miredo client software. Then, establish HIP connections to Teredo addresses (check ifconfig teredo) at the client side as instructed in the section called “For Hackers: How to Test HIP Connectivity from the Command Line using two Locally-Connected Hosts”. As Teredo is a NAT traversal solution by itself, you don't have use UDP encapsulation for HIP (hipconf daemon nat none).

See http://www.cs.helsinki.fi/u/sklvarjo/miredo.htm for further information on Teredo configuration with HIP. Table 3.1, “Test Servers” lists addresses of the public InfraHIP test servers with Teredo addresses. The servers provide also free rendezvous service that can be combined with Teredo.

At the protocol level, HIPL implements the HIP_CERT parameter as defined in RFC 6253. Specifically, X509 certificates are supported, whereas no functionality is provided for SPKI certificates. HIP does not define the usage of certificates in the protocol exchange. In HIPL, we currently add certificates to the R2 in the BEX and the second update message U2 (e.g. during the mobility-triggered update exchange). The HIP firewall verifies the certificate in the R2 and U2 if configured accordingly. If your use case requires certificates to be included in different messages, changes in the source code will be necessary.

For the following guide, we assume a setup consisting of three machines (A, B, and C), where B is situated on the forwarding path between A and C. A and C execute the hipd, while B executes the hipfw. The hipd automatically adds a certificate to R2s and U2s if a file called host-cert.der is located in /etc/hip. The hipfw checks for certificates if certificate-based rules exist in /etc/hip/hipfw.conf.

To set up certificates, you have to perform the following steps:

The setup of a certificate-based network scenario can be vastly simplified by using a fourth HIPL-enabled host D as the certificate authority. In this case, generate the root certificate on D by running:

    openssl req -new -x509 -key /etc/hip/hip_host_rsa_key_pub -out ca-root-cert.pem
    

NOTE: Apart from the common name, all fields in the certificate can be empty. The common name must contain the HIT of D.

Now, run a BEX between C and D. After the BEX has succeeded, run the following command on D as root in order to generate the certificate for C:

    hipconf acquire certificate #HIT_OF_C# > host-cert.der
    

As the final step, copy the certificates to the places mentioned in the guide above.

There are a couple of things that may go wrong in a certificate-based setup. The most common ones are listed below. Please, make sure to check the listed items before asking questions on the hipl-users mailing list.

HIP dual-version support allows a host to run HIPv1 and HIPv2 as a dual stack. Based on the version number of received I1 messages, the host automatically determines the HIP version for this peer. The version is decided separately for each host association, which means the host can have a HIPv1 association with one peer, while maintaining a HIPv2 association with another peer.

HIP dual-version support also enables a host to choose the default HIP version for HIP association initiation. This behavior can be configured via both the hipd configuration file and the hipconf command line tool.

The configuration parameter: hip-default-version in the hipd.conf file accepts two values: 1 and 2, which stand for HIPv1 and HIPv2 respectively. If the hipd cannot find this parameter in the configuration file, HIPv1 will be used as default value.

Modification of the configuration parameter: hip-default-version in the hipconf command line takes effect immediately and no restart of the daemon is required. Any HA before the modification remains unchanged and all new HIP initiation messages (I1 message) will be switched to the version given by the hipconf command. Below is an example of setting the parameter to HIPv1. To use HIPv2, change the value from 1 to 2.

    hipconf daemon default-hip-version 1
    

At the protocol level, the extension allows sending multiple I1 or UPDATE-with-locator packets sequentially. The idea is to scan through all possible source and destination IP pairs at the HIP layer to improve the chances for successful initial contact (I1) and to reestablish contact (UPDATE-with-locator) in way similar to the NAT-ICE extensions. We have playfully called the extension as "shotgun" mode in the implementation.

The obvious difference to ICE is that the shotgun mode works at the HIP protocol layer. A non-obvious difference is that the approach supports also fault-tolerance for a single relay/rendezvous (Responder's RVS has crashed) and it can make use of multiple relay/rendezvous servers for better redundancy. At the moment, neither of these are possible directly with the ICE-NAT extensions. I actually believe the shotgun approach can be applied even with the ICE-NAT extensions to improve fault-tolerance.

The shotgun approach seems useful to improve fault-tolerance with an without (single or multiple) rendezvous/relay middleboxes, but there is also another use case for this. The Initiator (or Mobile Node) can learn multiple mappings for the peer, some of which may have connectivity and some not. It is also possible that a malign user intentionally sends invalid mappings for a well-known service in a multiuser system (this case also requires some rate control for mappings per user). In such scenarios, it is useful to try multiple peer addresses sequentially instead of just single one.

The shotgun extension can be enabled as follows:

hipconf daemon shotgun on

The same line can be also included in /etc/hip/hipd.conf without the "hipconf daemon" prefix.

At the time of writing this, the shotgun extension did not yet work with UPDATE.

Libhipl provides HIP functionality as a library for upper layer applications without requiring the HIPL daemon. Instead, HIP control messages are transmitted on top of TCP/UDP. From the applications' point of view, there is an API similar to the normal socket API. This section describes the libhipl API.

The libhipl API is described in "lhipl.h". Detailed information about each function is available there.

Libhipl initialization.  Libhipl requires initialization before calling any other related functions. The function: hipl_lib_init_all() serves this purpose and different debug levels can be set as its parameters to track problems inside the library.

Name-based API.  Compared to standard socket API, one apparent difference in Libhipl is that a peer is specified by giving a peer name and a port number instead of a sockaddr data structure. The peer name is a string representation of the peer. Currently, libhipl only supports a HIT string as peer name.

Libhipl socket creation.  The function hipl_socket() creates a new libhipl socket. An ID is assigned to each created libhipl socket and returned by this function, then the caller can pass this ID to other libhipl functions to operate on this libhipl socket. NOTE: there is NO relation between libhipl socket IDs and normal socket file descriptors, and the result of using this ID as file descriptor is undefined.

Setup TCP connection.  When using libhipl in TCP mode, TCP connection setup is the first task. Similar to the normal socket syntax, libhipl provides: hipl_connect(), hipl_listen() and hipl_accept() for this goal. Those functions process the 3-way handshake and establish a TCP connection.

libhipl Base Exchange (BEX) and user data transmission.  Data transmission is handled by hipl_sendto() and hipl_recvfrom(). In libhipl, The first sending data call triggers BEX and the first receiving call waits for an incoming BEX message. Once BEX succeeds, the pending user data is transmitted to the peer side. This BEX process is handled by libhipl automatically by default. Meanwhile, there is also an advanced way to handle BEX step by step, which will be explained bellow.

libhipl assistant API. 

Libhipl sample program.  For a libhipl usage example, refer to the check_libhipl program in the test directory.