-
Notifications
You must be signed in to change notification settings - Fork 19
/
Copy pathreporting.txt
1792 lines (1159 loc) · 64.6 KB
/
reporting.txt
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
Using TLS in Applications D. Margolis
Internet-Draft Google, Inc
Intended status: Standards Track A. Brotman
Expires: December 16, 2018 Comcast, Inc
B. Ramakrishnan
Yahoo!, Inc
J. Jones
Microsoft, Inc
M. Risher
Google, Inc
June 14, 2018
SMTP TLS Reporting
draft-ietf-uta-smtp-tlsrpt-23
Abstract
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.
Status of This Memo
This Internet-Draft is submitted in full conformance with the
provisions of BCP 78 and BCP 79.
Internet-Drafts are working documents of the Internet Engineering
Task Force (IETF). Note that other groups may also distribute
working documents as Internet-Drafts. The list of current Internet-
Drafts is at http://datatracker.ietf.org/drafts/current/.
Internet-Drafts are draft documents valid for a maximum of six months
and may be updated, replaced, or obsoleted by other documents at any
time. It is inappropriate to use Internet-Drafts as reference
material or to cite them other than as "work in progress."
This Internet-Draft will expire on December 16, 2018.
Margolis, et al. Expires December 16, 2018 [Page 1]
Internet-Draft SMTP-TLSRPT June 2018
Copyright Notice
Copyright (c) 2018 IETF Trust and the persons identified as the
document authors. All rights reserved.
This document is subject to BCP 78 and the IETF Trust's Legal
Provisions Relating to IETF Documents
(http://trustee.ietf.org/license-info) in effect on the date of
publication of this document. Please review these documents
carefully, as they describe your rights and restrictions with respect
to this document. Code Components extracted from this document must
include Simplified BSD License text as described in Section 4.e of
the Trust Legal Provisions and are provided without warranty as
described in the Simplified BSD License.
Table of Contents
1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3
1.1. Terminology . . . . . . . . . . . . . . . . . . . . . . . 4
2. Related Technologies . . . . . . . . . . . . . . . . . . . . 4
3. Reporting Policy . . . . . . . . . . . . . . . . . . . . . . 5
3.1. Example Reporting Policy . . . . . . . . . . . . . . . . 7
3.1.1. Report using MAILTO . . . . . . . . . . . . . . . . . 7
3.1.2. Report using HTTPS . . . . . . . . . . . . . . . . . 7
4. Reporting Schema . . . . . . . . . . . . . . . . . . . . . . 7
4.1. Report Time-frame . . . . . . . . . . . . . . . . . . . . 8
4.2. Delivery Summary . . . . . . . . . . . . . . . . . . . . 9
4.2.1. Success Count . . . . . . . . . . . . . . . . . . . . 9
4.2.2. Failure Count . . . . . . . . . . . . . . . . . . . . 9
4.3. Result Types . . . . . . . . . . . . . . . . . . . . . . 9
4.3.1. Negotiation Failures . . . . . . . . . . . . . . . . 10
4.3.2. Policy Failures . . . . . . . . . . . . . . . . . . . 10
4.3.3. General Failures . . . . . . . . . . . . . . . . . . 11
4.3.4. Transient Failures . . . . . . . . . . . . . . . . . 11
4.4. JSON Report Schema . . . . . . . . . . . . . . . . . . . 11
4.5. Policy Samples . . . . . . . . . . . . . . . . . . . . . 14
5. Report Delivery . . . . . . . . . . . . . . . . . . . . . . . 15
5.1. Report Filename . . . . . . . . . . . . . . . . . . . . . 15
5.2. Compression . . . . . . . . . . . . . . . . . . . . . . . 16
5.3. Email Transport . . . . . . . . . . . . . . . . . . . . . 16
5.3.1. Example Report . . . . . . . . . . . . . . . . . . . 17
5.4. HTTPS Transport . . . . . . . . . . . . . . . . . . . . . 18
5.5. Delivery Retry . . . . . . . . . . . . . . . . . . . . . 19
5.6. Metadata Variances . . . . . . . . . . . . . . . . . . . 19
6. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 19
6.1. Message headers . . . . . . . . . . . . . . . . . . . . . 19
6.2. Report Type . . . . . . . . . . . . . . . . . . . . . . . 19
6.3. +gzip Media Type Suffix . . . . . . . . . . . . . . . . . 20
Margolis, et al. Expires December 16, 2018 [Page 2]
Internet-Draft SMTP-TLSRPT June 2018
6.4. application/tlsrpt+json Media Type . . . . . . . . . . . 21
6.5. application/tlsrpt+gzip Media Type . . . . . . . . . . . 23
6.6. STARTTLS Validation Result Types . . . . . . . . . . . . 24
7. Security Considerations . . . . . . . . . . . . . . . . . . . 24
8. Privacy Considerations . . . . . . . . . . . . . . . . . . . 26
9. References . . . . . . . . . . . . . . . . . . . . . . . . . 26
9.1. Normative References . . . . . . . . . . . . . . . . . . 26
9.2. Informative References . . . . . . . . . . . . . . . . . 28
9.3. URIs . . . . . . . . . . . . . . . . . . . . . . . . . . 29
Appendix A. Example Reporting Policy . . . . . . . . . . . . . . 30
A.1. Report using MAILTO . . . . . . . . . . . . . . . . . . . 30
A.2. Report using HTTPS . . . . . . . . . . . . . . . . . . . 30
Appendix B. Example JSON Report . . . . . . . . . . . . . . . . 30
Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 32
1. Introduction
The STARTTLS extension to SMTP [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) [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).
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.
Recipient domains may also use the mechanisms defined by MTA-STS
[I-D.ietf-uta-mta-sts] or DANE [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.
Specifically, this document defines a reporting schema that covers
failures in routing, DNS resolution, STARTTLS negotiation, and both
DANE [RFC6698] and MTA-STS [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.
Margolis, et al. Expires December 16, 2018 [Page 3]
Internet-Draft SMTP-TLSRPT June 2018
This document is intended as a companion to the specification for
SMTP MTA Strict Transport Security [I-D.ietf-uta-mta-sts], as well as
adds reporting abilities for those implementing DANE [RFC7672].
1.1. Terminology
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] [RFC2119] [RFC8174] when, and only when, they appear in all
capitals, as shown here.
We also define the following terms for further use in this document:
o 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
[I-D.ietf-uta-mta-sts].
o 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].
o TLSRPT Policy: A policy specifying the endpoint to which sending
MTAs should deliver reports.
o 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 RFC7672 [1]
and RFC6698 [2].
o Sending MTA: The MTA initiating the relay of an email message.
o Aggregate Report URI (rua): A comma-separated list of locations
where the report is to be submitted.
2. Related Technologies
o This document is intended as a companion to the specification for
SMTP MTA Strict Transport Security [I-D.ietf-uta-mta-sts].
o SMTP-TLSRPT defines a mechanism for sending domains that are
compatible with MTA-STS or DANE to share success and failure
Margolis, et al. Expires December 16, 2018 [Page 4]
Internet-Draft SMTP-TLSRPT June 2018
statistics with recipient domains. DANE is defined in [RFC6698]
and MTA-STS is defined in [I-D.ietf-uta-mta-sts].
3. Reporting Policy
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 "_smtp._tls". For example, for the Policy
Domain "example.com", the recipient's TLSRPT policy can be retrieved
from "_smtp._tls.example.com".
Policies consist of the following directives:
o "v": This document defines version 1 of TLSRPT, for which this
value MUST be equal to "TLSRPTv1". Other versions may be defined
in later documents.
o "rua": A URI specifying the endpoint to which aggregate
information about policy validation results should be sent (see
Section 4, "Reporting Schema", for more information). Two URI
schemes are supported: "mailto" and "https". As with DMARC
[RFC7489], the policy domain can specify a comma-separated list of
URIs.
o In the case of "https", reports should be submitted via POST
([RFC7231]) to the specified URI. Report submitters MAY ignore
certificate validation errors when submitting reports via https.
o In the case of "mailto", reports should be submitted to the
specified email address ([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 [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, "s=tlsrpt", and if not present the receiving system
SHOULD ignore reports signed using this record.
The formal definition of the "_smtp._tls" TXT record, defined using
[RFC5234] & [RFC7405], is as follows:
Margolis, et al. Expires December 16, 2018 [Page 5]
Internet-Draft SMTP-TLSRPT June 2018
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
If multiple TXT records for "_smtp._tls" are returned by the
resolver, records which do not begin with "v=TLSRPTv1;" 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 [RFC4408]), then the record MUST be treated as if
those strings are concatenated together without adding spaces.
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.
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.
Margolis, et al. Expires December 16, 2018 [Page 6]
Internet-Draft SMTP-TLSRPT June 2018
3.1. Example Reporting Policy
3.1.1. Report using MAILTO
_smtp._tls.example.com. IN TXT \
"v=TLSRPTv1;rua=mailto:reports@example.com"
3.1.2. Report using HTTPS
_smtp._tls.example.com. IN TXT \
"v=TLSRPTv1; \
rua=https://reporting.example.com/v1/tlsrpt"
4. Reporting Schema
The report is composed as a plain text file encoded in the I-JSON
format ([RFC7493]).
Aggregate reports contain the following fields:
o Report metadata:
* The organization responsible for the report
* Contact information for one or more responsible parties for the
contents of the report
* A unique identifier for the report
* The reporting date range for the report
o Policy, consisting of:
* 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 "no-policy-found", if
neither a DANE nor MTA-STS policy could be found.
* The domain for which the policy is applied
* The MX host
o 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.
Margolis, et al. Expires December 16, 2018 [Page 7]
Internet-Draft SMTP-TLSRPT June 2018
Note that the failure types are non-exclusive; an aggregate report
may contain overlapping "counts" 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.
In the case of multiple failure types, the "failure-details" array
would contain multiple entries. Each entry would have its own set of
infomation pertaining to that failure type.
4.1. Report Time-frame
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.
As an example, a sending site might want to introduce a random delay
of up to four hours:
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)
}
}
A sending site might wish to introduce a random delay per destination
site, up to four hours:
Margolis, et al. Expires December 16, 2018 [Page 8]
Internet-Draft SMTP-TLSRPT June 2018
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)
}
}
4.2. Delivery Summary
4.2.1. Success Count
o "total-successful-session-count": 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.
4.2.2. Failure Count
o "total-failure-session-count": This indicates that the sending MTA
was unable to successfully establish a connection with the
receiving platform. Section 4.3, "Result Types", will elaborate
on the failed negotiation attempts. This field contains an
aggregate count of failed connections.
4.3. Result Types
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:
Margolis, et al. Expires December 16, 2018 [Page 9]
Internet-Draft SMTP-TLSRPT June 2018
4.3.1. Negotiation Failures
o "starttls-not-supported": This indicates that the recipient MX did
not support STARTTLS.
o "certificate-host-mismatch": 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) [RFC5280].
o "certificate-expired": This indicates that the certificate has
expired.
o "certificate-not-trusted": 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 "failure-reason-
code" to provide more information to the receiving entity.
o "validation-failure": This indicates a general failure for a
reason not matching a category above. When using this
declaration, the reporting MTA SHOULD utilize the "failure-reason-
code" to provide more information to the receiving entity.
4.3.2. Policy Failures
4.3.2.1. DANE-specific Policy Failures
o "tlsa-invalid": 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.
o "dnssec-invalid": This would indicate that no valid records were
returned from the recursive resolver. The request returned with
SERVFAIL for the requested TLSA record.
o "dane-required": 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 [RFC7672].
Such policies may be created by mutual agreement between two
organizations that frequently exchange sensitive content via
email.
Margolis, et al. Expires December 16, 2018 [Page 10]
Internet-Draft SMTP-TLSRPT June 2018
4.3.2.2. MTA-STS-specific Policy Failures
o "sts-policy-invalid": This indicates a validation error for the
overall MTA-STS policy.
o "sts-webpki-invalid": This indicates that the MTA-STS policy could
not be authenticated using PKIX validation.
4.3.3. General Failures
When a negotiation failure can not be categorized into one of the
"Negotiation Failures" stated above, the reporter SHOULD use the
"validation-failure" 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 "failure-reason-code" 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".
4.3.4. Transient Failures
Transient errors due to too-busy network, TCP timeouts, etc. are not
required to be reported.
4.4. JSON Report Schema
The JSON schema is derived from the HPKP JSON schema [RFC7469] (cf.
Section 3)
Margolis, et al. Expires December 16, 2018 [Page 11]
Internet-Draft SMTP-TLSRPT June 2018
{
"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
}
]
}
]
}
JSON Report Format
o "organization-name": The name of the organization responsible for
the report. It is provided as a string.
o "date-time": 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 [RFC3339]. The
report should be for a full UTC day, 0000-2400.
Margolis, et al. Expires December 16, 2018 [Page 12]
Internet-Draft SMTP-TLSRPT June 2018
o "email-address": 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 [RFC5321].
o "report-id": 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.
o "policy-type": The type of policy that was applied by the sending
domain. Presently, the only three valid choices are "tlsa",
"sts", and the literal string "no-policy-found". It is provided
as a string.
o "policy-string": An encoding of the applied policy as a JSON array
of strings, whether TLSA record ([RFC6698] section 2.3) or MTA-STS
policy. Examples follow in the next section.
o "domain": The Policy Domain is the domain against which the MTA-
STS or DANE policy is defined. In the case of Internationalized
Domain Names ([RFC5891]), the domain MUST consist of the Punycode-
encoded A-labels ([RFC3492]) and not the U-labels.
o "mx-host-pattern": 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 [RFC6125]. In the case of Internationalized
Domain Names ([RFC5891]), the domain MUST consist of the Punycode-
encoded A-labels ([RFC3492]) and not the U-labels.
o "result-type": A value from Section 4.3, "Result Types", above.
o "ip-address": 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 ([RFC5952]) address in dot-decimal or
colon-hexadecimal notation.
o "receiving-mx-hostname": The hostname of the receiving MTA MX
record with which the sending MTA attempted to negotiate a
STARTTLS connection.
o "receiving-mx-helo": (optional) The HELO or EHLO string from the
banner announced during the reported session.
o "receiving-ip": 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 ([RFC5952]) address
in dot-decimal or colon-hexadecimal notation.
Margolis, et al. Expires December 16, 2018 [Page 13]
Internet-Draft SMTP-TLSRPT June 2018
o "total-successful-session-count": The aggregate count (integer,
encoded as a JSON number) of successfully negotiated TLS-enabled
connections to the receiving site.
o "total-failure-session-count": The aggregate count (integer,
encoded as a JSON number) of failures to negotiate a TLS-enabled
connection to the receiving site.
o "failed-session-count": The number of (attempted) sessions that
match the relevant "result-type" for this section (integer,
encoded as a JSON number).
o "additional-info-uri": An optional URI [RFC3986] pointing to
additional information around the relevant "result-type". For
example, this URI might host the complete certificate chain
presented during an attempted STARTTLS session.
o "failure-reason-code": A text field to include a TLS-related error
code or error message.
For report purposes, an IPv4 Address is defined via the following
ABNF:
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
4.5. Policy Samples
Part of the report body includes the policy that is applied when
attemping relay to the destination.
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 [RFC6698] Section 2.2) with no
internal spaces or grouping parentheses:
[
"3 0 1 1F850A337E6DB9C609C522D136A475638CC43E1ED424F8EEC8513D747D1D085D",
"3 0 1 12350A337E6DB9C6123522D136A475638CC43E1ED424F8EEC8513D747D1D1234"
]
For MTA-STS policies, this is an array of JSON strings that
represents the policy that is declared by the receiving site,
Margolis, et al. Expires December 16, 2018 [Page 14]
Internet-Draft SMTP-TLSRPT June 2018
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.
[
"version: STSv1",
"mode: testing",
"mx: mx1.example.com",
"mx: mx2.example.com",
"mx: mx.backup-example.com",
"max_age: 604800"
]
5. Report Delivery
Reports can be delivered either as an email message via SMTP or via
HTTP POST.
5.1. Report Filename
The filename is RECOMMENDED to be constructed using the following
ABNF:
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"
The extension MUST be "json" for a plain JSON file, or "json.gz" for
a JSON file compressed using GZIP.
Margolis, et al. Expires December 16, 2018 [Page 15]
Internet-Draft SMTP-TLSRPT June 2018
"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":
"mail.sndr.example.com!example.net!1470013207!1470186007!001.json.gz"
5.2. Compression
The report SHOULD be subjected to GZIP [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.
5.3. Email Transport
The report MAY be delivered by email. To make the reports machine-
parsable for the receivers, we define a top-level media type
"multipart/report" with a new parameter "report-type="tlsrpt"".
Inside it, there are two parts: The first part is human readable,
typically "text/plain", and the second part is machine readable with
a new media type defined called "application/tlsrpt+json". If
compressed, the report should use the media type "application/
tlsrpt+gzip".
In addition, the following two new top level message header fields
are defined:
"TLS-Report-Domain: Receiver-Domain"
"TLS-Report-Submitter: Sender-Domain"
The "TLS-Report-Submitter" value MUST match the value found in the
[RFC5321] domain from the "contact-info" 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 [RFC3501]:
"s SEARCH HEADER "TLS-Report-Domain" "example.com""
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 [RFC6376] signature
for the message.
Margolis, et al. Expires December 16, 2018 [Page 16]
Internet-Draft SMTP-TLSRPT June 2018
The [RFC5322].Subject field for report submissions SHOULD conform to
the following ABNF:
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)
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.
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
[RFC5322]:
Subject: Report Domain: example.net
Submitter: mail.sender.example.com
Report-ID: <735ff.e317+bf22029@mailexample.net>
5.3.1. Example Report
Margolis, et al. Expires December 16, 2018 [Page 17]
Internet-Draft SMTP-TLSRPT June 2018
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--
...
Note that, when sending failure reports via SMTP, sending MTAs MUST
NOT honor MTA-STS or DANE TLSA failures.
5.4. HTTPS Transport
The report MAY be delivered by POST to HTTPS. If compressed, the
report SHOULD use the media type "application/tlsrpt+gzip", and
"application/tlsrpt+json" otherwise (see section Section 6, "IANA
Considerations").
The receiving system MUST return a "successful" response from its