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 by 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.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>
Enabling certificate revocation checking with the
default IbmPKIX trust manager
You can view and change IbmPKIX
Trust Manager Custom Properties using the administrative console.
To
do this,
- Click Security > SSL certificate and key management.
- Under Related Items, click Trust managers.
- Click IbmPKIX.
- Under Additional Properties, click Custom properties.
IbmPKIX custom properties
- com.ibm.jsse2.checkRevocation
- This property configures revocation checking for the Java Virtual
Machine (JVM). This property 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.
Note: 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.
Note: If you 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.
Note: 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:
- ocsp.enable
- ocsp.responder
- ocsp.responderCertSubjectName
- ocsp.responderCertIssuerName
- ocsp.responderCertSerialNumber
These JDK properties can be set using the administrative console. You should reference
Java(TM) Certification Path API Programmer's Guide - SDK 6.0 for
descriptions of these properties and their allowable settings.
Note: 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, you must 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 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
You 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
Note: In order for these properties to be effective, you
must 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, 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.