# libhicn

## Introduction

libhicn provides a support library coded in C designed to help developers embed
Hybrid ICN (hICN) functionalities in their applications (eg. forwarder, socket
API, etc.). Its purpose is to follow the hICN specification for which it
provides a reference implementation, abstracting the user from all internal
mechanisms, and offering an API independent of the packet format (eg. IPv4 or
IPv6). The library is designed to be portable across both desktop and
mobile platforms, and we currently aim at supporting Linux, Android, OSX and
iOS, by writing the necessary adapters to realize hICN functionality in
userspace according to the available APIs and permissions that each system
offers.

The library consists in several layers:
- the core library (hicn.h) provides a standard hICN packet format, as well as
an API allowing manipulation of packet headers;
- an hICN helper, allowing an hICN stack to be built in userspace in a portable
way, based on TUN devices and accessible though file descriptors;
- a network layer allow the sending an receiving of hICN packets on those file
descriptors, implementing both source and destination address translation as
required by the hICN mechanisms;
- finally, a "transport" API allows the forging of dummy interest and data
packets.

A commandline interface (hicnc) is also provided that uses the library and can
for instance be used as a test traffic generator. This interface can be run as
either a consumer, a producer, or a simple forwarder.

## Folder content

CMakeLists.txt          CMkake global build file
doc                     Package documentation
README.md               This file
src
    base.h		Base definitions for hICN implementation
    CMakeLists.txt      CMake library build file
    common.{h,c}	Harmonization layer across supported platforms
    compat.{h,c}	Compatibility layer for former API
    error.{h,c}		Error management files
    header.h		hICN header definitions
    hicn.h		Master include file
    mapme.{h,c}		MAP-Me : anchorless producer mobility mechanisms 
    name.{h,c}		hICN naming conventions and name processing + IP helpers
    ops.{h,c}		Protocol-independent hICN operations
    protocol/*		Protocol headers + protocol-dependent implementations
    protocol.h		Common file for protocols

## Using libhicn

### Platforms ###

libhicn has been tested in:

- Ubuntu 16.04 LTS (x86_64)
- Ubuntu 18.04 LTS (x86_64)
- Debian Stable/Testing
- Red Hat Enterprise Linux 7
- CentOS 7
- Android 8
- iOS 12
- macOS 10.12
- Windows 10

Other platforms and architectures may work.

### Dependencies

Build dependencies:

- c11 ( clang / gcc )
- CMake 3.4

Basic dependencies: None

## Installation

You can either use released packages, or compile libhicn from sources.

### Release mode

mkdir build
cd build
cmake ..
make
sudo make install

### Debug mode

mkdir debug
cd debug
cmake .. -DCMAKE_BUILD_TYPE=Debug
make
sudo make install

## License

This software is distributed under the following license:

```
Copyright (c) 2017-2019 Cisco and/or its affiliates.
Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at:

    http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
```