Add support for Field-Level Automatic and Queryable Encryption

lib/Doctrine/ODM/MongoDB/Configuration.php

@@ -34,8 +34,12 @@
 use ReflectionClass;
 
 use function array_key_exists;
+use function array_key_first;
 use function class_exists;
+use function count;
 use function interface_exists;
+use function is_array;
+use function is_string;
 use function trigger_deprecation;
 use function trim;
 
@@ -50,6 +54,11 @@
  *     $dm = DocumentManager::create(new Connection(), $config);
  *
  * @phpstan-import-type CommitOptions from UnitOfWork
+ * @phpstan-type AutoEncryptionOptions array{
+ *     keyVaultNamespace: string,
+ *     kmsProviders: array<string, array<string, string>>,
+ *     tlsOptions?: array{kmip: array{tlsCAFile: string, tlsCertificateKeyFile: string}},
+ * }
  */
 class Configuration
 {
@@ -121,7 +130,8 @@ class Configuration
      *      persistentCollectionNamespace?: string,
      *      proxyDir?: string,
      *      proxyNamespace?: string,
-     *      repositoryFactory?: RepositoryFactory
+     *      repositoryFactory?: RepositoryFactory,
+     *      autoEncryption?: AutoEncryptionOptions,
      * }
      */
     private array $attributes = [];
@@ -653,6 +663,49 @@ public function isLazyGhostObjectEnabled(): bool
     {
         return $this->useLazyGhostObject;
     }
+
+    /**
+     * Set the options for auto-encryption.
+     *
+     * @see https://www.php.net/manual/en/mongodb-driver-clientencryption.construct.php
+     *
+     * @param AutoEncryptionOptions $options
+     *
+     * @throws InvalidArgumentException If the options are invalid.
+     */
+    public function setAutoEncryption(array $options): void
+    {
+        if (! isset($options['keyVaultNamespace']) || ! is_string($options['keyVaultNamespace'])) {
+            throw new InvalidArgumentException('The "keyVaultNamespace" option is required.');
+        }
+
+        if (! isset($options['kmsProviders']) || ! is_array($options['kmsProviders']) || count($options['kmsProviders']) < 1) {
+            throw new InvalidArgumentException('The "kmsProviders" option is required.');
+        }
+
+        $this->attributes['autoEncryption'] = $options;
+    }
+
+    /**
+     * Get the options for auto-encryption.
+     *
+     * @see https://www.php.net/manual/en/mongodb-driver-clientencryption.construct.php
+     *
+     * @return AutoEncryptionOptions
+     */
+    public function getAutoEncryption(): ?array
+    {
+        return $this->attributes['autoEncryption'] ?? null;
+    }
+
+    public function getKmsProvider(): ?string
+    {
+        if (! isset($this->attributes['autoEncryption'])) {
+            return null;
+        }
+
+        return array_key_first($this->attributes['autoEncryption']['kmsProviders']);
+    }
 }
 
 interface_exists(MappingDriver::class);

lib/Doctrine/ODM/MongoDB/DocumentManager.php

@@ -29,6 +29,7 @@
 use MongoDB\Client;
 use MongoDB\Collection;
 use MongoDB\Database;
+use MongoDB\Driver\ClientEncryption;
 use MongoDB\Driver\ReadPreference;
 use MongoDB\GridFS\Bucket;
 use ProxyManager\Proxy\GhostObjectInterface;
@@ -64,6 +65,8 @@
      */
     private Client $client;
 
+    private ClientEncryption $clientEncryption;
+
     /**
      * The used Configuration.
      */
@@ -151,12 +154,7 @@
         $this->client       = $client ?: new Client(
             'mongodb://127.0.0.1',
             [],
-            [
-                'driver' => [
-                    'name' => 'doctrine-odm',
-                    'version' => self::getVersion(),
-                ],
-            ],
+            $this->getDriverOptions(),
         );
 
         $this->classNameResolver = $this->config->isLazyGhostObjectEnabled()
@@ -225,6 +223,21 @@
         return $this->client;
     }
 
+    public function getClientEncryption(): ClientEncryption
+    {
+        $autoEncryptionOptions = $this->config->getAutoEncryption();
+
+        if (! $autoEncryptionOptions) {
+            throw new RuntimeException('Auto-encryption is not enabled.');
+        }
+
+        return $this->clientEncryption ??= $this->client->createClientEncryption([
+            'keyVaultNamespace' => $autoEncryptionOptions['keyVaultNamespace'],
+            'kmsProviders' => $autoEncryptionOptions['kmsProviders'],
+            'tlsOptions' => $autoEncryptionOptions['tlsOptions'] ?? [],
+        ]);
+    }
+
     /** Gets the metadata factory used to gather the metadata of classes. */
     public function getMetadataFactory(): ClassmetadataFactoryInterface
     {
@@ -924,6 +937,23 @@
         return $mapping['targetDocument'];
     }
 
+    /** @todo move this to the Configuration class, so that it can be use to instantiate the Client outside of the DocumentManager */
+    private function getDriverOptions(): array
+    {
+        $driverOptions = [
+            'driver' => [
+                'name' => 'doctrine-odm',
+                'version' => self::getVersion(),
+            ],
+        ];
+
+        if ($this->config->getAutoEncryption()) {
+            $driverOptions['autoEncryption'] = $this->config->getAutoEncryption();
+        }
+
+        return $driverOptions;
+    }
+
     private static function getVersion(): string
     {
         if (self::$version === null) {

lib/Doctrine/ODM/MongoDB/Mapping/Annotations/Encrypt.php

@@ -0,0 +1,49 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Doctrine\ODM\MongoDB\Mapping\Annotations;
+
+use Attribute;
+use Doctrine\Common\Annotations\Annotation\NamedArgumentConstructor;
+use InvalidArgumentException;
+use MongoDB\BSON\Type;
+use MongoDB\Driver\ClientEncryption;
+
+use function in_array;
+
+/**
+ * Defines an encrypted field mapping.
+ *
+ * @see https://www.mongodb.com/docs/manual/core/queryable-encryption/fundamentals/encrypt-and-query/#configure-encrypted-fields-for-optimal-search-and-storage
+ *
+ * @Annotation
+ * @NamedArgumentConstructor
+ */
+#[Attribute(Attribute::TARGET_PROPERTY)]
+final class Encrypt implements Annotation
+{
+    public const QUERY_TYPE_EQUALITY = ClientEncryption::QUERY_TYPE_EQUALITY;
+    public const QUERY_TYPE_RANGE    = ClientEncryption::QUERY_TYPE_RANGE;
+
+    /**
+     * @param self::QUERY_TYPE_*|null $queryType  Set the query type for the field, null if not queryable.
+     * @param int<1, 4>|null          $sparsity
+     * @param positive-int|null       $prevision
+     * @param positive-int|null       $trimFactor
+     * @param positive-int|null       $contention
+     */
+    public function __construct(
+        public ?string $queryType = null,
+        public string|int|Type|null $min = null,
+        public string|int|Type|null $max = null,
+        public ?int $sparsity = null,
+        public ?int $prevision = null,
+        public ?int $trimFactor = null,
+        public ?int $contention = null,
+    ) {
+        if ($this->queryType && ! in_array($this->queryType, [self::QUERY_TYPE_EQUALITY, self::QUERY_TYPE_RANGE], true)) {
+            throw new InvalidArgumentException('Invalid query type');
+        }
+    }
+}

lib/Doctrine/ODM/MongoDB/Mapping/ClassMetadata.php

@@ -107,6 +107,7 @@
  *      order?: int|string,
  *      background?: bool,
  *      enumType?: class-string<BackedEnum>,
+ *      encrypt?: array{queryType?: ?string, min?: mixed, max?: mixed, sparsity?: int<1, 4>, prevision?: int, trimFactor?: int, contention?: int}
  * }
  * @phpstan-type FieldMapping array{
  *      type: string,
@@ -153,6 +154,7 @@
  *      alsoLoadFields?: list<string>,
  *      enumType?: class-string<BackedEnum>,
  *      storeEmptyArray?: bool,
+ *      encrypt?: array{queryType?: ?string, min?: mixed, max?: mixed, sparsity?: int<1, 4>, prevision?: int, trimFactor?: int, contention?: int},
  * }
  * @phpstan-type AssociationFieldMapping array{
  *      type?: string,
@@ -801,6 +803,13 @@
      */
     public $isReadOnly;
 
+    /**
+     * READ-ONLY: A flag for whether or not this document has encrypted fields.
+     *
+     * @var bool
+     */
+    public $isEncrypted = false;
+
     /** READ ONLY: stores metadata about the time series collection */
     public ?TimeSeries $timeSeriesOptions = null;
 

lib/Doctrine/ODM/MongoDB/Mapping/Driver/AttributeDriver.php

@@ -32,7 +32,7 @@
 use function trigger_deprecation;
 
 /**
- * The AtttributeDriver reads the mapping metadata from attributes.
+ * The AttributeDriver reads the mapping metadata from attributes.
  */
 class AttributeDriver implements MappingDriver
 {
@@ -264,6 +264,8 @@ public function loadMetadataForClass($className, PersistenceClassMetadata $metad
                     $mapping['version'] = true;
                 } elseif ($propertyAttribute instanceof ODM\Lock) {
                     $mapping['lock'] = true;
+                } elseif ($propertyAttribute instanceof ODM\Encrypt) {
+                    $mapping['encrypt'] = (array) $propertyAttribute;
                 }
             }
 

lib/Doctrine/ODM/MongoDB/SchemaManager.php

@@ -7,6 +7,7 @@
 use Doctrine\ODM\MongoDB\Mapping\ClassMetadata;
 use Doctrine\ODM\MongoDB\Mapping\ClassMetadataFactoryInterface;
 use Doctrine\ODM\MongoDB\Repository\ViewRepository;
+use Doctrine\ODM\MongoDB\Utility\EncryptionFieldMap;
 use InvalidArgumentException;
 use MongoDB\Driver\Exception\CommandException;
 use MongoDB\Driver\Exception\RuntimeException;
@@ -643,10 +644,29 @@ public function createDocumentCollection(string $documentName, ?int $maxTimeMs =
             }
         }
 
-        $this->dm->getDocumentDatabase($documentName)->createCollection(
-            $class->getCollection(),
-            $this->getWriteOptions($maxTimeMs, $writeConcern, $options),
-        );
+        // Encryption is enabled only if the KMS provider is set and at least one field is encrypted
+        if ($this->dm->getConfiguration()->getKmsProvider()) {
+            $encryptedFields = (new EncryptionFieldMap($this->dm->getMetadataFactory()))->getEncryptionFieldMap($class->name);
+
+            if ($encryptedFields) {
+                $options['encryptedFields'] = ['fields' => $encryptedFields];
+            }
+        }
+
+        if (isset($options['encryptedFields'])) {
+            $this->dm->getDocumentDatabase($documentName)->createEncryptedCollection(
+                $class->getCollection(),
+                $this->dm->getClientEncryption(),
+                $this->dm->getConfiguration()->getKmsProvider(),
+                null, // @todo when is it necessary to set the master key?
+                $options,
+            );
+        } else {
+            $this->dm->getDocumentDatabase($documentName)->createCollection(
+                $class->getCollection(),
+                $this->getWriteOptions($maxTimeMs, $writeConcern, $options),
+            );
+        }
     }
 
     /**

lib/Doctrine/ODM/MongoDB/Utility/EncryptionFieldMap.php

@@ -0,0 +1,62 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Doctrine\ODM\MongoDB\Utility;
+
+use Doctrine\ODM\MongoDB\Mapping\ClassMetadataFactoryInterface;
+use Generator;
+
+use function array_filter;
+use function iterator_to_array;
+
+final class EncryptionFieldMap
+{
+    public function __construct(private ClassMetadataFactoryInterface $classMetadataFactory)
+    {
+    }
+
+    /**
+     * Generate the encryption field map from the class metadata.
+     *
+     * @param class-string $className
+     */
+    public function getEncryptionFieldMap(string $className): array
+    {
+        return iterator_to_array($this->createEncryptionFieldMap($className));
+    }
+
+    private function createEncryptionFieldMap(string $className, string $path = ''): Generator
+    {
+        $classMetadata = $this->classMetadataFactory->getMetadataFor($className);
+        foreach ($classMetadata->fieldMappings as $mapping) {
+            // @todo support polymorphic types and inheritence?
+            // Add fields recursively
+            if ($mapping['embedded'] ?? false) {
+                yield from $this->createEncryptionFieldMap($mapping['targetDocument'], $path . $mapping['name'] . '.');
+            }
+
+            if (! isset($mapping['encrypt'])) {
+                continue;
+            }
+
+            $field = [
+                'path' => $path . $mapping['name'],
+                'bsonType' => match ($mapping['type']) {
+                    'one' => 'object',
+                    'many' => 'array',
+                    default => $mapping['type'],
+                },
+                // @todo allow setting a keyId in #[Encrypt] attribute
+                'keyId' => null, // Generate the key automatically
+            ];
+
+            // When queryType is null, the field is not queryable
+            if (isset($mapping['encrypt']['queryType'])) {
+                $field['queries'] = array_filter($mapping['encrypt'], static fn ($v) => $v !== null);
+            }
+
+            yield $field;
+        }
+    }
+}

tests/Doctrine/ODM/MongoDB/Tests/BaseTestCase.php

@@ -129,8 +129,14 @@ protected static function createMetadataDriverImpl(): MappingDriver
 
     protected static function createTestDocumentManager(): DocumentManager
     {
-        $config = static::getConfiguration();
-        $client = new Client(self::getUri());
+        $config        = static::getConfiguration();
+        $driverOptions = [];
+
+        if ($config->getAutoEncryption()) {
+            $driverOptions['autoEncryption'] = $config->getAutoEncryption();
+        }
+
+        $client = new Client(self::getUri(), [], $driverOptions);
 
         return DocumentManager::create($client, $config);
     }