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.
Tealeaf-pcapackage 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.
The following certificate and key files are created by the
/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.
After you generate the certificate and private key files, use the script
/usr/local/ctccap/bin/crlf.shto generate a single DOS-EOL ASCII file that is needed by the transport service.
For example, if your private key is in file
example.keyand your certificate is in file
example.crt, use the following command to generate a single DOS EOL file named
/usr/local/ctccap/bin/crlf.sh example.key example.crt > example.pem
- The resulting file contains a private key, so you must restrict its ownership and permissions by using the
- After you generate the certificate and private key files, use the script
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
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
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.
Using our sample
example.pem, you would change
css-cert.pemto produce the following results:
[Globals]section, insert the port number to which the transport service listens for SSL traffic. Insert the following code :
1967is 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.
DataDropis the first session agent in the pipeline that is configured to process the received SSL traffic.
- Add or edit the following directives in the
Log in to the Passive Capture configuration web UI and click the Delivery tab.
- In the Target Recipients section, click Add.
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
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:
and extends up to and including the following line:
- Copy and paste everything from (and including) the
BEGINline up to (and including) the
- 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.cfgfile in the installation directory on the machine that is hosting the transport service, locate the
To configure the socket to use SSL, enter or set the following code:
- Set the Server to be
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.
- 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
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
tealeaf.crt, or the
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
.p12 files can be found in
C:\ProgramData\IBM\Tealeaf\security\, and the
.pfx file in
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.
- 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 /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:
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.
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 (188.8.131.521+) the
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.
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.
Configure an all-in-one (Canister and Portal in one) server to receive data from a PCA over SSL by replacing
SSLPort=1966:DataDrop in the
[Globals] section in
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
SSLPort=1966:DataDrop in the
[Globals] section in
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:
- Remove the
UseSSL=truelines from any
[Socket]configurations, for example, in
UseSSL=truefrom the end of any inline socket configuration in
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.