operatorfoundation / shapeshifter-transports

Shapeshifter Transports is a set of Pluggable Transports implementing the Go API from the Pluggable Transports 2.0 specification

The Operator Foundation

Operator makes usable tools to help people around the world with censorship, security, and privacy.

Shapeshifter

The Shapeshifter project provides network protocol shapeshifting technology (also sometimes referred to as obfuscation). The purpose of this technology is to change the characteristics of network traffic so that it is not identified and subsequently blocked by network filtering devices.

There are two components to Shapeshifter: transports and the dispatcher.

If you are an end user that is trying to circumvent filtering on your network, or a developer that wants to add pluggable transports to an existing tool that is not written in the Go programming language, then you probably want shapeshifter-dispatcher. Please note that familiarity with executing programs on the command line is necessary to use this tool.

If you are looking for a complete, easy-to-use VPN that incorporates shapeshifting technology and has a graphical user interface, consider Moonbounce, an application for macOS which incorporates shapeshifting without the need to write code or use the command line.

Shapeshifter Transports

The purpose of the transport suite is to provide a variety of transports to choose from. Each transport implements a different method of shapeshifting network traffic. The goal is for application traffic to be sent over the network in a shapeshifted form that bypasses network filtering, allowing the application to work on networks where it would otherwise be blocked or heavily throttled.

Each transport provides a different approach to shapeshifting. These transports are provided as a Go library which can be integrated directly into applications. The dispatcher is 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.

These transports implement the Pluggable Transports 3.0 specification. Specifically, they implement the Go Transports API v3.

If you are a tool developer working in the Go programming language, then you probably want to use one or more transport libraries directly in your application.

The following transports are currently implemented in Go:

Replicant

Replicant is Operator's flagship transport which can be tuned for each adversary. It is designed to be more effective and efficient that older transports. It can be quickly reconfigured as filtering conditions change by updating just the configuration file.

A Swift implementation is also available.

Starbridge

Starbridge is a Pluggable Transport that requires only minimal configuration information from the user. Under the hood, it uses the Replicant Pluggable Transport technology for network protocol obfuscation. Replicant is more complex to configure, so Starbridge is a good starting point for those wanting to use the technology to circumvent Internet cenorship, but wanting a minimal amount of setup.

A Swift implementation is also available.

Shadow (Shadowsocks)

Shadowsocks is a simple, but effective and popular network traffic obfuscation tool that uses basic encryption with a shared password. Shadow is a wrapper for Shadowsocks that makes it available as a Pluggable Transport.

A Swift implementation is also available.

Optimizer

Optimizer is a pluggable transport that works with your other transports to find the best option. It has multiple configurable strategies to find the optimal choice among the available transports. It can be used for numerous optimization tasks, such as round robin load spreading among multiple transport servers or minimizing latency given multiple transport configurations.

Installation

For individual installation instructions, see the README's for the individual transports:

• Replicant README

• Starbridge README

• Shadow README

• Optimizer README

Frequently Asked Questions

What transport should I use in my application?

Try Replicant, Operator's flagship transport which can be tuned for each adversary. Email [email protected] for a sample config file for the adversary of interest. shadow is also a good choice as it works on many networks and is easy to configure.

If you are an application developer using Pluggable Transports, feel free to reach out to the Operator Foundation for help in determining which transport might work best for your application. Email [email protected].

My application is not written in Go. Can I still use the transports?

Yes, the Go API is only one way to integrate transports into your application. There is also an interprocess communication (IPC) protocol that allows you to control a separate process (called the dispatcher) which provides access to the transports through a proxy interface. When using this method, your application can be written in any language. You just need to implement the IPC protocol so that you can communicate with the dispatcher. The IPC protocol is specified in the Pluggable Transports 3.0 specification and an implementation of the dispatcher is available which you can bundle with your application.

In addition, we have native Swift implementations available for those developers looking to integrate transports directly into their iOS, macOS, or Linux applications:

• Replicant
• Starbridge
• Shadow

Credits

• Replicant, Starbridge, Shadow, and Optimizer were developed by Operator Foundation
• Shadowsocks was developed by the Shadowsocks team.

shapeshifter-transports's Issues

Are all the transports listed in the Readme.md actually supported?

The Readme.md of this repo says:

The following transports are currently provided by the library:

• meek
• obfs4
• obfs3
• obfs2
• scramblesuit

However I see that actually only obfs2 is being included in https://github.com/OperatorFoundation/shapeshifter-transports/blob/master/transports/transports.go#L81. I also don't see any code for obfs3 or scramblesuit in the repo itself. There is code for obfs4 (which looks like obfs4proxy from @Yawning), but it doesn't seem to be imported by transports.go. I also see some glue code for shadowsocks, but it's unclear if that is also supported.

Are these PTs supported?

It would also be useful perhaps to make it clear from the readme that this is work in progress and that some bits are not yet working.

I would perhaps be interested t help out with this, if it were more clear what is missing and what is the current state and direction of the project.

Broken links

Looks like all the transport readme links are broken due to the v2 v3 creation. My suggestion is to look for consistency:

• call it all the same (README or readme),
• point to the main branch not the master one
• Point to either the 'front page' or the README.md directly: vs

Replicant polish toneburst packages missing

This commit introuced polish and toneburst from replicant: 566171f

However both give me a 404:
github.com/OperatorFoundation/shapeshifter-transports/transports/replicant/polish
github.com/OperatorFoundation/shapeshifter-transports/transports/replicant/toneburst

:~/go# go get github.com/OperatorFoundation/shapeshifter-transports/transports/Replicant
package github.com/OperatorFoundation/shapeshifter-transports/transports/replicant/polish: cannot find package "github.com/OperatorFoundation/shapeshifter-transports/transports/replicant/polish" in any of:
        /usr/lib/go-1.11/src/github.com/OperatorFoundation/shapeshifter-transports/transports/replicant/polish (from $GOROOT)
        /root/go/src/github.com/OperatorFoundation/shapeshifter-transports/transports/replicant/polish (from $GOPATH)
package github.com/OperatorFoundation/shapeshifter-transports/transports/replicant/toneburst: cannot find package "github.com/OperatorFoundation/shapeshifter-transports/transports/replicant/toneburst" in any of:
        /usr/lib/go-1.11/src/github.com/OperatorFoundation/shapeshifter-transports/transports/replicant/toneburst (from $GOROOT)
        /root/go/src/github.com/OperatorFoundation/shapeshifter-transports/transports/replicant/toneburst (from $GOPATH)

Shadowsocks example is unsafe

The Shadow documentation is using a stream cipher that should be banned. It's unsafe and easy to block.

Please update the example to use one of the AEAD Ciphers.

I would also recommend removing support for stream ciphers from your implementation. There's no reason for that and it only helps users shoot themselves in the foot.

shapeshifter-dispatcher build breaking due to changes to dial function

This commit 4e221a1 broke the build of shapeshifter-dispatcher due to the code expecting the old method signature for Dial() (without the error return value). Even if the code in shapeshifter-dispatcher were updated it's still broken due to the change not being applied to obfs2 and dust.

could we have semantic versioning?

Now and then there are changes in the API of the transports that are not backward compatible (like few days ago adding the Dialer). In LEAP we use the obfs4 transport directly with a little library grapper. So every time the the API changes our code stops compiling.

Will be great if this repo starts doing semantic versioning. Since golang 1.11 there are support for modules:
https://github.com/golang/go/wiki/Modules

That implies basically create a go.mod file in the repo (I can send a pull-req for it) and add a tag to the repo for each release and incrementing the mayor number each time there is an API incompatibility change. This will allow us to pin a mayor version and only increase it when we adapt the code to the API changes.

How do you feel about that? Can I help in the process?