WSO2 products use asymmetric encryption by default for the purposes of authentication and protection of data. In asymmetric encryption, keystores (with private keys and public key certificates) and truststores (only public key certificates) are created and stored for a product. It is possible to have multiple keystores so that the keys used for different use cases are kept unique. The following topics explain more details on keystores and truststores.

Understanding keystores and truststores

A keystore is a repository (protected by a password) that holds the keys and certificates that form (one or multiple) trust chains of digital certificates. You use these artifacts for security purposes such as protecting sensitive information and establishing trust between your server and the outside parties that connect to the server. The usage of keys and certificates contained in a keystore are explained below.

Key pairs: According to public-key cryptography, the concept of a key pair (public key and the corresponding private key) is used for protecting sensitive information and for authenticating the identity of external parties that communicate with your server. For example, information that is encrypted in your server using the public key can only be decrypted using the corresponding private key. Therefore, if any party wants to decrypt this encrypted data, they should have the corresponding private key, which is usually kept as a secret (not publicly shared).Digital certificate: When there is a key pair, it is also necessary to have a digital certificate to verify the identity of the keys. Typically, the public key of a key pair is embedded in this digital certificate, which also contains additional information such as the owner, validity, etc. of the keys. For example, if an external party wants to verify the integrity of data or validate the identity of the signer (by validating the digital signature), it is necessary for them to have this digital certificate.

Trusted certificates: To establish trust, the digital certificate containing the public key should be signed by a trusted certifying authority (CA). You can generate self-signed certificates for the public key (thereby creating your own certifying authority), or you can get the certificates signed by an external CA. Both types of trusted certificates can be effectively used depending on the sensitivity of the information that is protected by the keys. When the certificate is signed by a reputed CA, all the parties who trust this CA also trust the certificates signed by them.

Identity and Trust

The key pair and the CA-signed certificates in a keystore establishes two security functions in your server: The key pair with the digital certificate is an indication of identity and the CA-signed certificate provides trust to the identity. Since the public key is used to encrypt information, the keystore containing the corresponding private key should always be protected, as it can decrypt the sensitive information. Furthermore, the privacy of the private key is important as it represents its own identity and protects the integrity of data. However, the CA-signed digital certificates should be accessible to outside parties that require to decrypt and use the information.

To facilitate this requirement, the certificates must be copied to a separate keystore (called a Truststore), which can then be shared with outside parties. Therefore, in a typical setup, you will have one keystore for identity (containing the private key) that is protected, and a separate keystore for trust (containing CA certificates) that is shared with outside parties.

Setting up keystores for WSO2 products

In WSO2 products, public key encryption is used for the following purposes:

Encrypting data such as scripts, configuration files, xmld, xsds etc. into the registry.

Encrypting/signing in WS-Security.

You can set up several keystores with separate key pairs and certificates for the above use cases in your system. It is recommended to maintain the following keystores:

Maintain a primary keystore for encrypting sensitive data such as admin passwords and certain registry data. By default, the primary keystore is also used for WS-Security and for authenticating Tomcat level connections.

Maintain a separate keystore for authenticating the communication over SSL/TLS for Tomcat level connections.

Optionally, you can set up separate keystores with key pairs and certificates for WS-Security.

A separate keystore (truststore) for the purpose of storing the trusted certificates of public keys in your keystores.

Default keystore settings in WSO2 products

All WSO2 products are shipped with two default keystore files stored in the <PRODUCT_HOME>/repository/resources/security/ directory;

wso2carbon.jks: This keystore contains a key pair and is used by default in your Carbon server for all of the purposes explained above.

client-truststore.jks: This is the default trust store, which contains the trusted certificates of the keystore used in SSL communication.

It is recommended to replace this default keystore with a new keystore that has self-signed or CA signed certificates when the products are deployed in production environments. This is because wso2carbon.jks is available with open source WSO2 products, which means anyone can have access to the private key of the default keystore.

Managing keystores

WSO2 products provide the facility to add keystores using the Management Console or using an XML configuration, and to import certificates to the keystore using the Management Console. The WSO2 keystore management feature provides a UI and an API to add and manage keystores used for WS-Security scenarios. When you apply WS-Security to Web services using the Management Console, you can select a keystore from uploaded keystores for encryption/signing processes. The Management Console also allows you to view/delete keystores.

All the functions of keystore management are exposed via APIs. As a result, if you are writing a custom extension to a WSO2 product (e.g., for WSO2 ESB mediators), you can directly access configured keystores using the API. The API hides the underlying complexity, allowing you to easily use it in third-party applications to manage their keystores as well.

This functionality is bundled with the following feature that is installed in your product.