Configuring SSL/TLS for End User Interface

By default, End User Interface is automatically redirecting all HTTP requests to encrypted HTTPS connection. In order to ensure secure connection to EUI, you need to use certificate trusted in your environment.

In case you want to communicate using unsecured HTTP, you have to set the following configuration option in the <eui_folder>\u i-conf\ environment-configuration.properties (usually <install_dir> \SPOC\EUI\u i-config\environment-configuration.properties ) configuration file:

web.channel=http

This is, however, not recommended.

This guide will help you with the configuration of the secured connection (HTTPS) to the End User Interface, using a CA-signed certificate.

CA-signed certificate requirements

  • The certificate must be signed by a certification authority trusted in your environment.

  • Certificate (fields Common Name and Subject Alternative Name) must contain all network names (i.e. all hostnames, fully qualified domain names and IP addresses) used for connection to the respective server.

  • For importing the certificate you need an appropriate format - Java Keystore (.jks file) containing the private key and whole certificate chain. The procedure below is simplified by creating a new keystore instead of reusing the existing one.

  • Both the keystore and key itself need to be protected by a password.

In case your key/certificate is in a different format than Java Keystore, convert it following the guide Conversions between different keystores and certificate types.

In case you do not have key/certificate at all, follow the guide in the Generating key/certificate in Java Keystore format chapter in System communication hardening.

Configuring EUI to use secure communication channel

This section describes the way how to make the web connection secure using the CA-signed certificate.

  1. Stop YSoft SafeQ End User Interface service on YSoft SafeQ server.

  2. Copy your key/certificate in the Java Keystore format to the server where EUI is installed.

  3. Modify <eui_folder>\conf\server.xml (usually <install_dir> \SPOC\EUI\conf\server.xml) file as follows:

    keystoreFile = "absolute/path/to/your/keystore.jks"
    keystorePass = "keystore protecting password"
    keyPass = "key protecting password"

    By default, keyPass attribute has the same value as keystorePass. Set this attribute if the key and the keystore are protected using different passwords.

    During the update, the spooler controller installer attempts to update the original end user interface configuration server.xml file. If this process is successful, the original file in the new installation is used and the new installation file is placed in a repository with a .new extension. If the update process is not successful, the original end user interface configuration server.xml file is replaced with a new installation file. The original file is marked with a .bak extension. Process result information is logged in the sc-install.log file. If an error is reported here, check the status of server.xml files in <install_dir> SPOC\EUI\conf folder and check the contents of both files.

  4. Start the YSoft SafeQ End User Interface service on YSoft SafeQ server.

  5. Verify that the End User Interface is functional and uses your own certificate (open https://<server-ip-address>:9443/end-user/ui in browser, click on the lock and view certificate button). In case you did not disable the automatic redirection to HTTPS, opening the http://<server-ip-address>:9090 address will be automatically redirected to https protocol.

Example of Tomcat HTTPS configuration

The configuration is stored in <eui_folder>\conf\server.xml (usually <install_dir> \SPOC\EUI\conf\server.xml)

Keep HTTP non-SSL port (default 9090) as the first in XML. The installer requires HTTP port to be the first in definition. HTTPS should be the second.

<!-- Define a non-SSL HTTP/1.1 Connector on port 8080 -->
<Connector port="9090" connectionTimeout="20000" protocol="HTTP/1.1" redirectPort="9443"/>
 
<Connector port="9443" protocol="org.apache.coyote.http11.Http11Nio2Protocol"
maxThreads="200"
SSLEnabled="true"
secure="true"
scheme="https"
sslProtocol="TLS"
useBodyEncodingForURI="true"
keystoreFile="${catalina.base}/ui-conf/keystore.jks"
keystorePass="*****"
truststoreFile="${catalina.base}/ui-conf/truststore.jks"
truststorePass="*****"
clientAuth="false"
sslEnabledProtocols="TLSv1.3,+TLSv1.2"
ciphers="..." >
</Connector>

The default, pre-installed private key is stored together with its corresponding certificate in <eui_folder>\ui-conf\keystore.jks file. Both, keystore and private key, are protected by the same password specified in configuration file with attribute keystorePass.

The <eui_folder>\ui-conf\truststore.jks file contains certificates that should be trusted by EUI when client authentication is required (clientAuth attribute). Currently this file is empty.

The ciphers attribute contains the list of cipher suites you want to support. The following configuration is recommended:

ciphers="TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384,TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384,TLS_ECDHE_ECDSA_WITH_CHACHA20_POLY1305_SHA256,TLS_ECDHE_RSA_WITH_CHACHA20_POLY1305_SHA256,TLS_AES_256_GCM_SHA384,TLS_CHACHA20_POLY1305_SHA256,TLS_AES_128_GCM_SHA256,TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256,TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256"