MongoDB\Driver\Exception\EncryptionException — Klasse · PHP-Referenz

Signatur

class MongoDB\Driver\Exception\EncryptionException extends MongoDB\Driver\Exception\RuntimeException

Beschreibung

MongoDB\Driver\Exception\EncryptionException ist eine spezialisierte Ausnahme, die der MongoDB-PHP-Treiber wirft, wenn ein Fehler im Zusammenhang mit der clientseitigen Feldverschlüsselung (Client-Side Field Level Encryption, CSFLE) oder der Queryable Encryption auftritt. Sie erweitert MongoDB\Driver\Exception\RuntimeException und damit letztlich RuntimeException und \Exception.

Typische Auslöser sind: fehlerhafte oder fehlende Schlüsselverwaltungs-Konfiguration (KMS), ungültige oder abgelaufene Datenverschlüsselungsschlüssel (DEK), Probleme bei der Kommunikation mit einem externen Key-Management-Service (z. B. AWS KMS, Azure Key Vault, Google Cloud KMS oder einem lokalen KMIP-Server) sowie Versuche, verschlüsselte Felder mit einem inkompatiblen Schema zu lesen oder zu schreiben.

Um EncryptionException sinnvoll abzufangen, sollte man sie vor allgemeineren Elternklassen wie MongoDB\Driver\Exception\RuntimeException im catch-Block platzieren. So lässt sich gezielt auf Verschlüsselungsfehler reagieren, etwa durch Protokollierung, Benachrichtigung des Betreibers oder geordnetes Herunterfahren des betroffenen Prozesses.

Die Klasse definiert keine eigenen Methoden; alle Diagnoseinformationen (Fehlermeldung, Fehlercode, vorherige Ausnahme) werden über die Standardmethoden von \Exception bereitgestellt.

Beispiele

EncryptionException abfangen bei verschlüsselter Schreiboperation

<?php
use MongoDB\Driver\Manager;
use MongoDB\Driver\BulkWrite;
use MongoDB\Driver\Exception\EncryptionException;
use MongoDB\Driver\Exception\Exception as MongoDBException;

// AutoEncryption-Optionen konfigurieren (vereinfachtes Beispiel)
$autoEncryptionOpts = [
    'keyVaultNamespace' => 'encryption.__keyVault',
    'kmsProviders' => [
        'local' => [
            'key' => new MongoDB\BSON\Binary(
                str_repeat("\x00", 96), // 96 Null-Bytes als Beispiel-Masterkey
                MongoDB\BSON\Binary::TYPE_GENERIC
            ),
        ],
    ],
];

try {
    $manager = new Manager(
        'mongodb://localhost:27017',
        [],
        ['autoEncryption' => $autoEncryptionOpts]
    );

    $bulk = new BulkWrite();
    $bulk->insert(['ssn' => '123-45-6789']); // Feld ist als verschlüsselt definiert

    $manager->executeBulkWrite('mydb.users', $bulk);
    echo "Dokument erfolgreich eingefügt." . PHP_EOL;

} catch (EncryptionException $e) {
    // Gezieltes Abfangen von Verschlüsselungsfehlern
    echo "Verschlüsselungsfehler (Code " . $e->getCode() . "): " . $e->getMessage() . PHP_EOL;
    if ($e->getPrevious()) {
        echo "Ursache: " . $e->getPrevious()->getMessage() . PHP_EOL;
    }
} catch (MongoDBException $e) {
    echo "Allgemeiner MongoDB-Fehler: " . $e->getMessage() . PHP_EOL;
}

Verschlüsselungsfehler (Code 0): <fehlerspezifische Meldung des Treibers>

Verschlüsselungsfehler von anderen Laufzeitfehlern unterscheiden

<?php
use MongoDB\Driver\Exception\EncryptionException;
use MongoDB\Driver\Exception\RuntimeException;
use MongoDB\Driver\Exception\ConnectionException;

function handleMongoException(\Exception $e): void
{
    // Reihenfolge: spezifischste Klasse zuerst
    if ($e instanceof EncryptionException) {
        error_log('[CSFLE] Verschlüsselungsfehler: ' . $e->getMessage());
        // Betriebsteam benachrichtigen, KMS-Konfiguration prüfen
        return;
    }

    if ($e instanceof ConnectionException) {
        error_log('[MongoDB] Verbindungsfehler: ' . $e->getMessage());
        return;
    }

    if ($e instanceof RuntimeException) {
        error_log('[MongoDB] Laufzeitfehler: ' . $e->getMessage());
        return;
    }

    error_log('[Unbekannt] ' . $e->getMessage());
}

// Beispielaufruf mit simulierter Exception
$ex = new EncryptionException('Datenverschlüsselungsschlüssel nicht gefunden.', 1);
handleMongoException($ex);

[CSFLE] Verschlüsselungsfehler: Datenverschlüsselungsschlüssel nicht gefunden.

// Wichtig · Fallstricke

Sicherheitshinweis: Fehlermeldungen von EncryptionException können interne Informationen über die Schlüsselinfrastruktur enthalten. Geben Sie diese Meldungen niemals unbereinigt an Endnutzer weiter, sondern protokollieren Sie sie nur intern.

Voraussetzungen: Die Verwendung von CSFLE und Queryable Encryption erfordert den libmongocrypt-Hilfsprozess sowie den optionalen mongocryptd-Daemon oder die Nutzung von Shared Library (mongo_crypt_v1). Fehlt eine dieser Komponenten, wird ebenfalls eine EncryptionException (oder eine RuntimeException) geworfen.

PHP-Erweiterungs-Version: Die Klasse steht erst ab Version 1.7.0 der mongodb-PECL-Erweiterung zur Verfügung. In älteren Versionen werden Verschlüsselungsfehler als allgemeine RuntimeException geworfen.

Siehe auch

MongoDB\Driver\Exception\RuntimeException MongoDB\Driver\ClientEncryption MongoDB\Driver\Exception\ConnectionException MongoDB\Driver\Exception\Exception