Carbon Secure Vault Implementation

WSO2 Carbon is shipped with a Secure Vault implementation, which is a modified version of synapse Secure Vault. This allows you to store encrypted passwords that are mapped to aliases. That is, you can use the aliases instead of the actual passwords in your configuration files for better security. For example, some configurations require the admin username and password. If the admin user password is "admin", you could use the alias UserManager.AdminUser.Password in your configuration file. You would then map that alias to the actual password "admin". At runtime, the product will look up this alias in the secure vault and then decrypt and use its password.

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 <WSO2_OB_KM_HOME>/repository/conf/security and <WSO2_OB_APIM_HOME>/repository/conf/security folders 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.
• Secret Manger: 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 secret values. The keystore and Secret Repository are configurable through the secret-conf.properties file, which is created in the <WSO2_OB_KM_HOME>/repository/conf/security and <WSO2_OB_APIM_HOME>/repository/conf/security folders when you execute the Cipher Tool.
  
• 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.  

Create custom Secure Vault configuration

You can implement your own Secure Vault configurations by implementing a new secret repository, secret callback handler or by changing the keystore that is used for encryption. By default, the primary keystore of the product is used for encrypting and decrypting. You can find out more about working with keystores from here.

Writing a new secret callback handler

Let's see how we can write a new Secret Callback Handler class to secure the user management and registry 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.

1. Write a Secret Callback class. You need to implement the SecretCallbackHandler interface or extend the AbstractSecretCallbackHandler abstract class. For example,
   

   public class HardCodedSecretCallbackHandler extends AbstractSecretCallbackHandler {
        protected void handleSingleSecretCallback(SingleSecretCallback singleSecretCallback) {
               singleSecretCallback.setSecret("password");
        }
   }

2. We can set multiple passwords:
   

   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");
              }
      }
   }

3. Create a JAR or an OSGI bundle and copy the JAR file to the  <WSO2_OB_KM_HOME>/repository/component/lib/ and <WSO2_OB_APIM_HOME>/repository/component/lib/  directories or the OSGI bundle to the  <WSO2_OB_APIM_HOME>/repository/component/dropins/ and <WSO2_OB_APIM_HOME>/repository/component/dropins/ directories.

4. Configure the master-datasources.xml file with an alias name and your Secret Callback handler class name. For example,
   

   <datasource>
               <name>WSO2_CARBON_DB</name>
               <description>The datasource used for registry and user manager</description>
               <jndiConfig>
                   <name>jdbc/WSO2CarbonDB</name>
               </jndiConfig>
               <definition type="RDBMS">
                   <configuration>
    <url>jdbc:h2:repository/database/WSO2CARBON_DB;DB_CLOSE_ON_EXIT=FALSE;LOCK_TIMEOUT=60000</url>
                       <username>wso2carbon</username>
                       <passwordsvns:secretAlias="Datasources.WSO2_CARBON_DB.Configuration.Password">password</password>
                       <driverClassName>org.h2.Driver</driverClassName>
                       <maxActive>50</maxActive>
                       <maxWait>60000</maxWait>
                       <testOnBorrow>true</testOnBorrow>
                       <validationQuery>SELECT 1</validationQuery>
                       <validationInterval>30000</validationInterval>
                   </configuration>
               </definition>
           </datasource>

    Also, replace the secret callback handler class name in the <WSO2_OB_KM_HOME>/repository/conf/security/secret-conf.properties and <WSO2_OB_APIM_HOME>/repository/conf/security/secret-conf.properties files with your Secret Callback handler class name.

5. Restart the server.

Configure the Secure Vault Support for ConsentEnforcementHandler

You can pass the encrypted passwords to ConsentEnforcementHandler when the secure vault is enabled. To secure jks_secret passed to ConsentEnforcementHandler, follow the steps below:

If the Secure Vault is enabled and the Accounts API is already deployed, follow the steps below to pass the encrypted JKS_SECRET to ConsentEnforcementHandler:

1. Open the <WSO2_OB_APIM_HOME>/repository/deployment/server/synapse-configs/default/api/<PUBLISHER_USERNAME>--AccountAndTransactionAPI_vv3.1.xml file.

2. Locate the section under the following handler:

3. Remove the following handler:

   <property name="password" value="<PASSWORD>"/>

4. Add the following handler:

   <property name="secretAlias" value=”<ALIAS_OF_JKS_SECRET>”/>

If the Secure Vault is enabled and the Accounts API has not been deployed yet, follow the steps below:

1. Open the <WSO2_OB_APIM_HOME>/repository/resources/api_templates/velocity_template.xml file.

2. Locate the section under the following handler:

3. Remove the following handler:

   <property name="password" value="<PASSWORD>"/>

4. Add the following handler:

   <property name="secretAlias" value=”<ALIAS_OF_JKS_SECRET>"/>

   For example:

   If ALIAS_OF_JKS_SECRET is jks_secret, set the configuration as follows: