1## obfs4 - The obfourscator 2#### Yawning Angel (yawning at schwanenlied dot me) 3 4### What? 5 6This is a look-like nothing obfuscation protocol that incorporates ideas and 7concepts from Philipp Winter's ScrambleSuit protocol. The obfs naming was 8chosen primarily because it was shorter, in terms of protocol ancestery obfs4 9is much closer to ScrambleSuit than obfs2/obfs3. 10 11The notable differences between ScrambleSuit and obfs4: 12 13 * The handshake always does a full key exchange (no such thing as a Session 14 Ticket Handshake). 15 * The handshake uses the Tor Project's ntor handshake with public keys 16 obfuscated via the Elligator 2 mapping. 17 * The link layer encryption uses NaCl secret boxes (Poly1305/XSalsa20). 18 19As an added bonus, obfs4proxy also supports acting as an obfs2/3 client and 20bridge to ease the transition to the new protocol. 21 22### Why not extend ScrambleSuit? 23 24It's my protocol and I'll obfuscate if I want to. 25 26Since a lot of the changes are to the handshaking process, it didn't make sense 27to extend ScrambleSuit as writing a server implementation that supported both 28handshake variants without being obscenely slow is non-trivial. 29 30### Dependencies 31 32Build time library dependencies are handled by the Go module automatically. 33 34If you are on Go versions earlier than 1.11, you might need to run `go get -d 35./...` to download all the dependencies. Note however, that modules always use 36the same dependency versions, while `go get -d` always downloads master. 37 38 * Go 1.11.0 or later. Patches to support up to 2 prior major releases will 39 be accepted if they are not overly intrusive and well written. 40 * See `go.mod`, `go.sum` and `go list -m -u all` for build time dependencies. 41 42### Installation 43 44To build: 45 46 `go build -o obfs4proxy/obfs4proxy ./obfs4proxy` 47 48To install, copy `./obfs4proxy/obfsproxy` to a permanent location 49(Eg: `/usr/local/bin`) 50 51Client side torrc configuration: 52``` 53ClientTransportPlugin obfs4 exec /usr/local/bin/obfs4proxy 54``` 55 56Bridge side torrc configuration: 57``` 58# Act as a bridge relay. 59BridgeRelay 1 60 61# Enable the Extended ORPort 62ExtORPort auto 63 64# Use obfs4proxy to provide the obfs4 protocol. 65ServerTransportPlugin obfs4 exec /usr/local/bin/obfs4proxy 66 67# (Optional) Listen on the specified address/port for obfs4 connections as 68# opposed to picking a port automatically. 69#ServerTransportListenAddr obfs4 0.0.0.0:443 70``` 71 72### Tips and tricks 73 74 * On modern Linux systems it is possible to have obfs4proxy bind to reserved 75 ports (<=1024) even when not running as root by granting the 76 `CAP_NET_BIND_SERVICE` capability with setcap: 77 78 `# setcap 'cap_net_bind_service=+ep' /usr/local/bin/obfs4proxy` 79 80 * obfs4proxy can also act as an obfs2 and obfs3 client or server. Adjust the 81 `ClientTransportPlugin` and `ServerTransportPlugin` lines in the torrc as 82 appropriate. 83 84 * obfs4proxy can also act as a ScrambleSuit client. Adjust the 85 `ClientTransportPlugin` line in the torrc as appropriate. 86 87 * The autogenerated obfs4 bridge parameters are placed in 88 `DataDir/pt_state/obfs4_state.json`. To ease deployment, the client side 89 bridge line is written to `DataDir/pt_state/obfs4_bridgeline.txt`. 90 91### Thanks 92 93 * David Fifield for goptlib. 94 * Adam Langley for his Elligator implementation. 95 * Philipp Winter for the ScrambleSuit protocol which provided much of the 96 design. 97