sodium_crypto_generichash_final — Funktion · PHP-Referenz

Signatur

sodium_crypto_generichash_final(string &$state, int $length = SODIUM_CRYPTO_GENERICHASH_BYTES): string

Beschreibung

sodium_crypto_generichash_final() beendet eine mehrstufige (Streaming-)Hash-Berechnung, die zuvor mit sodium_crypto_generichash_init() initialisiert und mit einem oder mehreren Aufrufen von sodium_crypto_generichash_update() befüllt wurde. Die Funktion gibt den fertig berechneten BLAKE2b-Hash als binären String zurück.

Dieser Streaming-Ansatz ist besonders sinnvoll, wenn große Datenmengen in Chunks verarbeitet werden sollen (z. B. beim Hashing großer Dateien), ohne dass der gesamte Inhalt auf einmal im Speicher gehalten werden muss. Statt alle Daten zu puffern, werden sie schrittweise in den internen Zustand eingearbeitet.

Der Parameter $length legt die gewünschte Ausgabelänge des Hashes in Bytes fest. Gültige Werte liegen zwischen SODIUM_CRYPTO_GENERICHASH_BYTES_MIN (16) und SODIUM_CRYPTO_GENERICHASH_BYTES_MAX (64). Standardmäßig wird SODIUM_CRYPTO_GENERICHASH_BYTES (32) verwendet.

Nach dem Aufruf von sodium_crypto_generichash_final() ist der übergebene $state verbraucht und darf nicht mehr für weitere Updates verwendet werden. Für einen neuen Hash-Vorgang muss sodium_crypto_generichash_init() erneut aufgerufen werden.

Parameter

Name	Typ	Default	Beschreibung
$state Pflicht	string		Der interne Zustand der Hash-Berechnung, der zuvor durch `sodium_crypto_generichash_init()` erzeugt und durch `sodium_crypto_generichash_update()` befüllt wurde. Wird als Referenz übergeben und nach dem Aufruf als ungültig markiert.
$length	int	SODIUM_CRYPTO_GENERICHASH_BYTES	Gewünschte Länge des Ausgabe-Hashes in Bytes. Muss zwischen `SODIUM_CRYPTO_GENERICHASH_BYTES_MIN` (16) und `SODIUM_CRYPTO_GENERICHASH_BYTES_MAX` (64) liegen. Standard ist 32 Bytes.

Rückgabewert

Typ

string

Beschreibung

Gibt den fertigen BLAKE2b-Hash als binären String der angegebenen Länge zurück. Im Fehlerfall wird eine SodiumException ausgelöst.

Beispiele

Einfache mehrstufige Hash-Berechnung

<?php
// Zustand initialisieren (kein Schlüssel, Standard-Ausgabelänge)
$state = sodium_crypto_generichash_init();

// Daten in Blöcken hinzufügen
sodium_crypto_generichash_update($state, 'Hallo ');
sodium_crypto_generichash_update($state, 'Welt!');

// Hash abschließen und ausgeben
$hash = sodium_crypto_generichash_final($state);
echo bin2hex($hash) . PHP_EOL;
// Ausgabe: 32-Byte BLAKE2b-Hash als Hex-String

a0b1c2d3... (64 Hex-Zeichen, BLAKE2b-Hash von "Hallo Welt!")

Große Datei chunk-weise hashen

<?php
$filename = '/var/www/uploads/grossedatei.bin';
$key = sodium_crypto_generichash_keygen(); // 32-Byte-Zufallsschlüssel

// Zustand mit Schlüssel und 64-Byte-Ausgabe initialisieren
$state = sodium_crypto_generichash_init($key, SODIUM_CRYPTO_GENERICHASH_BYTES_MAX);

$fp = fopen($filename, 'rb');
if ($fp === false) {
    throw new RuntimeException('Datei konnte nicht geöffnet werden.');
}

while (!feof($fp)) {
    $chunk = fread($fp, 8192); // 8 KB pro Durchlauf
    if ($chunk !== false && $chunk !== '') {
        sodium_crypto_generichash_update($state, $chunk);
    }
}
fclose($fp);

// Hash (64 Bytes) finalisieren
$hash = sodium_crypto_generichash_final($state, SODIUM_CRYPTO_GENERICHASH_BYTES_MAX);
echo 'Datei-Hash: ' . bin2hex($hash) . PHP_EOL;

Datei-Hash: (128 Hex-Zeichen, BLAKE2b-512-Hash der Datei)

// Wichtig · Fallstricke

Sicherheitshinweis: Der Rückgabewert ist ein roher Binär-String. Für die Ausgabe oder Speicherung sollte er mit bin2hex() oder base64_encode() in ein darstellbares Format umgewandelt werden.

Zustandsverwaltung: Der $state-Parameter wird als Referenz übergeben. Nach dem Aufruf von sodium_crypto_generichash_final() ist der Zustand erschöpft — weitere Aufrufe von sodium_crypto_generichash_update() auf demselben Zustand führen zu undefiniertem Verhalten oder einem Fehler.

Vergleiche: Beim Vergleich von zwei Hash-Werten sollte stets sodium_memcmp() oder hash_equals() verwendet werden, um Timing-Angriffe zu verhindern.

Siehe auch

sodium_crypto_generichash_init sodium_crypto_generichash_update sodium_crypto_generichash sodium_crypto_generichash_keygen hash_equals