WSO2 SP shipped with a default keystore named wso2carbon.jks, which is stored in the
<SP_HOME>/resources/security directory. This keystore comes with a private/public key pair that is used to encrypt sensitive information, for communication over SSL and for encryption/signature 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.
- Creating a keystore using an existing certificate
- Creating a keystore using a new certificate
- Adding the public key to client-truststore.jks
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 CA-signed certificates to generate a Java keystore using OpenSSL and the Java keytool.
First you must export certificates to the PKCS12/PFX format. Give strong passwords whenever required.
In WSO2 products, it is a must to have same password for both the keystore and key.
Execute the following command to export the certificates:
Convert the PKCS12 to a Java keystore using the following command:
Now you have a keystore with CA-signed certificates.
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 a new certificate. We will be using the keytool that is available with your JDK installation.
Step 1: Creating keystore with private key and public certificate
- Open a command prompt and go to the
<SP_HOME>/resources/securitydirectory. All keystores should be stored here.
Create the keystore that includes the private key by executing the following command:
This command creates a keystore with the following details:
- Keystore name:
- Alias of public certificate:
- Keystore password:
- Private key password: mypassword (this is required to be the same as keystore password)
If you did not specify values for 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.
- Keystore name:
- Open the
<SP_HOME>/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 because if not your private key is available only on one location.
Step 2: Creating CA-signed certificates for public key
Now we have a
.jks file. This keystore (
.jks file) can be used to generate a certificate signing request (CSR). This CSR file must be certified by a certificate authority or certification authority (CA), which is an entity that issues digital certificates. These certificates can certify the ownership of a public key.
Execute the following command to generate the CSR:
As mentioned before, use the same alias that you used during the keystore creation process.
You are asked to give the keystore password. Once the password is given, the command outputs the
newcertreq.csrfile to the
<SP_HOME>/resources/security/directory. This is the CSR that you must submit to a CA
You must provide this CSR file to the CA. For testing purposes, try the 90 days trial SSL certificate from Comodo.
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.
After accepting the request, a signed certificate is provided along with several intermediate certificates (depending on the CA) as a bundle (.zip file).
Step 3: Importing CA-signed certificates to keystore
Before importing the CA-signed certificate to the keystore, add the root CA certificate and the two intermediate certificates by executing the commands given below. Note that the sample certificates given above are used as examples.
Optionally, you can append the
-storepass <keystore password>option to avoid having to enter the password when prompted later in the interactive mode.
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:
In this command, use the same alias that you used when you created the keystore.
Now you have a Java keystore including a CA-signed certificate that can be used in a production environment. Next, you must add its public key to the
client-truststore.jks file to enable backend communication and inter-system communication via SSL.
Adding the public key to client-truststore.jks
client-truststore.jksthat resides in the same directory as the keystore (i.e.,
<SP_HOME>/resources/security). Therefore, you need to import the new public certificate into this trust store for front-end and backend communication of WSO2 SP to take place in the required manner over SSL.
In this example, you are using the default
client-truststore.jks file in WSO2 SP as the trust store.
To add the public key of the signed certificate to the client trust store:
- Get a copy of the
client-truststore.jksfile from the
Export the public key from your
.jksfile using the by issuing the following command.
Import the public key you extracted in the previous step to the
client-truststore.jksfile by issuing the following command.
wso2carbonis the keystore password of the default
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
<SP_HOME>/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 more information, see Configuring Keystores.