sodium_crypto_aead_aes256gcm_encrypt — Funktion · PHP-Referenz

Signatur

sodium_crypto_aead_aes256gcm_encrypt(string $message, string $additional_data, string $nonce, string $key): string

Beschreibung

sodium_crypto_aead_aes256gcm_encrypt() verschlüsselt eine Nachricht mit dem AES-256-GCM-Algorithmus und hängt einen Authentifizierungs-Tag (MAC) an den Geheimtext an. Dadurch wird sichergestellt, dass der Empfänger sowohl die Vertraulichkeit als auch die Integrität der Nachricht überprüfen kann. Dieses Verfahren gehört zur Klasse der Authenticated Encryption with Associated Data (AEAD) und ist in vielen Protokollen wie TLS 1.3 verbreitet.

Der Parameter additional_data ermöglicht es, zusätzliche, nicht verschlüsselte Metadaten (z. B. Header oder Kontextinformationen) in die Authentifizierung einzubeziehen. Diese Daten werden im Klartext übertragen, sind aber gegen Manipulation geschützt. Der Empfänger muss bei der Entschlüsselung dieselben additional_data übergeben.

Der nonce (Number used once) muss für jede Verschlüsselung mit demselben Schlüssel eindeutig sein. Eine Wiederverwendung des Nonce mit demselben Schlüssel bricht die Sicherheit des Verfahrens vollständig. Für die Nonce-Erzeugung empfiehlt sich random_bytes(SODIUM_CRYPTO_AEAD_AES256GCM_NPUBBYTES).

Wichtig: AES-256-GCM ist hardwarebeschleunigt (AES-NI) und damit sehr performant — jedoch nicht auf allen Plattformen verfügbar. Vor der Verwendung sollte mit sodium_crypto_aead_aes256gcm_is_available() geprüft werden, ob die Funktion auf dem aktuellen System unterstützt wird. Ist dies nicht der Fall, bietet sich sodium_crypto_aead_chacha20poly1305_encrypt() als portable Alternative an.

Parameter

Name	Typ	Beschreibung
$message Pflicht	string	Die zu verschlüsselnde Klartextnachricht (beliebige Binärdaten).
$additional_data Pflicht	string	Zusätzliche Daten, die nicht verschlüsselt, aber in die Authentifizierung einbezogen werden. Kann ein leerer String `''` sein, wenn keine zusätzlichen Daten benötigt werden.
$nonce Pflicht	string	Eine eindeutige Zufallszahl (Nonce) mit einer Länge von exakt `SODIUM_CRYPTO_AEAD_AES256GCM_NPUBBYTES` (12 Byte). Darf niemals mit demselben Schlüssel wiederverwendet werden.
$key Pflicht	string	Der geheime Schlüssel mit einer Länge von exakt `SODIUM_CRYPTO_AEAD_AES256GCM_KEYBYTES` (32 Byte). Kann z. B. mit `sodium_crypto_aead_aes256gcm_keygen()` erzeugt werden.

Rückgabewert

Typ

string

Beschreibung

Gibt den verschlüsselten Geheimtext als Binärstring zurück. Der Rückgabewert enthält den Chiffretext sowie den angehängten Authentifizierungs-Tag (SODIUM_CRYPTO_AEAD_AES256GCM_ABYTES, 16 Byte). Bei einem Fehler wird eine SodiumException geworfen.

Beispiele

Einfache Verschlüsselung einer Nachricht

<?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 generieren
$key   = sodium_crypto_aead_aes256gcm_keygen();
$nonce = random_bytes(SODIUM_CRYPTO_AEAD_AES256GCM_NPUBBYTES);

$message         = 'Geheime Nachricht: Passwort 12345';
$additional_data = 'user_id=42'; // Nicht verschlüsselt, aber authentifiziert

// Verschlüsseln
$ciphertext = sodium_crypto_aead_aes256gcm_encrypt($message, $additional_data, $nonce, $key);

echo 'Geheimtext (Base64): ' . base64_encode($ciphertext) . PHP_EOL;

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

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

echo 'Entschlüsselt: ' . $decrypted . PHP_EOL;

Geheimtext (Base64): <zufälliger Base64-String> Entschlüsselt: Geheime Nachricht: Passwort 12345

Verschlüsselung mit Nonce-Zähler für viele Nachrichten

<?php
if (!sodium_crypto_aead_aes256gcm_is_available()) {
    throw new RuntimeException('AES-256-GCM nicht verfügbar.');
}

$key      = sodium_crypto_aead_aes256gcm_keygen();
$messages = ['Nachricht 1', 'Nachricht 2', 'Nachricht 3'];
$packets  = [];

foreach ($messages as $index => $msg) {
    // Eindeutigen Nonce pro Nachricht erzeugen
    $nonce = random_bytes(SODIUM_CRYPTO_AEAD_AES256GCM_NPUBBYTES);
    $aad   = 'seq=' . $index; // Sequenznummer als zusätzliche Daten

    $ciphertext = sodium_crypto_aead_aes256gcm_encrypt($msg, $aad, $nonce, $key);

    // Nonce und Geheimtext gemeinsam speichern/übertragen
    $packets[] = [
        'nonce'      => base64_encode($nonce),
        'ciphertext' => base64_encode($ciphertext),
        'aad'        => $aad,
    ];
}

// Entschlüsseln
foreach ($packets as $packet) {
    $plain = sodium_crypto_aead_aes256gcm_decrypt(
        base64_decode($packet['ciphertext']),
        $packet['aad'],
        base64_decode($packet['nonce']),
        $key
    );
    echo $plain . PHP_EOL;
}

Nachricht 1 Nachricht 2 Nachricht 3

// Wichtig · Fallstricke

Verfügbarkeit prüfen: AES-256-GCM erfordert CPU-seitige AES-NI-Unterstützung. Immer zuerst sodium_crypto_aead_aes256gcm_is_available() aufrufen. Ohne diese Prüfung kann die Funktion auf manchen Systemen (z. B. ARM ohne AES-Erweiterung) eine Ausnahme werfen.

Nonce-Eindeutigkeit: Die Wiederverwendung eines Nonce mit demselben Schlüssel ist katastrophal für die Sicherheit — ein Angreifer kann damit den Schlüssel rekonstruieren oder Nachrichten fälschen. Verwende immer random_bytes() für die Nonce-Erzeugung oder einen sicheren, monoton steigenden Zähler.

Schlüsselverwaltung: Den Schlüssel niemals im Klartext speichern oder ausgeben. Nutze sodium_memzero(), um den Schlüssel nach der Verwendung sicher aus dem Speicher zu löschen. Schlüssel sollten ausschließlich über sodium_crypto_aead_aes256gcm_keygen() oder einen kryptografisch sicheren PRNG erzeugt werden.

Portable Alternative: Falls AES-256-GCM nicht verfügbar ist, kann sodium_crypto_aead_chacha20poly1305_ietf_encrypt() als sichere, plattformunabhängige Alternative verwendet werden.

Siehe auch

sodium_crypto_aead_aes256gcm_decrypt sodium_crypto_aead_aes256gcm_is_available sodium_crypto_aead_aes256gcm_keygen sodium_crypto_aead_chacha20poly1305_ietf_encrypt sodium_memzero random_bytes