idnits 2.17.1 draft-ietf-httpbis-expect-ct-06.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 : ---------------------------------------------------------------------------- ** The abstract seems to contain references ([2], [3], [1]), which it shouldn't. Please replace those with straight textual mentions of the documents in question. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year -- The document date (June 29, 2018) is 2128 days in the past. Is this intentional? Checking references for intended status: Experimental ---------------------------------------------------------------------------- -- Looks like a reference, but probably isn't: '1' on line 904 -- Looks like a reference, but probably isn't: '2' on line 906 -- Looks like a reference, but probably isn't: '3' on line 908 -- Looks like a reference, but probably isn't: '4' on line 910 == Outdated reference: A later version (-42) exists of draft-ietf-trans-rfc6962-bis-27 ** Obsolete normative reference: RFC 6962 (Obsoleted by RFC 9162) ** Obsolete normative reference: RFC 7230 (Obsoleted by RFC 9110, RFC 9112) ** Obsolete normative reference: RFC 7234 (Obsoleted by RFC 9111) -- Obsolete informational reference (is this intentional?): RFC 5246 (Obsoleted by RFC 8446) Summary: 4 errors (**), 0 flaws (~~), 2 warnings (==), 6 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 HTTP E. Stark 3 Internet-Draft Google 4 Intended status: Experimental June 29, 2018 5 Expires: December 31, 2018 7 Expect-CT Extension for HTTP 8 draft-ietf-httpbis-expect-ct-06 10 Abstract 12 This document defines a new HTTP header field, named Expect-CT, that 13 allows web host operators to instruct user agents to expect valid 14 Signed Certificate Timestamps (SCTs) to be served on connections to 15 these hosts. When configured in enforcement mode, user agents (UAs) 16 will remember that hosts expect SCTs and will refuse connections that 17 do not conform to the UA's Certificate Transparency policy. When 18 configured in report-only mode, UAs will report the lack of valid 19 SCTs to a URI configured by the host, but will allow the connection. 20 By turning on Expect-CT, web host operators can discover 21 misconfigurations in their Certificate Transparency deployments and 22 ensure that misissued certificates accepted by UAs are discoverable 23 in Certificate Transparency logs. 25 Note to Readers 27 Discussion of this draft takes place on the HTTP working group 28 mailing list (ietf-http-wg@w3.org), which is archived at 29 https://lists.w3.org/Archives/Public/ietf-http-wg/ [1]. 31 Working Group information can be found at http://httpwg.github.io/ 32 [2]; source code and issues list for this draft can be found at 33 https://github.com/httpwg/http-extensions/labels/expect-ct [3]. 35 Status of This Memo 37 This Internet-Draft is submitted in full conformance with the 38 provisions of BCP 78 and BCP 79. 40 Internet-Drafts are working documents of the Internet Engineering 41 Task Force (IETF). Note that other groups may also distribute 42 working documents as Internet-Drafts. The list of current Internet- 43 Drafts is at https://datatracker.ietf.org/drafts/current/. 45 Internet-Drafts are draft documents valid for a maximum of six months 46 and may be updated, replaced, or obsoleted by other documents at any 47 time. It is inappropriate to use Internet-Drafts as reference 48 material or to cite them other than as "work in progress." 49 This Internet-Draft will expire on December 31, 2018. 51 Copyright Notice 53 Copyright (c) 2018 IETF Trust and the persons identified as the 54 document authors. All rights reserved. 56 This document is subject to BCP 78 and the IETF Trust's Legal 57 Provisions Relating to IETF Documents 58 (https://trustee.ietf.org/license-info) in effect on the date of 59 publication of this document. Please review these documents 60 carefully, as they describe your rights and restrictions with respect 61 to this document. Code Components extracted from this document must 62 include Simplified BSD License text as described in Section 4.e of 63 the Trust Legal Provisions and are provided without warranty as 64 described in the Simplified BSD License. 66 Table of Contents 68 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3 69 1.1. Requirements Language . . . . . . . . . . . . . . . . . . 4 70 1.2. Terminology . . . . . . . . . . . . . . . . . . . . . . . 4 71 2. Server and Client Behavior . . . . . . . . . . . . . . . . . 5 72 2.1. Response Header Field Syntax . . . . . . . . . . . . . . 5 73 2.1.1. The report-uri Directive . . . . . . . . . . . . . . 6 74 2.1.2. The enforce Directive . . . . . . . . . . . . . . . . 6 75 2.1.3. The max-age Directive . . . . . . . . . . . . . . . . 7 76 2.1.4. Examples . . . . . . . . . . . . . . . . . . . . . . 7 77 2.2. Server Processing Model . . . . . . . . . . . . . . . . . 7 78 2.2.1. HTTP-over-Secure-Transport Request Type . . . . . . . 8 79 2.2.2. HTTP Request Type . . . . . . . . . . . . . . . . . . 8 80 2.3. User Agent Processing Model . . . . . . . . . . . . . . . 8 81 2.3.1. Missing or Malformed Expect-CT Header Fields . . . . 8 82 2.3.2. Expect-CT Header Field Processing . . . . . . . . . . 8 83 2.3.3. Reporting . . . . . . . . . . . . . . . . . . . . . . 10 84 2.4. Evaluating Expect-CT Connections for CT Compliance . . . 10 85 2.4.1. Skipping CT compliance checks . . . . . . . . . . . . 11 86 3. Reporting Expect-CT Failure . . . . . . . . . . . . . . . . . 11 87 3.1. Generating a violation report . . . . . . . . . . . . . . 12 88 3.2. Sending a violation report . . . . . . . . . . . . . . . 13 89 3.3. Receiving a violation report . . . . . . . . . . . . . . 14 90 4. Security Considerations . . . . . . . . . . . . . . . . . . . 14 91 4.1. Maximum max-age . . . . . . . . . . . . . . . . . . . . . 15 92 4.2. Avoiding amplification attacks . . . . . . . . . . . . . 15 93 5. Privacy Considerations . . . . . . . . . . . . . . . . . . . 15 94 6. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 16 95 6.1. Header Field Registry . . . . . . . . . . . . . . . . . . 16 96 6.2. Media Types Registry . . . . . . . . . . . . . . . . . . 16 98 7. Usability Considerations . . . . . . . . . . . . . . . . . . 17 99 8. Authoring Considerations . . . . . . . . . . . . . . . . . . 17 100 9. References . . . . . . . . . . . . . . . . . . . . . . . . . 18 101 9.1. Normative References . . . . . . . . . . . . . . . . . . 18 102 9.2. Informative References . . . . . . . . . . . . . . . . . 19 103 9.3. URIs . . . . . . . . . . . . . . . . . . . . . . . . . . 19 104 Appendix A. Changes . . . . . . . . . . . . . . . . . . . . . . 20 105 A.1. Since -05 . . . . . . . . . . . . . . . . . . . . . . . . 20 106 A.2. Since -04 . . . . . . . . . . . . . . . . . . . . . . . . 20 107 A.3. Since -03 . . . . . . . . . . . . . . . . . . . . . . . . 20 108 A.4. Since -02 . . . . . . . . . . . . . . . . . . . . . . . . 20 109 A.5. Since -01 . . . . . . . . . . . . . . . . . . . . . . . . 20 110 A.6. Since -00 . . . . . . . . . . . . . . . . . . . . . . . . 20 111 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 21 113 1. Introduction 115 This document defines a new HTTP header field that enables UAs to 116 identify web hosts that expect the presence of Signed Certificate 117 Timestamps (SCTs) [I-D.ietf-trans-rfc6962-bis] in future Transport 118 Layer Security (TLS) [RFC5246] connections. 120 Web hosts that serve the Expect-CT HTTP header field are noted by the 121 UA as Known Expect-CT Hosts. The UA evaluates each connection to a 122 Known Expect-CT Host for compliance with the UA's Certificate 123 Transparency (CT) Policy. If the connection violates the CT Policy, 124 the UA sends a report to a URI configured by the Expect-CT Host and/ 125 or fails the connection, depending on the configuration that the 126 Expect-CT Host has chosen. 128 If misconfigured, Expect-CT can cause unwanted connection failures 129 (for example, if a host deploys Expect-CT but then switches to a 130 legitimate certificate that is not logged in Certificate Transparency 131 logs, or if a web host operator believes their certificate to conform 132 to all UAs' CT policies but is mistaken). Web host operators are 133 advised to deploy Expect-CT with caution, by using the reporting 134 feature and gradually increasing the interval where the UA remembers 135 the host as a Known Expect-CT Host. These precautions can help web 136 host operators gain confidence that their Expect-CT deployment is not 137 causing unwanted connection failures. 139 Expect-CT is a trust-on-first-use (TOFU) mechanism. The first time a 140 UA connects to a host, it lacks the information necessary to require 141 SCTs for the connection. Thus, the UA will not be able to detect and 142 thwart an attack on the UA's first connection to the host. Still, 143 Expect-CT provides value by 1) allowing UAs to detect the use of 144 unlogged certificates after the initial communication, and 2) 145 allowing web hosts to be confident that UAs are only trusting 146 publicly-auditable certificates. 148 1.1. Requirements Language 150 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 151 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 152 "OPTIONAL" in this document are to be interpreted as described in RFC 153 2119 [RFC2119]. 155 1.2. Terminology 157 Terminology is defined in this section. 159 o "Certificate Transparency Policy" is a policy defined by the UA 160 concerning the number, sources, and delivery mechanisms of Signed 161 Certificate Timestamps that are served on TLS connections. The 162 policy defines the properties of a connection that must be met in 163 order for the UA to consider it CT-qualified. 165 o "Certificate Transparency Qualified" describes a TLS connection 166 for which the UA has determined that a sufficient quantity and 167 quality of Signed Certificate Timestamps have been provided. 169 o "CT-qualified" is an abbreviation for "Certificate Transparency 170 Qualified". 172 o "CT Policy" is an abbreviation for "Certificate Transparency 173 Policy". 175 o "Effective Expect-CT Date" is the time at which a UA observed a 176 valid Expect-CT header field for a given host. 178 o "Expect-CT Host" is a conformant host implementing the HTTP server 179 aspects of Expect-CT. This means that an Expect-CT Host returns 180 the "Expect-CT" HTTP response header field in its HTTP response 181 messages sent over secure transport. The term "host" is 182 equivalent to "server" in this specification. 184 o "Known Expect-CT Host" is an Expect-CT Host that the UA has noted 185 as such. See Section 2.3.2.1 for particulars. 187 o UA is an acronym for "user agent". For the purposes of this 188 specification, a UA is an HTTP client application typically 189 actively manipulated by a user [RFC7230]. 191 o "Unknown Expect-CT Host" is an Expect-CT Host that the UA has not 192 noted. 194 2. Server and Client Behavior 196 2.1. Response Header Field Syntax 198 The "Expect-CT" response header field is a new field defined in this 199 specification. It is used by a server to indicate that UAs should 200 evaluate connections to the host emitting the header field for CT 201 compliance (Section 2.4). 203 Figure 1 describes the syntax (Augmented Backus-Naur Form) of the 204 header field, using the grammar defined in [RFC5234] and the rules 205 defined in Section 3.2 of [RFC7230]. 207 Expect-CT = #expect-ct-directive 208 expect-ct-directive = directive-name [ "=" directive-value ] 209 directive-name = token 210 directive-value = token / quoted-string 212 Figure 1: Syntax of the Expect-CT header field 214 Optional white space ("OWS") is used as defined in Section 3.2.3 of 215 [RFC7230]. "token" and "quoted-string" are used as defined in 216 Section 3.2.6 of [RFC7230]. 218 The directives defined in this specification are described below. 219 The overall requirements for directives are: 221 1. The order of appearance of directives is not significant. 223 2. A given directive MUST NOT appear more than once in a given 224 header field. Directives are either optional or required, as 225 stipulated in their definitions. 227 3. Directive names are case insensitive. 229 4. UAs MUST ignore any header fields containing directives, or other 230 header field value data, that do not conform to the syntax 231 defined in this specification. In particular, UAs must not 232 attempt to fix malformed header fields. 234 5. If a header field contains any directive(s) the UA does not 235 recognize, the UA MUST ignore those directives. 237 6. If the Expect-CT header field otherwise satisfies the above 238 requirements (1 through 5), the UA MUST process the directives it 239 recognizes. 241 2.1.1. The report-uri Directive 243 The OPTIONAL "report-uri" directive indicates the URI to which the UA 244 SHOULD report Expect-CT failures (Section 2.4). The UA POSTs the 245 reports to the given URI as described in Section 3. 247 The "report-uri" directive is REQUIRED to have a directive value, for 248 which the syntax is defined in Figure 2. 250 report-uri-value = absolute-URI 252 Figure 2: Syntax of the report-uri directive value 254 "absolute-URI" is defined in Section 4.3 of [RFC3986]. 256 Hosts may set "report-uri"s that use HTTP or HTTPS. If the scheme in 257 the "report-uri" is one that uses TLS (e.g., HTTPS), UAs MUST check 258 Expect-CT compliance when the host in the "report-uri" is a Known 259 Expect-CT Host; similarly, UAs MUST apply HSTS if the host in the 260 "report-uri" is a Known HSTS Host. 262 Note that the report-uri need not necessarily be in the same Internet 263 domain or web origin as the host being reported about. 265 UAs SHOULD make their best effort to report Expect-CT failures to the 266 "report-uri", but they may fail to report in exceptional conditions. 267 For example, if connecting to the "report-uri" itself incurs an 268 Expect-CT failure or other certificate validation failure, the UA 269 MUST cancel the connection. Similarly, if Expect-CT Host A sets a 270 "report-uri" referring to Expect-CT Host B, and if B sets a "report- 271 uri" referring to A, and if both hosts fail to comply to the UA's CT 272 Policy, the UA SHOULD detect and break the loop by failing to send 273 reports to and about those hosts. 275 UAs SHOULD limit the rate at which they send reports. For example, 276 it is unnecessary to send the same report to the same "report-uri" 277 more than once. 279 2.1.2. The enforce Directive 281 The OPTIONAL "enforce" directive is a valueless directive that, if 282 present (i.e., it is "asserted"), signals to the UA that compliance 283 to the CT Policy should be enforced (rather than report-only) and 284 that the UA should refuse future connections that violate its CT 285 Policy. When both the "enforce" directive and "report-uri" directive 286 (as defined in Figure 2) are present, the configuration is referred 287 to as an "enforce-and-report" configuration, signalling to the UA 288 both that compliance to the CT Policy should be enforced and that 289 violations should be reported. 291 2.1.3. The max-age Directive 293 The "max-age" directive specifies the number of seconds after the 294 reception of the Expect-CT header field during which the UA SHOULD 295 regard the host from whom the message was received as a Known Expect- 296 CT Host. 298 The "max-age" directive is REQUIRED to be present within an "Expect- 299 CT" header field. The "max-age" directive is REQUIRED to have a 300 directive value, for which the syntax (after quoted-string 301 unescaping, if necessary) is defined in Figure 3. 303 max-age-value = delta-seconds 304 delta-seconds = 1*DIGIT 306 Figure 3: Syntax of the max-age directive value 308 "delta-seconds" is used as defined in Section 1.2.1 of [RFC7234]. 310 2.1.4. Examples 312 The following three examples demonstrate valid Expect-CT response 313 header fields (where the second splits the directives into two field 314 instances): 316 Expect-CT: max-age=86400, enforce 318 Expect-CT: max-age=86400,enforce 319 Expect-CT: report-uri="https://foo.example/report" 321 Expect-CT: max-age=86400,report-uri="https://foo.example/report" 323 Figure 4: Examples of valid Expect-CT response header fields 325 2.2. Server Processing Model 327 This section describes the processing model that Expect-CT Hosts 328 implement. The model has 2 parts: (1) the processing rules for HTTP 329 request messages received over a secure transport (e.g., 330 authenticated, non-anonymous TLS); and (2) the processing rules for 331 HTTP request messages received over non-secure transports, such as 332 TCP. 334 2.2.1. HTTP-over-Secure-Transport Request Type 336 An Expect-CT Host includes an Expect-CT header field in its response. 337 The header field MUST satisfy the grammar specified in Section 2.1. 339 Establishing a given host as an Expect-CT Host, in the context of a 340 given UA, is accomplished as follows: 342 1. Over the HTTP protocol running over secure transport, by 343 correctly returning (per this specification) a valid Expect-CT 344 header field to the UA. 346 2. Through other mechanisms, such as a client-side preloaded Expect- 347 CT Host list. 349 2.2.2. HTTP Request Type 351 Expect-CT Hosts SHOULD NOT include the Expect-CT header field in HTTP 352 responses conveyed over non-secure transport. UAs MUST ignore any 353 Expect-CT header field received in an HTTP response conveyed over 354 non-secure transport. 356 2.3. User Agent Processing Model 358 The UA processing model relies on parsing domain names. Note that 359 internationalized domain names SHALL be canonicalized according to 360 the scheme in Section 10 of [RFC6797]. 362 The UA stores Known Expect-CT Hosts and their associated Expect-CT 363 directives. This data is collectively known as a host's "Expect-CT" 364 metadata". 366 2.3.1. Missing or Malformed Expect-CT Header Fields 368 If an HTTP response does not include an Expect-CT header field that 369 conforms to the grammar specified in Section 2.1, then the UA MUST 370 NOT update any Expect-CT metadata. 372 2.3.2. Expect-CT Header Field Processing 374 If the UA receives, over a secure transport, an HTTP response that 375 includes an Expect-CT header field conforming to the grammar 376 specified in Section 2.1, the UA MUST evaluate the connection on 377 which the header field was received for compliance with the UA's CT 378 Policy, and then process the Expect-CT header field as follows. 380 If the connection does not comply with the UA's CT Policy (i.e., the 381 connection is not CT-qualified), then the UA MUST NOT update any 382 Expect-CT metadata. If the header field includes a "report-uri" 383 directive, the UA SHOULD send a report to the specified "report-uri" 384 (Section 2.3.3). 386 If the connection complies with the UA's CT Policy (i.e., the 387 connection is CT-qualified), then the UA MUST either: 389 o Note the host as a Known Expect-CT Host if it is not already so 390 noted (see Section 2.3.2.1), or 392 o Update the UA's cached information for the Known Expect-CT Host if 393 the "enforce", "max-age", or "report-uri" header field value 394 directives convey information different from that already 395 maintained by the UA. If the "max-age" directive has a value of 396 0, the UA MUST remove its cached Expect-CT information if the host 397 was previously noted as a Known Expect-CT Host, and MUST NOT note 398 this host as a Known Expect-CT Host if it is not already noted. 400 2.3.2.1. Noting Expect-CT 402 Upon receipt of the Expect-CT response header field over an error- 403 free TLS connection (including the validation adding in Section 2.4), 404 the UA MUST note the host as a Known Expect-CT Host, storing the 405 host's domain name and its associated Expect-CT directives in non- 406 volatile storage. 408 To note a host as a Known Expect-CT Host, the UA MUST set its Expect- 409 CT metadata given in the most recently received valid Expect-CT 410 header field, as specified in Section 2.3.2.2. 412 For forward compatibility, the UA MUST ignore any unrecognized 413 Expect-CT header field directives, while still processing those 414 directives it does recognize. Section 2.1 specifies the directives 415 "enforce", "max-age", and "report-uri", but future specifications and 416 implementations might use additional directives. 418 2.3.2.2. Storage Model 420 If the substring matching the host production from the Request-URI 421 (of the message to which the host responded) does not congruently 422 match an existing Known Expect-CT Host's domain name, per the 423 matching procedure specified in Section 8.2 of [RFC6797], then the UA 424 MUST add this host to the Known Expect-CT Host cache. The UA caches: 426 o the Expect-CT Host's domain name, 428 o whether the "enforce" directive is present 429 o the Effective Expiration Date, which is the Effective Expect-CT 430 Date plus the value of the "max-age" directive. Alternatively, 431 the UA MAY cache enough information to calculate the Effective 432 Expiration Date. The Effective Expiration Date is calculated from 433 when the UA observed the Expect-CT header field and is independent 434 of when the response was generated. 436 o the value of the "report-uri" directive, if present. 438 If any other metadata from optional or future Expect-CT header 439 directives are present in the Expect-CT header field, and the UA 440 understands them, the UA MAY note them as well. 442 UAs MAY set an upper limit on the value of max-age, so that UAs that 443 have noted erroneous Expect-CT hosts (whether by accident or due to 444 attack) have some chance of recovering over time. If the server sets 445 a max-age greater than the UA's upper limit, the UA MAY behave as if 446 the server set the max-age to the UA's upper limit. For example, if 447 the UA caps max-age at 5,184,000 seconds (60 days), and an Expect-CT 448 Host sets a max- age directive of 90 days in its Expect-CT header 449 field, the UA MAY behave as if the max-age were effectively 60 days. 450 (One way to achieve this behavior is for the UA to simply store a 451 value of 60 days instead of the 90-day value provided by the Expect- 452 CT host.) 454 2.3.3. Reporting 456 If the UA receives, over a secure transport, an HTTP response that 457 includes an Expect-CT header field with a "report-uri" directive, and 458 the connection does not comply with the UA's CT Policy (i.e., the 459 connection is not CT-qualified), and the UA has not already sent an 460 Expect-CT report for this connection, then the UA SHOULD send a 461 report to the specified "report-uri" as specified in Section 3. 463 2.4. Evaluating Expect-CT Connections for CT Compliance 465 When a UA sets up a TLS connection, the UA determines whether the 466 host is a Known Expect-CT Host according to its Known Expect-CT Host 467 cache. An Expect-CT Host is "expired" if the effective expiration 468 date refers to a date in the past. The UA MUST ignore any expired 469 Expect-CT Hosts in its cache and not treat such hosts as Known 470 Expect-CT hosts. 472 When a UA connects to a Known Expect-CT Host using a TLS connection, 473 if the TLS connection has no errors, then the UA will apply an 474 additional correctness check: compliance with a CT Policy. A UA 475 should evaluate compliance with its CT Policy whenever connecting to 476 a Known Expect-CT Host, as soon as possible. However, the check can 477 be skipped for local policy reasons (as discussed in Section 2.4.1), 478 or in the event that other checks cause the UA to terminate the 479 connection before CT compliance is evaluated. For example, a Public 480 Key Pinning failure [RFC7469] could cause the UA to terminate the 481 connection before CT compliance is checked. Similarly, if the UA 482 terminates the connection due to an Expect-CT failure, this could 483 cause the UA to skip subsequent correctness checks. When the CT 484 compliance check is skipped or bypassed, Expect-CT reports 485 (Section 3) will not be sent. 487 When CT compliance is evaluted for a Known Expect-CT Host, the UA 488 MUST evaluate compliance when setting up the TLS session, before 489 beginning an HTTP conversation over the TLS channel. 491 If a connection to a Known Expect-CT Host violates the UA's CT policy 492 (i.e., the connection is not CT-qualified), and if the Known Expect- 493 CT Host's Expect-CT metadata indicates an "enforce" configuration, 494 the UA MUST treat the CT compliance failure as an error. 496 If a connection to a Known Expect-CT Host violates the UA's CT 497 policy, and if the Known Expect-CT Host's Expect-CT metadata includes 498 a "report-uri", the UA SHOULD send an Expect-CT report to that 499 "report-uri" (Section 3). 501 2.4.1. Skipping CT compliance checks 503 It is acceptable for a UA to skip CT compliance checks for some hosts 504 according to local policy. For example, a UA may disable CT 505 compliance checks for hosts whose validated certificate chain 506 terminates at a user-defined trust anchor, rather than a trust anchor 507 built-in to the UA (or underlying platform). 509 If the UA does not evaluate CT compliance, e.g., because the user has 510 elected to disable it, or because a presented certificate chain 511 chains up to a user-defined trust anchor, UAs SHOULD NOT send Expect- 512 CT reports. 514 3. Reporting Expect-CT Failure 516 When the UA attempts to connect to a Known Expect-CT Host and the 517 connection is not CT-qualified, the UA SHOULD report Expect-CT 518 failures to the "report-uri", if any, in the Known Expect-CT Host's 519 Expect-CT metadata. 521 When the UA receives an Expect-CT response header field over a 522 connection that is not CT-qualified, if the UA has not already sent 523 an Expect-CT report for this connection, then the UA SHOULD report 524 Expect-CT failures to the configured "report-uri", if any. 526 3.1. Generating a violation report 528 To generate a violation report object, the UA constructs a JSON 529 [RFC8259] object with the following keys and values: 531 o "date-time": the value for this key indicates the UTC time that 532 the UA observed the CT compliance failure. The value is a string 533 formatted according to Section 5.6, "Internet Date/Time Format", 534 of [RFC3339]. 536 o "hostname": the value is the hostname to which the UA made the 537 original request that failed the CT compliance check. The value 538 is provided as a string. 540 o "port": the value is the port to which the UA made the original 541 request that failed the CT compliance check. The value is 542 provided as an integer. 544 o "effective-expiration-date": the value indicates the Effective 545 Expiration Date (see Section 2.3.2.2) for the Expect-CT Host that 546 failed the CT compliance check, in UTC. The value is provided as 547 a string formatted according to Section 5.6 of [RFC3339] 548 ("Internet Date/Time Format"). 550 o "served-certificate-chain": the value is the certificate chain as 551 served by the Expect-CT Host during TLS session setup. The value 552 is provided as an array of strings, which MUST appear in the order 553 that the certificates were served; each string in the array is the 554 Privacy-Enhanced Mail (PEM) representation of each X.509 555 certificate as described in [RFC7468]. 557 o "validated-certificate-chain": the value is the certificate chain 558 as constructed by the UA during certificate chain verification. 559 (This may differ from the value of the "served-certificate-chain" 560 key.) The value is provided as an array of strings, which MUST 561 appear in the order matching the chain that the UA validated; each 562 string in the array is the Privacy-Enhanced Mail (PEM) 563 representation of each X.509 certificate as described in 564 [RFC7468]. 566 o "scts": the value represents the SCTs (if any) that the UA 567 received for the Expect-CT host and their validation statuses. 568 The value is provided as an array of JSON objects. The SCTs may 569 appear in any order. Each JSON object in the array has the 570 following keys: 572 * A "version" key, with an integer value. The UA MUST set this 573 value to "1" if the SCT is in the format defined in Section 3.2 574 of [RFC6962] and "2" if it is in the format defined in 575 Section 4.5 of [I-D.ietf-trans-rfc6962-bis]. 577 * The "status" key, with a string value that the UA MUST set to 578 one of the following values: "unknown" (indicating that the UA 579 does not have or does not trust the public key of the log from 580 which the SCT was issued), "valid" (indicating that the UA 581 successfully validated the SCT as described in Section 5.2 of 582 [RFC6962] or Section 8.2.3 of [I-D.ietf-trans-rfc6962-bis]), or 583 "invalid" (indicating that the SCT validation failed because 584 of, e.g., a bad signature). 586 * The "source" key, with a string value that indicates from where 587 the UA obtained the SCT, as defined in Section 3 of [RFC6962] 588 and Section 6 of [I-D.ietf-trans-rfc6962-bis]. The UA MUST set 589 the value to one of "tls-extension", "ocsp", or "embedded". 591 * The "serialized_sct" key, with a string value. If the value of 592 the "version" key is "1", the UA MUST set this value to the 593 base64 encoded [RFC4648] serialized 594 "SignedCertificateTimestamp" structure from Section 3.2 of 595 [RFC6962]. If the value of the "version" key is "2", the UA 596 MUST set this value to the base64 encoded [RFC4648] serialized 597 "TransItem" structure representing the SCT, as defined in 598 Section 4.5 of [I-D.ietf-trans-rfc6962-bis]. 600 o "failure-mode": the value indicates whether the Expect-CT report 601 was triggered by an Expect-CT policy in enforce or report-only 602 mode. The value is provided as a string. The UA MUST set this 603 value to "enforce" if the Expect-CT metadata indicates an 604 "enforce" configuration, and "report-only" otherwise. 606 o "test-report": the value is set to true if the report is being 607 sent by a testing client to verify that the reporting server 608 behaves correctly. The value is provided as a boolean, and MUST 609 be set to true if the report serves to test the server's behavior 610 and can be discarded. 612 3.2. Sending a violation report 614 The UA SHOULD report an Expect-CT failure when a connection to a 615 Known Expect-CT Host does not comply with the UA's CT Policy and the 616 host's Expect-CT metadata contains a "report-uri". Additionally, the 617 UA SHOULD report an Expect-CT failure when it receives an Expect-CT 618 header field which contains the "report-uri" directive over a 619 connection that does not comply with the UA's CT Policy. 621 The steps to report an Expect-CT failure are as follows. 623 1. Prepare a JSON object "report object" with the single key 624 "expect-ct-report", whose value is the result of generating a 625 violation report object as described in Section 3.1. 627 2. Let "report body" be the JSON stringification of "report object". 629 3. Let "report-uri" be the value of the "report-uri" directive in 630 the Expect-CT header field. 632 4. Send an HTTP POST request to "report-uri" with a "Content-Type" 633 header field of "application/expect-ct-report+json", and an 634 entity body consisting of "report body". 636 The UA MAY perform other operations as part of sending the HTTP POST 637 request, for example sending a CORS preflight as part of [FETCH]. 639 3.3. Receiving a violation report 641 Upon receiving an Expect-CT violation report, the report server MUST 642 respond with a 2xx (Successful) status code if it can parse the 643 request body as valid JSON and recognizes the hostname in the 644 "hostname" field of the report. If the report body cannot be parsed 645 or the report server does not expect to receive reports for the 646 hostname in the "hostname" field, the report server MUST respond with 647 a 4xx (Client Error) status code. 649 If the report's "test-report" key is set to true, the server MAY 650 discard the report without further processing but MUST still return a 651 2xx (Successful) status code. 653 4. Security Considerations 655 When UAs support the Expect-CT header field, it becomes a potential 656 vector for hostile header attacks against site owners. If a site 657 owner uses a certificate issued by a certificate authority which does 658 not embed SCTs nor serve SCTs via OCSP or TLS extension, a malicious 659 server operator or attacker could temporarily reconfigure the host to 660 comply with the UA's CT policy, and add the Expect-CT header field in 661 enforcing mode with a long "max-age". Implementing user agents would 662 note this as an Expect-CT Host (see Section 2.3.2.1). After having 663 done this, the configuration could then be reverted to not comply 664 with the CT policy, prompting failures. Note this scenario would 665 require the attacker to have substantial control over the 666 infrastructure in question, being able to obtain different 667 certificates, change server software, or act as a man-in-the-middle 668 in connections. 670 Site operators could themselves only cure this situation by one of: 671 reconfiguring their web server to transmit SCTs using the TLS 672 extension defined in Section 6.5 of [I-D.ietf-trans-rfc6962-bis], 673 obtaining a certificate from an alternative certificate authority 674 which provides SCTs by one of the other methods, or by waiting for 675 the user agents' persisted notation of this as an Expect-CT host to 676 reach its "max-age". User agents may choose to implement mechanisms 677 for users to cure this situation, as noted in Section 7. 679 4.1. Maximum max-age 681 There is a security trade-off in that low maximum values provide a 682 narrow window of protection for users that visit the Known Expect-CT 683 Host only infrequently, while high maximum values might result in a 684 denial of service to a UA in the event of a hostile header attack, or 685 simply an error on the part of the site-owner. 687 There is probably no ideal maximum for the "max-age" directive. 688 Since Expect-CT is primarily a policy-expansion and investigation 689 technology rather than an end-user protection, a value on the order 690 of 30 days (2,592,000 seconds) may be considered a balance between 691 these competing security concerns. 693 4.2. Avoiding amplification attacks 695 Another kind of hostile header attack uses the "report-uri" mechanism 696 on many hosts not currently exposing SCTs as a method to cause a 697 denial-of-service to the host receiving the reports. If some highly- 698 trafficked websites emitted a non-enforcing Expect-CT header field 699 with a "report-uri", implementing UAs' reports could flood the 700 reporting host. It is noted in Section 2.1.1 that UAs should limit 701 the rate at which they emit reports, but an attacker may alter the 702 Expect-CT header's fields to induce UAs to submit different reports 703 to different URIs to still cause the same effect. 705 5. Privacy Considerations 707 Expect-CT can be used to infer what Certificate Transparency policy 708 is in use, by attempting to retrieve specially-configured websites 709 which pass one user agents' policies but not another's. Note that 710 this consideration is true of UAs which enforce CT policies without 711 Expect-CT as well. 713 Additionally, reports submitted to the "report-uri" could reveal 714 information to a third party about which webpage is being accessed 715 and by which IP address, by using individual "report-uri" values for 716 individually-tracked pages. This information could be leaked even if 717 client-side scripting were disabled. 719 Implementations must store state about Known Expect-CT Hosts, and 720 hence which domains the UA has contacted. 722 Violation reports, as noted in Section 3, contain information about 723 the certificate chain that has violated the CT policy. In some 724 cases, such as organization-wide compromise of the end-to-end 725 security of TLS, this may include information about the interception 726 tools and design used by the organization that the organization would 727 otherwise prefer not be disclosed. 729 Because Expect-CT causes remotely-detectable behavior, it's advisable 730 that UAs offer a way for privacy-sensitive users to clear currently 731 noted Expect-CT hosts, and allow users to query the current state of 732 Known Expect-CT Hosts. 734 6. IANA Considerations 736 6.1. Header Field Registry 738 This document registers the "Expect-CT" header field in the "Message 739 Headers" registry located at https://www.iana.org/assignments/ 740 message-headers [4]. 742 Header field name: Expect-CT 744 Applicable protocol: http 746 Status: standard 748 Author/Change controller: IETF 750 Specification document(s): This document 752 Related information: (empty) 754 6.2. Media Types Registry 756 The MIME media type for Expect-CT violation reports is "application/ 757 expect-ct-report+json" (which uses the suffix established in 758 [RFC6839]). 760 Type name: application 762 Subtype name: expect-ct-report+json 764 Required parameters: n/a 766 Optional parameters: n/a 767 Encoding considerations: binary 769 Security considerations: See Section 4 771 Interoperability considerations: n/a 773 Published specification: This document 775 Applications that use this media type: UAs that implement 776 Certificate Transparency compliance checks and reporting 778 Additional information: 780 Deprecated alias names for this type: n/a 782 Magic number(s): n/a 784 File extension(s): n/a 786 Macintosh file type code(s): n/a 788 Person & email address to contact for further information: Emily 789 Stark (estark@google.com) 791 Intended usage: COMMON 793 Restrictions on usage: none 795 Author: Emily Stark (estark@google.com) 797 Change controller: IETF 799 7. Usability Considerations 801 When the UA detects a Known Expect-CT Host in violation of the UA's 802 CT Policy, users will experience denials of service. It is advisable 803 for UAs to explain the reason why. 805 8. Authoring Considerations 807 Expect-CT could be specified as a TLS extension or X.509 certificate 808 extension instead of an HTTP response header field. Using an HTTP 809 header field as the mechanism for Expect-CT introduces a layering 810 mismatch: for example, the software that terminates TLS and validates 811 Certificate Transparency information might know nothing about HTTP. 812 Nevertheless, an HTTP header field was chosen primarily for ease of 813 deployment. In practice, deploying new certificate extensions 814 requires certificate authorities to support them, and new TLS 815 extensions require server software updates, including possibly to 816 servers outside of the site owner's direct control (such as in the 817 case of a third-party CDN). Ease of deployment is a high priority 818 for Expect-CT because it is intended as a temporary transition 819 mechanism for user agents that are transitioning to universal 820 Certificate Transparency requirements. 822 9. References 824 9.1. Normative References 826 [I-D.ietf-trans-rfc6962-bis] 827 Laurie, B., Langley, A., Kasper, E., Messeri, E., and R. 828 Stradling, "Certificate Transparency Version 2.0", draft- 829 ietf-trans-rfc6962-bis-27 (work in progress), October 830 2017. 832 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 833 Requirement Levels", BCP 14, RFC 2119, 834 DOI 10.17487/RFC2119, March 1997, 835 . 837 [RFC3339] Klyne, G. and C. Newman, "Date and Time on the Internet: 838 Timestamps", RFC 3339, DOI 10.17487/RFC3339, July 2002, 839 . 841 [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform 842 Resource Identifier (URI): Generic Syntax", STD 66, 843 RFC 3986, DOI 10.17487/RFC3986, January 2005, 844 . 846 [RFC4648] Josefsson, S., "The Base16, Base32, and Base64 Data 847 Encodings", RFC 4648, DOI 10.17487/RFC4648, October 2006, 848 . 850 [RFC5234] Crocker, D., Ed. and P. Overell, "Augmented BNF for Syntax 851 Specifications: ABNF", STD 68, RFC 5234, 852 DOI 10.17487/RFC5234, January 2008, 853 . 855 [RFC6797] Hodges, J., Jackson, C., and A. Barth, "HTTP Strict 856 Transport Security (HSTS)", RFC 6797, 857 DOI 10.17487/RFC6797, November 2012, 858 . 860 [RFC6839] Hansen, T. and A. Melnikov, "Additional Media Type 861 Structured Syntax Suffixes", RFC 6839, 862 DOI 10.17487/RFC6839, January 2013, 863 . 865 [RFC6962] Laurie, B., Langley, A., and E. Kasper, "Certificate 866 Transparency", RFC 6962, DOI 10.17487/RFC6962, June 2013, 867 . 869 [RFC7230] Fielding, R., Ed. and J. Reschke, Ed., "Hypertext Transfer 870 Protocol (HTTP/1.1): Message Syntax and Routing", 871 RFC 7230, DOI 10.17487/RFC7230, June 2014, 872 . 874 [RFC7234] Fielding, R., Ed., Nottingham, M., Ed., and J. Reschke, 875 Ed., "Hypertext Transfer Protocol (HTTP/1.1): Caching", 876 RFC 7234, DOI 10.17487/RFC7234, June 2014, 877 . 879 [RFC7468] Josefsson, S. and S. Leonard, "Textual Encodings of PKIX, 880 PKCS, and CMS Structures", RFC 7468, DOI 10.17487/RFC7468, 881 April 2015, . 883 [RFC8259] Bray, T., Ed., "The JavaScript Object Notation (JSON) Data 884 Interchange Format", STD 90, RFC 8259, 885 DOI 10.17487/RFC8259, December 2017, 886 . 888 9.2. Informative References 890 [FETCH] WHATWG, "Fetch - Living Standard", n.d., 891 . 893 [RFC5246] Dierks, T. and E. Rescorla, "The Transport Layer Security 894 (TLS) Protocol Version 1.2", RFC 5246, 895 DOI 10.17487/RFC5246, August 2008, 896 . 898 [RFC7469] Evans, C., Palmer, C., and R. Sleevi, "Public Key Pinning 899 Extension for HTTP", RFC 7469, DOI 10.17487/RFC7469, April 900 2015, . 902 9.3. URIs 904 [1] https://lists.w3.org/Archives/Public/ietf-http-wg/ 906 [2] http://httpwg.github.io/ 908 [3] https://github.com/httpwg/http-extensions/labels/expect-ct 910 [4] https://www.iana.org/assignments/message-headers 912 Appendix A. Changes 914 A.1. Since -05 916 o Remove SHOULD requirement that UAs disallow certificate error 917 overrides for Known Expect-CT Hosts. 919 o Remove restriction that Expect-CT Hosts cannot be IP addresses. 921 o Editorial changes 923 A.2. Since -04 925 o Editorial changes 927 A.3. Since -03 929 o Editorial changes 931 A.4. Since -02 933 o Add concept of test reports and specify that servers must respond 934 with 2xx status codes to valid reports. 936 o Add "failure-mode" key to reports to allow report servers to 937 distinguish report-only from enforced failures. 939 A.5. Since -01 941 o Change SCT reporting format to support both RFC 6962 and 6962-bis 942 SCTs. 944 A.6. Since -00 946 o Editorial changes 948 o Change Content-Type header of reports to 'application/expect-ct- 949 report+json' 951 o Update header field syntax to match convention (issue #327) 953 o Reference RFC 6962-bis instead of RFC 6962 955 Author's Address 957 Emily Stark 958 Google 960 Email: estark@google.com