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