draft-ietf-httpbis-http2-secondary-certs-01.txt   draft-ietf-httpbis-http2-secondary-certs-02.txt 
HTTP M. Bishop HTTP M. Bishop
Internet-Draft Akamai Internet-Draft Akamai
Intended status: Standards Track N. Sullivan Intended status: Standards Track N. Sullivan
Expires: November 29, 2018 Cloudflare Expires: December 28, 2018 Cloudflare
M. Thomson M. Thomson
Mozilla Mozilla
May 28, 2018 June 26, 2018
Secondary Certificate Authentication in HTTP/2 Secondary Certificate Authentication in HTTP/2
draft-ietf-httpbis-http2-secondary-certs-01 draft-ietf-httpbis-http2-secondary-certs-02
Abstract Abstract
A use of TLS Exported Authenticators is described which enables A use of TLS Exported Authenticators is described which enables
HTTP/2 clients and servers to offer additional certificate-based HTTP/2 clients and servers to offer additional certificate-based
credentials after the connection is established. The means by which credentials after the connection is established. The means by which
these credentials are used with requests is defined. these credentials are used with requests is defined.
Note to Readers Note to Readers
skipping to change at page 1, line 46 skipping to change at page 1, line 46
Internet-Drafts are working documents of the Internet Engineering Internet-Drafts are working documents of the Internet Engineering
Task Force (IETF). Note that other groups may also distribute Task Force (IETF). Note that other groups may also distribute
working documents as Internet-Drafts. The list of current Internet- working documents as Internet-Drafts. The list of current Internet-
Drafts is at https://datatracker.ietf.org/drafts/current/. Drafts is at https://datatracker.ietf.org/drafts/current/.
Internet-Drafts are draft documents valid for a maximum of six months Internet-Drafts are draft documents valid for a maximum of six months
and may be updated, replaced, or obsoleted by other documents at any and may be updated, replaced, or obsoleted by other documents at any
time. It is inappropriate to use Internet-Drafts as reference time. It is inappropriate to use Internet-Drafts as reference
material or to cite them other than as "work in progress." material or to cite them other than as "work in progress."
This Internet-Draft will expire on November 29, 2018. This Internet-Draft will expire on December 28, 2018.
Copyright Notice Copyright Notice
Copyright (c) 2018 IETF Trust and the persons identified as the Copyright (c) 2018 IETF Trust and the persons identified as the
document authors. All rights reserved. document authors. All rights reserved.
This document is subject to BCP 78 and the IETF Trust's Legal This document is subject to BCP 78 and the IETF Trust's Legal
Provisions Relating to IETF Documents Provisions Relating to IETF Documents
(https://trustee.ietf.org/license-info) in effect on the date of (https://trustee.ietf.org/license-info) in effect on the date of
publication of this document. Please review these documents publication of this document. Please review these documents
skipping to change at page 2, line 25 skipping to change at page 2, line 25
to this document. Code Components extracted from this document must to this document. Code Components extracted from this document must
include Simplified BSD License text as described in Section 4.e of include Simplified BSD License text as described in Section 4.e of
the Trust Legal Provisions and are provided without warranty as the Trust Legal Provisions and are provided without warranty as
described in the Simplified BSD License. described in the Simplified BSD License.
Table of Contents Table of Contents
1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3
1.1. Server Certificate Authentication . . . . . . . . . . . . 3 1.1. Server Certificate Authentication . . . . . . . . . . . . 3
1.2. Client Certificate Authentication . . . . . . . . . . . . 4 1.2. Client Certificate Authentication . . . . . . . . . . . . 4
1.2.1. HTTP/1.1 using TLS 1.2 and previous . . . . . . . . . 5 1.2.1. HTTP/1.1 Using TLS 1.2 and Earlier . . . . . . . . . 5
1.2.2. HTTP/1.1 using TLS 1.3 . . . . . . . . . . . . . . . 6 1.2.2. HTTP/1.1 Using TLS 1.3 . . . . . . . . . . . . . . . 6
1.2.3. HTTP/2 . . . . . . . . . . . . . . . . . . . . . . . 6 1.2.3. HTTP/2 . . . . . . . . . . . . . . . . . . . . . . . 6
1.3. HTTP-Layer Certificate Authentication . . . . . . . . . . 7 1.3. HTTP-Layer Certificate Authentication . . . . . . . . . . 7
1.4. Terminology . . . . . . . . . . . . . . . . . . . . . . . 8 1.4. Terminology . . . . . . . . . . . . . . . . . . . . . . . 8
2. Discovering Additional Certificates at the HTTP/2 Layer . . . 8 2. Discovering Additional Certificates at the HTTP/2 Layer . . . 8
2.1. Indicating support for HTTP-layer certificate 2.1. Indicating Support for HTTP-Layer Certificate
authentication . . . . . . . . . . . . . . . . . . . . . 8 Authentication . . . . . . . . . . . . . . . . . . . . . 8
2.2. Making certificates or requests available . . . . . . . . 9 2.2. Making Certificates or Requests Available . . . . . . . . 9
2.3. Requiring certificate authentication . . . . . . . . . . 9 2.3. Requiring Certificate Authentication . . . . . . . . . . 10
2.3.1. Requiring additional server certificates . . . . . . 9 2.3.1. Requiring Additional Server Certificates . . . . . . 10
3. Certificates Frames for HTTP/2 . . . . . . . . . . . . . . . 11 2.3.2. Requiring Additional Client Certificates . . . . . . 11
3.1. The CERTIFICATE_NEEDED frame . . . . . . . . . . . . . . 11 3. Certificates Frames for HTTP/2 . . . . . . . . . . . . . . . 12
3.2. The USE_CERTIFICATE Frame . . . . . . . . . . . . . . . . 12 3.1. The CERTIFICATE_NEEDED Frame . . . . . . . . . . . . . . 12
3.3. The CERTIFICATE_REQUEST Frame . . . . . . . . . . . . . . 14 3.2. The USE_CERTIFICATE Frame . . . . . . . . . . . . . . . . 14
3.3.1. Exported Authenticator Request Characteristics . . . 15 3.3. The CERTIFICATE_REQUEST Frame . . . . . . . . . . . . . . 15
3.4. The CERTIFICATE Frame . . . . . . . . . . . . . . . . . . 15 3.3.1. Exported Authenticator Request Characteristics . . . 16
3.4.1. Exported Authenticator Characteristics . . . . . . . 16 3.4. The CERTIFICATE Frame . . . . . . . . . . . . . . . . . . 16
4. Indicating failures during HTTP-Layer Certificate 3.4.1. Exported Authenticator Characteristics . . . . . . . 17
Authentication . . . . . . . . . . . . . . . . . . . . . . . 16 4. Indicating Failures During HTTP-Layer Certificate
5. Security Considerations . . . . . . . . . . . . . . . . . . . 17 Authentication . . . . . . . . . . . . . . . . . . . . . . . 17
5.1. Impersonation . . . . . . . . . . . . . . . . . . . . . . 17 5. Security Considerations . . . . . . . . . . . . . . . . . . . 18
5.2. Fingerprinting . . . . . . . . . . . . . . . . . . . . . 18 5.1. Impersonation . . . . . . . . . . . . . . . . . . . . . . 18
5.3. Denial of Service . . . . . . . . . . . . . . . . . . . . 18 5.2. Fingerprinting . . . . . . . . . . . . . . . . . . . . . 19
5.4. Confusion About State . . . . . . . . . . . . . . . . . . 18 5.3. Denial of Service . . . . . . . . . . . . . . . . . . . . 19
6. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 19 5.4. Confusion About State . . . . . . . . . . . . . . . . . . 19
6.1. HTTP/2 SETTINGS_HTTP_CERT_AUTH Setting . . . . . . . . . 19 6. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 20
6.2. New HTTP/2 Frames . . . . . . . . . . . . . . . . . . . . 19 6.1. HTTP/2 SETTINGS_HTTP_CERT_AUTH Setting . . . . . . . . . 20
6.3. New HTTP/2 Error Codes . . . . . . . . . . . . . . . . . 20 6.2. New HTTP/2 Frames . . . . . . . . . . . . . . . . . . . . 20
7. References . . . . . . . . . . . . . . . . . . . . . . . . . 20 6.3. New HTTP/2 Error Codes . . . . . . . . . . . . . . . . . 21
7.1. Normative References . . . . . . . . . . . . . . . . . . 20 7. References . . . . . . . . . . . . . . . . . . . . . . . . . 21
7.2. Informative References . . . . . . . . . . . . . . . . . 21 7.1. Normative References . . . . . . . . . . . . . . . . . . 21
7.3. URIs . . . . . . . . . . . . . . . . . . . . . . . . . . 21 7.2. Informative References . . . . . . . . . . . . . . . . . 22
Appendix A. Change Log . . . . . . . . . . . . . . . . . . . . . 21 7.3. URIs . . . . . . . . . . . . . . . . . . . . . . . . . . 22
A.1. Since draft-ietf-httpbis-http2-secondary-certs-00: . . . 21 Appendix A. Change Log . . . . . . . . . . . . . . . . . . . . . 23
A.2. Since draft-bishop-httpbis-http2-additional-certs-05: . . 22 A.1. Since draft-ietf-httpbis-http2-secondary-certs-01: . . . 23
Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . . 22 A.2. Since draft-ietf-httpbis-http2-secondary-certs-00: . . . 23
Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 22 A.3. Since draft-bishop-httpbis-http2-additional-certs-05: . . 23
Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . . 23
Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 23
1. Introduction 1. Introduction
HTTP clients need to know that the content they receive on a HTTP clients need to know that the content they receive on a
connection comes from the origin that they intended to retrieve in connection comes from the origin that they intended to retrieve in
from. The traditional form of server authentication in HTTP has been from. The traditional form of server authentication in HTTP has been
in the form of a single X.509 certificate provided during the TLS in the form of a single X.509 certificate provided during the TLS
RFC5246 [I-D.ietf-tls-tls13] handshake. ([RFC5246], [I-D.ietf-tls-tls13]) handshake.
Many existing HTTP [RFC7230] servers also have authentication Many existing HTTP [RFC7230] servers also have authentication
requirements for the resources they serve. Of the bountiful requirements for the resources they serve. Of the bountiful
authentication options available for authenticating HTTP requests, authentication options available for authenticating HTTP requests,
client certificates present a unique challenge for resource-specific client certificates present a unique challenge for resource-specific
authentication requirements because of the interaction with the authentication requirements because of the interaction with the
underlying TLS layer. underlying TLS layer.
TLS 1.2 [RFC5246] supports one server and one client certificate on a TLS 1.2 [RFC5246] supports one server and one client certificate on a
connection. These certificates may contain multiple identities, but connection. These certificates may contain multiple identities, but
skipping to change at page 5, line 4 skipping to change at page 5, line 8
The TLS 1.3 CertificateRequest can be used by servers to give clients The TLS 1.3 CertificateRequest can be used by servers to give clients
hints about which certificate to offer. Servers that rely on hints about which certificate to offer. Servers that rely on
certificate-based authentication might request different certificates certificate-based authentication might request different certificates
for different resources. Such a server cannot use contextual for different resources. Such a server cannot use contextual
information about the resource to construct an appropriate TLS information about the resource to construct an appropriate TLS
CertificateRequest message during the initial handshake. CertificateRequest message during the initial handshake.
Consequently, client certificates are requested at connection Consequently, client certificates are requested at connection
establishment time only in cases where all clients are expected or establishment time only in cases where all clients are expected or
required to have a single certificate that is used for all resources. required to have a single certificate that is used for all resources.
Many other uses for client certificates are reactive, that is, Many other uses for client certificates are reactive, that is,
certificates are requested in response to the client making a certificates are requested in response to the client making a
request. request.
1.2.1. HTTP/1.1 using TLS 1.2 and previous 1.2.1. HTTP/1.1 Using TLS 1.2 and Earlier
In HTTP/1.1, a server that relies on client authentication for a 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 subset of users or resources does not request a certificate when the
connection is established. Instead, it only requests a client connection is established. Instead, it only requests a client
certificate when a request is made to a resource that requires a certificate when a request is made to a resource that requires a
certificate. TLS 1.2 [RFC5246] accomodates this by permitting the certificate. TLS 1.2 [RFC5246] accomodates this by permitting the
server to request a new TLS handshake, in which the server will server to request a new TLS handshake, in which the server will
request the client's certificate. request the client's certificate.
Figure 1 shows the server initiating a TLS-layer renegotiation in Figure 1 shows the server initiating a TLS-layer renegotiation in
skipping to change at page 5, line 33 skipping to change at page 5, line 36
-- (HTTP) GET /protected -------------------> *1 -- (HTTP) GET /protected -------------------> *1
<---------------------- (TLS) HelloRequest -- *2 <---------------------- (TLS) HelloRequest -- *2
-- (TLS) ClientHello -----------------------> -- (TLS) ClientHello ----------------------->
<------------------ (TLS) ServerHello, ... -- <------------------ (TLS) ServerHello, ... --
<---------------- (TLS) CertificateRequest -- *3 <---------------- (TLS) CertificateRequest -- *3
-- (TLS) ..., Certificate ------------------> *4 -- (TLS) ..., Certificate ------------------> *4
-- (TLS) Finished --------------------------> -- (TLS) Finished -------------------------->
<-------------------------- (TLS) Finished -- <-------------------------- (TLS) Finished --
<--------------------------- (HTTP) 200 OK -- *5 <--------------------------- (HTTP) 200 OK -- *5
Figure 1: HTTP/1.1 Reactive Certificate Authentication with TLS 1.2 Figure 1: HTTP/1.1 reactive certificate authentication with TLS 1.2
In this example, the server receives a request for a protected In this example, the server receives a request for a protected
resource (at *1 on Figure 1). Upon performing an authorization resource (at *1 on Figure 1). Upon performing an authorization
check, the server determines that the request requires authentication check, the server determines that the request requires authentication
using a client certificate and that no such certificate has been using a client certificate and that no such certificate has been
provided. provided.
The server initiates TLS renegotiation by sending a TLS HelloRequest The server initiates TLS renegotiation by sending a TLS HelloRequest
(at *2). The client then initiates a TLS handshake. Note that some (at *2). The client then initiates a TLS handshake. Note that some
TLS messages are elided from the figure for the sake of brevity. TLS messages are elided from the figure for the sake of brevity.
skipping to change at page 6, line 9 skipping to change at page 6, line 9
The critical messages for this example are the server requesting a The critical messages for this example are the server requesting a
certificate with a TLS CertificateRequest (*3); this request might certificate with a TLS CertificateRequest (*3); this request might
use information about the request or resource. The client then use information about the request or resource. The client then
provides a certificate and proof of possession of the private key in provides a certificate and proof of possession of the private key in
Certificate and CertificateVerify messages (*4). Certificate and CertificateVerify messages (*4).
When the handshake completes, the server performs any authorization When the handshake completes, the server performs any authorization
checks a second time. With the client certificate available, it then checks a second time. With the client certificate available, it then
authorizes the request and provides a response (*5). authorizes the request and provides a response (*5).
1.2.2. HTTP/1.1 using TLS 1.3 1.2.2. HTTP/1.1 Using TLS 1.3
TLS 1.3 [I-D.ietf-tls-tls13] introduces a new client authentication TLS 1.3 [I-D.ietf-tls-tls13] introduces a new client authentication
mechanism that allows for clients to authenticate after the handshake mechanism that allows for clients to authenticate after the handshake
has been completed. For the purposes of authenticating an HTTP has been completed. For the purposes of authenticating an HTTP
request, this is functionally equivalent to renegotiation. Figure 2 request, this is functionally equivalent to renegotiation. Figure 2
shows the simpler exchange this enables. shows the simpler exchange this enables.
Client Server Client Server
-- (HTTP) GET /protected -------------------> -- (HTTP) GET /protected ------------------->
<---------------- (TLS) CertificateRequest -- <---------------- (TLS) CertificateRequest --
-- (TLS) Certificate, CertificateVerify, -- (TLS) Certificate, CertificateVerify,
Finished -----------------------> Finished ----------------------->
<--------------------------- (HTTP) 200 OK -- <--------------------------- (HTTP) 200 OK --
Figure 2: HTTP/1.1 Reactive Certificate Authentication with TLS 1.3 Figure 2: HTTP/1.1 reactive certificate authentication with TLS 1.3
TLS 1.3 does not support renegotiation, instead supporting direct TLS 1.3 does not support renegotiation, instead supporting direct
client authentication. In contrast to the TLS 1.2 example, in TLS client authentication. In contrast to the TLS 1.2 example, in TLS
1.3, a server can simply request a certificate. 1.3, a server can simply request a certificate.
1.2.3. HTTP/2 1.2.3. HTTP/2
An important part of the HTTP/1.1 exchange is that the client is able 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. to easily identify the request that caused the TLS renegotiation.
The client is able to assume that the next unanswered request on the The client is able to assume that the next unanswered request on the
skipping to change at page 7, line 33 skipping to change at page 7, line 33
and other frames incorporate them to particular requests by reference and other frames incorporate them to particular requests by reference
as needed. as needed.
TLS Exported Authenticators are structured messages that can be TLS Exported Authenticators are structured messages that can be
exported by either party of a TLS connection and validated by the exported by either party of a TLS connection and validated by the
other party. Given an established TLS connection, a request can be other party. Given an established TLS connection, a request can be
constructed which describes the desired certificate and an constructed which describes the desired certificate and an
authenticator message can be constructed proving possession of a authenticator message can be constructed proving possession of a
certificate and a corresponding private key. Both requests and certificate and a corresponding private key. Both requests and
authenticators can be generated by either the client or the server. authenticators can be generated by either the client or the server.
Exported Authenticators use the message structures from sections Exported Authenticators use the message structures from Sections
4.3.2 and 4.4 of [I-D.ietf-tls-tls13], but different parameters. 4.3.2 and 4.4 of [I-D.ietf-tls-tls13], but different parameters.
Each Authenticator is computed using a Handshake Context and Finished Each Authenticator is computed using a Handshake Context and Finished
MAC Key derived from the TLS session. The Handshake Context is MAC Key derived from the TLS session. The Handshake Context is
identical for both parties of the TLS connection, while the Finished identical for both parties of the TLS connection, while the Finished
MAC Key is dependent on whether the Authenticator is created by the MAC Key is dependent on whether the Authenticator is created by the
client or the server. client or the server.
Successfully verified Authenticators result in certificate chains, Successfully verified Authenticators result in certificate chains,
with verified possession of the corresponding private key, which can with verified possession of the corresponding private key, which can
skipping to change at page 8, line 41 skipping to change at page 8, line 41
requests. The client responds with a "USE_CERTIFICATE" frame requests. The client responds with a "USE_CERTIFICATE" frame
indicating the certificate which should be used to satisfy the indicating the certificate which should be used to satisfy the
request. request.
Data sent by each peer is correlated by the ID given in each frame. Data sent by each peer is correlated by the ID given in each frame.
This ID is unrelated to values used by the other peer, even if each This ID is unrelated to values used by the other peer, even if each
uses the same ID in certain cases. "USE_CERTIFICATE" frames indicate uses the same ID in certain cases. "USE_CERTIFICATE" frames indicate
whether they are sent proactively or are in response to a whether they are sent proactively or are in response to a
"CERTIFICATE_NEEDED" frame. "CERTIFICATE_NEEDED" frame.
2.1. Indicating support for HTTP-layer certificate authentication 2.1. Indicating Support for HTTP-Layer Certificate Authentication
Clients and servers that will accept requests for HTTP-layer Clients and servers that will accept requests for HTTP-layer
certificate authentication indicate this using the HTTP/2 certificate authentication indicate this using the HTTP/2
"SETTINGS_HTTP_CERT_AUTH" (0xSETTING-TBD) setting. "SETTINGS_HTTP_CERT_AUTH" (0xSETTING-TBD) setting.
The initial value for the "SETTINGS_HTTP_CERT_AUTH" setting is 0, The initial value for the "SETTINGS_HTTP_CERT_AUTH" setting is 0,
indicating that the peer does not support HTTP-layer certificate indicating that the peer does not support HTTP-layer certificate
authentication. If a peer does support HTTP-layer certificate authentication. If a peer does support HTTP-layer certificate
authentication, the value is 1. authentication, the value is non-zero.
2.2. Making certificates or requests available In order to ensure that the TLS connection is direct to the server,
rather than via a TLS-terminating proxy, each side will separately
compute and confirm the value of this setting. The setting is
derived from a TLS exporter (see Section 7.5 of [I-D.ietf-tls-tls13]
and [RFC5705] for more details on exporters). Clients MUST NOT use
an early exporter during their 0-RTT flight, but MUST send an updated
SETTINGS frame using a regular exporter after the TLS handshake
completes.
The exporter is constructed with the following input:
o Label:
* "EXPORTER HTTP CERTIFICATE client" for clients
* "EXPORTER HTTP CERTIFICATE server" for servers
o Context: Empty
o Length: Four bytes
The resulting exporter is converted to a setting value as:
(Exporter & 0x3fffffff) | 0x80000000
That is, the most significant bit will always be set, regardless of
the value of the exporter. Each endpoint will compute the expected
value from their peer. If the setting is not received, or if the
value received is not the expected value, the frames defined in this
document SHOULD NOT be sent.
2.2. Making Certificates or Requests Available
When both peers have advertised support for HTTP-layer certificates When both peers have advertised support for HTTP-layer certificates
as in Section 2.1, either party can supply additional certificates as in Section 2.1, either party can supply additional certificates
into the connection at any time. This means that clients or servers into the connection at any time. This means that clients or servers
which predict a certificate will be required could supply the which predict a certificate will be required could supply the
certificate before being asked. These certificates are available for certificate before being asked. These certificates are available for
reference by future "USE_CERTIFICATE" frames. reference by future "USE_CERTIFICATE" frames.
Certificates supplied by servers can be considered by clients without Certificates supplied by servers can be considered by clients without
further action by the server. A server SHOULD NOT send certificates further action by the server. A server SHOULD NOT send certificates
which do not cover origins which it is prepared to service on the which do not cover origins which it is prepared to service on the
current connection, but MAY use the ORIGIN frame [RFC8336] to current connection, but MAY use the ORIGIN frame [RFC8336] to
indicate that not all covered origins will be served. indicate that not all covered origins will be served.
Client Server Client Server
<------------------ (stream 0) CERTIFICATE -- <------------------ (stream 0) CERTIFICATE --
... ...
-- (stream N) GET /from-new-origin ---------> -- (stream N) GET /from-new-origin --------->
<----------------------- (stream N) 200 OK -- <----------------------- (stream N) 200 OK --
Figure 3: Proactive Server Certificate Figure 3: Proactive server authentication
Client Server Client Server
-- (stream 0) CERTIFICATE ------------------> -- (stream 0) CERTIFICATE ------------------>
-- (stream 0) USE_CERTIFICATE (S=1) --------> -- (stream 0) USE_CERTIFICATE (S=1) -------->
-- (stream 0) USE_CERTIFICATE (S=3) --------> -- (stream 0) USE_CERTIFICATE (S=3) -------->
-- (streams 1,3) GET /protected ------------> -- (streams 1,3) GET /protected ------------>
<-------------------- (streams 1,3) 200 OK -- <-------------------- (streams 1,3) 200 OK --
Figure 4: Proactive Client Certificate Figure 4: Proactive client authentication
Likewise, either party can supply a "CERTIFICATE_REQUEST" that Likewise, either party can supply a "CERTIFICATE_REQUEST" that
outlines parameters of a certificate they might request in the outlines parameters of a certificate they might request in the
future. Upon receipt of a "CERTIFICATE_REQUEST", servers SHOULD future. Upon receipt of a "CERTIFICATE_REQUEST", endpoints SHOULD
provide a corresponding certificate. Clients MAY wait for a provide a corresponding certificate in anticipation of a request
"CERTIFICATE_NEEDED" frame to assist in associating the certificate shortly being blocked. Clients MAY wait for a "CERTIFICATE_NEEDED"
request with a particular HTTP transition. frame to assist in associating the certificate request with a
particular HTTP transaction.
2.3. Requiring certificate authentication 2.3. Requiring Certificate Authentication
2.3.1. Requiring additional server certificates 2.3.1. Requiring Additional Server Certificates
As defined in [RFC7540], when a client finds that a https:// origin As defined in [RFC7540], when a client finds that a https:// origin
(or Alternative Service [RFC7838]) to which it needs to make a (or Alternative Service [RFC7838]) to which it needs to make a
request has the same IP address as a server to which it is already request has the same IP address as a server to which it is already
connected, it MAY check whether the TLS certificate provided contains connected, it MAY check whether the TLS certificate provided contains
the new origin as well, and if so, reuse the connection. the new origin as well, and if so, reuse the connection.
If the TLS certificate does not contain the new origin, but the If the TLS certificate does not contain the new origin, but the
server has claimed support for that origin (with an ORIGIN frame, see server has claimed support for that origin (with an ORIGIN frame, see
[RFC8336]) and advertised support for HTTP-layer certificates (see [RFC8336]) and advertised support for HTTP-layer certificates (see
Section 2.1), the client MAY send a "CERTIFICATE_REQUEST" frame Section 2.1), the client MAY send a "CERTIFICATE_REQUEST" frame
describing the desired origin. Servers SHOULD provide a describing the desired origin. The client then sends a
corresponding certificate if one is available. "CERTIFICATE_NEEDED" frame for stream zero referencing the request,
indicating that the connection cannot be used for that origin until
the certificate is provided.
If the server does not have the desired certificate, it MUST [see If the server does not have the desired certificate, it MUST send an
issue #564]. In this case, or if the server has not advertised Empty Authenticator, as described in Section 5 of
support for HTTP-layer certificates, the client MUST NOT send any
requests for resources in that origin on the current connection. [I-D.ietf-tls-exported-authenticator], in a "CERTIFICATE" frame in
response to the request, followed by a "USE_CERTIFICATE" frame for
stream zero which references the Empty Authenticator. In this case,
or if the server has not advertised support for HTTP-layer
certificates, the client MUST NOT send any requests for resources in
that origin on the current connection.
Client Server Client Server
<----------------------- (stream 0) ORIGIN -- <----------------------- (stream 0) ORIGIN --
-- (stream 0) CERTIFICATE_REQUEST ----------> -- (stream 0) CERTIFICATE_REQUEST ---------->
-- (stream 0) CERTIFICATE_NEEDED (S=0) ----->
<------------------ (stream 0) CERTIFICATE -- <------------------ (stream 0) CERTIFICATE --
<-------- (stream 0) USE_CERTIFICATE (S=0) --
-- (stream N) GET /from-new-origin ---------> -- (stream N) GET /from-new-origin --------->
<----------------------- (stream N) 200 OK -- <----------------------- (stream N) 200 OK --
Figure 5: Client-Requested Certificate Figure 5: Client-requested certificate
If a client receives a "PUSH_PROMISE" referencing an origin for which
it has not yet received the server's certificate, this is a fatal
connection error (see section 8.2 of [RFC7540]). To avoid this,
servers MUST supply the associated certificates before pushing
resources from a different origin.
2.3.2. Requiring Additional Client Certificates
Likewise, the server sends a "CERTIFICATE_NEEDED" frame for each Likewise, the server sends a "CERTIFICATE_NEEDED" frame for each
stream where certificate authentication is required. The client stream where certificate authentication is required. The client
answers with a "USE_CERTIFICATE" frame indicating the certificate to answers with a "USE_CERTIFICATE" frame indicating the certificate to
use on that stream. If the request parameters or the responding use on that stream. If the request parameters or the responding
certificate are not already available, they will need to be sent as certificate are not already available, they will need to be sent as
described in Section 2.2 as part of this exchange. described in Section 2.2 as part of this exchange.
Client Server Client Server
<---------- (stream 0) CERTIFICATE_REQUEST -- <---------- (stream 0) CERTIFICATE_REQUEST --
... ...
-- (stream N) GET /protected ---------------> -- (stream N) GET /protected --------------->
<----- (stream 0) CERTIFICATE_NEEDED (S=N) -- <----- (stream 0) CERTIFICATE_NEEDED (S=N) --
-- (stream 0) CERTIFICATE ------------------> -- (stream 0) CERTIFICATE ------------------>
-- (stream 0) USE_CERTIFICATE (S=N) --------> -- (stream 0) USE_CERTIFICATE (S=N) -------->
<----------------------- (stream N) 200 OK -- <----------------------- (stream N) 200 OK --
Figure 6: Reactive Certificate Authentication Figure 6: Reactive certificate authentication
If a client receives a "PUSH_PROMISE" referencing an origin for which If the client does not have the desired certificate, it instead sends
it has not yet received the server's certificate, this is a fatal an Empty Authenticator, as described in Section 5 of
connection error (see section 8.2 of [RFC7540]). To avoid this, [I-D.ietf-tls-exported-authenticator], in a "CERTIFICATE" frame in
servers MUST supply the associated certificates before pushing response to the request, followed by a "USE_CERTIFICATE" frame which
resources from a different origin. references the Empty Authenticator. In this case, or if the client
has not advertised support for HTTP-layer certificates, the server
processes the request based solely on the certificate provided during
the TLS handshake, if any. This might result in an error response
via HTTP, such as a status code 403 (Not Authorized).
3. Certificates Frames for HTTP/2 3. Certificates Frames for HTTP/2
The "CERTIFICATE_REQUEST" and "CERTIFICATE_NEEDED" frames are The "CERTIFICATE_REQUEST" and "CERTIFICATE_NEEDED" frames are
correlated by their "Request-ID" field. Subsequent correlated by their "Request-ID" field. Subsequent
"CERTIFICATE_NEEDED" frames with the same "Request-ID" value MAY be "CERTIFICATE_NEEDED" frames with the same "Request-ID" value MAY be
sent for other streams where the sender is expecting a certificate sent for other streams where the sender is expecting a certificate
with the same parameters. with the same parameters.
The "CERTIFICATE", and "USE_CERTIFICATE" frames are correlated by The "CERTIFICATE", and "USE_CERTIFICATE" frames are correlated by
skipping to change at page 11, line 42 skipping to change at page 12, line 47
| NEEDED |---------->| USE | | NEEDED |---------->| USE |
+---------+ +---------+ +---------+ +---------+
Figure 7: Frame correlation Figure 7: Frame correlation
"Request-ID" and "Cert-ID" are independent and sender-local. The use "Request-ID" and "Cert-ID" are independent and sender-local. The use
of the same value by the other peer or in the other context does not of the same value by the other peer or in the other context does not
imply any correlation between these frames. These values MUST be imply any correlation between these frames. These values MUST be
unique per sender for each space over the lifetime of the connection. unique per sender for each space over the lifetime of the connection.
3.1. The CERTIFICATE_NEEDED frame 3.1. The CERTIFICATE_NEEDED Frame
The "CERTIFICATE_NEEDED" frame (0xFRAME-TBD1) is sent on stream zero The "CERTIFICATE_NEEDED" frame (0xFRAME-TBD1) is sent on stream zero
to indicate that the HTTP request on the indicated stream is blocked to indicate that the HTTP request on the indicated stream is blocked
pending certificate authentication. The frame includes stream ID and pending certificate authentication. The frame includes stream ID and
a request identifier which can be used to correlate the stream with a a request identifier which can be used to correlate the stream with a
previous "CERTIFICATE_REQUEST" frame sent on stream zero. The previous "CERTIFICATE_REQUEST" frame sent on stream zero. The
"CERTIFICATE_REQUEST" describes the certificate the sender requires "CERTIFICATE_REQUEST" describes the certificate the sender requires
to make progress on the stream in question. to make progress on the stream in question.
0 1 2 3 0 1 2 3
skipping to change at page 12, line 33 skipping to change at page 13, line 37
A server MAY send multiple "CERTIFICATE_NEEDED" frames for the same A server MAY send multiple "CERTIFICATE_NEEDED" frames for the same
stream. If a server requires that a client provide multiple stream. If a server requires that a client provide multiple
certificates before authorizing a single request, each required certificates before authorizing a single request, each required
certificate MUST be indicated with a separate "CERTIFICATE_NEEDED" certificate MUST be indicated with a separate "CERTIFICATE_NEEDED"
frame, each of which MUST have a different request identifier frame, each of which MUST have a different request identifier
(referencing different "CERTIFICATE_REQUEST" frames describing each (referencing different "CERTIFICATE_REQUEST" frames describing each
required certificate). To reduce the risk of client confusion, required certificate). To reduce the risk of client confusion,
servers SHOULD NOT have multiple outstanding "CERTIFICATE_NEEDED" servers SHOULD NOT have multiple outstanding "CERTIFICATE_NEEDED"
frames for the same stream at any given time. frames for the same stream at any given time.
Clients MUST NOT send multiple "CERTIFICATE_NEEDED" frames for the Clients MUST only send multiple "CERTIFICATE_NEEDED" frames for
same stream. stream zero. Multiple "CERTIFICATE_NEEDED" frames on any other
stream MUST be considered a stream error of type "PROTOCOL_ERROR".
The "CERTIFICATE_NEEDED" frame MUST NOT be sent to a peer which has The "CERTIFICATE_NEEDED" frame MUST NOT be sent to a peer which has
not advertised support for HTTP-layer certificate authentication. not advertised support for HTTP-layer certificate authentication.
The "CERTIFICATE_NEEDED" frame MUST NOT reference a stream in the The "CERTIFICATE_NEEDED" frame MUST NOT reference a stream in the
"half-closed (local)" or "closed" states [RFC7540]. A client that "half-closed (local)" or "closed" states [RFC7540]. A client that
receives a "CERTIFICATE_NEEDED" frame for a stream which is not in a receives a "CERTIFICATE_NEEDED" frame for a stream which is not in a
valid state SHOULD treat this as a stream error of type valid state SHOULD treat this as a stream error of type
"PROTOCOL_ERROR". "PROTOCOL_ERROR".
skipping to change at page 16, line 37 skipping to change at page 17, line 46
context" API, retrieve the "certificate_request_context" used to context" API, retrieve the "certificate_request_context" used to
generate the authenticator, if any. - Verify that the generate the authenticator, if any. - Verify that the
"certificate_request_context" is either empty (clients only) or "certificate_request_context" is either empty (clients only) or
contains the Request-ID of a previously-sent "CERTIFICATE_REQUEST" contains the Request-ID of a previously-sent "CERTIFICATE_REQUEST"
frame. - Use the "validate" API to confirm the validity of the frame. - Use the "validate" API to confirm the validity of the
authenticator with regard to the generated request (if any). authenticator with regard to the generated request (if any).
Once the authenticator is accepted, the endpoint can perform any Once the authenticator is accepted, the endpoint can perform any
other checks for the acceptability of the certificate itself. other checks for the acceptability of the certificate itself.
4. Indicating failures during HTTP-Layer Certificate Authentication 4. Indicating Failures During HTTP-Layer Certificate Authentication
Because this draft permits certificates to be exchanged at the HTTP Because this draft permits certificates to be exchanged at the HTTP
framing layer instead of the TLS layer, several certificate-related framing layer instead of the TLS layer, several certificate-related
errors which are defined at the TLS layer might now occur at the HTTP 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 framing layer. In this section, those errors are restated and added
to the HTTP/2 error code registry. to the HTTP/2 error code registry.
BAD_CERTIFICATE (0xERROR-TBD1): A certificate was corrupt, contained BAD_CERTIFICATE (0xERROR-TBD1): A certificate was corrupt, contained
signatures that did not verify correctly, etc. signatures that did not verify correctly, etc.
skipping to change at page 21, line 26 skipping to change at page 22, line 36
Transfer Protocol Version 2 (HTTP/2)", RFC 7540, Transfer Protocol Version 2 (HTTP/2)", RFC 7540,
DOI 10.17487/RFC7540, May 2015, DOI 10.17487/RFC7540, May 2015,
<https://www.rfc-editor.org/info/rfc7540>. <https://www.rfc-editor.org/info/rfc7540>.
[RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC
2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174,
May 2017, <https://www.rfc-editor.org/info/rfc8174>. May 2017, <https://www.rfc-editor.org/info/rfc8174>.
7.2. Informative References 7.2. Informative References
[RFC5705] Rescorla, E., "Keying Material Exporters for Transport
Layer Security (TLS)", RFC 5705, DOI 10.17487/RFC5705,
March 2010, <https://www.rfc-editor.org/info/rfc5705>.
[RFC7838] Nottingham, M., McManus, P., and J. Reschke, "HTTP [RFC7838] Nottingham, M., McManus, P., and J. Reschke, "HTTP
Alternative Services", RFC 7838, DOI 10.17487/RFC7838, Alternative Services", RFC 7838, DOI 10.17487/RFC7838,
April 2016, <https://www.rfc-editor.org/info/rfc7838>. April 2016, <https://www.rfc-editor.org/info/rfc7838>.
[RFC8336] Nottingham, M. and E. Nygren, "The ORIGIN HTTP/2 Frame", [RFC8336] Nottingham, M. and E. Nygren, "The ORIGIN HTTP/2 Frame",
RFC 8336, DOI 10.17487/RFC8336, March 2018, RFC 8336, DOI 10.17487/RFC8336, March 2018,
<https://www.rfc-editor.org/info/rfc8336>. <https://www.rfc-editor.org/info/rfc8336>.
7.3. URIs 7.3. URIs
skipping to change at page 21, line 47 skipping to change at page 23, line 12
[2] http://httpwg.github.io/ [2] http://httpwg.github.io/
[3] https://github.com/httpwg/http-extensions/labels/secondary-certs [3] https://github.com/httpwg/http-extensions/labels/secondary-certs
Appendix A. Change Log Appendix A. Change Log
*RFC Editor's Note:* Please remove this section prior to *RFC Editor's Note:* Please remove this section prior to
publication of a final version of this document. publication of a final version of this document.
A.1. Since draft-ietf-httpbis-http2-secondary-certs-00: A.1. Since draft-ietf-httpbis-http2-secondary-certs-01:
o Clients can send "CERTIFICATE_NEEDED" for stream 0 rather than
speculatively reserving a stream for an origin.
o Use SETTINGS to disable when a TLS-terminating proxy is present
(#617,#651)
A.2. Since draft-ietf-httpbis-http2-secondary-certs-00:
o All frames sent on stream zero; replaced "AUTOMATIC_USE" on o All frames sent on stream zero; replaced "AUTOMATIC_USE" on
"CERTIFICATE" with "UNSOLICITED" on "USE_CERTIFICATE". (#482,#566) "CERTIFICATE" with "UNSOLICITED" on "USE_CERTIFICATE". (#482,#566)
A.2. Since draft-bishop-httpbis-http2-additional-certs-05: o Use Exported Requests from the TLS Exported Authenticators draft;
eliminate facilities for expressing certificate requirements in
"CERTIFICATE_REQUEST" frame. (#481)
A.3. Since draft-bishop-httpbis-http2-additional-certs-05:
o Adopted as draft-ietf-httpbis-http2-secondary-certs o Adopted as draft-ietf-httpbis-http2-secondary-certs
Acknowledgements Acknowledgements
Eric Rescorla pointed out several failings in an earlier revision. Eric Rescorla pointed out several failings in an earlier revision.
Andrei Popov contributed to the TLS considerations. Andrei Popov contributed to the TLS considerations.
A substantial portion of Mike's work on this draft was supported by A substantial portion of Mike's work on this draft was supported by
Microsoft during his employment there. Microsoft during his employment there.
 End of changes. 34 change blocks. 
75 lines changed or deleted 146 lines changed or added

This html diff was produced by rfcdiff 1.47. The latest version is available from http://tools.ietf.org/tools/rfcdiff/