upstream

Documentation

Overview

Package upstream implements DNS clients for all known DNS encryption protocols.

Index

• Constants
• Variables
• func LookupParallel(ctx context.Context, resolvers []Resolver, host string) ([]netip.Addr, error)
• type DialerInitializer
• type ExchangeAllResult
  • func ExchangeAll(ups []Upstream, req *dns.Msg) (res []ExchangeAllResult, err error)
• type HTTPVersion
• type Options
  • func (o *Options) Clone() (clone *Options)
• type QUICTraceFunc
• type Resolver
  • func NewResolver(resolverAddress string, opts *Options) (r Resolver, err error)
• type Upstream
  • func AddressToUpstream(addr string, opts *Options) (u Upstream, err error)
  • func ExchangeParallel(u []Upstream, req *dns.Msg) (reply *dns.Msg, resolved Upstream, err error)

Constants

const (
	// QUICCodeNoError is used when the connection or stream needs to be closed,
	// but there is no error to signal.
	QUICCodeNoError = quic.ApplicationErrorCode(0)

	// QUICCodeInternalError signals that the DoQ implementation encountered
	// an internal error and is incapable of pursuing the transaction or the
	// connection.
	QUICCodeInternalError = quic.ApplicationErrorCode(1)

	// QUICKeepAlivePeriod is the value that we pass to *quic.Config and that
	// controls the period with with keep-alive frames are being sent to the
	// connection. We set it to 20s as it would be in the quic-go@v0.27.1 with
	// KeepAlive field set to true This value is specified in
	// https://pkg.go.dev/github.com/quic-go/quic-go/internal/protocol#MaxKeepAliveInterval.
	//
	// TODO(ameshkov):  Consider making it configurable.
	QUICKeepAlivePeriod = time.Second * 20

	// NextProtoDQ is the ALPN token for DoQ. During the connection establishment,
	// DNS/QUIC support is indicated by selecting the ALPN token "doq" in the
	// crypto handshake.
	//
	// See https://datatracker.ietf.org/doc/rfc9250.
	NextProtoDQ = "doq"
)

const ErrNoUpstreams errors.Error = "no upstream specified"

ErrNoUpstreams is returned from the methods that expect at least a single upstream to work with when no upstreams specified.

Variables

var CipherSuites []uint16

CipherSuites is a custom list of TLSv1.2 ciphers.

var DefaultHTTPVersions = []HTTPVersion{HTTPVersion11, HTTPVersion2}

DefaultHTTPVersions is the list of HTTPVersion that we use by default in the DNS-over-HTTPS client.

var RootCAs *x509.CertPool

RootCAs is the CertPool that must be used by all upstreams. Redefining RootCAs makes sense on iOS to overcome the 15MB memory limit of the NEPacketTunnelProvider.

TODO(ameshkov): remove this and replace with an upstream option.

Functions

func LookupParallel

func LookupParallel(ctx context.Context, resolvers []Resolver, host string) ([]netip.Addr, error)

LookupParallel tries to lookup for ip of host with all resolvers concurrently.

Types

type DialerInitializer

type DialerInitializer func() (handler bootstrap.DialHandler, err error)

DialerInitializer returns the handler that it creates. All the subsequent calls to it, except the first one, will return the same handler so that resolving will be performed only once.

type ExchangeAllResult

type ExchangeAllResult struct {
	// Resp is the response DNS request resolved into.
	Resp *dns.Msg

	// Upstream is the upstream that successfully resolved the request.
	Upstream Upstream
}

ExchangeAllResult is the successful result of ExchangeAll for a single upstream.

func ExchangeAll

func ExchangeAll(ups []Upstream, req *dns.Msg) (res []ExchangeAllResult, err error)

ExchangeAll retunrs the responses from all of u. It returns an error only if all upstreams failed to exchange the request.

type HTTPVersion

type HTTPVersion string

HTTPVersion is an enumeration of the HTTP versions that we support. Values that we use in this enumeration are also used as ALPN values.

const (
	// HTTPVersion11 is HTTP/1.1.
	HTTPVersion11 HTTPVersion = "http/1.1"
	// HTTPVersion2 is HTTP/2.
	HTTPVersion2 HTTPVersion = "h2"
	// HTTPVersion3 is HTTP/3.
	HTTPVersion3 HTTPVersion = "h3"
)

type Options

type Options struct {
	// Bootstrap is a list of DNS servers to be used to resolve
	// DNS-over-HTTPS/DNS-over-TLS hostnames.  Plain DNS, DNSCrypt, or
	// DNS-over-HTTPS/DNS-over-TLS with IP addresses (not hostnames) could be
	// used.
	Bootstrap []string

	// Timeout is the default upstream timeout.  It's also used as a timeout for
	// bootstrap DNS requests.  Zero value disables the timeout.
	Timeout time.Duration

	// List of IP addresses of the upstream DNS server.  If not empty, bootstrap
	// DNS servers won't be used at all.
	ServerIPAddrs []net.IP

	// HTTPVersions is a list of HTTP versions that should be supported by the
	// DNS-over-HTTPS client.  If not set, HTTP/1.1 and HTTP/2 will be used.
	HTTPVersions []HTTPVersion

	// VerifyServerCertificate is used to set the VerifyPeerCertificate property
	// of the *tls.Config for DNS-over-HTTPS, DNS-over-QUIC, and DNS-over-TLS.
	VerifyServerCertificate func(rawCerts [][]byte, verifiedChains [][]*x509.Certificate) error

	// VerifyConnection is used to set the VerifyConnection property
	// of the *tls.Config for DNS-over-HTTPS, DNS-over-QUIC, and DNS-over-TLS.
	VerifyConnection func(state tls.ConnectionState) error

	// VerifyDNSCryptCertificate is the callback the DNSCrypt server certificate
	// will be passed to.  It's called in dnsCrypt.exchangeDNSCrypt.
	// Upstream.Exchange method returns any error caused by it.
	VerifyDNSCryptCertificate func(cert *dnscrypt.Cert) error

	// QUICTracer is an optional callback that allows tracing every QUIC
	// connection and logging every packet that goes through.
	QUICTracer QUICTraceFunc

	// InsecureSkipVerify disables verifying the server's certificate.
	InsecureSkipVerify bool

	// PreferIPv6 tells the bootstrapper to prefer IPv6 addresses for an
	// upstream.
	PreferIPv6 bool
}

Options for AddressToUpstream func. With these options we can configure the upstream properties.

func (*Options) Clone

func (o *Options) Clone() (clone *Options)

Clone copies o to a new struct. Note, that this is not a deep clone.

type QUICTraceFunc

type QUICTraceFunc func(
	ctx context.Context,
	role logging.Perspective,
	connID quic.ConnectionID,
) (tracer logging.ConnectionTracer)

QUICTraceFunc is a function that returns a logging.ConnectionTracer specific for a given role and connection ID.

type Resolver

type Resolver = bootstrap.Resolver

Resolver is an alias for bootstrap.Resolver to avoid the import cycle.

func NewResolver

func NewResolver(resolverAddress string, opts *Options) (r Resolver, err error)

NewResolver creates a Resolver. resolverAddress should be either a plain IP address or empty. If it is empty, the default net.Resolver is used, and sorting the resolved addresses is the caller's responsibility. Otherwise, it creates an Upstream using opts.

TODO(e.burkov): Require resolverAddress not being empty and rename into NewUpstreamResolver.

type Upstream

type Upstream interface {
	// Exchange sends the DNS query req to this upstream and returns the
	// response that has been received or an error if something went wrong.
	Exchange(req *dns.Msg) (*dns.Msg, error)

	// Address returns the address of the upstream DNS resolver.
	Address() string

	// Closer used to close the upstreams properly.  Exchange shouldn't be
	// called after calling Close.
	io.Closer
}

Upstream is an interface for a DNS resolver.

func AddressToUpstream

func AddressToUpstream(addr string, opts *Options) (u Upstream, err error)

AddressToUpstream converts addr to an Upstream using the specified options. addr can be either a URL, or a plain address, either a domain name or an IP.

• udp://5.3.5.3:53 or 5.3.5.3:53 for plain DNS using IP address;
• udp://name.server:53 or name.server:53 for plain DNS using domain name;
• tcp://5.3.5.3:53 for plain DNS-over-TCP using IP address;
• tcp://name.server:53 for plain DNS-over-TCP using domain name;
• tls://5.3.5.3:853 for DNS-over-TLS using IP address;
• tls://name.server:853 for DNS-over-TLS using domain name;
• https://5.3.5.3:443/dns-query for DNS-over-HTTPS using IP address;
• https://name.server:443/dns-query for DNS-over-HTTPS using domain name;
• quic://5.3.5.3:853 for DNS-over-QUIC using IP address;
• quic://name.server:853 for DNS-over-QUIC using domain name;
• h3://dns.google for DNS-over-HTTPS that only works with HTTP/3;
• sdns://... for DNS stamp, see https://dnscrypt.info/stamps-specifications.

If addr doesn't have port specified, the default port of the appropriate protocol will be used.

opts are applied to the u and shouldn't be modified afterwards, nil value is valid.

TODO(e.burkov): Clone opts?

func ExchangeParallel

func ExchangeParallel(u []Upstream, req *dns.Msg) (reply *dns.Msg, resolved Upstream, err error)

ExchangeParallel returns the dirst successful response from one of u. It returns an error if all upstreams failed to exchange the request.