Encrypting Passwords

Encrypting passwords provides better security and less vulnerability to security attacks than saving passwords in plain text. It is recommended in a production setup. WSO2 API Manager provides a secure vault implementation that encrypts passwords, stores them in the registry, maps them to aliases and uses the alias instead of the actual passwords in configuration files. At runtime, the API Manager looks up aliases and decrypts the passwords. The secure vault is unable to encrypt the passwords of registry resources at the moment.

The steps below explain how to encrypt passwords in different contexts:

Encrypting passwords in configuration files

1. Shutdown the server if it is already running and open <APIM_HOME>/repository/conf/security/cipher-tool.properties file. It contains all the aliases to different server components.

2. Note that the file has several aliases already defined as the alias name and the value where the value is <file name>//<xpath to the property value to be secured>, <true if the XML element starts with a capital letter>. Uncomment the entries you want to encrypt.

   transports.https.keystorePass=mgt-transports.xml//transports/transport[@name='https']/parameter[@name='keystorePass'],false
   Carbon.Security.KeyStore.Password=carbon.xml//Server/Security/KeyStore/Password,true
   Carbon.Security.KeyStore.KeyPassword=carbon.xml//Server/Security/KeyStore/KeyPassword,true
   Carbon.Security.TrustStore.Password=carbon.xml//Server/Security/TrustStore/Password,true
   UserManager.AdminUser.Password=user-mgt.xml//UserManager/Realm/Configuration/AdminUser/Password,true
   Datasources.WSO2_CARBON_DB.Configuration.Password=master-datasources.xml//datasources-configuration/datasources/datasource[name='WSO2_CARBON_DB']/definition[@type='RDBMS']/configuration/password,false
   #Datasource.WSO2AM_DB.configuration.password=master-datasources.xml//datasources-configuration/datasources/datasource[name='WSO2AM_DB']/definition[@type='RDBMS']/configuration/password,false
   #Datasource.WSO2AM_STATS_DB.configuration.password=master-datasources.xml//datasources-configuration/datasources/datasource[name='WSO2AM_STATS_DB']/definition[@type='RDBMS']/configuration/password,false
   #UserStoreManager.Property.ConnectionPassword=user-mgt.xml//UserManager/Realm/UserStoreManager/Property[@name='ConnectionPassword'],true
   #UserStoreManager.Property.password=user-mgt.xml//UserManager/Realm/UserStoreManager/Property[@name='password'],true
   #AuthManager.Password=api-manager.xml//APIManager/AuthManager/Password,true
   
   ...

3. Open <APIM_HOME>/repository/conf/security/cipher-text.properties file, which maps the default alias to their plain text passwords in square brackets. Uncomment the ones you want.

   Carbon.Security.KeyStore.Password=[wso2carbon]

4. If you are on Linux or a Unix-based operating system, run the cipher tool available here.
   If you are on Windows, get the cipher tool from the <APIM_HOME>/bin folder. Due to a known issue in the 1.8.0 release on Linux, we provide the .sh file separately. This script reads the aliases, encrypts their plain-text passwords, and stores them in the secure vault. If you are using the default primary keystore, give wso2carbon as its password when prompted.

   Tip: By default, the primary keystore, which is <APIM_HOME>/repository/resources/security/wso2carbon.jks is used as the secure vault. If you want to use another keystore or a custom callback class to handle decryption, modify the <APIM_HOME>/repository/conf/security/secret-conf.properties file as described in Carbon Secure Vault Implementation in the WSO2 Carbon documentation.

   On Windows: ciphertool.bat -Dconfigure
   On Linux: sh ciphertool.sh -Dconfigure

5. Note that the configuration files are automatically updated with the relevant password alias after running the cipher tool. For example, as the Carbon.Security.KeyStore.Password property is uncommented in this example, after you run the cipher tool, the plain-text password in <APIM_HOME>/repository/conf/carbon.xml file will be replaced by the alias as follows.

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

   Tip: As you encrypted the primary keystore's password in this example, you are prompted to enter the primary keystore password every time you start the server.

   
   

Encrypting secure endpoint passwords

When creating an API using the API Publisher, you specify the endpoint of its backend implementation in the Implement tab. If you select the endpoint as secured, you are prompted to give credentials in plain-text.

The steps below show how to secure the endpoint's password that is given in plain-text in the UI.

1. Shut down the server if it is already running and set the element <EnableSecureVault> in <APIM_HOME>/repository/conf/api-manager.xml to true. By default, the system stores passwords in configuration files in plain text because this values is set to false. 
2. Define synapse property in the synapse.properties file as follows: synapse.xpath.func.extensions=org.wso2.carbon.mediation.security.vault.xpath.SecureVaultLookupXPathFunctionProvider.

3. Run the cipher tool available in <APIM_HOME>/bin. If on windows, the file is ciphertool.bat. If you are using the default keystore, give wso2carbon as the primary keystore password when prompted.

   sh ciphertool.sh -Dconfigure