idnits 2.17.1 draft-ietf-httpbis-http2-secondary-certs-01.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 28, 2018) is 2154 days in the past. Is this intentional? Checking references for intended status: Proposed Standard ---------------------------------------------------------------------------- (See RFCs 3967 and 4897 for information about using normative references to lower-maturity documents in RFCs) -- Looks like a reference, but probably isn't: '1' on line 979 -- Looks like a reference, but probably isn't: '2' on line 981 -- Looks like a reference, but probably isn't: '3' on line 983 == Outdated reference: A later version (-15) exists of draft-ietf-tls-exported-authenticator-04 == Outdated reference: A later version (-28) exists of draft-ietf-tls-tls13-22 ** Obsolete normative reference: RFC 5246 (Obsoleted by RFC 8446) ** Obsolete normative reference: RFC 7230 (Obsoleted by RFC 9110, RFC 9112) ** Obsolete normative reference: RFC 7540 (Obsoleted by RFC 9113) Summary: 4 errors (**), 0 flaws (~~), 3 warnings (==), 4 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 HTTP M. Bishop 3 Internet-Draft Akamai 4 Intended status: Standards Track N. Sullivan 5 Expires: November 29, 2018 Cloudflare 6 M. Thomson 7 Mozilla 8 May 28, 2018 10 Secondary Certificate Authentication in HTTP/2 11 draft-ietf-httpbis-http2-secondary-certs-01 13 Abstract 15 A use of TLS Exported Authenticators is described which enables 16 HTTP/2 clients and servers to offer additional certificate-based 17 credentials after the connection is established. The means by which 18 these credentials are used with requests is defined. 20 Note to Readers 22 Discussion of this draft takes place on the HTTP working group 23 mailing list (ietf-http-wg@w3.org), which is archived at 24 https://lists.w3.org/Archives/Public/ietf-http-wg/ [1]. 26 Working Group information can be found at http://httpwg.github.io/ 27 [2]; source code and issues list for this draft can be found at 28 https://github.com/httpwg/http-extensions/labels/secondary-certs [3]. 30 Status of This Memo 32 This Internet-Draft is submitted in full conformance with the 33 provisions of BCP 78 and BCP 79. 35 Internet-Drafts are working documents of the Internet Engineering 36 Task Force (IETF). Note that other groups may also distribute 37 working documents as Internet-Drafts. The list of current Internet- 38 Drafts is at https://datatracker.ietf.org/drafts/current/. 40 Internet-Drafts are draft documents valid for a maximum of six months 41 and may be updated, replaced, or obsoleted by other documents at any 42 time. It is inappropriate to use Internet-Drafts as reference 43 material or to cite them other than as "work in progress." 45 This Internet-Draft will expire on November 29, 2018. 47 Copyright Notice 49 Copyright (c) 2018 IETF Trust and the persons identified as the 50 document authors. All rights reserved. 52 This document is subject to BCP 78 and the IETF Trust's Legal 53 Provisions Relating to IETF Documents 54 (https://trustee.ietf.org/license-info) in effect on the date of 55 publication of this document. Please review these documents 56 carefully, as they describe your rights and restrictions with respect 57 to this document. Code Components extracted from this document must 58 include Simplified BSD License text as described in Section 4.e of 59 the Trust Legal Provisions and are provided without warranty as 60 described in the Simplified BSD License. 62 Table of Contents 64 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3 65 1.1. Server Certificate Authentication . . . . . . . . . . . . 3 66 1.2. Client Certificate Authentication . . . . . . . . . . . . 4 67 1.2.1. HTTP/1.1 using TLS 1.2 and previous . . . . . . . . . 5 68 1.2.2. HTTP/1.1 using TLS 1.3 . . . . . . . . . . . . . . . 6 69 1.2.3. HTTP/2 . . . . . . . . . . . . . . . . . . . . . . . 6 70 1.3. HTTP-Layer Certificate Authentication . . . . . . . . . . 7 71 1.4. Terminology . . . . . . . . . . . . . . . . . . . . . . . 8 72 2. Discovering Additional Certificates at the HTTP/2 Layer . . . 8 73 2.1. Indicating support for HTTP-layer certificate 74 authentication . . . . . . . . . . . . . . . . . . . . . 8 75 2.2. Making certificates or requests available . . . . . . . . 9 76 2.3. Requiring certificate authentication . . . . . . . . . . 9 77 2.3.1. Requiring additional server certificates . . . . . . 9 78 3. Certificates Frames for HTTP/2 . . . . . . . . . . . . . . . 11 79 3.1. The CERTIFICATE_NEEDED frame . . . . . . . . . . . . . . 11 80 3.2. The USE_CERTIFICATE Frame . . . . . . . . . . . . . . . . 12 81 3.3. The CERTIFICATE_REQUEST Frame . . . . . . . . . . . . . . 14 82 3.3.1. Exported Authenticator Request Characteristics . . . 15 83 3.4. The CERTIFICATE Frame . . . . . . . . . . . . . . . . . . 15 84 3.4.1. Exported Authenticator Characteristics . . . . . . . 16 85 4. Indicating failures during HTTP-Layer Certificate 86 Authentication . . . . . . . . . . . . . . . . . . . . . . . 16 87 5. Security Considerations . . . . . . . . . . . . . . . . . . . 17 88 5.1. Impersonation . . . . . . . . . . . . . . . . . . . . . . 17 89 5.2. Fingerprinting . . . . . . . . . . . . . . . . . . . . . 18 90 5.3. Denial of Service . . . . . . . . . . . . . . . . . . . . 18 91 5.4. Confusion About State . . . . . . . . . . . . . . . . . . 18 92 6. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 19 93 6.1. HTTP/2 SETTINGS_HTTP_CERT_AUTH Setting . . . . . . . . . 19 94 6.2. New HTTP/2 Frames . . . . . . . . . . . . . . . . . . . . 19 95 6.3. New HTTP/2 Error Codes . . . . . . . . . . . . . . . . . 20 96 7. References . . . . . . . . . . . . . . . . . . . . . . . . . 20 97 7.1. Normative References . . . . . . . . . . . . . . . . . . 20 98 7.2. Informative References . . . . . . . . . . . . . . . . . 21 99 7.3. URIs . . . . . . . . . . . . . . . . . . . . . . . . . . 21 100 Appendix A. Change Log . . . . . . . . . . . . . . . . . . . . . 21 101 A.1. Since draft-ietf-httpbis-http2-secondary-certs-00: . . . 21 102 A.2. Since draft-bishop-httpbis-http2-additional-certs-05: . . 22 103 Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . . 22 104 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 22 106 1. Introduction 108 HTTP clients need to know that the content they receive on a 109 connection comes from the origin that they intended to retrieve in 110 from. The traditional form of server authentication in HTTP has been 111 in the form of a single X.509 certificate provided during the TLS 112 RFC5246 [I-D.ietf-tls-tls13] handshake. 114 Many existing HTTP [RFC7230] servers also have authentication 115 requirements for the resources they serve. Of the bountiful 116 authentication options available for authenticating HTTP requests, 117 client certificates present a unique challenge for resource-specific 118 authentication requirements because of the interaction with the 119 underlying TLS layer. 121 TLS 1.2 [RFC5246] supports one server and one client certificate on a 122 connection. These certificates may contain multiple identities, but 123 only one certificate may be provided. 125 Many HTTP servers host content from several origins. HTTP/2 permits 126 clients to reuse an existing HTTP connection to a server provided 127 that the secondary origin is also in the certificate provided during 128 the TLS handshake. In many cases, servers choose to maintain 129 separate certificates for different origins but still desire the 130 benefits of a shared HTTP connection. 132 1.1. Server Certificate Authentication 134 Section 9.1.1 of [RFC7540] describes how connections may be used to 135 make requests from multiple origins as long as the server is 136 authoritative for both. A server is considered authoritative for an 137 origin if DNS resolves the origin to the IP address of the server and 138 (for TLS) if the certificate presented by the server contains the 139 origin in the Subject Alternative Names field. 141 [RFC7838] enables a step of abstraction from the DNS resolution. If 142 both hosts have provided an Alternative Service at hostnames which 143 resolve to the IP address of the server, they are considered 144 authoritative just as if DNS resolved the origin itself to that 145 address. However, the server's one TLS certificate is still required 146 to contain the name of each origin in question. 148 [RFC8336] relaxes the requirement to perform the DNS lookup if 149 already connected to a server with an appropriate certificate which 150 claims support for a particular origin. 152 Servers which host many origins often would prefer to have separate 153 certificates for some sets of origins. This may be for ease of 154 certificate management (the ability to separately revoke or renew 155 them), due to different sources of certificates (a CDN acting on 156 behalf of multiple origins), or other factors which might drive this 157 administrative decision. Clients connecting to such origins cannot 158 currently reuse connections, even if both client and server would 159 prefer to do so. 161 Because the TLS SNI extension is exchanged in the clear, clients 162 might also prefer to retrieve certificates inside the encrypted 163 context. When this information is sensitive, it might be 164 advantageous to request a general-purpose certificate or anonymous 165 ciphersuite at the TLS layer, while acquiring the "real" certificate 166 in HTTP after the connection is established. 168 1.2. Client Certificate Authentication 170 For servers that wish to use client certificates to authenticate 171 users, they might request client authentication during or immediately 172 after the TLS handshake. However, if not all users or resources need 173 certificate-based authentication, a request for a certificate has the 174 unfortunate consequence of triggering the client to seek a 175 certificate, possibly requiring user interaction, network traffic, or 176 other time-consuming activities. During this time, the connection is 177 stalled in many implementations. Such a request can result in a poor 178 experience, particularly when sent to a client that does not expect 179 the request. 181 The TLS 1.3 CertificateRequest can be used by servers to give clients 182 hints about which certificate to offer. Servers that rely on 183 certificate-based authentication might request different certificates 184 for different resources. Such a server cannot use contextual 185 information about the resource to construct an appropriate TLS 186 CertificateRequest message during the initial handshake. 188 Consequently, client certificates are requested at connection 189 establishment time only in cases where all clients are expected or 190 required to have a single certificate that is used for all resources. 192 Many other uses for client certificates are reactive, that is, 193 certificates are requested in response to the client making a 194 request. 196 1.2.1. HTTP/1.1 using TLS 1.2 and previous 198 In HTTP/1.1, a server that relies on client authentication for a 199 subset of users or resources does not request a certificate when the 200 connection is established. Instead, it only requests a client 201 certificate when a request is made to a resource that requires a 202 certificate. TLS 1.2 [RFC5246] accomodates this by permitting the 203 server to request a new TLS handshake, in which the server will 204 request the client's certificate. 206 Figure 1 shows the server initiating a TLS-layer renegotiation in 207 response to receiving an HTTP/1.1 request to a protected resource. 209 Client Server 210 -- (HTTP) GET /protected -------------------> *1 211 <---------------------- (TLS) HelloRequest -- *2 212 -- (TLS) ClientHello -----------------------> 213 <------------------ (TLS) ServerHello, ... -- 214 <---------------- (TLS) CertificateRequest -- *3 215 -- (TLS) ..., Certificate ------------------> *4 216 -- (TLS) Finished --------------------------> 217 <-------------------------- (TLS) Finished -- 218 <--------------------------- (HTTP) 200 OK -- *5 220 Figure 1: HTTP/1.1 Reactive Certificate Authentication with TLS 1.2 222 In this example, the server receives a request for a protected 223 resource (at *1 on Figure 1). Upon performing an authorization 224 check, the server determines that the request requires authentication 225 using a client certificate and that no such certificate has been 226 provided. 228 The server initiates TLS renegotiation by sending a TLS HelloRequest 229 (at *2). The client then initiates a TLS handshake. Note that some 230 TLS messages are elided from the figure for the sake of brevity. 232 The critical messages for this example are the server requesting a 233 certificate with a TLS CertificateRequest (*3); this request might 234 use information about the request or resource. The client then 235 provides a certificate and proof of possession of the private key in 236 Certificate and CertificateVerify messages (*4). 238 When the handshake completes, the server performs any authorization 239 checks a second time. With the client certificate available, it then 240 authorizes the request and provides a response (*5). 242 1.2.2. HTTP/1.1 using TLS 1.3 244 TLS 1.3 [I-D.ietf-tls-tls13] introduces a new client authentication 245 mechanism that allows for clients to authenticate after the handshake 246 has been completed. For the purposes of authenticating an HTTP 247 request, this is functionally equivalent to renegotiation. Figure 2 248 shows the simpler exchange this enables. 250 Client Server 251 -- (HTTP) GET /protected -------------------> 252 <---------------- (TLS) CertificateRequest -- 253 -- (TLS) Certificate, CertificateVerify, 254 Finished -----------------------> 255 <--------------------------- (HTTP) 200 OK -- 257 Figure 2: HTTP/1.1 Reactive Certificate Authentication with TLS 1.3 259 TLS 1.3 does not support renegotiation, instead supporting direct 260 client authentication. In contrast to the TLS 1.2 example, in TLS 261 1.3, a server can simply request a certificate. 263 1.2.3. HTTP/2 265 An important part of the HTTP/1.1 exchange is that the client is able 266 to easily identify the request that caused the TLS renegotiation. 267 The client is able to assume that the next unanswered request on the 268 connection is responsible. The HTTP stack in the client is then able 269 to direct the certificate request to the application or component 270 that initiated that request. This ensures that the application has 271 the right contextual information for processing the request. 273 In HTTP/2, a client can have multiple outstanding requests. Without 274 some sort of correlation information, a client is unable to identify 275 which request caused the server to request a certificate. 277 Thus, the minimum necessary mechanism to support reactive certificate 278 authentication in HTTP/2 is an identifier that can be use to 279 correlate an HTTP request with a request for a certificate. Since 280 streams are used for individual requests, correlation with a stream 281 is sufficient. 283 [RFC7540] prohibits renegotiation after any application data has been 284 sent. This completely blocks reactive certificate authentication in 285 HTTP/2 using TLS 1.2. If this restriction were relaxed by an 286 extension or update to HTTP/2, such an identifier could be added to 287 TLS 1.2 by means of an extension to TLS. Unfortunately, many TLS 1.2 288 implementations do not permit application data to continue during a 289 renegotiation. This is problematic for a multiplexed protocol like 290 HTTP/2. 292 1.3. HTTP-Layer Certificate Authentication 294 This draft defines HTTP/2 frames to carry the relevant certificate 295 messages, enabling certificate-based authentication of both clients 296 and servers independent of TLS version. This mechanism can be 297 implemented at the HTTP layer without breaking the existing interface 298 between HTTP and applications above it. 300 This could be done in a naive manner by replicating the TLS messages 301 as HTTP/2 frames on each stream. However, this would create needless 302 redundancy between streams and require frequent expensive signing 303 operations. Instead, TLS Exported Authenticators 304 [I-D.ietf-tls-exported-authenticator] are exchanged on stream zero 305 and other frames incorporate them to particular requests by reference 306 as needed. 308 TLS Exported Authenticators are structured messages that can be 309 exported by either party of a TLS connection and validated by the 310 other party. Given an established TLS connection, a request can be 311 constructed which describes the desired certificate and an 312 authenticator message can be constructed proving possession of a 313 certificate and a corresponding private key. Both requests and 314 authenticators can be generated by either the client or the server. 315 Exported Authenticators use the message structures from sections 316 4.3.2 and 4.4 of [I-D.ietf-tls-tls13], but different parameters. 318 Each Authenticator is computed using a Handshake Context and Finished 319 MAC Key derived from the TLS session. The Handshake Context is 320 identical for both parties of the TLS connection, while the Finished 321 MAC Key is dependent on whether the Authenticator is created by the 322 client or the server. 324 Successfully verified Authenticators result in certificate chains, 325 with verified possession of the corresponding private key, which can 326 be supplied into a collection of available certificates. Likewise, 327 descriptions of desired certificates can be supplied into these 328 collections. 330 Section 2 describes how the feature is employed, defining means to 331 detect support in peers (Section 2.1), make certificates and requests 332 available (Section 2.2), and indicate when streams are blocked 333 waiting on an appropriate certificate (Section 2.3). Section 3 334 defines the required frame types, which parallel the TLS 1.3 message 335 exchange. Finally, Section 4 defines new error types which can be 336 used to notify peers when the exchange has not been successful. 338 1.4. Terminology 340 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 341 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 342 "OPTIONAL" in this document are to be interpreted as described in BCP 343 14 [RFC2119] [RFC8174] when, and only when, they appear in all 344 capitals, as shown here. 346 2. Discovering Additional Certificates at the HTTP/2 Layer 348 A certificate chain with proof of possession of the private key 349 corresponding to the end-entity certificate is sent as a sequence of 350 "CERTIFICATE" frames (see Section 3.4) on stream zero. Once the 351 holder of a certificate has sent the chain and proof, this 352 certificate chain is cached by the recipient and available for future 353 use. Clients can proactively indicate the certificate they intend to 354 use on each request using an unsolicited "USE_CERTIFICATE" frame, if 355 desired. The previously-supplied certificates are available for 356 reference without having to resend them. 358 Otherwise, the server uses a "CERTIFICATE_REQUEST" frame to describe 359 a class of certificates on stream zero, then uses 360 "CERTIFICATE_NEEDED" frames to associate these with individual 361 requests. The client responds with a "USE_CERTIFICATE" frame 362 indicating the certificate which should be used to satisfy the 363 request. 365 Data sent by each peer is correlated by the ID given in each frame. 366 This ID is unrelated to values used by the other peer, even if each 367 uses the same ID in certain cases. "USE_CERTIFICATE" frames indicate 368 whether they are sent proactively or are in response to a 369 "CERTIFICATE_NEEDED" frame. 371 2.1. Indicating support for HTTP-layer certificate authentication 373 Clients and servers that will accept requests for HTTP-layer 374 certificate authentication indicate this using the HTTP/2 375 "SETTINGS_HTTP_CERT_AUTH" (0xSETTING-TBD) setting. 377 The initial value for the "SETTINGS_HTTP_CERT_AUTH" setting is 0, 378 indicating that the peer does not support HTTP-layer certificate 379 authentication. If a peer does support HTTP-layer certificate 380 authentication, the value is 1. 382 2.2. Making certificates or requests available 384 When both peers have advertised support for HTTP-layer certificates 385 as in Section 2.1, either party can supply additional certificates 386 into the connection at any time. This means that clients or servers 387 which predict a certificate will be required could supply the 388 certificate before being asked. These certificates are available for 389 reference by future "USE_CERTIFICATE" frames. 391 Certificates supplied by servers can be considered by clients without 392 further action by the server. A server SHOULD NOT send certificates 393 which do not cover origins which it is prepared to service on the 394 current connection, but MAY use the ORIGIN frame [RFC8336] to 395 indicate that not all covered origins will be served. 397 Client Server 398 <------------------ (stream 0) CERTIFICATE -- 399 ... 400 -- (stream N) GET /from-new-origin ---------> 401 <----------------------- (stream N) 200 OK -- 403 Figure 3: Proactive Server Certificate 405 Client Server 406 -- (stream 0) CERTIFICATE ------------------> 407 -- (stream 0) USE_CERTIFICATE (S=1) --------> 408 -- (stream 0) USE_CERTIFICATE (S=3) --------> 409 -- (streams 1,3) GET /protected ------------> 410 <-------------------- (streams 1,3) 200 OK -- 412 Figure 4: Proactive Client Certificate 414 Likewise, either party can supply a "CERTIFICATE_REQUEST" that 415 outlines parameters of a certificate they might request in the 416 future. Upon receipt of a "CERTIFICATE_REQUEST", servers SHOULD 417 provide a corresponding certificate. Clients MAY wait for a 418 "CERTIFICATE_NEEDED" frame to assist in associating the certificate 419 request with a particular HTTP transition. 421 2.3. Requiring certificate authentication 423 2.3.1. Requiring additional server certificates 425 As defined in [RFC7540], when a client finds that a https:// origin 426 (or Alternative Service [RFC7838]) to which it needs to make a 427 request has the same IP address as a server to which it is already 428 connected, it MAY check whether the TLS certificate provided contains 429 the new origin as well, and if so, reuse the connection. 431 If the TLS certificate does not contain the new origin, but the 432 server has claimed support for that origin (with an ORIGIN frame, see 433 [RFC8336]) and advertised support for HTTP-layer certificates (see 434 Section 2.1), the client MAY send a "CERTIFICATE_REQUEST" frame 435 describing the desired origin. Servers SHOULD provide a 436 corresponding certificate if one is available. 438 If the server does not have the desired certificate, it MUST [see 439 issue #564]. In this case, or if the server has not advertised 440 support for HTTP-layer certificates, the client MUST NOT send any 441 requests for resources in that origin on the current connection. 443 Client Server 444 <----------------------- (stream 0) ORIGIN -- 445 -- (stream 0) CERTIFICATE_REQUEST ----------> 446 <------------------ (stream 0) CERTIFICATE -- 447 -- (stream N) GET /from-new-origin ---------> 448 <----------------------- (stream N) 200 OK -- 450 Figure 5: Client-Requested Certificate 452 Likewise, the server sends a "CERTIFICATE_NEEDED" frame for each 453 stream where certificate authentication is required. The client 454 answers with a "USE_CERTIFICATE" frame indicating the certificate to 455 use on that stream. If the request parameters or the responding 456 certificate are not already available, they will need to be sent as 457 described in Section 2.2 as part of this exchange. 459 Client Server 460 <---------- (stream 0) CERTIFICATE_REQUEST -- 461 ... 462 -- (stream N) GET /protected ---------------> 463 <----- (stream 0) CERTIFICATE_NEEDED (S=N) -- 464 -- (stream 0) CERTIFICATE ------------------> 465 -- (stream 0) USE_CERTIFICATE (S=N) --------> 466 <----------------------- (stream N) 200 OK -- 468 Figure 6: Reactive Certificate Authentication 470 If a client receives a "PUSH_PROMISE" referencing an origin for which 471 it has not yet received the server's certificate, this is a fatal 472 connection error (see section 8.2 of [RFC7540]). To avoid this, 473 servers MUST supply the associated certificates before pushing 474 resources from a different origin. 476 3. Certificates Frames for HTTP/2 478 The "CERTIFICATE_REQUEST" and "CERTIFICATE_NEEDED" frames are 479 correlated by their "Request-ID" field. Subsequent 480 "CERTIFICATE_NEEDED" frames with the same "Request-ID" value MAY be 481 sent for other streams where the sender is expecting a certificate 482 with the same parameters. 484 The "CERTIFICATE", and "USE_CERTIFICATE" frames are correlated by 485 their "Cert-ID" field. Subsequent "USE_CERTIFICATE" frames with the 486 same "Cert-ID" MAY be sent in response to other "CERTIFICATE_NEEDED" 487 frames and refer to the same certificate. 489 "CERTIFICATE_NEEDED" and "USE_CERTIFICATE" frames are correlated by 490 the Stream ID they reference. Unsolicited "USE_CERTIFICATE" frames 491 are not responses to "CERTIFICATE_NEEDED" frames; otherwise, each 492 "USE_CERTIFICATE" frame for a stream is considered to respond to a 493 "CERTIFICATE_NEEDED" frame for the same stream in sequence. 495 +---------+ +---------+ 496 | REQUEST | | CERT | 497 +---------+ +---------+ 498 | | 499 | Request-ID | Cert-ID 500 | | 501 v v 502 +---------+ Stream ID +---------+ 503 | NEEDED |---------->| USE | 504 +---------+ +---------+ 506 Figure 7: Frame correlation 508 "Request-ID" and "Cert-ID" are independent and sender-local. The use 509 of the same value by the other peer or in the other context does not 510 imply any correlation between these frames. These values MUST be 511 unique per sender for each space over the lifetime of the connection. 513 3.1. The CERTIFICATE_NEEDED frame 515 The "CERTIFICATE_NEEDED" frame (0xFRAME-TBD1) is sent on stream zero 516 to indicate that the HTTP request on the indicated stream is blocked 517 pending certificate authentication. The frame includes stream ID and 518 a request identifier which can be used to correlate the stream with a 519 previous "CERTIFICATE_REQUEST" frame sent on stream zero. The 520 "CERTIFICATE_REQUEST" describes the certificate the sender requires 521 to make progress on the stream in question. 523 0 1 2 3 524 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 525 +---------------------------------------------------------------+ 526 |R| Stream ID (31) | 527 +-------------------------------+-------------------------------+ 528 | Request-ID (16) | 529 +-------------------------------+ 531 Figure 8: CERTIFICATE_NEEDED frame payload 533 The "CERTIFICATE_NEEDED" frame contains 6 octets. The first four 534 octets indicate the Stream ID of the affected stream. The following 535 two octets are the authentication request identifier, "Request-ID". 536 A peer that receives a "CERTIFICATE_NEEDED" of any other length MUST 537 treat this as a stream error of type "PROTOCOL_ERROR". Frames with 538 identical request identifiers refer to the same 539 "CERTIFICATE_REQUEST". 541 A server MAY send multiple "CERTIFICATE_NEEDED" frames for the same 542 stream. If a server requires that a client provide multiple 543 certificates before authorizing a single request, each required 544 certificate MUST be indicated with a separate "CERTIFICATE_NEEDED" 545 frame, each of which MUST have a different request identifier 546 (referencing different "CERTIFICATE_REQUEST" frames describing each 547 required certificate). To reduce the risk of client confusion, 548 servers SHOULD NOT have multiple outstanding "CERTIFICATE_NEEDED" 549 frames for the same stream at any given time. 551 Clients MUST NOT send multiple "CERTIFICATE_NEEDED" frames for the 552 same stream. 554 The "CERTIFICATE_NEEDED" frame MUST NOT be sent to a peer which has 555 not advertised support for HTTP-layer certificate authentication. 557 The "CERTIFICATE_NEEDED" frame MUST NOT reference a stream in the 558 "half-closed (local)" or "closed" states [RFC7540]. A client that 559 receives a "CERTIFICATE_NEEDED" frame for a stream which is not in a 560 valid state SHOULD treat this as a stream error of type 561 "PROTOCOL_ERROR". 563 3.2. The USE_CERTIFICATE Frame 565 The "USE_CERTIFICATE" frame (0xFRAME-TBD4) is sent on stream zero to 566 indicate which certificate is being used on a particular request 567 stream. 569 The "USE_CERTIFICATE" frame defines a single flag: 571 UNSOLICITED (0x01): Indicates that no "CERTIFICATE_NEEDED" frame has 572 yet been received for this stream. 574 The payload of the "USE_CERTIFICATE" frame is as follows: 576 0 1 2 3 577 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 578 +---------------------------------------------------------------+ 579 |R| Stream ID (31) | 580 +-------------------------------+-------------------------------+ 581 | [Cert-ID (16)] | 582 +-------------------------------+ 584 Figure 9: USE_CERTIFICATE frame payload 586 The first four octets indicate the Stream ID of the affected stream. 587 The following two octets, if present, contain the two-octet "Cert-ID" 588 of the certificate the sender wishes to use. This MUST be the ID of 589 a certificate for which proof of possession has been presented in a 590 "CERTIFICATE" frame. Recipients of a "USE_CERTIFICATE" frame of any 591 other length MUST treat this as a stream error of type 592 "PROTOCOL_ERROR". Frames with identical certificate identifiers 593 refer to the same certificate chain. 595 A "USE_CERTIFICATE" frame which omits the Cert-ID refers to the 596 certificate provided at the TLS layer, if any. If no certificate was 597 provided at the TLS layer, the stream should be processed with no 598 authentication, likely returning an authentication-related error at 599 the HTTP level (e.g. 403) for servers or routing the request to a new 600 connection for clients. 602 The "UNSOLICITED" flag MAY be set by clients on the first 603 "USE_CERTIFICATE" frame referring to a given stream. This permits a 604 client to proactively indicate which certificate should be used when 605 processing a new request. When such an unsolicited indication refers 606 to a request that has not yet been received, servers SHOULD cache the 607 indication briefly in anticipation of the request. 609 Receipt of more than one unsolicited "USE_CERTIFICATE" frames or an 610 unsolicited "USE_CERTIFICATE" frame which is not the first in 611 reference to a given stream MUST be treated as a stream error of type 612 "CERTIFICATE_OVERUSED". 614 Each "USE_CERTIFICATE" frame which is not marked as unsolicited is 615 considered to respond in order to the "CERTIFICATE_NEEDED" frames for 616 the same stream. If a "USE_CERTIFICATE" frame is received for which 617 a "CERTIFICATE_NEEDED" frame has not been sent, this MUST be treated 618 as a stream error of type "CERTIFICATE_OVERUSED". 620 Receipt of a "USE_CERTIFICATE" frame with an unknown "Cert-ID" MUST 621 result in a stream error of type "PROTOCOL_ERROR". 623 The referenced certificate chain needs to conform to the requirements 624 expressed in the "CERTIFICATE_REQUEST" to the best of the sender's 625 ability, or the recipient is likely to reject it as unsuitable 626 despite properly validating the authenticator. If the recipient 627 considers the certificate unsuitable, it MAY at its discretion either 628 return an error at the HTTP semantic layer, or respond with a stream 629 error [RFC7540] on any stream where the certificate is used. 630 Section 4 defines certificate-related error codes which might be 631 applicable. 633 3.3. The CERTIFICATE_REQUEST Frame 635 The "CERTIFICATE_REQUEST" frame (id=0xFRAME-TBD2) provides a exported 636 authenticator request message from the TLS layer that specifies a 637 desired certificate. This describes the certificate the sender 638 wishes to have presented. 640 The "CERTIFICATE_REQUEST" frame SHOULD NOT be sent to a peer which 641 has not advertised support for HTTP-layer certificate authentication. 643 The "CERTIFICATE_REQUEST" frame MUST be sent on stream zero. A 644 "CERTIFICATE_REQUEST" frame received on any other stream MUST be 645 rejected with a stream error of type "PROTOCOL_ERROR". 647 0 1 2 3 648 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 649 +-------------------------------+-------------------------------+ 650 | Request-ID (16) | Request (?) ... 651 +---------------------------------------------------------------+ 653 Figure 10: CERTIFICATE_REQUEST frame payload 655 The frame contains the following fields: 657 Request-ID: "Request-ID" is a 16-bit opaque identifier used to 658 correlate subsequent certificate-related frames with this request. 659 The identifier MUST be unique in the session for the sender. 661 Request: An exported authenticator request, generated using the 662 "request" API described in [I-D.ietf-tls-exported-authenticator]. 663 See Section 3.4.1 for more details on the input to this API. 665 3.3.1. Exported Authenticator Request Characteristics 667 The Exported Authenticator "request" API defined in 668 [I-D.ietf-tls-exported-authenticator] takes as input a set of desired 669 certificate characteristics and a "certificate_request_context", 670 which needs to be unpredictable. When generating exported 671 authenticators for use with this extension, the 672 "certificate_request_context" MUST contain both the two-octet 673 Request-ID as well as at least 96 bits of additional entropy. 675 The TLS library on the authenticating peer will provide mechanisms to 676 select an appropriate certificate to respond to the transported 677 request. TLS libraries on servers MUST be able to recognize the 678 "server_name" extension ([RFC6066]) at a minimum. Clients MUST 679 always specify the desired origin using this extension, though other 680 extensions MAY also be included. 682 3.4. The CERTIFICATE Frame 684 The "CERTIFICATE" frame (id=0xFRAME-TBD3) provides a exported 685 authenticator message from the TLS layer that provides a chain of 686 certificates, associated extensions and proves possession of the 687 private key corresponding to the end-entity certificate. 689 The "CERTIFICATE" frame defines two flags: 691 TO_BE_CONTINUED (0x01): Indicates that the exported authenticator 692 spans more than one frame. 694 0 1 2 3 695 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 696 +-------------------------------+-------------------------------+ 697 | Cert-ID (16) | Authenticator Fragment (*)... 698 +---------------------------------------------------------------+ 700 Figure 11: CERTIFICATE frame payload 702 The "Exported Authenticator Fragment" field contains a portion of the 703 opaque data returned from the TLS connection exported authenticator 704 "authenticate" API. See Section 3.4.1 for more details on the input 705 to this API. 707 This opaque data is transported in zero or more "CERTIFICATE" frames 708 with the "TO_BE_CONTINUED" flag set, followed by one "CERTIFICATE" 709 frame with the "TO_BE_CONTINUED" flag unset. Each of these frames 710 contains the same "Cert-ID" field, permitting them to be associated 711 with each other. Receipt of any "CERTIFICATE" frame with the same 712 "Cert-ID" following the receipt of a "CERTIFICATE" frame with 713 "TO_BE_CONTINUED" unset MUST be treated as a connection error of type 714 "PROTOCOL_ERROR". 716 Upon receiving a complete series of "CERTIFICATE" frames, the 717 receiver may validate the Exported Authenticator value by using the 718 exported authenticator API. This returns either an error indicating 719 that the message was invalid, or the certificate chain and extensions 720 used to create the message. 722 The "CERTIFICATE" frame MUST be sent on stream zero. A "CERTIFICATE" 723 frame received on any other stream MUST be rejected with a stream 724 error of type "PROTOCOL_ERROR". 726 3.4.1. Exported Authenticator Characteristics 728 The Exported Authenticator API defined in 729 [I-D.ietf-tls-exported-authenticator] takes as input a request, a set 730 of certificates, and supporting information about the certificate 731 (OCSP, SCT, etc.). The result is an opaque token which is used when 732 generating the "CERTIFICATE" frame. 734 Upon receipt of a "CERTIFICATE" frame, an endpoint MUST perform the 735 following steps to validate the token it contains: - Using the "get 736 context" API, retrieve the "certificate_request_context" used to 737 generate the authenticator, if any. - Verify that the 738 "certificate_request_context" is either empty (clients only) or 739 contains the Request-ID of a previously-sent "CERTIFICATE_REQUEST" 740 frame. - Use the "validate" API to confirm the validity of the 741 authenticator with regard to the generated request (if any). 743 Once the authenticator is accepted, the endpoint can perform any 744 other checks for the acceptability of the certificate itself. 746 4. Indicating failures during HTTP-Layer Certificate Authentication 748 Because this draft permits certificates to be exchanged at the HTTP 749 framing layer instead of the TLS layer, several certificate-related 750 errors which are defined at the TLS layer might now occur at the HTTP 751 framing layer. In this section, those errors are restated and added 752 to the HTTP/2 error code registry. 754 BAD_CERTIFICATE (0xERROR-TBD1): A certificate was corrupt, contained 755 signatures that did not verify correctly, etc. 757 UNSUPPORTED_CERTIFICATE (0xERROR-TBD2): A certificate was of an 758 unsupported type or did not contain required extensions 760 CERTIFICATE_REVOKED (0xERROR-TBD3): A certificate was revoked by its 761 signer 763 CERTIFICATE_EXPIRED (0xERROR-TBD4): A certificate has expired or is 764 not currently valid 766 CERTIFICATE_GENERAL (0xERROR-TBD5): Any other certificate-related 767 error 769 CERTIFICATE_OVERUSED (0xERROR-TBD6): More certificates were used on 770 a request than were requested 772 As described in [RFC7540], implementations MAY choose to treat a 773 stream error as a connection error at any time. Of particular note, 774 a stream error cannot occur on stream 0, which means that 775 implementations cannot send non-session errors in response to 776 "CERTIFICATE_REQUEST", and "CERTIFICATE" frames. Implementations 777 which do not wish to terminate the connection MAY either send 778 relevant errors on any stream which references the failing 779 certificate in question or process the requests as unauthenticated 780 and provide error information at the HTTP semantic layer. 782 5. Security Considerations 784 This mechanism defines an alternate way to obtain server and client 785 certificates other than in the initial TLS handshake. While the 786 signature of exported authenticator values is expected to be equally 787 secure, it is important to recognize that a vulnerability in this 788 code path is at least equal to a vulnerability in the TLS handshake. 790 5.1. Impersonation 792 This mechanism could increase the impact of a key compromise. Rather 793 than needing to subvert DNS or IP routing in order to use a 794 compromised certificate, a malicious server now only needs a client 795 to connect to _some_ HTTPS site under its control in order to present 796 the compromised certificate. As recommended in [RFC8336], clients 797 opting not to consult DNS ought to employ some alternative means to 798 increase confidence that the certificate is legitimate. 800 As noted in the Security Considerations of 801 [I-D.ietf-tls-exported-authenticator], it difficult to formally prove 802 that an endpoint is jointly authoritative over multiple certificates, 803 rather than individually authoritative on each certificate. As a 804 result, clients MUST NOT assume that because one origin was 805 previously colocated with another, those origins will be reachable 806 via the same endpoints in the future. Clients MUST NOT consider 807 previous secondary certificates to be validated after TLS session 808 resumption. However, clients MAY proactively query for previously- 809 presented secondary certificates. 811 5.2. Fingerprinting 813 This draft defines a mechanism which could be used to probe servers 814 for origins they support, but opens no new attack versus making 815 repeat TLS connections with different SNI values. Servers SHOULD 816 impose similar denial-of-service mitigations (e.g. request rate 817 limits) to "CERTIFICATE_REQUEST" frames as to new TLS connections. 819 While the extensions in the "CERTIFICATE_REQUEST" frame permit the 820 sender to enumerate the acceptable Certificate Authorities for the 821 requested certificate, it might not be prudent (either for security 822 or data consumption) to include the full list of trusted Certificate 823 Authorities in every request. Senders, particularly clients, SHOULD 824 send only the extensions that narrowly specify which certificates 825 would be acceptable. 827 5.3. Denial of Service 829 Failure to provide a certificate on a stream after receiving 830 "CERTIFICATE_NEEDED" blocks processing, and SHOULD be subject to 831 standard timeouts used to guard against unresponsive peers. 833 Validating a multitude of signatures can be computationally 834 expensive, while generating an invalid signature is computationally 835 cheap. Implementations will require checks for attacks from this 836 direction. Invalid exported authenticators SHOULD be treated as a 837 session error, to avoid further attacks from the peer, though an 838 implementation MAY instead disable HTTP-layer certificates for the 839 current connection instead. 841 5.4. Confusion About State 843 Implementations need to be aware of the potential for confusion about 844 the state of a connection. The presence or absence of a validated 845 certificate can change during the processing of a request, 846 potentially multiple times, as "USE_CERTIFICATE" frames are received. 847 A server that uses certificate authentication needs to be prepared to 848 reevaluate the authorization state of a request as the set of 849 certificates changes. 851 Client implementations need to carefully consider the impact of 852 setting the "AUTOMATIC_USE" flag. This flag is a performance 853 optimization, permitting the client to avoid a round-trip on each 854 request where the server checks for certificate authentication. 855 However, once this flag has been sent, the client has zero knowledge 856 about whether the server will use the referenced cert for any future 857 request, or even for an existing request which has not yet completed. 858 Clients MUST NOT set this flag on any certificate which is not 859 appropriate for currently-in-flight requests, and MUST NOT make any 860 future requests on the same connection which they are not willing to 861 have associated with the provided certificate. 863 6. IANA Considerations 865 This draft adds entries in three registries. 867 The HTTP/2 "SETTINGS_HTTP_CERT_AUTH" setting is registered in 868 Section 6.1. Four frame types are registered in Section 6.2. Six 869 error codes are registered in Section 6.3. 871 6.1. HTTP/2 SETTINGS_HTTP_CERT_AUTH Setting 873 The SETTINGS_HTTP_CERT_AUTH setting is registered in the "HTTP/2 874 Settings" registry established in [RFC7540]. 876 Name: SETTINGS_HTTP_CERT_AUTH 878 Code: 0xSETTING-TBD 880 Initial Value: 0 882 Specification: This document. 884 6.2. New HTTP/2 Frames 886 Four new frame types are registered in the "HTTP/2 Frame Types" 887 registry established in [RFC7540]. The entries in the following 888 table are registered by this document. 890 +---------------------+--------------+---------------+ 891 | Frame Type | Code | Specification | 892 +---------------------+--------------+---------------+ 893 | CERTIFICATE_NEEDED | 0xFRAME-TBD1 | Section 3.1 | 894 | | | | 895 | CERTIFICATE_REQUEST | 0xFRAME-TBD2 | Section 3.3 | 896 | | | | 897 | CERTIFICATE | 0xFRAME-TBD3 | Section 3.4 | 898 | | | | 899 | USE_CERTIFICATE | 0xFRAME-TBD4 | Section 3.2 | 900 +---------------------+--------------+---------------+ 902 6.3. New HTTP/2 Error Codes 904 Six new error codes are registered in the "HTTP/2 Error Code" 905 registry established in [RFC7540]. The entries in the following 906 table are registered by this document. 908 +-------------------------+--------------+---------------+ 909 | Name | Code | Specification | 910 +-------------------------+--------------+---------------+ 911 | BAD_CERTIFICATE | 0xERROR-TBD1 | Section 4 | 912 | | | | 913 | UNSUPPORTED_CERTIFICATE | 0xERROR-TBD2 | Section 4 | 914 | | | | 915 | CERTIFICATE_REVOKED | 0xERROR-TBD3 | Section 4 | 916 | | | | 917 | CERTIFICATE_EXPIRED | 0xERROR-TBD4 | Section 4 | 918 | | | | 919 | CERTIFICATE_GENERAL | 0xERROR-TBD5 | Section 4 | 920 | | | | 921 | CERTIFICATE_OVERUSED | 0xERROR-TBD6 | Section 4 | 922 +-------------------------+--------------+---------------+ 924 7. References 926 7.1. Normative References 928 [I-D.ietf-tls-exported-authenticator] 929 Sullivan, N., "Exported Authenticators in TLS", draft- 930 ietf-tls-exported-authenticator-04 (work in progress), 931 October 2017. 933 [I-D.ietf-tls-tls13] 934 Rescorla, E., "The Transport Layer Security (TLS) Protocol 935 Version 1.3", draft-ietf-tls-tls13-22 (work in progress), 936 November 2017. 938 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 939 Requirement Levels", BCP 14, RFC 2119, 940 DOI 10.17487/RFC2119, March 1997, 941 . 943 [RFC5246] Dierks, T. and E. Rescorla, "The Transport Layer Security 944 (TLS) Protocol Version 1.2", RFC 5246, 945 DOI 10.17487/RFC5246, August 2008, 946 . 948 [RFC6066] Eastlake 3rd, D., "Transport Layer Security (TLS) 949 Extensions: Extension Definitions", RFC 6066, 950 DOI 10.17487/RFC6066, January 2011, 951 . 953 [RFC7230] Fielding, R., Ed. and J. Reschke, Ed., "Hypertext Transfer 954 Protocol (HTTP/1.1): Message Syntax and Routing", 955 RFC 7230, DOI 10.17487/RFC7230, June 2014, 956 . 958 [RFC7540] Belshe, M., Peon, R., and M. Thomson, Ed., "Hypertext 959 Transfer Protocol Version 2 (HTTP/2)", RFC 7540, 960 DOI 10.17487/RFC7540, May 2015, 961 . 963 [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 964 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, 965 May 2017, . 967 7.2. Informative References 969 [RFC7838] Nottingham, M., McManus, P., and J. Reschke, "HTTP 970 Alternative Services", RFC 7838, DOI 10.17487/RFC7838, 971 April 2016, . 973 [RFC8336] Nottingham, M. and E. Nygren, "The ORIGIN HTTP/2 Frame", 974 RFC 8336, DOI 10.17487/RFC8336, March 2018, 975 . 977 7.3. URIs 979 [1] https://lists.w3.org/Archives/Public/ietf-http-wg/ 981 [2] http://httpwg.github.io/ 983 [3] https://github.com/httpwg/http-extensions/labels/secondary-certs 985 Appendix A. Change Log 987 *RFC Editor's Note:* Please remove this section prior to 988 publication of a final version of this document. 990 A.1. Since draft-ietf-httpbis-http2-secondary-certs-00: 992 o All frames sent on stream zero; replaced "AUTOMATIC_USE" on 993 "CERTIFICATE" with "UNSOLICITED" on "USE_CERTIFICATE". (#482,#566) 995 A.2. Since draft-bishop-httpbis-http2-additional-certs-05: 997 o Adopted as draft-ietf-httpbis-http2-secondary-certs 999 Acknowledgements 1001 Eric Rescorla pointed out several failings in an earlier revision. 1002 Andrei Popov contributed to the TLS considerations. 1004 A substantial portion of Mike's work on this draft was supported by 1005 Microsoft during his employment there. 1007 Authors' Addresses 1009 Mike Bishop 1010 Akamai 1012 Email: mbishop@evequefou.be 1014 Nick Sullivan 1015 Cloudflare 1017 Email: nick@cloudflare.com 1019 Martin Thomson 1020 Mozilla 1022 Email: martin.thomson@gmail.com