This documentation is for WSO2 Carbon 4.4.1. View documentation for the latest release.
Page Comparison - Creating New Keystores (v.5 vs v.6) - Carbon 4.4.1 - WSO2 Documentation
Due to a known issue do not use JDK1.8.0_151 with WSO2 products. Use JDK 1.8.0_144 until JDK 1.8.0_162-ea is released.

Versions Compared

Key

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

WSO2 Carbon-based products are shipped with a default keystore named default keystore named  wso2carbon.jks , which is stored in the the  <PRODUCT_HOME>/repository/resources/security directory  directory. This keystore comes with a private/public key pair that is used to encrypt for all purposes, such as encrypting sensitive information, for communication over SSL and for encryptionfor message encryption/signature signing purposes in WS-Security. However, note that since wso2carbon.jks is available with open source WSO2 products, anyone can have access to the private key of the default keystore. It is therefore recommended to replace this with a keystore that has self-signed or CA signed certificates when the products are deployed in production environments. 

...

 You can either use one new keystore for all purposes in your product, or you can create multiple keystores for each purpose.

Let's start creating a new keystore:

Table of Contents
minLevel3

Before you begin

Be sure to go through the recommendations for setting up keystores in WSO2 products to understand the type of keystores you need.

Note

Important!

If you are creating a new keystore for data encryption, be sure to acquire a public key certificate that contains the Data Encipherment key usage as explained in the keystore recommendations. Otherwise, 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


Creating a keystore using an existing certificate

Secure Sockets Layer (SSL) is a protocol that is used to secure communication between systems. This protocol uses a public key, a private key and a random symmetric key to encrypt data. As SSL is widely used in many systems, certificates may already exist that can be reused. In such situations, you can use the an already existing CA-signed certificates certificate to generate a Java keystore your keystore for SSL by using OpenSSL and the Java keytool.

  1. First, you must export certificates to the PKCS12/PFX format. Give strong passwords whenever required.

    Info

    In WSO2 products, it is a must to have the same password for both the keystore and thekeystoreand private key.

    Execute the following command to export the certificatesthe entries of a trust chain into a keystore of .pfx format:

    Code Block
    languagepowershell
    openssl pkcs12 -export -in <certificate file>.crt -inkey <private>.key -name "<alias>" -certfile <additional certificate file> -out <pfx keystore name>.pfx
  2. Convert the PKCS12 to /PFX formatted keystore to a Java keystore using the following command:

    Code Block
    languagepowershell
    keytool -importkeystore -srckeystore <pkcs12 file name>.pfx -srcstoretype pkcs12 -destkeystore <JKS name>.jks -deststoretype JKS

    Now you have a keystore with a CA-signed certificatescertificate.

Creating a keystore using a new certificate

If there are no certificates signed by a Certification Authority, you can follow the steps in this section to create a keystore with keys and keystore for SSL using a new certificate. We will be using the keytool that is available with your JDK installation.

...

  1. Open a command prompt and go to the <PRODUCT_HOME>/repository/resources/security/ directory. All keystores should be stored here.
  2. Create the keystore that includes the private key by executing the following command:

    Code Block
    languagepowershell
    keytool -genkey -alias certaliasnewcert -keyalg RSA -keysize 2048 -keystore newkeystore.jks -dname "CN=<testdomain.org>,OU=Home,O=Home,L=SL,S=WS,C=LK" -storepass mypassword -keypass mypassword 

    This command will create a keystore with the following details: 

    • Keystore name: newkeystore.jks
    • Alias of public certificate: certaliasnewcert
    • Keystore password: mypassword
    • Private key password: mypassword (this is required to be the same as keystore password)
    Note

    Note that if you did not specify values for the '-keypass' and the '-storepass' in the above command, you will be asked to give a value for the '-storepass' (password of the keystore). As a best practice, use a password generator to generate a strong password. You will then be asked to enter a value for -keypass. Click Enter, because we need the same password for both the keystore and the key. Also, if you did not specify values for -dname, you will be asked to provide those details individually.

  3. Open the <PRODUCT_HOME>/repository/resources/security/ directory and check if the new keystore file is created. Make a backup of it and move it to a secure location. This is important as it is the only place with our your private key. 

Step 2: Creating CA-signed certificates for public key

...

  1. Execute the following command to generate the CSR:

    Code Block
    languagepowershell
    keytool -certreq -alias certalias -file newcertreq.csr -keystore newkeystore.jks

    Note

    As mentioned before, use the same alias that you used during the keystore creation process.

    You will be asked to give the keystore password. Once the password is given, the command will output the newcertreq.csr file to the <PRODUCT_HOME>/repository/resources/security/ directory. This is the CSR that you must submit to a CA.

  2. You must provide this CSR file to the CA. For testing purposes, try the 90 days trial SSL certificate from Comodo.

    Note

    It is preferable to have a wildcard certificate or multiple domain certificates if you wish to have multiple subdomains like gateway.sampledomain.org, publisher.sampledomain.org, identity.sampledomain.org, etc., for the deployment. For such requirements, you must modify the CSR request by adding subject alternative names. Most of the SSL providers give instructions to generate the CSR in such cases.

  3. After accepting the request, a signed certificate is provided along with a root certificate and several intermediate certificates (depending on the CA) as a bundle (.zip file).

    Panel
    titleSample certificates provided by the CA (Comodo)

    The Root certificate of the CA: AddTrustExternalCARoot.crt 
    Intermediate certificates:  COMODORSAAddTrustCA.crt , COMODORSADomainValidationSecureServerCA.crt 
    SSL Certificate signed by CA: test_sampleapp_org.crt

...

  1. Before importing the CA-signed certificate to the keystore, you must add the root CA certificate and the two (related) intermediate certificates by executing the commands given below. Note that the sample certificates given above are used as examples.

    Code Block
    keytool -import -v -trustcacerts -alias ExternalCARoot -file AddTrustExternalCARoot.crt -keystore newkeystore.jks -storepass mypassword
    keytool -import -v -trustcacerts -alias TrustCA -file COMODORSAAddTrustCA.crt -keystore newkeystore.jks -storepass mypassword
    keytool -import -v -trustcacerts -alias SecureServerCA -file COMODORSADomainValidationSecureServerCA.crt -keystore newkeystore.jks -storepass mypassword 

    Note

    Optionally we can append the -storepass <keystore password> option to avoid having to enter the password when prompted later in the interactive mode.

  2. After you add the root certificate and all other intermediate certificates, add the CA-signed SSL certificate to the keystore by executing the following command:

    Code Block
    languagepowershell
    keytool -import -v -alias <certalias>newcert -file <test_sampleapp_org.crt> -keystore newkeystore.jks -keypass myppasswordmypassword -storepass mykpasswordmypassword

    Note

    In this command, use the same alias (i.e., 'newcert') that you used while creating the keystore.

Now you have a Java keystore including , which includes a CA-signed public key certificate that can be used for SSL in a production environment. Next, you must add its may need to add the same CA-signed public key certificate to the client-truststore.jks file to enable . This will provide security and trust for backend communication and /inter-system communication of WSO2 products via SSL.

Adding

...

a public key to client-truststore.jks

In SSL handshake, the client needs to verify the certificate presented by the server. For this purpose, the client usually stores the certificates it trusts, in a trust store. All To enable secure and trusted backend communication, all WSO2 products are shipped with the a trust store named client-truststore.jks, which resides in the same directory as the keystore default keystore (<PRODUCT_HOME>/repository/resources/security/). Therefore,  In case we need to import the new a public key certificate into this trust store for frontend and backend communication of WSO2 products to happen properly over SSLthe trust store, you can achieve this using keytool as explained below. In this example, we are importing the same CA-signed public key certificate (which we obtained above) into client-truststore.jks.
Note

Note that we are using the default client-truststore.jks file in your WSO2 product as the trust store in this example.

To add the public key of the signed certificate to the client trust store:

  1. Get a copy of the client-truststore.jks file from the <PRODUCT_HOME>/repository/resources/security/ directory.
  2. Export the public key from your .jks file using the following command.

    Code Block
    languagepowershell
    keytool -export -alias certalias -keystore newkeystore.jks -file <public key name>.pem
  3. Import the public key you extracted in the previous step to the client-truststore.jks file using the following command.

    Code Block
    languagepowershell
    keytool -import -alias certalias -file <public key name>.pem -keystore client-truststore.jks -storepass wso2carbon

    Note

    Note that 'wso2carbon' is the keystore password of the default client-truststore.jks file.

Now, you have an SSL certificate stored in a Java keystore and a public key added to the client-truststore.jks file. Note that both these files should be in the <PRODUCT_HOME>/repository/resources/security/ directory. You can now replace the default wso2carbon.jks keystore in your product with the newly created keystore by updating the relevant configuration files in your product.   For information on the on the concepts of keystores and about how about how keystores are used in WSO2 products, see Setting up Keystores, and for information on how to update configuration files for keystores in WSO2 products, see .

What's next?

Once you have created a new keystore in your product as explained above, update the relevant configuration files as explained in Configuring Keystores in WSO2 Products.