sodium_memcmp — Funktion · PHP-Referenz

Signatur

sodium_memcmp(string $string1, string $string2): int

Beschreibung

sodium_memcmp vergleicht zwei Byte-Strings auf Gleichheit, ohne dabei die Laufzeit vom Vergleichsergebnis abhängig zu machen. Im Gegensatz zu strcmp oder dem ===-Operator, die bei der ersten Abweichung abbrechen können, läuft dieser Vergleich immer gleich lang – unabhängig davon, an welcher Stelle sich die Strings unterscheiden.

Diese Eigenschaft ist essenziell bei der Überprüfung kryptografischer Werte wie HMAC-Signaturen, Tokens oder Message-Authentication-Codes (MACs). Ein Angreifer könnte andernfalls anhand von Laufzeitunterschieden zeichenweise erraten, wie ein gültiger Wert aussieht (Timing-Angriff).

Die Funktion gibt 0 zurück, wenn beide Strings identisch sind, und einen anderen Integer-Wert, wenn sie sich unterscheiden. Wichtig: Anders als bei strcmp liefert ein Nicht-Null-Rückgabewert keine Aussage über die lexikografische Reihenfolge.

Für sicherheitskritische Vergleiche, z. B. beim Prüfen von API-Schlüsseln, CSRF-Tokens oder kryptografischen MACs, sollte immer sodium_memcmp oder hash_equals verwendet werden.

Parameter

Name	Typ	Default	Beschreibung
$string1 Pflicht	string		Der erste zu vergleichende Byte-String.
$string2 Pflicht	string		Der zweite zu vergleichende Byte-String. Beide Strings müssen dieselbe Länge haben, andernfalls wird eine `SodiumException` ausgelöst.

Rückgabewert

Typ

int

Beschreibung

Gibt 0 zurück, wenn beide Strings identisch sind. Gibt einen Wert ungleich 0 zurück, wenn sie sich unterscheiden. Der genaue Rückgabewert bei Ungleichheit hat keine semantische Bedeutung bezüglich Reihenfolge oder Position des Unterschieds.

Beispiele

HMAC-Signatur sicher vergleichen

<?php
$secret = 'mein-geheimer-schluessel';
$message = 'wichtige-nachricht';

// Erwartete Signatur berechnen
$expected = hash_hmac('sha256', $message, $secret, true);

// Empfangene Signatur (z. B. aus HTTP-Header)
$received = hash_hmac('sha256', $message, $secret, true);

// Sicherer Vergleich in konstanter Zeit
if (sodium_memcmp($expected, $received) === 0) {
    echo 'Signatur gültig.';
} else {
    echo 'Signatur ungültig!';
}

Signatur gültig.

Verhalten bei unterschiedlichen Strings

<?php
$a = 'korrekt123';
$b = 'falsch1234';

// Beide müssen gleich lang sein!
$result = sodium_memcmp($a, $b);

if ($result === 0) {
    echo 'Gleich';
} else {
    echo 'Unterschiedlich (Rückgabe: ' . $result . ')';
}

Unterschiedlich (Rückgabe: -1)

Längenunterschiede lösen eine Exception aus

<?php
try {
    $result = sodium_memcmp('kurz', 'viel-laenger');
} catch (SodiumException $e) {
    echo 'Fehler: ' . $e->getMessage();
}

Fehler: sodium_memcmp(): Argument #1 ($string1) and argument #2 ($string2) must have the same length

// Wichtig · Fallstricke

Sicherheitshinweis: sodium_memcmp schützt nur vor Timing-Angriffen. Es ersetzt nicht eine sichere Schlüsselverwaltung oder kryptografisch sichere Signaturverfahren. Der Vergleich selbst ist zwar zeitkonstant, aber wenn die zu vergleichenden Werte unsicher erzeugt wurden, nützt das nichts.

Längenpflicht: Beide Strings müssen exakt dieselbe Länge haben, sonst wirft die Funktion eine SodiumException. Das ist ein bewusstes Design: Längenunterschiede könnten selbst eine Informationsleckage darstellen, daher müssen Aufrufer sicherstellen, dass beide Seiten dieselbe Länge haben.

Als Alternative steht hash_equals zur Verfügung, das ebenfalls zeitkonstant arbeitet und auch Strings unterschiedlicher Länge akzeptiert (gibt dann einfach false zurück). Für rein kryptografische Kontexte ist sodium_memcmp die empfohlene Wahl.

Siehe auch

hash_equals sodium_crypto_auth_verify sodium_crypto_secretbox_open hash_hmac