Securely store and retrieve sensitive data in mediation

Photo by Markus Spiske on Unsplash

What is Secure Vault?

Secure vault helps users to store and retrieve sensitive data using aliases by improving the security aspect of the product. WSO2 products are shipped with the secure vault implementation which makes its users easier to incorporate this implementation whenever necessary.

Usage of encrypting data using secure vault and retrieve in mediation

This article describes how you can store sensitive information in WSO2 APIM using secure vault such that it would not be in a readable format, and retrieve those data for any mediation logic when making API requests.

Note: Before you continue, replace the existing org.wso2.ciphertool-1.0.0-wso2v8.jar with this jar.

Configure Secure Vault With APIM

• Encrypt the passwords in the configurations files using cipher tool.
• In order to do that you need to run the following command from <APIM_HOME>/bin directory

./ciphertool -Dconfigure

• You will be prompted the above to enter the primary keystore password, which is wso2carbon by default.
• After that, you will see encryption successfully happened.

• Now let’s start the server using ./wso2server.sh . Again, you will be prompted to enter the primary keystore password to decrypt the password during the server startup. Once you enter the password, the server will be successfully up and running.

Encrypt the data/value using Cipher tool

• Go to <APIM_HOME>/bin directory and execute the following command.

./ciphertool.sh -Dorg.wso2.CipherTransformation=RSA/ECB/OAEPwithSHA1andMGF1Padding

Very important: DO NOT USE “-Dconfigure” and
“-Dorg.wso2.CipherTransformation=RSA/ECB/OAEPwithSHA1andMGF1Padding” in the
same command ( eg: ./ciphertool.sh
-Dorg.wso2.CipherTransformation= RSA/ECB/OAEPwithSHA1andMGF1Padding
-Dconfigure)

• User will be prompted to enter the primary keystore password followed by an entry to enter the value to be encrypted as depicts in the following diagram.

• Copy the encrypted value into the clipboard.
• Log into carbon console. (https://{host}/carbon)
• Add the copied value as a property in
  /_system/config/repository/components/secure-vault location providing an alias (eg: “sample.password” as the alias).

Now you have successfully stores the password (or relevant property) in an encrypted format.

How to retrieve these values in mediation logic?

1. If you are writing the mediation logic in the form of an xml file using synapse, using “ {wso2:vault-lookup('alias')}” will retrieve the property.

• According to the above example, you can include something similar to the following in mediation logic.

<Password>{wso2:vault-lookup('sample.Password')}</Password>

2. If you are writing a class mediator using Java, the following code segment will help you to retrieve the corresponding value.

Following the steps properly, you will be able to achieve the encryption of values and retrieve them in the mediation as expected.