Configuring SSL

Configuring SSL for Web Client Connections

This section describes the procedure to enable SSL on for Web Client connections. Client Manager uses an embedded Jetty Web Server to implement web access. Configuring SSL on Client Manager is essentially the same as that on Jetty. A demo is discussed in the next section to provide a jump start.

This guide assumes you already have these Tidal Automation products installed and connected to one another:

• Master

• Client Manager

• Data Source Provider (DSP) Plugin

Demo

The Client Manager comes with a demo certificate to allow you to quickly test its SSL functionality.

To enable the demo:

1. Shut down the Client Manager.

2. Open Web server configuration file config/webserver.xml located in Client Manager installation directory using a text editor.

   Note: Back up this file before you start editing it to ensure there is a good copy to fall back to.

3. Find the segment of SSL connector that looks like this. Uncomment the segment by removing "<!--" at the beginning and "-->" at the end.

<!--

<New id="sslContextFactory"

class="org.eclipse.jetty.util.ssl.SslContextFactory">

<Set name="KeyStorePath"> 

<Property name="jetty.keystore" default="config/demo-keystore" /> </Set>

<Set name="KeyStorePassword"> 

<Property name="jetty.keystore.password"

default="OBF:1vny1ym91x1b1z7e1vu91y0s1ri71y0y1vv11z7o1x1b1ym51vn4" /> </Set>

<Set name="KeyManagerPassword">

<Property name="jetty.keymanager.password"

default="OBF:1vny1ym91x1b1z7e1vu91y0s1ri71y0y1vv11z7o1x1b1ym51vn4" /> </Set>

<Set name="TrustStorePath"> 

<Property name="jetty.truststore" default="config/demo-keystore" /> </Set>

<Set name="TrustStorePassword">

<Property name="jetty.truststore.password" 

default="OBF:1vny1ym91x1b1z7e1vu91y0s1ri71y0y1vv11z7o1x1b1ym51vn4" /> </Set>

<Set name="EndpointIdentificationAlgorithm"> </Set>

<Set name="NeedClientAuth"> 

<Property name="jetty.ssl.needClientAuth" default="false" /> </Set>

<Set name="WantClientAuth"> 

<Property name="jetty.ssl.wantClientAuth" default="false" /> </Set>

<Set name="IncludeCipherSuites"> 

<Array type="String">

<Item>.*CBC.*</Item>

<Item>.*RSA.*</Item>

</Array>

</Set>

<Set name="ExcludeCipherSuites">

<Array type="String">

<Item>SSL_RSA_WITH_DES_CBC_SHA</Item>

<Item>SSL_DHE_RSA_WITH_DES_CBC_SHA</Item>

<Item>SSL_DHE_DSS_WITH_DES_CBC_SHA</Item>

<Item>SSL_RSA_EXPORT_WITH_RC4_40_MD5</Item>

<Item>SSL_RSA_EXPORT_WITH_DES40_CBC_SHA</Item>

<Item>SSL_DHE_RSA_EXPORT_WITH_DES40_CBC_SHA</Item>

<Item>SSL_DHE_DSS_EXPORT_WITH_DES40_CBC_SHA</Item>

<Item>TLS_DHE_RSA_WITH_AES_128_CBC_SHA256</Item>

<Item>TLS_RSA_WITH_AES_128_CBC_SHA</Item>

<Item>TLS_DHE_RSA_WITH_AES_128_CBC_SHA</Item>

<Item>TLS_RSA_WITH_AES_128_CBC_SHA256</Item>

<Item>TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA</Item>

<Item>TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA256</Item>

<Item>TLS_RSA_WITH_3DES_EDE_CBC_SHA</Item>

<Item>TLS_DHE_RSA_WITH_3DES_EDE_CBC_SHA</Item>

<Item>TLS_ECDHE_RSA_WITH_3DES_EDE_CBC_SHA</Item>

<Item>RSA_WITH_3DES_EDE_CBC_SHA</Item>

</Array>

</Set>

<Set name="excludeProtocols"> <Array type="java.lang.String">

<Item>TLSv1</Item>

</Array>

</Set>

</New>

<New id="sslHttpConfig"

class="org.eclipse.jetty.server.HttpConfiguration">

<Arg><Ref refid="httpConfig" /></Arg><Call name="addCustomizer">

<Arg> <New class="org.eclipse.jetty.server.SecureRequestCustomizer" />

</Arg></Call>

</New>

<Call id="httpsConnector" name="addConnector">

<Arg>

<New class="org.eclipse.jetty.server.ServerConnector">

<Arg name="server">

<Ref refid="Server" />

</Arg>

<Arg name="factories">

<Arraytype="org.eclipse.jetty.server.ConnectionFactory">

<Item>

<New class="org.eclipse.jetty.server.SslConnectionFactory">

<Arg name="next">http/1.1</Arg>

<Arg name="sslContextFactory"> <Ref refid="sslContextFactory" />

</Arg>

</New>

</Item>

<Item>

<New class="org.eclipse.jetty.server.HttpConnectionFactory">

<Arg name="config">

<Ref refid="sslHttpConfig" />

</Arg>

</New>

</Item>

</Array>

</Arg>

<Set name="host"><Property name="jetty.host" /></Set>

<Set name="port"><Property name="https.port" default="8443" /></Set>

<Set name="idleTimeout"><Property name="https.timeout" default="120000" /></Set>

<Set name="soLingerTime"><Property name="https.soLingerTime" default="-1" /></Set>

</New>

</Arg>

</Call>

4. Find the segment that looks like this to disable the non-SSL port. Comment the segment by adding "<!--" at the beginning and "-->" at the end.

<Callname="addConnector">

<Arg>

<New class="org.eclipse.jetty.server.ServerConnector">

<Arg name="server">

<Ref refid="Server" />

</Arg>

<Arg name="factories">

<Array type="org.eclipse.jetty.server.ConnectionFactory">

<Item>

<New class="org.eclipse.jetty.server.HttpConnectionFactory">

<Arg name="config">

<Ref refid="httpConfig" />

</Arg>

</New>

</Item>

</Array>

</Arg>

<Set name="host"> <Property name="jetty.host" /></Set>

<Set name="port"> <Property name="jetty.port" default="8080" /></Set>

<Set name="idleTimeout"> <Property name="http.timeout" default="120000" /></Set>

<Set name="soLingerTime"> <Property name="http.soLingerTime" default="-1" /></Set>

</New>

</Arg>

</Call>

5. Save the file and start the Client Manager.

6. Add this property to the clientmgr.props file.

   WebServer.enableRedirectFromHttpToHttps=Y

   Note: If SSL is enabled and the property "WebServer.enableRedirectFromHttpToHttps" is set to "Y" in clientmgr.props file, then the HTTP requests would be redirected to HTTPS.

7. Open a web browser on the Client Manager host system and enter the URL of TA Web Client with HTTPS protocol, as seen below:

   Example: https://localhost:8443/client

   Note: You may be prompted with a message about the site does not have a trusted certificate. This because the demo certificate is not signed by a certificate authority. It is only for demo purpose and not meant to be used in production server. You may instruct the browser to proceed.

   Your browser is now communicating with the Client Manager via HTTPS protocol.

Configuring SSL Using Your Own Certificate

To configure SSL using your own certificate:

1. Obtain the server key and certificate. You may generate key and certificate by yourself or obtain them from a trusted certificate authority (CA):

   • Generating key and certificate.

     There are various tools that allow you to generate keys and certificates, among them the Java Keytool that comes with JRE installation.

     Java Keytool

     Example: Java Keytool: generating key and certificate in a keystore keytool -keystore my_keystore -alias tescm -genkey -keyalg RSA.

Once you have the keystore, you can follow the instructions in Step 2 to configure SSL connector for the Client Manager. However, your certificate will not be trusted by web browser and user will be prompted to this effect. To set up a production grade server, you must request a well known certificate authority (CA) to sign your key/certificate.

2. Obtaining key and certificate from a trusted CA.

   There are many trusted CA's, such as AddTrust, Entrust, GeoTrust, RSA Data Security, Thawte, VISA, ValiCert, Verisign, beTRUSTed. Each CA has its own instructions which should be followed (look for JSSE section), but all will involve a step to generate a certificate signing request (CSR).

   Example: Java Keytool: generating CSR: keytool -certreq -alias tescm -keystore my_keystore -file mycsr.csr

3. Configure the SSL connector with the server key and certificate:

   In this section, you edit the web server configuration file with the key and certificate you obtained from previous section.

   • Shut down the Client Manager.

   • Copy your server key store to the config directory in Client Manager's installation directory.

   • Using a text editor to open the Jetty Web Server configuration file config/webserver.xml located in Client Manager installation directory.

     Note: Back up this file before editing it to ensure there is a good copy to fall back to.

   • Uncomment the segment of SSL connector as described in Step 2 of Demo.

     Replace the values of these elements by the values applicable to your certificate.

     "keystore"– Path to the key store mentioned in step b

     "password" – Password needed to open the key store

     "keyPassword" – Password needed to read the key, if it's different from the password of the key store.

   • (Optional) Obfuscate the passwords before storing them in the file so their secrecy is secured. See Obfuscating Passwords for SSL.

   • (Optional) Change the port number to be used with HTTPS protocol by modifying the value of the "Port" element. Default is 8443.

   • Save the file and start the Client Manager.

4. Testing HTTPS connection to Client Manager from Web browser.

   • Open a Web browser and enter the URL of TA Web Client with HTTPS protocol:

     Example: https://<hostname>:<portnumber>/client

   • Replace <hostname> by the actual DNS name or IP address of the Client Manager system. Replace <portnumber>by the actual port number of the SSL connector.

     Your browser is now communicating with the Client Manager via HTTPS protocol.

Configuring SSL Access for Active Directory

Follow these steps to connect to a Active Directory, SSL-enabled environment.

To configure SSL for Active Directory:

1. Shut down the Client Manager.

2. Download the CA certificate for the Active Directory server from CA Certificate server, or export the installed Certificate from browser. Then save the certificate into a file.

   For example:

   • Navigate to http://<CA_SERVER>/certsrv, and then click Download a CA certificate, certificate chain, or CRL.

   • Choose the certificate on the CA Certificate list.

   • Click DER from the Encoding method section.

   • Click Download CA Certificate.

   • Save the certificate, such as certnew.cer.

3. Build a trusted keystore for the CA certificate.

   Example: C:\>keytool -import -trustcacerts -keystore store.jks -alias <unique-name> -file certnew.cer
   
   -storepass password

4. Using a text editor, modify <CM_INSTALL>/config/clientmgr.props to include these three lines, then save clientmgr.props:

   Example: Security.SSL.enabled=Y Security.SSL.trustStore=c:\\<path>\\store.jks Security.SSL.trustStorePassword=password

5. (Optional) Obfuscate the passwords before storing them in the file so their secrecy is secured. See Obfuscating Passwords for SSL.

6. Restart the Client Manager.

Obfuscating Passwords for SSL

When configuring SSL, you can obfuscate the passwords before storing them in the file so their secrecy is secured.

To obfuscate passwords:

1. Open a command shell window and change directory to the lib directory under Client Manager's installation directory.

2. Issue this command:

   java -cp jetty-util-9.4.45.v20220203.jar org.eclipse.jetty.util.security.Password <user_name> <your_password>

   where <your_password> is the password to be obfuscated.

   Example: java -cp jetty-util-9.4.45.v20220203.jar org.eclipse.jetty.util.security.Password MarkusMuller tidalpassword

   This output of this command is:

   OBF:<string> 
   MD5:<string> 
   CRYPT:<string>

   Example: C:\Program Files\TIDAL\ClientManager\lib&gt;java -cp jetty-util-10.0.17.jar org.eclipse.jetty.util.security.Password MarkusMuller tidalpassword

   Example:
   OBF:1v9a9l9e3k171s3g1xme1rww1mnp1wld1xnm3s3m1jyr1ky61n43
   MD5:123bB45n678p91Q0111gV2YIO3D4At15
   CRYPT:emV9j6NMG3mF9

3. Copy the entire line that starts with "OBF:" (including OBF:) from the output of the command, and paste it into the value field of that password in the file.

4. Repeat step 1 to 3 for each of the other passwords.

Enabling TLS v1.3 Protocol in the Client Manager

This section provides the configuration required to enable the TLS v1.3 protocol in the Client Manager.

Note: Before enabling TLS v1.3 protocol in the Client Manager, make sure that the machine where the Client Manager is installed has Java 1.8 (Java 1.8.261 or higher) or Java 11.

To enable TLS v1.3 protocol in the Client Manager

1. Stop the Client Manager.

2. Open the Web server configuration file, config/webserver.xml, located in Client Manager installation directory using a text editor.

   Note: Back up this file before editing it.

3. Find the segment of SSL connector that looks like this. Uncomment the segment by removing "<!--" at the beginning and "-->" at the end. The configuration for enabling TLS v1.3 is highlighted in bold-style font.

<!--

<New id="sslContextFactory" class="org.eclipse.jetty.util.ssl.SslContextFactory">

<Set name="KeyStorePath">

<Property name="jetty.keystore" default="config/demo-keystore" />

</Set>

<Set name="KeyStorePassword">

<Property name="jetty.keystore.password" default="OBF:1vny1ym91x1b1z7e1vu91y0s1ri71y0y1vv11z7o1x1b1ym51vn4" />

</Set>

<Set name="KeyManagerPassword">

<Property name="jetty.keymanager.password" default="OBF:1vny1ym91x1b1z7e1vu91y0s1ri71y0y1vv11z7o1x1b1ym51vn4" />

</Set>

<Set name="TrustStorePath">

<Property name="jetty.truststore" default="config/demo-keystore" />

</Set>

<Set name="TrustStorePassword">

<Property name="jetty.truststore.password" default="OBF:1vny1ym91x1b1z7e1vu91y0s1ri71y0y1vv11z7o1x1b1ym51vn4" />

</Set>

<Set name="EndpointIdentificationAlgorithm"></Set>

<Set name="NeedClientAuth">

<Property name="jetty.ssl.needClientAuth" default="false" />

</Set>

<Set name="WantClientAuth">

<Property name="jetty.ssl.wantClientAuth" default="false" />

</Set>

<Set name="excludeProtocols">

<Array type="java.lang.String">

<Item>TLSv1</Item>

<Item>TLSv1.2</Item>

</Array>

</Set>

<Set name="IncludeProtocols">

<Array type="java.lang.String">

<Item>TLSv1.3</Item>

</Array>

</Set>

<Set name="IncludeCipherSuites">

<Array type="String">

<Item>TLS_AES_128_GCM_SHA256</Item>

</Array>

</Set>

</New>

<New id="sslHttpConfig" class="org.eclipse.jetty.server.HttpConfiguration">

<Arg>

<Ref refid="httpConfig" />

</Arg>

<Call name="addCustomizer">

<Arg>

<New class="org.eclipse.jetty.server.SecureRequestCustomizer" />

</Arg>

</Call>

</New>

<Call id="httpsConnector" name="addConnector">

<Arg>

<New class="org.eclipse.jetty.server.ServerConnector">

<Arg name="server">

<Ref refid="Server" />

</Arg>

<Arg name="factories">

<Array type="org.eclipse.jetty.server.ConnectionFactory">

<Item>

<New class="org.eclipse.jetty.server.SslConnectionFactory">

<Arg name="next">http/1.1</Arg>

<Arg name="sslContextFactory">

<Ref refid="sslContextFactory" />

</Arg>

</New>

</Item>

<Item>

<New class="org.eclipse.jetty.server.HttpConnectionFactory">

<Arg name="config">

<Ref refid="sslHttpConfig" />

</Arg>

</New>

</Item>

</Array>

</Arg>

<Set name="host">

<Property name="jetty.host" />

</Set>

<Set name="port">

<Property name="https.port" default="8443" />

</Set>

<Set name="idleTimeout">

<Property name="https.timeout" default="120000" />

</Set>

<Set name="soLingerTime">

<Property name="https.soLingerTime" default="-1" />

</Set>

</New>

</Arg>

</Call>

-->

Note: Make sure that you add one or more supported TLS v1.3 cipher suites to <IncludeCipherSuites> element. For a complete list of cipher suites, see the Improve the TLS cipher suite order section.

4. Save the file and start the Client Manager.

5. Add the JVMARGS property to the config\clientmgr.props file.

   JVMARGS=java -Djdk.tls.client.protocols="TLSv1.3,TLSv1.2"