Managing_Keystores_And_Truststores.md

Managing Java Keystores and Truststores

This chapter depicts important information about managing Java keystores and truststores in a container based WSO2 product deployment.

Contents

The following will be discussed in detail in the document.

• Asymmetric Encryption in WSO2 products
• Manage Keystores and Certificate Truststores in Container Based Deployments

Asymmetric Encryption in WSO2 Products

WSO2 products use asymmetric encryption by default to ensure trust and secure tranfer of data. For advanced details, refer the official WSO2 documentation.

Java keystores and truststores are used to store SSL certificates required for asymmetric encryption.

Refer to the official WSO2 recommendations for managing keystores prior to following this guide.

Manage Keystores and Truststores in Container Based Deployments

As per aforementioned WSO2 recommendations, it is often required to customize the default, WSO2 product keystore and truststore in a production grade deployment.

The most recommended approach for introducing a custom keystore or a truststore to a container based deployment is by using volume mounting to replace the default one with the custom one.

1. Prepare the custom Java keystore or truststore.

   Follow the official guidelines for creating a new keystore or adding a Certificate Authority signed certificate to an existing keystore as per your preference.

   To import certificates to a truststore, follow the official documentation.

2. Add the keystore to the product container via a volume mount depending on the container platform.

   We recommend you to use the volume mount allocated for non-configuration resources in WSO2 product containers (i.e. /home/wso2carbon/wso2-artifact-volume) for this purpose.

   In Carbon Kernel version 4 based products, the default wso2carbon.jks keystore is located at the <WSO2_PRODUCT_HOME>/repository/resources/security directory. Thus, you may mount the volume containing the custom keystore to /home/wso2carbon/wso2-artifact-volume/repository/resources/security directory.

   In Carbon Kernel version 5 based products, the default wso2carbon.jks keystore is located at the <WSO2_PRODUCT_HOME>/resources/security directory. Thus, you may mount the volume containing the custom keystore to /home/wso2carbon/wso2-artifact-volume/resources/security directory.

3. Add the truststore to the product container via a volume mount depending on the container platform.

   We recommend you to use the volume mount allocated for non-configuration resources in WSO2 product containers (i.e. /home/wso2carbon/wso2-artifact-volume) for this purpose.

   In Carbon Kernel version 4 based products, the default client-truststore.jks truststore is located at the <WSO2_PRODUCT_HOME>/repository/resources/security directory. Thus, you may mount the volume containing the custom keystore to /home/wso2carbon/wso2-artifact-volume/repository/resources/security directory.

   In Carbon Kernel version 5 based products, the default client-truststore.jks truststore is located at the <WSO2_PRODUCT_HOME>/resources/security directory. Thus, you may mount the volume containing the custom keystore to /home/wso2carbon/wso2-artifact-volume/resources/security directory.

   In Kubernetes based WSO2 product deployments, it is advisable that you use a ConfigMap resource to mount the custom keystore and truststore.

   Note: Support for including binary data in Kubernetes ConfigMaps was introduced in version 1.10.

   For further understanding peruse:

   1. Create a ConfigMap resource from the keystore file

   2. Add the ConfigMap data to a volume