Learn how to create and import the SSL certificates required to enable secure inter-process communication in Tealeaf 9.0.2 FP6+.

Overview

Note: the terms "SSL" and "TLS" are used interchangeably in this document, even though the standard used is always TLS 1.2.

Tealeaf 9.0.2 Fix Pack 6 (9.0.2.1351) and above supports the use of a new SSL certificate based mechanism for securing all inter-process communication between the Tealeaf servers. This is important in a distributed environment with multiple servers, as the components of Tealeaf communicate with each other over the network, using a variety of ports. Before FP6 some of these communication channels were already secure, but the changes made in FP6 introduce one overarching mechanism to secure all inter-process communication, superseding previous ad hoc security measures. Implementing this new mechanism is referred to below as "Enabling TLS" and involves the following steps: Generating an SSL certificate pair Copying this certificate pair to all Tealeaf servers Importing the certificate pair Enabling TLS (telling Tealeaf to use the new certificate pair) Restarting Tealeaf services

Note: enabling TLS is optional. If you do not enable TLS then Tealeaf will continue to operate using the legacy inter-process communication mechanisms of earlier fix packs. However, creating, copying and importing the certificate pair on the Windows servers is recommended, even if TLS is not then enabled. This avoids a minor issue with PCA status checks (PCAStatus.exe) not working, as the code checks for the existence of these certificates, even if they are not used, and some spurious errors in the event log on the HBR servers. See the "Notes" section below for details.

Note: this document does not cover securing the pipeline through which captured session data flows within Tealeaf. This data can also be secured using the same certificate pair generated for securing inter-process communication.

Prerequisites

Network ports

No new network ports are used after enabling TLS; instead the standard ports are used securely. The only potential exception is the Tealeaf Data Service. The Data Service uses port 23000 by default but an option to use port 23443 instead was introduced in an earlier fix pack. At the time this option offered additional security, but this is no longer necessary with the introduction of FP6. If port 23443 is in use, the configuration should be updated to use port 23000 instead, before trying to enable TLS in FP6.

Windows registry—TLS 1.2 support in Windows 2008 R2

For TLS security to work, Windows itself must support TLS 1.2. Windows 2012 and 2012 R2 support TLS 1.2 by default. In Windows 2008 R2 the following registry entries must be present.

HKLM:\SYSTEM\CurrentControlSet\Control\SecurityProviders\SCHANNEL\SendTrustedIssuerList = 0 HKLM:\SYSTEM\CurrentControlSet\Control\SecurityProviders\SCHANNEL\Protocols\TLS 1.2\Server\DisabledByDefault = 0 HKLM:\SYSTEM\CurrentControlSet\Control\SecurityProviders\SCHANNEL\Protocols\TLS 1.2\Server\Enabled = 1

Note: you will need to reboot for these changes to take effect.

Windows registry—Tealeaf configuration

If the Windows registry contains an existing Tealeaf TLS configuration entry, it must be set to disabled (0). An "EnableTLS" entry may be present if the customer configured some of the optional security features first introduced in FP2.

HKLM:\SOFTWARE\Wow6432Node\TeaLeaf Technology\EnableTLS = 0 If the above "EnableTLS" option is present it must be set to 0.

Generate an SSL certificate pair

Interprocess security works by ensuring that all servers have an identical copy of the SSL key pair, so that all traffic between them can be encrypted for transmission and decrypted on arrival. The certificate pair is initially generated in PFX format. This creates a single password protected file containing the public and private keys forming the key pair. Some of the Tealeaf documentation refers to the key pair as a whole as "the certificate". When the PFX is imported on a server the password needs to be provided, and the key pair is then imported into a hidden directory, converted into two formats: a .cer and a .p12 file.

Note: a self-signed certificate pair can be generated by the TLSTool.exe utility included with FP6, a process described below.

1. Open a cmd prompt.
2. cd to <Tealeaf Installation Directory>\Tools\
3. TLSTool.exe create -site TCXcert.pfx <password>

Note: the password must be composed only of standard ASCII characters and no spaces, for example TLSTool.exe create -site TCXcert.pfx MyPassW0RD784.

In the example above the TCXcert.pfx file will be created in <Tealeaf Installation Directory>\Tools\. Copy this PFX file to all other Windows servers running Tealeaf. For convenience, copy it to <Tealeaf Installation Directory>\Tools\ on those servers too, to make it easier to import later.

Import the SSL certificate pair

The PFX file created in the previous step must now be imported, on all Windows servers in the Tealeaf environment, including the server on which it was created. To import the PFX:

1. Open a cmd prompt.
2. cd to <Tealeaf Installation Directory>\Tools\
3. TLSTool.exe import TCXcert.pfx <password>

The command above assumes you created the certificate pair naming the file TCXcert.pfx as in the example above.

For the password, enter the password used when creating the certificate pair. During import the key pair is extracted from the PFX file and saved in a hidden directory C:\ProgramData\IBM\Tealeaf\security\. Paste this path into the address bar in Windows Explorer to access the directory. Two files are created: tealeaf.crt and tealeaf.p12. Both contain the certificate and key, but are in different formats.

Enable TLS

TLS can now be enabled, as a valid certificate pair is present on all servers. On all Windows servers in the Tealeaf environment, enable TLS using the TLSTool.exe utility. TLS cannot be selectively enabled: if enabled at all, it must be enabled on all Windows servers.

1. Open a cmd prompt.
2. cd to <Tealeaf Installation Directory>\Tools\
3. TLSTool.exe enable
4. Restart all Tealeaf services

NOTE: when restarting services, do not rely on the Stop All Tealeaf Services Start menu shortcut, which does not in fact stop all services. Ensure all services whose name begins with "TeaLeaf" are restarted using the Windows Services snap-in. Also restart IIS, which you can do using the iisreset command from the cmd prompt. Alternatively, just reboot.

You will notice that after enabling TLS the registry entry is set to 1:

HKLM:\SOFTWARE\Wow6432Node\TeaLeaf Technology\EnableTLS = 1

In addition, a third file is now created in C:\ProgramData\IBM\Tealeaf\security\. server.tls.xml (configuration information)

Generate the status report with TLS enabled

To generate the Tealeaf status report while TLS is enabled, you must add or change your registry settings.

• HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\.NETFramework\v2.0.50727
• • "SchUseStrongCrypto": 00000001
  • "SystemDefaultTlsVersions": 00000001

• HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\.NETFramework\v4.0.30319
  • "SchUseStrongCrypto": 00000001
  • "SystemDefaultTlsVersions": 00000001

• HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows\CurrentVersion\Internet Settings\WinHttp\
  • DefaultSecureProtocols = (DWORD): 0xAA0
  • Check if AA0 reflected successfully, if not then just try AA0 and save.

• HKEY_LOCAL_MACHINE\SOFTWARE\Wow6432Node\Microsoft\Windows\CurrentVersion\Internet Settings\WinHttp\
  • DefaultSecureProtocols = (DWORD): 0xAA0
  • Check if AA0 reflected successfully, if not then just try AA0 and save.

• HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Control\SecurityProviders\SCHANNEL\Protocols\TLS 1.2\Client
  • "DisabledByDefault": 00000000
  • "Enabled": 00000001

• HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Control\SecurityProviders\SCHANNEL\Protocols\TLS 1.2\Server
  • "DisabledByDefault": 00000000
  • "Enabled": 00000001

Restart your Windows machine and test TealeafStatus -verbose from your command prompt. Your issue should be resolved.

NOTE: These settings need to be enabled for any server that shows TealeafStatus.

Secure the pipeline

The certificate pair, once imported using the steps above, can also be used to encrypt Pipeline traffic: the captured session data flowing between the Tealeaf servers. These Pipeline connections are not considered to be inter-process connections, and enabling TLS will not cause them to be encrypted. They must be secured separately by modifying the pipeline configuring files on the Tealeaf servers.

Inter-process communication and Pipeline connections between the servers both use the same certificate pair, but are independent: inter-process communications can be secured and pipeline data left unencrypted, and vice versa. Although a certificate pair must have been imported, TLS does not have to be enabled for the pipeline to be secured using these certificates.

Troubleshoot

If functions such as session search or TMS do not work correctly after enabling TLS, first double check that TLS has been enabled on all servers by checking for the registry key. It is set to 1 when enabled.

HKLM:\SOFTWARE\Wow6432Node\TeaLeaf Technology\EnableTLS = 1

Next, double check that the certificate pair is present in the hidden directory, on all servers. If possible, reboot all Windows servers to ensure the SSL cache is cleared. If a reboot is not possible, try the following:

• Click the "Clear SSL State" button on the "Content" tab in the Internet Options dialogue box, accessible from the Control Panel or from IE.
• Restart the "Cryptographic Services" Windows service

If this still does not resolve the problem, disable TLS and restart the Tealeaf services once more to return the environment to its earlier state and hopefully restore normal functioning whilst giving time to investigate the problem further by examining the logs. To disable TLS either set the registry key above to 0, or:

1. Open a cmd prompt.
2. cd to <Tealeaf Installation Directory>\Tools\
3. TLSTool.exe disable

Data Service Log

The Data Service log shows whether TLS is currently in effect, which may be useful during troubleshooting.

<Tealeaf Installation Directory>\Logs\TLDataService_<date>.log

The service initialization messages, shortly after service startup, indicate whether the service is using "Port" or "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

Notes

Minimize disruption

The certificate pair creation and import steps do not have any effect on running processes and can be performed on all Tealeaf servers without disruption. Only the import step and the associated service restart will affect availability. Apply the change to HBRs and Canisters one at a time, to prevent data loss. Once all servers have had TLS enabled, validate that data is being captured and components such as TMS and searches work as expected.

Known issues when the certificate pair is not present

The PortalStatus job which checks the status of all Tealeaf servers and generates the Tealeaf Status report invokes PCAStatus.exe on the Portal server to check the status of the PCA server(s). If access to the PCA web console is secured with HTTPS, this call will fail if no certificate pair exists on the Portal server. The certificate pair is not actually used to make the connection, but the certificate files must be present in the expected location.

If the HKLM:\SOFTWARE\Wow6432Node\TeaLeaf Technology\security\TLSCertPassword key is not present in the Windows registry on the HBR server(s) a spurious error is thrown in the Windows application event log:

TeaLeaf Rules: unable to open key: The system cannot find the file specified while executing "registry get $path $key".
This error does not impact the operation of the HBR. Creating the missing registry key as a string, with a dummy value (e.g. "Password123") resolves the problem.

Changes to TMS

Once TLS is enabled, the Tealeaf Management Service (TMS) will use the certificate pair to encrypt communication between TMS instances, rather than its own legacy certificate.

PCA

The PCA is not affected by enabling TLS for inter-process communication. However, if the Pipeline connection between the PCA and the downstream Canisters or HBRs needs to be secured then the PCA must be upgraded to version 3682-24 or above, and the certificate pair must be copied to the PCA and imported there.

NOTE: in previous versions a certificate pair was generated on the PCA and then copied to the Windows server downstream to secure the Pipeline. That is no longer the case in FP6, where the PCA uses the same certificate pair as the Windows servers.

RealiTea Viewer (RTV)

RTV cannot connect to a Tealeaf environment with TLS for inter-process communication enabled unless it can access a copy of the certificate pair. Auto-configuration works: the server is visible and RTV can automatically configure itself. However, without the key pair it cannot connect to the Search Server. Trying to search in RTV shows the search server as "unavailable".

This happens because TLSTool.exe is not present on a machine where only RTV has been installed. It needs to be copied from one of the Tealeaf servers, along with the associated openssl.exe file.

Copy these files from any Tealeaf server to the client with RTV installed. Ensure the Tealeaf environment is the same version as RTV.

Tealeaf Installation Directory\Tools\TLSTool.exe
Tealeaf Installation Directory\Tools\openssl.exe
Tealeaf Installation Directory\Tools\TCXcert.pfx

TheTCXcert.pfxkey pair file may be called something else, depending on what filename was specified when creating it with TLSTool.exe create

With these files in place on the RTV machine (in the same path), run the import command:

TLSTool.exe import TCXcert.pfx password

There is no need to run TLSTool.exe enablefor RTV to work.

RTV does not require any other registry or configuration changes to use TLS as it auto-negotiates the connection to the Tealeaf Servers.

Use a Signed Certificate

Tealeaf can use an X.509 certificate pair created with your own organization's certificate infrastructure, rather than its own self-signed certificate. 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. Provided the above requirements are met the import and enable steps for enabling TLS are the same as those described above.