WSO2 Carbon - Secure Vault [Documentation Index]

WSO2 Carbon Secure Vault

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

Contents

Introduction to Secure Vault

Secret Manger

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

Secret Repository

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.

Secret Callback

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.

Secret Resolver

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.

Use Secure Vault with default Configuration

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

Cipher Tool

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

Default Secret CallbackHandler

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.

Use Secure Vault with your own Configurations

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.

Secrets and Alias list in Carbon Configurations

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