filtering

Documentation

Overview

Package filtering allows to implement self-censorship.

The top-level struct is the TProxy. It implements model's UnderlyingNetworkLibrary interface. Therefore, you can use TProxy to implement filtering and blocking of TCP, TLS, QUIC, DNS, HTTP.

We also expose proxies that implement filtering policies for DNS, TLS, and HTTP.

The typical usage of this package's functionality is to load a censoring policy into TProxyConfig and then to create and start a TProxy instance using NewTProxy.

Index

• Constants
• type DNSAction
• type DNSListener
• type DNSProxy
  • func (p *DNSProxy) Start(address string) (DNSListener, error)
• type DNSTransport
• type HTTPAction
• type HTTPProxy
  • func (p *HTTPProxy) ServeHTTP(w http.ResponseWriter, r *http.Request)
  • func (p *HTTPProxy) Start(address string) (net.Listener, error)
• type TLSAction
• type TLSProxy
  • func (p *TLSProxy) Start(address string) (net.Listener, error)
• type TProxy
  • func NewTProxy(config *TProxyConfig, logger model.InfoLogger) (*TProxy, error)
  • func (p *TProxy) Close() error
  • func (p *TProxy) ListenUDP(network string, laddr *net.UDPAddr) (model.UDPLikeConn, error)
  • func (p *TProxy) LookupHost(ctx context.Context, domain string) ([]string, error)
  • func (p *TProxy) NewSimpleDialer(timeout time.Duration) model.SimpleDialer
• type TProxyConfig
  • func NewTProxyConfig(file string) (*TProxyConfig, error)
  • func (c *TProxyConfig) CanonicalizeDNS()
• type TProxyPolicy

Constants

const (
	// DNSActionPass passes the traffic to the upstream server.
	DNSActionPass = DNSAction("pass")

	// DNSActionNXDOMAIN replies with NXDOMAIN.
	DNSActionNXDOMAIN = DNSAction("nxdomain")

	// DNSActionRefused replies with Refused.
	DNSActionRefused = DNSAction("refused")

	// DNSActionLocalHost replies with `127.0.0.1` and `::1`.
	DNSActionLocalHost = DNSAction("localhost")

	// DNSActionNoAnswer returns an empty reply.
	DNSActionNoAnswer = DNSAction("no-answer")

	// DNSActionTimeout never replies to the query.
	DNSActionTimeout = DNSAction("timeout")

	// DNSActionCache causes the proxy to check the cache. If there
	// are entries, they are returned. Otherwise, NXDOMAIN is returned.
	DNSActionCache = DNSAction("cache")
)

const (
	// HTTPActionPass passes the traffic to the destination.
	HTTPActionPass = HTTPAction("pass")

	// HTTPActionReset resets the connection.
	HTTPActionReset = HTTPAction("reset")

	// HTTPActionTimeout causes the connection to timeout.
	HTTPActionTimeout = HTTPAction("timeout")

	// HTTPActionEOF causes the connection to EOF.
	HTTPActionEOF = HTTPAction("eof")

	// HTTPAction451 causes the proxy to return a 451 error.
	HTTPAction451 = HTTPAction("451")
)

const (
	// TLSActionPass passes the traffic to the destination.
	TLSActionPass = TLSAction("pass")

	// TLSActionReset resets the connection.
	TLSActionReset = TLSAction("reset")

	// TLSActionTimeout causes the connection to timeout.
	TLSActionTimeout = TLSAction("timeout")

	// TLSActionEOF closes the connection.
	TLSActionEOF = TLSAction("eof")

	// TLSActionAlertInternalError sends an internal error
	// alert message to the TLS client.
	TLSActionAlertInternalError = TLSAction("internal-error")

	// TLSActionAlertUnrecognizedName tells the client that
	// it's handshaking with an unknown SNI.
	TLSActionAlertUnrecognizedName = TLSAction("alert-unrecognized-name")
)

const (
	// TProxyPolicyTCPDropSYN simulates a SYN segment being dropped.
	TProxyPolicyTCPDropSYN = TProxyPolicy("tcp-drop-syn")

	// TProxyPolicyTCPRejectSYN simulates a closed TCP port.
	TProxyPolicyTCPRejectSYN = TProxyPolicy("tcp-reject-syn")

	// TProxyPolicyDropData drops outgoing data of an
	// established TCP/UDP connection.
	TProxyPolicyDropData = TProxyPolicy("drop-data")

	// TProxyPolicyHijackDNS causes the dialer to replace the target
	// address with the address of the local censored resolver.
	TProxyPolicyHijackDNS = TProxyPolicy("hijack-dns")

	// TProxyPolicyHijackTLS causes the dialer to replace the target
	// address with the address of the local censored TLS server.
	TProxyPolicyHijackTLS = TProxyPolicy("hijack-tls")

	// TProxyPolicyHijackHTTP causes the dialer to replace the target
	// address with the address of the local censored HTTP server.
	TProxyPolicyHijackHTTP = TProxyPolicy("hijack-http")
)

Types

type DNSAction

type DNSAction string

DNSAction is a DNS filtering action that this proxy should take.

type DNSListener

type DNSListener interface {
	io.Closer
	LocalAddr() net.Addr
}

DNSListener is the interface returned by DNSProxy.Start

type DNSProxy

type DNSProxy struct {
	// Cache is the DNS cache. Note that the keys of the map
	// must be FQDNs (i.e., including the final `.`).
	Cache map[string][]string

	// OnQuery is the MANDATORY hook called whenever we
	// receive a query for the given domain.
	OnQuery func(domain string) DNSAction

	// Upstream is the OPTIONAL upstream transport.
	Upstream DNSTransport
	// contains filtered or unexported fields
}

DNSProxy is a DNS proxy that routes traffic to an upstream resolver and may implement filtering policies.

func (*DNSProxy) Start

func (p *DNSProxy) Start(address string) (DNSListener, error)

Start starts the proxy.

type DNSTransport

type DNSTransport interface {
	RoundTrip(ctx context.Context, query []byte) ([]byte, error)
	CloseIdleConnections()
}

DNSTransport is the type we expect from an upstream DNS transport.

type HTTPAction

type HTTPAction string

HTTPAction is an HTTP filtering action that this proxy should take.

type HTTPProxy

type HTTPProxy struct {
	// OnIncomingHost is the MANDATORY hook called whenever we have
	// successfully received an HTTP request.
	OnIncomingHost func(host string) HTTPAction
}

HTTPProxy is a proxy that routes traffic depending on the host header and may implement filtering policies.

func (*HTTPProxy) ServeHTTP

func (p *HTTPProxy) ServeHTTP(w http.ResponseWriter, r *http.Request)

ServeHTTP serves HTTP requests

func (*HTTPProxy) Start

func (p *HTTPProxy) Start(address string) (net.Listener, error)

Start starts the proxy.

type TLSAction

type TLSAction string

TLSAction is a TLS filtering action that this proxy should take.

type TLSProxy

type TLSProxy struct {
	// OnIncomingSNI is the MANDATORY hook called whenever we have
	// successfully received a ClientHello message.
	OnIncomingSNI func(sni string) TLSAction
}

TLSProxy is a TLS proxy that routes the traffic depending on the SNI value and may implement filtering policies.

func (*TLSProxy) Start

func (p *TLSProxy) Start(address string) (net.Listener, error)

Start starts the proxy.

type TProxy

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

TProxy is a model.UnderlyingNetworkLibrary that implements self censorship.

func NewTProxy

func NewTProxy(config *TProxyConfig, logger model.InfoLogger) (*TProxy, error)

NewTProxy creates a new TProxy instance.

func (*TProxy) Close

func (p *TProxy) Close() error

Close closes the resources used by a TProxy.

func (*TProxy) ListenUDP

func (p *TProxy) ListenUDP(network string, laddr *net.UDPAddr) (model.UDPLikeConn, error)

ListenUDP implements netxlite.TProxy.ListenUDP.

func (*TProxy) LookupHost

func (p *TProxy) LookupHost(ctx context.Context, domain string) ([]string, error)

LookupHost implements netxlite.TProxy.LookupHost.

func (*TProxy) NewSimpleDialer

func (p *TProxy) NewSimpleDialer(timeout time.Duration) model.SimpleDialer

NewSimpleDialer implements netxlite.TProxy.NewTProxyDialer.

type TProxyConfig

type TProxyConfig struct {
	// DNSCache is the cached used when the domains policy is "cache". Note
	// that the map MUST contain FQDNs. That is, you need to append
	// a final dot to the domain name (e.g., `example.com.`).  If you
	// use the NewTProxyConfig factory, you don't need to worry about this
	// issue, because the factory will canonicalize non-canonical
	// entries. Otherwise, you can explicitly call the CanonicalizeDNS
	// method _before_ using the TProxy.
	DNSCache map[string][]string

	// Domains contains rules for filtering the lookup of domains. Note
	// that the map MUST contain FQDNs. That is, you need to append
	// a final dot to the domain name (e.g., `example.com.`).  If you
	// use the NewTProxyConfig factory, you don't need to worry about this
	// issue, because the factory will canonicalize non-canonical
	// entries. Otherwise, you can explicitly call the CanonicalizeDNS
	// method _before_ using the TProxy.
	Domains map[string]DNSAction

	// Endpoints contains rules for filtering TCP/UDP endpoints.
	Endpoints map[string]TProxyPolicy

	// SNIs contains rules for filtering TLS SNIs.
	SNIs map[string]TLSAction

	// Hosts contains rules for filtering by HTTP host.
	Hosts map[string]HTTPAction
}

TProxyConfig contains configuration for TProxy.

func NewTProxyConfig

func NewTProxyConfig(file string) (*TProxyConfig, error)

NewTProxyConfig reads the TProxyConfig from the given file.

func (*TProxyConfig) CanonicalizeDNS

func (c *TProxyConfig) CanonicalizeDNS()

CanonicalizeDNS ensures all DNS names are canonicalized. This method modifies the TProxyConfig structure in place.

type TProxyPolicy

type TProxyPolicy string

TProxyPolicy is a policy for TPRoxy.