Monday, February 15, 2016

Configuring Secure Vault in WSO2 ESB 4.9.0 and WSO2 GREG 4.6.0

Configuring Secure Vault in WSO2 ESB 4.9.0

WSO2 ESB 4.9.0 is the current latest version of the ESB based on carbon 4.4.0. Guide in [1] gives instructions to configure secure vault in an environment.

Following files contains the relevant configuration needed for the passwords that need to be encrypted. These files are located under ESB_HOME/repository/conf/security directory

  • cipher-tool.properties - This file contains the alias set that needed to will be used as the references for the passwords in each configuration file along with xpath expression specifying the configuration file location along with the location of the password.Sample cipher-tool.properties file content can be find below. Boolean value at the end of each alias indicate whether property is within a xml attribute or xml tag value. If the password in a xml tag the value will be false else it will be true.

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
Axis2.Https.Listener.TrustStore.Password=repository/conf/axis2/axis2.xml//axisconfig/transportReceiver[@name='https']/parameter[@name='truststore']/TrustStore/Password,false
Axis2.Https.Listener.KeyStore.Password=repository/conf/axis2/axis2.xml//axisconfig/transportReceiver[@name='https']/parameter[@name='keystore']/KeyStore/Password,false
Axis2.Https.Listener.KeyStore.KeyPassword=repository/conf/axis2/axis2.xml//axisconfig/transportReceiver[@name='https']/parameter[@name='keystore']/KeyStore/KeyPassword,false
Axis2.Https.Sender.TrustStore.Password=repository/conf/axis2/axis2.xml//axisconfig/transportSender[@name='https']/parameter[@name='truststore']/TrustStore/Password,false
Axis2.Https.Sender.KeyStore.Password=repository/conf/axis2/axis2.xml//axisconfig/transportSender[@name='https']/parameter[@name='keystore']/KeyStore/Password,false
Axis2.Https.Sender.KeyStore.KeyPassword=repository/conf/axis2/axis2.xml//axisconfig/transportSender[@name='https']/parameter[@name='keystore']/KeyStore/KeyPassword,false
Axis2.Mailto.Parameter.Password=repository/conf/axis2/axis2.xml//axisconfig/transportSender[@name='mailto']/parameter[@name='mail.smtp.password'],false



  • cipher-text.properties - This file contains the alias for the password in each configuration with the current password within square brackets. After properly configuring the secure vault, these values will be encrypted. Sample cipher-text.properties file content before the encryption can be find as below.

Axis2.Https.Sender.TrustStore.Password=[wso2carbon]
Axis2.Https.Sender.KeyStore.KeyPassword=[wso2carbon]
Axis2.Https.Sender.KeyStore.Password=[wso2carbon]
Axis2.Https.Listener.TrustStore.Password=[wso2carbon]
Datasources.WSO2_CARBON_DB.Configuration.Password=[wso2carbon]
UserManager.AdminUser.Password=[admin]
Axis2.Mailto.Parameter.Password=[wso2carbon]
Carbon.Security.KeyStore.Password=[wso2carbon]
Axis2.Https.Listener.KeyStore.Password=[wso2carbon]
Carbon.Security.KeyStore.KeyPassword=[wso2carbon]
Carbon.Security.TrustStore.Password=[wso2carbon]
Axis2.Https.Listener.KeyStore.KeyPassword=[wso2carbon]
Server.Service.Connector.keystorePass=[wso2carbon]

Note : Change the passwords to actual values
Step 1

After successfully configuring these files following command need to be executed within ESB_HOME/bin folder.

./ciphertool.sh -Dconfigure

After executing above command, passwords locations that specified in the cipher-tool.properties will be converted as follow. The secretAlias is there to identify the password that need to be replaced for that particular xml tag value.

<Password svns:secretAlias="Carbon.Security.KeyStore.Password">password</Password>

All the passwords that specified in the cipher-text.properties will be encrypted.



Step 2

After configure the secure vault, at the server startup it’s required to provide the carbon keystore password as it will be used to decrypt the passwords of the configurations using the private key.

IMPORTANT : Default server startup with ./wso2server.sh will ask to provide the password in the terminal. If the server startup as a service using ./wso2server.sh start or nohup, it’s required to create file named password-tmp file inside the ESB_HOME directory and include the keystore password. This file will be deleted after reading the keystore password. Refer [2] for more details.

Changing Existing Password

If it required to change the password of some configuration, it can be done by replacing the new password within square brackets again in the cipher-text.properties. After configuring the new password, it’s required to restart the server with following Step 1 and Step 2 mentioned in above.

NOTE : In previous versions, there is a option to change password with the command ./ciphertool.sh -Dchange. But it’s not working in this ESB version which is a known issue.

Adding new password for encryption

To add a new entry in a configuration file to encrypt, it’s required to configure cipher-text.properties and cipher-tool.properties configuration reppectively. First a unique alias with the location of configuration file and the location of the property file should be specified as a xpath as in previous values. Then current password should be specified within the brackets against the new alias. After properly configure these files, it’s required to restart the server by following Step 1 and Step 2.

Configuring Secure Vault in WSO2 GREG 4.6.0

Configuring the secure vault in GREG can be achieved by following the same steps mentioned in the above section. WSO2 GREG 4.6.0 is based on carbon 4.2.0. Hence some instructions can be slightly varied. More information about configuring the secure vault in GREG can be found in [3]. It’s required to properly configure the necessary entries that indicate which passwords need to be encrypted which is specific to GREG in cipher-text.properties and cipher-tool.properties files.

NOTE: To change existing password, ./ciphertool.sh -Dchange can be used with GREG 4.6.0. More information can be found in [4]. It’s required to restart the server once the password has changed. Steps to restart the server is same with the instructions specified for the ESB.

Securing passwords in synapse configurations

It’s required to configure the secure vault before encrypting the passwords in synapse configurations. After that, following blogpost in [5] can be followed to encrypt the password in the synapse configurations.


[3] https://docs.wso2.com/display/Carbon420/Securing+Passwords+in+Configuration+Files
[4] https://docs.wso2.com/display/Carbon420/Encrypting+Passwords+with+Cipher+Tool

[5] - http://nirodhawrites.blogspot.com.es/2015/10/wso2-esb-using-secure-vault-to-store.html

No comments:

Post a Comment