Open source STUN library.

This module contains implementation of STUN library in PJNATH - the open source NAT helper containing STUN and ICE.

Library organizations

The STUN part of PJNATH consists of the the following sections (see Table of Contents below).

Using the STUN transport

The STUN-aware socket transport is a ready to use object which provides send and receive interface for communicating UDP packets as well as means to communicate with the STUN server and manage the STUN mapped address.

Some features of the PJNATH_STUN_SOCK:

  • API to send and receive UDP packets,

  • interface to query the STUN mapped address info,

  • multiplex STUN and non-STUN incoming packets and distinguish between STUN responses that belong to internal requests with application data (the application data may be STUN packets as well),

  • resolution of the STUN server with DNS SRV query (if wanted),

  • maintaining STUN keep-alive, and

  • handle changes in STUN mapped address binding.

Please see STUN-aware socket transport for more information.

Advanced use of the STUN components

The rest of the STUN part of the library provides lower level objects which can be used to build your own STUN based transport or protocols (officially called STUN usages). These will be explained briefly below.

The STUN session

A STUN session is interactive information exchange between two STUN endpoints that lasts for some period of time. It is typically started by an outgoing or incoming request, and consists of several requests, responses, and indications. All requests and responses within the session typically share a same credential.

The STUN session is a transport-independent object to manage a client or server STUN session. It is one of the core object in PJNATH, and it is used by several higher level objects including the STUN-aware socket transport, TURN client session, and ICE Session.

The STUN session has the following features:

  • transport independent

  • authentication management

  • static or dynamic credential

  • client transaction management

  • server transaction management

For more information, including how to use it please see STUN session.

Extending STUN to support other usages

At present, the STUN subsystem in PJNATH supports STUN Binding, TURN, and ICE usages. If other usages are to be supported, typically you would need to add new STUN methods (and the corresponding request and response message types), attributes, and error codes to STUN Message Representation and Parsing subsystem of PJNATH, as well as implementing the logic for the STUN usage.

STUN samples

The pjturn-client, a sample TURN client sample application also contains sample code to use STUN-aware socket transport.

Also see PJNATH Samples and screenshots for other samples.