Docs Capture SIP over TLS

Capture SIP over TLS

Pick the right method for reading SIP over TLS: a key log from the endpoint, plaintext read out of the process with no keys at all, eBPF with peer addresses, or eCapture — chosen by what access you have, plus what does not work and why.

On this page

You have SIP on port 5061. sipnab shows you nothing useful. You want to see the signaling. This page picks the method for you.

For many production deployments this is not an advanced topic — it is the only topic.

  • A hardened SIP server often does not listen on 5060 at all.
  • So every call is TLS, and a capture that reads only plaintext reads nothing.
  • If that is your situation, start at the table below. Do not start with the plaintext quick-start elsewhere in these docs.

The short version. The wire alone never yields encrypted traffic.

  • Modern TLS uses forward secrecy. So even the server’s private key does not open a captured session.
  • Something on a machine you control has to hand over one of these:
    • the session keys,
    • the plaintext.
  • Every method below is one of those two. They differ only in what access each demands.

Before you start

On the machine that runs sipnab:

  • A build with the tls feature. sipnab --version prints the list after features:, and the release binaries carry tls. A build without it stops with a message such as --keylog requires the 'tls' feature (not compiled in).
  • For a live capture, capture rights on the interface: Install sets them up. Reading a capture file needs none.
  • For the two probe methods, Linux and root at the moment sipnab attaches.

On the other system, the one that ends the TLS session (a phone, a proxy, a session border controller), each method asks for one change:

MethodChange on the other system
The endpoint writes a key logSet SSLKEYLOGFILE in the environment of the phone or daemon and restart it. Give sipnab read access to that file, or copy the file to the machine that reads the capture
No keys at all, and plaintext with the peer addressNothing changes in the daemon. sipnab itself runs on that machine, as root, so that machine needs sipnab installed
Lift keys from a daemon you cannot restartInstall eCapture on that machine and run it as root. The daemon keeps running
The old RSA caseCopy the private key of the server to the machine that runs sipnab

A key log opens every session it holds keys for. Store it with the same care as a private key, and delete it when the work ends.

Which method can you use?

Answer these in order.

  • Each branch ends at one method below.
  • The question that separates two branches is always an access question. It is never a protocol question.
flowchart TD
    S["SIP on 5061, and sipnab decodes nothing"] --> Q1{"Can you set SSLKEYLOGFILE<br/>on an endpoint and restart it?"}
    Q1 -->|yes| M1["The endpoint writes a key log: --keylog<br/>full decryption, live or from a pcap"]
    Q1 -->|no| Q2{"Can you get root on the SIP host?"}
    Q2 -->|no| Q6{"Old TLS 1.2 server on RSA key exchange,<br/>and you hold its private key?"}
    Q6 -->|yes| M6["The old RSA case: --tls-key<br/>non-PFS handshakes only"]
    Q6 -->|no| X["Nothing opens it.<br/>Read What does not work, and why"]
    Q2 -->|yes| L["Check what you have: sudo sipnab --uprobe-list<br/>names the TLS libraries this host runs"]
    L --> Q3{"Do you want keys you can keep,<br/>or plaintext right now?"}
    Q3 -->|keys| M5["Lift keys from a daemon: eCapture, then --keylog<br/>daemon untouched, and the pcap stays readable"]
    Q3 -->|plaintext| Q4{"BTF kernel, and a build<br/>carrying the bpf feature?"}
    Q4 -->|yes| M4["Plaintext and the peer address: --uprobe-tls --uprobe-backend bpf<br/>plaintext with the real 5-tuple"]
    Q4 -->|no| M3["No keys at all: --uprobe-tls<br/>plaintext, no peer addresses"]

The table says the same thing in rows. Read down the first column. Stop at the first row you can satisfy.

If you canUseNeedsGets you
Set SSLKEYLOGFILE on the endpoint (a soft client, test UA, or a daemon you can restart)--keylogNothing specialFull decryption, live or from a pcap
Get root on the SIP host, but not restart the daemon--uprobe-tlsLinux, rootPlaintext, no peer addresses
Get root and the kernel has BTF--uprobe-tls --uprobe-backend bpfLinux, root, BTF, a bpf buildPlaintext with the real 5‑tuple
Run a helper on the SIP host but prefer keys to plaintexteCapture → --keylogLinux, rootFull decryption, daemon untouched
Only reach an old TLS 1.2 server using RSA key exchange--tls-keyThe server’s private keyDecryption, non-PFS handshakes only
None of the above——Nothing. See what does not work

Most people want --keylog or --uprobe-tls.

  • --keylog if you are testing and control an endpoint.
  • --uprobe-tls if you are on a production box and cannot restart anything.
    • That is the case sipnab exists for.
    • It is the one people assume is impossible.

The endpoint writes a key log

This is the ordinary case, and the cheapest. Any TLS library built on OpenSSL, NSS or GnuTLS writes session keys to the file named by SSLKEYLOGFILE.

# Run all of these, in order.
export SSLKEYLOGFILE=/tmp/sip-keys.log
# start your softphone or daemon from this shell, then:
sudo sipnab -d eth0 --keylog /tmp/sip-keys.log --keylog-watch

--keylog-watch re-reads the file as it grows.

  • So keys minted after sipnab starts still decrypt.
  • Without it you get only the sessions whose keys were already written.

The same flag reads a capture you already recorded:

sipnab -I tls-capture.pcap --keylog /tmp/sip-keys.log

The full recipes are cookbook recipes “Live decryption (UA produces keys, sipnab follows)” to “Decrypt without writing the keys to disk”, under recipe “Decrypt SIP over TLS with a key log file”. They include:

  • exporting a decrypted pcap for Wireshark,
  • keeping keys off disk entirely.

Check what you have before going further

sudo sipnab --uprobe-list

This installs nothing. It prints:

  • the TLS libraries running on this host,
  • which processes use them.

That tells you whether the methods “No keys at all” and “Plaintext and the peer address” are even available. You learn it before you spend time on them.

No keys at all: read the plaintext in the process

This is the method the long-standing upstream feature request asks for: TLS visibility with no recompile and no certificate. It is what sipnab does here.

sudo sipnab -N --uprobe-tls

sipnab attaches a uprobe to the TLS library’s write function. It reads the bytes before the library encrypts them.

  • It recovers no key.
  • It decrypts nothing.
  • It touches no other machine.

Dialogs carry no addresses and port 0. Their label is uprobe:<process>/<pid>.

  • A uprobe sees the bytes an application handed its TLS library.
  • It sees nothing about the socket underneath.
  • So sipnab names the process rather than inventing a peer.
  • If you need the addresses, use the method “Plaintext and the peer address”.

If it attaches and reports zero messages, the symbol is almost certainly wrong. OpenSSL 3 applications increasingly call SSL_write_ex rather than SSL_write:

# Run all of these, in order.
nm -D --undefined-only /usr/sbin/opensips | grep -i ssl_write
sudo sipnab -N --uprobe-tls --uprobe-symbol SSL_write_ex

Read the security implications before using this on a production host.

  • It reads process memory.
  • So anyone who can run it can read every SIP session on that machine, credentials included.

Plaintext and the peer address

sudo sipnab -N --uprobe-tls --uprobe-backend bpf --portrange 0-65535

This adds a kernel probe on tcp_sendmsg. It pairs the probe with the write by thread. So dialogs carry the real 5-tuple.

It needs two things:

  • a kernel with CONFIG_DEBUG_INFO_BTF=y,
  • a sipnab that actually holds the kernel programs.
    • --features bpf compiles the loader.
    • The programs themselves need a nightly toolchain and bpf-linker on the build host.

A build missing either still succeeds.

  • It produces a binary that lists bpf and refuses at attach time.
  • The uprobe walkthrough linked at the foot of this page carries the message. It also carries the build-time switch that turns that gap into a build failure.

sipnab refuses rather than falling back in silence. A silent downgrade would leave you with no peers and no reason given.

Widen --portrange. The port a uprobe reports is whatever the socket used. That is usually ephemeral rather than 5061.

Lift keys from a daemon you cannot restart

You may rather have keys than plaintext. Keys decrypt a pcap you keep, and plaintext does not.

  • eCapture reads them out of a running process.
  • sipnab consumes them unchanged:
# Run all of these, in order.
# eCapture picks the TLS library to instrument by looking at curl. Your SIP
# daemon may well map a different one, so name the daemon's explicitly — this
# is the single most common reason a keylog stays empty.
LIBSSL=$(sudo awk '/libssl/ {print $6; exit}' /proc/"$(pgrep -o opensips)"/maps)
sudo ecapture tls -m keylog --libssl="$LIBSSL" --keylogfile=/tmp/keys.log &
sudo sipnab -d eth0 --keylog /tmp/keys.log --keylog-watch

The uprobe attaches to the library, not to one process.

  • So a forking daemon needs no --pid.
  • It covers every worker that maps that path.
  • --pid would restrict you to one of them.

Check the path it chose in eCapture’s own startup line (openssl_path=) before trusting the run.

Start the capture before the connections you want to read. This is the single biggest trap on long-lived trunks. It bites differently in each TLS version:

  • TLS 1.3 (RFC 8446) numbers each record with a counter both endpoints keep privately.
    • Nothing on the wire carries it, so sipnab searches for it.
    • The search covers about a million records. That is roughly a day of a trunk ticking over at ten records a second.
    • The search costs one AEAD tag check per candidate. It runs once per direction per session.
    • So it is a one-off of about a second, not a per-record cost.
    • Past that, the keys are right and the records still do not open.
    • --tls-lockon-window moves that ceiling.
      • Raising it costs nothing on a connection captured from its handshake. The search widens only as records fail to open.
      • So raise it for a carrier trunk held open for days.
    • A separate per-run trial budget — four full windows — limits one case. It stops one session whose keys belong to some other connection from spending a window on every record it gets offered.
  • TLS 1.2 (RFC 5246) is worse.
    • A CLIENT_RANDOM line gives the master secret.
    • The server random and cipher suite that expand it into record keys are in the ServerHello.
    • Miss the handshake and there is no way to use the secret at all, now or later.

sipnab says which of these happened, with counts. The fix is at capture time either way:

  • Bounce the connection, or the far end, while capturing.
  • So the capture catches the stream from its handshake and its first record.

Cookbook recipe “Decrypt traffic from a daemon you cannot restart” has the full sequence. Recipe “Decrypt without writing the keys to disk” shows feeding keys through a pipe, so they never reach disk.

The old RSA case

sipnab -I capture.pcap --tls-key server.key

This works only for TLS 1.2 handshakes that used RSA key exchange.

  • Any ECDHE/DHE handshake has forward secrecy. That is every modern configuration, and it is mandatory in TLS 1.3.
  • With forward secrecy, the private key does not decrypt a recorded session.
  • If this produces nothing, your traffic is almost certainly PFS. You need one of these methods:
    • “The endpoint writes a key log”,
    • “No keys at all”,
    • “Plaintext and the peer address”,
    • “Lift keys from a daemon you cannot restart”.

Media as well as signaling

SRTP keys arrive two ways, and sipnab reads both:

  • SDES — keys travel in the SDP.
    • So decrypting the signaling decrypts the media with it.
    • There is nothing extra to do.
  • DTLS-SRTP — a DTLS handshake carries the keys.

--dtls-keylog is a separate flag from --keylog. The two name different handshakes. If you already hold SRTP master keys rather than a handshake, --srtp-keys takes them directly.

A run that loaded the keys says so, with a count: DTLS-SRTP active: N keylog entr(ies) from <file> for --dtls-keylog, and SRTP decryption active: N key(s) from <file> for --srtp-keys.

The --srtp-keys file

# One line per SRTP stream. ssrc= is the stream's SSRC in decimal.
# key= is the master key and salt together, base64.
ssrc=439041101 key=AQIDBAUGBwgJCgsMDQ4PEBESExQVFhcYGRobHB0e
# Or the key and the salt apart, and the crypto suite by its SDES name.
ssrc=1584364171 key=AQIDBAUGBwgJCgsMDQ4PEA== salt=ERITFBUWFxgZGhscHR4= suite=AES_CM_128_HMAC_SHA1_80
  • One key per line, as space-separated name=value fields in any order. sipnab skips blank lines and lines starting with #.
  • Every line needs key=, in base64. Without salt= it holds the master key followed by the master salt: 30 bytes for the 128-bit suites, 46 for AES_256_CM_HMAC_SHA1_80. With salt=, each holds its own half.
  • ssrc= ties the key to one stream, by its SSRC as a decimal number (a stream sipnab lists as 0x1a2b3c4d is 439041101). Without it, sipnab tries the key on every stream, after the keys that name that stream.
  • suite= takes AES_CM_128_HMAC_SHA1_80 (the default), AES_CM_128_HMAC_SHA1_32 or AES_256_CM_HMAC_SHA1_80.
  • A line sipnab cannot read stops the run with exit 1, naming the file and the line.
sipnab -N -I srtp-call.pcap --srtp-keys srtp.keys --export-audio call-2c9d47@192.0.2.10
INFO sipnab::app::batch: SRTP decryption active: 2 key(s) from srtp.keys
WARN sipnab::app::batch: manual SRTP keys loaded from srtp.keys — use only in test environments
Exported 6.0s stereo audio (300 + 300 frames, 8000Hz) to call-2c9d47_192.0.2.10.wav

That capture was the sample call with both RTP streams encrypted as SRTP (AES-CM-128, HMAC-SHA1-80) under the keys above. The WAV sipnab wrote matched, byte for byte, the one it writes from the unencrypted capture. Without --srtp-keys, the same export decoded the ciphertext as noise.

Not run for this page: a DTLS-SRTP call with --dtls-keylog. No harness here produces one. The repository’s test suite decrypts a synthetic DTLS-SRTP exchange (tests/decryption_wrapper_matrix_test.rs).

Without a key, SRTP media is still measured.

  • Packet counts, loss, jitter and timing come from the RTP header. SRTP leaves that header in the clear.
  • The payload is not kept as audio.
  • The SDP may declare an SRTP profile (RTP/SAVP, RTP/SAVPF, UDP/TLS/RTP/SAVP or UDP/TLS/RTP/SAVPF). Then sipnab keeps only the payload it decrypted.
    • A payload it could not decrypt is ciphertext, and decodes as noise.
    • A WAV export or a vCon for such a call then carries no audio. It says how many packets sipnab could not decrypt.
    • If sipnab decrypted only some packets, it marks the audio PARTIAL and counts the others.

Share a capture without its keys

A pcapng can carry the TLS keys inside it, in a Decryption Secrets Block: eCapture writes one, and so does --pcap-export-mode encrypted+dsb. Anyone with the file can then read the calls. --strip-secrets writes a copy without them, and leaves the original as it was:

sipnab --strip-secrets shareable.pcapng -I with-keys.pcapng

It exits 0 and prints one line on stderr, at any log level and with --quiet: how many Decryption Secrets Blocks it removed, counted by the kind of secret each held, and the path it wrote.

Stripped 1 Decryption Secrets Block (1 TLS Key Log): with-keys.pcapng -> shareable.pcapng

A capture with no secrets says 0 Decryption Secrets Blocks (the input had none) and still writes the copy. Check the copy by reading both:

sipnab -N -I with-keys.pcapng --portrange 1-65535 --report --no-cli-print
INFO sipnab::app::batch: TLS decryption active: 5 secret(s) from embedded DSB in with-keys.pcapng
INFO sipnab::app::batch: sipnab: 25 packets captured, 7 SIP messages, 0 RTP packets across 0 streams

The same command on shareable.pcapng finds no secrets and reads 0 SIP messages from the same 25 packets. The capture was a TLS 1.3 SIP call on port 15061, made with harness/tls/make-tls-call.py.

Write the decrypted call to a file

--pcap-export-mode decides what -O writes for traffic sipnab decrypted:

ModeThe file holdsKeys in the file
raw (default)The packets as captured, still encryptedNone
encrypted+dsbThe packets as captured, and the keys in a Decryption Secrets Block, so Wireshark decrypts themYes
decryptedOne plain TCP frame per SIP message from TLS or WSS, and plain RTP for SRTP, on the captured addresses and timesNone, but the content is readable
sipnab -N -I tlscall.pcap --keylog tlscall.keylog --pcapng -O plain.pcapng --pcap-export-mode decrypted --no-cli-print

A decrypted run ends with a line of counts:

sipnab: decrypted export: 7 SIP from TLS, 0 SIP from WSS, 0 RTP from SRTP; 0 TLS segments copied as captured, 25 captured segments replaced, 0 SRTCP copied as captured, 0 not rebuildable, 0 out of order, 0 discarded at stop

An encrypted+dsb run logs Wrote DSB (992 bytes of key material) instead. Treat a decrypted or encrypted+dsb file like the call itself. Export encrypted packets for Wireshark has the three commands side by side.

When the keys arrive after the call starts

Any run whose keys arrive while it runs has one race. Such runs are:

  • “The endpoint writes a key log” or “Lift keys from a daemon you cannot restart”, with --keylog-watch,
  • keys fed through a descriptor with --keylog-fd.

“No keys at all” and “Plaintext and the peer address” use no keys. So they do not have it.

The race goes like this:

  • You attach the key source to a daemon that is already running.
  • A call arrives.
  • The first records reach sipnab before the first key does.

On a SIP session the first record is the INVITE.

  • So the symptom is not “a few records are unreadable”.
  • It is a call with no offer in it.
  • sipnab then reports that as a media mismatch or a NAT problem. From the dialog’s point of view, that is exactly what it looks like.

With --keylog-watch or --keylog-fd, sipnab holds application data it cannot open yet. It retries the data as soon as a key for that session turns up. No separate flag switches this on.

sipnab reads a plain --keylog file, without --keylog-watch, once at startup. It holds nothing then.

  • No key arrives later in the run.
  • So a record the loaded keys cannot open now never opens.

A run that recovered records says so:

TLS late decrypt: recovered 3 record(s) that arrived before their keys

The hold has limits. Otherwise a peer whose keys never arrive would grow it without end:

BoundValue
Total held, across every session4 MiB
Records per direction16
Directions4096
Age5 seconds

Those bounds are the reason to start the key source before the capture wherever you can. Recovery closes a gap measured in packets. It does not close one measured in minutes.

The run also says what the hold could NOT recover. These two are different problems with different fixes:

  • “we never had the keys for those records”,
  • “we had them and had already discarded the ciphertext”.
sipnab discarded 3 TLS record(s) held from before a key arrived: the
late-decrypt hold is bounded (4 MiB total, 16 record(s) per direction, 5s),
and it filled before any key matched them. Start the key source before the
capture, or expect the first message of a call to be missing.

That one argues for starting the key source earlier, or for a bigger bound. Records still held when the run ended produce a different line. That line argues for neither:

5 TLS record(s) were still waiting when the run ended: no key ever arrived
for them. Nothing was discarded and starting the capture earlier would not
have helped -- the key source never produced those secrets.

What does not work, and why

Stated plainly, because time spent here is time people lose:

  • A packet capture alone.
    • No amount of sipnab flags decrypts a pcap with no keys.
    • If the handshake had forward secrecy, the information required is not in the capture and never was.
  • The server’s private key, on modern TLS. See the section on the old RSA case.
  • A mirror port or tap, by itself. It gives you the same ciphertext as a local capture. You still need keys or plaintext from an endpoint.
  • “No keys at all”, “Plaintext and the peer address” or “Lift keys from a daemon you cannot restart”, against a machine you do not control. They read process memory on the host they run on. That is the whole boundary.
  • Attaching to a long-lived connection and expecting the back catalog.
    • Keys extracted from a running process decrypt records captured from that point on. That holds if the capture catches the stream early enough.
    • sipnab does recover records that reached it in the moments before the key did, as described above.
    • But that closes a gap of packets, not one of history.
    • Traffic that went past before the capture started is not in the capture. Nothing recovers it.

Check that it worked

Before a probe method, list what sipnab can attach to:

sudo sipnab --uprobe-list

Expect a table under the header FLAVOR INODE PIDS LIBRARY, one row for each TLS library. A host with none in view prints No TLS library is mapped by any process sipnab can see.

After a key method, read the capture with its keys:

sipnab -N -I tls-capture.pcap --keylog /tmp/sip-keys.log

Expect three things:

  • One line for each decrypted message, ending in TLS: 22:13:20.004 10.9.0.1:40111 -> 10.9.0.2:5061 INVITE TLS.
  • TLS session decrypted in the log on standard error.
  • A totals line that counts the messages: 6 packets captured, 2 SIP messages for a call of one INVITE and one 180.

This check ran on Ubuntu 24.04 (Linux 6.8, aarch64) against the TLS 1.3 call that the test suite builds with its keys, an INVITE and a 180 Ringing, and printed the lines above. The listing ran there without root and printed the header and its rows. Not run for this section: the two probe methods and the eCapture method, which need root on a machine that runs a SIP daemon. A probe run labels each dialog uprobe:<process>/<pid>.

When decryption does not work

SymptomLikely cause
This capture holds at least 2 TLS application-data record(s) and this run was given no TLS key (the number varies) after a totals line with 0 SIP messagesThe run had no --keylog, --keylog-fd or --tls-key, so sipnab decrypted no TLS record. Pass the key log: sipnab -N -I tls-capture.pcap --keylog /tmp/sip-keys.log
sipnab could not decrypt 2 TLS application-data record(s): it holds no key material for any session in this capture (the number varies)The key log is empty or holds no key line. Check that the key source attached to the TLS library and the process the daemon uses, and that it started before the connection opened
sipnab loaded 1 keylog line(s) and built no session from any of them (the numbers vary), then No key in the key log belongs to a handshake in this captureThe capture holds the handshake, and the key log comes from other connections: another process, another run, or a log rotated after these connections began. sipnab prints the remedy: Use the key log that the endpoint of these connections wrote during this capture.
sipnab loaded 1 keylog line(s) and built no session from any of them, then The handshake is missing: this capture holds no ClientHello and no ServerHello.The capture started after the connection opened. For TLS 1.2, restart the connection while the capture runs. For TLS 1.3, use a key log that holds both traffic secret lines of the connection
capture quality: 2 hole(s) in TCP streams (the number varies), with reading resumed at the next SIP message or TLS record behind eachThe capture point missed packets of a TCP connection. sipnab resumes at the next TLS record behind each hole and decrypts from there. A message that lay in a hole is not in the output. Capture closer to the traffic, or with a larger buffer (Tuning capture)
Failed to load --keylog <path>: with No such file or directory, exit 1The path is wrong, or the user that runs sipnab cannot reach the file
Permission denied attaching TLS probes (--uprobe-tls)., exit 1sipnab was not root when it attached. Run it with sudo. sipnab --setup-caps grants the rights for a capture on an interface, and they do not cover a probe
--uprobe-list finds no TLS libraryIt reads /proc/<pid>/maps, and an unprivileged run sees only its own processes. Re-run with sudo
--uprobe-list marks a library (UNREACHABLE)The path lives in another mount namespace, almost always a container. Run as root
Attaches, reports 0 messagesWrong symbol — try --uprobe-symbol SSL_write_ex (see No keys at all)
needs this kernel's BTFNo CONFIG_DEBUG_INFO_BTF; use --uprobe-backend tracefs
no kernel programsBinary carries the bpf feature and not the programs — the build host had no bpf-linker. Use tracefs, or rebuild somewhere that has it
Keylog present, still encryptedKeys minted after start — add --keylog-watch
Call decodes, but its INVITE is missing and sipnab reports a media or NAT problemThe keys arrived after the INVITE did. sipnab retries records held from before the key, within the bounds above; start the key source before the capture
Keylog stays emptyeCapture attached to a TLS library the daemon never calls — pass --libssl with the path from /proc/<daemon-pid>/maps
Keys load, sessions listed, nothing decryptsThe capture joined TLS 1.3 connections already running, past the record numbers sipnab searches. Restart the connection while capturing, or raise --tls-lockon-window
Keys load, no sessions listedTLS 1.2 without the handshake — the ServerHello never got captured, and the master secret alone cannot make record keys. Restart the connection while capturing
TLS 1.2, right keys, still nothingA CBC suite. sipnab refuses to emit record plaintext it cannot MAC-verify, so a forged capture cannot inject “decrypted” SIP. Configure an AES-GCM suite
Addresses show 0.0.0.0:0Expected on the tracefs backend; use Plaintext and the peer address for peers

More in Troubleshooting and the uprobe walkthrough.