Configuring SSL for Tomcat in R12.1.

Document ID : KB000053621
Last Modified Date : 14/02/2018
Show Technical Document Details

Description:

The Service Desk r12.1 Implementation Guide has steps for configuring SSL with a self signed Certificate. These instructions include an example from the server.xml which is incorrect and if copied and pasted directly into the server.xml will cause the SSL to fail to locate the Certificate. The instructions are otherwise correct, and if the server.xml is modified by entering the changes by hand, will work.

The following steps taken from the Implementation guide have been updated with the correct example from the server.xml as well as and example of implementing a Certificate from VeriSign.

Solution:

The first step(s) should be to setup and verify that the Self Signed certificate functions. Once the self signed certificate is configured and Tomcat running on the SSL ports specified it is a matter of following the instructions provided by the Certificate Authority to put the official Certificate in place.

Configure SSL with a Self Signed Certificate:

The process is taken from the Tomcat documentation updated for the Service Desk implementation of Tomcat, and can be found in the Implementation guide with a slightly incorrect example from the server.xml file.

  1. From the command line, change directories to the JRE install location, and enter the following command:
     $JAVA_HOME\bin\keytool -genkey -alias tomcat -keyalg RSA  
    A .keystore file is created by default in the home directory of the logged in user. You can specify a different location during .keystore file generation. On UNIX, make sure that the directory in which you generate the .keystore file has sufficient permissions for CA Service Desk access.

    Note: For more about specifying a different .keystore file location, see your Tomcat documentation.

  2. Answer the prompts appropriately. The default password is changeit. Note: You can enter a password other than the default one. For more information, see your Tomcat documentation.

  3. Edit the server.xml file located in the following directory:

    $NX_ROOT\bopcfg\www\CATALINA_BASE\conf.
    Uncomment the following SSL connector <!-- Define a SSL HTTP/1.1 Connector on port 8443 --> and modify adding keystoreFile= and keystorePass= as shown below:
    <Connector port="8443" maxHttpHeaderSize="8192" 
        maxThreads="150" minSpareThreads="25" maxSpareThreads="75" 
        enableLookups="false" disableUploadTimeout="true" 
        acceptCount="100" scheme="https" secure="true" 
        clientAuth="false" sslProtocol="TLS" keystoreFile="C:\Documents and Settings\user\.keystore"  keystorePass="password"/>
    DO NOT COPY AND PASTE THE ABOVE SSL CONNECTOR FROM THE 12.1 IMPLEMENTATION GUIDE - MODIFY THE EXISTING FILE TO ADD THE NECESSARY KEYSTORE INFORMATION

  4. Cycle Tomcat as follows:
    pdm_tomcat_nxd -c stop  
    pdm_tomcat_nxd -c start  
  5. To access the CA Service Desk web interface with SSL, use https://hostname:8443/CAisd/pdmweb.exe. You can also derive the Web Services URL in a similar fashion.

    Note: You can specify a port other than 8443 in the server.xml file.

Once SSL is up and functional with the Self Signed certificate you are ready to implement an official Certificate Authority provided certificate.

Please Note:

Each Certificate Authority should provide specific steps for their Certificate for most if not all Web Servers including the 2 supported by Service Desk, Tomcat and IIS.

There will likely be additional steps past the below documentation, such as importing the cert into the java\lib\security\cacerts file. These additional steps are beyond the scope of this technical article. Please review with your Certificate authority if the Self Signed Certificate works but the official Certificate Authority provided Certificate does not.

Follow the steps are taken from the VeriSign site and depend on the type of purchase made ("Secure Site", "Secure Site Pro", etc...):
https://knowledge.verisign.com/support/ssl-certificates-support/index?page=content&id=AR234

When prompted for the certificate type, be sure to request the Microsoft PKCS7 format. The java "keytool" should be able to read these without issue.

Import the certificate received from VeriSign:

keytool -import -trustcacerts -file c:\newcert.crt -file "c:\.keystore" -alias tomcat
Note: the Microsoft pkcs7 format should have the VeriSign intermediate certificates.

Edit the $NX_ROOT\bopcfg\www\CATALINA_BASE\conf\server.xml in a text editor.
Locate the SSL connector section and update the keystore path and password values as per the VeriSign documentation:
<Connector port="8443" maxHttpHeaderSize="8192" 
    maxThreads="150" minSpareThreads="25" maxSpareThreads="75" 
    enableLookups="false" disableUploadTimeout="true" 
    acceptCount="100" scheme="https" secure="true" 
    clientAuth="false" sslProtocol="TLS" keystoreFile="C:\.keystore"  keystorePass="securepassword"/>