• Java Software
• Java SE Downloads
• Java SE 8 Documentation

Search

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 TransportLayer Security (TLS) handshake.

X.509 certificates used in TLS can be revoked bythe issuing Certificate Authority (CA) if there is reason tobelieve that a certificate is compromised. You can check therevocation status of certificates during the TLS handshake byusing one of the following approaches.

• Certificate Revocation List (CRL): ACRL is a simple list of revoked certificates. The applicationreceiving a certificate gets the CRL from a CRL server and checksif the certificate received is on the list. There are twodisadvantages to using CRLs that mean a certificate could berevoked:

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

  • Many CRLs are created with longer validity periods, whichincreases the possibility of a certificate being revoked withinthat validity period and not showing up until the next CRLrefresh.

  SeeCertificate/CRL Storage Classes inJava PKI Programmer's Guide.

• Client-driven OCSP: Inclient-driven OCSP, the client uses OCSP to contact an OCSPresponder to check the certificate's revocation status. Theamount of data required is usually less than that of a CRL, andthe OCSP responder is likely to be more up-to-date with therevocation status than a CRL. Each client connecting to a serverrequires an OCSP response for each certificate being checked. Ifthe server is a popular one, and many of the clients are usingclient-driven OCSP, these OCSP requests can have a negativeeffect on the performance of the OCSP responder.

• OCSP stapling: OCSP stapling enablesthe server, rather than the client, to make the request to theOCSP responder. The server staples the OCSP response to thecertificate and returns it to the client during the TLShandshake. This approach enables the presenter of thecertificate, rather than the issuing CA, to bear the resourcecost of providing OCSP responses. It also enables the server tocache the OCSP responses and supply them to all clients. Thissignificantly reduces the load on the OCSP responder because theresponse can be cached and periodically refreshed by the serverrather 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 byconnecting to an OCSP responder during the Transport LayerSecurity (TLS) handshake.

The client-driven OCSP request occurs during the TLS handshakejust after the client receives the certificate from the serverand validates it.

TLS Handshake with Client-Driven OCSP

Client-driven OCSP is used during the TLS handshake betweenthe client and the server to check the server certificaterevocation status. After the client receives the certificate, itperforms certificate validation. If the validation is successful,then the client verifies that the certificate was not revoked bythe issuer. This is done by sending an OCSP request to an OCSPresponder. After receiving the OCSP response, the client checksthis 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 lookingin the Authority Information Access (AIA) extension of thecertificate, but it can be set to a static URL through the use ofa system property.

Setting up a Java Client to use Client-Driven OCSP

Client-driven OCSP is enabled by enabling revocation checkingand enabling OCSP.

To configure a Java client to use client-drivenOCSP, the Java client must already be set up to connect to aserver using TLS.

1. Enable revocation checking. You can do this in two different ways.
   • Set the system propertycom.sun.net.ssl.checkRevocation totrue.
   • Use thesetRevocationEnabled method onPKIXParameters.
2. Enable client-driven OCSP:

   Set the Security Propertyocsp.enable totrue.

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

OCSP Stapling and Certificate Revocation

Online Certificate Status Protocol (OCSP) stapling enables thepresenter of a certificate, rather than the issuing CertificateAuthority (CA), to bear the resource cost of providing the OCSPresponses that contain the certificate's revocationstatus.

TLS Handshake with OCSP Stapling

OCSP stapling is used during the Transport Layer Security(TLS) handshake between the client and the server to check theserver certificate revocation status. The server makes the OCSPrequest to the OCSP responder and staples the OCSP responses tothe certificates returned to the client. By having the servermake the request to the OCSP responder, the responses can becached, 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 touse client-driven OCSP or Certificate Revocation Lists (CRLs) toget revocation information if the following are true:

• TheRevocationEnabled flag is set totrue through thePKIXParameters.setRecovcationEnabled method.

• OCSP checking is enabled by setting theocsp.enable Security Property totrue.

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 revocationchecking. SeeOCSP Support for PKI.

Status Request Versus Multiple Status Request

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

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

Although TLS allows the server to also request theclient's certificate, there is no provision in OCSPstapling that enables the client to contact the appropriate OCSPresponder and staple the response to the certificate sent to theserver.

The OCSP Request and Response

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

If necessary, the stapled responses can be obtained in theclient code by calling thegetStatusResponses method on theExtendedSSLSession object. The method signatureis:

public List<byte[]> getStatusResponses();

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

Setting up a Java Client to Use OCSP Stapling

Online Certificate Status Protocol (OCSP) stapling is enabledon the client side by setting the system propertyjdk.tls.client.enableStatusRequestExtension tofalse (its default value).

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

1. Enable OCSP stapling on the client:

   If necessary, set the system propertyjdk.tls.client.enableStatusRequestExtension totrue.

2. Enable revocation checking. You can do this in two different ways.
   • Set the system propertycom.sun.net.ssl.checkRevocation totrue. You can do this from the command line or inthe code.
   • Use thesetRevocationEnabledmethod on thePKIXParameters class.

   For the client to include the stapled responses received fromthe server in the certificate validation, revocation checkingmust be set totrue. If revocationchecking is not set totrue, then theconnection will be allowed to proceed regardless of the presenceor status of the revocation information

Setting Up a Java Server to Use OCSP Stapling

Online Certificate Status Protocol (OCSP) stapling is enabledon the server by setting the system propertyjdk.tls.server.enableStatusRequestExtension totrue. (It is set tofalse by default.)

The following steps can be used to configure aJava server to connect to an OCSP responder and staple the OCSPresponse to the certificate to be returned to the client. TheJava server must already be set up to respond to clients usingTLS.

1. Enable OCSP stapling on theserver:

   Set the system propertyjdk.tls.server.enableStatusRequestExtension totrue.

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

OCSP Stapling Configuration Properties

This topic lists the effects of setting various propertieswhen using the Online Certificate Status Protocol (OCSP). Itshows the properties used in both client-driven OCSP and OCSPstapling.

Server-Side Properties

Most of the properties are read atSSLContext instantiation time. This means that ifyou set a property, you must obtain a newSSLContext object so that anSSLSocket orSSLEngine object you obtain from thatSSLContext object will reflect theproperty setting. The one exception is thejdk.tls.stapling.responseTimeout property. Thatproperty is evaluated when theServerHandshaker object is created (essentiallyat the same time that anSSLSocket orSSLEngine object gets created).

Client-Side Settings

¹Note that client-side OCSP fallback will occur only iftheocsp.enable Security Property isset totrue.

Developers have some flexibility in how to handle theresponses provided through OCSP stapling. OCSP stapling makes nochanges to the current methodologies involved in certificate pathchecking and revocation checking. This means that it is possibleto have both client and server assert thestatus_request extensions, obtain OCSP responsesthrough theCertificateStatus message, and provide userflexibility in how to react to revocation information, or thelack thereof.

If noPKIXBuilderParameters isprovided by the caller, then revocation checking is disabled. Ifthe caller creates aPKIXBuilderParameters object and usesthesetRevocationEnabled method toenable revocation checking, then stapled OCSP responses will beevaluated. This is also the case if thecom.sun.net.ssl.checkRevocation property is settotrue.

OCSP Support for PKI

Client-side support for the On-Line Certificate StatusProtocol (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 Javaruntime's<java_home>/conf/security/java.security file,or dynamically using thejava.security.Security.setProperty() method.

By default, OCSP checking is not enabled. It is enabled bysetting theocsp.enable property totrue. Use of the remainingproperties is optional. Note that enabling OCSP checking only hasan effect if revocation checking has also been enabled.Revocation checking is enabled via thePKIXParameters.setRevocationEnabled()method.

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

Maximum Allowable Clock Skew

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