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
- 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
Constants ¶
This section is empty.
Variables ¶
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 ¶ added in v0.0.14
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.
Source Files