WSO2 Carbon is shipped with a secure vault implementation which is a modified version of synapse secure vault. This guide describes how to secure the plain text password in carbon configuration files.
Secret
...
Manager
The 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 through aliases. The keystore is required to create the decryption crypto, which can be used to resolve encrypted secrets values. The The keystore and secret repository Secret Repository are configurable nd the configuration can be done through the 'through the <GREG_HOME>/repository/conf/security/secret-conf.properties' file found in $GREG_HOME/repository/conf directory. file, which is generated once you execute the Cipher tool.
Secret Repository
This is used to store the secret values. Currently, there is only one secret repository implemented within secure vault and it is called the FileBaseSecretRepository. It uses cipher-text.properties which can be found in $GREG_HOMEthe <GREG_HOME>/repository/conf directory. It /security/cipher-text.properties file, and 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.
...
- A file-base secret repository is used. The (<
GREG_HOME>/repository/conf/security/cipher-text.properties file can be found in$GREG_HOME/repository/confdirectorypropertiesfile). - Carbon Server's primary keystore is used for encrypting and decrypting passwords, which can be found in $GREGthe <
GREG_HOMEHOME>/repository/resourcesconf/security/folder. - 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.
- SecretManagerSecretCallbackHandler (org.wso2.securevault.secret.handler.SecretManagerSecretCallbackHandler) is used as the password resolver for all the secret values which are defined in the carbon configuration files.
...
- This option allows the user to secure plain text passwords in carbon configuration files.
- 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.
- 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 in the configuration file and add proper name spaces for defining the secure vault.
- 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 $GREG_HOME<
GREG_HOME>/repository/confdirectory/carbon.xmlfile.) - Replace plain text values in the cipher-text.properties file with the encrypted passwords.
- Add the default configuration to secret-conf.properties file
...
When Carbon Server is starting, it first checks for the text file called "password" in $GREG<GREG_HOMEHOME> 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" in $GREG<GREG_HOMEHOME> and enter the keyStore password in the first line of the file. Steps are as follows:
- Shut down the server if it is already started.
- Create a text file named "password" in $GREG<
GREG_HOMEHOME>. - Enter your primary keystore password in the 1st line of the text file and save it.
- Start the Carbon Server using command, daemon. sh wso2server.sh -start
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.
Info title Important 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 title Note At every restart, the Admin has to create a text file.
...
Create a jar or an OSGI bundle. Copy the jar file to $GREG<GREG_HOMEHOME>/repository/component/lib/ directory or the OSGI bundle to $GREG<GREG_HOMEHOME>/repository/component/dropins/ directory. Configure the <GREG_HOME>/repository/conf/user-mgt.xml file with an alias name and your secret callback handler class name. For example,
...
| Code Block |
|---|
transports.https.keystorePass -> SSL key and keystore password in mgtcatalina-transportserver.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 |