Schlüsselverwaltung

Vaultigen verwendet mehrere voneinander unabhängige Schlüssel, damit die Kompromittierung eines Schlüssels nicht unbemerkt die anderen gefährdet. Keiner davon liegt in der Datenbank.

Die Schlüssel

Schlüssel	Erzeugt durch	Gespeichert in	Schützt
Installations-KEK	vaultigen:initialize (oder vaultigen:kek:generate)	storage/app/private/kek.json	Verpackt den Datenschlüssel jedes Tresors.
Tresorschlüssel	Automatisch, einer pro Tresor	Datenbank, verpackt mit dem KEK	Einträge, Revisionen und Dateischlüssel eines Tresors.
Audit-Integritätsschlüssel	vaultigen:initialize	installation.json	Prüfpunkte des Audit-Logs.
Installations-ID	vaultigen:initialize	installation.json	In fast jede kryptografische Operation eingebunden. Nicht geheim, darf sich aber nie ändern.
Passkey-Geheimnis	vaultigen:initialize	installation.json	Reserviert für Passkey-Unterstützung.
Backup-Schlüsselbund	vaultigen:backup-key:generate	storage/app/private/backup.json	Verschlüsselt Backup-Sätze.
APP_KEY	php artisan key:generate	.env	Laravels Schlüssel: Cookies und gespeicherte Authentifizierungsdaten wie TOTP-Geheimnisse.

Alle Dateien werden mit Modus 0600 angelegt und gehören dem PHP-Benutzer.

Bei Docker Compose legt die Einrichtung alle in data/keys/ neben compose.yaml an: app.key (der APP_KEY), installation.json, kek.json und backup.json, im Besitz des Anwendungsbenutzers des Containers (UID 10001). Siehe Docker Compose unten.

Schlüssel erzeugen

Auf einer neuen Installation:

php artisan key:generate                                # APP_KEY
php artisan vaultigen:initialize                        # installation.json + kek.json
php artisan vaultigen:backup-key:generate --if-missing  # backup.json

Jeder Befehl weigert sich, einen vorhandenen Schlüssel zu überschreiben. Erzeugen Sie für eine Installation mit verschlüsselten Daten nie neue Schlüssel. Stellen Sie stattdessen die hinterlegten Dateien wieder her.

Hinterlegung

Geht der KEK-Schlüsselbund verloren, ist jeder Tresor dauerhaft unlesbar. Es gibt bewusst keine Hintertür; eine Umgehung wäre genau das.

• Kopieren Sie installation.json, kek.json, backup.json und APP_KEY direkt nach dem Erzeugen in eine Hinterlegung.
• Bewahren Sie den Backup-Schlüsselbund getrennt vom KEK-Schlüsselbund und von den Backup-Sätzen auf.
• Stellen Sie sicher, dass eine zweite Person die Hinterlegung abrufen kann, falls Sie nicht verfügbar sind.
• Aktualisieren Sie die Hinterlegung nach jeder Rotation.

System → Operations → Keys zeigt Kennung und Vorhandensein jeder Wiederherstellungsvoraussetzung, nie die Werte.

Docker Compose

• Erzeugen: docker compose run --rm setup legt nur fehlende Schlüssel an, und nur für eine leere Datenbank. Eine bestehende Datenbank, deren Schlüssel fehlen, lehnt es ab; stellen Sie dann Ihre Schlüsselkopie wieder her. Ein normales up erzeugt nie Schlüssel.

• Hinterlegung: Kopieren Sie den ganzen Ordner nach der Einrichtung und nach jeder Rotation vom Server weg:

  umask 077
  sudo tar -czf vaultigen-keys.tar.gz -C ~/vaultigen/data keys
  sudo chown "$USER" vaultigen-keys.tar.gz

  Bewahren Sie es mit einer Kopie von .env verschlüsselt und getrennt von den Backups auf und löschen Sie danach das lokale Archiv. Behalten Sie ältere Kopien, solange aufbewahrte Backups ihre Schlüssel brauchen.

• Rotationsbefehle laufen im Web-Container, zum Beispiel docker compose exec web php artisan vaultigen:kek:add. Die Aktionen im Browser funktionieren wie bei jeder Installation.

• Wiederherstellen: Entpacken Sie das Archiv nach data/ (tar -xzf vaultigen-keys.tar.gz -C ~/vaultigen/data), bevor Sie die Wiederherstellung ausführen.

Umgebungsvariablen statt Dateien

Manuelle Installationen auf Hosts, die keine Geheimnisdateien einbinden können, dürfen die Werte über die Umgebung liefern:

Variable	Ersetzt
VAULTIGEN_INSTALLATION_ID	Installations-ID
VAULTIGEN_AUDIT_KEY	Audit-Schlüssel (Base64, 32 Byte)
PASSKEYS_USER_HANDLE_SECRET	Passkey-Geheimnis (Base64, 32 Byte)
VAULTIGEN_KEK_PROVIDER=environment + VAULTIGEN_KEK_KEYRING	KEK-Schlüsselbund als JSON
VAULTIGEN_BACKUP_KEYRING	Backup-Schlüsselbund

Dateien sind vorzuziehen: Werte in der Umgebung gelangen leichter über Prozesslisten und Diagnosen nach außen.

Den Installations-KEK rotieren

Das Neuverpacken ändert nur, wie Tresorschlüssel verpackt sind; Eintragsdaten werden nicht neu geschrieben.

php artisan vaultigen:kek:add      # neuen KEK hinzufügen und aktivieren
php artisan vaultigen:rotate-kek   # jeden Tresorschlüssel damit neu verpacken

Oder nutzen Sie Rewrap installation key unter System → Operations → Keys. Behalten Sie den alten KEK im Schlüsselbund, solange aufbewahrte Backups ihn brauchen könnten, und aktualisieren Sie Ihre Hinterlegung.

Einen Tresorschlüssel rotieren

Verschlüsselt Einträge, Revisionen und Dateischlüssel eines Tresors mit einer neuen Schlüsselversion. Erstellen Sie vorher ein verifiziertes Backup; die alte Version wird erst stillgelegt, wenn ein abgeschlossenes Backup existiert.

php artisan vaultigen:rotate-vault-key <vault-uuid-or-slug>
php artisan vaultigen:rotation:resume <rotation-run-uuid>   # nur wenn sie unterwegs abgebrochen ist

Oder nutzen Sie Rotate a vault key im Browser. Rotationen laufen in fortsetzbaren Stapeln, werden protokolliert und überschreiben nie eine neuere Änderung eines Benutzers.

Den Backup-Schlüssel rotieren

php artisan vaultigen:backup-key:rotate

Fügt einen neuen Backup-Schlüssel hinzu und verschlüsselt jeden aufbewahrten Satz neu. Verwenden Sie --retire-old-keys erst, wenn jede Offline-Kopie neu verschlüsselt wurde oder verworfen werden kann.

APP_KEY und Audit-Schlüssel

• Rotieren Sie APP_KEY nicht im laufenden Betrieb: Gespeicherte Authentifizierungsdaten würden unlesbar. Halten Sie ihn für kompromittiert, behandeln Sie den Host als kompromittiert und stellen Sie ein sauberes Backup wieder her.
• Geht der Audit-Schlüssel verloren, läuft die Anwendung weiter, aber die bestehende Kette lässt sich nicht mehr verifizieren. Rotieren Sie ihn nicht leichtfertig; alte Prüfpunkte lassen sich nicht neu signieren.

Welcher Schlüssel nach einem Vorfall rotiert wird

Vermutete Offenlegung	Maßnahme
kek.json	Neuen KEK hinzufügen und neu verpacken.
Daten eines Tresors	Diesen Tresorschlüssel rotieren, dann die externen Zugangsdaten darin ändern.
backup.json	Backup-Schlüssel rotieren; den alten stilllegen, sobald die Offline-Kopien erledigt sind.
Der ganze Host	Anwendung stoppen, KEK und alle Tresorschlüssel rotieren, ein Backup von vor der Kompromittierung wiederherstellen und externe Zugangsdaten ändern.