sodium_crypto_box_open — Funktion · PHP-Referenz

Signatur

sodium_crypto_box_open(string $ciphertext, string $nonce, string $key_pair): string|false

Beschreibung

sodium_crypto_box_open() führt eine authentifizierte Public-Key-Entschlüsselung durch. Sie verwendet das X25519-Diffie-Hellman-Schlüsselaustauschsverfahren in Kombination mit XSalsa20 (Verschlüsselung) und Poly1305 (Authentifizierungstoken / MAC). Die Funktion stellt sicher, dass die Nachricht tatsächlich vom erwarteten Absender stammt und auf dem Übertragungsweg nicht verändert wurde.

Für die Entschlüsselung wird ein Schlüsselpaar benötigt, das aus dem privaten Schlüssel des Empfängers und dem öffentlichen Schlüssel des Absenders besteht. Dieses Paar wird mit sodium_crypto_box_keypair_from_secretkey_and_publickey() erzeugt und enthält genau die Informationen, die zur Ableitung des gemeinsamen Geheimnisses benötigt werden.

Gibt die Funktion false zurück, bedeutet dies, dass die Nachricht entweder manipuliert wurde, der falsche Schlüssel verwendet wird oder der Nonce nicht übereinstimmt. In diesem Fall darf der Klartext unter keinen Umständen weiterverwendet werden.

Der Nonce muss für jede verschlüsselte Nachricht eindeutig sein, darf aber nicht geheim gehalten werden — er wird typischerweise zusammen mit dem Chiffretext übertragen. Seine Länge beträgt exakt SODIUM_CRYPTO_BOX_NONCEBYTES (24 Byte).

Parameter

Name	Typ	Beschreibung
$ciphertext Pflicht	string	Der verschlüsselte Text inklusive MAC (Authentifizierungstoken), wie er von `sodium_crypto_box()` erzeugt wurde. Muss mindestens `SODIUM_CRYPTO_BOX_MACBYTES` (16 Byte) lang sein.
$nonce Pflicht	string	Ein einmaliger Zufallswert (Number used Once) der Länge `SODIUM_CRYPTO_BOX_NONCEBYTES` (24 Byte). Muss identisch mit dem beim Verschlüsseln verwendeten Nonce sein.
$key_pair Pflicht	string	Ein kombiniertes Schlüsselpaar aus dem privaten Schlüssel des Empfängers und dem öffentlichen Schlüssel des Absenders, erzeugt mit `sodium_crypto_box_keypair_from_secretkey_and_publickey()`.

Rückgabewert

Typ

string|false

Beschreibung

Gibt den entschlüsselten Klartext als string zurück, wenn Entschlüsselung und Authentifizierung erfolgreich waren. Gibt false zurück, wenn die Authentifizierung fehlschlägt (manipulierter Chiffretext, falscher Schlüssel oder falscher Nonce).

Beispiele

Verschlüsseln und Entschlüsseln zwischen zwei Parteien

<?php
// Schlüsselpaare für Alice (Absenderin) und Bob (Empfänger) erzeugen
$aliceKeypair = sodium_crypto_box_keypair();
$aliceSecretKey = sodium_crypto_box_secretkey($aliceKeypair);
$alicePublicKey = sodium_crypto_box_publickey($aliceKeypair);

$bobKeypair = sodium_crypto_box_keypair();
$bobSecretKey = sodium_crypto_box_secretkey($bobKeypair);
$bobPublicKey = sodium_crypto_box_publickey($bobKeypair);

// Alice verschlüsselt eine Nachricht für Bob
$nonce = random_bytes(SODIUM_CRYPTO_BOX_NONCEBYTES);
$plaintext = 'Geheime Nachricht von Alice an Bob';

// Schlüsselpaar: Alice-Privatekey + Bob-Publickey
$aliceToBobKeyPair = sodium_crypto_box_keypair_from_secretkey_and_publickey(
    $aliceSecretKey,
    $bobPublicKey
);
$ciphertext = sodium_crypto_box($plaintext, $nonce, $aliceToBobKeyPair);

// Bob entschlüsselt mit seinem Privatekey und Alice' Publickey
$bobFromAliceKeyPair = sodium_crypto_box_keypair_from_secretkey_and_publickey(
    $bobSecretKey,
    $alicePublicKey
);
$decrypted = sodium_crypto_box_open($ciphertext, $nonce, $bobFromAliceKeyPair);

if ($decrypted === false) {
    echo 'Entschlüsselung fehlgeschlagen – Nachricht manipuliert oder falscher Schlüssel!';
} else {
    echo $decrypted;
}

Geheime Nachricht von Alice an Bob

Fehlerbehandlung bei manipuliertem Chiffretext

<?php
$keypairA = sodium_crypto_box_keypair();
$keypairB = sodium_crypto_box_keypair();

$secretA = sodium_crypto_box_secretkey($keypairA);
$publicA = sodium_crypto_box_publickey($keypairA);
$secretB = sodium_crypto_box_secretkey($keypairB);
$publicB = sodium_crypto_box_publickey($keypairB);

$nonce = random_bytes(SODIUM_CRYPTO_BOX_NONCEBYTES);
$sendKeyPair = sodium_crypto_box_keypair_from_secretkey_and_publickey($secretA, $publicB);
$ciphertext = sodium_crypto_box('Wichtige Daten', $nonce, $sendKeyPair);

// Manipulation simulieren: ein Byte verändern
$tampered = $ciphertext;
$tampered[0] = chr(ord($tampered[0]) ^ 0xFF);

$recvKeyPair = sodium_crypto_box_keypair_from_secretkey_and_publickey($secretB, $publicA);
$result = sodium_crypto_box_open($tampered, $nonce, $recvKeyPair);

if ($result === false) {
    echo 'Authentifizierung fehlgeschlagen: Nachricht wurde verändert.';
} else {
    echo $result;
}

Authentifizierung fehlgeschlagen: Nachricht wurde verändert.

// Wichtig · Fallstricke

Sicherheitshinweise:

Verwenden Sie niemals denselben Nonce zweimal mit demselben Schlüsselpaar. Ein wiederverwendeter Nonce bricht die Vertraulichkeit vollständig. Erzeugen Sie Nonces stets mit random_bytes(SODIUM_CRYPTO_BOX_NONCEBYTES).
Der Rückgabewert false muss mit === false geprüft werden, da ein leerer Klartext-String ebenfalls als falsy gilt.
Speichern Sie private Schlüssel ($secretKey) niemals im Klartext oder im Quellcode. Nutzen Sie sichere Speichermechanismen.
Löschen Sie sensible Schlüsselmaterialien nach Verwendung mit sodium_memzero() aus dem Arbeitsspeicher.
Der Nonce wird nicht automatisch mitgesendet — es liegt in der Verantwortung des Entwicklers, Nonce und Chiffretext gemeinsam zu übertragen (z. B. konkateniert).

Siehe auch

sodium_crypto_box sodium_crypto_box_keypair sodium_crypto_box_keypair_from_secretkey_and_publickey sodium_crypto_box_publickey sodium_crypto_box_secretkey sodium_crypto_secretbox_open sodium_memzero