From daf4799fd6c9e9acc47df86fe076d2de760d9969 Mon Sep 17 00:00:00 2001 From: Brandon Wiley Date: Tue, 22 Nov 2016 10:55:28 -0600 Subject: Rewrote README.md to be relevant to shapeshifter-dispatcher --- README.md | 183 ++++++++++++++++++++++++++++++++++++++------------------------ 1 file changed, 114 insertions(+), 69 deletions(-) (limited to 'README.md') diff --git a/README.md b/README.md index a7d2343..7262d3b 100644 --- a/README.md +++ b/README.md @@ -1,96 +1,141 @@ -## obfs4 - The obfourscator -#### Yawning Angel (yawning at torproject dot org) +# The Operator Foundation -### What? +Operator makes useable tools to help people around the world with censorship, security, and privacy. -This is a look-like nothing obfuscation protocol that incorporates ideas and -concepts from Philipp Winter's ScrambleSuit protocol. The obfs naming was -chosen primarily because it was shorter, in terms of protocol ancestery obfs4 -is much closer to ScrambleSuit than obfs2/obfs3. +## Shapeshifter -The notable differences between ScrambleSuit and obfs4: +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. - * The handshake always does a full key exchange (no such thing as a Session - Ticket Handshake). - * The handshake uses the Tor Project's ntor handshake with public keys - obfuscated via the Elligator 2 mapping. - * The link layer encryption uses NaCl secret boxes (Poly1305/XSalsa20). +There are two components to Shapeshifter: transports and the dispatcher. Each +transport provide 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. -As an added bonus, obfs4proxy also supports acting as an obfs2/3 client and -bridge to ease the transition to the new protocol. +If you are a tool developer working in the Go programming language, then you +probably want to use the transports library directly in your application. +[https://github.com/OperatorFoundation/shapeshifter-transports] -### Why not extend ScrambleSuit? +If you want a end user that is trying to circumvent filtering on your network or +you are 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 the +dispatcher. Please note that familiarity with executing programs on the command +line is necessary to use this tool. +[https://github.com/OperatorFoundation/shapeshifter-dispatcher] -It's my protocol and I'll obfuscate if I want to. +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. -Since a lot of the changes are to the handshaking process, it didn't make sense -to extend ScrambleSuit as writing a server implementation that supported both -handshake variants without being obscenely slow is non-trivial. +### Shapeshifter Dispatcher -### Dependencies +This is the repository for the shapeshifter-dispatcher command line proxy tool. +If you are looking for the transports is provides, they are here: +[https://github.com/OperatorFoundation/shapeshifter-transports] -Build time library dependencies are handled by go get automatically but are -listed for clarity. +The dispatcher implements the Pluggable Transports 2.0 draft 1 specification available here: +[http://www.pluggabletransports.info/assets/PTSpecV2Draft1.pdf] - * Go 1.2.0 or later. Prior versions of Go (Eg: 1.0.2) are missing certain - important parts of the runtime library like a SHA256 implementation. - * go.crypto (https://golang.org/x/crypto) - * go.net (https://golang.org/x/net) - * ed25519/extra25519 (https://github.com/agl/ed25519/extra25519) - * SipHash-2-4 (https://github.com/dchest/siphash) - * goptlib (https://git.torproject.org/pluggable-transports/goptlib.git) +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 shapeshifted form that bypasses network filtering, allowing +the application to work on networks where it would otherwise be blocked or +heavily throttled. -### Installation +The dispatcher currently supports the following proxy modes: + * SOCKS5 (with optional PT 1.0 authentication protocol) + * Transparent TCP + * Transparent UDP + * STUN UDP -To build: -`go get github.com/OperatorFoundation/obfs4/obfs4proxy` +The dispatcher currently supports the following transports: + * meek + * obfs4 + * obfs3 + * obfs2 + * scramblesuit -To install: -Copy `$GOPATH/bin/obfs4proxy` to a permanent location (Eg: `/usr/local/bin`) +#### Installation -Client side torrc configuration: -``` -ClientTransportPlugin obfs4 exec /usr/local/bin/obfs4proxy -``` +The dispatcher is written in the Go programming language. To compile it you need +to install Go: -Bridge side torrc configuration: -``` -# Act as a bridge relay. -BridgeRelay 1 +[https://golang.org/doc/install] -# Enable the Extended ORPort -ExtORPort auto +If you just installed Go for the first time, you will need to create a directory +to keep all of your Go source code: -# Use obfs4proxy to provide the obfs4 protocol. -ServerTransportPlugin obfs4 exec /usr/local/bin/obfs4proxy +mkdir ~/go +export GOPATH=~/go +cd ~/go -# (Optional) Listen on the specified address/port for obfs4 connections as -# opposed to picking a port automatically. -#ServerTransportListenAddr obfs4 0.0.0.0:443 -``` +Software written in Go is installed using the "go get" command: -### Tips and tricks +go get github.com/OperatorFoundation/shapeshifter-dispatcher - * On modern Linux systems it is possible to have obfs4proxy bind to reserved - ports (<=1024) even when not running as root by granting the - `CAP_NET_BIND_SERVICE` capability with setcap: +This will fetch the source code for shapeshifter-dispatcher, and all the +dependencies, compile everything, and put the result in +bin/shapeshifter-dispatcher. - `# setcap 'cap_net_bind_service=+ep' /usr/local/bin/obfs4proxy` +#### Running - * obfs4proxy can also act as an obfs2 and obfs3 client or server. Adjust the - `ClientTransportPlugin` and `ServerTransportPlugin` lines in the torrc as - appropriate. +Run without argument to get usage information: - * obfs4proxy can also act as a ScrambleSuit client. Adjust the - `ClientTransportPlugin` line in the torrc as appropriate. +bin/shapeshifter-dispatcher - * The autogenerated obfs4 bridge parameters are placed in - `DataDir/pt_state/obfs4_state.json`. To ease deployment, the client side - bridge line is written to `DataDir/pt_state/obfs4_bridgeline.txt`. +A minimal configuration requires at least --client, --state, and --transports. +Example: -### Thanks +bin/shapeshifter-dispatcher --client --state state --transports obfs2 - * David Fifield for goptlib. - * Adam Langley for his Elligator implementation. - * Philipp Winter for the ScrambleSuit protocol which provided much of the - design. +Use either --client or --server to place the proxy into client or server mode, +respectively. Use --state to specify a directory to put transports state +information. Use --transports to specify which transports to launch. + +The default proxy mode is SOCKS5 (with optional PT 1.0 authentication protocol), +which can only proxy SOCKS5-aware TCP connections. For some transports, the +proxied connection will also need to know how to speak the PT 1.0 authentication +protocol. This requirement varies by the transport used. + +Another TCP proxy mode is available, Transparent TCP, by using the --transparent +flag. In this mode, the proxy listens on a socket and any data from incoming +connections is forwarded over the transport. + +UDP proxying can be enabled with the --udp flag. The default UDP mode is STUN +packet proxying. This requires that the application only send STUN packets, so +works for protocols such as WebRTC, which are based on top of STUN. + +Another UDP proxy mode is available, Transparent UDP, by using the --transparent +flag with the --udp flag. In this mode, the proxy listens on a UDP socket and +any incoming packets are forwarded over the transport. + +Only one proxy mode can be used at a time. + +The full set of command line flags is specified in the Pluggable Transport 2.0 +draft 1 specification. +[http://www.pluggabletransports.info/assets/PTSpecV2Draft1.pdf] + +##### Environment Variables + +Using command line flags is convenient for testing. However, when launching the +dispatcher automatically from inside of an application, another option is to +use environment variables. Most of the functionality specified by command line +flags can also be set using environment variables instead. + +The full set of environment variables is specified in the Pluggable Transport +2.0 draft 1 specification. +[http://www.pluggabletransports.info/assets/PTSpecV2Draft1.pdf] + +### Credits + +shapeshifter-dispatcher is based on the Tor project's "obfs4proxy" tool. + + * Yawning Angel for obfs4proxy + * David Fifield for goptlib + * Adam Langley for the Go Elligator implementation. + * Philipp Winter for the ScrambleSuit protocol. -- cgit v1.2.3