Andy Dixon
f3cfa9ccf1
Updated README/architecture/security/limitations/testing/api/CHANGELOG and the LaTeX user guide (now 14pp) with the Certificates and HTTP Explorer screens. 0 called Go vulns, npm audit clean.
93 lines
4.7 KiB
Markdown
93 lines
4.7 KiB
Markdown
# 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.
|