sodium_crypto_secretbox_open — Funktion · PHP-Referenz

Signatur

sodium_crypto_secretbox_open(string $ciphertext, string $nonce, string $key): string|false

Beschreibung

sodium_crypto_secretbox_open() implementiert die authentifizierte Entschlüsselung mittels des symmetrischen Algorithmus XSalsa20-Poly1305 aus der libsodium-Bibliothek. Die Funktion überprüft zunächst den Authentifizierungs-Tag (MAC), bevor sie den Geheimtext entschlüsselt. Ist die Verifikation erfolgreich, wird der Klartext zurückgegeben – andernfalls false.

Dieser Ansatz schützt gleichzeitig vor Manipulation (Tampering) und vor unbefugtem Lesen: Wurde der Geheimtext nach der Verschlüsselung verändert, schlägt die Authentifizierung fehl, und die Nachricht wird gar nicht erst entschlüsselt. Das verhindert Padding-Oracle-Angriffe und ähnliche kryptographische Schwachstellen älterer Ansätze.

Die Funktion ist das Gegenstück zu sodium_crypto_secretbox(). Der Nonce muss derselbe sein, der bei der Verschlüsselung verwendet wurde, und darf für denselben Schlüssel niemals wiederverwendet werden. Für die Erzeugung eines kryptographisch sicheren Nonce sollte random_bytes(SODIUM_CRYPTO_SECRETBOX_NONCEBYTES) genutzt werden.

Typische Anwendungsfälle sind die verschlüsselte Speicherung sensibler Daten (z. B. in Datenbanken oder Dateien) sowie der sichere Datenaustausch zwischen zwei Parteien, die denselben geheimen Schlüssel kennen.

Parameter

Name	Typ	Beschreibung
$ciphertext Pflicht	string	Der zu entschlüsselnde Geheimtext, wie er von `sodium_crypto_secretbox()` zurückgegeben wurde (enthält den MAC-Tag vorangestellt).
$nonce Pflicht	string	Der Nonce, der bei der Verschlüsselung verwendet wurde. Muss exakt `SODIUM_CRYPTO_SECRETBOX_NONCEBYTES` (24) Bytes lang sein.
$key Pflicht	string	Der geheime Schlüssel, der bei der Verschlüsselung verwendet wurde. Muss exakt `SODIUM_CRYPTO_SECRETBOX_KEYBYTES` (32) Bytes lang sein.

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 Authentifizierung fehlschlägt (z. B. bei manipuliertem Geheimtext, falschem Schlüssel oder falschem Nonce).

Beispiele

Einfache Verschlüsselung und anschließende Entschlüsselung

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

$message    = 'Geheime Nachricht!';
$ciphertext = sodium_crypto_secretbox($message, $nonce, $key);

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

if ($decrypted === false) {
    echo 'Entschlüsselung fehlgeschlagen – Nachricht manipuliert?';
} else {
    echo $decrypted;
}

Geheime Nachricht!

Speichern und Laden eines verschlüsselten Werts (z. B. aus einer Datenbank)

<?php
// Schlüssel wird sicher aus einer Umgebungsvariable geladen
$key = sodium_hex2bin(getenv('SECRET_KEY_HEX'));

function encrypt(string $plaintext, string $key): string
{
    $nonce      = random_bytes(SODIUM_CRYPTO_SECRETBOX_NONCEBYTES);
    $ciphertext = sodium_crypto_secretbox($plaintext, $nonce, $key);
    // Nonce + Geheimtext zusammen Base64-kodiert speichern
    return base64_encode($nonce . $ciphertext);
}

function decrypt(string $stored, string $key): string|false
{
    $decoded    = base64_decode($stored, true);
    if ($decoded === false) {
        return false;
    }
    $nonce      = substr($decoded, 0, SODIUM_CRYPTO_SECRETBOX_NONCEBYTES);
    $ciphertext = substr($decoded, SODIUM_CRYPTO_SECRETBOX_NONCEBYTES);
    return sodium_crypto_secretbox_open($ciphertext, $nonce, $key);
}

$stored    = encrypt('Passwort123', $key);
$recovered = decrypt($stored, $key);

echo $recovered; // Passwort123

Passwort123

// Wichtig · Fallstricke

Sicherheitshinweise:

Ein Nonce darf für denselben Schlüssel niemals wiederverwendet werden. Bei Wiederverwendung kann ein Angreifer den Klartext rekonstruieren.
Der Rückgabewert false sollte mit === false geprüft werden, da ein leerer String ein gültiges Entschlüsselungsergebnis sein kann.
Den Schlüssel niemals im Klartext im Quellcode speichern – stattdessen Umgebungsvariablen oder einen Key-Management-Service verwenden.
Für die Kommunikation zwischen zwei Parteien mit eigenen Schlüsselpaaren ist sodium_crypto_box() die bessere Wahl, da dort kein gemeinsames Geheimnis vorab ausgetauscht werden muss.
Der Geheimtext enthält den Poly1305-MAC (SODIUM_CRYPTO_SECRETBOX_MACBYTES = 16 Bytes) vorangestellt; ein leerer Klartext erzeugt daher einen nicht-leeren Geheimtext.

Siehe auch

sodium_crypto_secretbox sodium_crypto_secretbox_keygen sodium_crypto_box_open sodium_crypto_aead_chacha20poly1305_decrypt random_bytes