WebRTC: Difference between revisions

From VoIPmonitor.org
(Add critical prerequisite: sipport parameter required for WebRTC on non-standard ports)
(Rewrite: konsolidace, lepší struktura, tabulka pro srovnání metod, warning/note boxy, See Also sekce)
 
(3 intermediate revisions by the same user not shown)
Line 1: Line 1:
{{DISPLAYTITLE:Monitoring Encrypted WebRTC (WSS/DTLS-SRTP)}}
{{DISPLAYTITLE:Monitoring Encrypted WebRTC (WSS/DTLS-SRTP)}}


'''This guide provides a complete, step-by-step tutorial for configuring Asterisk to support secure WebRTC clients and enabling VoIPmonitor to capture and decrypt the associated SIP over Secure WebSocket (WSS) and SRTP traffic.'''
'''This guide covers monitoring encrypted WebRTC traffic with VoIPmonitor, including SIP over Secure WebSocket (WSS) and DTLS-SRTP media encryption.'''


== Overview ==
== Overview ==
WebRTC (Web Real-Time Communication) requires encrypted transport for both signaling and media. This is achieved using:
*'''WSS (Secure WebSocket):''' For the SIP signaling, encrypting it with TLS.
*'''DTLS-SRTP:''' For the media (RTP) stream, encrypting it with DTLS negotiation to establish SRTP keys.


VoIPmonitor can sniff and decrypt both layers, provided it has access to the private TLS key used by the PBX. This guide will walk through the full setup for Asterisk.
WebRTC requires encrypted transport for both signaling and media:
* '''WSS (Secure WebSocket):''' SIP signaling encrypted with TLS
* '''DTLS-SRTP:''' Media (RTP) encrypted via DTLS key negotiation


== Critical Prerequisite: Configure sipport ===
VoIPmonitor can decrypt both layers using either a private TLS key or the SSL Key Logger method.


Before configuring SSL/TLS decryption, you must tell VoIPmonitor which ports to monitor for WebRTC traffic. This is done using the <code>sipport</code> parameter.
<kroki lang="mermaid">
%%{init: {'flowchart': {'nodeSpacing': 15, 'rankSpacing': 30}}}%%
flowchart LR
    subgraph Browser["WebRTC Client"]
        WC[Web Browser]
    end
    subgraph PBX["Asterisk PBX"]
        WSS[WSS :8089]
        SRTP[DTLS-SRTP]
    end
    subgraph VM["VoIPmonitor"]
        CAP[Capture]
        DEC[Decrypt]
        CDR[CDR]
    end
    WC -->|"SIP/WSS"| WSS
    WC -->|"Media"| SRTP
    WSS -.->|"mirror"| CAP
    SRTP -.->|"mirror"| CAP
    CAP --> DEC --> CDR
</kroki>


By default, VoIPmonitor only listens on port 5060. If your WebRTC service runs on a non-standard port (e.g., TCP 8088 for WebSocket or 8089 for Secure WebSocket), you must add it to the configuration.
== Prerequisites: Configure sipport ==


=== Adding Non-Standard Ports to sipport ===
{{Warning|1=VoIPmonitor only monitors port 5060 by default. You '''must''' add WebRTC ports to <code>sipport</code> or traffic will be ignored.}}


Edit <code>/etc/voipmonitor.conf</code>:
Edit <code>/etc/voipmonitor.conf</code>:


<pre>
<syntaxhighlight lang="ini">
# Add the WebRTC ports used by your PBX
# Add WebRTC ports (WS=8088, WSS=8089)
# Multiple ports can be separated by commas
sipport = 5060,8088,8089
sipport = 5060,8088,8089


# Or use port ranges
# Or use port ranges
# sipport = 5060,8080-8090
sipport = 5060,8080-8090
</pre>
</syntaxhighlight>


=== Why This Is Required ===
Restart after changes: <code>systemctl restart voipmonitor</code>


''The <code>sipport</code> parameter controls which TCP ports VoIPmonitor monitors for SIP and WebRTC (WebSocket/WSS) traffic. Without adding your WebRTC port to this list, VoIPmonitor will completely ignore traffic on that port, even if SSL/TLS decryption is configured correctly.''
{{Note|1=In probe/server architecture, configure <code>sipport</code> on '''both''' probe and server.}}


* '''Basic WebSocket (WS):''' If using unencrypted WebSocket on port 8088, add <code>8088</code> to <code>sipport</code>
== Decryption Methods ==
* '''Secure WebSocket (WSS):''' If using encrypted WebSocket on port 8089, add <code>8089</code> to <code>sipport</code>
* '''Both protocols together:''' Add both ports: <code>sipport = 5060,8088,8089</code>


=== Restart the Service ===
Choose based on your environment:


After changing <code>sipport</code>, restart VoIPmonitor:
{| class="wikitable"
|-
! Method !! When to Use !! Limitations
|-
| '''A: Private Key''' || Development/testing, RSA ciphers || Fails with TLS 1.3/PFS (DHE/ECDHE)
|-
| '''B: SSL Key Logger''' || Production, TLS 1.3, PFS, distributed setups || Requires library injection on PBX
|}


<pre>
=== Method A: Private Key ===
systemctl restart voipmonitor
</pre>


=== Client/Server Architecture Note ===
<syntaxhighlight lang="ini">
 
In a probe/server setup:
* The <code>sipport</code> parameter on the probe controls which TCP packets are forwarded to the server
* The parsing and SSL/TLS decryption configuration must be on the server
* Ensure the server also has the same <code>sipport</code> configuration to properly parse the forwarded traffic
 
For full details on the <code>sipport</code> parameter, see [[Sniffer_configuration]].
 
== Part 1: Configuring VoIPmonitor to Decrypt TLS ==
There are two methods to decrypt WebRTC traffic (SIP over Secure WebSocket and DTLS-SRTP). Choose the method that best fits your environment.
 
=== Method A: Private Key Decryption (Recommended for Development/Testing) ===
This is the simpler method suitable for controlled environments where you have access to the PBX/SBC private key and can control the TLS cipher suite.
 
In `/etc/voipmonitor.conf`, enable the SSL module and provide the path to the private key:
 
<pre>
# /etc/voipmonitor.conf
# /etc/voipmonitor.conf
ssl = yes
ssl = yes
ssl_ipport = 192.168.2.107:8089 /etc/asterisk/keys/asterisk.pem


# Point to the private key used by your PBX.
# Or use CIDR for multiple hosts
# Format: <IP of PBX> : <WSS Port> /path/to/private.key
ssl_ipport = 192.168.2.0/24:8089 /path/to/key.pem
#
</syntaxhighlight>
# Example for this guide:
ssl_ipport = 192.168.2.107 : 8089 /etc/asterisk/keys/asterisk.pem
</pre>
 
'''Important Limitations:'''
* This method will NOT work if the PBX uses TLS 1.3 or Perfect Forward Secrecy (PFS) ciphers (DHE/ECDHE)
* Requires access to the PBX/SBC private key file
* The PBX and VoIPmonitor sensor must use the same key file
 
'''Alternative: CIDR Notation'''
You can specify a subnet instead of a single IP:
<pre>
# Apply to all PBX hosts in the 192.168.2.0/24 network
ssl_ipport = 192.168.2.0/24 : 8089 /path/to/your.key
</pre>
 
''Note: This configuration is also applicable for FreeSWITCH. You would just need to point to the key file used by FreeSWITCH.''
 
=== Method B: SSL Key Logger (Universal Solution) ===
 
If any of the following apply to your environment, use the SSL Key Logger method instead:
* Your PBX uses TLS 1.3 or PFS ciphers (ECDHE, DHE)
* You cannot access the PBX/SBC private key file
* You are using a client/server (distributed) architecture
* Multiple PBX/SBC servers need decryption
 
The SSL Key Logger works by injecting a library (`sslkeylog.so`) into your PBX/SBC process. This library captures TLS session keys dynamically and forwards them to VoIPmonitor via UDP/TCP.


'''Advantages:'''
=== Method B: SSL Key Logger ===
* Works with ALL cipher suites including TLS 1.3 and PFS
* No access to private key files required
* Automatically handles multiple hosts when using CIDR notation in `ssl_ipport`
* Works seamlessly in client/server architectures


'''Configuration Overview:'''
Works with ALL cipher suites including TLS 1.3 and PFS.


1. '''Compile sslkeylog.so''':
'''1. Compile the library:'''
<pre>
<syntaxhighlight lang="bash">
cd /usr/local/src
git clone https://github.com/voipmonitor/sniffer.git /usr/local/src/voipmonitor-git
git clone https://github.com/voipmonitor/sniffer.git voipmonitor-git
cd /usr/local/src/voipmonitor-git/tools/ssl_keylogger/
cd voipmonitor-git/tools/ssl_keylogger/
make
make
</pre>
</syntaxhighlight>


2. '''Configure PBX/SBC to Send Session Keys''':
'''2. Configure PBX to send session keys:'''


For Asterisk (via systemd):
For Asterisk (create <code>/etc/default/asterisk-ssl</code>):
<pre>
<syntaxhighlight lang="bash">
# /etc/default/asterisk-ssl
SSLKEYLOG_UDP='127.0.0.1:1234'
SSLKEYLOG_UDP='127.0.0.1:1234'
LD_PRELOAD='/usr/local/src/voipmonitor-git/tools/ssl_keylogger/sslkeylog.so'
LD_PRELOAD='/usr/local/src/voipmonitor-git/tools/ssl_keylogger/sslkeylog.so'
</pre>
</syntaxhighlight>
 
For FreeSWITCH:
Edit `/lib/systemd/system/freeswitch.service`:
<pre>
ExecStart=env SSLKEYLOG_UDP='127.0.0.1:1234' LD_PRELOAD='/usr/local/src/voipmonitor-git/tools/ssl_keylogger/sslkeylog.so' /usr/bin/freeswitch ...
</pre>


3. '''Configure VoIPmonitor to Receive Keys''':
For FreeSWITCH, add to systemd service:
<syntaxhighlight lang="bash">
ExecStart=env SSLKEYLOG_UDP='127.0.0.1:1234' LD_PRELOAD='/path/to/sslkeylog.so' /usr/bin/freeswitch ...
</syntaxhighlight>


In `/etc/voipmonitor.conf`:
'''3. Configure VoIPmonitor:'''
<pre>
<syntaxhighlight lang="ini">
# /etc/voipmonitor.conf
# /etc/voipmonitor.conf
ssl = yes
ssl = yes
 
ssl_ipport = 192.168.2.0/24:8089   # NO key file path!
# IMPORTANT: When using SSL Key Logger, ssl_ipport must NOT include a key file path
# You can use CIDR notation to handle multiple hosts
ssl_ipport = 192.168.2.0/24 : 8089
 
# Enable UDP session key reception (for SSL Key Logger)
ssl_sessionkey_udp = yes
ssl_sessionkey_udp = yes
ssl_sessionkey_udp_port = 1234
ssl_sessionkey_udp_port = 1234
</pre>


'''Critical Configuration Note:'''
# Add loopback if sending keys locally
* When using the SSL Key Logger, `ssl_ipport` '''must only''' contain IP:port (or IP/mask:port), NO key file path
interface = eth0,lo
* The port (8089) must match your PBX/SBC WSS port configuration
</syntaxhighlight>
* Add `lo` (loopback) to `interface` if sending keys to 127.0.0.1: `interface = eth0,lo`
* Restart both PBX/SBC and VoIPmonitor after configuration


'''Client/Server Architecture:'''
{{Tip|1=For distributed mode (<code>packetbuffer_sender=yes</code>), send keys to the '''central server IP''', not localhost.}}
If using `packetbuffer_sender=yes` (distributed mode), session keys from the PBX/SBC '''must''' be sent to the central server's IP address, not localhost or the client sensor:
<pre>
# On PBX/SBC - send keys to CENTRAL SERVER IP
SSLKEYLOG_UDP='192.168.1.100:1234'
</pre>


For complete details on SSL Key Logger configuration, UDP/TCP modes, troubleshooting, and client/server deployments, see the comprehensive [[Tls]] documentation (Method 2 and Method 3 sections).
For complete SSL Key Logger documentation, see [[Tls#Method_2:_SSL_Key_Logger|TLS Decryption]].


== Part 2: Configuring Asterisk for Secure WebRTC ==
== Asterisk Configuration ==
This section details the full configuration for Asterisk, from generating keys to setting up PJSIP endpoints.


=== Step 1: Generate TLS Certificates ===
=== Step 1: Generate TLS Certificates ===
First, we need to create a Certificate Authority (CA) and a server certificate that Asterisk will use for its HTTPS and WSS interfaces.


<pre>
<syntaxhighlight lang="bash">
# Create a directory for your keys
mkdir -p /etc/asterisk/keys && cd /etc/asterisk/keys
mkdir -p /etc/asterisk/keys
cd /etc/asterisk/keys


# 1. Create a private key for your local Certificate Authority (CA)
# Create CA
openssl genrsa -des3 -out ca.key 4096
openssl genrsa -des3 -out ca.key 4096
# 2. Create a root CA certificate
openssl req -new -x509 -days 3650 -key ca.key -out ca.crt
openssl req -new -x509 -days 3650 -key ca.key -out ca.crt


# 3. Create a private key for the Asterisk server
# Create server certificate
openssl genrsa -out key.pem 2048
openssl genrsa -out key.pem 2048
openssl req -new -key key.pem -out server.csr
openssl x509 -req -days 3650 -in server.csr -CA ca.crt -CAkey ca.key -set_serial 01 -out cert.crt


# 4. Create a certificate signing request (CSR) for the Asterisk server
# Combine for Asterisk
openssl req -new -key key.pem -out req-sip_server.csr
cat key.pem cert.crt > asterisk.pem
</syntaxhighlight>


# 5. Sign the server certificate with your CA
=== Step 2: Configure HTTP Server ===
openssl x509 -req -days 3650 -in req-sip_server.csr -CA ca.crt -CAkey ca.key -set_serial 01 -out cert-sip_server.crt
 
# 6. Combine the private key and signed certificate into a single .pem file for Asterisk
cat key.pem > asterisk.pem
cat cert-sip_server.crt >> asterisk.pem
</pre>
 
=== Step 2: Configure Asterisk's HTTP Server for WSS ===
Edit `/etc/asterisk/http.conf` to enable the built-in web server and activate TLS for the WebSocket transport.
 
<pre>
; /etc/asterisk/http.conf


<code>/etc/asterisk/http.conf</code>:
<syntaxhighlight lang="ini">
[general]
[general]
enabled = yes
enabled = yes
bindaddr = 0.0.0.0
bindaddr = 0.0.0.0
bindport = 8088 ; Port for unencrypted WS
bindport = 8088         ; WS (unencrypted)
 
tlsenable = yes
tlsenable = yes
tlsbindaddr = 0.0.0.0:8089 ; Port for encrypted WSS
tlsbindaddr = 0.0.0.0:8089 ; WSS (encrypted)
tlscertfile = /etc/asterisk/keys/asterisk.pem
tlscertfile = /etc/asterisk/keys/asterisk.pem
tlscipher = AES128-SHA
tlscipher = AES128-SHA
</pre>
</syntaxhighlight>
 
=== Step 3: Configure RTP Settings ===
Edit `/etc/asterisk/rtp.conf` and ensure ICE support is enabled, which is essential for WebRTC clients to traverse NAT.


<pre>
=== Step 3: Configure RTP ===
; /etc/asterisk/rtp.conf


<code>/etc/asterisk/rtp.conf</code>:
<syntaxhighlight lang="ini">
[general]
[general]
icesupport = yes
icesupport = yes
; You can optionally configure a public STUN server
; stunaddr = stun.l.google.com:19302
; stunaddr = stun.l.google.com:19302
</pre>
</syntaxhighlight>


=== Step 4: Configure PJSIP for WebRTC ===
=== Step 4: Configure PJSIP ===
This is the core configuration. We will set up UDP, WS, and WSS transports, and then create endpoints that require DTLS encryption.


;First, disable the old chan_sip module in `/etc/asterisk/modules.conf` to avoid conflicts:
Disable old chan_sip in <code>/etc/asterisk/modules.conf</code>:
<pre>
<syntaxhighlight lang="ini">
; /etc/asterisk/modules.conf
noload => chan_sip.so
noload => chan_sip.so
</pre>
</syntaxhighlight>
 
;Next, configure `/etc/asterisk/pjsip.conf`:
<pre>
; /etc/asterisk/pjsip.conf


<code>/etc/asterisk/pjsip.conf</code>:
<syntaxhighlight lang="ini">
[global]
[global]
type = global
type = global
user_agent = MyAsteriskPBX
realm = 192.168.2.107
realm = 192.168.2.107 ; Use your Asterisk server's IP or domain


; --- Transports ---
; --- Transports ---
Line 244: Line 176:
protocol = udp
protocol = udp
bind = 0.0.0.0:5060
bind = 0.0.0.0:5060
[transport-ws]
type = transport
protocol = ws
bind = 0.0.0.0:8088


[transport-wss]
[transport-wss]
Line 255: Line 182:
bind = 0.0.0.0:8089
bind = 0.0.0.0:8089


; --- WebRTC Endpoint Template ---
; --- WebRTC Template ---
; We create a template to avoid repeating settings
[webrtc-template](!)
[webrtc-endpoint-template](!)
type = endpoint
type = endpoint
disallow = all
disallow = all
allow = opus,ulaw,alaw
allow = opus,ulaw,alaw
context = internal-webrtc
context = internal-webrtc
auth = webrtc-auth
aors = webrtc-aor
; Require DTLS encryption for media
media_encryption = dtls
media_encryption = dtls
dtls_verify = fingerprint
dtls_verify = fingerprint
Line 273: Line 195:
use_avpf = yes
use_avpf = yes
ice_support = yes
ice_support = yes
media_use_received_transport = yes
rtcp_mux = yes
rtcp_mux = yes


; --- Define Users (101 and 102) ---
; --- User 101 ---
[101](webrtc-endpoint-template) ; Inherits from the template
[101](webrtc-template)
[webrtc-auth](+)
auth = 101-auth
aors = 101-aor
 
[101-auth]
type = auth
type = auth
auth_type = userpass
auth_type = userpass
username = 101
username = 101
password = your_strong_password_101
password = secret101
[webrtc-aor](+)
type = aor
max_contacts = 1


[102](webrtc-endpoint-template) ; Inherits from the template
[101-aor]
[webrtc-auth](+)
type = auth
auth_type = userpass
username = 102
password = your_strong_password_102
[webrtc-aor](+)
type = aor
type = aor
max_contacts = 1
max_contacts = 1
</pre>
</syntaxhighlight>


=== Step 5: Create a Basic Dialplan ===
=== Step 5: Dialplan ===
Edit `/etc/asterisk/extensions.conf` to allow the two users to call each other.
 
<pre>
; /etc/asterisk/extensions.conf


<code>/etc/asterisk/extensions.conf</code>:
<syntaxhighlight lang="ini">
[internal-webrtc]
[internal-webrtc]
exten => 101,1,NoOp(Call to 101)
exten => _1XX,1,Dial(PJSIP/${EXTEN})
same => n,Dial(PJSIP/101)
</syntaxhighlight>
same => n,Hangup()


exten => 102,1,NoOp(Call to 102)
== WebRTC Client Setup (sipML5) ==
same => n,Dial(PJSIP/102)
same => n,Hangup()
</pre>


== Part 3: Configuring the WebRTC Client (sipML5) ==
Using [https://www.doubango.org/sipml5/call.htm sipML5]:
Now, configure your WebRTC softphone to connect to Asterisk. This example uses the popular [https://www.doubango.org/sipml5/call.htm sipML5 online client].


=== Step 1: Basic Settings ===
'''Basic Settings:'''
Enter your user credentials on the main registration screen.
* Display Name: <code>101</code>
* '''Display Name:''' `101`
* Private Identity: <code>101</code>
* '''Private Identity:''' `101`
* Public Identity: <code>sip:101@192.168.2.107</code>
* '''Public Identity:''' `sip:101@192.168.2.107`
* Password: <code>secret101</code>
* '''Password:''' `your_strong_password_101`
* Realm: <code>192.168.2.107</code>
* '''Realm:''' `192.168.2.107`


=== Step 2: Expert Mode Settings ===
'''Expert Mode:'''
Click "Expert Mode" and configure the following:
* WebSocket Server URL: <code>wss://192.168.2.107:8089/ws</code>
* '''Disable Video:''' Checked (unless you need video).
* Enable RTCWeb Breaker: Checked
* '''Enable RTCWeb Breaker:''' Checked.
* Disable 3GPP Early IMS: Checked
* '''WebSocket Server URL:''' `wss://192.168.2.107:8089/ws` (Note the '''wss://''' prefix and the correct port).
* '''ICE Servers:''' `[]` (Leave empty or use `[{ "url": "stun:stun.l.google.com:19302" }]`)
* '''Disable 3GPP Early IMS:''' Checked.


=== Step 3: Trust the Certificate ===
{{Warning|1=Before login, open <code><nowiki>https://192.168.2.107:8089/ws</nowiki></code> in browser and accept the self-signed certificate.}}
Before attempting to register, you '''must''' open a new browser tab and navigate to `https://192.168.2.107:8089/ws`. Your browser will show a security warning because the certificate is self-signed. You must accept the risk and proceed. This action adds a temporary security exception, allowing the WebSocket connection to be established.


After completing these steps, you can return to the sipML5 tab and click "Login". Your client should register successfully, and calls will be encrypted and monitored by VoIPmonitor.
== Third-Party WebRTC Monitoring (--rtp-no-sig) ==


== Part 4: Monitoring Third-Party WebRTC Services Without Signaling Access ==
For monitoring WebRTC where you have no access to signaling (e.g., external providers).


In some scenarios, you may need to monitor WebRTC traffic from a third-party service where you cannot access the SIP signaling (for example, when monitoring calls from an external provider's WebRTC server). For these cases, VoIPmonitor offers the <code>--rtp-no-sig</code> command-line option, which allows you to capture and analyze RTP streams without processing signaling.
=== When to Use ===
 
* Third-party WebRTC service without signaling access
=== When to Use <code>--rtp-no-sig</code> ===
* Only media (RTP) stream is accessible
 
* Need QoS metrics without decryption
Use <code>--rtp-no-sig</code> when:
* You are monitoring WebRTC traffic from a third-party service where signaling is not accessible
* You have network access to the media (RTP) stream but not to the signaling (SIP/WS) packets
* You need to collect QoS metrics (MOS, packet loss, jitter) for WebRTC calls that use a single UDP port for all streams (BUNDLE)
 
=== How <code>--rtp-no-sig</code> Works ===
 
When you start the VoIPmonitor sniffer with <code>--rtp-no-sig</code>:
* VoIPmonitor creates CDRs (Call Detail Records) based entirely on RTP packets
* It identifies separate RTP streams using SSRC (Synchronization Source) identifiers, not STUN packets
* It detects calls when RTP packets start flowing and closes them when the stream stops
* Quality metrics (MOS, packet loss, jitter) are collected even without decryption


=== Configuration ===
=== Configuration ===


To use <code>--rtp-no-sig</code>, modify your VoIPmonitor startup command or service file:
<syntaxhighlight lang="bash">
 
# Start with --rtp-no-sig flag
<pre>
# Direct command-line usage:
voipmonitor --rtp-no-sig --interface eth0
voipmonitor --rtp-no-sig --interface eth0


# For systemd service, edit /etc/systemd/system/voipmonitor.service
# Or add to systemd service ExecStart line
# Add the --rtp-no-sig flag to the ExecStart line:
</syntaxhighlight>
ExecStart=/usr/sbin/voipmonitor -c /etc/voipmonitor.conf --rtp-no-sig --daemon --pidfile /var/run/voipmonitor/voipmonitor.pid
</pre>


=== Limitations Without Signaling ===
'''Behavior:'''
* CDRs created from RTP packets using SSRC identifiers
* QoS metrics (MOS, jitter, packet loss) collected without decryption
* Caller ID and call direction unavailable


When using <code>--rtp-no-sig</code>, certain features are unavailable or have limitations:
=== With Audio Replay ===
* Caller ID information is not available (no SIP INVITE to extract phone numbers)
* Call direction (incoming/outgoing) cannot be determined
* You must rely on IP addresses to group related calls
* Audio replay requires decryption (see below)


=== Decrypting DTLS-SRTP for Audio Replay ===
Combine <code>--rtp-no-sig</code> with SSL Key Logger for full monitoring:


If you need to replay the audio from captured WebRTC calls, you must decrypt the DTLS-encrypted media. This is achieved by installing the VoIPmonitor SSL Key Logger library on the WebRTC server. The keylogger captures DTLS session keys and forwards them to the VoIPmonitor sensor.
<syntaxhighlight lang="ini">
 
# On WebRTC server
For detailed instructions on setting up the SSL Key Logger, see the [[Tls]] documentation. The key points are:
 
1. The WebRTC server must have the <code>sslkeylog.so</code> library preloaded via <code>LD_PRELOAD</code>
2. The keylogger sends session keys to VoIPmonitor over UDP (or TCP for secure transport)
3. VoIPmonitor uses these keys to decrypt the DTLS handshake and derive SRTP master keys
 
Note: Quality of Service (QoS) metrics can be collected by VoIPmonitor even without decryption, allowing you to monitor call quality while maintaining the encrypted media's confidentiality.
 
=== Combining <code>--rtp-no-sig</code> with SSL Key Logger ===
 
For complete third-party WebRTC monitoring (CDRs + audio replay), combine both methods:
 
<pre>
# On the WebRTC server:
# Configure SSL Key Logger to send session keys to VoIPmonitor sensor
SSLKEYLOG_UDP='10.0.0.10:1234'
SSLKEYLOG_UDP='10.0.0.10:1234'
LD_PRELOAD='/usr/local/src/voipmonitor-git/tools/ssl_keylogger/sslkeylog.so'
LD_PRELOAD='/path/to/sslkeylog.so'


# On the VoIPmonitor sensor:
# On VoIPmonitor sensor
# Enable both RTP-only mode and key reception
ssl = yes
ssl_sessionkey_udp = yes
ssl_sessionkey_udp = yes
ssl_sessionkey_udp_port = 1234
ssl_sessionkey_udp_port = 1234
ssl = yes
</syntaxhighlight>
# Note: No ssl_ipport needed -- keys are applied dynamically


# Start VoIPmonitor with --rtp-no-sig:
== See Also ==
voipmonitor --rtp-no-sig --interface eth0
* [[Tls]] - Complete TLS/SRTP decryption guide
</pre>
* [[Sniffer_configuration]] - Full configuration reference
* [[Sniffing_modes]] - Deployment topologies


== AI Summary for RAG ==
== AI Summary for RAG ==
'''Summary:''' This guide provides a comprehensive tutorial on configuring VoIPmonitor to sniff encrypted WebRTC traffic, specifically SIP over Secure WebSockets (WSS) and DTLS-SRTP. CRITICAL PREREQUISITE: Before configuring SSL/TLS decryption, you MUST add the WebRTC port to the `sipport` parameter in `/etc/voipmonitor.conf`. By default, VoIPmonitor only listens on port 5060. For non-standard WebRTC ports (e.g., 8088 for WebSocket, 8089 for WSS), add them via `sipport = 5060,8088,8089`. In a probe/server setup, `sipport` on the probe controls which TCP packets are forwarded to the server. The guide details two decryption methods for WSS signaling: Method A (Private Key Decryption) which uses `ssl_ipport = IP:PORT /path/to/key.pem` but fails with TLS 1.3 or PFS ciphers, and Method B (SSL Key Logger - Universal Solution) which works with all cipher suites by injecting `sslkeylog.so` via `LD_PRELOAD` and sending session keys via UDP/TCP to VoIPmonitor with `ssl_sessionkey_udp=yes`. Method B configuration includes `SSLKEYLOG_UDP='IP:PORT'` on the PBX/SBC and `ssl_ipport = IP/mask:PORT` (with NO key file path) on VoIPmonitor. CIDR notation in `ssl_ipport` handles multiple hosts automatically. For client/server architectures (`packetbuffer_sender=yes`), keys must be sent to the central server IP, not localhost or the client sensor. For distributed mode and troubleshooting, see the complete [[Tls]] documentation. Part 2 provides a detailed Asterisk setup guide including generating self-signed certificates with OpenSSL, configuring WSS in `http.conf`, ICE in `rtp.conf`, and PJSIP endpoint configuration. Part 3 covers WebRTC client (sipML5) setup. Part 4 explains `--rtp-no-sig` for monitoring third-party WebRTC services without signaling access, combining with SSL Key Logger for audio replay, and using SSRC IDs for stream separation with BUNDLE.
 
'''Keywords:''' webrtc, wss, secure websocket, dtls, srtp, encrypted, tls, ssl, asterisk, pjsip, http.conf, rtp.conf, freeswitch, decryption, `ssl_ipport`, openssl, certificate, self-signed, `--rtp-no-sig`, `rtp-no-sig`, rtp only, no signaling, third party, sslkeylog, key logger, ld_preload, `SSLKEYLOG_UDP`, `ssl_sessionkey_udp`, `ssl_sessionkey_udp_port`, cidr notation, ip/mask, perfect forward secrecy, pfs, ecdhe, dhe, tls 1.3, client/server architecture, packetbuffer_sender, distributed mode, central server, multiple hosts, sipml5, dtls-srtp decryption, bundle, single udp port, qos, quality of service, `sipport`, non-standard port, tcp port, port configuration, probe/server architecture
'''Summary:''' Guide for monitoring encrypted WebRTC (WSS/DTLS-SRTP) with VoIPmonitor. CRITICAL: Add WebRTC ports to <code>sipport</code> (e.g., <code>sipport = 5060,8088,8089</code>) before configuring decryption. Two methods: Private Key (<code>ssl_ipport = IP:PORT /path/key.pem</code>) fails with TLS 1.3/PFS; SSL Key Logger works with all ciphers via <code>LD_PRELOAD</code> injection and <code>ssl_sessionkey_udp=yes</code>. For distributed mode, send keys to central server IP. Includes Asterisk WSS/PJSIP setup. Use <code>--rtp-no-sig</code> for third-party WebRTC without signaling access.
 
'''Keywords:''' webrtc, wss, secure websocket, dtls, srtp, encrypted, tls, ssl, asterisk, pjsip, freeswitch, decryption, ssl_ipport, sslkeylog, ld_preload, ssl_sessionkey_udp, sipport, rtp-no-sig, pfs, tls 1.3, distributed mode, 8088, 8089
 
'''Key Questions:'''
'''Key Questions:'''
* Why is VoIPmonitor not detecting WebRTC calls on a non-standard TCP port?
* How do I monitor encrypted WebRTC calls with VoIPmonitor?
* How do I configure the sipport parameter for WebRTC on port 8088 or 8089?
* Why is VoIPmonitor not detecting WebRTC traffic?
* What is the sipport parameter and why is it required for WebRTC?
* How do I configure sipport for WebRTC ports 8088/8089?
* Do I need to add the WebRTC port to sipport if using SSL/TLS decryption?
* What is the difference between Private Key and SSL Key Logger decryption methods?
* How do I monitor WebSocket (WS) vs Secure WebSocket (WSS) with VoIPmonitor?
* How do I configure Asterisk for secure WebRTC?
* What sipport configuration is needed on the probe vs server in distributed mode?
* How does --rtp-no-sig work for third-party WebRTC monitoring?
* How can I monitor encrypted WebRTC calls?
* How do I decrypt DTLS-SRTP for audio replay?
* How do I configure VoIPmonitor to decrypt WSS and DTLS-SRTP traffic?
* What is the SSL Key Logger method and when should I use it instead of private keys?
* How do I use LD_PRELOAD to inject sslkeylog.so into Asterisk or FreeSWITCH?
* How do I configure ssl_sessionkey_udp for receiving session keys?
* What ssl_ipport format is required for SSL Key Logger (no key file path)?
* Can I use CIDR notation in ssl_ipport for multiple PBX hosts?
* How does SSL Key Logger work in client/server distributed architecture?
* What Asterisk configuration is needed for secure WebRTC?
* How do I set up a PJSIP endpoint for a WebRTC client?
* Why is my WebRTC client not connecting over WSS?
* What is the purpose of `dtls_cert_file` in `pjsip.conf`?
* How to configure sipML5 for a secure connection to Asterisk?
* How do I monitor WebRTC traffic from a third-party service without signaling access?
* What does the `--rtp-no-sig` command-line option do?
* How can I capture WebRTC RTP streams when SIP signaling is not available?
* What is the SSL Key Logger and how does it help decrypt WebRTC media?
* How do I use SSL Key Logger to replay audio from encrypted WebRTC calls?

Latest revision as of 16:50, 8 January 2026


This guide covers monitoring encrypted WebRTC traffic with VoIPmonitor, including SIP over Secure WebSocket (WSS) and DTLS-SRTP media encryption.

Overview

WebRTC requires encrypted transport for both signaling and media:

  • WSS (Secure WebSocket): SIP signaling encrypted with TLS
  • DTLS-SRTP: Media (RTP) encrypted via DTLS key negotiation

VoIPmonitor can decrypt both layers using either a private TLS key or the SSL Key Logger method.

Prerequisites: Configure sipport

⚠️ Warning: VoIPmonitor only monitors port 5060 by default. You must add WebRTC ports to sipport or traffic will be ignored.

Edit /etc/voipmonitor.conf: 

# Add WebRTC ports (WS=8088, WSS=8089)
sipport = 5060,8088,8089

# Or use port ranges
sipport = 5060,8080-8090

Restart after changes: systemctl restart voipmonitor

ℹ️ Note: In probe/server architecture, configure sipport on both probe and server.

Decryption Methods

Choose based on your environment:

Method When to Use Limitations
A: Private Key Development/testing, RSA ciphers Fails with TLS 1.3/PFS (DHE/ECDHE)
B: SSL Key Logger Production, TLS 1.3, PFS, distributed setups Requires library injection on PBX

Method A: Private Key

# /etc/voipmonitor.conf
ssl = yes
ssl_ipport = 192.168.2.107:8089 /etc/asterisk/keys/asterisk.pem

# Or use CIDR for multiple hosts
ssl_ipport = 192.168.2.0/24:8089 /path/to/key.pem

Method B: SSL Key Logger

Works with ALL cipher suites including TLS 1.3 and PFS.

1. Compile the library: 

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

2. Configure PBX to send session keys:

For Asterisk (create /etc/default/asterisk-ssl): 

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

For FreeSWITCH, add to systemd service: 

ExecStart=env SSLKEYLOG_UDP='127.0.0.1:1234' LD_PRELOAD='/path/to/sslkeylog.so' /usr/bin/freeswitch ...

3. Configure VoIPmonitor: 

# /etc/voipmonitor.conf
ssl = yes
ssl_ipport = 192.168.2.0/24:8089    # NO key file path!
ssl_sessionkey_udp = yes
ssl_sessionkey_udp_port = 1234

# Add loopback if sending keys locally
interface = eth0,lo

💡 Tip: For distributed mode (packetbuffer_sender=yes), send keys to the central server IP, not localhost.

For complete SSL Key Logger documentation, see TLS Decryption.

Asterisk Configuration

Step 1: Generate TLS Certificates

mkdir -p /etc/asterisk/keys && cd /etc/asterisk/keys

# Create CA
openssl genrsa -des3 -out ca.key 4096
openssl req -new -x509 -days 3650 -key ca.key -out ca.crt

# Create server certificate
openssl genrsa -out key.pem 2048
openssl req -new -key key.pem -out server.csr
openssl x509 -req -days 3650 -in server.csr -CA ca.crt -CAkey ca.key -set_serial 01 -out cert.crt

# Combine for Asterisk
cat key.pem cert.crt > asterisk.pem

Step 2: Configure HTTP Server

/etc/asterisk/http.conf: 

[general]
enabled = yes
bindaddr = 0.0.0.0
bindport = 8088          ; WS (unencrypted)
tlsenable = yes
tlsbindaddr = 0.0.0.0:8089  ; WSS (encrypted)
tlscertfile = /etc/asterisk/keys/asterisk.pem
tlscipher = AES128-SHA

Step 3: Configure RTP

/etc/asterisk/rtp.conf: 

[general]
icesupport = yes
; stunaddr = stun.l.google.com:19302

Step 4: Configure PJSIP

Disable old chan_sip in /etc/asterisk/modules.conf: 

noload => chan_sip.so

/etc/asterisk/pjsip.conf: 

[global]
type = global
realm = 192.168.2.107

; --- Transports ---
[transport-udp]
type = transport
protocol = udp
bind = 0.0.0.0:5060

[transport-wss]
type = transport
protocol = wss
bind = 0.0.0.0:8089

; --- WebRTC Template ---
[webrtc-template](!)
type = endpoint
disallow = all
allow = opus,ulaw,alaw
context = internal-webrtc
media_encryption = dtls
dtls_verify = fingerprint
dtls_cert_file = /etc/asterisk/keys/asterisk.pem
dtls_ca_file = /etc/asterisk/keys/ca.crt
dtls_setup = actpass
use_avpf = yes
ice_support = yes
rtcp_mux = yes

; --- User 101 ---
[101](webrtc-template)
auth = 101-auth
aors = 101-aor

[101-auth]
type = auth
auth_type = userpass
username = 101
password = secret101

[101-aor]
type = aor
max_contacts = 1

Step 5: Dialplan

/etc/asterisk/extensions.conf: 

[internal-webrtc]
exten => _1XX,1,Dial(PJSIP/${EXTEN})

WebRTC Client Setup (sipML5)

Using sipML5:

Basic Settings:

  • Display Name: 101
  • Private Identity: 101
  • Public Identity: sip:101@192.168.2.107
  • Password: secret101
  • Realm: 192.168.2.107

Expert Mode:

  • WebSocket Server URL: wss://192.168.2.107:8089/ws
  • Enable RTCWeb Breaker: Checked
  • Disable 3GPP Early IMS: Checked

⚠️ Warning: Before login, open https://192.168.2.107:8089/ws in browser and accept the self-signed certificate.

Third-Party WebRTC Monitoring (--rtp-no-sig)

For monitoring WebRTC where you have no access to signaling (e.g., external providers).

When to Use

  • Third-party WebRTC service without signaling access
  • Only media (RTP) stream is accessible
  • Need QoS metrics without decryption

Configuration

# Start with --rtp-no-sig flag
voipmonitor --rtp-no-sig --interface eth0

# Or add to systemd service ExecStart line

Behavior:

  • CDRs created from RTP packets using SSRC identifiers
  • QoS metrics (MOS, jitter, packet loss) collected without decryption
  • Caller ID and call direction unavailable

With Audio Replay

Combine --rtp-no-sig with SSL Key Logger for full monitoring: 

# On WebRTC server
SSLKEYLOG_UDP='10.0.0.10:1234'
LD_PRELOAD='/path/to/sslkeylog.so'

# On VoIPmonitor sensor
ssl = yes
ssl_sessionkey_udp = yes
ssl_sessionkey_udp_port = 1234

See Also

AI Summary for RAG

Summary: Guide for monitoring encrypted WebRTC (WSS/DTLS-SRTP) with VoIPmonitor. CRITICAL: Add WebRTC ports to sipport (e.g., sipport = 5060,8088,8089) before configuring decryption. Two methods: Private Key (ssl_ipport = IP:PORT /path/key.pem) fails with TLS 1.3/PFS; SSL Key Logger works with all ciphers via LD_PRELOAD injection and ssl_sessionkey_udp=yes. For distributed mode, send keys to central server IP. Includes Asterisk WSS/PJSIP setup. Use --rtp-no-sig for third-party WebRTC without signaling access.

Keywords: webrtc, wss, secure websocket, dtls, srtp, encrypted, tls, ssl, asterisk, pjsip, freeswitch, decryption, ssl_ipport, sslkeylog, ld_preload, ssl_sessionkey_udp, sipport, rtp-no-sig, pfs, tls 1.3, distributed mode, 8088, 8089

Key Questions:

  • How do I monitor encrypted WebRTC calls with VoIPmonitor?
  • Why is VoIPmonitor not detecting WebRTC traffic?
  • How do I configure sipport for WebRTC ports 8088/8089?
  • What is the difference between Private Key and SSL Key Logger decryption methods?
  • How do I configure Asterisk for secure WebRTC?
  • How does --rtp-no-sig work for third-party WebRTC monitoring?
  • How do I decrypt DTLS-SRTP for audio replay?
Retrieved from "https://www.voipmonitor.org/doc/index.php?title=WebRTC&oldid=10171"