Brekeke SBC TLS Decryption

This guide covers setting up TLS decryption for Brekeke SBC (Java-based) with VoIPmonitor using the jSSLKeyLog Java agent. For C-based PBXs (Asterisk, FreeSWITCH, Kamailio), see TLS: SSL Key Logger.

Overview

Brekeke SBC runs on Apache Tomcat (Java). The standard VoIPmonitor C-based sslkeylog.so library (LD_PRELOAD) does not work with Java applications. Instead, use jSSLKeyLog — a Java agent that intercepts TLS session keys at the JVM level.

Component	Role
jSSLKeyLog (Java agent)	Intercepts TLS session keys from Brekeke's JVM and writes them to a log file
Key forwarder script	Sends each key line via UDP to VoIPmonitor in real time
VoIPmonitor (`ssl_sessionkey_udp`)	Receives session keys on a UDP port and uses them to decrypt captured SIP TLS traffic

Step 1: Install jSSLKeyLog on Brekeke Host

mkdir -p /opt/jsslkeylog
cd /opt/jsslkeylog
wget https://github.com/jsslkeylog/jsslkeylog/releases/download/v1.4.0/jSSLKeyLog-1.4.zip
unzip jSSLKeyLog-1.4.zip

Create the key log file:

: > /opt/jsslkeylog/sslkeys.log

Step 2: Configure Tomcat to Load the Java Agent

Create /opt/tomcat/bin/setenv.sh:

#!/bin/sh
export JAVA_HOME=/usr/lib/jvm/java-11-openjdk-amd64
export JRE_HOME=/usr/lib/jvm/java-11-openjdk-amd64
export JAVA_TOOL_OPTIONS="-javaagent:/opt/jsslkeylog/jSSLKeyLog.jar=/opt/jsslkeylog/sslkeys.log"

chmod +x /opt/tomcat/bin/setenv.sh

ℹ️ Note: Adjust JAVA_HOME to match your Java installation. Check with java -version and update-alternatives --list java.

Step 3: Create Persistent Tomcat Service

Create /etc/systemd/system/tomcat.service:

[Unit]
Description=Apache Tomcat for Brekeke SIP Server
After=network.target

[Service]
Type=forking
Environment=JAVA_HOME=/usr/lib/jvm/java-11-openjdk-amd64
Environment=JRE_HOME=/usr/lib/jvm/java-11-openjdk-amd64
Environment=JAVA_TOOL_OPTIONS=-javaagent:/opt/jsslkeylog/jSSLKeyLog.jar=/opt/jsslkeylog/sslkeys.log
ExecStart=/opt/tomcat/bin/startup.sh
ExecStop=/opt/tomcat/bin/shutdown.sh
User=root
Group=root
Restart=on-failure
RestartSec=5

[Install]
WantedBy=multi-user.target

systemctl daemon-reload
systemctl enable tomcat
systemctl restart tomcat

Verify:

systemctl status tomcat --no-pager
ss -lntp | egrep '18080|5060|5061'
curl -I http://127.0.0.1:18080/sip/gate

Step 4: Create Key Forwarder Service

⚠️ Warning: Do NOT use the bulk forwarder tail -F sslkeys.log | socat - UDP:IP:1234. This sends all key lines in a single UDP packet which VoIPmonitor cannot parse. Use the line-by-line forwarder below — it sends one key per UDP packet as required.

Create /usr/local/bin/brekeke-key-forwarder.sh:

#!/bin/bash
tail -F /opt/jsslkeylog/sslkeys.log | while read line; do
  echo "$line" | socat - UDP:VOIPMONITOR_IP:1234
done

Replace VOIPMONITOR_IP with your VoIPmonitor server's IP address.

chmod +x /usr/local/bin/brekeke-key-forwarder.sh

Create /etc/systemd/system/brekeke-key-forwarder.service:

[Unit]
Description=Brekeke TLS Key Forwarder to VoIPmonitor
After=network.target tomcat.service
Requires=tomcat.service

[Service]
Type=simple
ExecStart=/usr/local/bin/brekeke-key-forwarder.sh
Restart=always
RestartSec=3
User=root
Group=root

[Install]
WantedBy=multi-user.target

systemctl daemon-reload
systemctl enable brekeke-key-forwarder
systemctl start brekeke-key-forwarder

Step 5: Configure VoIPmonitor

Add to /etc/voipmonitor.conf:

ssl = yes
ssl_ipport = BREKEKE_IP:5061
ssl_sessionkey_udp = yes
ssl_sessionkey_udp_port = 1234
sipport = 5060,5061

Replace BREKEKE_IP with your Brekeke SBC's IP address. Add multiple ssl_ipport lines if you have multiple SBCs.

ℹ️ Note: Port 5061 must be listed in both ssl_ipport (for TLS decryption) and sipport (for SIP processing). If you also have non-encrypted SIP on port 5061, see ssl_enable_redirection_unencrypted_sip_content.

systemctl restart voipmonitor

Step 6: Validation

Run these checks in order:

#	Check	Command	Expected Result
1	Brekeke GUI is up	`curl -I http://127.0.0.1:18080/sip/gate`	HTTP 200
2	SIP ports listening	`ss -lntp \| egrep '5060\|5061'`	5060 and 5061 listed
3	Keys being generated	`tail -f /opt/jsslkeylog/sslkeys.log`	New lines appear during TLS calls
4	Keys reaching VoIPmonitor	`tcpdump -A -i any -n udp port 1234`	Readable key lines visible
5	VoIPmonitor processing calls	`tail -f /var/log/syslog \| grep calls`	Call count increasing
6	CDRs in GUI	Check VoIPmonitor GUI CDR list	TLS calls appear with decoded SIP details

Troubleshooting

No Keys Being Generated

# Verify the Java agent is loaded
ps -efww | grep 'com.brekeke' | grep -v grep
# Check JAVA_TOOL_OPTIONS is set in the running process
tr '\0' '\n' < /proc/$(pgrep -f com.brekeke)/environ | grep JAVA_TOOL_OPTIONS
# Verify setenv.sh
cat /opt/tomcat/bin/setenv.sh

If JAVA_TOOL_OPTIONS is missing, Tomcat was started without the agent. Restart:

systemctl restart tomcat

Key Forwarder Not Running

systemctl status brekeke-key-forwarder --no-pager
ps -ef | grep socat

VoIPmonitor Receiving Keys but Not Decrypting

# Verify config
egrep -n '^(ssl|sip_tls|ssl_ipport|ssl_sessionkey_udp|sipport)' /etc/voipmonitor.conf

# Check bidirectional TLS traffic exists
tcpdump -i any -nn host BREKEKE_IP and port 5061

# Capture combined trace for support analysis
tcpdump -i any -nn -s 0 -w /tmp/voip_tls_and_keys.pcap \
  '(host BREKEKE_IP and port 5061) or udp port 1234'

Reboot Persistence

After reboot, verify all three services are running:

# On Brekeke host
systemctl status tomcat --no-pager
systemctl status brekeke-key-forwarder --no-pager

# On VoIPmonitor host
systemctl status voipmonitor --no-pager