Rivet

Ihre Anlage vom Handy aus bedienen – ohne offene Tür ins Firmennetz

Rivet verbindet das Handy einer berechtigten Person mit einer Steuerung im lokalen Netz. Vor Ort muss dafür keine Portfreigabe eingerichtet werden, und es ist kein fremder Cloud-Anbieter im Spiel.

Für Fachleute: die Technik im Detail

Alle Angaben unten sind im Repository forgeiec-rivet (Branch development, Stand Commit 5f01540, 22.10.2026) nachprüfbar. Die Spezifikation steht dort in CLAUDE.md. Wir unterscheiden streng: umgesetzt (Code und Tests vorhanden), spezifiziert (in CLAUDE.md beschrieben, nicht programmiert) und geplant/offen (als offene Frage oder „später“ vermerkt).

Stand der Umsetzung

Architektur

Ports auf dem Server (aus server/contrib/nginx/rivet-stream.conf.in, forgeiec-rivet-wg.service.in, settings.py):

Datenwege

1. Browser → Gateway-Oberfläche https://<gerät>.<kunde>.<zone>.forgeiec.io: nginx liest nur den Hostnamen (SNI), schlägt das Ziel in routes.sqlite nach und reicht die Verbindung verschlüsselt mit PROXY-Protocol-Header über den Uplink an 10.78.x.y:443. TLS endet erst im Gateway (rustls); nginx entschlüsselt nichts. Diese Oberfläche dient der Einrichtung.
2. Handy → Dienst im LAN (Weg über den Server, CLAUDE.md 4.13): Handy-WireGuard zu UDP 52000 → Server-Interface phones → Filter phone_access (Handy-Adresse, Gateway-Adresse, TCP-Port) → SNAT auf 10.78.0.2 → Uplink → Gateway. Das Gateway nimmt von 10.78.0.2 nur TCP auf Ports mit Weiterleitung an und öffnet dafür eine eigene TCP-Verbindung im LAN zum Ziel. Das Handy erreicht den Dienst unter <uplink-adresse>:<port>, z. B. http://10.78.0.5:8000, oder per Name über den Mini-DNS.
3. Handy → Gateway direkt (alter Weg, läuft weiter, bis alle Handys umgestellt sind): WireGuard zum UDP-Port des Gateways auf dem Server → nginx → Uplink → Handy-Tunnel im Gateway (10.77.0.0/24, Gateway 10.77.0.1) → Kernel-Weg (TUN rivet0, nftables-DNAT in Tabelle ip rivet) oder, ohne CAP_NET_ADMIN, Weiterleitung im Userspace (smoltcp).
4. Gateway → Portal: HTTPS direkt übers Internet (nicht durch den Uplink), damit die Registrierung ohne Uplink funktioniert: register, heartbeat, cert, peers (Long-Poll), uplink-key.

Uplink im Gateway (client/src/net/uplink.rs): ein boringtun::noise::Tunn mit dem Server als einzigem Peer über einen gewöhnlichen, ausgehenden UDP-Socket, dahinter ein smoltcp-Stack mit der Adresse 10.78.x.y. Angenommen wird nur, was an diese Adresse geht: von 10.78.0.1 (nginx) TCP 443/80, UDP 51820 und ICMP; von 10.78.0.2 nur TCP. Fragmente und alle anderen Absender werden verworfen. Keepalive 15 s, MTU 1280. Nach 180 s ohne Handshake öffnet das Gateway einen neuen UDP-Socket und löst den Servernamen neu auf (gegen einseitig tote NAT-Zuordnungen im Mobilfunk). Höchstens 256 gleichzeitige Verbindungen im Uplink-Stack.

Betriebsarten (Feld uplink_mode im Portal, models.py): rivet (Rivet-Gateway hält den Tunnel selbst), router (der WireGuard des Routers hält den Tunnel, ein Rivet-Gateway dahinter bindet sich per Code an), client (reiner WireGuard-Client ohne Rivet, kein Heartbeat). Erstes Router-Ziel laut CLAUDE.md: Teltonika RUT241, Anleitung docs/router-rutos.md.

Adressschema und Zertifikate

Die Namen ergeben sich aus vier Ebenen (server/portal/gateways/hosts.py; die Basisdomain ist eine Einstellung, Vorgabe forgeiec.io):

Die README nennt noch das ältere Schema <slug>.<zone>.forgeiec.io; der Code verwendet das obige.

• Wildcard-Zertifikat je Kunde *.<kunde>.<zone>.<basis>: ausgestellt von certbot mit certbot-dns-hetzner (DNS-01, ECDSA) aus dem venv des Portals; Erneuerung per Timer forgeiec-rivet-certs (täglich 03:00 und 15:00).
• Verteilung: Der Deploy-Hook import_wildcard_cert legt den privaten Schlüssel Fernet-verschlüsselt in der Portal-Datenbank ab und erhöht die cert_version des Kunden. Das Gateway sieht die höhere Version in der Heartbeat-Antwort und holt GET /api/v1/cert (Bearer-Schlüssel des Gateways, Antwort mit Cache-Control: no-store). Jeder Abruf wird in CertFetchLog protokolliert. Gesperrte Gateways bekommen nichts (API 403).
• Prüfung im Gateway (client/src/tls.rs) vor der Übernahme: PEM lesbar, Schlüssel passt zum Zertifikat, Name deckt die eigene Adresse ab, nicht abgelaufen, neuer als das aktive. Dann atomar geschrieben (Schlüssel 0600) und per ArcSwap ohne Neustart aktiviert. Fehlt ein gültiges Wildcard, nutzt das Gateway ein selbst signiertes Zertifikat (rcgen).
• Portale haben eigene Zertifikate; ein Gateway-Wildcard deckt sie nicht ab. Notfall-Rotation je Zone im Betreiberbereich und im Django-Admin (services.emergency_rotation).
• DNS: Das Portal pflegt die Einträge bei Hetzner (gateways/dns.py, Timer forgeiec-rivet-dns alle 15 Minuten) und fasst nur Einträge mit seinen eigenen Labels an.

Identität und Berechtigung

• Anmeldung am Gateway (client/src/auth.rs, web.rs): Vergleich in konstanter Zeit (subtle), verschlüsseltes Sitzungs-Cookie (Rocket secrets) für 12 Stunden mit einem Präfix des Schlüssel-Hashes, so dass ein neuer Schlüssel alle Sitzungen beendet. Fehlversuche: 1 s Verzögerung, höchstens 5 je Quell-IP und 30 insgesamt in 5 Minuten.
• Registrierung: POST /api/v1/register ohne Anmeldung, begrenzt auf 10/hour je Client-IP (FORGEIEC_RIVET_REGISTER_RATE). Alle anderen API-Aufrufe mit Bearer-Schlüssel, im Portal nur als Hash.
• Handy einrichten: QR-Code und .conf-Datei entstehen im Browser; der private Schlüssel verlässt die Seite nie. Alternativ ein Einrichtungslink per Mail: im Portal nur der SHA-256 des Tokens, 7 Tage gültig, einmal verwendbar.
• Portal-Konten sind an ihre Ebene gebunden; Rechte je Mitgliedschaft: Handys, Gateways, Benutzer verwalten. Die Sitzung gilt nur für den Host, an dem sie entstand.

Isolation

• Was ein Handy erreicht (Weg über den Server): nur TCP zu (Handy-Adresse, Uplink-Adresse eines Gateways, Port) aus der Zugriffsliste. Sie enthält die Weiterleitungen aller aktiven Gateways seines Kunden; Regeln mit Zugang „Service“ nur für Handys mit Zugang „Service“. Dazu der Mini-DNS auf 10.79.0.1:53. Alles andere aus phones wird verworfen (fw.rs).
• Was ein kompromittiertes Gateway erreicht: Auf dem Server gilt iifname "uplink" oifname "uplink" drop und iifname "uplink" drop: keine anderen Gateways, kein Routing über den Server. Zu den Handys nur Antworten (oifname "phones" nur established,related). Es besitzt aber den Wildcard-Schlüssel seines Kunden und kann sich damit als jedes andere Gateway dieses Kunden ausgeben, wenn es zusätzlich DNS oder Verkehr umleiten kann (in CLAUDE.md Abschnitt 5 als bewusst akzeptiertes Risiko beschrieben).
• Was der Server erreicht: Das Gateway nimmt aus dem Uplink nur die oben genannten Verbindungen an; ins LAN führen nur die Weiterleitungen aus dem Portal. Ohne Weiterleitung wird nichts weitergeleitet.
• Was der Server sieht: HTTPS zur Gateway-Oberfläche läuft verschlüsselt durch (Passthrough). Den inneren Verkehr der Handys auf dem Weg über den Server sieht er dagegen, weil er die Handy-Tunnel entschlüsselt (CLAUDE.md 4.13: „bewusst akzeptiert“). Was die Anwendung nicht selbst verschlüsselt, liegt dort im Klartext vor.
• Überlappende LAN-Netze sind möglich: In kein LAN wird geroutet, der Server kennt nur die je Gateway eindeutige 10.78.x.y.

Routing-Modul ngx_stream_rivet_module

Betrieb

Hinweis: Die README beschreibt den Gateway-Dienst noch ohne nftables und nur mit CAP_NET_BIND_SERVICE. Der aktuelle Code braucht für den Kernel-Weg zusätzlich CAP_NET_ADMIN (TUN rivet0, nftables per Netlink, ohne externe Programme).

Plattformen, Pakete und Bau

• Gebaut für 12 Slots, Gateway und Server gleich: Debian 12/13 und Ubuntu 22.04/24.04, je amd64, arm64 und armhf (client/contrib/slot-build.sh --list). Als Zielhardware des Gateways nennt CLAUDE.md Debian 12 arm64 und Ubuntu 24.04 armhf. Das nginx-Modul ist laut seiner README nur gegen nginx 1.26.3 (Debian 13) gebaut und getestet.
• Pakete: forgeiec-rivet (cargo-deb) und forgeiec-rivet-server (CMake/CPack), gebaut nativ im Container der Zielarchitektur (podman, qemu-user), nicht per Cross-Compile.
• client/deploy.sh: build (Standard), rebuild, test, run (Probelauf ohne root auf 8443/8080), peer, package, slot <s|all>, install, restart, clean, help. server/deploy.sh: configure, rebuild, test, run, package, install, restart, clean, slot, help.
• CI: Forgejo-Workflows client.yml und server.yml, je eine Matrix über die 12 Slots; nach apt.forgeiec.io veröffentlicht nur main.

Qualität

Der Lasttest des nginx-Moduls (laut dessen README, 1000 Verbindungen mit 20 parallelen Clients, Ryzen 9 9950X im Podman-Container) ergab rund 11 600 Verbindungen pro Sekunde mit und ohne DB-Abfrage; die gemessene Latenz bestimmt dort der Python-Client, nicht die Abfrage. Weitere Leistungs- oder Verfügbarkeitszahlen gibt es nicht.

Repository

client/          Gateway (Rust): src/{main,auth,config,front,tls,web,setup,sync,portal,forwards}.rs,
                 src/net/{uplink,hub,peers,stack}.rs, src/sys/{tun,rtnl,nft}.rs, templates/, locale/
server/portal/   Django-Projekt rivet_server, App gateways (Modelle, API, Ebenen, Tests)
server/wg-daemon/  forgeiec-rivet-wg (Rust, Netlink, nftables, Mini-DNS)
server/nginx-module/  ngx_stream_rivet_module (C) mit Unit-, Integrations- und Lasttest
server/contrib/  systemd-Units und Timer, debconf/postinst, nginx-Vorlagen
docs/            api-v1.md, betrieb-server.md, router-rutos.md
.github/workflows/  client.yml, server.yml

Bedrohungsmodell (soweit CLAUDE.md es nennt)

• Gemeinsamer Wildcard-Schlüssel je Kunde (bewusst akzeptiert): Wer ein Gateway ausliest, kann sich als beliebige Adresse unter *.<kunde>.<zone> ausgeben, nicht aber als Gateway eines anderen Kunden oder als Portal. Gegenmaßnahmen laut Spezifikation: Ausnutzen braucht zusätzlich Umleitung von DNS oder Verkehr; Portale unter eigenen Zertifikaten; Sitzungs-Cookie nur für den eigenen Host; Notfall-Rotation; gesperrte Gateways bekommen keine neuen Zertifikate; kurze Laufzeiten von Let’s Encrypt.
• Der Server ist der Vertrauensanker: Er verteilt die Schlüssel und sieht den inneren Verkehr der Handys auf dem Weg über den Server (bewusst akzeptiert).
• Router-Gateways: Ob der Server ins LAN kommt, entscheidet dort die Firewall des Routers, nicht Rivet.
• Manipulierte Routing-Datenbank: Das nginx-Modul nimmt nur Ziele innerhalb allow_backend an.
• ECH würde den SNI verbergen; für die Rivet-Zonen werden deshalb keine DNS-HTTPS-Records mit ECH veröffentlicht.
• UDP gesperrt oder gedrosselt im Mobilfunk: Dann steht der Uplink nicht (offene Frage 11).
• Abhängigkeit vom Server: Ohne Server kein Fernzugriff; das LAN selbst arbeitet weiter (offene Frage 8).

Bekannte Grenzen

• Weiterleitungen nur für TCP; höchstens 20 Regeln je Gateway; im Tunnel nur IPv4.
• Kommt ein Gateway zum Kunden hinzu, braucht das Handy eine neue Konfiguration (AllowedIPs).
• Kein Ausweichweg, wenn UDP gesperrt ist; kein Direktzugang bei Serverausfall.
• Theme-Übernahme auf dem Gateway, Alarm-Mails, install.sh und der Selbsttest für Router-Gateways fehlen noch (siehe Stand der Umsetzung).
• Zwei Handy-Wege laufen parallel, bis der alte über das Gateway entfällt.

Im Unterschied zu …

Die Tabelle nennt nur Eigenschaften, die aus dem Aufbau folgen.