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 would let PiLens decrypt a test device's HTTPS, by having that device explicitly trust it. This is not implemented in this version (Phase 4). When it is, it will be opt-in, per-device, and require you to install and trust the CA on the client yourself. There is no way to do it silently.

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

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.