sodium_crypto_pwhash_scryptsalsa208sha256 — Funktion · PHP-Referenz

Signatur

sodium_crypto_pwhash_scryptsalsa208sha256(int $length, string $password, string $salt, int $opslimit, int $memlimit): string

Beschreibung

Die Funktion sodium_crypto_pwhash_scryptsalsa208sha256() verwendet den scrypt-Algorithmus, um aus einem Passwort und einem Salt einen Schlüssel mit frei wählbarer Länge abzuleiten. scrypt ist speicher- und CPU-intensiv konzipiert, sodass Brute-Force- und Dictionary-Angriffe durch Angreifer mit spezialisierter Hardware (z. B. ASICs, GPUs) erheblich erschwert werden.

Der Parameter $opslimit steuert den Rechenaufwand (Anzahl der Operationen), während $memlimit den Speicherbedarf in Bytes definiert. Beide Parameter sollten so hoch gewählt werden, dass ein legitimer Hash-Vorgang noch in akzeptabler Zeit abläuft, aber Angriffe unwirtschaftlich teuer werden. Die Konstanten SODIUM_CRYPTO_PWHASH_SCRYPTSALSA208SHA256_OPSLIMIT_INTERACTIVE und SODIUM_CRYPTO_PWHASH_SCRYPTSALSA208SHA256_MEMLIMIT_INTERACTIVE bieten vernünftige Standardwerte für interaktive Anwendungen.

Typische Anwendungsfälle sind: Ableitung eines symmetrischen Verschlüsselungsschlüssels aus einem Benutzerpasswort, Erzeugen von Schlüsselmaterial für weitere kryptografische Operationen sowie als Alternative zu sodium_crypto_pwhash() (Argon2), wenn explizit scrypt gewünscht wird. Für das Speichern von Passwort-Hashes empfiehlt sich hingegen sodium_crypto_pwhash_scryptsalsa208sha256_str().

Das Salt muss zufällig und einmalig sein; es sollte mit random_bytes(SODIUM_CRYPTO_PWHASH_SCRYPTSALSA208SHA256_SALTBYTES) erzeugt und zusammen mit dem abgeleiteten Schlüssel (oder dem Verifikationsstring) gespeichert werden.

Parameter

Name	Typ	Beschreibung
$length Pflicht	int	Gewünschte Länge des abgeleiteten Schlüssels in Bytes. Muss mindestens `SODIUM_CRYPTO_PWHASH_SCRYPTSALSA208SHA256_BYTES_MIN` und höchstens `SODIUM_CRYPTO_PWHASH_SCRYPTSALSA208SHA256_BYTES_MAX` betragen.
$password Pflicht	string	Das Passwort im Klartext, aus dem der Schlüssel abgeleitet werden soll. Länge und Zeichensatz sind frei wählbar.
$salt Pflicht	string	Ein zufälliges, kryptografisch sicheres Salt. Muss exakt `SODIUM_CRYPTO_PWHASH_SCRYPTSALSA208SHA256_SALTBYTES` Bytes lang sein. Empfohlen: `random_bytes(SODIUM_CRYPTO_PWHASH_SCRYPTSALSA208SHA256_SALTBYTES)`.
$opslimit Pflicht	int	Maximale Anzahl der Rechenoperationen. Höhere Werte erhöhen den Rechenaufwand. Vordefinierte Konstanten: `SODIUM_CRYPTO_PWHASH_SCRYPTSALSA208SHA256_OPSLIMIT_INTERACTIVE` (normal), `SODIUM_CRYPTO_PWHASH_SCRYPTSALSA208SHA256_OPSLIMIT_SENSITIVE` (hoch).
$memlimit Pflicht	int	Maximaler Speicherverbrauch in Bytes. Höhere Werte machen Angriffe teurer. Vordefinierte Konstanten: `SODIUM_CRYPTO_PWHASH_SCRYPTSALSA208SHA256_MEMLIMIT_INTERACTIVE` (normal), `SODIUM_CRYPTO_PWHASH_SCRYPTSALSA208SHA256_MEMLIMIT_SENSITIVE` (hoch).

Rückgabewert

Typ

string

Beschreibung

Gibt einen binären String der angeforderten Länge ($length Bytes) zurück, der das abgeleitete Schlüsselmaterial enthält. Im Fehlerfall (z. B. ungültige Salt-Länge oder unzureichender Speicher) wird eine SodiumException ausgelöst.

Beispiele

Verschlüsselungsschlüssel aus Passwort ableiten

<?php
// Salt erzeugen (wird dauerhaft gespeichert, z. B. in der Datenbank)
$salt = random_bytes(SODIUM_CRYPTO_PWHASH_SCRYPTSALSA208SHA256_SALTBYTES);

$password = 'MeinSicheresPasswort!';

// 32-Byte-Schlüssel für AES-256 oder XSalsa20 ableiten
$key = sodium_crypto_pwhash_scryptsalsa208sha256(
    32,
    $password,
    $salt,
    SODIUM_CRYPTO_PWHASH_SCRYPTSALSA208SHA256_OPSLIMIT_INTERACTIVE,
    SODIUM_CRYPTO_PWHASH_SCRYPTSALSA208SHA256_MEMLIMIT_INTERACTIVE
);

echo 'Schlüssellänge: ' . strlen($key) . ' Bytes' . PHP_EOL;
echo 'Schlüssel (hex): ' . sodium_bin2hex($key) . PHP_EOL;

// Speicher sicher löschen
sodium_memzero($password);
sodium_memzero($key);

Schlüssellänge: 32 Bytes Schlüssel (hex): <64 hexadezimale Zeichen>

Schlüssel reproduzieren (gleiches Salt + Passwort)

<?php
// Gespeichertes Salt (z. B. aus der Datenbank geladen)
$salt = sodium_hex2bin('0102030405060708090a0b0c0d0e0f101112131415161718191a1b1c1d1e1f20');
// Sicherstellen, dass Salt die korrekte Länge hat
assert(strlen($salt) === SODIUM_CRYPTO_PWHASH_SCRYPTSALSA208SHA256_SALTBYTES);

$password = 'MeinSicheresPasswort!';

$key1 = sodium_crypto_pwhash_scryptsalsa208sha256(
    32,
    $password,
    $salt,
    SODIUM_CRYPTO_PWHASH_SCRYPTSALSA208SHA256_OPSLIMIT_INTERACTIVE,
    SODIUM_CRYPTO_PWHASH_SCRYPTSALSA208SHA256_MEMLIMIT_INTERACTIVE
);

$key2 = sodium_crypto_pwhash_scryptsalsa208sha256(
    32,
    $password,
    $salt,
    SODIUM_CRYPTO_PWHASH_SCRYPTSALSA208SHA256_OPSLIMIT_INTERACTIVE,
    SODIUM_CRYPTO_PWHASH_SCRYPTSALSA208SHA256_MEMLIMIT_INTERACTIVE
);

// Beide Schlüssel müssen identisch sein
if (hash_equals($key1, $key2)) {
    echo 'Schlüssel sind identisch – Ableitung ist deterministisch.' . PHP_EOL;
}

sodium_memzero($password);
sodium_memzero($key1);
sodium_memzero($key2);

Schlüssel sind identisch – Ableitung ist deterministisch.

// Wichtig · Fallstricke

Sicherheitshinweise:

Das Salt darf niemals wiederverwendet werden. Jedes Passwort benötigt ein eigenes, zufällig generiertes Salt.
Verwende niemals diesen Rückgabewert direkt als Passwort-Hash für eine Datenbank. Für die Verifikation von Passwörtern steht sodium_crypto_pwhash_scryptsalsa208sha256_str() / sodium_crypto_pwhash_scryptsalsa208sha256_str_verify() zur Verfügung.
Die abgeleiteten Schlüssel sollten nach Gebrauch mit sodium_memzero() aus dem Speicher gelöscht werden, um sie vor Speicher-Dumps zu schützen.
Für neue Projekte wird oft sodium_crypto_pwhash() mit Argon2id bevorzugt, da Argon2id sowohl speicher- als auch zeitintensiv ist und breiter empfohlen wird (RFC 9106).
Bei zu niedrig gewählten $opslimit- oder $memlimit-Werten wird eine SodiumException geworfen.

Siehe auch

sodium_crypto_pwhash_scryptsalsa208sha256_str sodium_crypto_pwhash_scryptsalsa208sha256_str_verify sodium_crypto_pwhash sodium_memzero random_bytes