1package tlsrpt

3import (

4 "compress/gzip"

5 "context"

6 "crypto/tls"

7 "crypto/x509"

8 "encoding/json"

9 "errors"

10 "fmt"

11 "io"

12 "net"

13 "os"

14 "reflect"

15 "sort"

16 "strings"

17 "time"

19 "golang.org/x/exp/slices"

20 "golang.org/x/exp/slog"

22 "github.com/mjl-/adns"

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

25 "github.com/mjl-/mox/message"

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

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

28)

30var ErrNoReport = errors.New("no tlsrpt report found")

32// ../rfc/8460:628

34// Report is a TLSRPT report.

35type Report struct {

36 OrganizationName string

37 DateRange TLSRPTDateRange

38 ContactInfo string

39 ReportID string

40 Policies []Result

41}

43// ReportJSON is a TLS report with field names as used in the specification. These field names are inconvenient to use in JavaScript, so after parsing a ReportJSON is turned into a Report.

44type ReportJSON struct {

45 OrganizationName string `json:"organization-name"`

46 DateRange TLSRPTDateRangeJSON `json:"date-range"`

47 ContactInfo string `json:"contact-info"` // Email address.

48 ReportID string `json:"report-id"`

49 Policies []ResultJSON `json:"policies"`

50}

52func convertSlice[T interface{ Convert() S }, S any](l []T) []S {

53 if l == nil {

54 return nil

55 }

56 r := make([]S, len(l))

57 for i, e := range l {

58 r[i] = e.Convert()

59 }

60 return r

61}

63func (v Report) Convert() ReportJSON {

64 return ReportJSON{v.OrganizationName, v.DateRange.Convert(), v.ContactInfo, v.ReportID, convertSlice[Result, ResultJSON](v.Policies)}

65}

67func (v ReportJSON) Convert() Report {

68 return Report{v.OrganizationName, v.DateRange.Convert(), v.ContactInfo, v.ReportID, convertSlice[ResultJSON, Result](v.Policies)}

69}

71// Merge combines the counts and failure details of results into the report.

72// Policies are merged if identical and added otherwise. Same for failure details

73// within a result.

74func (r *Report) Merge(results ...Result) {

75Merge:

76 for _, nr := range results {

77 for i, p := range r.Policies {

78 if !p.Policy.equal(nr.Policy) {

79 continue

80 }

82 r.Policies[i].Add(nr.Summary.TotalSuccessfulSessionCount, nr.Summary.TotalFailureSessionCount, nr.FailureDetails...)

83 continue Merge

84 }

86 r.Policies = append(r.Policies, nr)

87 }

88}

90// Add increases the success/failure counts of a result, and adds any failure

91// details.

92func (r *Result) Add(success, failure int64, fds ...FailureDetails) {

93 r.Summary.TotalSuccessfulSessionCount += success

94 r.Summary.TotalFailureSessionCount += failure

96 // In smtpclient we can compensate with a negative success, after failed read after

97 // successful handshake. Sanity check that we never get negative counts.

98 if r.Summary.TotalSuccessfulSessionCount < 0 {

99 r.Summary.TotalSuccessfulSessionCount = 0

100 }

101 if r.Summary.TotalFailureSessionCount < 0 {

102 r.Summary.TotalFailureSessionCount = 0

103 }

104

105Merge:

106 for _, nfd := range fds {

107 for i, fd := range r.FailureDetails {

108 if !fd.equalKey(nfd) {

109 continue

110 }

111

112 fd.FailedSessionCount += nfd.FailedSessionCount

113 r.FailureDetails[i] = fd

114 continue Merge

115 }

116 r.FailureDetails = append(r.FailureDetails, nfd)

117 }

118}

119

120// Add is a convenience function for merging making a Result and merging it into

121// the report.

122func (r *Report) Add(policy ResultPolicy, success, failure int64, fds ...FailureDetails) {

123 r.Merge(Result{policy, Summary{success, failure}, fds})

124}

125

126// TLSAPolicy returns a policy for DANE.

127func TLSAPolicy(records []adns.TLSA, tlsaBaseDomain dns.Domain) ResultPolicy {

128 // The policy domain is the TLSA base domain. ../rfc/8460:251

129

130 l := make([]string, len(records))

131 for i, r := range records {

132 l[i] = r.Record()

133 }

134 sort.Strings(l) // For consistent equals.

135 return ResultPolicy{

136 Type: TLSA,

137 String: l,

138 Domain: tlsaBaseDomain.ASCII,

139 MXHost: []string{},

140 }

141}

142

143func MakeResult(policyType PolicyType, domain dns.Domain, fds ...FailureDetails) Result {

144 if fds == nil {

145 fds = []FailureDetails{}

146 }

147 return Result{

148 Policy: ResultPolicy{Type: policyType, Domain: domain.ASCII, String: []string{}, MXHost: []string{}},

149 FailureDetails: fds,

150 }

151}

152

153// note: with TLSRPT prefix to prevent clash in sherpadoc types.

154type TLSRPTDateRange struct {

155 Start time.Time

156 End time.Time

157}

158

159func (v TLSRPTDateRange) Convert() TLSRPTDateRangeJSON {

160 return TLSRPTDateRangeJSON(v)

161}

162

163type TLSRPTDateRangeJSON struct {

164 Start time.Time `json:"start-datetime"`

165 End time.Time `json:"end-datetime"`

166}

167

168func (v TLSRPTDateRangeJSON) Convert() TLSRPTDateRange {

169 return TLSRPTDateRange(v)

170}

171

172// UnmarshalJSON is defined on the date range, not the individual time.Time fields

173// because it is easier to keep the unmodified time.Time fields stored in the

174// database.

175func (dr *TLSRPTDateRangeJSON) UnmarshalJSON(buf []byte) error {

176 var v struct {

177 Start xtime `json:"start-datetime"`

178 End xtime `json:"end-datetime"`

179 }

180 if err := json.Unmarshal(buf, &v); err != nil {

181 return err

182 }

183 dr.Start = time.Time(v.Start)

184 dr.End = time.Time(v.End)

185 return nil

186}

187

188// xtime and its UnmarshalJSON exists to work around a specific invalid date-time encoding seen in the wild.

189type xtime time.Time

190

191func (x *xtime) UnmarshalJSON(buf []byte) error {

192 var t time.Time

193 err := t.UnmarshalJSON(buf)

194 if err == nil {

195 *x = xtime(t)

196 return nil

197 }

198

199 // Microsoft is sending reports with invalid start-datetime/end-datetime (missing

200 // timezone, ../rfc/8460:682 ../rfc/3339:415). We compensate.

201 var s string

202 if err := json.Unmarshal(buf, &s); err != nil {

203 return err

204 }

205 t, err = time.Parse("2006-01-02T15:04:05", s)

206 if err != nil {

207 return err

208 }

209 *x = xtime(t)

210 return nil

211}

212

213type Result struct {

214 Policy ResultPolicy

215 Summary Summary

216 FailureDetails []FailureDetails

217}

218

219func (r Result) Convert() ResultJSON {

220 return ResultJSON{ResultPolicyJSON(r.Policy), SummaryJSON(r.Summary), convertSlice[FailureDetails, FailureDetailsJSON](r.FailureDetails)}

221}

222

223type ResultJSON struct {

224 Policy ResultPolicyJSON `json:"policy"`

225 Summary SummaryJSON `json:"summary"`

226 FailureDetails []FailureDetailsJSON `json:"failure-details"`

227}

228

229func (r ResultJSON) Convert() Result {

230 return Result{ResultPolicy(r.Policy), Summary(r.Summary), convertSlice[FailureDetailsJSON, FailureDetails](r.FailureDetails)}

231}

232

233// todo spec: ../rfc/8460:437 says policy is a string, with rules for turning dane records into a single string. perhaps a remnant of an earlier version (for mtasts a single string would have made more sense). i doubt the intention is to always have a single element in policy-string (though the field name is singular).

234

235type ResultPolicy struct {

236 Type PolicyType

237 String []string

238 Domain string

239 MXHost []string

240}

241

242type ResultPolicyJSON struct {

243 Type PolicyType `json:"policy-type"`

244 String []string `json:"policy-string"`

245 Domain string `json:"policy-domain"`

246 MXHost []string `json:"mx-host"` // Example in RFC has errata, it originally was a single string. ../rfc/8460-eid6241 ../rfc/8460:1779

247}

248

249// PolicyType indicates the policy success/failure results are for.

250type PolicyType string

251

252const (

253 // For DANE, against a mail host (not recipient domain).

254 TLSA PolicyType = "tlsa"

255

256 // For MTA-STS, against a recipient domain (not a mail host).

257 STS PolicyType = "sts"

258

259 // Recipient domain did not have MTA-STS policy, or mail host (TSLA base domain)

260 // did not have DANE TLSA records.

261 NoPolicyFound PolicyType = "no-policy-found"

262 // todo spec: ../rfc/8460:440 ../rfc/8460:697 suggest to replace with values like "no-sts-found" and "no-tlsa-found" to make it explicit which policy isn't found. also easier to implement, because you don't have to handle leaving out an sts no-policy-found result for a mail host when a tlsa policy is present.

263)

264

265func (rp ResultPolicy) equal(orp ResultPolicy) bool {

266 return rp.Type == orp.Type && slices.Equal(rp.String, orp.String) && rp.Domain == orp.Domain && slices.Equal(rp.MXHost, orp.MXHost)

267}

268

269type Summary struct {

270 TotalSuccessfulSessionCount int64

271 TotalFailureSessionCount int64

272}

273

274type SummaryJSON struct {

275 TotalSuccessfulSessionCount int64 `json:"total-successful-session-count"`

276 TotalFailureSessionCount int64 `json:"total-failure-session-count"`

277}

278

279// ResultType represents a TLS error.

280type ResultType string

281

282// ../rfc/8460:1377

283// https://www.iana.org/assignments/starttls-validation-result-types/starttls-validation-result-types.xhtml

284

285const (

286 ResultSTARTTLSNotSupported ResultType = "starttls-not-supported"

287 ResultCertificateHostMismatch ResultType = "certificate-host-mismatch"

288 ResultCertificateExpired ResultType = "certificate-expired"

289 ResultTLSAInvalid ResultType = "tlsa-invalid"

290 ResultDNSSECInvalid ResultType = "dnssec-invalid"

291 ResultDANERequired ResultType = "dane-required"

292 ResultCertificateNotTrusted ResultType = "certificate-not-trusted"

293 ResultSTSPolicyInvalid ResultType = "sts-policy-invalid"

294 ResultSTSWebPKIInvalid ResultType = "sts-webpki-invalid"

295 ResultValidationFailure ResultType = "validation-failure" // Other error.

296 ResultSTSPolicyFetch ResultType = "sts-policy-fetch-error"

297)

298

299// todo spec: ../rfc/8460:719 more of these fields should be optional. some sts failure details, like failed policy fetches, won't have an ip or mx, the failure happens earlier in the delivery process.

300

301type FailureDetails struct {

302 ResultType ResultType

303 SendingMTAIP string

304 ReceivingMXHostname string

305 ReceivingMXHelo string

306 ReceivingIP string

307 FailedSessionCount int64

308 AdditionalInformation string

309 FailureReasonCode string

310}

311