How to Install Your Own Certificate to the WSO2 ESB

  • By Amila Jayasekara
  • 13 Aug, 2012

1. Introduction

By default the WSO2 ESB is shipped with a WSO2 specific self signed certificate. It is recommended to change this default JKS file with your own JKS file. Specially in a production environment, you must replace the default WSO2 JKS file with your own one. In this article we will discuss, how you can create your own self signed certificate and replace it with the default wso2carbon.jks. If you are interested in creating a CA signed certificate in your deployment you should follow instructions in [1]. If you are using a product other than ESB and if you want to change default JKS file with your own keystore, please follow blog post [2].

2. Creating a Keystore

To generate a keystore and a key pair you can use Java Key tool [3].

E.g :­
[email protected]:~$ keytool ­genkey ­alias MyCompany ­keyalg RSA ­keystore MyCompany.jks ­keysize 2048
Enter keystore password: 
Re­enter new password:
What is your first and last name?
  [Unknown]:  Amila Jayasekara
What is the name of your organizational unit?
  [Unknown]:  ENGINEERING
What is the name of your organization?
  [Unknown]:  WSO2
What is the name of your City or Locality?
  [Unknown]:  Colombo
What is the name of your State or Province?
  [Unknown]:  Western
What is the two­letter country code for this unit?
  [Unknown]:  LK
Is CN=Amila Jayasekara, OU=ENGINEERING, O=WSO2, L=Colombo,
ST=Western, C=LK correct?
  [no]:  yes
Enter key password for
(RETURN if same as keystore password):

Store above created MyCompany.jks file in the following location;

For ESB 3.0.0 and ESB 3.0.1 - $ESB_HOME/resources/security.

For ESB 3.2.0 and onwards versions - $ESB_HOME/repository/resources/security

3. Change Configurations

Change highlighted configuration values.

a. $ESB_HOME/repository/conf/carbon.xml

Locate Securty/Keystore tag,

<KeyStore>
    <!--­­ Keystore file location--­­>
    <Location>${carbon.home}/repository/resources/security/MyCompany.jks</Location>
    <Type>JKS</Type>
    <!--­­ Keystore password­­-->
    <Password>MyCompany</Password>
    <!--­­ Private Key alias­­-->
    <KeyAlias>MyCompany</KeyAlias>
    <!­­-- Private Key password­­-->
    <KeyPassword>xxxxxx</KeyPassword>
</KeyStore>

b. $ESB_HOME/repository/conf/mgt-transports.xml

<parameter name="keystorePass">xxxxx</parameter>

c. $ESB_HOME/repository/conf/axis2.xml

Change HTTPS transport receiver configuration,

<transportReceiver name="https"
class="org.apache.synapse.transport.nhttp.HttpCoreNIOSSLListener">
.....
.....
<parameter name="keystore" locked="false">
 <KeyStore>
   <Location>repository/resources/security/MyCompany.jks</Location>
   <Type>JKS</Type>
   <Password>MyCompany</Password>
   <KeyPassword>xxxxx</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>

Change HTTPS transport sender configuration,

<transportSender name="https"
class="org.apache.synapse.transport.nhttp.HttpCoreNIOSSLSender">
<parameter name="non­blocking" locked="false">true</parameter>
<parameter name="keystore" locked="false">
 <KeyStore>
How to install your own certificate to WSO2 ESB   <Location>repository/resources/security/MyCompany.jks</Location>
  <Type>JKS</Type>
  <Password>xxxxx</Password>
  <KeyPassword>xxxxx</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="HostnameVerifier">DefaultAndLocalhost</parameter>­­>
<!­­supports Strict|AllowAll|DefaultAndLocalhost or the default if none
specified ­­>
</transportSender>

4. Making Newly Created Certificate a Trusted Certificate

All trusted certificates reside inside $ESB_HOME/repository/resources/security/client-truststore.jks ($ESB_HOME/resources/security/client-truststore.jks for ESB 3.0.0 and 3.0.1) file. Most of the popular trusted certificates are already installed as trusted certificates. You can list existing trusted CA certificates using following command,
> keytool -list -v -keystore client-truststore.jks

You need to add newly created certificate to $ESB_HOME/repository/resources/security/client-truststore.jks, inorder to make it a trusted one. To do that follow instructions given below

a. Export certificate from MyCompany.jks
> keytool -export -alias MyCompany -file MyCompany.crt -keystore MyCompany.jks

b. Import above exported certificate to client-truststore.jks
> keytool ­importcert ­alias MyCompany ­keystore client-truststore.jks ­­file MyCompany.crt

5. References

[1] Adding CA (Certificate Authority) Signed Certificate to WSO2 Products - https://wso2.org/library/knowledge-base/2011/08/adding-ca-certificate-authority-signed-certificate-wso2-products

[2] Installing a new keystore into WSO2 Carbon based products. - https://hasini-gunasinghe.blogspot.com/2011/12/installing-new-keystore-into-wso2.html

[3] The Most Common Java Keytool Keystore Commands - https://www.sslshopper.com/article-most-common-java-keytool-keystore-commands.html