sodium_crypto_aead_aegis256_decrypt — Funktion · PHP-Referenz

Signatur

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

Beschreibung

sodium_crypto_aead_aegis256_decrypt() ist Teil der libsodium-Bindings für PHP und implementiert den modernen AEGIS-256-Algorithmus (Authenticated Encryption with Associated Data). Die Funktion prüft zunächst den Authentizierungs-Tag der verschlüsselten Nachricht und entschlüsselt sie nur, wenn die Prüfung erfolgreich war.

AEGIS-256 ist ein hochperformanter AEAD-Algorithmus, der sowohl Vertraulichkeit als auch Integrität der Nachricht sowie optionale Zusatzdaten (Additional Data) schützt. Die Zusatzdaten werden authentifiziert, aber nicht verschlüsselt – typische Anwendungsfälle sind z. B. HTTP-Header, Protokollversionen oder andere Metadaten, die im Klartext übertragen werden sollen, aber vor Manipulation geschützt werden müssen.

Der Nonce (Number used once) muss für jede Verschlüsselung mit demselben Schlüssel eindeutig sein. Er hat eine Länge von SODIUM_CRYPTO_AEAD_AEGIS256_NPUBBYTES Bytes (32 Bytes). Der Schlüssel hat eine Länge von SODIUM_CRYPTO_AEAD_AEGIS256_KEYBYTES Bytes (32 Bytes) und sollte mit sodium_crypto_aead_aegis256_keygen() erzeugt werden.

Gibt die Funktion false zurück, wurde die Authentizität der Nachricht oder der Zusatzdaten verletzt – in diesem Fall darf der Inhalt keinesfalls weiterverwendet werden. Dieser Rückgabewert sollte immer explizit geprüft werden, da auch eine manipulierte Nachricht als false zurückgegeben wird.

Parameter

Name	Typ	Beschreibung
$ciphertext Pflicht	string	Der verschlüsselte Text einschließlich Authentizierungs-Tag, wie er von `sodium_crypto_aead_aegis256_encrypt()` zurückgegeben wurde.
$additional_data Pflicht	string	Zusätzliche authentifizierte Daten (AAD), die nicht verschlüsselt, aber in die Authentizitätsprüfung einbezogen werden. Muss exakt mit den beim Verschlüsseln verwendeten Daten übereinstimmen. Kann ein leerer String sein.
$nonce Pflicht	string	Ein eindeutiger Nonce mit einer Länge von genau `SODIUM_CRYPTO_AEAD_AEGIS256_NPUBBYTES` (32) Bytes. Darf für denselben Schlüssel niemals wiederverwendet werden.
$key Pflicht	string	Der geheime Schlüssel mit einer Länge von genau `SODIUM_CRYPTO_AEAD_AEGIS256_KEYBYTES` (32) Bytes. Sollte mit `sodium_crypto_aead_aegis256_keygen()` erzeugt werden.

Rückgabewert

Typ

string|false

Beschreibung

Gibt den entschlüsselten Klartext als string zurück, wenn Authentizitätsprüfung und Entschlüsselung erfolgreich waren. Gibt false zurück, wenn die Authentizitätsprüfung fehlschlägt (z. B. bei manipulierten Daten, falschem Schlüssel, falschem Nonce oder falschen Zusatzdaten).

Beispiele

Verschlüsseln und anschließend entschlüsseln mit AEGIS-256

<?php
// Schlüssel und Nonce erzeugen
$key   = sodium_crypto_aead_aegis256_keygen();
$nonce = random_bytes(SODIUM_CRYPTO_AEAD_AEGIS256_NPUBBYTES);

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

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

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

if ($decrypted === false) {
    throw new RuntimeException('Entschlüsselung fehlgeschlagen: Nachricht manipuliert oder Schlüssel falsch.');
}

echo $decrypted;

Geheime Nachricht

Fehlgeschlagene Authentizitätsprüfung bei manipulierten Daten

<?php
$key   = sodium_crypto_aead_aegis256_keygen();
$nonce = random_bytes(SODIUM_CRYPTO_AEAD_AEGIS256_NPUBBYTES);

$ciphertext = sodium_crypto_aead_aegis256_encrypt(
    'Vertraulicher Inhalt',
    'meta=original',
    $nonce,
    $key
);

// Versuch mit falschen Zusatzdaten (Angriffsszenario)
$result = sodium_crypto_aead_aegis256_decrypt(
    $ciphertext,
    'meta=manipuliert', // abweichende AAD
    $nonce,
    $key
);

if ($result === false) {
    echo 'Authentizitätsprüfung fehlgeschlagen – Daten wurden nicht akzeptiert.';
} else {
    echo $result;
}

Authentizitätsprüfung fehlgeschlagen – Daten wurden nicht akzeptiert.

// Wichtig · Fallstricke

Sicherheitshinweise:

Nonce-Wiederverwendung ist kritisch: Wird derselbe Nonce mit demselben Schlüssel zweimal verwendet, bricht die Sicherheit von AEGIS-256 vollständig zusammen. Nonces müssen entweder zufällig (random_bytes()) oder als streng monoton steigende Zähler erzeugt werden.
Rückgabewert prüfen: Ein Rückgabewert von false darf nicht ignoriert werden. Der Vergleich sollte mit === (strikter Vergleich) erfolgen, da ein leerer Klartext als leerer String zurückgegeben wird, der bei losem Vergleich falsch interpretiert werden könnte.
Schlüssel geheim halten: Der Schlüssel muss sicher gespeichert werden (z. B. in Umgebungsvariablen oder einem Secret-Management-System), niemals im Quellcode.
AEGIS-256 ist erst ab PHP 8.4 (mit libsodium ≥ 1.0.19) verfügbar. Die Verfügbarkeit kann mit defined('SODIUM_CRYPTO_AEAD_AEGIS256_KEYBYTES') geprüft werden.

Siehe auch

sodium_crypto_aead_aegis256_encrypt sodium_crypto_aead_aegis256_keygen sodium_crypto_aead_aegis128l_decrypt sodium_crypto_aead_chacha20poly1305_decrypt sodium_crypto_aead_aes256gcm_decrypt