RFC 8904

DNS Whitelist (DNSWL) Email Authentication Method Extension

📅 published September 2020, from ietf

RFC 8904: DNS Whitelist (DNSWL) Email Authentication Method Extension 💌

  • Stream: Independent Submission 🌸
  • Number: RFC 8904 🦋
  • Author: A. Vesely 🫶
  • Published: September 2020 🗓️
  • Category: Informational 🎀
  • ISSN: 2070-1721 ✨
  • Obsoletes or updates: nothing! It doesn't obsolete or update any other RFCs 💅

Abstract 🌈

okay so this doc describes an email authentication method that follows RFC 8601. The method looks up the sender's IP address in a DNS whitelist. It gives info in case you spot the method out in the wild, suggests a useful practice, and registers the relevant keywords. It does not consider blacklists 🙈

Status of This Memo 📝

This doc is not an Internet Standards Track spec. It's just published for informational purposes 💜

This is a contribution to the RFC Series, independent of any other RFC stream. The RFC Editor chose to publish it at its discretion and makes no statement about its value for implementation or deployment. Documents approved for publication by the RFC Editor are not candidates for any level of Internet Standard, see Section 2 of RFC 7841 ✨

Info about the current status of this doc, any errata, and how to give feedback can be found at https://www.rfc-editor.org/info/rfc8904 🔗

Copyright (c) 2020 IETF Trust and the persons identified as the document authors. All rights reserved.

This doc is subject to BCP 78 and the IETF Trust's Legal Provisions Relating to IETF Documents (https://trustee.ietf.org/license-info) as they're in effect on the date of publication. Please read these carefully, because they describe your rights and restrictions for this doc 📜

Table of Contents 🗺️

1.  Introduction
2.  Method Details
3.  TXT Record Contents
4.  IANA Considerations
  4.1.  Email Authentication Methods
  4.2.  Email Authentication Property Type
  4.3.  Email Authentication Result Names
5.  Security Considerations
  5.1.  Over-Quota Signaling
  5.2.  Security of DNSSEC Validation
  5.3.  Inherited Security Considerations
6.  References
  6.1.  Normative References
  6.2.  Informative References
Appendix A.  Example
Appendix B.  Known Implementation
Appendix C.  Future Possibilities of the 'dns' ptype
Author's Address

1. Introduction 🎀

okay bestie, one of the many checks mail servers run is querying DNS whitelists (DNSWLs)! 💖 That whole method is fully discussed in [RFC5782]. The DNS [RFC1034] lookup is based on the connecting client's IP address (IPv4 or IPv6), and it returns zero or more A records. Those A records are IPv4 addresses in the 127.0.0.0/8 range. Depending on the query, TXT records with different content can come back too. Query examples are in Appendix A ✨

Since the IP address is known as soon as the connection is accepted, this check can happen super early in an SMTP transaction 🏃‍♀️ Its result can be used to counterweight policies that also happen at early stages, like the Sender Policy Framework (SPF) (the last paragraph of Appendix D.3 of [RFC7208] is also illustrated in Appendix A). The result of a DNSWL lookup can also be used at later stages. For example, a delivery agent can use it to learn how trustworthy a mail relay is, so it can estimate how spammy an email message is. That later use needs a place to collect query results for downstream use, and that's exactly what the Authentication-Results header field is for 💅

Results often contain extra data, encoded according to DNSWL-specific criteria. This method only considers whitelists, which is one of the major branches described in [RFC5782]. There are also blacklists/blocklists (DNSBLs) and combined lists. Since they all have the same structure, the abbreviation DNSxL is used to mean any of them. The core procedures of a Mail Transfer Agent (MTA) tend to be pretty general, leaving the special cases to add-on modules 🧩 For combined lists, the boundary MTA (see [RFC5598]), which carries out the check and possibly stores the result, has to be able to tell at least the color of each entry, because that's needed for accept/reject decisions. This document provides for storing the result when the DNSxL record being reported is a whitelisting one 🌸

Data in A and TXT records can be stored as properties of the method. What that data means varies wildly depending on the list operator, so the queried zone has to be stored too 🔍 Mail site operators who set their MTAs to query specific DNSWLs basically adopt those lists' policies, since they become effectively local policies, just outsourced 🤝 Downstream agents who know the DNSWL-specific encoding and understand what the data means can use it to make delivery or display decisions. For example, a mail filter that detects heuristic evidence of a scam can counterweight that with the trustworthiness score encoded in the A response, so it protects against false positives 🛡️ Mail User Agents (MUAs) can display those results, or use them to decide how to report abusive messages, if they're configured to do so 🙌

This document describes a usage of TXT fields that's consistent with other authentication methods: it serves the domain name in the TXT record. That way, a downstream filter could also consider whether the sending agent is aligned with the author domain, with semantics similar to [RFC7489] 💜

At the time of writing, this method is implemented by Courier-MTA [Courier-MTA]. An outline of the implementation is in Appendix B 🦄

2. Method Details 💅

The result of the method says how the query went, up to the interpretation of the returned data 🔎

The method has four possible results:

  • pass: The query successfully returned applicable records. This result is usually accompanied by one or both of the policy properties described below. Since the list is configured as a DNSWL, agents that can't interpret list-specific properties can still derive a positive value from the fact that the sender is whitelisted ✨
  • none: The query worked but yielded no A record or returned NXDOMAIN, so the sender is not whitelisted 🫤
  • temperror: The DNS evaluation couldn't be completed because of some error that's likely transient in nature, such as a temporary DNS error (e.g., a DNS RCODE of 2, commonly known as SERVFAIL) or another error condition. A later attempt may produce a final result ⏳
  • permerror: The DNS evaluation can't work because test entries don't work (that is, DNSWL is broken), or because queries are over quota (reported by a DNS RCODE of 5, commonly known as REFUSED, or by a DNSWL-specific property (policy.ip, defined below) with the same meaning). A later attempt is unlikely to produce a final result. Human intervention is required 🚨

Note that there is no "fail" result. No fail, no drama 💀

The following ptype.property items define how the data provided by the whitelist lookup can be saved 💾

  • dns.zone: The DNSWL query root domain, which defines the meaning of the policy.ip property below. An MTA can use a local mirror with a different name. The name stored here has to be the best available reference for all foreseeable downstream consumers. Setting dns.zone to the global zone makes the result intelligible even if the message is handed outside of the internal network 🌍
  • policy.ip: The bit mask value received in the type A response, in dotted quad notation. Multiple entries can be arranged in a quoted, comma-separated list. The quotes are necessary because commas are not allowed in a token 🎀
  • policy.txt: The TXT record, if any. Multiple records are concatenated in the usual way (explained, for example, in Section 3.3 of [RFC7208]). See Section 3 for the resulting content and query options 📖
  • dns.sec: This is a generic property stating whether the relevant data was validated using DNSSEC [RFC4033]. For the present method, the relevant data consists of the reported policy properties above or, if the method result is "none", its nonexistence. This property has three possible values:
    • yes: DNSSEC validation confirms the integrity of the data. Section 5.2 considers how that's related to the DNS response 🔐
    • no: The data is not signed. See Section 5.2 🙅‍♀️
    • na: Not applicable. No DNSSEC validation can be performed, possibly because the lookup is run through a different means than a security-aware DNS resolver. This does not necessarily imply less security. In particular, na is used if the data was downloaded in bulk and then loaded on a local nameserver, which is the case of an MTA querying a local zone different from the reported dns.zone. DNS errors, including validation errors, can also report na. This is also the value assumed by default 🫧

3. TXT Record Contents 📝

Okay so TXT records are the part that explains why an IP is on the list 🫶 Per [RFC5782], they describe the reason an IP address is listed in a DNSWL. Appendix B has an example of a DNSWL whose TXT records contain the domain name of the organization assignee of the sending IP. That domain would match the DNS domain used by or within the Administrative Management Domain (ADMD) running the relevant MTA, which is sometimes called the "organizational domain" 💅 In that case, the authentication this method provides is equivalent to a DomainKeys Identified Mail (DKIM) signature [RFC6376] or an SPF check host [RFC7208], if the DNSWL is trusted ✨

Attributing an IP to an organization can take more than a basic PTR record consistency check, depending on the DNSWL's policy 🧐 If no domain names can be responsibly tied to an IP address, maybe because it got added without the organization being involved at all, DNSWLs can use a subdomain of .INVALID [RFC2606]. The leftmost label hints at why the address is whitelisted 🙈 For example, if the list managers added 192.0.2.38 purely based on their own knowledge, the TXT record might be AUTOPROMOTED.INVALID, so nobody gets explicitly named for something they never opted into. Iconic behavior from the DNSWL, honestly 🦋

Following Multicast DNS (see the second paragraph of Section 16 of [RFC6762]), names with non-ASCII characters can be encoded in UTF-8 [RFC3629] using Normalization Form C [NFC], as described in "Unicode Format for Network Interchange" [RFC5198] 🌸 Putting unaltered UTF-8 TXT values in the header means you need an environment that's compatible with Email Address Internationalization (EAI) [RFC6530]. Very specific, very important, bestie 💜

DNS queries with a QTYPE of ANY can give inconsistent replies, depending on cache status 💀 Also, ANY is not "all"! The provisions for queries with QTYPE=ANY [RFC8482] don't cover DNSxLs, so don't be fooled 🙅‍♀️ A mail server can send two simultaneous queries, one A and one TXT. Or a downstream filter can send a TXT query on its own, but only if it already knows the A query worked and that the DNSWL serves useful TXT records. And it's highly unlikely TXT records exist if the QTYPE A query came back with a result of "none" 🥀

4. IANA Considerations 🌈

IANA maintains the "Email Authentication Parameters" registry, which has several subregistries 🗂️ IANA has made the assignments listed in the following sections, so here's the tea 🍵

4.1. Email Authentication Methods

IANA has created four new entries in the "Email Authentication Methods" registry, like this:

+======+===========+======+========+=================+======+=======+
|Method|Definition |ptype |property|Value            |Status|Version|
+======+===========+======+========+=================+======+=======+
|dnswl |RFC 8904   |dns   |zone    |DNSWL publicly   |active|   1   |
|      |           |      |        |accessible query |      |       |
|      |           |      |        |root domain      |      |       |
+------+-----------+------+--------+-----------------+------+-------+
|dnswl |RFC 8904   |policy|ip      |type A response  |active|   1   |
|      |           |      |        |received (or a   |      |       |
|      |           |      |        |quoted, comma-   |      |       |
|      |           |      |        |separated list   |      |       |
|      |           |      |        |thereof)         |      |       |
+------+-----------+------+--------+-----------------+------+-------+
|dnswl |RFC 8904   |policy|txt     |type TXT query   |active|   1   |
|      |           |      |        |response         |      |       |
+------+-----------+------+--------+-----------------+------+-------+
|dnswl |RFC 8904   |dns   |sec     |one of "yes" for |active|   1   |
|      |           |      |        |DNSSEC           |      |       |
|      |           |      |        |authenticated    |      |       |
|      |           |      |        |data, "no" for   |      |       |
|      |           |      |        |not signed, or   |      |       |
|      |           |      |        |"na" for not     |      |       |
|      |           |      |        |applicable       |      |       |
+------+-----------+------+--------+-----------------+------+-------+

                                  Table 1

4.2. Email Authentication Property Type

IANA has created a new entry in the "Email Authentication Property Types" registry, like so 🎀

        +=======+============+====================================+
        | ptype | Definition | Description                        |
        +=======+============+====================================+
        | dns   | RFC 8904   | The property being reported        |
        |       |            | belongs to the Domain Name System. |
        +-------+------------+------------------------------------+

                                  Table 2

4.3. Email Authentication Result Names

IANA has created four new entries in the "Email Authentication Result Names" registry, as follows 💖

           +=============+===========+===============+========+
           | Auth Method | Code      | Specification | Status |
           +=============+===========+===============+========+
           | dnswl       | pass      | RFC 8904      | active |
           +-------------+-----------+---------------+--------+
           | dnswl       | none      | RFC 8904      | active |
           +-------------+-----------+---------------+--------+
           | dnswl       | temperror | RFC 8904      | active |
           +-------------+-----------+---------------+--------+
           | dnswl       | permerror | RFC 8904      | active |
           +-------------+-----------+---------------+--------+

                                 Table 3

5. Security Considerations 🚨

Okay, this section is serious, so read it carefully, bestie 🫶 No skipping!

5.1. Over-Quota Signaling

Some DNSWLs give free access up to a given quota, and they're known to return special codes to signal that the quota has been exceeded (for example, 127.0.0.255) 😬 If the MTA can't interpret that value, it results in a false positive, and the MTA can accept messages it would otherwise reject. Yikes. A DNSWL-specific module would be able to realize this fact and call for human intervention 🙋

Returning an RCODE 5 (REFUSED) conveys the concept that the query is "unauthorized" and that human intervention is required 🛑

5.2. Security of DNSSEC Validation

The dns.sec property is meant to be as secure as DNSSEC results are. It makes sense to use it in an environment where DNSSEC validation can succeed 🔐

Section 7 of [RFC4033] looks at different ways of setting up a stub resolver that either validates DNSSEC locally or trusts the validation provided through a secure channel 🧠 For a different class, it's possible to set up a dedicated, caching, DNSSEC-enabled resolver that the mail server can reach through interprocess communication on 127.0.0.1. In those cases, the property dns.sec=yes corresponds to the Authenticated Data (AD) bit in the DNS response header ✨

When the response contains no DNSSEC data, a security-aware resolver looks for a signed proof of the nonexistence of a DS record at some delegation point. If no error is returned, the zone is unsigned and dns.sec=no can be set 🧩 The Security Considerations section of [RFC3225] states:

|  The absence of DNSSEC data in response to a query with the DO bit
|  set MUST NOT be taken to mean no security information is available
|  for that zone as the response may be forged or a non-forged
|  response of an altered (DO bit cleared) query.

If the application verifies the DNSSEC signatures on its own, it effectively behaves like a validating resolver, so it can set dns.sec accordingly 💅

When the data is downloaded in bulk and made available on a trusted channel without using DNSSEC, the application sets dns.sec=na, or doesn't set it at all 📦 For example, consider DNSWLs that publish bulk versions of their data, duly signed using OpenPGP [RFC4880]. It is the responsibility of system administrators to authenticate the data by downloading it and validating the signature. The result of that validation is not reported using dns.sec 🔏

5.3. Inherited Security Considerations

For DNSSEC, the considerations of Section 12 of [RFC4033] apply 🧾

All of the considerations described in Section 7 of [RFC8601] apply too 🌟 That includes securing against tampering all the channels after the Authentication-Results header field has been produced.

On top of that, the usual caveats apply about importing text from external online sources 🌐 Even though queried DNSWLs are well-known, trusted entities, it's suggested that TXT records only be reported if, upon inspection, their content is deemed actionable and their format is compatible with the computing environment 🥹

6. References 📚

6.1. Normative References

[RFC2606]  Eastlake 3rd, D. and A. Panitz, "Reserved Top Level DNS
           Names", BCP 32, RFC 2606, DOI 10.17487/RFC2606, June 1999,
           <https://www.rfc-editor.org/info/rfc2606>.

[RFC5782]  Levine, J., "DNS Blacklists and Whitelists", RFC 5782,
           DOI 10.17487/RFC5782, February 2010,
           <https://www.rfc-editor.org/info/rfc5782>.

[RFC8601]  Kucherawy, M., "Message Header Field for Indicating
           Message Authentication Status", RFC 8601,
           DOI 10.17487/RFC8601, May 2019,
           <https://www.rfc-editor.org/info/rfc8601>.

6.2. Informative References 📚

Okay bestie, these are the "go read this if you want the deep lore" sources 🤓✨

Appendix A. Example ✨

Let's walk through a real-life drama 🎬 Here's what the header trace looks like:

Delivered-To: recipient@example.org
Return-Path: <sender@example.com>
Authentication-Results: mta.example.org;
  dkim=pass (whitelisted) header.i=@example.com
Authentication-Results: mta.example.org;
  dnswl=pass dns.zone=list.dnswl.example dns.sec=na
  policy.ip=127.0.10.1
  policy.txt="fwd.example https://dnswl.example/?d=fwd.example"
Received-SPF: fail (Address does not pass Sender Policy Framework)
  client-ip=2001:db8::2:1;
  envelope-from="sender@example.com";
  helo=mail.fwd.example;
  receiver=mta.example.org;
Received: from mail.fwd.example (mail.fwd.example [2001:db8::2:1])
  (TLS: TLSv1/SSLv3,128bits,ECDHE-RSA-AES128-GCM-SHA256)
  by mta.example.org with ESMTPS; Thu, 03 Oct 2019 19:23:11 +0200
  id 00000000005DC044.000000005702D87C.000007FC

Figure 1: Trace Fields at the Top of the Header

So a third party, fwd.example, forwarded the message on to the final MTA 📨 Nobody set up that mail path ahead of time with the MTAs involved. It just kind of happened spontaneously 🙈 Without whitelisting, this message would NOT have made it through, because:

  • the author domain published a strict SPF policy (-all),
  • the forwarder did not alter the bounce address, and
  • the target usually honors reject on fail, according to Section 8.4 of [RFC7208].

BUT the target also implemented the last paragraph of Appendix D.3 of [RFC7208] 💅 Its behavior hinges on these DNS entries:

  1.0.0.0.2.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.d.b.8.2.0.0.1.
                                                list.dnswl.example.
        IN  A    127.0.10.1
        IN  TXT  "fwd.example https://dnswl.example/?d=fwd.example"

Figure 2: DNS Resource Records for 2001:db8::2:1 (line breaks for editorial reasons)

If mail.fwd.example had connected from address 192.0.2.1, the query name would have been "1.2.0.192.list.dnswl.example". The full description is in [RFC5782].

At connection time, the remote IP address was whitelisted, so the target MTA did NOT reject the message before DATA 🦋 Instead, it recorded the SPF fail result and noted which local policy mechanism was applied to override that result. Then later filtering verified DKIM [RFC6376].

At later stages, mail filters can reject or quarantine the message based on its content 🛡️ Knowing more about the policy values from dnswl.example helps you interpret the values of policy.ip and weigh them against other factors, so you can make better calls 🧠

Appendix B. Known Implementation 🔧

Okay, the implementation details in this section have been stable for several years ✨ But this description is necessarily superficial, version dependent, and subject to change, so don't take it as gospel 🙃

Courier-MTA [Courier-MTA] can be configured to look up DNSBLs and DNSWLs, using similar command-line switches:

-block=zone[=displayzone][,var[/n.n.n.n][,msg]]
-allow=zone[=displayzone][,var[/n.n.n.n[,]]]

"zone" is the zone to be queried.

"displayzone" is only used for -allow; it is the value to be set in the dns.zone property.

"var" stands for the environment variable whose existence triggers a special action. The default variable names give you a conventional behavior implemented by Courier-MTA, but you can customize things by setting different environment variables 💖 The conventional behavior is very different between -block and -allow. The former rejects the message, and the latter produces Authentication-Results header fields.

The n.n.n.n IP address requires a precise A record response. If it's not given, any response sets the corresponding variable. If it is given, variables are set only if the response matches exactly. This syntax offers a very limited interpretation of the information encoded in A records 🙈 It's considered to be too complicated already, though. Even specifying a range, an enumeration of values, or a regular expression would require something beyond what a normal user would be willing to manage 😭

Finally, the trailing message, which overrides the 5xx SMTP reply for -block, is not used for -allow. The only exception is that its mere presence requires querying TXT records to be registered in policy.txt.

SPF is part of Courier-MTA's core. It is configured separately, and it provides an "allowok" keyword to indicate the choice to override rejection in case of SPF failure and -allow whitelisting.

A customary whitelist is defined by DNSWL.org [DNSWL] 🌸 It serves A records encoded as follows:

1st octet:  127.

2nd octet:  0.

3rd octet:  Category of business, 15 values.

4th octet:  Trustworthiness/score, 4 values.

They also serve TXT records containing the domain name followed by a URL pointing to further information about the relevant organization, such as what other IP addresses of theirs are being whitelisted. They don't use UTF-8.

DNSWL.org offers free registration and free access below 100,000 queries per day. To signal that the quota has been exceeded, they use a special return code, 127.0.0.255, as exemplified above. Courier-MTA itself does not recognize this return code 🥺 But it has a mail filter (zdkimfilter, named after its main usage) that hard codes recognition of this code and the code for trustworthiness in the 4th octet. Iconic 👑

Appendix C. Future Possibilities of the 'dns' ptype 🔮

The description of the new ptype proposed in Section 4.2 says, "The property being reported belongs to the Domain Name System." That definition can broadly include any tag found in a domain's TXT record 🌈 For example, designers of authentication methods can agree that within a resinfo of a given method, any dns ptype refers to tags in the relevant DNS record, unless otherwise specified. So you could have, say:

Authentication-Results: example.com;
  spf=pass smtp.mailfrom=example.net dns.sec=y;
  dkim=pass header.i=@example.org header.b=jIvx30NG dns.s=tlsrpt

While dns.sec is defined above, albeit not for the spf method, the use of tlsrpt in the DKIM record is exemplified in Section 3 of [RFC8460]. The tag s= is part of the DKIM TXT record, so don't mix it up with the selector s=, which is part of a DKIM signature 🧐 Just like the selector can be reported as header.s because the DKIM header field is in the message header, it may make sense to report the tag as dns.s because the DKIM DNS record is in the DNS.

NOTE: This is only a hint at what may become a consistent naming convention around the new ptype. In any case, any new property using this ptype requires its own formal definition. This document does NOT define the property dns.s=, let alone the service tlsrpt. 🫶

Author's Address 🖋️

Alessandro Vesely
v. L. Anelli 13
20122 Milano MI
Italy

Email: vesely@tana.it
📦 where this page comes from