These instructions apply exclusively to Process Commander systems supported by Apache Tomcat.

To prevent unauthorized access to your Web services, you can implement two-way SSL (Secure Socket Layer). Two-way SSL requires the Web services server to present a signed certificate to the client proving its identity, as well as requiring the client to present a signed certificate to the server verifying its identity.

If two-way SSL is not configured properly, no connection is made and an error similar to the following might be issued:

ssl error:
11:14:20,883 [ http8080-Processor7] (ivity.Invoke.Rule_Connect_SOAP) ERROR ADJSMNMP003DEV|172.26.97.45|Rule-Connect-SOAP.Data-ASI-V207-ASIService-.searchSpecialInstructions AcmeCo.Acme - SOAP service failed: javax.net.ssl.SSLHandshakeException: sun.security.validator.ValidatorException: PKIX path building failed: sun.security.provider.certpath.SunCertPathBuilderException: unable to find valid certification path to requested target
AxisFault
faultCode: {http://schemas.xmlsoap.org/soap/envelope/}Server.userException
faultSubcode:
faultString: javax.net.ssl.SSLHandshakeException: sun.security.validator.ValidatorException: PKIX path building failed: sun.security.provider.certpath.SunCertPathBuilderException: unable to find valid certification path to requested target
faultActor:
faultNode:
faultDetail:
{http://xml.apache.org/axis/}stackTrace: javax.net.ssl.SSLHandshakeException: sun.security.validator.ValidatorException: PKIX path building failed: sun.security.provider.certpath.SunCertPathBuilderException: unable to find valid certification path to requested target
at com.sun.net.ssl.internal.ssl.Alerts.getSSLException(Alerts.java:150)

This error occurs because two-way SSL requires both a client certificate and a server certificate.

Suggested approach

To initiate two-way SSL over HTTPS using Rule-Connect-SOAP, you need to configure the trust store and key store files, and then configure the client and server.

Configure the trust store and key store files

The trust store and key store files should already be configured. If not, your Web Services system administrator needs to perform the following steps.

1. Create and import the server certificate into the client trust store.

2. Create and import the client certificate into the server trust store.

See the instructions at the following link to complete steps 1 and 2: http://tomcat.apache.org/tomcat-5.5-doc/ssl-howto.html

Server configuration

On the server, configure the HTTPS connector in Tomcat’s server.xml file ($CATALINA_HOME/conf/server.xml):

1. Uncomment the connector definition in the file. (By default it is commented out.)

2. Set the clientAuth attribute to ‘true’.

3. Enter values for the following attributes to point to their configured file locations:

• keystoreFile
• truststoreFile

4. Enter the appropriate passwords for the following attributes:

• keystorePass
• truststorePass

The updated connector definition in the server.xml file will be similar to the following:

<!-- Define a SSL HTTP/1.1 Connector on port 8443 -->

<Connector port="8443" maxHttpHeaderSize="8192"

maxThreads="150" minSpareThreads="25" maxSpareThreads="75"

enableLookups="false" disableUploadTimeout="true"

acceptCount="100" scheme="https" secure="true"

clientAuth="true" sslProtocol="TLS"

keystoreFile="server_keystore.keystore"

keystorePass="server_keystore_pw_mypassword"

truststoreFile="server_truststore.keystore"

truststorePass=" server_truststore_pw_mypassword"/>

Relative filepaths for the keystoreFile and truststoreFile are resolved relative to the $CATALINA_HOME directory.

Client configuration

On the client, add the following command line arguments to the Tomcat setenv.bat file:

-Djavax.net.ssl.keyStore=C:/tomcat/client_keystore.keystore

-Djavax.net.ssl.keyStorePassword=client_keystore_pw_mypassword

-Djavax.net.ssl.trustStore= C:/tomcat/client_truststore.keystore

-Djavax.net.ssl.trustStorePassword= client_truststore_pw_mypassword

where the values for these arguments are the file locations and the passwords.

For further details on this step, see the instructions at the following link:

http://java.sun.com/j2se/1.5.0/docs/tooldocs/solaris/keytool.html

Error reporting

Two-way SSL involves heavy HTTP traffic. If an error message displays, this traffic makes it difficult to determine where in the process the error occurred. To resolve this issue, set the following command line option in Process Commander:

For Sun JVMs:

-Djavax.net.debug=all

For IBM JVMs:

-Djavax.net.debug=true