TYPO3 Adventskalender 2025
21.12.2025: Verschlüsselung
Der TYPO3 “Encryption Key” (`$GLOBALS['TYPO3_CONF_VARS']['SYS']['encryptionKey']`) wurde bislang nur benutzt, um instanzspezifisch
- für (Extbase-)Formulare HMAC-Werte,
- den “cHash”-Wert für Caching,
- für “sys_file” die Checksum-Hashes,
- für JWT-Tokens (Login/Sessions) die Signing-Keys
- für CSP-Nonces einen eindeutigen Wert
zu erzeugen und zu validieren. Der Key wurde hierbei also nur benutzt, um eindeutige Werte mit geringer Lebenszeit zu erzeugen. Im schlimmsten Fall konnte man einen Encryption Key also ändern, und durch das Leeren der Caches und einem Re-Login/Re-Submit von Formularen wäre dann alles wieder funktional und nutzbar. Sprich, bislang wurde der Encryption Key nur benutzt um Werte zu validieren/hashen, nicht um sie rückwärts wieder zu “entschlüsseln”.
Das ändert sich mit einem neuen Feature in TYPO3 v14 deutlich:
Einführung einer symmetrischen Verschlüsselung
Mit der Einführung einer symmetrischen Verschlüsselung ist es dem TYPO3 Core und auch eigenen Extensions möglich, einen sicheren Key anhand des Encryption Keys zu erzeugen, der dann Werte verschlüsseln und entschlüsseln kann. Wenn der Encryption Key also verloren gehen würde, oder sich ändert, können alle verschlüsselten Werte nicht mehr entschlüsselt werden!
Beispielnutzung
Aktuell ist diese Verschlüsselung von TYPO3 v14 nur ein “Angebot” an Extensions, dies nutzen zu können. Dies ist relativ einfach:
<?php use TYPO3\CMS\Core\Crypto\Cipher\CipherDecryptionFailedException; use TYPO3\CMS\Core\Crypto\Cipher\CipherService; use TYPO3\CMS\Core\Crypto\Cipher\KeyFactory; use TYPO3\CMS\Core\Crypto\Cipher\SharedKey; final readonly class DerAdventsVerschluesselor { // Dependency Inwichtelung public function __construct( private CipherService $cipherService, private KeyFactory $keyFactory, ) {} // Liefert den Key für ver/entschlüsselung public function getSecretKey(): SharedKey { // In einem beliebigen Namensraum einen "Shared Key" erzeugen, // der TYPO3 Encryption Key wird einbezogen! return $this->keyFactory->deriveSharedKeyFromEncryptionKey('weihnachten'); } public function encrypt(string $meinGeheimerWunschzettel): string { $secretKey = $this->getSecretKey(); // ... und jetzt mit diesem Key den Wert verschlüsseln $cipherValue = $this->cipherService->encrypt(meinGeheimerWunschzettel, $secretKey); // Den verschlüsselten Text (base64url-encoded-json) zurückgeben return (string)$cipherValue; } public function decrypt(string $meinVerschluesselterWunschzettel): string { $secretKey = $this->getSecretKey(); // Aus dem verschlüsselten base64url-encoded-json String den ursprünglichen // Text entschlüsseln: $cipherValue = CipherValue::fromSerialized($meinVerschluesselterWunschzettel); try { $apiToken = $this->cipherService->decrypt($cipherValue, $secretKey); return $apiToken; } catch (CipherDecryptionFailedException $e) { // Uppsie! Naughty, not nice! throw new \RuntimeException( 'Keine Geschenke für Dich: ' . $e->getMessage(), 1762465682, $e ); } } }
Fazit: Ab TYPO3 v14 den Encryption Key wie ein Passwort behandeln!
Ein paar Tipps:
- Jedes Projekt sollte einen individuellen Key besitzen (keine Mehrfachverwendung unabhängiger Projekte).
- Der Encryption Key sollte eine gewisse Komplexität besitzen (damit nicht ggf. auf Basis von Hashing gecrackte Encryption Keys daraufhin für die Key-Erzeugung missbraucht werden kann). Kein “foo” als Key!
- Der Encryption Key sollte bestenfalls nicht in der Versionierung gespeichert werden, sondern nur auf der jeweiligen Instanz.
- Bei Deployments darauf achten dass falls gehashte Datenbankinhalte und verschlüsselte Werte abgeglichen werden, der Encryption Key ebenfalls gleich sein sollte. Wenn möglich sollte man für Production und Staging eigenständige Encryption Keys haben und die damit erzeugten Werte nicht untereinander teilen.
- Der Key muss in vollständigen Backups enthalten sein.
- Gedanke: Encryption Key auf einen Standard-Wert in “settings.php” setzen, und erst in “additional.php” gezielt belegen, ggf. auch abgeleitet von einer ENV-Variable, die wiederum in einer instanz-spezifischen `.env` Datei liegen kann, die dann auch Teil eines System-Backups ist.