View on GitHub


User Guide

3.1 Introduction

Since version 1.5.0, PCAPdroid has the ability to decrypt the TLS traffic and display the decrypted payload directly into the app. Moreover, it can generate a SSLKEYLOGFILE containing the decryption secrets, which can be used to decrypt the generated PCAP file in other tools.

Most apps today employ TLS to secure their data against inspection and tampering. Such connections are reported in PCAPdroid with either the TLS or the HTTPS protocol. Decryption can be useful in the following contexts:

Note: before decrypting, you should check the app ToS to see if this is allowed

Note: running TLS decryption will weaken the security of your app. You should only do this if you know what you are doing and for a limited amount of time

Current limitations:

TLS decryption on Android is not an easy task, technical knowledge and familiarity with the topic is required. There are many caveats and which are be discussed below. A rooted device will help you being successful in most circumstances.

3.2 Initial setup

TLS decryption can be enabled from the PCAPdroid settings. The first time decryption is enabled, a setup wizard will help you properly setting up decryption. It includes the following steps:

  1. Download and installation of the PCAPdroid-mitm addon. The actual decryption is performed by mitmproxy, which is bundled into the addon. Please note the addon is built using chaquopy, a closed source tool
  2. Permission to control the mitm addon. This is a security measure to prevent other apps from controlling the addon
  3. Installation of the PCAPdroid CA certificate. The CA certificate is what allows PCAPdroid to decrypt the app data, and to do so, it must first be added to the certificate store. To increase security, a unique CA is generated at runtime by PCAPdroid

Before proceeding, check if your device has Autostart or similar software which prevents background services excecution, in which case you will need to whitelist the mitm addon, otherwise decryption will refuse to start.

3.3 Decrypting

Before starting the decryption, you will need to select a target app. Decryption is an invasive operation which can break the connectivity of some apps due to certificate trust problems, so it’s a good practice to only limit it to a single app.

The first test you should do to verify that decryption works is to choose an app which is easy to decrypt. It turns out Google Chrome is a good candidate. Enable decryption, select Google Chrome as the target app and then start the capture in PCAPdroid. In chrome, open a new tab and a new HTTPS website (or just clear the browser cache) and you should start seeing decrypted connections in PCAPdroid. These are marked with a green open lock.

The lock icon and color indicates the decryption status, which is also reported into the connection details:

You can easily show decrypted or decryption-failed connections via the “Edit Filter” dialog under the filter icon. If you tap on a decrypted connection, the payload and the HTTP tabs will show the decrypted payload data.

If the PCAP dump is enabled, after you stop the capture you will be prompted to save the SSLKEYLOGFILE, which you can load in Wireshark to decrypt the PCAP file.

3.4 Caveats and possible solutions

Google chrome is a relatively easy app to decrypt. If you try to decrypt other apps you will soon face some problems, which can mostly addressed with a rooted device and the right tools.

3.4.1 The client does not trust the mitm certificate

This decryption error may occur for different reasons:

If you are on Android 7 or newer and the app you are decrypting has target SDK > 23, which is usually the case, the mitm certificate will be rejected, as apps do not trust user certificates anymore. In order to overcome this issue, you either need to:

Additionally, some apps (mainly browsers) implement a custom certificate trust store, separate from the system store. You should check if they have an option to disable it, for example, in Firefox you can do this via about:config. If such option is not available, you will need to patch the app.

If the client still refuses to connect, then the app may employ certificate pinning, which means that the app actively performs certificate verification against a whitelist. To bypass this, you either need to:

3.4.2 Certificate transparency

When decrypting a browser traffic, the browser may refuse to connect to websites giving you an error about certificate transparency. With Certificate transparency, custom system CA are normally rejected. To fix this, you either need to:

3.4.3 Traffic is still encrypted

After decrypting the TLS traffic, the decrypted payload may still be encrypted with a another protocol. This occurs, in particular, with Telegram and Whatsapp, which use a custom encrypted protocol. Such protocols require the development of custom tools for the decryption, which are out of the scope of PCAPdroid.

Moreover, beware that the result of decryption may produce a binary protocol, which is not in a human-readable form. It’s important to understand that a binary protocol does not necessarily means that the protocol is encrypted. For example, DNS is a binary protocol but it’s not encrypted.

3.5 Decrypting via an external mitmproxy

For better flexibility, e.g. to modify the traffic or use an upstream proxy, you can perform the TLS decryption on a third-party SOCKS5 proxy, possibly located into another device. Here is an example on how to configure mitmproxy for this.

On a PC, you can install mitmproxy by following the official installation guide. Both the Android device and the PC should be connected to the same network for this to work. As an alternative, you can install mitmproxy directly on the Android device in termux. After installing the termux app, open it and run the following commands:

pkg update
pkg install python openssl-1.1-static
python3 -m pip install --upgrade pip

  LDFLAGS="$PREFIX/lib/openssl-1.1/libssl.a $PREFIX/lib/openssl-1.1/libcrypto.a" \
  CFLAGS="-I$PREFIX/include/openssl-1.1" \
  pip install mitmproxy==7.0.4

This installs mitmproxy 7.0.4, which is the latest version to not require rust. If you want to install version 8+, refer to these instructions.

Note: when installed on the Android device via termux, it’s essential to set an app filter in PCAPdroid to only capture a specific app traffic, otherwise the termux mitmproxy traffic would run in a loop, breaking the phone internet connectivity.

After installing mitmproxy, you need to perform the following steps:

  1. Run mitmproxy without options to generate the mitm certificate. Install the certificate (usually ~/.mitmproxy/mitmproxy-ca-cert.cer) in the Android phone. It may be needed to change the extension to .crt to install it
  2. Open the PCAPdroid settings
  3. Toggle “Enable SOCKS5 Proxy”
  4. Set the IP address and port of the remote mitmproxy instance (port 8050 in this example)
  5. Run mitmproxy in SOCKS5 mode, e.g. via mitmproxy --mode socks5 --listen-port 8050

PCAPdroid will now redirect all the TCP traffic to the mitmproxy server, which will proxy the connections and decrypt the TLS traffic. Please note that the PCAP generated by PCAPdroid will still contain the encrypted traffic with the original IP destinations and ports.