sodium_crypto_auth_verify — Funktion · PHP-Referenz

Signatur

sodium_crypto_auth_verify(string $tag, string $message, string $key): bool

Beschreibung

sodium_crypto_auth_verify() verifiziert einen Message Authentication Code (MAC), der zuvor mit sodium_crypto_auth() für eine Nachricht und einen geheimen Schlüssel erstellt wurde. Die Funktion gibt true zurück, wenn der Tag authentisch ist, andernfalls false.

Intern verwendet die Funktion HMAC-SHA512256, einen auf SHA-512 basierenden Algorithmus, der auf 256 Bit gekürzt wird. Damit kann nachgewiesen werden, dass eine Nachricht von einem Sender stammt, der den geheimen Schlüssel kennt, und dass sie nicht verändert wurde – ohne dabei den Nachrichteninhalt zu verschlüsseln.

Die Verifikation erfolgt zeitkonstant (constant-time comparison), sodass Timing-Angriffe verhindert werden. Es sollte daher niemals eine manuelle Vergleichsoperation (z. B. === oder strcmp()) zum Vergleich von MACs verwendet werden.

Typische Einsatzgebiete sind das Sichern von API-Anfragen, das Prüfen von Datenintegrität bei der Speicherung oder Übertragung sowie überall dort, wo Sender und Empfänger denselben geheimen Schlüssel teilen (symmetrische Authentifizierung).

Parameter

Name	Typ	Beschreibung
$tag Pflicht	string	Der zu prüfende Authentifizierungs-Tag, wie er von `sodium_crypto_auth()` erzeugt wurde. Muss exakt `SODIUM_CRYPTO_AUTH_BYTES` (32) Bytes lang sein.
$message Pflicht	string	Die Originalnachricht, für die der Tag überprüft werden soll. Muss identisch mit der Nachricht sein, die beim Erzeugen des Tags verwendet wurde.
$key Pflicht	string	Der geheime Schlüssel, der beim Erstellen des Tags verwendet wurde. Muss exakt `SODIUM_CRYPTO_AUTH_KEYBYTES` (32) Bytes lang sein. Erzeugt wird er z. B. mit `sodium_crypto_auth_keygen()`.

Rückgabewert

Typ

bool

Beschreibung

Gibt true zurück, wenn der Tag für die angegebene Nachricht und den Schlüssel gültig ist, andernfalls false. Bei ungültigen Parametern (z. B. falscher Schlüssellänge) wird eine SodiumException geworfen.

Beispiele

Grundlegendes Erstellen und Verifizieren eines MACs

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

$message = 'Wichtige Nachricht, die nicht verändert werden darf.';

// MAC erstellen
$tag = sodium_crypto_auth($message, $key);

// MAC verifizieren
if (sodium_crypto_auth_verify($tag, $message, $key)) {
    echo 'Nachricht ist authentisch und unverändert.';
} else {
    echo 'WARNUNG: Nachricht wurde verändert oder Tag ist ungültig!';
}

Nachricht ist authentisch und unverändert.

Erkennen einer manipulierten Nachricht

<?php
$key = sodium_crypto_auth_keygen();

$originalMessage = 'Betrag: 100 Euro';
$tag = sodium_crypto_auth($originalMessage, $key);

// Angreifer manipuliert die Nachricht
$manipulatedMessage = 'Betrag: 10000 Euro';

if (sodium_crypto_auth_verify($tag, $manipulatedMessage, $key)) {
    echo 'Nachricht gültig.';
} else {
    echo 'WARNUNG: Nachricht wurde manipuliert – Tag ist ungültig!';
}

WARNUNG: Nachricht wurde manipuliert – Tag ist ungültig!

Sichern einer API-Anfrage mit MAC

<?php
// Schlüssel wird sicher in einer Umgebungsvariablen gespeichert
$key = sodium_base642bin(getenv('API_MAC_KEY'), SODIUM_BASE64_VARIANT_ORIGINAL);

// Empfangene Anfrage (z. B. aus HTTP-Header und Body)
$receivedTag = sodium_base642bin($_SERVER['HTTP_X_MAC'] ?? '', SODIUM_BASE64_VARIANT_ORIGINAL);
$body = file_get_contents('php://input');

if (!sodium_crypto_auth_verify($receivedTag, $body, $key)) {
    http_response_code(403);
    exit('Ungültige Anfrage: MAC-Verifikation fehlgeschlagen.');
}

echo 'Anfrage akzeptiert.';

// Wichtig · Fallstricke

Sicherheitshinweise:

Verwende niemals einen selbst gebauten String-Vergleich (===, strcmp() etc.) zum Vergleichen von MACs – nur zeitkonstante Vergleiche wie die von libsodium intern verwendeten schützen vor Timing-Angriffen.
Der Schlüssel muss geheim bleiben und sollte ausschließlich mit sodium_crypto_auth_keygen() erzeugt werden, um die erforderliche Entropie sicherzustellen.
sodium_crypto_auth/sodium_crypto_auth_verify bieten keine Verschlüsselung – der Nachrichteninhalt ist weiterhin lesbar. Für vertrauliche Nachrichten muss zusätzlich sodium_crypto_secretbox() oder ähnliches verwendet werden.
Bei ungültiger Schlüssellänge wirft die Funktion eine SodiumException, die entsprechend abgefangen werden sollte.

Siehe auch

sodium_crypto_auth sodium_crypto_auth_keygen sodium_crypto_secretbox sodium_crypto_secretbox_open hash_equals