This documentation is for WSO2 Carbon 4.4.1. View documentation for the latest release.
Page Comparison - Configuring Keystores in WSO2 Products (v.23 vs v.24) - Carbon 4.3.0 - WSO2 Documentation
Due to a known issue do not use JDK1.8.0_151 with WSO2 products. Use JDK 1.8.0_144 until JDK 1.8.0_162-ea is released.

Versions Compared


  • This line was added.
  • This line was removed.
  • Formatting was changed.

Include PageShared:Configuring Keystores in WSO2 Products (Carbon 4.3.0)Shared:Configuring Keystores in WSO2 Products (Carbon 4.3.0)After you have created a new keystore and updated the client-truststore.jks file, you must update a few configuration files in order to make it work. Note that keystores are used for multiple functions in WSO2 products, which includes securing the servlet transport, encrypting confidential information in configuration files etc. Therefore, you must update the relevant configuration files with the relevant keystore information. For example, you may have separate keystores for the purpose of encrypting passwords in configuration files, and for securing the servlet transport.

The wso2carbon.jks kestore file, which is shipped with all WSO2 products, is used as the default keystore for all functions. However, in a production environment, it is recommended to create new keystores with keys and certificates.


If you want an easy way to locate all the configuration files that have references to keystores, you can use the grep command as follows:

  1. Open a command prompt and go to the <PRODUCT_HOME>/repository/conf/ directory where your product stores all configuration files.
  2. Execute the following command: grep -nr ".jks" .

You will now get a list of configuration files and the list of keystore files that are referred to in each file. See the example below.

Code Block
./axis2/axis2.xml:260:                <Location>repository/resources/security/wso2carbon.jks</Location>
./axis2/axis2.xml:431:                <Location>repository/resources/security/wso2carbon.jks</Location>
./carbon.xml:316:            <Location>${carbon.home}/repository/resources/security/wso2carbon.jks</Location>
./carbon.xml:332:            <Location>${carbon.home}/repository/resources/security/wso2carbon.jks</Location>
./identity.xml:180:				<Location>${carbon.home}/repository/resources/security/wso2carbon.jks</Location>

You can update the relevant configuration files as follows: 

Table of Contents

Configuring the primary keystore

The primary keystore mainly stores the keys for encrypting administrator passwords as well as other confidential information. The Keystore element in the carbon.xml file, stored in the < PRODUCT_HOME>/repository/conf/ directory should be updated with details of the primary keystore. The default configuration is shown below.

Code Block
	<!-- trust-store file location -->
	<!-- trust-store type (JKS/PKCS12 etc.) -->
	<!-- trust-store password -->

You need to add in the following information:

  • <jks store password>
  • <jks alias>
  • <jks store password(same as the key password)>

Configuring Secure Vault for password encryption

All passwords in configuration files are made secure by encrypting them using cipher text. When a password is encrypted, a keystore is required for creating the decryption crypto to resolve encrypted secret values. The file, stored in the <PRODUCT_HOME>/repository/conf/security/ directory is used for this purpose. Therefore, you must update this file with the relevant keystore information.

Code Block
##KeyStores configurations
#keystore.identity.alias=wso2carbon<any implementation of>
##keystore.identity.key.secretProvider=<any implementation of>
#<any implementation of>

Configuring a keystore for SSL connections

The catalina-server.xml file stored in the <PRODUCT_HOME>/repository/conf/tomcat/ directory should be updated with the keystore used for certifying SSL connections to Carbon servers. Given below is the default configuration in the catalina-server.xml file, which points to the default keystore in your product.

Code Block

Configuring a keystore for Java permissions

The sec.policy file stored in the <PRODUCT_HOME>/repository/conf/ directory should be updated with details of the keystore used for enabling Java permissions for your server. The default configuration is shown below.

Code Block
keystore "file:${user.dir}/repository/resources/security/wso2carbon.jks", "JKS";

NOTE to WRITERS: The following section can be used to list down product specific configuration files that use keystores.

Product-specific configurations

  • For Carbon documentation:

    Configuring keystores for WS-Security

    If there are WS-Security scenarios implemented in your WSO2 product, you can use separate keystores for these scenarios.

    Configuring keystores for advanced transport handling

    To have more advanced transport handling functions using keystores, you need to update the <PRODUCT_HOME>/repository/conf/tomcat/catalina-server.xml file and the <PRODUCT_HOME>/reposotory/conf/axis2/axis2.xml file.