# 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](network.md)). Clients fall back to IPv4, which is fully
captured. This avoids an uninspected escape path.