diff --git a/adr/0022-device-fingerprint-lokal-hinterlegt.md b/adr/0022-device-fingerprint-lokal-hinterlegt.md new file mode 100644 index 0000000..192c833 --- /dev/null +++ b/adr/0022-device-fingerprint-lokal-hinterlegt.md @@ -0,0 +1,46 @@ +# ADR-0022: Device-Fingerprint lokal auf dem Gerät hinterlegt + +**Status:** Beschlossen +**Datum:** 28.08.2026 + +## Kontext + +Beim Nachforschen, warum ein physisch installiertes Test-Notebook +(`tuxflotte-mint-test`) in keiner Geräteliste auftauchte, stellte sich +heraus: die Installation stammte aus der Zeit vor dem Mint-Backend +(04.08.2026) bzw. vor dem WLAN-Zugangsdaten-Mechanismus (21.07.2026) — zu +diesem Zeitpunkt gab es noch keinen Provisioning-Agent, die fehlende +Registrierung war also erwartbar, kein Bug. + +Dabei kam aber eine echte Lücke ans Licht: `device_fingerprint` (SHA256 aus +System-UUID, Seriennummern und MAC-Adressen, `10_hardware.sh: +build_device_fingerprint()`) wird nur einmalig während des Live-Boots +berechnet, an `/api/v1/activate` geschickt und danach **nirgends auf dem +installierten Zielsystem hinterlegt**. Die Kundenplattform-Geräteliste +zeigt ihn an (`geraete_liste.html`), aber steht man vor der physischen +Maschine, gab es keine Möglichkeit, den angezeigten Wert gegenzuprüfen — +Identifikation war nur in einer Richtung möglich. + +## Entscheidung + +Beide Backends (`backends/mint/backend.sh` + `postinstall.sh`, +`backends/fedora/backend.sh` + `kickstart.tpl`) lesen den bereits während +des Live-Boots berechneten Fingerprint jetzt zusätzlich aus der ohnehin +vorhandenen `/run/tuxflotte/hardware/hardware.json` (`.identity. +device_fingerprint`) — bewusst nicht aus der Serverantwort, die nur die +zugewiesene `device_id` kennt, nicht den ursprünglichen Hardware-Hash. +Wird per `envsubst` als neue Variable `TUXFLOTTE_DEVICE_FINGERPRINT` in +den bestehenden Postinstall-/Kickstart-Renderpfad eingespeist (gleiches +Muster wie `TUXFLOTTE_DEVICE_ID`/`TUXFLOTTE_BLUEPRINTS_JSON`) und landet +in einer neuen Klartextdatei `/etc/tuxflotte/device_fingerprint` — +bewusst ohne `chmod 0600` wie bei `agent.credentials`, da reiner +Hardware-Hash ohne Geheimnischarakter. + +## Konsequenzen + +Kein Server-/Datenbankeingriff nötig — reine Installer-seitige Ergänzung, +liest eine bereits vorhandene Datei erneut aus. Lokal verifiziert +(`bash -n` auf dem mit Dummy-Werten `envsubst`-aufgelösten `%post`-Block +bzw. zweistufig aufgelöstem `postinstall.sh`, keine unaufgelösten +`${TUXFLOTTE_...}`-Platzhalter mehr). Volle Live-Verifikation folgt beim +nächsten realen Geräte-Install im Rahmen des Self-Service-Flow-Tests.