ReTurn Overview

From reSIProcate
Jump to: navigation, search

Overview[edit]

What is reTurn?[edit]

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?[edit]

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?[edit]

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[edit]

  • 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[edit]

  • 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[edit]

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

How to Participate[edit]

Project Details[edit]

Working with reTurn[edit]


Current External Library Usage[edit]

  • currently uses OpenSSL, ASIO, BOOST and RUTIL
  • ASIO - 1.2.0 or above - recently tested with 1.4.8
    • 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.53.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[edit]

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

/* ====================================================================

Copyright (c) 2007-2008, Plantronics, 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.

==================================================================== */