dns

README

net.Resolver instances with caching, opportunistic encryption, and DNS over TLS/HTTPS

Documentation

Overview

Package dns provides net.Resolver instances implementing caching, opportunistic encryption, and DNS over TLS/HTTPS.

To replace the net.DefaultResolver with a caching DNS over HTTPS instance using the Google Public DNS resolver:

net.DefaultResolver = dns.NewDoHResolver(
	"https://dns.google/dns-query",
	dns.DoHCache())

Index

• Constants
• Variables
• func NewCachingResolver(parent *net.Resolver, options ...CacheOption) *net.Resolver
• func NewDoHResolver(uri string, options ...DoHOption) (*net.Resolver, error)
• func NewDoTResolver(server string, options ...DoTOption) (*net.Resolver, error)
• type CacheOption
  • func MaxCacheEntries(n int) CacheOption
  • func MaxCacheTTL(d time.Duration) CacheOption
  • func MinCacheTTL(d time.Duration) CacheOption
  • func NegativeCache(b bool) CacheOption
• type DialFunc
  • func NewCachingDialer(parent DialFunc, options ...CacheOption) DialFunc
• type DoHOption
  • func DoHAddresses(addresses ...string) DoHOption
  • func DoHCache(options ...CacheOption) DoHOption
  • func DoHTransport(transport *http.Transport) DoHOption
• type DoTOption
  • func DoTAddresses(addresses ...string) DoTOption
  • func DoTCache(options ...CacheOption) DoTOption
  • func DoTConfig(config *tls.Config) DoTOption
  • func DoTDialFunc(f DialFunc) DoTOption

Examples

• DoHAddresses
• DoTAddresses
• NewCachingResolver
• NewDoHResolver
• NewDoTResolver

Constants

const DefaultMaxCacheEntries = 150

Variables

var OpportunisticResolver = &net.Resolver{
	Dial:     opportunisticDial,
	PreferGo: true,
}

OpportunisticResolver opportunistically tries encrypted DNS over TLS using the local resolver.

Functions

func NewCachingResolver

func NewCachingResolver(parent *net.Resolver, options ...CacheOption) *net.Resolver

NewCachingResolver creates a caching net.Resolver that uses parent to resolve names.

Example

resolver := dns.NewCachingResolver(nil)

ips, _ := resolver.LookupIPAddr(context.TODO(), "one.one.one.one")
for _, ip := range ips {
	fmt.Println(ip.String())
}

Output:

1.1.1.1
1.0.0.1
2606:4700:4700::1111
2606:4700:4700::1001

func NewDoHResolver

func NewDoHResolver(uri string, options ...DoHOption) (*net.Resolver, error)

NewDoHResolver creates a DNS over HTTPS resolver. The uri may be an URI Template.

Example

resolver, err := dns.NewDoHResolver("https://dns.google/dns-query{?dns}")
if err != nil {
	log.Fatal(err)
}

ips, _ := resolver.LookupIPAddr(context.TODO(), "dns.google")
for _, ip := range ips {
	fmt.Println(ip.String())
}

Output:

8.8.8.8
8.8.4.4
2001:4860:4860::8888
2001:4860:4860::8844

func NewDoTResolver

func NewDoTResolver(server string, options ...DoTOption) (*net.Resolver, error)

NewDoTResolver creates a DNS over TLS resolver. The server can be an IP address, a host name, or a network address of the form "host:port".

Example

resolver, err := dns.NewDoTResolver("dns.google")
if err != nil {
	log.Fatal(err)
}

ips, _ := resolver.LookupIPAddr(context.TODO(), "dns.google")
for _, ip := range ips {
	fmt.Println(ip.String())
}

Output:

8.8.8.8
8.8.4.4
2001:4860:4860::8888
2001:4860:4860::8844

Types

type CacheOption

type CacheOption interface {
	// contains filtered or unexported methods
}

A CacheOption customizes the resolver cache.

func MaxCacheEntries

func MaxCacheEntries(n int) CacheOption

MaxCacheEntries sets the maximum number of entries to cache. If zero, DefaultMaxCacheEntries is used; negative means no limit.

func MaxCacheTTL

func MaxCacheTTL(d time.Duration) CacheOption

MaxCacheTTL sets the maximum time-to-live for entries in the cache.

func MinCacheTTL

func MinCacheTTL(d time.Duration) CacheOption

MinCacheTTL sets the minimum time-to-live for entries in the cache.

func NegativeCache

func NegativeCache(b bool) CacheOption

NegativeCache sets whether to cache negative responses.

type DialFunc

type DialFunc func(ctx context.Context, network, address string) (net.Conn, error)

DialFunc is a net.Resolver.Dial function.

func NewCachingDialer

func NewCachingDialer(parent DialFunc, options ...CacheOption) DialFunc

NewCachingDialer adds caching to a net.Resolver.Dial function.

type DoHOption

type DoHOption interface {
	// contains filtered or unexported methods
}

A DoHOption customizes the DNS over HTTPS resolver.

func DoHAddresses

func DoHAddresses(addresses ...string) DoHOption

DoHAddresses sets the network addresses of the resolver. These should be IP addresses, or network addresses of the form "IP:port". This avoids having to resolve the resolver's addresses, improving performance and privacy.

Example

dns.NewDoHResolver("https://dns.google/dns-query{?dns}",
	dns.DoHAddresses("8.8.8.8", "8.8.4.4", "2001:4860:4860::8888", "2001:4860:4860::8844"),
	dns.DoHCache())

func DoHCache

func DoHCache(options ...CacheOption) DoHOption

DoHCache adds caching to the resolver, with the given options.

func DoHTransport

func DoHTransport(transport *http.Transport) DoHOption

DoHTransport sets the http.Transport used by the resolver.

type DoTOption

type DoTOption interface {
	// contains filtered or unexported methods
}

A DoTOption customizes the DNS over TLS resolver.

func DoTAddresses

func DoTAddresses(addresses ...string) DoTOption

DoTAddresses sets the network addresses of the resolver. These should be IP addresses, or network addresses of the form "IP:port". This avoids having to resolve the resolver's addresses, improving performance and privacy.

Example

dns.NewDoTResolver("dns.google",
	dns.DoTAddresses("8.8.8.8", "8.8.4.4", "2001:4860:4860::8888", "2001:4860:4860::8844"),
	dns.DoTCache())

func DoTCache

func DoTCache(options ...CacheOption) DoTOption

DoTCache adds caching to the resolver, with the given options.

func DoTConfig

func DoTConfig(config *tls.Config) DoTOption

DoTConfig sets the tls.Config used by the resolver.

func DoTDialFunc

func DoTDialFunc(f DialFunc) DoTOption

DoTDialFunc sets the DialFunc used by the resolver. By default net.Dialer.DialContext is used.