idnits 2.17.1 draft-ietf-httpbis-expect-ct-03.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 : ---------------------------------------------------------------------------- ** There is 1 instance of too long lines in the document, the longest one being 2 characters in excess of 72. ** 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 == Line 153 has weird spacing: '... Policy is a ...' == Line 159 has weird spacing: '...alified descr...' == Line 167 has weird spacing: '...CT Date is th...' == Line 175 has weird spacing: '...CT Host is a ...' == Line 180 has weird spacing: '...CT Host is an...' == (1 more instance...) -- The document date (February 26, 2018) is 2243 days in the past. Is this intentional? Checking references for intended status: Experimental ---------------------------------------------------------------------------- -- Looks like a reference, but probably isn't: '1' on line 848 -- Looks like a reference, but probably isn't: '2' on line 850 -- Looks like a reference, but probably isn't: '3' on line 852 == Unused Reference: 'HTML' is defined on line 779, but no explicit reference was found in the text == Outdated reference: A later version (-42) exists of draft-ietf-trans-rfc6962-bis-27 ** Obsolete normative reference: RFC 5246 (Obsoleted by RFC 8446) ** 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) Summary: 6 errors (**), 0 flaws (~~), 9 warnings (==), 4 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 February 26, 2018 5 Expires: August 30, 2018 7 Expect-CT Extension for HTTP 8 draft-ietf-httpbis-expect-ct-03 10 Abstract 12 This document defines a new HTTP header, named Expect-CT, that allows 13 web host operators to instruct user agents to expect valid Signed 14 Certificate Timestamps (SCTs) to be served on connections to these 15 hosts. When configured in enforcement mode, user agents (UAs) will 16 remember that hosts expect SCTs and will refuse connections that do 17 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 August 30, 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. HTTP-Equiv Element Attribute . . . . . . . . . 9 83 2.3.3. Noting Expect-CT . . . . . . . . . . . . . . . . . . 9 84 2.3.4. Storage Model . . . . . . . . . . . . . . . . . . . . 9 85 2.4. Evaluating Expect-CT Connections for CT Compliance . . . 10 86 3. Reporting Expect-CT Failure . . . . . . . . . . . . . . . . . 11 87 3.1. Generating a violation report . . . . . . . . . . . . . . 11 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 7. Usability Considerations . . . . . . . . . . . . . . . . . . 16 96 8. Authoring Considerations . . . . . . . . . . . . . . . . . . 16 97 8.1. HTTP Header . . . . . . . . . . . . . . . . . . . . . . . 16 98 9. Changes . . . . . . . . . . . . . . . . . . . . . . . . . . . 16 99 9.1. Since -02 . . . . . . . . . . . . . . . . . . . . . . . . 16 100 9.2. Since -01 . . . . . . . . . . . . . . . . . . . . . . . . 17 101 9.3. Since -00 . . . . . . . . . . . . . . . . . . . . . . . . 17 102 10. References . . . . . . . . . . . . . . . . . . . . . . . . . 17 103 10.1. Normative References . . . . . . . . . . . . . . . . . . 17 104 10.2. URIs . . . . . . . . . . . . . . . . . . . . . . . . . . 18 105 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 19 107 1. Introduction 109 This document defines a new HTTP header that enables UAs to identify 110 web hosts that expect the presence of Signed Certificate Timestamps 111 (SCTs) [I-D.ietf-trans-rfc6962-bis] in future Transport Layer 112 Security (TLS) [RFC5246] connections. 114 Web hosts that serve the Expect-CT HTTP header are noted by the UA as 115 Known Expect-CT Hosts. The UA evaluates each connection to a Known 116 Expect-CT Host for compliance with the UA's Certificate Transparency 117 (CT) Policy. If the connection violates the CT Policy, the UA sends 118 a report to a URI configured by the Expect-CT Host and/or fails the 119 connection, depending on the configuration that the Expect-CT Host 120 has chosen. 122 If misconfigured, Expect-CT can cause unwanted connection failures 123 (for example, if a host deploys Expect-CT but then switches to a 124 legitimate certificate that is not logged in Certificate Transparency 125 logs, or if a web host operator believes their certificate to conform 126 to all UAs' CT policies but is mistaken). Web host operators are 127 advised to deploy Expect-CT with caution, by using the reporting 128 feature and gradually increasing the interval where the UA remembers 129 the host as a Known Expect-CT Host. These precautions can help web 130 host operators gain confidence that their Expect-CT deployment is not 131 causing unwanted connection failures. 133 Expect-CT is a trust-on-first-use (TOFU) mechanism. The first time a 134 UA connects to a host, it lacks the information necessary to require 135 SCTs for the connection. Thus, the UA will not be able to detect and 136 thwart an attack on the UA's first connection to the host. Still, 137 Expect-CT provides value by 1) allowing UAs to detect the use of 138 unlogged certificates after the initial communication, and 2) 139 allowing web hosts to be confident that UAs are only trusting 140 publicly-auditable certificates. 142 1.1. Requirements Language 144 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 145 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 146 "OPTIONAL" in this document are to be interpreted as described in RFC 147 2119 [RFC2119]. 149 1.2. Terminology 151 Terminology is defined in this section. 153 Certificate Transparency Policy is a policy defined by the UA 154 concerning the number, sources, and delivery mechanisms of Signed 155 Certificate Timestamps that are served on TLS connections. The 156 policy defines the properties of a connection that must be met in 157 order for the UA to consider it CT-qualified. 159 Certificate Transparency Qualified describes a TLS connection for 160 which the UA has determined that a sufficient quantity and quality 161 of Signed Certificate Timestamps have been provided. 163 CT-qualified See Certificate Transparency Qualified. 165 CT Policy See Certificate Transparency Policy. 167 Effective Expect-CT Date is the time at which a UA observed a valid 168 Expect-CT header for a given host. 170 Expect-CT Host See HTTP Expect-CT Host. 172 HTTP Expect-CT is the overall name for the combined UA- and server- 173 side security policy defined by this specification. 175 HTTP Expect-CT Host is a conformant host implementing the HTTP 176 server aspects of HTTP Expect-CT. This means that an Expect-CT 177 Host returns the "Expect-CT" HTTP response header field in its 178 HTTP response messages sent over secure transport. 180 Known Expect-CT Host is an Expect-CT Host that the UA has noted as 181 such. See Section 2.3.3 for particulars. 183 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 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" header field is a new response header 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 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 examples demonstrate valid Expect-CT response header 309 fields: 311 Expect-CT: max-age=86400,enforce 313 Expect-CT: max-age=86400, enforce, report-uri="https://foo.example/report" 315 Expect-CT: max-age=86400,report-uri="https://foo.example/report" 317 Figure 4: Examples of valid Expect-CT response header fields 319 2.2. Server Processing Model 321 This section describes the processing model that Expect-CT Hosts 322 implement. The model has 2 parts: (1) the processing rules for HTTP 323 request messages received over a secure transport (e.g., 324 authenticated, non-anonymous TLS); and (2) the processing rules for 325 HTTP request messages received over non-secure transports, such as 326 TCP. 328 2.2.1. HTTP-over-Secure-Transport Request Type 330 When replying to an HTTP request that was conveyed over a secure 331 transport, an Expect-CT Host SHOULD include in its response exactly 332 one Expect-CT header field. The header field MUST satisfy the 333 grammar specified in Section 2.1. 335 Establishing a given host as an Expect-CT Host, in the context of a 336 given UA, is accomplished as follows: 338 1. Over the HTTP protocol running over secure transport, by 339 correctly returning (per this specification) at least one valid 340 Expect-CT header field to the UA. 342 2. Through other mechanisms, such as a client-side preloaded Expect- 343 CT Host list. 345 2.2.2. HTTP Request Type 347 Expect-CT Hosts SHOULD NOT include the Expect-CT header field in HTTP 348 responses conveyed over non-secure transport. UAs MUST ignore any 349 Expect-CT header received in an HTTP response conveyed over non- 350 secure transport. 352 2.3. User Agent Processing Model 354 The UA processing model relies on parsing domain names. Note that 355 internationalized domain names SHALL be canonicalized according to 356 the scheme in Section 10 of [RFC6797]. 358 2.3.1. Expect-CT Header Field Processing 360 If the UA receives, over a secure transport, an HTTP response that 361 includes an Expect-CT header field conforming to the grammar 362 specified in Section 2.1, the UA MUST evaluate the connection on 363 which the header was received for compliance with the UA's CT Policy, 364 and then process the Expect-CT header field as follows. 366 If the connection complies with the UA's CT Policy (i.e. the 367 connection is CT-qualified), then the UA MUST either: 369 o Note the host as a Known Expect-CT Host if it is not already so 370 noted (see Section 2.3.3), or 372 o Update the UA's cached information for the Known Expect-CT Host if 373 the "enforce", "max-age", or "report-uri" header field value 374 directives convey information different from that already 375 maintained by the UA. If the "max-age" directive has a value of 376 0, the UA MUST remove its cached Expect-CT information if the host 377 was previously noted as a Known Expect-CT Host, and MUST NOT note 378 this host as a Known Expect-CT Host if it is not already noted. 380 If the connection does not comply with the UA's CT Policy (i.e. is 381 not CT-qualified), then the UA MUST NOT note this host as a Known 382 Expect-CT Host. 384 If the header field includes a "report-uri" directive, and the 385 connection does not comply with the UA's CT Policy (i.e. the 386 connection is not CT-qualified), and the UA has not already sent an 387 Expect-CT report for this connection, then the UA SHOULD send a 388 report to the specified "report-uri" as specified in Section 3. 390 The UA MUST ignore any Expect-CT header field not conforming to the 391 grammar specified in Section 2.1. 393 2.3.2. HTTP-Equiv Element Attribute 395 UAs MUST NOT heed "http-equiv="Expect-CT"" attribute settings on 396 "" elements [W3C.REC-html51-20161101] in received content. 398 2.3.3. Noting Expect-CT 400 Upon receipt of the Expect-CT response header field over an error- 401 free TLS connection (including the validation adding in Section 2.4), 402 the UA MUST note the host as a Known Expect-CT Host, storing the 403 host's domain name and its associated Expect-CT directives in non- 404 volatile storage. The domain name and associated Expect-CT 405 directives are collectively known as "Expect-CT metadata". 407 To note a host as a Known Expect-CT Host, the UA MUST set its Expect- 408 CT metadata given in the most recently received valid Expect-CT 409 header, as specified in Section 2.3.4. 411 For forward compatibility, the UA MUST ignore any unrecognized 412 Expect-CT header directives, while still processing those directives 413 it does recognize. Section 2.1 specifies the directives "enforce", 414 "max-age", and "report-uri", but future specifications and 415 implementations might use additional directives. 417 2.3.4. Storage Model 419 Known Expect-CT Hosts are identified only by domain names, and never 420 IP addresses. If the substring matching the host production from the 421 Request-URI (of the message to which the host responded) 422 syntactically matches the IP-literal or IPv4address productions from 423 Section 3.2.2 of [RFC3986], then the UA MUST NOT note this host as a 424 Known Expect-CT Host. 426 Otherwise, if the substring does not congruently match an existing 427 Known Expect-CT Host's domain name, per the matching procedure 428 specified in Section 8.2 of [RFC6797], then the UA MUST add this host 429 to the Known Expect-CT Host cache. The UA caches: 431 o the Expect-CT Host's domain name, 433 o whether the "enforce" directive is present 435 o the Effective Expiration Date, which is the Effective Expect-CT 436 Date plus the value of the "max-age" directive. Alternatively, 437 the UA MAY cache enough information to calculate the Effective 438 Expiration Date. 440 o the value of the "report-uri" directive, if present. 442 If any other metadata from optional or future Expect-CT header 443 directives are present in the Expect-CT header, and the UA 444 understands them, the UA MAY note them as well. 446 UAs MAY set an upper limit on the value of max-age, so that UAs that 447 have noted erroneous Expect-CT hosts (whether by accident or due to 448 attack) have some chance of recovering over time. If the server sets 449 a max-age greater than the UA's upper limit, the UA MAY behave as if 450 the server set the max-age to the UA's upper limit. For example, if 451 the UA caps max-age at 5,184,000 seconds (60 days), and an Expect-CT 452 Host sets a max- age directive of 90 days in its Expect-CT header, 453 the UA MAY behave as if the max-age were effectively 60 days. (One 454 way to achieve this behavior is for the UA to simply store a value of 455 60 days instead of the 90-day value provided by the Expect-CT host.) 457 2.4. Evaluating Expect-CT Connections for CT Compliance 459 When a UA connects to a Known Expect-CT Host using a TLS connection, 460 if the TLS connection has errors, the UA MUST terminate the 461 connection without allowing the user to proceed anyway. (This 462 behavior is the same as that required by [RFC6797].) 464 If the connection has no errors, then the UA will apply an additional 465 correctness check: compliance with a CT Policy. A UA should evaluate 466 compliance with its CT Policy whenever connecting to a Known Expect- 467 CT Host, as soon as possible. It is acceptable to skip this CT 468 compliance check for some hosts according to local policy. For 469 example, a UA may disable CT compliance checks for hosts whose 470 validated certificate chain terminates at a user-defined trust 471 anchor, rather than a trust anchor built-in to the UA (or underlying 472 platform). 474 An Expect-CT Host is "expired" if the effective expiration date 475 refers to a date in the past. The UA MUST ignore any expired Expect- 476 CT Hosts in its cache and not treat such hosts as Known Expect-CT 477 hosts. 479 If a connection to a Known CT Host violates the UA's CT policy (i.e. 480 the connection is not CT-qualified), and if the Known Expect-CT 481 Host's Expect-CT metadata indicates an "enforce" configuration, the 482 UA MUST treat the CT compliance failure as a non-recoverable error. 484 If a connection to a Known CT Host violates the UA's CT policy, and 485 if the Known Expect-CT Host's Expect-CT metadata includes a "report- 486 uri", the UA SHOULD send an Expect-CT report to that "report-uri" 487 (Section 3). 489 A UA that has previously noted a host as a Known Expect-CT Host MUST 490 evaluate CT compliance when setting up the TLS session, before 491 beginning an HTTP conversation over the TLS channel. 493 If the UA does not evaluate CT compliance, e.g. because the user has 494 elected to disable it, or because a presented certificate chain 495 chains up to a user-defined trust anchor, UAs SHOULD NOT send Expect- 496 CT reports. 498 3. Reporting Expect-CT Failure 500 When the UA attempts to connect to a Known Expect-CT Host and the 501 connection is not CT-qualified, the UA SHOULD report Expect-CT 502 failures to the "report-uri", if any, in the Known Expect-CT Host's 503 Expect-CT metadata. 505 When the UA receives an Expect-CT response header field over a 506 connection that is not CT-qualified, if the UA has not already sent 507 an Expect-CT report for this connection, then the UA SHOULD report 508 Expect-CT failures to the configured "report-uri", if any. 510 3.1. Generating a violation report 512 To generate a violation report object, the UA constructs a JSON 513 object with the following keys and values: 515 o "date-time": the value for this key indicates the time the UA 516 observed the CT compliance failure. The value is a string 517 formatted according to Section 5.6, "Internet Date/Time Format", 518 of [RFC3339]. 520 o "hostname": the value is the hostname to which the UA made the 521 original request that failed the CT compliance check. The value 522 is provided as a string. 524 o "port": the value is the port to which the UA made the original 525 request that failed the CT compliance check. The value is 526 provided as an integer. 528 o "effective-expiration-date": the value indicates the Effective 529 Expiration Date (see Section 2.3.4) for the Expect-CT Host that 530 failed the CT compliance check. The value is provided as a string 531 formatted according to Section 5.6 of [RFC3339] ("Internet Date/ 532 Time Format"). 534 o "served-certificate-chain": the value is the certificate chain as 535 served by the Expect-CT Host during TLS session setup. The value 536 is provided as an array of strings, which MUST appear in the order 537 that the certificates were served; each string in the array is the 538 Privacy-Enhanced Mail (PEM) representation of each X.509 539 certificate as described in [RFC7468]. 541 o "validated-certificate-chain": the value is the certificate chain 542 as constructed by the UA during certificate chain verification. 543 (This may differ from the value of the "served-certificate-chain" 544 key.) The value is provided as an array of strings, which MUST 545 appear in the order matching the chain that the UA validated; each 546 string in the array is the Privacy-Enhanced Mail (PEM) 547 representation of each X.509 certificate as described in 548 [RFC7468]. 550 o "scts": the value represents the SCTs (if any) that the UA 551 received for the Expect-CT host and their validation statuses. 552 The value is provided as an array of JSON objects. The SCTs may 553 appear in any order. Each JSON object in the array has the 554 following keys: 556 * A "version" key, with an integer value. The UA MUST set this 557 value to "1" if the SCT is in the format defined in Section 3.2 558 of [RFC6962] and "2" if it is in the format defined in 559 Section 4.6 of [I-D.ietf-trans-rfc6962-bis]. 561 * The "status" key, with a string value that the UA MUST set to 562 one of the following values: "unknown" (indicating that the UA 563 does not have or does not trust the public key of the log from 564 which the SCT was issued), "valid" (indicating that the UA 565 successfully validated the SCT as described in Section 5.2 of 566 [RFC6962] or Section 8.2.3 of [I-D.ietf-trans-rfc6962-bis]), or 567 "invalid" (indicating that the SCT validation failed because 568 of, e.g., a bad signature). 570 * The "source" key, with a string value that indicates from where 571 the UA obtained the SCT, as defined in Section 3 or [RFC6962] 572 and Section 6 of [I-D.ietf-trans-rfc6962-bis]. The UA MUST set 573 the value to one of "tls-extension", "ocsp", or "embedded". 575 * The "serialized_sct" key, with a string value. If the value of 576 the "version" key is "1", the UA MUST set this value to the 577 base64 encoded [RFC4648] serialized 578 "SignedCertificateTimestamp" structure from Section 3.2 of 579 [RFC6962]. If the value of the "version" key is "2", the UA 580 MUST set this value to the base64 encoded [RFC4648] serialized 581 "TransItem" structure representing the SCT, as defined in 582 Section 4.6 of [I-D.ietf-trans-rfc6962-bis]. 584 o "failure-mode": the value indicates whether the Expect-CT report 585 was triggered by an Expect-CT policy in enforce or report-only 586 mode. The value is provided as a string. The UA MUST set this 587 value to "enforce" if the Expect-CT metadata indicates an 588 "enforce" configuration, and "report-only" otherwise. 590 o "test-report": the value is set to true if the report is being 591 sent by a testing client to verify that the reporting server 592 behaves correctly. The value is provided as a boolean, and MUST 593 be set to true if the report serves to test the server's behavior 594 and can be discarded. 596 3.2. Sending a violation report 598 The UA SHOULD report an Expect-CT failure when a connection to a 599 Known Expect-CT Host does not comply with the UA's CT Policy and the 600 host's Expect-CT metadata contains a "report-uri". Additionally, the 601 UA SHOULD report an Expect-CT failure when it receives an Expect-CT 602 header field which contains the "report-uri" directive over a 603 connection that does not comply with the UA's CT Policy. 605 The steps to report an Expect-CT failure are as follows. 607 1. Prepare a JSON object "report object" with the single key 608 "expect-ct-report", whose value is the result of generating a 609 violation report object as described in Section 3.1. 611 2. Let "report body" be the JSON stringification of "report object". 613 3. Let "report-uri" be the value of the "report-uri" directive in 614 the Expect-CT header field. 616 4. Send an HTTP POST request to "report-uri" with a "Content-Type" 617 header field of "application/expect-ct-report+json", and an 618 entity body consisting of "report body". 620 The UA MAY perform other operations as part of sending the HTTP POST 621 request, for example sending a CORS preflight as part of [FETCH]. 623 3.3. Receiving a violation report 625 Upon receiving an Expect-CT violation report, the report server MUST 626 respond with a 2xx (Successful) status code if it can parse the 627 request body as valid JSON and recognizes the hostname in the 628 "hostname" field of the report. If the report body cannot be parsed 629 or the report server does not expect to receive reports for the 630 hostname in the "hostname" field, the report server MUST respond with 631 a 4xx (Client Error) status code. 633 If the report's "test-report" key is set to true, the server MAY 634 discard the report without further processing but MUST still return a 635 2xx (Successful) status code. 637 4. Security Considerations 639 When UAs support the Expect-CT header, it becomes a potential vector 640 for hostile header attacks against site owners. If a site owner uses 641 a certificate issued by a certificate authority which does not embed 642 SCTs nor serve SCTs via OCSP or TLS extension, a malicious server 643 operator or attacker could temporarily reconfigure the host to comply 644 with the UA's CT policy, and add the Expect-CT header in enforcing 645 mode with a long "max-age". Implementing user agents would note this 646 as an Expect-CT Host (see Section 2.3.3). After having done this, 647 the configuration could then be reverted to not comply with the CT 648 policy, prompting failures. Note this scenario would require the 649 attacker to have substantial control over the infrastructure in 650 question, being able to obtain different certificates, change server 651 software, or act as a man-in-the-middle in connections. 653 Site operators could themselves only cure this situation by one of: 654 reconfiguring their web server to transmit SCTs using the TLS 655 extension defined in Section 6.5 of [I-D.ietf-trans-rfc6962-bis], 656 obtaining a certificate from an alternative certificate authority 657 which provides SCTs by one of the other methods, or by waiting for 658 the user agents' persisted notation of this as an Expect-CT host to 659 reach its "max-age". User agents may choose to implement mechanisms 660 for users to cure this situation, as noted in Section 7. 662 4.1. Maximum max-age 664 There is a security trade-off in that low maximum values provide a 665 narrow window of protection for users that visit the Known Expect-CT 666 Host only infrequently, while high maximum values might result in a 667 denial of service to a UA in the event of a hostile header attack, or 668 simply an error on the part of the site-owner. 670 There is probably no ideal maximum for the "max-age" directive. 671 Since Expect-CT is primarily a policy-expansion and investigation 672 technology rather than an end-user protection, a value on the order 673 of 30 days (2,592,000 seconds) may be considered a balance between 674 these competing security concerns. 676 4.2. Avoiding amplification attacks 678 Another kind of hostile header attack uses the "report-uri" mechanism 679 on many hosts not currently exposing SCTs as a method to cause a 680 denial-of-service to the host receiving the reports. If some highly- 681 trafficked websites emitted a non-enforcing Expect-CT header with a 682 "report-uri", implementing UAs' reports could flood the reporting 683 host. It is noted in Section 2.1.1 that UAs should limit the rate at 684 which they emit reports, but an attacker may alter the Expect-CT 685 header's fields to induce UAs to submit different reports to 686 different URIs to still cause the same effect. 688 5. Privacy Considerations 690 Expect-CT can be used to infer what Certificate Transparency policy 691 is in use, by attempting to retrieve specially-configured websites 692 which pass one user agents' policies but not another's. Note that 693 this consideration is true of UAs which enforce CT policies without 694 Expect-CT as well. 696 Additionally, reports submitted to the "report-uri" could reveal 697 information to a third party about which webpage is being accessed 698 and by which IP address, by using individual "report-uri" values for 699 individually-tracked pages. This information could be leaked even if 700 client-side scripting were disabled. 702 Implementations must store state about Known Expect-CT Hosts, and 703 hence which domains the UA has contacted. 705 Violation reports, as noted in Section 3, contain information about 706 the certificate chain that has violated the CT policy. In some 707 cases, such as organization-wide compromise of the end-to-end 708 security of TLS, this may include information about the interception 709 tools and design used by the organization that the organization would 710 otherwise prefer not be disclosed. 712 Because Expect-CT causes remotely-detectable behavior, it's advisable 713 that UAs offer a way for privacy-sensitive users to clear currently 714 noted Expect-CT hosts, and allow users to query the current state of 715 Known Expect-CT Hosts. 717 6. IANA Considerations 719 TBD 721 7. Usability Considerations 723 When the UA detects a Known Expect-CT Host in violation of the UA's 724 CT Policy, users will experience denials of service. It is advisable 725 for UAs to explain the reason why. 727 8. Authoring Considerations 729 8.1. HTTP Header 731 Expect-CT could be specified as a TLS extension or X.509 certificate 732 extension instead of an HTTP response header. Using an HTTP header 733 as the mechanism for Expect-CT introduces a layering mismatch: for 734 example, the software that terminates TLS and validates Certificate 735 Transparency information might know nothing about HTTP. 736 Nevertheless, an HTTP header was chosen primarily for ease of 737 deployment. In practice, deploying new certificate extensions 738 requires certificate authorities to support them, and new TLS 739 extensions require server software updates, including possibly to 740 servers outside of the site owner's direct control (such as in the 741 case of a third-party CDN). Ease of deployment is a high priority 742 for Expect-CT because it is intended as a temporary transition 743 mechanism for user agents that are transitioning to universal 744 Certificate Transparency requirements. 746 9. Changes 748 9.1. Since -02 750 o Add concept of test reports and specify that servers must respond 751 with 2xx status codes to valid reports. 753 o Add "failure-mode" key to reports to allow report servers to 754 distinguish report-only from enforced failures. 756 9.2. Since -01 758 o Change SCT reporting format to support both RFC 6962 and 6962-bis 759 SCTs. 761 9.3. Since -00 763 o Editorial changes 765 o Change Content-Type header of reports to 'application/expect-ct- 766 report+json' 768 o Update header field syntax to match convention (issue #327) 770 o Reference RFC 6962-bis instead of RFC 6962 772 10. References 774 10.1. Normative References 776 [FETCH] van Kesteren, A., "Fetch", n.d., 777 . 779 [HTML] Hickson, I., Pieters, S., van Kesteren, A., Jaegenstedt, 780 P., and D. Denicola, "HTML", n.d., 781 . 783 [I-D.ietf-trans-rfc6962-bis] 784 Laurie, B., Langley, A., Kasper, E., Messeri, E., and R. 785 Stradling, "Certificate Transparency Version 2.0", draft- 786 ietf-trans-rfc6962-bis-27 (work in progress), October 787 2017. 789 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 790 Requirement Levels", BCP 14, RFC 2119, 791 DOI 10.17487/RFC2119, March 1997, 792 . 794 [RFC3339] Klyne, G. and C. Newman, "Date and Time on the Internet: 795 Timestamps", RFC 3339, DOI 10.17487/RFC3339, July 2002, 796 . 798 [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform 799 Resource Identifier (URI): Generic Syntax", STD 66, 800 RFC 3986, DOI 10.17487/RFC3986, January 2005, 801 . 803 [RFC4648] Josefsson, S., "The Base16, Base32, and Base64 Data 804 Encodings", RFC 4648, DOI 10.17487/RFC4648, October 2006, 805 . 807 [RFC5234] Crocker, D., Ed. and P. Overell, "Augmented BNF for Syntax 808 Specifications: ABNF", STD 68, RFC 5234, 809 DOI 10.17487/RFC5234, January 2008, 810 . 812 [RFC5246] Dierks, T. and E. Rescorla, "The Transport Layer Security 813 (TLS) Protocol Version 1.2", RFC 5246, 814 DOI 10.17487/RFC5246, August 2008, 815 . 817 [RFC6797] Hodges, J., Jackson, C., and A. Barth, "HTTP Strict 818 Transport Security (HSTS)", RFC 6797, 819 DOI 10.17487/RFC6797, November 2012, 820 . 822 [RFC6962] Laurie, B., Langley, A., and E. Kasper, "Certificate 823 Transparency", RFC 6962, DOI 10.17487/RFC6962, June 2013, 824 . 826 [RFC7230] Fielding, R., Ed. and J. Reschke, Ed., "Hypertext Transfer 827 Protocol (HTTP/1.1): Message Syntax and Routing", 828 RFC 7230, DOI 10.17487/RFC7230, June 2014, 829 . 831 [RFC7234] Fielding, R., Ed., Nottingham, M., Ed., and J. Reschke, 832 Ed., "Hypertext Transfer Protocol (HTTP/1.1): Caching", 833 RFC 7234, DOI 10.17487/RFC7234, June 2014, 834 . 836 [RFC7468] Josefsson, S. and S. Leonard, "Textual Encodings of PKIX, 837 PKCS, and CMS Structures", RFC 7468, DOI 10.17487/RFC7468, 838 April 2015, . 840 [W3C.REC-html51-20161101] 841 Faulkner, S., Eicholz, A., Leithead, T., and A. Danilo, 842 "HTML 5.1", World Wide Web Consortium Recommendation REC- 843 html51-20161101, November 2016, 844 . 846 10.2. URIs 848 [1] https://lists.w3.org/Archives/Public/ietf-http-wg/ 850 [2] http://httpwg.github.io/ 852 [3] https://github.com/httpwg/http-extensions/labels/expect-ct 854 Author's Address 856 Emily Stark 857 Google 859 Email: estark@google.com