obfs4

The obfourscator (Courtesy mirror)

1,076

179

1,076

View on GitHub

Top Related Projects

bbs

3,349

Forum for discussing Internet censorship circumvention

Quick Overview

Obfs4 is a network protocol obfuscation layer designed to make network traffic appear random. It's primarily used as a pluggable transport for Tor to bypass censorship and avoid detection. Obfs4 improves upon its predecessors by adding authentication and more sophisticated obfuscation techniques.

Pros

Strong obfuscation capabilities, making traffic difficult to detect and block
Includes authentication to prevent active probing attacks
Highly configurable, allowing for fine-tuning of obfuscation parameters
Implemented in Go, providing good performance and cross-platform compatibility

Cons

Requires distribution of bridge information through out-of-band channels
May introduce additional latency due to obfuscation overhead
Complexity of the protocol can make it challenging to implement and maintain
Potential for misuse in malicious activities, though this is true for many privacy-enhancing technologies

Code Examples

// Initialize an obfs4 server
config := &obfs4.ServerConfig{
    StateDir:    "/path/to/state",
    PrivateKey:  privateKey,
    PublicKey:   publicKey,
    NodeID:      nodeID,
    BindAddr:    "0.0.0.0:443",
    OrAddr:      "127.0.0.1:9001",
}
server, err := obfs4.NewServer(config)

// Create an obfs4 client connection
clientConfig := &obfs4.ClientConfig{
    StateDir:    "/path/to/state",
    NodeID:      nodeID,
    PublicKey:   serverPublicKey,
    ServerAddr:  "example.com:443",
}
conn, err := obfs4.Dial("tcp", clientConfig)

// Handle incoming obfs4 connections
listener, err := server.Listen()
for {
    conn, err := listener.Accept()
    go handleConnection(conn)
}

Getting Started

To use obfs4 in your Go project:

Install the library:
```
go get gitlab.com/yawning/obfs4.git
```
Import the package in your code:
```
import "gitlab.com/yawning/obfs4.git"
```
Initialize a server or client configuration as shown in the code examples above.
Use the NewServer() function to create a server, or Dial() to create a client connection.
Handle connections using standard Go networking patterns.

Competitor Comparisons

bbs

3,349

Forum for discussing Internet censorship circumvention

Pros of bbs

More active development with recent commits and releases
Broader scope, focusing on various censorship circumvention techniques
Larger community and contributor base

Cons of bbs

Less specialized, potentially less optimized for specific use cases
May have a steeper learning curve due to broader feature set
Potentially more complex to deploy and maintain

Code Comparison

obfs4:

func (t *Transport) Dial(network, address string) (net.Conn, error) {
    conn, err := t.dialFn(network, address)
    if err != nil {
        return nil, err
    }
    return NewObfs4Client(conn, t.Args)
}

bbs:

func (t *Transport) Dial(ctx context.Context, network, address string) (net.Conn, error) {
    d := t.Dialer
    if d == nil {
        d = &net.Dialer{}
    }
    conn, err := d.DialContext(ctx, network, address)
    if err != nil {
        return nil, err
    }
    return t.Handshake(ctx, conn)
}

Both projects implement a Dial function, but bbs includes context support and a more flexible dialer configuration.

Convert designs to code with AI

Introducing Visual Copilot: A new AI model to turn Figma designs to high quality code using your components.

Try Visual Copilot

README

obfs4 - The obfourscator

Yawning Angel (yawning at schwanenlied dot me)

What?

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.

The notable differences between ScrambleSuit and obfs4:

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).

As an added bonus, obfs4proxy also supports acting as an obfs2/3 client and bridge to ease the transition to the new protocol.

Why not extend ScrambleSuit?

It's my protocol and I'll obfuscate if I want to.

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.

Dependencies

Build time library dependencies are handled by the Go module automatically.

If you are on Go versions earlier than 1.11, you might need to run go get -d ./... to download all the dependencies. Note however, that modules always use the same dependency versions, while go get -d always downloads master.

Go 1.11.0 or later. Patches to support up to 2 prior major releases will be accepted if they are not overly intrusive and well written.
See go.mod, go.sum and go list -m -u all for build time dependencies.

Installation

To build:

`go build -o obfs4proxy/obfs4proxy ./obfs4proxy`

To install, copy ./obfs4proxy/obfsproxy to a permanent location (Eg: /usr/local/bin)

Client side torrc configuration:

ClientTransportPlugin obfs4 exec /usr/local/bin/obfs4proxy

Bridge side torrc configuration:

# Act as a bridge relay.
BridgeRelay 1

# Enable the Extended ORPort
ExtORPort auto

# Use obfs4proxy to provide the obfs4 protocol.
ServerTransportPlugin obfs4 exec /usr/local/bin/obfs4proxy

# (Optional) Listen on the specified address/port for obfs4 connections as
# opposed to picking a port automatically.
#ServerTransportListenAddr obfs4 0.0.0.0:443

Tips and tricks

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:

# setcap 'cap_net_bind_service=+ep' /usr/local/bin/obfs4proxy
obfs4proxy can also act as an obfs2 and obfs3 client or server. Adjust the ClientTransportPlugin and ServerTransportPlugin lines in the torrc as appropriate.
obfs4proxy can also act as a ScrambleSuit client. Adjust the ClientTransportPlugin line in the torrc as appropriate.
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.

Thanks

Loup Vaillant for motivating me to replace the Elligator implementation and a body of code I could draw on to accelerate the replacement process.
David Fifield for goptlib.
Adam Langley for his initial Elligator implementation.
Philipp Winter for the ScrambleSuit protocol which provided much of the design.

Top Related Projects

bbs

3,349

Forum for discussing Internet censorship circumvention

Convert designs to code with AI

Introducing Visual Copilot: A new AI model to turn Figma designs to high quality code using your components.

Try Visual Copilot