Content Comparison

WSO2 Carbon-based products are shipped with a default keystore named wso2carbon.jks, which is stored in the <PRODUCT_HOME>/repository/resources/security directory. This keystore comes with a private/public key pair that is used to encrypt sensitive information, for communication over SSL and for encryption/signature purposes in WS-Security. However, note that since wso2carbon.jks is available with open source WSO2 products, anyone can have access to the private key of the default keystore. It is therefore recommended to replace this with a keystore that has self-signed or CA signed certificates when the products are deployed in production environments. 

• Creating a keystore using an existing certificate
• Creating a keystore using a new certificate
• Adding the public key to client-truststore.jks
• Updating configurations in WSO2 products
• Product-specific configurations

Creating a keystore using an existing certificate

Secure Socket Layer (SSL) is a protocol that is used to secure communication between systems. This protocol uses a public key, a private key and a random symmetric key to encrypt data. As SSL is widely used in many systems, certificates may already exist that can be reused. In such situations, you can use the CA-signed certificates to generate a Java keystore using OpenSSL and the Java keytool.

1. First you must export certificates to the PKCS12/PFX format. Give strong passwords whenever required.

   Info
   In WSO2 products, it is a must to have same password for both keystore and key.

   Execute the following command to export the certificates:

   Code Block
   language powershell
   openssl pkcs12 -export -in <certificate file>.crt -inkey <private>.key -name "<alias>" -certfile <additional certificate file> -out <pfx keystore name>.pfx

2. Convert the PKCS12 to a Java keystore using the following command:

   Code Block
   language powershell
   keytool -importkeystore -srckeystore <pkcs12 file name>.pfx -srcstoretype pkcs12 -destkeystore <JKS name>.jks -deststoretype JKS

   Now you have a keystore with CA-signed certificates.

Creating a keystore using a new certificate

If there are no certificates signed by a Certification Authority, creating a keystore with keys and signed certificates involves the steps given below. We will be using the key tool installation that is available with your JDK installation.

Step 1: Creating keystore with private key and public certificate

1. Open a command prompt and go to the <PRODUCT_HOME>/repository/resources/security/ directory. All keystores should be stored here.

2. Create the keystore that includes the private key by executing the following command:

   Code Block
   language powershell
   keytool -genkey -alias certalias -keyalg RSA -keysize 2048 -keystore newkeystore.jks -dname "CN=<testdomain.org>,OU=Home,O=Home,L=SL,S=WS,C=LK" -storepass mypassword -keypass mypassword

   This command will create a keystore with the following details: 

   • Keystore name: newkeystore.jks
   • Alias of public certificate: certalias
   • Keystore password: mypassword
   • Private key password: mypassword (this is required to be the same as keystore password)

   Note

   Note that if you did not specify values for the '-keypass' and the '-storepass' in the above command, you will be asked to give a value for the '-storepass' (password of the keystore). As a best practice, use a password generator to generate a strong password. You will then be asked to enter a value for -keypass. Click Enter, because we need same password for both keystore and key. Also, if you did not specify values for -dname, you will be asked to provide those details individually.

3. Open the <PRODUCT_HOME>/repository/resources/security/ directory and see that the new keystore file is created. Make a backup of it and move it to a secure location. This is important as it is the only place with our private key. 

Step 2: Creating CA-signed certificates for public key

Now we have a .jks file. Then we need to use that keystore (.jks) to generate a certificate signing request (CSR). CSR is the file we need to provide to the certificate authority (CA).

1. Execute the following command to generate the CSR:

   Code Block
   language powershell
   keytool -certreq -alias certalias -file newcertreq.csr -keystore newkeystore.jks

   Note
   As mentioned before, use the same alias that you used during the keystore creation process.

   You will be asked to give the keystore password. Once the password is given, the command will output the newcertreq.csr file to the <PRODUCT_HOME>/repository/resources/security/ directory. This is the CSR which you must submit to a CA.

2. Now you must provide this CSR file to the CA. For testing purposes, try the 90 days trial SSL certificate from Comodo.

   Note

   It is preferable to have a wildcard certificate or multiple domain certificates if you wish to have multiple subdomains like gateway.sampledomain.org, publisher.sampledomain.org, identity.sampledomain.org, etc., for the deployment. For such requirements you must modify the CSR request by adding subject alternative names. Most of the SSL providers give instructions to generate the CSR in such cases.

3. After accepting the request, a signed certificate is provided along with several intermediate certificates (depending on the CA) as a bundle (.zip).

   Panel
   title Sample certificates provided by the CA (Comodo)
   The Root certificate of the CA: AddTrustExternalCARoot.crt  Intermediate certificates:  COMODORSAAddTrustCA.crt , COMODORSADomainValidationSecureServerCA.crt  SSL Certificate signed by CA: test_sampleapp_org.crt

Step 3: Importing CA-signed certificates to keystore

1. Before importing the CA-signed certificate to the keystore, you must add the root CA certificate and the two intermediate certificates by executing the commands given below. Note that the sample certificates given above are used as examples.

   Code Block

   keytool -import -v -trustcacerts -alias ExternalCARoot -file AddTrustExternalCARoot.crt -keystore newkeystore.jks -storepass mypassword keytool -import -v -trustcacerts -alias TrustCA -file COMODORSAAddTrustCA.crt -keystore newkeystore.jks -storepass mypassword keytool -import -v -trustcacerts -alias SecureServerCA -file COMODORSADomainValidationSecureServerCA.crt -keystore newkeystore.jks -storepass mypassword

   Note
   Optionally we can append the -storepass <keystore password> option to avoid having to enter the password when prompted later in the interactive mode.

2. After you add the root certificate and all other intermediate certificates, add the CA-signed SSL certificate to the keystore by executing the following command:

   Code Block
   language powershell
   keytool -import -v -alias <certalias> -file <test_sampleapp_org.crt> -keystore newkeystore.jks -keypass myppassword -storepass mykpassword

   Note
   In this command, use the same alias that you used while creating the keystore.

Now you have a Java keystore including a CA-signed certificate that can be used in a production environment. Next, you must add its public key to the client-truststore.jks file to enable backend communication and inter-system communication via SSL.

Adding the public key to client-truststore.jks

To add the public key of the signed certificate to the client trust store:

1. Get a copy of the client-truststore.jks file from the <PRODUCT_HOME>/repository/resources/security/ directory.

2. Export the public key from your .jks file using the following command.

   Code Block
   language powershell
   keytool -export -alias certalias -keystore newkeystore.jks -file <public key name>.pem

3. Import the public key you extracted in the previous step to the client-truststore.jks file using the following command.

   Code Block
   language powershell
   keytool -import -alias certalias -file <public key name>.pem -keystore client-truststore.jks -storepass wso2carbon

   Note
   Note that 'wso2carbon' is the keystore password of the default client-truststore.jks file.

Now, you have an SSL certificate stored in a Java keystore and a public key added to the client-truststore.jks file. Note that both these files should be in the <PRODUCT_HOME>/repository/resources/security/ directory. You can now replace the default wso2carbon.jks keystore in your product with the newly created keystore by updating the relevant configurations files in your product.

Updating configurations in WSO2 products

After you update the client-truststore.jks file and add the new keystore to the WSO2 product, you must update a few configuration files in order to make it work as follows.

1. Make the following changes to the <PRODUCT_HOME>/repository/conf/carbon.xml configuration file.

   1. Set the HostName and MgtHostName accordingly.

      Code Block
      language xml
      <HostName>test.sampleapp.org</HostName> <MgtHostName>test.sampleapp.org</MgtHostName>

   2. Update the keystore settings accordingly.

      Code Block
      language xml
      <Security> <KeyStore> <Location>${carbon.home}/repository/resources/security/<jks name>.jks</Location> <Type>JKS</Type> <Password><jks store password></Password> <KeyAlias><jks alias></KeyAlias> <KeyPassword><jks store password(same as the key password)></KeyPassword> </KeyStore> ... <RegistryKeyStore> <Location>${carbon.home}/repository/resources/security/<jks name>.jks</Location> <Type>JKS</Type> <Password><jks store password></Password> <KeyAlias><jks alias></KeyAlias> <KeyPassword><jks store password(same as the key password)></KeyPassword> </RegistryKeyStore> <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)>

2. Make the following changes in the <PRODUCT_HOME>/repository/conf/identity.xml file.

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

   Add the following information into the transportReceiver and transportSender sections.

   • <jks name>
   • <jks store password>

3. 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
   language xml
   <transportSender name="https" class="org.apache.synapse.transport.nhttp.HttpCoreNIOSSLSender"> <parameter name="non-blocking" locked="false">true</parameter> <parameter name="keystore" locked="false"> <KeyStore> <Location>repository/resources/security/wso2carbon.jks</Location> <Type>JKS</Type> <Password>wso2carbon</Password> <KeyPassword>wso2carbon</KeyPassword> </KeyStore> </parameter> <parameter name="truststore" locked="false"> <TrustStore> <Location>repository/resources/security/client-truststore.jks</Location> <Type>JKS</Type> <Password>wso2carbon</Password> </TrustStore> </parameter> </transportSender>

4. Uncomment the following configurations and change the default keystore properties in the KeyStores section in the <PRODUCT_HOME>/repository/conf/security/secret-conf.properties file accordingly if you are using it.

   Code Block
   language text
   ##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>

Now you can start the server as usual and try to access the web console of your WSO2 product. The following is what the web console URL would look like for this example: https://test.sampleapp.org:9443/publisher/

Product-specific configurations

After you update the client-truststore.jks file and add the new keystore to the WSO2 product, you must update a few product-specific configuration files in order to make it work as follows.

...

Related links

...