Configuring Dynamic SSL Profiles with Backend Service - WSO2 ESB 4.9.0

In order to establish connections with backend services, ESB needs to have backend services's public key in it's trust store. Therefore let's first create required key stores and trust stores for both ESB and backend mock service. Also, if Mutual SSL is required, backend service must need ESB's public key in it's trust store file.

Create Key Store and Trust Store files for SSL

First create keystore and truststore files as follows.

Backend

• Key Store 
• Name - backend.jks
• Contains backend's private key
• Trust Store
• backendtruststore.jks
• Contains ESB’s certificate

ESB

• Key Store
• Name - esb.jks
• Contains ESB’s Private Key
• Trust Store
• Name - esbtruststore.jks
• Contains backend's certificate

Generate KeyStores

backend.jks

keytool -keystore backend.jks -genkey -alias backend

esb.jks

keytool -keystore esb.jks -genkey -alias esb

Export Certificates

backend.jks

keytool -export -keystore backend.jks -alias backend -file backend.crt

esb.jks

keytool -export -keystore esb.jks -alias esb -file esb.crt

Import Certificates and Create TrustStores

backendtruststore.jks

keytool -import -file esb.crt -alias esb -keystore backendtruststore.jks

esbtruststore.jks

keytool -import -file backend.crt -alias backend -keystore esbtruststore.jks

SSL with Back End Services

1. We will use echo service of Backend ESB (WSO2 ESB-4.8.1) as the back end service.

2. First use default Key Store and Trust Store configured.
3. Change port offset of the Backend ESB using below configuration of carbon.xml in {ESB_HOME}/repository/conf/ folder. It will allow to start two ESB instances at once.

<Offset>1</Offset>

4. Start Backend ESB.
5. Go to https://localhost:9444/carbon/ and it will show “echo” service as a default deployed axis2 service in Backend ESB.

6. Now to configure ESB (used WSO2 ESB-4.9.0 for this example) to use above backend service through a Pass Through Proxy. Use new instance of ESB and start the server.
7. Admin console can be access through https://localhost:9443/carbon/
8. Go to proxy services and create a new Pass Through Proxy service to access “echo” service mentioned above (https://localhost:8244/services/echo) using https.

9. Now configure ESB for Dynamic SSL Profiles for Senders. Create new XML file “senderprofiles.xml” in {ESB_HOME}/repository/conf/sslprofiles/ folder. (this path is configurable)
10. Include below configuration block in newly created file to enable Dynamic SSL Profiles. This will configure client-truststore.jks as Trust Store for all connections to localhost:8244.

<parameter name="customSSLProfiles">

<profile>

<servers>localhost:8244</servers>

<TrustStore>

<Location>repository/resources/security/client-truststore.jks

</Location>

<Type>JKS</Type>

<Password>wso2carbon</Password>

</TrustStore>

</profile>

</parameter>

11. To enable dynamic loading of this configuration, add below configurations to the Transport Sender configuration (PassThroughHttpSSLSender) of ESB ({ESB_HOME}/repository/conf/axis2.xml). Set above file’s path as “filePath” parameter.

<parameter name="dynamicSSLProfilesConfig">

<filePath>repository/conf/sslprofiles/senderprofiles.xml</filePath>

<fileReadInterval>3600000</fileReadInterval>

</parameter>

<parameter name="HostnameVerifier">DefaultAndLocalhost</parameter>

12. Now both back end service and ESB is configured to use default key stores and ESB is configured to load dynamic SSL profiles.
13. Restart ESB. It will show below message in the console confirming that dynamic configurations loaded.

ClientConnFactoryBuilder customSSLProfiles configuration is loaded from path:

14. Access backend service using “TryIt” tool of proxy service created in Step 8.

https://localhost:9443/services/ESBEchoService?tryit

Use sample value and send the request. Backend will respond with same value as follows;

15. Now change Backend ESB’s configuration to use new key stores. Change below configurations in Backend ESB’s axis2.xml file ({ESB_HOME}/ repository/conf/axis2.xml ).

<parameter name="keystore" locked="false">

           <KeyStore>

               <Location>repository/resources/security/backend.jks</Location>

               <Type>JKS</Type>

               <Password>123456</Password>

               <KeyPassword>123456</KeyPassword>

           </KeyStore>

        </parameter>

        <parameter name="truststore" locked="false">

           <TrustStore>

               <Location>repository/resources/security/backendtruststore.jks</Location>

               <Type>JKS</Type>

               <Password>123456</Password>

           </TrustStore>

        </parameter>

16. Copy backend.jks and backendtruststoe.jks files to {ESB_HOME}/repository/resources/security/ folder and restart the Backend ESB and it will use new key stores configured.
17. Try to access backend service again as in Step 14, but it will give below error messages in ESB console. This happens because we have now changes backend service’s key stores and therefore SSL handshake fails between two servers.

ERROR - TargetHandler I/O error: General SSLEngine problem

javax.net.ssl.SSLHandshakeException: General SSLEngine problem

Caused by: sun.security.validator.ValidatorException: PKIX path building failed:

sun.security.provider.certpath.SunCertPathBuilderException: unable to find valid certification path to requested target

18. Now change dynamic configuration in ESB so that new key stores will be applied at run-time to connect with newly changed backend. To do that, change “senderprofiles.xml” file created in Step 10 as follows;

<parameter name="customSSLProfiles">

<profile>

<servers>localhost:8244</servers>

<TrustStore>

<Location>repository/resources/security/esbtruststore.jks</Location>

<Type>JKS</Type>

<Password>123456</Password>

</TrustStore>

</profile>

</parameter>

19. Copy esb.jks and esbtruststoe.jks files to {ESB_HOME}/repository/resources/security/ folder.
20. New configurations can be applied using two methods. (mentioned earlier in this document) Here we can use JMX method. Start JConsole and connect it to ESB  instance. It will show “SenderSSLProfileReloader” under org.apache.synapse menu in MBeans tab.

Here, “ConfigFilePath” attribute shows the path of the configuration file. Make sure it is the same file changed in Step 18. Once confirmed, execute “notifyFileUpdate” operation.

21. ESB console will show below messages confirming that new SSL configuration loaded and applied.

INFO - PassThroughHttpSSLSender PassThroughHttpSender reloading SSL Config..

INFO - PassThroughHttpSSLSender Pass-through HTTPS Sender updated with Dynamic Configuration Updates …

22. Try to access backend service again as in Step 14, it will be success and connection will be established using new keys loaded dynamically.

Mutual SSL with Back End Services

When mutual SSL is enabled, backend and ESB will share their certificates each other. Therefore trust stores of both sides should contains each other's certificates.

23. To enable Mutual SSL, set below configuration in {ESB_HOME}/repository/conf/axis2.xml file inside the corresponding SSL Sender configuration block and restart backend ESB.

<parameter name="SSLVerifyClient">require</parameter>

24. Now follow Step 14, it will give below error in Backend ESB which does not allow to connect. It is because for Mutual SSL, client should send it’s key to the backend and it is still not configured in ESB.

ERROR - SourceHandler I/O error: null cert chain

javax.net.ssl.SSLHandshakeException: null cert chain

25. To configure correct keystore file in ESB, change {ESB_HOME}/repository/conf/sslprofiles/senderprofiles.xml file as follows.

<parameter name="customSSLProfiles">

<profile>

<servers>localhost:8244</servers>

<KeyStore>

<Location>repository/resources/security/esb.jks</Location>

<Type>JKS</Type>

<Password>123456</Password>

        <KeyPassword>123456</KeyPassword>

            </KeyStore>

<TrustStore>

<Location>repository/resources/security/esbtruststore.jks</Location>

<Type>JKS</Type>

<Password>123456</Password>

</TrustStore>

</profile>

</parameter>

26. Follow Steps 20 and 21 to reload new configurations. Follow Step 14 and it will get the result successfully confirming that new configurations applied for Mutual SSL.