HTTP M. Thomson Internet-Draft Mozilla Intended status: Standards Track M. Bishop Expires: July 25, 2016 Microsoft January 22, 2016 Reactive Certificate-Based Client Authentication in HTTP/2 draft-thomson-http2-client-certs-01 Abstract Some HTTP servers provide a subset of resources that require additional authentication to interact with. HTTP/1.1 servers rely on TLS renegotiation that is triggered by a request to a protected resource. HTTP/2 made this pattern impossible by forbidding the use of TLS renegotiation. While TLS 1.3 provides an alternate mechanism to obtain client certificates, this mechanism does not map well to usage in TLS 1.2. This document describes a how client authentication might be requested by a server as a result of receiving a request to a protected resource. Status of This Memo This Internet-Draft is submitted in full conformance with the provisions of BCP 78 and BCP 79. Internet-Drafts are working documents of the Internet Engineering Task Force (IETF). Note that other groups may also distribute working documents as Internet-Drafts. The list of current Internet- Drafts is at http://datatracker.ietf.org/drafts/current/. Internet-Drafts are draft documents valid for a maximum of six months and may be updated, replaced, or obsoleted by other documents at any time. It is inappropriate to use Internet-Drafts as reference material or to cite them other than as "work in progress." This Internet-Draft will expire on July 25, 2016. Copyright Notice Copyright (c) 2016 IETF Trust and the persons identified as the document authors. All rights reserved. This document is subject to BCP 78 and the IETF Trust's Legal Provisions Relating to IETF Documents Thomson & Bishop Expires July 25, 2016 [Page 1] Internet-Draft HTTP/2 Client Certs January 2016 (http://trustee.ietf.org/license-info) in effect on the date of publication of this document. Please review these documents carefully, as they describe your rights and restrictions with respect to this document. Code Components extracted from this document must include Simplified BSD License text as described in Section 4.e of the Trust Legal Provisions and are provided without warranty as described in the Simplified BSD License. Table of Contents 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3 1.1. Reactive Certificate Authentication in HTTP/1.1 . . . . . 4 1.1.1. Using TLS 1.2 and previous . . . . . . . . . . . . . 4 1.1.2. Using TLS 1.3 . . . . . . . . . . . . . . . . . . . . 5 1.2. Reactive Client Authentication in HTTP/2 . . . . . . . . 5 1.3. Terminology . . . . . . . . . . . . . . . . . . . . . . . 7 2. Presenting Client Certificates at the HTTP/2 Framing Layer . 7 2.1. The CERTIFICATE_REQUIRED frame . . . . . . . . . . . . . 7 2.2. The USE_CERTIFICATE Frame . . . . . . . . . . . . . . . . 8 2.3. The CERTIFICATE_REQUEST Frame . . . . . . . . . . . . . . 9 2.4. The CERTIFICATE frame . . . . . . . . . . . . . . . . . . 10 2.4.1. The Certificate structure . . . . . . . . . . . . . . 12 2.5. The CERTIFICATE_PROOF Frame . . . . . . . . . . . . . . . 13 3. Indicating failures during HTTP-Layer Certificate Authentication . . . . . . . . . . . . . . . . . . . . . . . 14 4. Indicating Support for HTTP-Layer Certificate Authentication 15 5. Security Considerations . . . . . . . . . . . . . . . . . . . 15 6. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 15 6.1. HTTP/2 SETTINGS_HTTP_CERT_AUTH Setting . . . . . . . . . 15 6.2. New HTTP/2 Frames . . . . . . . . . . . . . . . . . . . . 16 6.2.1. CERTIFICATE_REQUIRED . . . . . . . . . . . . . . . . 16 6.2.2. CERTIFICATE_REQUEST . . . . . . . . . . . . . . . . . 16 6.2.3. CERTIFICATE . . . . . . . . . . . . . . . . . . . . . 16 6.2.4. CERTIFICATE_PROOF . . . . . . . . . . . . . . . . . . 16 6.2.5. USE_CERTIFICATE . . . . . . . . . . . . . . . . . . . 16 6.3. New HTTP/2 Error Codes . . . . . . . . . . . . . . . . . 17 6.3.1. BAD_CERTIFICATE . . . . . . . . . . . . . . . . . . . 17 6.3.2. UNSUPPORTED_CERTIFICATE . . . . . . . . . . . . . . . 17 6.3.3. CERTIFICATE_REVOKED . . . . . . . . . . . . . . . . . 17 6.3.4. CERTIFICATE_EXPIRED . . . . . . . . . . . . . . . . . 17 6.3.5. BAD_SIGNATURE . . . . . . . . . . . . . . . . . . . . 17 6.3.6. CERTIFICATE_GENERAL . . . . . . . . . . . . . . . . . 18 7. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 18 8. Normative References . . . . . . . . . . . . . . . . . . . . 18 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 19 Thomson & Bishop Expires July 25, 2016 [Page 2] Internet-Draft HTTP/2 Client Certs January 2016 1. Introduction Many existing HTTP [RFC7230] servers have different authentication requirements for the different resources they serve. Of the bountiful authentication options available for authenticating HTTP requests, client certificates present a unique challenge for resource-specific authentication requirements because of the interaction with the underlying TLS RFC5246 [I-D.ietf-tls-tls13] layer. For servers that wish to use client certificates to authenticate users, they might request client authentication during or immediately after the TLS handshake. However, if not all users or resources need certificate-based authentication, a request for a certificate has the unfortunate consequence of triggering the client to seek a certificate. Such a request can result in a poor experience, particularly when sent to a client that does not expect the request. The TLS 1.3 CertificateRequest can be used by servers to give clients hints about which certificate to offer. Servers that rely on certificate-based authentication might request different certificates for different resources. Such a server cannot use contextual information about the resource to construct an appropriate TLS CertificateRequest message during the initial handshake. Consequently, client certificates are requested at connection establishment time only in cases where all clients are expected or required to have a single certificate that is used for all resources. Many other uses for client certificates are reactive, that is, certificates are requested in response to the client making a request. In Yokohama, there was extensive working group discussion regarding why certificate authentication could not easily be done at the HTTP semantic layer. However, in subsequent discussion, it became apparent that the HTTP _framing_ layer did not suffer from the same limitation. In this document, a mechanism for doing certificate-based client authentication via HTTP/2 frames is defined. This mechanism can be implemented at the HTTP layer without requiring new TLS stack behavior and without breaking the existing interface between HTTP and applications which employ client certificates. Thomson & Bishop Expires July 25, 2016 [Page 3] Internet-Draft HTTP/2 Client Certs January 2016 1.1. Reactive Certificate Authentication in HTTP/1.1 1.1.1. Using TLS 1.2 and previous In HTTP/1.1, a server that relies on client authentication for a subset of users or resources does not request a certificate when the connection is established. Instead, it only requests a client certificate when a request is made to a resource that requires a certificate. TLS 1.2 [RFC5246] accomodates this by permitting the server to request a new TLS handshake, in which the server will request the client's certificate. Figure 1 shows the server initiating a TLS-layer renegotiation in response to receiving an HTTP/1.1 request to a protected resource. Client Server -- (HTTP) GET /protected -------------------> *1 <---------------------- (TLS) HelloRequest -- *2 -- (TLS) ClientHello -----------------------> <------------------ (TLS) ServerHello, ... -- <---------------- (TLS) CertificateRequest -- *3 -- (TLS) ..., Certificate ------------------> *4 -- (TLS) Finished --------------------------> <-------------------------- (TLS) Finished -- <--------------------------- (HTTP) 200 OK -- *5 Figure 1: HTTP/1.1 Reactive Certificate Authentication with TLS 1.2 In this example, the server receives a request for a protected resource (at *1 on Figure 1). Upon performing an authorization check, the server determines that the request requires authentication using a client certificate and that no such certificate has been provided. The server initiates TLS renegotiation by sending a TLS HelloRequest (at *2). The client then initiates a TLS handshake. Note that some TLS messages are elided from the figure for the sake of brevity. The critical messages for this example are the server requesting a certificate with a TLS CertificateRequest (*3); this request might use information about the request or resource. The client then provides a certificate and proof of possession of the private key in Certificate and CertificateVerify messages (*4). When the handshake completes, the server performs any authorization checks a second time. With the client certificate available, it then authorizes the request and provides a response (*5). Thomson & Bishop Expires July 25, 2016 [Page 4] Internet-Draft HTTP/2 Client Certs January 2016 1.1.2. Using TLS 1.3 TLS 1.3 [I-D.ietf-tls-tls13] introduces a new client authentication mechanism that allows for clients to authenticate after the handshake has been completed. For the purposes of authenticating an HTTP request, this is functionally equivalent to renegotiation. Figure 2 shows the simpler exchange this enables. Client Server -- (HTTP) GET /protected -------------------> <---------------- (TLS) CertificateRequest -- -- (TLS) Certificate, CertificateVerify ----> <--------------------------- (HTTP) 200 OK -- Figure 2: HTTP/1.1 Reactive Certificate Authentication with TLS 1.3 TLS 1.3 does not support renegotiation, instead supporting direct client authentication. In contrast to the TLS 1.2 example, in TLS 1.3, a server can simply request a certificate. 1.2. Reactive Client Authentication in HTTP/2 An important part of the HTTP/1.1 exchange is that the client is able to easily identify the request that caused the TLS renegotiation. The client is able to assume that the next unanswered request on the connection is responsible. The HTTP stack in the client is then able to direct the certificate request to the application or component that initiated that request. This ensures that the application has the right contextual information for processing the request. In HTTP/2, a client can have multiple outstanding requests. Without some sort of correlation information, a client is unable to identify which request caused the server to request a certificate. Thus, the minimum necessary mechanism to support reactive certificate authentication in HTTP/2 is an identifier that can be use to correlate an HTTP request with a request for a certificate. Such an identifier could be added to TLS 1.2 by means of an extension, but many TLS 1.2 implementations do not permit application data to continue during a renegotiation. This is problematic for a multiplexed protocol like HTTP/2. Instead, this draft proposes bringing the TLS 1.3 CertificateRequest, Certificate, and CertificateVerify messages into HTTP/2 frames, making client certificate authentication TLS-version-agnostic. This could be done in a naive manner by replicating the messages as HTTP/2 frames on each stream. However, this would create needless Thomson & Bishop Expires July 25, 2016 [Page 5] Internet-Draft HTTP/2 Client Certs January 2016 redundancy between streams and require frequent expensive signing operations. Instead, this draft lifts the bulky portions of each message into frames on stream zero and permits the on-stream frames to incorporate them by reference as needed. On each stream where certificate authentication is required, the server sends a "CERTIFICATE_REQUIRED" frame, which the client answers with a "USE_CERTIFICATE" frame either indicating the certificate to use, or indicating that no certificate should be used. These frames are simple, referencing information previously sent on stream zero to reduce redundancy. "CERTIFICATE_REQUIRED" frames reference a "CERTIFICATE_REQUEST" on stream zero, analogous to the CertificateRequest message. "USE_CERTIFICATE" frames reference a sequence of "CERTIFICATE" and "CERTIFICATE_PROOF" frames on stream zero, analogous to the the Certificate and CertificateVerify messages. The exchange then looks like this: Client Server -- (streams 1,3) GET /protected ------------> <---------- (stream 0) CERTIFICATE_REQUEST -- <------ (streams 1,3) CERTIFICATE_REQUIRED -- -- (stream 0) CERTIFICATE ------------------> -- (stream 0) CERTIFICATE_PROOF ------------> -- (streams 1,3) USE_CERTIFICATE -----------> <-------------------- (streams 1,3) 200 OK -- Figure 3: HTTP/2 Reactive Certificate Authentication To avoid the extra round-trip per stream required for a challenge and response, the "AUTOMATIC_USE" flag enables a certificate to be automatically used by the server on subsequent requests without sending a "CERTIFICATE_REQUIRED" exchange. Section 2 describes how certificates can be requested and presented at the HTTP/2 framing layer using several new frame types which parallel the TLS 1.3 message exchange. Section 3 defines new error types which can be used to notify peers when the exchange has not been successful. Finally, Section 4 describes how an HTTP/2 client can announce support for this feature so that a server might use these capabilities. Thomson & Bishop Expires July 25, 2016 [Page 6] Internet-Draft HTTP/2 Client Certs January 2016 1.3. Terminology RFC 2119 [RFC2119] defines the terms "MUST", "MUST NOT", "SHOULD" and "MAY". 2. Presenting Client Certificates at the HTTP/2 Framing Layer An HTTP/2 request from a client that has signaled support for reactive certificate authentication (see Section 4) might cause a server to request client authentication. In HTTP/2 a server does this by sending at least one "CERTIFICATE_REQUEST" frame (see Section 2.3) on stream zero and sending a "CERTIFICATE_REQUIRED" frame (see Section 2.1) on the affected stream(s). The "CERTIFICATE_REQUEST" and "CERTIFICATE_REQUIRED" frames are correlated by their "Request-ID" field. Subsequent "CERTIFICATE_REQUIRED" frames with the same Request-ID MAY be sent on other streams where the server is expecting client authentication with the same parameters. A server MAY send multiple concurrent "CERTIFICATE_REQUIRED" frames on the same stream. If a server requires that a client provide multiple certificates before authorizing a single request, it MUST send a "CERTIFICATE_REQUIRED" frame with a different request identifier and a corresponding "CERTIFICATE_REQUEST" frame describing each required certificate. Clients respond to requests by sending one or more "CERTIFICATE" frames (see Section 2.4), followed by a "CERTIFICATE_PROOF" frame (see Section 2.5), on stream zero containing the "Request-ID" to which they are responding. The "USE_CERTIFICATE" (see Section 2.2) frame is sent on-stream to notify the server the stream is ready to be processed. To reduce round-trips, the client MAY set the "AUTOMATIC_USE" flag on a "CERTIFICATE_PROOF" frame, indicating that the server SHOULD automatically apply the supplied certificate to any future streams matching that request, rather than sending a "CERTIFICATE_REQUIRED" frame. 2.1. The CERTIFICATE_REQUIRED frame The "CERTIFICATE_REQUIRED" frame (0xFRAME-TBD2) is sent by servers to indicate that processing of an HTTP request is blocked pending certificate authentication. The frame includes a request identifier which can be used to correlate the stream with a previous "CERTIFICATE_REQUEST" frame received on stream zero. The "CERTIFICATE_REQUEST" describes the client certificate the server requires to process the request. Thomson & Bishop Expires July 25, 2016 [Page 7] Internet-Draft HTTP/2 Client Certs January 2016 The "CERTIFICATE_REQUIRED" frame contains 1 octet, which is the authentication request identifier. A client that receives a "CERTIFICATE_REQUIRED" of any other length MUST treat this as a stream error of type "PROTOCOL_ERROR". Frames with identical request identifiers refer to the same "CERTIFICATE_REQUEST". The "CERTIFICATE_REQUIRED" frame MUST NOT be sent by clients. A "CERTIFICATE_REQUIRED" frame received by a server SHOULD be rejected with a stream error of type PROTOCOL_ERROR. The server MUST NOT send a "CERTIFICATE_REQUIRED" frame on stream zero, a server-initiated stream or a stream that does not have an outstanding request. In other words, a server can only send in the "open" or "half-closed (remote)" stream states. A client that receives a "CERTIFICATE_REQUIRED" frame on a stream which is not in a valid state ("open" or "half-closed (local)" for clients) SHOULD treat this as a connection error of type "PROTOCOL_ERROR". 2.2. The USE_CERTIFICATE Frame The "USE_CERTIFICATE" frame (0xFRAME-TBD5) is sent by clients in response to a "CERTIFICATE_REQUIRED" frame to indicate that the requested certificate has been provided (or will not be). A "USE_CERTIFICATE" frame with no payload expresses the client's refusal to use the associated certificate (if any) with this stream. If the request was originally issued for a different stream, servers MAY create a new "CERTIFICATE_REQUEST" and permit the client to offer a different certificate. Alternatively, servers MAY process the request as unauthenticated, likely returning an authentication- related error at the HTTP level (e.g. 403). Otherwise, the "USE_CERTIFICATE" frame contains the "Request-ID" of the now-completed certificate request. This MUST be an ID previously issued by the server, and for which a matching certificate has previously been presented along with a supporting certificate chain in one or more "CERTIFICATE" frames, and for which proof of possession has been presented in a "CERTIFICATE_PROOF" frame. Use of the "USE_CERTIFICATE" frame by servers is not defined by this document. A "USE_CERTIFICATE" frame received by a client MUST be ignored. The client MUST NOT send a "USE_CERTIFICATE" frame on stream zero, a server-initiated stream or a stream that does not have an outstanding request. In other words, a client can only send in the "open" or Thomson & Bishop Expires July 25, 2016 [Page 8] Internet-Draft HTTP/2 Client Certs January 2016 "half-closed (local)" stream states. The client MUST NOT send a "USE_CERTIFICATE" frame except in response to a "CERTIFICATE_REQUIRED" frame from the server. A server that receives a "USE_CERTIFICATE" frame on a stream which is not in a valid state ("open" or "half-closed (remote)" for servers), on which it has not sent a "CERTIFICATE_REQUIRED" frame, or referencing a certificate it has not previously received SHOULD treat this as a connection error of type "PROTOCOL_ERROR". 2.3. The CERTIFICATE_REQUEST Frame TLS 1.3 defines the "CertificateRequest" message, which prompts the client to provide a certificate which conforms to certain properties specified by the server. This draft defines the "CERTIFICATE_REQUEST" frame (0xFRAME-TBD1), which contains the same contents as a TLS 1.3 "CertificateRequest" message, but can be sent over any TLS version. The "CERTIFICATE_REQUEST" frame MUST NOT be sent by clients. A "CERTIFICATE_REQUEST" frame received by a server SHOULD be rejected with a stream error of type "PROTOCOL_ERROR". The "CERTIFICATE_REQUEST" frame MUST be sent on stream zero. A "CERTIFICATE_REQUEST" frame received on any other stream MUST be rejected with a stream error of type "PROTOCOL_ERROR". 0 1 2 3 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 +-------------------------------+-------------------------------+ | Request-ID (8)| Algorithm-Count (16) | Algorithms ... +---------------------------------------------------------------+ | CA-Count (16) | Certificate-Authorities(?) ... +---------------------------------------------------------------+ | Cert-Extension-Count (16) | Cert-Extensions(?) ... +---------------------------------------------------------------+ Figure 4: CERTIFICATE_REQUEST frame payload The frame contains the following fields: Request-ID: "Request-ID" is an 8-bit opaque identifier used to correlate subsequent certificate-related frames with this request. The identifier MUST be unique in the session. Algorithm-Count and Algorithms: A list of the hash/signature algorithm pairs that the server is able to verify, listed in descending order of preference. Any certificates provided by the Thomson & Bishop Expires July 25, 2016 [Page 9] Internet-Draft HTTP/2 Client Certs January 2016 client MUST be signed using a hash/signature algorithm pair found in "Algorithms". Each algorithm pair is encoded as a "SignatureAndHashAlgorithm" (see [I-D.ietf-tls-tls13] section 6.3.2.1), and the number of such structures is given by the 16-bit "Algorithm-Count" field, which MUST NOT be zero. CA-Count and Certificate-Authorities: "Certificate-Authorities" is a series of distinguished names of acceptable certificate authorities, represented in DER-encoded [X690] format. These distinguished names may specify a desired distinguished name for a root CA or for a subordinate CA; thus, this message can be used to describe known roots as well as a desired authorization space. The number of such structures is given by the 16-bit "CA-Count" field, which MAY be zero. If the "CA-Count" field is zero, then the client MAY send any certificate that meets the rest of the selection criteria in the "CERTIFICATE_REQUEST", unless there is some external arrangement to the contrary. Cert-Extension-Count and Cert-Extensions: A list of certificate extension OIDs [RFC5280] with their allowed values, represented in a series of "CertificateExtension" structures (see [I-D.ietf-tls-tls13] section 6.3.5). The list of OIDs MUST be used in certificate selection as described in [I-D.ietf-tls-tls13]. The number of Cert-Extension structures is given by the 16-bit "Cert-Extension-Count" field, which MAY be zero. Some certificate extension OIDs allow multiple values (e.g. Extended Key Usage). If the sender has included a non-empty certificate_extensions list, the certificate MUST contain all of the specified extension OIDs that the recipient recognizes. For each extension OID recognized by the recipient, all of the specified values MUST be present in the certificate (but the certificate MAY have other values as well). However, the recipient MUST ignore and skip any unrecognized certificate extension OIDs. PKIX RFCs define a variety of certificate extension OIDs and their corresponding value types. Depending on the type, matching certificate extension values are not necessarily bitwise-equal. It is expected that implementations will rely on their PKI libraries to perform certificate selection using these certificate extension OIDs. 2.4. The CERTIFICATE frame The "CERTIFICATE" frame (0xFRAME-TBD3) allows the sender to provide elements of a certificate chain which can be used as authentication for previous or subsequent requests. Thomson & Bishop Expires July 25, 2016 [Page 10] Internet-Draft HTTP/2 Client Certs January 2016 The "CERTIFICATE" frame defines no flags. The payload of a "CERTIFICATE" frame contains elements of a certificate chain, terminating in an end certificate. Multiple "CERTIFICATE" frames MAY be sent with the same Request-ID, to accomodate certificate chains which are too large to fit in a single HTTP/2 frame (see [RFC7540] section 4.2). Particularly when a certificate contains a large number of Subject Alternative Names, it might not fit into a single "CERTIFICATE" frame even as the only provided certificate. Senders unable to transfer a requested certificate due to the recipient's "SETTINGS_MAX_FRAME_SIZE" value SHOULD increase their own "SETTINGS_MAX_FRAME_SIZE" to a size that would accomodate their certificate, then terminate affected streams with "CERTIFICATE_TOO_LARGE". Use of the "CERTIFICATE" frame by servers is not defined by this document. A "CERTIFICATE" frame received by a client MUST be ignored. The "CERTIFICATE" frame MUST be sent on stream zero. A "CERTIFICATE" frame received on any other stream MUST be rejected with a stream error of type "PROTOCOL_ERROR". 0 1 2 3 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 +-------------------------------+-------------------------------+ | Request-ID (8)| Cert-Count(8) | Cert-List (*) ... +---------------------------------------------------------------+ Figure 5: CERTIFICATE frame payload The fields defined by the "CERTIFICATE" frame are: Request-ID: The ID of the "CERTIFICATE_REQUEST" to which this frame responds. Cert-Count and Cert-List: A sequence of Certificate objects (see Section 2.4.1), each representing one certificate in the sender's certificate chain. For the first or only "CERTIFICATE" frame with a given Request-ID and Cert-ID, the sender's certificate MUST be the first in the list. Each subsequent certificate SHOULD directly certify the certificate immediately preceding it. A certificate which specifies a trust anchor MAY be omitted, provided that the recipient is known to already possess the relevant certificate. (For example, because it was included in a Thomson & Bishop Expires July 25, 2016 [Page 11] Internet-Draft HTTP/2 Client Certs January 2016 "CERTIFICATE_REQUEST"'s Certificate-Authorities list.) "Cert- Count" describes the number of certificates provided. The "Request-ID" field MUST contain the same value as the corresponding "CERTIFICATE_REQUEST" frame, and the provided certificate chain MUST conform to the requirements expressed in the "CERTIFICATE_REQUEST" to the best of the client's ability. Specifically: o If the "CERTIFICATE_REQUEST" contained a non-empty "Certificate- Authorities" element, one of the certificates in the chain SHOULD be signed by one of the listed CAs. o If the "CERTIFICATE_REQUEST" contained a non-empty "Cert- Extensions" element, the first certificate MUST match with regard to the extension OIDs recognized by the client. o Each certificate that is not self-signed MUST be signed using a hash/signature algorithm listed in the "Algorithms" element. If these requirements are not satisfied, the server MAY at its discretion either process the request without client authentication, or respond with a stream error [RFC7540] on any stream where the certificate is used. Section 3 defines certificate-related error codes which might be applicable. A client cannot provide different certificates in response to the same "CERTIFICATE_REQUEST" for use on different streams. A client that has already sent and proven a certificate, but does not wish to use it on a particular stream SHOULD send an empty "USE_CERTIFICATE" frame, refusing to use that certificate on that stream. 2.4.1. The Certificate structure 0 1 2 3 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 +-------------------------------+-------------------------------+ | Cert-Length (24) | Cert (*) ... +---------------------------------------------------------------+ Figure 6: Certificate structure The Certificate structure is a length-prefixed X.509v3 [RFC5280] certificate. The certificate MUST be signed with an acceptable hash/ signature algorithm pair, if the recipient's list of acceptable pairs is known. Thomson & Bishop Expires July 25, 2016 [Page 12] Internet-Draft HTTP/2 Client Certs January 2016 2.5. The CERTIFICATE_PROOF Frame The "CERTIFICATE_PROOF" frame proves possession of the private key corresponding to an end certificate previously shown in a "CERTIFICATE" frame, along with its certificate chain in the same or other "CERTIFICATE" frames. The "CERTIFICATE_PROOF" frame defines one flag: AUTOMATIC_USE (0x01): Indicates that the certificate can be used automatically on future requests. 0 1 2 3 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 +-------------------------------+-------------------------------+ | Request-ID (8)| Algorithm (16) | Signature(*)... +---------------------------------------------------------------+ Figure 7: CERTIFICATE_PROOF frame payload The "CERTIFICATE_PROOF" frame (0xFRAME-TBD4) contains an "Algorithm" field (a "SignatureAndHashAlgorithm", from [I-D.ietf-tls-tls13] section 6.3.2.1), describing the hash/signature algorithm pair being used. The signature is performed as described in [I-D.ietf-tls-tls13], with the following values being used: o The context string for the signature is "HTTP/2 CERTIFICATE" o The "specified content" is an [RFC5705] exported value, with the following parameters: * Disambiguating label string: "EXPORTER HTTP/2 CERTIFICATE" * Length: 1024 bytes Because the exported value can be independently calculated by both sides of the TLS connection, the value to be signed is not sent on the wire at any time. The same signed value is used for all "CERTIFICATE_PROOF" frames in a single HTTP/2 connection. A "CERTIFICATE_PROOF" frame MUST be sent only after all "CERTIFICATE" frames with the same Request-ID and Cert-ID have been sent, and MUST correspond to the first certificate presented in the first "CERTIFICATE" frame with that Request-ID and Cert-ID. Receipt of multiple "CERTIFICATE_PROOF" frames for the same Request-ID and Cert- ID, receipt of a "CERTIFICATE_PROOF" frame without a corresponding "CERTIFICATE" frame, or receipt of a "CERTIFICATE" frame after a Thomson & Bishop Expires July 25, 2016 [Page 13] Internet-Draft HTTP/2 Client Certs January 2016 corresponding "CERTIFICATE_PROOF" MUST be treated as a session error of type "PROTOCOL_ERROR". If the "AUTOMATIC_USE" flag is set, the server MAY omit sending "CERTIFICATE_REQUIRED" frames on future streams associated with this request and use the referenced certificate for authentication without further notice to the client. This behavior is optional, and receipt of a "CERTIFICATE_REQUIRED" frame does not imply that previously- presented certificates were unacceptable to the server. Use of the "CERTIFICATE_PROOF" frame by servers is not defined by this document. A "CERTIFICATE_PROOF" frame received by a client MUST be ignored. 3. Indicating failures during HTTP-Layer Certificate Authentication Because this draft permits client certificates to be exchanged at the HTTP framing layer instead of the TLS layer, several certificate- related errors which are defined at the TLS layer might now occur at the HTTP framing layer. In this section, those errors are restated and added to the HTTP/2 error code registry. BAD_CERTIFICATE (0xERROR-TBD1): A certificate was corrupt, contained signatures that did not verify correctly, etc. UNSUPPORTED_CERTIFICATE (0xERROR-TBD2): A certificate was of an unsupported type or did not contain required extensions CERTIFICATE_REVOKED (0xERROR-TBD3): A certificate was revoked by its signer CERTIFICATE_EXPIRED (0xERROR-TBD4): A certificate has expired or is not currently valid BAD_SIGNATURE (0xERROR-TBD5): The digital signature provided did not match CERTIFICATE_TOO_LARGE (0xERROR-TBD6): The certificate cannot be transferred due to the recipient's "SETTINGS_MAX_FRAME_SIZE" CERTIFICATE_GENERAL (0xERROR-TBD7): Any other certificate-related error As described in [RFC7540], implementations MAY choose to treat a stream error as a connection error at any time. Of particular note, a stream error cannot occur on stream 0, which means that implementations cannot send non-session errors in response to "CERTIFICATE_REQUEST" and "CERTIFICATE" frames. Implementations Thomson & Bishop Expires July 25, 2016 [Page 14] Internet-Draft HTTP/2 Client Certs January 2016 which do not wish to terminate the connection MAY either send relevant errors on any stream which references the failing certificate in question or process the requests as unauthenticated and provide error information at the HTTP semantic layer. 4. Indicating Support for HTTP-Layer Certificate Authentication Clients that support HTTP-layer certificate authentication indicate this using the HTTP/2 "SETTINGS_HTTP_CERT_AUTH" (0xSETTING-TBD) setting. The initial value for the "SETTINGS_HTTP_CERT_AUTH" setting is 0, indicating that the client does not support reactive certificate authentication. A client sets the "SETTINGS_HTTP_CERT_AUTH" setting to a value of 1 to indicate support for HTTP-layer certificate authentication as defined in this document. Any value other than 0 or 1 MUST be treated as a connection error (Section 5.4.1 of [RFC7540]) of type "PROTOCOL_ERROR". 5. Security Considerations Failure to provide a certificate on a stream after receiving "CERTIFICATE_REQUIRED" blocks server processing, and SHOULD be subject to standard timeouts used to guard against unresponsive peers. Implementations need to be aware of the potential for confusion about the state of a connection. The presence or absence of a validated client certificate can change during the processing of a request, potentially multiple times, as "USE_CERTIFICATE" frames are received. A server that uses certificate authentication needs to be prepared to reevaluate the authorization state of a request as the set of certificates changes. 6. IANA Considerations The HTTP/2 "SETTINGS_HTTP_CERT_AUTH" setting is registered in Section 6.1. Five frame types are registered in Section 6.2. Five error codes are registered in Section 6.3. 6.1. HTTP/2 SETTINGS_HTTP_CERT_AUTH Setting The SETTINGS_HTTP_CERT_AUTH setting is registered in the "HTTP/2 Settings" registry established in [RFC7540]. Name: SETTINGS_HTTP_CERT_AUTH Code: 0xSETTING-TBD Thomson & Bishop Expires July 25, 2016 [Page 15] Internet-Draft HTTP/2 Client Certs January 2016 Initial Value: 0 Specification: This document. 6.2. New HTTP/2 Frames Four new frame types are registered in the "HTTP/2 Frame Types" registry established in [RFC7540]. 6.2.1. CERTIFICATE_REQUIRED Frame Type: CERTIFICATE_REQUIRED Code: 0xFRAME-TBD1 Specification: This document. 6.2.2. CERTIFICATE_REQUEST Frame Type: CERTIFICATE_REQUEST Code: 0xFRAME-TBD2 Specification: This document. 6.2.3. CERTIFICATE Frame Type: CERTIFICATE Code: 0xFRAME-TBD3 Specification: This document. 6.2.4. CERTIFICATE_PROOF Frame Type: CERTIFICATE_PROOF Code: 0xFRAME-TBD4 Specification: This document. 6.2.5. USE_CERTIFICATE Frame Type: USE_CERTIFICATE Code: 0xFRAME-TBD5 Specification: This document. Thomson & Bishop Expires July 25, 2016 [Page 16] Internet-Draft HTTP/2 Client Certs January 2016 6.3. New HTTP/2 Error Codes Five new error codes are registered in the "HTTP/2 Error Code" registry established in [RFC7540]. 6.3.1. BAD_CERTIFICATE Name: BAD_CERTIFICATE Code: 0xERROR-TBD1 Specification: This document. 6.3.2. UNSUPPORTED_CERTIFICATE Name: UNSUPPORTED_CERTIFICATE Code: 0xERROR-TBD2 Specification: This document. 6.3.3. CERTIFICATE_REVOKED Name: CERTIFICATE_REVOKED Code: 0xERROR-TBD3 Specification: This document. 6.3.4. CERTIFICATE_EXPIRED Name: CERTIFICATE_EXPIRED Code: 0xERROR-TBD4 Specification: This document. 6.3.5. BAD_SIGNATURE Name: BAD_SIGNATURE Code: 0xERROR-TBD5 Specification: This document. Thomson & Bishop Expires July 25, 2016 [Page 17] Internet-Draft HTTP/2 Client Certs January 2016 6.3.6. CERTIFICATE_GENERAL Name: CERTIFICATE_GENERAL Code: 0xERROR-TBD6 Specification: This document. 7. Acknowledgements Eric Rescorla pointed out several failings in an earlier revision. Andrei Popov contributed to the TLS considerations. 8. Normative References [I-D.ietf-tls-tls13] Rescorla, E., "The Transport Layer Security (TLS) Protocol Version 1.3", draft-ietf-tls-tls13-11 (work in progress), December 2015. [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, DOI 10.17487/ RFC2119, March 1997, . [RFC5246] Dierks, T. and E. Rescorla, "The Transport Layer Security (TLS) Protocol Version 1.2", RFC 5246, DOI 10.17487/ RFC5246, August 2008, . [RFC5280] Cooper, D., Santesson, S., Farrell, S., Boeyen, S., Housley, R., and W. Polk, "Internet X.509 Public Key Infrastructure Certificate and Certificate Revocation List (CRL) Profile", RFC 5280, DOI 10.17487/RFC5280, May 2008, . [RFC5705] Rescorla, E., "Keying Material Exporters for Transport Layer Security (TLS)", RFC 5705, DOI 10.17487/RFC5705, March 2010, . [RFC7230] Fielding, R., Ed. and J. Reschke, Ed., "Hypertext Transfer Protocol (HTTP/1.1): Message Syntax and Routing", RFC 7230, DOI 10.17487/RFC7230, June 2014, . Thomson & Bishop Expires July 25, 2016 [Page 18] Internet-Draft HTTP/2 Client Certs January 2016 [RFC7540] Belshe, M., Peon, R., and M. Thomson, Ed., "Hypertext Transfer Protocol Version 2 (HTTP/2)", RFC 7540, DOI 10.17487/RFC7540, May 2015, . [X690] ITU-T, "Information technology - ASN.1 encoding Rules: Specification of Basic Encoding Rules (BER), Canonical Encoding Rules (CER) and Distinguished Encoding Rules (DER)", ISO ISO/IEC 8825-1:2002, 2002, . Authors' Addresses Martin Thomson Mozilla Email: martin.thomson@gmail.com Mike Bishop Microsoft Email: michael.bishop@microsoft.com Thomson & Bishop Expires July 25, 2016 [Page 19]