Kryptoarchitektur

1. Zielbild in einfachen Worten

Ephraim verschlüsselt Daten nicht mit einem einzigen Generalschlüssel. Stattdessen gibt es mehrere Schlüsselbereiche. Private Inhalte einer Nutzerin oder eines Nutzers hängen am persönlichen Vault. Geteiltes Projektmaterial hat eigene Projektschlüssel. Serverdaten, die Cron, Worker oder Adminfunktionen unabhängig von einer angemeldeten Person benötigen, werden mit serverseitigen Schlüsseln geschützt.

Das wichtigste Bild ist der verschlossene Umschlag: Der eigentliche Inhalt liegt in einem Umschlag. Der Schlüssel zu diesem Umschlag liegt wiederum in einem zweiten Umschlag, der nur mit dem passenden Passwort oder einem Servergeheimnis geöffnet wird. Dadurch muss bei einem Passwortwechsel nicht jeder Chat neu verschlüsselt werden; Ephraim verpackt nur den Datenschlüssel neu.

2. Begriffe für Nicht-Experten

3. Datenklassen und Schlüsselmodelle

Ephraim trennt Daten danach, ob sie privat, geteilt oder serverbetrieben sind. Diese Trennung ist wichtiger als die einzelne Tabelle. Für Schul-Admins ist entscheidend, welche Daten ohne Nutzerpasswort verarbeitet werden müssen und welche bewusst nur im Nutzer-Vault liegen.

4. Schlüsselkarte

5. Nutzer-Vault und User-DEK

Für private Inhalte erzeugt Ephraim pro normalem Konto eine zufällige 32-Byte-User-DEK. Diese User-DEK ist der eigentliche Datenschlüssel für private Inhalte. Sie entsteht nicht aus dem Passwort und sie ist auch nicht das Passwort. Das Passwort dient dazu, eine KEK abzuleiten, mit der die User-DEK verpackt wird.

Die Ableitung nutzt Argon2id mit individuellem 16-Byte-Salt, opslimit 3 und 64 MiB Speicherlimit. Für Laien übersetzt: Das System macht die Passwortprüfung für Angreifer absichtlich teuer. Wer nur Datenbankmaterial erbeutet, muss jedes vermutete Passwort mit deutlichem Rechen- und Speicheraufwand ausprobieren.

6. Warum bcrypt und Argon2id beide vorkommen

Ephraim nutzt zwei verschiedene Passwortfunktionen für zwei verschiedene Aufgaben. Der bcrypt-Hash dient der Login-Prüfung: Stimmt das eingegebene Passwort zum gespeicherten Hash? Ephraim speichert diesen Hash mit bcrypt und Kostenfaktor 12. Argon2id dient der Schlüsselableitung: Aus dem eingegebenen Passwort entsteht eine KEK, mit der die User-DEK entpackt wird.

Diese Trennung verhindert eine gefährliche Vereinfachung. Der Passwort-Hash ist kein Datenschlüssel. Wenn sich das Passwort ändert, ändert sich der Login-Hash und die Verpackung der User-DEK. Die privaten Chats selbst bleiben mit derselben User-DEK verschlüsselt.

7. Passwortwechsel, Recovery und Reset

Beim normalen Passwortwechsel ist der alte Vault bereits entsperrt. Ephraim nimmt die User-DEK aus der aktuellen Sitzung, prüft das alte Passwort, leitet aus dem neuen Passwort eine neue KEK ab und verpackt dieselbe User-DEK neu. Die privaten Inhalte bleiben lesbar. Andere aktive Sitzungen werden über die Session-Version beendet.

Bei vorbereiteter datenerhaltender Recovery ist die User-DEK ebenfalls nicht verloren: Ein aktivierter Wiederherstellungskontakt gibt in einem zeitlich begrenzten Live-Fall kryptografisch frei. Ephraim rekonstruiert daraus nicht ein neues Passwort, sondern verpackt dieselbe User-DEK mit dem neuen Passwort des Kontoinhabers neu. Der Kontakt erhält keinen Klartextzugriff auf Chats, Dateien oder die User-DEK.

Beim datenlöschenden Reset ist die Lage anders. Das alte Passwort steht nicht mehr zur Verfügung und keine gültige datenerhaltende Recovery wird genutzt. Ephraim deaktiviert beim Admin-Reset das alte Passwort sofort; beim Self-Service-Reset geschieht der eigentliche Vault-Neustart beim Setzen des neuen Passworts. Danach entsteht eine neue User-DEK. Alte verschlüsselte Chats und persönliche Dateien werden entfernt, weil Ephraim ohne alte User-DEK keinen vertrauenswürdigen Zugriff auf den alten Vault herstellen soll.

8. AEAD, Nonces und Manipulationsschutz

Für viele Text- und Payload-Verschlüsselungen nutzt Ephraim XChaCha20-Poly1305. Das ist ein AEAD-Verfahren: Es verschlüsselt und prüft gleichzeitig, ob der Ciphertext manipuliert wurde. Bei falschem Schlüssel, falscher Zweckbindung oder beschädigtem Inhalt liefert die Entschlüsselung keinen plausiblen Klartext, sondern schlägt fehl.

Viele verschlüsselte Textfelder liegen als Base64(Nonce || Ciphertext) vor. Das heißt: Die Nonce steht vor dem eigentlichen Ciphertext und ist mitgespeichert. Das ist korrekt, weil die Nonce kein Geheimnis ist. Secretbox-verschlüsselte Dateinamen verwenden ein eigenes Präfix, damit Ephraim das Format erkennt.

Die Nonce ist dabei kein Passwort und kein geheimer Schlüssel. Sie ist ein Einmalwert, der zusammen mit dem Ciphertext gespeichert wird. XChaCha20 hat eine lange Nonce; zufällige Nonces sind in dieser Architektur praktikabel. Die Sicherheit hängt weiterhin am geheimen Schlüssel, nicht an der Geheimhaltung der Nonce.

9. Serverseitige Verschlüsselung und Zweckbindung

Nicht alle Daten lassen sich an ein Nutzerpasswort binden. Cron, Worker, Adminfunktionen, Projektverwaltung und 2FA-Prüfung müssen auch dann laufen, wenn kein Nutzer gerade seinen Vault entsperrt hat. Dafür verwendet Ephraim serverseitige At-rest-Verschlüsselung.

Der bevorzugte Betriebskey ist AT_REST_ENCRYPTION_KEY. Daraus leitet Ephraim pro Zweck einen eigenen Schlüssel ab. Der Zweck wird zusätzlich als authentifizierter Kontext verwendet. Technisch bedeutet das: Ein Ciphertext für den Zweck totp-secret lässt sich nicht einfach als project-config verwenden.

Serverseitig verschlüsselte Textwerte tragen ein eigenes internes Präfix. Daran erkennt Ephraim, dass ein Feld bereits im neuen At-rest-Format vorliegt. Das hilft bei Migrationen und verhindert, dass alter Klartext und neuer Ciphertext still verwechselt werden.

Wenn AT_REST_ENCRYPTION_KEY fehlt, existiert für Kompatibilität ein Fallback auf STREAM_DEK_SERVER_KEY. In Produktion gehört ein expliziter AT_REST_ENCRYPTION_KEY gesetzt. Der Entwicklungsmodus darf einen lokalen Ableitungsfallback nutzen; dieser Zustand ist kein Produktionsbetrieb.

10. Persönliche Dateien im EFR1-Format

Persönliche Dateien liegen nicht als Klartext im Webbereich. Beim Upload wird die temporäre PHP-Uploaddatei validiert und anschließend in das verschlüsselte EFR1-Format geschrieben. EFR1 besteht aus einer Kennung, einem Secretstream-Header und einer Folge von längengepackten Ciphertext-Blöcken. Die Klartext-Blockgröße beträgt 1 MiB.

Beim Download liest Ephraim den Ciphertext chunkweise, entschlüsselt im RAM und schreibt direkt in die HTTP-Antwort. Es entsteht keine entschlüsselte Downloadkopie auf Platte. Dateinamen werden separat mit Secretbox verschlüsselt gespeichert, damit nicht schon ein Dateiname sensible Informationen verrät.

Datenexporte sind ein Sonderfall: Für die Nutzerin oder den Nutzer entsteht am Ende ein lesbares Exportarchiv, aber die temporäre Datei auf dem Server liegt ebenfalls verschlüsselt. Ephraim verwendet dafür ein servergeschütztes Streaming-Format und löscht abgelaufene oder bereits heruntergeladene Exportdateien wieder.

11. Projektdateien und Re-Encryption

Projektmaterial ist bewusst geteilt. Deshalb hängt es nicht dauerhaft an der User-DEK der hochladenden Lehrkraft. Ephraim erzeugt für Projektdateien einen eigenen Projektdatei- Schlüssel. Die Datei selbst liegt wieder im EFR1-Format, aber mit dem Projektdatei-Schlüssel. Dieser Schlüssel wird serverseitig mit Zweck project-file-key verpackt.

Wenn eine private Datei als Projektmaterial übernommen wird, geschieht kein bloßes Freischalten des privaten Originals. Ephraim entschlüsselt die private Datei im berechtigten Request und verschlüsselt sie direkt als neue Projektkopie mit dem Projektdatei-Schlüssel. Dadurch bleiben privates Original und Projektkopie kryptografisch getrennt.

12. Basiswissen, Kalender, Wetter und Wikipedia

Zentrales Basiswissen ist kein normaler Nutzer-Vault. Globale Quellen, globale Kalenderquellen, Wetterdaten und Wikipedia-Cache müssen durch Cron, Retrieval und Adminfunktionen verarbeitet werden. Deshalb verwendet Ephraim für diesen Bereich KNOWLEDGE_STORAGE_KEY_HEX.

Embedding ist dabei eine Rechenoperation, kein Spark-Speicher. Die Webanwendung sendet freigegebene Klartext-Chunks und konkrete Suchfragen nur für den aktuellen Request an den lokalen SGLang-Embedding-Dienst school-ui-embedding. Dieser Dienst berechnet Zahlenvektoren und speichert weder Klartexte noch Suchfragen noch Vektoren dauerhaft. Persistenz findet auf dem Webserver statt: Chunktexte und Embedding-Vektoren werden mit dem passenden Schlüssel verschlüsselt in MySQL gespeichert.

Private Kalenderquellen gehören kryptografisch zum persönlichen Vault des Besitzers. Für jede private Kalenderquelle erzeugt Ephraim einen eigenen Quellschlüssel. Dieser Quellschlüssel wird mit der User-DEK des Besitzers verpackt. Die private ICS-URL, der geladene Kalender-Blob, daraus erzeugte Chunks, Embeddings und Termintexte werden mit diesem Quellschlüssel verschlüsselt. Ohne entsperrten User-Vault kann der Server diese privaten Kalender nicht entschlüsseln und nicht automatisch per Cron aktualisieren.

Sichtbarkeit und Eigentümerbindung bleiben zusätzlich erhalten: Private Kalender werden nur im normalen Chat und auf der Startseite des Besitzers verwendet, nicht im Projektchat und nicht im Projektbuilder. Zentrale Kalenderquellen sind davon getrennt: Sie sind Teil des administrativ freigegebenen Basiswissens und werden mit dem Knowledge-Schlüssel geschützt, damit Cron, Retrieval und Adminfunktionen sie ohne entsperrten Nutzer-Vault warten können.

13. Sitzungen, Sessiondaten und Sitzungsliste

Eine angemeldete Sitzung ist der Moment, in dem private Daten verarbeitet werden dürfen. Deshalb schützt Ephraim serverseitige PHP-Sessiondateien mit ServerCrypto und Zweck php-session. In solchen Sessions liegen temporär sicherheitsrelevante Werte, zum Beispiel CSRF-Kontext und die entsperrte User-DEK.

Die Sitzungsliste speichert keine Klartext-Sessiontokens. Ein zufälliger Sitzungstoken wird gehasht. Geräte- und Zugriffshinweise werden für die Anzeige gekürzt oder mit einem Privacy-Hash versehen. Die Session-Version ist der harte Schalter: Nach Passwortwechsel, Reset oder 2FA-Reset werden alte Sitzungen ungültig.

14. Zwei-Faktor-Authentifizierung

TOTP basiert auf einem gemeinsamen Geheimnis zwischen Ephraim und der Authenticator-App. Dieses Geheimnis ist wertvoller als ein einzelner sechsstelliger Code. Ephraim erzeugt ein 160-Bit-Secret, zeigt es als QR-Code oder manuelle Eingabe an und speichert es anschließend serverseitig verschlüsselt mit Zweck totp-secret.

Die laufenden TOTP-Codes folgen dem üblichen Muster: 30-Sekunden-Zeitschritte, sechs Ziffern, HMAC-SHA1. Recovery-Codes werden anders behandelt: Ephraim erzeugt acht Codes, speichert nur SHA3-512-Hashes und entfernt einen Code nach erfolgreicher Nutzung. Ein Admin kann Recovery-Codes deshalb nicht auslesen. Ein 2FA-Reset löscht das alte Secret und die alten Recovery-Codes und zwingt zur Neueinrichtung.

15. KI-Jobs, Streaming und kurzlebige Puffer

KI-Antworten laufen über Jobs und Streams. Der Browser sieht eine fortlaufende Antwort, technisch gibt es aber Queue-Einträge, Stream-Chunks und Reconnect-Snapshots. Private oder nutzerabgeleitete Job-Payloads liegen mit der User-DEK verschlüsselt. Die technischen JSON-Felder enthalten dann nur Metadaten; eigentliche Prompt- und Ergebnisblobs liegen in verschlüsselten Payloadfeldern.

Der Worker benötigt zur Verarbeitung zeitweise Zugriff auf den passenden Vault-Kontext. Dafür speichert Ephraim eine serverseitig verschlüsselte Kopie des Job-DEK-Zugangs, nicht den Klartext im normalen Job-Payload. Stream-Chunks werden zusätzlich mit einem jobbezogenen Stream-Token geschützt und haben kurze Lebensdauer. Das Ziel ist: Reconnect und Streaming funktionieren, ohne dauerhafte Klartextpuffer anzulegen.

16. Wo Klartext unvermeidlich ist

Verschlüsselung schützt ruhende Daten. Sie verhindert nicht, dass Daten dort im Klartext entstehen, wo sie fachlich verarbeitet werden müssen. Der Browser muss einen Chat anzeigen. Der PHP-Prozess muss beim Speichern oder Exportieren entschlüsseln. Die Spark muss den Prompt lesen, um eine Antwort zu berechnen.

17. Runtime-JWTs und Supervisor-Webterminal

Administrative Runtime-Zugriffe verwenden kurzlebige JWTs mit Ed25519-Signatur. Das Frontend signiert mit JWT_SIGNING_KEY_HEX. Runtime und Supervisor prüfen mit dem passenden öffentlichen Schlüssel, der dort als RUNTIME_WS_TOKEN_PUBLIC_KEY erwartet wird. In Ephraim selbst muss JWT_VERIFY_KEY_HEX zu diesem öffentlichen Schlüssel passen.

Signatur bedeutet: Die Runtime prüft, ob das Token wirklich vom berechtigten Frontend stammt und ob Audience und Issuer passen. Das Token verschlüsselt nicht den Inhalt des WebSocket-Verkehrs; dafür ist die Transport- und Netzwerkinfrastruktur zuständig. Die Signatur schützt die Berechtigung, nicht den gesamten Datenkanal.

Typische Fehlkonfigurationen zeigen sich hart: Der Token-Endpunkt liefert einen Fehler oder die Runtime lehnt das Token ab. Mehrere Frontends, die dieselbe Spark ansprechen, müssen dieselbe Schlüsselpaarlogik verwenden oder die Runtime muss den passenden neuen Public Key erhalten.

18. Zugangslinks, Resetlinks und Nonces

Initiallinks, Admin-Resetlinks und Self-Service-Resetlinks sind keine Passwortarchive. Ephraim speichert nicht einfach eine Liste wiederanzeigbarer Klartextlinks. Gespeichert werden Token-Hashes, Nonces, Zweck, Ablaufzeit und Nutzungsstatus. Der vorgelegte Link wird geprüft, nicht aus der Datenbank rekonstruiert.

Die Zwecke sind getrennt: Initialzugang, Admin-Reset, Self-Service-Bestätigung, datenerhaltender Recovery-Fall und Passwort-Setzlink. Self-Service-Anfragen antworten neutral, damit das Formular keine Konten verrät. Admin-Resetlinks deaktivieren das alte Passwort sofort. Resetlinks und Recovery-Fälle sind kurzlebig und je nach Policy einmalig nutzbar.

19. MCP-OAuth und Admin-Werkzeuge

Der MCP-Server ist ein Admin-Werkzeug und gehört nicht zur normalen Schüler- oder Lehrkraftnutzung. Er arbeitet mit OAuth und PKCE. Zugriffstokens werden nur gehasht gespeichert und mit Scopes begrenzt. Ein Client erhält also nicht automatisch alle Adminrechte, sondern nur die angeforderten und genehmigten Berechtigungen.

Für Admins ist dabei entscheidend: Kryptografie schützt den Tokenbestand, aber Scopes, Bestätigungsabfragen und Auditspuren sind genauso wichtig. Ein gültiger Token mit Schreibscope ist ein echtes Machtmittel und muss widerrufen werden, wenn ein Client nicht mehr vertrauenswürdig ist.

20. Backups, Restore und Schlüsselverlust

Verschlüsselung macht Backups nicht unwichtig, sondern anspruchsvoller. Datenbank, Dateispeicher und Betriebsgeheimnisse müssen zusammen betrachtet werden. Wer nur die Datenbank sichert, verliert Dateiinhalte. Wer Dateispeicher und Datenbank sichert, aber die Serverkeys verliert, verliert servergeschützte Inhalte. Wer Serverkeys ungeschützt in dasselbe Backup legt, schwächt die Schutzwirkung.

Schlüsselrotation bedeutet nicht „neuen Wert eintragen und fertig“. Betroffene Daten müssen mit dem alten Schlüssel gelesen und mit dem neuen Schlüssel neu verpackt werden, oder das System muss während einer Übergangszeit mehrere Schlüsselgenerationen verstehen.

21. Was Admins lesen und nicht lesen

Normale Adminfunktionen geben keinen Klartextzugriff auf fremde private Vault-Inhalte. Lehrkräfte lesen keine privaten Schülerchats und auch keine Projektchat-Rohtexte einzelner Teilnehmender. Super-Admins verwalten System, Nutzer, Klassen, Quoten, Basiswissen, Runtime und Sicherheitszustände; sie erhalten damit technische Macht, aber nicht automatisch eine Lesefunktion für fremde Vaults.

Gleichzeitig schützt keine Kryptografie gegen eine vollständig kompromittierte Serverlaufzeit. Wer Serverprozess, Konfiguration und Code kontrolliert, kontrolliert die Stelle, an der Klartext legitimerweise verarbeitet wird. Deshalb gehören Betriebsschutz, 2FA für Admins, minimale Adminrollen, Patchpflege, Auditlogs und gute Backupdisziplin zur Kryptoarchitektur dazu.

22. Typische Angriffsbilder

23. Betriebsregeln für Schul-Admins

• Produktivsysteme brauchen eigene, zufällig erzeugte Werte für AT_REST_ENCRYPTION_KEY, KNOWLEDGE_STORAGE_KEY_HEX, STREAM_DEK_SERVER_KEY und das Runtime-JWT-Schlüsselpaar.
• Secrets gehören in die geschützte Serverkonfiguration oder ins Environment, nicht in Git, Tickets, Chatprotokolle oder Screenshots.
• Backups müssen Datenbank, Dateispeicher und benötigte Schlüssel abdecken; Schlüsselkopien brauchen strengere Zugriffsregeln als normale Datenbackups.
• Passwortresets werden nur als Notfallpfad genutzt. Bei bekanntem Passwort ist der normale Passwortwechsel der richtige Weg.
• 2FA für Admin- und Super-Admin-Konten ist nicht Komfort, sondern Grundschutz.
• Fehlersuche beginnt mit Status, Metadaten und Auditereignissen. Private Klartexte gehören nicht in Logs.
• Vor Schlüsselrotation oder Migration wird geprüft, welche Datenklasse betroffen ist und ob ein Rewrap-Pfad existiert.

24. Fehlersuche ohne Datenschutzschaden

Viele Krypto-Fehler sehen für Nutzer gleich aus: Daten lassen sich nicht laden, 2FA klappt nicht, Projektmaterial wirkt unlesbar oder die Runtime lehnt Tokens ab. Admins sollten zuerst die betroffene Datenklasse bestimmen. Ein Problem im Nutzer-Vault ist anders zu behandeln als ein Problem im Knowledge-Schlüssel oder im JWT-Schlüsselpaar.

25. Grenzen der Kryptografie

Kryptografie ist ein starker Baustein, aber sie löst nicht jede Sicherheitsfrage. Sie schützt keine Inhalte, die eine berechtigte Person gerade im Browser sieht. Sie verhindert keine falsche Freigabeentscheidung in einem Projekt. Sie ersetzt keine Rollenprüfung. Und sie schützt nicht vor einem Angreifer, der den laufenden Serverprozess samt Konfiguration kontrolliert.

Die richtige Erwartung lautet deshalb: At-rest-Verschlüsselung reduziert Schäden bei Datenbank-, Dateispeicher- und Backupabflüssen deutlich. Sie erzwingt aber weiterhin sauberen Betrieb, minimale Rechte, Protokollhygiene, sichere Adminzugänge und transparente Fachentscheidungen.