Documentation Contents

Client-Driven OCSP and OCSP Stapling

The following topics are covered:

• Introduction
• Client-Driven OCSP and Certificate Revocation
  • TLS Handshake with Client-Driven OCSP
  • Setting up a Java Client to use Client-Driven OCSP
• OCSP Stapling and Certificate Revocation
  • TLS Handshake with OCSP Stapling
  • Status Request Versus Multiple Status Request
  • The OCSP Request and Response
  • Setting up a Java Client to use OCSP Stapling
  • Setting Up a Java Server to Use OCSP Stapling
• OCSP Stapling Configuration Properties
  • Server-Side Properties
  • Client-Side Settings
• OCSP Support for PKI
  • Maximum Allowable Clock Skew

Introduction

Use the Online Certificate Status Protocol (OCSP), available since JDK 8u261, to determine the X.509 certificate revocation status during the Transport Layer Security (TLS) handshake.

X.509 certificates used in TLS can be revoked by the issuing Certificate Authority (CA) if there is reason to believe that a certificate is compromised. You can check the revocation status of certificates during the TLS handshake by using one of the following approaches.

• Certificate Revocation List (CRL): A CRL is a simple list of revoked certificates. The application receiving a certificate gets the CRL from a CRL server and checks if the certificate received is on the list. There are two disadvantages to using CRLs that mean a certificate could be revoked:

  • CRLs can become very large so there can be a substantial increase in network traffic.

  • Many CRLs are created with longer validity periods, which increases the possibility of a certificate being revoked within that validity period and not showing up until the next CRL refresh.

  See Certificate/CRL Storage Classes in Java PKI Programmer's Guide.

• Client-driven OCSP: In client-driven OCSP, the client uses OCSP to contact an OCSP responder to check the certificate's revocation status. The amount of data required is usually less than that of a CRL, and the OCSP responder is likely to be more up-to-date with the revocation status than a CRL. Each client connecting to a server requires an OCSP response for each certificate being checked. If the server is a popular one, and many of the clients are using client-driven OCSP, these OCSP requests can have a negative effect on the performance of the OCSP responder.

• OCSP stapling: OCSP stapling enables the server, rather than the client, to make the request to the OCSP responder. The server staples the OCSP response to the certificate and returns it to the client during the TLS handshake. This approach enables the presenter of the certificate, rather than the issuing CA, to bear the resource cost of providing OCSP responses. It also enables the server to cache the OCSP responses and supply them to all clients. This significantly reduces the load on the OCSP responder because the response can be cached and periodically refreshed by the server rather than by each client.

Client-Driven OCSP and Certificate Revocation

Client-driven Online Certificate Status Protocol (OCSP) enables the client to check the certificate revocation status by connecting to an OCSP responder during the Transport Layer Security (TLS) handshake.

The client-driven OCSP request occurs during the TLS handshake just after the client receives the certificate from the server and validates it.

TLS Handshake with Client-Driven OCSP

Client-driven OCSP is used during the TLS handshake between the client and the server to check the server certificate revocation status. After the client receives the certificate, it performs certificate validation. If the validation is successful, then the client verifies that the certificate was not revoked by the issuer. This is done by sending an OCSP request to an OCSP responder. After receiving the OCSP response, the client checks this response before completing the TLS handshake.

The following figure illustrates how client-driven OCSP fits into the TLS handshake:

TLS Handshake with Client-Driven OCSP

This figure illustrates the following sequence:

1. The client sends a ClientHello message to the server.

2. The server receives this message and processes it.

3. The server sends a ServerHello message, followed by additional ServerHello messages, followed by a ServerHello done message to the client.

4. The client validates the server certificate. The client sends an OCSP request to the OCSP responder for this certificate.

5. The OCSP responder receives the request, then returns an OCSP response to the client.

6. The client checks the OCSP response to determine if the certificate has been revoked.

7. The client and server complete the TLS handshake (this takes multiple additional messages).

Usually the client finds the OCSP responder's URL by looking in the Authority Information Access (AIA) extension of the certificate, but it can be set to a static URL through the use of a system property.

Setting up a Java Client to use Client-Driven OCSP

Client-driven OCSP is enabled by enabling revocation checking and enabling OCSP.

To configure a Java client to use client-driven OCSP, the Java client must already be set up to connect to a server using TLS.

1. Enable revocation checking. You can do this in two different ways.
   • Set the system property com.sun.net.ssl.checkRevocation to true.
   • Use the setRevocationEnabled method on PKIXParameters.
2. Enable client-driven OCSP:

   Set the Security Property ocsp.enable to true.

Both steps are necessary. The ocsp.enable setting has no effect unless revocation checking is enabled.

OCSP Stapling and Certificate Revocation

Online Certificate Status Protocol (OCSP) stapling enables the presenter of a certificate, rather than the issuing Certificate Authority (CA), to bear the resource cost of providing the OCSP responses that contain the certificate's revocation status.

TLS Handshake with OCSP Stapling

OCSP stapling is used during the Transport Layer Security (TLS) handshake between the client and the server to check the server certificate revocation status. The server makes the OCSP request to the OCSP responder and staples the OCSP responses to the certificates returned to the client. By having the server make the request to the OCSP responder, the responses can be cached, and then used multiple times for many clients.

The TLS handshake begins with the TLS ClientHello message. When OCSP stapling is used, this message is sent to the server with the status_request extension that indicates that the server should perform an OCSP request. After processing the ClientHello message, the server sends an OCSP request to the appropriate OCSP responder for each certificate. When the server receives the OCSP responses from the OCSP responders, it sends a ServerHello message with its status_request extension, indicating that OCSP responses will be provided in the TLS handshake. The server will then present the server certificate chain, followed by a message that consists of one or more OCSP responses for those certificates. The client receiving the certificates with stapled OCSP responses validates each certificate, and then checks the OCSP responses before continuing with the handshake.

If, from the client's perspective, the stapled OCSP response from the server for a certificate is missing, the client will attempt to use client-driven OCSP or Certificate Revocation Lists (CRLs) to get revocation information if the following are true:

• The RevocationEnabled flag is set to true through the PKIXParameters.setRecovcationEnabled method.

• OCSP checking is enabled by setting the ocsp.enable Security Property to true.

The following figure illustrates how client-driven OCSP fits into the TLS handshake:

TLS Handshake with OCSP Stapling

This figure illustrates the following sequence:

1. The client sends a ClientHello message with a status request extension to the server.

2. The server receives this message and processes it.

3. The server sends an OCSP request to the OCSP responder for this certificate.

4. The OCSP responder receives the request, then returns an OCSP response to the server.

5. The server sends a ServerHello message with a status request extension to the client.

6. The server sends a certificate message to the client.

7. The server sends a certificate status message to the client.

8. The server sends additional ServerHello messages, followed by a ServerHello done messages to the client.

9. The client validates the server certificate

10. The client checks the OCSP response in the certificate status message to determine if the certificate has been revoked.

11. The client and server complete the TLS handshake (this takes multiple additional messages).

OCSP checking works in conjunction with CRLs during revocation checking. See OCSP Support for PKI.

Status Request Versus Multiple Status Request

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

The TLS Certificate Status Request extension requests revocation information for only the server certificate in the certificate chain while the Multiple Certificate Status Request Extension requests revocation information for all certificates in the certificate chain. In the case where only the server certificate's revocation information is sent to the client, other certificates in the chain may be verified using the Certificate Revocation Lists (CRLs) or client-driven OCSP (but the client will need to be set up to do this).

Although TLS allows the server to also request the client's certificate, there is no provision in OCSP stapling that enables the client to contact the appropriate OCSP responder and staple the response to the certificate sent to the server.

The OCSP Request and Response

OCSP request and response messages are usually sent over unencrypted HTTP. The response is signed by the CA.

If necessary, the stapled responses can be obtained in the client code by calling the getStatusResponses method on the ExtendedSSLSession object. The method signature is:

public List<byte[]> getStatusResponses();

The OCSP response is encoded using the Distinguished Encoding Rules (DER) in a format described by the ASN.1 found in RFC 6960.

Setting up a Java Client to Use OCSP Stapling

Online Certificate Status Protocol (OCSP) stapling is enabled on the client side by setting the system property jdk.tls.client.enableStatusRequestExtension to false (its default value).

To configure a Java client to make use of the OCSP response stapled to the certificate returned by a server, the Java client must already be set up to connect to a server using TLS, and the server must be set up to staple an OCSP response to the certificate it returns part of the TLS handshake.

1. Enable OCSP stapling on the client:

   If necessary, set the system property jdk.tls.client.enableStatusRequestExtension to true.

2. Enable revocation checking. You can do this in two different ways.
   • Set the system property com.sun.net.ssl.checkRevocation to true. You can do this from the command line or in the code.
   • Use the setRevocationEnabled method on the PKIXParameters class.

   For the client to include the stapled responses received from the server in the certificate validation, revocation checking must be set to true. If revocation checking is not set to true, then the connection will be allowed to proceed regardless of the presence or status of the revocation information

Setting Up a Java Server to Use OCSP Stapling

Online Certificate Status Protocol (OCSP) stapling is enabled on the server by setting the system property jdk.tls.server.enableStatusRequestExtension to true. (It is set to false by default.)

The following steps can be used to configure a Java server to connect to an OCSP responder and staple the OCSP response to the certificate to be returned to the client. The Java server must already be set up to respond to clients using TLS.

1. Enable OCSP stapling on the server:

   Set the system property jdk.tls.server.enableStatusRequestExtension to true.

2. Optional: Set other properties as required. See the next section, "OCSP Stapling Configuration Properties," for a list of the valid properties.

OCSP Stapling Configuration Properties

This topic lists the effects of setting various properties when using the Online Certificate Status Protocol (OCSP). It shows the properties used in both client-driven OCSP and OCSP stapling.

Server-Side Properties

Most of the properties are read at SSLContext instantiation time. This means that if you set a property, you must obtain a new SSLContext object so that an SSLSocket or SSLEngine object you obtain from that SSLContext object will reflect the property setting. The one exception is the jdk.tls.stapling.responseTimeout property. That property is evaluated when the ServerHandshaker object is created (essentially at the same time that an SSLSocket or SSLEngine object gets created).

Client-Side Settings

¹Note that client-side OCSP fallback will occur only if the ocsp.enable Security Property is set to true.

Developers have some flexibility in how to handle the responses provided through OCSP stapling. OCSP stapling 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 provide user flexibility in how to react to revocation information, or the lack thereof.

If no PKIXBuilderParameters is provided by the caller, then revocation checking is disabled. If the caller creates a PKIXBuilderParameters object and uses the setRevocationEnabled method to enable revocation checking, then stapled OCSP responses will be evaluated. This is also the case if the com.sun.net.ssl.checkRevocation property is set to true.

OCSP Support for PKI

Client-side support for the On-Line Certificate Status Protocol (OCSP) as defined in RFC 2560 is supported.

ocsp.responderURL=http://ocsp.example.net:80

ocsp.responderCertSubjectName="CN=OCSP Responder, O=XYZ Corp"

ocsp.responderCertIssuerName="CN=Enterprise CA, O=XYZ Corp"

ocsp.responderCertSerialNumber=2A:FF:00

These properties may be set either statically in the Java runtime's <java_home>/conf/security/java.security file, or dynamically using the java.security.Security.setProperty() method.

By default, OCSP checking is not enabled. It is enabled by setting the ocsp.enable property to true. Use of the remaining properties is optional. Note that enabling OCSP checking only has an effect if revocation checking has also been enabled. Revocation checking is enabled via the PKIXParameters.setRevocationEnabled() method.

OCSP checking works in conjunction with Certificate Revocation Lists (CRLs) during revocation checking. Below is a summary of the interaction of OCSP and CRLs. Failover to CRLs occurs only if an OCSP problem is encountered. Failover does not occur if the OCSP responder confirms either that the certificate has been revoked or that it has not been revoked.

Maximum Allowable Clock Skew

You might encounter connection failures during revocation checking because the network is slow or the system clock is off by some amount. Set the maximum allowable clock skew (the time difference between response time and local time), in seconds, used for revocation checks with the system property com.sun.security.ocsp.clockskew. If the property has not been set, or if its value is negative, it's set to the default value of 900 seconds (15 minutes).

---

Copyright © 1993, 2022, Oracle and/or its affiliates. All rights reserved.

Contact Us