14 KiB
Bad-Signature-Toolkit
Werkzeuge zum Aufspüren und Beheben von "Bad Signature"-Fehlern der Nextcloud Server-Side-Encryption (Dateien, die sich wegen einer fehlerhaften Verschlüsselungs-Signatur nicht mehr öffnen lassen).
Alle Scripte laufen als root auf dem jeweiligen Nextcloud-Server und
können auch ganz ohne Parameter aufgerufen werden – -s <website>
ist optional, nicht Pflicht. Fehlt es, ermittelt das Script alle
konfigurierten Instanzen anhand der .conf-Dateien im conf/-
Verzeichnis neben den Scripten. Gibt es davon mehrere (mehrere
Nextcloud-Instanzen auf demselben Server), wird interaktiv eine
Auswahlliste angezeigt, aus der die gewünschte Website ausgewählt wird.
Das gilt für alle sechs Scripte gleichermaßen.
Der Ablauf auf einen Blick
1. scan_bad_signature.sh Betroffene Dateien FINDEN (read-only)
2. recover_bad_signature.sh Dateien probeweise ENTSCHLÜSSELN (read-only,
schreibt nur außerhalb von Nextcloud)
3. restore_bad_signature.sh Geprüfte Dateien ZURÜCKSCHREIBEN (live-Schreibzugriff)
4. recreate_bad_signature.sh Fallback für die Fälle, die (3) (live-Schreibzugriff,
nicht reparieren kann bricht Freigaben!)
5. delete_bad_signature.sh Nicht rettbare Dateien LÖSCHEN (Dateisystem-Bypass +
(letzter Ausweg nach 3 und 4) direktes DB-Cleanup,
kein Papierkorb!)
delete_files.sh Explizite Dateiliste LÖSCHEN (live-Schreibzugriff,
(unabhängig vom obigen Ablauf) -> Papierkorb)
Jeder Schritt liest den Report des vorherigen Schritts. Reports landen
alle unter reports/ (Dateiname verrät den Schritt: bad_signature_…,
recovery_…, restore_…, recreate_…, delete_…).
1. scan_bad_signature.sh – Betroffene Dateien finden
Liest einmal jede verschlüsselte Datei eines/mehrerer/aller Accounts und protokolliert, welche dabei mit einem Signaturfehler scheitert. Rein lesend – verändert, verschiebt oder löscht nichts.
./scan_bad_signature.sh -s <website>
# oder ganz ohne Parameter - Website wird interaktiv abgefragt
# (bei mehreren konfigurierten Instanzen als Auswahlliste):
./scan_bad_signature.sh
→ Ergebnis: reports/bad_signature_<website>_<datum>.tsv
2. recover_bad_signature.sh – Versuchsweise entschlüsseln
Schaltet die Signaturprüfung instanzweit, nur für die Laufzeit des
Scripts ab (encryption_skip_signature_check) und versucht, die
betroffenen Dateien trotzdem zu entschlüsseln. Funktioniert nur, wenn
die Signaturprüfung selbst das Problem ist – nicht bei tatsächlich
beschädigtem Chiffretext. Jede gewonnene Datei wird automatisch geprüft
(Dateityp-Signatur, PDF-/ZIP-Integrität, Plausibilität der Dateigröße
o. Ä.) und als VALID, UNVERIFIED ("Nicht prüfbar") oder INVALID
("Datenmüll") eingestuft.
Wichtig: Original-Dateien in Nextcloud werden nie angefasst. Alles
landet in einem separaten Verzeichnis außerhalb von Nextclouds eigener
Ablage (/var/nc-recovery/<website>/…) – dort liegen danach
unverschlüsselte Daten, also nach Gebrauch aufräumen.
./recover_bad_signature.sh -s <website>
# oder ganz ohne Parameter - Website wird interaktiv abgefragt:
./recover_bad_signature.sh
# Nur erneut validieren (z. B. nach einem Script-Update mit neuen
# Prüfregeln), ohne nochmal zu entschlüsseln:
./recover_bad_signature.sh -V -s <website>
→ Ergebnis: reports/recovery_<website>_<datum>.tsv
3. restore_bad_signature.sh – Zurückschreiben (Regelfall)
Schreibt die in Schritt 2 gewonnenen Dateien über die normale Nextcloud-Files-API an ihren ursprünglichen Pfad zurück – der einzige Weg, der Datei-ID und bestehende Freigaben erhält. Danach ist die Datei wieder ganz normal verschlüsselt, mit frischer, korrekter Signatur.
Seit dem letzten Update werden standardmäßig zwei Kategorien
zurückgeschrieben, klar unterscheidbar im Report (Spalte origin):
| validation im Recovery-Report | Bedeutung | wird restauriert |
|---|---|---|
VALID |
dedizierte Strukturprüfung hat den Inhalt bestätigt | ja |
UNVERIFIED, Größe plausibel |
kein dedizierter Check, aber nichts sieht falsch aus | ja |
UNVERIFIED, Größe "LOOKS OFF" |
Größenverhältnis auffällig – echtes Warnsignal | nein |
INVALID ("Datenmüll") |
Strukturprüfung fehlgeschlagen | nein |
./restore_bad_signature.sh -s <website>
# oder ganz ohne Parameter - Website wird interaktiv abgefragt:
./restore_bad_signature.sh
# nur Dry-Run (nichts wird geschrieben):
./restore_bad_signature.sh -n -s <website>
Fragt danach interaktiv: welcher Recovery-Report, welche(r) Account(s).
Sicherheit: Neuvalidierung direkt vor jedem Schreiben · aktueller
(noch kaputter) Chiffretext wird vorher byte-genau gesichert
(/var/nc-restore-backup/<website>) · jede Datei wird nach dem
Schreiben normal zurückgelesen und per SHA-256 verglichen · Dry-Run ist
Default, echter Lauf braucht eine ausdrückliche YES-Bestätigung.
⚠️ Ein erneuter Lauf wählt wieder alle passenden Einträge des gewählten Accounts aus dem Report – auch bereits erfolgreich restaurierte, nicht nur neue. Für ein gezieltes Nachziehen einzelner, noch offener Dateien lieber einen auf diese Dateien reduzierten Mini-Report verwenden, statt den ganzen Account-Bestand erneut zu überschreiben.
→ Ergebnis: reports/restore_<website>_<datum>.tsv
4. recreate_bad_signature.sh – Fallback für Schlüsselmaterial-Fehler
Nur nötig, wenn restore_bad_signature.sh bei einer Datei mit einem
Schlüsselmaterial-Fehler scheitert (MultiKeyDecryptException /
"probably this is a shared file…") statt mit "Bad Signature". Löscht
die kaputte Datei auf reiner Dateisystem-Ebene (inkl. altem
Schlüssel-Verzeichnis) und legt sie komplett neu an, mit frischem
Schlüssel.
⚠️ Invasiver als restore: Die Datei bekommt eine neue Datei-ID – bestehende Freigaben, Kommentare, Tags und Versionshistorie dieser Datei gehen dabei verloren und müssten danach manuell neu eingerichtet werden. Nur verwenden, wenn Schritt 3 tatsächlich mit diesem spezifischen Fehler gescheitert ist.
./recreate_bad_signature.sh -s <website>
# oder ganz ohne Parameter - Website wird interaktiv abgefragt:
./recreate_bad_signature.sh
# Dateien mit aktiven Freigaben standardmäßig übersprungen,
# nur mit Bedacht einschließen:
./recreate_bad_signature.sh -f -s <website>
Sicherheit: Nur Dateien mit passendem Fehler aus dem
restore-Report werden angefasst · Chiffretext UND Schlüssel-Verzeichnis
werden vorher gesichert und die Sicherung vor dem Löschen verifiziert
(/var/nc-recreate-backup/<website>) · Dateien mit aktiven Freigaben
werden standardmäßig übersprungen · Verifikation nach dem Schreiben wie
bei restore.
→ Ergebnis: reports/recreate_<website>_<datum>.tsv
5. delete_bad_signature.sh – Letzter Ausweg für nicht rettbare Dateien
Für Dateien, bei denen weder restore_bad_signature.sh noch
recreate_bad_signature.sh geholfen hat und die nicht mehr
erhaltenswert sind: löscht sie vollständig, indem die
Verschlüsselungsschicht vollständig umgangen wird.
Hintergrund: Dateien mit kaputten Signaturen können nicht über die
normale Nextcloud-API oder WebDAV gelöscht werden – auch ein normaler
rm im Dateisystem reicht nicht, weil der Filecache-Eintrag in der
Datenbank bestehen bleibt und Nextcloud die Datei weiterhin anzeigt.
Außerdem blockieren solche Dateien die Archiv-/Download-Funktion
(Nextcloud wirft bei jedem Versuch, sie einzuschließen, eine
DecryptionFailedException). Dieses Script erledigt daher drei Dinge:
- Rohen Chiffretext per
rm -fvom Dateisystem entfernen - Schlüsselmaterial-Verzeichnis per
rm -rfentfernen - Filecache-Eintrag, Freigabe-Einträge und Sperren direkt per MySQL-Abfragen aus der Datenbank löschen
Das Script benötigt kein INSTALL_DIR, HTTP_USER oder PHP –
das Datenbank-Cleanup erfolgt direkt über den MySQL-Client.
Standardverhalten (sicher): Alle recreate_<website>_*.tsv-Reports
im reports/-Verzeichnis werden automatisch ausgewertet. Dateien, die
dort bereits als OK oder WRITTEN_UNVERIFIED stehen (erfolgreich
wiederhergestellt), werden nicht gelöscht. So werden nur Dateien
entfernt, die tatsächlich nicht gerettet werden konnten.
DATA_DIR-Erkennung: Wenn DATA_DIR in der conf-Datei nicht
gesetzt ist, versucht das Script es automatisch aus WEB_BASE_DIR/data
oder /var/www/<website>/data abzuleiten – mit interaktiver
Bestätigung, bevor fortgefahren wird.
./delete_bad_signature.sh -s <website>
# oder ganz ohne Parameter - Website wird interaktiv abgefragt:
./delete_bad_signature.sh
# Dry-Run: zeigt, was gelöscht würde, ohne etwas zu verändern:
./delete_bad_signature.sh -n -s <website>
# Alle kaputten Signaturdateien löschen, auch bereits recreatete
# (Vorsicht!):
./delete_bad_signature.sh -a -s <website>
# Zusätzlichen recreate-Report für den Ausschluss angeben:
./delete_bad_signature.sh -x reports/recreate_<website>_<datum>.tsv -s <website>
Pflicht-Variablen in der conf-Datei:
| Variable | Beschreibung |
|---|---|
DATABASE_NAME |
Name der Nextcloud-Datenbank |
DATABASE_TYPE |
Muss mysql sein (PostgreSQL noch nicht unterstützt) |
MYSQL_CREDENTIALS |
MySQL-Client-Argumente, z. B. -u root -S /run/mysqld/mysqld.sock |
Optionale Variablen (werden auto-erkannt oder haben Defaults):
| Variable | Beschreibung | Default |
|---|---|---|
DATA_DIR |
Nextcloud-Datenverzeichnis | auto-erkannt aus WEB_BASE_DIR/data oder /var/www/<website>/data |
WEB_BASE_DIR |
Nextcloud-Webroot | – |
DB_TABLE_PREFIX |
Datenbank-Tabellenpräfix | oc_ |
DELETE_BACKUP_BASE_DIR |
Backup-Verzeichnis vor dem Löschen | ein Verzeichnis über DATA_DIR |
⚠️ Kein Papierkorb. Die Dateien werden unwiderruflich entfernt –
lediglich ein Backup des Chiffretexts und des Schlüssel-Verzeichnisses
wird unter DELETE_BACKUP_BASE_DIR angelegt, bevor gelöscht wird. Das
ermöglicht ein manuelles Wiederherstellen auf Dateisystem-Ebene, aber
kein automatisches "Rückgängig" innerhalb von Nextcloud.
→ Ergebnis: reports/delete_<website>_<datum>.tsv
delete_files.sh – Gezielt nicht benötigte Dateien löschen
Generisches, von Account und Site unabhängiges Script für den zweiten Teil des Aufräum-Workflows: eine von Hand geprüfte Liste an Dateien entfernen, die nicht erhaltenswert sind (z. B. macOS-Spotlight- Indexdateien, Fragmente aus "Webseite speichern"). Kein Scannen, kein automatisches Erraten – jede Zeile in der Liste ist eine bewusste Entscheidung.
Pfadliste: einfache Textdatei, ein Pfad pro Zeile (#-Kommentare und
Leerzeilen erlaubt), Account wird automatisch aus dem Pfad erkannt:
/inge/files/Ordner/Datei.ext
/anderer-account/files/Anderer/Pfad/datei2.ext
./delete_files.sh -s <website> -f <pfadliste.txt>
# oder ganz ohne Parameter - Website UND Pfad zur Liste werden
# interaktiv abgefragt:
./delete_files.sh
# nur Dry-Run:
./delete_files.sh -n -s <website> -f <pfadliste.txt>
Löscht über die normale Files-API (→ Papierkorb, sofern
files_trashbin aktiv ist) und sichert den Chiffretext zusätzlich
byte-genau vorher (/var/nc-delete-backup/<website>). Ein bereits
nicht mehr existierender Pfad wird als NOT_FOUND gemeldet, nicht als
Fehler.
→ Ergebnis: reports/delete_<website>_<datum>.tsv
Typischer Ablauf
./scan_bad_signature.sh -s cloud-01.oopen.de # betroffene Dateien finden
./recover_bad_signature.sh -s cloud-01.oopen.de # entschlüsseln + prüfen
./restore_bad_signature.sh -s cloud-01.oopen.de # VALID + plausible zurückschreiben
# nur bei einzelnen WRITE_ERROR mit Schlüsselmaterial-Fehler nötig:
./recreate_bad_signature.sh -s cloud-01.oopen.de
# letzter Ausweg: nicht rettbare Dateien bereinigen
# (schließt automatisch alle erfolgreich recreateten aus):
./delete_bad_signature.sh -s cloud-01.oopen.de
# optional: von Hand geprüfte, nicht erhaltenswerte Dateien entfernen
./delete_files.sh -s cloud-01.oopen.de -f nicht_benoetigt.txt
# zur Kontrolle: sollte jetzt (für erledigte Accounts) 0 melden
./scan_bad_signature.sh -s cloud-01.oopen.de
Verzeichnisse
| Zweck | Standardpfad | Override (conf-Datei) |
|---|---|---|
| Recovery-Kopien (unverschlüsselt!) | /var/nc-recovery/<website> |
RECOVERY_BASE_DIR |
| Backup vor restore-Überschreiben | /var/nc-restore-backup/<website> |
RESTORE_BACKUP_BASE_DIR |
| Backup vor recreate-Löschen | /var/nc-recreate-backup/<website> |
RECREATE_BACKUP_BASE_DIR |
| Backup vor delete_bad_sig.-Löschen | ein Verzeichnis über DATA_DIR |
DELETE_BACKUP_BASE_DIR |
| Backup vor delete_files-Löschen | /var/nc-delete-backup/<website> |
DELETE_BACKUP_BASE_DIR |
| Reports aller Scripte | reports/ (neben den Scripten) |
– |
Sicherheitsprinzipien (gelten für alle schreibenden Scripte)
- Dry-Run ist Standard – ein echter Lauf braucht eine ausdrückliche
YES-Bestätigung. - Immer zuerst sichern, dann erst schreiben/löschen – byte-genaue Kopie, unabhängig von Nextcloud.
- Immer neu validieren unmittelbar vor dem Zugriff, nicht blind aus einem alten Report übernehmen.
- Immer verifizieren nach dem Schreiben (Rücklesen + SHA-256-Vergleich).
- Jedes Script kann per
Strg-Csicher unterbrochen werden – kein halb geschriebener Report.
Kurzreferenz aller Flags
-s <website> ist bei allen Scripten optional – fehlt es, wird die
Website interaktiv abgefragt (Auswahlliste bei mehreren konfigurierten
Instanzen).
| Script | -s (optional) |
weitere Optionen |
|---|---|---|
scan_bad_signature.sh |
Website | – |
recover_bad_signature.sh |
Website | -V nur revalidieren |
restore_bad_signature.sh |
Website | -n Dry-Run erzwingen |
recreate_bad_signature.sh |
Website | -n Dry-Run erzwingen · -f Dateien mit aktiven Freigaben einschließen |
delete_bad_signature.sh |
Website | -n Dry-Run erzwingen · -a alle löschen (auch recreatete) · -x <report> zusätzlichen recreate-Report für Ausschluss angeben |
delete_files.sh |
Website | -n Dry-Run erzwingen · -f <datei> Pfadliste (ohne Angabe interaktiv abgefragt) |
-h zeigt bei jedem Script die ausführliche Hilfe.