Securing WSO2 Enterprise Integrator 6.5 Analytics Using Secure Vault

Abstract

An application may have numerous configuration files—which are used to define how the application should function. Some of these configuration files may include passwords. Plaintext passwords in configuration files would allow anyone with read access to the configuration files to obtain them. Hence, having plaintext passwords in configuration files is considered a bad practice as explained in this Password Plaintext Storage OWASP article.

WSO2 Enterprise Integrator Analytics has several such configuration files. They provide database connection configurations, keystore configurations, clustering configurations, etc. Some of them include passwords. To prevent plaintext passwords from being leaked through configuration files, WSO2 products include the Secure Vault tool that makes it possible to use encrypted passwords in configuration files.

This tutorial will guide you on securing a WSO2 Enterprise Integrator 6.5 Analytics worker installation using WSO2 Secure Vault. Some other WSO2 products/product profiles follow a similar approach and this guide will be applicable to these as well.

Background

The secure vault feature is shipped with WSO2 Enterprise Integrator Analytics by default. Therefore, we do not need to install any additional plugins to start using it; we only need to configure it.

When configuring Secure Vault, we need to work with three main files.

1. secrets.properties(<PRODUCT_HOME>/wso2/analytics/conf/worker/secrets.properties)

When passwords are encrypted using Secure Vault, all encrypted passwords are specified in a single file, which is the secrets.properties file.

It includes mapping from a given alias to the base64 encoded ciphertext of a password that you wish to use in one of the configuration files. The mappings have the following format.

<alias>=<type> <value>

Alias = The name that you would like to use to refer the password in configuration files
Type = {plainText, cipherText}
value = A password in plaintext or the ciphertext in base64 encoded format

Example:

password.1=plainText thisIsAPlainTextPassword
password2=cipherText o3jOcVzrP/9yxNn75eeG0g9UImMt/WoRyt/XF2YV+MEA2poe/1NJMOjew6Yae4Rb8efvQv+lwCK7X0UqkTCblOVjQ0z0wSlvhehCB2X1PCShEo0ze8eAsL73VLUZoBmoEl3TDERkI5tt5YDMqnGoyc7xxTxk6VJHLo7HMzOJCFk4Hc832NvP7f7E1S8ThpAnJR/c5ECBils/kpfQzS9rADno4mczrhWSk72skSMMU8HGJHx6/Ln/XBWvKAdk25n7SINZUGDd2vB/f0xxqK3W+6oLwWWl3TUI0v4vhb7qZKIDh/numD/aBWSxyII/B7IF657RZLPov2PSBKHaGunxcQ==

2. Master-keys.yaml (<PRODUCT_HOME>/wso2/analytics/conf/worker/master-keys.yaml)

The base64 encoded plaintext keystore password and the base64 encoded plaintext private password of the keystore used for Secure Vault is defined in this file. WSO2 Carbon Server reads this file to obtain these two passwords, so that it can decrypt the passwords in the secrets.properties file in order to start the server. This file has an important parameter named “permanent”, which accepts the Boolean values true or false. WSO2 Carbon Server decides whether or not to delete the master-keys.yaml file after starting the server based on the value set for the “permanent” option as explained below.

true- Specifying “permanent: true” would cause the master-keys.yaml file to persist on the filesystem even after the WSO2 Carbon server has started. This means that the master-keys.yaml file is never deleted by the Carbon server. Therefore, after you have secured your installation with Secure Vault, you can stop and start the WSO2 carbon server without having to recreate the master-keys.yaml file. But, there is a catch; someone who has access to the master-keys.yaml file can obtain the base64 encoded plaintext password from it and can decode it to obtain the plaintext password. This, in turn, can be used to decrypt the passwords that are encrypted using Secure Vault. Therefore, it is better not to set this value to true.

false — Specifying “permanent: false” causes the master-keys.yaml file to be deleted after starting WSO2 Carbon Server. This means that we need to always recreate the master-keys.yaml file before starting WSO2 Carbon Server, so that it can read the keystore password and decrypt the passwords in configuration files. Furthermore, this also means that if the master-keys.yaml file has already been deleted when we are setting up Secure Vault, we need to enter the keyStorePassword and the privateKeyPassword when we run the ciphertool.sh script (this is explained later in detail).

3. deployment.yaml(<PRODUCT_HOME>/wso2/analytics/conf/worker/deployment.yaml)

This file contains product configurations including places to define passwords, e.g., Datasource passwords. The alias values that are defined in the secrets.properties file are used in the deployment.yaml file to map the passwords in the secrets.properties file to the deployment.yaml file.

In addition to the above files, we will also be using the script <PRODUCT_HOME>/wso2/analytics/bin/ciphertool.sh when setting up Secure vault. This script is what encrypts and decrypts the passwords using Secure Vault.

Now that we have a basic understanding of WSO2 Secure Vault and the files associated with it, we can start securing our Enterprise Integrator 6.5 Analytics installation using Secure Vault.

Instructions

1. Download the WSO2 Enterprise Integrator 6.5 binary from https://wso2.com/enterprise-integrator/6.5.0 and extract it. (I have extracted it to my home directory for the purpose of this tutorial. Therefore my <PRODUCT_HOME> will be ~/wso2ei-6.5.0. Your <PRODUCT_HOME> need not be the same and you may select any location that you prefer.
2. Navigate to <PRODUCT_HOME>/wso2/analytics/conf/worker Here, you will find the three files that we will be working with to set up Secure Vault. They are the master-keys.yaml file, secrets.properties file and the deployment.yaml file discussed earlier.
3. In the master-keys.yaml file, set permanent: false so that the master-keys.yaml file gets deleted after starting the WSO2 Carbon server.
4. Open the master-keys.yaml file, and set the key store password and the private password of the keystore used for secure vault. The keystore used for secure vault is specified in the deployment.yaml file and is configured to use <PRODUCT_HOME>/wso2/analytics/resources/security/securevault.jks by default. Please note that the passwords that we must specify in this file are the base64 encoded plaintext values of the passwords. The format is as follows:

   keyStorePassword: !!binary <base64EncodedPlainTextPassword>
   privateKeyPassword: !!binary <base64EncodedPlainTextPassword>

   We can use the base64 command in Linux as follows to encode our passwords.

   echo -n <PlainTextPassword> | base 64

5. Next, we will encrypt the passwords that we are going to use in configuration files. There are two methods to do so.
   One method is to specify all the plaintext passwords in the secrets.properties file and encrypt and base64 encode them in one go using the ciphertool.sh script. The other method is to input each password into the ciphertool.sh script and obtain the base64 encoded ciphertext as output and add this output to the secrets.properties file. Method 1 is easier if you have multiple passwords that you need to encrypt (typical at the time of setting up Secure Vault initially)

Method one

Populate the secrets.properties file with the plaintext values of all the password that you want to encrypt.

Since we are populating the file with plaintext passwords, the format of each password entry should be as follows.

<password alias>= plainText <plaintext password>

The password alias can be any name you wish to use.

Next, execute the ciphertool.sh script as follows.

./ciphertool.sh -runtime <productProfile>

Here productProfile would be worker as we are using the analytics worker profile of Enterprise Integrator.

If you set permanent:false in the master-keys.yaml file and if it had deleted, you will be prompted for the Key Store Password and the Private Key Password when you try to execute the ciphertool.sh script. Starting WSO2 Carbon Server with permanent:false would also result in the file being deleted.

This would encrypt all the passwords in the secrets.properties file and replace the plaintext values in it with the base64 encoded ciphertext values. The content of the secrets.properties file will have the following format after executing the ciphertool.sh script as above.

<password1Alias>=cipherText <base64EncodedCiphertext>
<password2Alias>=cipherText <base64EncodedCiphertext>
<password3Alias>=cipherText <base64EncodedCiphertext>

If you need to encrypt more passwords, simply append the plaintext passwords using the plaintext password format explained earlier and execute the ciphertool.sh script. It will then encrypt and encode the new passwords.

Method two

Execute the ciphertool.sh script as follows by providing the plaintext password to be encrypted.

./ciphertool.sh -encryptText <plainTextPassword> -runtime <productProfile>

Since we are working with the analytics worker profile, the <productProfile> would be worker.

If the master-keys.yaml file exists at the time of execution of the ciphertool.sh script, you will not be prompted for the keystore password and the private key password and the output will be as shown below.

However if the master-keys.yaml file had been deleted at the time of execution of the ciphertool.sh script, we will be prompted for passwords as shown below.

Execution of the ciphertool.sh script as described above outputs the base64 encoded ciphertext of the plaintext password that we provided. Now, we can manually populate the secrets.properties file according to the following format with the value returned from the above command.

<password1Alias>=cipherText <base64EncodedCiphertext>

We will need to repeat the steps under method two for each password that we would like to encrypt. Hence method one is easier if we have multiple passwords to be encrypted.

Now that we have encrypted the passwords using the ciphertool.sh script, we need to instruct the carbon server to refer to the encrypted and encoded values in the secrets.properties file. We use the following format inside the deployment.yaml file to refer to the passwords in the secrets.properties file.

Once all our passwords are secured using WSO2 Secure Vault in this manner, even a person who has access to the configuration files would not be able to find out the plaintext passwords.

Conclusion

Passwords that you use in WSO2 Enterprise Integrator Analytics configuration files are viewable by anyone who has read permission to these configuration files. In order to prevent this, WSO2 Enterprise Integrator Analytics includes the Secure Vault feature. Secure Vault makes it possible to use encrypted passwords in configuration files. This tutorial guided you on how to secure your WSO2 Enterprise Integrator Analytics installation using Secure Vault.