Encrypting passwords in config files using a separate keystore (an internal keystore) in WSO2 servers.

Image Source: https://www.flickr.com/photos/30478819@N08/51080621877

In any software product it is not a wiser decision to leave sensitive information like administrator passwords, database passwords, keystore passwords, private key password and etc. in plain text in relevant configuration files as it posses a sever security vulnerability. So almost all of the software vendors today provide a way to secure the sensitive information used by their software products.

At WSO2 we do the same and by any chance if you have used any of the WSO2 products in past, you might have already come across the terms like cipher tool and secure vault which are provided by WSO2 for the above purpose. Since the above two features are available out of the box in all of the WSO2 products based on Carbon Kernel 4.4.0 and higher, encrypting/decrypting sensitive information in configuration files can be easily done without any overhead 😌

That been said, from the latest releases of WSO2 products (wso2is-5.7.0, wso2is-analytics-5.7.0, wso2is-km-5.7.0, wso2am-2.6.0, wso2am-analytics-2.6.0, wso2ei-6.4.0, wso2-obam-1.3.0, wso2-obbi-1.3.0, wso2-obkm-1.3.0 and etc.) you could define a separate keystore to be used by both the cipher tool and secure vault used in encrypting/decrypting sensitive information in configuration files, other than the primary keystore that was used by default in previous releases. Here the primary keystore is the keystore which is been configured as the <Security>/<KeyStore> element in <PRODUCT_HOME>/repository/conf/carbon.xml file in any WSO2 product.

(By default all WSO2 products uses the preshipped wso2carbon.jks located at <PRODUCT_HOME>/repository/resources/security/ directory as the primary keystore).

The above feature gets really useful in a scenario, where you would like to have a separate internal keystore (which will not change at all 😉) for encrypting sensitive information in configuration files and another keystore for signing messages and assertions send for third parties (using the protocols like SAML, OIDC and etc.). This because the keystore certificates used in public communications over the Internet has an expiry time and when the certificate get expires you would need to go through a huge burden of migrating the already encrypted sensitive information at your servers 😟.

So to live an easy life lets see how to configure the internal keystore in WSO2 products, which will allow you to change the keystore used for signing messages and assertions send for third parties at any point in time 😌.

• For latest products mentioned above.

For the latest products configuring the internal keystore is pretty simple and straight forward as the above feature is supported out of the box in them 😅 . All you need is to configure the <Security>/<InternalKeyStore> element in <PRODUCT_HOME>/repository/conf/carbon.xml file to point to the relevant internal keystore as follows,

<InternalKeyStore>
            <!-- Keystore file location-->
            <Location>${carbon.home}/repository/resources/security/internalKeystore.jks</Location>
            <!-- Keystore type (JKS/PKCS12 etc.)-->
            <Type>JKS</Type>
            <!-- Keystore password-->
            <Password>yourPassword</Password>
            <!-- Private Key alias-->
            <KeyAlias>wso2internal</KeyAlias>
            <!-- Private Key password-->
            <KeyPassword>yourPassword</KeyPassword>
</InternalKeyStore>

• For previous version of WSO2 servers.

If you are using a previous version of a WSO2 server, you need to get the latest wum updated distribution as the above feature is provided via an update (released on 8th of July 2018) to previous WSO2 products. Please refer WSO2 Update Channels on how to use WUM for updating your WSO2 servers.

Upon updating your product please follow below instructions in order to enable this feature,

1. Enable the Crypto Service by adding the following configuration block to the <PRODUCT_HOME>/repository/conf/carbon.xml file.

<CryptoService>
<Enabled>true</Enabled>
<InternalCryptoProviderClassName>org.wso2.carbon.crypto.provider.KeyStoreBasedInternalCryptoProvider</InternalCryptoProviderClassName>
<ExternalCryptoProviderClassName>org.wso2.carbon.core.encryption.KeyStoreBasedExternalCryptoProvider</ExternalCryptoProviderClassName>
<KeyResolvers>
<KeyResolver className="org.wso2.carbon.crypto.defaultProvider.resolver.ContextIndependentKeyResolver" priority="-1"/>
</KeyResolvers>
</CryptoService>

2. Configure the new keystore by adding the following configuration block inside the <Security> element in the <PRODUCT_HOME>/repository/conf/carbon.xml file.

<InternalKeyStore>
            <!-- Keystore file location-->
            <Location>${carbon.home}/repository/resources/security/internalKeystore.jks</Location>
            <!-- Keystore type (JKS/PKCS12 etc.)-->
            <Type>JKS</Type>
            <!-- Keystore password-->
            <Password>yourPassword</Password>
            <!-- Private Key alias-->
            <KeyAlias>wso2internal</KeyAlias>
            <!-- Private Key password-->
            <KeyPassword>yourPassword</KeyPassword>
</InternalKeyStore>

Please visit cipher tool doc and secure vault doc for more information regarding their usage and extensibility.

Cheers !!!!