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 by using
the administrative console or by manually updating the ssl.client.props
file.
The default IbmPKIX trust manager
<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.
- 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
- ocsp.enable
- ocsp.responder
- ocsp.responderCertSubjectName
- ocsp.responderCertIssuerName
- ocsp.responderCertSerialNumber
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
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
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.