idnits 2.17.1 draft-adams-bimi-reporting-02.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- No issues found here. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year -- The document date (10 April 2022) is 719 days in the past. Is this intentional? Checking references for intended status: Informational ---------------------------------------------------------------------------- == Outdated reference: A later version (-07) exists of draft-svg-tiny-ps-abrotman-01 Summary: 0 errors (**), 0 flaws (~~), 2 warnings (==), 1 comment (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 Network Working Group T. Adams 3 Internet-Draft Proofpoint 4 Intended status: Informational A. Brotman 5 Expires: 12 October 2022 Comcast, Inc. 6 10 April 2022 8 BIMI Reporting 9 draft-adams-bimi-reporting-02 11 Abstract 13 To support the utility of Brand Indicators for Message Identification 14 (BIMI), domains publishing BIMI records may find it useful to know 15 when their logos are failing to be displayed as expected. When an 16 entity, for example a mailbox operator, determines whether or not to 17 display the logo identified in the BIMI record, they may encounter 18 errors trying to retrieve the image file. Similarly, the associated 19 evidence document used to validate the logo may fail evaluation. In 20 other cases, the evaluator may decide that despite everything 21 validating, they may rely on local policies that determine validated 22 logos should still not be displayed. This specification defines how 23 BIMI evaluators should report their evaluation outcome back to the 24 publisher within the context of existing Domain-based Message 25 Authentication, Reporting, and Conformance (DMARC) reports. 27 Status of This Memo 29 This Internet-Draft is submitted in full conformance with the 30 provisions of BCP 78 and BCP 79. 32 Internet-Drafts are working documents of the Internet Engineering 33 Task Force (IETF). Note that other groups may also distribute 34 working documents as Internet-Drafts. The list of current Internet- 35 Drafts is at https://datatracker.ietf.org/drafts/current/. 37 Internet-Drafts are draft documents valid for a maximum of six months 38 and may be updated, replaced, or obsoleted by other documents at any 39 time. It is inappropriate to use Internet-Drafts as reference 40 material or to cite them other than as "work in progress." 42 This Internet-Draft will expire on 12 October 2022. 44 Copyright Notice 46 Copyright (c) 2022 IETF Trust and the persons identified as the 47 document authors. All rights reserved. 49 This document is subject to BCP 78 and the IETF Trust's Legal 50 Provisions Relating to IETF Documents (https://trustee.ietf.org/ 51 license-info) in effect on the date of publication of this document. 52 Please review these documents carefully, as they describe your rights 53 and restrictions with respect to this document. Code Components 54 extracted from this document must include Revised BSD License text as 55 described in Section 4.e of the Trust Legal Provisions and are 56 provided without warranty as described in the Revised BSD License. 58 Table of Contents 60 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2 61 1.1. Terminology and Definitions . . . . . . . . . . . . . . . 3 62 2. Identifying the Report Consumer . . . . . . . . . . . . . . . 4 63 2.1. Example 1: Sub-domain Reporting . . . . . . . . . . . . . 4 64 2.2. Example 2: Inherited Reporting . . . . . . . . . . . . . 5 65 3. Reporting Schema . . . . . . . . . . . . . . . . . . . . . . 5 66 3.1. Element . . . . . . . . . . . . . . . . . . . . 6 67 3.2. Element . . . . . . . . . . . . . . . . . . . 6 68 3.3. Element . . . . . . . . . . . . . . . . . . . 7 69 3.4. Element . . . . . . . . . . . . . . . . . . . . 7 70 4. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 11 71 5. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 11 72 6. Security Considerations . . . . . . . . . . . . . . . . . . . 11 73 7. On-going Discussions . . . . . . . . . . . . . . . . . . . . 12 74 8. References . . . . . . . . . . . . . . . . . . . . . . . . . 12 75 8.1. Normative References . . . . . . . . . . . . . . . . . . 12 76 8.2. Informative References . . . . . . . . . . . . . . . . . 12 77 Appendix A. Example RUA Report with BIMI . . . . . . . . . . . . 13 78 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 14 80 1. Introduction 82 Organizations sending email associated with specific brands and 83 domains may use Brand Indicators for Message Identification (BIMI) 84 [I-D.blank-ietf-bimi] to signal which brand identifier (e.g. a 85 company logo) should be displayed when receiving authenticated email 86 for the specified domain. This document is intended as a companion 87 to the BIMI specification as it defines the associated error 88 reporting method and schema. It includes information necessary for 89 Domain Owners to identify and troubleshoot potential issues related 90 to the evaluation of the elements identified within their BIMI 91 records. 93 The document supports the ability for a domain sending email to 94 identify and diagnose problems with their BIMI deployment. It is 95 designed to be as easy to deploy as possible for BIMI reporters and 96 report consumers. It integrates with existing Domain-based Message 97 Authentication, Reporting, and Conformance (DMARC) [RFC7489] 98 aggregate reporting (RUA) rather than adding a new reporting 99 mechanism. The data being reported is aggregated in a way that 100 respects the privacy of senders, receivers, and users by not leaking 101 potentially sensitive information. 103 This document is intended as a companion to the BIMI specification 104 draft [I-D.blank-ietf-bimi] by adding reporting abilities. 106 1.1. Terminology and Definitions 108 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 109 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 110 document are to be interpreted as described in [RFC2119] and 111 [RFC8174] when, and only when, they appear in all capitals, as shown 112 here. 114 This document is designed to operate within the context of Internet 115 Mail service, as defined in [RFC5598], as well as the reporting 116 structure defined by [RFC7489]. In addition to the terms defined 117 below, some terminology throughout the document has been inherited 118 from those specifications. 120 Aligned Domain: The FQDN that passes the DMARC evaluation to 121 determine where to initially look the associated DMARC policy 122 record. 124 Assertion Domain: The FQDN where the BIMI record associated with an 125 email is found. 127 Evaluator: The entity or organization that evaluates the BIMI 128 assertions when an email is received and has passed DMARC 129 evaluation. This may be the email receiver (e.g. the MX server 130 identified as the inbound MTA gateway), or another entity that 131 processes the email later in the email evaluation pipeline. For 132 example, an MTA may perform DMARC and BIMI evaluation within a 133 single authentication process, while in some contexts DMARC 134 evaluation may occur at a perimeter MTA while BIMI evaluation is 135 performed by another MTA later in the process (which may or may 136 not be operated by the same organization). 138 Report: The data compiled by the Evaluator about how it evaluated 139 BIMI in relation to email sent from, or on behalf of, a specified 140 domain. 142 Reporter: The operator that sends Reports to the Report Consumer 143 identified within the applicable DMARC record. 145 Report Consumer: An operator that receives Reports from a Reporter 146 implementing the reporting mechanism described in this document. 147 Such an operator might be receiving reports about its own 148 messages, or Reports about messages related to another operator. 149 This term applies collectively to the system components that 150 receive and process these reports and the organizations that 151 operate them. 153 Selector Name: The name of the BIMI selector, if one exists, within 154 the designated header field in an email. If no specific BIMI 155 selector is identified, the Selector Name is assumed to be 156 "default". 158 2. Identifying the Report Consumer 160 Given that BIMI relies on DMARC evaluation, this document does not 161 define a separate Report Consumer outside the context of DMARC. The 162 BIMI Report MUST be included as part of a DMARC report sent to the 163 RUA address identified within the applicable DMARC record for the 164 email being evaluated. The applicable Report address is determined 165 by the DMARC policy discovered for the Aligned Domain of the sending 166 email. This may be the Fully-Qualified Domain Name (FQDN) [RFC1983], 167 or Organizational Domain as determined by DMARC evaluation. Note 168 that the domain of the applicable DMARC policy may not be the same 169 domain where the applicable BIMI record is discovered. 171 2.1. Example 1: Sub-domain Reporting 173 For example, consider the following situation in which an 174 Organizational Domain (i.e. "example.com") has slightly different 175 DMARC and BIMI reporting configurations for the two FQDNs: 177 Domain: example.com 178 * Publishes a DMARC record 179 * Requests RUA reports be sent to "rua@example.com" 180 * Publishes a BIMI record 182 Domain: sub.example.com 183 * Publishes a DMARC record 184 * Requests RUA reports sent to "rua@sub.example.com" 185 * Does not publish a BIMI record 187 When the organization sends email with the [RFC5322].From domain set 188 to "sub.example.com", the Evaluator does not find a BIMI record at 189 the FQDN, but does find one at the Organizational Domain level: 190 "example.com". 192 The Evaluator sends BIMI reports to the applicable report consumer 193 identified within the Aligned Domain's DMARC record: 194 "rua@sub.example.com", not to the RUA address associated with the 195 Organizational Domain where the BIMI record was discovered. 197 2.2. Example 2: Inherited Reporting 199 In another example, consider another situation in which an 200 Organizational Domain (i.e. "example.com") has slightly different 201 DMARC and BIMI reporting configurations for the two FQDNs: 203 Domain: example.com 204 * Publishes a DMARC record covering all sub-domains 205 * Requests RUA reports be sent to "rua@example.com" 206 * Publishes a BIMI record 208 Domain: sub.example.com 209 * Does not publish a DMARC record 210 * Does not publish a BIMI record 212 When the organization sends email with the [RFC5322].From domain set 213 to "sub.example.com", the Evaluator does not find a BIMI record at 214 the FQDN, but does find one at the Organizational Domain level: 215 "example.com". 217 The Evaluator sends BIMI reports to the applicable report consumer 218 identified for the Aligned Domain which is discovered within the 219 applicable DMARC record published at the organizational domain: 220 "rua@example.com". 222 3. Reporting Schema 224 The following data defined in this section MUST be reported within 225 the context of an XML-formatted DMARC [RFC7489] Aggregate Report 226 (RUA). Given the reliance on DMARC evaluation, the BIMI Reports are 227 sent as additional elements within RUA reports, inheriting its 228 terminology and metadata (e.g. "date_range", "report_id", etc.). 230 The complete set of BIMI Report elements and attributes are collected 231 within a single top-level element within the RUA root 232 element (i.e. at the same level as the elements). The 233 element SHOULD be the last top-level element within the 234 root element, but MAY be placed in any order in relation to other 235 top-level elements. 237 The nested structure of the elements is illustrated below. The 238 attributes and contents for each element are described in more detail 239 in the following sections. 241 242 243 244 245 246 [count] 247 [count] 248 [count] 249 [count] 250 251 252 253 255 3.1. Element 257 Within the element is one or more elements, each 258 element of which MUST include the following attributes: 260 "aligned" (REQUIRED): The Aligned Domain. 262 "assertion" (REQUIRED): The Assertion Domain. 264 Each element MUST represent a unique "aligned":"assertion" 265 tuple within the enclosing element. All BIMI assertion 266 records related to this domain tuple MUST be reported within this 267 element. 269 3.2. Element 271 The content of each element MUST include one or more 272 elements, each element of which MUST include the 273 following attributes: 275 "selector" (REQUIRED): The Selector Name defined by the relevant 276 email header, or set to "default" if no Selector Name was 277 specifically defined. 279 "l" (REQUIRED): The field extracted from the "l=" field within the 280 BIMI assertion record. If blank, the attribute label MUST be 281 present, and the attribute MUST be set to "unpublished". 283 "a" (REQUIRED): The field extracted from the "a=" field within the 284 BIMI assertion record. If blank, the attribute label MUST be 285 present, and the attribute MUST be left blank (i.e. a="") 287 Each element MUST represent a unique "selector":"l":"a" 288 tuple within the enclosing element. All errors related to 289 this assertion tuple MUST be reported within this element. 291 In the case in which a non-default Selector Name is provided, but the 292 evaluation of the referenced selector results in an error, and 293 evaluation of the default selector also results in an error, both the 294 initial error and the default selector errors are reported within 295 separate elements. One element will include 296 the "selector" attribute set to "default"', and the other will 297 include the "selector" attribute set to the Selector Name identified 298 in the email. 300 3.3. Element 302 The element is OPTIONAL and is only REQUIRED if the 303 attributes as described below are included in the Report. The 304 element is a null element that contains the following 305 attributes: 307 "evidence-date" (OPTIONAL): A [RFC5322]-formatted date expression 308 indicating when the evidence document was evaluated. Evaluators 309 MAY periodically evaluate Evidence Documents and locally cache the 310 results for some period of time before re-evaluating them. 312 "evidence-issuer" (OPTIONAL): The issuer of the Evidence Document 313 retrieved and evaluated. 315 "evidence-type" (OPTIONAL): The type of Evidence Document retrieved 316 and evaluated. 318 "evidence-url" (OPTIONAL; REQUIRED if the "a=" field is 319 populated): The URL defined by the "a=" field within the BIMI record 320 pointing to the authority Evidence Document. If the field exists 321 and is populated, but evaluation of the field results in errors 322 during parsing or retrieval, the attribute is set to the value of 323 the "a=" field, and the appropriate set of "evidence-error-" 324 elements (defined below) are populated). 326 3.4. Element 328 All errors to be reported MUST be included within the 329 element which is within the element. Within the 330 element are one or more elements containing the error data aggregated 331 as described below. If there are no errors within a reporting 332 period, the element MUST NOT exist in the Report. 334 The count of non-zero errors being reported MUST be grouped by the 335 logical tuple: 337 ERROR-NAME:class:type 339 Where ERROR-NAME is an element named one of: 341 * "assertion" 342 * "evidence" 343 * "indicator" 344 * "undefined" 346 The "class" for each error tuple is set to one of: 348 "temp" If the Evaluator determines that the error is temporary (e.g. 349 a recoverable error such as a DNS query timeout when trying to 350 retrieve the resource), the Evaluator MAY rely on a previously 351 cached result and SHOULD set the class of the error to "temp". 352 Doing so indicates the Evaluator will try again in the future for 353 updated results. For example, a temporary error may cause an 354 Evaluator to stop processing BIMI for a single message, but try 355 again for the next message it receives from the domain. 357 "perm" If the Evaluator determines that the error is permanent (e.g. 358 the resource is successfully retrieved, but is non-conformant), 359 the Evaluator SHOULD set the class to "perm". Doing so indicates 360 the Evaluator MAY stop evaluating BIMI for all messages from the 361 specified domain until additional information becomes available. 363 The "type" component of the tuple is defined for the specific error 364 elements in their descriptions below. 366 There MUST only be one instance of a specific error tuple per Report, 367 each of which aggregates the count of errors associated with that 368 tuple during the report period. There MAY be multiple error elements 369 with the same name, but the tuples MUST be differentiated by distinct 370 element attributes. 372 For example, the element may contain two error 373 elements. One error element may contain a "class=temp" 374 attribute, while the other may contain a "class=perm" attribute. 375 Each of which aggregates the count of the specified class of errors. 377 3.4.1. Errors Element 379 The errors element is OPTIONAL and is only REQUIRED if 380 there are assertion errors to report. The error element 381 encloses a positive natural number indicating the count of assertion 382 errors encountered during the reporting period for the set of element 383 attributes indicating the class, type, and (optionally) description: 385 "class" Attribute: Set to either "temp" or "perm" depending upon 386 whether the Evaluator is treating the errors as temporary or 387 permanent. 389 "type" Attribute: Set to one of: 391 * "retrieval" if the Evaluator was unable to successfully retrieve 392 the assertion record (e.g. receiving a DNS RCODE:3 when trying to 393 retrieve the selector) 395 * "parsing" if one or more fields in the BIMI assertion record fails 396 to parse (e.g. the value in the "l=" or "a=" fields contain 397 unexpected characters) 399 "description" Attribute (OPTIONAL): Free-form text provided by the 400 Evaluator indicating any specific details they believe useful to 401 understanding the error(s). The element SHOULD contain no more 402 than 256 characters. 404 3.4.2. Errors Element 406 The errors element is OPTIONAL and is only REQUIRED if 407 there are evidence errors to report. The error element 408 encloses a positive natural number indicating the count of evidence 409 errors encountered during the reporting period for the set of element 410 attributes indicating the class, type, and (optionally) description: 412 "class" Attribute: Set to either "temp" or "perm" depending upon 413 whether the Evaluator is treating the errors as temporary or 414 permanent. 416 "type" Attribute: Set to one of: 418 * "retrieval" if the Evaluator was unable to successfully retrieve 419 the authority evidence document (e.g. receiving a DNS RCODE:3 when 420 trying to retrieve the document) 422 * "parsing" if the authority evidence document in the BIMI record 423 fails to parse (e.g. the URI identified in the BIMI record 424 contains invalid characters) 426 * "validation" if the retrieved authority evidence document fails to 427 validate (e.g. the retrieved X.509 [RFC5280] certificate fails to 428 validate) 430 * "expired" if the authority evidence document has expired (e.g. the 431 retrieved X.509 certificate expiration date has passed at the time 432 of validation) 434 * "revoked" if the authority evidence document has been reported as 435 being revoked (e.g. the X.509 certificate being evaluated, or any 436 in its progenitor chain, have been reported to the issuer's 437 Certificate Revocation List) 439 * "policy" if the Evaluator determines that, even if the authority 440 evidence document is technically validated, they have additional 441 information that may impact the evaluation (e.g. the Evaluator has 442 a local policy that doesn't recognize the issuing authority, the 443 evidence type is deemed insufficient, etc.) 445 "description" Attribute: Free-form text provided by the Evaluator 446 indicating any specific details they believe useful to 447 understanding the error(s). The element SHOULD contain no more 448 than 256 characters. 450 3.4.3. Errors Element 452 The errors element is OPTIONAL and is only REQUIRED if 453 there are indicator errors to report. The errors element 454 encloses a positive natural number indicating the count of indicator 455 errors encountered during the reporting period for the set of element 456 attributes indicating the class, type, and (optionally) description: 458 "class" Attribute: Set to either "temp" or "perm" depending upon 459 whether the Evaluator is treating the errors as temporary or 460 permanent. 462 "type" Attribute: Set to one of: 464 * "retrieval" if the Evaluator was unable to successfully retrieve 465 the indicator (e.g. receiving a DNS RCODE:3 when trying to 466 retrieve the indicator) 468 * "parsing" if the indicator in the BIMI record fails to parse (e.g. 469 the indicator cannot be extracted from the presented evidence 470 document) 472 * "validation" if the Evaluator cannot validate that the indicator 473 can be used in the context of BIMI (e.g. the SVG document 474 referenced by the "l=" URI isn't a valid SVG Tiny Portable Secure 475 (SVG P/S) [I-D.svg-tiny-ps-abrotman] profile) 477 "description" (OPTIONAL): Free-form text provided by the Evaluator 478 indicating any specific details they believe useful to 479 understanding the error(s). The element SHOULD contain no more 480 than 256 characters 482 3.4.4. Errors Element 484 The errors element is OPTIONAL and SHOULD be used to 485 report errors that are not covered by other error elements. The 486 errors element encloses a positive natural number 487 indicating the count of undefined errors encountered during the 488 reporting period for the set of element attributes indicating the 489 class and (optionally) description: 491 "class" Attribute: Set to either "temp" or "perm" depending upon 492 whether the Evaluator is treating the error as temporary or 493 permanent. 495 "description" Attribute: Free-form text provided by the Evaluator 496 indicating any specific details they believe useful to 497 understanding the error(s). The element SHOULD contain no more 498 than 256 characters. 500 4. Acknowledgements 502 This document was informed by discussions with and/or contributions 503 from Arne Allisat, Kurt Andersen, Tom Bartel, Marcel Becker, Seth 504 Blank, Marc Bradshaw, Alex Brotman, Wei Chuang, Todd Herr, Neil 505 Kumaran, Hansen Lee, Thede Loder, Maddie McCaffrey, Alex Rubin, Len 506 Shneyder, and Matthew Vernhout. 508 5. IANA Considerations 510 This section will be filled out in more detail when the draft moves 511 toward completion. 513 6. Security Considerations 515 Security considerations related to this document are inherited from 516 those mentioned in [RFC7489] and [I-D.blank-ietf-bimi]. This section 517 will be filled out in more detail when the draft moves toward 518 completion. 520 7. On-going Discussions 522 * Can/Should the BIMI report data include information about MUA use 523 of BIMI images? 524 - Concerns about web bugs? 525 - What information would be provided? 526 - How is data aggregated? 528 8. References 530 8.1. Normative References 532 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 533 Requirement Levels", BCP 14, RFC 2119, 534 DOI 10.17487/RFC2119, March 1997, 535 . 537 [RFC5280] Cooper, D., Santesson, S., Farrell, S., Boeyen, S., 538 Housley, R., and W. Polk, "Internet X.509 Public Key 539 Infrastructure Certificate and Certificate Revocation List 540 (CRL) Profile", RFC 5280, DOI 10.17487/RFC5280, May 2008, 541 . 543 [RFC5322] Resnick, P., Ed., "Internet Message Format", RFC 5322, 544 DOI 10.17487/RFC5322, October 2008, 545 . 547 [RFC5598] Crocker, D., "Internet Mail Architecture", RFC 5598, 548 DOI 10.17487/RFC5598, July 2009, 549 . 551 [RFC7489] Kucherawy, M., Ed. and E. Zwicky, Ed., "Domain-based 552 Message Authentication, Reporting, and Conformance 553 (DMARC)", RFC 7489, DOI 10.17487/RFC7489, March 2015, 554 . 556 [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 557 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, 558 May 2017, . 560 8.2. Informative References 562 [I-D.blank-ietf-bimi] 563 Blank, S., Goldstein, P., Loder, T., Zink, T., and M. 564 Bradshaw, "Brand Indicators for Message Identification 565 (BIMI)", Work in Progress, Internet-Draft, draft-blank- 566 ietf-bimi-02, 9 March 2021, 567 . 570 [I-D.svg-tiny-ps-abrotman] 571 Brotman, A. and J. T. Adams, "SVG Tiny Portable/Secure", 572 Work in Progress, Internet-Draft, draft-svg-tiny-ps- 573 abrotman-01, 9 March 2021, 574 . 577 [RFC1983] Malkin, G., Ed., "Internet Users' Glossary", FYI 18, 578 RFC 1983, DOI 10.17487/RFC1983, August 1996, 579 . 581 Appendix A. Example RUA Report with BIMI 583 The following is an example DMARC RUA report with BIMI error 584 elements. 586 587 588 589 reporter.tld 590 info@reporter.tld 591 uniqueidentifier 592 593 1609459200M 594 1609545599 595 596 597 598 sender.tld 599 r 600 r 601

reject

602 reject? 603 100 604
605 606 607 192.0.2.1 608 10 609 610 none 611 pass 612 pass 613 614 615 616 sender.tld 617 618 619 620 sender.tld 621 pass 622 selector01 623 624 625 sender.tld 626 pass 627 628 629 630 631 632 634 635 636 1 638 639 640 641 642
644 Authors' Addresses 646 J. Trent Adams 647 Proofpoint 648 105 Edgeview Drive, Suite 440 649 Broomfield, CO 80021 650 United States of America 651 Email: tadams@proofpoint.com 653 Alex Brotman (ed) 654 Comcast, Inc. 655 Email: alex_brotman@comcast.com