sodium_crypto_aead_aegis128l_decrypt — Funktion · PHP-Referenz

Signatur

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

Beschreibung

sodium_crypto_aead_aegis128l_decrypt() entschlüsselt einen Geheimtext, der zuvor mit sodium_crypto_aead_aegis128l_encrypt() erzeugt wurde, und verifiziert dabei gleichzeitig dessen Authentizierungs-Tag. AEGIS-128L ist ein moderner, hochperformanter authentifizierter Verschlüsselungsalgorithmus (AEAD – Authenticated Encryption with Associated Data), der auf AES-Instruktionen moderner CPUs optimiert ist.

Neben dem eigentlichen Geheimtext können sogenannte Additional Data (zusätzliche Daten) in die Authentifizierung einbezogen werden, ohne selbst verschlüsselt zu werden. Typische Anwendungsfälle sind HTTP-Header, Nutzer-IDs oder Versionsinformationen, die im Klartext übertragen, aber vor Manipulation geschützt werden sollen.

Schlägt die Integritätsprüfung fehl – d. h. wurde der Geheimtext, der Nonce, der Schlüssel oder die zusätzlichen Daten verändert – gibt die Funktion false zurück, ohne einen Klartextausschnitt preiszugeben. Dieses Verhalten verhindert Padding-Oracle- und ähnliche Angriffe.

Schlüssel und Nonce müssen exakt die vorgeschriebene Länge haben (SODIUM_CRYPTO_AEAD_AEGIS128L_KEYBYTES bzw. SODIUM_CRYPTO_AEAD_AEGIS128L_NPUBBYTES). Nonces dürfen pro Schlüssel niemals wiederverwendet werden; am sichersten generiert man sie mit random_bytes().

Parameter

Name	Typ	Beschreibung
$ciphertext Pflicht	string	Der zu entschlüsselnde Geheimtext inklusive angehängtem Authentizierungs-Tag, wie er von `sodium_crypto_aead_aegis128l_encrypt()` erzeugt wurde.
$additional_data Pflicht	string	Zusätzliche Daten, die bei der Verschlüsselung in die Authentifizierung einbezogen wurden (darf ein leerer String sein, muss aber identisch mit dem beim Verschlüsseln verwendeten Wert sein).
$nonce Pflicht	string	Einmal-Zufallswert (Nonce) der Länge `SODIUM_CRYPTO_AEAD_AEGIS128L_NPUBBYTES` (16 Byte). Muss identisch mit dem bei der Verschlüsselung verwendeten Nonce sein.
$key Pflicht	string	Geheimer Schlüssel der Länge `SODIUM_CRYPTO_AEAD_AEGIS128L_KEYBYTES` (16 Byte), am besten erzeugt mit `sodium_crypto_aead_aegis128l_keygen()`.

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 Integritätsprüfung fehlschlägt (z. B. bei manipulierten Daten, falschem Schlüssel oder falschem Nonce).

Beispiele

Grundlegendes Ver- und Entschlüsseln mit AEGIS-128L

<?php
$key   = sodium_crypto_aead_aegis128l_keygen();
$nonce = random_bytes(SODIUM_CRYPTO_AEAD_AEGIS128L_NPUBBYTES);

$plaintext       = 'Geheime Nachricht';
$additional_data = 'Benutzer-ID:42';

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

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

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

echo $decrypted;

Geheime Nachricht

Erkennung manipulierter Daten

<?php
$key   = sodium_crypto_aead_aegis128l_keygen();
$nonce = random_bytes(SODIUM_CRYPTO_AEAD_AEGIS128L_NPUBBYTES);

$ciphertext = sodium_crypto_aead_aegis128l_encrypt(
    'Wichtige Nachricht',
    'meta=original',
    $nonce,
    $key
);

// Angreifer versucht, die Additional Data zu fälschen
$result = sodium_crypto_aead_aegis128l_decrypt(
    $ciphertext,
    'meta=gefaelscht',  // abweichend vom Original
    $nonce,
    $key
);

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

Manipulation erkannt – Entschlüsselung abgebrochen.

// Wichtig · Fallstricke

Nonce-Wiederverwendung ist fatal: Wird derselbe Nonce mit demselben Schlüssel für zwei verschiedene Nachrichten verwendet, können Angreifer den Schlüsselstrom rekonstruieren und beide Klartexte kompromittieren. Generiere Nonces immer zufällig mit random_bytes() oder einem sicheren Zähler.

Schlüssellänge: Der Schlüssel muss exakt SODIUM_CRYPTO_AEAD_AEGIS128L_KEYBYTES (16 Byte) lang sein, andernfalls wird eine SodiumException geworfen.

Verfügbarkeit: AEGIS-128L ist ab PHP 8.4 mit libsodium ≥ 1.0.19 verfügbar. Prüfe die Verfügbarkeit mit defined('SODIUM_CRYPTO_AEAD_AEGIS128L_KEYBYTES').

Rückgabewert prüfen: Vergleiche das Ergebnis immer strikt mit === false, da ein leerer Klartext-String einen falsy-Wert erzeugen würde, der bei == false ebenfalls als fehlgeschlagen interpretiert werden könnte.

Siehe auch

sodium_crypto_aead_aegis128l_encrypt sodium_crypto_aead_aegis128l_keygen sodium_crypto_aead_aegis256_decrypt sodium_crypto_aead_chacha20poly1305_decrypt sodium_crypto_aead_aes256gcm_decrypt