If the directory/file paths specified in this guide do not exist in your WSO2 product, see Directory Structure of WSO2 Products to locate the paths applicable to your product.
Page Comparison - Using Asymmetric Encryption (v.20 vs v.21) - Administration Guide 4.4.x - WSO2 Documentation

Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

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.

Table of Contents
maxLevel3
minLevel3

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).

Excerpt
hiddentrue

In a keystore, each trust chain entry contains the following:

  • A private key protected by a password.
  • A digital certificate in which the public key (corresponding to the private key) is embedded. 
  • If that certificate is not self-signed, the associated chain of trusted certificate signing authorities to verify trust.


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 of the signer.

Trusted certificates and certificate signing authorities: To establish trust, the digital certificate containing the public key should be signed by a trusted certificate signing 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.

Excerpt
hiddentrue

The usage of a truststore aligns with this concept of trust. A truststore is also another repository (protected by a password) similar to a keystore, which stores digital certificates. These certifcates can be either of the following:

  • Trusted third parties with which a software system would intend to directly communicate
  • Reputed certificate signing authorities (CA) that can be used to validate the identity of untrusted third parties been contacted.

Even if the exact certificate of a third party that a WSO2 server would intend to communicate with, is not in the truststore, if it’s a CA signed certificate and one of the certificates of its trust chain is already included in the truststore, the trust is automatically granted to the certificate in question and a successful SSL connection is made.

By default, Every WSO2 product is shipped with a truststore that it uses to validate the identity of third party systems been contacted.

Info
titleIdentity and Trust

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.

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.

Default keystore and truststore in WSO2 products

All WSO2 products are by default shipped with a keystore file and truststore file (stored in the <PRODUCT_HOME>/repository/resources/security/ directory):

  • wso2carbon.jks: This is the default keystore, which contains the server’s private key and the self-signed public key certificate.
  • client-truststore.jks: This is the default trust store, which contains the trusted certificates of the keystore used in SSL communication. This is the default truststore, which contains many of the reputed root CAs that customers can use.

Anchor
setting_up_keystores
setting_up_keystores
Setting up keystores for WSO2 products

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

  • Authenticating the communication over Secure Sockets Layer (SSL)/Transport Layer Security (TLS) protocols.
  • Encrypting sensitive data such as plain-text passwords found in both product-level and product feature-level configurations/configuration files using secure vault.

  • Encrypting and signing SOAP messages using WS-Security.
Note

The default keystore that is shipped with a WSO2 product (wso2carbon.jks) is by default configured for all of the above purposes. However, in a production environment, it is required and advised to set up several different keystores with separate trust chains for the above use cases.

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 one 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.

  • 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 the keystore used for SSL communication; however, this is not mandatory. Even a self-signed certificate may suffice, if it can be trusted by the clients.

  • Keystore used for SSL must contain same password for both KeyStore and private key passwords due to a Tomcat limitation.

  • Primary keystore used for admin passwords and other data encryption requirements can be a self-signed one. You can use a CA-signed keystore, But there is no added value of using such CA-signed keystore as it is not used for external communication, but only for internal data encryption.

  • 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. Therefore, note that it is necessary to create the public key certificate with “Data_Encipherment” key usage. This key usage is already included in the default self-signed certificate.

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

Note

For information on creating new keystores with the required certificates, see Creating New Keystores, and for information on how to update configuration files in your product with keystore information, see Configuring Keystores in WSO2 Products.

Managing 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.

Name: WSO2 Carbon - Security Management Feature
Identifier: org.wso2.carbon.security.mgt.feature.group