connectproxy

README

ConnectProxy

Small Go library to use CONNECT-speaking proxies standalone or with the proxy library.

Please see the godoc for more details.

This library is written to make connecting through proxies easier. It unashamedly steals from https://gist.github.com/jim3ma/3750675f141669ac4702bc9deaf31c6b, but adds a nice and simple interface.

For legal use only.

Domain Fronting

To make it easier to have a different SNI name and Host: header, a separate SNI name may be specified when registering the proxy. See the GeneratorWithConfig documentation for more details.

Examples

The godoc has a couple of examples. Also, in the examples directory there is an example program.

Documentation

Overview

Package connectproxy implements a proxy.Dialer which uses HTTP(s) CONNECT requests.

It is heavily based on https://gist.github.com/jim3ma/3750675f141669ac4702bc9deaf31c6b and meant to compliment the proxy package (golang.org/x/net/proxy).

Two URL schemes are supported: http and https. These represent plaintext and TLS-wrapped connections to the proxy server, respectively.

The proxy.Dialer returned by the package may either be used directly to make connections via a proxy which understands CONNECT request, or indirectly via dialer.RegisterDialerType.

Direct use:

/* Make a proxy.Dialer */
d, err := connectproxy.New("https://proxyserver:4433", proxy.Direct)
if nil != err{
        panic(err)
}

/* Connect through it */
c, err := d.Dial("tcp", "internalsite.com")
if nil != err {
        log.Printf("Dial: %v", err)
        return
}

/* Do something with c */

Indirectly, via dialer.RegisterDialerType:

/* Register handlers for HTTP and HTTPS proxies */
proxy.RegisterDialerType("http", connectproxy.New)
proxy.RegisterDialerType("https", connectproxy.New)

/* Make a Dialer for a proxy */
u, err := url.Parse("https://proxyserver.com:4433")
if nil != err {
        log.Fatalf("Parse: %v", err)
}
d, err := proxy.FromURL(u, proxy.Direct)
if nil != err {
        log.Fatalf("Proxy: %v", err)
}

/* Connect through it */
c, err := d.Dial("tcp", "internalsite.com")
if nil != err {
        log.Fatalf("Dial: %v", err)
}

/* Do something with c */

It's also possible to make the TLS handshake with an HTTPS proxy server use a different name for SNI than the Host: header uses in the CONNECT request:

d, err := NewWithConfig(
        "https://sneakyvhost.com:443",
        proxy.Direct,
        &connectproxy.Config{
                ServerName: "normalhoster.com",
        },
)
if nil != err {
        panic(err)
}

/* Use d.Dial(...) */

Index

• func GeneratorWithConfig(config *Config) func(*url.URL, proxy.ContextDialer) (proxy.ContextDialer, error)
• func New(u *url.URL, forward proxy.ContextDialer) (proxy.ContextDialer, error)
• func NewWithConfig(u *url.URL, forward proxy.ContextDialer, config *Config) (proxy.ContextDialer, error)
• type Config
• type ErrorConnectionTimeout
• type ErrorUnsupportedScheme

Functions

func GeneratorWithConfig

func GeneratorWithConfig(config *Config) func(*url.URL, proxy.ContextDialer) (proxy.ContextDialer, error)

GeneratorWithConfig is like NewWithConfig, but is suitable for passing to proxy.RegisterDialerType while maintaining configuration options.

This is to enable registration of an http(s) proxy with options, e.g.:

proxy.RegisterDialerType("https", connectproxy.GeneratorWithConfig(
        &connectproxy.Config{DialTimeout: 5 * time.Minute},
))

func New

func New(u *url.URL, forward proxy.ContextDialer) (proxy.ContextDialer, error)

New returns a proxy.ContextDialer given a URL specification and an underlying proxy.Dialer for it to make network requests. New may be passed to proxy.RegisterDialerType for the schemes "http" and "https". The convenience function RegisterDialerFromURL simplifies this.

func NewWithConfig

func NewWithConfig(u *url.URL, forward proxy.ContextDialer, config *Config) (proxy.ContextDialer, error)

NewWithConfig is like New, but allows control over various options.

Types

type Config

type Config struct {
	// ServerName is the name to use in the TLS connection to (not through)
	// the proxy server if different from the host in the URL.
	// Specifically, this is used in the ServerName field of the
	// *tls.Config used in connections to TLS-speaking proxy servers.
	ServerName string

	// For proxy servers supporting TLS connections (to, not through),
	// skip TLS certificate validation.
	InsecureSkipVerify bool // Passed directly to tls.Dial

	// Header sets the headers in the initial HTTP CONNECT request.  See
	// the documentation for http.Request for more information.
	Header http.Header

	// DialTimeout is an optional timeout for connections through (not to)
	// the proxy server.
	DialTimeout time.Duration
}

Config allows various parameters to be configured. It is used with NewWithConfig. The config passed to NewWithConfig may be changed between requests. If it is, the changes will affect all current and future invocations of the returned proxy.Dialer's Dial method.

type ErrorConnectionTimeout

type ErrorConnectionTimeout error

ErrorConnectionTimeout is returned if the connection through the proxy server was not able to be made before the configured timeout expired.

type ErrorUnsupportedScheme

type ErrorUnsupportedScheme error

ErrorUnsupportedScheme is returned if a scheme other than "http" or "https" is used.