Page Comparison

WSO2 Carbon is shipped with a secure vault Secure Vault implementation which is a modified version of synapse secure vaultSecure Vault. This guide describes how to secure the plain text password in carbon configuration files.

Secret

...

Manager

The Secret Manager initializes the secret repository Secret Repository and the keystores. It uses secret repository Secret Repository to keep the secret values (encrypted values). These secrets can be accessed through aliases. The keystore is required to create the decryption crypto, which can be used to resolve encrypted secrets values. The keystore and secret repository Secret Repository are configurable nd the configuration can be done through the 'secret-conf.properties' file found in PRODUCTthe <PRODUCT_HOMEHOME>/repository/conf directory/security folder.

Secret Repository

This is used to store the secret values. Currently, there is only one secret repository Secret Repository implemented within secure vault and it is called the Secure Vault: FileBaseSecretRepository. It uses cipher-text.properties, which can be found in PRODUCTthe <PRODUCT_HOMEHOME>/repository/conf directory/security folder. It 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.

Secret Callback

This provides the actual password for a given alias. There is a SecretManagerSecretCallbackHandler, which is combined with secret manager Secret Manager to resolve the secret. Any callback can be written by implementing the SecretCallbackHandler class.

Secret Resolver

Any configuration builder , which that uses secret information within its own configuration file , is needed needs to initialize the secret resolver Secret Resolver when building its own configuration. The secret resolver Secret Resolver keeps a list of secured elements which that need to be defined in the configuration file with secret aliases. Secret resolver Resolver initializes the secret callback Secret Callback handler class, which is defined in the configuration file.

Use Secure Vault with

...

default configuration

In default configuration,

1. A file-base secret repository Secret Repository is used. The cipher-text.properties file can be found in PRODUCTthe <PRODUCT_HOMEHOME>/repository/conf directory/security folder.
2. Carbon Server's primary keystore is used for encrypting and decrypting passwords, which can be found in PRODUCTthe <PRODUCT_HOMEHOME>/repository/resources/security folder folder.
3. DefaultSecretCallbackHandler (org.wso2.carbon.securevault.DefaultSecretCallbackHandler) is used as the password resolver for the keystore and the private key passwords of the Carbon server's primary Keystore.
4. SecretManagerSecretCallbackHandler (org.wso2.securevault.secret.handler.SecretManagerSecretCallbackHandler) is used as the password resolver for all the secret values which that are defined in the carbon Carbon configuration files.

The secure vault Secure Vault configuration is made easier by the command-line tool called Ciphertool.

Cipher Tool

By default, the CipherTool can be used for creating encrypted values for given plaint text. There are two options for secure vault Secure Vault configuration as follows:

...

1. This option allows the user to secure plain text passwords in carbon configuration files.
2. Read alias values and their corresponding plain text passwords from the cipher-text.properties file. Note that the CipherTool identifies plain text defined within square brackets as the plain text passwords. If a password is not specified in the cipher-text.properties file for a corresponding alias, the user needs to provide it through the command-line.
3. Check whether the alias is a known password alias in Carbon configurations. If the tool modifies the configuration element and file, then replace the configuration element with the alias name. Define a secret callback Secret Callback in the configuration file and add proper name spaces for defining the secure vaultSecure Vault.
4. Encrypt the plain text value using the primary keystore of the carbon server (Details of the primary keytore is taken from the carbon.xml file, which can be found in PRODUCTthe <PRODUCT_HOMEHOME>/repository/conf directory folder.)
5. Replace plain text values in the cipher-text.properties file with the encrypted passwords.
6. Add the default configuration to secret-conf.properties file

...

1. This option allows the user to change a secured password.

The

...

default Secret CallbackHandler

This secret callback 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 Secret Manager decrypted the encrypted values in the secret repositorySecret Repository, they act as the root passwords for the secure vaultSecure 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 prompt to enter the private key and keystore passwords.
The  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  By default, the password provider assumes that both private key and keystore passwords are the same. If not, the following system propeties 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 using sh wso2server.sh. When the server is started as a daemon, this option can not cannot 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 in <PRODUCT_HOME> and  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<PRODUCT_HOME HOME> and enter the keyStore password in the first line of the file. Steps are as follows:

1. Shut down the server if it is already started.
2. Create a text file named "password-tmp" in in <PRODUCT_HOME>.
3. Enter your primary keystore password in the 1st first line of the text file and save it.
4. Start the Carbon Server using command, daemon. sh wso2server.sh -start.

5. 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.
   

   If the carbon server is deployed in any other app server (eg:- weblogic) or key password of https transport (password in catalina-server.xml), it is not secured. Then the file name of the text file must be 'password-tmp', not 'password'

   Info
   Note
   Note that if you name the password file "password-persist" instead of "password-tmp", the file will not be deleted after the server starts. Therefore, it will not be required to provide the password when the server is started again. However, note that this method is not recommended in production environments.

   Info
   At every restart, the Admin has to create a text file.

Use Secure Vault with your own

...

configurations

You can use your own configurations by changing the following according to your choice.

• Secret repositoryRepository.
• Secret Callback HanderHandler.
• Using a keystore other than the primary keystore of the carbon server.

Let's see how we can write a new Secret Callback Hander Handler class to secure the user management and registry database connection password. In this sample, you do not need to configure a secret repository Secret Repository or keyStore (cipher-text.properties) as you are not going to store the secret or encrypted values.

Write a secret callback 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) {
         if("foo".equals(singleSecretCallback.getId())){
            singleSecretCallback.setSecret("foo_password");
         } else if("bar".equals(singleSecretCallback.getId())){
            singleSecretCallback.setSecret("bar_password");
           }
   }
}

Create a jar or JAR or an OSGI bundle. Copy the jar JAR file to the <PRODUCT_HOME>/repository/component/lib directory / directory or the OSGI bundle to the <PRODUCT_HOME>/repository/component/dropins/ directory. Configure the usermaster-mgtdatasources.xml file with an alias name and your secret callback Secret Callback handler class name. For example,

<UserManagerxmlns:svns="http://org.wso2.securevault/configuration" ><datasource>
             <svns:SecureVault provider="org.wso2.securevault.secret.handler.HardCodedSecretCallbackHandler"><name>WSO2_CARBON_DB</name>
      <Realm>     <Configuration> <description>The datasource used for registry and user <AdminRole>admin<manager</AdminRole>description>
       <AdminUser>     <jndiConfig>
      <UserName>admin</UserName>          <name>jdbc/WSO2CarbonDB</name>
 <Password>admin</Password>        </AdminUser>   </jndiConfig>
    <EveryOneRoleName>everyone</EveryOneRoleName>        <Property<definition nametype="url">jdbcRDBMS">
                <configuration>
 <url>jdbc:h2:repository/database/WSO2CARBON_DB;DB_CLOSE_ON_EXIT=FALSE</Property>=FALSE;LOCK_TIMEOUT=60000</url>
                   <Property name="userName">wso2carbon</Property> <username>wso2carbon</username>
                  <Property name="password" svns<passwordsvns:secretAlias="UserManagerDatasources.WSO2_CARBON_DB.Configuration.Property.passwordPassword">password</Property>password>
                   <Property name="driverName">org <driverClassName>org.h2.Driver</Property>/driverClassName>
                    <maxActive>50</maxActive>
                    <maxWait>60000</maxWait>
                    <testOnBorrow>true</testOnBorrow>
                    <Property name="maxActive">50</Property><validationQuery>SELECT 1</validationQuery>
                   <Property name="maxWait">60000</Property> <validationInterval>30000</validationInterval>
               <Property name="minIdle">5</Property> </configuration>
            </Configuration>
definition>
        </datasource>

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 vaultSecure Vault.

transports.https.keystorePass -> SSL key and keystore password in catalinamgt-servertransport.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
UserManagerDatasources.WSO2_CARBON_DB.Configuration.Property.passwordPassword -> User management and Managerregistry database connection password in usermaster-mgtdatasources.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