Secure Vault Implementation for WSO2 EI

Nipuna Dilhara
2 min readJul 1, 2019

--

If you are familiar with WSO2 products, you might already have noticed that WSO2 configuration files contain the hard-coded credentials in various places. Ever wondered why they are left like that which might cause a security threat?

One simple mechanism that comes with all the WSO2 products to overcome this vulnerability is called Secure Vault implementation. It’s an extended version of synapse Secure Vault and hence it has been inherited to WSO2 Carbon platform. This particular feature simply allows us to replace the real password with an alias and then this alias will be mapped with the encrypted version of the real password inside the Secure Vault. Sounds confusing?? I hope that all doubts will be cleared by the end of the post.

Before going any further let’s consider a simple example.

The user-mgt.xml which resides at <EI_HOME>/conf folder contains the password of the Admin User which is ‘admin’. Using the secure vault, this can be replaced by an alias such as UserManager.AdminUser.Password and the encrypted version of the real password will go to Secure Vault. During the runtime, the WSO2 product will check this alias in Secure Vault and decrypt the corresponding password.

The entire Secure Vault implementation mainly based on three files.

  • cipher-tool.properties
  • cipher-text.properties
  • cipher-tool.sh

Following are the summarized steps to make it work.

Step 1: Open the cipher-tool.properties file resides in the <EI_HOME>/conf/security folder and adds the file name and the XPath of the password which you wants to be encrypted in the following format.

<alias>=<file_name>//<xpath>,<true/false>
  • <alias>: The value which is going to replace the hard-coded password.
    ex: UserManager.AdminUser.Password
  • <file_name>: The file name of the configuration file where the password resides.
    ex: repository/conf/user-mgt.xml
  • <xpath>: XPath to the password in the configuration file
    ex: UserManager/Realm/Configuration/AdminUser/Password
  • <true, false>: Use value ‘false’ if you are encrypting the value of an XML element, or the value of an XML attribute’s tag. Use the value ‘true’ if you are encrypting the tag of an XML attribute.

ex:
UserManager.AdminUser.Password=repository/conf/user-mgt.xml//UserManager/Realm/Configuration/AdminUser/Password,false

Step2: Open the cipher-text.properties file (<EI_HOME>/conf/security) and adds the alias and the corresponding plaintext password.

<alias>=[plain_text_password]

ex: UserManager.AdminUser.Password=[admin]

Step 3. Run the cipher-tool.sh file (<EI_HOME>/bin) by using the ‘./ciphertool.sh -Dconfigure’ command.

That’s it !!! You will see the original password has been replaced by an alias in the configuration file and the encrypted password appearing in the cipher-text.properties file with the corresponding alias.

Please feel free to comment out any doubts regarding this procedure. Your thoughts will be highly appreciated.

References:

--

--