sodium_crypto_aead_xchacha20poly1305_ietf_decrypt — Funktion · PHP-Referenz

Signatur

sodium_crypto_aead_xchacha20poly1305_ietf_decrypt(string $ciphertext, string $additional_data, string $nonce, string $key): string|false

Beschreibung

sodium_crypto_aead_xchacha20poly1305_ietf_decrypt gehört zur AEAD-Familie (Authenticated Encryption with Associated Data) und kombiniert die Stromverschlüsselung XChaCha20 mit dem Authentifizierungs-MAC Poly1305. Die Funktion verifiziert zunächst den Authentifizierungs-Tag des Chiffretexts und entschlüsselt den Nachrichteninhalt nur, wenn die Prüfung erfolgreich war. Schlägt die Verifikation fehl, wird false zurückgegeben, ohne dass eine teilweise Nachricht preisgegeben wird.

Gegenüber dem regulären chacha20poly1305_ietf-Variant verwendet XChaCha20 einen 192-Bit-Nonce (24 Byte) statt 96 Bit. Der deutlich größere Nonce-Raum macht es sicher, zufällig generierte Nonces einzusetzen, ohne dass Kollisionen praktisch relevant werden – ein erheblicher Vorteil bei häufig wechselnden Sitzungsschlüsseln oder Massenverschlüsselungen.

Das Argument additional_data ermöglicht es, öffentliche Metadaten (z. B. Header, Empfänger-ID, Timestamp) kryptografisch an den Chiffretext zu binden, ohne sie selbst zu verschlüsseln. Werden die Metadaten manipuliert, schlägt die Entschlüsselung fehl. Wenn keine zusätzlichen Daten benötigt werden, kann ein leerer String '' übergeben werden.

Diese Funktion ist für alle Anwendungsfälle empfohlen, bei denen symmetrische authentifizierte Verschlüsselung benötigt wird und der nonce-Raum ausreichend groß sein soll, um eine zufällige Nonce-Generierung (via random_bytes) sicher zu machen.

Parameter

Name	Typ	Beschreibung
$ciphertext Pflicht	string	Der zu entschlüsselnde Chiffretext inklusive des angehängten Poly1305-Authentifizierungs-Tags (mindestens `SODIUM_CRYPTO_AEAD_XCHACHA20POLY1305_IETF_ABYTES` Byte lang).
$additional_data Pflicht	string	Öffentliche Zusatzdaten, die bei der Verschlüsselung mitauthentifiziert wurden. Muss exakt mit dem Wert übereinstimmen, der beim Verschlüsseln übergeben wurde. Leerer String `''` ist zulässig.
$nonce Pflicht	string	Der Nonce, der bei der Verschlüsselung verwendet wurde. Muss exakt `SODIUM_CRYPTO_AEAD_XCHACHA20POLY1305_IETF_NPUBBYTES` (24) Byte lang sein. Darf niemals für denselben Schlüssel wiederverwendet werden.
$key Pflicht	string	Der geheime Schlüssel. Muss exakt `SODIUM_CRYPTO_AEAD_XCHACHA20POLY1305_IETF_KEYBYTES` (32) Byte lang sein. Idealerweise mit `sodium_crypto_aead_xchacha20poly1305_ietf_keygen()` erzeugt.

Rückgabewert

Typ

string|false

Beschreibung

Gibt bei erfolgreicher Verifikation und Entschlüsselung den Klartext als string zurück. Falls die Authentifizierung fehlschlägt (Manipulation am Chiffretext, falscher Schlüssel, falscher Nonce oder falsche Zusatzdaten), wird false zurückgegeben.

Beispiele

Nachricht verschlüsseln und wieder entschlüsseln

<?php
// Schlüssel und Nonce erzeugen
$key   = sodium_crypto_aead_xchacha20poly1305_ietf_keygen();
$nonce = random_bytes(SODIUM_CRYPTO_AEAD_XCHACHA20POLY1305_IETF_NPUBBYTES); // 24 Byte

$plaintext       = 'Geheime Nachricht';
$additional_data = 'user_id=42;version=1';

// Verschlüsseln
$ciphertext = sodium_crypto_aead_xchacha20poly1305_ietf_encrypt(
    $plaintext,
    $additional_data,
    $nonce,
    $key
);

// Entschlüsseln
$decrypted = sodium_crypto_aead_xchacha20poly1305_ietf_decrypt(
    $ciphertext,
    $additional_data,
    $nonce,
    $key
);

if ($decrypted === false) {
    throw new RuntimeException('Entschlüsselung fehlgeschlagen – Nachricht manipuliert?');
}

echo $decrypted;

Geheime Nachricht

Erkennung von Manipulationen an den Zusatzdaten

<?php
$key   = sodium_crypto_aead_xchacha20poly1305_ietf_keygen();
$nonce = random_bytes(SODIUM_CRYPTO_AEAD_XCHACHA20POLY1305_IETF_NPUBBYTES);

$plaintext       = 'Wichtige Daten';
$additional_data = 'role=user';

$ciphertext = sodium_crypto_aead_xchacha20poly1305_ietf_encrypt(
    $plaintext,
    $additional_data,
    $nonce,
    $key
);

// Angreifer versucht, die Rolle zu ändern
$tampered_ad = 'role=admin';

$result = sodium_crypto_aead_xchacha20poly1305_ietf_decrypt(
    $ciphertext,
    $tampered_ad, // manipulierte Zusatzdaten
    $nonce,
    $key
);

var_dump($result); // Authentifizierung schlägt fehl

bool(false)

// Wichtig · Fallstricke

Nonce-Wiederverwendung: Der gleiche Nonce darf unter demselben Schlüssel niemals zweimal verwendet werden. Bei XChaCha20 mit 24-Byte-Nonce ist es sicher, den Nonce zufällig mit random_bytes(24) zu erzeugen, da die Wahrscheinlichkeit einer Kollision selbst bei Millionen von Nachrichten vernachlässigbar gering ist.

Rückgabewert prüfen: Der Rückgabewert muss zwingend auf false geprüft werden. Wird eine manipulierte Nachricht ohne diese Prüfung weiterverarbeitet, entsteht eine kritische Sicherheitslücke. Verwende niemals !$result, da ein leerer Klartext-String ebenfalls falsy ist – prüfe stattdessen mit === false.

Schlüsselverwaltung: Der Schlüssel muss geheim bleiben und sollte niemals zusammen mit Chiffretext und Nonce übertragen werden. Nonce und Chiffretext können öffentlich gespeichert oder übertragen werden.

Speicher bereinigen: Nach der Verwendung sollte der Schlüssel mit sodium_memzero($key) aus dem Speicher gelöscht werden, um Seitenkanal-Angriffe zu erschweren.

Siehe auch

sodium_crypto_aead_xchacha20poly1305_ietf_encrypt sodium_crypto_aead_xchacha20poly1305_ietf_keygen sodium_crypto_aead_chacha20poly1305_ietf_decrypt sodium_crypto_secretbox_open sodium_memzero random_bytes