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

reject

590 reject? 591 100 592
593 594 595 192.0.2.1 596 10 597 598 none 599 pass 600 pass 601 602 603 604 sender.tld 605 606 607 608 sender.tld 609 pass 610 selector01 611 612 613 sender.tld 614 pass 615 616 617 618 619 620 622 623 624 1 626 627 628 629 630
632 Author's Address 634 J. Trent Adams 635 Proofpoint 636 105 Edgeview Drive, Suite 440 637 Broomfield, CO 80021 638 United States of America 640 Email: tadams@proofpoint.com