WSO2 6 min

WSO2TORIAL: Encrypt passwords using Secure Vault

Jan Timmerman
WSO2 Integration Consultant
27 aug no 1

In this episode of our WSO2 tutorialWSO2 products use configuration files to store all kinds of settings. This includes the administrator password in the user-mgt.xml file. If you want to use WSO2 beyond the test phase, this is one of the things that we recommend you need to change.

WSO2 products use configuration files to store all kinds of settings. This includes the administrator password in the user-mgt.xml file. If you want to use WSO2 beyond the test phase, this is one of the things that we recommend you need to change.

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 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 WSO2 product looks up aliases and decrypts the passwords.

Please note that the secure vault is unable to encrypt the passwords of registry resources at the moment.


Figure 1 the admin password in user-mgt.xml

Luckily, WSO2 (or rather WSO2 Carbon on which all WSO2 products are based) is shipped with a Secure Vault implementation (a modified version of synapse Secure Vault). This will enable you to store encrypted passwords that are mapped to aliases.

The config files will not show the actual passwords but an alias that will be substituted at runtime by the decrypted password. This, of course, will strengthen the security.

Elements of the secure vault

Some of the important elements in the secure vault implementation, which are used in Carbon products for encrypting plain text passwords, are as follows:

Secret Repository: This is used to store the secret values (encrypted values). The cipher-text.properties file, located in the <PRODUCT_HOME>/repository/conf/security folder is the default file based secret repository used by the Secret Manager in your Carbon product. Note that, currently, Secure Vault only implements file based secret repositories. The Secret Repository stores aliases vs. their actual secrets in encrypted format (encrypted via a key in KeyStore). Any secret repositories can be written by implementing the SecretRepository and SecretRepositoryProvider classes. See the topic on creating custom secure vault configurations: https://docs.wso2.com/display/Carbon420/WSO2+Carbon+Secure+Vault#WSO2CarbonSecureVault-CreatecustomSecureVaultconfiguration.

Secret Manager: The Secret Manager initializes the Secret Repository and the KeyStore configured for the Carbon server. The secrets stored in the Secret Repository are accessed using the aliases indicated in the cipher-text.properties file. The KeyStore is required to create the decryption crypto, which can be used to resolve encrypted secrets values. The KeyStore and Secret Repository are configurable through the ‘secret-conf.properties’ file found in the <PRODUCT_HOME>/repository/conf/security folder.

Secret Callback: This provides the actual password for a given alias. There is a SecretManagerSecretCallbackHandler, which is combined with Secret Manager to resolve the secret. Any callback can be written by implementing the SecretCallbackHandler class. See the topic on creating custom secure vault configurations.

Secret Resolver: Any configuration builder that uses secret information within its own configuration file needs to initialize the Secret Resolver when building its own configuration. The Secret Resolver keeps a list of secured elements that need to be defined in the configuration file with secret aliases. Secret Resolver initializes the Secret Callback handler class, which is defined in the configuration file.

Step 1

Shutdown the server if it is already running and open <PRODUCT_HOME>/repository/conf/security/cipher-tool.properties file.

It contains all the aliases to different server components.

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. You will see that standard a number of entries are already uncommented. Running the ciphertool.bat will encrypt all (matching uncommented passwords.






[name=’WSO2_CARBON_DB’]/definition[@type=’RDBMS’] /configuration/password,false






Step 2

Open <PRODUCT_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.


Get the cipher tool from the <PRODUCT_HOME>/bin folder. 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 <PRODUCT_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<PRODUCT_HOME>/repository/conf/security/secret-conf.properties file as described in WSO2 Carbon Secure Vault in the WSO2 Carbon documentation.

On Windows: ciphertool.bat -Dconfigure

On Linux: sh ciphertool.sh -Dconfigure

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<PRODUCT_HOME>/repository/conf/carbon.xml file will be replaced by the alias as follows.


<!– Keystore password–>

<Password svns_secretAlias=”Carbon.Security.KeyStore.Password”>password</


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.

Suggested encryptions

The following are a list of commonly encrypted passwords and possible aliases:

Alias Purpose
transports.https.keystorePass  SSL key and keystore password in mgt-transport.xml
Carbon.Security.KeyStore.Password Keystore password of Carbon server in carbon.xml
Carbon.Security.KeyStore.KeyPassword  Private key password of Carbon server in carbon.xml
Carbon.Security.TrustStore.Password  Trust store password of Carbon server in carbon.xml
UserManager.AdminUser.Password  Admin User password in user-mgt.xml
Datasources.WSO2_CARBON_DB.Configuration.Password  User management and registry database connection password in master-datasources.xml
UserStoreManager.Property.ConnectionPassword  User store connection password in user-mgt .xml
Axis2.Https.Listener.TrustStore.Password  NIO Listener SSL trust store password in axis2.xml
Axis2.Https.Listener.KeyStore.Password  NIO Listener SSL KeyStore store password in axis2.xml
Axis2.Https.Listener.KeyStore.KeyPassword  NIO Listener SSL key password in axis2.xml
Axis2.Https.Sender.TrustStore.Password  NIO Sender SSL trust store password in axis2.xml
Axis2.Https.Sender.KeyStore.Password  NIO Sender SSL key store password in axis2.xml
Axis2.Https.Sender.KeyStore.KeyPassword  NIO Sender SSL key password in axis2.xml
Axis2.Mailto.Parameter.Password  Email sender password in axis2.xml
WSO2TORIALS help you to change, update or improve WSO2 products and are based on our experiences with the products. WSO2TORIALS will guide you step by step with minimal knowledge required.   WSO2TORIAL.jpeg

Full API lifecycle Management Selection Guide

whitepaper hero
Get it now
We appreciate it
Care to share

Please select one of the social media platforms below to share this pages content with the world