Since most WSO2 products are open source, all passwords need to be encrypted. This blog is applicable to any WSO2 product, for example WSO2 API Manager, WSO2 Enterprise Integrator and WSO2 Identity Server. But let me first start with an introduction.

Scientists have been studying human behavior and personality traits for more than a couple of hundred years. And they still have a long way to go in order to fully understand how our brain works. But one thing that they have figured out about the human personality, is that everybody likes to keep secrets. Its an interesting piece of observation, that most people have secrets that they won’t even share with their closest family, friends or even partners. When people keep secrets, they sometimes share it in different circles of people in their lives. If I’ve done something wild ( ), I’d probably rather share it with my friends than with my parents. Or I even might never share it with my parents. I think if we look at our lives, we can test this theory. Just take a deep breath and think about the secrets that you have in your life or pieces of information about your life that you may not want to share with everyone. Similarly, there is another thing that you will notice: different people in your live have different information about you at any given time. Some people know one aspect of your personality and some knows other.  There is also another aspect of it, as much as human beings like to keep secrets, they also like to gossip. In fact, human beings use the language mainly to learn about other people lives. Who is doing what, who is in relationship, who cheated, stuff like that. But how does this relate to WSO2?

WSO2 Products

In the above context, if we want to make a system secure enough, so that no one can mess with the systems and view the secrets (for example, passwords), we must take some steps to ensure that this does not happen. Even if a hacker or security breach could get the intruder to where the products are deployed, the intruder should not get all the passwords on a record. After all, every security measure means that we create a new obstacle for anyone who wants to or can cause damage. Since most WSO2 products are open source, all passwords related to Truststores or Keystores and all other passwords are written in the Plain Text Format. When we make a system production ready, it is very important that we don’t allow these passwords to be remain there in just an unencrypted form. We need to encrypt it. Here Cipher Tool comes in. 

Cipher Tool

We can use the cipher tool in two ways to encrypt the passwords:

1. Encrypt passwords Automatically
2. Encrypt passwords Manually

In this blog post we will discuss the manual way. If you want to see how to do it through the automatic way, then please refer the WSO2 documentation.

Encrypting Passwords Manually

This process helps us to encrypt those passwords manually that can not be reached by an XPath expression or a configurations file that does not contain the xml. For example, the log4j.properties file.  This file is usually located at <PRODUCT_HOME>/repository/conf file path.

Let’s suppose we want to encrypt the password of log event appender and does not want it to be remain as plain text. We will do this through following steps:

1. First, we will activate the Cipher Tool, if it has not been previously used by running following command in the <PRODUCT_HOME>/bin directory:

• On Linux: ./ciphertool.sh -Dconfigre
• On Windows: ciphertool.bat -Dconfigure

2. After that we can start the manual encryption process. First, we will start the cipher tool by following command:

• On Linux: ./ciphertool.sh
• On Windows: ciphertool.bat

3. This will ask you for the primary key store password. By default, it is “wso2carbon”, you can enter the password:

4. After that it will ask you for the plain text value that you want to encrypt two times. Please then enter the values: (Note: while you are enter the value, you cannot see it )

5. Once you have successfully entered the plain text value that you want to encrypt,  the encrypted version of the plain text that you earlier entered will be displayed.

6. After we have got the encrypted value, we will create the alias in the <PRODUCT_HOME>/repository/conf/security/cipher-text.properties file. Then paste the encrypted value there.

7. Now we will add the secret alias in the log4j file so that it can refer to the encrypted key.

8. Just restart the product and you are good to go.

In similar fashion, we can now encrypt any password in any configuration file. But there are always some exceptions that we need to take care of. For example, if we want to encrypt the trust store and KeyStore password in the <PRODUCT_HOME>/repository/conf/identity/EndpointConfig.properties file. For that if we have generated following two keys:

• Security.KeyStore.Password

• Security.TrustStore.Password

In order to make it work, you will also have to add the values of keys itself by using the following two line:

• - protectedTokens=Carbon.Security.KeyStore.Password,Carbon.Security.TrustStore.Password

• - mutualSSLManagerEnabled=false

So, this is how your EndpointConfig.properties file would look like:

By following the above technique, we can now encrypt the password in WSO2 products manually. Try this example scenario yourself and don’t hesitate to give your feedback or ask any questions in the comment section below.