tlsmasq

README

TLS Masquerade

A server which masquerades as a different TLS server. For example, the server may masquerade as a microsoft.com server, depsite not actually being run by Microsoft.

Clients properly configured with the masquerade protocol can connect and speak to the true server, but passive observers will see connections which look like connections to microsoft.com. Similarly, active probes will find that the server behaves like a microsoft.com server.

Documentation

Overview

Package tlsmasq implements a server which masquerades as a different TLS server. For example, the server may masquerade as a microsoft.com server, depsite not actually being run by Microsoft.

Clients properly configured with the masquerade protocol can connect and speak to the true server, but passive observers will see connections which look like connections to microsoft.com. Similarly, active probes will find that the server behaves like a microsoft.com server.

Index

• func Dial(network, address string, cfg DialerConfig) (net.Conn, error)
• func DialTimeout(network, address string, cfg DialerConfig, timeout time.Duration) (net.Conn, error)
• func Listen(network, address string, cfg ListenerConfig) (net.Listener, error)
• func WrapListener(l net.Listener, cfg ListenerConfig) net.Listener
• type Conn
  • func Client(conn net.Conn, cfg DialerConfig) Conn
  • func Server(conn net.Conn, cfg ListenerConfig) Conn
• type Dialer
  • func WrapDialer(d Dialer, cfg DialerConfig) Dialer
• type DialerConfig
• type ListenerConfig

Functions

func Dial

func Dial(network, address string, cfg DialerConfig) (net.Conn, error)

Dial a tlsmasq listener. This will result in a TLS connection with the peer.

func DialTimeout

func DialTimeout(network, address string, cfg DialerConfig, timeout time.Duration) (net.Conn, error)

DialTimeout acts like Dial but takes a timeout.

func Listen

func Listen(network, address string, cfg ListenerConfig) (net.Listener, error)

Listen for tlsmasq dialers. Accepted connections will be TLS connections.

func WrapListener

func WrapListener(l net.Listener, cfg ListenerConfig) net.Listener

WrapListener wraps the input listener with one which speaks the tlsmasq protocol. Accepted connections will be TLS connections.

Types

type Conn

type Conn interface {
	net.Conn

	// Handshake executes the tlsmasq handshake protocol, if it has not yet been performed. Note
	// that, per the protocol, the connection will proxy all data until the completion signal. Thus,
	// if this connection comes from an active probe, this handshake function may not return until
	// the probe closes the connection on its end. As a result, this function should be treated as
	// one which may be long-running or never return.
	Handshake() error
}

Conn is a network connection between two peers speaking the tlsmasq protocol.

Connections returned by listeners and dialers in this package will implement this interface. However, most users of this package can ignore this type.

func Client

func Client(conn net.Conn, cfg DialerConfig) Conn

Client initializes a client-side connection.

func Server

func Server(conn net.Conn, cfg ListenerConfig) Conn

Server initializes a server-side connection.

type Dialer

type Dialer interface {
	Dial(network, address string) (net.Conn, error)
	DialContext(ctx context.Context, network, address string) (net.Conn, error)
}

Dialer is the interface implemented by network dialers.

func WrapDialer

func WrapDialer(d Dialer, cfg DialerConfig) Dialer

WrapDialer wraps the input dialer with a network dialer which will perform the tlsmasq protocol. Dialing will result in TLS connections with peers.

type DialerConfig

type DialerConfig struct {
	// ProxiedHandshakeConfig specifies configuration for the proxied handshake.
	ProxiedHandshakeConfig ptlshs.DialerConfig

	// TLSConfig specifies configuration for the hijacked, true TLS connection with the server. This
	// hijacked connection will use whatever combination of cipher suite and version was negotiated
	// during the proxied handshake. Thus it is important to set fields like CipherSuites and
	// MinVersion to ensure that the security parameters of the hijacked connection are acceptable.
	TLSConfig *tls.Config
}

DialerConfig specifies configuration for dialing.

type ListenerConfig

type ListenerConfig struct {
	// ProxiedHandshakeConfig specifies configuration for the proxied handshake.
	ProxiedHandshakeConfig ptlshs.ListenerConfig

	// TLSConfig specifies configuration for hijacked, true TLS connections with the clients. These
	// hijacked connections will use whatever combination of cipher suite and version was negotiated
	// during the proxied handshake. Thus it is important to set fields like CipherSuites and
	// MinVersion to ensure that the security parameters of the hijacked connections are acceptable.
	TLSConfig *tls.Config
}

ListenerConfig specifies configuration for listening.