idnits 2.17.1 draft-thomson-http2-client-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 : ---------------------------------------------------------------------------- == 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 (January 22, 2016) is 3016 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: July 25, 2016 Microsoft 6 January 22, 2016 8 Reactive Certificate-Based Client Authentication in HTTP/2 9 draft-thomson-http2-client-certs-01 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 July 25, 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.4.1. The Certificate structure . . . . . . . . . . . . . . 12 71 2.5. The CERTIFICATE_PROOF Frame . . . . . . . . . . . . . . . 13 72 3. Indicating failures during HTTP-Layer Certificate 73 Authentication . . . . . . . . . . . . . . . . . . . . . . . 14 74 4. Indicating Support for HTTP-Layer Certificate Authentication 15 75 5. Security Considerations . . . . . . . . . . . . . . . . . . . 15 76 6. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 15 77 6.1. HTTP/2 SETTINGS_HTTP_CERT_AUTH Setting . . . . . . . . . 15 78 6.2. New HTTP/2 Frames . . . . . . . . . . . . . . . . . . . . 16 79 6.2.1. CERTIFICATE_REQUIRED . . . . . . . . . . . . . . . . 16 80 6.2.2. CERTIFICATE_REQUEST . . . . . . . . . . . . . . . . . 16 81 6.2.3. CERTIFICATE . . . . . . . . . . . . . . . . . . . . . 16 82 6.2.4. CERTIFICATE_PROOF . . . . . . . . . . . . . . . . . . 16 83 6.2.5. USE_CERTIFICATE . . . . . . . . . . . . . . . . . . . 16 84 6.3. New HTTP/2 Error Codes . . . . . . . . . . . . . . . . . 17 85 6.3.1. BAD_CERTIFICATE . . . . . . . . . . . . . . . . . . . 17 86 6.3.2. UNSUPPORTED_CERTIFICATE . . . . . . . . . . . . . . . 17 87 6.3.3. CERTIFICATE_REVOKED . . . . . . . . . . . . . . . . . 17 88 6.3.4. CERTIFICATE_EXPIRED . . . . . . . . . . . . . . . . . 17 89 6.3.5. BAD_SIGNATURE . . . . . . . . . . . . . . . . . . . . 17 90 6.3.6. CERTIFICATE_GENERAL . . . . . . . . . . . . . . . . . 18 91 7. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 18 92 8. Normative References . . . . . . . . . . . . . . . . . . . . 18 93 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 19 95 1. Introduction 97 Many existing HTTP [RFC7230] servers have different authentication 98 requirements for the different resources they serve. Of the 99 bountiful authentication options available for authenticating HTTP 100 requests, client certificates present a unique challenge for 101 resource-specific authentication requirements because of the 102 interaction with the underlying TLS RFC5246 [I-D.ietf-tls-tls13] 103 layer. 105 For servers that wish to use client certificates to authenticate 106 users, they might request client authentication during or immediately 107 after the TLS handshake. However, if not all users or resources need 108 certificate-based authentication, a request for a certificate has the 109 unfortunate consequence of triggering the client to seek a 110 certificate. Such a request can result in a poor experience, 111 particularly when sent to a client that does not expect the request. 113 The TLS 1.3 CertificateRequest can be used by servers to give clients 114 hints about which certificate to offer. Servers that rely on 115 certificate-based authentication might request different certificates 116 for different resources. Such a server cannot use contextual 117 information about the resource to construct an appropriate TLS 118 CertificateRequest message during the initial handshake. 120 Consequently, client certificates are requested at connection 121 establishment time only in cases where all clients are expected or 122 required to have a single certificate that is used for all resources. 123 Many other uses for client certificates are reactive, that is, 124 certificates are requested in response to the client making a 125 request. 127 In Yokohama, there was extensive working group discussion regarding 128 why certificate authentication could not easily be done at the HTTP 129 semantic layer. However, in subsequent discussion, it became 130 apparent that the HTTP _framing_ layer did not suffer from the same 131 limitation. 133 In this document, a mechanism for doing certificate-based client 134 authentication via HTTP/2 frames is defined. This mechanism can be 135 implemented at the HTTP layer without requiring new TLS stack 136 behavior and without breaking the existing interface between HTTP and 137 applications which employ client certificates. 139 1.1. Reactive Certificate Authentication in HTTP/1.1 141 1.1.1. Using TLS 1.2 and previous 143 In HTTP/1.1, a server that relies on client authentication for a 144 subset of users or resources does not request a certificate when the 145 connection is established. Instead, it only requests a client 146 certificate when a request is made to a resource that requires a 147 certificate. TLS 1.2 [RFC5246] accomodates this by permitting the 148 server to request a new TLS handshake, in which the server will 149 request the client's certificate. 151 Figure 1 shows the server initiating a TLS-layer renegotiation in 152 response to receiving an HTTP/1.1 request to a protected resource. 154 Client Server 155 -- (HTTP) GET /protected -------------------> *1 156 <---------------------- (TLS) HelloRequest -- *2 157 -- (TLS) ClientHello -----------------------> 158 <------------------ (TLS) ServerHello, ... -- 159 <---------------- (TLS) CertificateRequest -- *3 160 -- (TLS) ..., Certificate ------------------> *4 161 -- (TLS) Finished --------------------------> 162 <-------------------------- (TLS) Finished -- 163 <--------------------------- (HTTP) 200 OK -- *5 165 Figure 1: HTTP/1.1 Reactive Certificate Authentication with TLS 1.2 167 In this example, the server receives a request for a protected 168 resource (at *1 on Figure 1). Upon performing an authorization 169 check, the server determines that the request requires authentication 170 using a client certificate and that no such certificate has been 171 provided. 173 The server initiates TLS renegotiation by sending a TLS HelloRequest 174 (at *2). The client then initiates a TLS handshake. Note that some 175 TLS messages are elided from the figure for the sake of brevity. 177 The critical messages for this example are the server requesting a 178 certificate with a TLS CertificateRequest (*3); this request might 179 use information about the request or resource. The client then 180 provides a certificate and proof of possession of the private key in 181 Certificate and CertificateVerify messages (*4). 183 When the handshake completes, the server performs any authorization 184 checks a second time. With the client certificate available, it then 185 authorizes the request and provides a response (*5). 187 1.1.2. Using TLS 1.3 189 TLS 1.3 [I-D.ietf-tls-tls13] introduces a new client authentication 190 mechanism that allows for clients to authenticate after the handshake 191 has been completed. For the purposes of authenticating an HTTP 192 request, this is functionally equivalent to renegotiation. Figure 2 193 shows the simpler exchange this enables. 195 Client Server 196 -- (HTTP) GET /protected -------------------> 197 <---------------- (TLS) CertificateRequest -- 198 -- (TLS) Certificate, CertificateVerify ----> 199 <--------------------------- (HTTP) 200 OK -- 201 Figure 2: HTTP/1.1 Reactive Certificate Authentication with TLS 1.3 203 TLS 1.3 does not support renegotiation, instead supporting direct 204 client authentication. In contrast to the TLS 1.2 example, in TLS 205 1.3, a server can simply request a certificate. 207 1.2. Reactive Client Authentication in HTTP/2 209 An important part of the HTTP/1.1 exchange is that the client is able 210 to easily identify the request that caused the TLS renegotiation. 211 The client is able to assume that the next unanswered request on the 212 connection is responsible. The HTTP stack in the client is then able 213 to direct the certificate request to the application or component 214 that initiated that request. This ensures that the application has 215 the right contextual information for processing the request. 217 In HTTP/2, a client can have multiple outstanding requests. Without 218 some sort of correlation information, a client is unable to identify 219 which request caused the server to request a certificate. 221 Thus, the minimum necessary mechanism to support reactive certificate 222 authentication in HTTP/2 is an identifier that can be use to 223 correlate an HTTP request with a request for a certificate. 225 Such an identifier could be added to TLS 1.2 by means of an 226 extension, but many TLS 1.2 implementations do not permit application 227 data to continue during a renegotiation. This is problematic for a 228 multiplexed protocol like HTTP/2. Instead, this draft proposes 229 bringing the TLS 1.3 CertificateRequest, Certificate, and 230 CertificateVerify messages into HTTP/2 frames, making client 231 certificate authentication TLS-version-agnostic. 233 This could be done in a naive manner by replicating the messages as 234 HTTP/2 frames on each stream. However, this would create needless 235 redundancy between streams and require frequent expensive signing 236 operations. Instead, this draft lifts the bulky portions of each 237 message into frames on stream zero and permits the on-stream frames 238 to incorporate them by reference as needed. 240 On each stream where certificate authentication is required, the 241 server sends a "CERTIFICATE_REQUIRED" frame, which the client answers 242 with a "USE_CERTIFICATE" frame either indicating the certificate to 243 use, or indicating that no certificate should be used. These frames 244 are simple, referencing information previously sent on stream zero to 245 reduce redundancy. 247 "CERTIFICATE_REQUIRED" frames reference a "CERTIFICATE_REQUEST" on 248 stream zero, analogous to the CertificateRequest message. 249 "USE_CERTIFICATE" frames reference a sequence of "CERTIFICATE" and 250 "CERTIFICATE_PROOF" frames on stream zero, analogous to the the 251 Certificate and CertificateVerify messages. 253 The exchange then looks like this: 255 Client Server 256 -- (streams 1,3) GET /protected ------------> 257 <---------- (stream 0) CERTIFICATE_REQUEST -- 258 <------ (streams 1,3) CERTIFICATE_REQUIRED -- 259 -- (stream 0) CERTIFICATE ------------------> 260 -- (stream 0) CERTIFICATE_PROOF ------------> 261 -- (streams 1,3) USE_CERTIFICATE -----------> 262 <-------------------- (streams 1,3) 200 OK -- 264 Figure 3: HTTP/2 Reactive Certificate Authentication 266 To avoid the extra round-trip per stream required for a challenge and 267 response, the "AUTOMATIC_USE" flag enables a certificate to be 268 automatically used by the server on subsequent requests without 269 sending a "CERTIFICATE_REQUIRED" exchange. 271 Section 2 describes how certificates can be requested and presented 272 at the HTTP/2 framing layer using several new frame types which 273 parallel the TLS 1.3 message exchange. Section 3 defines new error 274 types which can be used to notify peers when the exchange has not 275 been successful. Finally, Section 4 describes how an HTTP/2 client 276 can announce support for this feature so that a server might use 277 these capabilities. 279 1.3. Terminology 281 RFC 2119 [RFC2119] defines the terms "MUST", "MUST NOT", "SHOULD" and 282 "MAY". 284 2. Presenting Client Certificates at the HTTP/2 Framing Layer 286 An HTTP/2 request from a client that has signaled support for 287 reactive certificate authentication (see Section 4) might cause a 288 server to request client authentication. In HTTP/2 a server does 289 this by sending at least one "CERTIFICATE_REQUEST" frame (see 290 Section 2.3) on stream zero and sending a "CERTIFICATE_REQUIRED" 291 frame (see Section 2.1) on the affected stream(s). The 292 "CERTIFICATE_REQUEST" and "CERTIFICATE_REQUIRED" frames are 293 correlated by their "Request-ID" field. Subsequent 294 "CERTIFICATE_REQUIRED" frames with the same Request-ID MAY be sent on 295 other streams where the server is expecting client authentication 296 with the same parameters. 298 A server MAY send multiple concurrent "CERTIFICATE_REQUIRED" frames 299 on the same stream. If a server requires that a client provide 300 multiple certificates before authorizing a single request, it MUST 301 send a "CERTIFICATE_REQUIRED" frame with a different request 302 identifier and a corresponding "CERTIFICATE_REQUEST" frame describing 303 each required certificate. 305 Clients respond to requests by sending one or more "CERTIFICATE" 306 frames (see Section 2.4), followed by a "CERTIFICATE_PROOF" frame 307 (see Section 2.5), on stream zero containing the "Request-ID" to 308 which they are responding. The "USE_CERTIFICATE" (see Section 2.2) 309 frame is sent on-stream to notify the server the stream is ready to 310 be processed. 312 To reduce round-trips, the client MAY set the "AUTOMATIC_USE" flag on 313 a "CERTIFICATE_PROOF" frame, indicating that the server SHOULD 314 automatically apply the supplied certificate to any future streams 315 matching that request, rather than sending a "CERTIFICATE_REQUIRED" 316 frame. 318 2.1. The CERTIFICATE_REQUIRED frame 320 The "CERTIFICATE_REQUIRED" frame (0xFRAME-TBD2) is sent by servers to 321 indicate that processing of an HTTP request is blocked pending 322 certificate authentication. The frame includes a request identifier 323 which can be used to correlate the stream with a previous 324 "CERTIFICATE_REQUEST" frame received on stream zero. The 325 "CERTIFICATE_REQUEST" describes the client certificate the server 326 requires to process the request. 328 The "CERTIFICATE_REQUIRED" frame contains 1 octet, which is the 329 authentication request identifier. A client that receives a 330 "CERTIFICATE_REQUIRED" of any other length MUST treat this as a 331 stream error of type "PROTOCOL_ERROR". Frames with identical request 332 identifiers refer to the same "CERTIFICATE_REQUEST". 334 The "CERTIFICATE_REQUIRED" frame MUST NOT be sent by clients. A 335 "CERTIFICATE_REQUIRED" frame received by a server SHOULD be rejected 336 with a stream error of type PROTOCOL_ERROR. 338 The server MUST NOT send a "CERTIFICATE_REQUIRED" frame on stream 339 zero, a server-initiated stream or a stream that does not have an 340 outstanding request. In other words, a server can only send in the 341 "open" or "half-closed (remote)" stream states. 343 A client that receives a "CERTIFICATE_REQUIRED" frame on a stream 344 which is not in a valid state ("open" or "half-closed (local)" for 345 clients) SHOULD treat this as a connection error of type 346 "PROTOCOL_ERROR". 348 2.2. The USE_CERTIFICATE Frame 350 The "USE_CERTIFICATE" frame (0xFRAME-TBD5) is sent by clients in 351 response to a "CERTIFICATE_REQUIRED" frame to indicate that the 352 requested certificate has been provided (or will not be). 354 A "USE_CERTIFICATE" frame with no payload expresses the client's 355 refusal to use the associated certificate (if any) with this stream. 356 If the request was originally issued for a different stream, servers 357 MAY create a new "CERTIFICATE_REQUEST" and permit the client to offer 358 a different certificate. Alternatively, servers MAY process the 359 request as unauthenticated, likely returning an authentication- 360 related error at the HTTP level (e.g. 403). 362 Otherwise, the "USE_CERTIFICATE" frame contains the "Request-ID" of 363 the now-completed certificate request. This MUST be an ID previously 364 issued by the server, and for which a matching certificate has 365 previously been presented along with a supporting certificate chain 366 in one or more "CERTIFICATE" frames, and for which proof of 367 possession has been presented in a "CERTIFICATE_PROOF" frame. 369 Use of the "USE_CERTIFICATE" frame by servers is not defined by this 370 document. A "USE_CERTIFICATE" frame received by a client MUST be 371 ignored. 373 The client MUST NOT send a "USE_CERTIFICATE" frame on stream zero, a 374 server-initiated stream or a stream that does not have an outstanding 375 request. In other words, a client can only send in the "open" or 376 "half-closed (local)" stream states. The client MUST NOT send a 377 "USE_CERTIFICATE" frame except in response to a 378 "CERTIFICATE_REQUIRED" frame from the server. 380 A server that receives a "USE_CERTIFICATE" frame on a stream which is 381 not in a valid state ("open" or "half-closed (remote)" for servers), 382 on which it has not sent a "CERTIFICATE_REQUIRED" frame, or 383 referencing a certificate it has not previously received SHOULD treat 384 this as a connection error of type "PROTOCOL_ERROR". 386 2.3. The CERTIFICATE_REQUEST Frame 388 TLS 1.3 defines the "CertificateRequest" message, which prompts the 389 client to provide a certificate which conforms to certain properties 390 specified by the server. This draft defines the 391 "CERTIFICATE_REQUEST" frame (0xFRAME-TBD1), which contains the same 392 contents as a TLS 1.3 "CertificateRequest" message, but can be sent 393 over any TLS version. 395 The "CERTIFICATE_REQUEST" frame MUST NOT be sent by clients. A 396 "CERTIFICATE_REQUEST" frame received by a server SHOULD be rejected 397 with a stream error of type "PROTOCOL_ERROR". 399 The "CERTIFICATE_REQUEST" frame MUST be sent on stream zero. A 400 "CERTIFICATE_REQUEST" frame received on any other stream MUST be 401 rejected with a stream error of type "PROTOCOL_ERROR". 403 0 1 2 3 404 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 405 +-------------------------------+-------------------------------+ 406 | Request-ID (8)| Algorithm-Count (16) | Algorithms ... 407 +---------------------------------------------------------------+ 408 | CA-Count (16) | Certificate-Authorities(?) ... 409 +---------------------------------------------------------------+ 410 | Cert-Extension-Count (16) | Cert-Extensions(?) ... 411 +---------------------------------------------------------------+ 413 Figure 4: CERTIFICATE_REQUEST frame payload 415 The frame contains the following fields: 417 Request-ID: "Request-ID" is an 8-bit opaque identifier used to 418 correlate subsequent certificate-related frames with this request. 419 The identifier MUST be unique in the session. 421 Algorithm-Count and Algorithms: A list of the hash/signature 422 algorithm pairs that the server is able to verify, listed in 423 descending order of preference. Any certificates provided by the 424 client MUST be signed using a hash/signature algorithm pair found 425 in "Algorithms". Each algorithm pair is encoded as a 426 "SignatureAndHashAlgorithm" (see [I-D.ietf-tls-tls13] section 427 6.3.2.1), and the number of such structures is given by the 16-bit 428 "Algorithm-Count" field, which MUST NOT be zero. 430 CA-Count and Certificate-Authorities: "Certificate-Authorities" is a 431 series of distinguished names of acceptable certificate 432 authorities, represented in DER-encoded [X690] format. These 433 distinguished names may specify a desired distinguished name for a 434 root CA or for a subordinate CA; thus, this message can be used to 435 describe known roots as well as a desired authorization space. 436 The number of such structures is given by the 16-bit "CA-Count" 437 field, which MAY be zero. If the "CA-Count" field is zero, then 438 the client MAY send any certificate that meets the rest of the 439 selection criteria in the "CERTIFICATE_REQUEST", unless there is 440 some external arrangement to the contrary. 442 Cert-Extension-Count and Cert-Extensions: A list of certificate 443 extension OIDs [RFC5280] with their allowed values, represented in 444 a series of "CertificateExtension" structures (see 445 [I-D.ietf-tls-tls13] section 6.3.5). The list of OIDs MUST be 446 used in certificate selection as described in 447 [I-D.ietf-tls-tls13]. The number of Cert-Extension structures is 448 given by the 16-bit "Cert-Extension-Count" field, which MAY be 449 zero. 451 Some certificate extension OIDs allow multiple values (e.g. Extended 452 Key Usage). If the sender has included a non-empty 453 certificate_extensions list, the certificate MUST contain all of the 454 specified extension OIDs that the recipient recognizes. For each 455 extension OID recognized by the recipient, all of the specified 456 values MUST be present in the certificate (but the certificate MAY 457 have other values as well). However, the recipient MUST ignore and 458 skip any unrecognized certificate extension OIDs. 460 PKIX RFCs define a variety of certificate extension OIDs and their 461 corresponding value types. Depending on the type, matching 462 certificate extension values are not necessarily bitwise-equal. It 463 is expected that implementations will rely on their PKI libraries to 464 perform certificate selection using these certificate extension OIDs. 466 2.4. The CERTIFICATE frame 468 The "CERTIFICATE" frame (0xFRAME-TBD3) allows the sender to provide 469 elements of a certificate chain which can be used as authentication 470 for previous or subsequent requests. 472 The "CERTIFICATE" frame defines no flags. 474 The payload of a "CERTIFICATE" frame contains elements of a 475 certificate chain, terminating in an end certificate. Multiple 476 "CERTIFICATE" frames MAY be sent with the same Request-ID, to 477 accomodate certificate chains which are too large to fit in a single 478 HTTP/2 frame (see [RFC7540] section 4.2). 480 Particularly when a certificate contains a large number of Subject 481 Alternative Names, it might not fit into a single "CERTIFICATE" frame 482 even as the only provided certificate. Senders unable to transfer a 483 requested certificate due to the recipient's 484 "SETTINGS_MAX_FRAME_SIZE" value SHOULD increase their own 485 "SETTINGS_MAX_FRAME_SIZE" to a size that would accomodate their 486 certificate, then terminate affected streams with 487 "CERTIFICATE_TOO_LARGE". 489 Use of the "CERTIFICATE" frame by servers is not defined by this 490 document. A "CERTIFICATE" frame received by a client MUST be 491 ignored. 493 The "CERTIFICATE" frame MUST be sent on stream zero. A "CERTIFICATE" 494 frame received on any other stream MUST be rejected with a stream 495 error of type "PROTOCOL_ERROR". 497 0 1 2 3 498 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 499 +-------------------------------+-------------------------------+ 500 | Request-ID (8)| Cert-Count(8) | Cert-List (*) ... 501 +---------------------------------------------------------------+ 503 Figure 5: CERTIFICATE frame payload 505 The fields defined by the "CERTIFICATE" frame are: 507 Request-ID: The ID of the "CERTIFICATE_REQUEST" to which this frame 508 responds. 510 Cert-Count and Cert-List: A sequence of Certificate objects (see 511 Section 2.4.1), each representing one certificate in the sender's 512 certificate chain. For the first or only "CERTIFICATE" frame with 513 a given Request-ID and Cert-ID, the sender's certificate MUST be 514 the first in the list. Each subsequent certificate SHOULD 515 directly certify the certificate immediately preceding it. A 516 certificate which specifies a trust anchor MAY be omitted, 517 provided that the recipient is known to already possess the 518 relevant certificate. (For example, because it was included in a 519 "CERTIFICATE_REQUEST"'s Certificate-Authorities list.) "Cert- 520 Count" describes the number of certificates provided. 522 The "Request-ID" field MUST contain the same value as the 523 corresponding "CERTIFICATE_REQUEST" frame, and the provided 524 certificate chain MUST conform to the requirements expressed in the 525 "CERTIFICATE_REQUEST" to the best of the client's ability. 526 Specifically: 528 o If the "CERTIFICATE_REQUEST" contained a non-empty "Certificate- 529 Authorities" element, one of the certificates in the chain SHOULD 530 be signed by one of the listed CAs. 532 o If the "CERTIFICATE_REQUEST" contained a non-empty "Cert- 533 Extensions" element, the first certificate MUST match with regard 534 to the extension OIDs recognized by the client. 536 o Each certificate that is not self-signed MUST be signed using a 537 hash/signature algorithm listed in the "Algorithms" element. 539 If these requirements are not satisfied, the server MAY at its 540 discretion either process the request without client authentication, 541 or respond with a stream error [RFC7540] on any stream where the 542 certificate is used. Section 3 defines certificate-related error 543 codes which might be applicable. 545 A client cannot provide different certificates in response to the 546 same "CERTIFICATE_REQUEST" for use on different streams. A client 547 that has already sent and proven a certificate, but does not wish to 548 use it on a particular stream SHOULD send an empty "USE_CERTIFICATE" 549 frame, refusing to use that certificate on that stream. 551 2.4.1. The Certificate structure 553 0 1 2 3 554 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 555 +-------------------------------+-------------------------------+ 556 | Cert-Length (24) | Cert (*) ... 557 +---------------------------------------------------------------+ 559 Figure 6: Certificate structure 561 The Certificate structure is a length-prefixed X.509v3 [RFC5280] 562 certificate. The certificate MUST be signed with an acceptable hash/ 563 signature algorithm pair, if the recipient's list of acceptable pairs 564 is known. 566 2.5. The CERTIFICATE_PROOF Frame 568 The "CERTIFICATE_PROOF" frame proves possession of the private key 569 corresponding to an end certificate previously shown in a 570 "CERTIFICATE" frame, along with its certificate chain in the same or 571 other "CERTIFICATE" frames. 573 The "CERTIFICATE_PROOF" frame defines one flag: 575 AUTOMATIC_USE (0x01): Indicates that the certificate can be used 576 automatically on future requests. 578 0 1 2 3 579 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 580 +-------------------------------+-------------------------------+ 581 | Request-ID (8)| Algorithm (16) | Signature(*)... 582 +---------------------------------------------------------------+ 584 Figure 7: CERTIFICATE_PROOF frame payload 586 The "CERTIFICATE_PROOF" frame (0xFRAME-TBD4) contains an "Algorithm" 587 field (a "SignatureAndHashAlgorithm", from [I-D.ietf-tls-tls13] 588 section 6.3.2.1), describing the hash/signature algorithm pair being 589 used. The signature is performed as described in 590 [I-D.ietf-tls-tls13], with the following values being used: 592 o The context string for the signature is "HTTP/2 CERTIFICATE" 594 o The "specified content" is an [RFC5705] exported value, with the 595 following parameters: 597 * Disambiguating label string: "EXPORTER HTTP/2 CERTIFICATE" 599 * Length: 1024 bytes 601 Because the exported value can be independently calculated by both 602 sides of the TLS connection, the value to be signed is not sent on 603 the wire at any time. The same signed value is used for all 604 "CERTIFICATE_PROOF" frames in a single HTTP/2 connection. 606 A "CERTIFICATE_PROOF" frame MUST be sent only after all "CERTIFICATE" 607 frames with the same Request-ID and Cert-ID have been sent, and MUST 608 correspond to the first certificate presented in the first 609 "CERTIFICATE" frame with that Request-ID and Cert-ID. Receipt of 610 multiple "CERTIFICATE_PROOF" frames for the same Request-ID and Cert- 611 ID, receipt of a "CERTIFICATE_PROOF" frame without a corresponding 612 "CERTIFICATE" frame, or receipt of a "CERTIFICATE" frame after a 613 corresponding "CERTIFICATE_PROOF" MUST be treated as a session error 614 of type "PROTOCOL_ERROR". 616 If the "AUTOMATIC_USE" flag is set, the server MAY omit sending 617 "CERTIFICATE_REQUIRED" frames on future streams associated with this 618 request and use the referenced certificate for authentication without 619 further notice to the client. This behavior is optional, and receipt 620 of a "CERTIFICATE_REQUIRED" frame does not imply that previously- 621 presented certificates were unacceptable to the server. 623 Use of the "CERTIFICATE_PROOF" frame by servers is not defined by 624 this document. A "CERTIFICATE_PROOF" frame received by a client MUST 625 be ignored. 627 3. Indicating failures during HTTP-Layer Certificate Authentication 629 Because this draft permits client certificates to be exchanged at the 630 HTTP framing layer instead of the TLS layer, several certificate- 631 related errors which are defined at the TLS layer might now occur at 632 the HTTP framing layer. In this section, those errors are restated 633 and added to the HTTP/2 error code registry. 635 BAD_CERTIFICATE (0xERROR-TBD1): A certificate was corrupt, contained 636 signatures that did not verify correctly, etc. 638 UNSUPPORTED_CERTIFICATE (0xERROR-TBD2): A certificate was of an 639 unsupported type or did not contain required extensions 641 CERTIFICATE_REVOKED (0xERROR-TBD3): A certificate was revoked by its 642 signer 644 CERTIFICATE_EXPIRED (0xERROR-TBD4): A certificate has expired or is 645 not currently valid 647 BAD_SIGNATURE (0xERROR-TBD5): The digital signature provided did not 648 match 650 CERTIFICATE_TOO_LARGE (0xERROR-TBD6): The certificate cannot be 651 transferred due to the recipient's "SETTINGS_MAX_FRAME_SIZE" 653 CERTIFICATE_GENERAL (0xERROR-TBD7): Any other certificate-related 654 error 656 As described in [RFC7540], implementations MAY choose to treat a 657 stream error as a connection error at any time. Of particular note, 658 a stream error cannot occur on stream 0, which means that 659 implementations cannot send non-session errors in response to 660 "CERTIFICATE_REQUEST" and "CERTIFICATE" frames. Implementations 661 which do not wish to terminate the connection MAY either send 662 relevant errors on any stream which references the failing 663 certificate in question or process the requests as unauthenticated 664 and provide error information at the HTTP semantic layer. 666 4. Indicating Support for HTTP-Layer Certificate Authentication 668 Clients that support HTTP-layer certificate authentication indicate 669 this using the HTTP/2 "SETTINGS_HTTP_CERT_AUTH" (0xSETTING-TBD) 670 setting. 672 The initial value for the "SETTINGS_HTTP_CERT_AUTH" setting is 0, 673 indicating that the client does not support reactive certificate 674 authentication. A client sets the "SETTINGS_HTTP_CERT_AUTH" setting 675 to a value of 1 to indicate support for HTTP-layer certificate 676 authentication as defined in this document. Any value other than 0 677 or 1 MUST be treated as a connection error (Section 5.4.1 of 678 [RFC7540]) of type "PROTOCOL_ERROR". 680 5. Security Considerations 682 Failure to provide a certificate on a stream after receiving 683 "CERTIFICATE_REQUIRED" blocks server processing, and SHOULD be 684 subject to standard timeouts used to guard against unresponsive 685 peers. 687 Implementations need to be aware of the potential for confusion about 688 the state of a connection. The presence or absence of a validated 689 client certificate can change during the processing of a request, 690 potentially multiple times, as "USE_CERTIFICATE" frames are received. 691 A server that uses certificate authentication needs to be prepared to 692 reevaluate the authorization state of a request as the set of 693 certificates changes. 695 6. IANA Considerations 697 The HTTP/2 "SETTINGS_HTTP_CERT_AUTH" setting is registered in 698 Section 6.1. Five frame types are registered in Section 6.2. Five 699 error codes are registered in Section 6.3. 701 6.1. HTTP/2 SETTINGS_HTTP_CERT_AUTH Setting 703 The SETTINGS_HTTP_CERT_AUTH setting is registered in the "HTTP/2 704 Settings" registry established in [RFC7540]. 706 Name: SETTINGS_HTTP_CERT_AUTH 708 Code: 0xSETTING-TBD 709 Initial Value: 0 711 Specification: This document. 713 6.2. New HTTP/2 Frames 715 Four new frame types are registered in the "HTTP/2 Frame Types" 716 registry established in [RFC7540]. 718 6.2.1. CERTIFICATE_REQUIRED 720 Frame Type: CERTIFICATE_REQUIRED 722 Code: 0xFRAME-TBD1 724 Specification: This document. 726 6.2.2. CERTIFICATE_REQUEST 728 Frame Type: CERTIFICATE_REQUEST 730 Code: 0xFRAME-TBD2 732 Specification: This document. 734 6.2.3. CERTIFICATE 736 Frame Type: CERTIFICATE 738 Code: 0xFRAME-TBD3 740 Specification: This document. 742 6.2.4. CERTIFICATE_PROOF 744 Frame Type: CERTIFICATE_PROOF 746 Code: 0xFRAME-TBD4 748 Specification: This document. 750 6.2.5. USE_CERTIFICATE 752 Frame Type: USE_CERTIFICATE 754 Code: 0xFRAME-TBD5 756 Specification: This document. 758 6.3. New HTTP/2 Error Codes 760 Five new error codes are registered in the "HTTP/2 Error Code" 761 registry established in [RFC7540]. 763 6.3.1. BAD_CERTIFICATE 765 Name: BAD_CERTIFICATE 767 Code: 0xERROR-TBD1 769 Specification: This document. 771 6.3.2. UNSUPPORTED_CERTIFICATE 773 Name: UNSUPPORTED_CERTIFICATE 775 Code: 0xERROR-TBD2 777 Specification: This document. 779 6.3.3. CERTIFICATE_REVOKED 781 Name: CERTIFICATE_REVOKED 783 Code: 0xERROR-TBD3 785 Specification: This document. 787 6.3.4. CERTIFICATE_EXPIRED 789 Name: CERTIFICATE_EXPIRED 791 Code: 0xERROR-TBD4 793 Specification: This document. 795 6.3.5. BAD_SIGNATURE 797 Name: BAD_SIGNATURE 799 Code: 0xERROR-TBD5 801 Specification: This document. 803 6.3.6. CERTIFICATE_GENERAL 805 Name: CERTIFICATE_GENERAL 807 Code: 0xERROR-TBD6 809 Specification: This document. 811 7. Acknowledgements 813 Eric Rescorla pointed out several failings in an earlier revision. 814 Andrei Popov contributed to the TLS considerations. 816 8. Normative References 818 [I-D.ietf-tls-tls13] 819 Rescorla, E., "The Transport Layer Security (TLS) Protocol 820 Version 1.3", draft-ietf-tls-tls13-11 (work in progress), 821 December 2015. 823 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 824 Requirement Levels", BCP 14, RFC 2119, DOI 10.17487/ 825 RFC2119, March 1997, 826 . 828 [RFC5246] Dierks, T. and E. Rescorla, "The Transport Layer Security 829 (TLS) Protocol Version 1.2", RFC 5246, DOI 10.17487/ 830 RFC5246, August 2008, 831 . 833 [RFC5280] Cooper, D., Santesson, S., Farrell, S., Boeyen, S., 834 Housley, R., and W. Polk, "Internet X.509 Public Key 835 Infrastructure Certificate and Certificate Revocation List 836 (CRL) Profile", RFC 5280, DOI 10.17487/RFC5280, May 2008, 837 . 839 [RFC5705] Rescorla, E., "Keying Material Exporters for Transport 840 Layer Security (TLS)", RFC 5705, DOI 10.17487/RFC5705, 841 March 2010, . 843 [RFC7230] Fielding, R., Ed. and J. Reschke, Ed., "Hypertext Transfer 844 Protocol (HTTP/1.1): Message Syntax and Routing", RFC 845 7230, DOI 10.17487/RFC7230, June 2014, 846 . 848 [RFC7540] Belshe, M., Peon, R., and M. Thomson, Ed., "Hypertext 849 Transfer Protocol Version 2 (HTTP/2)", RFC 7540, DOI 850 10.17487/RFC7540, May 2015, 851 . 853 [X690] ITU-T, "Information technology - ASN.1 encoding Rules: 854 Specification of Basic Encoding Rules (BER), Canonical 855 Encoding Rules (CER) and Distinguished Encoding Rules 856 (DER)", ISO ISO/IEC 8825-1:2002, 2002, 857 . 860 Authors' Addresses 862 Martin Thomson 863 Mozilla 865 Email: martin.thomson@gmail.com 867 Mike Bishop 868 Microsoft 870 Email: michael.bishop@microsoft.com