sodium_crypto_pwhash_str_needs_rehash — Funktion · PHP-Referenz

Signatur

sodium_crypto_pwhash_str_needs_rehash(string $hash, int $opslimit, int $memlimit): bool

Beschreibung

sodium_crypto_pwhash_str_needs_rehash() analysiert einen mit sodium_crypto_pwhash_str() erzeugten Passwort-Hash und vergleicht die darin gespeicherten Parameter (Rechenaufwand und Speicherbedarf) mit den aktuell geforderten Werten. Gibt die Funktion true zurück, sollte der Hash bei nächster Gelegenheit – typischerweise direkt nach einem erfolgreichen Login – mit den neuen Parametern neu berechnet werden.

Das ist vor allem dann nützlich, wenn Sicherheitsanforderungen im Laufe der Zeit verschärft werden: Alte Hashes wurden vielleicht mit niedrigerem Aufwand erzeugt und sind heute weniger resistent gegen Brute-Force-Angriffe. Die Funktion erlaubt eine schrittweise, transparente Migration aller gespeicherten Hashes, ohne die Nutzer zu einer Passwort-Änderung zu zwingen.

Die Funktion gibt ebenfalls true zurück, wenn der übergebene $hash kein gültiger Argon2id-Hash ist oder ein unbekanntes Format hat – so wird in jedem Fehlerfall ein sicheres Rehashing ausgelöst.

Typischerweise wird diese Funktion im Login-Workflow nach sodium_crypto_pwhash_str_verify() aufgerufen: Wenn das Passwort korrekt ist und ein Rehash benötigt wird, wird der neue Hash in der Datenbank gespeichert.

Parameter

Name	Typ	Beschreibung
$hash Pflicht	string	Der vorhandene Passwort-Hash, der mit `sodium_crypto_pwhash_str()` erzeugt wurde. Der Hash enthält die ursprünglichen Parameter als Metadaten.
$opslimit Pflicht	int	Die aktuell gewünschte Obergrenze für Rechenoperationen. Typische Konstanten: `SODIUM_CRYPTO_PWHASH_OPSLIMIT_INTERACTIVE`, `SODIUM_CRYPTO_PWHASH_OPSLIMIT_MODERATE` oder `SODIUM_CRYPTO_PWHASH_OPSLIMIT_SENSITIVE`.
$memlimit Pflicht	int	Die aktuell gewünschte Obergrenze für den Speicherbedarf in Bytes. Typische Konstanten: `SODIUM_CRYPTO_PWHASH_MEMLIMIT_INTERACTIVE`, `SODIUM_CRYPTO_PWHASH_MEMLIMIT_MODERATE` oder `SODIUM_CRYPTO_PWHASH_MEMLIMIT_SENSITIVE`.

Rückgabewert

Typ

bool

Beschreibung

Gibt true zurück, wenn der Hash neu berechnet werden sollte – entweder weil die gespeicherten Parameter unterhalb der geforderten Werte liegen oder weil der Hash ungültig/unbekannt ist. Gibt false zurück, wenn der Hash den aktuellen Anforderungen bereits entspricht.

Beispiele

Rehash-Prüfung nach erfolgreichem Login

<?php
// Aktuell gewünschte Parameter
$opslimit = SODIUM_CRYPTO_PWHASH_OPSLIMIT_INTERACTIVE;
$memlimit = SODIUM_CRYPTO_PWHASH_MEMLIMIT_INTERACTIVE;

// Simulierter Datenbankwert (alter Hash mit niedrigeren Parametern)
$storedHash = sodium_crypto_pwhash_str(
    'geheimesPasswort',
    SODIUM_CRYPTO_PWHASH_OPSLIMIT_MIN,
    SODIUM_CRYPTO_PWHASH_MEMLIMIT_MIN
);

$inputPassword = 'geheimesPasswort';

// Schritt 1: Passwort verifizieren
if (sodium_crypto_pwhash_str_verify($storedHash, $inputPassword)) {
    echo "Login erfolgreich." . PHP_EOL;

    // Schritt 2: Prüfen, ob Rehash nötig ist
    if (sodium_crypto_pwhash_str_needs_rehash($storedHash, $opslimit, $memlimit)) {
        echo "Hash veraltet – wird neu berechnet." . PHP_EOL;
        $newHash = sodium_crypto_pwhash_str($inputPassword, $opslimit, $memlimit);
        // $newHash in der Datenbank speichern
        echo "Neuer Hash gespeichert." . PHP_EOL;
    } else {
        echo "Hash ist noch aktuell." . PHP_EOL;
    }
} else {
    echo "Ungültiges Passwort." . PHP_EOL;
}

Login erfolgreich. Hash veraltet – wird neu berechnet. Neuer Hash gespeichert.

Massenprüfung gespeicherter Hashes auf Aktualität

<?php
$opslimit = SODIUM_CRYPTO_PWHASH_OPSLIMIT_MODERATE;
$memlimit = SODIUM_CRYPTO_PWHASH_MEMLIMIT_MODERATE;

// Simulierte Liste aus der Datenbank
$hashes = [
    'user1' => sodium_crypto_pwhash_str('pw1', SODIUM_CRYPTO_PWHASH_OPSLIMIT_MIN, SODIUM_CRYPTO_PWHASH_MEMLIMIT_MIN),
    'user2' => sodium_crypto_pwhash_str('pw2', SODIUM_CRYPTO_PWHASH_OPSLIMIT_MODERATE, SODIUM_CRYPTO_PWHASH_MEMLIMIT_MODERATE),
];

foreach ($hashes as $user => $hash) {
    if (sodium_crypto_pwhash_str_needs_rehash($hash, $opslimit, $memlimit)) {
        echo "{$user}: Hash muss beim nächsten Login erneuert werden." . PHP_EOL;
    } else {
        echo "{$user}: Hash ist aktuell." . PHP_EOL;
    }
}

user1: Hash muss beim nächsten Login erneuert werden. user2: Hash ist aktuell.

// Wichtig · Fallstricke

Sicherheitshinweis: Das Rehashing sollte nur nach einer erfolgreichen Passwortverifikation erfolgen, da dazu das Klartextpasswort benötigt wird. Speichern Sie niemals Klartextpasswörter, um späteres Rehashing zu ermöglichen.

Wenn $hash kein gültiger Argon2id-Hash ist (z. B. ein alter MD5- oder bcrypt-Hash), gibt die Funktion true zurück. Dies ermöglicht eine sichere Migration auch von fremden Hash-Formaten, sofern das Klartextpasswort zur Verifikation noch anderweitig geprüft werden kann.

Die Funktion wirft keine Exception und gibt im Fehlerfall immer true zurück – dies ist ein bewusstes sicheres Standardverhalten (Fail-Safe).

Siehe auch

sodium_crypto_pwhash_str sodium_crypto_pwhash_str_verify sodium_crypto_pwhash password_needs_rehash password_hash