PacketSafari
Log in

TLS decryption and session keys

Provide authorized TLS session keys manually or through a supported on-prem capture probe, then inspect decrypted protocol fields in a derived capture.

PacketSafari can decode supported TLS traffic when the capture is paired with the correct session secrets. Decryption does not recover missing keys, bypass endpoint protections, or guarantee that every encrypted flow becomes readable.

There are two current paths:

  • Manual key-log merge for a PCAP and an existing TLS key-log file.
  • Capture-probe TLS key extraction for explicitly authorized, process-scoped collection on a qualified on-prem provider profile.

The endpoint sensor can use cooperative key logging, qualified passive original-path providers, or an explicitly authorized managed-proxy fallback. Coverage varies by operating system, application, provider, exact build, protocol, and privilege boundary. Observing or embedding a secret is not proof of decryption; the receipt reports packet verification separately.

Both paths handle sensitive key material. Follow your organization's authorization, retention, access-control, and incident-handling requirements.

Merge an existing TLS key log

Configure the target application to write a key log before starting the connection you need to capture. Many compatible applications use the SSLKEYLOGFILE environment variable and the NSS/Wireshark key-log format.

Example on Linux or macOS:

SSLKEYLOGFILE=/secure/path/packet-session-keys.log application-command

Example in Windows PowerShell:

$env:SSLKEYLOGFILE = "C:\Secure\packet-session-keys.log"
application-command

After collecting the PCAP and matching key log:

  1. Select one capture in the capture library.
  2. Choose Decrypt PCAP from the capture action menu.
  3. Upload the matching key-log file.
  4. Open the derived capture after processing completes.
  5. Confirm decrypted fields against the expected endpoints, protocol, and capture time.

PacketSafari creates a derived capture so the original evidence remains separate. If the application did not emit the required secrets, the key log belongs to another session, or the negotiated protocol/cipher is unsupported, the encrypted payload remains unavailable.

For the key-log format and supported Wireshark behavior, see Wireshark TLS decryption.

Capture-probe TLS key extraction

On-prem deployments with capture probes enabled can use the PacketSafari CLI to request native, process-scoped TLS key extraction while capturing traffic. This is an advanced operator workflow; it is not exposed as automatic decryption for every capture.

The request must include:

  • a specific target process
  • explicit operator authorization
  • a supported Linux capture and library profile
  • sufficient host privileges for the selected capture and attach operations

Example structure:

./packetsafari \
  --server https://packetsafari.example \
  --api-key pscap_xxx \
  --probe-id probe-id \
  --capture-mode native-ebpf \
  --process-id 1234 \
  --tls-key-extract \
  --tls-key-process-id 1234 \
  --tls-key-authorized \
  --stop-after-seconds 60

Only use --tls-key-authorized when you are authorized to inspect that exact process. The probe writes a TLS key sidecar and a session receipt alongside the capture, then uploads them according to the selected storage workflow. The receipt records preflight and boundary information even when extraction cannot proceed.

Extraction is exact-provider dependent. Qualified paths include selected OpenSSL, BoringSSL, NSS, Go crypto/tls, GnuTLS, rustls/ring, JVM, Schannel, QUIC, and protocol-specific session-key providers. This is not a claim of support for every version, build, application, cipher, protected process, or packaging layout. Unsupported or mismatched targets fail closed.

Verify the result

After creating a decrypted capture:

  1. Check that the expected TLS flow and time window are present.
  2. Confirm that the Analyzer exposes the expected decrypted protocol fields.
  3. Use View packets or a display filter to inspect the exact frames behind a conclusion.
  4. Keep decryption success separate from investigation or verification status.

A readable payload proves that PacketSafari received usable secrets for that captured session. It does not prove the payload is benign, complete, or captured from the correct operational viewpoint.

Security and cleanup

  • Treat key logs and decrypted derived captures as sensitive evidence.
  • Restrict capture and download permissions to the case team.
  • Prefer short-lived collection and the minimum process/time scope needed.
  • Delete derived captures and key artifacts according to the applicable retention policy when the investigation ends.
  • Do not attach to processes or decrypt traffic without explicit authority.

Related documentation