hash_hmac_file — Funktion · PHP-Referenz

Signatur

hash_hmac_file(string $algo, string $filename, string $key, bool $binary = false): string|false

Beschreibung

hash_hmac_file() erzeugt einen HMAC (Hash-based Message Authentication Code) aus dem Inhalt einer Datei. Im Gegensatz zu einem einfachen Datei-Hash bindet HMAC einen geheimen Schlüssel ein, sodass der resultierende Wert nur von Parteien reproduziert werden kann, die diesen Schlüssel kennen. Dies eignet sich hervorragend zur Integritätsprüfung und Authentizitätssicherung von Dateien.

Die Funktion liest den Dateiinhalt direkt vom Dateisystem, ohne dass der Inhalt explizit in den Arbeitsspeicher geladen werden muss. Das macht sie besonders geeignet für große Dateien, da sie speichereffizient arbeitet. Als algo-Parameter stehen alle Algorithmen zur Verfügung, die auch hash_hmac() unterstützt – eine vollständige Liste liefert hash_hmac_algos().

Der Rückgabewert ist standardmäßig eine hexadezimale Zeichenkette in Kleinbuchstaben. Wird $binary auf true gesetzt, liefert die Funktion stattdessen den rohen Binär-Hash, was bei der Weiterverarbeitung (z. B. Base64-Kodierung) nützlich sein kann.

Sicherheitshinweis: Beim Vergleich zweier HMAC-Werte sollte ausschließlich hash_equals() verwendet werden, um Timing-Angriffe zu verhindern. Ein direkter Vergleich mit === ist anfällig für diese Art von Seitenkanal-Angriff.

Parameter

Name	Typ	Default	Beschreibung
$algo Pflicht	string		Name des Hash-Algorithmus, z. B. `"sha256"`, `"sha512"` oder `"sha3-256"`. Alle unterstützten Algorithmen liefert `hash_hmac_algos()`.
$filename Pflicht	string		Pfad zur Datei, deren Inhalt als Eingabe für den HMAC verwendet wird. Unterstützt auch URL-Wrapper (z. B. `ftp://`, `https://`), sofern diese aktiviert sind.
$key Pflicht	string		Der geheime Schlüssel, der in die HMAC-Berechnung einfließt. Sollte ausreichend lang und zufällig sein (empfohlen: mindestens 32 Byte, erzeugt z. B. mit `random_bytes(32)`).
$binary	bool	false	Gibt `true` zurück den rohen Binär-Hash, bei `false` (Standard) wird eine hexadezimale Zeichenkette in Kleinbuchstaben zurückgegeben.

Rückgabewert

Typ

string|false

Beschreibung

Bei Erfolg die HMAC-Prüfsumme als hexadezimale Zeichenkette (oder als Binärstring, wenn $binary = true). Gibt false zurück, wenn die Datei nicht gelesen werden kann oder der Algorithmus unbekannt ist.

Beispiele

Integrität einer heruntergeladenen Datei prüfen

<?php
$secretKey = 'mein-sehr-geheimer-schluessel-abc123';
$datei     = '/var/uploads/paket.tar.gz';

// HMAC beim Speichern berechnen und ablegen
$gespeicherterHmac = hash_hmac_file('sha256', $datei, $secretKey);
file_put_contents('/var/uploads/paket.tar.gz.hmac', $gespeicherterHmac);

// Später: Integrität prüfen
$aktuellerHmac = hash_hmac_file('sha256', $datei, $secretKey);
$erwartetHmac  = file_get_contents('/var/uploads/paket.tar.gz.hmac');

if (hash_equals($erwartetHmac, $aktuellerHmac)) {
    echo 'Datei ist unverändert und authentisch.';
} else {
    echo 'WARNUNG: Datei wurde manipuliert!';
}

Datei ist unverändert und authentisch.

HMAC als Binärwert und Base64-Kodierung

<?php
$key      = random_bytes(32); // Zufälliger 256-Bit-Schlüssel
$datei    = '/tmp/bericht.pdf';

// Binären HMAC berechnen und Base64-kodieren
$hmacBin    = hash_hmac_file('sha512', $datei, $key, true);
$hmacBase64 = base64_encode($hmacBin);

echo 'HMAC (Base64): ' . $hmacBase64 . PHP_EOL;
echo 'Länge (Bytes): ' . strlen($hmacBin) . PHP_EOL;

HMAC (Base64): <Base64-kodierter 512-Bit-HMAC> Länge (Bytes): 64

Verfügbare HMAC-Algorithmen auflisten

<?php
// Alle unterstützten Algorithmen anzeigen
$algos = hash_hmac_algos();
echo implode(', ', array_slice($algos, 0, 8)) . ' ...';

// Praxis: Nur sichere Algorithmen verwenden
$sichereAlgos = array_filter($algos, fn($a) => str_starts_with($a, 'sha') && !str_contains($a, 'sha1'));
echo PHP_EOL . count($sichereAlgos) . ' als sicher geltende Algorithmen verfügbar.';

md2, md4, md5, sha1, sha224, sha256, sha384, sha512/224 ... 22 als sicher geltende Algorithmen verfügbar.

// Wichtig · Fallstricke

Timing-Angriffe: Vergleichen Sie HMAC-Werte niemals mit === oder ==. Verwenden Sie immer hash_equals(), da es eine konstante Laufzeit garantiert und damit Timing-basierte Seitenkanal-Angriffe verhindert.

Schlüssellänge: Ein zu kurzer oder schwacher Schlüssel schwächt den HMAC erheblich. Nutzen Sie random_bytes(32) oder mehr für kryptografisch sichere Schlüssel.

Algorithmuswahl: MD5 und SHA-1 gelten als kollisionsanfällig und sollten für neue Implementierungen nicht mehr verwendet werden. Empfohlen sind SHA-256, SHA-384, SHA-512 oder Algorithmen der SHA-3-Familie.

Dateizugriff: Wenn der angegebene Dateipfad nicht existiert oder nicht lesbar ist, gibt die Funktion false zurück. Prüfen Sie daher den Rückgabewert, bevor Sie ihn weiterverarbeiten.

Siehe auch

hash_hmac hash_file hash_equals hash_hmac_algos random_bytes hash