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?