sodium_crypto_aead_aes256gcm_decrypt — Funktion · PHP-Referenz

Signatur

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

Beschreibung

Die Funktion sodium_crypto_aead_aes256gcm_decrypt() entschlüsselt einen Geheimtext, der zuvor mit sodium_crypto_aead_aes256gcm_encrypt() erzeugt wurde. Dabei wird zunächst die GCM-Authentizierungs-Tag-Überprüfung (AEAD – Authenticated Encryption with Associated Data) durchgeführt: Nur wenn die Integritätsprüfung des Geheimtexts und der zusätzlichen Daten erfolgreich ist, wird der Klartext zurückgegeben.

AES-256-GCM ist ein symmetrisches Verschlüsselungsverfahren, das sowohl Vertraulichkeit als auch Authentizität sicherstellt. Die zusätzlichen Daten (additional_data) werden nicht verschlüsselt, aber in die Authentizitätsprüfung einbezogen – typischerweise werden hier Metadaten wie Header oder Absenderinformationen übergeben, die unverfälscht bleiben müssen.

Wichtig: AES-256-GCM erfordert Hardware-Unterstützung (AES-NI) für sichere und performante Ausführung. Ob die Funktion auf dem aktuellen System verfügbar ist, lässt sich mit sodium_crypto_aead_aes256gcm_is_available() prüfen. Auf Systemen ohne AES-NI sollte stattdessen sodium_crypto_aead_chacha20poly1305_decrypt() verwendet werden.

Der übergebene Schlüssel muss exakt SODIUM_CRYPTO_AEAD_AES256GCM_KEYBYTES (32 Bytes) lang sein, und der Nonce muss exakt SODIUM_CRYPTO_AEAD_AES256GCM_NPUBBYTES (12 Bytes) lang sein. Ein Nonce darf bei gleichem Schlüssel niemals wiederverwendet werden.

Parameter

Name	Typ	Beschreibung
$ciphertext Pflicht	string	Der zu entschlüsselnde Geheimtext inklusive des angehängten GCM-Authentizierungs-Tags (ausgegeben von `sodium_crypto_aead_aes256gcm_encrypt()`).
$additional_data Pflicht	string	Zusätzliche, nicht verschlüsselte Daten, die bei der Verschlüsselung angegeben wurden und in die Authentizitätsprüfung einfließen. Muss exakt dem Wert entsprechen, der bei der Verschlüsselung übergeben wurde. Kann ein leerer String sein.
$nonce Pflicht	string	Ein eindeutiger, zufälliger Wert (Number used once) mit einer Länge von exakt `SODIUM_CRYPTO_AEAD_AES256GCM_NPUBBYTES` (12 Bytes). Muss derselbe Nonce sein, der bei der Verschlüsselung verwendet wurde.
$key Pflicht	string	Der geheime symmetrische Schlüssel mit einer Länge von exakt `SODIUM_CRYPTO_AEAD_AES256GCM_KEYBYTES` (32 Bytes). Empfohlen: mit `sodium_crypto_aead_aes256gcm_keygen()` erzeugen.

Rückgabewert

Typ

string|false

Beschreibung

Gibt den entschlüsselten Klartext als string zurück, wenn die Authentizitätsprüfung erfolgreich ist. Gibt false zurück, wenn die Verifikation fehlschlägt (Geheimtext, zusätzliche Daten oder Schlüssel wurden manipuliert oder stimmen nicht überein).

Beispiele

Verschlüsseln und Entschlüsseln mit AES-256-GCM

<?php
if (!sodium_crypto_aead_aes256gcm_is_available()) {
    throw new RuntimeException('AES-256-GCM wird auf diesem System nicht unterstützt.');
}

// Schlüssel und Nonce erzeugen
$key   = sodium_crypto_aead_aes256gcm_keygen();
$nonce = random_bytes(SODIUM_CRYPTO_AEAD_AES256GCM_NPUBBYTES);

$plaintext       = 'Geheime Nachricht!';
$additionalData  = 'Metadaten: Empfaenger=Alice';

// Verschlüsseln
$ciphertext = sodium_crypto_aead_aes256gcm_encrypt(
    $plaintext,
    $additionalData,
    $nonce,
    $key
);

echo 'Geheimtext (hex): ' . bin2hex($ciphertext) . PHP_EOL;

// Entschlüsseln
$decrypted = sodium_crypto_aead_aes256gcm_decrypt(
    $ciphertext,
    $additionalData,
    $nonce,
    $key
);

if ($decrypted === false) {
    echo 'Entschlüsselung fehlgeschlagen: Authentizitätsprüfung nicht bestanden.' . PHP_EOL;
} else {
    echo 'Klartext: ' . $decrypted . PHP_EOL;
}

sodium_memzero($key);

Geheimtext (hex): <variiert je nach Zufallswerten> Klartext: Geheime Nachricht!

Fehlschlag bei manipuliertem Geheimtext

<?php
if (!sodium_crypto_aead_aes256gcm_is_available()) {
    throw new RuntimeException('AES-256-GCM wird auf diesem System nicht unterstützt.');
}

$key   = sodium_crypto_aead_aes256gcm_keygen();
$nonce = random_bytes(SODIUM_CRYPTO_AEAD_AES256GCM_NPUBBYTES);

$ciphertext = sodium_crypto_aead_aes256gcm_encrypt(
    'Originalnachricht',
    'meta',
    $nonce,
    $key
);

// Geheimtext absichtlich manipulieren
$tampered = $ciphertext;
$tampered[0] = chr(ord($tampered[0]) ^ 0xFF);

$result = sodium_crypto_aead_aes256gcm_decrypt(
    $tampered,
    'meta',
    $nonce,
    $key
);

if ($result === false) {
    echo 'Manipulierter Geheimtext erkannt – Entschlüsselung abgebrochen.' . PHP_EOL;
}

sodium_memzero($key);

Manipulierter Geheimtext erkannt – Entschlüsselung abgebrochen.

// Wichtig · Fallstricke

Sicherheitshinweise:

Nonce-Wiederverwendung ist katastrophal: Bei gleicher Schlüssel-Nonce-Kombination können zwei verschiedene Klartexte vollständig kompromittiert werden. Verwende immer random_bytes(SODIUM_CRYPTO_AEAD_AES256GCM_NPUBBYTES) zur Erzeugung eines neuen Nonces.
Schlüssel sicher behandeln: Nach der Verwendung sollte der Schlüssel mit sodium_memzero() aus dem Speicher gelöscht werden.
Verfügbarkeit prüfen: Die Funktion ist nicht auf allen Systemen verfügbar. Prüfe die Verfügbarkeit immer mit sodium_crypto_aead_aes256gcm_is_available() und biete ChaCha20-Poly1305 als Fallback an.
Rückgabe prüfen: Das Ergebnis false darf niemals ignoriert werden, da es auf Manipulation oder Fehler hinweist. Niemals den Rückgabewert ohne Prüfung weiterverarbeiten.
Der übergebene $ciphertext enthält den eigentlichen Geheimtext und das 16-Byte-GCM-Tag; der Eingabe-String muss daher mindestens 16 Bytes lang sein.

Siehe auch

sodium_crypto_aead_aes256gcm_encrypt sodium_crypto_aead_aes256gcm_is_available sodium_crypto_aead_aes256gcm_keygen sodium_crypto_aead_chacha20poly1305_decrypt sodium_crypto_aead_chacha20poly1305_ietf_decrypt sodium_memzero