HTTP Working GroupM. Bishop
Intended status: Standards TrackN. Sullivan
Expires: November 29, 2018Cloudflare
M. Thomson
May 28, 2018

Secondary Certificate Authentication in HTTP/2


A use of TLS Exported Authenticators is described which enables HTTP/2 clients and servers to offer additional certificate-based credentials after the connection is established. The means by which these credentials are used with requests is defined.

Note to Readers



Status of this Memo




This Internet-Draft will expire on November 29, 2018.

Copyright Notice



1. Introduction

HTTP clients need to know that the content they receive on a connection comes from the origin that they intended to retrieve in from. The traditional form of server authentication in HTTP has been in the form of a single X.509 certificate provided during the TLS RFC5246 [I-D.ietf-tls-tls13] handshake.



Many HTTP servers host content from several origins. HTTP/2 permits clients to reuse an existing HTTP connection to a server provided that the secondary origin is also in the certificate provided during the TLS handshake. In many cases, servers choose to maintain separate certificates for different origins but still desire the benefits of a shared HTTP connection.

1.1. Server Certificate Authentication






1.2. Client Certificate Authentication




1.2.1. HTTP/1.1 using TLS 1.2 and previous



Client                                      Server

Figure 1: HTTP/1.1 Reactive Certificate Authentication with TLS 1.2





1.2.2. HTTP/1.1 using TLS 1.3


Client                                      Server
   -- (TLS) Certificate, CertificateVerify,

Figure 2: HTTP/1.1 Reactive Certificate Authentication with TLS 1.3


1.2.3. HTTP/2





1.3. HTTP-Layer Certificate Authentication


This could be done in a naive manner by replicating the TLS messages as HTTP/2 frames on each stream. However, this would create needless redundancy between streams and require frequent expensive signing operations. Instead, TLS Exported Authenticators [I-D.ietf-tls-exported-authenticator] are exchanged on stream zero and other frames incorporate them to particular requests by reference as needed.

TLS Exported Authenticators are structured messages that can be exported by either party of a TLS connection and validated by the other party. Given an established TLS connection, a request can be constructed which describes the desired certificate and an authenticator message can be constructed proving possession of a certificate and a corresponding private key. Both requests and authenticators can be generated by either the client or the server. Exported Authenticators use the message structures from sections 4.3.2 and 4.4 of [I-D.ietf-tls-tls13], but different parameters.




1.4. Terminology


2. Discovering Additional Certificates at the HTTP/2 Layer

A certificate chain with proof of possession of the private key corresponding to the end-entity certificate is sent as a sequence of CERTIFICATE frames (see Section 3.4) on stream zero. Once the holder of a certificate has sent the chain and proof, this certificate chain is cached by the recipient and available for future use. Clients can proactively indicate the certificate they intend to use on each request using an unsolicited USE_CERTIFICATE frame, if desired. The previously-supplied certificates are available for reference without having to resend them.

Otherwise, the server uses a CERTIFICATE_REQUEST frame to describe a class of certificates on stream zero, then uses CERTIFICATE_NEEDED frames to associate these with individual requests. The client responds with a USE_CERTIFICATE frame indicating the certificate which should be used to satisfy the request.

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 uses the same ID in certain cases. USE_CERTIFICATE frames indicate whether they are sent proactively or are in response to a CERTIFICATE_NEEDED frame.

2.1. Indicating support for HTTP-layer certificate authentication



2.2. Making certificates or requests available

When both peers have advertised support for HTTP-layer certificates as in Section 2.1, either party can supply additional certificates into the connection at any time. This means that clients or servers which predict a certificate will be required could supply the certificate before being asked. These certificates are available for reference by future USE_CERTIFICATE frames.

Certificates supplied by servers can be considered by clients without further action by the server. A server SHOULD NOT send certificates which do not cover origins which it is prepared to service on the current connection, but MAY use the ORIGIN frame [RFC8336] to indicate that not all covered origins will be served.

Client                                      Server

Figure 3: Proactive Server Certificate

Client                                      Server
   -- (stream 0) USE_CERTIFICATE (S=1) -------->
   -- (stream 0) USE_CERTIFICATE (S=3) -------->

Figure 4: Proactive Client Certificate

Likewise, either party can supply a CERTIFICATE_REQUEST that outlines parameters of a certificate they might request in the future. Upon receipt of a CERTIFICATE_REQUEST, servers SHOULD provide a corresponding certificate. Clients MAY wait for a CERTIFICATE_NEEDED frame to assist in associating the certificate request with a particular HTTP transition.

2.3. Requiring certificate authentication

2.3.1. Requiring additional server certificates


If the TLS certificate does not contain the new origin, but the server has claimed support for that origin (with an ORIGIN frame, see [RFC8336]) and advertised support for HTTP-layer certificates (see Section 2.1), the client MAY send a CERTIFICATE_REQUEST frame describing the desired origin. Servers SHOULD provide a corresponding certificate if one is available.

If the server does not have the desired certificate, it MUST [see issue #564]. 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

Figure 5: Client-Requested Certificate

Likewise, the server sends a CERTIFICATE_NEEDED frame for each stream where certificate authentication is required. The client answers with a USE_CERTIFICATE frame indicating the certificate to use on that stream. If the request parameters or the responding certificate are not already available, they will need to be sent as described in Section 2.2 as part of this exchange.

Client                                      Server
   <----- (stream 0) CERTIFICATE_NEEDED (S=N) --
   -- (stream 0) USE_CERTIFICATE (S=N) -------->

Figure 6: Reactive Certificate Authentication

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.

3. Certificates Frames for HTTP/2

The CERTIFICATE_REQUEST and CERTIFICATE_NEEDED frames are correlated by their Request-ID field. Subsequent CERTIFICATE_NEEDED frames with the same Request-ID value MAY be sent for other streams where the sender is expecting a certificate with the same parameters.


CERTIFICATE_NEEDED and USE_CERTIFICATE frames are correlated by the Stream ID they reference. Unsolicited USE_CERTIFICATE frames are not responses to CERTIFICATE_NEEDED frames; otherwise, each USE_CERTIFICATE frame for a stream is considered to respond to a CERTIFICATE_NEEDED frame for the same stream in sequence.

   | REQUEST |           |   CERT  |
        |                     |
        | Request-ID          | Cert-ID
        |                     |
        v                     v
   +---------+ Stream ID +---------+
   | NEEDED  |---------->|   USE   |

Figure 7: Frame correlation

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 imply any correlation between these frames. These values MUST be unique per sender for each space over the lifetime of the connection.


The CERTIFICATE_NEEDED frame (0xFRAME-TBD1) is sent on stream zero to indicate that the HTTP request on the indicated stream is blocked pending certificate authentication. The frame includes stream ID and a request identifier which can be used to correlate the stream with a previous CERTIFICATE_REQUEST frame sent on stream zero. The CERTIFICATE_REQUEST describes the certificate the sender requires to make progress on the stream in question.

  0                   1                   2                   3
 |R|                        Stream ID (31)                       |
 |        Request-ID (16)        |

Figure 8: CERTIFICATE_NEEDED frame payload

The CERTIFICATE_NEEDED frame contains 6 octets. The first four octets indicate the Stream ID of the affected stream. The following two octets are the authentication request identifier, Request-ID. A peer that receives a CERTIFICATE_NEEDED 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.

A server MAY send multiple CERTIFICATE_NEEDED frames for the same stream. If a server requires that a client provide multiple certificates before authorizing a single request, each required certificate MUST be indicated with a separate CERTIFICATE_NEEDED frame, each of which MUST have a different request identifier (referencing different CERTIFICATE_REQUEST frames describing each required certificate). To reduce the risk of client confusion, servers SHOULD NOT have multiple outstanding CERTIFICATE_NEEDED frames for the same stream at any given time.

Clients MUST NOT send multiple CERTIFICATE_NEEDED frames for the same stream.


The CERTIFICATE_NEEDED frame MUST NOT reference a stream in the “half-closed (local)” or “closed” states [RFC7540]. A client that receives a CERTIFICATE_NEEDED frame for a stream which is not in a valid state SHOULD treat this as a stream error of type PROTOCOL_ERROR.


The USE_CERTIFICATE frame (0xFRAME-TBD4) is sent on stream zero to indicate which certificate is being used on a particular request stream.

The USE_CERTIFICATE frame defines a single flag:

Indicates that no CERTIFICATE_NEEDED frame has yet been received for this stream.

The payload of the USE_CERTIFICATE frame is as follows:

  0                   1                   2                   3
 |R|                        Stream ID (31)                       |
 |         [Cert-ID (16)]        |

Figure 9: USE_CERTIFICATE frame payload

The first four octets indicate the Stream ID of the affected stream. The following two octets, if present, contain the two-octet Cert-ID of the certificate the sender wishes to use. This MUST be the ID of a certificate for which proof of possession has been presented in a CERTIFICATE frame. Recipients of a USE_CERTIFICATE frame of any other length MUST treat this as a stream error of type PROTOCOL_ERROR. Frames with identical certificate identifiers refer to the same certificate chain.


The UNSOLICITED flag MAY be set by clients on the first USE_CERTIFICATE frame referring to a given stream. This permits a client to proactively indicate which certificate should be used when processing a new request. When such an unsolicited indication refers to a request that has not yet been received, servers SHOULD cache the indication briefly in anticipation of the request.

Receipt of more than one unsolicited USE_CERTIFICATE frames or an unsolicited USE_CERTIFICATE frame which is not the first in reference to a given stream MUST be treated as a stream error of type CERTIFICATE_OVERUSED.

Each USE_CERTIFICATE frame which is not marked as unsolicited is considered to respond in order to the CERTIFICATE_NEEDED frames for the same stream. If a USE_CERTIFICATE frame is received for which a CERTIFICATE_NEEDED frame has not been sent, this MUST be treated as a stream error of type CERTIFICATE_OVERUSED.

Receipt of a USE_CERTIFICATE frame with an unknown Cert-ID MUST result in a stream error of type PROTOCOL_ERROR.

The referenced certificate chain needs to conform to the requirements expressed in the CERTIFICATE_REQUEST to the best of the sender’s ability, or the recipient is likely to reject it as unsuitable despite properly validating the authenticator. If the recipient considers the certificate unsuitable, it MAY at its discretion either return an error at the HTTP semantic layer, or respond with a stream error [RFC7540] on any stream where the certificate is used. Section 4 defines certificate-related error codes which might be applicable.


The CERTIFICATE_REQUEST frame (id=0xFRAME-TBD2) provides a exported authenticator request message from the TLS layer that specifies a desired certificate. This describes the certificate the sender wishes to have presented.



  0                   1                   2                   3
 |        Request-ID (16)        |          Request (?)        ...

Figure 10: CERTIFICATE_REQUEST frame payload

The frame contains the following fields:

An exported authenticator request, generated using the request API described in [I-D.ietf-tls-exported-authenticator]. See Section 3.4.1 for more details on the input to this API.

3.3.1. Exported Authenticator Request Characteristics

The Exported Authenticator request API defined in [I-D.ietf-tls-exported-authenticator] takes as input a set of desired certificate characteristics and a certificate_request_context, which needs to be unpredictable. When generating exported authenticators for use with this extension, the certificate_request_context MUST contain both the two-octet Request-ID as well as at least 96 bits of additional entropy.

The TLS library on the authenticating peer will provide mechanisms to select an appropriate certificate to respond to the transported request. TLS libraries on servers MUST be able to recognize the server_name extension ([RFC6066]) at a minimum. Clients MUST always specify the desired origin using this extension, though other extensions MAY also be included.

3.4. The CERTIFICATE Frame


The CERTIFICATE frame defines two flags:

Indicates that the exported authenticator spans more than one frame.
  0                   1                   2                   3

Figure 11: CERTIFICATE frame payload





3.4.1. Exported Authenticator Characteristics

The Exported Authenticator API defined in [I-D.ietf-tls-exported-authenticator] takes as input a request, a set of certificates, and supporting information about the certificate (OCSP, SCT, etc.). The result is an opaque token which is used when generating the CERTIFICATE frame.

Upon receipt of a CERTIFICATE frame, an endpoint MUST perform the following steps to validate the token it contains: - Using the get context API, retrieve the certificate_request_context used to generate the authenticator, if any. - Verify that the certificate_request_context is either empty (clients only) or contains the Request-ID of a previously-sent CERTIFICATE_REQUEST frame. - Use the validate API to confirm the validity of the authenticator with regard to the generated request (if any).


4. Indicating failures during HTTP-Layer Certificate Authentication


A certificate was revoked by its signer
A certificate has expired or is not currently valid
Any other certificate-related error
More certificates were used on a request than were requested


5. Security Considerations


5.1. Impersonation



5.2. Fingerprinting



5.3. Denial of Service



5.4. Confusion About State



6. IANA Considerations

This draft adds entries in three registries.




Initial Value:
This document.

6.2. New HTTP/2 Frames


Frame TypeCodeSpecification

6.3. New HTTP/2 Error Codes



7. References

7.1. Normative References

Sullivan, N., “Exported Authenticators in TLS”, Internet-Draft draft-ietf-tls-exported-authenticator-06 (work in progress), March 2018.

7.2. Informative References

Nottingham, M. and E. Nygren, “The ORIGIN HTTP/2 Frame”, RFC 8336, DOI 10.17487/RFC8336, March 2018, <>.

Appendix A. Change Log

A.1. Since draft-ietf-httpbis-http2-secondary-certs-00: 📄 🔍

  • All frames sent on stream zero; replaced AUTOMATIC_USE on CERTIFICATE with UNSOLICITED on USE_CERTIFICATE. (#482,#566)

A.2. Since draft-bishop-httpbis-http2-additional-certs-05: 📄

  • Adopted as draft-ietf-httpbis-http2-secondary-certs




Authors' Addresses

Mike Bishop
Nick Sullivan
Martin Thomson