miekg/dns Go Library

The miekg/dns library is a granular, high-performance DNS library supporting both client-side and server-side programming. Key features include:

• Protocol Support: UDP/TCP queries for both IPv4 and IPv6.
• Zone Files: RFC 1035 zone file parsing, including $INCLUDE, $ORIGIN, $TTL, and $GENERATE.
• DNSSEC: Signing, validating, and key generation for DSA, RSA, ECDSA, and Ed25519.
• Security & Encryption: DNS over TLS (DoT), TSIG, and SIG(0).
• Advanced DNS Features: EDNS0, NSID, Cookies, AXFR/IXFR, and DNS name compression.
• Server/Client: Server-side programming mimics the net/http package style.

The dns library uses Go modules and semantic versioning. You can install and build it using the standard go tool.

go get github.com/miekg/dns
go build github.com/miekg/dns

To understand how to use the API, you can:

1. Check the beginning of doc.go in the repository.
2. Use godoc to view documentation: godoc github.com/miekg/dns.
3. Explore the github.com/miekg/exdns repository for concrete example programs.

A ServeMux is a DNS request multiplexer that matches the zone name of incoming requests against registered patterns. It selects the handler for the pattern that most closely matches the zone name.

Key characteristics:

• DNSSEC Aware: For TypeDS queries, it attempts to redirect to the parent zone if registered; otherwise, it falls back to the child zone.
• Concurrency Safe: It is safe for concurrent access from multiple goroutines.
• Matching Logic: It uses CanonicalName for matching and supports a root zone (.) as a wildcard fallback.
• Default Instance: DefaultServeMux is provided for simple use cases where you don't want to manage your own mux instance.

The Transfer struct allows fine-grained control over connection parameters for zone transfers:

• DialTimeout: The timeout for net.Dial. Defaults to 2 seconds.
• ReadTimeout: The timeout for net.Conn.SetReadTimeout. Defaults to 2 seconds.
• WriteTimeout: The timeout for net.Conn.SetWriteTimeout. Defaults to 2 seconds.
• TLS: A *tls.Config. If provided, In will attempt an XFR over TLS using tcp-tls.

To secure zone transfers using TSIG, you can provide authentication in two ways within the Transfer struct:

1. TsigProvider: An implementation of the TsigProvider interface. If set, it replaces TsigSecret for all TSIG operations.
2. TsigSecret: A map of secrets where the key is the zonename in canonical form (lowercase, FQDN) and the value is the base64 encoded secret. Example: map[string]string{"example.com.": "base64-secret"}.

For advanced configuration, instantiate a dns.Server struct directly and call its ListenAndServe or ActivateAndServe methods.

Key configuration fields:

• Addr: Address to listen on (e.g., ":53").
• Net: Network type ("udp", "tcp", "tcp-tls", "udp4", "tcp4", etc.).
• Handler: The Handler to invoke.
• TLSConfig: *tls.Config for TLS connections.
• UDPSize: Default buffer size for UDP messages (defaults to MinMsgSize).
• ReadTimeout / WriteTimeout: Connection timeouts.
• MaxTCPQueries: Maximum number of queries per TCP connection (default 128, or -1 for unlimited).
• TsigSecret: A map of map[string]string where keys are canonical zonenames and values are base64 secrets for TSIG.
• MsgInvalidFunc: A hook called when a message cannot be parsed.
• ReusePort / ReuseAddr: Enable socket options for multiple listeners on the same address.

To plug in a custom TSIG (Transaction Signature) implementation, implement the TsigProvider interface. This allows you to define how signatures are generated and verified for DNS messages.

Methods to implement:

• Generate(msg []byte, t *TSIG) ([]byte, error): Takes the DNS message and the partial TSIG resource record, returning the signature bytes.
• Verify(msg []byte, t *TSIG) error: Takes the DNS message and the TSIG resource record, returning nil if the signature is valid or an error otherwise.

type TsigProvider interface {
	Generate(msg []byte, t *TSIG) ([]byte, error)
	Verify(msg []byte, t *TSIG) error
}