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) ([]net.IPAddr, error)
• type ExchangeAllResult
  • func ExchangeAll(ups []Upstream, req *dns.Msg) (res []ExchangeAllResult, err error)
• type Options
• type Resolver
  • func NewResolver(resolverAddress string, options *Options) (*Resolver, error)
  • func (r *Resolver) LookupIPAddr(ctx context.Context, host string) ([]net.IPAddr, error)
• type TLSPool
  • func (n *TLSPool) Create() (net.Conn, error)
  • func (n *TLSPool) Get() (net.Conn, error)
  • func (n *TLSPool) Put(c net.Conn)
• type Upstream
  • func AddressToUpstream(addr string, opts *Options) (u Upstream, err error)
  • func ExchangeParallel(u []Upstream, req *dns.Msg) (*dns.Msg, Upstream, error)

Constants

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.

const NextProtoDQ = "doq-i02"

NextProtoDQ is the ALPN token for DoQ. During connection establishment, DNS/QUIC support is indicated by selecting the ALPN token "dq" in the crypto handshake. Current draft version: https://datatracker.ietf.org/doc/html/draft-ietf-dprive-dnsoquic-02

Variables

var CipherSuites []uint16

CipherSuites - custom list of TLSv1.2 ciphers nolint

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 nolint

Functions

func LookupParallel

func LookupParallel(ctx context.Context, resolvers []*Resolver, host string) ([]net.IPAddr, error)

LookupParallel starts parallel lookup for host ip with many Resolvers First answer without error will be returned Return nil and error if count of errors equals count of resolvers

Types

type ExchangeAllResult

type ExchangeAllResult struct {
	Resp     *dns.Msg // response
	Upstream Upstream // upstream server
}

ExchangeAllResult - result of ExchangeAll()

func ExchangeAll

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

ExchangeAll receives a response from each of ups.

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

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

	// VerifyServerCertificate used to be set to crypto/tls
	// Config.VerifyPeerCertificate for DNS-over-HTTPS, DNS-over-QUIC,
	// DNS-over-TLS.
	VerifyServerCertificate func(rawCerts [][]byte, verifiedChains [][]*x509.Certificate) 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
}

Options for AddressToUpstream func

type Resolver

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

Resolver is wrapper for resolver and it's address

func NewResolver

func NewResolver(resolverAddress string, options *Options) (*Resolver, error)

NewResolver creates an instance of a Resolver structure with defined net.Resolver and it's address resolverAddress -- is address of net.Resolver The host in the address parameter of Dial func will always be a literal IP address (from documentation) options are the upstream customization options, nil means use default options.

func (*Resolver) LookupIPAddr

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

LookupIPAddr returns result of LookupIPAddr method of Resolver's net.Resolver

type TLSPool

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

TLSPool is a connections pool for the DNS-over-TLS Upstream.

Example:

pool := TLSPool{Address: "tls://1.1.1.1:853"}
netConn, err := pool.Get()
if err != nil {panic(err)}
c := dns.Conn{Conn: netConn}
q := dns.Msg{}
q.SetQuestion("google.com.", dns.TypeA)
log.Println(q)
err = c.WriteMsg(&q)
if err != nil {panic(err)}
r, err := c.ReadMsg()
if err != nil {panic(err)}
log.Println(r)
pool.Put(c.Conn)

func (*TLSPool) Create

func (n *TLSPool) Create() (net.Conn, error)

Create creates a new connection for the pool (but not puts it there)

func (*TLSPool) Get

func (n *TLSPool) Get() (net.Conn, error)

Get gets or creates a new TLS connection

func (*TLSPool) Put

func (n *TLSPool) Put(c net.Conn)

Put returns connection to the pool

type Upstream

type Upstream interface {
	Exchange(m *dns.Msg) (*dns.Msg, error)
	Address() string
}

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 instance:

8.8.8.8:53 or udp://dns.adguard.com for plain DNS;
tcp://8.8.8.8:53 for plain DNS-over-TCP;
tls://1.1.1.1 for DNS-over-TLS;
https://dns.adguard.com/dns-query for DNS-over-HTTPS;
sdns://... for DNS stamp, see https://dnscrypt.info/stamps-specifications.

opts are applied to the u. nil is a valid value for opts.

func ExchangeParallel

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

ExchangeParallel function is called to parallel exchange dns request by many upstreams First answer without error will be returned We will return nil and error if count of errors equals count of upstreams