Securing network traffic – SSL

This section describes how to enable secure networking communication between the different components of the ROB-EX system. Enabling SSL means that traffic between server and clients are encrypted and that web-server sessions with the Shop Floor client must be accessed through https in the browser.

For how to configure encryption between ROB-EX Scheduler Server and the database see the section Server installation – Secure network communication.

*SSL/HTTPS is by default turned off when ROB-EX is installed out-of-the box.

*Note that it is supported to enable SSL/HTTPS individually for the different components. As an example HTTPS can be enabled for Shop Floor clients – without enabling SSL for the communication between ROB-EX Server and ROB-EX Clients. The SSL communication between server and clients is enabled based on settings made on the Multiuser Server side (application.yaml). The SSL for Shop Floor clients are enabled through the Shop Floor plugin file on the integration client.

This manual is divided into the following sections, explaining how to enable secure communication for the different components (the number refers to the number on the drawing above)

• Multiuser Server
• Web-admin
• Shop Floor clients
• REST Server Service

!The components 1+2 uses a different certificate technology than 3+4. Generating a new self-signed certificate for the different technologies follows two different methods as described below.

*The current setup will work out of the box on self signed certificates as explained below. If you plan to install the ROB-EX Scheduler system in a publicly available environment, we recommend that you place the entire environment behind a software proxy like Traefik . The Traefik proxy will allow you to easily setup a single endpoint with a single CA trusted certificate being auto renewed. Please contact ROB-EX Scheduler support for more information regarding this option.

Multiuser Server

SSL communication between the Multiuser Server and ROB-EX cliens is by default turned off. To enable this feature change the configuration by hand editing file application.yml. Read more about the settings of this file here.

Start out by locating the location on the file system where your server is installed. If in doubt locate the Server service (Run->Services.msc and locate the ROB-EX Multiuser Service for instance X). Double click on the service and take a note of the “Path to executable:” – the application.yml file will be in the same directory as the executable. The default location will be in C:\Program Files (x86)\ROB-EX\ganttServerG2\application.yml.

Add these lines to the file, changing the grpc.server.security.enabled value to true

grpc:
   port: 6566  # client http port
   server:
      security:
         enabled: true

!After editing of the application.yml file, restart your ROB-EX Server service before the change will take effect (Run->Services.msc)

!All ROB-EX Scheduler clients must now connect with https as prefix in the Server Host setting of Functions->Settings->General->Multiuser

!The out-of-the-box generated certificates will only work for localhost, e.g. clients connecting to https://localhost:6565. Read below how to generate your own self signed certificates that works for your server hostname.

!To use self-signed certificates, the ROB-EX Scheduler must be started with the command line parameter -Dgantt.certificates.local=true (valid from v7.0.0.267 and later). By default public certificate authorities are expected for https client connections.

Generating ROB-EX Scheduler Server certificates

This explains how to generate self-signed certificates for the components 1+2 on the top drawing.

The default certicate installed out-of-the-box is located in ganttServerG2\certificates. This self signed certificate is locked to the localhost domain and should only be used for testing, i.e. the default certificates will only work for ROB-EX clients connecting to https://localhost:6565. You need to generate your own private self-signed certificates where you bake the hostname of your server into.

To generate new self-signed certificates

1. Install the Openssl command line tool from a trusted location. See e.g. wiki.openssl.org/index.php/Binaries . You can test a valid openssl tool by opening a command prompt with cmd.exe and run the command openssl version -a . The following has been tested to work with the v1.1.1 of the Openssl tool.
2. Edit ganttServerG2\create-selfsigned-certificate.bat, replacing robex-srv1 in the line set SRV_NAME=robex-srv1 with the actual name of your ROB-EX server. Then save the file
3. Run the ganttServerG2\create-selfsigned-certificate.bat script, by double clicking the file from Windows File Explorer. Verify that new *.pem and *.pfx files were generated to the ganttServerG2\certificates folder.

Finally copy the two files selfsigned-public-key-cert.pem and selfsigned-key-store.pfx to the \config\certificates folder of your ROB-EX Scheduler Client installation directory. This will ensure that the ROB-EX Scheduler clients know the new certificates.

Common issues and debugging pointers.

If self signed certificates are used the property gantt.certificates.local has to be set to true, if not the client wont be able to connect to the server. By default there will be nothing in the log file indicating that an error has happened, besides the time out when connecting. To obtain the information that the TLS handshake failed, because the client doesn’t trust the certificate, the log level for the name space io.grpc.netty need to be set to trace. The same problem will happen if host name does not match the name in the generated certificate.

In general issues with the certificates wont be shown at the error log level, so it is necessary to edit the logback.xml of the client or server to debug issues with certificates.

Web-admin

SSL communication between the Multiuser Server Admin pages (typically on port 9090) and ROB-EX cliens is by default turned off. To enable this feature change the configuration by hand editing file application.yml. Read more about the settings of this file here.

Start out by locating the location on the file system where your server is installed. If in doubt locate the Server service (Run->Services.msc and locate the ROB-EX Multiuser Service for instance X). Double click on the service and take a note of the “Path to executable:” – the application.yml file will be in the same directory as the executable. The default location will be in C:\Program Files (x86)\ROB-EX\ganttServerG2\application.yml.

Add these highlighted lines to the file as part of the server section, making sure the server.port.ssl.enabled value is set to true

server:
   port: 9090  # web-admin http server port
   use-forward-headers: true  # To support reverse-proxy like Traefik
   ssl:
      enabled: true
      key-store: ./certificates/selfsigned-key-store.pfx
      key-store-password:     # see openssl '-passout pass:' option
      key-password:           # see openssl '-passout pass:' option (use same value as key-store-password)
      key-alias: localhost    # see openssl '-name' option. Will typically be the lower case hostname of the server
      key-store-type: pkcs12  # .pfx file extension.

Very likely the key-alias must also be edited to reflect the real hostname of the Windows server that hosts the ROB-EX Scheduler Multiuser Server service. On top, if the certificate is not a selfsigned certificate, in order to discover the alias name, you need to use the jre keytool for this

bin\jre\bin\keytool -v -list -storetype pkcs12 -keystore RobexPrivateKey.pfx
Enter keystore password: ***

The output will look like this. The alias name is toward the top. The name marked in bold is the alias needed. Update config file ganttSeverG2\application.yml with this name.

Keystore type: PKCS12
Keystore provider: SUN
Your keystore contains 1 entry
Alias name: te-85a00c42-4d6f-487f-86a9-e072c9182816
Creation date: Jun 8, 2023
Entry type: PrivateKeyEntry
..

!After editing of the application.yml file, restart your ROB-EX Scheduler Multiuser Server service before the change will take effect (Run->Services.msc). Also make to open the Web-admin pages using https, e.g. https://localhost:9090

Shop Floor

Changes must be made to the \plugins\shopfloor\site\conf\server.xml file. If Shop Floor is available as a public service on the internet, then it is strongly recommended to secure the communication with SSL.

The normal http connector should be commented out, like this:

<!--
 <Connector className="org.apache.catalina.connector.http.HttpConnector"
               port="80" minProcessors="5" maxProcessors="75"
               enableLookups="true" redirectPort="18443"
               acceptCount="10" debug="0" connectionTimeout="60000"/>
-->

Below the above connector is another with scheme=https. This needs to be commented-in by removing the immediate surrounding <!-- and -->

 <Connector className="org.apache.catalina.connector.http.HttpConnector"
                       port="443" minProcessors="5" maxProcessors="75"
                       enableLookups="true"
                       acceptCount="10" debug="0" scheme="https" secure="true">
                <Factory className=
                                 "org.apache.catalina.net.SSLServerSocketFactory"
                         clientAuth="false"
                         keystoreFile="/config/ssl/.keystore"
                         keystorePass="xxxxxxxxxx"
                         protocol="TLS"
                         keyAlias="gantt"
                        />
            </Connector>

The important parts are the marked areas for port, scheme and secure. The default https port is 443 and Shopfloor can be accessed on https://localhost (i.e. notice it is not necessary to specify the port number, as 443 is the default port for https communication). If another port is preferred the port attribute should be changed.

More information about how to install your own certificate files can be found in the chapter Keystore and truststore. Note that if you install your own certificates, then In addition the client must be configured with updated SSL settings as described in ROB-EX Client configuration.

*Note that it is supported to enable HTTPS for Shop Floor – without enabling SSL for the communication between ROB-EX Server and ROB-EX Clients. The SSL communication between server and clients is enabled based on settings made on the Multiuser Server side.

REST Server Service

To enable SSL for the REST Server Service integration (used as example for communication with .NET based clients) add the https scheme usage as a parameter on the short cut for starting ROB-EX, or alternatively insert this line in custom/GanttSetup.properties:

-Dgantt.rest.scheme=https

More information about how to install your own certificate files can be found in the chapter Installing your own Shop Floor and REST certificate. Note that if you install your own certificates, then In addition the client must be configured with updated SSL settings as described in ROB-EX Client configuration.

REST clients connecting to a https enabled REST service, must be configured to allow and accept self-signed certificates. The details of this depends on the coding language used, but should be straight forward to implement.

Installing your own Shop Floor and REST certificate

This explains how to generate self-signed certificates for the components 3+4 on the top drawing.

The default certicate installed out-of-the-box is located in \config\ssl. These default certificates are not locked to the localhost domain and could be used out-of-the-box. However for improved safety is is always good to generate your own self signed certificates.

This section describes what tools to use in case you would like to install and use your own certificate, e.g. your own self signed certificates or a certificate obtained from a trusted certificate authority (CA). The certificate provided out of the box with ROB-EX, is a self signed certificate. This certificate type has the following pros and cons:

• (+) it is free to use
• (+) it never expires (a certificate issues by a CA, will typically expire after 1-2 years)
• (+) it is secure, in the sense that transmitted data is encrypted in a robust and secure fashion
• (-) a browser will warn that the certificate is not issued by a trusted certificate authority. If you want to avoid the warning, the different browsers all have options a user can accept a self signed certificate as being safe (search the Internet for a how-to on the subject).

If you would like to install your own certificate, the certificate should be generated and added to the keystore for the ROB-EX client sides. A tool that is part of the JDK from Oracle/OpenJDK, called keytool and is located in the bin folder, is used for working with certificate stores

To generate your own certificate.

keytool -genkey -alias gantt -keyalg RSA -validity 36500 -keystore .keystore

If you wish to add an existing signed primary certificate use this:

keytool -import -trustcacerts -alias gantt -file mycertificate.crt -keystore .keystore

The client side need to use a truststore with the certificate. To do this, export from the keystore with the keytool:

Export the certificate from the keystore

keytool -export -alias gantt -keystore .keystore -rfc -file provider.cer

Import the certificate into the truststore

keytool -import -alias gantt -file provider.cer -keystore .truststore

New keystore and truststore files should be placed into the \config\ssl folder (client side)

ROB-EX Client

The client setup properties for Shop Floor and REST Server Service must be changed by adding/modifying the lines below to the \custom\GanttSetup.properties file (typically add these lines at the top of the file):

-Djavax.net.ssl.keyStore=./config/ssl/.keystore
-Djavax.net.ssl.keyStorePassword=

-Djavax.net.ssl.trustStore=./config/ssl/.truststore
-Djavax.net.ssl.trustStorePassword=

Note that when using the internal ROB-EX generated certificate, passwords can be left as blank and it will automatically use the password defined in the server.xml config. Passwords need only be specified when you want to use your own generated certificate.

Copyright © 2023 ROB-EX A/S