PJNATH - Open Source ICE, STUN, and TURN Library

This is the documentation of PJNATH, an Open Source library providing NAT traversal helper functionalities by using standard based protocols such as STUN, TURN, and ICE.

Library Components

STUN

Session Traversal Utilities (STUN, or previously known as Simple Traversal of User Datagram Protocol (UDP) Through Network Address Translators (NAT)s), is a lightweight protocol that serves as a tool for application protocols in dealing with NAT traversal. It allows a client to determine the IP address and port allocated to them by a NAT and to keep NAT bindings open.

This version of PJNATH implements the following STUN-bis draft:

• draft-ietf-behave-rfc3489bis-15: Session Traversal Utilities for (NAT) (STUN),

TURN

Traversal Using Relays around NAT (TURN) allows the host to control the operation of the relay and to exchange packets with its peers using the relay.

This version of PJNATH implements both TCP and UDP client transport and it complies with the following TURN draft:

• draft-ietf-behave-turn-07: Obtaining Relay Addresses from Simple Traversal Underneath NAT (STUN)

ICE

Interactive Connectivity Establishment (ICE) is a standard based methodology for traversing Network Address Translator (NAT). This implementation is aimed to provide a usable and generic ICE transports for different types of application, including but not limited to the usage of ICE in SIP/SDP offer/answer.

This version of PJNATH implements the following ICE draft:

• draft-ietf-mmusic-ice-19.txt draft. The PJNATH ICE

NAT Classification Utility

The PJNATH library also provides NAT classification utility as described in RFC 3489. While the practice to detect the NAT type to assist NAT traversal has been deprecated in favor of ICE, the information may still be useful for troubleshooting purposes, hence the utility is provided.

Library Organization

The PJNATH library consists of many components with each providing specific functionality that may or may not be of the interests of applications (or application developers). This section attempts to give brief overview on the components provided by PJNATH.

The PJNATH components from the highest layer to the lower layer are as follows.

High-level Transport Objects

PJNATH library provides some high-level objects that may be used by applications:

STUN Transport

The STUN aware socket transport provides asynchronous UDP like socket transport with the additional capability to query the publicly mapped transport address (using STUN resolution), to refresh the NAT binding, and to demultiplex internal STUN messages from application data (the application data may be a STUN message as well).

TURN Client Transport

The TURN client transport may be used by the application to send and receive data via TURN server. For more information please see the documentation of TURN client transport.

ICE Stream Transport

The ICE Stream Transport provides transport interface to send and receive data through connection that is negotiated with ICE protocol. The ICE Stream Transport naturally contains both STUN Transport and TURN client transport.

The ICE Stream Transport interface is suitable for both SIP or non-SIP use. For SIP use, application may prefer to use the ICE media transport in PJMEDIA instead where it has been integrated with the SDP offer and answer mechanism.

NAT Classification Utility

PJNATH also provides PJNATH_NAT_DETECT to assist troubleshooting of problems related to NAT traversal.

Transport Independent Sessions Layer

Right below the high level transports objects are the transport independent sessions. These sessions don't have access to sockets, so higher level objects (such as transports) must give incoming packets to the sessions and provide callback to be called by sessions to send outgoing packets.

ICE Session

The ICE Session is used by the ICE Stream Transport and contains the actual logic of the ICE negotiation.

TURN Session

The Transport independent TURN client session is used by the TURN client transport and it contains TURN protocol logic. Implementors may implement other types of TURN client connection (such as TURN TLS client) by utilizing this session.

STUN Session

The STUN Client/Server Session manages STUN message exchange between a client and server (or vice versa). It manages STUN Client Transaction for sending or receiving requests and STUN Authentication for both both incoming and outgoing STUN messages.

The STUN Client/Server Session is naturally used by the Transport independent TURN client session and ICE Session

STUN Transaction Layer

The STUN Client Transaction is a thin layer to manage retransmission of STUN requests.

STUN Messaging Layer

At the very bottom of the PJNATH components is the STUN Message Representation and Parsing layer. The API contains various representation of STUN messaging components and it provides API to encode and decode STUN messages.

Class Diagram

The following class diagram shows the interactions between objects in PJNATH:

Class Diagram

Sample Applications

Some sample applications have been provided with PJNATH, and it's available under pjnath/src directory:

• pjturn-client: this is a stand-alone, console based TURN client application to be used as a demonstration for PJNATH TURN client transport API and for simple testing against TURN server implementations. The client supports both UDP and TCP connection to the TURN server.

• pjturn-srv: this is a simple TURN server to be used for testing purposes. It supports both UDP and TCP connections to the clients.