Update of Pipeline Pilot's CACERTS file required when the Server Port Usage is set to 'SSL Only'

Program

Pipeline Pilot Server (all supported versions)

 

Operating System
 

All supported operating systems

 

Description

Pipeline Pilot provides the option 'SSL Only' in the Admin Portal under the menu item Setup → Server Configuration → Server Port Usage. If this option is set, Pipeline Pilot will always use HTTPS connections, and as of Pipeline Pilot version 2022, the server certificates will be verified by default. In order for the remote server certificates to be verified, the Certificate Authorities (CAs) of the server certificate must be known and classified as trustworthy. This also applies in particular to HTTPS connections to internal servers in your own network, as well as to connections between the Apache HTTP and Tomcat servers used internally in the Pipeline Pilot Server. If the server certificate cannot be verified, the HTTPS connection will fail and with it the calling Pipeline Pilot application or protocol. 

Internal servers typically use server certificates that are issued by the company's internal root and intermediate CAs. As these internal CAs are company-specific and non-public, they are not initially part of the standard operating systems and runtime environments. They must therefore be added by system administrators to the standard Certificate Trust Stores of the operating systems and runtime environments of the server and client machines, and this is usually part of the standard deployment of real and virtual machines. This allows applications that access the Certificate Trust Stores prepared in this way to verify the internal server certificates.

Both servers used in Pipeline Pilot, Apache HTTP Server and Apache Tomcat, regularly use HTTPS connections, whether as part of BIOVIA applications such as Insight and Chemical Registration or when using corresponding components in protocols. The Apache HTTP server accesses the standard trust stores of the operating system and can therefore generally verify both the certificates of public servers and those of internal servers. However, the embedded Java runtime environment used for the Pipeline Pilot Tomcat server initially only recognizes the public CAs officially supported by Java. The internal CAs must therefore be added to the Java runtime environment of the Pipeline Pilot at the latest if you want to use the server port usage option 'SSL only'.

In the following solution we describe the steps to add your internal CAs to the Pipeline Pilot Java runtime environment. These steps also apply if you need to add uncommon CAs from public servers that are not part of a standard Java runtime deployment.

 

Solution

The following steps describe how to add your company's internal CAs to the Java runtime environment of your Pipeline Pilot installation. For this, we assume that you have installed Pipeline Pilot into the following directories:

	Linux: /opt/BIOVIA/PPS
	Windows: c:\Program Files\BIOVIA\PPS

 

  1. Obtain the public certificates of the Root and Intermediate CAs in unencrypted PEM format from your company's IT department. As these certificates are public you can also export them from the browser. For instance, in Chrome navigate to the Pipeline Pilot home page, and click on the 'Site Information' icon at the left end of the address bar. Click on 'Connection is secure' and then 'Certificate is valid' to open the Certificate View. In the 'Details' tab, you can select each of the root and intermediate certificates from the Certificate Hierarchy section, and export them into files. Specify the base64-encoded single certificate file option as export format. Let's assume the root and intermediate certificates were saved as 'RootCA.cer' and 'IntermediateCA.cer', respectively.

     

  2. On the Pipeline Pilot server, open a command line, and navigate to the location of the trust store of the Java runtime of the Pipeline Pilot installation

    Linux:
    cd /opt/BIOVIA/PPS/apps/scitegic/core/packages_linux64/java/jdk/lib/security
    
    Windows:
    cd /D  "c:\Program Files\BIOVIA\PPS\apps\scitegic\core\packages_win64\java\jdk\lib\security"

     

  3. For easier file handling in the commands in step 6, copy the certificate files obtained in step 1 to this directory .

     

  4. Make a backup copy of the 'cacerts' file located in this directory.

     

  5. Add the 'bin' directory of the Pipeline Pilot's Java runtime to the PATH environment variable.

    Linux:
    export PATH=/opt/BIOVIA/PPS/apps/scitegic/core/packages_linux64/java/jdk/bin:\$PATH
    
    Windows:
    set PATH=C:\Program Files\PPS\apps\scitegic\core\packages_win64\java\jdk\bin;%PATH%

     

  6. Add the two certificates to the 'cacerts' file, using the Java keytool command. The values in the -alias option are arbitrary but must be unique.

    keytool -import -keystore ./cacerts -storepass changeit -alias RootCA -file ./RootCA.cer
    keytool -import -keystore ./cacerts -storepass changeit -alias IntermediateCA -file ./IntermediateCA.cer 

     

  7. Restart the Pipeline Pilot services.