Add support for Field-Level Automatic and Queryable Encryption (#2759)

* Add test document classes from tutorial

https://github.com/mongodb/docs/blob/master/source/includes/qe-tutorials/node/queryable-encryption-tutorial.js

* Create encryption field map

* Create encrypted collection

* Use promoted properties for encrypted document tests

* Revert changes in BaseTestCase

* Rename EncryptionFieldMapTest

* Create Configuration::getDriverOptions() to create the client

* Support class-level #[Encrypt] attribute

* Skip QE tests on non-supported server configuration

* Add documentation on #[Encrypt] attribute

* Add XML mapping for "encrypt" tag

* Create specific xsd type for embedded documents to enable <encrypt> tag

* Fix import class Throwable

* Fix access to $version property before initialization

* Use an enum for query type

* Make getClientEncryption internal

* Improve type of min/max bounds for range queries

* Use getWriteOptions with createEncryptedCollection

* Use random local master key

* Add assertion on non-decrypted data

* Ignore all DOCTRINE_MONGODB_DATABASE phpstan errors

* Baseline phpstan

* Fix CS and skip phpstan issues

Author: GromNaN

docs/en/reference/attributes-reference.rst

@@ -336,6 +336,46 @@ Unlike normal documents, embedded documents cannot specify their own database or
 collection. That said, a single embedded document class may be used with
 multiple document classes, and even other embedded documents!
 
+#[Encrypt]
+----------
+
+The ``#[Encrypt]`` attribute is used to define an encrypted field mapping for a
+document property. It allows you to configure fields for encryption and queryable
+encryption in MongoDB.
+
+Optional arguments:
+
+- ``queryType`` - Specifies the query type for the field. Possible values:
+  - ``null`` (default) - Field is not queryable.
+  - ``EncryptQuery::Equality`` - Enables equality queries.
+  - ``EncryptQuery::Range`` - Enables range queries.
+- ``min``, ``max`` - Specify minimum and maximum (inclusive) queryable values
+  for a field when possible, as smaller bounds improve query efficiency. If
+  querying values outside of these bounds, MongoDB returns an error.
+- ``sparsity``, ``prevision``, ``trimFactor``, ``contention`` - For advanced
+  users only. The default values for these options are suitable for the majority
+  of use cases, and should only be modified if your use case requires it.
+
+Example:
+
+.. code-block:: php
+
+    <?php
+
+    use Doctrine\ODM\MongoDB\Mapping\Annotations\Encrypt;
+    use Doctrine\ODM\MongoDB\Mapping\Annotations\EncryptQuery;
+
+    #[Document]
+    class Client
+    {
+        #[Field]
+        #[Encrypt(queryType: EncryptQuery::Equality)]
+        public string $name;
+    }
+
+For more details, refer to the MongoDB documentation on
+`Queryable Encryption <https://www.mongodb.com/docs/manual/core/queryable-encryption/fundamentals/encrypt-and-query/>`_.
+
 #[Field]
 --------
 

doctrine-mongo-mapping.xsd

@@ -31,6 +31,7 @@
       <xs:element name="field" type="odm:field" minOccurs="0" maxOccurs="unbounded" />
       <xs:element name="embed-one" type="odm:embed-one" minOccurs="0" maxOccurs="unbounded" />
       <xs:element name="embed-many" type="odm:embed-many" minOccurs="0" maxOccurs="unbounded" />
+      <xs:element name="encrypt" type="odm:encrypt-field" minOccurs="0" maxOccurs="1" />
       <xs:element name="reference-one" type="odm:reference-one" minOccurs="0" maxOccurs="unbounded" />
       <xs:element name="reference-many" type="odm:reference-many" minOccurs="0" maxOccurs="unbounded" />
       <xs:element name="discriminator-field" type="odm:discriminator-field" minOccurs="0" />
@@ -183,7 +184,31 @@
     <xs:attribute name="mode" type="odm:read-preference-values" />
   </xs:complexType>
 
+  <xs:complexType name="encrypt-field">
+    <xs:attribute name="queryType">
+      <xs:simpleType>
+        <xs:restriction base="xs:string">
+          <xs:enumeration value="equality" />
+          <xs:enumeration value="range" />
+        </xs:restriction>
+      </xs:simpleType>
+    </xs:attribute>
+    <xs:attribute name="min" type="xs:string" />
+    <xs:attribute name="max" type="xs:string" />
+    <xs:attribute name="sparsity" type="xs:integer" />
+    <xs:attribute name="prevision" type="xs:integer" />
+    <xs:attribute name="trimFactor" type="xs:integer" />
+    <xs:attribute name="contention" type="xs:integer" />
+  </xs:complexType>
+
+  <xs:complexType name="encrypt-embedded-document">
+  </xs:complexType>
+
   <xs:complexType name="field">
+    <xs:choice minOccurs="0" maxOccurs="unbounded">
+      <xs:element name="encrypt" type="odm:encrypt-field" minOccurs="0" maxOccurs="1" />
+    </xs:choice>
+
     <xs:attribute name="name" type="xs:NMTOKEN" />
     <xs:attribute name="type" type="xs:NMTOKEN" />
     <xs:attribute name="strategy" type="odm:storage-strategy" default="set" />

lib/Doctrine/ODM/MongoDB/Configuration.php

@@ -24,6 +24,7 @@
 use Doctrine\Persistence\Mapping\Driver\MappingDriver;
 use Doctrine\Persistence\ObjectRepository;
 use InvalidArgumentException;
+use Jean85\PrettyVersions;
 use LogicException;
 use MongoDB\Driver\WriteConcern;
 use ProxyManager\Configuration as ProxyManagerConfiguration;
@@ -32,10 +33,15 @@
 use ProxyManager\GeneratorStrategy\FileWriterGeneratorStrategy;
 use Psr\Cache\CacheItemPoolInterface;
 use ReflectionClass;
+use Throwable;
 
 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 +56,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 +132,8 @@ class Configuration
      *      persistentCollectionNamespace?: string,
      *      proxyDir?: string,
      *      proxyNamespace?: string,
-     *      repositoryFactory?: RepositoryFactory
+     *      repositoryFactory?: RepositoryFactory,
+     *      autoEncryption?: AutoEncryptionOptions,
      * }
      */
     private array $attributes = [];
@@ -135,6 +147,29 @@ class Configuration
 
     private bool $useLazyGhostObject = false;
 
+    private static string $version;
+
+    /**
+     * Provides the driver options to be used when creating the MongoDB client.
+     *
+     * @return array<string, mixed>
+     */
+    public function getDriverOptions(): array
+    {
+        $driverOptions = [
+            'driver' => [
+                'name' => 'doctrine-odm',
+                'version' => self::getVersion(),
+            ],
+        ];
+
+        if (isset($this->attributes['autoEncryption'])) {
+            $driverOptions['autoEncryption'] = $this->attributes['autoEncryption'];
+        }
+
+        return $driverOptions;
+    }
+
     /**
      * Adds a namespace under a certain alias.
      */
@@ -651,6 +686,63 @@ 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
+     *
+     * @phpstan-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.');
+        }
+
+        // @todo Throw en exception if multiple KMS providers are defined. This is not supported yet and would require a setting for the KMS provider to use when creating a new collection
+        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
+     *
+     * @phpstan-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']);
+    }
+
+    private static function getVersion(): string
+    {
+        if (! isset(self::$version)) {
+            try {
+                self::$version = PrettyVersions::getVersion('doctrine/mongodb-odm')->getPrettyVersion();
+            } catch (Throwable) {
+                return self::$version = 'unknown';
+            }
+        }
+
+        return self::$version;
+    }
 }
 
 interface_exists(MappingDriver::class);

lib/Doctrine/ODM/MongoDB/DocumentManager.php

@@ -25,10 +25,10 @@
 use Doctrine\Persistence\ObjectManager;
 use Doctrine\Persistence\ObjectRepository;
 use InvalidArgumentException;
-use Jean85\PrettyVersions;
 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 +64,8 @@ class DocumentManager implements ObjectManager
      */
     private Client $client;
 
+    private ClientEncryption $clientEncryption;
+
     /**
      * The used Configuration.
      */
@@ -138,8 +140,6 @@ class DocumentManager implements ObjectManager
     /** @var ProxyClassNameResolver&ClassNameResolver  */
     private ProxyClassNameResolver $classNameResolver;
 
-    private static ?string $version = null;
-
     /**
      * Creates a new Document that operates on the given Mongo connection
      * and uses the given Configuration.
@@ -151,12 +151,7 @@ protected function __construct(?Client $client = null, ?Configuration $config =
         $this->client       = $client ?: new Client(
             'mongodb://127.0.0.1',
             [],
-            [
-                'driver' => [
-                    'name' => 'doctrine-odm',
-                    'version' => self::getVersion(),
-                ],
-            ],
+            $this->config->getDriverOptions(),
         );
 
         $this->classNameResolver = $this->config->isLazyGhostObjectEnabled()
@@ -225,6 +220,22 @@ public function getClient(): Client
         return $this->client;
     }
 
+    /** @internal */
+    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
     {
@@ -923,17 +934,4 @@ public function getClassNameForAssociation(array $mapping, $data): string
 
         return $mapping['targetDocument'];
     }
-
-    private static function getVersion(): string
-    {
-        if (self::$version === null) {
-            try {
-                self::$version = PrettyVersions::getVersion('doctrine/mongodb-odm')->getPrettyVersion();
-            } catch (Throwable) {
-                return 'unknown';
-            }
-        }
-
-        return self::$version;
-    }
 }

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

@@ -0,0 +1,47 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Doctrine\ODM\MongoDB\Mapping\Annotations;
+
+use Attribute;
+use DateTimeInterface;
+use Doctrine\Common\Annotations\Annotation\NamedArgumentConstructor;
+use MongoDB\BSON\Decimal128;
+use MongoDB\BSON\Int64;
+use MongoDB\BSON\UTCDateTime;
+
+/**
+ * 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_CLASS | Attribute::TARGET_PROPERTY)]
+final class Encrypt implements Annotation
+{
+    public int|float|Int64|Decimal128|UTCDateTime|null $min;
+    public int|float|Int64|Decimal128|UTCDateTime|null $max;
+
+    /**
+     * @param EncryptQuery|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 ?EncryptQuery $queryType = null,
+        int|float|Int64|Decimal128|UTCDateTime|DateTimeInterface|null $min = null,
+        int|float|Int64|Decimal128|UTCDateTime|DateTimeInterface|null $max = null,
+        public ?int $sparsity = null,
+        public ?int $prevision = null,
+        public ?int $trimFactor = null,
+        public ?int $contention = null,
+    ) {
+        $this->min = $min instanceof DateTimeInterface ? new UTCDateTime($min) : $min;
+        $this->max = $max instanceof DateTimeInterface ? new UTCDateTime($max) : $max;
+    }
+}

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

@@ -0,0 +1,13 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Doctrine\ODM\MongoDB\Mapping\Annotations;
+
+use MongoDB\Driver\ClientEncryption;
+
+enum EncryptQuery: string
+{
+    case Equality = ClientEncryption::QUERY_TYPE_EQUALITY;
+    case Range    = ClientEncryption::QUERY_TYPE_RANGE;
+}