Enabling Cipher Tool for Password Encryption

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 install the Cipher Tool feature when building a product.

Cipher Tool consists of the following files:

org.wso2.ciphertool-1.0.0-wso2v3.jar: This is the JAR of the Cipher Tool.
ciphertool.bat: The script for running the tool on Windows.
ciphertool.sh: The script for running the tool on Linux.
cipher-tool.properties: This file contains the secret alias, file and the xpath of the sensitive data that should be encrypted. In the case of WSO2 products, the default file that is shipped with a pack should contain the sensitive data in the file system of that particular product.
cipher-text.properties: This file contains the secret aliases with the encrypted values. In the case of WSO2 products, the default file that is shipped with a pack should contain the data relevant to the respective product.
cipher-standalone-config.properties: This file contains the configurations for non-WSO2 environments.

You can find the source code of Cipher Tool here.

See the following topics:

Enabling Cipher Tool for WSO2 products

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. Given below are the instructions for installing the Cipher Tool feature in a WSO2 product using the pom.xml.

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

<featureArtifacts>
......
   <featureArtifactDef>org.wso2.ciphertool:org.wso2.ciphertool.feature:${cipher.tool.version}</featureArtifactDef>
</featureArtifacts>

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

<execution>
  .....
    <configuration>
      <profile>default</profile>
        .......
        <features>
			.......
			<feature>
   			<id>org.wso2.ciphertool.feature.group</id>
   			<version>${cipher.tool.version}</version>
			</feature>
        </features>
    </configuration>
</execution>

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:

files>
    .........
    <!-- Cipher Tool Files -->
    <file>
<source>../p2-profile-gen/target/wso2carbon-core-${carbon.kernel.version}/bin/ciphertool.sh</source>
<outputDirectory>${pom.artifactId}-${pom.version}/bin</outputDirectory>
<fileMode>755</fileMode>
    </file>
    <file>
<source>../p2-profile-gen/target/wso2carbon-core-${carbon.kernel.version}/bin/ciphertool.bat</source>
<outputDirectory>${pom.artifactId}-${pom.version}/bin</outputDirectory>
    </file>
    <file>
<source>../p2-profile-gen/target/wso2carbon-core-${carbon.kernel.version}/lib/org.wso2.ciphertool-${cipher.tool.version}.jar</source>
<outputDirectory>${pom.artifactId}-${pom.version}/lib</outputDirectory>
    </file>
</files>

Now you must create the cipher-tool.properties and cipher-text.properties 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 cipher-tool.properties and cipher-text.properties files that are created for Carbon Kernel.

Sample cipher-text.properties:

# 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.

Carbon.Security.KeyStore.Password=[wso2carbon]
Carbon.Security.KeyStore.KeyPassword=[wso2carbon]
Carbon.Security.TrustStore.Password=[wso2carbon]
UserManager.AdminUser.Password=[admin]
Datasources.WSO2_CARBON_DB.Configuration.Password=[wso2carbon]
Server.Service.Connector.keystorePass=[wso2carbon]

Sample cipher-tool.properties:

# 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"

Carbon.Security.KeyStore.Password=repository/conf/carbon.xml//Server/Security/KeyStore/Password,false
Carbon.Security.KeyStore.KeyPassword=repository/conf/carbon.xml//Server/Security/KeyStore/KeyPassword,false
Carbon.Security.TrustStore.Password=repository/conf/carbon.xml//Server/Security/TrustStore/Password,false
UserManager.AdminUser.Password=repository/conf/user-mgt.xml//UserManager/Realm/Configuration/AdminUser/Password,false
Datasources.WSO2_CARBON_DB.Configuration.Password=repository/conf/datasources/master-datasources.xml//datasources-configuration/datasources/datasource[name='WSO2_CARBON_DB']/definition[@type='RDBMS']/configuration/password,false
Server.Service.Connector.keystorePass=repository/conf/tomcat/catalina-server.xml//Server/Service/Connector[@keystorePass],true

Note the following when you update the cipher-tool.properties file:

For Carbon 4.4.x, you will be using a new version of the Cipher tool (1.0.0-wso2v3). This new version provides the capability of encrypting passwords that are specified as property values as well as attribute values in configuration files. Consider the following examples:

A password specified as a property value: <Property name="ConnectionPassword">admin</Property>
A password specified as an attribute value: <Connector protocol="org.apache.coyote.http11.Http11NioProtocol" password="wso2carbon" />

Note that with the previous version of the Cipher tool (1.0.0-wso2v2), which was valid for Carbon 4.2.0, it was only possible to encrypt property values.

With the new Cipher tool for Carbon 4.4.x, when you set the xpath to the password you want to encrypt, you need to use the 'true/false' setting depending on whether the password is defined as a property value or an attribute value. For property values, the xpath should be followed by 'false' and for attribute values, the xpath should be followed by 'true'. Consider the following examples from the cipher-tool.properties file in Carbon Kernel:

configuration/datasources/datasource[name='WSO2_CARBON_DB']/definition[@type='RDBMS']/configuration/password,false
Server.Service.Connector.keystorePass=repository/conf/tomcat/catalina-server.xml//Server/Service/Connector[@keystorePass],true

If you have developed your WSO2 product with the configurations given above, the Cipher Tool feature will be installed. Alternatively, you can also install this feature using the management console of a Carbon product. See the following topics for more information:

Installing Features: This topic explains how to install features to a WSO2 product from the feature repository.
Securing Passwords in Configuration Files: This topic explains how Cipher Tool is used for data encryption in WSO2 products.

Enabling Cipher Tool for non-WSO2 environments

The cipher tool can only encrypt the password. Therefore in a non-WSO2 environment, the decrypting code needs to be written. Follow the steps given below to configure and run Cipher Tool.

Download the latest released org.wso2.ciphertool-{version}.jar from the nexus repository.
Copy the following configuration files from Github to a folder called “conf” where your Cipher Tool Jar is placed:

cipher-tool.properties
cipher-text.properties
cipher-standalone-config.properties

Now, you must update the cipher-text.properties and the cipher-tool.properties files with information on the configuration files and the passwords that you want to encrypt.
- Update the cipher-tool.properties file with the location of the file (this can be the absolute path or the relative path from the .jar file) and the XPath of the value to be encrypted.
- The cipher-text.properties file should contains the secret aliases with the encrypted values.
Update the cipher-standalone-config.properties file. This file is used in a non-WSO2 environment to get the location of the Keystore, the Keystore type, Key alias, location of the cipher-tool.properties and cipher-text.properties. In this case, Cipher Tool also returns the file name (along with the path) where it should create the sercet-conf.properties file.
To run the tool, execute the following command:
```
java -jar org.wso2.ciphertool-1.0.0-wso2v3.jar
```