MongoDB\Driver\ClientEncryption — Klasse · PHP-Referenz

Signatur

class MongoDB\Driver\ClientEncryption

Beschreibung

MongoDB\Driver\ClientEncryption ermöglicht die sogenannte explizite Verschlüsselung von MongoDB-Feldern. Im Gegensatz zur automatischen Verschlüsselung übernimmt dabei die Anwendung selbst die Kontrolle darüber, welche Werte wann ver- oder entschlüsselt werden. Dazu werden Data Encryption Keys (DEKs) aus einem Key Vault verwendet, die ihrerseits durch einen Key Management Service (KMS) – z. B. AWS KMS, Azure Key Vault, GCP KMS oder ein lokales Masterkey-Material – geschützt sind.

Die Klasse wird nicht direkt instanziiert, sondern über die Methode MongoDB\Driver\Manager::createClientEncryption() erzeugt. Sie benötigt eine Konfiguration, die u. a. den Key-Vault-Namespace (Datenbank + Collection), den zu verwendenden KMS-Provider und optionale TLS-Einstellungen enthält.

Typische Anwendungsfälle sind: explizite Verschlüsselung sensibler Felder (z. B. Kreditkartennummern, Sozialversicherungsnummern) vor dem Schreiben in die Datenbank, das Erstellen und Verwalten von Data Encryption Keys sowie das gezielte Entschlüsseln von Feldern beim Lesen. Damit eignet sich die Klasse besonders für Szenarien, in denen feingranulare Kontrolle über die Verschlüsselungslogik erforderlich ist.

Wichtig: Für die Nutzung wird die PHP-Extension mongodb (PECL) in Version 1.7 oder höher sowie die Systembibliothek libmongocrypt benötigt. Ohne diese Abhängigkeiten sind alle Methoden nicht verfügbar.

Parameter

Name	Typ	Default	Beschreibung
$options Pflicht	array		Konfigurationsarray für die ClientEncryption-Instanz. Pflichtfelder sind `keyVaultClient` (ein `MongoDB\Driver\Manager`-Objekt, das auf die Key-Vault-Collection zeigt), `keyVaultNamespace` (z. B. `'encryption.__keyVault'`) sowie `kmsProviders` (assoziatives Array mit KMS-Konfigurationen wie `local`, `aws`, `azure` oder `gcp`). Optional kann `tlsOptions` für TLS-Verbindungen zum KMS angegeben werden.

Rückgabewert

Typ

Beispiele

Data Encryption Key erstellen und Wert explizit verschlüsseln

<?php
use MongoDB\Driver\Manager;
use MongoDB\Driver\ClientEncryption;

// Lokales Master-Key-Material (96 Bytes, nur für Testzwecke!)
$localKey = random_bytes(96);

$manager = new Manager('mongodb://localhost:27017');

$clientEncryption = $manager->createClientEncryption([
    'keyVaultNamespace' => 'encryption.__keyVault',
    'keyVaultClient'    => $manager,
    'kmsProviders'      => [
        'local' => [
            'key' => new MongoDB\BSON\Binary($localKey, MongoDB\BSON\Binary::TYPE_GENERIC),
        ],
    ],
]);

// Neuen Data Encryption Key erstellen
$keyId = $clientEncryption->createDataKey('local', [
    'keyAltNames' => ['meinSchluessel'],
]);

echo 'DEK erstellt: ' . base64_encode((string)$keyId->getData()) . PHP_EOL;

// Wert explizit verschlüsseln
$verschluesselt = $clientEncryption->encrypt(
    'Geheime Kreditkartennummer: 4111-1111-1111-1111',
    [
        'algorithm' => ClientEncryption::AEAD_AES_256_CBC_HMAC_SHA_512_DETERMINISTIC,
        'keyAltName' => 'meinSchluessel',
    ]
);

echo 'Verschlüsselter Wert (Typ): ' . get_class($verschluesselt) . PHP_EOL;

// Wert explizit entschlüsseln
$entschluesselt = $clientEncryption->decrypt($verschluesselt);
echo 'Entschlüsselt: ' . $entschluesselt . PHP_EOL;

DEK erstellt: <base64-encodierter UUID-Wert> Verschlüsselter Wert (Typ): MongoDB\BSON\Binary Entschlüsselt: Geheime Kreditkartennummer: 4111-1111-1111-1111

Data Encryption Key per alternativen Namen abrufen

<?php
use MongoDB\Driver\Manager;

$localKey = random_bytes(96);
$manager  = new Manager('mongodb://localhost:27017');

$clientEncryption = $manager->createClientEncryption([
    'keyVaultNamespace' => 'encryption.__keyVault',
    'keyVaultClient'    => $manager,
    'kmsProviders'      => [
        'local' => [
            'key' => new MongoDB\BSON\Binary($localKey, MongoDB\BSON\Binary::TYPE_GENERIC),
        ],
    ],
]);

// Schlüssel per Alt-Name abrufen
$keyDocument = $clientEncryption->getKeyByAltName('meinSchluessel');

if ($keyDocument !== null) {
    echo 'Schlüssel gefunden, ID: ' . base64_encode((string)$keyDocument['_id']->getData()) . PHP_EOL;
} else {
    echo 'Schlüssel nicht gefunden.' . PHP_EOL;
}

Schlüssel gefunden, ID: <base64-encodierter UUID-Wert>

// Wichtig · Fallstricke

Sicherheitshinweise:

Das lokale Master-Key-Material (local-KMS-Provider) eignet sich ausschließlich für Entwicklung und Tests. In Produktionsumgebungen sollte ein externer KMS-Anbieter (AWS, Azure, GCP) verwendet werden.
Der Key-Vault-Collection sollte ein eindeutiger Index auf dem Feld keyAltNames angelegt werden, um doppelte Schlüssel zu verhindern.
Beim deterministischen Algorithmus (AEAD_AES_256_CBC_HMAC_SHA_512_DETERMINISTIC) sind verschlüsselte Werte abfragbar, aber identische Klartexte erzeugen identische Chiffretexte – dies kann unter Umständen Informationen preisgeben.
Der randomisierte Algorithmus (AEAD_AES_256_CBC_HMAC_SHA_512_RANDOM) ist sicherer, erlaubt aber keine Abfragen auf verschlüsselte Felder.
Die Klasse erfordert libmongocrypt auf dem System sowie die PECL-Extension mongodb >= 1.7.0.

Siehe auch

MongoDB\Driver\Manager::createClientEncryption MongoDB\Driver\Manager MongoDB\BSON\Binary