If you go through the conf directory of WSO2 products, there are some configuration file, that contains secret informations such as passwords…This blog post describes how we can secure the plain text passwords in these configuration files. This document gives you clear understanding about secure vault implementation. But here i am going step by step to configure it. Please note this configurations only valid for carbon 3.2.X, 4.0.X, 4.1.X and 4.2.X products. But with 4.X.X releases, there are new configurations files…. as an example, we have “master-datasources.xml” file which can be found in “conf/datasources”. In this file, we are configuring all data source related configurations… Therefore database configuring passwords would be in this file.
First, let see what are the secret information that can be secured. Following are the alias names and secrets of carbon configuration files.
What can be secured
1. in user-mgt.xml
Any property in user store configuration element in the user-mgt.xml file. But passwords areusually contained in following elements.
UserManager.AdminUser.Password -> Admin User password in user-mgt.xml
UserStoreManager.Property.ConnectionPassword -> User store connection password in user-mgt .xml
UserManager.Configuration.Property.password -> User Manager database connection password in user-mgt.xml (Only in 3.2.X)
2. in carbon.xml
Any property in carbon.xml file. But passwords are usually contained in following elements.
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
Following are introduced with Carbon 4.2.X (Which is used for encryt/decrypt registry data)
Carbon.Security.RegistryKeyStore.Passwor -> Registry Keystore password of Carbon server in carbon.xml
Carbon.Security.RegistryKeyStore.KeyPassword -> Registry Private key password of Carbon server in carbon.xml
3. master-datasources.xml (With Carbon 4.X.X )
Datasources.[Data source name].Configuration.Password -> Database connection password of defined data source. There can be more than one datasource configurations in this file.
4. in registry.xml (Only in 3.2.X )
wso2registry.[Registry Name].password -> Registry database connection password in registry.xml
5. in mgt-transport.xml (Only in 3.2.X )
transports.https.keystorePass -> SSL key and keystore password in mgt-transport.xml
6. In axis2.xml file. By using secure vault you can secure the passwords in axis2.xml file, i.e.
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
7. identity.xml file (With Carbon 4.X.X )
Any property in identity.xml file
How to Secure
Step 1. (Optional) Configure cipher-tool.properties file with your passwords.
By default. All required properties are configured here. This is only required, if you need to add more properties to secure other than the default values.
As an example, if you need to secure the thrift password in identity.xml file. You need to add following property.
EntitlementSettings.ThirftBasedEntitlementConfig.KeyStore.Password=identity.xml//Server/EntitlementSettings/ThirftBasedEntitlementConfig/KeyStore/Password,true
Property name must be generated from XML elements. Value is the file name, XPath to the element and boolean true value.
Step 2. Locate cipher-text.properties which can be found at /repository/conf/sceurity directory in your WSO2 product. This file contains the alias names and the corresponding plain text password in square brackets.
Step 3. Configure cipher-text.properties file with your passwords.
As an example, I want to secure keystore passwords and registry keystore of carbon.xml file , both database and LDAP connection password of user-mgt.xml file. My cipher-text.properties would be as follows,
Carbon.Security.KeyStore.Password=[mykeystorepass] Carbon.Security.KeyStore.KeyPassword=[mykeystorepass] Carbon.Security.TrustStore.Password=[mytruststorepass] Carbon.Security.RegistryKeyStore.Password=[myregistrykeystorepass] Carbon.Security.RegistryKeyStore.KeyPassword=[myregistrykeypass] UserManager.Configuration.Property.password=[myuserdbpass] UserStoreManager.Property.ConnectionPassword=[myldappass]
If there are any other elements, You need to configure in there.
Step 4. Locate “ciphertool” script which can be found at /bin directory. If you can not find this file in your product, Please download it from this svn location and copy to above location.
Step 5. Run “ciphertool” script with -Dconfigure option.
as an example in UNIX,
>ciphertool.sh -Dconfigure
This script does followings
- Encrypt the passwords defined in cipher-text.properties file
- Remove plain text passwords in conf files.
- Configure secret-conf.properties file with default configuration
Step 6. Check above mentioned files, are properly configured.
Step 7. Start server. in startup, server would promote for master password (i.e is key store password) you need to provide it.
This is the default way of providing the master password according default implementation. Let see more above default implementation of providing master password.
How to change a password
Step 1. Configure cipher-text.properties file with the password you want to modify. You need remove the encrypted value and replace it with plain text password with [ ] square brackets
Carbon.Security.KeyStore.Password=[new password value]
Step 2. Run “ciphertool” script with -Dconfigure option.
Step 7. Start server.
Default Secret CallbackHandler
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.
Enter password in command-line
If option 2 is not configured, when the Carbon server is starting, it will propt 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 back ground process, this option can not be used.
Store the password in a temporary text file
When Carbon Server is starting, it first checks for the text file called “password-tmp” 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-tmp” in PRODUCT_HOME and enter the keyStore password in the first line of the file. Steps are as follows:
- Shut down the server if it is already started.
- Create a text file named “password-tmp” in <PRODUCT_HOME>.
- Enter your primary keystore password in the 1st line of the text file and save it.
- Start the Carbon Server using command, daemon. sh wso2server.sh -start
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.
Writing custom CallbackHandler
Personally, I do not like to provide master password each server startup, although it is one of a secured way to provide it…. You can write your own implementation for this. Therefore i just write a simple implementation for this where i have hard coded my master password. Please find the my project from here.
Let see how we can configure new master password callback handler
Step 1. Build the project and create a jar file
Step 2 . Replace the default password handler class name (org.wso2.carbon.securevault.DefaultSecretCallbackHandler) from secret-conf.properties file and configure my own one which is com.sample.password.callback.handler.HardCodedSecretCallbackHandler.
Step 3. Copy own implementations as a jar file in to /repository/components/lib directory
Step 4 (Only for 3.2.X). If you have secured the passwords in mgt-transport.xml file, Please Copy your jar file to /lib/api directory.
Step 5. Restart the server.