hash_init — Funktion · PHP-Referenz

Signatur

hash_init(string $algo, int $flags = 0, string $key = "", array $options = []): HashContext

Beschreibung

hash_init() erstellt einen neuen, inkrementellen Hash-Kontext, der es ermöglicht, Daten in mehreren Schritten zu hashen, ohne sie vollständig im Speicher vorzuhalten. Dies ist besonders nützlich beim Hashing großer Datenmengen wie Dateiinhalte oder Streams, die stückweise verarbeitet werden.

Der zurückgegebene HashContext wird anschließend mit hash_update() (für Strings) oder hash_update_stream() (für Streams) befüllt und schließlich mit hash_final() abgeschlossen, was den fertigen Hash-Wert liefert.

Wird der Flag HASH_HMAC gesetzt, arbeitet die Funktion im HMAC-Modus (Hash-based Message Authentication Code). In diesem Fall muss ein geheimer Schlüssel über den Parameter $key übergeben werden. HMAC eignet sich zur Integritätsprüfung und Authentifizierung von Nachrichten.

Seit PHP 8.1 unterstützt der Parameter $options algorithmusspezifische Optionen, z. B. die gewünschte Ausgabelänge für XOF-Algorithmen wie shake128 oder shake256.

Parameter

Name	Typ	Default	Beschreibung
$algo Pflicht	string		Name des zu verwendenden Hash-Algorithmus, z. B. `'sha256'`, `'sha512'` oder `'md5'`. Eine Liste aller unterstützten Algorithmen liefert `hash_algos()`.
$flags	int	0	Optionale Flags für den Hashing-Modus. Derzeit wird nur `HASH_HMAC` unterstützt, das den HMAC-Modus aktiviert und die Angabe eines geheimen Schlüssels über `$key` erfordert.
$key	string	""	Geheimer Schlüssel für den HMAC-Modus. Wird nur berücksichtigt, wenn `$flags` den Wert `HASH_HMAC` enthält. Sollte ausreichend lang und zufällig sein.
$options	array	[]	Algorithmusspezifische Optionen (seit PHP 8.1). Für XOF-Algorithmen wie `shake128` kann hier z. B. `['length' => 64]` die gewünschte Ausgabelänge in Bytes angeben.

Rückgabewert

Typ

HashContext

Beschreibung

Gibt ein HashContext-Objekt zurück, das den Hashing-Zustand repräsentiert und an hash_update(), hash_update_stream(), hash_update_file() und hash_final() übergeben werden kann. Bei ungültigem Algorithmus oder fehlendem HMAC-Schlüssel wird eine ValueError-Exception geworfen (seit PHP 8.0; zuvor false).

Beispiele

Schrittweises Hashing einer großen Datei

<?php
// SHA-256-Hash einer Datei chunkweise berechnen
$context = hash_init('sha256');

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

while (!feof($handle)) {
    $chunk = fread($handle, 8192); // 8 KB pro Schritt
    hash_update($context, $chunk);
}
fclose($handle);

$hash = hash_final($context);
echo 'SHA-256: ' . $hash . PHP_EOL;

SHA-256: <hexadezimaler Hash der Datei>

HMAC im Streaming-Modus

<?php
// HMAC-SHA256 eines Textes in mehreren Teilen berechnen
$secretKey = 'mein-geheimer-schluessel';

$context = hash_init('sha256', HASH_HMAC, $secretKey);

hash_update($context, 'Erster Teil der Nachricht. ');
hash_update($context, 'Zweiter Teil der Nachricht.');

$hmac = hash_final($context);
echo 'HMAC-SHA256: ' . $hmac . PHP_EOL;

// Zum Vergleich: Einmaliger HMAC über die vollständige Nachricht
$vergleich = hash_hmac('sha256', 'Erster Teil der Nachricht. Zweiter Teil der Nachricht.', $secretKey);
echo 'Vergleich:   ' . $vergleich . PHP_EOL;
echo 'Identisch:   ' . ($hmac === $vergleich ? 'Ja' : 'Nein') . PHP_EOL;

HMAC-SHA256: <hexadezimaler HMAC> Vergleich: <hexadezimaler HMAC> Identisch: Ja

XOF-Algorithmus mit benutzerdefinierter Ausgabelänge (PHP 8.1+)

<?php
// SHAKE128 mit 32 Byte Ausgabe
$context = hash_init('shake128', options: ['length' => 32]);
hash_update($context, 'Testdaten');
$hash = hash_final($context);
echo 'SHAKE128 (32 Byte): ' . $hash . PHP_EOL;

SHAKE128 (32 Byte): <64 hexadezimale Zeichen>

// Wichtig · Fallstricke

Sicherheitshinweise:

Für kryptografisch sichere Passwort-Hashes sollte password_hash() statt hash_init() verwendet werden, da letztere keine Salts oder Iterationen verwaltet.
Der HMAC-Schlüssel sollte mittels random_bytes() erzeugt und sicher gespeichert werden. Kurze oder vorhersehbare Schlüssel schwächen die Sicherheit erheblich.
Beim Vergleich von HMACs immer hash_equals() statt === verwenden, um Timing-Angriffe zu verhindern.
MD5 und SHA-1 gelten als kryptografisch unsicher und sollten nicht für sicherheitskritische Anwendungen verwendet werden.

Ab PHP 8.0 wirft die Funktion bei ungültigem Algorithmus oder fehlendem HMAC-Schlüssel eine ValueError-Exception; in früheren Versionen wurde false zurückgegeben und ein E_WARNING ausgelöst.

Siehe auch

hash_update hash_update_stream hash_update_file hash_final hash_hmac hash_algos hash_equals hash