wip PHPLIB-913: Database::createEncryptedCollection() helper

Author: jmikola

src/Database.php

@@ -18,6 +18,7 @@
 namespace MongoDB;
 
 use Iterator;
+use MongoDB\Driver\ClientEncryption;
 use MongoDB\Driver\Cursor;
 use MongoDB\Driver\Exception\RuntimeException as DriverRuntimeException;
 use MongoDB\Driver\Manager;
@@ -44,7 +45,10 @@
 use MongoDB\Operation\Watch;
 use Traversable;
 
+use function array_key_exists;
 use function is_array;
+use function is_object;
+use function property_exists;
 use function strlen;
 
 class Database
@@ -300,6 +304,60 @@ public function createCollection(string $collectionName, array $options = [])
         return $result;
     }
 
+    /**
+     * Create a new encrypted collection.
+     *
+     * This function will automatically create data keys for any encrypted
+     * fields where the "keyId" option is null. This function will return a copy
+     * of the modified "encryptedFields" option in addition to the result from
+     * createCollection().
+     *
+     * This function requires that the "encryptedFields" option be specified.
+     *
+     * If any error is encountered while creating data keys or invoking
+     * createCollection(), a CreateEncryptedCollectionException will be thrown.
+     * The original exception and modified "encryptedFields" option can be
+     * accessed via getPrevious() and getEncryptedFields(), respectively.
+     *
+     * @see CreateCollection::__construct() for supported options
+     * @return array A tuple consisting of the createCollection() result and modified "encryptedFields" option
+     * @throws InvalidArgumentException for parameter/option parsing errors
+     * @throws CreateEncryptedCollectionException for errors generating data keys or invoking createCollection
+     */
+    public function createEncryptedCollection(string $collectionName, ClientEncryption $clientEncryption, string $kmsProvider, ?array $masterKey, array $options = []): array
+    {
+        if (! isset($options['encryptedFields']) || ! is_array($options['encryptedFields']) && ! is_object($options['encryptedFields'])) {
+            throw InvalidArgumentException::invalidType('"encryptedFields" option', $options['encryptedFields'] ?? null, 'array or object');
+        }
+
+        $encryptedFields = (array) recursive_copy($options['encryptedFields']);
+
+        $createDataKeyArgs = [
+            $kmsProvider,
+            isset($masterKey) ? ['masterKey' => $masterKey] : [],
+        ];
+
+        try {
+            if (isset($encryptedFields['fields']) && is_array($encryptedFields['fields'])) {
+                foreach ($encryptedFields['fields'] as &$field) {
+                    if (is_array($field) && array_key_exists('keyId', $field) && $field['keyId'] === null) {
+                        $field['keyId'] = $clientEncryption->createDataKey(...$createDataKeyArgs);
+                    } elseif (is_object($field) && property_exists($field, 'keyId') && $field->keyId === null) {
+                        $field->keyId = $clientEncryption->createDataKey(...$createDataKeyArgs);
+                    }
+                }
+
+                $options['encryptedFields'] = $encryptedFields;
+            }
+
+            $result = $this->createCollection($collectionName, $options);
+
+            return [$result, $encryptedFields];
+        } catch (Exception $e) {
+            throw new CreateEncryptedCollectionException($e, $encryptedFields);
+        }
+    }
+
     /**
      * Drop this database.
      *

src/Exception/CreateEncryptedCollectionException.php

@@ -0,0 +1,55 @@
+<?php
+/*
+ * Copyright 2023-present MongoDB, Inc.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *   https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+namespace MongoDB\Exception;
+
+use Throwable;
+
+use function get_class;
+use function sprintf;
+
+/**
+ * @internal
+ * @see \MongoDB\Database::createEncryptedCollection()
+ */
+final class CreateEncryptedCollectionException extends RuntimeException
+{
+    private array $encryptedFields;
+
+    public function __construct(Throwable $previous, array $encryptedFields)
+    {
+        parent::__construct(sprintf('Creating encrypted collection failed due to previous %s: %s', get_class($previous), $previous->getMessage()), 0, $previous);
+
+        $this->encryptedFields = $encryptedFields;
+    }
+
+    /**
+     * Returns the encryptedFields option in its last known state before the
+     * operation was interrupted.
+     *
+     * This can be used to infer which data keys were successfully created;
+     * however, it is possible that additional data keys were successfully
+     * created and are not present in the returned value. For example, if the
+     * operation was interrupted by a timeout error when creating a data key,
+     * the write may actually have succeeded on the server but the key will not
+     * be present in the returned value.
+     */
+    public function getEncryptedFields(): array
+    {
+        return $this->encryptedFields;
+    }
+}

tests/SpecTests/ClientSideEncryption/FunctionalTestCase.php

@@ -0,0 +1,130 @@
+<?php
+
+namespace MongoDB\Tests\SpecTests\ClientSideEncryption;
+
+use MongoDB\BSON\Int64;
+use MongoDB\Client;
+use MongoDB\Driver\WriteConcern;
+use MongoDB\Tests\SpecTests\FunctionalTestCase as BaseFunctionalTestCase;
+use PHPUnit\Framework\Assert;
+use stdClass;
+
+use function explode;
+use function getenv;
+use function is_executable;
+use function is_readable;
+use function sprintf;
+use function strlen;
+use function unserialize;
+
+use const DIRECTORY_SEPARATOR;
+use const PATH_SEPARATOR;
+
+/**
+ * Base class for client-side encryption prose tests.
+ *
+ * @see https://github.com/mongodb/specifications/blob/bc37892f360cab9df4082922384e0f4d4233f6d3/source/client-side-encryption/tests/README.rst
+ */
+abstract class FunctionalTestCase extends BaseFunctionalTestCase
+{
+    public const LOCAL_MASTERKEY = 'Mng0NCt4ZHVUYUJCa1kxNkVyNUR1QURhZ2h2UzR2d2RrZzh0cFBwM3R6NmdWMDFBMUN3YkQ5aXRRMkhGRGdQV09wOGVNYUMxT2k3NjZKelhaQmRCZGJkTXVyZG9uSjFk';
+
+    public function setUp(): void
+    {
+        parent::setUp();
+
+        $this->skipIfClientSideEncryptionIsNotSupported();
+
+        if (! static::isCryptSharedLibAvailable() && ! static::isMongocryptdAvailable()) {
+            $this->markTestSkipped('Neither crypt_shared nor mongocryptd are available');
+        }
+    }
+
+    public static function createTestClient(?string $uri = null, array $options = [], array $driverOptions = []): Client
+    {
+        if (isset($driverOptions['autoEncryption']) && getenv('CRYPT_SHARED_LIB_PATH')) {
+            $driverOptions['autoEncryption']['extraOptions']['cryptSharedLibPath'] = getenv('CRYPT_SHARED_LIB_PATH');
+        }
+
+        return parent::createTestClient($uri, $options, $driverOptions);
+    }
+
+    protected static function getAWSCredentials(): array
+    {
+        return [
+            'accessKeyId' => static::getEnv('AWS_ACCESS_KEY_ID'),
+            'secretAccessKey' => static::getEnv('AWS_SECRET_ACCESS_KEY'),
+        ];
+    }
+
+    protected static function insertKeyVaultData(Client $client, ?array $keyVaultData = null): void
+    {
+        $collection = $client->selectCollection('keyvault', 'datakeys', ['writeConcern' => new WriteConcern(WriteConcern::MAJORITY)]);
+        $collection->drop();
+
+        if (empty($keyVaultData)) {
+            return;
+        }
+
+        $collection->insertMany($keyVaultData);
+    }
+
+    private function createInt64(string $value): Int64
+    {
+        $array = sprintf('a:1:{s:7:"integer";s:%d:"%s";}', strlen($value), $value);
+        $int64 = sprintf('C:%d:"%s":%d:{%s}', strlen(Int64::class), Int64::class, strlen($array), $array);
+
+        return unserialize($int64);
+    }
+
+    private function createTestCollection(?stdClass $encryptedFields = null, ?stdClass $jsonSchema = null): void
+    {
+        $context = $this->getContext();
+        $options = $context->defaultWriteOptions;
+
+        if (! empty($encryptedFields)) {
+            $options['encryptedFields'] = $encryptedFields;
+        }
+
+        if (! empty($jsonSchema)) {
+            $options['validator'] = ['$jsonSchema' => $jsonSchema];
+        }
+
+        $context->getDatabase()->createCollection($context->collectionName, $options);
+    }
+
+    private static function getEnv(string $name): string
+    {
+        $value = getenv($name);
+
+        if ($value === false) {
+            Assert::markTestSkipped(sprintf('Environment variable "%s" is not defined', $name));
+        }
+
+        return $value;
+    }
+
+    private static function isCryptSharedLibAvailable(): bool
+    {
+        $cryptSharedLibPath = getenv('CRYPT_SHARED_LIB_PATH');
+
+        if ($cryptSharedLibPath === false) {
+            return false;
+        }
+
+        return is_readable($cryptSharedLibPath);
+    }
+
+    private static function isMongocryptdAvailable(): bool
+    {
+        $paths = explode(PATH_SEPARATOR, getenv("PATH"));
+
+        foreach ($paths as $path) {
+            if (is_executable($path . DIRECTORY_SEPARATOR . 'mongocryptd')) {
+                return true;
+            }
+        }
+
+        return false;
+    }
+}