sodium_crypto_pwhash_str_verify — Funktion · PHP-Referenz

Signatur

sodium_crypto_pwhash_str_verify(string $hash, string $password): bool

Beschreibung

sodium_crypto_pwhash_str_verify vergleicht ein Klartextpasswort mit einem Hash, der zuvor mittels sodium_crypto_pwhash_str erzeugt wurde. Die Funktion extrahiert automatisch die im Hash enthaltenen Parameter (Algorithmus, Speicherbedarf, Zeitkosten, Salt) und führt die Verifizierung korrekt durch – ohne dass der Aufrufer diese Werte separat speichern muss.

Der Vergleich erfolgt intern in konstanter Zeit (Timing-Safe), sodass Timing-Angriffe, die versuchen anhand der Antwortzeit Rückschlüsse auf den Hash zu ziehen, verhindert werden. Dies ist ein wesentlicher Sicherheitsvorteil gegenüber naivem Stringvergleich mit ===.

Die Funktion basiert auf der libsodium-Bibliothek und verwendet standardmäßig Argon2id als Hashing-Algorithmus, sofern verfügbar. Sie eignet sich besonders für Passwort-Authentifizierungssysteme, bei denen Sicherheit und Zukunftsfähigkeit wichtig sind.

Liefert die Funktion true zurück, sollte zusätzlich mit sodium_crypto_pwhash_str_needs_rehash geprüft werden, ob der Hash mit aktuelleren Parametern neu berechnet werden sollte, um die Sicherheit langfristig zu gewährleisten.

Parameter

Name	Typ	Default	Beschreibung
$hash Pflicht	string		Der zuvor mit `sodium_crypto_pwhash_str` erzeugte Hash-String im ASCII-Format, inklusive eingebetteter Algorithmusparameter und Salt.
$password Pflicht	string		Das Klartextpasswort, das gegen den Hash geprüft werden soll.

Rückgabewert

Typ

bool

Beschreibung

Gibt true zurück, wenn das Passwort mit dem Hash übereinstimmt, andernfalls false. Im Fehlerfall (z. B. ungültiges Hash-Format) wird eine SodiumException ausgelöst.

Beispiele

Einfache Passwort-Verifizierung

<?php
$passwort = 'MeinSicheresPasswort123!';

// Hash beim Registrieren erzeugen und in der Datenbank speichern
$hash = sodium_crypto_pwhash_str(
    $passwort,
    SODIUM_CRYPTO_PWHASH_OPSLIMIT_INTERACTIVE,
    SODIUM_CRYPTO_PWHASH_MEMLIMIT_INTERACTIVE
);

// Beim Login: Passwort gegen den gespeicherten Hash prüfen
if (sodium_crypto_pwhash_str_verify($hash, $passwort)) {
    echo 'Passwort korrekt – Zugang gewährt.';
} else {
    echo 'Falsches Passwort – Zugang verweigert.';
}

Passwort korrekt – Zugang gewährt.

Verifizierung mit anschließendem Rehash-Check

<?php
// Beispiel: Hash aus der Datenbank laden
$gespeicherterHash = holeHashAusDatenbank($nutzerId); // Pseudofunktion
$eingegebenesPasswort = $_POST['passwort'] ?? '';

if (sodium_crypto_pwhash_str_verify($gespeicherterHash, $eingegebenesPasswort)) {
    echo 'Login erfolgreich.';

    // Prüfen, ob der Hash mit neueren/stärkeren Parametern neu berechnet werden sollte
    if (sodium_crypto_pwhash_str_needs_rehash(
        $gespeicherterHash,
        SODIUM_CRYPTO_PWHASH_OPSLIMIT_INTERACTIVE,
        SODIUM_CRYPTO_PWHASH_MEMLIMIT_INTERACTIVE
    )) {
        $neuerHash = sodium_crypto_pwhash_str(
            $eingegebenesPasswort,
            SODIUM_CRYPTO_PWHASH_OPSLIMIT_INTERACTIVE,
            SODIUM_CRYPTO_PWHASH_MEMLIMIT_INTERACTIVE
        );
        aktualisiereHashInDatenbank($nutzerId, $neuerHash); // Pseudofunktion
        echo ' Hash wurde mit aktuellen Parametern erneuert.';
    }
} else {
    echo 'Login fehlgeschlagen.';
}

// Wichtig · Fallstricke

Sicherheitshinweis: Übergebe niemals einen Hash, der nicht von sodium_crypto_pwhash_str stammt. Ein ungültiges Format führt zu einer SodiumException – fange diese im Produktivcode ab, um Information Leakage zu vermeiden.

Timing-Sicherheit: Vergleiche Passwörter niemals direkt mit === oder hash_equals gegen Argon2-Hashes. Verwende ausschließlich diese Funktion oder password_verify für password_hash-Hashes.

Kompatibilität: Die Funktion setzt die libsodium-Extension voraus, die seit PHP 7.2 als Core-Extension enthalten ist. Für ältere PHP-Versionen steht das PECL-Paket libsodium zur Verfügung.

Das Passwort sollte vor der Übergabe nicht vorab gehasht werden (z. B. mit SHA-1), da dies die Entropie verringert und Angriffe erleichtert.

Siehe auch

sodium_crypto_pwhash_str sodium_crypto_pwhash_str_needs_rehash sodium_crypto_pwhash password_verify password_hash