Tealeaf 9.0.2 Fix Pack 6 adds consistent support for secure communication between Tealeaf services running on servers at a site. Site administrators are encouraged to take advantage of this feature to protect the Tealeaf environment and data from potential attackers.

The procedure in short:

1. Upgrade all Tealeaf servers including PCA servers to 9.0.2 Fix Pack 6 or later.
2. Create or acquire an X.509 certificate with associated private key and key password stored in PKCS#12 (PFX) format.The certificate may be created either with a Tealeaf tool or using your organization's own public key infrastructure. See [creating] below for details.
3. Import the certificate onto all Tealeaf servers using the supplied tools. See [importing] below for details.
4. Enable the new feature on all Tealeaf servers using the supplied tools. This will require stopping and restarting Tealeaf services. Tealeaf servers with the new feature enabled will not communicate with those servers which do not have it enabled so this step should be done as quickly as possible across the site.

An example of these steps using a self-signed certificate. Run this from <tealeaf>Tools in an elevated command prompt:

TLSTool.exe create -site "C:\temp\TCXcert.pfx" My725Password284

TLSTool.exe import "C:\temp\TCXcert.pfx" My725Password284

TLSTool.exe enable

The certificate must be imported and enabled on each server... it is not auto-propagated from any one machine.

Site Certificates

The site certificate can either be created as a self-signed certificate using a Tealeaf tool or created using your own organization's certificate infrastructure depending on your organization's security requirements. In either case the generated certificate and its associated private key password should be kept confidential with extreme care. In the hands of an attacker with access to the Tealeaf environment they permit interception of data and disruption of services.

Creating a Self-Signed Certificate

Tealeaf provides a "tlstool.exe" utility for creating a self-signed site certificate.

To create a certificate run the command on a Tealeaf server as follows:

• Open a command prompt in the Tealeaf \Tools\ folder
• Run the utility with this syntax:

TLSTool.exe" create -site path password

Where 'path' is the full file name to be created and 'password' is an ASCII character string for encrypting the private key.

• For example:

TLSTool.exe create -site "C:\temp\TCXcert.pfx" My725Password284

When the utility is successful it returns no response but creates the requested file.

Note: The certificate generated by this procedure expires one year later, so before that time it must be replaced.

Detecting whether Enable TLS is active

Registry setting

Installing SSL certificates and enabling TLS is a one-time task. After that the TLS security function can be toggled on-and-off by restarting all services with this registry flag enabled or disabled:

HKEY_LOCAL_MACHINE\SOFTWARE\WOW6432Node\TeaLeaf Technology

The EnableTLS flag is set to 1 when TLS is enabled and to 0 when it's disabled. All servers must have the same value in this registry key to inter-operate.

Data Servce log

The TLDataService log initialization messages indicate whether the Tealeaf system has TLS enabled: ? ("Port" vs "TLS Port"):

Example where TLS is not enabled:

2017-08-15T13:35:01??? Service.Start???? INFO??? Starting HTTP Server???
2017-08-15T13:35:01??? Service.Start???? INFO??? Port: 23000???
2017-08-15T13:35:02??? Service.Start???? INFO??? HTTP Server Started??

Example where TLS is enabled:

2017-08-15T13:31:27??? Service.Start???? INFO??? Starting HTTP Server???
2017-08-15T13:31:27??? Service.Start???? INFO??? TLS Port: 23000???
2017-08-15T13:31:27??? Service.Start???? INFO??? HTTP Server Started??

RTV note

RTV (RealiTea Viewer) does not require a registry or configuration flag to enable TLS. Because RTV may be configured to communicate with may Tealeaf systems each of which may have different and changing TLS settings RTV auto-negotiates with Tealeaf servers using a secure connection where it's needed.

Using a Signed Certificate

Tealeaf can also use an X.509 certificate created with your own organization's certificate infrastructure. The certificate must have a subject name of "IBM Tealeaf CX" and be suitable for use by both TLS 1.2 clients and servers. It must be stored in a single file in PKCS#12 format containing both the certificate and its associated private key. The private key must be protected by a password consisting entirely of ASCII characters.

Importing the Site certificate

This procedure must be performed on each Tealeaf server using the same certificate file that has been created or acquired in the above steps.

To import the site certificate onto a Windows Server system run the command below: (requires an elevated command prompt)

"<tealeaf>\Tools\TLSTool.exe" import path password

Where 'Path' is the certificate file name and 'password' is it's password. Example

TLSTool.exe import "C:\temp\TCXcert.pfx" My725Password284

There is no confirmation when the import is successful but if there is an error (incorrect password etc.) a warning will be returned. The Import process places these certificate files in a \security folder:

C:\ProgramData\IBM\Tealeaf\security
server.tls.xml
tealeaf.crt
tealeaf.p12

This is a? hidden folder. To view it's contents you may need to specify the full path name in the File Explorer address bar or access View/Options to enable "Show hidden files folders and drives".

Note: An upgraded Tealeaf system may have obsolete "TLSCert" and "TLSCertDER" folder settings (in the registry and TMS/Tealeaf/Global)... but these pre-date Fix Pack 6. They are obsolete and are no longer used. Formerly, these pointers specified a certificate file location <tealeaf>\TLS, which is no longer used. The new certificate location is always in a <Tealeaf>\security folder, and the utility places certificate files there.

To import the certificate onto a PCA (Linux) system:

1. Run Winscp to connect to the PCA system from the Windows Server system.
2. Transfer the certificate file to the PCA installation path <installdir>/etc. The default PCA installation directory is /usr/local/ctccap
3. Extract the .crt and .key file from the .p12 or .pfx file
4. Note also editing notes for ctc-conf.xml later in this guide.

Enabling Secure Communication (Windows servers)

Remember that Tealeaf servers with the new feature enabled will not communicate with those servers which do not have it enabled.

To enable secure communication on a Windows Server system:

• Stop all Tealeaf services.
  If the "Stop" batch file is used follow up with the services manager to ensure the Tealeaf management service Transport service etc..
  ?
• Run the TLSTool utility from the \Tool folder:
  TLSTool.exe enable
  ?
• Start all Tealeaf services

The 9.0.2 Fix Pack 6 upgrader disables TLS by default as the prior TLS security method is not compatible. This ensures inter-process communication is possible among upgraded servers until the new certificate is installed. To verify that TLS has been enabled by the TLSTool utility check the registry on each machine:

HKEY_LOCAL_MACHINE\SOFTWARE\WOW6432Node\TeaLeaf Technology

The EnableTLS flag is set to 1 when TLS is enabled and to 0 when it's disabled.

Rebooting Clearing SSL state Restarting Cryptographic Services

Some Tealeaf installation sites have reported that inter-process communication after enabling TLS does not work properly until each server is rebooted. This problem is not always seen and may be due to a local SSL cache problem. Clearing the SSL State may resolved the problem without requiring a reboot:

Press the Clear SSL State button on the Content tab in the Internet Options dialog box

This will remove all client authentication certificates from the Secure Sockets Layer (SSL) cache.

In an SSL session (i.e. using https://) when a server requests client validation the client certificate is saved in a cache. The certificate may remain in the cache until the computer is restarted. Clearing the SSL state removes all certificates from the cache and therefore initializes server-client validation.

Something else that may resolve this communication problem while avoiding a reboot:

Restarting the Cryptographic Services service

Enabling Secure Communication (Linux PCA)

If SSL delivery is required to 9.0.2 Fix Pak 6+ servers the PCA must be upgraded to 3682-24+ to maintain compatibility.

To enable secure communication on a PCA (Linux) system:

1. In the PCA WebConsole under Delivery Tab and under Target Recipients click "Add"
2. Configure the delivery peer with the "Secure" option checked:?
3. Press "OK" and "Save Changes"
4. In the ctc-conf.xml under <installdir>/etc/ctc-conf.xml add/edit the following fields:?
   (these fields belong in the "Delivery" section)
   ? ? ? ? <ServerCertPath></ServerCertPath>
   ? ? ? ? <ClientP12Path></ClientP12Path>
   ? ? ? ? <ClientP12Pass></ClientP12Pass>
   ? ? ? ? <ServerCertEnable>false</ServerCertEnable>
   ? ? ? ? <ClientCertEnable>false</ClientCertEnable>
5. ServerCertEnable should be set to true.?
   ClientCertEnable should be set to true.
   ServerCertPath should be the path to the extracted certificate from the .p12 or .pfx file from the Windows Server system.
   ClientP12Path should be the path to the .p12 or .pfx file.
   ClientP12Pass should be the Password to the .p12 or .pfx file configured above.
6. Restart PCA services by doing "tealeaf restart all" or "tealeaf stop all" followed by "tealeaf start all"

Additional notes:

• If the above fields are not present in the ctc-conf.xml you can find an example in ctc-conf-defaults.xml. This file is in <installdir>/etc/ and is replaced upon every upgrade.
• Just enabling the secure option in the WebConsole without enabling the above fields in the ctc-conf.xml will not work with TealeafCX that has Client Authentication enabled as these fields are new as of 9.0.2 Fix Pack 6.

To enable the secure communication on a PCA server WebConsole:

???????? 1. Update the runtime.conf to enable the web_console_security_crt_enable as below
??????????? ? ? ? vim /usr/local/ctccap/etc/runtime.conf and enable it like below
??????????? ? ? ? web_console_security_crt_enable=YES
???????? 2. Create a username and Password for PCA webconsole authentication client browser who doesn't present certificate need to authenticate if web_console_security_crt_enable is enabled
???????? 3. Run the below script and follow the steps to copy your certificates and to generate the p12
????????????? /usr/local/ctccap/etc/web-crt-gen.sh
???????? 4. In case of upgrade compare your current http.conf with httpd.conf.default and copy over the new additions to your httpd.conf
???????? 5. For a fresh install "tealeaf start" and for an upgrade "tealeaf restart httpd"

- For presenting certificates from client browser one has to copy the valid *.p12 and add to the browser.
- Steps vary from browser to browser
- Valid password is required to import the *.p12 in browser password is the one which is used while creating *.p12

PCA WebConsole Behavior while accessing webConsole from the browser.

????????? 1. If a client presents Valid certificate then user gains access to the PCA Web UI
????????? 2. If a client presents NO certificate then user gets prompt for user name and password
????????? 3. If a client presents WRONG certificate then connection simply fails.

Forcing TLS 1.0 on PCA:

User must add "<TLSVersion>0</TLSVersion>" under Delivery settings in the PCA ctc-conf.xml file and restart the PCA.

This option?is hidden and by default this value is "2" which specifies TLS 1.2. Value of "0" is for TLS 1.0 and "1" is for TLS 1.1

Disabling Secure Communication

Remember that Tealeaf servers with the new feature enabled will not communicate with those servers which do not have it enabled.

To disable secure communication on a Windows Server system:

1. Stop all Tealeaf services
2. Run "C:\Program Files (x86)\IBM\IBM Tealeaf CX\Tools\TLSTool.exe" disable
3. Start all Tealeaf services

To disable secure communication on a PCA (Linux) system:

1. Set the following fields in the ctc-conf.xml?from true to false:
   ? ? ? ? <ServerCertEnable>false</ServerCertEnable>