pilens/docs/tls-and-encryption.md

Encryption: what PiLens can and cannot see

Short version: in capture-only mode PiLens shows you packets and metadata, never decrypted application content. This page explains why, because it is the single most common misunderstanding about a tool like this.

Two completely separate kinds of TLS

1. Management TLS — the HTTPS you use to reach the PiLens web UI on :8443. PiLens generates its own self-signed certificate for this on first start (ECDSA P-256, 5-year). It protects your connection to the appliance and is unrelated to anything captured. The installer prints its SHA-256 fingerprint; verify it the first time your browser warns about it.

2. Interception CA — a separate authority that lets PiLens decrypt a test device's HTTPS, after that device's owner explicitly installs and trusts it. Generated in-app (RSA-2048, PiLens Interception CA), downloadable from the Certificates page (public cert only — the key never leaves the appliance). Interception is a toggle, off by default. There is no way to make a device trust it silently or over the network.

The two are kept independent on purpose: compromising or distributing an interception CA must never affect the management channel.

Mode B: authorised interception (optional, off by default)

Turn it on from Certificates & HTTPS Inspection. PiLens then transparently redirects AP clients' TCP 80/443 to a local mitmdump, which presents certificates signed by the appliance CA. A device that has installed and trusts that CA sees a valid chain, so its HTTPS is decrypted and the transactions appear in the HTTP Explorer. A device that has not installed it sees an untrusted certificate and its connections fail — which is why interception is useless (and harmless) until you do the manual install step on each device you own.

• Redirect is iifname <ap> only, TCP 80/443. The proxy accepts only connections the redirect created (ct status dnat), so it is never an open proxy for clients.
• Excluded hosts (pinned apps, privacy-sensitive sites) are passed straight through, still encrypted.
• Bodies are not retained by default. Enable it per-investigation; the data is on the appliance disk until cleared, and views/exports are audited.
• Pinned apps, private trust stores, mutual TLS and QUIC cannot be intercepted and are reported as such — never bypassed, never downgraded.

Why HTTPS content is unavailable without client trust

TLS exists precisely to stop a device in the middle from reading traffic. To decrypt it, the middle device must present a certificate the client trusts — which means the client must have been configured, by its owner, to trust PiLens's CA. Without that explicit step, PiLens sees only:

• The TLS handshake metadata sent in clear: SNI (the server name, unless Encrypted ClientHello is used), offered/negotiated version, cipher, ALPN.
• The certificate the server sends — but only for TLS 1.2 and earlier. TLS 1.3 encrypts the certificate, so the TLS Explorer's certificate tab is usually empty for modern servers. That is expected.
• Everything after the handshake as ciphertext. "Follow TCP stream" will show it, clearly labelled as encrypted transport bytes, not content.

Cannot be sent via DHCP

A trusted root CA cannot be delivered or installed through DHCP, a captive portal, or any network mechanism. No mainstream OS will trust a CA handed to it by the network — doing so would defeat TLS entirely. Trust is always a manual, explicit action by the device owner. This is a feature, not a limitation.

QUIC and HTTP/3

QUIC carries HTTP/3 inside TLS 1.3 over UDP. PiLens captures it and reads the clear handshake fields (SNI, ALPN), and labels it TLS 1.3 (QUIC). The payload is encrypted. Many apps prefer QUIC, so a lot of "web" traffic appears as QUIC rather than TCP/TLS.

Encrypted DNS (DoH / DoT)

If a client uses DNS-over-HTTPS or DNS-over-TLS, its lookups are inside TLS to a resolver and do not appear in the DNS Explorer — they look like HTTPS/QUIC to that resolver's address. Only cleartext DNS through the appliance's resolver is observable. PiLens never presents encrypted DNS as if it were cleartext.

Certificate pinning

Some apps pin to a specific certificate or key and will refuse any substitute, including a trusted interception CA. When Phase 4 lands, such connections will be reported honestly as failed/pinned rather than silently bypassed — PiLens will never weaken a client's TLS to force a connection through.

IPv6

IPv6 is not inspected, so it is disabled on the AP and dropped in the firewall (see network.md). Clients fall back to IPv4, which is fully captured. This avoids an uninspected escape path.