http_dialer

README

HTTP CONNECT tunneling Go Dialer

A net.Dialer drop-in that establishes the TCP connection over an HTTP CONNECT Tunnel.

Why?!

Some enterprises have fairly restrictive networking environments. They typically operate HTTP forward proxies that require user authentication. These proxies usually allow HTTPS (TCP to :443) to pass through the proxy using the CONNECT method. The CONNECT method is basically a HTTP-negotiated "end-to-end" TCP stream... which is exactly what net.Conn is :)

But, really, why?

Because if you want to call gRPC services which are exposed publicly over :443 TLS over an HTTP proxy, you can't.

Also, this allows you to call any TCP service over HTTP CONNECT... if your proxy allows you to ¯\(ツ)/¯

Supported features

• unencrypted connection to proxy (e.g. http://proxy.example.com:3128
• TLS connection to proxy (customizeable) (e.g. https://proxy.example.com)
• customizeable for Proxy-Authenticate, with challenge-response semantics
• out of the box support for Basic auth
• appropriate RemoteAddr remapping

Usage with gRPC

License

go-http-dialer is released under the Apache 2.0 license. See the LICENSE file for details.

Documentation

Overview

Package http_dialer provides HTTP(S) CONNECT tunneling net.Dialer. It allows you to establish arbitrary TCP connections (as long as your proxy allows them) through a HTTP(S) CONNECT point.

Index

• func WithConnectionTimeout(timeout time.Duration) opt
• func WithDialer(dialer *net.Dialer) opt
• func WithProxyAuth(auth ProxyAuthorization) opt
• func WithTls(tlsConfig *tls.Config) opt
• type HttpTunnel
  • func New(proxyUrl *url.URL, opts ...opt) *HttpTunnel
  • func (t *HttpTunnel) Dial(network string, address string) (net.Conn, error)
• type ProxyAuthorization
  • func AuthBasic(username string, password string) ProxyAuthorization

Functions

func WithConnectionTimeout

func WithConnectionTimeout(timeout time.Duration) opt

WithConnectionTimeout customizes the underlying net.Dialer.Timeout.

func WithDialer

func WithDialer(dialer *net.Dialer) opt

WithDialer allows the customization of the underlying net.Dialer used for establishing TCP connections to the proxy.

func WithProxyAuth

func WithProxyAuth(auth ProxyAuthorization) opt

WithProxyAuth allows you to add ProxyAuthorization to calls.

func WithTls

func WithTls(tlsConfig *tls.Config) opt

WithTls sets the tls.Config to be used (e.g. CA certs) when connecting to an HTTP proxy over TLS.

Types

type HttpTunnel

type HttpTunnel struct {
	// contains filtered or unexported fields
}

HttpTunnel represents a configured HTTP Connect Tunnel dialer.

func New

func New(proxyUrl *url.URL, opts ...opt) *HttpTunnel

New constructs an HttpTunnel to be used a net.Dial command. The first parameter is a proxy URL, for example https://foo.example.com:9090 will use foo.example.com as proxy on port 9090 using TLS for connectivity. Optional customization parameters are available, e.g.: WithTls, WithDialer, WithConnectionTimeout

func (*HttpTunnel) Dial

func (t *HttpTunnel) Dial(network string, address string) (net.Conn, error)

Dial is an implementation of net.Dialer, and returns a TCP connection handle to the host that HTTP CONNECT reached.

type ProxyAuthorization

type ProxyAuthorization interface {
	// Type represents what kind of Authorization, e.g. "Bearer", "Token", "Digest".
	Type() string

	// Initial allows you to specify an a-priori "Proxy-Authenticate" response header, attached to first request,
	// so you don't need to wait for an additional challenge. If empty string is returned, "Proxy-Authenticate"
	// header is added.
	InitialResponse() string

	// ChallengeResponse returns the content of the "Proxy-Authenticate" response header, that has been chose as
	// response to "Proxy-Authorization" request header challenge.
	ChallengeResponse(challenge string) string
}

ProxyAuthorization allows for plugging in arbitrary implementations of the "Proxy-Authorization" handler.

func AuthBasic

func AuthBasic(username string, password string) ProxyAuthorization

AuthBasic returns a ProxyAuthorization that implements "Basic" protocol while ignoring realm challanges.