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