Configuring Keystores in WSO2 Products

After you have created a new keystore and updated the client-truststore.jks file, you must update a few configuration files in order to make the keystores work. Note that keystores are used for multiple functions in WSO2 products, which includes authenticating communication over SSL/TLS, encrypting passwords and other confidential information in configuration files etc. Therefore, you must update the specific configuration files with the updated keystore information. For example, you may have separate keystores for the purpose of encrypting passwords in configuration files, and for authenticating communication over SSL/TLS.

The wso2carbon.jks keystore file, which is shipped with all WSO2 products, is used as the default keystore for all functions. However, in a production environment, it is recommended to create new keystores with new keys and certificates.

Please note that in WSO2 IoT Server the <PRODUCT_HOME>/repository/conf directory is in the following location: <PRODUCT_HOME>/conf

If you want an easy way to locate all the configuration files that have references to keystores, you can use the grep command as follows:

Open a command prompt and navigate to the <PRODUCT_HOME>/repository/conf/ directory where your product stores all configuration files.
Execute the following command: grep -nr ".jks" .

The configuration files and the keystore files referred to in each file are listed out. See an example of this below.

./axis2/axis2.xml:260:                <Location>repository/resources/security/wso2carbon.jks</Location>
./axis2/axis2.xml:431:                <Location>repository/resources/security/wso2carbon.jks</Location>
./carbon.xml:316:            <Location>${carbon.home}/repository/resources/security/wso2carbon.jks</Location>
./carbon.xml:332:            <Location>${carbon.home}/repository/resources/security/wso2carbon.jks</Location>
./identity.xml:180:				<Location>${carbon.home}/repository/resources/security/wso2carbon.jks</Location>
./security/secret-conf.properties:21:#keystore.identity.location=repository/resources/security/wso2carbon.jks

See the following for details:

Before you begin

Be sure to go through the recommendations for setting up keystores in WSO2 products to understand the various keystores you will need.
If you haven't already created the keystores required for your system, see the instructions for creating new keystores.

Configuring the primary keystore (for internal data encryption)

Encrypting administrator passwords as well as other confidential, internal information that are maintained in various product-level and product feature-level configurations/configuration files can be classified as internal data encryption. The Keystore element in the carbon.xml file, stored in the <PRODUCT_HOME>/repository/conf/ directory should be updated with details of the keystore serving this purpose.

Be sure to use a keystore with a public key certificate that contains the Data Encipherment key usage as explained in the keystore recommendations. Otherwise, the following error can occur when you attempt data encryption:

Exception in thread "main" org.wso2.ciphertool.CipherToolException: Error initializing Cipher at org.wso2.ciphertool.CipherTool.handleException(CipherTool.java:861) at org.wso2.ciphertool.CipherTool.initCipher(CipherTool.java:202) at org.wso2.ciphertool.CipherTool.main(CipherTool.java:80) Caused by: java.security.InvalidKeyException: Wrong key usage at javax.crypto.Cipher.init(DashoA13..) at javax.crypto.Cipher.init(DashoA13..) at org.wso2.ciphertool.CipherTool.initCipher(CipherTool.java:200) ... 1 more

The default configuration is shown below.

<KeyStore>
	<Location>${carbon.home}/resources/security/wso2carbon.jks</Location>
	<Type>JKS</Type>
	<Password>wso2carbon</Password>
	<KeyAlias>wso2carbon</KeyAlias>
	<KeyPassword>wso2carbon</KeyPassword>
</KeyStore>
 
<TrustStore>
	<!-- trust-store file location -->
	<Location>${carbon.home}/repository/resources/security/client-truststore.jks</Location>
	<!-- trust-store type (JKS/PKCS12 etc.) -->
	<Type>JKS</Type> 
	<!-- trust-store password -->
	<Password>wso2carbon</Password>
</TrustStore>

Configuring a secondary keystore (for SSL connections)

The catalina-server.xml file stored in the <PRODUCT_HOME>/repository/conf/tomcat/ directory should be updated with the keystore used for certifying SSL connections to Carbon servers. Given below is the default configuration in the catalina-server.xml file, which points to the default keystore in your product.

keystoreFile="${carbon.home}/repository/resources/security/wso2carbon.jks"
keystorePass="wso2carbon"

Configuring a keystore for Java permissions

The Java Security Manager is used for defining various security policies that prevent untrusted code from manipulating your system. Enabling the Java Security Manager for WSO2 products will activate the Java permissions that are in the <PRODUCT_HOME>/repository/conf/sec.policy file. Administrators can modify this file to change the Java security permissions as required and grant various application-level permissions to the signed and trusted code using Java.

If you are granting specific Java-level permissions to some signed code, you should import the public key certificate of the signer as a trusted certificate to one of your keystores. You must then update the sec.policy file with the keystore path and the alias of the certificate as shown below.

keystore "file:${user.dir}/repository/resources/security/wso2carbon.jks", "JKS";

Following is the default keystore configuration in the sec.policy file, which grants all Java-level permissions to the code signed by the certificate that uses the “wso2carbon” alias.

grant signedBy "wso2carbon" {
  permission java.security.AllPermission;
};

Configuring keystores for WS-Security

If there are WS-Security scenarios implemented in your WSO2 product, you can use separate keystores for these scenarios.

What's next?

Some WSO2 products will use keystore for more use cases than the ones listed above. See the documentation for your WSO2 product for instructions.

Carbon 4.4.1