Decrypting TLS Traffic with PolarProxy

This is a guest blog post by Erik Hjelmvik, an expert in network forensics and network security monitoring at NETRESEC.

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 is to inspect encrypted traffic from IoT devices and other embedded products or to analyze 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 Suricata, Zeek 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.

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.PolarProxy decryption flow chart

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:

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:

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 (here: 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 wanna 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.

Photo by Hans-Jurgen Mager on Unsplash.

4 thoughts on “Decrypting TLS Traffic with PolarProxy

  1. Hi Erik, I want to test some DoH/DoT/whatever stuff with PolarProxy. A few questions:

    1) Can I use PolarProxy as the “default gateway” for my victim’s PC? What do I have to use on the PolarProxy machine to configure it that way? Two different NICs? I think you have done something similar at your CS3Sthlm 2019 talk. Do you have a diagram of your setup?

    2) Can I simply use PolarProxy for *all* TCP/UDP connections? Will it output all traffic, that is: the plaintext protocols as well as the encrypted protocols (that are not decrypted)? How will it detect TLS encrypted traffic that is on a non-standard port? Can I man-in-the-middle STARTTLS for FTP or SMTP with it?

    Thanks ;)

  2. 1) It is possible to set up a machine as default GW with just one NIC, but the “normal” practice is to use two NICs; one internal and one external. In my live demo at CS3Sthlm 2019 I configured a Raspberry Pi as explained in this blog post titled “Raspberry Pi WiFi Access Point with TLS Inspection”:

    My CS3Sthlm live demo can be seen here:

    Here’s a network diagram of that setup:

    In essence I configured the Raspberry Pi as a normal Linux-based default gateway (with IP forwarding and NAT) and then added a PREROUTING rule that redirected outgoing traffic destined for TCP 443 to the PolarProxy service instead.

    2) No PolarProxy can only handle TLS traffic, so there is no point in redirecting non-TLS traffic to the proxy. The recommended practice is to only redirect traffic for the ports you want to intercept, such as TCP 443 (HTTPS), 853 (DNS-over-TLS), 990 (FTPS), 465 (SMTPS), 993 (IMAPS), 995 (POP3S) or 5061 (SIP-TLS). PolarProxy does not support STARTTLS, only implicit TLS.

Leave a Reply

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