WSO2TORIAL: Encrypt passwords using Secure Vault

In this episode of our WSO2 tutorial: 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.

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.

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.

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.

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:

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.