sodium_crypto_generichash_update — Funktion · PHP-Referenz

Signatur

sodium_crypto_generichash_update(string &$state, string $msg): bool

Beschreibung

sodium_crypto_generichash_update ist Teil des Streaming-Interface für den BLAKE2b-Hashing-Algorithmus aus der libsodium-Bibliothek. Sie nimmt einen zuvor mit sodium_crypto_generichash_init erzeugten Zustand entgegen und verarbeitet einen weiteren Datenblock, ohne die bisher verarbeiteten Daten erneut einlesen zu müssen.

Diese Funktion ist besonders nützlich, wenn große Datenmengen in Blöcken gehasht werden sollen – etwa beim Lesen einer Datei in Chunks –, da nicht der gesamte Inhalt auf einmal im Speicher gehalten werden muss. Der interne Zustand $state wird dabei direkt als Referenz aktualisiert.

Das Zusammenspiel der drei Funktionen sodium_crypto_generichash_init, sodium_crypto_generichash_update und sodium_crypto_generichash_final entspricht dem klassischen Init-Update-Final-Pattern, das aus vielen kryptographischen Bibliotheken bekannt ist. Es können beliebig viele _update-Aufrufe zwischen Init und Final erfolgen.

BLAKE2b ist ein schneller und kryptographisch sicherer Hash-Algorithmus, der als Ersatz für MD5, SHA-1 und SHA-2 geeignet ist. Er unterstützt optionale Schlüssel (MAC-Modus) und variable Ausgabelängen.

Parameter

Name	Typ	Default	Beschreibung
$state Pflicht	string		Der laufende Hash-Zustand als Referenz, erzeugt von `sodium_crypto_generichash_init`. Wird in-place aktualisiert.
$msg Pflicht	string		Der Datenchunk (Nachricht oder Dateiblock), der in den laufenden Hash eingearbeitet werden soll. Kann beliebig lang sein.

Rückgabewert

Typ

bool

Beschreibung

Gibt true zurück, wenn der Update-Schritt erfolgreich war. Bei einem Fehler wird eine SodiumException geworfen, nicht false zurückgegeben.

Beispiele

Datei blockweise hashen

<?php
// Großes File in 8-KB-Chunks hashen, ohne alles in den Speicher zu laden
$key   = sodium_crypto_generichash_keygen(); // 32-Byte-Schlüssel
$state = sodium_crypto_generichash_init($key, SODIUM_CRYPTO_GENERICHASH_BYTES);

$handle = fopen('/var/www/upload/large_file.bin', 'rb');
if ($handle === false) {
    throw new RuntimeException('Datei konnte nicht geöffnet werden.');
}

while (!feof($handle)) {
    $chunk = fread($handle, 8192);
    if ($chunk === false) break;
    sodium_crypto_generichash_update($state, $chunk);
}
fclose($handle);

$hash = sodium_crypto_generichash_final($state, SODIUM_CRYPTO_GENERICHASH_BYTES);
echo 'BLAKE2b-Hash: ' . sodium_bin2hex($hash) . PHP_EOL;

BLAKE2b-Hash: <64-stelliger Hex-String>

Mehrere Strings zu einem Hash zusammenführen

<?php
// Einzelne Felder eines Datensatzes zu einem einzigen Hash kombinieren
$state = sodium_crypto_generichash_init('', SODIUM_CRYPTO_GENERICHASH_BYTES);

sodium_crypto_generichash_update($state, 'Benutzer:');
sodium_crypto_generichash_update($state, 'alice@example.com');
sodium_crypto_generichash_update($state, '|Zeitstempel:');
sodium_crypto_generichash_update($state, (string) time());

$hash = sodium_crypto_generichash_final($state, SODIUM_CRYPTO_GENERICHASH_BYTES);
echo sodium_bin2hex($hash) . PHP_EOL;

// Zur Verifikation: direktes Hashen des zusammengesetzten Strings liefert dasselbe Ergebnis
$direct = sodium_crypto_generichash(
    'Benutzer:alice@example.com|Zeitstempel:' . time(),
    '',
    SODIUM_CRYPTO_GENERICHASH_BYTES
);
// $hash === $direct (wenn time() identisch ist)

// Wichtig · Fallstricke

Wichtig: Der $state-Parameter wird als Referenz übergeben und darf nicht manuell verändert werden. Eine Kopie des Zustands kann jedoch angelegt werden, um an einem bestimmten Punkt in der Hash-Berechnung zu branchen (z. B. für Prefix-MACs).

Kompatibilität: Das Streaming-Interface steht erst ab PHP 7.2 zur Verfügung, da libsodium erst ab dieser Version Bestandteil der PHP-Standarderweiterungen ist. Für ältere PHP-Versionen kann die PECL-Erweiterung libsodium verwendet werden.

Fehlerbehandlung: Fehler werden als SodiumException geworfen. Aufrufe sollten daher in einen try/catch-Block eingebettet werden.

Siehe auch

sodium_crypto_generichash_init sodium_crypto_generichash_final sodium_crypto_generichash sodium_crypto_generichash_keygen hash_update