dns

Documentation

Overview

Package dns provides utilities to interact with the Domain Name System (DNS).

The Domain Name System (DNS) is responsible for mapping domain names to IP addresses. Because domain resolution gatekeeps connections and is predominantly done in plaintext, it is commonly used for network-level filtering.

Transports

The main concept in this library is that of a Resolver, which allows code to query the DNS. Different implementations are provided to perform DNS resolution over different transports:

• DNS-over-UDP: the standard mechanism of querying resolvers. Communication is done in plaintext, using port 53.
• DNS-over-TCP: alternative to UDP that allows for more reliable delivery and larger responses, but requires establishing a connection. Communication is done in plaintext, using port 53.
• DNS-over-TLS (DoT): uses the TCP protocol, but over a connection encrypted with TLS. Is uses port 853, which makes it very easy to block using the port number, as no other protocol is assigned to that port.
• DNS-over-HTTPS (DoH): uses HTTP exchanges for querying the resolver and communicates over a connection encrypted with TLS. It uses port 443. That makes the DoH traffic undistinguishable from web traffic, making it harder to block.

Establishing Stream Connections

Typically you will want to use custom DNS resolution to establish connections to a destination. NewStreamDialer will create a transport.StreamDialer that uses the given resolver to resolve host names and the given dialer to establish connections. The dialer efficiently performs resolutions and connection attempts in parallel, as per the Happy Eyeballs v2 algorithm.

Index

• Variables
• func NewQuestion(domain string, qtype dnsmessage.Type) (*dnsmessage.Question, error)
• func NewStreamDialer(resolver Resolver, dialer transport.StreamDialer) (transport.StreamDialer, error)
• type FuncResolver
  • func (f FuncResolver) Query(ctx context.Context, q dnsmessage.Question) (*dnsmessage.Message, error)
• type Resolver
  • func NewHTTPSResolver(sd transport.StreamDialer, resolverAddr string, url string) Resolver
  • func NewTCPResolver(sd transport.StreamDialer, resolverAddr string) Resolver
  • func NewTLSResolver(sd transport.StreamDialer, resolverAddr string, resolverName string) Resolver
  • func NewUDPResolver(pd transport.PacketDialer, resolverAddr string) Resolver

Variables

var (
	ErrBadRequest  = errors.New("request input is invalid")
	ErrDial        = errors.New("dial DNS resolver failed")
	ErrSend        = errors.New("send DNS message failed")
	ErrReceive     = errors.New("receive DNS message failed")
	ErrBadResponse = errors.New("response message is invalid")
)

Functions

func NewQuestion

func NewQuestion(domain string, qtype dnsmessage.Type) (*dnsmessage.Question, error)

NewQuestion is a convenience function to create a dnsmessage.Question. The input domain is interpreted as fully-qualified. If the end "." is missing, it's added.

func NewStreamDialer

func NewStreamDialer(resolver Resolver, dialer transport.StreamDialer) (transport.StreamDialer, error)

NewStreamDialer creates a transport.StreamDialer that uses Happy Eyeballs v2 to establish a connection. It uses resolver to map host names to IP addresses, and the given dialer to attempt connections.

Types

type FuncResolver

type FuncResolver func(ctx context.Context, q dnsmessage.Question) (*dnsmessage.Message, error)

FuncResolver is a Resolver that uses the given function to query DNS.

func (FuncResolver) Query

func (f FuncResolver) Query(ctx context.Context, q dnsmessage.Question) (*dnsmessage.Message, error)

Query implements the Resolver interface.

type Resolver

type Resolver interface {
	Query(ctx context.Context, q dnsmessage.Question) (*dnsmessage.Message, error)
}

Resolver can query the DNS with a question, and obtain a DNS message as response. This abstraction helps hide the underlying transport protocol.

func NewHTTPSResolver

func NewHTTPSResolver(sd transport.StreamDialer, resolverAddr string, url string) Resolver

NewHTTPSResolver creates a Resolver that implements the DNS-over-HTTPS protocol, using a transport.StreamDialer to connect to the resolverAddr, and the url as the DoH template URI. It uses an internal HTTP client that reuses connections when possible.

func NewTCPResolver

func NewTCPResolver(sd transport.StreamDialer, resolverAddr string) Resolver

NewTCPResolver creates a Resolver that implements the DNS-over-TCP protocol, using a transport.StreamDialer for transport. It creates a new connection to the resolver for every request.

func NewTLSResolver

func NewTLSResolver(sd transport.StreamDialer, resolverAddr string, resolverName string) Resolver

NewTLSResolver creates a Resolver that implements the DNS-over-TLS protocol, using a transport.StreamDialer to connect to the resolverAddr, and the resolverName as the TLS server name. It creates a new connection to the resolver for every request.

func NewUDPResolver

func NewUDPResolver(pd transport.PacketDialer, resolverAddr string) Resolver

NewUDPResolver creates a Resolver that implements the DNS-over-UDP protocol, using a transport.PacketDialer for transport. It uses a different port for every request.