enricobuehler
9e015304ee
Make the host docs match the real distribution path and the actual CLI. Reviewed by a multi-agent pass (6 editors against one verified fact sheet + an accuracy reviewer); its findings (a wrong client-Recommends claim, a native-concurrency overstatement) folded in. - Install front door: new README "Install (host)" method-picker + docs-site/install.md (+ nav), routing each distro to its package registry; source build demoted to a fallback. - Registry-first install: ubuntu-gnome/ubuntu-kde now lead with the apt registry (not a cargo build); bazzite leads with the Gitea RPM registry (was COPR/source). Source builds moved to an appendix. - CLI accuracy: serve --native arms pairing from the web console (NOT --allow-pairing, which with --require-pairing/--max-concurrent is m3-host-only); --open disables mandatory pairing. host-cli/configuration/pairing/quickstart/troubleshooting corrected; mgmt API documented as always HTTPS+token. Native host serves one session at a time (extras queue) — not multi. - Firewall: real ports documented (native UDP 9777 + the ephemeral data port caveat + GameStream ports) for Debian + Arch (ufw + nftables), not just Bazzite. - Sync/accuracy: punktfunk-client (GTK4) presented as a shipping client (not "roadmap"), punktfunk-client-rs as the headless tool; host Recommends punktfunk-web only (not the client); COPR chroots f43/44; bootc header says Gitea registry not COPR. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
73 lines
3.6 KiB
Markdown
73 lines
3.6 KiB
Markdown
---
|
|
title: Pairing & Trust
|
|
description: How a client and host establish trust — PIN pairing once, pinned reconnects after.
|
|
---
|
|
|
|
punktfunk has no accounts and no cloud. Trust is established directly between a client and a host,
|
|
on your network, with a one-time pairing — either an **approval click in the host's console** or a
|
|
**PIN ceremony**. After that, the device reconnects automatically on a pinned cryptographic
|
|
identity.
|
|
|
|
## How it works
|
|
|
|
- Each host has a stable **identity** (a certificate). Clients remember its fingerprint, so they know
|
|
they're talking to the same host next time.
|
|
- The first time a client connects, you **pair** it: the host shows a short **4-digit PIN**, you type
|
|
it into the client, and a secure exchange (SPAKE2) binds the two identities. An attacker who doesn't
|
|
know the PIN gets a single online guess — no offline cracking.
|
|
- After pairing, the host stores the client's identity in its allow-list, and the client stores the
|
|
host's fingerprint. Reconnects are automatic — no PIN.
|
|
|
|
## Approving a device from the console (no PIN)
|
|
|
|
The fastest way to admit a new device: just **try to connect** from it. On a pairing-required host,
|
|
the attempt shows up in the web console's Pairing page under **Waiting for approval** — with the
|
|
device's name and identity fingerprint. Click **Approve** (and optionally give it a label like
|
|
"Living Room TV"), and the device is paired on the spot: its next connect goes straight through. No
|
|
PIN to read or type.
|
|
|
|
**Deny** just dismisses the request (the device can knock again later — it's "not now", not a
|
|
blocklist). Requests expire on their own after a few minutes.
|
|
|
|
This works because approval happens on the host's authenticated management surface — only someone
|
|
with console access can admit a device.
|
|
|
|
## Pairing with a PIN
|
|
|
|
The PIN ceremony is the other path — useful for the *first* device (before the console has admitted
|
|
anything) or when you're at the client and the console isn't handy.
|
|
|
|
Pairing has to be **armed** on the host before a client can pair (so a random device can't pair
|
|
itself). On the production host (`serve --native`), this is done from the **web console**: open the
|
|
host's management console, click to arm pairing, and the host displays a 4-digit PIN along with the
|
|
list of paired devices. This works on a headless host over the network — there is no command-line flag
|
|
to arm pairing on `serve`.
|
|
|
|
(The standalone headless test host, `m3-host`, takes `--allow-pairing`/`--require-pairing` on its
|
|
command line instead; the production `serve --native` host arms pairing from the console.)
|
|
|
|
Then, on the client:
|
|
|
|
- **Apple app:** select the host (or use *Pair with PIN…* from its menu) and enter the PIN.
|
|
- **Moonlight:** choose **Pair**; Moonlight shows the PIN to confirm on the host side.
|
|
|
|
## Requiring pairing (the default)
|
|
|
|
By default, the native host **requires** pairing — only devices that have paired can stream. This is
|
|
the right setting on a shared network: a device has to complete the PIN ceremony once before it can
|
|
connect.
|
|
|
|
If you're on a fully trusted single-user network and want to skip pairing, start the host with
|
|
`serve --native --open` — but requiring pairing is strongly recommended.
|
|
|
|
## Trust-on-first-use
|
|
|
|
If a host *isn't* requiring pairing, a client connecting for the first time will show the host's
|
|
fingerprint and ask you to confirm it (trust-on-first-use), then pin it. Pairing is the stronger path
|
|
and the default; trust-on-first-use is a convenience for trusted setups.
|
|
|
|
## Managing paired devices
|
|
|
|
The web console lists every paired device and lets you remove one (revoking its access). Re-pairing is
|
|
just the PIN ceremony again.
|