Example: Enabling certificate revocation checking with the default IbmPKIX trust manager

Example: Enabling certificate revocation checking with the default IbmPKIX trust manager

The IbmPKIX trust manager is enabled in the WebSphere Application Server by default. The IbmPKIX trust manager allows certificate revocation checking to occur. We enable certificate revocation checking using the administrative console or by manually updating the ssl.client.props file.

The default IbmPKIX trust manager

The IbmPKIX trust manager is enabled by default, but revocation checking is not enabled by default. The following trust manager definition for IbmPKIX reflects the default condition:
<trustManagers xmi:id="TrustManager_managementNode_2" 
               name="IbmPKIX" 
               provider="IBMJSSE2" 
               algorithm="IbmPKIX" 
               trustManagerClass="" 
               managementScope="ManagementScope_managementNode_1">

    <additionalTrustManagerAttrs xmi:id="DescriptiveProperty_1" 
                                 name="com.ibm.security.enableCRLDP" 
                                 value="false" 
                                 type="boolean" 
                                 displayNameKey="" 
                                 nlsRangeKey=" " 
                                 hoverHelpKey="" 
                                 range="" 
                                 inclusive="false" 
                                 firstClass="false"/>
    <additionalTrustManagerAttrs xmi:id="DescriptiveProperty_2" 
                                 name="com.ibm.jsse2.checkRevocation" 
                                 value="false" 
                                 type="boolean" 
                                 displayNameKey="" 
                                 nlsRangeKey="" 
                                 hoverHelpKey="" 
                                 range="" 
                                 inclusive="false" 
                                 firstClass="false"/>
    <additionalTrustManagerAttrs xmi:id="DescriptiveProperty_3" 
                                 name="ocsp.enable" 
                                 value="false" 
                                 type="String" 
                                 displayNameKey="" 
                                 nlsRangeKey="" 
                                 hoverHelpKey="" 
                                 range="" 
                                 inclusive="false" 
                                 firstClass="false"/> 
    <additionalTrustManagerAttrs xmi:id="DescriptiveProperty_4" 
                                 name="ocsp.responderURL" 
                                 value="http://ocsp.example.net:80" 
                                 type="String" 
                                 displayNameKey="" 
                                 nlsRangeKey="" 
                                 hoverHelpKey="" 
                                 range="" 
                                 inclusive="false" 
                                 firstClass="false"/>
    <additionalTrustManagerAttrs xmi:id="DescriptiveProperty_5" 
                                 name="ocsp.responderCertSubjectName" 
                                 value="" 
                                 type="String" 
                                 displayNameKey="" 
                                 nlsRangeKey="" 
                                 hoverHelpKey="" 
                                 range="" 
                                 inclusive="false" 
                                 firstClass="false"/>
    <additionalTrustManagerAttrs xmi:id="DescriptiveProperty_6" 
                                 name="ocsp.responderCertIssuerName" 
                                 value="" 
                                 type="String" 
                                 displayNameKey="" 
                                 nlsRangeKey="" 
                                 hoverHelpKey="" 
                                 range="" 
                                 inclusive="false" 
                                 firstClass="false"/>
    <additionalTrustManagerAttrs xmi:id="DescriptiveProperty_7" 
                                 name="ocsp.responderCertSerialNumber" 
                                 value="" 
                                 type="String" 
                                 displayNameKey="" 
                                 nlsRangeKey="" 
                                 hoverHelpKey="" 
                                 range="" 
                                 inclusive="false" 
                                 firstClass="false"/>
</trustManagers>
Enable certificate revocation checking with the default IbmPKIX trust manager

We can view and change IbmPKIX Trust Manager Custom Properties using the administrative console.

To do this, click...
Security > SSL certificate and key management > Related Items > Trust managers > IbmPKIX > Additional Properties > Custom properties

IbmPKIX custom properties

com.ibm.jsse2.checkRevocation

Configure revocation checking for the Java Virtual Machine (JVM). Set to false by default because the default WebSphere certificates used for SSL communication do not contain certificate revocation list (CRL) distribution points or Online Certificate Status Protocol (OCSP) information.
Since this property is a JVM property, this value is in effect for the entire application server. If the property is defined in trust managers at different scopes, the value in effect is used from the most specifically scoped IbmPKIX trust manager. For example, the property for an IbmPKIX trust manager defined at the node level overrides the property for an IbmPKIX trust manager defined at the cell level. This property is ignored for the IbmX509 trust manager.

default: false

com.ibm.security.enableCRLDP

Configure CRL distribution point checking for the PKIX trust manager.
If we enable CRL distribution point revocation checking, the certificates used for secure sockets layer (SSL) must contain a valid distribution point and the distribution point must be accessible or else SSL communication will fail and the server will not function correctly.

default: false

For certificates that do not contain an internal CRL distribution point, the following properties can used so the revocation status will be checked against a remote LDAP server containing the CRL.

com.ibm.security.ldap.certstore.host

LDAP server host name containing trusted certificates or certificate revocation lists. The target LDAP server host is used to obtain CA certificates or certificate revocation lists when validating a certificate and the local truststore does not contain the required certificate. The local truststore must contain the required certificates if an LDAP server is not specified. In cases when an LDAP server is used, the root CA certificates must also be located in the local truststore as the LDAP server is not a trusted certificate store.
Enable this property in addition to the com.ibm.jsse2.checkRevocation property enables revocation checking. The remote LDAP server must contain a valid certificate revocation list and the server must be accessible. If the revocation status cannot be determined then the check will fail and SSL communication will fail and the server will not function correctly.

default: none

com.ibm.security.ldap.certstore.port

LDAP server port. A port value of 389 will be used by default if no LDAP server port is specified.

default

389

The following Java Development Kit (JDK) properties apply to enabling certificate revocation checking with the default IbmPKIX trust manager:

ocsp.enable
ocsp.responder
ocsp.responderCertSubjectName
ocsp.responderCertIssuerName
ocsp.responderCertSerialNumber
These JDK properties can be set using the administrative console. We should reference Java(TM) Certification Path API Programmer's Guide - SDK 6.0 for descriptions of these properties and their allowable settings.
In addition to its role of standard certificate verification, the IbmPKIX trust manager checks for certificates that contain CRL distribution points. This process is known as extended CRL checking. By default, CRL distribution point revocation checking is disabled. To enable CRL distribution point revocation checking, set the following properties to true using the administrative console:

com.ibm.security.enableCRLDP
com.ibm.jsse2.checkRevocation

OCSP properties and CRL properties affect certificate revocation checking. By default OCSP properties are checked first. If there is an error validating the certificate with OCSP, then validation uses a CRL distribution point instead.

When we select a trust manager, its associated properties are automatically set as Java system properties so that the IBMCertPath and IBMJSSE2 providers are aware that CRL checking is enabled or disabled. Similarly, the same applies for OCSP properties, which are java.security.Security properties.

Client considerations

We can also enable revocation checking for WebSphere application and administrative clients by directly setting the properties in the ssl.client.props file. An example of the ssl.client.props file follows:
#-------------------------------------------------------------------------
# Default Revocation Checking Properties
# These properties are used for certificate revocation checking with the IBM # PKIX TrustManager.
#
# To enable CRL Distribution Points extension checking, use the system property
# com.ibm.security.enableCRLDP.
#
# OCSP checking is not enabled by default. It is enabled by setting the # ocsp.enable property to "true".  Use of the other ocsp properties is optional.
#
# Note: Both OCSP and CRLDP checking is only effective if revocation checking
# has also been enabled by setting com.ibm.jsse2.checkRevocation to "true".
#
#-------------------------------------------------------------------------
com.ibm.jsse2.checkRevocation=false
com.ibm.security.enableCRLDP=false
#ocsp.enable=true
#ocsp.responderURL=http://ocsp.example.net
#ocsp.responderCertSubjectName=CN=OCSP Responder, O=XYZ Corp
#ocsp.responderCertIssuerName=CN=Enterprise CA, O=XYZ Corp
#ocsp.responderCertSerialNumber=2A:FF:00
In order for these properties to be effective, ensure that the IbmPKIX trust manager is initialized by setting com.ibm.ssl.trustManager=IbmPKIX.
In addition, for revocation checking to be processed successfully on the client, we are required to turn off the signer exchange prompt. To do this, change the value of the com.ibm.ssl.enableSignerExchangePrompt property to false, in the ssl.client.props file.

Related:

SSL configurations