idnits 2.17.1 draft-ietf-httpbis-expect-ct-05.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 (May 30, 2018) is 2157 days in the past. Is this intentional? Checking references for intended status: Experimental ---------------------------------------------------------------------------- -- Looks like a reference, but probably isn't: '1' on line 827 -- Looks like a reference, but probably isn't: '2' on line 829 -- Looks like a reference, but probably isn't: '3' on line 831 -- Looks like a reference, but probably isn't: '4' on line 833 == 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 May 30, 2018 5 Expires: December 1, 2018 7 Expect-CT Extension for HTTP 8 draft-ietf-httpbis-expect-ct-05 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 1, 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. Expect-CT Header Field Processing . . . . . . . . . . 8 82 2.3.2. Noting Expect-CT . . . . . . . . . . . . . . . . . . 9 83 2.3.3. Storage Model . . . . . . . . . . . . . . . . . . . . 9 84 2.4. Evaluating Expect-CT Connections for CT Compliance . . . 10 85 3. Reporting Expect-CT Failure . . . . . . . . . . . . . . . . . 11 86 3.1. Generating a violation report . . . . . . . . . . . . . . 11 87 3.2. Sending a violation report . . . . . . . . . . . . . . . 13 88 3.3. Receiving a violation report . . . . . . . . . . . . . . 14 89 4. Security Considerations . . . . . . . . . . . . . . . . . . . 14 90 4.1. Maximum max-age . . . . . . . . . . . . . . . . . . . . . 15 91 4.2. Avoiding amplification attacks . . . . . . . . . . . . . 15 92 5. Privacy Considerations . . . . . . . . . . . . . . . . . . . 15 93 6. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 16 94 7. Usability Considerations . . . . . . . . . . . . . . . . . . 16 95 8. Authoring Considerations . . . . . . . . . . . . . . . . . . 16 96 8.1. HTTP Header . . . . . . . . . . . . . . . . . . . . . . . 16 98 9. References . . . . . . . . . . . . . . . . . . . . . . . . . 17 99 9.1. Normative References . . . . . . . . . . . . . . . . . . 17 100 9.2. Informative References . . . . . . . . . . . . . . . . . 18 101 9.3. URIs . . . . . . . . . . . . . . . . . . . . . . . . . . 18 102 Appendix A. Changes . . . . . . . . . . . . . . . . . . . . . . 18 103 A.1. Since -04 . . . . . . . . . . . . . . . . . . . . . . . . 18 104 A.2. Since -03 . . . . . . . . . . . . . . . . . . . . . . . . 18 105 A.3. Since -02 . . . . . . . . . . . . . . . . . . . . . . . . 19 106 A.4. Since -01 . . . . . . . . . . . . . . . . . . . . . . . . 19 107 A.5. Since -00 . . . . . . . . . . . . . . . . . . . . . . . . 19 108 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 19 110 1. Introduction 112 This document defines a new HTTP header field that enables UAs to 113 identify web hosts that expect the presence of Signed Certificate 114 Timestamps (SCTs) [I-D.ietf-trans-rfc6962-bis] in future Transport 115 Layer Security (TLS) [RFC5246] connections. 117 Web hosts that serve the Expect-CT HTTP header field are noted by the 118 UA as Known Expect-CT Hosts. The UA evaluates each connection to a 119 Known Expect-CT Host for compliance with the UA's Certificate 120 Transparency (CT) Policy. If the connection violates the CT Policy, 121 the UA sends a report to a URI configured by the Expect-CT Host and/ 122 or fails the connection, depending on the configuration that the 123 Expect-CT Host has chosen. 125 If misconfigured, Expect-CT can cause unwanted connection failures 126 (for example, if a host deploys Expect-CT but then switches to a 127 legitimate certificate that is not logged in Certificate Transparency 128 logs, or if a web host operator believes their certificate to conform 129 to all UAs' CT policies but is mistaken). Web host operators are 130 advised to deploy Expect-CT with caution, by using the reporting 131 feature and gradually increasing the interval where the UA remembers 132 the host as a Known Expect-CT Host. These precautions can help web 133 host operators gain confidence that their Expect-CT deployment is not 134 causing unwanted connection failures. 136 Expect-CT is a trust-on-first-use (TOFU) mechanism. The first time a 137 UA connects to a host, it lacks the information necessary to require 138 SCTs for the connection. Thus, the UA will not be able to detect and 139 thwart an attack on the UA's first connection to the host. Still, 140 Expect-CT provides value by 1) allowing UAs to detect the use of 141 unlogged certificates after the initial communication, and 2) 142 allowing web hosts to be confident that UAs are only trusting 143 publicly-auditable certificates. 145 1.1. Requirements Language 147 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 148 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 149 "OPTIONAL" in this document are to be interpreted as described in RFC 150 2119 [RFC2119]. 152 1.2. Terminology 154 Terminology is defined in this section. 156 o "Certificate Transparency Policy" is a policy defined by the UA 157 concerning the number, sources, and delivery mechanisms of Signed 158 Certificate Timestamps that are served on TLS connections. The 159 policy defines the properties of a connection that must be met in 160 order for the UA to consider it CT-qualified. 162 o "Certificate Transparency Qualified" describes a TLS connection 163 for which the UA has determined that a sufficient quantity and 164 quality of Signed Certificate Timestamps have been provided. 166 o "CT-qualified" is an abbreviation for "Certificate Transparency 167 Qualified". 169 o "CT Policy" is an abbreviation for "Certificate Transparency 170 Policy". 172 o "Effective Expect-CT Date" is the time at which a UA observed a 173 valid Expect-CT header field for a given host. 175 o "Expect-CT Host" is a conformant host implementing the HTTP server 176 aspects of Expect-CT. This means that an Expect-CT Host returns 177 the "Expect-CT" HTTP response header field in its HTTP response 178 messages sent over secure transport. 180 o "Known Expect-CT Host" is an Expect-CT Host that the UA has noted 181 as such. See Section 2.3.2 for particulars. 183 o UA is an acronym for "user agent". For the purposes of this 184 specification, a UA is an HTTP client application typically 185 actively manipulated by a user [RFC7230]. 187 o "Unknown Expect-CT Host" is an Expect-CT Host that the UA has not 188 noted. 190 2. Server and Client Behavior 192 2.1. Response Header Field Syntax 194 The "Expect-CT" response header field is a new field defined in this 195 specification. It is used by a server to indicate that UAs should 196 evaluate connections to the host emitting the header field for CT 197 compliance (Section 2.4). 199 Figure 1 describes the syntax (Augmented Backus-Naur Form) of the 200 header field, using the grammar defined in [RFC5234] and the rules 201 defined in Section 3.2 of [RFC7230]. 203 Expect-CT = #expect-ct-directive 204 expect-ct-directive = directive-name [ "=" directive-value ] 205 directive-name = token 206 directive-value = token / quoted-string 208 Figure 1: Syntax of the Expect-CT header field 210 Optional white space ("OWS") is used as defined in Section 3.2.3 of 211 [RFC7230]. "token" and "quoted-string" are used as defined in 212 Section 3.2.6 of [RFC7230]. 214 The directives defined in this specification are described below. 215 The overall requirements for directives are: 217 1. The order of appearance of directives is not significant. 219 2. A given directive MUST NOT appear more than once in a given 220 header field. Directives are either optional or required, as 221 stipulated in their definitions. 223 3. Directive names are case insensitive. 225 4. UAs MUST ignore any header fields containing directives, or other 226 header field value data, that do not conform to the syntax 227 defined in this specification. In particular, UAs must not 228 attempt to fix malformed header fields. 230 5. If a header field contains any directive(s) the UA does not 231 recognize, the UA MUST ignore those directives. 233 6. If the Expect-CT header field otherwise satisfies the above 234 requirements (1 through 5), the UA MUST process the directives it 235 recognizes. 237 2.1.1. The report-uri Directive 239 The OPTIONAL "report-uri" directive indicates the URI to which the UA 240 SHOULD report Expect-CT failures (Section 2.4). The UA POSTs the 241 reports to the given URI as described in Section 3. 243 The "report-uri" directive is REQUIRED to have a directive value, for 244 which the syntax is defined in Figure 2. 246 report-uri-value = absolute-URI 248 Figure 2: Syntax of the report-uri directive value 250 "absolute-URI" is defined in Section 4.3 of [RFC3986]. 252 Hosts may set "report-uri"s that use HTTP or HTTPS. If the scheme in 253 the "report-uri" is one that uses TLS (e.g., HTTPS), UAs MUST check 254 Expect-CT compliance when the host in the "report-uri" is a Known 255 Expect-CT Host; similarly, UAs MUST apply HSTS if the host in the 256 "report-uri" is a Known HSTS Host. 258 Note that the report-uri need not necessarily be in the same Internet 259 domain or web origin as the host being reported about. 261 UAs SHOULD make their best effort to report Expect-CT failures to the 262 "report-uri", but they may fail to report in exceptional conditions. 263 For example, if connecting to the "report-uri" itself incurs an 264 Expect-CT failure or other certificate validation failure, the UA 265 MUST cancel the connection. Similarly, if Expect-CT Host A sets a 266 "report-uri" referring to Expect-CT Host B, and if B sets a "report- 267 uri" referring to A, and if both hosts fail to comply to the UA's CT 268 Policy, the UA SHOULD detect and break the loop by failing to send 269 reports to and about those hosts. 271 UAs SHOULD limit the rate at which they send reports. For example, 272 it is unnecessary to send the same report to the same "report-uri" 273 more than once. 275 2.1.2. The enforce Directive 277 The OPTIONAL "enforce" directive is a valueless directive that, if 278 present (i.e., it is "asserted"), signals to the UA that compliance 279 to the CT Policy should be enforced (rather than report-only) and 280 that the UA should refuse future connections that violate its CT 281 Policy. When both the "enforce" directive and "report-uri" directive 282 (as defined in Figure 2) are present, the configuration is referred 283 to as an "enforce-and-report" configuration, signalling to the UA 284 both that compliance to the CT Policy should be enforced and that 285 violations should be reported. 287 2.1.3. The max-age Directive 289 The "max-age" directive specifies the number of seconds after the 290 reception of the Expect-CT header field during which the UA SHOULD 291 regard the host from whom the message was received as a Known Expect- 292 CT Host. 294 The "max-age" directive is REQUIRED to be present within an "Expect- 295 CT" header field. The "max-age" directive is REQUIRED to have a 296 directive value, for which the syntax (after quoted-string 297 unescaping, if necessary) is defined in Figure 3. 299 max-age-value = delta-seconds 300 delta-seconds = 1*DIGIT 302 Figure 3: Syntax of the max-age directive value 304 "delta-seconds" is used as defined in Section 1.2.1 of [RFC7234]. 306 2.1.4. Examples 308 The following three examples demonstrate valid Expect-CT response 309 header fields (where the second splits the directives into two field 310 instances): 312 Expect-CT: max-age=86400, enforce 314 Expect-CT: max-age=86400,enforce 315 Expect-CT: report-uri="https://foo.example/report" 317 Expect-CT: max-age=86400,report-uri="https://foo.example/report" 319 Figure 4: Examples of valid Expect-CT response header fields 321 2.2. Server Processing Model 323 This section describes the processing model that Expect-CT Hosts 324 implement. The model has 2 parts: (1) the processing rules for HTTP 325 request messages received over a secure transport (e.g., 326 authenticated, non-anonymous TLS); and (2) the processing rules for 327 HTTP request messages received over non-secure transports, such as 328 TCP. 330 2.2.1. HTTP-over-Secure-Transport Request Type 332 When replying to an HTTP request that was conveyed over a secure 333 transport, an Expect-CT Host SHOULD include in its response exactly 334 one Expect-CT header field. The header field MUST satisfy the 335 grammar specified in Section 2.1. 337 Establishing a given host as an Expect-CT Host, in the context of a 338 given UA, is accomplished as follows: 340 1. Over the HTTP protocol running over secure transport, by 341 correctly returning (per this specification) at least one valid 342 Expect-CT header field to the UA. 344 2. Through other mechanisms, such as a client-side preloaded Expect- 345 CT Host list. 347 2.2.2. HTTP Request Type 349 Expect-CT Hosts SHOULD NOT include the Expect-CT header field in HTTP 350 responses conveyed over non-secure transport. UAs MUST ignore any 351 Expect-CT header field received in an HTTP response conveyed over 352 non-secure transport. 354 2.3. User Agent Processing Model 356 The UA processing model relies on parsing domain names. Note that 357 internationalized domain names SHALL be canonicalized according to 358 the scheme in Section 10 of [RFC6797]. 360 2.3.1. Expect-CT Header Field Processing 362 If the UA receives, over a secure transport, an HTTP response that 363 includes an Expect-CT header field conforming to the grammar 364 specified in Section 2.1, the UA MUST evaluate the connection on 365 which the header field was received for compliance with the UA's CT 366 Policy, and then process the Expect-CT header field as follows. 368 If the connection complies with the UA's CT Policy (i.e. the 369 connection is CT-qualified), then the UA MUST either: 371 o Note the host as a Known Expect-CT Host if it is not already so 372 noted (see Section 2.3.2), or 374 o Update the UA's cached information for the Known Expect-CT Host if 375 the "enforce", "max-age", or "report-uri" header field value 376 directives convey information different from that already 377 maintained by the UA. If the "max-age" directive has a value of 378 0, the UA MUST remove its cached Expect-CT information if the host 379 was previously noted as a Known Expect-CT Host, and MUST NOT note 380 this host as a Known Expect-CT Host if it is not already noted. 382 If the connection does not comply with the UA's CT Policy (i.e. is 383 not CT-qualified), then the UA MUST NOT note this host as a Known 384 Expect-CT Host. 386 If the header field includes a "report-uri" directive, and the 387 connection does not comply with the UA's CT Policy (i.e. the 388 connection is not CT-qualified), and the UA has not already sent an 389 Expect-CT report for this connection, then the UA SHOULD send a 390 report to the specified "report-uri" as specified in Section 3. 392 The UA MUST ignore any Expect-CT header field not conforming to the 393 grammar specified in Section 2.1. 395 2.3.2. Noting Expect-CT 397 Upon receipt of the Expect-CT response header field over an error- 398 free TLS connection (including the validation adding in Section 2.4), 399 the UA MUST note the host as a Known Expect-CT Host, storing the 400 host's domain name and its associated Expect-CT directives in non- 401 volatile storage. The domain name and associated Expect-CT 402 directives are collectively known as "Expect-CT metadata". 404 To note a host as a Known Expect-CT Host, the UA MUST set its Expect- 405 CT metadata given in the most recently received valid Expect-CT 406 header field, as specified in Section 2.3.3. 408 For forward compatibility, the UA MUST ignore any unrecognized 409 Expect-CT header field directives, while still processing those 410 directives it does recognize. Section 2.1 specifies the directives 411 "enforce", "max-age", and "report-uri", but future specifications and 412 implementations might use additional directives. 414 2.3.3. Storage Model 416 Known Expect-CT Hosts are identified only by domain names, and never 417 IP addresses. If the substring matching the host production from the 418 Request-URI (of the message to which the host responded) 419 syntactically matches the IP-literal or IPv4address productions from 420 Section 3.2.2 of [RFC3986], then the UA MUST NOT note this host as a 421 Known Expect-CT Host. 423 Otherwise, if the substring does not congruently match an existing 424 Known Expect-CT Host's domain name, per the matching procedure 425 specified in Section 8.2 of [RFC6797], then the UA MUST add this host 426 to the Known Expect-CT Host cache. The UA caches: 428 o the Expect-CT Host's domain name, 430 o whether the "enforce" directive is present 432 o the Effective Expiration Date, which is the Effective Expect-CT 433 Date plus the value of the "max-age" directive. Alternatively, 434 the UA MAY cache enough information to calculate the Effective 435 Expiration Date. 437 o the value of the "report-uri" directive, if present. 439 If any other metadata from optional or future Expect-CT header 440 directives are present in the Expect-CT header field, and the UA 441 understands them, the UA MAY note them as well. 443 UAs MAY set an upper limit on the value of max-age, so that UAs that 444 have noted erroneous Expect-CT hosts (whether by accident or due to 445 attack) have some chance of recovering over time. If the server sets 446 a max-age greater than the UA's upper limit, the UA MAY behave as if 447 the server set the max-age to the UA's upper limit. For example, if 448 the UA caps max-age at 5,184,000 seconds (60 days), and an Expect-CT 449 Host sets a max- age directive of 90 days in its Expect-CT header 450 field, the UA MAY behave as if the max-age were effectively 60 days. 451 (One way to achieve this behavior is for the UA to simply store a 452 value of 60 days instead of the 90-day value provided by the Expect- 453 CT host.) 455 2.4. Evaluating Expect-CT Connections for CT Compliance 457 When a UA connects to a Known Expect-CT Host using a TLS connection, 458 if the TLS connection has errors, the UA MUST terminate the 459 connection without allowing the user to proceed anyway. (This 460 behavior is the same as that required by [RFC6797].) 462 If the connection has no errors, then the UA will apply an additional 463 correctness check: compliance with a CT Policy. A UA should evaluate 464 compliance with its CT Policy whenever connecting to a Known Expect- 465 CT Host, as soon as possible. It is acceptable to skip this CT 466 compliance check for some hosts according to local policy. For 467 example, a UA may disable CT compliance checks for hosts whose 468 validated certificate chain terminates at a user-defined trust 469 anchor, rather than a trust anchor built-in to the UA (or underlying 470 platform). 472 An Expect-CT Host is "expired" if the effective expiration date 473 refers to a date in the past. The UA MUST ignore any expired Expect- 474 CT Hosts in its cache and not treat such hosts as Known Expect-CT 475 hosts. 477 If a connection to a Known CT Host violates the UA's CT policy (i.e. 478 the connection is not CT-qualified), and if the Known Expect-CT 479 Host's Expect-CT metadata indicates an "enforce" configuration, the 480 UA MUST treat the CT compliance failure as a non-recoverable error. 482 If a connection to a Known CT Host violates the UA's CT policy, and 483 if the Known Expect-CT Host's Expect-CT metadata includes a "report- 484 uri", the UA SHOULD send an Expect-CT report to that "report-uri" 485 (Section 3). 487 A UA that has previously noted a host as a Known Expect-CT Host MUST 488 evaluate CT compliance when setting up the TLS session, before 489 beginning an HTTP conversation over the TLS channel. 491 If the UA does not evaluate CT compliance, e.g. because the user has 492 elected to disable it, or because a presented certificate chain 493 chains up to a user-defined trust anchor, UAs SHOULD NOT send Expect- 494 CT reports. 496 3. Reporting Expect-CT Failure 498 When the UA attempts to connect to a Known Expect-CT Host and the 499 connection is not CT-qualified, the UA SHOULD report Expect-CT 500 failures to the "report-uri", if any, in the Known Expect-CT Host's 501 Expect-CT metadata. 503 When the UA receives an Expect-CT response header field over a 504 connection that is not CT-qualified, if the UA has not already sent 505 an Expect-CT report for this connection, then the UA SHOULD report 506 Expect-CT failures to the configured "report-uri", if any. 508 3.1. Generating a violation report 510 To generate a violation report object, the UA constructs a JSON 511 object with the following keys and values: 513 o "date-time": the value for this key indicates the time the UA 514 observed the CT compliance failure. The value is a string 515 formatted according to Section 5.6, "Internet Date/Time Format", 516 of [RFC3339]. 518 o "hostname": the value is the hostname to which the UA made the 519 original request that failed the CT compliance check. The value 520 is provided as a string. 522 o "port": the value is the port to which the UA made the original 523 request that failed the CT compliance check. The value is 524 provided as an integer. 526 o "effective-expiration-date": the value indicates the Effective 527 Expiration Date (see Section 2.3.3) for the Expect-CT Host that 528 failed the CT compliance check. The value is provided as a string 529 formatted according to Section 5.6 of [RFC3339] ("Internet Date/ 530 Time Format"). 532 o "served-certificate-chain": the value is the certificate chain as 533 served by the Expect-CT Host during TLS session setup. The value 534 is provided as an array of strings, which MUST appear in the order 535 that the certificates were served; each string in the array is the 536 Privacy-Enhanced Mail (PEM) representation of each X.509 537 certificate as described in [RFC7468]. 539 o "validated-certificate-chain": the value is the certificate chain 540 as constructed by the UA during certificate chain verification. 541 (This may differ from the value of the "served-certificate-chain" 542 key.) The value is provided as an array of strings, which MUST 543 appear in the order matching the chain that the UA validated; each 544 string in the array is the Privacy-Enhanced Mail (PEM) 545 representation of each X.509 certificate as described in 546 [RFC7468]. 548 o "scts": the value represents the SCTs (if any) that the UA 549 received for the Expect-CT host and their validation statuses. 550 The value is provided as an array of JSON objects. The SCTs may 551 appear in any order. Each JSON object in the array has the 552 following keys: 554 * A "version" key, with an integer value. The UA MUST set this 555 value to "1" if the SCT is in the format defined in Section 3.2 556 of [RFC6962] and "2" if it is in the format defined in 557 Section 4.6 of [I-D.ietf-trans-rfc6962-bis]. 559 * The "status" key, with a string value that the UA MUST set to 560 one of the following values: "unknown" (indicating that the UA 561 does not have or does not trust the public key of the log from 562 which the SCT was issued), "valid" (indicating that the UA 563 successfully validated the SCT as described in Section 5.2 of 564 [RFC6962] or Section 8.2.3 of [I-D.ietf-trans-rfc6962-bis]), or 565 "invalid" (indicating that the SCT validation failed because 566 of, e.g., a bad signature). 568 * The "source" key, with a string value that indicates from where 569 the UA obtained the SCT, as defined in Section 3 or [RFC6962] 570 and Section 6 of [I-D.ietf-trans-rfc6962-bis]. The UA MUST set 571 the value to one of "tls-extension", "ocsp", or "embedded". 573 * The "serialized_sct" key, with a string value. If the value of 574 the "version" key is "1", the UA MUST set this value to the 575 base64 encoded [RFC4648] serialized 576 "SignedCertificateTimestamp" structure from Section 3.2 of 577 [RFC6962]. If the value of the "version" key is "2", the UA 578 MUST set this value to the base64 encoded [RFC4648] serialized 579 "TransItem" structure representing the SCT, as defined in 580 Section 4.6 of [I-D.ietf-trans-rfc6962-bis]. 582 o "failure-mode": the value indicates whether the Expect-CT report 583 was triggered by an Expect-CT policy in enforce or report-only 584 mode. The value is provided as a string. The UA MUST set this 585 value to "enforce" if the Expect-CT metadata indicates an 586 "enforce" configuration, and "report-only" otherwise. 588 o "test-report": the value is set to true if the report is being 589 sent by a testing client to verify that the reporting server 590 behaves correctly. The value is provided as a boolean, and MUST 591 be set to true if the report serves to test the server's behavior 592 and can be discarded. 594 3.2. Sending a violation report 596 The UA SHOULD report an Expect-CT failure when a connection to a 597 Known Expect-CT Host does not comply with the UA's CT Policy and the 598 host's Expect-CT metadata contains a "report-uri". Additionally, the 599 UA SHOULD report an Expect-CT failure when it receives an Expect-CT 600 header field which contains the "report-uri" directive over a 601 connection that does not comply with the UA's CT Policy. 603 The steps to report an Expect-CT failure are as follows. 605 1. Prepare a JSON object "report object" with the single key 606 "expect-ct-report", whose value is the result of generating a 607 violation report object as described in Section 3.1. 609 2. Let "report body" be the JSON stringification of "report object". 611 3. Let "report-uri" be the value of the "report-uri" directive in 612 the Expect-CT header field. 614 4. Send an HTTP POST request to "report-uri" with a "Content-Type" 615 header field of "application/expect-ct-report+json", and an 616 entity body consisting of "report body". 618 The UA MAY perform other operations as part of sending the HTTP POST 619 request, for example sending a CORS preflight as part of [FETCH]. 621 3.3. Receiving a violation report 623 Upon receiving an Expect-CT violation report, the report server MUST 624 respond with a 2xx (Successful) status code if it can parse the 625 request body as valid JSON and recognizes the hostname in the 626 "hostname" field of the report. If the report body cannot be parsed 627 or the report server does not expect to receive reports for the 628 hostname in the "hostname" field, the report server MUST respond with 629 a 4xx (Client Error) status code. 631 If the report's "test-report" key is set to true, the server MAY 632 discard the report without further processing but MUST still return a 633 2xx (Successful) status code. 635 4. Security Considerations 637 When UAs support the Expect-CT header field, it becomes a potential 638 vector for hostile header attacks against site owners. If a site 639 owner uses a certificate issued by a certificate authority which does 640 not embed SCTs nor serve SCTs via OCSP or TLS extension, a malicious 641 server operator or attacker could temporarily reconfigure the host to 642 comply with the UA's CT policy, and add the Expect-CT header field in 643 enforcing mode with a long "max-age". Implementing user agents would 644 note this as an Expect-CT Host (see Section 2.3.2). After having 645 done this, the configuration could then be reverted to not comply 646 with the CT policy, prompting failures. Note this scenario would 647 require the attacker to have substantial control over the 648 infrastructure in question, being able to obtain different 649 certificates, change server software, or act as a man-in-the-middle 650 in connections. 652 Site operators could themselves only cure this situation by one of: 653 reconfiguring their web server to transmit SCTs using the TLS 654 extension defined in Section 6.5 of [I-D.ietf-trans-rfc6962-bis], 655 obtaining a certificate from an alternative certificate authority 656 which provides SCTs by one of the other methods, or by waiting for 657 the user agents' persisted notation of this as an Expect-CT host to 658 reach its "max-age". User agents may choose to implement mechanisms 659 for users to cure this situation, as noted in Section 7. 661 4.1. Maximum max-age 663 There is a security trade-off in that low maximum values provide a 664 narrow window of protection for users that visit the Known Expect-CT 665 Host only infrequently, while high maximum values might result in a 666 denial of service to a UA in the event of a hostile header attack, or 667 simply an error on the part of the site-owner. 669 There is probably no ideal maximum for the "max-age" directive. 670 Since Expect-CT is primarily a policy-expansion and investigation 671 technology rather than an end-user protection, a value on the order 672 of 30 days (2,592,000 seconds) may be considered a balance between 673 these competing security concerns. 675 4.2. Avoiding amplification attacks 677 Another kind of hostile header attack uses the "report-uri" mechanism 678 on many hosts not currently exposing SCTs as a method to cause a 679 denial-of-service to the host receiving the reports. If some highly- 680 trafficked websites emitted a non-enforcing Expect-CT header field 681 with a "report-uri", implementing UAs' reports could flood the 682 reporting host. It is noted in Section 2.1.1 that UAs should limit 683 the rate at which they emit reports, but an attacker may alter the 684 Expect-CT header's fields to induce UAs to submit different reports 685 to different URIs to still cause the same effect. 687 5. Privacy Considerations 689 Expect-CT can be used to infer what Certificate Transparency policy 690 is in use, by attempting to retrieve specially-configured websites 691 which pass one user agents' policies but not another's. Note that 692 this consideration is true of UAs which enforce CT policies without 693 Expect-CT as well. 695 Additionally, reports submitted to the "report-uri" could reveal 696 information to a third party about which webpage is being accessed 697 and by which IP address, by using individual "report-uri" values for 698 individually-tracked pages. This information could be leaked even if 699 client-side scripting were disabled. 701 Implementations must store state about Known Expect-CT Hosts, and 702 hence which domains the UA has contacted. 704 Violation reports, as noted in Section 3, contain information about 705 the certificate chain that has violated the CT policy. In some 706 cases, such as organization-wide compromise of the end-to-end 707 security of TLS, this may include information about the interception 708 tools and design used by the organization that the organization would 709 otherwise prefer not be disclosed. 711 Because Expect-CT causes remotely-detectable behavior, it's advisable 712 that UAs offer a way for privacy-sensitive users to clear currently 713 noted Expect-CT hosts, and allow users to query the current state of 714 Known Expect-CT Hosts. 716 6. IANA Considerations 718 This document registers the "Expect-CT" header field in the "Message 719 Headers" registry located at https://www.iana.org/assignments/ 720 message-headers [4]. 722 Header field name: Expect-CT 724 Applicable protocol: http 726 Status: standard 728 Author/Change controller: IETF 730 Specification document(s): This document 732 Related information: (empty) 734 7. Usability Considerations 736 When the UA detects a Known Expect-CT Host in violation of the UA's 737 CT Policy, users will experience denials of service. It is advisable 738 for UAs to explain the reason why. 740 8. Authoring Considerations 742 8.1. HTTP Header 744 Expect-CT could be specified as a TLS extension or X.509 certificate 745 extension instead of an HTTP response header field. Using an HTTP 746 header field as the mechanism for Expect-CT introduces a layering 747 mismatch: for example, the software that terminates TLS and validates 748 Certificate Transparency information might know nothing about HTTP. 749 Nevertheless, an HTTP header field was chosen primarily for ease of 750 deployment. In practice, deploying new certificate extensions 751 requires certificate authorities to support them, and new TLS 752 extensions require server software updates, including possibly to 753 servers outside of the site owner's direct control (such as in the 754 case of a third-party CDN). Ease of deployment is a high priority 755 for Expect-CT because it is intended as a temporary transition 756 mechanism for user agents that are transitioning to universal 757 Certificate Transparency requirements. 759 9. References 761 9.1. Normative References 763 [I-D.ietf-trans-rfc6962-bis] 764 Laurie, B., Langley, A., Kasper, E., Messeri, E., and R. 765 Stradling, "Certificate Transparency Version 2.0", draft- 766 ietf-trans-rfc6962-bis-27 (work in progress), October 767 2017. 769 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 770 Requirement Levels", BCP 14, RFC 2119, 771 DOI 10.17487/RFC2119, March 1997, 772 . 774 [RFC3339] Klyne, G. and C. Newman, "Date and Time on the Internet: 775 Timestamps", RFC 3339, DOI 10.17487/RFC3339, July 2002, 776 . 778 [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform 779 Resource Identifier (URI): Generic Syntax", STD 66, 780 RFC 3986, DOI 10.17487/RFC3986, January 2005, 781 . 783 [RFC4648] Josefsson, S., "The Base16, Base32, and Base64 Data 784 Encodings", RFC 4648, DOI 10.17487/RFC4648, October 2006, 785 . 787 [RFC5234] Crocker, D., Ed. and P. Overell, "Augmented BNF for Syntax 788 Specifications: ABNF", STD 68, RFC 5234, 789 DOI 10.17487/RFC5234, January 2008, 790 . 792 [RFC6797] Hodges, J., Jackson, C., and A. Barth, "HTTP Strict 793 Transport Security (HSTS)", RFC 6797, 794 DOI 10.17487/RFC6797, November 2012, 795 . 797 [RFC6962] Laurie, B., Langley, A., and E. Kasper, "Certificate 798 Transparency", RFC 6962, DOI 10.17487/RFC6962, June 2013, 799 . 801 [RFC7230] Fielding, R., Ed. and J. Reschke, Ed., "Hypertext Transfer 802 Protocol (HTTP/1.1): Message Syntax and Routing", 803 RFC 7230, DOI 10.17487/RFC7230, June 2014, 804 . 806 [RFC7234] Fielding, R., Ed., Nottingham, M., Ed., and J. Reschke, 807 Ed., "Hypertext Transfer Protocol (HTTP/1.1): Caching", 808 RFC 7234, DOI 10.17487/RFC7234, June 2014, 809 . 811 [RFC7468] Josefsson, S. and S. Leonard, "Textual Encodings of PKIX, 812 PKCS, and CMS Structures", RFC 7468, DOI 10.17487/RFC7468, 813 April 2015, . 815 9.2. Informative References 817 [FETCH] WHATWG, "Fetch - Living Standard", n.d., 818 . 820 [RFC5246] Dierks, T. and E. Rescorla, "The Transport Layer Security 821 (TLS) Protocol Version 1.2", RFC 5246, 822 DOI 10.17487/RFC5246, August 2008, 823 . 825 9.3. URIs 827 [1] https://lists.w3.org/Archives/Public/ietf-http-wg/ 829 [2] http://httpwg.github.io/ 831 [3] https://github.com/httpwg/http-extensions/labels/expect-ct 833 [4] https://www.iana.org/assignments/message-headers 835 Appendix A. Changes 837 A.1. Since -04 839 o Editorial changes 841 A.2. Since -03 843 o Editorial changes 845 A.3. Since -02 847 o Add concept of test reports and specify that servers must respond 848 with 2xx status codes to valid reports. 850 o Add "failure-mode" key to reports to allow report servers to 851 distinguish report-only from enforced failures. 853 A.4. Since -01 855 o Change SCT reporting format to support both RFC 6962 and 6962-bis 856 SCTs. 858 A.5. Since -00 860 o Editorial changes 862 o Change Content-Type header of reports to 'application/expect-ct- 863 report+json' 865 o Update header field syntax to match convention (issue #327) 867 o Reference RFC 6962-bis instead of RFC 6962 869 Author's Address 871 Emily Stark 872 Google 874 Email: estark@google.com