Implement Certificate Revocation Using OCSP

The documentation topic How TLS/SSL Works with the Gateway describes in detail how the Gateway uses TLS/SSL to secure network traffic with clients and back-end servers. TLS/SSL uses certificates to establish trust between two network hosts over TCP using the HTTPS and WSS (WebSocket Secure) protocols. You can optionally extend security by:

  1. Requiring clients to provide certificates to the Gateway (described in Require Clients to Provide Certificates to the Gateway).
  2. Setting up your Gateway to use Online Certificate Status Protocol (OCSP) so that when a client presents a certificate, the Gateway uses OCSP to verify the certificate is still valid and has not been revoked prior to letting the connection succeed.

This topic describes how to set up OCSP with the Gateway to dynamically check the revocation status of a particular certificate during the TLS/SSL handshake and either succeed or revoke (fail) the connection. In the event the certificate has become invalid:

  • The client certificate is revoked and the TLS/SSL connection to the Gateway does not succeed.
  • The back-end service certificate is revoked and the TLS/SSL connection to the back-end service does not succeed.

For further details about how OCSP provides revocation information, see RFC 6960.

Before You Begin

This procedure is part of Checklist: Secure Network Traffic with the Gateway, that includes the following steps:

To Set Up to Use OCSP

Certificate revocation checking is optional and disabled by default. Perform the following steps to enable OCSP:

  1. Optionally (depending on your particular use case and environment), perform the steps in Secure the Gateway Using Trusted Certificates to configure secure networking between Kaazing WebSocket Gateway and its clients and back-end servers using trusted certificates issued by a Certificate Authority using TLS/SSL.
  2. Optionally (depending on your particular use case and environment), perform the steps in Require Clients to Provide Certificates to the Gateway to configure the Gateway to use certificates to validate the client's identity. The Gateway will not establish a TLS/SSL connection (HTTPS or WSS) with the client until the identity of client has been verified.
  3. Ensure the ssl.verify-client accept-option is set to required in the Gateway configuration file.
  4. Start the Gateway using -Dcom.sun.security.enableCRLDP=true -Dcom.sun.net.ssl.checkRevocation=true system properties to locate revocation information and to enable revocation checking.

    See Java Secure Socket Extension (JSSE) Reference Guide for more information.

  5. Set the value of the ocsp.enable security property to true (in $JAVA_HOME/jre/lib/security/java.security).

    Setting up this security property enables OCSP checking when doing certificate revocation checking. See Java PKI Programmer’s Guide for information about this property and other security properties, such as ocsp.responderURL, that you can use to configure OCSP checking.

Notes

  • See the Gateway start log for entries related to OCSP checking. For example:
    certpath: connecting to OCSP service at: http://ocsp2.globalsign.com/gsorganizationvalsha2g2
    certpath: OCSP response status: SUCCESSFUL
    certpath: OCSP response type: basic
    certpath: Responder's key ID: e1:16:98:1b:a0:51:7b:87:7c:d5:cb:fb:3f:a2:b4:64:50:d8:14:1b
    certpath: OCSP response produced at: Tue Nov 25 19:09:39 PST 2014
    certpath: OCSP number of SingleResponses: 1
    certpath: OCSP response cert #1: SERIALNUMBER=20141125142700, CN=GlobalSign OV CA - SHA256 - G2 OCSP responder - 1, O=GlobalSign nv-sa, C=BE
    certpath: Status of certificate (with serial number 1492176451322427379234331084253676141083944) is: GOOD

    See Setting Up Kaazing WebSocket Gateway to learn the location of the Gateway start log for your platform.

  • Use keytool to see authority information in a certificate, such as OCSP responder URL. For example:
     
    $ keytool -printcert -v -file target.cert
    
    ...
    #1: ObjectId: 1.3.6.1.5.5.7.1.1 Criticality=false
    AuthorityInfoAccess [
      [
       accessMethod: ocsp
       accessLocation: URIName: http://ocsp.digicert.com
    ]
    ]

    In the example, http://ocsp.digicert.com indicates the location of the OCSP responder service. You can override the OCSP responder URL using a system property, as described in Java PKI Programmer’s Guide.

  • To enable debugging, start the Gateway using -Djava.security.debug=certpath.
  • Because system properties are used to enable revocation checking, OCSP checking is applied to all services, including proxy services where the Gateway acts as a client. In this case, the back-end service certificate is checked with regard to revocation.
  • Certificate revocation checking is done using both OCSP and CRLs (first OCSP with failover to CRLs).
  • Enabling OCSP requires a round trip to the OCSP responder for every new client request, adding overhead when setting up HTTPS/WSS connections.
  • OCSP Stapling allows the presenter of a certificate to bear the cost involved in providing OCSP responses. Because OCSP Stapling is not supported in JSSE, the Gateway does not currently support OCSP Stapling.

Next Step

To troubleshoot TLS/SSL errors and exceptions, see Troubleshooting Kaazing WebSocket Gateway Security.

See Also

TOP