sodium_crypto_generichash_init — Funktion · PHP-Referenz

Signatur

sodium_crypto_generichash_init(string $key = '', int $length = SODIUM_CRYPTO_GENERICHASH_BYTES): string

Beschreibung

sodium_crypto_generichash_init erzeugt einen internen Hash-Zustand (State), der anschließend mit sodium_crypto_generichash_update schrittweise mit Daten befüllt und schließlich mit sodium_crypto_generichash_final abgeschlossen wird. Diese dreistufige Vorgehensweise ist ideal, wenn Daten stückweise vorliegen – etwa beim Lesen großer Dateien oder beim Verarbeiten eines Netzwerk-Streams –, weil zu keinem Zeitpunkt der gesamte Inhalt im Arbeitsspeicher gehalten werden muss.

Intern basiert die Funktion auf dem kryptografisch starken BLAKE2b-Algorithmus, der deutlich schneller als SHA-3 und mindestens so sicher wie SHA-2 ist. Optional kann ein geheimer $key übergeben werden, womit der Hash als MAC (Message Authentication Code) fungiert, vergleichbar mit HMAC, aber effizienter. Ohne Schlüssel erzeugt die Funktion einen einfachen kryptografischen Prüfwert.

Der Rückgabewert ist ein opaker Binär-String, der den internen Zustand repräsentiert und ausschließlich als Argument für sodium_crypto_generichash_update und sodium_crypto_generichash_final verwendet werden sollte. Er darf nicht direkt interpretiert oder serialisiert werden.

Die Funktion ist Teil der libsodium-Bindungen (ext-sodium) und steht ab PHP 7.2 nativ zur Verfügung. Für ältere PHP-Versionen ist sie über das PECL-Paket libsodium verfügbar.

Parameter

Name	Typ	Default	Beschreibung
$key	string	''	Optionaler geheimer Schlüssel für BLAKE2b-MAC-Betrieb. Die Länge muss zwischen `SODIUM_CRYPTO_GENERICHASH_KEYBYTES_MIN` (16) und `SODIUM_CRYPTO_GENERICHASH_KEYBYTES_MAX` (64) Bytes liegen. Ein leerer String deaktiviert den MAC-Modus. Zum Erzeugen eines sicheren Schlüssels kann `sodium_crypto_generichash_keygen()` genutzt werden.
$length	int	SODIUM_CRYPTO_GENERICHASH_BYTES	Gewünschte Ausgabelänge des Hashes in Bytes. Muss zwischen `SODIUM_CRYPTO_GENERICHASH_BYTES_MIN` (16) und `SODIUM_CRYPTO_GENERICHASH_BYTES_MAX` (64) liegen. Standard ist `SODIUM_CRYPTO_GENERICHASH_BYTES` (32 Bytes).

Rückgabewert

Typ

string

Beschreibung

Gibt einen opaken Binär-String zurück, der den internen BLAKE2b-Hash-Zustand enthält. Dieser Zustand wird als Argument an sodium_crypto_generichash_update und sodium_crypto_generichash_final übergeben. Im Fehlerfall wird eine SodiumException geworfen.

Beispiele

Große Datei stückweise hashen

<?php
// Datei-Hash ohne Schlüssel (32 Bytes = Standard)
$state = sodium_crypto_generichash_init();

$fp = fopen('grosse-datei.bin', 'rb');
while (!feof($fp)) {
    $chunk = fread($fp, 8192);
    sodium_crypto_generichash_update($state, $chunk);
}
fclose($fp);

$hash = sodium_crypto_generichash_final($state);
echo bin2hex($hash) . PHP_EOL;
// Ausgabe: 64-stelliger Hex-String (32 Bytes)

a3f1c2... (64 Hex-Zeichen, abhängig vom Dateiinhalt)

Inkrementellen MAC mit Schlüssel erzeugen

<?php
// Schlüssel sicher generieren
$key = sodium_crypto_generichash_keygen();

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

$parts = ['Erster Teil der Nachricht.', ' Zweiter Teil.', ' Dritter Teil.'];
foreach ($parts as $part) {
    sodium_crypto_generichash_update($state, $part);
}

$mac = sodium_crypto_generichash_final($state, SODIUM_CRYPTO_GENERICHASH_BYTES_MAX);
echo 'MAC: ' . bin2hex($mac) . PHP_EOL;
// Ausgabe: 128-stelliger Hex-String (64 Bytes)

// Zur Verifikation: Gleiche Eingabe muss gleichen MAC liefern
$state2 = sodium_crypto_generichash_init($key, SODIUM_CRYPTO_GENERICHASH_BYTES_MAX);
sodium_crypto_generichash_update($state2, implode('', $parts));
$mac2 = sodium_crypto_generichash_final($state2, SODIUM_CRYPTO_GENERICHASH_BYTES_MAX);

if (sodium_memcmp($mac, $mac2) === 0) {
    echo 'MACs stimmen überein.' . PHP_EOL;
}

MAC: 3f9a... (128 Hex-Zeichen) MACs stimmen überein.

// Wichtig · Fallstricke

Sicherheitshinweise:

Den zurückgegebenen Zustand nie serialisieren oder in einer Datenbank speichern, da er interne kryptografische Informationen enthält und plattformabhängig ist.
Bei MAC-Verwendung muss der Schlüssel geheim und zufällig generiert sein – verwende sodium_crypto_generichash_keygen() statt selbst erdachter Schlüssel.
Den Vergleich von Hashes oder MACs stets mit sodium_memcmp() oder hash_equals() durchführen, um Timing-Angriffe zu vermeiden.
Die Länge des Ausgabe-Hashes muss bei sodium_crypto_generichash_final identisch mit dem bei sodium_crypto_generichash_init angegebenen $length sein, sonst wird eine Ausnahme ausgelöst.
Fehlerhafte Schlüssellängen oder ungültige Längenangaben führen zu einer SodiumException – die Funktion wirft keine klassischen PHP-Warnungen.

Siehe auch

sodium_crypto_generichash_update sodium_crypto_generichash_final sodium_crypto_generichash sodium_crypto_generichash_keygen sodium_memcmp hash_init