WSO2 Carbon - Secure Vault [Documentation Index]
This guide describes how we can secure the plain text password in carbon configuration files. WSO2Carbon 3.2.0 is shipped with a secure vault implementation which is a modified version of synapse secure vault. Please refer synapse secure vault guide for more detail on it
All secrets are managed using the Secret Manager. 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 by providing aliases for them. Key store is required to create the decryption crypto which can use to resolve encrypted secrets values. Keystore and secret repository are configurable. It can be done through the 'secret-conf.properties' which can be found in CARBON_HOME/repository/conf
This is used to keep the secret values. Currently, there is only one secret repository is implemented within secure vault and it is called the FileBaseSecretRepository. It uses cipher-text.properties which can be found in CARBON_HOME/repository/conf , to keep the secrets. It keeps aliases vs. its actual secret in encrypted format (encrypted by a key in keystore). Any secret repositories can be written by implementing the SecretRepository and SecretRepositoryProvider classes.
This provides the actual password for the given alias. There is a SecretManagerSecretCallbackHandler which has 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 their own configuration file, is needed to initialize the secret resolver when building its own configuration. secret resolver keeps the list of secured elements which are needed to be defined in configuration file with secret alias. Secret resolver initializes secret callback handler class which is defined in configuration file.
In default configuration,
1. File base secret repository is used , cipher-text.properties which can be found in
CARBON_HOME/repository/conf
2. Carbon Server primary key store is used for encrypting and decrypting passwords,
which can be found in CARBON_HOME/repository/resources/security
3.DefaultSecretCallbackHandler
(org.wso2.carbon.securevault.DefaultSecretCallbackHandler) is used as the password
resolver for keystore and private key passwords of Carbon Server primary Keystore
4. SecretManagerSecretCallbackHandler
(org.wso2.securevault.secret.handler.SecretManagerSecretCallbackHandler) is used as the
password resolver for the all secret values which are defined in carbon configuration
files
WSO2Carbon 3.2.0 has made the secure vault configuration easy by shipping a command line
tools called Ciphertool
By default, CipherTool can be used for creating encrypted value for given plaint text.
But there are two options that helps for secure vault configuration
-Dconfigure
(sh ciphertool.sh -Dconfigure)
This option would allow user to secure plain text passwords in carbon configuration
files.
1. Read alias values and their corresponding plain text passwords from the
cipher-text.properties file.
Please note that CipherTool identifies the plain text which are defined with in square
brackets as the plain text passwords.
If password is not in the cipher-text.properties for corresponding alias, User needs to
provide it using command-line
2. Check whether alias is a known password alias in Carbon configurations, If Ciphertool
modifies the configuration element and file
Replace configuration element with alias name
Define a secret callback in configuration file
Add proper name spaces for defining secure vault.
3. Encrypt plain test value using the primary key store of carbon server (Details of
primary Key store is read from carbon.xml file which can be found in
CARBON_HOME/repository/conf)
4. Replace plain text values in cipher-text.properties file with the encrypted
passwords.
5. Add default configuration to secret-conf.properties
-Dchange
(sh ciphertool.sh -Dchange)
This option is allowed user to change password of a secured password
This secret callback handler is used to resolve the keystore and private key passwords
of Carbon Server primary key store. As these password are need to initialize the secret
manager decrypt the encrypted values in secret repository, these passwords act as the
root passwords for secure vault. Therefore DefaultSecretCallbackHandler provides two
options of reading this password when starting carbon sever.
1. Enter Password in command-line
If option 2 has not been configured, When Carbon Server is starting, It would promote
to enter the private key and keystore passwords.
Admin who starts the Carbon server, must provide the private key and keystore passwords
using command-line. (passwords are hided from terminal and logs files)
By default Password provider assumes that both private key and keystore passwords are
same. If not, following system property must be passed when Carbon server is start-up
export JAVA_OPTS=-Dkey.password=true (in UNIX)
Limitation :
This option is only valid, when Carbon server is started with sh
wso2server.sh . But when Carbon server is started using nohup, This option can not be
used
2. Store Password in a temporary text file
When Carbon Server is starting, It first check for the text file called
"password" in
CARBON_HOME directory
and read private key and keystore password. After reading text
file, It would be deleted automatically
Admin who starts the Carbon Server. must create a text file called "password" in
CARBON_HOME and enter the keyStore password in first line of the file. Steps are as
followings,
1. Shutdown server if you have already started.
2. Create a text file with name "password" in CARBON_HOME location.
3. Open and enter your primary keystore password in the 1st line of the text file and
save it.
4. Then restart the Carbon Server using nohup. sh wso2server.sh -start
By default Password provider assumes that both private key and keystore passwords are
same. If not, private key password must be entered in second line of the file.
Important :
If carbon server is deployed in any other app server (ex - weblogic) or key
password of https transport (password in mgt-transports.xml ) is not secured, File name
of text file must be “password-tmp” (not “password”)
Limitation :
Every restart, Admin needs to create a text file.
You can use your own configurations by changing follows according to your choice.
1. Secret repository
2. Secret Callback Hander
3. Using a keystore other than the primary key store of carbon server.
Lets see how we can write a new Secret Callback Hander class to secure the user
management database connection password. In this sample you need not to configure a
secret repository or keyStore (cipher-text.properties) as you are not going to store the
secret or encrypted values.
1. Write secret callback class. You need to implement the SecretCallbackHandler
interface or extend the AbstractSecretCallbackHandler abstract class.
public class HardCodedSecretCallbackHandler extends AbstractSecretCallbackHandler {
protected void handleSingleSecretCallback(SingleSecretCallback singleSecretCallback) {
singleSecretCallback.setSecret("password");
}
}
we can set multiple passwords based id of SingleSecretCallback as follows,
public class HardCodedSecretCallbackHandler extends AbstractSecretCallbackHandler {
protected void handleSingleSecretCallback(SingleSecretCallback singleSecretCallback) {
if("foo".equals(singleSecretCallback.getId())){
singleSecretCallback.setSecret("foo_password");
} else if("bar".equals(singleSecretCallback.getId())){
singleSecretCallback.setSecret("bar_password");
}
}
}
2. Create a jar or OSGI bundle
3. Copy jar file to CARBON_HOME/repository/component/lib , OSGI bundle to
CARBON_HOME/repository/component/dropins>
4. Configure user-mgt.xml file with alias name and your secret callback handler class
name
<UserManagerxmlns:svns="http://org.wso2.securevault/configuration"
>
<svns:SecureVault
provider="org.wso2.securevault.secret.handler.HardCodedSecretCallbackHandler">
<Realm>
<Configuration>
<AdminRole>admin</AdminRole>
<AdminUser>
<UserName>admin</UserName>
<Password>admin</Password>
</AdminUser>
<EveryOneRoleName>everyone</EveryOneRoleName>
<Property name="url">jdbc:h2:repository/database/WSO2CARBON_DB;DB_CLOSE_ON_EXIT=FALSE</Property>
<Property name="userName">wso2carbon</Property>
<Property name="password"
svns:secretAlias="UserManager.Configuration.Property.password">password</Property>
<Property name="driverName">org.h2.Driver</Property>
<Property name="maxActive">50</Property>
<Property name="maxWait">60000</Property>
<Property name="minIdle">5</Property>
</Configuration>
5. Restart the server.
Following are the alias names and secrets of carbon configuration files which are supported
by secure vault
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
UserManager.Configuration.Property.password -> User Manager database connection password in
user-mgt.xml
UserStoreManager.Property.ConnectionPassword -> User store connection password in user-mgt
.xml
wso2registry.[Registry Name].password -> Registry database connection password in
registry.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