Set up the transport service for SSL encryption

To encrypt the communication between the Passive Capture host machine and the Tealeaf transport service, you must obtain an SSL certificate. Then configure the Passive Capture software and the transport service to use it.

The certificate must be 2048-bit private key.
The certificate is installed on both the PCA and the transport service machine. The PCA requires the certificate for startup, and the transport service uses the certificate for managing secure connections with the PCA.
Note: Transmitting through SSL between the PCA and the transport service requires more processing and can impact overall throughput.

Obtain the SSL certificate. If you create your own self-signed certificate, you must create a 2048-bit private key.
1. The Tealeaf-pca package creates a self-signed certificate for you to use when you configure SSL encryption of the network communication between the Passive Capture host machine and the transport service . This self-signed certificate contains the host name of the host machine at the time of the package installation.
2. The following certificate and key files are created by the Tealeaf-pca package:
  - /usr/local/ctccap/etc/tealeaf-tts.crt (certificate file)
  - /usr/local/ctccap/etc/tealeaf-tts.key (key file)
  - /usr/local/ctccap/etc/tealeaf-tts.pem (combined certificate and key file in DOS EOL)
You can choose to use the above PEM file or create your own.
1. After you generate the certificate and private key files, use the script /usr/local/ctccap/bin/crlf.sh to generate a single DOS-EOL ASCII file that is needed by the transport service.
  
  For example, if your private key is in file example.key and your certificate is in file example.crt, use the following command to generate a single DOS EOL file named example.pem.
```
/usr/local/ctccap/bin/crlf.sh example.key example.crt > example.pem
```
2. The resulting file contains a private key, so you must restrict its ownership and permissions by using the chmod and chown commands.
Transfer the single DOS EOL PEM file to the machine that is running the transport service. Ideally, you must restrict its access to just the transport service.

Note: The certificate must be installed on the root installation directory.
If required, you can use the Archive Reader to verify that the certificate is valid and usable.
On the transport service server, edit your TealeafCaptureSocket.cfg file.

You can also perform configuration changes through the Pipeline Editor in TMS, which provides centralized versioning and assignment of configuration files. Edit the raw transport service configuration file and insert the values in the [Globals] section.
1. Add or edit the following directives in the [Globals] section to the path name of the PEM file. If the files are not in the installation directory, then specify the full path to the files.
```
CertificateFile=css-cert.pem
PrivateKeyFile=css-cert.pem
```
2. Using our sample example.pem, you would change css-cert.pem to produce the following results:
```
CertificateFile=example.pem
PrivateKeyFile=example.pem
```
3. In the [Globals] section, insert the port number to which the transport service listens for SSL traffic. Insert the following code :
```
SSLPort=1967:DataDrop
```
  - 1967 is the port number to which the transport service listens for SSL traffic. This value is the default value. You can change it, as needed.
    Note: This port number must not be used by any other pipeline or component to listen for traffic.
  - DataDrop is the first session agent in the pipeline that is configured to process the received SSL traffic.
Log in to the Passive Capture configuration web UI and click the Delivery tab.
1. In the Target Recipients section, click Add.
2. The Add Recipient for Hit Delivery page is displayed. Enter the host address and port in the corresponding fields, select the Secure check box, and then click OK.
  
  Note: The entered port must match the SSL listening port on the transport service. The default for SSL transport is 1967.
The Add Certificate for Secure Delivery page is displayed. Paste in the certificate, and click OK to save the changes. The certificate is the piece of ASCII text that begins with the following line:
```
-----BEGIN CERTIFICATE-----
 
```
and extends up to and including the following line:
```
-----END CERTIFICATE-----
```
Copy and paste everything from (and including) the BEGIN line up to (and including) the END line.
Restart the PCA.
Restart the transport service.

Test the SSL certificate used by the transport service

Before you deploy the SSL certificate to the machine that is hosting the Tealeaf transport service, verify that the certificate is valid and usable using the archive reader.

Leave the SSL certificate installed on the PCA.
In the ArchiveReader.cfg file in the installation directory on the machine that is hosting the transport service, locate the [Socket] section.
To configure the socket to use SSL, enter or set the following code:
```
USESSL=True
```
Set the Server to be localhost.
Configure the following values to file name of the certificate that is installed in the root installation directory. Remove the hash mark (#) before the configuration line to enable it.
```
CertificateFile=css-cert.pem
PrivateKeyFile=css-cert.pem
```
Save the file.
Use the archive reader to submit hits to the transport service.
In the TMS Pipeline Status tab, verify that hits are being captured and processed by the appropriate pipeline.
If hits are being captured and processed, the SSL certificate is working properly.
You can now apply the configuration changes to the [Globals] section of the TealeafCaptureSocket.cfg.

PCA configuration

If the connection between the Tealeaf PCA and the downstream HBR or Canister must be secured with SSL the PCA must be upgraded to version 3741-28 or above.

Copy the certificate pair to the PCA

Copy either the TCXcert.pfx and tealeaf.crt, or the tealeaf.p12 and tealeaf.crt and files generated on the Windows servers using TLSTool.exe to the PCA. The usual location is /usr/local/ctccap/etc/. On the Windows server, the .crt and .p12 files can be found in C:\ProgramData\IBM\Tealeaf\security\, and the .pfx file in \Tools\.

Configure a secure delivery connection through the PCA web console

Through the PCA web console

Click on the Delivery tab, create a secure delivery connection to the HBR or Canister and save the change.
1. If an existing non-secure connection exists, delete it first, then create a secure connection.
Remaining in the Delivery tab, select the Use SSL box to enable the secure delivery of statistics hits, once configured for SSL, the receiving transport service will no longer accept non-SSL traffic.

Edit the `ctc-conf.xml` file

Edit /usr/local/ctccap/etc/ctc-conf.xml and add the following lines to the section if they are not already present:

Alternatively, use the .pfx file for the field rather than the .p12 file. The must be the .crt file. In both cases, the password used to generate the .pfx ("teapot" in this example) is required in the field.

A complete example of a section of ctc-conf.xml:

Restart capture

After saving the ctc-conf.xml file, restart capture. If using the PCA web console, you will be warned that "the configuration was modified" because you edited the file directly. Click "Revert to Modified" to retain your manual changes.

HBR/Canister configuration

To secure the Transport Service Pipeline using SSL, two directives are used. SSLPort=1966:DataDrop is used in the [Globals] section at the beginning of the pipeline in place of Port=1966:DataDrop to specify that the incoming connection. For exmaple, from the PCA, or from an HBR, if a Canister server is expected to be secured with SSL. Any port can be used, including the default of 1966, but must match the configuration specified at the other end of the connection. UseSSL=true is a property of the Socket session agent and controls whether the output of the socket is secured with SSL. This directive is used to secure the output of HBR child pipelines and the statistics pipeline.

Note: In FP6 and later (9.0.2.1351+) the CertificateFile and PrivateKeyFile directives are ignored. These may still be present in the TeaLeafCaptureSocket.cfg file if the environment has been upgraded from an earlier version of Tealeaf. They can be removed. The Transport Service will instead use the Windows registry to locate the same SSL certificate pair used to secure inter-process communications, and use those. These are the same certificates that are imported on the PCA.

HKEY_LOCAL_MACHINE\SOFTWARE\Wow6432Node\TeaLeaf Technology\TLSCert HKEY_LOCAL_MACHINE\SOFTWARE\Wow6432Node\TeaLeaf Technology\TLSCertP12

This means that even if inter-process SSL is not in use, the SSL certificates must be created and imported on all servers that are going to be using a secure pipeline.

Examples

Configure an all-in-one (Canister and Portal in one) server to receive data from a PCA over SSL by replacing Port=1966:DataDrop with SSLPort=1966:DataDrop in the [Globals] section in TeaLeafCaptureSocket.cfg.

Configure an HBR child pipeline in HBR_Pipeline1.cfg to send traffic to a canister (TEATESTS03) over SSL by adding the UseSSL=true line to the configuration of the [Socket] session agent:

Configure a canister server (TEATESTS03) to listen for SSL traffic arriving from an HBR by replacing Port=1966:DataDrop with SSLPort=1966:DataDrop in the [Globals] section in TeaLeafCaptureSocket.cfg.

Configure the statistics hits from a canister to route to a Portal server over SSL by adding UseSSL=true to the end of line, right after the Socket port.

This kind of inline configuration of a socket can be used to route session data as well as statistics hits.

Note: The Tealeaf Transport Service needs to be restarted for any of these changes to take effect.

Disabling secure transport

To disable secure transport in the pipeline, revert the changes described above. Note that this does not disable SSL for interprocess communication (between Tealeaf components), only for traffic in the pipeline.

Revert changes on the Windows servers:

Replace SSPort=1966:DataDrop with Port=1966:DataDrop in TeaLeafCaptureSocket.cfg
Remove the UseSSL=true lines from any [Socket] configurations, for example, in HBR_Pipeline1.cfg
Remove UseSSL=true from the end of any inline socket configuration in [SessionRouter]

On the PCA, the configuration changes to ctc-conf.xml can be left in place, but the secure connection to the delivery peers (HBRs or Canisters) must be deleted in the Delivery tab, and recreated as non-secure connections.

If secure delivery of statistics hits has been enabled, this should also be disabled from the Delivery tab, since the receiving transport service no longer accepts SSL traffic.

Note: however that leaving this enabled will not prevent session traffic from being delivered successfully over the new non-SSL connection.

Test the SSL certificate used by the transport service