Root-Key sicher rotieren

Diese Betriebsseite richtet sich an Administratoren einer selbst gehosteten Workspace-Installation. Nutzen Sie sie, wenn Sie einen Schlüsseltausch planen, eine ältere Installation auf ein Root-Key-Bundle umstellen oder einen kompromittierten Schlüssel abschalten müssen.

Nach Abschluss verwendet jeder beteiligte Prozess dasselbe Bundle mit der gewünschten aktiven Schlüsselversion. Sie haben den alten Schlüssel entweder sicher für die notwendige Übergangszeit behalten oder nach vollständig erfüllten Prüfungen entfernt.

Wählen Sie zuerst den richtigen Weg

Ihre Situation	Richtiger Weg	Was mit dem alten Schlüssel geschieht
Ihre Installation verwendet noch einen einzelnen Legacy-`NUCLEUS_KEY`.	Migrieren Sie zuerst auf das Bundle-Format.	Das Schlüsselmaterial bleibt unverändert. Das ist noch keine Rotation.
Sie tauschen den Schlüssel geplant aus und es gibt keinen Sicherheitsvorfall.	Verwenden Sie die Routine-Rotation.	Der alte Schlüssel bleibt nach dem Beobachtungsbeginn 365 Tage entschlüsselungsfähig.
Der Schlüssel ist bestätigt oder mit hoher Wahrscheinlichkeit kompromittiert.	Verwenden Sie die Emergency-Rotation.	Sie dürfen nur die verbleibende Wartezeit überspringen. Alle technischen Prüfungen bleiben verpflichtend.
Eine Prüfung ist unvollständig oder blockiert.	Brechen Sie ab oder rollen Sie auf das letzte vollständige Bundle zurück.	Entfernen Sie den alten Schlüssel nicht. Einen ungeprüften `--force`-Weg gibt es nicht.

Wenn Sie nicht sicher wissen, welcher Fall vorliegt, behandeln Sie den Vorgang als blockiert. Eine langsamere sichere Rotation ist besser als ein unwiederbringlich entfernter Schlüssel.

Verstehen Sie die Werkzeuggrenzen

nucli bedient einen laufenden Server über authentisierte APIs. Es darf keine lokalen Root-Key-Bundles, Config-Keys, Datenbanken oder Storage-Dateien lesen. Der eingebaute Skill erklärt deshalb den Ablauf, führt die Rotation aber nicht selbst aus:

bash

nucli skills show root-key-rotation

MCP-Clients erhalten denselben Inhalt über nucleus_root_key_rotation_skill. Der MCP-Aufruf nimmt keine Key-Werte oder Dateipfade entgegen.

Nutzen Sie für Bundle, Konfiguration, Inventur und Retirement ausschließlich den freigegebenen, versionsgleichen und privilegierten Betriebsweg Ihrer Installation. Verwenden Sie weder direkte Datenbankänderungen noch eigene Skripte als Ersatz. numin beschreibt die eng begrenzten Offline-Verträge von numin; Root-Key-Rotation gehört nicht dazu.

Bereiten Sie den Wechsel vor

Prüfen Sie vor jeder Änderung:

Sie besitzen eine aktuelle Sicherung von PostgreSQL, Storage, verschlüsselter Konfiguration und aktuellem Root-Key-Bundle.
Sie haben den Restore außerhalb der Produktion getestet.
Ihre Secret-Verteilung erreicht jeden Prozess, der verschlüsselt, entschlüsselt, signiert oder verifiziert.
Sie kennen alle erwarteten Prozessrollen, mindestens Workspace-Server und Ingress.
Monitoring und Inventur können alte und neue kid getrennt ausweisen.
Ein dokumentiertes Change-Fenster und ein Rückweg zum letzten vollständigen Bundle liegen vor.

Führen Sie die gemeinsamen Phasen aus

Routine und Emergency verwenden denselben technischen Ablauf:

Bereiten Sie eine neue Schlüsselversion vor, ohne sie sofort zu aktivieren.
Verteilen Sie das vorbereitete Bundle über Ihre Geheimnisverwaltung an alle erwarteten Prozesse.
Starten Sie die betroffenen Go-Dienste neu. Aktivieren Sie die neue kid erst, wenn alle Prozesse dasselbe Bundle melden.
Verteilen Sie das aktivierte Bundle und starten Sie die Prozesse erneut.
Verschlüsseln Sie die Serverkonfiguration mit der aktiven kid neu.
Schreiben Sie unterstützte verschlüsselte Datensätze nur über ihre autoritativen Produkt-APIs neu. Ändern Sie Ciphertexte niemals direkt in PostgreSQL.
Prüfen Sie verschlüsselte Bestände und jede Runtime-Domäne. Starten Sie danach den geschützten Observation-State.
Wählen Sie Routine oder Emergency. Entfernen Sie die alte kid erst, wenn der gewählte Weg und alle gemeinsamen Prüfungen freigegeben sind.
Verteilen Sie das reduzierte Bundle, starten Sie alle Prozesse neu und prüfen Sie die endgültige Konvergenz.

Lesen Sie die Prüfungen in Alltagssprache

Prüfung	Bedeutung	Erfolgreiches Ergebnis
Distribution	Alle erwarteten Prozesse besitzen dasselbe Bundle und dieselbe aktive `kid`.	`clear`
Inventur	Konfiguration, Felder und Blobs benötigen die alte `kid` nicht mehr. Fehlende oder ungültige Bestände zählen als Blocker.	Keine Referenz und kein offener Befund
Runtime-Beobachtung	Jede relevante Signatur- und Verifikationsdomäne hat die neue `kid` nach der Aktivierung verwendet.	Alle erwarteten Domänen beobachtet
Fehlerfreiheit	Es gibt keine relevanten Decrypt-, Verify-, Replay-, Signier- oder Unknown-KID-Fehler.	Fehlerzähler bleiben null
Observation	Der Zustand bindet Modus, Startzeit, Bundle-Fingerprint, Ziel-`kid` und erwartete Rollen.	Passender Zustand vorhanden
Removal-Gate	Die konkrete alte `kid` besitzt keine bekannte Abhängigkeit mehr.	`retirement` und `retirement_gate[<kid>]` sind `clear`

Eine nicht erreichbare Datenbank, ein unvollständiger Storage-Scan oder eine fehlende Prozessrolle bedeutet nicht „kein Bestand“. Es bedeutet „nicht geprüft“ und blockiert die Entfernung.

Routine-Rotation verwenden

Nutzen Sie Routine für geplante Wartung ohne Kompromittierungsverdacht. Nach Aktivierung und freier Distribution starten Sie den Observation-State genau einmal. Workspace wartet anschließend 365 Tage, weil noch gültige Newsletter-Abmeldelinks so lange mit dem alten Schlüssel signiert sein können.

Während dieser Zeit bleibt die alte kid nur zum Entschlüsseln und Verifizieren im Bundle. Neue Verschlüsselungen und Signaturen verwenden die aktive kid. Prüfen Sie die Gates während des Beobachtungszeitraums erneut, besonders nach Deployments, Restores und Änderungen an Prozessrollen.

Emergency-Rotation verwenden

Nutzen Sie Emergency nur bei einem bestätigten oder sehr wahrscheinlichen Kompromiss. Dokumentieren Sie eine Incident-Referenz ohne Geheimnisse und bestätigen Sie ausdrücklich, dass noch gültige Tokens ungültig werden dürfen.

Emergency überspringt ausschließlich die verbleibende Beobachtungszeit. Sie müssen weiterhin Distribution, vollständige Inventur, Runtime-Beobachtung, Fehlerfreiheit und das Removal-Gate der konkreten kid erfüllen. Planen Sie die tatsächliche Abschaltzeit ab dem Incident deshalb als Summe aus Bundle-Verteilung, Neustarts, Rekey, Inventur und Metrikkonvergenz. Es gibt keine allgemeine Zeitgarantie für unterschiedliche Installationen.

Wenn ein nichtzeitliches Gate blockiert, behalten Sie die alte kid und begrenzen Sie stattdessen sofort den Zugang zum Secret-Store, zu Hosts und zu Deployment-Kanälen. Emergency ist kein force-Schalter.

Legacy-Key auf ein Bundle umstellen

Eine Legacy-Migration ändert zunächst kein Schlüsselmaterial. Sie verpackt den vorhandenen einzelnen NUCLEUS_KEY versionsgebunden in das Bundle-Format, verteilt dieses Bundle und prüft nach den Neustarts den gemeinsamen Fingerprint. Führen Sie erst danach eine normale Rotation mit einer neuen kid durch.

Behandeln Sie „Bundle-Migration“ und „Rotation“ als zwei getrennte Change-Schritte. Dadurch bleibt im Fehlerfall klar, ob das Format oder das neue Schlüsselmaterial die Ursache ist.

Erfolg erkennen

Die Rotation ist abgeschlossen, wenn:

alle erwarteten Prozesse denselben finalen Bundle-Fingerprint und dieselbe aktive kid melden,
geschützte Konfigurationen, Secrets und Blobs weiterhin lesbar sind,
keine At-Rest-Referenz oder neue Signatur die entfernte kid verwendet,
distribution, drain, retirement und das konkrete Removal-Gate frei sind,
keine Unknown-KID-, Verify-, Decrypt- oder Read-Fehler auftreten,
das reduzierte Bundle ausschließlich über die Geheimnisverwaltung verteilt wurde und keine Key-Werte in Betriebsnachweisen stehen.

Ein abgebrochener oder unvollständiger Prüflauf ist kein Erfolg. Behalten Sie den alten Schlüssel und wiederholen Sie die Prüfung vollständig.

Nächste Schritte

Prüfen Sie Blob-Bestände mit Blob-v2-Schlüsselinventur.
Ordnen Sie Backup, Secret-Verteilung und Logging unter Betriebssicherheit ein.
Planen Sie Binär- und Prozessrollouts mit Updates und Rollback.
Verwenden Sie nucli für authentisierte Serverdiagnose, nicht für lokale Key-Dateien.