sodium_crypto_secretstream_xchacha20poly1305_init_push — Funktion · PHP-Referenz

Signatur

sodium_crypto_secretstream_xchacha20poly1305_init_push(string $key): array

Beschreibung

Diese Funktion erzeugt einen neuen Push-Kontext für die libsodium-Secretstream-API. Ein Secretstream erlaubt die sichere, authentifizierte Verschlüsselung einer beliebig langen Folge von Nachrichten (Chunks), die in einer festgelegten Reihenfolge stehen. Der Algorithmus XChaCha20-Poly1305 gewährleistet dabei sowohl Vertraulichkeit als auch Integrität jeder einzelnen Nachricht.

Die Funktion gibt ein Array zurück, das zwei Elemente enthält: den internen Zustandskontext (state) sowie einen zufällig generierten Header (header). Der Header muss vor dem ersten verschlüsselten Chunk an die Gegenseite (den Pull-Kontext) übertragen werden, damit dieser den Datenstrom korrekt initialisieren kann. Der Header ist nicht geheim und kann im Klartext übertragen werden.

Der Push-Kontext wird anschließend mit sodium_crypto_secretstream_xchacha20poly1305_push() verwendet, um einzelne Datenpakete zu verschlüsseln. Jedes Paket kann optional mit einem Tag versehen werden, das z. B. das Ende des Streams signalisiert (SODIUM_CRYPTO_SECRETSTREAM_XCHACHA20POLY1305_TAG_FINAL). Diese API eignet sich hervorragend für verschlüsselte Dateiübertragungen, TLS-ähnliche Protokolle oder jede Situation, in der Daten in geordneten Blöcken übertragen werden sollen.

Als Schlüssel muss ein Zufallsschlüssel der korrekten Länge verwendet werden, der mit sodium_crypto_secretstream_xchacha20poly1305_keygen() erzeugt werden kann. Sender und Empfänger müssen denselben Schlüssel kennen – er sollte niemals über einen unsicheren Kanal übertragen werden.

Parameter

Name	Typ	Default	Beschreibung
$key Pflicht	string		Der symmetrische Geheimschlüssel mit einer Länge von genau `SODIUM_CRYPTO_SECRETSTREAM_XCHACHA20POLY1305_KEYBYTES` Bytes (32 Bytes). Kann mit `sodium_crypto_secretstream_xchacha20poly1305_keygen()` sicher erzeugt werden.

Rückgabewert

Typ

array

Beschreibung

Gibt ein Array mit zwei Elementen zurück:

[0] (state): Der interne Zustandskontext, der bei jedem nachfolgenden Aufruf von sodium_crypto_secretstream_xchacha20poly1305_push() übergeben werden muss.
[1] (header): Ein zufällig generierter Header (Byte-String der Länge SODIUM_CRYPTO_SECRETSTREAM_XCHACHA20POLY1305_HEADERBYTES), der an die Empfängerseite übermittelt werden muss, bevor der erste verschlüsselte Chunk gesendet wird.

Beispiele

Einfache Stream-Verschlüsselung mit Push und Pull

<?php
// Schlüssel generieren (nur einmal erzeugen, sicher speichern/teilen)
$key = sodium_crypto_secretstream_xchacha20poly1305_keygen();

// === SENDER-SEITE ===
[$pushState, $header] = sodium_crypto_secretstream_xchacha20poly1305_init_push($key);

$chunk1 = sodium_crypto_secretstream_xchacha20poly1305_push(
    $pushState,
    'Hallo, das ist Nachricht 1!'
);
$chunk2 = sodium_crypto_secretstream_xchacha20poly1305_push(
    $pushState,
    'Das ist die letzte Nachricht.',
    '',
    SODIUM_CRYPTO_SECRETSTREAM_XCHACHA20POLY1305_TAG_FINAL
);

// $header, $chunk1 und $chunk2 werden übertragen ...

// === EMPFÄNGER-SEITE ===
$pullState = sodium_crypto_secretstream_xchacha20poly1305_init_pull($key, $header);

[$msg1, $tag1] = sodium_crypto_secretstream_xchacha20poly1305_pull($pullState, $chunk1);
[$msg2, $tag2] = sodium_crypto_secretstream_xchacha20poly1305_pull($pullState, $chunk2);

echo $msg1 . PHP_EOL;
echo $msg2 . PHP_EOL;
echo ($tag2 === SODIUM_CRYPTO_SECRETSTREAM_XCHACHA20POLY1305_TAG_FINAL ? 'Stream beendet.' : '') . PHP_EOL;

Hallo, das ist Nachricht 1! Das ist die letzte Nachricht. Stream beendet.

Datei-Chunk-Verschlüsselung mit Fortschrittsanzeige

<?php
$key = sodium_crypto_secretstream_xchacha20poly1305_keygen();
$chunkSize = 4096;

// Quelldatei öffnen (simuliert durch einen String)
$plaintext = str_repeat('A', 10000);
$inputLength = strlen($plaintext);
$offset = 0;
$encryptedChunks = [];

// Push-Kontext initialisieren
[$state, $header] = sodium_crypto_secretstream_xchacha20poly1305_init_push($key);

while ($offset < $inputLength) {
    $chunk = substr($plaintext, $offset, $chunkSize);
    $offset += $chunkSize;
    $isLast = ($offset >= $inputLength);

    $tag = $isLast
        ? SODIUM_CRYPTO_SECRETSTREAM_XCHACHA20POLY1305_TAG_FINAL
        : SODIUM_CRYPTO_SECRETSTREAM_XCHACHA20POLY1305_TAG_MESSAGE;

    $encryptedChunks[] = sodium_crypto_secretstream_xchacha20poly1305_push($state, $chunk, '', $tag);
}

echo 'Anzahl verschlüsselter Chunks: ' . count($encryptedChunks) . PHP_EOL;
echo 'Header-Länge: ' . strlen($header) . ' Bytes' . PHP_EOL;

Anzahl verschlüsselter Chunks: 3 Header-Länge: 24 Bytes

// Wichtig · Fallstricke

Sicherheitshinweise:

Der Schlüssel muss geheim gehalten werden. Verwende ausschließlich sodium_crypto_secretstream_xchacha20poly1305_keygen() zur Schlüsselerzeugung, nie selbst generierte Strings.
Der Header ist nicht geheim und kann im Klartext übertragen werden, jedoch darf er nicht manipuliert werden – andernfalls schlägt die Initialisierung auf der Pull-Seite fehl.
Der interne Zustandskontext (state) darf nicht wiederverwendet werden. Jede neue Verschlüsselungssession benötigt einen frischen Push-Kontext mit neuem Header.
Wird ein falscher oder manipulierter Chunk auf der Pull-Seite entschlüsselt, gibt sodium_crypto_secretstream_xchacha20poly1305_pull() false zurück – prüfe diesen Rückgabewert immer.
Die Funktion wirft eine SodiumException, wenn der Schlüssel die falsche Länge hat.

Siehe auch

sodium_crypto_secretstream_xchacha20poly1305_push sodium_crypto_secretstream_xchacha20poly1305_init_pull sodium_crypto_secretstream_xchacha20poly1305_pull sodium_crypto_secretstream_xchacha20poly1305_keygen