Administratorhandbuch

Dateien im Betrieb

Dateien sind in Ephraim kein statischer Webordner. Sie werden geprüft, verschlüsselt abgelegt, über kontrollierte Endpunkte ausgeliefert und in Produktion zusätzlich durch ClamAV gescannt.

· Stand: Juni 2026

1. Kurzfassung

Ephraim speichert hochgeladene Dateien außerhalb des Webroots. Der Webserver liefert diese Dateien nicht direkt aus. Jede Anzeige, Vorschau und jeder Download läuft durch PHP-Endpunkte, die Anmeldung, Berechtigung, Vault-Zustand, Dateieigentum und Projektzugang erneut prüfen.

Uploads durchlaufen Dateitypprüfungen und einen ClamAV-Scan. Danach werden Inhalte verschlüsselt gespeichert; Anzeigenamen werden verschlüsselt und Speicherverzeichnisse über HMAC-Hashing aus Nutzer- oder Projekt-IDs abgeleitet. Auf dem Datenträger stehen dadurch keine Klartextdateien, keine sprechenden Dateinamen und keine direkt lesbaren Nutzer- oder Projektpfade.

Für Administratoren sind drei Fragen entscheidend: Welche Dateiarten dürfen überhaupt hochgeladen werden? Reicht Speicherplatz und Quota? Und meldet die Datei-Sicherheitsseite auffällige Uploads oder Scannerprobleme?

Einfach gesagt: Eine hochgeladene Datei wird nicht wie ein Bild in einem öffentlichen Website-Ordner abgelegt. Ephraim nimmt sie entgegen, prüft sie, verschließt sie kryptografisch und legt nur die verschlossene Fassung ab. Wenn eine berechtigte Person die Datei später öffnet, wird sie nur für diese konkrete Antwort wieder entschlüsselt.

Flussdiagramm vom Datei-Upload über Prüfung, ClamAV, Verschlüsselung, Speicherung und kontrollierte Auslieferung
Der Weg einer Datei führt immer durch PHP: erst prüfen und scannen, dann verschlüsseln und speichern, später nur nach erneuter Berechtigungsprüfung entschlüsseln und streamen.

2. Drei Dateiklassen

Betrieblich sehen Nutzerinnen einfach „Dateien“. Technisch unterscheidet Ephraim drei Klassen, weil Datenschutz, Freigabe und Schlüsselverwaltung unterschiedlich sind.

Dateiklasse Speicherort Schlüssel Zugriff
Persönliche Dateien STORAGE_ROOT/users User-Vault-DEK des Besitzers Nur der Besitzer mit entsperrtem Vault
Projektmaterialien STORAGE_ROOT/projects Eigener Projektdateischlüssel, serverseitig geschützt Projektbesitzer, Admins und berechtigte Projektteilnehmer
Zentrale Basiswissen-Dateien STORAGE_ROOT/knowledge Serverseitiger Knowledge-Schlüssel Kontrolliert über Basiswissen-Quellen und Sichtbarkeit

Diese Trennung ist gewollt. Eine persönliche Datei wird nicht automatisch zu Projektmaterial. Wenn eine Lehrkraft eine private Datei in ein Projekt übernimmt, entsteht eine bewusste Projektkopie mit eigenem Schlüssel. Das private Original bleibt privat.

3. Speicherung auf dem Server

Der Standard-Speicher liegt neben dem Webroot im Verzeichnis storage. In Produktion wird der Speicherort über STORAGE_ROOT festgelegt und muss außerhalb des auslieferbaren Webbereichs liegen. Pfade enthalten keine Klarnamen und keine direkt ablesbaren Benutzer- oder Projekt-IDs.

Ebene Was gespeichert wird Warum das wichtig ist
Dateisystem Verschlüsselte EFR1-Dateien mit zufälligem Speichernamen Ein Dateisystemfund ist kein Klartextfund.
Datenbank Metadaten wie MIME-Typ, Größe, Status, SHA-256-Fingerprint und Speichername Die Anwendung kann Dateien verwalten, ohne sie öffentlich abzulegen.
Anzeigename Verschlüsselt beim jeweiligen Dateiobjekt Dateinamen verraten oft Inhalte und werden deshalb geschützt.
RAG-Chunks Extrahierter Text und Embeddings verschlüsselt in Chunk-Tabellen Auch Suchkontext bleibt an den passenden Schlüssel gebunden.

Das Dateiinnere wird streamend mit XChaCha20-Poly1305 verarbeitet. Eine Datei besteht aus dem Marker EFR1, einem Secretstream-Header und verschlüsselten Chunks. Der letzte Chunk trägt ein Abschluss-Tag. Fehlt dieses Abschluss-Tag, gilt die Datei beim Entschlüsseln als unvollständig.

Präzise formuliert: Der sichtbare Anzeigename wird verschlüsselt, der technische Speicherdateiname wird zufällig erzeugt, und das Nutzer- oder Projektverzeichnis wird per HMAC aus der jeweiligen ID abgeleitet. So bleibt auch die Verzeichnisstruktur für Außenstehende unlesbar.

Der SHA-256-Fingerprint ist keine Kopie des Inhalts und nicht zurückrechenbar. Er ist aber ein stabiler technischer Fingerabdruck: dieselbe Klartextdatei erzeugt denselben Wert. Deshalb gehört er zu den Metadaten und nicht zu den öffentlich sichtbaren Informationen.

4. Upload-Pipeline

Uploads werden nicht erst nach dem Speichern geprüft. Die Prüfungen laufen vor der dauerhaften Persistenz. Erst wenn die Datei Größe, Name, Typ, Struktur und den Virenscan passiert hat, wird sie verschlüsselt abgelegt.

Schritt Prüfung Fehlerwirkung
1 Anmeldung, CSRF-Token und bei persönlichen Dateien entsperrter Vault Request wird abgewiesen; persönliche Dateien bleiben ohne Vault unzugänglich.
2 PHP-Uploadstatus und maximale Dateigröße Zu große oder fehlerhaft übertragene Dateien werden abgelehnt.
3 Dateiname, gefährliche Namen, Endung und systemweite Allowlist Riskante Namen und nicht erlaubte Typen werden protokolliert und blockiert.
4 MIME-Erkennung, Magic Bytes, HEIC/HEIF-Header und Office-/iWork-Struktur Inhalt muss zur behaupteten Datei passen.
5 ClamAV-Scan im Produktionsbetrieb Malware-Fund blockiert den Upload und erzeugt ein kritisches Sicherheitsereignis.
6 Quota und physischer Speicherplatz Nutzer-, System- und Speichergrenzen verhindern Überfüllung.
7 Verschlüsselung, Datenbankeintrag und optionale RAG-Indexierung Erst jetzt wird die Datei dauerhaft nutzbar.

5. ClamAV in Produktion

In Produktion ist ClamAV Teil der Upload-Pipeline. Der Webprozess übergibt die temporäre Upload-Datei an den Scanner, bevor Ephraim sie verschlüsselt und persistiert. Das System unterscheidet vier Ergebnisse: sauber, infiziert, Scannerfehler und nicht verfügbar. Nur ein Malware-Fund ist ein fachlicher Upload-Blocker. Scannerfehler und fehlende Erreichbarkeit sind Betriebszustände, die Admins über Datei-Sicherheit und Cron im Blick behalten.

Scan-Ergebnis Betriebliche Bedeutung
Sauber Die Datei läuft weiter durch Quota, Verschlüsselung und Speicherung.
Infiziert Die temporäre Datei wird verworfen, der Upload endet mit Fehler und ein kritisches Ereignis wird protokolliert.
Scannerfehler Der Upload wird nicht durch einen temporären Scannerfehler blockiert; Ephraim protokolliert den Fehler und Admins prüfen den Scannerzustand.
Nicht verfügbar Der Zustand ist ein Betriebsfehler. Die Adminseite und Cron zeigen, ob ClamAV aktiviert und erreichbar ist.
Wichtig: ClamAV ersetzt nicht die anderen Prüfungen. Ephraim prüft Dateinamen, Typen, MIME-Werte, Magic Bytes und Containerstrukturen zusätzlich, weil ein Virenscanner bekannte Schadsoftware erkennt, aber keine vollständige Dateipolitik ist.

6. Auslieferung und Vorschau

Downloads und Vorschauen werden dynamisch erzeugt. Die Anwendung lädt den verschlüsselten Datenträgerinhalt, prüft erneut die Berechtigung, entschlüsselt nur für diesen Request und streamt den Klartext direkt in die HTTP-Antwort. Es gibt keinen öffentlichen Link auf die gespeicherte Datei.

Funktion Auslieferung Schutz
Persönlicher Download Als Attachment an den eingeloggten Besitzer Login, Vault-DEK, Eigentümerprüfung
Persönliche Vorschau PDF inline oder Bild-Thumbnail Same-Origin-Framing, no-store, nosniff
Projekt-Download Als Attachment an berechtigte Projektakteure Projektzugang, Projektstatus, Schlüsselentsiegelung
Projekt-Vorschau PDF inline oder Bild-Thumbnail Same-Origin-Framing, no-store, nosniff

Bildvorschauen sind keine persistierten Klartextdateien. Ephraim entschlüsselt das Bild für den aktuellen Request, erzeugt ein verkleinertes JPEG ohne Metadaten und sendet es sofort aus. Für PDF-Vorschauen wird die geschützte Quelle inline ausgeliefert.

7. Quotas und Speicherpflege

Die Datei-Quota zählt persönliche Dateien und aktive Projektmaterialien zusammen. RAG-Chunks werden nicht ein zweites Mal als Nutzerquota gezählt. Für Admins ist wichtig: Uploadgröße, Nutzerquota, systemweite Datei-Quota und freier physischer Speicher wirken gemeinsam.

Grenze Wo sie wirkt
Maximale Uploadgröße Kleinster Wert aus Admin-Einstellung, Konfiguration, PHP-Limits und App-Hard-Cap.
Nutzerquota User-Override, Rollen-Default oder System-Default.
Systemweite Datei-Quota Schützt den Gesamtspeicher vor Überbelegung.
Physischer Speicher Ephraim blockiert Uploads, wenn der verfügbare Speicher unter die Reserve fällt.

Der Cron-Task cleanup_orphan_storage entfernt verwaiste Binärdateien unter STORAGE_ROOT/users und STORAGE_ROOT/projects, wenn sie nicht mehr in den Datei-Tabellen referenziert sind. cleanup_security_events entfernt alte Datei-Sicherheitsereignisse nach 90 Tagen.

8. Adminaufgaben

  1. Datei-Sicherheit regelmäßig prüfen: erlaubte Typen, ClamAV-Status und letzte Sicherheitsereignisse.
  2. Speicherquoten beobachten: Systemlimit, Rollenlimits, Nutzer-Overrides und freien physischen Speicher.
  3. Cron überwachen: verwaiste Speicherdateien und alte Sicherheitsereignisse müssen regelmäßig bereinigt werden.
  4. Bei ClamAV-Fehlern nicht nur Uploads testen, sondern den Scannerzustand und die Sicherheitsereignisse prüfen.
  5. Projektmaterialien als bewusste Freigabe behandeln: Eine private Datei bleibt privat, bis sie aktiv ins Projekt kopiert oder dort hochgeladen wird.