tls

type Config ¶

type Config struct {
	// CA is the certificate authority used to sign generated leaf
	// certificates. It must include at least one certificate and a private key.
	CA stdtls.Certificate

	// ClientConfig configures the upstream TLS client connection. The
	// middleware clones this config for each intercepted connection and sets
	// ServerName and NextProtos from the client's ClientHello. Nil uses the Go
	// TLS defaults with ServerName and NextProtos set from the ClientHello.
	ClientConfig *stdtls.Config

	// SniffBufferSize is the maximum number of bytes inspected from the first
	// client write. Zero uses sniffer.DefaultTLSClientHelloMaxBytes. A smaller
	// value can cause large TLS ClientHello messages to be rejected.
	SniffBufferSize int

	// LeafTTL is the validity period for generated leaf certificates. Zero uses
	// a conservative default. The CA expiration still bounds the leaf
	// certificate expiration.
	LeafTTL time.Duration

	// InterceptionFilter optionally selects which TLS connections are
	// intercepted. The zero value keeps the default behavior and intercepts
	// every interceptable TLS ClientHello. Filtered-out TLS connections are
	// passed through unchanged to the wrapped Network.
	InterceptionFilter InterceptionFilter

	// Spawner optionally starts background copy workers. Nil uses normal
	// goroutines.
	Spawner gonnect.Spawner
}

Config configures a TLS MITM Network.

type InterceptionFilter ¶

type InterceptionFilter struct {
	// Mode selects inclusive or exclusive filtering. The zero value disables
	// filtering and requires Rules to be empty.
	Mode InterceptionFilterMode

	// Rules is the list of match rules.
	Rules []InterceptionRule
}

InterceptionFilter controls which TLS connections Network intercepts.

Rules are ORed. In inclusive mode, a connection is selected for interception when any rule matches. In exclusive mode, a connection is passed through unchanged when any rule matches. A selected TLS ClientHello still must have a visible SNI host and no ECH signal before Network can intercept it.

Empty Rules are valid. They make inclusive mode pass all TLS connections through and make exclusive mode use the default interception behavior.

type InterceptionFilterMode ¶

type InterceptionFilterMode uint8

InterceptionFilterMode selects how InterceptionFilter rules are used.

const (
	// InterceptionFilterOff disables interception filtering. This is the
	// default and keeps the historical behavior: every interceptable TLS
	// ClientHello is intercepted.
	InterceptionFilterOff InterceptionFilterMode = iota

	// InterceptionFilterInclusive intercepts only connections that match at
	// least one rule. Valid TLS connections that do not match are passed
	// through unchanged.
	InterceptionFilterInclusive

	// InterceptionFilterExclusive filters out connections that match at least
	// one rule. Other TLS connections use the default interception behavior.
	InterceptionFilterExclusive
)

type InterceptionFlag ¶

type InterceptionFlag uint8

InterceptionFlag is a tri-state boolean matcher used by InterceptionRule.

The zero value is a wildcard. Required matches when the observed value is true. Forbidden matches when the observed value is false.

const (
	// InterceptionFlagAny accepts both true and false.
	InterceptionFlagAny InterceptionFlag = iota

	// InterceptionFlagRequired requires the observed value to be true.
	InterceptionFlagRequired

	// InterceptionFlagForbidden requires the observed value to be false.
	InterceptionFlagForbidden
)

type InterceptionRule ¶

type InterceptionRule struct {
	Networks []string

	ConnSrcs []string
	ConnDsts []string

	SNIHosts []string
	ALPNs    []string

	SNIAvailable InterceptionFlag
	SNIEncrypted InterceptionFlag

	TLSVersions []uint16
}

InterceptionRule matches one TLS connection.

Empty field groups are wildcards. Non-empty values in one field group are ORed, and all configured field groups must match.

Networks are exact or glob patterns over the dial network string, such as "tcp", "tcp4", or "tcp*".

ConnSrcs match the requested DialTCP local address and the actual local socket address after dialing. Dial has no requested local address. ConnDsts match the requested remote address and the actual remote socket address after dialing. Source and destination patterns use the same syntax as gonnect.FilterFromString: host, host:port, IP, IP:port, CIDR, and host wildcards are supported.

SNIHosts match the visible SNI host_name. Matching is case-insensitive. ALPNs match any ALPN protocol name. Matching is case-sensitive. Both fields use whole-value glob patterns where * matches any byte sequence, ? matches one byte, and character classes use path.Match syntax.

SNIAvailable and SNIEncrypted match the visible ClientHello flags. SNIEncrypted only reports that the encrypted_client_hello extension is present. Network cannot decrypt ECH or intercept a connection that has ECH.

TLSVersions match protocol versions offered by the ClientHello. If the supported_versions extension is present, it is used. Otherwise the ClientHello legacy_version field is used.

type Network ¶

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

Network is a gonnect.Network middleware that MITMs outgoing TLS TCP dials.

Dial and DialTCP establish the real upstream TCP connection immediately, so dial errors are still returned by those calls. The returned connection is a local TCP-like pipe. A background worker sniffs the first client bytes. If they are interceptable TLS, the worker terminates client TLS with a generated certificate and then opens upstream TLS through the already-dialed connection. If they are non-TLS, the worker relays bytes without modification. Server-first TCP protocols are out of scope; callers should use connection deadlines or another timeout policy and close the connection on timeout.

Lifecycle calls are delegated when the wrapped Network implements the matching optional interface. If it does not, Close, Up, Down, SubscribeCloser, and SubscribeUpDown are no-ops, and IsUp reports true. IsNative always reports false because this middleware changes TCP behavior.

func NewNetwork(
	network gonnect.Network,
	ca stdtls.Certificate,
	clientConfig *stdtls.Config,
) (*Network, error)

func NewNetworkWithConfig(
	network gonnect.Network,
	config Config,
) (*Network, error)

func (n *Network) Close() error

func (n *Network) Dial(
	ctx context.Context,
	network, address string,
) (net.Conn, error)

func (n *Network) DialTCP(
	ctx context.Context,
	network, laddr, raddr string,
) (gonnect.TCPConn, error)

func (n *Network) DialUDP(
	ctx context.Context,
	network, laddr, raddr string,
) (gonnect.UDPConn, error)

func (n *Network) Down() error

func (n *Network) GetNetwork() gonnect.Network

func (n *Network) GetWrapped() any

func (n *Network) InterfaceAddrs() ([]net.Addr, error)

func (n *Network) InterfaceMulticastAddrs() ([]net.Addr, error)

func (n *Network) Interfaces() ([]gonnect.NetworkInterface, error)

func (n *Network) InterfacesByIndex(
	index int,
) ([]gonnect.NetworkInterface, error)

func (n *Network) InterfacesByName(
	name string,
) ([]gonnect.NetworkInterface, error)

func (n *Network) IsNative() bool

func (n *Network) IsUp() (bool, error)

func (n *Network) Listen(
	ctx context.Context,
	network, address string,
) (net.Listener, error)

func (n *Network) ListenMulticastUDP(
	ctx context.Context,
	network, address string,
	opts gonnect.MulticastOptions,
) (gonnect.MulticastPacketConn, error)

func (n *Network) ListenPacket(
	ctx context.Context,
	network, address string,
) (gonnect.PacketConn, error)

func (n *Network) ListenPacketConfig(
	ctx context.Context,
	lc *gonnect.ListenConfig,
	network, address string,
) (gonnect.PacketConn, error)

func (n *Network) ListenTCP(
	ctx context.Context,
	network, laddr string,
) (gonnect.TCPListener, error)

func (n *Network) ListenUDP(
	ctx context.Context,
	network, laddr string,
) (gonnect.UDPConn, error)

func (n *Network) ListenUDPConfig(
	ctx context.Context,
	lc *gonnect.ListenConfig,
	network, laddr string,
) (gonnect.UDPConn, error)

func (n *Network) LookupAddr(
	ctx context.Context,
	addr string,
) ([]string, error)

func (n *Network) LookupCNAME(
	ctx context.Context,
	host string,
) (string, error)

func (n *Network) LookupHost(
	ctx context.Context,
	host string,
) ([]string, error)

func (n *Network) LookupIP(
	ctx context.Context,
	network, address string,
) ([]net.IP, error)

func (n *Network) LookupIPAddr(
	ctx context.Context,
	host string,
) ([]net.IPAddr, error)

func (n *Network) LookupMX(
	ctx context.Context,
	name string,
) ([]*net.MX, error)

func (n *Network) LookupNS(
	ctx context.Context,
	name string,
) ([]*net.NS, error)

func (n *Network) LookupNetIP(
	ctx context.Context,
	network, host string,
) ([]netip.Addr, error)

func (n *Network) LookupPort(
	ctx context.Context,
	network, service string,
) (int, error)

func (n *Network) LookupSRV(
	ctx context.Context,
	service, proto, name string,
) (string, []*net.SRV, error)

func (n *Network) LookupTXT(
	ctx context.Context,
	name string,
) ([]string, error)

func (n *Network) PacketDial(
	ctx context.Context,
	network, address string,
) (gonnect.PacketConn, error)

func (n *Network) SubscribeCloser(c io.Closer) (func(), error)

func (n *Network) SubscribeUpDown(u gonnect.UpDown) (func(), error)

func (n *Network) Up() error

type Terminator ¶

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

Terminator is a gonnect.Network middleware that terminates outgoing TLS over TCP and sends plaintext TCP to the wrapped Network.

Dial and DialTCP return a local TCP-like pipe immediately. A background worker waits for the first client bytes, requires a valid TLS ClientHello with visible SNI and no ECH signal, selects the upstream plaintext destination, dials it through the wrapped Network, completes client-facing TLS with a generated certificate, and then copies decrypted bytes to the upstream TCP connection.

Non-TLS TCP is rejected. TLS without visible SNI, TLS with ECH, malformed TLS, and TLS over the sniff limit are rejected. No rejected stream is passed through or dialed upstream. Operations other than TCP Dial and DialTCP return ErrTerminatorUnsupported and do not call the wrapped Network.

The Dial or DialTCP context is checked before the local pipe is returned. After Dial or DialTCP returns, canceling that context does not stop the background worker. Close the returned connection to abort sniffing, hidden upstream dials, and bridge work.

Lifecycle calls are delegated when the wrapped Network implements the matching optional interface. If it does not, Close, Up, Down, SubscribeCloser, and SubscribeUpDown are no-ops, and IsUp reports true. IsNative always reports false because this middleware changes TCP behavior.

func NewTerminator(
	network gonnect.Network,
	ca stdtls.Certificate,
) (*Terminator, error)

func NewTerminatorWithConfig(
	network gonnect.Network,
	config TerminatorConfig,
) (*Terminator, error)

func (n *Terminator) Close() error

func (n *Terminator) Dial(
	ctx context.Context,
	network, address string,
) (net.Conn, error)

func (n *Terminator) DialTCP(
	ctx context.Context,
	network, laddr, raddr string,
) (gonnect.TCPConn, error)

func (n *Terminator) DialUDP(
	ctx context.Context,
	network, laddr, raddr string,
) (gonnect.UDPConn, error)

func (n *Terminator) Down() error

func (n *Terminator) GetNetwork() gonnect.Network

func (n *Terminator) GetWrapped() any

func (n *Terminator) InterfaceAddrs() ([]net.Addr, error)

func (n *Terminator) InterfaceMulticastAddrs() ([]net.Addr, error)

func (n *Terminator) Interfaces() ([]gonnect.NetworkInterface, error)

func (n *Terminator) InterfacesByIndex(
	index int,
) ([]gonnect.NetworkInterface, error)

func (n *Terminator) InterfacesByName(
	name string,
) ([]gonnect.NetworkInterface, error)

func (n *Terminator) IsNative() bool

func (n *Terminator) IsUp() (bool, error)

func (n *Terminator) Listen(
	ctx context.Context,
	network, address string,
) (net.Listener, error)

func (n *Terminator) ListenMulticastUDP(
	ctx context.Context,
	network, address string,
	opts gonnect.MulticastOptions,
) (gonnect.MulticastPacketConn, error)

func (n *Terminator) ListenPacket(
	ctx context.Context,
	network, address string,
) (gonnect.PacketConn, error)

func (n *Terminator) ListenPacketConfig(
	ctx context.Context,
	lc *gonnect.ListenConfig,
	network, address string,
) (gonnect.PacketConn, error)

func (n *Terminator) ListenTCP(
	ctx context.Context,
	network, laddr string,
) (gonnect.TCPListener, error)

func (n *Terminator) ListenUDP(
	ctx context.Context,
	network, laddr string,
) (gonnect.UDPConn, error)

func (n *Terminator) ListenUDPConfig(
	ctx context.Context,
	lc *gonnect.ListenConfig,
	network, laddr string,
) (gonnect.UDPConn, error)

func (n *Terminator) LookupAddr(
	ctx context.Context,
	addr string,
) ([]string, error)

func (n *Terminator) LookupCNAME(
	ctx context.Context,
	host string,
) (string, error)

func (n *Terminator) LookupHost(
	ctx context.Context,
	host string,
) ([]string, error)

func (n *Terminator) LookupIP(
	ctx context.Context,
	network, address string,
) ([]net.IP, error)

func (n *Terminator) LookupIPAddr(
	ctx context.Context,
	host string,
) ([]net.IPAddr, error)

func (n *Terminator) LookupMX(
	ctx context.Context,
	name string,
) ([]*net.MX, error)

func (n *Terminator) LookupNS(
	ctx context.Context,
	name string,
) ([]*net.NS, error)

func (n *Terminator) LookupNetIP(
	ctx context.Context,
	network, host string,
) ([]netip.Addr, error)

func (n *Terminator) LookupPort(
	ctx context.Context,
	network, service string,
) (int, error)

func (n *Terminator) LookupSRV(
	ctx context.Context,
	service, proto, name string,
) (string, []*net.SRV, error)

func (n *Terminator) LookupTXT(
	ctx context.Context,
	name string,
) ([]string, error)

func (n *Terminator) PacketDial(
	ctx context.Context,
	network, address string,
) (gonnect.PacketConn, error)

func (n *Terminator) SubscribeCloser(c io.Closer) (func(), error)

func (n *Terminator) SubscribeUpDown(u gonnect.UpDown) (func(), error)

func (n *Terminator) Up() error

type TerminatorConfig ¶

type TerminatorConfig struct {
	// CA is the certificate authority used to sign generated leaf
	// certificates. It must include at least one certificate and a private key.
	CA stdtls.Certificate

	// SniffBufferSize is the maximum number of bytes inspected from the first
	// client write. Zero uses sniffer.DefaultTLSClientHelloMaxBytes. A smaller
	// value can cause large TLS ClientHello messages to be rejected.
	SniffBufferSize int

	// LeafTTL is the validity period for generated leaf certificates. Zero uses
	// a conservative default. The CA expiration still bounds the leaf
	// certificate expiration.
	LeafTTL time.Duration

	// DestinationRemaps optionally replace the upstream plaintext TCP
	// destination. Rules are checked in order, and the first match wins. When
	// no rule matches, Terminator uses the original dial destination unless
	// UseSNIHostname is true.
	DestinationRemaps []TerminatorDestinationRemap

	// UseSNIHostname makes the default upstream destination use the SNI host
	// with the original destination port. It is ignored when a destination
	// remap matches. The zero value keeps the original destination.
	UseSNIHostname bool

	// NextProtos is the list of ALPN protocols the client-facing TLS server
	// can select. Empty disables ALPN selection. Remap rules still match the
	// ALPN protocols offered by the client.
	NextProtos []string

	// Spawner optionally starts background copy workers. Nil uses normal
	// goroutines.
	Spawner gonnect.Spawner
}

TerminatorConfig configures a TLS terminating Network.

type TerminatorDestinationRemap ¶

type TerminatorDestinationRemap struct {
	// OriginalDsts match the original Dial or DialTCP remote address.
	OriginalDsts []string

	// SNIHosts match the visible SNI host_name.
	SNIHosts []string

	// ALPNs match any ALPN protocol offered by the client.
	ALPNs []string

	// Dst is the plaintext TCP destination used when this rule matches. It
	// must use host:port syntax.
	Dst string
}

TerminatorDestinationRemap maps intercepted TLS connections to another plaintext TCP destination.

Empty match fields are wildcards. Values in one field are ORed. Different fields are ANDed. OriginalDsts use the address syntax accepted by gonnect.FilterFromString. SNIHosts and ALPNs use whole-value glob patterns, where * matches any byte sequence and ? matches one byte. SNIHosts match case-insensitively. ALPNs match the client offer, not the selected ALPN.