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.
- 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. -
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)
-
- The
-
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.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 fileexample.crt
, use the following command to generate a single DOS EOL file namedexample.pem
./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
chmod
andchown
commands.
-
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
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.-
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
-
Using our sample
example.pem
, you would changecss-cert.pem
to produce the following results:CertificateFile=example.pem PrivateKeyFile=example.pem
-
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.
-
-
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
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) theEND
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 theTealeafCaptureSocket.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.
- 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
withPort=1966:DataDrop
inTeaLeafCaptureSocket.cfg
- Remove the
UseSSL=true
lines from any[Socket]
configurations, for example, inHBR_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.