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, you must enable the listener and, crucially, tell the sniffer which traffic to apply the keys to using the correct syntax.

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.

# /etc/voipmonitor.conf

# Enable the listener for session keys
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

# 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

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 an `ssl_ipport` line that includes the path to the private key file; this method fails if Perfect Forward Secrecy (PFS) ciphers like Diffie-Hellman are used. Method 2, the SSL Key Logger, is the universally recommended solution for all ciphers. 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. The guide provides step-by-step compilation and configuration instructions. It stresses the critical configuration syntax for Method 2: the corresponding `ssl_ipport` line must not contain a path to a key file, as this would override the key logger. The guide also details DTLS-SRTP decryption, recommending the `ssl_dtls_boost` parameter. 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 Key Questions:

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