idnits 2.17.1 draft-thomson-http2-client-certs-02.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 are 1 instance of lines with non-RFC6890-compliant IPv4 addresses in the document. If these are example addresses, they should be changed. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year == The document seems to lack the recommended RFC 2119 boilerplate, even if it appears to use RFC 2119 keywords. (The document does seem to have the reference to RFC 2119 which the ID-Checklist requires). -- The document date (March 14, 2016) is 2965 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) == Outdated reference: A later version (-28) exists of draft-ietf-tls-tls13-11 ** 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) -- Possible downref: Non-RFC (?) normative reference: ref. 'X690' Summary: 3 errors (**), 0 flaws (~~), 4 warnings (==), 2 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 HTTP M. Thomson 3 Internet-Draft Mozilla 4 Intended status: Standards Track M. Bishop 5 Expires: September 15, 2016 Microsoft 6 March 14, 2016 8 Reactive Certificate-Based Client Authentication in HTTP/2 9 draft-thomson-http2-client-certs-02 11 Abstract 13 Some HTTP servers provide a subset of resources that require 14 additional authentication to interact with. HTTP/1.1 servers rely on 15 TLS renegotiation that is triggered by a request to a protected 16 resource. HTTP/2 made this pattern impossible by forbidding the use 17 of TLS renegotiation. While TLS 1.3 provides an alternate mechanism 18 to obtain client certificates, this mechanism does not map well to 19 usage in TLS 1.2. 21 This document describes a how client authentication might be 22 requested by a server as a result of receiving a request to a 23 protected resource. 25 Status of This Memo 27 This Internet-Draft is submitted in full conformance with the 28 provisions of BCP 78 and BCP 79. 30 Internet-Drafts are working documents of the Internet Engineering 31 Task Force (IETF). Note that other groups may also distribute 32 working documents as Internet-Drafts. The list of current Internet- 33 Drafts is at http://datatracker.ietf.org/drafts/current/. 35 Internet-Drafts are draft documents valid for a maximum of six months 36 and may be updated, replaced, or obsoleted by other documents at any 37 time. It is inappropriate to use Internet-Drafts as reference 38 material or to cite them other than as "work in progress." 40 This Internet-Draft will expire on September 15, 2016. 42 Copyright Notice 44 Copyright (c) 2016 IETF Trust and the persons identified as the 45 document authors. All rights reserved. 47 This document is subject to BCP 78 and the IETF Trust's Legal 48 Provisions Relating to IETF Documents 49 (http://trustee.ietf.org/license-info) in effect on the date of 50 publication of this document. Please review these documents 51 carefully, as they describe your rights and restrictions with respect 52 to this document. Code Components extracted from this document must 53 include Simplified BSD License text as described in Section 4.e of 54 the Trust Legal Provisions and are provided without warranty as 55 described in the Simplified BSD License. 57 Table of Contents 59 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3 60 1.1. Reactive Certificate Authentication in HTTP/1.1 . . . . . 4 61 1.1.1. Using TLS 1.2 and previous . . . . . . . . . . . . . 4 62 1.1.2. Using TLS 1.3 . . . . . . . . . . . . . . . . . . . . 5 63 1.2. Reactive Client Authentication in HTTP/2 . . . . . . . . 5 64 1.3. Terminology . . . . . . . . . . . . . . . . . . . . . . . 7 65 2. Presenting Client Certificates at the HTTP/2 Framing Layer . 7 66 2.1. The CERTIFICATE_REQUIRED frame . . . . . . . . . . . . . 7 67 2.2. The USE_CERTIFICATE Frame . . . . . . . . . . . . . . . . 8 68 2.3. The CERTIFICATE_REQUEST Frame . . . . . . . . . . . . . . 9 69 2.4. The CERTIFICATE frame . . . . . . . . . . . . . . . . . . 10 70 2.5. The CERTIFICATE_PROOF Frame . . . . . . . . . . . . . . . 12 71 3. Indicating failures during HTTP-Layer Certificate 72 Authentication . . . . . . . . . . . . . . . . . . . . . . . 13 73 4. Indicating Support for HTTP-Layer Certificate Authentication 14 74 5. Security Considerations . . . . . . . . . . . . . . . . . . . 14 75 6. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 15 76 6.1. HTTP/2 SETTINGS_HTTP_CERT_AUTH Setting . . . . . . . . . 16 77 6.2. New HTTP/2 Frames . . . . . . . . . . . . . . . . . . . . 16 78 6.2.1. CERTIFICATE_REQUIRED . . . . . . . . . . . . . . . . 16 79 6.2.2. CERTIFICATE_REQUEST . . . . . . . . . . . . . . . . . 16 80 6.2.3. CERTIFICATE . . . . . . . . . . . . . . . . . . . . . 16 81 6.2.4. CERTIFICATE_PROOF . . . . . . . . . . . . . . . . . . 16 82 6.2.5. USE_CERTIFICATE . . . . . . . . . . . . . . . . . . . 17 83 6.3. New HTTP/2 Error Codes . . . . . . . . . . . . . . . . . 17 84 6.3.1. BAD_CERTIFICATE . . . . . . . . . . . . . . . . . . . 17 85 6.3.2. UNSUPPORTED_CERTIFICATE . . . . . . . . . . . . . . . 17 86 6.3.3. CERTIFICATE_REVOKED . . . . . . . . . . . . . . . . . 17 87 6.3.4. CERTIFICATE_EXPIRED . . . . . . . . . . . . . . . . . 17 88 6.3.5. BAD_SIGNATURE . . . . . . . . . . . . . . . . . . . . 18 89 6.3.6. CERTIFICATE_GENERAL . . . . . . . . . . . . . . . . . 18 90 7. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 18 91 8. Normative References . . . . . . . . . . . . . . . . . . . . 18 92 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 19 94 1. Introduction 96 Many existing HTTP [RFC7230] servers have different authentication 97 requirements for the different resources they serve. Of the 98 bountiful authentication options available for authenticating HTTP 99 requests, client certificates present a unique challenge for 100 resource-specific authentication requirements because of the 101 interaction with the underlying TLS RFC5246 [I-D.ietf-tls-tls13] 102 layer. 104 For servers that wish to use client certificates to authenticate 105 users, they might request client authentication during or immediately 106 after the TLS handshake. However, if not all users or resources need 107 certificate-based authentication, a request for a certificate has the 108 unfortunate consequence of triggering the client to seek a 109 certificate. Such a request can result in a poor experience, 110 particularly when sent to a client that does not expect the request. 112 The TLS 1.3 CertificateRequest can be used by servers to give clients 113 hints about which certificate to offer. Servers that rely on 114 certificate-based authentication might request different certificates 115 for different resources. Such a server cannot use contextual 116 information about the resource to construct an appropriate TLS 117 CertificateRequest message during the initial handshake. 119 Consequently, client certificates are requested at connection 120 establishment time only in cases where all clients are expected or 121 required to have a single certificate that is used for all resources. 122 Many other uses for client certificates are reactive, that is, 123 certificates are requested in response to the client making a 124 request. 126 In Yokohama, there was extensive working group discussion regarding 127 why certificate authentication could not easily be done at the HTTP 128 semantic layer. However, in subsequent discussion, it became 129 apparent that the HTTP _framing_ layer did not suffer from the same 130 limitation. 132 In this document, a mechanism for doing certificate-based client 133 authentication via HTTP/2 frames is defined. This mechanism can be 134 implemented at the HTTP layer without requiring new TLS stack 135 behavior and without breaking the existing interface between HTTP and 136 applications which employ client certificates. 138 1.1. Reactive Certificate Authentication in HTTP/1.1 140 1.1.1. Using TLS 1.2 and previous 142 In HTTP/1.1, a server that relies on client authentication for a 143 subset of users or resources does not request a certificate when the 144 connection is established. Instead, it only requests a client 145 certificate when a request is made to a resource that requires a 146 certificate. TLS 1.2 [RFC5246] accomodates this by permitting the 147 server to request a new TLS handshake, in which the server will 148 request the client's certificate. 150 Figure 1 shows the server initiating a TLS-layer renegotiation in 151 response to receiving an HTTP/1.1 request to a protected resource. 153 Client Server 154 -- (HTTP) GET /protected -------------------> *1 155 <---------------------- (TLS) HelloRequest -- *2 156 -- (TLS) ClientHello -----------------------> 157 <------------------ (TLS) ServerHello, ... -- 158 <---------------- (TLS) CertificateRequest -- *3 159 -- (TLS) ..., Certificate ------------------> *4 160 -- (TLS) Finished --------------------------> 161 <-------------------------- (TLS) Finished -- 162 <--------------------------- (HTTP) 200 OK -- *5 164 Figure 1: HTTP/1.1 Reactive Certificate Authentication with TLS 1.2 166 In this example, the server receives a request for a protected 167 resource (at *1 on Figure 1). Upon performing an authorization 168 check, the server determines that the request requires authentication 169 using a client certificate and that no such certificate has been 170 provided. 172 The server initiates TLS renegotiation by sending a TLS HelloRequest 173 (at *2). The client then initiates a TLS handshake. Note that some 174 TLS messages are elided from the figure for the sake of brevity. 176 The critical messages for this example are the server requesting a 177 certificate with a TLS CertificateRequest (*3); this request might 178 use information about the request or resource. The client then 179 provides a certificate and proof of possession of the private key in 180 Certificate and CertificateVerify messages (*4). 182 When the handshake completes, the server performs any authorization 183 checks a second time. With the client certificate available, it then 184 authorizes the request and provides a response (*5). 186 1.1.2. Using TLS 1.3 188 TLS 1.3 [I-D.ietf-tls-tls13] introduces a new client authentication 189 mechanism that allows for clients to authenticate after the handshake 190 has been completed. For the purposes of authenticating an HTTP 191 request, this is functionally equivalent to renegotiation. Figure 2 192 shows the simpler exchange this enables. 194 Client Server 195 -- (HTTP) GET /protected -------------------> 196 <---------------- (TLS) CertificateRequest -- 197 -- (TLS) Certificate, CertificateVerify ----> 198 <--------------------------- (HTTP) 200 OK -- 200 Figure 2: HTTP/1.1 Reactive Certificate Authentication with TLS 1.3 202 TLS 1.3 does not support renegotiation, instead supporting direct 203 client authentication. In contrast to the TLS 1.2 example, in TLS 204 1.3, a server can simply request a certificate. 206 1.2. Reactive Client Authentication in HTTP/2 208 An important part of the HTTP/1.1 exchange is that the client is able 209 to easily identify the request that caused the TLS renegotiation. 210 The client is able to assume that the next unanswered request on the 211 connection is responsible. The HTTP stack in the client is then able 212 to direct the certificate request to the application or component 213 that initiated that request. This ensures that the application has 214 the right contextual information for processing the request. 216 In HTTP/2, a client can have multiple outstanding requests. Without 217 some sort of correlation information, a client is unable to identify 218 which request caused the server to request a certificate. 220 Thus, the minimum necessary mechanism to support reactive certificate 221 authentication in HTTP/2 is an identifier that can be use to 222 correlate an HTTP request with a request for a certificate. 224 Such an identifier could be added to TLS 1.2 by means of an 225 extension, but many TLS 1.2 implementations do not permit application 226 data to continue during a renegotiation. This is problematic for a 227 multiplexed protocol like HTTP/2. Instead, this draft proposes 228 bringing the TLS 1.3 CertificateRequest, Certificate, and 229 CertificateVerify messages into HTTP/2 frames, making client 230 certificate authentication TLS-version-agnostic. 232 This could be done in a naive manner by replicating the messages as 233 HTTP/2 frames on each stream. However, this would create needless 234 redundancy between streams and require frequent expensive signing 235 operations. Instead, this draft lifts the bulky portions of each 236 message into frames on stream zero and permits the on-stream frames 237 to incorporate them by reference as needed. 239 On each stream where certificate authentication is required, the 240 server sends a "CERTIFICATE_REQUIRED" frame, which the client answers 241 with a "USE_CERTIFICATE" frame either indicating the certificate to 242 use, or indicating that no certificate should be used. These frames 243 are simple, referencing information previously sent on stream zero to 244 reduce redundancy. 246 "CERTIFICATE_REQUIRED" frames reference a "CERTIFICATE_REQUEST" on 247 stream zero, analogous to the CertificateRequest message. 248 "USE_CERTIFICATE" frames reference a sequence of "CERTIFICATE" and 249 "CERTIFICATE_PROOF" frames on stream zero, analogous to the the 250 Certificate and CertificateVerify messages. 252 The exchange then looks like this: 254 Client Server 255 -- (streams 1,3) GET /protected ------------> 256 <---------- (stream 0) CERTIFICATE_REQUEST -- 257 <------ (streams 1,3) CERTIFICATE_REQUIRED -- 258 -- (stream 0) CERTIFICATE ------------------> 259 -- (stream 0) CERTIFICATE_PROOF ------------> 260 -- (streams 1,3) USE_CERTIFICATE -----------> 261 <-------------------- (streams 1,3) 200 OK -- 263 Figure 3: HTTP/2 Reactive Certificate Authentication 265 To avoid the extra round-trip per stream required for a challenge and 266 response, the "AUTOMATIC_USE" flag enables a certificate to be 267 automatically used by the server on subsequent requests without 268 sending a "CERTIFICATE_REQUIRED" exchange. 270 Section 2 describes how certificates can be requested and presented 271 at the HTTP/2 framing layer using several new frame types which 272 parallel the TLS 1.3 message exchange. Section 3 defines new error 273 types which can be used to notify peers when the exchange has not 274 been successful. Finally, Section 4 describes how an HTTP/2 client 275 can announce support for this feature so that a server might use 276 these capabilities. 278 1.3. Terminology 280 RFC 2119 [RFC2119] defines the terms "MUST", "MUST NOT", "SHOULD" and 281 "MAY". 283 2. Presenting Client Certificates at the HTTP/2 Framing Layer 285 An HTTP/2 request from a client that has signaled support for 286 reactive certificate authentication (see Section 4) might cause a 287 server to request client authentication. In HTTP/2 a server does 288 this by sending at least one "CERTIFICATE_REQUEST" frame (see 289 Section 2.3) on stream zero and sending a "CERTIFICATE_REQUIRED" 290 frame (see Section 2.1) on the affected stream(s). The 291 "CERTIFICATE_REQUEST" and "CERTIFICATE_REQUIRED" frames are 292 correlated by their "Request-ID" field. Subsequent 293 "CERTIFICATE_REQUIRED" frames with the same Request-ID MAY be sent on 294 other streams where the server is expecting client authentication 295 with the same parameters. 297 A server MAY send multiple concurrent "CERTIFICATE_REQUIRED" frames 298 on the same stream. If a server requires that a client provide 299 multiple certificates before authorizing a single request, it MUST 300 send a "CERTIFICATE_REQUIRED" frame with a different request 301 identifier and a corresponding "CERTIFICATE_REQUEST" frame describing 302 each required certificate. 304 Clients respond to requests by sending one or more "CERTIFICATE" 305 frames (see Section 2.4), followed by a "CERTIFICATE_PROOF" frame 306 (see Section 2.5), on stream zero containing the "Request-ID" to 307 which they are responding. The "USE_CERTIFICATE" (see Section 2.2) 308 frame is sent on-stream to notify the server the stream is ready to 309 be processed. 311 To reduce round-trips, the client MAY set the "AUTOMATIC_USE" flag on 312 a "CERTIFICATE_PROOF" frame, indicating that the server SHOULD 313 automatically apply the supplied certificate to any future streams 314 matching that request, rather than sending a "CERTIFICATE_REQUIRED" 315 frame. 317 2.1. The CERTIFICATE_REQUIRED frame 319 The "CERTIFICATE_REQUIRED" frame (0xFRAME-TBD2) is sent by servers to 320 indicate that processing of an HTTP request is blocked pending 321 certificate authentication. The frame includes a request identifier 322 which can be used to correlate the stream with a previous 323 "CERTIFICATE_REQUEST" frame received on stream zero. The 324 "CERTIFICATE_REQUEST" describes the client certificate the server 325 requires to process the request. 327 The "CERTIFICATE_REQUIRED" frame contains 1 octet, which is the 328 authentication request identifier. A client that receives a 329 "CERTIFICATE_REQUIRED" of any other length MUST treat this as a 330 stream error of type "PROTOCOL_ERROR". Frames with identical request 331 identifiers refer to the same "CERTIFICATE_REQUEST". 333 The "CERTIFICATE_REQUIRED" frame MUST NOT be sent by clients. A 334 "CERTIFICATE_REQUIRED" frame received by a server SHOULD be rejected 335 with a stream error of type PROTOCOL_ERROR. 337 The server MUST NOT send a "CERTIFICATE_REQUIRED" frame on stream 338 zero, a server-initiated stream or a stream that does not have an 339 outstanding request. In other words, a server can only send in the 340 "open" or "half-closed (remote)" stream states. 342 A client that receives a "CERTIFICATE_REQUIRED" frame on a stream 343 which is not in a valid state ("open" or "half-closed (local)" for 344 clients) SHOULD treat this as a connection error of type 345 "PROTOCOL_ERROR". 347 2.2. The USE_CERTIFICATE Frame 349 The "USE_CERTIFICATE" frame (0xFRAME-TBD5) is sent by clients in 350 response to a "CERTIFICATE_REQUIRED" frame to indicate that the 351 requested certificate has been provided (or will not be). 353 A "USE_CERTIFICATE" frame with no payload expresses the client's 354 refusal to use the associated certificate (if any) with this stream. 355 If the request was originally issued for a different stream, servers 356 MAY create a new "CERTIFICATE_REQUEST" and permit the client to offer 357 a different certificate. Alternatively, servers MAY process the 358 request as unauthenticated, likely returning an authentication- 359 related error at the HTTP level (e.g. 403). 361 Otherwise, the "USE_CERTIFICATE" frame contains the "Request-ID" of 362 the now-completed certificate request. This MUST be an ID previously 363 issued by the server, and for which a matching certificate has 364 previously been presented along with a supporting certificate chain 365 in one or more "CERTIFICATE" frames, and for which proof of 366 possession has been presented in a "CERTIFICATE_PROOF" frame. 368 Use of the "USE_CERTIFICATE" frame by servers is not defined by this 369 document. A "USE_CERTIFICATE" frame received by a client MUST be 370 ignored. 372 The client MUST NOT send a "USE_CERTIFICATE" frame on stream zero, a 373 server-initiated stream or a stream that does not have an outstanding 374 request. In other words, a client can only send in the "open" or 375 "half-closed (local)" stream states. The client MUST NOT send a 376 "USE_CERTIFICATE" frame except in response to a 377 "CERTIFICATE_REQUIRED" frame from the server. 379 A server that receives a "USE_CERTIFICATE" frame on a stream which is 380 not in a valid state ("open" or "half-closed (remote)" for servers), 381 on which it has not sent a "CERTIFICATE_REQUIRED" frame, or 382 referencing a certificate it has not previously received SHOULD treat 383 this as a connection error of type "PROTOCOL_ERROR". 385 2.3. The CERTIFICATE_REQUEST Frame 387 TLS 1.3 defines the "CertificateRequest" message, which prompts the 388 client to provide a certificate which conforms to certain properties 389 specified by the server. This draft defines the 390 "CERTIFICATE_REQUEST" frame (0xFRAME-TBD1), which contains the same 391 contents as a TLS 1.3 "CertificateRequest" message, but can be sent 392 over any TLS version. 394 The "CERTIFICATE_REQUEST" frame MUST NOT be sent by clients. A 395 "CERTIFICATE_REQUEST" frame received by a server SHOULD be rejected 396 with a stream error of type "PROTOCOL_ERROR". 398 The "CERTIFICATE_REQUEST" frame MUST be sent on stream zero. A 399 "CERTIFICATE_REQUEST" frame received on any other stream MUST be 400 rejected with a stream error of type "PROTOCOL_ERROR". 402 0 1 2 3 403 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 404 +-------------------------------+-------------------------------+ 405 | Request-ID (8)| Algorithm-Count (16) | Algorithms ... 406 +---------------------------------------------------------------+ 407 | CA-Count (16) | Certificate-Authorities(?) ... 408 +---------------------------------------------------------------+ 409 | Cert-Extension-Count (16) | Cert-Extensions(?) ... 410 +---------------------------------------------------------------+ 412 Figure 4: CERTIFICATE_REQUEST frame payload 414 The frame contains the following fields: 416 Request-ID: "Request-ID" is an 8-bit opaque identifier used to 417 correlate subsequent certificate-related frames with this request. 418 The identifier MUST be unique in the session. 420 Algorithm-Count and Algorithms: A list of the hash/signature 421 algorithm pairs that the server is able to verify, listed in 422 descending order of preference. Any certificates provided by the 423 client MUST be signed using a hash/signature algorithm pair found 424 in "Algorithms". Each algorithm pair is encoded as a 425 "SignatureAndHashAlgorithm" (see [I-D.ietf-tls-tls13] section 426 6.3.2.1), and the number of such structures is given by the 16-bit 427 "Algorithm-Count" field, which MUST NOT be zero. 429 CA-Count and Certificate-Authorities: "Certificate-Authorities" is a 430 series of distinguished names of acceptable certificate 431 authorities, represented in DER-encoded [X690] format. These 432 distinguished names may specify a desired distinguished name for a 433 root CA or for a subordinate CA; thus, this message can be used to 434 describe known roots as well as a desired authorization space. 435 The number of such structures is given by the 16-bit "CA-Count" 436 field, which MAY be zero. If the "CA-Count" field is zero, then 437 the client MAY send any certificate that meets the rest of the 438 selection criteria in the "CERTIFICATE_REQUEST", unless there is 439 some external arrangement to the contrary. 441 Cert-Extension-Count and Cert-Extensions: A list of certificate 442 extension OIDs [RFC5280] with their allowed values, represented in 443 a series of "CertificateExtension" structures (see 444 [I-D.ietf-tls-tls13] section 6.3.5). The list of OIDs MUST be 445 used in certificate selection as described in 446 [I-D.ietf-tls-tls13]. The number of Cert-Extension structures is 447 given by the 16-bit "Cert-Extension-Count" field, which MAY be 448 zero. 450 Some certificate extension OIDs allow multiple values (e.g. Extended 451 Key Usage). If the sender has included a non-empty 452 certificate_extensions list, the certificate MUST contain all of the 453 specified extension OIDs that the recipient recognizes. For each 454 extension OID recognized by the recipient, all of the specified 455 values MUST be present in the certificate (but the certificate MAY 456 have other values as well). However, the recipient MUST ignore and 457 skip any unrecognized certificate extension OIDs. 459 PKIX RFCs define a variety of certificate extension OIDs and their 460 corresponding value types. Depending on the type, matching 461 certificate extension values are not necessarily bitwise-equal. It 462 is expected that implementations will rely on their PKI libraries to 463 perform certificate selection using these certificate extension OIDs. 465 2.4. The CERTIFICATE frame 467 A certificate chain is transferred as a series of "CERTIFICATE" 468 frames (0xFRAME-TBD3) with the same Request-ID, each containing a 469 single certificate in the chain. The end certificate of the chain 470 can be used as authentication for previous or subsequent requests. 472 The "CERTIFICATE" frame defines no flags. 474 While unlikely, it is possible that an exceptionally large 475 certificate might be too large to fit in a single HTTP/2 frame (see 476 [RFC7540] section 4.2). Senders unable to transfer a requested 477 certificate due to the recipient's "SETTINGS_MAX_FRAME_SIZE" value 478 SHOULD terminate affected streams with "CERTIFICATE_TOO_LARGE". 480 Use of the "CERTIFICATE" frame by servers is not defined by this 481 document. A "CERTIFICATE" frame received by a client MUST be 482 ignored. 484 The "CERTIFICATE" frame MUST be sent on stream zero. A "CERTIFICATE" 485 frame received on any other stream MUST be rejected with a stream 486 error of type "PROTOCOL_ERROR". 488 0 1 2 3 489 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 490 +-------------------------------+-------------------------------+ 491 | Request-ID (8)| Certificate (*) ... 492 +---------------------------------------------------------------+ 494 Figure 5: CERTIFICATE frame payload 496 The fields defined by the "CERTIFICATE" frame are: 498 Request-ID: The ID of the "CERTIFICATE_REQUEST" to which this frame 499 responds. 501 Certificate: An X.509v3 [RFC5280] certificate in the sender's 502 certificate chain. 504 The first or only "CERTIFICATE" frame with a given Request-ID MUST 505 contain the sender's certificate. Each subsequent certificate SHOULD 506 directly certify the certificate immediately preceding it. A 507 certificate which specifies a trust anchor MAY be omitted, provided 508 that the recipient is known to already possess the relevant 509 certificate. (For example, because it was included in a 510 "CERTIFICATE_REQUEST"'s Certificate-Authorities list.) 512 The "Request-ID" field MUST contain the same value as the 513 corresponding "CERTIFICATE_REQUEST" frame, and the provided 514 certificate chain MUST conform to the requirements expressed in the 515 "CERTIFICATE_REQUEST" to the best of the client's ability. 516 Specifically: 518 o If the "CERTIFICATE_REQUEST" contained a non-empty "Certificate- 519 Authorities" element, one of the certificates in the chain SHOULD 520 be signed by one of the listed CAs. 522 o If the "CERTIFICATE_REQUEST" contained a non-empty "Cert- 523 Extensions" element, the first certificate MUST match with regard 524 to the extension OIDs recognized by the client. 526 o Each certificate that is not self-signed MUST be signed using a 527 hash/signature algorithm listed in the "Algorithms" element. 529 If these requirements are not satisfied, the server MAY at its 530 discretion either process the request without client authentication, 531 or respond with a stream error [RFC7540] on any stream where the 532 certificate is used. Section 3 defines certificate-related error 533 codes which might be applicable. 535 A client cannot provide different certificates in response to the 536 same "CERTIFICATE_REQUEST" for use on different streams. A client 537 that has already sent and proven a certificate, but does not wish to 538 use it on a particular stream SHOULD send an empty "USE_CERTIFICATE" 539 frame, refusing to use that certificate on that stream. 541 2.5. The CERTIFICATE_PROOF Frame 543 The "CERTIFICATE_PROOF" frame proves possession of the private key 544 corresponding to an end certificate previously shown in a 545 "CERTIFICATE" frame. 547 The "CERTIFICATE_PROOF" frame defines one flag: 549 AUTOMATIC_USE (0x01): Indicates that the certificate can be used 550 automatically on future requests. 552 0 1 2 3 553 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 554 +-------------------------------+-------------------------------+ 555 | Request-ID (8)| Algorithm (16) | Signature(*)... 556 +---------------------------------------------------------------+ 558 Figure 6: CERTIFICATE_PROOF frame payload 560 The "CERTIFICATE_PROOF" frame (0xFRAME-TBD4) contains an "Algorithm" 561 field (a "SignatureAndHashAlgorithm", from [I-D.ietf-tls-tls13] 562 section 6.3.2.1), describing the hash/signature algorithm pair being 563 used. The signature is performed as described in 564 [I-D.ietf-tls-tls13], with the following values being used: 566 o The context string for the signature is "HTTP/2 CERTIFICATE_PROOF" 568 o The "specified content" is an [RFC5705] exported value, with the 569 following parameters: 571 * Disambiguating label string: "EXPORTER HTTP/2 572 CERTIFICATE_PROOF" 574 * Length: 64 bytes 576 Because the exported value can be independently calculated by both 577 sides of the TLS connection, the value to be signed is not sent on 578 the wire at any time. The same signed value is used for all 579 "CERTIFICATE_PROOF" frames in a single HTTP/2 connection. 581 A "CERTIFICATE_PROOF" frame MUST be sent only after all "CERTIFICATE" 582 frames with the same Request-ID have been sent, and MUST correspond 583 to the first certificate presented in the first "CERTIFICATE" frame 584 with that Request-ID. Receipt of multiple "CERTIFICATE_PROOF" frames 585 for the same Request-ID, receipt of a "CERTIFICATE_PROOF" frame 586 without a corresponding "CERTIFICATE" frame, or receipt of a 587 "CERTIFICATE" frame after a corresponding "CERTIFICATE_PROOF" MUST be 588 treated as a session error of type "PROTOCOL_ERROR". 590 If the "AUTOMATIC_USE" flag is set, the server MAY omit sending 591 "CERTIFICATE_REQUIRED" frames on future streams associated with this 592 request and use the referenced certificate for authentication without 593 further notice to the client. This behavior is optional, and receipt 594 of a "CERTIFICATE_REQUIRED" frame does not imply that previously- 595 presented certificates were unacceptable to the server. 597 Use of the "CERTIFICATE_PROOF" frame by servers is not defined by 598 this document. A "CERTIFICATE_PROOF" frame received by a client MUST 599 be ignored. 601 3. Indicating failures during HTTP-Layer Certificate Authentication 603 Because this draft permits client certificates to be exchanged at the 604 HTTP framing layer instead of the TLS layer, several certificate- 605 related errors which are defined at the TLS layer might now occur at 606 the HTTP framing layer. In this section, those errors are restated 607 and added to the HTTP/2 error code registry. 609 BAD_CERTIFICATE (0xERROR-TBD1): A certificate was corrupt, contained 610 signatures that did not verify correctly, etc. 612 UNSUPPORTED_CERTIFICATE (0xERROR-TBD2): A certificate was of an 613 unsupported type or did not contain required extensions 615 CERTIFICATE_REVOKED (0xERROR-TBD3): A certificate was revoked by its 616 signer 618 CERTIFICATE_EXPIRED (0xERROR-TBD4): A certificate has expired or is 619 not currently valid 621 BAD_SIGNATURE (0xERROR-TBD5): The digital signature provided did not 622 match 624 CERTIFICATE_TOO_LARGE (0xERROR-TBD6): The certificate cannot be 625 transferred due to the recipient's "SETTINGS_MAX_FRAME_SIZE" 627 CERTIFICATE_GENERAL (0xERROR-TBD7): Any other certificate-related 628 error 630 As described in [RFC7540], implementations MAY choose to treat a 631 stream error as a connection error at any time. Of particular note, 632 a stream error cannot occur on stream 0, which means that 633 implementations cannot send non-session errors in response to 634 "CERTIFICATE_REQUEST" and "CERTIFICATE" frames. Implementations 635 which do not wish to terminate the connection MAY either send 636 relevant errors on any stream which references the failing 637 certificate in question or process the requests as unauthenticated 638 and provide error information at the HTTP semantic layer. 640 4. Indicating Support for HTTP-Layer Certificate Authentication 642 Clients that support HTTP-layer certificate authentication indicate 643 this using the HTTP/2 "SETTINGS_HTTP_CERT_AUTH" (0xSETTING-TBD) 644 setting. 646 The initial value for the "SETTINGS_HTTP_CERT_AUTH" setting is 0, 647 indicating that the client does not support reactive certificate 648 authentication. A client sets the "SETTINGS_HTTP_CERT_AUTH" setting 649 to a value of 1 to indicate support for HTTP-layer certificate 650 authentication as defined in this document. Any value other than 0 651 or 1 MUST be treated as a connection error (Section 5.4.1 of 652 [RFC7540]) of type "PROTOCOL_ERROR". 654 5. Security Considerations 656 Failure to provide a certificate on a stream after receiving 657 "CERTIFICATE_REQUIRED" blocks server processing, and SHOULD be 658 subject to standard timeouts used to guard against unresponsive 659 peers. 661 In order to protect the privacy of the connection against triple- 662 handshake attacks, this feature of HTTP/2 MUST be used only over TLS 663 1.3 or greater, or over TLS 1.2 in combination with the Extended 664 Master Secret extension defined in [RFC7627]. Because this feature 665 is intended to operate with equivalent security to the TLS 666 connection, hash and signature algorithms not permitted by the 667 version of TLS in use MUST NOT be used. Additionally, the following 668 algorithms MUST NOT be used, even if permitted by the underlying TLS 669 version: 671 o MD5 673 o SHA1 675 o SHA224 677 o DSA 679 o ECDSA with curves on prime fields that are less than 240 bits wide 681 o RSA with a prime modulus less than 2048 bits 683 Client implementations need to carefully consider the impact of 684 setting the "AUTOMATIC_USE" flag. This flag is a performance 685 optimization, permitting the client to avoid a round-trip on each 686 request where the server checks for certificate authentication. 687 However, once this flag has been sent, the client has zero knowledge 688 about whether the server will use the referenced cert for any future 689 request, or even for an existing request which has not yet completed. 690 Clients MUST NOT set this flag on any certificate which is not 691 appropriate for currently-in-flight requests, and MUST NOT make any 692 future requests on the same connection which they do not intend to 693 have associated with the provided certificate. 695 Implementations need to be aware of the potential for confusion about 696 the state of a connection. The presence or absence of a validated 697 client certificate can change during the processing of a request, 698 potentially multiple times, as "USE_CERTIFICATE" frames are received. 699 A server that uses certificate authentication needs to be prepared to 700 reevaluate the authorization state of a request as the set of 701 certificates changes. 703 6. IANA Considerations 705 The HTTP/2 "SETTINGS_HTTP_CERT_AUTH" setting is registered in 706 Section 6.1. Five frame types are registered in Section 6.2. Six 707 error codes are registered in Section 6.3. 709 6.1. HTTP/2 SETTINGS_HTTP_CERT_AUTH Setting 711 The SETTINGS_HTTP_CERT_AUTH setting is registered in the "HTTP/2 712 Settings" registry established in [RFC7540]. 714 Name: SETTINGS_HTTP_CERT_AUTH 716 Code: 0xSETTING-TBD 718 Initial Value: 0 720 Specification: This document. 722 6.2. New HTTP/2 Frames 724 Four new frame types are registered in the "HTTP/2 Frame Types" 725 registry established in [RFC7540]. 727 6.2.1. CERTIFICATE_REQUIRED 729 Frame Type: CERTIFICATE_REQUIRED 731 Code: 0xFRAME-TBD1 733 Specification: This document. 735 6.2.2. CERTIFICATE_REQUEST 737 Frame Type: CERTIFICATE_REQUEST 739 Code: 0xFRAME-TBD2 741 Specification: This document. 743 6.2.3. CERTIFICATE 745 Frame Type: CERTIFICATE 747 Code: 0xFRAME-TBD3 749 Specification: This document. 751 6.2.4. CERTIFICATE_PROOF 753 Frame Type: CERTIFICATE_PROOF 755 Code: 0xFRAME-TBD4 756 Specification: This document. 758 6.2.5. USE_CERTIFICATE 760 Frame Type: USE_CERTIFICATE 762 Code: 0xFRAME-TBD5 764 Specification: This document. 766 6.3. New HTTP/2 Error Codes 768 Five new error codes are registered in the "HTTP/2 Error Code" 769 registry established in [RFC7540]. 771 6.3.1. BAD_CERTIFICATE 773 Name: BAD_CERTIFICATE 775 Code: 0xERROR-TBD1 777 Specification: This document. 779 6.3.2. UNSUPPORTED_CERTIFICATE 781 Name: UNSUPPORTED_CERTIFICATE 783 Code: 0xERROR-TBD2 785 Specification: This document. 787 6.3.3. CERTIFICATE_REVOKED 789 Name: CERTIFICATE_REVOKED 791 Code: 0xERROR-TBD3 793 Specification: This document. 795 6.3.4. CERTIFICATE_EXPIRED 797 Name: CERTIFICATE_EXPIRED 799 Code: 0xERROR-TBD4 801 Specification: This document. 803 6.3.5. BAD_SIGNATURE 805 Name: BAD_SIGNATURE 807 Code: 0xERROR-TBD5 809 Specification: This document. 811 6.3.6. CERTIFICATE_GENERAL 813 Name: CERTIFICATE_GENERAL 815 Code: 0xERROR-TBD6 817 Specification: This document. 819 7. Acknowledgements 821 Eric Rescorla pointed out several failings in an earlier revision. 822 Andrei Popov contributed to the TLS considerations. 824 8. Normative References 826 [I-D.ietf-tls-tls13] 827 Rescorla, E., "The Transport Layer Security (TLS) Protocol 828 Version 1.3", draft-ietf-tls-tls13-11 (work in progress), 829 December 2015. 831 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 832 Requirement Levels", BCP 14, RFC 2119, 833 DOI 10.17487/RFC2119, March 1997, 834 . 836 [RFC5246] Dierks, T. and E. Rescorla, "The Transport Layer Security 837 (TLS) Protocol Version 1.2", RFC 5246, 838 DOI 10.17487/RFC5246, August 2008, 839 . 841 [RFC5280] Cooper, D., Santesson, S., Farrell, S., Boeyen, S., 842 Housley, R., and W. Polk, "Internet X.509 Public Key 843 Infrastructure Certificate and Certificate Revocation List 844 (CRL) Profile", RFC 5280, DOI 10.17487/RFC5280, May 2008, 845 . 847 [RFC5705] Rescorla, E., "Keying Material Exporters for Transport 848 Layer Security (TLS)", RFC 5705, DOI 10.17487/RFC5705, 849 March 2010, . 851 [RFC7230] Fielding, R., Ed. and J. Reschke, Ed., "Hypertext Transfer 852 Protocol (HTTP/1.1): Message Syntax and Routing", 853 RFC 7230, DOI 10.17487/RFC7230, June 2014, 854 . 856 [RFC7540] Belshe, M., Peon, R., and M. Thomson, Ed., "Hypertext 857 Transfer Protocol Version 2 (HTTP/2)", RFC 7540, 858 DOI 10.17487/RFC7540, May 2015, 859 . 861 [RFC7627] Bhargavan, K., Ed., Delignat-Lavaud, A., Pironti, A., 862 Langley, A., and M. Ray, "Transport Layer Security (TLS) 863 Session Hash and Extended Master Secret Extension", 864 RFC 7627, DOI 10.17487/RFC7627, September 2015, 865 . 867 [X690] ITU-T, "Information technology - ASN.1 encoding Rules: 868 Specification of Basic Encoding Rules (BER), Canonical 869 Encoding Rules (CER) and Distinguished Encoding Rules 870 (DER)", ISO ISO/IEC 8825-1:2002, 2002, 871 . 874 Authors' Addresses 876 Martin Thomson 877 Mozilla 879 Email: martin.thomson@gmail.com 881 Mike Bishop 882 Microsoft 884 Email: michael.bishop@microsoft.com