This documentation is for WSO2 Carbon 4.2.0. View documentation for the latest release.
Page Comparison - Configuring Keystores in WSO2 Products (v.16 vs v.69) - Carbon 4.2.0 - WSO2 Documentation

Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

Keystores allow you to manage the keys that are stored in a database. A Keystore must contain a key pair with a certificate signed by a trusted Certification Authority (CA). A CA is an entity trusted by all parties participating in a secure communication. This entity will certify the trusted party's public keys by signing them. Since the certificate authority is trusted, it will accept the public key certificates signed by that particular CA as trusted. WSO2 Carbon uses several keystores to power the HTTPS transport and to encrypt other confidential information such as administrator passwords.

Table of Contents
maxLevel3
minLevel3

Keystore of the HTTPS transport

The keystore of the HTTPS transport is configured in the axis2.xml file under the HTTPS transport receiver and HTTPS transport sender configurations. 

...

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. 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.

Tip

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.

Code Block
./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. 

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

...

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/resources/security directory. To change the keystores used by the HTTPS transport, update the HTTPS transport receiver and sender configurations by specifying the paths to keystores files and other attributes of the files such as the keystores passwords.

Info

Under the <KeyStore> element two password values must be specified.

The <Password> element should indicate the password of the keystore file.
The <KeyPassword> element should point to the password required to access the private key.

Keystore for encrypting confidential information

The keystores used to encrypt administrator passwords and other confidential information in Carbon is configured in the <PRODUCTconf/ directory should be updated with details of the keystore used for enabling Java permissions for your server. The default configuration is shown below.

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

NOTE to WRITERS: The following section can be used to list down product specific configuration files that use keystores. For example in BAM:

  Product-specific configurations

  • Make the following changes in the <PRODUCT_HOME>/repository/conf/

...

  • identity.xml file.

...

Keystore for SSL connection to server

The keystore configuration used to store the certification for the SSL server connection is as follows.

Code Block
<KeyStore>
  • Code Block
    languagexml
    <Security>
    	<UserTrustedRPStore>
    			<!-- Keystore password -->
    			<Password>wso2carbon</Password>
    			<!-- Private Key password -->
    			<KeyPassword>wso2carbon</KeyPassword>
    	</UserTrustedRPStore>
    </Security>
    <EntitlementSettings>
    ...
    	<ThirftBasedEntitlementConfig>
    ...
    		<KeyStore>
    			<Location>${carbon.home}/repository/resources/security/
wso2carbon
  • <jks name>.jks</Location>
    
<Type>JKS</Type> <Password>wso2carbon<
  • 			<Password><jks store password></Password>
    	
<KeyAlias>wso2carbon<
  • 	</
KeyAlias>
  • KeyStore>
    	
<KeyPassword>wso2carbon<
  • </
KeyPassword>
  • ThirftBasedEntitlementConfig>
    </
KeyStore>

Keystore for encrypting to registry

The keystore configuration used for encrypting meta data into the registry in Carbon is as follows.

Code Block
<RegistryKeyStore>
  • EntitlementSettings>
  • If you want to use NIO sender, change the  <transportSender> section in the <PRODUCT_HOME>/repository/conf/axis2/axis2.xml file accordingly as shown below.

    Code Block
    languagexml
    <transportSender name="https" class="org.apache.synapse.transport.nhttp.HttpCoreNIOSSLSender">
            <parameter name="non-blocking" locked="false">true</parameter>
           
<!--
  •  
Keystore file location-->
  • <parameter name="keystore" locked="false">
                <KeyStore>
              
<Location>${carbon.home}/repository
  •       <Location>repository/resources/security/wso2carbon.jks</Location>
                    <Type>JKS</Type>
          
<!-- Keystore type (JKS/PKCS12 etc.)-->
  •           <Password>wso2carbon</Password>
                    
<Type>JKS</Type>
  • <KeyPassword>wso2carbon</KeyPassword>
                </KeyStore>
            <
!-- Keystore password-->
  • /parameter>
            <parameter name="truststore" locked="false">
                <TrustStore>
      
<Password>wso2carbon</Password>
  •               
<!-- Private Key alias-->
  • <Location>repository/resources/security/client-truststore.jks</Location>
                    
<KeyAlias>wso2carbon<
  • <Type>JKS</
KeyAlias>
  • Type>
                 
<!--
  •  
Private
  •  
Key password-->
  •  <Password>wso2carbon</Password>
                
<KeyPassword>wso2carbon</KeyPassword>
  • </TrustStore>
            </
RegistryKeyStore>
  • parameter>
    </transportSender>