Skip to content

reTurn Overview

Scott Godin edited this page Jan 29, 2021 · 1 revision

Table of Contents

Overview

What is reTurn?

reTurn is a highly efficient C++ open-source STUN/TURN server and client library. It is an implementation of the latest STUN/TURN RFCs: RFC5389 (STUN), and RFC5766 (TURN).

What is STUN?

taken from RFC5389

Session Traversal Utilities for NAT (STUN) is a protocol that serves as a tool for other protocols in dealing with Network Address Translator (NAT) traversal. It can be used by an endpoint to determine the IP address and port allocated to it by a NAT. It can also be used to check connectivity between two endpoints, and as a keep-alive protocol to maintain NAT bindings. STUN works with many existing NATs, and does not require any special behavior from them.

What is TURN?

taken from RFC5766

If a host is located behind a NAT, then in certain situations it can be impossible for that host to communicate directly with other hosts (peers) located behind other NATs. In these situations, it is necessary for the host to use the services of an intermediate node that acts as a communication relay. This specification defines a protocol, called TURN (Traversal Using Relays around NAT), that allows the host to control the operation of the relay and to exchange packets with its peers using the relay.

The TURN protocol can be used in isolation, but is more properly used as part of the ICE (Interactive Connectivity Establishment) approach to NAT traversal.

Initial Project Team

  • Rohan Mahy
  • Scott Godin ( s g o d i n AT s i p s p e c t r u m DOT c o m )

Key Features

  • Correct and comprehensive implementation of the relevant standards from the SIP working groups
  • Support for UDP/TCP/TLS protocols over both IPv4 and IPv6
  • Synchronous and asynchrounous client APIs provided
  • Designed for high scalability
  • Platforms: Win32, Linux, Mac OS X
  • RFC3489 backwards compatibility support
  • Shared secret with short term credentials
  • Shared secret with long term credentials (implementation currently only accepts one hardcoded username/password)
  • Finger Print Insertion and Validation
  • Turn Allocation
  • Requested Props (Even, Pair)
  • Turn Permissions
  • Asynchronous Client APIs
  • Channel Binding
  • Fully passes draft-ietf-behave-stun-test-vectors-04 test cases

Upcoming Features

  • Support TCP relaying
  • Bandwidth Enforcement
  • User Quota Enforcement
  • Multi-threaded Support
  • ICE Support

How to Participate

Project Details

Working with reTurn

Current External Library Usage

  • currently uses OpenSSL, ASIO, BOOST and RUTIL
  • ASIO - 1.10.6 or above - recently tested with 1.14.0
    • Used for server sockets and transports
    • Note: We are not using the ASIO embedded into boost since it cannot be used in header file only mode. See Note below
    • Tuple information used in StunMessage uses asio::ip::udp::endpoint - easily changed
    • StunMessage, TurnAllocation and RequestHandler use asio::ip:address to manipulate IPV6, and IPV4 StunAddresses - easily changed
    • StunTuple uses asio::ip::address - easily changed
  • BOOST - 1.34.0 or above - recently tested with 1.60.0
    • Using BOOST in no-lib mode (header file only mode) is fine
    • BOOST::bind is used in server transports
    • BOOST::crc_optimal is used for fingerprint CRC calculations
    • BOOST::shared_ptr, array, enable_shared_from_this is used in server transports
    • RUTIL - Data class is used in StunMessage and StunAuth for strings and TurnData, SharedPtr is also used
 Note:  Using boost 1.53.0 that includes ASIO 1.4.8 was considered, but this adds 
        an extra requirement to build the boost system library.  Use of boost 1.35.0 
        (or above) and a standalone ASIO release allows us to use boost without needing
        to link with any boost libraries, thus making builds easier (especially on 
        Windows based platforms).

Licensing

reTurn is distributed under a standard 3-clause BSD license:

 Copyright (c) 2007-2008, Plantronics, Inc.
 Copyright (c) 2008-2018, SIP Spectrum, Inc.
 All rights reserved.
 
 Redistribution and use in source and binary forms, with or without
 modification, are permitted provided that the following conditions are 
 met:
 
 1. Redistributions of source code must retain the above copyright 
    notice, this list of conditions and the following disclaimer. 
 
 2. Redistributions in binary form must reproduce the above copyright
    notice, this list of conditions and the following disclaimer in the
    documentation and/or other materials provided with the distribution. 
 
 3. Neither the name of Plantronics nor the names of its contributors 
    may be used to endorse or promote products derived from this 
    software without specific prior written permission. 
 
 THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS 
 "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT 
 LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR 
 A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT 
 OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, 
 SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT 
 LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, 
 DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY 
 THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT 
 (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE 
 OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 
 ==================================================================== */
Clone this wiki locally