sodium_crypto_auth — Funktion · PHP-Referenz

Signatur

sodium_crypto_auth(string $message, string $key): string

Beschreibung

sodium_crypto_auth erzeugt einen Message Authentication Code (MAC) für eine gegebene Nachricht. Der MAC dient dazu, sicherzustellen, dass eine Nachricht von einem berechtigten Absender stammt und unterwegs nicht manipuliert wurde. Es handelt sich dabei um eine symmetrische Operation: Sowohl Sender als auch Empfänger müssen denselben geheimen Schlüssel kennen.

Intern verwendet die Funktion HMAC-SHA512256 (einen auf SHA-512/256 basierenden HMAC), der Teil der NaCl/libsodium-Bibliothek ist. Das Verfahren ist nicht-deterministisch in Bezug auf Geheimnisse, aber deterministisch für gleiche Eingaben – d. h. dieselbe Nachricht mit demselben Schlüssel ergibt immer denselben Tag.

Der berechnete Tag kann anschließend mit sodium_crypto_auth_verify überprüft werden. Der Vergleich sollte stets über diese Funktion erfolgen, da sie einen zeitkonstanten Vergleich durchführt und damit Timing-Angriffe verhindert. Dieses Verfahren eignet sich besonders für API-Signaturen, Integritätsprüfungen von Daten oder Tokens zwischen vertrauenden Parteien.

Für die Verschlüsselung von Nachrichten ist diese Funktion nicht geeignet – sie stellt lediglich Authentizität und Integrität sicher, nicht Vertraulichkeit. Für Vertraulichkeit sollte sodium_crypto_secretbox verwendet werden.

Parameter

Name	Typ	Default	Beschreibung
$message Pflicht	string		Die Nachricht, für die der Authentifizierungs-Tag berechnet werden soll. Kann beliebige Binärdaten enthalten.
$key Pflicht	string		Der geheime Schlüssel zur Berechnung des MACs. Muss genau `SODIUM_CRYPTO_AUTH_KEYBYTES` (32) Bytes lang sein. Sollte mit `sodium_crypto_auth_keygen()` erzeugt werden.

Rückgabewert

Typ

string

Beschreibung

Gibt den berechneten Authentifizierungs-Tag als binären String zurück. Die Länge beträgt stets SODIUM_CRYPTO_AUTH_BYTES (32 Bytes). Im Fehlerfall (z. B. falsche Schlüssellänge) wird eine SodiumException geworfen.

Beispiele

Nachricht authentifizieren und verifizieren

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

$message = 'Wichtige Nachricht, die integer bleiben muss.';

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

echo 'Tag (hex): ' . bin2hex($tag) . PHP_EOL;

// Nachricht verifizieren
if (sodium_crypto_auth_verify($tag, $message, $key)) {
    echo 'Nachricht ist authentisch und unverändert.' . PHP_EOL;
} else {
    echo 'Ungültiger Tag – Nachricht manipuliert oder falscher Schlüssel!' . PHP_EOL;
}

// Schlüssel aus dem Speicher löschen
sodium_memzero($key);

Tag (hex): <32-Byte-Hex-String> Nachricht ist authentisch und unverändert.

API-Token-Signierung mit gespeichertem Schlüssel

<?php
// Schlüssel aus sicherer Konfiguration laden (z. B. Umgebungsvariable)
$key = sodium_hex2bin(getenv('API_HMAC_KEY'));

$payload = json_encode(['user_id' => 42, 'action' => 'delete', 'ts' => time()]);

// Signatur berechnen und Base64-kodiert übertragen
$signature = base64_encode(sodium_crypto_auth($payload, $key));

echo 'Payload:    ' . $payload . PHP_EOL;
echo 'Signatur:   ' . $signature . PHP_EOL;

// Auf Empfängerseite verifizieren
$receivedTag = base64_decode($signature);
if (sodium_crypto_auth_verify($receivedTag, $payload, $key)) {
    echo 'API-Anfrage verifiziert.' . PHP_EOL;
} else {
    http_response_code(403);
    echo 'Ungültige Signatur.' . PHP_EOL;
}

sodium_memzero($key);

Payload: {"user_id":42,"action":"delete","ts":...} Signatur: <Base64-String> API-Anfrage verifiziert.

// Wichtig · Fallstricke

Schlüssellänge: Der Schlüssel muss exakt SODIUM_CRYPTO_AUTH_KEYBYTES (32 Bytes) lang sein. Eine abweichende Länge führt zu einer SodiumException. Verwende grundsätzlich sodium_crypto_auth_keygen() zur Schlüsselerzeugung statt eigener Zufallsgeneratoren.

Kein Ersatz für Verschlüsselung: Der MAC schützt nur Integrität und Authentizität, nicht die Vertraulichkeit. Die Nachricht selbst wird im Klartext übertragen. Soll der Inhalt geheim bleiben, muss zusätzlich verschlüsselt werden.

Zeitsicherer Vergleich: Den MAC niemals mit === oder strcmp vergleichen – das öffnet Timing-Angriffe. Stets sodium_crypto_auth_verify() verwenden.

Schlüsselhygiene: Schlüssel nach Verwendung mit sodium_memzero() aus dem Speicher löschen, um sie nicht als Artefakt im Prozess zu hinterlassen.

Siehe auch

sodium_crypto_auth_verify sodium_crypto_auth_keygen sodium_crypto_secretbox sodium_memzero sodium_crypto_generichash