This documentation is for WSO2 Carbon 4.2.0. View documentation for the latest release.
Page Comparison - Configuring Keystores in WSO2 Products (v.54 vs v.69) - Carbon 4.2.0 - WSO2 Documentation

Versions Compared


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

WSO2 Carbon uses several keystores to power the servlet transport and to encrypt other confidential information such as administrator passwords. The carbon.xml file in the <PRODUCTAfter you have created a new keystore and updated the client-truststore.jks file, you must update a few configuration files in order to make the keystore 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 specific 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  keystore 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 navigate to the <PRODUCT_HOME>/repository/conf/ directory


  1. where your product



The default keystore named wso2carbon.jks can be found in the <PRODUCT_HOME>/repository/resources/security directory of your product pack.


Note that when keystores are configured, two keystore passwords are specified in the relevant .xml file:

  • The <Password> element indicates the password of the keystore file.
  • The <KeyPassword> element points to the password required to access the private key.

Table of Contents

Primary Keystore


  1. stores all configuration files.
  2. Execute the following command: grep -nr ".jks" .

The configuration files and the keystore files referred to in each file are listed out. See an example of this 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>

Configuring the primary keystore

The primary keystore mainly stores the keys certifying SSL connections to Carbon servers and the keys for encrypting administrator passwords as well as other confidential information. The  The Keystore element  element in the the carbon.xml file is used to configure  file, stored in the < PRODUCT_HOME>/repository/conf/ directory must be updated with details of the primary keystore as given below. Note that in this example, the default keystore in your product pack (wso2carbon.jks) is used as the primary keystore.. The default configuration is shown below. 

Code Block

Registry Keystore

RegistryKeyStore is a separate keystore element configurable in the carbon.xml file. This configuration applies for the keystore which stores the keys that certify encrypting/decrypting meta data to the registry. Therefore, using the registry keystore in addition to the primary keystore in the carbon.xml file allows you to maintain a separate keystore for the purpose of encrypting/decrypting meta data to the registry. The registry keystore configuration which needs to be added in the carbon.xml file is as given bellow. Note that in this example, we are referring to the default keystore in the product pack (wso2carbon.jks) as the registry keystore.

Code Block
            <!-- Keystore file location-->
	<!-- 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 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. For example in BAM:

  Product-specific configurations

  • Make the following changes in the <PRODUCT_HOME>/repository/conf/identity.xml file.

    Code Block
    			<!-- Keystore password -->
    			<!-- Private Key password -->
  • <jks name>.jks</Location>
    			<Password><jks store password></Password>
  • If you want to use NIO sender, change the  <transportSender> section in the <PRODUCT_HOME>/repository/conf/axis2/axis2.xml file accordingly as shown below.

    Code Block
    <transportSender name="https" class="org.apache.synapse.transport.nhttp.HttpCoreNIOSSLSender">
<!-- Keystore type (JKS/PKCS12 etc.)-->
  • <parameter name="non-blocking" locked="false">true</parameter>
            <parameter name="keystore" locked="false">
<!-- Keystore password-->
  •                 <KeyPassword>wso2carbon</KeyPassword>
            <parameter name="truststore" locked="false">
<!-- Private Key alias-->
  • <Location>repository/resources/security/client-truststore.jks</Location>
  • <Type>JKS</Type>
<!-- Private Key password-->
  •          </TrustStore>
  • </
  • parameter>
  • transportSender>