sodium_crypto_aead_chacha20poly1305_ietf_decrypt — Funktion · PHP-Referenz

Signatur

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

Beschreibung

Diese Funktion kombiniert die symmetrische Stromverschlüsselung ChaCha20 mit dem Nachrichtenauthentifizierungscode Poly1305 zu einem AEAD-Verfahren (Authenticated Encryption with Associated Data). Die IETF-Variante verwendet einen 96-Bit-Nonce (12 Byte), was sie kompatibel mit dem in RFC 7539 standardisierten Verfahren macht.

Die Funktion prüft zunächst das im Chiffriertext enthaltene Poly1305-Tag (MAC). Ist das Tag gültig, wird der Klartext entschlüsselt und zurückgegeben. Schlägt die Verifikation fehl, wird false zurückgegeben, ohne den Klartext preiszugeben. So ist sichergestellt, dass manipulierte oder korrumpierte Nachrichten niemals entschlüsselt werden.

Der Parameter additional_data erlaubt es, zusätzliche Metadaten (z. B. Header, Protokollversion) in die Authentifikation einzubeziehen, ohne sie zu verschlüsseln. Diese Daten müssen beim Entschlüsseln exakt mit den beim Verschlüsseln verwendeten übereinstimmen, andernfalls schlägt die Verifikation fehl.

Dieses Verfahren eignet sich besonders für Szenarien, in denen hohe Performance auf Systemen ohne AES-NI-Hardware-Beschleunigung gefordert ist, etwa in eingebetteten Systemen oder serverseitigen Anwendungen ohne entsprechende CPU-Unterstützung.

Parameter

Name	Typ	Beschreibung
$ciphertext Pflicht	string	Der zu entschlüsselnde Chiffriertext inklusive angehängtem Poly1305-Authentifizierungs-Tag (16 Byte). Wird typischerweise von `sodium_crypto_aead_chacha20poly1305_ietf_encrypt()` erzeugt.
$additional_data Pflicht	string	Zusätzliche, nicht verschlüsselte Daten, die jedoch in die Authentifikation einfließen (z. B. Protokoll-Header). Kann ein leerer String sein, muss aber exakt mit dem Wert beim Verschlüsseln übereinstimmen.
$nonce Pflicht	string	Ein 96-Bit-Nonce (exakt `SODIUM_CRYPTO_AEAD_CHACHA20POLY1305_IETF_NPUBBYTES` = 12 Byte). Darf für denselben Schlüssel niemals wiederverwendet werden. Wird üblicherweise zufällig mit `random_bytes()` erzeugt.
$key Pflicht	string	Der symmetrische Schlüssel mit exakt `SODIUM_CRYPTO_AEAD_CHACHA20POLY1305_IETF_KEYBYTES` = 32 Byte. Sollte mit `sodium_crypto_aead_chacha20poly1305_ietf_keygen()` erzeugt werden.

Rückgabewert

Typ

string|false

Beschreibung

Gibt den entschlüsselten Klartext als string zurück, wenn das Poly1305-Tag gültig ist. Gibt false zurück, wenn die Authentifizierung fehlschlägt (ungültiges Tag, manipulierte Daten oder falscher Schlüssel/Nonce).

Beispiele

Verschlüsseln und Entschlüsseln einer Nachricht

<?php
$key   = sodium_crypto_aead_chacha20poly1305_ietf_keygen();
$nonce = random_bytes(SODIUM_CRYPTO_AEAD_CHACHA20POLY1305_IETF_NPUBBYTES);

$message        = 'Geheime Nachricht: Passwort ist 42!';
$additionalData = 'version=1;user=alice';

// Verschlüsseln
$ciphertext = sodium_crypto_aead_chacha20poly1305_ietf_encrypt(
    $message,
    $additionalData,
    $nonce,
    $key
);

// Entschlüsseln
$plaintext = sodium_crypto_aead_chacha20poly1305_ietf_decrypt(
    $ciphertext,
    $additionalData,
    $nonce,
    $key
);

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

Geheime Nachricht: Passwort ist 42!

Erkennung manipulierter Daten

<?php
$key   = sodium_crypto_aead_chacha20poly1305_ietf_keygen();
$nonce = random_bytes(SODIUM_CRYPTO_AEAD_CHACHA20POLY1305_IETF_NPUBBYTES);

$message        = 'Wichtige Transaktion: 100 EUR an Bob';
$additionalData = 'tx-id=9876';

$ciphertext = sodium_crypto_aead_chacha20poly1305_ietf_encrypt(
    $message,
    $additionalData,
    $nonce,
    $key
);

// Chiffriertext manipulieren (1 Byte ändern)
$tampered = $ciphertext;
$tampered[0] = chr(ord($tampered[0]) ^ 0xFF);

$result = sodium_crypto_aead_chacha20poly1305_ietf_decrypt(
    $tampered,
    $additionalData,
    $nonce,
    $key
);

if ($result === false) {
    echo 'Manipulation erkannt — Entschlüsselung verweigert.';
} else {
    echo $result;
}

Manipulation erkannt — Entschlüsselung verweigert.

// Wichtig · Fallstricke

Nonce-Wiederverwendung ist katastrophal: Wird derselbe Nonce mit demselben Schlüssel für zwei verschiedene Nachrichten verwendet, kann ein Angreifer durch XOR-Verknüpfung beider Chiffretexte Rückschlüsse auf den Klartext ziehen. Verwende stets zufällige Nonces via random_bytes() oder einen sicheren Zähler.

Rückgabewert prüfen: Der Rückgabewert muss zwingend auf false geprüft werden (strikter Vergleich mit ===), da ein leerer Klartext als leerer String '' zurückgegeben wird und loosely als falsy gilt.

Kein geheimes Additional Data: Der additional_data-Parameter wird nicht verschlüsselt und sollte keine vertraulichen Informationen enthalten.

Nonce-Größe: Die IETF-Variante verwendet 12-Byte-Nonces (im Gegensatz zur originalen Variante mit 8 Byte). Achte darauf, die korrekte Konstante SODIUM_CRYPTO_AEAD_CHACHA20POLY1305_IETF_NPUBBYTES zu verwenden.

Siehe auch

sodium_crypto_aead_chacha20poly1305_ietf_encrypt sodium_crypto_aead_chacha20poly1305_ietf_keygen sodium_crypto_aead_chacha20poly1305_decrypt sodium_crypto_aead_aes256gcm_decrypt sodium_crypto_secretbox_open