WAS v8.5 > Reference > Administrator examples

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. You enable certificate revocation checking using the dmgr 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.se
curity.enableCRLDP" value="false" type="boolean" displayNameKey="" nlsRangeKey="
" hoverHelpKey="" range="" inclusive="false" firstClass="false"/> <additionalTrustManagerAttrs xmi:id="DescriptiveProperty_2" name="com.ibm.js
se2.checkRevocation" value="false" type="boolean" displayNameKey="" nlsRangeKey=
"" hoverHelpKey="" range="" inclusive="false" firstClass="false"/> <additionalTrustManagerAttrs xmi:id="DescriptiveProperty_3" name="ocsp.enable
e" value="false" type="String" displayNameKey="" nlsRangeKey="" hoverHelpKey=""
range="" inclusive="false" firstClass="false"/> <additionalTrustManagerAttrs xmi:id="DescriptiveProperty_4" name="ocsp.respo
nderURL" value="http://ocsp.example.net:80" type="String" displayNameKey="" 
nlsRangeKey="" hoverHelpKey="" range="" inclusive="false" firstClass="false"/> <additionalTrustManagerAttrs xmi:id="DescriptiveProperty_5" name="ocsp.respo
nderCertSubjectName" value="" type="String" displayNameKey="" nlsRangeKey="" hov
erHelpKey="" range="" inclusive="false" firstClass="false"/> <additionalTrustManagerAttrs xmi:id="DescriptiveProperty_6" name="ocsp.respo
nderCertIssuerName" value="" type="String" displayNameKey="" nlsRangeKey="" hove
rHelpKey="" range="" inclusive="false" firstClass="false"/> <additionalTrustManagerAttrs xmi:id="DescriptiveProperty_7" name="ocsp.respo
nderCertSerialNumber" value="" type="String" displayNameKey="" nlsRangeKey="" ho
verHelpKey="" 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 dmgr console.

To do this,


IbmPKIX custom properties

com.ibm.jsse2.checkRevocation

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

This property configures CRL distribution point checking for the PKIX trust manager.

If we enable CRL distribution point revocation checking, the certificates used for 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

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

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 dmgr 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 containing 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 dmgr 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 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 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, you 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.

For more information 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


+

Search Tips   |   Advanced Search