This documentation is for WSO2 Carbon 4.2.0. View documentation for the latest release.
Configuring Keystores in WSO2 Products - Carbon 4.2.0 - WSO2 Documentation
Skip to end of metadata
Go to start of metadata

You are viewing an old version of this page. View the current version.

Compare with Current View Page History

« Previous Version 61 Next »

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 keystore work the way it is intended to. Note that keystores are used for multiple functions in WSO2 products, which includes securing the servlet transport, encrypting confidential information in configuration files, etc. Therefore, you must update the specific configuration files with the relevant keystore information. For example, you may have separate keystores for the purpose of encrypting passwords in configuration files, and for securing the servlet transport. 

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 keys and certificates.

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:

  1. Open a command prompt and navigate to the <PRODUCT_HOME>/repository/conf/ directory where your product stores all configuration files.
  2. 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

Configuring the primary keystore

The primary keystore mainly stores the keys certifying SSL connections to Carbon servers and the keys for encrypting administrator passwords as well as other confidential information. The Keystore element in the carbon.xml file, stored in the < PRODUCT_HOME>/repository/conf/ directory must be updated with details of the primary keystore. 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>

You need to add in the following information:

  • <jks store password>
  • <jks alias>
  • <jks store password(same as the key password)>

Configuring a keystore for Java permissions

The sec.policy file stored in the <PRODUCT_HOME>/repository/conf/ directory should be updated with details of the keystore used for enabling Java permissions for your server. The default configuration is shown below. 

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

Configuring Secure Vault for password encryption

All passwords in configuration files are made secure by encrypting them using cipher text. When a password is encrypted, a keystore is required for creating the decryption crypto to resolve encrypted secret values. The secret-conf.properties file, stored in the <PRODUCT_HOME>/repository/conf/security/ directory is used for this purpose. Therefore, you must update this file with the relevant keystore information.

##KeyStores configurations
#
#keystore.identity.location=repository/resources/security/wso2carbon.jks
#keystore.identity.type=JKS
#keystore.identity.alias=wso2carbon
#keystore.identity.store.password=wso2carbon
##keystore.identity.store.secretProvider=<any implementation of org.apache.synapse.commons.security.secret.SecretCallbackHandler>
#keystore.identity.key.password=wso2carbon
##keystore.identity.key.secretProvider=<any implementation of org.apache.synapse.commons.security.secret.SecretCallbackHandler>
##keystore.identity.parameters=enableHostnameVerifier=false;keyStoreCertificateFilePath=/home/esb.cer
#
#keystore.trust.location=repository/resources/security/client-truststore.jks
#keystore.trust.type=JKS
#keystore.trust.alias=wso2carbon
#keystore.trust.store.password=wso2carbon
##keystore.trust.store.secretProvider=<any implementation of org.apache.synapse.commons.security.secret.SecretCallbackHandler> 

Configuring a keystore for registry metadata

RegistryKeyStore is a separate keystore element configurable in the carbon.xml file. This configuration applies for the keystore which stores the keys that certify encrypting/decrypting meta data to the registry. Therefore, using the registry keystore in addition to the primary keystore in the carbon.xml  file allows you to maintain a separate keystore for the purpose of encrypting/decrypting meta data to the registry.

Copy the following <RegistryKeystore> element to the carbon.xml file under the <Security> element. In the following example, we are referring to the default keystore in the product pack  ( wso2carbon.jks) as the registry keystore . You can change these values so that the configuration corresponds to the actual registry keystore in your system.

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

Configuring keystores for WS-Security 

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

Configuring keystores for advanced transport handling

To have more advanced transport handling functions using keystores, you need to update the <PRODUCT_HOME>/repository/conf/tomcat/catalina-server.xml file and the <PRODUCT_HOME>/reposotory/conf/axis2/axis2.xml file.

  • No labels