quictun

README

quictun

quictun is a simple hidden tunnel based on the QUIC protocol.

This repository contains a proof-of-concept implementation of quictun. Its purpose is to demonstrate that quictun clients and servers can be implemented with minimal effort on top of an existing QUIC and HTTP/2 over QUIC implementation. The implementation uses the quic-go QUIC implementation as a basis.

Note that while quictun is meant to be implemented on top of IETF QUIC, this proof-of-concept implementation uses Google QUIC instead, as at the time of development no usable implementation of the (still work-in-progress) IETF version exists. Due to the limitations of the underlying QUIC implementation, this quictun implementation is neither meant for production usage, nor for performance evaluation of the approach.

Overview

h2quic is a fork of github.com/lucas-clemente/quic-go/h2quic. It adds the upgrade mechanism to the HTTP/2 over QUIC (h2quic) implementation. The fork can be used as a drop-in replacement for the upstream package to add support for quictun.

cmd/quictun_client contains a very minimal client example. Actual clients MUST take care to be indistinguishable from an legitimate HTTP/2 over QUIC client, which a censor is unwilling to block, at the wire level. This could be achieved e.g. by reusing the net stack of a QUIC-capable web browser.

cmd/quictun_server likewise contains a minimal server example. Note that this example server is easily fingerprintable and thus blockable.

Installation

go get -u github.com/julienschmidt/quictun

Usage

Clients should use the quictun.Client struct. An example client can be found in cmd/quictun_client.

Servers should either use the quictun.Server struct directly and manually implement the upgrade mechanism in the web server, or use the h2quic sub-package.

A valid certificate is required to operate a server, which can e.g. be acquired from Let's Encrypt. For testing purposes, the client may be insecurely configured to allow any, possible invalid, certificate instead. The example client provides a -invalidCerts flag for that purpose.

Documentation

Overview

Package quictun is an implementation of quictun. The package can be used to implement quictun clients and servers.

Index

• Variables
• type Client
  • func (c *Client) Run() error
• type SequenceCache
• type Server
  • func (s *Server) CheckSequenceNumber(header string) bool
  • func (s *Server) Upgrade(session quic.Session)

Variables

var (
	ErrInvalidResponse   = errors.New("server returned an invalid response")
	ErrInvalidSequence   = errors.New("client sequence number invalid")
	ErrNotAQuictunServer = errors.New("server does not seems to be a quictun server")
	ErrWrongCredentials  = errors.New("authentication credentials seems to be wrong")
)

Types

type Client

type Client struct {
	// config
	ListenAddr  string
	TunnelAddr  string
	UserAgent   string
	TlsCfg      *tls.Config
	QuicConfig  *quic.Config
	DialTimeout time.Duration
	// contains filtered or unexported fields
}

Client holds the configuration and state of a quictun client

func (*Client) Run

func (c *Client) Run() error

Run starts the client to accept incoming SOCKS connections, which are tunneled to the configured quictun server. The tunnel connection is opened only on-demand.

type SequenceCache

type SequenceCache interface {
	Set(key uint64, value uint32) (old uint32)
	Get(key uint64) (value uint32)
}

SequenceCache is a cache for client sequence numbers. Implementations should limit the number of cached key-value pairs using a strategy like least recently used (LRU).

type Server

type Server struct {
	DialTimeout   time.Duration
	SequenceCache SequenceCache
}

Server is a quictun server which handles QUIC sessions upgraded to the quictun protocol.

func (*Server) CheckSequenceNumber

func (s *Server) CheckSequenceNumber(header string) bool

CheckSequenceNumber checks and caches the sequence number sent by a client

func (*Server) Upgrade

func (s *Server) Upgrade(session quic.Session)

Upgrade starts using a given QUIC session with the quictun protocol. The quictun server immediately starts accepting new QUIC streams and assumes them to speak the quictun protocol (QTP). The actual protocol upgrade (via a HTTP/2 request-response) is handled entirely by the web server.