-
Notifications
You must be signed in to change notification settings - Fork 19
/
reporting.xml
1343 lines (1232 loc) · 55.8 KB
/
reporting.xml
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE rfc SYSTEM 'rfc2629.dtd' []>
<rfc ipr="trust200902" category="std" docName="draft-ietf-uta-smtp-tlsrpt-23">
<?rfc toc="yes"?>
<?rfc symrefs="yes"?>
<?rfc sortrefs="yes"?>
<?rfc compact="yes"?>
<?rfc subcompact="no"?>
<?rfc private=""?>
<?rfc topblock="yes"?>
<?rfc comments="no"?>
<front>
<title abbrev="SMTP-TLSRPT">SMTP TLS Reporting</title>
<author initials="D." surname="Margolis" fullname="Daniel Margolis">
<organization>Google, Inc</organization>
<address>
<postal>
<street></street>
<city></city>
<code></code>
<country></country>
<region></region>
</postal>
<phone></phone>
<email>dmargolis@google.com</email>
<uri></uri>
</address>
</author>
<author initials="A." surname="Brotman" fullname="Alexander Brotman">
<organization>Comcast, Inc</organization>
<address>
<postal>
<street></street>
<city></city>
<code></code>
<country></country>
<region></region>
</postal>
<phone></phone>
<email>alex_brotman@comcast.com</email>
<uri></uri>
</address>
</author>
<author initials="B." surname="Ramakrishnan" fullname="Binu Ramakrishnan">
<organization>Yahoo!, Inc</organization>
<address>
<postal>
<street></street>
<city></city>
<code></code>
<country></country>
<region></region>
</postal>
<phone></phone>
<email>rbinu@oath.com</email>
<uri></uri>
</address>
</author>
<author initials="J." surname="Jones" fullname="Janet Jones">
<organization>Microsoft, Inc</organization>
<address>
<postal>
<street></street>
<city></city>
<code></code>
<country></country>
<region></region>
</postal>
<phone></phone>
<email>janet.jones@microsoft.com</email>
<uri></uri>
</address>
</author>
<author initials="M." surname="Risher" fullname="Mark Risher">
<organization>Google, Inc</organization>
<address>
<postal>
<street></street>
<city></city>
<code></code>
<country></country>
<region></region>
</postal>
<phone></phone>
<email>risher@google.com</email>
<uri></uri>
</address>
</author>
<date year="2018" month="June" day="14"/>
<area>Applications</area>
<workgroup>Using TLS in Applications</workgroup>
<keyword></keyword>
<abstract>
<t>A number of protocols exist for establishing encrypted channels between
SMTP Mail Transfer Agents, including STARTTLS, DANE TLSA, and MTA-STS.
These protocols can fail due to misconfiguration or active attack,
leading to undelivered messages or delivery over unencrypted or
unauthenticated channels. This document describes a reporting mechanism
and format by which sending systems can share statistics and specific
information about potential failures with recipient domains. Recipient
domains can then use this information to both detect potential attacks and
diagnose unintentional misconfigurations.
</t>
</abstract>
</front>
<middle>
<section anchor="introduction" title="Introduction">
<t>The STARTTLS extension to SMTP <xref target="RFC3207"/> allows SMTP clients and hosts
to establish secure SMTP sessions over TLS. The protocol design uses an
approach that has come to be known as "Opportunistic Security" (OS)
<xref target="RFC7435"/>. This method maintains interoperability with clients that do
not support STARTTLS, but means that any attacker could potentially
eavesdrop on a session. An attacker could perform a downgrade or
interception attack by deleting parts of the SMTP session (such as the
"250 STARTTLS" response) or redirect the entire SMTP session (perhaps
by overwriting the resolved MX record of the delivery domain).
</t>
<t>Because such "downgrade attacks" are not necessarily apparent to the
receiving MTA, this document defines a mechanism for sending domains to
report on failures at multiple stages of the MTA-to-MTA conversation.
</t>
<t>Recipient domains may also use the mechanisms defined by MTA-STS
<xref target="I-D.ietf-uta-mta-sts"/> or DANE <xref target="RFC6698"/> to
publish additional encryption and authentication requirements; this
document defines a mechanism for sending domains that are compatible
with MTA-STS or DANE to share success and failure statistics with
recipient domains.
</t>
<t>Specifically, this document defines a reporting schema that covers
failures in routing, DNS resolution, STARTTLS negotiation, and both
DANE <xref target="RFC6698"/> and MTA-STS <xref target="I-D.ietf-uta-mta-sts"/> policy validation
errors, and a standard TXT record that recipient domains can use to
indicate where reports in this format should be sent. The report can
also serve as a heartbeat that systems are successfully negotiating
TLS during sessions as expected.
</t>
<t>This document is intended as a companion to the specification for SMTP
MTA Strict Transport Security <xref target="I-D.ietf-uta-mta-sts"/>, as well as adds
reporting abilities for those implementing DANE <xref target="RFC7672"/>.
</t>
<section anchor="terminology" title="Terminology">
<t>The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD",
"SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" in this
document are to be interpreted as described in [BCP 14] <xref target="RFC2119"/>
<xref target="RFC8174"/> when, and only when, they appear in all capitals, as shown here.
</t>
<t>We also define the following terms for further use in this document:
</t>
<t>
<list style="symbols">
<t>MTA-STS Policy: A mechanism by which administrators can specify the expected
TLS availability, presented identity, and desired actions for a given
email recipient domain. MTA-STS is defined in <xref target="I-D.ietf-uta-mta-sts"/>.</t>
<t>DANE Policy: A mechanism by which administrators can use DNSSEC
to commit an MTA to support STARTTLS and to publish criteria to
be used to validate its presented certificates. DANE for SMTP
is defined in [RFC7672], with the base specification in [RFC6698]
(updated in [RFC7671].</t>
<t>TLSRPT Policy: A policy specifying the endpoint to which sending MTAs
should deliver reports.</t>
<t>Policy Domain: The domain against which an MTA-STS or DANE Policy
is defined. For MTA-STS this is typically the same as the envelope
recipient domain [RFC5321], but when mail is routed to a "smarthost"
gateway by local policy, the "smarthost" domain name is used instead.
For DANE the Policy Domain is the "TLSA base domain" of the receiving
SMTP server as described in <eref target="Section 2.2.3">RFC7672</eref> and <eref target="Section 3">RFC6698</eref>.</t>
<t>Sending MTA: The MTA initiating the relay of an email message.</t>
<t>Aggregate Report URI (rua): A comma-separated list of locations where
the report is to be submitted.</t>
</list>
</t>
</section>
</section>
<section anchor="related-technologies" title="Related Technologies">
<t>
<list style="symbols">
<t>This document is intended as a companion to the specification for SMTP
MTA Strict Transport Security <xref target="I-D.ietf-uta-mta-sts"/>.</t>
<t>SMTP-TLSRPT defines a mechanism for sending domains that are
compatible with MTA-STS or DANE to share success and failure
statistics with recipient domains. DANE is defined in <xref target="RFC6698"/> and
MTA-STS is defined in <xref target="I-D.ietf-uta-mta-sts"/>.</t>
</list>
</t>
</section>
<section anchor="reporting-policy" title="Reporting Policy">
<t>A domain publishes a record to its DNS indicating that it wishes to
receive reports. These SMTP TLSRPT policies are distributed via DNS from
the Policy Domain's zone, as TXT records (similar to DMARC policies)
under the name <spanx style="verb">_smtp._tls</spanx>. For example, for the Policy Domain
<spanx style="verb">example.com</spanx>, the recipient's TLSRPT policy can be retrieved from
<spanx style="verb">_smtp._tls.example.com</spanx>.
</t>
<t>Policies consist of the following directives:
</t>
<t>
<list style="symbols">
<t><spanx style="verb">v</spanx>: This document defines version 1 of TLSRPT, for which this value MUST be
equal to <spanx style="verb">TLSRPTv1</spanx>. Other versions may be defined in later documents.</t>
<t><spanx style="verb">rua</spanx>: A URI specifying the endpoint to which aggregate information
about policy validation results should be sent (see
<xref target="reporting-schema"/>, "Reporting Schema", for more information). Two
URI schemes are supported: <spanx style="verb">mailto</spanx> and <spanx style="verb">https</spanx>. As with DMARC
<xref target="RFC7489"/>, the policy domain can specify a comma-separated list of
URIs.</t>
<t>In the case of <spanx style="verb">https</spanx>, reports should be submitted via POST
(<xref target="RFC7231"/>) to the specified URI. Report submitters MAY ignore
certificate validation errors when submitting reports via https.</t>
<t>In the case of <spanx style="verb">mailto</spanx>, reports should be submitted to the specified email
address (<xref target="RFC6068"/>). When sending failure reports via SMTP, sending MTAs
MUST deliver reports despite any TLS-related failures and SHOULD NOT include
this SMTP session in the next report. When sending failure reports via HTTPS,
sending MTAs MAY deliver reports despite any TLS-related faliures. This may
mean that the reports are delivered in the clear. Reports sent via SMTP MUST
contain a valid DKIM <xref target="RFC6376"/> signature by the reporting domain. Reports
lacking such a signature MUST be ignored by the recipient. DKIM signatures
must not use the "l=" attribute to limit the body length used in the
signature. The DKIM TXT record must contain the appropriate service type
declaration, <spanx style="verb">s=tlsrpt</spanx>, and if not present the receiving system SHOULD ignore
reports signed using this record.</t>
</list>
</t>
<t>The formal definition of the <spanx style="verb">_smtp._tls</spanx> TXT record, defined using
<xref target="RFC5234"/> & <xref target="RFC7405"/>, is as follows:
</t>
<figure align="center"><artwork align="center">
tlsrpt-record = tlsrpt-version 1*(field-delim tlsrpt-field)
[field-delim]
field-delim = *WSP ";" *WSP
tlsrpt-field = tlsrpt-rua / ; Note that the
tlsrpt-extension ; tlsrpt-rua record is
; required.
tlsrpt-version = %s"v=TLSRPTv1"
tlsrpt-rua = %s"rua="
tlsrpt-uri *(*WSP "," *WSP tlsrpt-uri)
tlsrpt-uri = URI
; "URI" is imported from [RFC3986];
; commas (ASCII 0x2C), exclamation
; points (ASCII 0x21), and semicolons
; (ASCII 0x3B) MUST be encoded
tlsrpt-extension = tlsrpt-ext-name "=" tlsrpt-ext-value
tlsrpt-ext-name = (ALPHA / DIGIT) *31(ALPHA /
DIGIT / "_" / "-" / ".")
tlsrpt-ext-value = 1*(%x21-3A / %x3C / %x3E-7E)
; chars excluding "=", ";", SP, and control
; chars
</artwork></figure>
<t>If multiple TXT records for <spanx style="verb">_smtp._tls</spanx> are returned by the resolver,
records which do not begin with <spanx style="verb">v=TLSRPTv1;</spanx> are discarded. If the
number of resulting records is not one, senders MUST assume the
recipient domain does not implement TLSRPT. If the resulting TXT record
contains multiple strings (as described in Section 3.1.3 of <xref target="RFC4408"/>),
then the record MUST be treated as if those strings are concatenated
together without adding spaces.
</t>
<t>The record supports the abillity to declare more than one rua, and if
there exists more than one, the reporter MAY attempt to deliver to
each of the supported rua destinations. A receiver MAY opt to only
attempt delivery to one of the endpoints, however the report SHOULD NOT
be considered successfully delivered until one of the endpoints accepts
delivery of the report.
</t>
<t>Parsers MUST accept TXT records which are syntactically valid (i.e.
valid key-value pairs separated by semi-colons) and implementing a
superset of this specification, in which case unknown fields SHALL be
ignored.
</t>
<section anchor="example-reporting-policy" title="Example Reporting Policy">
<section anchor="report-using-mailto" title="Report using MAILTO">
<figure align="center"><artwork align="center">
_smtp._tls.example.com. IN TXT \
"v=TLSRPTv1;rua=mailto:reports@example.com"
</artwork></figure>
</section>
<section anchor="report-using-https" title="Report using HTTPS">
<figure align="center"><artwork align="center">
_smtp._tls.example.com. IN TXT \
"v=TLSRPTv1; \
rua=https://reporting.example.com/v1/tlsrpt"
</artwork></figure>
</section>
</section>
</section>
<section anchor="reporting-schema" title="Reporting Schema">
<t>The report is composed as a plain text file encoded in the I-JSON format
(<xref target="RFC7493"/>).
</t>
<t>Aggregate reports contain the following fields:
</t>
<t>
<list style="symbols">
<t>Report metadata:
<list style="symbols">
<t>The organization responsible for the report</t>
<t>Contact information for one or more responsible parties for the
contents of the report</t>
<t>A unique identifier for the report</t>
<t>The reporting date range for the report</t>
</list></t>
<t>Policy, consisting of:
<list style="symbols">
<t>One of the following policy types: (1) The MTA-STS policy applied
(as a string) (2) The DANE TLSA record applied (as a string, with
each RR entry of the RRset listed and separated by a semicolon) (3)
The literal string <spanx style="verb">no-policy-found</spanx>, if neither a DANE nor MTA-STS
policy could be found.</t>
<t>The domain for which the policy is applied</t>
<t>The MX host</t>
</list></t>
<t>Aggregate counts, comprising result type, sending MTA IP, receiving
MTA hostname, session count, and an optional additional information
field containing a URI for recipients to review further information on
a failure type.</t>
</list>
</t>
<t>Note that the failure types are non-exclusive; an aggregate report may
contain overlapping <spanx style="verb">counts</spanx> of failure types when a single send attempt
encountered multiple errors. Reporters may report multiple applied
policies (for example, an MTA-STS policy and a DANE TLSA record for the
same domain and MX). Because of this, even in the case where only a single
policy was applied, the "policies" field of the report body MUST be an array and
not a singular value.
</t>
<t>In the case of multiple failure types, the <spanx style="verb">failure-details</spanx> array
would contain multiple entries. Each entry would have its own set of
infomation pertaining to that failure type.
</t>
<section anchor="report-timeframe" title="Report Time-frame">
<t>The report SHOULD cover a full day, from 0000-2400 UTC. This should
allow for easier correlation of failure events. To avoid a Denial of
Service against the system processing the reports, the reports should be
delivered after some delay, perhaps several hours.
</t>
<t>As an example, a sending site might want to introduce a random delay of up
to four hours:
</t>
<figure align="center"><artwork align="center">
func generate_sleep_delay() {
min_delay = 1
max_delay = 14400
rand = random(min_delay,max_delay)
return rand
}
func generate_report(policy_domain) {
do_rpt_work(policy_domain)
send_rpt(policy_domain)
}
func generate_tlsrpt() {
sleep(generate_sleep_delay())
for policy_domain in list_of_tlsrpt_enabled_domains {
generate_report(policy_domain)
}
}
</artwork></figure>
<t>A sending site might wish to introduce a random delay per destination
site, up to four hours:
</t>
<figure align="center"><artwork align="center">
func generate_sleep_delay() {
min_delay = 1
max_delay = 14400
rand = random(min_delay,max_delay)
return rand
}
func generate_report(policy_domain) {
sleep(generate_sleep_delay())
do_rpt_work(policy_domain)
send_rpt(policy_domain)
}
func generate_tlsrpt() {
for policy_domain in list_of_tlsrpt_enabled_domains {
generate_report(policy_domain)
}
}
</artwork></figure>
</section>
<section anchor="delivery-summary" title="Delivery Summary">
<section anchor="success-count" title="Success Count">
<t>
<list style="symbols">
<t><spanx style="verb">total-successful-session-count</spanx>: This indicates that the sending MTA
was able to successfully negotiate a policy-compliant TLS connection,
and serves to provide a "heartbeat" to receiving domains that reporting
is functional and tabulating correctly. This field contains an
aggregate count of successful connections for the reporting system.
<vspace/></t>
</list>
</t>
</section>
<section anchor="failure-count" title="Failure Count">
<t>
<list style="symbols">
<t><spanx style="verb">total-failure-session-count</spanx>: This indicates that the sending MTA was
unable to successfully establish a connection with the receiving platform.
<xref target="result-types"/>, "Result Types", will elaborate on the failed
negotiation attempts. This field contains an aggregate count of
failed connections.</t>
</list>
</t>
</section>
</section>
<section anchor="result-types" title="Result Types">
<t>The list of result types will start with the minimal set below, and is
expected to grow over time based on real-world experience. The initial
set is:
</t>
<section anchor="negotiation-failures" title="Negotiation Failures">
<t>
<list style="symbols">
<t><spanx style="verb">starttls-not-supported</spanx>: This indicates that the recipient MX did not
support STARTTLS.</t>
<t><spanx style="verb">certificate-host-mismatch</spanx>: This indicates that the certificate
presented did not adhere to the constraints specified in the MTA-STS
or DANE policy, e.g. if the MX hostname does not match any identities
listed in the Subject Alternate Name (SAN) <xref target="RFC5280"/>.</t>
<t><spanx style="verb">certificate-expired</spanx>: This indicates that the certificate has
expired.</t>
<t><spanx style="verb">certificate-not-trusted</spanx>: This a label that covers multiple
certificate related failures that include, but not limited to errors
such as untrusted/unknown CAs, certificate name constraints,
certificate chain errors etc. When using this declaration, the
reporting MTA SHOULD utilize the <spanx style="verb">failure-reason-code</spanx> to provide more
information to the receiving entity.</t>
<t><spanx style="verb">validation-failure</spanx>: This indicates a general failure for a reason
not matching a category above. When using this declaration, the
reporting MTA SHOULD utilize the <spanx style="verb">failure-reason-code</spanx> to provide more
information to the receiving entity.</t>
</list>
</t>
</section>
<section anchor="policy-failures" title="Policy Failures">
<section anchor="danespecific-policy-failures" title="DANE-specific Policy Failures">
<t>
<list style="symbols">
<t><spanx style="verb">tlsa-invalid</spanx>: This indicates a validation error in the TLSA record
associated with a DANE policy. None of the records in the RRset were
found to be valid.</t>
<t><spanx style="verb">dnssec-invalid</spanx>: This would indicate that no valid records were
returned from the recursive resolver. The request returned with
SERVFAIL for the requested TLSA record.</t>
<t><spanx style="verb">dane-required</spanx>: This indicates that the sending system is
configured to require DANE TLSA records for all the MX hosts
of the destination domain, but no DNSSEC-validated TLSA records
were present for the MX host that is the subject of the report.
Mandatory DANE for SMTP is described in section 6 of <xref target="RFC7672"/>.
Such policies may be created by mutual agreement between two
organizations that frequently exchange sensitive content via
email.</t>
</list>
</t>
</section>
<section anchor="mtastsspecific-policy-failures" title="MTA-STS-specific Policy Failures">
<t>
<list style="symbols">
<t><spanx style="verb">sts-policy-invalid</spanx>: This indicates a validation error for the
overall MTA-STS policy.</t>
<t><spanx style="verb">sts-webpki-invalid</spanx>: This indicates that the MTA-STS policy could not
be authenticated using PKIX validation.
<vspace/></t>
</list>
</t>
</section>
</section>
<section anchor="general-failures" title="General Failures">
<t>When a negotiation failure can not be categorized into one of the
"Negotiation Failures" stated above, the reporter SHOULD use the
<spanx style="verb">validation-failure</spanx> category. As TLS grows and becomes more complex,
new mechanisms may not be easily categorized. This allows for a generic
feedback category. When this category is used, the reporter SHOULD also
use the <spanx style="verb">failure-reason-code</spanx> to give some feedback to the receiving
entity. This is intended to be a short text field, and the contents of
the field should be an error code or error text, such as
"X509_V_ERR_UNHANDLED_CRITICAL_CRL_EXTENSION".
</t>
</section>
<section anchor="transient-failures" title="Transient Failures">
<t>Transient errors due to too-busy network, TCP timeouts, etc. are not
required to be reported.
</t>
</section>
</section>
<section anchor="json-report-schema" title="JSON Report Schema">
<t>The JSON schema is derived from the HPKP JSON schema <xref target="RFC7469"/> (cf.
Section 3)
</t>
<figure align="center" title="JSON Report Format
"><artwork align="center">
{
"organization-name": organization-name,
"date-range": {
"start-datetime": date-time,
"end-datetime": date-time
},
"contact-info": email-address,
"report-id": report-id,
"policies": [{
"policy": {
"policy-type": policy-type,
"policy-string": policy-string,
"policy-domain": domain,
"mx-host": mx-host-pattern
},
"summary": {
"total-successful-session-count": total-successful-session-count,
"total-failure-session-count": total-failure-session-count
},
"failure-details": [
{
"result-type": result-type,
"sending-mta-ip": ip-address,
"receiving-mx-hostname": receiving-mx-hostname,
"receiving-mx-helo": receiving-mx-helo,
"receiving-ip": receiving-ip,
"failed-session-count": failed-session-count,
"additional-information": additional-info-uri,
"failure-reason-code": failure-reason-code
}
]
}
]
}
</artwork></figure>
<t>
<list style="symbols">
<t><spanx style="verb">organization-name</spanx>: The name of the organization responsible for the
report. It is provided as a string.</t>
<t><spanx style="verb">date-time</spanx>: The date-time indicates the start- and end-times for the
report range. It is provided as a string formatted according to
Section 5.6, "Internet Date/Time Format", of <xref target="RFC3339"/>. The report
should be for a full UTC day, 0000-2400.</t>
<t><spanx style="verb">email-address</spanx>: The contact information for a responsible party of
the report. It is provided as a string formatted according to Section
3.4.1, "Addr-Spec", of <xref target="RFC5321"/>.</t>
<t><spanx style="verb">report-id</spanx>: A unique identifier for the report. Report authors may
use whatever scheme they prefer to generate a unique identifier. It is
provided as a string.</t>
<t><spanx style="verb">policy-type</spanx>: The type of policy that was applied by the sending
domain. Presently, the only three valid choices are <spanx style="verb">tlsa</spanx>, <spanx style="verb">sts</spanx>,
and the literal string <spanx style="verb">no-policy-found</spanx>. It is provided as a string.</t>
<t><spanx style="verb">policy-string</spanx>: An encoding of the applied policy as a JSON array of
strings, whether TLSA record (<xref target="RFC6698"/> section 2.3) or MTA-STS
policy. Examples follow in the next section.</t>
<t><spanx style="verb">domain</spanx>: The Policy Domain is the domain against which the MTA-STS or
DANE policy is defined. In the case of Internationalized Domain Names
(<xref target="RFC5891"/>), the domain MUST consist of the Punycode-encoded
A-labels (<xref target="RFC3492"/>) and not the U-labels.</t>
<t><spanx style="verb">mx-host-pattern</spanx>: The pattern of MX hostnames from the applied
policy. It is provided as a string, and is interpreted in the same
manner as the "Checking of Wildcard Certificates" rules in Section
6.4.3 of <xref target="RFC6125"/>. In the case of Internationalized Domain Names
(<xref target="RFC5891"/>), the domain MUST consist of the Punycode-encoded
A-labels (<xref target="RFC3492"/>) and not the U-labels.</t>
<t><spanx style="verb">result-type</spanx>: A value from <xref target="result-types"/>, "Result Types", above.</t>
<t><spanx style="verb">ip-address</spanx>: The IP address of the sending MTA that attempted the
STARTTLS connection. It is provided as a string representation of an
IPv4 (see below) or IPv6 (<xref target="RFC5952"/>) address in dot-decimal or
colon-hexadecimal notation.</t>
<t><spanx style="verb">receiving-mx-hostname</spanx>: The hostname of the receiving MTA MX record
with which the sending MTA attempted to negotiate a STARTTLS
connection.</t>
<t><spanx style="verb">receiving-mx-helo</spanx>: (optional) The HELO or EHLO string from the
banner announced during the reported session.</t>
<t><spanx style="verb">receiving-ip</spanx>: The destination IP address that was using when
creating the outbound session. It is provided as a string
representation of an IPv4 (see below) or IPv6 (<xref target="RFC5952"/>) address
in dot-decimal or colon-hexadecimal notation.</t>
<t><spanx style="verb">total-successful-session-count</spanx>: The aggregate count (integer, encoded as a
JSON number) of successfully negotiated TLS-enabled connections to the
receiving site.</t>
<t><spanx style="verb">total-failure-session-count</spanx>: The aggregate count (integer, encoded as a JSON
number) of failures to negotiate a TLS-enabled connection to the receiving
site.</t>
<t><spanx style="verb">failed-session-count</spanx>: The number of (attempted) sessions that match
the relevant <spanx style="verb">result-type</spanx> for this section (integer, encoded as a JSON
number).</t>
<t><spanx style="verb">additional-info-uri</spanx>: An optional URI <xref target="RFC3986"/> pointing to
additional information around the relevant <spanx style="verb">result-type</spanx>. For example,
this URI might host the complete certificate chain presented during an
attempted STARTTLS session.</t>
<t><spanx style="verb">failure-reason-code</spanx>: A text field to include a TLS-related error
code or error message.
<vspace/></t>
</list>
</t>
<t>For report purposes, an IPv4 Address is defined via the following ABNF:
</t>
<figure align="center"><artwork align="center">
IPv4address = dec-octet "." dec-octet "." dec-octet "." dec-octet
dec-octet = DIGIT ; 0-9
/ %x31-39 DIGIT ; 10-99
/ "1" 2DIGIT ; 100-199
/ "2" %x30-34 DIGIT ; 200-249
/ "25" %x30-35 ; 250-255
</artwork></figure>
</section>
<section anchor="policy-samples" title="Policy Samples">
<t>Part of the report body includes the policy that is applied when attemping
relay to the destination.
</t>
<t>For DANE TLSA policies, this is a JSON array of strings each representing the
RDATA of a single TLSA resource record as a space-separated list of its four
TLSA fields; the fields are in presentation format (defined in <xref target="RFC6698"/>
Section 2.2) with no internal spaces or grouping parentheses:
</t>
<figure align="center"><artwork align="center">
[
"3 0 1 1F850A337E6DB9C609C522D136A475638CC43E1ED424F8EEC8513D747D1D085D",
"3 0 1 12350A337E6DB9C6123522D136A475638CC43E1ED424F8EEC8513D747D1D1234"
]
</artwork></figure>
<t>For MTA-STS policies, this is an array of JSON strings that represents the
policy that is declared by the receiving site, including any errors that may be
present. Note that where there are multiple "mx" values, they must be listed
as separate "mx" elements in the policy array, rather as a single nested "mx"
sub-array.
</t>
<figure align="center"><artwork align="center">
[
"version: STSv1",
"mode: testing",
"mx: mx1.example.com",
"mx: mx2.example.com",
"mx: mx.backup-example.com",
"max_age: 604800"
]
</artwork></figure>
</section>
</section>
<section anchor="report-delivery" title="Report Delivery">
<t>Reports can be delivered either as an email message via SMTP or via HTTP
POST.
</t>
<section anchor="report-filename" title="Report Filename">
<t>The filename is RECOMMENDED to be constructed using the following ABNF:
</t>
<figure align="center"><artwork align="center">
filename = sender "!" policy-domain "!" begin-timestamp
"!" end-timestamp [ "!" unique-id ] "." extension
unique-id = 1*(ALPHA / DIGIT)
sender = domain ; From the [RFC5321] that is used
; as the domain for the `contact-info`
; address in the report body
policy-domain = domain
begin-timestamp = 1*DIGIT
; seconds since 00:00:00 UTC January 1, 1970
; indicating start of the time range contained
; in the report
end-timestamp = 1*DIGIT
; seconds since 00:00:00 UTC January 1, 1970
; indicating end of the time range contained
; in the report
extension = "json" / "json.gz"
</artwork></figure>
<t>The extension MUST be "json" for a plain JSON file, or "json.gz" for a
JSON file compressed using GZIP.
</t>
<t>"unique-id" allows an optional unique ID generated by the Sending MTA to
distinguish among multiple reports generated simultaneously by different
sources within the same Policy Domain. For example, this is a possible
filename for a compressed report to the Policy Domain "example.net"
from the Sending MTA "mail.sndr.example.com":
</t>
<t><spanx style="verb">mail.sndr.example.com!example.net!1470013207!1470186007!001.json.gz</spanx>
</t>
</section>
<section anchor="compression" title="Compression">
<t>The report SHOULD be subjected to GZIP <xref target="RFC1952"/> compression for both email
and HTTPS transport. Declining to apply compression can cause the report to
be too large for a receiver to process (a commonly observed receiver
limit is ten megabytes); compressing the file increases the chances of
acceptance of the report at some compute cost.
</t>
</section>
<section anchor="email-transport" title="Email Transport">
<t>The report MAY be delivered by email. To make the reports
machine-parsable for the receivers, we define a top-level media type
<spanx style="verb">multipart/report</spanx> with a new parameter <spanx style="verb">report-type="tlsrpt"</spanx>. Inside
it, there are two parts: The first part is human readable, typically
<spanx style="verb">text/plain</spanx>, and the second part is machine readable with a new media
type defined called <spanx style="verb">application/tlsrpt+json</spanx>. If compressed, the
report should use the media type <spanx style="verb">application/tlsrpt+gzip</spanx>.
</t>
<t>In addition, the following two new top level message header fields are
defined:
</t>
<t><spanx style="verb">TLS-Report-Domain: Receiver-Domain</spanx>
</t>
<t><spanx style="verb">TLS-Report-Submitter: Sender-Domain</spanx>
</t>
<t>The <spanx style="verb">TLS-Report-Submitter</spanx> value MUST match the value found in the
<xref target="RFC5321"/> domain from the <spanx style="verb">contact-info</spanx> from the report body. These
message headers MUST be included and should allow for easy searching
for all reports submitted by a report domain or a particular submitter,
for example in IMAP <xref target="RFC3501"/>:
</t>
<t><spanx style="verb">s SEARCH HEADER "TLS-Report-Domain" "example.com"</spanx>
</t>
<t>It is presumed that the aggregate reporting address will be equipped to
process new message header fields and extract MIME parts with the
prescribed media type and filename, and ignore the rest. These
additional headers SHOULD be included in the DKIM <xref target="RFC6376"/> signature
for the message.
</t>
<t>The <xref target="RFC5322"/>.Subject field for report submissions SHOULD conform to
the following ABNF:
</t>
<figure align="center"><artwork align="center">
tlsrpt-subject = %s"Report" FWS ; "Report"
%s"Domain:" FWS ; "Domain:"
domain-name FWS ; per [RFC6376]
%s"Submitter:" FWS ; "Submitter:"
domain-name FWS ; per [RFC6376]
%s"Report-ID:" FWS ; "Report-ID:
"<" id-left "@" id-right ">" ; per [RFC5322]
[CFWS] ; per [RFC5322]
; (as with FWS)
</artwork></figure>
<t>The first domain-name indicates the DNS domain name about which the
report was generated. The second domain-name indicates the DNS domain
name representing the Sending MTA generating the report. The purpose
of the Report-ID: portion of the field is to enable the Policy Domain
to identify and ignore duplicate reports that might be sent by a
Sending MTA.
</t>
<t>For instance, this is a possible Subject field for a report to the
Policy Domain "example.net" from the Sending MTA
"mail.sender.example.com". It is line-wrapped as allowed
by <xref target="RFC5322"/>:
</t>
<figure align="center"><artwork align="center">
Subject: Report Domain: example.net
Submitter: mail.sender.example.com
Report-ID: <735ff.e317+bf22029@mailexample.net>
</artwork></figure>
<section anchor="example-report" title="Example Report">
<figure align="center"><artwork align="center">
From: tlsrpt@mail.sender.example.com
Date: Fri, May 09 2017 16:54:30 -0800
To: mts-sts-tlsrpt@example.net
Subject: Report Domain: example.net
Submitter: mail.sender.example.com
Report-ID: <735ff.e317+bf22029@example.net>
TLS-Report-Domain: example.net
TLS-Report-Submitter: mail.sender.example.com
MIME-Version: 1.0
Content-Type: multipart/report; report-type="tlsrpt";
boundary="----=_NextPart_000_024E_01CC9B0A.AFE54C00"
Content-Language: en-us
This is a multipart message in MIME format.
------=_NextPart_000_024E_01CC9B0A.AFE54C00
Content-Type: text/plain; charset="us-ascii"
Content-Transfer-Encoding: 7bit
This is an aggregate TLS report from mail.sender.example.com
------=_NextPart_000_024E_01CC9B0A.AFE54C00
Content-Type: application/tlsrpt+gzip
Content-Transfer-Encoding: base64
Content-Disposition: attachment;
filename="mail.sender.example!example.com!
1013662812!1013749130.json.gz"
<gzipped content of report>
------=_NextPart_000_024E_01CC9B0A.AFE54C00--
...
</artwork></figure>
<t>Note that, when sending failure reports via SMTP, sending MTAs MUST NOT
honor MTA-STS or DANE TLSA failures.
</t>
</section>
</section>
<section anchor="https-transport" title="HTTPS Transport">
<t>The report MAY be delivered by POST to HTTPS. If compressed, the report
SHOULD use the media type <spanx style="verb">application/tlsrpt+gzip</spanx>, and
<spanx style="verb">application/tlsrpt+json</spanx> otherwise (see section <xref target="iana-considerations"/>,
"IANA Considerations").
</t>
<t>The receiving system MUST return a "successful" response from its HTTPS
server, typically a 200 or 201 HTTP code <xref target="RFC7321"/>. Other codes could
indicate a delivery failure, and may be retried as per local sender policy.
The receiving system is not expected to process reports at receipt time, and
MAY store them for processing at a later time.
</t>
</section>
<section anchor="delivery-retry" title="Delivery Retry">
<t>In the event of a delivery failure, regardless of the delivery method, a
sender SHOULD attempt redelivery for up to 24hrs after the initial
attempt. As previously stated the reports are optional, so while it is
ideal to attempt redelivery, it is not required. If multiple retries
are attempted, ideally they SHOULD be done with exponential backoff.
</t>
</section>
<section anchor="metadata-variances" title="Metadata Variances">
<t>As stated above, there are a variable number of ways to declare
information about the data therein. If any of items declared via
subject or filename disagree with the report, the report MUST be
considered the authoritative source.
</t>
</section>
</section>
<section anchor="iana-considerations" title="IANA Considerations">
<t>The following are the IANA considerations discussed in this document.
</t>
<section anchor="message-headers" title="Message headers">
<t>Below is the Internet Assigned Numbers Authority (IANA) Permanent
Message Header Field registration information per <xref target="RFC3864"/>.
</t>
<figure align="center"><artwork align="center">
Header field name: TLS-Report-Domain
Applicable protocol: mail
Status: standard
Author/Change controller: IETF
Specification document(s): this one
Header field name: TLS-Report-Submitter
Applicable protocol: mail
Status: standard
Author/Change controller: IETF
Specification document(s): this one
</artwork></figure>
</section>
<section anchor="report-type" title="Report Type">
<t>This document creates a new registry for "report-type" parameter to
the Content-Type header field for the "multipart/report" top-level media
type defined in <xref target="RFC6522"/>.
</t>
<t>The registry name is "Report Type Registry", and the procedure for
updating the registry will be "Specification Required".
</t>
<t>An entry in this registry should contain:
</t>
<t>
<list style="symbols">
<t>the report-type being registered</t>
<t>one or more registered media-types that can be used with this report-type</t>
<t>the document containing the registration action</t>
<t>an optional comment</t>
</list>
</t>
<t>The initial entries are:
</t>
<t>Report-Type: tlsrpt
Media Type: application/tlsrpt+gzip, application/tlsrpt+json
Registered By: [RFCXXXX]
Comment: Media types suitable for use with this report-type are defined in Sections 6.4 and 6.5 of [RFCXXXX]
</t>
<t>Report-Type: disposition-notification
Media Type: message/disposition-notification
Registered By: <xref target="RFC8098"/> Section 10
</t>
<t>Report-Type: disposition-notification
Media Type: message/global-disposition-notification
Registered By: <xref target="RFC6533"/> Section 6
</t>
<t>Report-Type: delivery-status
Media Type: message/delivery-status
Registered By: <xref target="RFC3464"/> Appendix D
</t>
<t>Report-Type: delivery-status
Media Type: message/global-delivery-status
Registered By: <xref target="RFC6533"/> Section 6
</t>
</section>
<section anchor="gzip-media-type-suffix" title="+gzip Media Type Suffix">
<t>This document registers a new media type suffix "+gzip". The GZIP
format is a public domain, cross-platform, interoperable file
storage and transfer format, specified in <xref target="RFC1952"/>; it
supports compression and is used as the underlying representation
by a variety of file formats. The media type "application/gzip"
has been registered for such files. The suffix "+gzip" MAY be
used with any media type whose representation follows that
established for "application/gzip". The media type structured
syntax suffix registration form follows:
</t>
<t>Type name: GZIP file storage and transfer format
</t>
<t>+suffix: +gzip
</t>
<t>References: <xref target="RFC1952"/><xref target="RFC6713"/>
</t>
<t>Encoding considerations: GZIP is a binary encoding.
</t>
<t>Fragment identifier considerations: The syntax and semantics
of fragment identifiers specified for
+gzip SHOULD be as specified for "application/gzip". (At
publication of this document, there is no fragment identification
syntax defined for "application/gzip".) The syntax and semantics
for fragment identifiers for a specific "xxx/yyy+gzip" SHOULD be
processed as follows:
</t>
<figure align="center"><artwork align="center">
For cases defined in +gzip, where the fragment identifier
resolves per the +gzip rules, then process as specified in
+gzip.
For cases defined in +gzip, where the fragment identifier does
not resolve per the +gzip rules, then process as specified in
"xxx/yyy+gzip".
For cases not defined in +gzip, then process as specified in
"xxx/yyy+gzip".
</artwork></figure>
<t>Interoperability considerations: n/a
</t>
<t>Security considerations: GZIP format doesn't provide confidentiality protection.
Integrity protection is provided by an Adler-32 checksum, which is not
cryptographically strong. See also security considerations of <xref target="RFC6713"/>.
Each individual media type registered with a +gzip suffix can have additional
security considerations. Additionally, GZIP objects can contain multiple
files and associated paths. File paths must be validated when the files
are extracted; a malicious file path could otherwise cause the extractor
to overwrite application or system files.
</t>
<t>Contact: art@ietf.org
</t>
<t>Author/Change controller: Internet Engineering Task Force
(mailto:iesg@ietf.org).
</t>
</section>