This documentation is for WSO2 Carbon 4.4.1. View documentation for the latest release.
Page Comparison - Enabling Cipher Tool for Password Encryption (v.2 vs v.3) - Carbon 4.4.1 - 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.

Cipher Tool is developed by WSO2 for encrypting sensitive data in files stored in a file system. Thereby, Cipher Tool can be used in WSO2 products as well as in non-WSO2 environments. However, in order to use the Cipher Tool in a WSO2 product or any other environment, product developers must ensure that Cipher Tool is enabled in the respective product build. The instructions on this page explain how developers can enable install the Cipher Tool feature when building a product.

 Cipher Tool consists of the following files:


WSO2 products use the Cipher Tool for encrypting passwords in configuration files. The tool uses the Secure Vault implementation that is built into Carbon. Cipher Tool is available as a separate feature that can be installed in each product. However, in order to install this feature, the product has to be built using the following configurations:Given below are the instructions for installing the Cipher Tool feature in a WSO2 product using the pom.xml. 

  1. In the pom.xml of the p2-profile-gen, the Cipher Tool features needs to be added under <featureArtifacts> as given below.

    Code Block
  2. Under the "default" profile, the Cipher Tool feature ID needs to be added as given below:

    Code Block
  3. In the bin.xml (in distribution), the location in the product pack to which the Cipher Tool Jar and its configuration files should be copied is mentioned as given below. Note that ${cipher.tool.version} refers to the Cipher Tool version:

    Code Block
        <!-- Cipher Tool Files -->
  4. Now you must create the and files for your product and store them in the <PRODUCT_HOME>/repsoistory/conf/security directory. Note that these two files are always product specific. This is because the type and number of passwords in configuration files that require encryption may be different in each product. Therefore, each product team should create these files with the information that is relevant to the product. For example, shown below are the and files that are created for Carbon Kernel.


    Code Block
    # By default, This file contains the secret alias names and the plain text passwords enclosed with '[]' brackets
    # In Production environments, It is recommend to replace these plain text password by the encrypted values. CipherTool can be used for it.


    Code Block
    # Important: This properties file contains all the aliases to be used in carbon components. If any property need to be secured, you need to add alias name, file name and the xpath as follows:.
    # The value goes as, the <file_name>//<xpath>,<true/false>
    # where <file_name> - is the file (along with the file path) to be secured,
    #       <xpath> - is the xpath to the property value to be secured
    #       <true / false> - This is true if the last parameter in the xpath is parameter (starts with [ and ends with ]) and you want its value to be replaced with "password"

If you have developed your WSO2 product with the configurations given above, users of the product Cipher Tool feature will be able to install the Cipher Tool feature and use it for encrypting passwords in configuration filesinstalled. Alternatively, you can also install this feature using the management console of a Carbon product. See the following topics for more information: