HTTPS protocol (TLS for HTTP) allows both to encrypt the communication between the two parties, to ensure the integrity of the information and to verify the authentication of the web server.


In Semarchy xDI, the HTTPS communication is by default mandatory for non-local access.


This article details how to configure TLS for HTTP communication in each xDI components in order to have a secured architecture.

Limitation
  1. As Semarchy xDI can be integrated in a large choice of architectures (on-premise, cloud, docker - with/without cluster, load-balancer, firewall, proxy, scheduler, etc.), it is important to adapt this content to YOUR architecture.

    The provided steps configurations/screenshots have been applied in a Windows architecture, java jdk 11 LTS, Semarchy 2023.1 LTS, Apache Tomcat 9.0.x. No third party application/tool involved like cluster, load-balancer.


  2. For a better understanding, the open source tool KeyStore Explorer under GNU General Public License (more information here) will be mainly used for the certificate management actions. This graphical user interface will replace most of the Java command-line utilities keytool and jarsigner.
General specifications
This section is a guide on KeyStore, Key Pair and Trusted Certificate with KeyStore Explorer.
Go to the next section for the TLS implementation in Semarchy xDI.


KeyStore
A KeyStore is a file storage mechanism for cryptographic tokens known as entries.

You can use an existing KeyStore or create a new KeyStore.

To create a new KeyStore using KeyStore Explorer :
  1. From the File menu, choose New
  2. Select the KeyStore Type : JKS Java KeyStore for example.
  3. Press the OK button.
  4. The new KeyStore will appear as an additional Untitled tab.
  5. From the File menu, choose Save     
  6. Set a password for the KeyStore.
  7. Select the drive and folder where the KeyStore file is to be saved.
  8. Type the filename.
  9. Click on the Save button.


Example :


Key Pair
The Keystore will have Key Pair (Holds a private key and its associated chain of one or more certificates) entries.

In the KeyStore, you can import an existing Key Pair with Signed Certificate (done by a CA (Certificate Authority)), import a Key Pair with Self-Signed Certificate or generate a Key Pair with Self-Signed Certificate.

A Self-Signed Certificate is not recommended for use in production environments and should only be used to facilitate test environments prior to production.

Contact your server administrator for a Signed Certificate by a Certificate Authority.

To generate a Key Pair with a Self-Signed Certificate using Keystore Explorer :
  1. From the Tools menu, choose Generate Key Pair. 
  2. Select an Algorithm and a Key Size
  3. Press the OK button.
  4. Select a Version and Signature Algorithm and enter a Validity Period, Serial Number and Name.
  5. In Name dialog : enter the CN (Common Name = server domain name), OU (Organization Unit), O (Organization Name), L (Locality Name), ST (State Name), C (Country)
  6. Enter the alias for the new Key Pair entry and press the OK button.
  7. Enter the password with which to protect the new Key Pair entry, confirm it and press the OK button.
  8. The new Key Pair entry will appear in the KeyStore Entries table.


Example :



Trusted Certificate
The Keystore will have Trusted Certificate (contains a single certificate) entries.

In the KeyStore, you can import an existing Trusted Certificate or export a Certificate Chain from a Key Pair and then import it as a Trusted Certificate.

To export a Key Pair's Certificate Chain :
  1. Right-click on the Key Pair entry in the KeyStore Entries table. 
  2. Select the Export sub-menu from the pop-up menu and from there choose Export Certificate Chain.
  3. Select an Export Length : Entire Chain
  4. Select an Export Format : X.509
  5. Use the Browse button to select an export file.
  6. Press the Export button to commence the export.

To import a Trusted Certificate :
  1. From the Tools menu, choose Import Trusted Certificate.
  2. Select the drive and folder where the certificate file is stored.
  3. Click on the required certificate file or type the filename into the File Name text box.
  4. Click on the Import button.
  5. Enter the alias of the new Trusted Certificate and press OK.
  6. The new Trusted Certificate entry will appear in the KeyStore Entries table with the chosen alias.


Example :

Concepts

In most cases, KeyStore and TrustStore are used by systems (application, servers, etc.) for TLS communication.
Generally speaking, a KeyStore will holds entries that identify the system itself, while a TrustStore will holds entries that identify others.

A secured architecture of Semarchy xDI example :



Overview

Semarchy xDI License Server
  • The License Server (Badge #1) will be secured with a private key and its associated chain certificate will be used by the Designer (Badge #2) for communication.
Semarchy xDI Runtime
  • The Runtime (Badge #3) will be secured with a private key and its associated chain certificate will be used by the Designer (Badge #4) and the Production Analytics (Badge #6) for communication.
Semarchy xDI Designer
  • The Designer will use the License Server chain certificate (Badge #2) for communication.
  • The Designer will use the Runtime chain certificate (Badge #4) for communication.
Semarchy xDI Production Analytics
  • The Production Analytics (Badge #5) will be secured with a private key.
  • The Production Analytics will use the Runtime chain certificate (Badge #6) for communication.


Manipulated/required objects in next section

Semarchy xDI License Server
  • License Server KeyStore "semarchy-xdi-license-keystore.jks" with :

  • License Server Key Pair "semarchy-xdi-license-keypair"  

  • License Server configuration : conf/spring-context.xml

Semarchy xDI Runtime

  • Runtime KeyStore "semarchy-xdi-runtime-keystore.jks" with :

  • Runtime Key Pair "semarchy-xdi-runtime-keypair" 

  • Runtime configuration : properties/engineParameters.xml

Semarchy xDI Designer

  • Designer TrustStore "semarchy-xdi-designer-truststore.jks" with :

  • License Server Trusted Certificate "semarchy-xdi-license-trustcer"

  • Runtime Trusted Certificate "semarchy-xdi-runtime-trustcer"

  • Designer configuration : semarchy-xdi-designer-windows.ini

  • Or Java TrustStore if the configuration is not done in semarchy-xdi-designer-windows.ini

Semarchy xDI Production Analytics

  • Production Analytics KeyStore "semarchy-xdi-analytics-keystore.jks" with :

  • Production Analytics Key Pair "semarchy-xdi-analytics-keypair"  

  • Production Analytics TrustStore "semarchy-xdi-analytics-truststore.jks" with :  

  • Runtime Trusted Certificate "semarchy-xdi-runtime-trustcer"

  • Apache Tomcat configuration

  • Server configuration : conf/server.xml

  • Java options : bin/setenv.bat (for command line)  and/or Windows service  

  • Or Java TrustStore if the configuration is not done with Java options  


Semarchy xDI License Server


Semarchy xDI License Server is an optional component that you can install to manage internally the Semarchy xDI instance's licenses when the host server doesn't have internet access.


KeyStore Management

To enable the TLS in Semarchy xDI License Server, a Key Pair is mandatory.


Based on the information in the General specifications section, create/use a KeyStore with the Key Pair entry of Semarchy xDI License Server.


Example : KeyStore semarchy-xdi-license-keystore.jks with Key Pair semarchy-xdi-license-keypair


Note : Detail of the Self-Signed Certificate (if used) when working in localhost for development purpose



TLS Configuration

Badge  #1 on the architecture 

Edit the license server's spring-context.xml with the TLS configuration as described in the Documentation.


Example :

   <bean

        class="com.semarchy.xdi.license.server.plugin.ssl.impl.DesignerSslPlugin">    

        <!-- enableSsl: This parameter is mandatory. It allow to enable or disable SSL -->            

        <property name="enableSsl" value="true"></property>

        <!-- keyStoreType: The keyStore type -->                    

        <property name="keyStoreType" value="JKS"></property>

        <!-- keyStore:  The relative or absolute path to the keyStore -->                    

        <property name="keyStore" value="C:\Projects\Tools\certificate\semarchy-xdi-license-keystore.jks"></property>

        <!-- keyStorePassword: The keyStore password -->                    

        <property name="keyStorePassword" value="changeit"></property>

        <!-- keyAlias: The certificate alias to be used -->                    

        <property name="keyAlias" value="semarchy-xdi-license-keypair"></property>

        <!-- keyPassword: The certificate password -->                    

        <property name="keyPassword" value="changeit"></property>

    </bean>


Communicating with the License Server

Provide the certificate to the clients 

Semarchy xDI Designer
Badge #2 on the architecture

2 available options
A/ Semarchy xDI Designer TrustStore (recommended)
TrustStore Management

It is recommended to initialize the TrustStore from the Java installation TrustStore.


Copy the <JAVA_HOME>\lib\security\cacerts to semarchy-xdi-designer-truststore.jks.


Based on the information in the General specifications section, use the TrustStore and import the Trusted Certificate entry of Semarchy xDI License Server. Default password is "changeit".


Example : TrustStore semarchy-xdi-designer-truststore.jks with Trusted Certificate semarchy-xdi-license-trustcer


TLS Configuration
Provide the TrustStore to Semarchy xDI Designer in order to use the Semarchy xDI License Server associated certificate.


Add the below example lines in <Designer installation folder>\semarchy-xdi-designer-windows.ini :
-Djavax.net.ssl.trustStore=C:\Projects\Tools\certificate\semarchy-xdi-designer-truststore.jks
-Djavax.net.ssl.trustStoreType=JKS
-Djavax.net.ssl.trustStorePassword=changeit



B/ Java TrustStore

Based on the information in the General specifications section, import the Semarchy xDI License Server Trusted Certificate in Semarchy xDI Designer Java installation TrustStore.


Example : Using KeyStore Explorer, open <JAVA_HOME>\lib\security\cacerts and import semarchy-xdi-license-trustcer.


Note : Adding the certificate in the Java TrustStore will make it available for all applications using that Java installation.


Semarchy xDI Runtime


KeyStore Management

To enable the TLS in Semarchy xDI Runtime, a Key Pair is mandatory.


Based on the information in the General specifications section, create/use a KeyStore with the Key Pair entry of Semarchy xDI Runtime.


Example : KeyStore semarchy-xdi-runtime-keystore.jks with Key Pair semarchy-xdi-runtime-keypair


Note : Detail of the Self-Signed Certificate (if used) when working in localhost for development purpose


TLS Configuration

Badge  #3 on the architecture 

Edit the Runtime engineParameters.xml with the TLS configuration as described in the Documentation. 


Example :

<parameter name="webServiceSecureProtocol" value="TLSv1.2"/>

<parameter name="webServiceKeyStoreFile" value="C:\Projects\Tools\certificate\semarchy-xdi-runtime-keystore.jks"/>

<parameter name="webServiceKeyStoreType" value="JKS"/> 

<parameter name="webServiceKeyStorePassword" value="changeit"/> 

<parameter name="webServiceKeyAlias" value="semarchy-xdi-runtime-keypair"/>

<parameter name="webServiceKeyPassword" value="changeit"/>



Communicating with the Runtime

Provide the certificate to the clients 

Semarchy xDI Designer
Badge #4 on the architecture

2 available options
A/ Semarchy xDI Designer TrustStore (recommended)
TrustStore Management

It is recommended to initialize the TrustStore from the Java installation TrustStore.


Copy the <JAVA_HOME>\lib\security\cacerts to semarchy-xdi-designer-truststore.jks. The file might already exists if the TrustStore has already been configured in Semarchy xDI Designer for communication to Semarchy xDI Licence Server. 


Based on the information in the General specifications section, use the TrustStore and import the Trusted Certificate entry of Semarchy xDI Runtime. Default password is "changeit".


Example : TrustStore semarchy-xdi-designer-truststore.jks with Trusted Certificate semarchy-xdi-runtime-trustcer


The Trusted Certificate semarchy-xdi-license-trustcer might exists in the TrustStore semarchy-xdi-designer-truststore.jks if it has been configured for communication with Semarchy xDI License Server.


TLS Configuration

This step can be skipped if the TrustStore has already been configured in Semarchy xDI Designer for communication with Semarchy xDI License Server.


Otherwise, provide the TrustStore to Semarchy xDI Designer in order to use the Semarchy xDI Runtime associated certificate.


Add the below example lines in <Designer installation folder>\semarchy-xdi-designer-windows.ini :
-Djavax.net.ssl.trustStore=C:\Projects\Tools\certificate\semarchy-xdi-designer-truststore.jks
-Djavax.net.ssl.trustStoreType=JKS
-Djavax.net.ssl.trustStorePassword=changeit


B/ Java TrustStore

Based on the information in the General specifications section, import the Semarchy xDI Runtime Trusted Certificate in Semarchy xDI Designer Java installation TrustStore.


Example : Using KeyStore Explorer, open <JAVA_HOME>\lib\security\cacerts and import semarchy-xdi-runtime-trustcer.


Note : Adding the certificate in the Java TrustStore will make it available for all applications using that Java installation.

Semarchy xDI Production Analytics

Badge #6 on the architecture

2 available options

A/ Semarchy xDI Production Analytics TrustStore (recommended)

TrustStore Management

It is recommended to initialize the TrustStore from the Java installation TrustStore.


Copy the <JAVA_HOME>\lib\security\cacerts to semarchy-xdi-analytics-truststore.jks.


Based on the information in the General specifications section, use the TrustStore and import the Trusted Certificate entry of Semarchy xDI Runtime. Default password is "changeit".


Example : KeyStore semarchy-xdi-analytics-truststore.jks with Trusted Certificate semarchy-xdi-runtime-trustcer


TLS Configuration

Provide the TrustStore to Apache Tomcat in order to use the Semarchy xDI Runtime associated certificate.


Command line execution (startup.bat)
Add the below example lines to the web application environment variables in <Apache Tomcat installation folder>\bin\setenv.bat (to create if not exists) :
SET JAVA_OPTS=%JAVA_OPTS% "-Djavax.net.ssl.trustStore=C:\Projects\Tools\certificate\semarchy-xdi-analytics-truststore.jks"

SET JAVA_OPTS=%JAVA_OPTS% "-Djavax.net.ssl.trustStorePassword=changeit"

SET JAVA_OPTS=%JAVA_OPTS% "-Djavax.net.ssl.trustStoreType=JKS"


Windows service execution

Update the apache tomcat service (if used) in a Windows command prompt with below command example line :

Tomcat9.exe //US//Tomcat9 ++JvmOptions="-Djavax.net.ssl.trustStore=C:\Projects\Tools\certificate\semarchy-xdi-analytics-truststore.jks";"-Djavax.net.ssl.trustStorePassword=changeit";"-Djavax.net.ssl.trustStoreType=JKS"


B/ Java TrustStore

Based on the information in the General specifications section, import the Semarchy xDI Runtime Trusted Certificate in Apache Tomcat Java installation TrustStore.


Example : Using KeyStore Explorer, open <JAVA_HOME>\lib\security\cacerts and import semarchy-xdi-runtime-trustcer.


Note : Adding the certificate in the Java TrustStore will make it available for all applications using that Java installation.


Semarchy xDI Production Analytics


KeyStore Management

To enable the TLS in Semarchy xDI Production Analytics, a Key Pair is mandatory.


Based on the information in the General specifications section, create/use a KeyStore with the Key Pair entry of Semarchy xDI Production Analytics.


Example : KeyStore semarchy-xdi-analytics-keystore.jks with Key Pair semarchy-xdi-analytics-keypair


Note : Detail of the Self-Signed Certificate (if used) when working in localhost for development purpose



TLS Configuration

Badge  #5 on the architecture 

Edit the Apache Tomcat web server file with the TLS configuration.


Update the below example lines in <Apache Tomcat installation folder>\conf\server.xml :

     <Connector port="8443" protocol="org.apache.coyote.http11.Http11NioProtocol"

               maxThreads="150" SSLEnabled="true"

               maxParameterCount="1000"

               >

        <SSLHostConfig>

            <Certificate certificateKeystoreFile="C:\Projects\Tools\certificate\semarchy-xdi-analytics-keystore.jks"

                         certificateKeystorePassword="changeit"

                         certificateKeyAlias="semarchy-xdi-analytics-keypair"

                         certificateKeyPassword="changeit"

                         certificateKeystoreType="JKS"

                         type="RSA" />

        </SSLHostConfig>

    </Connector>