WebRTC

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.

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.

Critical Prerequisite: Configure sipport

Before configuring SSL/TLS decryption, you must tell VoIPmonitor which ports to monitor for WebRTC traffic. This is done using the sipport 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

Edit /etc/voipmonitor.conf:

# Add the WebRTC ports used by your PBX
# Multiple ports can be separated by commas
sipport = 5060,8088,8089

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

Why This Is Required

The sipport 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 8088 to sipport
• Secure WebSocket (WSS): If using encrypted WebSocket on port 8089, add 8089 to sipport
• Both protocols together: Add both ports: sipport = 5060,8088,8089

Restart the Service

After changing sipport, restart VoIPmonitor:

systemctl restart voipmonitor

Client/Server Architecture Note

In a probe/server setup:

• The sipport 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 sipport configuration to properly parse the forwarded traffic

For full details on the sipport 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:

# /etc/voipmonitor.conf

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

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:

# 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

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:

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

1. Compile sslkeylog.so:

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

2. Configure PBX/SBC to Send Session Keys:

For Asterisk (via systemd):

# /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:

Edit /lib/systemd/system/freeswitch.service:

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

3. Configure VoIPmonitor to Receive Keys:

In /etc/voipmonitor.conf:

# /etc/voipmonitor.conf

ssl = yes

# 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_port = 1234

Critical Configuration Note:

• When using the SSL Key Logger, ssl_ipport 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 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:

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:

# On PBX/SBC - send keys to CENTRAL SERVER IP
SSLKEYLOG_UDP='192.168.1.100:1234'

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).

Part 2: Configuring Asterisk for Secure WebRTC

This section details the full configuration for Asterisk, from generating keys to setting up PJSIP endpoints.

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.

# Create a directory for your keys
mkdir -p /etc/asterisk/keys
cd /etc/asterisk/keys

# 1. Create a private key for your local Certificate Authority (CA)
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

# 3. Create a private key for the Asterisk server
openssl genrsa -out key.pem 2048

# 4. Create a certificate signing request (CSR) for the Asterisk server
openssl req -new -key key.pem -out req-sip_server.csr

# 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

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.

; /etc/asterisk/http.conf

[general]
enabled = yes
bindaddr = 0.0.0.0
bindport = 8088 ; Port for unencrypted WS

tlsenable = yes
tlsbindaddr = 0.0.0.0:8089 ; Port for encrypted WSS
tlscertfile = /etc/asterisk/keys/asterisk.pem
tlscipher = AES128-SHA

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.

; /etc/asterisk/rtp.conf

[general]
icesupport = yes
; You can optionally configure a public STUN server
; stunaddr = stun.l.google.com:19302

Step 4: Configure PJSIP for WebRTC

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:

; /etc/asterisk/modules.conf
noload => chan_sip.so

Next, configure /etc/asterisk/pjsip.conf:

; /etc/asterisk/pjsip.conf

[global]
type = global
user_agent = MyAsteriskPBX
realm = 192.168.2.107 ; Use your Asterisk server's IP or domain

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

[transport-ws]
type = transport
protocol = ws
bind = 0.0.0.0:8088

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

; --- WebRTC Endpoint Template ---
; We create a template to avoid repeating settings
[webrtc-endpoint-template](!)
type = endpoint
disallow = all
allow = opus,ulaw,alaw
context = internal-webrtc
auth = webrtc-auth
aors = webrtc-aor

; Require DTLS encryption for media
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
media_use_received_transport = yes
rtcp_mux = yes

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

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

Step 5: Create a Basic Dialplan

Edit /etc/asterisk/extensions.conf to allow the two users to call each other.

; /etc/asterisk/extensions.conf

[internal-webrtc]
exten => 101,1,NoOp(Call to 101)
 same => n,Dial(PJSIP/101)
 same => n,Hangup()

exten => 102,1,NoOp(Call to 102)
 same => n,Dial(PJSIP/102)
 same => n,Hangup()

Part 3: Configuring the WebRTC Client (sipML5)

Now, configure your WebRTC softphone to connect to Asterisk. This example uses the popular sipML5 online client.

Step 1: Basic Settings

Enter your user credentials on the main registration screen.

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

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

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.

Part 4: Monitoring Third-Party WebRTC Services Without Signaling Access

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 --rtp-no-sig command-line option, which allows you to capture and analyze RTP streams without processing signaling.

When to Use --rtp-no-sig

Use --rtp-no-sig 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 --rtp-no-sig Works

When you start the VoIPmonitor sniffer with --rtp-no-sig:

• 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

To use --rtp-no-sig, modify your VoIPmonitor startup command or service file:

# Direct command-line usage:
voipmonitor --rtp-no-sig --interface eth0

# For systemd service, edit /etc/systemd/system/voipmonitor.service
# 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

Limitations Without Signaling

When using --rtp-no-sig, certain features are unavailable or have limitations:

• 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

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.

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 sslkeylog.so library preloaded via LD_PRELOAD 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 --rtp-no-sig with SSL Key Logger

For complete third-party WebRTC monitoring (CDRs + audio replay), combine both methods:

# On the WebRTC server:
# Configure SSL Key Logger to send session keys to VoIPmonitor sensor
SSLKEYLOG_UDP='10.0.0.10:1234'
LD_PRELOAD='/usr/local/src/voipmonitor-git/tools/ssl_keylogger/sslkeylog.so'

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

# Start VoIPmonitor with --rtp-no-sig:
voipmonitor --rtp-no-sig --interface eth0

AI Summary for RAG

Summary: Guide for monitoring encrypted WebRTC (WSS/DTLS-SRTP) with VoIPmonitor. CRITICAL: Add WebRTC ports to sipport parameter (e.g., sipport = 5060,8088,8089) before configuring decryption. Two decryption methods: Method A (Private Key) uses ssl_ipport = IP:PORT /path/to/key.pem but fails with TLS 1.3/PFS; Method B (SSL Key Logger) works with all ciphers by injecting sslkeylog.so via LD_PRELOAD and sending keys to VoIPmonitor (ssl_sessionkey_udp=yes). For distributed mode (packetbuffer_sender=yes), send keys to central server IP. Includes Asterisk WSS/PJSIP setup and --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, third party, pfs, tls 1.3, distributed mode

Key Questions:

• How do I monitor encrypted WebRTC calls with VoIPmonitor?
• Why is VoIPmonitor not detecting WebRTC calls on a non-standard port?
• How do I configure sipport for WebRTC ports 8088/8089?
• What is the SSL Key Logger method and when to use it?
• How do I configure ssl_sessionkey_udp for receiving session keys?
• What Asterisk configuration is needed for secure WebRTC?
• How does --rtp-no-sig work for third-party WebRTC monitoring?
• How do I decrypt DTLS-SRTP for audio replay?