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:
- Requiring clients to provide certificates to the Gateway (described in Require Clients to Provide Certificates to the Gateway).
- 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:
- Secure the Gateway Using Trusted Certificates
- Secure the Gateway Using Self-Signed Certificates (Optional)
- Secure Clients and Web Browsers with a Self-Signed Certificate (Optional)
- Require Clients to Provide Certificates to the Gateway (Optional)
- Implement Certificate Revocation Using OCSP (Optional)
To Set Up to Use OCSP
Certificate revocation checking is optional and disabled by default. Perform the following steps to enable OCSP:
- 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.
- 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.
- Ensure the
ssl.verify-client
accept-option is set torequired
in the Gateway configuration file. - 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.
- Set the value of the
ocsp.enable
security property totrue
(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.