Internet-Draft | BIMI Reporting | April 2023 |
Adams & Brotman | Expires 9 October 2023 | [Page] |
To support the utility of Brand Indicators for Message Identification (BIMI), domains publishing BIMI records may find it useful to know when their logos are failing to be displayed as expected. When an entity, for example a mailbox operator, determines whether or not to display the logo identified in the BIMI record, they may encounter errors trying to retrieve the image file. Similarly, the associated evidence document used to validate the logo may fail evaluation. In other cases, the evaluator may decide that despite everything validating, they may rely on local policies that determine validated logos should still not be displayed. This specification defines how BIMI evaluators should report their evaluation outcome back to the publisher within the context of existing Domain-based Message Authentication, Reporting, and Conformance (DMARC) reports.¶
This Internet-Draft is submitted in full conformance with the provisions of BCP 78 and BCP 79.¶
Internet-Drafts are working documents of the Internet Engineering Task Force (IETF). Note that other groups may also distribute working documents as Internet-Drafts. The list of current Internet-Drafts is at https://datatracker.ietf.org/drafts/current/.¶
Internet-Drafts are draft documents valid for a maximum of six months and may be updated, replaced, or obsoleted by other documents at any time. It is inappropriate to use Internet-Drafts as reference material or to cite them other than as "work in progress."¶
This Internet-Draft will expire on 9 October 2023.¶
Copyright (c) 2023 IETF Trust and the persons identified as the document authors. All rights reserved.¶
This document is subject to BCP 78 and the IETF Trust's Legal Provisions Relating to IETF Documents (https://trustee.ietf.org/license-info) in effect on the date of publication of this document. Please review these documents carefully, as they describe your rights and restrictions with respect to this document. Code Components extracted from this document must include Revised BSD License text as described in Section 4.e of the Trust Legal Provisions and are provided without warranty as described in the Revised BSD License.¶
Organizations sending email associated with specific brands and domains may use Brand Indicators for Message Identification (BIMI) [I-D.blank-ietf-bimi] to signal which brand identifier (e.g. a company logo) should be displayed when receiving authenticated email for the specified domain. This document is intended as a companion to the BIMI specification as it defines the associated error reporting method and schema. It includes information necessary for Domain Owners to identify and troubleshoot potential issues related to the evaluation of the elements identified within their BIMI records.¶
The document supports the ability for a domain sending email to identify and diagnose problems with their BIMI deployment. It is designed to be as easy to deploy as possible for BIMI reporters and report consumers. It integrates with existing Domain-based Message Authentication, Reporting, and Conformance (DMARC) [RFC7489] aggregate reporting (RUA) rather than adding a new reporting mechanism. The data being reported is aggregated in a way that respects the privacy of senders, receivers, and users by not leaking potentially sensitive information.¶
This document is intended as a companion to the BIMI specification draft [I-D.blank-ietf-bimi] by adding reporting abilities.¶
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in [RFC2119] and [RFC8174] when, and only when, they appear in all capitals, as shown here.¶
This document is designed to operate within the context of Internet Mail service, as defined in [RFC5598], as well as the reporting structure defined by [RFC7489]. In addition to the terms defined below, some terminology throughout the document has been inherited from those specifications.¶
Given that BIMI relies on DMARC evaluation, this document does not define a separate Report Consumer outside the context of DMARC. The BIMI Report MUST be included as part of a DMARC report sent to the RUA address identified within the applicable DMARC record for the email being evaluated. The applicable Report address is determined by the DMARC policy discovered for the Aligned Domain of the sending email. This may be the Fully-Qualified Domain Name (FQDN) [RFC1983], or Organizational Domain as determined by DMARC evaluation. Note that the domain of the applicable DMARC policy may not be the same domain where the applicable BIMI record is discovered.¶
For example, consider the following situation in which an Organizational Domain (i.e. "example.com") has slightly different DMARC and BIMI reporting configurations for the two FQDNs:¶
When the organization sends email with the [RFC5322].From domain set to "sub.example.com", the Evaluator does not find a BIMI record at the FQDN, but does find one at the Organizational Domain level: "example.com".¶
The Evaluator sends BIMI reports to the applicable report consumer identified within the Aligned Domain's DMARC record: "rua@sub.example.com", not to the RUA address associated with the Organizational Domain where the BIMI record was discovered.¶
In another example, consider another situation in which an Organizational Domain (i.e. "example.com") has slightly different DMARC and BIMI reporting configurations for the two FQDNs:¶
When the organization sends email with the [RFC5322].From domain set to "sub.example.com", the Evaluator does not find a BIMI record at the FQDN, but does find one at the Organizational Domain level: "example.com".¶
The Evaluator sends BIMI reports to the applicable report consumer identified for the Aligned Domain which is discovered within the applicable DMARC record published at the organizational domain: "rua@example.com".¶
The following data defined in this section MUST be reported within the context of an XML-formatted DMARC [RFC7489] Aggregate Report (RUA). Given the reliance on DMARC evaluation, the BIMI Reports are sent as additional elements within RUA reports, inheriting its terminology and metadata (e.g. "date_range", "report_id", etc.).¶
The complete set of BIMI Report elements and attributes are collected within a single top-level <bimi> element within the RUA <xml> root element (i.e. at the same level as the <record> elements). The <bimi> element SHOULD be the last top-level element within the <xml> root element, but MAY be placed in any order in relation to other top-level elements.¶
The nested structure of the elements is illustrated below. The attributes and contents for each element are described in more detail in the following sections.¶
<bimi> <domain> <assertion> <evidence /> <errors> <assertion>[count]</assertion> <evidence>[count]</evidence> <indicator>[count]</indicator> <undefined>[count]</undefined> </errors> </assertion> </domain> </bimi>¶
Within the <bimi> element is one or more <domain> elements, each element of which MUST include the following attributes:¶
Each <domain> element MUST represent a unique "aligned":"assertion" tuple within the enclosing <bimi> element. All BIMI assertion records related to this domain tuple MUST be reported within this element.¶
The content of each <domain> element MUST include one or more <assertion> elements, each element of which MUST include the following attributes:¶
Each <assertion> element MUST represent a unique "selector":"l":"a" tuple within the enclosing <domain> element. All errors related to this assertion tuple MUST be reported within this element.¶
In the case in which a non-default Selector Name is provided, but the evaluation of the referenced selector results in an error, and evaluation of the default selector also results in an error, both the initial error and the default selector errors are reported within separate <assertion> elements. One <assertion> element will include the "selector" attribute set to "default"', and the other will include the "selector" attribute set to the Selector Name identified in the email.¶
The <evidence> element is OPTIONAL and is only REQUIRED if the attributes as described below are included in the Report. The <evidence> element is a null element that contains the following attributes:¶
All errors to be reported MUST be included within the <errors> element which is within the <assertion> element. Within the <errors> element are one or more elements containing the error data aggregated as described below. If there are no errors within a reporting period, the <errors> element MUST NOT exist in the Report.¶
The count of non-zero errors being reported MUST be grouped by the logical tuple:¶
Where ERROR-NAME is an element named one of:¶
The "class" for each error tuple is set to one of:¶
The "type" component of the tuple is defined for the specific error elements in their descriptions below.¶
There MUST only be one instance of a specific error tuple per Report, each of which aggregates the count of errors associated with that tuple during the report period. There MAY be multiple error elements with the same name, but the tuples MUST be differentiated by distinct element attributes.¶
For example, the <errors> element may contain two <indicator> error elements. One <indicator> error element may contain a "class=temp" attribute, while the other may contain a "class=perm" attribute. Each of which aggregates the count of the specified class of errors.¶
The <assertion> errors element is OPTIONAL and is only REQUIRED if there are assertion errors to report. The <assertion> error element encloses a positive natural number indicating the count of assertion errors encountered during the reporting period for the set of element attributes indicating the class, type, and (optionally) description:¶
The <evidence> errors element is OPTIONAL and is only REQUIRED if there are evidence errors to report. The <evidence> error element encloses a positive natural number indicating the count of evidence errors encountered during the reporting period for the set of element attributes indicating the class, type, and (optionally) description:¶
The <indicator> errors element is OPTIONAL and is only REQUIRED if there are indicator errors to report. The <indicator> errors element encloses a positive natural number indicating the count of indicator errors encountered during the reporting period for the set of element attributes indicating the class, type, and (optionally) description:¶
The <undefined> errors element is OPTIONAL and SHOULD be used to report errors that are not covered by other error elements. The <undefined> errors element encloses a positive natural number indicating the count of undefined errors encountered during the reporting period for the set of element attributes indicating the class and (optionally) description:¶
This document was informed by discussions with and/or contributions from Arne Allisat, Kurt Andersen, Tom Bartel, Marcel Becker, Seth Blank, Marc Bradshaw, Alex Brotman, Wei Chuang, Todd Herr, Neil Kumaran, Hansen Lee, Thede Loder, Maddie McCaffrey, Alex Rubin, Len Shneyder, and Matthew Vernhout.¶
This section will be filled out in more detail when the draft moves toward completion.¶
Security considerations related to this document are inherited from those mentioned in [RFC7489] and [I-D.blank-ietf-bimi]. This section will be filled out in more detail when the draft moves toward completion.¶
The following is an example DMARC RUA report with BIMI error elements.¶
<?xml version="1.0" encoding="UTF-8" ?> <feedback> <report_metadata> <org_name>reporter.tld</org_name> <email>info@reporter.tld</email> <report_id>uniqueidentifier</report_id> <date_range> <begin>1609459200M</begin> <end>1609545599</end> </date_range> </report_metadata> <policy_published> <domain>sender.tld</domain> <adkim>r</adkim> <aspf>r</aspf> <p>reject</p> <sp>reject</sp>? <pct>100</pct> </policy_published> <record> <row> <source_ip>192.0.2.1</source_ip> <count>10</count> <policy_evaluated> <disposition>none</disposition> <dkim>pass</dkim> <spf>pass</spf> </policy_evaluated> </row> <identifiers> <header_from>sender.tld</header_from> </identifiers> <auth_results> <dkim> <domain>sender.tld</domain> <result>pass</result> <selector>selector01</selector> </dkim> <spf> <domain>sender.tld</domain> <result>pass</result> </spf> </auth_results> </record> <bimi> <domain aligned="sender.tld" assertion="sender.tld"> <assertion selector="default" a="" l="https://www.sender.tld/images/logos/bimi.svg"> <evidence /> <errors> <indicator class="temp" type="retrieval" description="DNS RCODE:3">1</indicator> </errors> </assertion> </domain> </bimi> </feedback>¶