JEP 249: OCSP Stapling for TLS

OwnerJamil Nimeh
StatusClosed / Delivered
Componentsecurity-libs /
Discussionsecurity dash dev at openjdk dot java dot net
Reviewed byBrian Goetz, Sean Mullan
Endorsed byBrian Goetz
Created2014/06/09 07:30
Updated2023/12/12 21:24


Implement OCSP stapling via the TLS Certificate Status Request extension (section 8 of RFC 6066) and the Multiple Certificate Status Request Extension (RFC 6961).

Success Metrics

The implementation, for both client and server modes, must interoperate successfully with at least two third-party TLS implementations that support OCSP stapling.


Checking the revocation status of an X.509 certificate is a critical part of valid certificate-based authentication. However, certificate status checking using OCSP typically involves a network request for each certificate being checked. Because of the additional network requests, enabling OCSP checking for TLS on the client side can have a significant impact on performance.

OCSP stapling allows the presenter of a certificate, rather than the issuing Certificate Authority (CA), to bear the resource cost of providing OCSP responses. In a TLS context, it is the responsibility of the TLS server to request the OCSP response and send it to clients during the SSL/TLS handshake. This also allows the server to cache OCSP responses and supply them to all clients that are connecting to it. This significantly reduces the load on the OCSP responder since the response can be cached and periodically refreshed by the server rather than by each client.

Currently, certificate revocation-status checking can be enabled on the client side. This classical approach, however, faces several challenges:


If a client obtains the revocation status directly from the OCSP responder then, for each client making a connection to a specific server, the OCSP responder has to respond with a particular certificate status. For a high-traffic web site, the OCSP responder is likely to be the performance bottleneck. Also, revocation-status checking involves several round-trips. There is a significant performance impact if OCSP checking is enabled on the client side.


Adam Langley in one of his blogs talks about the security challenges that client applications face with traditional OCSP. He describes the "soft-fail" behavior implemented by most browsers, a policy where a failure to contact an OCSP responder does not result in a failed revocation check. This allows an attacker to cause the client to bypass revocation checking, either by intercepting or blocking the OCSP request from the client, or by mounting a denial-of-service attack against the responder itself.

OCSP stapling by itself does not totally mitigate this challenge, but it removes the need for OCSP checks between the client and the responder. The server must still be able to obtain its own OCSP response and place it in-band as part of the TLS handshake.

Currently in draft form in IETF is a proposal for a "must-staple" certificate extension which would require the attachment of an OCSP response during the TLS handshake. This would, essentially, override any soft-fail behavior that may be employed by a client. This proposed extension is beyond the scope of this JEP, but if this extension proceeds beyond a draft it could be a useful addition in the future.

Finally, Java clients may not have the same needs for soft-fail defaults that browsers do. In some cases clients may prefer a hard-fail approach, or opt to get user feedback through a dialog box in the event of a failure to receive an OCSP response. As examples, the default soft-fail approach for both the Java Plugin and Java Web Start is to display a warning dialog box when loading signed applets.

Potential privacy impairment of OCSP requests

In normal OCSP scenarios, when a client sends an OCSP request, it exposes both the server (via the server certificate entry) and itself (via the IP address at least) to the OCSP responder, and hence can disclose client behaviors. OCSP stapling addresses this issue since the client is no longer making the request to the OCSP responder.

Limitations of the "captive portal" technique

The "captive portal" technique forces an HTTP client on a network to download a special web page, usually for authentication purposes, before using the network normally. In such environments, clients are not able to check the OCSP status of the SSL/TLS certificate since all network access is blocked until authentication is successful.


The above issues can be partially mitigated by using CRLs, or better addressed via OCSP stapling.

In summary, OCSP stapling can help improve the performance of TLS by reducing the performance bottleneck of the OCSP responder. It can also prevent the potential privacy impairment of the OCSP request, and avoid the limitation of the "captive portal" technique.


This feature will be implemented in the SunJSSE provider implementation. Minor API changes are planned, with the goal to keep these changes as small as possible. The implementation will choose reasonable defaults for OCSP specific parameters, and will provide configuration of these defaults via the following system properties:

Client and server-side Java implementations will be capable of supporting the status_request and status_request_v2 TLS hello extensions. The status_request extension is described in RFC 6066. Supporting servers would include a single OCSP response for the certificate used to identify the server in a new TLS handshake message (CertificateStatus). The status_request_v2 extension is described in RFC 6961. The extension allows the client to request the server to provide a single OCSP response in the CertificateStatus message (similar to status_request) or request that the server fetch an OCSP response for each certificate in the list of certificates provided in the Certificate message (referenced below as the ocsp_multi type).

Client side

Server side

Stapling and X509ExtendedTrustManagers

Developers have some flexibility in terms of how to handle the responses provided through OCSP stapling. This JEP makes no changes to the current methodologies involved in certificate path checking and revocation checking. This means that it is possible to have both client and server assert the status_request extensions, obtain OCSP responses through the CertificateStatus message, and allow the user flexibility in how to react to revocation information, or the lack thereof.

As with previous JDK releases, if no PKIXBuilderParameters is provided by the caller, revocation checking is disabled. If the caller creates a PKIXBuilderParameters and uses the setRevocationEnabled method to enable revocation checking, then stapling OCSP responses will be evaluated. This is also the case if the property is set to true. The table below shows a few different approaches as examples (assume OCSP stapling is enabled both in the client and server):

PKIXBuilderParameters checkRevocation Property PKIXRevocationChecker Result
default default default Revocation checking is disabled
default true default Revocation checking enabled*, SOFT_FAIL set
instantiated default default Revocation checking enabled*, SOFT_FAIL set
instantiated default instantiated, added to PKIXBuilderParameters Revocation checking enabled*, hard fail behavior.

* Client-side OCSP fallback will occur only if the ocsp.enable Security property has been set to true

Further details about the configuration of the PKIXBuilderParameters and PKIXRevocationChecker objects and their relationship to JSSE can be found in both the Java PKI API Programmer's Guide and the JSSE Reference Guide.


  1. The OCSP Stapling implementation must not break backward compatibility.

  2. The client implementation must be able to send RFC 6066-style status_request ClientHello extensions to supporting servers. It must be able to properly parse the same hello extension in the ServerHello handshake message, and properly parse the subsequent CertificateStatus handshake-message contents.

  3. The client implementation must be able to send RFC 6961-style status_request_v2 ClientHello extensions to supporting servers. It must be able to assert ocsp or ocsp_multi types (or both) in the hello extension. It must be able to properly parse the same hello extensions in the ServerHello handshake message, and properly parse the subsequent CertificateStatus handshake-message contents.

  4. The server implementation must be able to receive status_request and status_request_v2 extensions in the ClientHello handshake message and query the appropriate OCSP responder. It must be able to place OCSP responses in a CertificateStatus TLS handshake message to be returned to the client.

  5. The server implementation must be capable of caching valid OCSP responses for reuse with clients that do not make requests with nonce extensions in their status_request[_v2] hello extensions.

  6. The client must be able to interoperate with at least two different web servers capable of performing OCSP stapling (e.g. Apache 2.4+).

  7. The server must be able to interoperate with at least two different client implementations capable of asserting status_request or status_request_v2. At this time, most major browsers (Firefox, Chrome, etc.) can generate the status_request hello extension, as can other tools such as OpenSSL's s_client. For automated testing purposes, small applications could be created that link against NSS and OpenSSL libraries to establish TLS connections with OCSP stapling.

Risks and Assumptions

The OCSP stapling feature will be enabled by default for java clients in JDK with this implementation. However, there are potential interoperability issues with TLS servers that cannot accept the status_request or status_request_v2 TLS extensions. A system or security property has been defined to disable OCSP stapling if necessary.