This documentation is for WSO2 Carbon 4.4.3. View documentation for the latest release.
Page Comparison - Enabling Cipher Tool for Password Encryption (v.7 vs v.8) - Carbon 4.4.3 - WSO2 Documentation

Versions Compared

Key

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

...

  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
    <featureArtifacts>
    ......
       <featureArtifactDef>org.wso2.ciphertool:org.wso2.ciphertool.feature:${cipher.tool.version}</featureArtifactDef>
    </featureArtifacts> 
  2. Under the "default" profile, the Cipher Tool feature ID needs to be added as given below:

    Code Block
    <execution>
      .....
        <configuration>
          <profile>default</profile>
            .......
            <features>
    			.......
    			<feature>
       			<id>org.wso2.ciphertool.feature.group</id>
       			<version>${cipher.tool.version}</version>
    			</feature>
            </features>
        </configuration>
    </execution> 
  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
    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>
  4. 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:

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

    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"
    
    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
    titleNote 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. 

    Therefore, in 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 given abovein Carbon Kernel:

    Code Block
    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

...