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.

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

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

# IP and Port where VoIPmonitor sensor is listening
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

In `/etc/voipmonitor.conf` on your sensor, enable the UDP listener.

# /etc/voipmonitor.conf

# Enable the listener
ssl_sessionkey_udp = yes

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

# Optional: Restrict listener to a specific IP or subnet
# ssl_sessionkey_udp_ip = 192.168.0.0/24

# For this method, you still need to tell the sensor which connections to decrypt
ssl = yes
ssl_ipport = 192.168.0.1:5061 # IP and port of your SIP application

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

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 two primary methods for decrypting TLS-encrypted SIP and SRTP media in VoIPmonitor. Method 1, Private Key Decryption, is the simpler approach, configured with `ssl=yes` and `ssl_ipport`, but it fails if Perfect Forward Secrecy (PFS) ciphers like Diffie-Hellman are used. Method 2, the SSL Key Logger, is the universally recommended solution. It works by injecting a shared library (`sslkeylog.so`) into SIP applications (Asterisk, Kamailio, FreeSWITCH) using `LD_PRELOAD`. This library intercepts session keys and sends them to the VoIPmonitor sensor over UDP or secure TCP. The guide provides step-by-step instructions for compiling the keylogger and configuring systemd service files for Asterisk and FreeSWITCH. It also details the corresponding VoIPmonitor configuration (`ssl_sessionkey_udp`, `ssl_sessionkey_udp_port`). Finally, it explains the mechanisms for decrypting DTLS-SRTP, recommending the `ssl_dtls_boost` parameter to enable optimal settings for handling the DTLS handshake and session key queueing. 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` Key Questions:

• How do I decrypt TLS encrypted SIP calls?
• Why is VoIPmonitor not decrypting my TLS traffic?
• 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?