sodium_crypto_pwhash_str — Funktion · PHP-Referenz

Signatur

sodium_crypto_pwhash_str(string $password, int $opslimit, int $memlimit): string

Beschreibung

sodium_crypto_pwhash_str ist eine Funktion der libsodium-Erweiterung, die ein Passwort mit dem Argon2id-Algorithmus hasht. Das Ergebnis ist ein selbstbeschreibender, ASCII-kodierter String, der Salt, Algorithmus-Parameter und den eigentlichen Hash-Wert enthält – ähnlich dem Format von password_hash(). Dieser String kann direkt in einer Datenbank gespeichert und später mit sodium_crypto_pwhash_str_verify überprüft werden.

Die beiden Kostenparameter $opslimit (CPU-Aufwand) und $memlimit (Speicherverbrauch in Bytes) steuern, wie rechenintensiv und damit brute-force-resistent der Hashing-Vorgang ist. Für typische interaktive Anwendungen (z. B. Web-Login) empfehlen sich die Konstanten SODIUM_CRYPTO_PWHASH_OPSLIMIT_INTERACTIVE und SODIUM_CRYPTO_PWHASH_MEMLIMIT_INTERACTIVE. Für sensiblere Anwendungsfälle (z. B. Verschlüsselung privater Daten) sollte man SODIUM_CRYPTO_PWHASH_OPSLIMIT_SENSITIVE und SODIUM_CRYPTO_PWHASH_MEMLIMIT_SENSITIVE verwenden.

Ein großer Vorteil gegenüber veralteten Funktionen wie md5 oder sha1 ist, dass Argon2id bewusst langsam und speicherintensiv gestaltet ist, was GPU-basierte Brute-Force-Angriffe erheblich erschwert. Ein zufälliger Salt wird automatisch generiert und im Rückgabe-String eingebettet, sodass keine manuelle Salt-Verwaltung erforderlich ist.

Diese Funktion ist die empfohlene Alternative zu password_hash(PASSWORD_ARGON2ID) wenn man bereits libsodium nutzt oder explizit die Argon2id-Parameter feingranular steuern möchte.

Parameter

Name	Typ	Beschreibung
$password Pflicht	string	Das zu hashende Klartext-Passwort. Es gibt keine Längenbeschränkung, aber sehr lange Passwörter können den Vorgang verlangsamen.
$opslimit Pflicht	int	Maximale Anzahl an CPU-Operationen beim Hashing. Höhere Werte bedeuten mehr Sicherheit, aber auch mehr Rechenzeit. Empfohlene Konstanten: `SODIUM_CRYPTO_PWHASH_OPSLIMIT_INTERACTIVE`, `SODIUM_CRYPTO_PWHASH_OPSLIMIT_MODERATE` oder `SODIUM_CRYPTO_PWHASH_OPSLIMIT_SENSITIVE`.
$memlimit Pflicht	int	Maximale Speichermenge in Bytes, die beim Hashing verwendet wird. Höhere Werte erschweren GPU-Angriffe. Empfohlene Konstanten: `SODIUM_CRYPTO_PWHASH_MEMLIMIT_INTERACTIVE`, `SODIUM_CRYPTO_PWHASH_MEMLIMIT_MODERATE` oder `SODIUM_CRYPTO_PWHASH_MEMLIMIT_SENSITIVE`.

Rückgabewert

Typ

string

Beschreibung

Gibt einen ASCII-kodierten Hash-String zurück, der Salt, Algorithmus-Parameter und den Hash-Wert in einem Format enthält, das direkt von sodium_crypto_pwhash_str_verify ausgewertet werden kann. Bei einem Fehler wird eine SodiumException geworfen.

Beispiele

Passwort für Login-System hashen und speichern

<?php
// Passwort des Benutzers aus dem Registrierungsformular
$password = $_POST['password'] ?? '';

// Hash erzeugen mit interaktiven Kostenwerten (geeignet für Web-Logins)
$hash = sodium_crypto_pwhash_str(
    $password,
    SODIUM_CRYPTO_PWHASH_OPSLIMIT_INTERACTIVE,
    SODIUM_CRYPTO_PWHASH_MEMLIMIT_INTERACTIVE
);

// Beispiel-Ausgabe des Hash-Strings (enthält Salt und Parameter)
echo $hash;
// Ausgabe z. B.: $argon2id$v=19$m=65536,t=2,p=1$...

// In der Datenbank speichern (als VARCHAR(255) oder TEXT)
// $pdo->prepare('INSERT INTO users (email, password_hash) VALUES (?, ?)')->execute([$email, $hash]);

$argon2id$v=19$m=65536,t=2,p=1$<salt>$<hash>

Passwort beim Login verifizieren

<?php
// Aus der Datenbank geladener Hash
$storedHash = '$argon2id$v=19$m=65536,t=2,p=1$...gespeicherter_hash...';

// Eingegebenes Passwort aus dem Login-Formular
$inputPassword = $_POST['password'] ?? '';

// Passwort gegen gespeicherten Hash prüfen
if (sodium_crypto_pwhash_str_verify($storedHash, $inputPassword)) {
    echo 'Login erfolgreich!';

    // Prüfen, ob der Hash mit aktuellen Parametern neu berechnet werden sollte
    if (sodium_crypto_pwhash_str_needs_rehash(
        $storedHash,
        SODIUM_CRYPTO_PWHASH_OPSLIMIT_INTERACTIVE,
        SODIUM_CRYPTO_PWHASH_MEMLIMIT_INTERACTIVE
    )) {
        $newHash = sodium_crypto_pwhash_str(
            $inputPassword,
            SODIUM_CRYPTO_PWHASH_OPSLIMIT_INTERACTIVE,
            SODIUM_CRYPTO_PWHASH_MEMLIMIT_INTERACTIVE
        );
        // Neuen Hash in der Datenbank speichern
        echo ' (Hash wurde aktualisiert)';
    }
} else {
    echo 'Ungültige Anmeldedaten.';
}

Login erfolgreich!

Sensible Daten mit erhöhten Sicherheitsparametern schützen

<?php
// Für sensible Daten (z. B. Verschlüsselung privater Schlüssel)
// werden stärkere Kostenwerte empfohlen
try {
    $sensitiveHash = sodium_crypto_pwhash_str(
        'mein_sehr_geheimes_passwort',
        SODIUM_CRYPTO_PWHASH_OPSLIMIT_SENSITIVE,
        SODIUM_CRYPTO_PWHASH_MEMLIMIT_SENSITIVE
    );
    echo 'Hash erfolgreich erzeugt: ' . strlen($sensitiveHash) . ' Zeichen';
} catch (SodiumException $e) {
    // Kann auftreten, wenn nicht genug Speicher verfügbar ist
    echo 'Fehler beim Hashing: ' . $e->getMessage();
}

Hash erfolgreich erzeugt: 97 Zeichen

// Wichtig · Fallstricke

Sicherheitshinweise:

Speichern Sie den vollständigen Rückgabe-String in der Datenbank – er enthält alle notwendigen Informationen zur späteren Verifikation. Als Datenbankspaltentyp empfiehlt sich VARCHAR(255) oder TEXT.
Wählen Sie $opslimit und $memlimit so hoch, dass das Hashing auf Ihrem Server ca. 0,1–1 Sekunde dauert (für interaktive Anwendungen). Zu niedrige Werte schwächen die Sicherheit erheblich.
Bei zu niedrigem $memlimit (unter SODIUM_CRYPTO_PWHASH_MEMLIMIT_MIN) oder ungültigen Parametern wird eine SodiumException geworfen – fangen Sie diese immer ab.
Verwenden Sie niemals selbst gewählte, sehr niedrige Integer-Werte für die Kostenparameter. Nutzen Sie stets die vordefinierten Konstanten der libsodium-Bibliothek.
Im Gegensatz zu password_hash() müssen hier Kostenparameter explizit angegeben werden. Das gibt mehr Kontrolle, erfordert aber auch mehr Sorgfalt bei der Wahl geeigneter Werte.
Der erzeugte Hash-String ist nicht fest gleich lang – planen Sie ausreichend Speicherplatz ein.

Siehe auch

sodium_crypto_pwhash_str_verify sodium_crypto_pwhash_str_needs_rehash sodium_crypto_pwhash password_hash password_verify password_needs_rehash