Tls

This guide provides a comprehensive overview of the methods used by VoIPmonitor to decrypt encrypted SIP over TLS and encrypted media (SRTP). It covers the two primary decryption approaches: using a static private key and using the dynamic SSL Key Logger.

Introduction to TLS Decryption

VoIPmonitor can decrypt SIP signaling encrypted with TLS (v1.2 and v1.3 supported) and media encrypted with SRTP. It is essential to understand that not all TLS traffic can be decrypted.

Important Limitation: If the SIP session negotiates a cipher suite using a Perfect Forward Secrecy (PFS) algorithm, such as Diffie-Hellman (DHE/ECDHE), decryption using only the server's private key is mathematically impossible. In these cases, you must use the SSL Key Logger method to capture session-specific keys.

TLS Version and Cipher Suite Impact

The feasibility of private key decryption depends entirely on the TLS version and cipher suite:

• SSL/TLS 1.2 or older WITHOUT DH ciphers (e.g., RSA, AES256-SHA): Decryption IS possible using the server's private key. This is Method 1 configuration.

• SSL/TLS 1.3 or any DH-based cipher (EDH, DHE, ECDHE): Decryption using the private key is IMPOSSIBLE. You must use the SSL Key Logger (Method 2) to obtain session-specific keys.

Modern VoIP services typically use_TLS 1.3 or strong PFS ciphers for security, making the SSL Key Logger the only viable decryption method.

Cloud Service Decryption Limitations

When monitoring SIP traffic between phones and cloud-based services (e.g., Cisco Webex Cloud, Microsoft Teams, Zoom Phone):

• Direct hardware phone to cloud: Decryption is generally IMPOSSIBLE because:

 ** You do not have the cloud service's private key
 ** Cloud services typically use TLS 1.3 or strong DH ciphers
 ** You cannot inject an SSL keylogger into cloud infrastructure

• Softphone to cloud: Decryption IS possible using the SSL Key Logger (Method 2) on the local machine where the softphone runs, as long as you control that host.

• Phone to local SBC to cloud: Use SBC-specific monitoring features (e.g., Ribbon SBC Monitoring Profile) to extract decrypted SIP signaling before it leaves your network.

Decrypted SIP packets are stored in PCAP files as virtual UDP packets for consistent analysis within the GUI.

Method 1: Private Key Decryption

This is the simpler method and works well for environments where you control the TLS cipher suites and can disable PFS.

Configuration

To enable this method, add the following to `/etc/voipmonitor.conf`:

# /etc/voipmonitor.conf

# Enable the SSL decryption module
ssl = yes

# Provide the server's IP, TLS port, and the absolute path to its private key.
# The key must be in PEM format. You can have multiple lines for multiple servers.
ssl_ipport = 10.0.0.1 : 5061 /etc/pki/tls/private/my_server.key

Common Issues: SSL Key Logger Not Decrypting

If you have configured the SSL Key Logger but TLS SIP packets are still not being decrypted, check these common causes:

Issue 1: Session Keys Not Being Captured (localhost/127.0.0.1)

Symptom: The SSL Key Logger appears to be running (you see "SSL KEYLOG: OK" messages), but TLS packets are not being decrypted.

Root Cause: When sending session keys via UDP to `127.0.0.1` or `localhost`, the VoIPmonitor sensor can only capture these packets if the loopback interface (`lo`) is included in the `interface` directive.

Solution: Add `lo` to the interface configuration in `/etc/voipmonitor.conf`:

# Include the loopback interface to capture UDP packets sent to 127.0.0.1
interface = eth0,lo

After making this change: 1. Restart VoIPmonitor: `systemctl restart voipmonitor` 2. Restart your TLS application (e.g., Asterisk, Kamailio) to generate a new SSL handshake with fresh session keys

Verification: The sensor should now see the UDP session key packets and decryption should work.

Issue 2: ssl_ipport Syntax Error (Private Key Overrides Key Logger)

Symptom: Decryption fails with DHE/ECDHE ciphers even though the SSL Key Logger is configured.

Root Cause: If `ssl_ipport` contains a file path (e.g., `/path/to/private.key`), VoIPmonitor ignores the SSL Key Logger and tries to use Method 1 (Private Key), which fails for Perfect Forward Secrecy ciphers.

Solution: Remove the key file path from `ssl_ipport`:

# INCORRECT - this forces Method 1 and ignores the key logger:
ssl_ipport = 192.168.0.1:5061 /path/to/private.key

# CORRECT - IP and port only, enables SSL Key Logger method:
ssl_ipport = 192.168.0.1:5061

Issue 3: Distributed Mode (packetbuffer_sender=yes)

Symptom: Decryption works with `packetbuffer_sender=no` but fails when `packetbuffer_sender=yes` is enabled.

Root Cause: Session keys are being sent to the local client sensor instead of the central server. Client sensors only forward raw packets to the central server; session keys are lost in transit.

Solution: Send session keys directly to the central server's IP address, not localhost or the client sensor:

# On the PBX, set SSLKEYLOG_UDP to the central server's IP:
SSLKEYLOG_UDP='192.168.1.100:1234'  # Central server IP and port

See the "Method 3: TLS Decryption in Distributed/Client-Server Mode" section below for complete configuration details.

Method 2: SSL Key Logger (Recommended & Universal)

This is the most powerful and recommended method. It works for all cipher suites, including those with Perfect Forward Secrecy, by dynamically capturing session keys directly from the application's memory.

It works by using the `LD_PRELOAD` mechanism to inject a small library (`sslkeylog.so`) into your SIP application (e.g., Asterisk, Kamailio, FreeSWITCH). This library intercepts the creation of new SSL/TLS session keys and sends them over the network (UDP or secure TCP) to the VoIPmonitor sensor.

Step 1: Compile the SSL Key Logger Library

First, you need to compile the `sslkeylog.so` library on the same server as your SIP application.

1. Install prerequisites

# For Debian/Ubuntu
apt-get install libssl-dev build-essential git

# For CentOS/RHEL/AlmaLinux
yum install openssl-devel make gcc git

2. Clone the repository and compile

cd /usr/local/src
git clone https://github.com/voipmonitor/sniffer.git voipmonitor-git
cd voipmonitor-git/tools/ssl_keylogger/
make

This will create the `sslkeylog.so` library in the current directory.

Step 2: Configure Your SIP Application to Use the Key Logger

You must modify the startup script or service file of your SIP application to preload the library.

General Test (works for any application using OpenSSL)

First, test that the library works correctly. This command should print "SSL KEYLOG : OK" messages.

env SSLKEYLOG_UDP='127.0.0.1:1234' LD_PRELOAD="/usr/local/src/voipmonitor-git/tools/ssl_keylogger/sslkeylog.so" openssl

Asterisk

For `systemd`, create an environment file for the Asterisk service.

1. Edit the service file

`systemctl edit asterisk.service` and add:

[Service]
EnvironmentFile=/etc/default/asterisk-ssl

2. Create the environment file `/etc/default/asterisk-ssl` with the following content

# Destination IP and Port for sending session keys (UDP mode)
# IMPORTANT: For UDP mode, the sniffer does NOT listen on this port.
# Instead, the sniffer captures packets that are sent to this UDP port
# through its main interface (see Step 3 below).
SSLKEYLOG_UDP='127.0.0.1:1234'
LD_PRELOAD='/usr/local/src/voipmonitor-git/tools/ssl_keylogger/sslkeylog.so'

3. Reload and restart

`systemctl daemon-reload && systemctl restart asterisk`

Kamailio

Kamailio often loads OpenSSL dynamically, so you must preload both the key logger and the main SSL library.

Modify your `/etc/init.d/kamailio` or systemd service file's `ExecStart` line

# The path to libssl may vary. Find it with: find / -name "libssl.so*"
env SSLKEYLOG_UDP='127.0.0.1:1234' LD_PRELOAD="/usr/local/src/voipmonitor-git/tools/ssl_keylogger/sslkeylog.so /usr/lib/x86_64-linux-gnu/libssl.so" /usr/sbin/kamailio ...

FreeSWITCH

FreeSWITCH can be sensitive to `systemd` settings. It's often necessary to modify the service file directly.

Edit `/lib/systemd/system/freeswitch.service` and change `ExecStart` to

ExecStart=env SSLKEYLOG_UDP='10.0.0.1:1234' LD_PRELOAD='/usr/local/src/voipmonitor-git/tools/ssl_keylogger/sslkeylog.so' /usr/bin/freeswitch -u www-data -g www-data -nonat

Then run `systemctl daemon-reload && systemctl restart freeswitch`.

Step 3: Configure VoIPmonitor to Receive Session Keys

IMPORTANT: UDP vs TCP Mode Behavior

The SSL Key Logger supports two transport modes with **fundamentally different behavior**:

• UDP Mode (default): The sniffer does NOT listen on a socket. Instead, the sniffer captures packets on its main interface (configured with `interface=`) and processes any UDP packets on `ssl_sessionkey_udp_port` as TLS session keys.

• TCP Mode: The sniffer actively listens on a TCP port for incoming session key connections. Use `ssl_sessionkey_bind` and `ssl_sessionkey_bind_port` for TCP mode.

=== UDP Mode Configuration ===

For UDP delivery, ensure your VoIPmonitor sensor's main `interface` is configured to capture traffic from the network where the PBX sends UDP session key packets.

IMPORTANT: Capturing Keys from Localhost

If your PBX and VoIPmonitor sensor are on the same server, and you are sending keys to `127.0.0.1` (localhost), you must add the loopback interface (`lo`) to the `interface` directive, or the sensor will never see the UDP packets containing the session keys.

In `/etc/voipmonitor.conf`:

# Include loopback interface when SSLKEYLOG_UDP points to 127.0.0.1
interface = eth0,lo

If you do not add `lo`, the sensor will appear to run correctly, but decryption will fail because the session key packets are never captured.

In `/etc/voipmonitor.conf`:

# /etc/voipmonitor.conf

# UDP MODE: Tell sniffer to process captured UDP packets on this port as session keys
# The sniffer does NOT bind/listen on this port - it passively captures packets.
# The sniffer's main 'interface' must capture traffic from the network where
# the PBX sends these UDP packets.
ssl_sessionkey_udp = yes

# The port must match the one set in the SSLKEYLOG_UDP environment variable
ssl_sessionkey_udp_port = 1234

# Optional: Only accept session keys from specific IP/subnet
# ssl_sessionkey_udp_ip = 192.168.0.0/24

# Enable the SSL decryption module globally
ssl = yes

# CORRECT SYNTAX for the Key Logger Method:
# Tell the sensor which IP:Port to apply the received session keys to.
# Notice there is NO path to a key file.
ssl_ipport = 192.168.0.1:5061

# --------------------------------------------------------------------

# INCORRECT SYNTAX for the Key Logger Method:
# The following line will IGNORE the key logger and try to use the key file,
# which will fail for DHE/ECDHE ciphers. DO NOT USE THIS SYNTAX WITH THE KEY LOGGER.
# ssl_ipport = 192.168.0.1:5061 /path/to/my_server.key

CRITICAL CONFIGURATION NOTE: When using the SSL Key Logger method, the `ssl_ipport` directive must only specify the IP address and port. It must not include a path to a key file.

Including a key file path forces VoIPmonitor to use Method 1 (Private Key) for that specific IP:Port, which will override the key logger and cause decryption to fail if PFS ciphers are in use.

Securing Key Transport (TCP Mode)

By default, keys are sent unencrypted over UDP. For production environments where the sensor and PBX are on different hosts, it is recommended to use the secure TCP mode.

1. Compile the keylogger with TCP support

cd /usr/local/src/voipmonitor-git/tools/ssl_keylogger/
make with_tcp

2. Change the environment variable on your PBX from `SSLKEYLOG_UDP` to `SSLKEYLOG_TCP`.

3. Change the VoIPmonitor sensor configuration to listen on TCP

# In voipmonitor.conf
ssl_sessionkey_udp = no
ssl_sessionkey_bind = 0.0.0.0  # IP for the sniffer to listen on
ssl_sessionkey_bind_port = 1234

Method 3: TLS Decryption in Distributed/Client-Server Mode

When using VoIPmonitor's client-server architecture (packetbuffer_sender=yes), remote sensors forward raw packets to a central server. In this configuration, TLS/SRTP decryption must occur on the central server. This requires special configuration for the SSL Key Logger to send session keys to the correct destination.

Architecture Overview

When a client sensor forwards packets with packetbuffer_sender=yes:

• The client sensor sends raw packet stream to the central server
• The central server performs packet analysis and decryption
• Session keys from the PBX must be sent to the central server, not the remote client sensor

HTTP-Response: 
Error 400: Syntax Error? (Assumed diagram type: component) (line: 8)

Diagram-Code:
@startuml
skinparam shadowing false
skinparam defaultFontName Arial

rectangle "PBX Server" as PBX
rectangle "Client Sensor" as Client
rectangle "Central Server" as Central

PBX --(1)--> Central : Session Keys\n(SSLKEYLOG to Central IP)
Client --(2)--> Central : Raw Packets\n(packetbuffer_sender=yes)

note right of Client
  Client does NOT\nreceive session keys
end note

note right of PBX
  Send keys to\nCentral Server IP
  NOT to localhost
  or client sensor
end note
@enduml

Configuration for Distributed Mode

Step 1: Configure Client Sensor /etc/voipmonitor.conf on the remote client sensor:

id_sensor               = 2
server_destination      = central.server.ip
server_destination_port = 60024
server_password         = your_strong_password

packetbuffer_sender     = yes    # Forward raw packets to central server
interface               = eth0
# NO ssl_* configuration needed on client

Step 2: Configure PBX sslkeylog to Send Keys to Central Server On your PBX server, the SSLKEYLOG_UDP or SSLKEYLOG_TCP variable MUST point to the central server's IP address, NOTlocalhost or the client sensor'.

# /etc/default/asterisk-ssl (example)

# CRITICAL: Send keys to CENTRAL SERVER IP and port
# NOT to localhost, NOT to client sensor
SSLKEYLOG_UDP='192.168.1.100:1234'  # Central Server IP : ssl_sessionkey_udp_port
LD_PRELOAD='/usr/local/src/voipmonitor-git/tools/ssl_keylogger/sslkeylog.so'

Step 3: Configure Central Server /etc/voipmonitor.conf on the central server:

# Server mode configuration
server_bind            = 0.0.0.0
server_bind_port       = 60024
server_password        = your_strong_password

mysqlhost              = localhost
mysqldb                = voipmonitor
mysqluser              = voipmonitor
mysqlpassword          = db_password

# Enable SSL decryption on central server
ssl = yes

# UDP MODE: Process captured UDP packets on this port as session keys
# The central server's interface must capture traffic where PBX sends keys
ssl_sessionkey_udp = yes
ssl_sessionkey_udp_port = 1234  # Must match SSLKEYLOG_UDP port on PBX

# Apply keys to the PBX's TLS/IP address
ssl_ipport = 192.168.1.50:5061   # PBX IP and TLS port (no key file path)

Common Configuration Error

Symptom: TLS/SRTP decryption fails when packetbuffer_sender=yes is enabled, but works with packetbuffer_sender=no.

Root Cause: The PBX's SSLKEYLOG_UDP is pointing to 127.0.0.1 (localhost) instead of the central server's IP address. Session keys are received by the client sensor, but the client sensor forwards only raw packets to the central server - the keys are lost in transit.

Fix: Change the PBX environment variable:

Wrong (causes decryption failure in distributed mode)

SSLKEYLOG_UDP='127.0.0.1:1234'

Correct (send keys directly to central server)

SSLKEYLOG_UDP='192.168.1.100:1234'   # Central server's IP address

Using TCP Mode in Distributed Deployments

For secure key transport in distributed architectures, use TCP mode.

On the PBX:

# Use TCP instead of UDP
SSLKEYLOG_TCP='192.168.1.100:1234'
LD_PRELOAD='/usr/local/src/voipmonitor-git/tools/ssl_keylogger/sslkeylog.so'

On the Central Server:

ssl_sessionkey_udp = no
ssl_sessionkey_bind = 0.0.0.0        # Accept connections on all interfaces
ssl_sessionkey_bind_port = 1234

Summary Checklist

For successful TLS/SRTP decryption with packetbuffer_sender=yes:

• Client sensor: Enable packetbuffer_sender=yes, forward raw packets
• Central server: Enable ssl=1 and configure SSL key listener
• PBX: Set SSLKEYLOG_UDP to central server IP, not localhost or client sensor
• Central server's ssl_ipport must match PBX IP:port (no key file path)
• Central server's ssl_sessionkey_udp_port must match PBX's SSLKEYLOG_UDP port

Decrypting SRTP (DTLS)

Decrypting SRTP requires capturing both the DTLS handshake packets (which happen before RTP) and the session keys from the key logger. VoIPmonitor uses a sophisticated queueing system to hold DTLS packets until the corresponding session key arrives.

Recommended Configuration

The ssl_dtls_boost pseudo-parameter enables a set of recommended defaults for robust decryption. It is enabled by default in recent versions.

# This single parameter enables the best-practice settings below it.
ssl_dtls_boost = yes

# --- Settings enabled by ssl_dtls_boost ---
# ssl_dtls_queue_expiration = 30
# ssl_sessionkey_keep = yes
# ssl_dtls_queue_keep = yes
# ssl_dtls_handshake_safe = ext
# srtp_rtp_local_instances = yes

AI Summary for RAG

Summary: This guide details the methods for decrypting TLS-encrypted SIP and SRTP media in VoIPmonitor. Method 1, Private Key Decryption, uses `ssl=yes` with `ssl_ipport=IP:PORT /path/to/key`; this method works ONLY for TLS 1.2 or older WITHOUT Diffie-Hellman ciphers (non-PFS). For all other cases (TLS 1.3 or any DH cipher like DHE/ECDHE/EDH), private key decryption is IMPOSSIBLE due to Perfect Forward Secrecy. Method 2, the SSL Key Logger, is the universal solution working with all ciphers including PFS. It injects `sslkeylog.so` into SIP applications (Asterisk, Kamailio, FreeSWITCH) via `LD_PRELOAD`, which intercepts and sends session keys to the VoIPmonitor sensor via UDP (default) or TCP. The critical syntax rule for Method 2: `ssl_ipport` must NOT include a key file path. CLOUD SERVICE LIMITATIONS: Direct hardware phone to cloud decryption is IMPOSSIBLE because you lack the cloud's private key, cloud uses TLS 1.3/DH, and you cannot inject keylogger. Softphone to cloud is possible via SSL Key Logger on the local host. Phone to local SBC to cloud is possible using SBC monitoring features (e.g., Ribbon SBC Monitoring Profile to export decrypted SIP). IMPORTANT: UDP mode does NOT make the sniffer listen on a port; the sniffer passively captures UDP packets on `ssl_sessionkey_udp_port` through its main interface. CRITICAL ISSUE: When sending keys to `127.0.0.1`, the loopback interface (`lo`) MUST be added to `interface` directive (e.g., `interface = eth0,lo`), otherwise keys won't be captured and decryption fails. After adding `lo`, restart VoIPmonitor and the TLS application. Method 3 describes TLS decryption in distributed client-server architecture with `packetbuffer_sender=yes`. The common issue in distributed mode is that PBX's `SSLKEYLOG_UDP` points to `127.0.0.1` instead of the central server's IP; session keys sent to localhost are captured by the client sensor but never forwarded. The fix is to send session keys directly to the central server (e.g., `SSLKEYLOG_UDP='192.168.1.100:1234'`). TCP mode is recommended for secure key transport using `SSLKEYLOG_TCP`, `ssl_sessionkey_bind`, and `ssl_sessionkey_bind_port`. The guide also covers DTLS-SRTP decryption with the recommended `ssl_dtls_boost` parameter. COMMON SYMPTOMS AND FIXES: (1) Key logger running but decryption not working → add `lo` to interface, (2) DHE/ECDHE decryption fails despite key logger → remove key file path from `ssl_ipport`, (3) Works with `packetbuffer_sender=no` but fails with `yes` → send keys to central server IP not localhost, (4) Cloud service decryption impossible → need local SBC or softphone. Keywords: tls, ssl, srtp, dtls, decryption, decrypt, encrypted, pfs, perfect forward secrecy, diffie-hellman, private key, sslkeylog, ld_preload, session key, asterisk, kamailio, freeswitch, `ssl_ipport`, `ssl_sessionkey_udp`, `ssl_dtls_boost`, `make with_tcp`, syntax, distributed architecture, client-server, `packetbuffer_sender`, central server, remote sensor, `SSLKEYLOG_UDP`, `SSLKEYLOG_TCP`, `ssl_sessionkey_bind`, `ssl_sessionkey_bind_port`, localhost, `127.0.0.1`, loopback, `lo`, `interface`, not decrypting, not working, key logger not decrypting, troubleshooting, cloud service, webex, teams, zoom phone, tls 1.3, ciphersuite, ecdhe, dhe, edh, softphone hardware phone sbc ribbon monitoring profile Key Questions:

• How do I decrypt TLS encrypted SIP calls between phones and a cloud VoIP service like Webex?
• Can I decrypt SIP traffic between hardware phones and cloud services without a local SBC?
• Why is VoIPmonitor not decrypting my TLS packets when SSL key logger is running?
• What is the correct syntax for `ssl_ipport` when using the SSL Key Logger?
• What is the SSL Key Logger and how does it work?
• How to configure Asterisk or FreeSWITCH to send TLS session keys to VoIPmonitor?
• How do I decrypt calls that use Diffie-Hellman (DHE/ECDHE) ciphers?
• What is `LD_PRELOAD` and how is it used for decryption?
• How can I decrypt SRTP and DTLS media streams?
• What does the `ssl_dtls_boost` parameter do?
• How to configure TLS decryption with `packetbuffer_sender=yes` in distributed mode?
• Why does TLS decryption work with `packetbuffer_sender=no` but fail with `packetbuffer_sender=yes`?
• Where should I send SSL session keys in a VoIPmonitor client-server architecture?
• Do I need to add loopback `lo` to interface when sending SSL keys to 127.0.0.1?
• Why is SSL key logger not capturing session keys from localhost?
• How do I fix TLS decryption that fails with the key logger method?