How to intercept and decrypt TLS traffic

This recipe is dedicated to intrepid users ๐Ÿ˜Ž

PiRogue comes with a pirogue-intercept-* helpers to help you intercept encrypted TLS traffic from applications, even in presence of TLS certificate pinning.

These helpers are meant to:

  • capture the network traffic
  • instrument a specific application or any launched application

Requirements

To follow this recipe, you need:

  • an up-to-date PiRogue
  • a rooted Android device

Procedure

First, SSH onto your PiRogue. Attach your smartphone to the PiRogue through USB and make sure “USB debugging” is on and working.

Make sure to enable ADB Transfer files by clicking on the Android System notification.

Then check if the PiRogue sees your device by running the command:

adb devices

You should see your device listed. If not, be sure to use the right USB cable for your device. If the issue remains, check that you have the rights to interact with USB devices. To do so, run the command groups to list the groups you belong to and check if the group plugdev is listed. If not, execute the following command sudo usermod -aG plugdev $LOGNAME and reboot.

Identify and install the application

Android applications are identified by their package name. As an example, the French weather forecast application is fr.meteo. You can get the package name either from Google Play URL or from any tool analyzing Android apps such as Pithus, Virus Total, etc. In our example, the Google Play URL looks like https://play.google.com/store/apps/details?id=fr.meteo, the package name of the application is specified after id=.

Once you have identified the application you want to analyze, you have to download and install it on your target device. If you need to download the application from Google Play, we recommend to use apkeep (not installed by default on PiRogue).

Finally, to install the application, run the following command:

adb install <APK file>

If your application contains multiple APKs (like in XAPK), use the command adb install-multiple <list all apks>.

Don’t launch the application.

Instrument and intercept

Once the application to be analyzed is installed on your Android device, connect your device to the PiRogue Wi-Fi network and run the following command:

sudo pirogue-intercept-gated -o <path to the output directory>

Adapt the command according to your output directory of choice. Once started and showing Waiting for data, manually launch the application you want to analyze.

Command capturing TLS traffic

Now, interact with the application freely. When you are done interacting with the app, hit Ctrl+C on your keyboard to stop interception.

Caution

Make sure that the application you want to be analyzed is not running in background. You can, for example, force stop it in Settings > Apps, select the application and click on Stop.

Decrypt the traffic

If we run the previous command with sudo, we have to fix the permissions of generated files by running:

chown -R pi:pi <path to the output directory>

Then enter the output directory with:

cd <path to the output directory>
Command fixing file permissions

Next, we generate a PCAPNG file containing both the TLS keys and the captured traffic:

editcap --inject-secrets tls,sslkeylog.txt traffic.pcap decrypted.pcapng

Next, we export the decrypted traffic in JSON:

tshark -2 -T ek --enable-protocol communityid -Ndmn -r decrypted.pcapng > traffic.json
Command decrypting TLS traffic

Finally, to view the decrypted traffic, run:

pirogue-view-tls -i traffic.json -t socket_trace.json
Command displaying TLS traffic

Caution

The display of the stack trace has been added to pirogue-cli in version 1.0.5. Be sure to upgrade your PiRogue.

If you face any issue, join the Discord channel to get help.

Generated files

The commands pirogue-intercept-single and pirogue-intercept-gated generate the following files:

  • aes_info.json contains all AES and RSA encryption/decryption operation with both cleartext and cyphertext
  • device.json contains various information about the device such as IMEI, Android version
  • experiment.json contains timing information such as the start and end date of the experiment
  • screen.mp4 contains the video recording of the device’s screen
  • socket_trace.json contains the stack trace of all operations on sockets (open, close, read, write…)
  • sslkeylog.txt contains the TLS encryption keys in the NSS key log format
  • traffic.pcap contains the entire network traffic captured during the experiment

NB: you can open the PCAP file with Wireshark and specify the key log file in Settings > Protocols > TLS. This way, Wireshark will automatically decrypt TLS traffic.