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 "net"

9 "strings"

10

11 "golang.org/x/net/idna"

12

13 "github.com/mjl-/adns"

14)

15

16// Pedantic enables stricter parsing.

17var Pedantic bool

18

19var (

20 errTrailingDot = errors.New("dns name has trailing dot")

21 errUnderscore = errors.New("domain name with underscore")

22 errIDNA = errors.New("idna")

23)

24

25// Domain is a domain name, with one or more labels, with at least an ASCII

26// representation, and for IDNA non-ASCII domains a unicode representation.

27// The ASCII string must be used for DNS lookups. The strings do not have a

28// trailing dot. When using with StrictResolver, add the trailing dot.

29type Domain struct {

30 // A non-unicode domain, e.g. with A-labels (xn--...) or NR-LDH (non-reserved

31 // letters/digits/hyphens) labels. Always in lower case. No trailing dot.

32 ASCII string

33

34 // Name as U-labels, in Unicode NFC. Empty if this is an ASCII-only domain. No

35 // trailing dot.

36 Unicode string

37}

38

39// Name returns the unicode name if set, otherwise the ASCII name.

40func (d Domain) Name() string {

41 if d.Unicode != "" {

42 return d.Unicode

43 }

44 return d.ASCII

45}

46

47// XName is like Name, but only returns a unicode name when utf8 is true.

48func (d Domain) XName(utf8 bool) string {

49 if utf8 && d.Unicode != "" {

50 return d.Unicode

51 }

52 return d.ASCII

53}

54

55// ASCIIExtra returns the ASCII version of the domain name if smtputf8 is true and

56// this is a unicode domain name. Otherwise it returns an empty string.

57//

58// This function is used to add the punycode name in a comment to SMTP message

59// headers, e.g. Received and Authentication-Results.

60func (d Domain) ASCIIExtra(smtputf8 bool) string {

61 if smtputf8 && d.Unicode != "" {

62 return d.ASCII

63 }

64 return ""

65}

66

67// Strings returns a human-readable string.

68// For IDNA names, the string contains both the unicode and ASCII name.

69func (d Domain) String() string {

70 return d.LogString()

71}

72

73// LogString returns a domain for logging.

74// For IDNA names, the string is the slash-separated Unicode and ASCII name.

75// For ASCII-only domain names, just the ASCII string is returned.

76func (d Domain) LogString() string {

77 if d.Unicode == "" {

78 return d.ASCII

79 }

80 return d.Unicode + "/" + d.ASCII

81}

82

83// IsZero returns if this is an empty Domain.

84func (d Domain) IsZero() bool {

85 return d == Domain{}

86}

87

88// ParseDomain parses a domain name that can consist of ASCII-only labels or U

89// labels (unicode).

90// Names are IDN-canonicalized and lower-cased.

91// Characters in unicode can be replaced by equivalents. E.g. "Ⓡ" to "r". This

92// means you should only compare parsed domain names, never unparsed strings

93// directly.

94func ParseDomain(s string) (Domain, error) {

95 if strings.HasSuffix(s, ".") {

96 return Domain{}, errTrailingDot

97 }

98

99 ascii, err := idna.Lookup.ToASCII(s)

100 if err != nil {

101 return Domain{}, fmt.Errorf("%w: to ascii: %v", errIDNA, err)

102 }

103 unicode, err := idna.Lookup.ToUnicode(s)

104 if err != nil {

105 return Domain{}, fmt.Errorf("%w: to unicode: %w", errIDNA, err)

106 }

107 // todo: should we cause errors for unicode domains that were not in

108 // canonical form? we are now accepting all kinds of obscure spellings

109 // for even a basic ASCII domain name.

110 // Also see https://daniel.haxx.se/blog/2022/12/14/idn-is-crazy/

111 if ascii == unicode {

112 return Domain{ascii, ""}, nil

113 }

114 return Domain{ascii, unicode}, nil

115}

116

117// ParseDomainLax parses a domain like ParseDomain, but allows labels with

118// underscores if the entire domain name is ASCII-only non-IDNA and Pedantic mode

119// is not enabled. Used for interoperability, e.g. domains may specify MX

120// targets with underscores.

121func ParseDomainLax(s string) (Domain, error) {

122 if Pedantic || !strings.Contains(s, "_") {

123 return ParseDomain(s)

124 }

125

126 // If there is any non-ASCII, this is certainly not an A-label-only domain.

127 s = strings.ToLower(s)

128 for _, c := range s {

129 if c >= 0x80 {

130 return Domain{}, fmt.Errorf("%w: underscore and non-ascii not allowed", errUnderscore)

131 }

132 }

133

134 // Try parsing with underscores replaced with allowed ASCII character.

135 // If that's not valid, the version with underscore isn't either.

136 repl := strings.ReplaceAll(s, "_", "a")

137 d, err := ParseDomain(repl)

138 if err != nil {

139 return Domain{}, fmt.Errorf("%w: %v", errUnderscore, err)

140 }

141 // If we found an IDNA domain, we're not going to allow it.

142 if d.Unicode != "" {

143 return Domain{}, fmt.Errorf("%w: idna domain with underscores not allowed", errUnderscore)

144 }

145 // Just to be safe, ensure no unexpected conversions happened.

146 if d.ASCII != repl {

147 return Domain{}, fmt.Errorf("%w: underscores and non-canonical names not allowed", errUnderscore)

148 }

149 return Domain{ASCII: s}, nil

150}

151

152// IsNotFound returns whether an error is an adns.DNSError or net.DNSError with

153// IsNotFound set.

154//

155// IsNotFound means the requested type does not exist for the given domain (a

156// nodata or nxdomain response). It doesn't not necessarily mean no other types for

157// that name exist.

158//

159// A DNS server can respond to a lookup with an error "nxdomain" to indicate a

160// name does not exist (at all), or with a success status with an empty list.

161// The adns resolver (just like the Go resolver) returns an IsNotFound error for

162// both cases, there is no need to explicitly check for zero entries.

163func IsNotFound(err error) bool {

164 var adnsErr *adns.DNSError

165 var dnsErr *net.DNSError

166 return err != nil && (errors.As(err, &adnsErr) && adnsErr.IsNotFound || errors.As(err, &dnsErr) && dnsErr.IsNotFound)

167}

168