tailscale/feature/dnsresolvecache/dnsresolvecache.go

// Copyright (c) Tailscale Inc & contributors
// SPDX-License-Identifier: BSD-3-Clause

// Package dnsresolvecache persists successful DNS resolutions from
// net/dnscache to disk, one JSON file per hostname, so that a later
// tailscaled boot with misconfigured DNS can still find
// last-known-good IPs for critical hostnames such as the control
// plane. It is intended to eventually replace the DERP-based
// bootstrap DNS in net/dnsfallback.
//
// To keep bogus answers (say, from a captive portal's DNS server) off
// disk, a resolution is not written when it happens. It is instead
// held in memory as pending until a TLS connection to one of the
// resolution's IPs presents a certificate chain that is valid for
// that hostname; only then is the record flushed to disk. The chain
// is checked independently of the connection's own TLS configuration,
// which for the control plane's Noise connection deliberately
// tolerates interception. A captive portal cannot present a valid
// certificate for a hostname it is impersonating, so its answers are
// never persisted. That is also the
// invalidation contract: a hostname's file is only ever written or
// replaced by a newer resolution that was itself verified this way;
// there is no expiry. Verification currently comes from
// [dnscache.TLSDialer] (used by the control plane connection), so
// other hostnames resolve normally but are not persisted.
//
// A file is rewritten only when its contents change, so its
// modification time records when the answer last changed, not when
// it was last confirmed.
//
// This package is linked into tailscaled by default and omitted from
// tsnet. Nothing here is automatic for tsnet-based apps: to use it,
// they must both blank-import this package and configure the cache
// directory themselves by invoking [dnscache.HookSetCacheDir], which
// is otherwise only called by tailscaled at startup.
//
// This package's state is process-global. In tsnet-based apps running
// multiple tsnet.Server instances in one process, only the cache
// directory from the first [dnscache.HookSetCacheDir] call is used;
// later calls are ignored and all servers share the first cache.
package dnsresolvecache

import (
	"bytes"
	"crypto/sha256"
	"encoding/json"
	"net/netip"
	"os"
	"path/filepath"
	"slices"
	"strings"
	"sync"

	"tailscale.com/atomicfile"
	"tailscale.com/feature"
	"tailscale.com/net/dnscache"
	"tailscale.com/types/logger"
	"tailscale.com/util/mak"
	"tailscale.com/util/set"
)

func init() {
	feature.Register("dnsresolvecache")
	dnscache.HookSetCacheDir.Set(setCacheDir)
	dnscache.HookPersistResolution.Set(persist)
	dnscache.HookLookupDiskCache.Set(lookup)
	dnscache.HookHostVerified.Set(hostVerified)
}

var (
	mu          sync.Mutex            // guards the variables below
	cacheDir    string                // empty until the first successful setCacheDir call
	logf        logger.Logf           // non-nil once cacheDir is set
	lastWritten map[string]string     // hostname => digest of last JSON written
	pending     map[string]pendingRec // hostname => resolution awaiting TLS verification
)

// pendingRec is a marshaled resolution awaiting TLS verification of
// one of its IPs before being written to disk.
type pendingRec struct {
	j   []byte // marshaled record
	ips set.Set[netip.Addr]
}

// record is the JSON structure of each persisted per-hostname file.
type record struct {
	Resolver string       // resolver source of the answer: "forward", "cloud", or "fallback"
	A        []netip.Addr `json:",omitempty"` // IPv4 addresses, sorted
	AAAA     []netip.Addr `json:",omitempty"` // IPv6 addresses, sorted
}

// setCacheDir creates dir if needed and enables persistence to it.
// It implements [dnscache.HookSetCacheDir].
//
// Only the first successful call has any effect; later calls are
// no-ops that keep using the first directory. See the package doc
// for what that means for multi-server tsnet apps.
func setCacheDir(dir string, lf logger.Logf) {
	if lf == nil {
		lf = logger.Discard
	}
	mu.Lock()
	defer mu.Unlock()
	if cacheDir != "" {
		if dir != cacheDir {
			lf("dnsresolvecache: cache dir already set to %q; ignoring %q", cacheDir, dir)
		}
		return
	}
	if err := os.MkdirAll(dir, 0700); err != nil {
		lf("dnsresolvecache: %v", err)
		return
	}
	cacheDir = dir
	logf = lf
}

// filePath returns the path of the cache file for host.
// The caller must have validated host and hold mu (for cacheDir).
func filePath(host string) string {
	return filepath.Join(cacheDir, "dns-"+host+".json")
}

// persist records the resolution of host as pending, to be written to
// disk by hostVerified once one of its IPs passes TLS certificate
// verification for host. It implements [dnscache.HookPersistResolution].
func persist(host, resolver string, ips []netip.Addr) {
	host = strings.ToLower(host)
	if !validHostname(host) || len(ips) == 0 {
		return
	}
	rec := record{Resolver: resolver}
	ipSet := make(set.Set[netip.Addr])
	ips = slices.Clone(ips)
	slices.SortFunc(ips, netip.Addr.Compare)
	for _, ip := range slices.Compact(ips) {
		ipSet.Add(ip)
		if ip.Is4() {
			rec.A = append(rec.A, ip)
		} else {
			rec.AAAA = append(rec.AAAA, ip)
		}
	}
	j, err := json.Marshal(rec)
	if err != nil {
		return
	}

	mu.Lock()
	defer mu.Unlock()
	if cacheDir == "" {
		return
	}
	mak.Set(&pending, host, pendingRec{j: j, ips: ipSet})
}

// hostVerified flushes the pending resolution of host to disk if ip
// is one of its addresses. It implements [dnscache.HookHostVerified].
func hostVerified(host string, ip netip.Addr) {
	host = strings.ToLower(host)
	if !validHostname(host) {
		return
	}
	mu.Lock()
	defer mu.Unlock()
	p, ok := pending[host]
	if !ok || !p.ips.Contains(ip.Unmap()) {
		// Nothing pending, or the verified connection didn't use an
		// IP from the pending resolution (e.g. an older resolution's
		// IP, or a bogus record whose IPs never verify). Keep any
		// pending record for a later handshake on a member IP.
		return
	}
	delete(pending, host)
	writeLocked(host, p.j)
}

// writeLocked writes j to host's cache file, unless the contents
// would be unchanged. The caller must hold mu, and cacheDir must be
// non-empty.
func writeLocked(host string, j []byte) {
	digest := sha256.Sum256(j)
	path := filePath(host)
	if last, ok := lastWritten[host]; ok {
		if last == string(digest[:]) {
			return
		}
	} else if old, err := os.ReadFile(path); err == nil && bytes.Equal(old, j) {
		// First write since process start and the file already
		// matches; skip the write to preserve its modtime.
		mak.Set(&lastWritten, host, string(digest[:]))
		return
	}
	if err := atomicfile.WriteFile(path, j, 0600); err != nil {
		logf("dnsresolvecache: writing %v: %v", path, err)
		return
	}
	mak.Set(&lastWritten, host, string(digest[:]))
}

// lookup returns the persisted last-known-good IPs for host, if any.
// It implements [dnscache.HookLookupDiskCache].
func lookup(host string) ([]netip.Addr, bool) {
	host = strings.ToLower(host)
	if !validHostname(host) {
		return nil, false
	}
	mu.Lock()
	defer mu.Unlock()
	if cacheDir == "" {
		return nil, false
	}
	j, err := os.ReadFile(filePath(host))
	if err != nil {
		return nil, false
	}
	var rec record
	if err := json.Unmarshal(j, &rec); err != nil {
		logf("dnsresolvecache: parsing cache for %q: %v", host, err)
		return nil, false
	}
	ips := append(rec.A, rec.AAAA...)
	if len(ips) == 0 {
		return nil, false
	}
	return ips, true
}

// validHostname reports whether host is a DNS hostname that is safe
// to embed in a filename: dot-separated non-empty labels of
// lowercase letters, digits, hyphens, and underscores. It is
// intentionally stricter than DNS itself (which permits nearly
// arbitrary bytes in labels) to keep hostile names out of paths.
func validHostname(host string) bool {
	if len(host) == 0 || len(host) > 253 {
		return false
	}
	for label := range strings.SplitSeq(host, ".") {
		if len(label) == 0 || len(label) > 63 {
			return false
		}
		for i := range len(label) {
			b := label[i]
			if b >= 'a' && b <= 'z' || b >= '0' && b <= '9' || b == '-' || b == '_' {
				continue
			}
			return false
		}
	}
	return true
}