If the directory/file paths specified in this guide do not exist in your WSO2 product, see Directory Structure of WSO2 Products to locate the paths applicable to your product.
Page Comparison - Carbon Secure Vault Implementation (v.2 vs v.13) - Administration Guide 4.4.x - WSO2 Documentation

Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

...

Note

The Cipher Tool is used in WSO2 products to create encrypted values for passwords. See the following sections in the documentation for more information:

See the following topics:

Table of Contents
maxLevel4
minLevel3

Elements of the Secure Vault implementation

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 <PRODUCT_HOME>/repository/conf/security folder 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 configurationscustomizing the Secure Vault configuration.
  • Secret Manager: 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 <PRODUCT_HOME>/repository/conf/security folder 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 configurationscustomizing the Secure Vault configuration.
  • 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. 

...

Customizing the Secure Vault configuration

You can implement your own Secure Vault configurations by changing the following according to your choice:

...

default Secret Repository and the Secret Callback Handler.

...

See the following for topics for instructions:

Creating a 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,

    Code Block
    Java
    Java
    public class HardCodedSecretCallbackHandler extends AbstractSecretCallbackHandler {
         protected void handleSingleSecretCallback(SingleSecretCallback singleSecretCallback) {
                singleSecretCallback.setSecret("password");
         }
    }
  2. We can set multiple password-based as follows:

    Code Block
    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 <PRODUCT_HOME>/repository/component/lib/ directory or the OSGI bundle to the <PRODUCT_HOME>/repository/component/dropins/ directory
  4. Configure the master-datasources.xml file with an alias name and your Secret Callback handler class name. For example,

    Code Block
    XML
    XML
    <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<password svns: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  

  5. Go to <PRODUCT_HOME>/bin and execute ./ciphertool.sh -Dconfigure

  6. Replace the values of two the properties keystore.identity.store.secretProvider and keystore.identity.key.secretProvider in <PRODUCT_HOME>/repository/conf/security/secret-conf.properties file with your Secret Callback handler class name.

  7. Restart the server.

Creating a custom Secret Repository

To create a custom secret repository, you need to implement the SecretRepository and SecretRepositoryProvider interfaces:

  1. Create your custom secret repository by implementing the org.wso2.securevault.secret.SecretRepository interface:

    Code Block
    public class CustomSecretRepositoryImpl extends SecretRepository {
     public void init(Properties properties, String s) {
     }
     public String getSecret(String s) {
           return null;
     }
     public String getEncryptedData(String s) {
           return null;
     }
     public void setParent(SecretRepository secretRepository) {
     }
     public SecretRepository getParent() {
           return null;
     }
    } 
  2. Then you need to implement the org.wso2.securevault.secret.SecretRepositoryProvider class as shown below. This class returns an instance of the custom SecretRepository that you implemented above.

    Code Block
    public class CustomSecretRepositoryProvider implements SecretRepositoryProvider {
       public SecretRepository getSecretRepository(IdentityKeyStoreWrapper identityKeyStoreWrapper,
           TrustKeyStoreWrapper trustKeyStoreWrapper) {
        return new CustomSecretRepositoryImpl(identityKeyStoreWrapper, trustKeyStoreWrapper);
      }
    } 
  3. Create a JAR or an OSGI bundle. 

  4. Then, copy the JAR file to the <PRODUCT_HOME>/repository/component/lib/directory or the OSGI bundle to the <PRODUCT_HOME>/repository/component/dropins/ directory

  5. Replace the secretRepositories.file.provider entryin the secret-conf.properties file (stored in the <PRODUCT_HOME>/repository/conf/security/ directory) with your secret repository class name.