sodium_add — Funktion · PHP-Referenz

Signatur

sodium_add(string &$val, string $addv): void

Beschreibung

sodium_add ist Teil der Libsodium-Erweiterung und ermöglicht die Addition zweier beliebig langer, vorzeichenloser Ganzzahlen, die im Little-Endian-Binärformat kodiert sind. Das Ergebnis wird direkt in den ersten Parameter ($val) zurückgeschrieben (In-Place-Operation).

Diese Funktion wird typischerweise im kryptografischen Kontext verwendet, wenn Nonces (Number Used Once) inkrementiert werden müssen, ohne dabei auf herkömmliche PHP-Integer-Arithmetik angewiesen zu sein, die auf 64-Bit-Systemen begrenzt ist. Gerade bei Nonces für symmetrische Verschlüsselung (z. B. mit sodium_crypto_secretbox) ist eine zuverlässige, konstant-zeitliche Inkrementierung essentiell.

Beide Parameter müssen exakt gleich lang sein, da die Länge der Binärstrings die Wortbreite der Addition bestimmt. Eine unterschiedliche Länge führt zu einem SodiumException-Fehler. Die Berechnung erfolgt modular (Überlauf wird ignoriert), was dem üblichen Verhalten bei Ganzzahl-Arithmetik mit fester Breite entspricht.

Im Gegensatz zu sodium_increment, das eine Zahl nur um 1 erhöht, erlaubt sodium_add das Hinzuzählen eines beliebigen Wertes, was bei bestimmten kryptografischen Protokollen notwendig sein kann.

Parameter

Name	Typ	Default	Beschreibung
$val Pflicht	string		Eine vorzeichenlose Ganzzahl im Little-Endian-Binärformat, übergeben als Referenz. Nach dem Aufruf enthält dieser Parameter das Ergebnis der Addition.
$addv Pflicht	string		Die zu addierende vorzeichenlose Ganzzahl im Little-Endian-Binärformat. Muss exakt dieselbe Länge wie `$val` haben.

Rückgabewert

Typ

void

Beschreibung

Die Funktion gibt keinen Wert zurück. Das Ergebnis der Addition wird direkt in $val gespeichert.

Beispiele

Nonce um einen beliebigen Wert erhöhen

<?php
// Nonce für sodium_crypto_secretbox erzeugen
$nonce = random_bytes(SODIUM_CRYPTO_SECRETBOX_NONCEBYTES);

// Addend: den Wert 5 als Little-Endian-Binärstring gleicher Länge kodieren
$addend = str_pad("\x05", SODIUM_CRYPTO_SECRETBOX_NONCEBYTES, "\x00");

echo 'Nonce vorher (hex): ' . bin2hex($nonce) . PHP_EOL;

sodium_add($nonce, $addend);

echo 'Nonce nachher (hex): ' . bin2hex($nonce) . PHP_EOL;

Nonce vorher (hex): (zufälliger Hex-String, 48 Zeichen) Nonce nachher (hex): (selber String + 5, Little-Endian addiert)

Einfache Addition zweier kleiner Little-Endian-Zahlen

<?php
// Zahl 200 als 4-Byte Little-Endian
$a = pack('V', 200); // \xC8\x00\x00\x00

// Zahl 100 als 4-Byte Little-Endian
$b = pack('V', 100); // \x64\x00\x00\x00

sodium_add($a, $b);

// Ergebnis zurück in eine PHP-Ganzzahl konvertieren
$result = unpack('V', $a)[1];
echo $result . PHP_EOL; // 300

300

// Wichtig · Fallstricke

Gleiche Länge erforderlich: Haben $val und $addv unterschiedliche Längen, wirft die Funktion eine SodiumException. Stellen Sie immer sicher, dass beide Strings gleich lang sind, etwa durch str_pad.

Überlaufverhalten: Die Addition ist modular — bei einem Überlauf wird das Ergebnis einfach abgeschnitten (Wrap-around), ähnlich wie bei Ganzzahl-Arithmetik mit fester Bitbreite. Dies ist im Nonce-Kontext gewollt.

Konstant-Zeit-Garantie: Die Libsodium-Implementierung ist darauf ausgelegt, in konstanter Zeit zu laufen, um Timing-Angriffe zu vermeiden — ein wichtiger Vorteil gegenüber eigener PHP-Implementierungen.

Kein Vorzeichen: Beide Operanden werden als vorzeichenlose Ganzzahlen behandelt. Negative Werte lassen sich nicht direkt darstellen.

Siehe auch

sodium_increment sodium_crypto_secretbox sodium_compare sodium_memcmp random_bytes