Transport Layer Security (TLS)

Transport Layer Security (TLS) provides security in the communication between two hosts. It provides integrity, authentication and confidentiality. It is used most commonly in web browsers, but can be used with any protocol that uses TCP as the transport layer.

Secure Sockets Layer (SSL) is the predecessor of the TLS protocol. These names are often used interchangeably which can lead to some confusion:

Protocol dependencies

TLS dissection in Wireshark

The TLS dissector is fully functional and even supports advanced features such as decryption of TLS if appropriate secrets are provided (#TLS_Decryption).

Since Wireshark 3.0, the TLS dissector has been renamed from SSL to TLS. Use of the ssl display filter will emit a warning.

TLS Decryption

Wireshark supports TLS decryption when appropriate secrets are provided. The two available methods are:

A key log file is a universal mechanism that always enables decryption, even if a Diffie-Hellman (DH) key exchange is in use. The RSA private key only works in a limited number of cases.

The key log file is a text file generated by applications such as Firefox, Chrome and curl when the SSLKEYLOGFILE environment variable is set. To be precise, their underlying library (NSS, OpenSSL or boringssl) writes the required per-session secrets to a file. This file can subsequently be configured in Wireshark (#Using_the_.28Pre.29-Master-Secret).

The RSA private key file can only be used in the following circumstances:

The key log file is generally recommended since it works in all cases, but requires the continuous ability to export the secrets from either the client or server application. The only advantage of the RSA private key is that it needs to be configured only once in Wireshark to enable decryption, subject to the above limitations.

Preference Settings

Go to Edit -> Preferences. Open the Protocols tree and select TLS. Alternatively, select a TLS packet in the packet list, right-click on the TLS layer in the packet details view and open the Protocol preferences menu.

The notable TLS protocol preferences are:

The following TCP protocol preferences are also required to enable TLS decryption:

Starting with Wireshark 3.0, a new RSA Keys dialog can be found at Edit -> Preferences -> RSA Keys. In this dialog, use the Add new keyfile... button to select a file. You will be prompted for a password if necessary. The Add new token... button can be used to add keys from a HSM which might require using Add new provider... to select select a DLL/.so file, and additional vendor-specific configuration.

The RSA key file can either be a PEM format private key or a PKCS#12 keystore (typically a file with a .pfx or .p12 extension). The PKCS#12 key is a binary file, but the PEM format is a text file which looks like this:

-----BEGIN PRIVATE KEY-----
MIIEvgIBADANBgkqhkiG9w0BAQEFAASCBKgwggSkAgEAAoIBAQDReQzlKVeAK8b5
TRcRBhSi9IYwHX8Nqc8K4HeDRvN7HiBQQP3bhUkVekdoXpRLYVuc7A8h1BLr93Qw
...
KOi8FZl+jhG+p8vtpK5ZAIyp
-----END PRIVATE KEY-----

The deprecated RSA keys list dialog may be removed at some point. To configure keys, use the RSA keys dialog instead. To change the protocol for decrypted network data, right-click on a TLS packet and use Decode As to change the Current protocol for the TLS port. The IP address and Port fields are unused.

Example capture file

See also SampleCaptures#SSL_with_decryption_keys.

Display Filter

A complete list of TLS display filter fields can be found in the display filter reference

Show only the TLS based traffic:

Capture Filter

You cannot directly filter TLS protocols while capturing. However, if you know the TCP port used (see above), you can filter on that one, for example using tcp port 443.

Using the (Pre)-Master-Secret

The master secret enables TLS decryption in Wireshark and can be supplied via the Key Log File. The pre-master secret is the result from the key exchange and can be converted to a master secret by Wireshark. This pre-master secret can be obtained when a RSA private key is provided and a RSA key exchange is in use.

Step-by-step instructions to decrypt TLS traffic from Chrome or Firefox in Wireshark:

  1. Close the browser completely (check your task manager just to be sure).
  2. Set environment variable SSLKEYLOGFILE to the absolute path of a writable file.

  3. Start the browser.
  4. Verify that the location from step 2 is created.
  5. In Wireshark, go to Preferences -> Protocols -> TLS, and change the (Pre)-Master-Secret log filename preference to the path from step 2.

  6. Start the Wireshark capture.
  7. Open a website, for example https://www.wireshark.org/

  8. Check that the decrypted data is visible. For example, using the tls and (http or http2) filter.

For Windows, an environment variable can be set globally as described in this walkthrough, but this is not recommended since it is easy to forget about and may be a security issue since it allows decryption of all your TLS traffic. A better way to set the environment variable is via a batch file. Create a file start-fx.cmd with:

@echo off
set SSLKEYLOGFILE=%USERPROFILE%\Desktop\keylogfile.txt
open firefox

Change the SSLKEYLOGFILE path as needed, and replace firefox with chrome for Google Chrome. This mechanism currently (2019) does not work for Safari, Microsoft Edge, and others since their TLS libraries (Microsoft SChannel/Apple SecureTransport) do not support this mechanism. This mechanism works for applications other than web browsers as well, but it dependent on the TLS library used by the application.

Examples of other applications:

For a survey of supported TLS applications and libraries, see also page 19 of Peter Wu's SSL/TLS Decryption SharkFest '18 presentation.

See also

Some other protocols are derived from TLS. This includes: