Use of SSL Profiles in WSO2 ESB

SSL profiles in WSO2 ESB allows you to use different trust stores/ key stores for different hosts. For example you will have couple of hosts that requires 1-way SSL (SSL-client is not verified by the server. Only server is verified by the client.) and another host requiring 2-way SSL (Mutual SSL - it is a certificate based authentication where two parties [client and server] authenticate each other by verifying digital certificates. So in simple terms both parties are assured of other's identity.).

In here I have given an example where ESB acting as the server. 1-way SSL requires only key store in it's configuration. For mutual SSL you need to configure both trust store and the key store. In ESB we can have 2 different SSL profiles to support the above mentioned scenario. One profile for hosts requiring only 1-way SSL and another profile for the host requiring mutual SSL.

How to configure SSL profiles in WSO2 ESB.

Open  <ESB_HOME>/repository/conf/Axis2/axis2.xml. Edit <transportReceiver> configurations as follows. (If ESB is acting as the client you have to edit <transportSender> configurations to add customSSLProfiles.)

<transportReceiver name="multi-https" class="org.apache.synapse.transport.nhttp.HttpCoreNIOMultiSSLListener">

        <parameter name="port">8343</parameter>

        <parameter name="non-blocking">true</parameter>

        <parameter name="SSLProfiles">

            <profile>

                <bindAddress>localhost:9445, localhost:9446</bindAddress>

                <KeyStore>

                    <Location>/path/to/keystore1.p12</Location>

                    <Type>PKCS12</Type>

                    <Password>key1</Password>

                    <KeyPassword>key1</KeyPassword>

                </KeyStore>

            </profile>

           <profile>

                <bindAddress>localhost:9455</bindAddress>

                <KeyStore>

                    <Location>/path/to/keystore2.p12</Location>

                    <Type>JKS</Type>

                    <Password>test</Password>

                    <KeyPassword>test</KeyPassword>

                </KeyStore>

                <TrustStore>

                    <Location>/path/to/trustStore2.jks</Location>

                    <Type>JKS</Type>

                    <Password>test</Password>

                </TrustStore>

                <SSLVerifyClient>require</SSLVerifyClient>

            </profile>

        </parameter>

</transportReceiver>

 As you can see 1st profile contains only key store. And it has 2 bind addresses. That means hosts running on localhost:9445 and localhost:9446 will use this profile for their SSL authentication.

2nd profile has both key store and trust store configurations. And also it has <SSLVerifyClient>require</SSLVerifyClient> parameter added to the configuration. That is used to enable mutual SSL. This profile will be used for host running on 9445 port. Like wise we can have multiple SSL profiles for different hosts and also we can have same profile for different hosts. This is useful when you have many proxy services or APIs running on your WSO2 ESB.

Configure ciphers in WSO2 Servers to establish secure connections.

Cipher suites are encryption algorithms which are used to establish secure communication between host and the client. However cipher suites can be classified in to different categories based on the level of security they provide. Some ciphers are capable of providing better security compared to others. So sometimes you will need to customize the ciphers that your server should support in order to have a better secure connection.

These supported ciphers can be given to any wso2 server. To test the supported ciphers, first download TestSSLServer.jar from here http://www.bolet.org/TestSSLServer/TestSSLServer.jar. It is a command line tool which contacts a SSL/TLS server and provide information on supported protocols and supported cipher suites. 

Then start a WSO2 server and normally server will start from port 9443.

Go to TestSSLServer.jar location from command line and list supported protocols and ciphers using this command.
java -jar TestSSLServer.jar localhost 9443

Then you can see a list like this.

Then again shut down the server and go to <product-home>/repository/conf/tomcat folder and open catalina-server.xml. Find the relevant connector configuration with SSL/TLS configurations. Add another field as ciphers and give preferred cipher list in a comma separated manner.

EX:

<Connector protocol="org.apache.coyote.http11.Http11NioProtocol" 

port="9443"  

bindOnInit="false" 

sslEnabledProtocols="TLSv1,TLSv1.1,TLSv1.2"  

ciphers="TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256,TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA"

Here I have given only two ciphers.

Then again start the server and list supported protocols. There you can see only the given ciphers are supported by the server.

Server will accept requests from clients supporting these given protocols. If client does not support given sslEnabledProtocols or ciphers, server will not establish a secure client/server connection.