Tunneling TCP in WebSocket (ssh -D alternative)
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Failed to load latest commit information.
extra
wstan
.gitignore
Dockerfile
LICENSE
README.md
main.py
setup.py

README.md

wstan

PyPI PyPI

Tunneling TCP connections in WebSocket to circumvent firewall. It's light and can run on some PaaS (SSL supported).

User-Agent(SOCKS5/HTTP) <--> (wstan)Client <-- Internet --> (wstan)Server <--> Target

Features

  • Encryption
  • Proxy support (using HTTP CONNECT; test yours)
  • Display error message in browser (plain HTTP only)
  • SOCKS5 and HTTP (slower) in the same port

WARN: Do not rely it on security when not using SSL

Usage

wstan [-h] [-g] [-c | -s] [-d] [-z] [-p PORT] [-t TUN_ADDR]
      [-r TUN_PORT]
      [uri] [key]

positional arguments:
  uri                   URI of server
  key                   base64 encoded 16-byte key

optional arguments:
  -h, --help            show this help message and exit
  -g, --gen-key         generate a key and exit
  -c, --client          run as client (default, also act as SOCKS5/HTTP(S)
                        server)
  -s, --server          run as server
  -d, --debug
  -z, --compatible      useful when server is behind WS proxy
  -i INI, --ini INI     load config file
  -y PROXY, --proxy PROXY
                        let client use a HTTPS proxy (host:port)
  -p PORT, --port PORT  listen port of SOCKS5/HTTP(S) server at localhost
                        (defaults 1080)
  -t TUN_ADDR, --tun-addr TUN_ADDR
                        listen address of server, overrides URI
  -r TUN_PORT, --tun-port TUN_PORT
                        listen port of server, overrides URI
  --x-forward           Use X-Forwarded-For as client IP address when behind
                        proxy

Setup:

# generate a key using "wstan -g"
wstan ws://yourserver.com KEY -s  # server
wstan ws://yourserver.com KEY  # client
# a proxy server is listening at localhost:1080 now (at client side)

Setup for OpenShift v3:

  1. Generate a key
  2. Pull Docker image and set environment variable KEY
  3. Add default route
  4. http://xxx.openshiftapps.com will return 200 if everything goes right; Run client wstan ws://xxx.openshiftapps.com KEY

It's a reinvented wheel

Details

Original Goal: make active probing against server side more difficult while still keeping low latency of connection establishment and being stateless (inspired by shadowsocks).

Weakness: can't prevent MITM attack; client can't detect fake server (may receive garbage data); replay attack detection may fail

Tech Detail:

  • request frame has HMAC and timestamp (data frame has nothing), and all frames are encrypted using AES-128-CTR
  • server will save encryption nonce and timestamp when receiving valid request (to detect replay attack)
  • the first request frame will be encoded into URI of WS handshake (to achieve low latency)
  • it has a connection pool