WebRTC: Difference between revisions

From VoIPmonitor.org
(Add Key Question about single UDP port STUN-based WebRTC capture)
(Rewrite: konsolidace, lepší struktura, tabulka pro srovnání metod, warning/note boxy, See Also sekce)
 
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
 
VoIPmonitor can decrypt both layers using either a private TLS key or the SSL Key Logger method.


<kroki lang="mermaid">
<kroki lang="mermaid">
%%{init: {'flowchart': {'nodeSpacing': 15, 'rankSpacing': 30}}}%%
flowchart LR
flowchart LR
     subgraph Browser["WebRTC Client"]
     subgraph Browser["WebRTC Client"]
         WC[Web Browser]
         WC[Web Browser]
     end
     end
     subgraph PBX["Asterisk PBX"]
     subgraph PBX["Asterisk PBX"]
         WSS[WSS :8089]
         WSS[WSS :8089]
         SRTP[DTLS-SRTP]
         SRTP[DTLS-SRTP]
     end
     end
     subgraph VM["VoIPmonitor"]
     subgraph VM["VoIPmonitor"]
         CAP[Packet Capture]
         CAP[Capture]
         DEC[TLS Decryption]
         DEC[Decrypt]
         CDR[CDR Generation]
         CDR[CDR]
     end
     end
 
     WC -->|"SIP/WSS"| WSS
     WC -->|"SIP over WSS<br/>(TLS encrypted)"| WSS
     WC -->|"Media"| SRTP
     WC -->|"Media<br/>(DTLS-SRTP)"| SRTP
     WSS -.->|"mirror"| CAP
 
     SRTP -.->|"mirror"| CAP
     WSS -.->|"mirrored traffic"| CAP
     CAP --> DEC --> CDR
     SRTP -.->|"mirrored traffic"| CAP
 
     CAP --> DEC
    DEC --> CDR
</kroki>
</kroki>


== Critical Prerequisite: Configure sipport ==
== Prerequisites: Configure sipport ==
 
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.
 
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.


=== 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>:


<syntaxhighlight lang="ini">
<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
</syntaxhighlight>
 
=== Why This Is Required ===
 
''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.''
 
* '''Basic WebSocket (WS):''' If using unencrypted WebSocket on port 8088, add <code>8088</code> to <code>sipport</code>
* '''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 ===
 
After changing <code>sipport</code>, restart VoIPmonitor:
 
<syntaxhighlight lang="bash">
systemctl restart voipmonitor
</syntaxhighlight>
</syntaxhighlight>


=== Client/Server Architecture Note ===
Restart after changes: <code>systemctl restart voipmonitor</code>


In a probe/server setup:
{{Note|1=In probe/server architecture, configure <code>sipport</code> on '''both''' probe and server.}}
* 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]].
== Decryption Methods ==


== Part 1: Configuring VoIPmonitor to Decrypt TLS ==
Choose based on your environment:
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) ===
{| class="wikitable"
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.
|-
! 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
|}


In <code>/etc/voipmonitor.conf</code>, enable the SSL module and provide the path to the private key:
=== Method A: Private Key ===


<syntaxhighlight lang="ini">
<syntaxhighlight lang="ini">
# /etc/voipmonitor.conf
# /etc/voipmonitor.conf
ssl = yes
ssl = yes
# Point to the private key used by your PBX.
# Format: <IP of PBX> : <WSS Port> /path/to/private.key
#
# Example for this guide:
ssl_ipport = 192.168.2.107:8089 /etc/asterisk/keys/asterisk.pem
ssl_ipport = 192.168.2.107:8089 /etc/asterisk/keys/asterisk.pem
</syntaxhighlight>


'''Important Limitations:'''
# Or use CIDR for multiple hosts
* This method will NOT work if the PBX uses TLS 1.3 or Perfect Forward Secrecy (PFS) ciphers (DHE/ECDHE)
ssl_ipport = 192.168.2.0/24:8089 /path/to/key.pem
* 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:
<syntaxhighlight lang="ini">
# 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
</syntaxhighlight>
</syntaxhighlight>


''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 ===


=== Method B: SSL Key Logger (Universal Solution) ===
Works with ALL cipher suites including TLS 1.3 and PFS.


If any of the following apply to your environment, use the SSL Key Logger method instead:
'''1. Compile the library:'''
* 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 (<code>sslkeylog.so</code>) into your PBX/SBC process. This library captures TLS session keys dynamically and forwards them to VoIPmonitor via UDP/TCP.
 
'''Advantages:'''
* 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 <code>ssl_ipport</code>
* Works seamlessly in client/server architectures
 
'''Configuration Overview:'''
 
1. '''Compile sslkeylog.so''':
<syntaxhighlight lang="bash">
<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
</syntaxhighlight>
</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>):
<syntaxhighlight lang="bash">
<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'
</syntaxhighlight>
</syntaxhighlight>


For FreeSWITCH:
For FreeSWITCH, add to systemd service:
 
Edit <code>/lib/systemd/system/freeswitch.service</code>:
<syntaxhighlight lang="bash">
<syntaxhighlight lang="bash">
ExecStart=env SSLKEYLOG_UDP='127.0.0.1:1234' LD_PRELOAD='/usr/local/src/voipmonitor-git/tools/ssl_keylogger/sslkeylog.so' /usr/bin/freeswitch ...
ExecStart=env SSLKEYLOG_UDP='127.0.0.1:1234' LD_PRELOAD='/path/to/sslkeylog.so' /usr/bin/freeswitch ...
</syntaxhighlight>
</syntaxhighlight>


3. '''Configure VoIPmonitor to Receive Keys''':
'''3. Configure VoIPmonitor:'''
 
In <code>/etc/voipmonitor.conf</code>:
<syntaxhighlight lang="ini">
<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
# Add loopback if sending keys locally
interface = eth0,lo
</syntaxhighlight>
</syntaxhighlight>


'''Critical Configuration Note:'''
{{Tip|1=For distributed mode (<code>packetbuffer_sender=yes</code>), send keys to the '''central server IP''', not localhost.}}
* When using the SSL Key Logger, <code>ssl_ipport</code> '''must only''' contain IP:port (or IP/mask:port), NO key file path
* The port (8089) must match your PBX/SBC WSS port configuration
* Add <code>lo</code> (loopback) to <code>interface</code> if sending keys to 127.0.0.1: <code>interface = eth0,lo</code>
* Restart both PBX/SBC and VoIPmonitor after configuration
 
'''Client/Server Architecture:'''
 
If using <code>packetbuffer_sender=yes</code> (distributed mode), session keys from the PBX/SBC '''must''' be sent to the central server's IP address, not localhost or the client sensor:
<syntaxhighlight lang="bash">
# On PBX/SBC - send keys to CENTRAL SERVER IP
SSLKEYLOG_UDP='192.168.1.100:1234'
</syntaxhighlight>


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.


<syntaxhighlight lang="bash">
<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
 
# 5. Sign the server certificate with your CA
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
</syntaxhighlight>
</syntaxhighlight>


=== Step 2: Configure Asterisk's HTTP Server for WSS ===
=== Step 2: Configure HTTP Server ===
Edit <code>/etc/asterisk/http.conf</code> to enable the built-in web server and activate TLS for the WebSocket transport.


<code>/etc/asterisk/http.conf</code>:
<syntaxhighlight lang="ini">
<syntaxhighlight lang="ini">
; /etc/asterisk/http.conf
[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
</syntaxhighlight>
</syntaxhighlight>


=== Step 3: Configure RTP Settings ===
=== Step 3: Configure RTP ===
Edit <code>/etc/asterisk/rtp.conf</code> and ensure ICE support is enabled, which is essential for WebRTC clients to traverse NAT.


<code>/etc/asterisk/rtp.conf</code>:
<syntaxhighlight lang="ini">
<syntaxhighlight lang="ini">
; /etc/asterisk/rtp.conf
[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
</syntaxhighlight>
</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 <code>/etc/asterisk/modules.conf</code> to avoid conflicts:
Disable old chan_sip in <code>/etc/asterisk/modules.conf</code>:
<syntaxhighlight lang="ini">
<syntaxhighlight lang="ini">
; /etc/asterisk/modules.conf
noload => chan_sip.so
noload => chan_sip.so
</syntaxhighlight>
</syntaxhighlight>


Next, configure <code>/etc/asterisk/pjsip.conf</code>:
<code>/etc/asterisk/pjsip.conf</code>:
<syntaxhighlight lang="ini">
<syntaxhighlight lang="ini">
; /etc/asterisk/pjsip.conf
[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 274: 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 285: 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 303: 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
</syntaxhighlight>
</syntaxhighlight>


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


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


== Part 3: Configuring the WebRTC Client (sipML5) ==
== WebRTC Client Setup (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 ===
Enter your user credentials on the main registration screen.
* '''Display Name:''' <code>101</code>
* '''Private Identity:''' <code>101</code>
* '''Public Identity:''' <code>sip:101@192.168.2.107</code>
* '''Password:''' <code>your_strong_password_101</code>
* '''Realm:''' <code>192.168.2.107</code>
 
=== Step 2: Expert Mode Settings ===
Click "Expert Mode" and configure the following:
* '''Disable Video:''' Checked (unless you need video).
* '''Enable RTCWeb Breaker:''' Checked.
* '''WebSocket Server URL:''' <code>wss://192.168.2.107:8089/ws</code> (Note the '''wss://''' prefix and the correct port).
* '''ICE Servers:''' <code>[]</code> (Leave empty or use <code>[{ "url": "stun:stun.l.google.com:19302" }]</code>)
* '''Disable 3GPP Early IMS:''' Checked.


=== Step 3: Trust the Certificate ===
Using [https://www.doubango.org/sipml5/call.htm sipML5]:
Before attempting to register, you '''must''' open a new browser tab and navigate to <code>https://192.168.2.107:8089/ws</code>. 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.
'''Basic Settings:'''
* Display Name: <code>101</code>
* Private Identity: <code>101</code>
* Public Identity: <code>sip:101@192.168.2.107</code>
* Password: <code>secret101</code>
* Realm: <code>192.168.2.107</code>


== Part 4: Monitoring Third-Party WebRTC Services Without Signaling Access ==
'''Expert Mode:'''
* WebSocket Server URL: <code>wss://192.168.2.107:8089/ws</code>
* Enable RTCWeb Breaker: Checked
* Disable 3GPP Early IMS: Checked


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.
{{Warning|1=Before login, open <code><nowiki>https://192.168.2.107:8089/ws</nowiki></code> in browser and accept the self-signed certificate.}}


=== When to Use <code>--rtp-no-sig</code> ===
== Third-Party WebRTC Monitoring (--rtp-no-sig) ==


Use <code>--rtp-no-sig</code> when:
For monitoring WebRTC where you have no access to signaling (e.g., external providers).
* 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 to Use ===
 
* Third-party WebRTC service without signaling access
When you start the VoIPmonitor sniffer with <code>--rtp-no-sig</code>:
* Only media (RTP) stream is accessible
* VoIPmonitor creates CDRs (Call Detail Records) based entirely on RTP packets
* Need QoS metrics without decryption
* 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">
<syntaxhighlight lang="bash">
# Direct command-line usage:
# Start with --rtp-no-sig flag
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:
ExecStart=/usr/sbin/voipmonitor -c /etc/voipmonitor.conf --rtp-no-sig --daemon --pidfile /var/run/voipmonitor/voipmonitor.pid
</syntaxhighlight>
</syntaxhighlight>


=== 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:
 
<syntaxhighlight lang="bash">
# 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
</syntaxhighlight>
* [[Sniffer_configuration]] - Full configuration reference
* [[Sniffing_modes]] - Deployment topologies


== AI Summary for RAG ==
== AI Summary for RAG ==
'''Summary:''' Guide for monitoring encrypted WebRTC (WSS/DTLS-SRTP) with VoIPmonitor. CRITICAL: Add WebRTC ports to <code>sipport</code> parameter (e.g., <code>sipport = 5060,8088,8089</code>) before configuring decryption. Two decryption methods: Method A (Private Key) uses <code>ssl_ipport = IP:PORT /path/to/key.pem</code> but fails with TLS 1.3/PFS; Method B (SSL Key Logger) works with all ciphers by injecting <code>sslkeylog.so</code> via <code>LD_PRELOAD</code> and sending keys to VoIPmonitor (<code>ssl_sessionkey_udp=yes</code>). For distributed mode (<code>packetbuffer_sender=yes</code>), send keys to central server IP. Includes Asterisk WSS/PJSIP setup and <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, third party, pfs, tls 1.3, distributed mode
'''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:'''
* How do I monitor encrypted WebRTC calls with VoIPmonitor?
* How do I monitor encrypted WebRTC calls with VoIPmonitor?
* Why is VoIPmonitor not detecting WebRTC calls on a non-standard port?
* Why is VoIPmonitor not detecting WebRTC traffic?
* How do I configure sipport for WebRTC ports 8088/8089?
* How do I configure sipport for WebRTC ports 8088/8089?
* What is the SSL Key Logger method and when to use it?
* What is the difference between Private Key and SSL Key Logger decryption methods?
* How do I configure ssl_sessionkey_udp for receiving session keys?
* How do I configure Asterisk for secure WebRTC?
* What Asterisk configuration is needed for secure WebRTC?
* How does --rtp-no-sig work for third-party WebRTC monitoring?
* How does <code>--rtp-no-sig</code> work for third-party WebRTC monitoring?
* How do I decrypt DTLS-SRTP for audio replay?
* How do I decrypt DTLS-SRTP for audio replay?
* Can VoIPmonitor capture WebRTC RTP streams when the server uses a single UDP port for all streams with STUN-based separation?

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"