sodium_crypto_aead_xchacha20poly1305_ietf_keygen — Funktion · PHP-Referenz

Signatur

sodium_crypto_aead_xchacha20poly1305_ietf_keygen(): string

Beschreibung

sodium_crypto_aead_xchacha20poly1305_ietf_keygen() erzeugt einen zufälligen Schlüssel der Länge SODIUM_CRYPTO_AEAD_XCHACHA20POLY1305_IETF_KEYBYTES (32 Byte), der für die authentifizierte Verschlüsselung mit zugehörigen Daten (AEAD) über sodium_crypto_aead_xchacha20poly1305_ietf_encrypt() und sodium_crypto_aead_xchacha20poly1305_ietf_decrypt() benötigt wird.

XChaCha20-Poly1305-IETF ist eine moderne AEAD-Konstruktion, die sowohl Vertraulichkeit als auch Integrität der verschlüsselten Daten garantiert. Sie eignet sich besonders für Szenarien, in denen große Mengen an Nachrichten mit demselben Schlüssel verschlüsselt werden müssen, da XChaCha20 eine 192-Bit-Nonce verwendet und damit das Risiko von Nonce-Kollisionen bei zufällig generierten Nonces drastisch reduziert.

Der erzeugte Schlüssel besteht aus rohen Binärdaten und sollte niemals direkt im Klartext gespeichert oder übertragen werden. Für die dauerhafte Speicherung empfiehlt sich eine Kodierung per sodium_bin2hex() oder base64_encode() sowie eine sichere Aufbewahrung, z. B. in Umgebungsvariablen oder einem dedizierten Secrets-Manager.

Im Unterschied zur normalen chacha20poly1305_ietf-Variante erlaubt die XChaCha20-Variante durch die erweiterte Nonce-Größe das sichere Generieren zufälliger Nonces ohne nennenswerte Kollisionswahrscheinlichkeit, was die Implementierung sicherer AEAD-Protokolle erheblich vereinfacht.

Rückgabewert

Typ

string

Beschreibung

Gibt einen zufälligen Binärstring der Länge SODIUM_CRYPTO_AEAD_XCHACHA20POLY1305_IETF_KEYBYTES (32 Byte) zurück, der als Schlüssel für XChaCha20-Poly1305-IETF-Operationen verwendet werden kann.

Beispiele

Schlüssel generieren und Nachricht verschlüsseln

<?php
// Schlüssel und Nonce generieren
$key   = sodium_crypto_aead_xchacha20poly1305_ietf_keygen();
$nonce = random_bytes(SODIUM_CRYPTO_AEAD_XCHACHA20POLY1305_IETF_NPUBBYTES);

$plaintext       = 'Geheime Nachricht';
$additionalData  = 'öffentliche Metadaten'; // wird authentifiziert, aber nicht verschlüsselt

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

echo 'Ciphertext (hex): ' . sodium_bin2hex($ciphertext) . PHP_EOL;

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

if ($decrypted === false) {
    throw new Exception('Entschlüsselung oder Integritätsprüfung fehlgeschlagen!');
}

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

// Speicher sicher freigeben
sodium_memzero($key);

Ciphertext (hex): <hex-kodierter Ciphertext> Entschlüsselt: Geheime Nachricht

Schlüssel sicher persistent speichern und laden

<?php
// Schlüssel generieren und hexadezimal kodiert speichern
$key     = sodium_crypto_aead_xchacha20poly1305_ietf_keygen();
$keyHex  = sodium_bin2hex($key);
sodium_memzero($key);

// Schlüssel in eine Umgebungsdatei oder einen sicheren Speicher schreiben
// (hier exemplarisch in eine Datei mit eingeschränkten Rechten)
$keyFile = '/var/secrets/xchacha20_key.hex';
file_put_contents($keyFile, $keyHex);
chmod($keyFile, 0600);

echo 'Schlüssel gespeichert.' . PHP_EOL;

// Später: Schlüssel laden und verwenden
$loadedKeyHex = file_get_contents($keyFile);
$loadedKey    = sodium_hex2bin($loadedKeyHex);

echo 'Schlüssellänge: ' . strlen($loadedKey) . ' Byte' . PHP_EOL;

sodium_memzero($loadedKey);

Schlüssel gespeichert. Schlüssellänge: 32 Byte

// Wichtig · Fallstricke

Sicherheitshinweise:

Der zurückgegebene Schlüssel enthält rohe Binärdaten — niemals direkt in Logs schreiben oder über unsichere Kanäle übertragen.
Verwende sodium_memzero(), um den Schlüssel nach der Verwendung sicher aus dem Speicher zu löschen, damit er nicht durch Speicher-Dumps kompromittiert werden kann.
Die Nonce muss für jede Verschlüsselungsoperation mit demselben Schlüssel einzigartig sein. Dank der 192-Bit-Nonce von XChaCha20 ist die Verwendung von random_bytes(SODIUM_CRYPTO_AEAD_XCHACHA20POLY1305_IETF_NPUBBYTES) sicher und praktikabel.
Ein Schlüssel darf niemals wiederverwendet werden, wenn er kompromittiert wurde — generiere in diesem Fall immer einen neuen Schlüssel.
Die Funktion ist seit PHP 7.2 verfügbar, da die libsodium-Erweiterung ab dieser Version in den PHP-Core integriert wurde.

Siehe auch

sodium_crypto_aead_xchacha20poly1305_ietf_encrypt sodium_crypto_aead_xchacha20poly1305_ietf_decrypt sodium_crypto_aead_chacha20poly1305_ietf_keygen sodium_memzero sodium_bin2hex random_bytes