[HOW TO: ESB] Enable Mutual SSL for Proxy services-I

Lets see how we can enable mutual SSL (two-way SSL) for all the proxy services that are deployed in WSO2 ESB

Configuring Mutual SSL in ESB

 

Step 1 :  Enable mutual SSL for transport receiver of the WSO2 ESB

WSO2 ESB uses Pass through transport (or NIO ) for sending and receiving messages.  You can find Pass through transport (or NIO)  receiver and sender configuration  from axis2.xml file which can be found at /repository/conf/axis2 directory. Under the transport receiver,  there are key store and trust store configurations as follows.

<transportReceiver name="https" class="org.apache.synapse.transport.passthru.PassThroughHttpSSLListener">
 <parameter name="port" locked="false">8243</parameter>
 <parameter name="non-blocking" locked="false">true</parameter>
 <parameter name="httpGetPraxis2.xmlocessor" locked="false">org.wso2.carbon.transport.nhttp.api.PassThroughNHttpGetProcessor</parameter>
 <parameter name="keystore" locked="false">
 <KeyStore>
 <Location>repository/resources/security/wso2carbon.jks</Location>
 <Type>JKS</Type>
 <Password>wso2carbon</Password>
 <KeyPassword>wso2carbon</KeyPassword>
 </KeyStore>
 </parameter>
 <parameter name="truststore" locked="false">
 <TrustStore>
 <Location>repository/resources/security/client-truststore.jks</Location>
 <Type>JKS</Type>
 <Password>wso2carbon</Password>
 </TrustStore>
 </parameter>
 <!--<parameter name="SSLVerifyClient">require</parameter>
 supports optional|require or defaults to none -->
 </transportReceiver>
By default
1.  Mutual authentication is not enabled
2.  WSO2ESB is using the default wso2carbon.jks and client-truststore.jks file for key store and trust store respectively
Therefore you need to change those default parameters.  Here I have changed only the SSLVerifyClient parameter to require to enable mutual authentication for all the proxy services that have been exposed via  Pass through transport (or NIO)
<parameter name="SSLVerifyClient">require</parameter>
If you like,  you can change the default key store and trust store parameters as well.
Step 2 : After configuration is finished, Restart WSO2ESB server, if you have already started.
Step 3 : Then just create a simple pass through proxy service.  Let say  “TestProxy”.
Note : If you need to enable mutual SSL only for  given proxy service,  Please refer my next blog post from here

 

Setting up Key Store and Trust Stores

 

Step 1 :  Writing Axis2 client to invoke

You can find the client program for here. To run the client program you need to setup your key store and trust store properly.  Actually we use same key store file as both key store (which contains private key) and trust store (which contains trusted certificates)

Step 2 : We need to import the Pass through transport (or NIO) receiver’s certificate to client’s trust store filePlease export Pass through transport (or NIO) receiver’s certificate from key store.  As a sample, you can use java keytool command as follows.
> keytool -export -keystore wso2carbon.jks -alias localhost -file wso2.crt
Please import Pass through transport (or NIO)  certificate in to client’s trust store.
> keytool -import -keystore client.jks -alias wso2carbon -file wso2.crt
Step 3 : We need to import client’s certificate in to the NIO transport receiver’s trust store file. Please go through above keytool command for this.

 

Troubleshooting

 

If you have not properly done the 2nd step ,  when you try with the sample client, you would receive following error in client side.  Message would not be sent to the server side.
org.apache.axis2.AxisFault: Connection has been shutdown: javax.net.ssl.SSLHandshakeException: sun.security.validator.ValidatorException: PKIX path building failed: sun.security.provider.certpath.

If you have not properly done the 3rd step, when you try with sample client, you would receive following error in client side.

Exception in thread "main" org.apache.axis2.AxisFault: Connection has been shutdown: javax.net.ssl.SSLException: java.net.SocketException: Connection reset

And in server side.

[2012-08-08 17:29:56,390] ERROR - ServerHandler I/O error: null cert chain javax.net.ssl.SSLHandshakeException: null cert chain

Now you know how to secure  ESB  proxy services using mutual SSL and invoke them.  In my next blog post let see,  how we can secure only the specified ESB  proxy  services using mutual SSL(Not all)

Related posts:

  1. Enable Mutual SSL for Proxy services in WSO2ESB-II
  2. Securing APIs using Mutual SSL with WSO2 API Manager.
  3. Securing a Proxy Service in WSO2 ESB -1 ( Using Hash passwords In Username Token)
  4. SSL profiles in WSO2 ESB
Tags: , , ,