sodium_crypto_generichash — Funktion · PHP-Referenz

Signatur

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

Beschreibung

sodium_crypto_generichash() ist eine flexible kryptografische Hash-Funktion, die auf dem BLAKE2b-Algorithmus basiert. Sie kann sowohl als einfache Hash-Funktion als auch als keyed Hash (ähnlich einem HMAC) verwendet werden. Die Funktion ist ein Teil der libsodium-Bibliothek und steht in PHP seit Version 7.2 nativ zur Verfügung.

Im Unterschied zu md5() oder sha1() ist BLAKE2b für kryptografische Sicherheit ausgelegt: Es ist kollisionsresistent, vorbildresistent und schnell auf moderner Hardware. Wenn ein optionaler $key angegeben wird, verhält sich die Funktion wie eine MAC-Funktion (Message Authentication Code), mit der die Integrität und Authentizität von Daten verifiziert werden kann.

Typische Einsatzgebiete sind: Datei-Integritätsprüfungen, Erstellung von Prüfsummen für Caches oder Datenbanken, Ableitungen von Schlüsseln sowie Authentifizierungs-Tokens. Die Ausgabelänge kann über den Parameter $length flexibel zwischen SODIUM_CRYPTO_GENERICHASH_BYTES_MIN (16) und SODIUM_CRYPTO_GENERICHASH_BYTES_MAX (64) eingestellt werden.

Für Passwort-Hashing ist diese Funktion nicht geeignet – dafür sollte sodium_crypto_pwhash() oder password_hash() verwendet werden, da diese bewusst langsam und ressourcenintensiv sind.

Parameter

Name	Typ	Default	Beschreibung
$msg Pflicht	string		Die Nachricht (beliebige Binärdaten oder Zeichenkette), die gehasht werden soll.
$key	string		Optionaler Schlüssel für einen keyed Hash (MAC). Die Länge muss zwischen `SODIUM_CRYPTO_GENERICHASH_KEYBYTES_MIN` (16) und `SODIUM_CRYPTO_GENERICHASH_KEYBYTES_MAX` (64) Bytes liegen. Wird kein Schlüssel angegeben, verhält sich die Funktion wie ein normaler Hash ohne Authentifizierung.
$length	int	SODIUM_CRYPTO_GENERICHASH_BYTES	Gewünschte Länge des Hashes in Bytes. Der Standardwert ist `SODIUM_CRYPTO_GENERICHASH_BYTES` (32). Erlaubt sind Werte von `SODIUM_CRYPTO_GENERICHASH_BYTES_MIN` (16) bis `SODIUM_CRYPTO_GENERICHASH_BYTES_MAX` (64).

Rückgabewert

Typ

string

Beschreibung

Gibt den berechneten Hash als rohen Binär-String der angegebenen Länge zurück. Für eine hexadezimale Darstellung kann der Rückgabewert mit sodium_bin2hex() oder bin2hex() kodiert werden.

Beispiele

Einfacher Hash ohne Schlüssel

<?php
$message = 'Hallo, Welt!';

// Standard-Hash mit 32 Bytes Ausgabe
$hash = sodium_crypto_generichash($message);

echo 'Hash (hex): ' . sodium_bin2hex($hash) . PHP_EOL;
echo 'Länge: ' . strlen($hash) . ' Bytes' . PHP_EOL;
?>

Hash (hex): 5a4e6dc8e1e3a0bfbf6d8b9e3c7a5f0123456789abcdef0123456789abcdef01 Länge: 32 Bytes

Keyed Hash zur Nachrichtenintegrität (MAC)

<?php
// Schlüssel erzeugen (einmalig, sicher speichern)
$key = sodium_crypto_generichash_keygen();

$data = 'Wichtige Nutzlast: Bestellnummer 4711';

// MAC berechnen
$mac = sodium_crypto_generichash($data, $key);

echo 'MAC (hex): ' . sodium_bin2hex($mac) . PHP_EOL;

// Verifizierung: Hash erneut berechnen und vergleichen
$received_data = 'Wichtige Nutzlast: Bestellnummer 4711';
$expected_mac  = sodium_crypto_generichash($received_data, $key);

if (hash_equals($mac, $expected_mac)) {
    echo 'Nachricht ist authentisch und unverändert.' . PHP_EOL;
} else {
    echo 'WARNUNG: Nachricht wurde manipuliert!' . PHP_EOL;
}
?>

MAC (hex): a3f1c2e4b5d6a7b8c9d0e1f2a3b4c5d6e7f8091011121314151617181920212223 Nachricht ist authentisch und unverändert.

Hash mit benutzerdefinierter Ausgabelänge

<?php
$message = 'Datei-Inhalt zum Prüfen';

// 64-Byte-Hash (maximale Länge, entspricht BLAKE2b-512)
$hash64 = sodium_crypto_generichash($message, '', SODIUM_CRYPTO_GENERICHASH_BYTES_MAX);
echo 'BLAKE2b-512 (hex): ' . sodium_bin2hex($hash64) . PHP_EOL;

// 16-Byte-Hash (minimale Länge)
$hash16 = sodium_crypto_generichash($message, '', SODIUM_CRYPTO_GENERICHASH_BYTES_MIN);
echo 'BLAKE2b-128 (hex): ' . sodium_bin2hex($hash16) . PHP_EOL;
?>

BLAKE2b-512 (hex): a1b2c3d4e5f6...(128 Hex-Zeichen) BLAKE2b-128 (hex): 0a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d

// Wichtig · Fallstricke

Sicherheitshinweise:

Kein Passwort-Hashing: Diese Funktion ist nicht für das Hashing von Passwörtern geeignet, da sie zu schnell ist. Verwende stattdessen sodium_crypto_pwhash() oder password_hash().
Timing-sichere Vergleiche: Beim Vergleichen von zwei Hashes stets hash_equals() verwenden, um Timing-Angriffe zu verhindern.
Schlüssellänge: Bei Angabe eines Schlüssels muss dessen Länge zwischen SODIUM_CRYPTO_GENERICHASH_KEYBYTES_MIN und SODIUM_CRYPTO_GENERICHASH_KEYBYTES_MAX liegen, sonst wird eine SodiumException ausgelöst. Zur sicheren Schlüsselerzeugung empfiehlt sich sodium_crypto_generichash_keygen().
Binärausgabe: Der Rückgabewert ist ein roher Binär-String. Für Datenbankspeicherung oder Ausgabe mit sodium_bin2hex() oder base64_encode() konvertieren.
Die Funktion wirft eine SodiumException, wenn die angegebene Hash-Länge oder Schlüssellänge außerhalb der gültigen Grenzen liegt.

Siehe auch

sodium_crypto_generichash_keygen sodium_crypto_generichash_init sodium_crypto_generichash_update sodium_crypto_generichash_final sodium_crypto_pwhash sodium_bin2hex hash_equals password_hash