sodium_crypto_aead_aegis128l_encrypt — Funktion · PHP-Referenz

Signatur

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

Beschreibung

sodium_crypto_aead_aegis128l_encrypt() gehört zur libsodium-Bindung in PHP und implementiert den AEGIS-128L-Algorithmus, ein modernes Authenticated Encryption with Associated Data (AEAD)-Verfahren. Es kombiniert Verschlüsselung und Integritätsprüfung in einem Schritt: Der zurückgegebene Chiffretext enthält am Ende einen kryptografischen Authentifizierungs-Tag, der sicherstellt, dass weder Nachricht noch zusätzliche Daten manipuliert wurden.

AEGIS-128L gilt als besonders performant (übertrifft AES-GCM auf moderner Hardware) und bietet hohe Sicherheit bei 128-Bit-Schlüsseln. Das optionale additional_data-Argument erlaubt es, Metadaten (z. B. Header, Protokoll-IDs) kryptografisch zu binden, ohne sie zu verschlüsseln – bei der Entschlüsselung müssen exakt dieselben Zusatzdaten angegeben werden, sonst schlägt die Authentifizierung fehl.

Der nonce muss exakt SODIUM_CRYPTO_AEAD_AEGIS128L_NPUBBYTES Bytes lang sein und darf für denselben Schlüssel niemals wiederverwendet werden. Der key muss exakt SODIUM_CRYPTO_AEAD_AEGIS128L_KEYBYTES Bytes lang sein; er sollte mit sodium_crypto_aead_aegis128l_keygen() erzeugt werden.

Zur Entschlüsselung und Verifikation dient die Gegenfunktion sodium_crypto_aead_aegis128l_decrypt(), die bei fehlgeschlagener Authentifizierung false zurückgibt.

Parameter

Name	Typ	Beschreibung
$message Pflicht	string	Die Klartextnachricht, die verschlüsselt werden soll. Kann beliebige Binärdaten enthalten.
$additional_data Pflicht	string	Zusätzliche Daten, die in die Authentifizierung einbezogen, aber nicht verschlüsselt werden (z. B. Header oder Protokoll-Metadaten). Kann ein leerer String `''` sein.
$nonce Pflicht	string	Einmalig zu verwendender Zufallswert (Number used once) der Länge `SODIUM_CRYPTO_AEAD_AEGIS128L_NPUBBYTES` (16 Bytes). Darf für denselben Schlüssel niemals wiederholt werden.
$key Pflicht	string	Geheimer Schlüssel der Länge `SODIUM_CRYPTO_AEAD_AEGIS128L_KEYBYTES` (16 Bytes). Am besten mit `sodium_crypto_aead_aegis128l_keygen()` erzeugen.

Rückgabewert

Typ

string

Beschreibung

Gibt den Chiffretext als binären String zurück. Er enthält die verschlüsselte Nachricht gefolgt vom Authentifizierungs-Tag (SODIUM_CRYPTO_AEAD_AEGIS128L_ABYTES Bytes). Im Fehlerfall (ungültige Parameter-Längen) wird eine SodiumException geworfen.

Beispiele

Nachricht verschlüsseln und wieder entschlüsseln

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

$plaintext       = 'Geheime Botschaft';
$additional_data = 'protokoll-v1';   // wird NICHT verschlüsselt

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

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

// Entschlüsseln – Additional Data muss identisch sein!
$decrypted = sodium_crypto_aead_aegis128l_decrypt(
    $ciphertext,
    $additional_data,
    $nonce,
    $key
);

if ($decrypted === false) {
    echo 'Authentifizierung fehlgeschlagen!';
} else {
    echo 'Klartext: ' . $decrypted . PHP_EOL;
}

Chiffretext (hex): <variiert je nach Zufallsnonce> Klartext: Geheime Botschaft

Nonce-basiertes Protokoll mit Übertragung von Nonce und Chiffretext

<?php
// Sender-Seite
$key   = sodium_crypto_aead_aegis128l_keygen(); // vorab sicher ausgetauscht
$nonce = random_bytes(SODIUM_CRYPTO_AEAD_AEGIS128L_NPUBBYTES);

$nachricht = 'Bestellung #4711: 3x Apfel';
$header    = 'user_id=42;session=abc';

$ciphertext = sodium_crypto_aead_aegis128l_encrypt($nachricht, $header, $nonce, $key);

// Nonce + Chiffretext werden übertragen (Nonce ist nicht geheim)
$paket = base64_encode($nonce . $ciphertext);
echo 'Übertragenes Paket: ' . $paket . PHP_EOL;

// Empfänger-Seite
$empfangen   = base64_decode($paket);
$nonce_len   = SODIUM_CRYPTO_AEAD_AEGIS128L_NPUBBYTES;
$nonce_recv  = substr($empfangen, 0, $nonce_len);
$cipher_recv = substr($empfangen, $nonce_len);

$plain = sodium_crypto_aead_aegis128l_decrypt($cipher_recv, $header, $nonce_recv, $key);
echo 'Empfangene Nachricht: ' . $plain . PHP_EOL;

Übertragenes Paket: <base64-kodierter String> Empfangene Nachricht: Bestellung #4711: 3x Apfel

// Wichtig · Fallstricke

Nonce-Einzigartigkeit: Eine Nonce darf bei gleichem Schlüssel absolut nicht wiederverwendet werden – andernfalls bricht die Vertraulichkeit des gesamten Verfahrens zusammen. Verwende random_bytes() für zufällige Nonces.
Zusatzdaten auf Empfängerseite: Die additional_data müssen bei der Entschlüsselung exakt dieselben sein wie bei der Verschlüsselung, sonst schlägt die Authentifizierung fehl und es wird false zurückgegeben.
Plattform-Verfügbarkeit: AEGIS-128L ist ab PHP 8.4 verfügbar. Ältere PHP-Versionen kennen diese Funktion nicht. Prüfe ggf. mit defined('SODIUM_CRYPTO_AEAD_AEGIS128L_KEYBYTES').
Keine direkte Fehlerrückgabe: Bei falschen Parameterlängen wirft die Funktion eine SodiumException – fang diese mit try/catch ab.
Sensible Schlüsseldaten sollten nach der Verwendung mit sodium_memzero() aus dem Speicher gelöscht werden.

Siehe auch

sodium_crypto_aead_aegis128l_decrypt sodium_crypto_aead_aegis128l_keygen sodium_crypto_aead_aegis256_encrypt sodium_crypto_aead_aes256gcm_encrypt sodium_crypto_aead_chacha20poly1305_encrypt random_bytes sodium_memzero