Using Pluggable Transports

This table shows some examples of software already using Pluggable Transports across the most popular platforms:

If you’re a software developer looking to deploy Pluggable Transports, the rest of the content on this plage will help you. We will look at some of the options for implementation, focusing mainly on Go - the language already used by many PT developers implementers.

Implementation Options

Developers can implement transports from scratch or using a library that implements some parts of the IPC protocol, such as shapeshifter-ipc or goptlib. Pluggable Transports themselves can be written in any programming language. A Pluggable Transport interacts with with a host application using a type of inter-process communication (IPC) protocol which is described in the Pluggable Transports 2.1 specification. There are Pluggable Transport implementations written in Go, Python, C++, and C.

If you just want to add existing transports into your application, this table summarizes the libraries that have already been developed and are available for us:

Implementation outside of these environments can be done with Shapeshifter Dispatcher, a command-line tool which provides a proxy that wraps the transport library. It has several different proxy modes and can proxy both TCP and UDP traffic.

The purpose of the dispatcher is to provide different proxy interfaces to using transports. Through the use of these proxies, application traffic can be sent over the network in a form that bypasses network filtering, allowing the application to work on networks where it would otherwise be blocked or heavily throttled.

Transport Connections vs Network Connections

An important distinction to remember when implementing a transport is the difference between transport connections and network connections. A transport connection is a communication channel between a transport client and a transport server, which is capable of communication using the chosen transport protocol. A network connection is a communication channel between two computers, which communicates data streams that can be in any protocol. For convenience, the API for making transport connections mimics closely the interface for making network connections. A transport connection essentially looks to the application like a “virtual network connection”. However, the actual mapping between transport connections and network connections depends on the transport. Some transports have exactly one network connection for each transport connection. Other transports may split the transport connection’s data over multiple network connections, or multiplex multiple transport connections over one network connection. A transport could even have 0 network connections, instead conveying data using a connectionless alternative such as UDP.

While the Pluggable Transport API is flexible enough to accommodate a variety of mappings between transport connections and network connections, it also provides support for the common case of one transport connection for each network connection. In particular, the underlying network connection for a transport connection, if there is one, can be retrieved and accessed directly. This is useful for doing lower-level configuration of the network, such as setting network options on the network connection.

This page contains content from Dispatcher’s README and documentation by Dr. Brandon Wiley