Installing a new keystore into WSO2 Carbon based products.

Applies to: WSO2 Carbon 3.2.0 based products.

WSO2 carbon products are shipped with a default keystore named wso2carbon.jks which resides in [CARBON_HOME]/repository/resources/security directory. This is the keystore with private/public key pair which is used for encrypting sensitive information, encryption/signature purposes in WS-Security and also for communication over SSL.

It is recommended to replace this with a keystore with self signed or CA signed certificates when the products are deployed in production environments. Because wso2carbon.jks is available with open source WSO2 products and anyone can have access to the private key of the default keystore.

Following is a step by step guide to achieve the $subject.

1). Create a new keystore with a private and public key pair using keytool utility that ships with JDK installation.

Make sure you have installed Java and set your PATH env variable to [i.e : JAVA_HOME\bin]
Go to [CARBON_HOME]/repository/resources/security directory and execute the following command:
keytool -genkey -alias mycert -keyalg RSA -keysize 1024 -keypass mypkpassword -keystore mykeystore.jks -storepass mypkpassword

Note: With tomcat SSL configuration, we need to have both keystore password and private key password the same.

You will be prompted to provide necessary information to construct the DN of the certificate.

Once you provide the information, a keystore file will be generated inside the same directory above, with:

keystore name=mykeystore.jks

alias of the public certificate=mycert

private key password & keystore password=mypkpassword

You can view the contents of the generated keystore from the following command:
keytool -list -v -keystore mykeystore.jks -storepass mypkpassword

2). Get the public certificate signed: You can either get your public certificate signed by a CA(recommended for production environment) or continue using the above generated self signed certificate (for local testing purposes).

Please refer to: http://blog.facilelogin.com/2008/03/keystore-management-part-i.html
for a step by step guide on how to get your public certificate signed by a CA and importing CA certs into your keystore. Here, in this guide I will continue to use the self signed certificate.

3). Export your public certificate from the keystore and import it into the trust store.

In SSL handshake, client side needs to verify the certificate presented by the server side. For that, client usually stores the certificates it trusts, in a trust store.

Related to SSL communication of WSO2 Carbon products, this trust store is set as client-truststore.jks which resides in the same above directory as the keystore.

Therefore we need to import the new public certificate into this trust store for Front End and Back End communication of WSO2 products to be properly happened over SSL.

Export the new public certificate with following command:
keytool -export -alias mycert -keystore mykeystore.jks -storepass mypkpassword -file mycert.pem
Above will export the public certificate into a file called mycert.pem in the same directory.

Now import it into client-truststore.jks with following command:
keytool -import -alias mynewcert -file mycert.pem -keystore client-truststore.jks -storepass wso2carbon
(Password of client-truststore.jks keystore is: wso2carbon)

4). Change the configuration files:

You need to locate and change the entries in the below elements of following configuration files which resides in [carbon_home]/repository/conf to point to the new keystore as highlighted below:

i. carbon.xml (Here we specify the keystore which is used by default for encrypting sensitive information to be stored and also for encryption/signature purposes in WS-Security)

 
${carbon.home}/repository/resources/security/mykeystore.jks 
JKS 
mypkpassword 
mycert 
mypkpassword 

ii. mgt-transports.xml (Here we specify the keystore which contains the public certificate to be fetched when accessing Management Console over SSL for all the WSO2 products and it is the same keystore which contains the certificate used when accessing services exposed over HTTPS as well, except for WSO2 ESB.)

 
${carbon.home}/repository/resources/security/mykeystore.jks 
 
mypkpassword

iii. axis2.xml (Only for WSO2 ESB) (WSO2 ESB uses different HTTPS transport sender and receiver for accessing the services exposed over HTTPS as below, and the keystore used for this purpose is specified in the following configuration)

 
8243 
true 
org.wso2.carbon.transport.nhttp.api.NHttpGetProcessor 
 
 
repository/resources/security/mykeystore.jks 
JKS 
mypkpassword 
mypkpassword 
 
 
 
 
repository/resources/security/client-truststore.jks 
JKS 
wso2carbon 
 
 


 
true 
 
 
repository/resources/security/mykeystore.jks 
JKS 
mypkpassword 
mypkpassword 
 
 
 
 
repository/resources/security/client-truststore.jks 
JKS 
wso2carbon