Decrypting TLS traffic with PolarProxy

By on 3 Aug 2021

Category: Tech matters

Tags: , , , , ,

1 Comment

Blog home

PolarProxy is a transparent TLS proxy that outputs decrypted TLS traffic as PCAP files. PolarProxy doesn’t interfere with the tunnelled data in any way, it simply takes the incoming TLS stream, decrypts it, re-encrypts it and forwards it to the destination. Because of this, PolarProxy can be used as a generic TLS decryption proxy for just about any protocol that uses TLS encryption, including HTTPS, HTTP/2, DoH, DoT, FTPS, SMTPS, IMAPS, POP3S and SIP-TLS.

PolarProxy is primarily designed for inspecting otherwise encrypted traffic from malware, such as botnets that use HTTPS for command-and-control of victim PCs. Other popular use cases for PolarProxy are to inspect encrypted traffic from IoT devices and other embedded products or to analyse otherwise encrypted traffic from mobile phones and tablets. The fact that PolarProxy exports the decrypted traffic in a decrypted format without any TLS headers also enables users to inspect the decrypted traffic with products that don’t support TLS decryption, such as intrusion detection and network forensics products like SuricataZeek, and NetworkMiner.

PolarProxy creates a unique root CA certificate for each installation, which must be trusted by clients that will have their TLS traffic decrypted. PolarProxy’s root CA must, therefore, be trusted by the operating systems, browsers, and applications that you wish to decrypt TLS traffic from.

Figure 1 — DNS-over-HTTPS (DoH) traffic in the file proxy-191023-091924.pcap.
Figure 1 — DNS-over-HTTPS (DoH) traffic in the file proxy-191023-091924.pcap.

The Wireshark screenshot above shows DNS-over-HTTPS (DoH) traffic in the file proxy-191023-091924.pcap, which was captured live during my TLS Interception and Decryption talk at the CS3Sthlm conference in 2019. As you can see, the DoH query is sent inside an HTTP/2 request. You might also notice that the HTTP/2 request is not encapsulated by a TLS record. This is because PolarProxy has removed all TLS data before saving the decrypted traffic to a capture file.

Figure 2 — PolarProxy removes all TLS data before saving the decrypted traffic to a capture file.
Figure 2 — PolarProxy removes all TLS data before saving the decrypted traffic to a capture file.

PolarProxy is released under a CC BY-ND 4.0 license, which means you are free to use the software for any purpose, even commercially. To take PolarProxy for a test run, simply run the following commands on a Linux machine:

mkdir ~/PolarProxy
cd ~/PolarProxy/
curl | tar -xzf -
sudo ./PolarProxy -v -p 443,80 --certhttp 10080 -w /tmp/polarproxy.pcap

You will then have a PolarProxy service listening on TCP port 443 that will output decrypted packets to ‘/tmp/polarproxy.pcap’. To test the proxy, simply run the following curl command on any PC in your network:

curl --insecure --resolve

Note: Replace with the IP address of PolarProxy.

This command tells curl to behave as if resolved to PolarProxy’s IP, whereby the outgoing connection is sent via the TLS decryption proxy. The --insecure option is there because PolarProxy will generate a fake X.509 certificate for the domain in question, on the fly, and sign it with its own root CA certificate, which neither curl nor your operating system trusts by default. This root CA cert can be downloaded from an HTTP service listening on port 10080 on the PolarProxy machine. For instructions on how to configure a PC to trust this certificate, please see the ‘Trusting the PolarProxy root CA’ section on the PolarProxy documentation.

It’s not possible to decrypt traffic from applications that use techniques like certificate transparency or public key pinning with PolarProxy though since they will not accept the X.509 certificate provided by PolarProxy even though it is signed by a trusted root.

PolarProxy is a transparent proxy, which means that, apart from trusting the root CA cert, no configuration is needed on the client in order to have the TLS traffic intercepted. Instead, you’ll need to deploy a firewall DNAT rule that redirects all outgoing TLS traffic to PolarProxy. For instructions on how to do this with iptables, please see the PolarProxy page. For other firewall solutions, however, you’ll need to figure out how to do this yourself.

If you want to learn how to deploy PolarProxy as a container, then take a look at my other blog posts covering how to install PolarProxy in Docker and Podman. I have also written blog posts covering how to integrate PolarProxy with network security monitoring solutions like Arkime and Security Onion.

Erik Hjelmvik is a developer, incident responder, and teacher. He created NetworkMiner, and runs Netresec AB, where he develops network forensics software and occasionally teaches network forensic classes.

This post was originally published at Weberblog.

Rate this article

The views expressed by the authors of this blog are their own and do not necessarily reflect the views of APNIC. Please note a Code of Conduct applies to this blog.

One Comment

  1. Flying Horse

    Hello Eric

    I don’t understand how the system works. This command…

    curl –insecure –resolve

    This will make curl connect to instead of Once the TCP and TLS handshakes are complete between curl and PolarProxy, all the PolarProxy will see is the bare HTTP GET request, like

    GET /

    So, as you can see, the original IP address of is lost! So how does PolarProxy know where to send this GET request?

    Unless, Polar is using TLS SNI field, or HTTP HOST field to dig out the original destination. But these fields are not mandatory. And HOST field is used only in HTTP protocol, which is just one of the many protocols tunneled by TLS. So how does the whole thing work? Can you please throw some light on this.


Leave a Reply

Your email address will not be published. Required fields are marked *