Configure KeyStore (JKS) files in WSO2 products in Production

Lets discuss;  How you can properly configure KeyStores in WSO2 products. There are two main keystores in all products which are,

In 4.2.X products

  1. Primary KeyStore which is used for SSL
  2. Registry KeyStore which is used for Data encryption and decryption.
    You can find that both KeyStore configurations in the /repository/conf/carbon.xml file. By default; same wso2carbon.jks has been configured as both primary and registry KeyStores.

In recent WSO2 products (After 4.4.X),

  1. Primary Keystore is used for Data encryption and decryption which is configured in/repository/conf/carbon.xml 
  2. There is a separate SSL keystore which is used for tomcat transport (with 9443 connector).  It is configured in /repository/conf/tomcat/catalina-server.xml

But in real production, you MUST use different KeyStores for Primary and SSL (or registry) keystores.

Followings are the simple rules regarding KeyStores, you MUST follow in WSO2 production deployments (This is with 4.4.X)

  1. Both primary KeyStore and SSL  KeyStore must be changed from default wso2carbon.jks file in production setup.
  2. As mentioned; You must configure different KeyStores for primary and SSL  KeyStores
  3. If your WSO2 deployment has been clustered with multiple WSO2 instance, Every WSO2 instance must use the same SSL & primary KeyStore. It can NOT be different from each products.
  4. If your WSO2 deployment contains different products. Same product instances must have same primary  KeyStore. Different products can have different SSL KeyStore  (it is not mandatory to be different but same SSL keystore can be used)
  5. It is recommended to use CA signed KeyStore for primary KeyStore as it is used for SSL communication. But it is not mandatory. You can even use self signed certificate, if your clients can trust it.
  6. Primary/SSL KeyStore must contain only one private key. There can not be two private keys. (This is due to some issue in WSO2 products which may be fixed in future).
  7. Primary/SSL KeyStore must contain same password as KeyStore password and private key password. (This is due to some issue in WSO2 products which may be fixed in future)
  8. Primary KeyStore can be a self signed one. You can use CA signed KeyStore, But there is no worth of using such CA signed KeyStore as it is not use for external communication and it is only for data encryption.
  9. Validity period of thePrimary KeyStore certificate does not matter for the encrypt/decrypt the data. When you are creating the registry KeyStore, you can provide the maximum validity period for it.
  10. Primary Keystore’s public certificate must have Data Encipherment key usage. Therefore, Please note that you need to create the certificate with “Data_Encipherment” usage.  Default self signed certificate would contain it already.

Thanks for reading…!!!