Install the ExtraHop session key forwarder on a Windows server
Perfect Forward Secrecy (PFS) is a property of secure communication protocols that enables short-term, completely private session key exchanges between clients and servers. ExtraHop offers session key forwarding software that can send session keys to the ExtraHop system for SSL/TLS decryption. Communication between the key forwarder and the sensor is encrypted with TLS 1.2 or TLS 1.3, and there is no limit to the number of session keys that the ExtraHop system can receive.
Note: | For more information about how the traffic feed or changes to the configuration might affect sensors, review the desync and capture drop rate metrics in the System Health dashboard. |
You must configure the ExtraHop system for session key forwarding and then install the forwarder software on the Windows and Linux servers that have the SSL/TLS traffic that you want to decrypt.
Before you begin- Read about SSL/TLS decryption and review the list of supported cipher suites.
- Make sure that the ExtraHop system is licensed for SSL Decryption and SSL Shared Secrets.
- Make sure that your server environment is supported by the ExtraHop session key
forwarder software:
- Microsoft Secure Channel (Schannel) security package
- Java SSL/TLS (Java versions 8 through 17). Do not upgrade to this version of the session key forwarder if you are currently monitoring Java 6 or Java 7 environments. Version 7.9 of the session key forwarder supports Java 6 and Java 7, and is compatible with the latest ExtraHop firmware.
- Dynamically linked OpenSSL (1.0.x and 1.1.x) libraries. OpenSSL is only supported on Linux systems with kernel versions 4.4 and later and RHEL 7.6 and later.
- Make sure the server where you install the session key forwarder trusts the SSL certificate of the ExtraHop sensor.
- Make sure your firewall rules allow connections to be initiated by the monitored server to TCP port 4873 on the sensor.
Important: | The ExtraHop system cannot decrypt TLS-encrypted TDS traffic through session key forwarding. Instead, you can upload an RSA private key. |
- Install the session key forwarder on one or more Windows 2016 or Windows 2019 servers that are running SSL-based services with the native Windows SSL framework. OpenSSL on Windows is not currently supported.
Important: | After you install the session key forwarder software, applications that
include SSL-enabled features, such as EDR agents and Windows Store applications, might fail to
function correctly. Validate the compatibility of the session key forwarder in your Windows test environment before deploying in your production environment. |
Enable the SSL session key receiver service
You must enable the session key receiver service on the ExtraHop system before the system can receive and decrypt session keys from the session key forwarder. By default, this service is disabled.
- Log in to the Administration settings on the ExtraHop system through https://<extrahop-hostname-or-IP-address>/admin.
- In the Appliance Settings section, click Services.
- Select the SSL Session Key Receiver checkbox.
- Click Save.
Add a global port to protocol mapping
Add each protocol for the traffic that you want to decrypt with your session key forwarders.
View connected session key forwarders
You can view recently connected session key forwarders after you install the session key forwarder on your server and enable the SSL session key receiver service on the ExtraHop system. Note that this page only displays session key forwarders that have connected over the last few minutes, not all session key forwarders that are currently connected.
- Log in to the Administration settings on the ExtraHop system through https://<extrahop-hostname-or-IP-address>/admin.
- In the System Configuration section, click Capture.
- Click SSL Shared Secrets.
Validate session key forwarding
Perform these steps to make sure that the installation was successful and the session key forwarder is forwarding the keys to the ExtraHop system.
- Log in to the Windows server.
-
Open the Services MMC snap-in. Ensure both services, "ExtraHop Session Key Forwarder"
and ExtraHop Registry Service" show the status as "Running".
-
If either service is not running, troubleshoot the issue
by completing the following steps.
- Open the Event Viewer MMC snap-in and navigate to Windows Logs > Application.
- Locate the most recent entries for the ExtraHopAgent source. Common reasons for failure and their associated error messages are listed in the Troubleshoot common error messages section below.
- If the Services and Event Viewer snap-in do not indicate any issues, apply a workload to the monitored services and go to the ExtraHop system to verify that secret-based decryption is working.
![](/images/9.7/pfs-metric-counter.png)
Key receiver system health metrics
The ExtraHop system provides key receiver metrics that you can add to a dashboard chart to monitor key receiver health and functionality.
To view a list of available metrics, click the System
Settings icon and
then click Metric Catalog. Type key
receiver in the filter field to display all available key receiver
metrics.
![](/images/9.7/key-receiver-health-metrics.png)
Tip: | To learn how to create a new dashboard chart, see Edit a chart with the Metric Explorer. |
Integrate the forwarder with the Java-based SSL application
As an example, Apache Tomcat supports customization of Java options in the Tomcat service manager properties. In the following example, adding the -javaagent option to the Java Options section causes the Java runtime to share SSL session secrets with the key forwarder process, which then relays the secrets to the ExtraHop system so that the secrets can be decrypted.
-javaagent:C:\Program Files\ExtraHop\exagent.jar
![](/images/9.7/pfs-windows-apache.png)
Note: | If your server is running Java 17 or later, you must also
allow the sun.security.ssl module to access all unnamed modules with the
--add-opens option, as shown in the following
example:--add-opens java.base/sun.security.ssl=ALL-UNNAMED |
Appendix
Troubleshoot common error messages
Error messages are saved to log files in the following locations, where TMP is the value of your TMP environment variable:
- TMP\ExtraHopSessionKeyForwarderSetup.log
- TMP\ExtraHopSessionKeyForwarderMsi.log
The following table shows common error messages that you can troubleshoot. If you see a different error or the proposed solution does not resolve your issue, contact ExtraHop Support.
Message | Cause | Solution |
---|---|---|
connect: dial tcp <IP address>:4873: connectex: A connection attempt failed because the connected party did not properly respond after a period of time, or established connection failed because connected host has failed to respond | The monitored server cannot route any traffic to the sensor. | Ensure firewall rules allow connections to be initiated by the monitored server to TCP port 4873 on the sensor. |
connect: dial tcp <IP address>:4873: connectex: No connection could be made because the target machine actively refused it | The monitored server can route traffic to the sensor, but the receiving process is not listening. | Ensure that the sensor is licensed for both the SSL Decryption and SSL Shared Secrets features. |
connect: x509: certificate signed by unknown authority | The monitored server is not able to chain up the sensor certificate to a trusted Certificate Authority (CA). | Ensure that the Windows certificate store for the computer account has trusted root certificate authorities that establish a chain of trust for the sensor. |
connect: x509: cannot validate certificate for <IP address> because it doesn't contain any IP SANs | An IP address was supplied as the EDA_HOSTNAME parameter when installing the forwarder, but the SSL certificate presented by the sensor does not include an IP address as a Subject Alternate Name (SAN). | Select from the following three solutions.
|
|
||
|
Uninstall the software
If you no longer want the ExtraHop session key forwarder software installed, or if any of the original installation parameters have changed (sensor hostname or certificate) and you need to reinstall the software with new parameters, do the following:
Important: | You must restart the server for the configuration changes to take effect. |
- Log in to the Windows server.
- (Optional): If you integrated the session key forwarder with Apache Tomcat, remove the -javaagent:C:\Program Files\ExtraHop\exagent.jar entry from Tomcat to prevent the web service from stopping.
-
Choose one of the following options to remove the software:
- Open the Control Panel and click Uninstall a program. Select ExtraHop Session Key Forwarder from the list and then click Uninstall.
-
Open a PowerShell command prompt and run the following commands to remove the software and associated registry entries:
-
$app=Get-WMIObject -class win32_product | where-object {$_.name -eq "ExtraHop Session Key Forwarder"}
-
$app.Uninstall()
-
- Click Yes to confirm.
- After the software is removed, click Yes to restart the system
Installation parameters
You can specify the following MSI parameters:
MSI Installation Parameter | EDA_HOSTNAME |
Registry Entry | HKEY_LOCAL_MACHINE\SOFTWARE\ExtraHop\EDAHost |
Description | The sensor hostname or IP address where SSL session keys will be sent. This parameter is required. |
MSI Installation Parameter | EDA_CERTIFICATEPATH |
Registry Entry | N/A |
Description |
The monitored server must trust the issuer of the sensor SSL certificate through the server's certificate store. In some environments, the sensor works with the self-signed certificate that the ExtraHop firmware generates upon installation. In this case, the certificate must be added to the certificate store. The EDA_CERTIFICATEPATH parameter enables a file-based PEM-encoded certificate to be imported into the Windows certificate store at installation. If the parameter is not specified at installation and a self-signed or other CA certificate must be placed into the certificate store manually, the administrator must import the certificate to Certificates (Computer Account) > Trusted Root Certification Authorities on the monitored system. This parameter is optional if the monitored server was previously configured to trust the SSL certificate of the sensor through the Windows certificate store. |
MSI Installation Parameter | SERVERNAMEOVERRIDE |
Registry Entry | HKEY_LOCAL_MACHINE\SOFTWARE\ExtraHop\ServerNameOverride |
Description |
If there is a mismatch between the sensor hostname that the forwarder knows (EDA_HOSTNAME) and the common name (CN) that is presented in the SSL certificate of the sensor, then the forwarder must be configured with the correct CN. This parameter is optional. We recommend that you regenerate the SSL self-signed certificate based on the hostname from the SSL Certificate section of the Administration settings instead of specifying this parameter. |
MSI Installation Parameter | TCPLISTENPORT |
Registry Entry | HKEY_LOCAL_MACHINE\SOFTWARE\ExtraHop\TCPListenPort |
Description | The key forwarder receives session keys locally from the Java environment
through a TCP listener on localhost (127.0.0.1) and the port specified in the
TCPListenPort entry. We recommended that this port remain set to
the default of 598. This parameter is optional. |
Supported SSL/TLS cipher suites
The ExtraHop system can decrypt SSL/TLS traffic that has been encrypted with PFS or RSA cipher suites. All supported cipher suites can be decrypted by installing the session key forwarder on a server and configuring the ExtraHop system.
Cipher suites for RSA can also decrypt the traffic with a certificate and private key—with or without session key forwarding.
Decryption methods
- PFS + GPP: the ExtraHop system can decrypt these cipher suites with session key forwarding and global protocol to port mapping
- PFS + Cert: the ExtraHop system can decrypt these cipher suites with session key forwarding and the certificate and private key
- RSA + Cert: the ExtraHop system can decrypt these cipher suites without session key forwarding as long as you have uploaded the certificate and private key
Hex Value | Name (IANA) | Name (OpenSSL) | Supported Decryption |
---|---|---|---|
0x04 | TLS_RSA_WITH_RC4_128_MD5 | RC4-MD5 | PFS + GPP PFS + Cert RSA + Cert |
0x05 | TLS_RSA_WITH_RC4_128_SHA | RC4-SHA | PFS + GPP PFS + Cert RSA + Cert |
0x0A | TLS_RSA_WITH_3DES_EDE_CBC_SHA | DES-CBC3-SHA | PFS + GPP PFS + Cert RSA + Cert |
0x16 | TLS_DHE_RSA_WITH_3DES_EDE_CBC_SHA | EDH-RSA-DES-CBC3-SHA | PFS + GPP PFS + Cert |
0x2F | TLS_RSA_WITH_AES_128_CBC_SHA | AES128-SHA | PFS + GPP PFS + Cert RSA + Cert |
0x33 | TLS_DHE_RSA_WITH_AES_128_CBC_SHA | DHE-RSA-AES128-SHA | PFS + GPP PFS + Cert |
0x35 | TLS_RSA_WITH_AES_256_CBC_SHA | AES256-SHA | PFS + GPP PFS + Cert RSA + Cert |
0x39 | TLS_DHE_RSA_WITH_AES_256_CBC_SHA | DHE-RSA-AES256-SHA | PFS + GPP PFS + Cert |
0x3C | TLS_RSA_WITH_AES_128_CBC_SHA256 | AES128-SHA256 | PFS + GPP PFS + Cert RSA + Cert |
0x3D | TLS_RSA_WITH_AES_256_CBC_SHA256 | AES256-SHA256 | PFS + GPP PFS + Cert RSA + Cert |
0x67 | TLS_DHE_RSA_WITH_AES_128_CBC_SHA256 | DHE-RSA-AES128-SHA256 | PFS + GPP PFS + Cert |
0x6B | TLS_DHE_RSA_WITH_AES_256_CBC_SHA256 | DHE-RSA-AES256-SHA256 | PFS + GPP PFS + Cert |
0x9C | TLS_RSA_WITH_AES_128_GCM_SHA256 | AES128-GCM-SHA256 | PFS + GPP PFS + Cert RSA + Cert |
0x9D | TLS_RSA_WITH_AES_256_GCM_SHA384 | AES256-GCM-SHA384 | PFS + GPP PFS + Cert RSA + Cert |
0x9E | TLS_DHE_RSA_WITH_AES_128_GCM_SHA256 | DHE-RSA-AES128-GCM-SHA256 | PFS + GPP PFS + Cert |
0x9F | TLS_DHE_RSA_WITH_AES_256_GCM_SHA384 | DHE-RSA-AES256-GCM-SHA384 | PFS + GPP PFS + Cert |
0x1301 | TLS_AES_128_GCM_SHA256 | TLS_AES_128_GCM_SHA256 | PFS + GPP PFS + Cert |
0x1302 | TLS_AES_256_GCM_SHA384 | TLS_AES_256_GCM_SHA384 | PFS + GPP PFS + Cert |
0x1303 | TLS_CHACHA20_POLY1305_SHA256 | TLS_CHACHA20_POLY1305_SHA256 | PFS + GPP PFS + Cert |
0xC007 | TLS_ECDHE_ECDSA_WITH_RC4_128_SHA | ECDHE-ECDSA-RC4-SHA | PFS + GPP |
0xC008 | TLS_ECDHE_ECDSA_WITH_3DES_EDE_CBC_SHA | ECDHE-ECDSA-DES-CBC3-SHA | PFS + GPP |
0xC009 | TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA | ECDHE-ECDSA-AES128-SHA | PFS + GPP |
0xC00A | TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA | ECDHE-ECDSA-AES256-SHA | PFS + GPP |
0xC011 | TLS_ECDHE_RSA_WITH_RC4_128_SHA | ECDHE-RSA-RC4-SHA | PFS + GPP PFS + Cert |
0xC012 | TLS_ECDHE_RSA_WITH_3DES_EDE_CBC_SHA | ECDHE-RSA-DES-CBC3-SHA | PFS + GPP PFS + Cert |
0xC013 | TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA | ECDHE-RSA-AES128-SHA | PFS + GPP PFS + Cert |
0xC014 | TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA | ECDHE-RSA-AES256-SHA | PFS + GPP PFS + Cert |
0xC023 | TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA256 | ECDHE-ECDSA-AES128-SHA256 | PFS + GPP |
0xC024 | TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA384 | ECDHE-ECDSA-AES256-SHA384 | PFS + GPP |
0xC027 | TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA256 | ECDHE-RSA-AES128-SHA256 | PFS + GPP PFS + Cert |
0xC028 | TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA384 | ECDHE-RSA-AES256-SHA384 | PFS + GPP PFS + Cert |
0xC02B | TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256 | ECDHE-ECDSA-AES128-GCM-SHA256 | PFS + GPP |
0xC02C | TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384 | ECDHE-ECDSA-AES256-GCM-SHA384 | PFS + GPP |
0xC02F | TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256 | ECDHE-RSA-AES128-GCM-SHA256 | PFS + GPP PFS + Cert |
0xC030 | TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384 | ECDHE-RSA-AES256-GCM-SHA384 | PFS + GPP PFS + Cert |
0xCCA8 | TLS_ECDHE_RSA_WITH_CHACHA20_POLY1305_SHA256 | ECDHE-RSA-CHACHA20-POLY1305 | PFS + GPP PFS + Cert |
0xCCA9 | TLS_ECDHE_ECDSA_WITH_CHACHA20_POLY1305_SHA256 | ECDHE-ECDSA-CHACHA20-POLY1305 | PFS + GPP |
0xCCAA | TLS_DHE_RSA_WITH_CHACHA20_POLY1305_SHA256 | DHE-RSA-CHACHA20-POLY1305 | PFS + GPP PFS + Cert |
Export the MSI file from the executable file
You can export the MSI file from the executable file to support a custom installation workflow.
ExtraHopSessionKeyForwarderSetup.exe -e
Note: | You can append <directory> to
the -e parameter to save the .msi file
to a directory other than the current working directory. For example, the
following command saves the file to the install_dir
directory:ExtraHopSessionKeyForwarderSetup.exe -e install_dir |
Thank you for your feedback. Can we contact you to ask follow up questions?