How to add new keystore to Carbon 4 based wso2 products.

All the wso2 carbon based products are shipping with default keystore called wso2carbon.jks.
You can be found it under PRODUCT_HOME/repository/resources/security. 
This keystore is used to communicate over SSL , encrypting security related information.

1. Create new keystore.

The Keystore is using to store the private key and certificates with their public keys.

Here, I'm going to use keytool functions, which is default shipped with your JDK installation.
Open a command window and execute the following command.

keytool -genkey -alias companycert -keyalg RSA -keysize 1024 -keypass companypkpassword -keystore companykeystore.jks -storepass companypkpassword

New keystore name = companykeystore.jks

Alias of the public certificate = companycert

Keystore password = companypkpassword (same password used as private key password)

You have to provide required info to generate the key store.

Eg:

What is your first and last name?

[Unknown]: Ajith Vitharana

What is the name of your organizational unit?

[Unknown]: Engineering

What is the name of your organization?

[Unknown]: ABC

What is the name of your City or Locality?

[Unknown]: Colombo

What is the name of your State or Province?

[Unknown]: Western

What is the two-letter country code for this unit?

[Unknown]: LK

Is CN=Ajith Vitharana, OU=Engineering, O=ABC, L=Colombo, ST=Western, C=LK correct?

[no]: yes

Now you can find the companykeystore.jks in the same location that you execute the command.  If you want to view the content of the new key store ,execute the following command.

keytool -list -v -keystore companykeystore.jks -storepass companypkpassword

Sample output :

Keystore type: JKS
Keystore provider: SUN

Your keystore contains 1 entry

Alias name: companycert
Creation date: Dec 4, 2012
Entry type: PrivateKeyEntry
Certificate chain length: 1
Certificate[1]:
Owner: CN=Ajith Vitharana, OU=Engineering, O=ABC, L=Colombo, ST=Western, C=LK
Issuer: CN=Ajith Vitharana, OU=Engineering, O=ABC, L=Colombo, ST=Western, C=LK
Serial number: 50bd3295
Valid from: Tue Dec 04 04:45:33 IST 2012 until: Mon Mar 04 04:45:33 IST 2013
Certificate fingerprints:
     MD5:  75:AE:2B:41:DF:C5:2A:D8:A2:D6:89:66:F0:1B:E4:EC
     SHA1: 52:35:50:EA:5D:6C:5A:27:AB:01:56:48:9F:97:48:CA:FB:5F:48:BC
     Signature algorithm name: SHA1withRSA
     Version: 3


*******************************************
*******************************************

2. Public certificate signed by CA.

We are recommend to get your public certificate signed by a CA. However for the testing purpose we are going to use the self signed certificate.

Note : Please find more details on this blog post on “get public certificate signed by CA” http://blog.facilelogin.com/2008/03/keystore-management-part-i.html 

3. Export public key certificate.

keytool -export -alias companycert -keystore companykeystore.jks -storepass companypkpassword -file ABCcompanycert.pem

Now you can find the public certificate(ABCcompanycert.pem) in same directory that you execute the command. 

4. Import public key to client trust store. 

 

The trust store is using to store the certificates of other parties that are suppose to communicate, or of  CAs(Certificate Authorities) that we trust to identify other parties.

Now, we should import this public key in to the client trust store.
 

i) Copy companykeystore.jks and ABCcompanycert.pem file to PRODUCT_HOME/repository/resources/security

ii) Locate your command line window to PRODUCT_HOME/repository/resources/security.

iii) Execute the following command to import the public certificate to client truststore(client-truststore.jks).

keytool -import -alias compantcert -file ABCcompanycert.pem -keystore client-truststore.jks -storepass wso2carbon

  
(wso2carbon = client truststore password)

Sample results:

Owner: CN=Ajith Vitharana, OU=Engineering, O=ABC, L=Colombo, ST=Western, C=LK
Issuer: CN=Ajith Vitharana, OU=Engineering, O=ABC, L=Colombo, ST=Western, C=LK
Serial number: 50bd0961
Valid from: Tue Dec 04 01:49:45 IST 2012 until: Mon Mar 04 01:49:45 IST 2013
Certificate fingerprints:
     MD5:  B8:6B:79:CA:6F:1D:4A:D3:04:64:8E:D7:C4:96:6A:BC
     SHA1: A1:48:1B:FC:8F:D8:69:B0:F3:3E:4B:EC:83:62:11:D6:63:71:1D:D8
     Signature algorithm name: SHA1withRSA
     Version: 3
Trust this certificate? [no]:  yes
Certificate was added to keystore

  

5) Change the key store configuration in carbon.xml

Open the carbon.xml file and change the default key store configuration as follow.

<KeyStore>

<Location>${carbon.home}/repository/resources/security/companykeystore.jks</Location>

<Type>JKS</Type>

<Password>companypkpassword</Password>

<KeyAlias>ABCcompanycert</KeyAlias>

<KeyPassword>companypkpassword</KeyPassword>

</KeyStore>

  

6) Open the PRODUCT_HOME/repository/conf/tomcat/catalina-server.xml and change keystoreFile and keystorePass  

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

keystorePass="companypkpassword"

7) Find inside the conf directory ( PRODUCT_HOME/repository/conf) for "wso2carbon.jks" to locate the all the other places having default key store configurations (axis2.xml, identity.xml ..etc), then configure that locations as well.


8) Start the Wso2 Carbon based product. 

9) Locate your browser to https://localhost:9443/carbon.

10) Now you should see the "Security Certificate Not Trusted" warning, because this is self signed certificate.

11) View the certificate details.

 

 

 12) Login to the admin console and navigate to Configure--> Keystore.
        Now you can view the details of companykeystore.jks .