1// Package mtasts implements MTA-STS (SMTP MTA Strict Transport Security, RFC 8461)

2// which allows a domain to specify SMTP TLS requirements.

3//

4// SMTP for message delivery to a remote mail server always starts out unencrypted,

5// in plain text. STARTTLS allows upgrading the connection to TLS, but is optional

6// and by default mail servers will fall back to plain text communication if

7// STARTTLS does not work (which can be sabotaged by DNS manipulation or SMTP

8// connection manipulation). MTA-STS can specify a policy for requiring STARTTLS to

9// be used for message delivery. A TXT DNS record at "_mta-sts.<domain>" specifies

10// the version of the policy, and

11// "https://mta-sts.<domain>/.well-known/mta-sts.txt" serves the policy.

12package mtasts

14import (

15 "context"

16 "errors"

17 "fmt"

18 "io"

19 "log/slog"

20 "net/http"

21 "strings"

22 "time"

24 "github.com/mjl-/adns"

26 "github.com/mjl-/mox/dns"

27 "github.com/mjl-/mox/mlog"

28 "github.com/mjl-/mox/moxio"

29 "github.com/mjl-/mox/stub"

30)

32var (

33 MetricGet stub.HistogramVec = stub.HistogramVecIgnore{}

34 HTTPClientObserve func(ctx context.Context, log *slog.Logger, pkg, method string, statusCode int, err error, start time.Time) = stub.HTTPClientObserveIgnore

35)

37// Pair is an extension key/value pair in a MTA-STS DNS record or policy.

38type Pair struct {

39 Key string

40 Value string

41}

43// Record is an MTA-STS DNS record, served under "_mta-sts.<domain>" as a TXT

44// record.

45//

46// Example:

47//

48// v=STSv1; id=20160831085700Z

49type Record struct {

50 Version string // "STSv1", for "v=". Required.

51 ID string // Record version, for "id=". Required.

52 Extensions []Pair // Optional extensions.

53}

55// String returns a textual version of the MTA-STS record for use as DNS TXT

56// record.

57func (r Record) String() string {

58 b := &strings.Builder{}

59 fmt.Fprint(b, "v="+r.Version)

60 fmt.Fprint(b, "; id="+r.ID)

61 for _, p := range r.Extensions {

62 fmt.Fprint(b, "; "+p.Key+"="+p.Value)

63 }

64 return b.String()

65}

67// Mode indicates how the policy should be interpreted.

68type Mode string

70// ../rfc/8461:655

72const (

73 ModeEnforce Mode = "enforce" // Policy must be followed, i.e. deliveries must fail if a TLS connection cannot be made.

74 ModeTesting Mode = "testing" // In case TLS cannot be negotiated, plain SMTP can be used, but failures must be reported, e.g. with TLSRPT.

75 ModeNone Mode = "none" // In case MTA-STS is not or no longer implemented.

76)

78// STSMX is an allowlisted MX host name/pattern.

79// todo: find a way to name this just STSMX without getting duplicate names for "MX" in the sherpa api.

80type STSMX struct {

81 // "*." wildcard, e.g. if a subdomain matches. A wildcard must match exactly one

82 // label. *.example.com matches mail.example.com, but not example.com, and not

83 // foor.bar.example.com.

84 Wildcard bool

86 Domain dns.Domain

87}

89// LogString returns a loggable string representing the host, with both unicode

90// and ascii version for IDNA domains.

91func (s STSMX) LogString() string {

92 pre := ""

93 if s.Wildcard {

94 pre = "*."

95 }

96 if s.Domain.Unicode == "" {

97 return pre + s.Domain.ASCII

98 }

99 return pre + s.Domain.Unicode + "/" + pre + s.Domain.ASCII

100}

101

102// Policy is an MTA-STS policy as served at "https://mta-sts.<domain>/.well-known/mta-sts.txt".

103type Policy struct {

104 Version string // "STSv1"

105 Mode Mode

106 MX []STSMX

107 MaxAgeSeconds int // How long this policy can be cached. Suggested values are in weeks or more.

108 Extensions []Pair

109}

110

111// String returns a textual representation for serving at the well-known URL.

112func (p Policy) String() string {

113 b := &strings.Builder{}

114 line := func(k, v string) {

115 fmt.Fprint(b, k+": "+v+"\n")

116 }

117 line("version", p.Version)

118 line("mode", string(p.Mode))

119 line("max_age", fmt.Sprintf("%d", p.MaxAgeSeconds))

120 for _, mx := range p.MX {

121 s := mx.Domain.Name()

122 if mx.Wildcard {

123 s = "*." + s

124 }

125 line("mx", s)

126 }

127 return b.String()

128}

129

130// Matches returns whether the hostname matches the mx list in the policy.

131func (p *Policy) Matches(host dns.Domain) bool {

132 // ../rfc/8461:636

133 for _, mx := range p.MX {

134 if mx.Wildcard {

135 v := strings.SplitN(host.ASCII, ".", 2)

136 if len(v) == 2 && v[1] == mx.Domain.ASCII {

137 return true

138 }

139 } else if host == mx.Domain {

140 return true

141 }

142 }

143 return false

144}

145

146// TLSReportFailureReason returns a concise error for known error types, or an

147// empty string. For use in TLSRPT.

148func TLSReportFailureReason(err error) string {

149 // If this is a DNSSEC authentication error, we'll collect it for TLS reporting.

150 // We can also use this reason for STS, not only DANE. ../rfc/8460:580

151 var errCode adns.ErrorCode

152 if errors.As(err, &errCode) && errCode.IsAuthentication() {

153 return fmt.Sprintf("dns-extended-error-%d-%s", errCode, strings.ReplaceAll(errCode.String(), " ", "-"))

154 }

155

156 for _, e := range mtastsErrors {

157 if errors.Is(err, e) {

158 s := strings.TrimPrefix(e.Error(), "mtasts: ")

159 return strings.ReplaceAll(s, " ", "-")

160 }

161 }

162 return ""

163}

164

165var mtastsErrors = []error{

166 ErrNoRecord, ErrMultipleRecords, ErrDNS, ErrRecordSyntax, // Lookup

167 ErrNoPolicy, ErrPolicyFetch, ErrPolicySyntax, // Fetch

168}

169

170// Lookup errors.

171var (

172 ErrNoRecord = errors.New("mtasts: no mta-sts dns txt record") // Domain does not implement MTA-STS. If a cached non-expired policy is available, it should still be used.

173 ErrMultipleRecords = errors.New("mtasts: multiple mta-sts records") // Should be treated as if domain does not implement MTA-STS, unless a cached non-expired policy is available.

174 ErrDNS = errors.New("mtasts: dns lookup") // For temporary DNS errors.

175 ErrRecordSyntax = errors.New("mtasts: record syntax error")

176)

177

178// LookupRecord looks up the MTA-STS TXT DNS record at "_mta-sts.<domain>",

179// following CNAME records, and returns the parsed MTA-STS record and the DNS TXT

180// record.

181func LookupRecord(ctx context.Context, elog *slog.Logger, resolver dns.Resolver, domain dns.Domain) (rrecord *Record, rtxt string, rerr error) {

182 log := mlog.New("mtasts", elog)

183 start := time.Now()

184 defer func() {

185 log.Debugx("mtasts lookup result", rerr,

186 slog.Any("domain", domain),

187 slog.Any("record", rrecord),

188 slog.Duration("duration", time.Since(start)))

189 }()

190

191 // ../rfc/8461:289

192 // ../rfc/8461:351

193 // We lookup the txt record, but must follow CNAME records when the TXT does not

194 // exist. LookupTXT follows CNAMEs.

195 name := "_mta-sts." + domain.ASCII + "."

196 var txts []string

197 txts, _, err := dns.WithPackage(resolver, "mtasts").LookupTXT(ctx, name)

198 if dns.IsNotFound(err) {

199 return nil, "", ErrNoRecord

200 } else if err != nil {

201 return nil, "", fmt.Errorf("%w: %s", ErrDNS, err)

202 }

203

204 var text string

205 var record *Record

206 for _, txt := range txts {

207 r, ismtasts, err := ParseRecord(txt)

208 if !ismtasts {

209 // ../rfc/8461:331 says we should essentially treat a record starting with e.g.

210 // "v=STSv1 ;" (note the space) as a non-STS record too in case of multiple TXT

211 // records. We treat it as an STS record that is invalid, which is possibly more

212 // reasonable.

213 continue

214 }

215 if err != nil {

216 return nil, "", err

217 }

218 if record != nil {

219 return nil, "", ErrMultipleRecords

220 }

221 record = r

222 text = txt

223 }

224 if record == nil {

225 return nil, "", ErrNoRecord

226 }

227 return record, text, nil

228}

229

230// Policy fetch errors.

231var (

232 ErrNoPolicy = errors.New("mtasts: no policy served") // If the name "mta-sts.<domain>" does not exist in DNS or if webserver returns HTTP status 404 "File not found".

233 ErrPolicyFetch = errors.New("mtasts: cannot fetch policy") // E.g. for HTTP request errors.

234 ErrPolicySyntax = errors.New("mtasts: policy syntax error")

235)

236

237// HTTPClient is used by FetchPolicy for HTTP requests.

238var HTTPClient = &http.Client{

239 CheckRedirect: func(req *http.Request, via []*http.Request) error {

240 return fmt.Errorf("redirect not allowed for MTA-STS policies") // ../rfc/8461:549

241 },

242}

243

244// FetchPolicy fetches a new policy for the domain, at

245// https://mta-sts.<domain>/.well-known/mta-sts.txt.

246//

247// FetchPolicy returns the parsed policy and the literal policy text as fetched

248// from the server. If a policy was fetched but could not be parsed, the policyText

249// return value will be set.

250//

251// Policies longer than 64KB result in a syntax error.

252//

253// If an error is returned, callers should back off for 5 minutes until the next

254// attempt.

255func FetchPolicy(ctx context.Context, elog *slog.Logger, domain dns.Domain) (policy *Policy, policyText string, rerr error) {

256 log := mlog.New("mtasts", elog)

257 start := time.Now()

258 defer func() {

259 log.Debugx("mtasts fetch policy result", rerr,

260 slog.Any("domain", domain),

261 slog.Any("policy", policy),

262 slog.String("policytext", policyText),

263 slog.Duration("duration", time.Since(start)))

264 }()

265

266 // Timeout of 1 minute. ../rfc/8461:569

267 ctx, cancel := context.WithTimeout(ctx, time.Minute)

268 defer cancel()

269

270 // TLS requirements are what the Go standard library checks: trusted, non-expired,

271 // hostname verified against DNS-ID supporting wildcard. ../rfc/8461:524

272 url := "https://mta-sts." + domain.Name() + "/.well-known/mta-sts.txt"

273 req, err := http.NewRequestWithContext(ctx, "GET", url, nil)

274 if err != nil {

275 return nil, "", fmt.Errorf("%w: http request: %s", ErrPolicyFetch, err)

276 }

277 // We are not likely to reuse a connection: we cache policies and negative DNS

278 // responses. So don't keep connections open unnecessarily.

279 req.Close = true

280

281 resp, err := HTTPClient.Do(req)

282 if dns.IsNotFound(err) {

283 return nil, "", ErrNoPolicy

284 }

285 if err != nil {

286 // We pass along underlying TLS certificate errors.

287 return nil, "", fmt.Errorf("%w: http get: %w", ErrPolicyFetch, err)

288 }

289 HTTPClientObserve(ctx, log.Logger, "mtasts", req.Method, resp.StatusCode, err, start)

290 defer resp.Body.Close()

291 if resp.StatusCode == http.StatusNotFound {

292 return nil, "", ErrNoPolicy

293 }

294 if resp.StatusCode != http.StatusOK {

295 // ../rfc/8461:548

296 return nil, "", fmt.Errorf("%w: http status %s while status 200 is required", ErrPolicyFetch, resp.Status)

297 }

298

299 // We don't look at Content-Type and charset. It should be ASCII or UTF-8, we'll

300 // just always whatever is sent as UTF-8. ../rfc/8461:367

301

302 // ../rfc/8461:570

303 buf, err := io.ReadAll(&moxio.LimitReader{R: resp.Body, Limit: 64 * 1024})

304 if err != nil {

305 return nil, "", fmt.Errorf("%w: reading policy: %s", ErrPolicySyntax, err)

306 }

307 policyText = string(buf)

308 policy, err = ParsePolicy(policyText)

309 if err != nil {

310 return nil, policyText, fmt.Errorf("parsing policy: %w", err)

311 }

312 return policy, policyText, nil

313}

314

315// Get looks up the MTA-STS DNS record and fetches the policy.

316//

317// Errors can be those returned by LookupRecord and FetchPolicy.

318//

319// If a valid policy cannot be retrieved, a sender must treat the domain as not

320// implementing MTA-STS. If a sender has a non-expired cached policy, that policy

321// would still apply.

322//

323// If a record was retrieved, but a policy could not be retrieved/parsed, the

324// record is still returned.

325//

326// Also see Get in package mtastsdb.

327func Get(ctx context.Context, elog *slog.Logger, resolver dns.Resolver, domain dns.Domain) (record *Record, policy *Policy, policyText string, err error) {

328 log := mlog.New("mtasts", elog)

329 start := time.Now()

330 result := "lookuperror"

331 defer func() {

332 MetricGet.ObserveLabels(float64(time.Since(start))/float64(time.Second), result)

333 log.Debugx("mtasts get result", err,

334 slog.Any("domain", domain),

335 slog.Any("record", record),

336 slog.Any("policy", policy),

337 slog.Duration("duration", time.Since(start)))

338 }()

339