WSO2 Carbon is shipped with a secure vault implementation which is a modified version of synapse secure vault. It provides capability to securely store sensitive data such as passwords.
This guide describes how to secure the plain text passwords in configuration files of the WSO2 Carbon platform, such as user-mgt.xml, Carbon.xml, Axis2.xml, registry.xml etc. They are available in all WSO2 Carbon-based products. However, the steps in this guide may differ when implementing secure vault for more product-specific configuration files.
The Secret Manager initializes the secret repository and the keystores. It uses secret repository to keep the secret values (encrypted values). These secrets can be accessed through aliases. 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 nd the configuration can be done through the 'secret-conf.properties' file found in PRODUCT_HOME/repository/conf/security directory.
This is used to store the secret values. Currently, there is only one secret repository implemented within secure vault and it is called the FileBaseSecretRepository. It uses cipher-text.properties which can be found in PRODUCT_HOME/repository/conf/security directory. It 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.
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.
Any configuration builder, which uses secret information within its own configuration file, is needed to initialize the secret resolver when building its own configuration. The secret resolver keeps a list of secured elements which 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.
In default configuration,
The secure vault configuration is made easier by the command-line tool called Ciphertool.
By default, the CipherTool can be used for creating encrypted values for given plaint text. There are two options for secure vault configuration as follows:
This secret callback handler is used to resolve the keystore and private key passwords of the Carbon server's primary keystore. As these passwords are needed to initialize the secret manager decrypted the encrypted values in the secret repository, they act as the root passwords for the secure vault. Therefore, DefaultSecretCallbackHandler provides two options for reading this password when starting the carbon sever.
If option 2 is not configured, when the Carbon server is starting, it will prompt to enter the private key and keystore passwords.
The admin starting the server must provide the private key and keystore passwords using the command-line. (Passwords are hidden from terminal and logs files.)
By default, the password provider assumes that both private key and keystore passwords are the same. If not, the following system properties must be passed when the server is starting up.
export JAVA_OPTS=-Dkey.password=true (in UNIX)
This option is valid only when the Carbon server is started using sh wso2server.sh. When the server is started as a daemon, this option can not be used.
When Carbon Server is starting, it first checks for the text file called "password" in <PRODUCT_HOME> and reads the private key and keystore password. The text file is deleted automatically after it is read. The admin who starts the Carbon Server must create a text file called "password" in PRODUCT_HOME and enter the keyStore password in the first line of the file. Steps are as follows:
By default, the password provider assumes that both private key and keystore passwords are the same. If not, the private key password must be entered in the second line of the file.
If the carbon server is deployed in any other app server (eg:- weblogic) or key password of https transport (password in mgt-transports.xml), it is not secured. Then the file name of the text file must be 'password-tmp', not 'password'.
At every restart, the Admin has to create a text file.
You can use your own configurations by changing the following according to your choice.
Let's see how we can write a new Secret Callback Handler class to secure the user management database connection password. In this sample, you do not need to configure a secret repository or keyStore (cipher-text.properties) as you are not going to store the secret or encrypted values.
Write a secret callback class. You need to implement the SecretCallbackHandler interface or extend the AbstractSecretCallbackHandler abstract class. For example,
We can set multiple password-based as follows,
Create a jar or an OSGI bundle. Copy the jar file to <PRODUCT_HOME>/repository/component/lib directory or the OSGI bundle to <PRODUCT_HOME>/repository/component/dropins. Configure the user-mgt.xml file with an alias name and your secret callback handler class name. For example,
Restart the server.
Following are the alias names and secrets of carbon configuration files which are supported by secure vault.