1// Package dns helps parse internationalized domain names (IDNA), canonicalize
2// names and provides a strict and metrics-keeping logging DNS resolver.
3package dns
4
5import (
6 "errors"
7 "fmt"
8 "strings"
9
10 "golang.org/x/net/idna"
11
12 "github.com/mjl-/adns"
13)
14
15// Pedantic enables stricter parsing.
16var Pedantic bool
17
18var (
19 errTrailingDot = errors.New("dns name has trailing dot")
20 errUnderscore = errors.New("domain name with underscore")
21 errIDNA = errors.New("idna")
22)
23
24// Domain is a domain name, with one or more labels, with at least an ASCII
25// representation, and for IDNA non-ASCII domains a unicode representation.
26// The ASCII string must be used for DNS lookups. The strings do not have a
27// trailing dot. When using with StrictResolver, add the trailing dot.
28type Domain struct {
29 // A non-unicode domain, e.g. with A-labels (xn--...) or NR-LDH (non-reserved
30 // letters/digits/hyphens) labels. Always in lower case. No trailing dot.
31 ASCII string
32
33 // Name as U-labels. Empty if this is an ASCII-only domain. No trailing dot.
34 Unicode string
35}
36
37// Name returns the unicode name if set, otherwise the ASCII name.
38func (d Domain) Name() string {
39 if d.Unicode != "" {
40 return d.Unicode
41 }
42 return d.ASCII
43}
44
45// XName is like Name, but only returns a unicode name when utf8 is true.
46func (d Domain) XName(utf8 bool) string {
47 if utf8 && d.Unicode != "" {
48 return d.Unicode
49 }
50 return d.ASCII
51}
52
53// ASCIIExtra returns the ASCII version of the domain name if smtputf8 is true and
54// this is a unicode domain name. Otherwise it returns an empty string.
55//
56// This function is used to add the punycode name in a comment to SMTP message
57// headers, e.g. Received and Authentication-Results.
58func (d Domain) ASCIIExtra(smtputf8 bool) string {
59 if smtputf8 && d.Unicode != "" {
60 return d.ASCII
61 }
62 return ""
63}
64
65// Strings returns a human-readable string.
66// For IDNA names, the string contains both the unicode and ASCII name.
67func (d Domain) String() string {
68 return d.LogString()
69}
70
71// LogString returns a domain for logging.
72// For IDNA names, the string is the slash-separated Unicode and ASCII name.
73// For ASCII-only domain names, just the ASCII string is returned.
74func (d Domain) LogString() string {
75 if d.Unicode == "" {
76 return d.ASCII
77 }
78 return d.Unicode + "/" + d.ASCII
79}
80
81// IsZero returns if this is an empty Domain.
82func (d Domain) IsZero() bool {
83 return d == Domain{}
84}
85
86// ParseDomain parses a domain name that can consist of ASCII-only labels or U
87// labels (unicode).
88// Names are IDN-canonicalized and lower-cased.
89// Characters in unicode can be replaced by equivalents. E.g. "Ⓡ" to "r". This
90// means you should only compare parsed domain names, never strings directly.
91func ParseDomain(s string) (Domain, error) {
92 if strings.HasSuffix(s, ".") {
93 return Domain{}, errTrailingDot
94 }
95
96 ascii, err := idna.Lookup.ToASCII(s)
97 if err != nil {
98 return Domain{}, fmt.Errorf("%w: to ascii: %v", errIDNA, err)
99 }
100 unicode, err := idna.Lookup.ToUnicode(s)
101 if err != nil {
102 return Domain{}, fmt.Errorf("%w: to unicode: %w", errIDNA, err)
103 }
104 // todo: should we cause errors for unicode domains that were not in
105 // canonical form? we are now accepting all kinds of obscure spellings
106 // for even a basic ASCII domain name.
107 // Also see https://daniel.haxx.se/blog/2022/12/14/idn-is-crazy/
108 if ascii == unicode {
109 return Domain{ascii, ""}, nil
110 }
111 return Domain{ascii, unicode}, nil
112}
113
114// ParseDomainLax parses a domain like ParseDomain, but allows labels with
115// underscores if the entire domain name is ASCII-only non-IDNA and Pedantic mode
116// is not enabled. Used for interoperability, e.g. domains may specify MX
117// targets with underscores.
118func ParseDomainLax(s string) (Domain, error) {
119 if Pedantic || !strings.Contains(s, "_") {
120 return ParseDomain(s)
121 }
122
123 // If there is any non-ASCII, this is certainly not an A-label-only domain.
124 s = strings.ToLower(s)
125 for _, c := range s {
126 if c >= 0x80 {
127 return Domain{}, fmt.Errorf("%w: underscore and non-ascii not allowed", errUnderscore)
128 }
129 }
130
131 // Try parsing with underscores replaced with allowed ASCII character.
132 // If that's not valid, the version with underscore isn't either.
133 repl := strings.ReplaceAll(s, "_", "a")
134 d, err := ParseDomain(repl)
135 if err != nil {
136 return Domain{}, fmt.Errorf("%w: %v", errUnderscore, err)
137 }
138 // If we found an IDNA domain, we're not going to allow it.
139 if d.Unicode != "" {
140 return Domain{}, fmt.Errorf("%w: idna domain with underscores not allowed", errUnderscore)
141 }
142 // Just to be safe, ensure no unexpected conversions happened.
143 if d.ASCII != repl {
144 return Domain{}, fmt.Errorf("%w: underscores and non-canonical names not allowed", errUnderscore)
145 }
146 return Domain{ASCII: s}, nil
147}
148
149// IsNotFound returns whether an error is an adns.DNSError with IsNotFound set.
150// IsNotFound means the requested type does not exist for the given domain (a
151// nodata or nxdomain response). It doesn't not necessarily mean no other types for
152// that name exist.
153//
154// A DNS server can respond to a lookup with an error "nxdomain" to indicate a
155// name does not exist (at all), or with a success status with an empty list.
156// The adns resolver (just like the Go resolver) returns an IsNotFound error for
157// both cases, there is no need to explicitly check for zero entries.
158func IsNotFound(err error) bool {
159 var dnsErr *adns.DNSError
160 return err != nil && errors.As(err, &dnsErr) && dnsErr.IsNotFound
161}
162