Uploaded image for project: 'JDK'
  1. JDK
  2. JDK-8046321

JEP 249: OCSP Stapling for TLS



    • Feature
    • Open
    • SE
    • security dash dev at openjdk dot java dot net
    • M
    • M
    • 249



      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:

      • jdk.tls.client.enableStatusRequestExtension: This property is true by default. This enables the status_request and status_request_v2 extensions, and enables processing for CertificateStatus messages sent by the server.
      • jdk.tls.server.enableStatusRequestExtension: This property is false by default. This enables the server-side support for OCSP stapling.
      • jdk.tls.stapling.responseTimeout: This property controls the maximum amount of time the server will use to obtain OCSP responses, whether from the cache or by contacting an OCSP responder. Those responses that have been received will be sent in a CertificateStatus message, if applicable based on the type of stapling being done. This property takes an integer value in milliseconds, with a default value of 5000.
      • jdk.tls.stapling.cacheSize: This property controls the maximum cache size in entries. The default value is 256 objects. If the cache is full and a new response needs to be cached, the least-recently-used cache entry will be replaced with the new one. A value of zero or less for this property means that the cache will have no upper bound on the number of responses it may contain.
      • jdk.tls.stapling.cacheLifetime: This property controls the maximum life of a cached response. The value is specified in seconds, and has a default value of 3600 (1 hour). It is possible for responses to have shorter lifetimes than the value set with this property if the response has a nextUpdate field that expires sooner than the cache lifetime. A value of zero or less for this property disables the cache lifetime. If an object has no nextUpdate and cache lifetimes have been disabled, then the response will not be cached.
      • jdk.tls.stapling.responderURI: This property allows the administrator to set a default URI in the event that certificates used for TLS do not have the Authority Info Access extension. It will not override the AIA extension value unless the jdk.tls.stapling.responderOverride property is set (see below). This property is not set by default.
      • jdk.tls.stapling.responderOverride: This property allows a URI provided through the jdk.tls.stapling.responderURI property to override any AIA extension value. It is false by default.
      • jdk.tls.stapling.ignoreExtensions: This property disables the forwarding of OCSP extensions specified in the status_request or status_request_v2 TLS extensions. It is false by default.

      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

      • OCSP Stapling will be enabled by default and can be disabled by setting a system property. This may be done through the jdk.tls.client.enableStatusRequestExtension property.

      • Clients will, by default, assert both the status_request and status_request_v2 extensions in the ClientHello handshake message. For the status_request_v2 extension, both ocsp and ocsp_multi types will be asserted.

      • Creation of the hello extensions will require the creation of new classes in sun.security.ssl, similar to how ServerNameIndicator, RenegotiationInfoExtension, and other extensions were implemented.

      • In order to employ the new extensions the ClientHello class will have additional methods defined that add these extensions. These methods will be invoked from ClientHandshaker.clientHello().

      • A new handshake message class in the HandshakeMessage class will need to be created to handle encoding and parsing of the CertificateStatus message.

      • A public API change is necessary in ExtendedSSLSession which allows callers to obtain the OCSP responses received during the handshake process. The new method is:

        public List getStatusResponses();

      Server side

      • The server-side implementation will have OCSP stapling disabled by default, but may be enabled through the jdk.tls.server.enableStatusRequestExtension system property. Servers with OCSP stapling support disabled will ignore the status_request and status_request_v2 extensions.

      • Server-side population of either status_request or status_request_v2 information in the ServerHello message will depend upon how the client asserted these extensions. In general the same request extension in the ClientHello will be returned in the ServerHello, with the following exceptions:

        • Servers receiving both status_request and status_request_v2 extensions in the ClientHello will assert status_request_v2 in the ServerHello.

        • Servers receiving status_request_v2 extensions in the ClientHello with both ocsp and ocsp_multi types will assert status_request_v2 in the ServerHello mesage and ocsp_multi in the CertificateStatus message.

        • In the case where status_request_v2/ocsp_multi is selected, different threads will be used to fetch each response. This will be managed by a StatusResponseManager which will handle both fetching and caching of OCSP responses.

      • OCSP responses should be cached whenever possible. Clients that do not specify nonces in their status_request[_v2] extension may receive a cached response.

        • Cached responses should not be used if current time is later than the nextUpdate field.

        • Cached responses with no nextUpdate field may be kept in the cache for a pre-determined lifetime (see Tunables below).

        • Servers receiving status_requests with the nonce extension must not return cached responses in the CertificateStatus message.

      • Server-side stapling support will be tunable via the system properties described above.

      • The StatusResponseManager is created as part of SSLContext instantiation. The property values are sampled during SSLContext construction. These property values can be changed and when a new SSLContext object is created, the StatusResponseManager will have those new values.

      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 com.sun.net.ssl.checkRevocation 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.


        Issue Links



              jnimeh Jamil Nimeh
              jnimeh Jamil Nimeh
              Jamil Nimeh Jamil Nimeh
              Brian Goetz, Sean Mullan
              Brian Goetz
              0 Vote for this issue
              12 Start watching this issue