[Download] | [Documentation Home] | [Release Note]

Change the WSO2 AppServer Crypto Keys

WSO2 AppServer uses a key pair to enable HTTPS and to secure the user passwords within it. You can find the default keystore and the client trust store in CARBON_HOME/repository/resources/security folder.

When you use WSO2 AppServer in production, it is strongly recommended that you change the default keys that are shipped with it.

Using the JDK keytool utility to create a keystore

It should be noted that the RSA algorithm must be used to generate the keypair. For example..

$ keytool -genkey -alias wso2appserver -keyalg RSA -keystore wso2appserver.jks -storepass wso2appserver

This will prompt a series of questions as shown below:

What is your first and last name?
  [Unknown]:  John Smith
What is the name of your organizational unit?
  [Unknown]:  Accounts
What is the name of your organization?
  [Unknown]:  ABC
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=John Smith, OU=Accounts, O=ABC, L=Colombo, ST=Western, C=LK correct?
  [no]:  yes

Enter key password for <tungsten>
    (RETURN if same as keystore password):

Now you will see a file with the name "wso2appserver.jks" created in the location from which you executed the above command.

Keystore management is a feature which is inherited from the WSO2 Carbon platform. WSO2 Carbon uses the keystores to secure passwords and to enable HTTPS.

Using your new keystore to secure user passwords and other sensitive information

You can use your new keystore for this purpose by pointing your keystore from the "Security" section of the CARBON_HOME/repository/conf/carbon.xml file as follows.

        <KeyStore>
            <!-- Keystore file location-->
            <Location>${carbon.home}/repository/resources/security/wso2appserver.jks</Location>
            <!-- Keystore type (JKS/PKCS12 etc.)-->
            <Type>JKS</Type>
            <!-- Keystore password-->
            <Password>wso2appserver</Password>
            <!-- Private Key alias-->
            <KeyAlias>wso2appserver</KeyAlias>
            <!-- Private Key password-->
            <KeyPassword>wso2appserver</KeyPassword>
        </KeyStore>
    

Using your new keystore to enable HTTPS

If you want to use your new keystore for this purpose, first you have to import your SSL certificates into your new keystore. Please refer to the above article for more information on how to do it.

Standalone Mode

When WSO2 AppServer is running in the standalone mode, you have to refer your keystore from CARBON_HOME/repository/conf/mgt-transports.xml file. Set the following parameters in the "https" transport configuration.

        <parameter name="keystoreFile">
            ${carbon.home}/repository/resources/security/wso2appserver.jks
        </parameter>
        <parameter name="keystorePass">wso2appserver</parameter>
    

Running in a Servlet Container

JBoss application server

  • Update the "SSL/TLS Connector configuration" section of the jboss_home/server/default/deploy/jbossweb-tomcat50.sar/server.xml
    • Full path to the keystore - keystoreFile
    • Keystore password - keystorePass

Apache Tomcat server

  • Update the "Define a non-SSL HTTP/1.1 Connector on port 9443" section of the catalina_home/conf/server.xml
    • Full path to the keystore - keystoreFile
    • Keystore password - keystorePass

If you have any further questions on this, please post to carbon-dev@wso2.org.