Signatur
Beschreibung
sodium_increment erhöht eine als Binärstring kodierte, große Zahl (im Little-Endian-Format) um den Wert 1. Die Funktion verändert den übergebenen String direkt (In-Place) und gibt keinen Wert zurück. Sie ist besonders nützlich im kryptografischen Kontext, beispielsweise für das sichere Hochzählen von Nonces (Number used once), die bei symmetrischer Verschlüsselung eingesetzt werden.
Ein typischer Anwendungsfall ist das sequentielle Erhöhen eines Nonce-Wertes bei der Verwendung von sodium_crypto_secretbox oder sodium_crypto_aead_*-Funktionen. Anstatt für jede Verschlüsselung einen neuen zufälligen Nonce zu generieren, kann ein Startnonce zufällig gewählt und anschließend für jede weitere Nachricht inkrementiert werden.
Die Funktion arbeitet mit Strings beliebiger Länge und behandelt korrekt Überträge (Carry), sodass auch ein Überlauf am Ende des Strings korrekt behandelt wird. Das Format ist Little-Endian, d. h. das niederwertigste Byte steht am Anfang des Strings – dies entspricht dem internen Format der libsodium-Bibliothek.
Parameter
| Name | Typ | Default | Beschreibung |
|---|---|---|---|
| $string Pflicht | string | Eine Referenz auf den Binärstring, der die große Zahl im Little-Endian-Format repräsentiert. Der String wird direkt verändert. Typischerweise handelt es sich um einen Nonce der passenden Länge (z. B. SODIUM_CRYPTO_SECRETBOX_NONCEBYTES). |
Rückgabewert
Beispiele
Nonce für aufeinanderfolgende Nachrichten inkrementieren
<?php
// Zufälligen Start-Nonce generieren
$nonce = random_bytes(SODIUM_CRYPTO_SECRETBOX_NONCEBYTES);
$key = sodium_crypto_secretbox_keygen();
$nachrichten = ['Nachricht 1', 'Nachricht 2', 'Nachricht 3'];
$verschluesselt = [];
foreach ($nachrichten as $nachricht) {
$verschluesselt[] = sodium_crypto_secretbox($nachricht, $nonce, $key);
// Nonce für die nächste Nachricht erhöhen
sodium_increment($nonce);
}
echo count($verschluesselt) . ' Nachrichten verschlüsselt.' . PHP_EOL;
// Entschlüsselung: Nonce zurücksetzen und erneut hochzählen
$nonce = random_bytes(SODIUM_CRYPTO_SECRETBOX_NONCEBYTES); // In der Praxis: denselben Startnonce verwenden!
// ...Verhalten des Inkrements und Übertrag demonstrieren
<?php
// Einen 4-Byte Little-Endian-String mit Wert 255 (0xFF 0x00 0x00 0x00) erstellen
$zahl = "\xFF\x00\x00\x00";
sodium_increment($zahl);
// Erwartet: 0x00 0x01 0x00 0x00 (= 256 in Little-Endian)
echo bin2hex($zahl) . PHP_EOL; // 00010000
// Überlauf über alle Bytes (Wert 0xFFFFFFFF = 4294967295)
$zahl = "\xFF\xFF\xFF\xFF";
sodium_increment($zahl);
// Erwartet: 0x00 0x00 0x00 0x00 (Überlauf zurück auf 0)
echo bin2hex($zahl) . PHP_EOL; // 00000000// Wichtig · Fallstricke
Nonce-Wiederverwendung vermeiden: Wird bei symmetrischer Verschlüsselung derselbe Nonce mit demselben Schlüssel zweimal verwendet, ist die Sicherheit der Verschlüsselung kompromittiert. Stellen Sie sicher, dass der Startnonce zufällig und der inkrementierte Nonce für jede Nachricht synchron zwischen Sender und Empfänger gehalten wird.
Little-Endian-Format: Der String muss im Little-Endian-Format vorliegen. Dies entspricht dem Standard aller libsodium-Nonce-Werte. Werden Nonces anderer Herkunft (z. B. Big-Endian) verwendet, muss das Format vorher angepasst werden.
Persistenz des Nonce: Bei der Kommunikation über mehrere Sitzungen hinweg muss der aktuelle Nonce-Stand sicher gespeichert werden, damit der Empfänger die Nachrichten korrekt entschlüsseln kann.