Description

Summary

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.

Motivation

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:

Performance

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.

Security

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.

Summary

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.

Description

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.

Testing

The OCSP Stapling implementation must not break backward
compatibility.

The client implementation must be able to send RFC 6066-style
status_requestClientHello 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.

The client implementation must be able to send RFC 6961-style
status_request_v2ClientHello 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.

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.

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.

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

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

relates to

JDK-8132943ServerHandshaker may select non-empty OCSPStatusRequest structures when Responder ID selection is not supported

JDK-8132942ServerHandshaker should not throw SSLHandshakeException when CertificateStatus constructor is called with invalid arguments

JDK-8138704CertStatusReqItemV2 should not implement StatusRequest interface

JDK-8145854SSLContextImpl.statusResponseManager should be generated if required