1// Package dmarc implements DMARC (Domain-based Message Authentication,
2// Reporting, and Conformance; RFC 7489) verification.
4// DMARC is a mechanism for verifying ("authenticating") the address in the "From"
5// message header, since users will look at that header to identify the sender of a
6// message. DMARC compares the "From"-(sub)domain against the SPF and/or
7// DKIM-validated domains, based on the DMARC policy that a domain has published in
8// DNS as TXT record under "_dmarc.<domain>". A DMARC policy can also ask for
9// feedback about evaluations by other email servers, for monitoring/debugging
10// problems with email delivery.
20 "github.com/mjl-/mox/dkim"
21 "github.com/mjl-/mox/dns"
22 "github.com/mjl-/mox/mlog"
23 "github.com/mjl-/mox/publicsuffix"
24 "github.com/mjl-/mox/spf"
25 "github.com/mjl-/mox/stub"
27 "golang.org/x/exp/slog"
31 MetricVerify stub.HistogramVec = stub.HistogramVecIgnore{}
39 ErrNoRecord = errors.New("dmarc: no dmarc dns record")
40 ErrMultipleRecords = errors.New("dmarc: multiple dmarc dns records") // Must also be treated as if domain does not implement DMARC.
41 ErrDNS = errors.New("dmarc: dns lookup")
42 ErrSyntax = errors.New("dmarc: malformed dmarc dns record")
45// Status is the result of DMARC policy evaluation, for use in an Authentication-Results header.
51 StatusNone Status = "none" // No DMARC TXT DNS record found.
52 StatusPass Status = "pass" // SPF and/or DKIM pass with identifier alignment.
53 StatusFail Status = "fail" // Either both SPF and DKIM failed or identifier did not align with a pass.
54 StatusTemperror Status = "temperror" // Typically a DNS lookup. A later attempt may results in a conclusion.
55 StatusPermerror Status = "permerror" // Typically a malformed DMARC DNS record.
58// Result is a DMARC policy evaluation.
60 // Whether to reject the message based on policies. If false, the message should
61 // not necessarily be accepted: other checks such as reputation-based and
62 // content-based analysis may lead to reject the message.
64 // Result of DMARC validation. A message can fail validation, but still
65 // not be rejected, e.g. if the policy is "none".
69 // Domain with the DMARC DNS record. May be the organizational domain instead of
70 // the domain in the From-header.
72 // Parsed DMARC record.
74 // Whether DMARC DNS response was DNSSEC-signed, regardless of whether SPF/DKIM records were DNSSEC-signed.
76 // Details about possible error condition, e.g. when parsing the DMARC record failed.
80// Lookup looks up the DMARC TXT record at "_dmarc.<domain>" for the domain in the
81// "From"-header of a message.
83// If no DMARC record is found for the "From"-domain, another lookup is done at
84// the organizational domain of the domain (if different). The organizational
85// domain is determined using the public suffix list. E.g. for
86// "sub.example.com", the organizational domain is "example.com". The returned
87// domain is the domain with the DMARC record.
89// rauthentic indicates if the DNS results were DNSSEC-verified.
90func Lookup(ctx context.Context, elog *slog.Logger, resolver dns.Resolver, msgFrom dns.Domain) (status Status, domain dns.Domain, record *Record, txt string, rauthentic bool, rerr error) {
91 log := mlog.New("dmarc", elog)
94 log.Debugx("dmarc lookup result", rerr,
95 slog.Any("fromdomain", msgFrom),
96 slog.Any("status", status),
97 slog.Any("domain", domain),
98 slog.Any("record", record),
99 slog.Duration("duration", time.Since(start)))
104 status, record, txt, authentic, err := lookupRecord(ctx, resolver, domain)
105 if status != StatusNone {
106 return status, domain, record, txt, authentic, err
110 domain = publicsuffix.Lookup(ctx, log.Logger, msgFrom)
111 if domain == msgFrom {
112 return StatusNone, domain, nil, txt, authentic, err
116 status, record, txt, xauth, err = lookupRecord(ctx, resolver, domain)
117 authentic = authentic && xauth
119 return status, domain, record, txt, authentic, err
122func lookupRecord(ctx context.Context, resolver dns.Resolver, domain dns.Domain) (Status, *Record, string, bool, error) {
123 name := "_dmarc." + domain.ASCII + "."
124 txts, result, err := dns.WithPackage(resolver, "dmarc").LookupTXT(ctx, name)
125 if err != nil && !dns.IsNotFound(err) {
126 return StatusTemperror, nil, "", result.Authentic, fmt.Errorf("%w: %s", ErrDNS, err)
130 var rerr error = ErrNoRecord
131 for _, txt := range txts {
132 r, isdmarc, err := ParseRecord(txt)
136 } else if err != nil {
137 return StatusPermerror, nil, text, result.Authentic, fmt.Errorf("%w: %s", ErrSyntax, err)
141 return StatusNone, nil, "", result.Authentic, ErrMultipleRecords
147 return StatusNone, record, text, result.Authentic, rerr
150func lookupReportsRecord(ctx context.Context, resolver dns.Resolver, dmarcDomain, extDestDomain dns.Domain) (Status, []*Record, []string, bool, error) {
152 name := dmarcDomain.ASCII + "._report._dmarc." + extDestDomain.ASCII + "."
153 txts, result, err := dns.WithPackage(resolver, "dmarc").LookupTXT(ctx, name)
154 if err != nil && !dns.IsNotFound(err) {
155 return StatusTemperror, nil, nil, result.Authentic, fmt.Errorf("%w: %s", ErrDNS, err)
157 var records []*Record
159 var rerr error = ErrNoRecord
160 for _, txt := range txts {
161 r, isdmarc, err := ParseRecordNoRequired(txt)
162 // Examples in the RFC use "v=DMARC1", even though it isn't a valid DMARC record.
163 // Accept the specific example.
165 if !isdmarc && txt == "v=DMARC1" {
167 r, isdmarc, err = &xr, true, nil
173 texts = append(texts, txt)
174 records = append(records, r)
176 return StatusPermerror, records, texts, result.Authentic, fmt.Errorf("%w: %s", ErrSyntax, err)
178 // Multiple records are allowed for the _report record, unlike for policies.
../rfc/7489:1593
181 return StatusNone, records, texts, result.Authentic, rerr
184// LookupExternalReportsAccepted returns whether the extDestDomain has opted in
185// to receiving dmarc reports for dmarcDomain (where the dmarc record was found),
186// through a "._report._dmarc." DNS TXT DMARC record.
188// accepts is true if the external domain has opted in.
189// If a temporary error occurred, the returned status is StatusTemperror, and a
190// later retry may give an authoritative result.
191// The returned error is ErrNoRecord if no opt-in DNS record exists, which is
192// not a failure condition.
194// The normally invalid "v=DMARC1" record is accepted since it is used as
195// example in RFC 7489.
197// authentic indicates if the DNS results were DNSSEC-verified.
198func LookupExternalReportsAccepted(ctx context.Context, elog *slog.Logger, resolver dns.Resolver, dmarcDomain dns.Domain, extDestDomain dns.Domain) (accepts bool, status Status, records []*Record, txts []string, authentic bool, rerr error) {
199 log := mlog.New("dmarc", elog)
202 log.Debugx("dmarc externalreports result", rerr,
203 slog.Bool("accepts", accepts),
204 slog.Any("dmarcdomain", dmarcDomain),
205 slog.Any("extdestdomain", extDestDomain),
206 slog.Any("records", records),
207 slog.Duration("duration", time.Since(start)))
210 status, records, txts, authentic, rerr = lookupReportsRecord(ctx, resolver, dmarcDomain, extDestDomain)
211 accepts = rerr == nil
212 return accepts, status, records, txts, authentic, rerr
215// Verify evaluates the DMARC policy for the domain in the From-header of a
216// message given the DKIM and SPF evaluation results.
218// applyRandomPercentage determines whether the records "pct" is honored. This
219// field specifies the percentage of messages the DMARC policy is applied to. It
220// is used for slow rollout of DMARC policies and should be honored during normal
223// Verify always returns the result of verifying the DMARC policy
224// against the message (for inclusion in Authentication-Result headers).
226// useResult indicates if the result should be applied in a policy decision,
227// based on the "pct" field in the DMARC record.
228func Verify(ctx context.Context, elog *slog.Logger, resolver dns.Resolver, msgFrom dns.Domain, dkimResults []dkim.Result, spfResult spf.Status, spfIdentity *dns.Domain, applyRandomPercentage bool) (useResult bool, result Result) {
229 log := mlog.New("dmarc", elog)
240 MetricVerify.ObserveLabels(float64(time.Since(start))/float64(time.Second), string(result.Status), reject, use)
241 log.Debugx("dmarc verify result", result.Err,
242 slog.Any("fromdomain", msgFrom),
243 slog.Any("dkimresults", dkimResults),
244 slog.Any("spfresult", spfResult),
245 slog.Any("status", result.Status),
246 slog.Bool("reject", result.Reject),
247 slog.Bool("use", useResult),
248 slog.Duration("duration", time.Since(start)))
251 status, recordDomain, record, _, authentic, err := Lookup(ctx, log.Logger, resolver, msgFrom)
253 return false, Result{false, status, false, false, recordDomain, record, authentic, err}
255 result.Domain = recordDomain
256 result.Record = record
257 result.RecordAuthentic = authentic
259 // Record can request sampling of messages to apply policy.
261 useResult = !applyRandomPercentage || record.Percentage == 100 || mathrand.Intn(100) < record.Percentage
263 // We treat "quarantine" and "reject" the same. Thus, we also don't "downgrade"
264 // from reject to quarantine if this message was sampled out.
266 if recordDomain != msgFrom && record.SubdomainPolicy != PolicyEmpty {
267 result.Reject = record.SubdomainPolicy != PolicyNone
269 result.Reject = record.Policy != PolicyNone
273 result.Status = StatusFail
274 if spfResult == spf.StatusTemperror {
275 result.Status = StatusTemperror
276 result.Reject = false
279 // Below we can do a bunch of publicsuffix lookups. Cache the results, mostly to
280 // reduce log pollution.
281 pubsuffixes := map[dns.Domain]dns.Domain{}
282 pubsuffix := func(name dns.Domain) dns.Domain {
283 if r, ok := pubsuffixes[name]; ok {
286 r := publicsuffix.Lookup(ctx, log.Logger, name)
287 pubsuffixes[name] = r
293 if spfResult == spf.StatusPass && spfIdentity != nil && (*spfIdentity == msgFrom || result.Record.ASPF == "r" && pubsuffix(msgFrom) == pubsuffix(*spfIdentity)) {
294 result.AlignedSPFPass = true
297 for _, dkimResult := range dkimResults {
298 if dkimResult.Status == dkim.StatusTemperror {
299 result.Reject = false
300 result.Status = StatusTemperror
304 if dkimResult.Status == dkim.StatusPass && dkimResult.Sig != nil && (dkimResult.Sig.Domain == msgFrom || result.Record.ADKIM == "r" && pubsuffix(msgFrom) == pubsuffix(dkimResult.Sig.Domain)) {
306 result.AlignedDKIMPass = true
311 if result.AlignedSPFPass || result.AlignedDKIMPass {
312 result.Reject = false
313 result.Status = StatusPass