Updating the SSL/TSL Security Certificates for WebSphere Liberty Under IBM CLM Tools

Why you should change the default certificates?

If you are a user of IBM Rational Team Concert, DOORs Next Generation, Quality Manager, Design Manger, or Engineering Lifecycle Manager, you likely have seen the issue with the browser stating “Your connection is not private”, and red error showing in the browser URL as ‘Not Secure’.

The RTC default SSL cert shows as localhost

If you click on the warning, you can view the certificate details, and see that the SSL certificate is issued to ‘localhost’ by ‘localhost’. This is what is called a self signed SSL certificate. A browser checks the validity of an SSL certificate based on three criteria:

1. Is the certificate issued by someone I trust (i.e. Google Trust, Thawte, Verisign, GoDaddy, etc)
2. Is the certificate issued to the same server I just accessed? (i.e. does the Issued To field of the certificate match the host name of the server I just accessed?)
3. Is the certificate still valid? (i.e. Is today’s date between the start and ending valid date range?)

If any of the three above are not true, then the certificate is not trusted. When you first install RTC, RQM or any of the other CLM applications, it creates a default self-signed certificate based on the host name of “localhost”, which of course is invalid.

Another reason to update your certificates, is that the default certificate store has a default password. Anyone with access to your file system can access your certificates (and by that they can either sabotage your environment, or can inject new certificates).

There are three common strategies for updating the certs:

1. Create a new self-signed certificate that matches your hostname. This strategy should be used only for small teams that are unconcerned with using self-signed certs. If you do this, you should ensure the validity of the certificate is for a reasonably long period of time. If the validity check fails, you may not be able to access the server at all.
2. Create a new certificate request and sign it with your company’s internal Certificate Authority. This is common in larger institutions (especially financial services companies), however, you can set up you own internal CA with some knowledge and skills even if you are a small or medium sized business.
3. Create a new certificate request and sign it with a known public Certificate Authority. This method is the more common method, but requires purchasing a certificate. This certifcate can range in prices between US$80 to over $1000 depending upon the validity date range, and whether you have a wildcard cert.

You also should plan on front ending the server with an HTTP server (which has its own SSL certificate store), which we elaborated on in https://www.strongback.us/2017/12/why-you-need-to-front-end-your-clm-servers-with-an-http-server

Where are they located?

For WebSphere Liberty, the SSL certs are stored under <JazzHome>/server/liberty/servers/clm/resources/security/ibm-team-ssl.keystore*.

*Assume <jazzhome> is /opt/IBM/JazzTeamServer on Linux/AIX, or C:\Program Files\IBM\JazzTeamServer by default on Windows

This acts as both the Trust keystore (where signer certificates are located), as well as the primary keystore (where the personal certificates are stored).

The default password for this keystore is ibm-team (this is well documented in the IBM Knowledge Center, and to reiterate, another reason to update the keystore!).

How do you change them?

Now comes the fun part. You will use the key tools found in the JRE of the installed product. This is located under <JazzHome>/server/jre/bin

If you are on Windows, you can use the graphical tool ikeyman.bat. Otherwise, you will use the command line version ikeycmd (like any good Linux/Unix admin should do).

Windows

Lauch ikeyman.bat. Navigate to the keystore (listed above) and enter the default password (ibm-team), if you are going to use the default keystore. You can also create a new keystore by clicking Key Database File > New.

If you use the default keystore, be sure to change the default password by selecting Key Database File > Change Password.

You will notice the default certificate in the personal certificates list. If you want to use a self-signed cert, click the “New Self Signed” button, and follow the prompts. You can stop reading now, as this train will focus on the other folks who really want to make it secure.

Click the drop down and select Personal Certificate Requests.

Adding a personal certificate request.

Click on the “New” button. In the dialog, provide the given information with the following advice:

• The common name and key label generally should match.
• The common name should be the fully qualified host name.
• If you need to include a Subject Alternative Name, enter the alternative DNS name into the DNS name field, along with the IP address of the server.

Click Ok. This will save the certificate request to the file shown in the bottom field in the image above. You will now send that certificate to your CA to have it stamped. Whether the CA is an internal CA, or a public CA, the result is the same. You should get a zip file with the stamped certificate as well as any intermediate certs.

Import the intermediate and root certificates.

In ikeyman, change the drop down to the Signer Certificate. Then click Add. Browse to where you downloaded the certificate file.

Add and browse the file with the certs to import.

Click Ok. You should now be prompted to select which of the intermediary certs you wish to import. Generally, you should import them all. Note: you must select the them as shown below before click on on Ok.

Select which certs in the file to import.

You will be prompted to change the default label on the next dialog. Don’t. Just click Ok. You should now see your intermediary certs. In this case, we’re using GoDaddy certs. You can also click Populate, which will add the default root certificates for Thawte, Entrust, and Verisign. This is convenient if your server ever will have to handshake to a server stamped with those certificates. Add any additional certificates you wish the server to trust here.

ikeyman with GoDaddy intermediary SSL certificates.

Now, change to the Personal Certificates and select Receive.  Browse to the directory where you saved the signed cert. Click Ok.  Do not change the label if prompted. Finally, delete the default certificate. This ensures that the server will no present the ‘localhost’ certificate. You should now have a server ready to communicate over SSL.

Linux/AIX

For you lucky users, you get to use the command line interface. Instead of ikeyman, you’ll use ikeycmd (yes, you will see ikeyman.sh, and if you can access the server graphically, then use the above instructions, otherwise, just follow along).

./ikeycmd -keydb -create -db <jazzhome>/server/liberty/servers/clm/resources/security/mykeystore.kdb -pw <password> -type jks

If you prefer to just change the password, use this command

./ikeycmd -keydb -changepw -db <jazzhome>/server/liberty/servers/clm/resources/security/ibm-team-ssl.keystore -pw ibm-team -new_pw <new_password>

Next, create a new certificate request. We recommend 2048 as a minimum size hash. The distinguished name should be in the format of CN=fully.qualified.host.name, O=organization, OU=organization_unit, L=location, ST=state/province, C=country. Note that only the CN, Organization, and Country are required.

./ikeycmd -certreq -create -db <jazzhome>/server/liberty/servers/clm/resources/security/ibm-team-ssl.keystore -pw <password> -size 2048 -dn <distinguished_name> -file <filename> -label <label>

This request, you will take to your CA to have it stamped. Once you get it back, its time to import it and the intermediary and root certificates.

./ikeycmd -cert -receive -file <filename> -db <jazzhome>/server/liberty/servers/clm/resources/security/ibm-team-ssl.keystore -pw <password> -format <ascii | binary> -default_cert <yes | no>
Finally, store the CA intermediary and root certs.

./ikeycmd -cert -add -db <jazzhome>/server/liberty/servers/clm/resources/security/ibm-team-ssl.keystore  -pw <password> -label <label> -format <ascii | binary>  -trust enable -file <file>

Update the Keystore Information in Liberty

You must change the server’s keystore location in the Liberty server.xml if you created a new one. Open the server.xml in <JazzHome>/server/liberty/servers/clm/server.xml. Locate the following line:

<keyStore id="defaultKeyStore" location="ibm-team-ssl.keystore" type="JCEKS" password="{xor}Nj0ycis6PjI="/>

Change the location attribute to the correct file name (this file should be stored in the liberty resources/security folder).

Next, you can either enter the actual password you created for the new keystore (not recommended), or you can encode it with the securityUtility.

Navigate to <JazzHome>/server/liberty/wlp/bin, and enter the following command

./securityUtility.bat encode <password>

Copy the output and enter that into the password attribute for the server.xml’s keystore element. Note for example if I used ibm-team as the password, I would get the following output:

.\securityUtility.bat encode ibm-team

{xor}Nj0ycis6PjI=

Final thoughts:

This article does not cover exchanging certificates with an HTTP Server (such as Apache or IBM HTTP Server). If you have more than 2 CLM applications, or have more than 20 users, you need an HTTP server. The IBM HTTP server uses the Global Security Kit and its command is gscapicmd, but the commands are very similar to ikeycmd.

SSL Certificate References:

Managing certificates with IBM GSKit https://ibm.co/2kT9v2A 

Using the WebSphere Liberty securityUtility: https://www.ibm.com/support/knowledgecenter/en/SSAW57_liberty/com.ibm.websphere.wlp.nd.multiplatform.doc/ae/rwlp_command_securityutil.html

Creating Your Own SSL Certificate Authority (and Dumping Self Signed Certs)