Working with Encrypted Passwords

All WSO2 products are shipped with a Secure Vault implementation that allows you to store encrypted passwords that are mapped to aliases. This approach allows you to use the aliases instead of the actual passwords in your configurations for better security. For example, some configurations require the admin username and password. If the admin user's password is "admin", you could use UserManager.AdminUser.Password as the password alias. You will then map that alias to the actual "admin" password using Secure Vault. The WSO2 product will then look up this alias in Secure Vault during runtime, decrypt and use its password.

In all WSO2 products, Secure Vault is commonly used for encrypting passwords and other sensitive information in configuration files. When you use WSO2 API-M, you can encrypt sensitive information contained in synapse configurations (i.e., mediation flow) in addition to the information in configuration files. For more information, see the following topics:

Encrypting passwords in configuration files

To encrypt passwords in configuration files, you simply have to update the cipher-text.properties and cipher-tool.properties files that are stored in the <API-M_HOME>/conf/security directory and then run the Cipher tool that is shipped with the product. Go to the links given below to see instructions in the WSO2 administration guide:

• Encrypting passwords using the automated process.
• Encrypting passwords using the manual process.
  The manual encryption process is relevant when the location of the configuration files, which contain the elements to be encrypted, cannot be specified using an xpath in the cipher -tool.properties file. The log4j.properties file and jndi.properties file are two such files which require the manual password encryption process.
• Changing already encrypted passwords.
• Resolving already encrypted passwords.

Encrypting passwords for mediation flow

The WSO2 API-M provides a UI that can be used for encrypting passwords and other sensitive information in synapse configurations. Follow the steps below.

1. If you are using the Cipher tool for the first time in your environment, you must first enable the Cipher tool by executing the -Dconfigure command with the cipher tool script: 
   Note that the cipher tool uses the RSA encryption algorithm by default.

   1. Open a terminal and navigate to the <API-M_HOME>/bin directory.

   2. Execute one of the following commands to start the cipher tool:

      Do not combine the following commands and run them as a single command.

      • To use the cipher tool with the RSA encryption algorithm.

        • On Linux: ./ciphertool.sh -Dconfigure

        • On Windows: ./ciphertool.bat -Dconfigure
If you are using the Cipher tool for the first time, this command first initializes the tool for your product.

      • To use the cipher tool with any other encryption algorithm.

        • Support for any encryption algorithm other than RSA with the cipher tool is not supported out-of-the-box.

        • You need to get the latest product updates for your product to use this feature in the current version of WSO2 API-M. This feature is available as a product update from August 26, 2019 onwards.

          Note that you can deploy updates in a production environment only if you have a valid subscription with WSO2. Read more about WSO2 Updates.

        <encryption-algorithm> - Make sure that the algorithm mentioned in the <API-M_HOME>/repository/conf/carbon.properties  file is the same as the value given when starting the cipher tool. Example:  RSA/ECB/OAEPwithSHA1andMGF1Padding

        • On Linux: ./ciphertool.sh -Dorg.wso2.CipherTransformation=<encryption-algorithm>

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

        • On Windows: ./ciphertool.bat -Dorg.wso2.CipherTransformation=<encryption-algorithm>

2. When prompted, enter the primary key password, which is by default wso2carbon. 
   Enter the password and proceed.

3. When prompted, enter the plain text password that you want to encrypt. 
   Enter the following element as the password and proceed.

   Enter Plain Text Value :admin

   Now, you will receive the encrypted value.

   Example

   Encrypted value is: 
   gaMpTzAccMScaHllsZLXspm1i4HLI0M/srL5pB8jyknRKQ2zT7NuCvt1+qEkElRLgwlrohz3lkuE0KFuapXrCSs5pxfGMOLn4/k7dNs2SlwbsG8C++/
   ZfUuft1Sl6cqvDRM55fQwzCPfybl713HvKu3oDaJ9VKgSbvHlQj6zqzg=

4. Start WSO2 API-M and sign in to the management console:
   1. Open a terminal and navigate to the <API-M_HOME>/bin directory.
   2. Execute one of the following scripts:
      • On Windows: wso2server.bat --run
      • On Linux/Mac OS: sh wso2server.sh
   3. Sign in to the management console.
      https://<server-host>:9443/carbon

5. Select Browse under Resources to access the registry browser and go to the  /_system/config/repository/ components/secure-vault location.

6. Add the aliases and the encrypted value as a property.

<APIManager xmlns:svns="http://org.wso2.securevault/configuration">
	<DataSourceName>jdbc/WSO2AM_DB</DataSourceName>
	<GatewayType>Synapse</GatewayType>
	<EnableSecureVault>false</EnableSecureVault>
	<AuthManager>
		<ServerURL>https://localhost:${mgt.transport.https.port}${carbon.context}services/</ServerURL>
		<Username>${admin.username}</Username>
		<Password>${admin.password}</Password>
		.
		.
</APIManager>

ThrottlingConfigurations.DataPublisher.Password 
ThrottlingConfigurations.PolicyDeployer.Password
ThrottlingConfigurations.JMSConnectionDetails.Password
Analytics.DASPassword.
Analytics.DASRestApiPassword

Using encrypted passwords in mediation flow

To use the alias of an encrypted password in a mediation flow, you need to add the {wso2:vault-lookup('alias')}custom path expression when you define the mediation flow. For example, instead of hard coding the admin user's password as <Password>admin</Password>, you can encrypt and store the password using the AdminUser.Password alias as follows: <Password>{wso2:vault-lookup('AdminUser.Password')}</Password>.

This password in the mediation flow can now be retrieved by using the  {wso2:vault-lookup('alias')} custom path expression to logically reference the password mapping.