mpiatka/libjuice

JUICE is a UDP Interactive Connectivity Establishment library

libjuice - UDP Interactive Connectivity Establishment

libjuice 🍋💦 (JUICE is a UDP Interactive Connectivity Establishment library) allows to open bidirectionnal User Datagram Protocol (UDP) streams with Network Address Translator (NAT) traversal.

The library is a simplified implementation of the Interactive Connectivity Establishment (ICE) protocol written in pure C without dependencies for POSIX platforms (including Linux and Apple macOS) and Microsoft Windows. It supports only a single component over UDP per session in a standard single-gateway network topology, as this should be sufficient for the majority of use cases nowadays.

Licensed under LGPLv2, see LICENSE.

Compatibility

The library implements a simplified but fully compatible ICE agent (RFC8445, RFC8489 for STUN, and RFC8656 for TURN) with an interface based on SDP (RFC4566). It supports both IPv4 and IPv6.

The limitations compared to a fully-featured ICE agent are:

• Only UDP is supported as transport protocol. Other protocols are ignored.
• Only one component is supported. This is sufficient for WebRTC Data Channels or multiplexed RTP/RTCP (RFC5731).
• Candidates are gathered without binding to specific network interfaces. This should behave identically to the full implementation on most client systems and allows to greatly reduce complexity.

It also implements a lightweight STUN/TURN server (RFC8489 and RFC8656). The server can be disabled at compile-time with the NO_SERVER flag.

For a STUN/TURN server application based on libjuice, see Violet.

Dependencies

None!

Optionally, Nettle can provide SHA1 and SHA256 algorithms instead of the internal implementation.

Building

Clone repository

$ git clone https://github.com/paullouisageneau/libjuice.git
$ cd libjuice

Build with CMake

The CMake library targets libjuice and libjuice-static respectively correspond to the shared and static libraries. The default target will build the library and tests.

POSIX-compliant operating systems (including Linux and Apple macOS)

$ cmake -B build
$ cd build
$ make -j2

The option USE_NETTLE allows to use the Nettle library instead of the internal implementation for HMAC-SHA1:

$ cmake -B build -DUSE_NETTLE=1
$ cd build
$ make -j2

Microsoft Windows with MinGW cross-compilation

$ cmake -B build -DCMAKE_TOOLCHAIN_FILE=/usr/share/mingw/toolchain-x86_64-w64-mingw32.cmake # replace with your toolchain file
$ cd build
$ make -j2

Microsoft Windows with Microsoft Visual C++

$ cmake -B build -G "NMake Makefiles"
$ cd build
$ nmake

Build directly with Make (Linux only)

$ make

The option USE_NETTLE allows to use the Nettle library instead of the internal implementation for HMAC-SHA1:

$ make USE_NETTLE=1

Example

See test/connectivity.c for a complete local connection example.

See test/server.c for a server example.