Skip to content
Tutorials Center
My learning

Topics

Lesson 31 of 37 ยท Advanced Techniques

Decrypting Your Own TLS Traffic with a Key Log File

Learn how to decrypt TLS in Wireshark for debugging your own apps: the SSLKEYLOGFILE method, how session secrets work, setup steps, and the legal and safety limits.

TLS hides the content of a connection from everyone on the path, including you when you debug your own application. To see why an API call fails, you can ask your own client to save its session secrets to a file and let Wireshark use them to decrypt that one capture. This lesson explains how it works, how to set it up, and where the limits are.

Only decrypt traffic from software you run, on machines you control. Decrypting other people's traffic is a privacy violation and usually a crime. Key log files are as sensitive as passwords: anyone who has the capture and the key file can read the session.

Why you cannot just "import the server's private key" any more

Older RSA key exchange let you load a server's private key into Wireshark and decrypt every session. Modern TLS uses ephemeral Diffie-Hellman key exchange (forward secrecy, and the only option in TLS 1.3). Each session derives fresh secrets that are never stored, so even the server's private key cannot decrypt a recorded capture later. That is a security feature.

The remaining way is to get the secrets from one of the endpoints while the session is live. Browsers, curl, and many libraries support the SSLKEYLOGFILE environment variable for exactly this debugging purpose.

flowchart LR
    A["Your client app"] -->|"writes secrets"| K["keys.log"]
    A -->|"encrypted traffic"| N["Network"]
    N --> C["capture.pcapng"]
    K --> W["Wireshark"]
    C --> W
    W --> P["Decrypted view"]

Wireshark combines the capture and the secrets file.

Setup steps

  1. Choose a file for the secrets, in a folder only you can read.
  2. Set the variable before starting the client:
Terminal
# Linux or macOS
export SSLKEYLOGFILE="$HOME/tls-keys.log"
curl https://localhost:8443/api    # or start your browser from this shell
TEXT
# Windows PowerShell
$env:SSLKEYLOGFILE = "$HOME\tls-keys.log"
  1. Capture the traffic (Wireshark or tshark) while you make the request.
  2. In Wireshark: Edit, Preferences, Protocols, TLS, then set "(Pre)-Master-Secret log filename" to the file.
  3. The packet list now shows HTTP or HTTP/2 lines where it previously showed Application Data. A new tab "Decrypted TLS" appears in the bytes pane.

Or on the command line:

Terminal
tshark -r capture.pcapng -o "tls.keylog_file:$HOME/tls-keys.log" -Y http2

The file format is plain text, one secret per line, labelled with the client's random value, so Wireshark can match secrets to sessions:

TEXT
CLIENT_HANDSHAKE_TRAFFIC_SECRET 3f2a...9c1d 7b81...e402
SERVER_HANDSHAKE_TRAFFIC_SECRET 3f2a...9c1d a5d3...117f
CLIENT_TRAFFIC_SECRET_0 3f2a...9c1d 22c0...5b6e
SERVER_TRAFFIC_SECRET_0 3f2a...9c1d 91ef...0d33

Values shortened and invented. The second column is the client random seen in the Client Hello; the third is the secret.

Python Read a key log: which sessions are covered?

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

The code only reads a made-up text; it does not include real secrets or decrypt anything.

Troubleshooting decryption

  • Capture started after the handshake. Wireshark needs the Client Hello to match the client random. Restart the app after capture begins, or the connection must be new.
  • Wrong file path or empty file. Check the file grows while you browse. Some programs ignore the variable (for example, ones that do not use OpenSSL, NSS, or a library that supports it), and some need a flag instead.
  • Session resumption. Resumed sessions reuse earlier secrets and may not log new ones; clear the browser's session cache or restart it.
  • QUIC / HTTP/3 is also decryptable with the same file in recent Wireshark versions; filter with quic or http3.
  • Certificate pinning and mutual TLS do not prevent decryption with the log method, because you are getting the secrets from the client itself.
  • TCP issues. Missing segments in the capture stop decryption partway: fix capture loss first (see Large Captures).

Alternatives for your own services

  • Reverse proxies and load balancers often offer a debug log of requests.
  • For local development, run the server over plain HTTP on loopback for tests.
  • Application-level tracing (OpenTelemetry) gives you request details without packet captures.

Keeping it safe

  • Delete the key log and the capture when finished.
  • Do not set SSLKEYLOGFILE globally or permanently. Malware that finds it can read all your sessions. Set it only in the shell where you test.
  • Never post captures together with key files.

A key log lets anyone with the capture read passwords, tokens and cookies from those sessions. Treat the two files together as a credential.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. Why can Wireshark no longer decrypt modern TLS just by loading the server's private key?

    With forward secrecy the session keys are derived per connection and never stored, so a recorded capture cannot be decrypted with the long-term key.
  2. 2. What does SSLKEYLOGFILE do?

    Supporting clients append session secrets to the named file, which Wireshark can use.
  3. 3. Why must the capture include the TLS handshake?

    Without the Client Hello, Wireshark cannot connect a secret to the session.
  4. 4. Which is the safest practice for the key log?

    Treat key logs like passwords: short-lived and private.

Summary

  • Forward secrecy means recorded traffic cannot be decrypted later with the server key.
  • For your own client, SSLKEYLOGFILE plus Wireshark's TLS preference decrypts a capture.
  • Capture from the start of the session, and verify the log file is being written.
  • Protect and delete keys and captures; decrypt only traffic you are authorized to inspect.

Next: Profiles, Coloring Rules and Lua Dissectors