Signatur
Beschreibung
SodiumException ist die zentrale Fehlerklasse der libsodium-Erweiterung (ext-sodium), die seit PHP 7.2 standardmäßig gebündelt ist. Sie erweitert die eingebaute Exception-Klasse und wird geworfen, wenn kryptografische Operationen scheitern – zum Beispiel wenn ein übergebener Schlüssel die falsche Länge hat, eine Nonce nicht den Anforderungen entspricht oder eine authentifizierte Entschlüsselung die Integritätsprüfung nicht besteht.
Da Sodium-Funktionen keine Fehlercodes zurückgeben, sondern Ausnahmen werfen, lässt sich der Fehlerfall sauber mit try/catch abfangen. Das Nicht-Abfangen dieser Ausnahmen bei sicherheitskritischen Operationen kann dazu führen, dass korrumpierte oder manipulierte Daten weiterverarbeitet werden.
Typische Auslöser sind: Übergabe eines Schlüssels falscher Länge (z. B. nicht SODIUM_CRYPTO_SECRETBOX_KEYBYTES Bytes), eine Nonce mit falscher Länge, ein fehlgeschlagener MAC-Check bei sodium_crypto_secretbox_open() oder sodium_crypto_aead_*_decrypt(), sowie Übergabe eines leeren Ciphertexts, der kürzer als der MAC ist.
Es empfiehlt sich, jede Sodium-Operation in einem try/catch(\SodiumException $e)-Block zu kapseln und im Fehlerfall einen sicheren Zustand herzustellen, ohne sensible Details nach außen zu geben.
Beispiele
Entschlüsselung mit Fehlerbehandlung
<?php
$key = sodium_crypto_secretbox_keygen(); // 32 Bytes
$nonce = random_bytes(SODIUM_CRYPTO_SECRETBOX_NONCEBYTES); // 24 Bytes
$plaintext = 'Geheime Nachricht';
$ciphertext = sodium_crypto_secretbox($plaintext, $nonce, $key);
// Manipulierten Ciphertext simulieren
$tampered = $ciphertext;
$tampered[0] = chr(ord($tampered[0]) ^ 0xFF); // erstes Byte kippen
try {
$decrypted = sodium_crypto_secretbox_open($tampered, $nonce, $key);
if ($decrypted === false) {
throw new \SodiumException('Entschlüsselung fehlgeschlagen (false zurückgegeben).');
}
echo $decrypted;
} catch (\SodiumException $e) {
// Kein sensibles Detail nach außen geben
error_log('Sodium-Fehler: ' . $e->getMessage());
echo 'Die Nachricht konnte nicht entschlüsselt werden.';
}Fehler bei falschem Schlüssel abfangen
<?php
try {
$wrongKey = 'zu_kurz'; // Kein gültiger 32-Byte-Schlüssel
$nonce = random_bytes(SODIUM_CRYPTO_SECRETBOX_NONCEBYTES);
$cipher = sodium_crypto_secretbox('Test', $nonce, $wrongKey);
} catch (\SodiumException $e) {
echo 'SodiumException: ' . $e->getMessage() . PHP_EOL;
}// Wichtig · Fallstricke
Sicherheitshinweis: Fange SodiumException immer explizit ab und gib keine internen Fehlermeldungen an den Client weiter – die Meldungen können Hinweise auf den verwendeten Algorithmus oder die erwarteten Parameter liefern.
Achtung bei sodium_crypto_secretbox_open(): Diese Funktion kann sowohl false zurückgeben als auch eine SodiumException werfen. Prüfe beides, um alle Fehlerfälle abzudecken.
Die Klasse selbst besitzt keinen eigenen Konstruktor – sie erbt alles von Exception. Eigene Ausnahmen für Anwendungslogik sollten daher besser von \RuntimeException abgeleitet werden, nicht von SodiumException.