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


The IbmPKIX trust manager is enabled in the WAS by default. The IbmPKIX trust manager allows certificate revocation checking to occur. You enable certificate revocation checking by using the admin 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="" 
                             hov 
                             erHelpKey="" 
                             range="" 
                             inclusive="false" 
                             firstClass="false"/>
<additionalTrustManagerAttrs xmi:id="DescriptiveProperty_6" 
                             name="ocsp.responderCertIssuerName" 
                             value="" 
                             type="String" 
                             displayNameKey="" 
                             nlsRangeKey="" 
                             hove 
                             rHelpKey="" 
                             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 admin console. To do this,

 

IbmPKIX custom properties

com.ibm.jsse2.checkRevocation

This property configures revocation checking for the Java Virtual Machine (JVM). Is 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.

default

false

com.ibm.security.enableCRLDP

This property configures 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

This property specifies the 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.

Enabling 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

This property specifies the 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:

These JDK properties can be set using the admin console. You 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 admin console:

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 you 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 admin 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.
#
# 

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, verify 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.

See on these properties, see Java (TM) Certification Path API Programmer's Guide - SDK 6.0.



 

Related concepts


SSL configurations

 

Related information


http://www.ibm.com/developerworks/java/jdk/security/60/secguides/certpathDocs/API_users_guide.html