Page History

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 (with 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, and how they are used in WSO2 products.

...

• Certificates of trusted third parties with which a software system intends to communicate directly.
• Certificates of reputed certificate signing authorities (CA) that can be used to validate the identity of untrusted third parties that are being contacted. For example, consider a scenario where the exact certificate of the third party that the WSO2 server is attempting to contact is not in the truststore. In this scenario, if the third party has a CA-signed certificate and one of the certificates of its trust chain is already included in the WSO2 server's truststore, the trust is automatically granted and a successful SSL connection is established between the WSO2 server and the third party.

...

...

The key pair and the CA-signed certificates in a keystore will establish 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.

...

• .

Default keystore and truststore in WSO2 products

...

• wso2carbon.jks: This is the default keystore, which contains a private key and the self-signed public key certificate.
• client-truststore.jks: This is the default truststore, which contains certificates of reputed CAs that can validate the identity of third party systems. This truststore also contains the self-signed certificate of the default wso2carbon.jks keystore.

Anchor
setting_up_keystores setting_up_keystores

...

Usage of keystores in WSO2 products

In WSO2 products, asymmetric encryption is used by default for the following purposes:

...

Anchor
recommendations recommendations

Recommendations for setting up keystores in WSO2 products

Follow the recommendations given below when you set up your keystores. 

• Maintain one primary keystore primary keystore for encrypting sensitive internal data such as admin passwords and any other sensitive information found at both product-level and product feature-level configurations/configuration files. Note that the primary keystore will also be used for signing messages when the product communicates with external parties (such SAML, OIDC id_token signing).

  Info
  In new versions of WSO2 products, you can have separate keystores for encrypting sensitive information for internal data encryption as a recommended practice. See Configuring Keystores in WSO2 Products for details.

• Maintain another secondary keystore, containing the server’s public key certificate for authenticating communication over SSL/TLS (for both Tomcat and Axis2 level HTTP connections).

• If your deployment contains multiple products, instances of the same product must use the same keystore for SSL. Different products can use different keystores for SSL, but it is not mandatory.

• It is recommended to use a CA-signed keystore for SSL communication; however, this is not mandatory. Even a self-signed certificate may suffice if it can be trusted by the clients.

• The keystore used for SSL must contain the same password for the Keystore and private key due to a Tomcat limitation.

• The primary keystore used for admin passwords and other data encryption requirements can be a self-signed one. There is no value added by using a CA-signed keystore for this purpose as it is not used for any external communication.

• The primary keystore's public key certificate must have the Data Encipherment key usage to allow direct encipherment of raw data using its public key. This key usage is already included in the default self-signed certificate that is included in the default wso2carbon.jks keystore. If the Data Encipherment key usage is not included in your public key certificate, the following error can occur when you attempt data encryption:
  

  Code Block

  Exception in thread "main" org.wso2.ciphertool.CipherToolException: Error initializing Cipher at org.wso2.ciphertool.CipherTool.handleException(CipherTool.java:861) at org.wso2.ciphertool.CipherTool.initCipher(CipherTool.java:202) at org.wso2.ciphertool.CipherTool.main(CipherTool.java:80) Caused by: java.security.InvalidKeyException: Wrong key usage at javax.crypto.Cipher.init(DashoA13..) at javax.crypto.Cipher.init(DashoA13..) at org.wso2.ciphertool.CipherTool.initCipher(CipherTool.java:200) ... 1 more

• Optionally, you can set up separate keystores for message-level data encryption in WS-Security.

• If you already have the required keystores for your product, you can generate CA-signed certificates and import them into the keystores. It is not recommended to create new keystores for the purpose of replacing the certificates in the keystore. See Adding CA-signed certificates to keystores for instructions.

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. For example, when you apply WS-Security to Web services using the Management Console, you can select a keystore for encryption/signing processes from the uploaded keystores. 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 the 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.

...

...