sodium_crypto_aead_chacha20poly1305_decrypt — Funktion · PHP-Referenz

Signatur

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

Beschreibung

Diese Funktion implementiert das AEAD-Verfahren (Authenticated Encryption with Associated Data) auf Basis von ChaCha20-Poly1305. Sie überprüft zunächst den Poly1305-Authentifizierungs-Tag des Chiffretexts – zusammen mit optionalen zusätzlichen Daten (additional_data) – und entschlüsselt die Nachricht anschließend mit ChaCha20. Schlägt die Verifikation fehl, gibt die Funktion false zurück, ohne die Nachricht zu entschlüsseln.

Der Parameter additional_data wird nicht verschlüsselt, aber in die MAC-Berechnung einbezogen. Dadurch lassen sich Metadaten (z. B. Protokollversion, Empfänger-ID) fälschungssicher an die Nachricht binden, ohne sie im Chiffretext zu verstecken.

ChaCha20-Poly1305 eignet sich besonders für Umgebungen ohne Hardware-AES-Unterstützung (z. B. eingebettete Systeme, ältere Mobilgeräte), da es auf reiner Software-Basis sehr effizient und sicher ist. Für 64-Bit-Systeme mit langen Nachrichten steht die erweiterte Variante sodium_crypto_aead_xchacha20poly1305_ietf_decrypt mit größerem Nonce-Raum zur Verfügung.

Nonce und Schlüssel müssen exakt die vorgeschriebene Länge haben (SODIUM_CRYPTO_AEAD_CHACHA20POLY1305_NPUBBYTES bzw. SODIUM_CRYPTO_AEAD_CHACHA20POLY1305_KEYBYTES). Der Nonce darf niemals für denselben Schlüssel wiederverwendet werden.

Parameter

Name	Typ	Beschreibung
$ciphertext Pflicht	string	Der zu entschlüsselnde Chiffretext, wie er von `sodium_crypto_aead_chacha20poly1305_encrypt` erzeugt wurde. Enthält den verschlüsselten Klartext sowie den angehängten 16-Byte-Poly1305-Tag.
$additional_data Pflicht	string	Zusätzliche authentifizierte, aber nicht verschlüsselte Daten (z. B. Header oder Metadaten). Muss exakt mit dem Wert übereinstimmen, der beim Verschlüsseln verwendet wurde. Kann ein leerer String sein.
$nonce Pflicht	string	Einmalig verwendete Zufallszahl (Number used Once) der Länge `SODIUM_CRYPTO_AEAD_CHACHA20POLY1305_NPUBBYTES` (8 Byte). Muss identisch mit dem beim Verschlüsseln genutzten Nonce sein und darf pro Schlüssel nur einmal verwendet werden.
$key Pflicht	string	Der geheime Schlüssel der Länge `SODIUM_CRYPTO_AEAD_CHACHA20POLY1305_KEYBYTES` (32 Byte). Sollte mit `sodium_crypto_aead_chacha20poly1305_keygen` erzeugt werden.

Rückgabewert

Typ

string|false

Beschreibung

Gibt den entschlüsselten Klartext als string zurück, wenn Authentifizierung und Entschlüsselung erfolgreich waren. Gibt false zurück, wenn die Authentifizierungsprüfung fehlschlägt (z. B. bei Manipulation des Chiffretexts, falschen zusätzlichen Daten oder falschem Schlüssel).

Beispiele

Einfaches Ver- und Entschlüsseln einer Nachricht

<?php
// Schlüssel und Nonce generieren
$key   = sodium_crypto_aead_chacha20poly1305_keygen();
$nonce = random_bytes(SODIUM_CRYPTO_AEAD_CHACHA20POLY1305_NPUBBYTES);

$plaintext       = 'Geheime Nachricht';
$additional_data = 'v1';

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

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

if ($decrypted === false) {
    echo 'Authentifizierung fehlgeschlagen!';
} else {
    echo $decrypted;
}

Geheime Nachricht

Erkennung von Manipulation am Chiffretext

<?php
$key   = sodium_crypto_aead_chacha20poly1305_keygen();
$nonce = random_bytes(SODIUM_CRYPTO_AEAD_CHACHA20POLY1305_NPUBBYTES);

$ciphertext = sodium_crypto_aead_chacha20poly1305_encrypt(
    'Wichtige Daten',
    'header',
    $nonce,
    $key
);

// Manipuliere den Chiffretext (1 Byte ändern)
$tampered = $ciphertext;
$tampered[0] = chr(ord($tampered[0]) ^ 0xFF);

$result = sodium_crypto_aead_chacha20poly1305_decrypt(
    $tampered,
    'header',
    $nonce,
    $key
);

var_dump($result);

bool(false)

// Wichtig · Fallstricke

Nonce-Wiederverwendung ist katastrophal: Wird derselbe Nonce mit demselben Schlüssel für zwei verschiedene Nachrichten verwendet, kann ein Angreifer den Klartext beider Nachrichten rekonstruieren. Verwende stets random_bytes(SODIUM_CRYPTO_AEAD_CHACHA20POLY1305_NPUBBYTES) oder einen sicher inkrementierten Zähler.

Rückgabewert prüfen: Der Rückgabewert false darf nicht ignoriert werden. Verarbeite die entschlüsselten Daten ausschließlich nach erfolgreicher Verifikation.

Nonce-Größe: Der 8-Byte-Nonce dieser Variante ist für zufällige Nonces bei großen Nachrichtenmengen riskant (Geburtstagsparadoxon). Für solche Szenarien empfiehlt sich die IETF-Variante sodium_crypto_aead_chacha20poly1305_ietf_decrypt mit 12-Byte-Nonce oder sodium_crypto_aead_xchacha20poly1305_ietf_decrypt mit 24-Byte-Nonce.

Die Funktion wirft eine SodiumException, wenn Nonce oder Schlüssel nicht die exakt geforderte Länge haben.

Siehe auch

sodium_crypto_aead_chacha20poly1305_encrypt sodium_crypto_aead_chacha20poly1305_keygen sodium_crypto_aead_chacha20poly1305_ietf_decrypt sodium_crypto_aead_xchacha20poly1305_ietf_decrypt sodium_crypto_secretbox_open