Configuring VHI Session Server to use a CA Signed Certificate in a Customized Keystore

  • 7024832
  • 18-Sep-2020
  • 11-Feb-2021

Environment

Verastream Host Integrator 7.7 and later
Windows operating systems
Linux operating systems

Situation

Verastream Host Integrator default install uses a self-signed certificate in the session server keystore. A customer may want to change the certificate to an internal or public signed CA.

These instructions cover the steps required to convert a PKCS12 keystore to a Bouncy Castle keystore and configure it so Verastream Host Integrator session server can use the new keystore.

Resolution

Requirements:

The keystore that will be used is a PKCS12 keystore and has already been created with all necessary CAs imported into the keystore.

The keystore and private key need to use the same password.

A copy of the root CA public cert stored in a file on disk.

KeyStore Explorer 5.4.3 or later - https://keystore-explorer.org/downloads.html

OpenJDK 14 or later - https://jdk.java.net/14/

Guidelines:

It is best to install KeyStore Explorer and modify the keystore on the workstation or server where you plan to run Verastream Host Integrator (VHI). If that is not possible KeyStore Explorer can be installed on another workstation and the keystore can be copied to the VHI server.

Modifying the VHI Session Server to use a custom configuration:

Installation and Configuration of Keystore Explorer:

1. Stop the VHI Session Server.

2. Install KeyStore Explorer 5.4.3 or later.

3. Extract the JDK 14 to a directory.

4. Create a directory called “jre”.

5. Copy the contents (bin, conf, include, jmods, legal, and lib) of the extracted JDK to the “jre” directory.

6. Copy the “jre” directory to the root directory of KeyStore Explorer.

     Modification of Verastream Host Integrator keystore:

1. Create a working directory on your machine to modify the keystore.

2. Copy the keystore into the working directory.

3. Make a backup of the file so you can easily revert back to the default file if necessary.

4. Run KeyStore Explorer.

5. Open the PKCS12 keystore.

6. Enter the keystore password and select “OK”.

7. Select ‘Tools/Change KeyStore Type/BCFKS’.

8. Enter the keystore password and select “OK”.

9. Select ‘File/Save As’.

10. Enter the keystore filename you would like to use (e.g. vhiss.bcfks), but use an extension of .bcfks. Do not the keystore with the filename of “sever.bcfks”.

11. Select “save” to save the file.

12. You are now working in the file with extension of .bcfks.

13. Right click on the keystore entry and select “Rename”.

14. Enter the name “server-container” and select “OK”.

15. Save the keystore.

16. Right click again on the keystore entry, now called “server-container” and select “Copy”.

17. Select ‘Edit/Paste’ from the toolbar. A duplicate entry should be created with the name “server-container (1)”.

18. Right click on the entry “server-container (1)” and select “Rename”.

19. Enter a name of “existingaliasname” and select “OK”.

20. Select ‘Tools/Import Trusted Certificate’.

21. Browse to the location where the root CA certificate file is stored and select the certificate and then “Open”.

22. Enter the alias of “trust-anchor” on the next screen and then click “OK” and “OK” again to dismiss the successful import dialog.

23. Your keystore should now look like this:

24. Save the keystore.

25. Copy the new keystore to the %VHI_HOME%/HostIntegrator/sesssrvr/etc directory).

26. Change directory to the %VHI_HOME/HostIntegrator/sesssrvr/services/ws/META-INF directory.

27. Backup the file “service-ctx.xml” by copying it to another directory.

28. Edit the “service-ctx.xml” in the “META-INF” directory.

29. Find the following entry (should be line 47 and 48):

<!-- HTTPS context factory bean instance. -->
<property name="SSLContextFactory" ref="httpsContextFactory"/>

30. Replace those two lines with the following 13 lines (update pathing as necessary):

<!-- HTTPS context factory bean instance. -->
<property name="SSLContextFactory">
<bean class="com.attachmate.integration.container.ssl.SSLContextFactorySC" init-method="initialize">
<property name="keyManagerFactory">
<bean class="com.attachmate.integration.container.ssl.KeyManagerFactorySC" init-method="initialize">
<property name="keystoreName" value="C:/Program Files/Micro Focus/Verastream/HostIntegrator/sesssrvr/etc/servlet.bcfks"/>
<property name="keystorePassword" value="YourPasswordGoesHere"/>
<property name="keyStoreType" value="BCFKS"/>
<property name="keyAlias" value="existingaliasname"/>
</bean>
</property>
</bean>
</property>

31. Save the file.

32. Start the VHI Session Server and test to your application.

Additional Information

For configuring VHI Web Server, see KB 7024812.