View on GitHub

PCAPdroid

User Guide

3.1 Introduction

PCAPdroid can decrypt the TLS traffic and display the decrypted payload directly in the app. Moreover, it can generate a pcapng file, which you can load in tools like Wireshark to analyze the decrypted traffic.

Most apps today employ TLS to secure their data against inspection and tampering. These 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

Current limitations:

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

3.2 Initial setup

TLS decryption can be enabled from the PCAPdroid settings.

In PCAPdroid settings (top right ⚙️ icon), toggle TLS decryption switch under Traffic inspection menu.

The first time decryption is enabled, a setup wizard will help you properly set 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
  2. 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 from running, in which case you will need to whitelist the mitm addon, otherwise decryption will refuse to start.

3.3 Decrypting

In order to decrypt connections, you first need to define some rules. You can do this either from the “Decryption rules” in the left drawer or by long pressing a connection and selecting a decryption criterion from the context menu. Please note that, due to Android security measures, decryption on common apps will not usually work, and will cause the apps to stop working. Read the caveats section below to understand and possibly bypass these protections.

Before starting the decryption, be sure to enable the “Full payload” option in the PCAPdroid settings, so that PCAPdroid can load the full decrypted data in memory.

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 indicate the decryption status, which is also reported in 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.

3.3.1 Inspecting HTTP requests

Most of the apps communicate with their servers via HTTP-based APIs. PCAPdroid has a dedicated view for the HTTP traffic inspection, which you can activate by pressing the ⇄ icon next to the “Connections” tab header.

Note: you need to enable the “Full payload” mode in order for this icon to appear

In the HTTP requests view, you can see the individual HTTP request data:

The filter in the action bar allows you to filter requests by request method, content type, status and size. From the action bar, you can export the HTTP requests as text or as HAR, which makes it convenient to analyze the requests with standard web tools, like the web-based HAR Analyzer from Google. To only export specific requests, long press one of the rows to activate the selection mode, then select the requests to export and finally choose “Save as HAR” from the action bar.

You can tap an HTTP request to show the full request data and its related reply.

Use the previous/next arrows in the action bar to easily navigate to the previous/next request.

3.3.2 Analyze the decrypted traffic in Wireshark

If the PCAP dump is enabled, PCAPdroid will store the packet capture under the PCAPdroid subfolder of the Downloads directory.

3.3.3 Exclude specific hosts/ports

Decryption rules already allow you to define what needs to be decrypted. However, in some cases it’s easier to create a rule to decrypt a whole app and only exclude specific hosts or ports. For this you can use the mitmproxy –ignore-hosts option, setting it in the “Additional mitmproxy options” in the PCAPdroid settings.

For example, to avoid decrypting connections to port 1234, you can use --ignore-hosts .*:1234.

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 be addressed with a rooted device and the right tools.

3.4.1 The client does not trust the mitm certificate

If you see the above error “client does not trust proxy’s certificate” while decrypting, this may be due to one of the following reasons:

Using a rooted Android device

Using a rooted Android emulator

Note: since PCAPdroid 2.0.0, you need an x86_64 or AArch64 emulator to run the mitm addon. Older x86 emulators are not supported anymore

Patching the APK

Reverse engineering APKs and other advanced topics

3.4.2 Certificate transparency

When decrypting browser traffic, the browser may refuse to connect to websites giving you an error about certificate transparency. With Certificate transparency, custom system CAs are normally rejected. To fix this, you need to do one of the following:

3.4.3 Traffic is still encrypted

After decrypting the TLS traffic, the decrypted payload may still be encrypted with 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 mean 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 on 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

CRYPTOGRAPHY_DONT_BUILD_RUST=1 CRYPTOGRAPHY_SUPPRESS_LINK_FLAGS=1 \
  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 that does 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. You may need 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.

3.6 Custom mitmproxy addons

Since PCAPdroid 1.7.0, you can load your custom mitmproxy addons. The following example will show how to do this to modify the HTTP response of a website.

First of all you need to specify the directory from where the addons should be loaded. To do this, create a new directory on the device (/sdcard/PCAPdroid_addons in this example), then open PCAPdroid mitm, tap on “Addons” and then on “Set user dir”.

Select “Allow” to grant PCAPdroid the ability to read the directory.

By default, custom addons run in the private app directory, which is not accessible by other apps. If you want your addons to read or write public files, e.g. the ones under /sdcard or the selected addons directory, select “Enable files access” from the same hamburger menu and grant the related permission.

In the selected addons directory, create the following script (or create on a PC and transfer via adb push "Modify HTTP.py" /sdcard/PCAPdroid_addons):

# Modify HTTP.py

class ModifyHttp:
    def done(self):
        # addon unloaded, close global resources (e.g. open files) here
        pass

    def response(self, flow):
        if flow.request.pretty_url == "https://example.com/":
            flow.response.content = flow.response.content.replace(
                b"Example Domain",
                b"Modified by PCAPdroid mitm")

            print("HTTP response modified")

addons = [ModifyHttp()]

This addon will modify the HTTP response of the https://example.com web page, by replacing the “Example Domain” text with “Modified by PCAPdroid mitm”. After copying it to the addons dir, in the Addons activity click the refresh icon and the addon should appear. Now enable it via the toggle and restart the PCAPdroid capture with TLS decryption.

The addon will only be executed on decrypted connections, so be sure to create a decryption rule either for the “example.com” domain or for your browser app.

When connecting to https://example.com, you should now see the “Modified by PCAPdroid mitm” text.

Note: the web browser may cache the HTTP reply, so be sure to flush the browser cache. To prevent this, you may consider adding --anticache to the “Additional mitmproxy options”.

The mitm addon log will also show the “HTTP response modified” message, from the addon print.

Check out the mitmproxy addons and events references to know more about the mitmproxy API to use in your addons.