Create key vault index in key management scripts and remove setup code elsewhere

jmikola · jmikola · commit 78b579900ca6 · 2023-07-10T12:29:18.000-04:00
This replaces the setup code with a top-of-script comment to avoid repetition. ExamplesTest now prepares the cleans up the necessary collections.

Add a note about creating the partial, unique index on keyAltNames.
diff --git a/docs/examples/create_data_key.php b/docs/examples/create_data_key.php
@@ -14,6 +14,15 @@
 // Create a client with no encryption options
 $client = new Client($uri);
 
+/* Prepare the database for this script. Drop the key vault collection and
+ * ensure it has a unique index for keyAltNames. This would typically be done
+ * during application deployment. */
+$client->selectCollection('encryption', '__keyVault')->drop();
+$client->selectCollection('encryption', '__keyVault')->createIndex(['keyAltNames' => 1], [
+    'unique' => true,
+    'partialFilterExpression' => ['keyAltNames' => ['$exists' => true]],
+]);
+
 // Create a ClientEncryption object to manage data encryption keys
 $clientEncryption = $client->createClientEncryption([
     'keyVaultNamespace' => 'encryption.__keyVault',
@@ -22,11 +31,6 @@
     ],
 ]);
 
-/* Create a new key vault collection for this script. The application must also
- * ensure that a unique index exists for keyAltNames. */
-$client->selectCollection('encryption', '__keyVault')->drop();
-$client->selectCollection('encryption', '__keyVault')->createIndex(['keyAltNames' => 1], ['unique' => true]);
-
 /* Create a data encryption key. To store the key ID for later use, you can use
  * serialize(), var_export(), etc. */
 $keyId = $clientEncryption->createDataKey('local');
diff --git a/docs/examples/csfle-automatic_encryption-local_schema.php b/docs/examples/csfle-automatic_encryption-local_schema.php
@@ -9,6 +9,10 @@
 
 $uri = getenv('MONGODB_URI') ?: 'mongodb://127.0.0.1/';
 
+/* Note: this script assumes that the test database is empty and that the key
+ * vault collection exists and has a partial, unique index on keyAltNames (as
+ * demonstrated in the encryption key management scripts). */
+
 // Generate a secure local key to use for this script
 $localKey = new Binary(random_bytes(96));
 
@@ -23,10 +27,8 @@
     ],
 ]);
 
-/* Create a new key vault collection and data encryption key for this script.
- * Alternatively, this key ID could be read from a configuration file. */
-$client->selectCollection('encryption', '__keyVault')->drop();
-$client->selectCollection('encryption', '__keyVault')->createIndex(['keyAltNames' => 1], ['unique' => true]);
+/* Create a data encryption key. Alternatively, this key ID could be read from a
+ * configuration file. */
 $keyId = $clientEncryption->createDataKey('local');
 
 /* Define a JSON schema for the encrypted collection. Since this only utilizes
@@ -61,7 +63,6 @@
  * Note: without a server-side schema, another client could potentially insert
  * unencrypted data into the collection. Therefore, a local schema should always
  * be used in conjunction with a server-side schema. */
-$encryptedClient->selectDatabase('test')->dropCollection('coll');
 $encryptedClient->selectDatabase('test')->createCollection('coll', ['validator' => ['$jsonSchema' => $schema]]);
 $encryptedCollection = $encryptedClient->selectCollection('test', 'coll');
 
diff --git a/docs/examples/csfle-automatic_encryption-server_side_schema.php b/docs/examples/csfle-automatic_encryption-server_side_schema.php
@@ -9,6 +9,10 @@
 
 $uri = getenv('MONGODB_URI') ?: 'mongodb://127.0.0.1/';
 
+/* Note: this script assumes that the test database is empty and that the key
+ * vault collection exists and has a partial, unique index on keyAltNames (as
+ * demonstrated in the encryption key management scripts). */
+
 // Generate a secure local key to use for this script
 $localKey = new Binary(random_bytes(96));
 
@@ -23,10 +27,8 @@
     ],
 ]);
 
-/* Create a new key vault collection and data encryption key for this script.
- * Alternatively, this key ID could be read from a configuration file. */
-$client->selectCollection('encryption', '__keyVault')->drop();
-$client->selectCollection('encryption', '__keyVault')->createIndex(['keyAltNames' => 1], ['unique' => true]);
+/* Create a data encryption key. Alternatively, this key ID could be read from a
+ * configuration file. */
 $keyId = $clientEncryption->createDataKey('local');
 
 // Create another client with automatic encryption enabled
@@ -53,7 +55,6 @@
 
 /* Create a new collection for this script. Configure a server-side schema by
  * explicitly creating the collection with a "validator" option. */
-$encryptedClient->selectDatabase('test')->dropCollection('coll');
 $encryptedClient->selectDatabase('test')->createCollection('coll', ['validator' => ['$jsonSchema' => $schema]]);
 $encryptedCollection = $encryptedClient->selectCollection('test', 'coll');
 
diff --git a/docs/examples/csfle-explicit_encryption.php b/docs/examples/csfle-explicit_encryption.php
@@ -8,6 +8,10 @@
 
 $uri = getenv('MONGODB_URI') ?: 'mongodb://127.0.0.1/';
 
+/* Note: this script assumes that the test database is empty and that the key
+ * vault collection exists and has a partial, unique index on keyAltNames (as
+ * demonstrated in the encryption key management scripts). */
+
 // Generate a secure local key to use for this script
 $localKey = new Binary(random_bytes(96));
 
@@ -22,22 +26,17 @@
     ],
 ]);
 
-/* Create a new key vault collection and data encryption key for this script.
- * Alternatively, this key ID could be read from a configuration file. */
-$client->selectCollection('encryption', '__keyVault')->drop();
-$client->selectCollection('encryption', '__keyVault')->createIndex(['keyAltNames' => 1], ['unique' => true]);
+/* Create a data encryption key. Alternatively, this key ID could be read from a
+ * configuration file. */
 $keyId = $clientEncryption->createDataKey('local');
 
-// Create a new collection for this script
-$collection = $client->selectCollection('test', 'coll');
-$collection->drop();
-
 // Insert a document with a manually encrypted field
 $encryptedValue = $clientEncryption->encrypt('mySecret', [
     'algorithm' => ClientEncryption::AEAD_AES_256_CBC_HMAC_SHA_512_DETERMINISTIC,
     'keyId' => $keyId,
 ]);
 
+$collection = $client->selectCollection('test', 'coll');
 $collection->insertOne(['_id' => 1, 'encryptedField' => $encryptedValue]);
 
 /* Using the client configured without encryption, find the document and observe
diff --git a/docs/examples/csfle-explicit_encryption_automatic_decryption.php b/docs/examples/csfle-explicit_encryption_automatic_decryption.php
@@ -8,6 +8,10 @@
 
 $uri = getenv('MONGODB_URI') ?: 'mongodb://127.0.0.1/';
 
+/* Note: this script assumes that the test database is empty and that the key
+ * vault collection exists and has a partial, unique index on keyAltNames (as
+ * demonstrated in the encryption key management scripts). */
+
 // Generate a secure local key to use for this script
 $localKey = new Binary(random_bytes(96));
 
@@ -28,22 +32,17 @@
     ],
 ]);
 
-/* Create a new key vault collection and data encryption key for this script.
- * Alternatively, this key ID could be read from a configuration file. */
-$client->selectCollection('encryption', '__keyVault')->drop();
-$client->selectCollection('encryption', '__keyVault')->createIndex(['keyAltNames' => 1], ['unique' => true]);
+/* Create a data encryption key. Alternatively, this key ID could be read from a
+ * configuration file. */
 $keyId = $clientEncryption->createDataKey('local');
 
-// Create a new collection for this script
-$collection = $client->selectCollection('test', 'coll');
-$collection->drop();
-
 // Insert a document with a manually encrypted field
 $encryptedValue = $clientEncryption->encrypt('mySecret', [
     'algorithm' => ClientEncryption::AEAD_AES_256_CBC_HMAC_SHA_512_DETERMINISTIC,
     'keyId' => $keyId,
 ]);
 
+$collection = $client->selectCollection('test', 'coll');
 $collection->insertOne(['_id' => 1, 'encryptedField' => $encryptedValue]);
 
 /* Using the client configured with encryption (but not automatic encryption),
diff --git a/docs/examples/key_alt_name.php b/docs/examples/key_alt_name.php
@@ -15,6 +15,15 @@
 // Create a client with no encryption options
 $client = new Client($uri);
 
+/* Prepare the database for this script. Drop the key vault collection and
+ * ensure it has a unique index for keyAltNames. This would typically be done
+ * during application deployment. */
+$client->selectCollection('encryption', '__keyVault')->drop();
+$client->selectCollection('encryption', '__keyVault')->createIndex(['keyAltNames' => 1], [
+    'unique' => true,
+    'partialFilterExpression' => ['keyAltNames' => ['$exists' => true]],
+]);
+
 // Create a ClientEncryption object to manage data encryption keys
 $clientEncryption = $client->createClientEncryption([
     'keyVaultNamespace' => 'encryption.__keyVault',
@@ -23,11 +32,6 @@
     ],
 ]);
 
-/* Create a new key vault collection for this script. The application must also
- * ensure that a unique index exists for keyAltNames. */
-$client->selectCollection('encryption', '__keyVault')->drop();
-$client->selectCollection('encryption', '__keyVault')->createIndex(['keyAltNames' => 1], ['unique' => true]);
-
 // Create a data encryption key with an alternate name
 $clientEncryption->createDataKey('local', ['keyAltNames' => ['myDataKey']]);
 
diff --git a/docs/examples/queryable_encryption-automatic.php b/docs/examples/queryable_encryption-automatic.php
@@ -8,6 +8,10 @@
 
 $uri = getenv('MONGODB_URI') ?: 'mongodb://127.0.0.1/';
 
+/* Note: this script assumes that the test database is empty and that the key
+ * vault collection exists and has a partial, unique index on keyAltNames (as
+ * demonstrated in the encryption key management scripts). */
+
 // Generate a secure local key to use for this script
 $localKey = new Binary(random_bytes(96));
 
@@ -20,10 +24,8 @@
     'kmsProviders' => ['local' => ['key' => $localKey]],
 ]);
 
-/* Create a new key vault collection and data encryption keys for this script.
- * Alternatively, the key IDs could be read from a configuration file. */
-$client->selectCollection('encryption', '__keyVault')->drop();
-$client->selectCollection('encryption', '__keyVault')->createIndex(['keyAltNames' => 1], ['unique' => true]);
+/* Create the data encryption keys for this script. Alternatively, the key IDs
+ * could be read from a configuration file. */
 $keyId1 = $clientEncryption->createDataKey('local');
 $keyId2 = $clientEncryption->createDataKey('local');
 
@@ -53,10 +55,10 @@
     ],
 ]);
 
-/* Create a new collection for this script. The drop and create helpers will
- * infer encryptedFields from the client and manage internal encryption
- * collections automatically. */
-$encryptedClient->selectDatabase('test')->dropCollection('coll');
+/* Create the data collection for this script. The create and drop helpers will
+ * infer encryptedFields from the client configuration and manage internal
+ * encryption collections automatically. Alternatively, the "encryptedFields"
+ * option can also be passed explicitly. */
 $encryptedClient->selectDatabase('test')->createCollection('coll');
 $encryptedCollection = $encryptedClient->selectCollection('test', 'coll');
 
diff --git a/docs/examples/queryable_encryption-explicit.php b/docs/examples/queryable_encryption-explicit.php
@@ -8,6 +8,10 @@
 
 $uri = getenv('MONGODB_URI') ?: 'mongodb://127.0.0.1/';
 
+/* Note: this script assumes that the test database is empty and that the key
+ * vault collection exists and has a partial, unique index on keyAltNames (as
+ * demonstrated in the encryption key management scripts). */
+
 // Generate a secure local key to use for this script
 $localKey = new Binary(random_bytes(96));
 
@@ -20,10 +24,8 @@
     'kmsProviders' => ['local' => ['key' => $localKey]],
 ]);
 
-/* Create a new key vault collection and data encryption keys for this script.
- * Alternatively, the key IDs could be read from a configuration file. */
-$client->selectCollection('encryption', '__keyVault')->drop();
-$client->selectCollection('encryption', '__keyVault')->createIndex(['keyAltNames' => 1], ['unique' => true]);
+/* Create the data encryption keys. Alternatively, the key IDs could be read
+ * from a configuration file. */
 $keyId1 = $clientEncryption->createDataKey('local');
 $keyId2 = $clientEncryption->createDataKey('local');
 
@@ -53,9 +55,10 @@
     ],
 ];
 
-/* Create a new collection for this script. Pass encryptedFields to the drop and
- * create helpers to ensure that internal encryption collections are managed. */
-$encryptedClient->selectDatabase('test')->dropCollection('coll', ['encryptedFields' => $encryptedFields]);
+/* Create the data collection for this script. Specify the "encryptedFields"
+ * option to ensure that internal encryption collections are also created. The
+ * "encryptedFields" option should also be specified when dropping the
+ * collection to ensure that internal encryption collections are dropped. */
 $encryptedClient->selectDatabase('test')->createCollection('coll', ['encryptedFields' => $encryptedFields]);
 $encryptedCollection = $encryptedClient->selectCollection('test', 'coll');
 
diff --git a/docs/tutorial/encryption.txt b/docs/tutorial/encryption.txt
@@ -115,10 +115,13 @@ To reference keys in your application, you can use the ``keyAltName``
 attribute specified when creating the key. The following example creates an
 encryption key with an alternative name, which could be done when deploying the
 application. The script then encrypts data by referencing the key by its
-alternative name.
+alternative name using the ``keyAltName`` option instead of ``keyId``.
 
-To use an alternate name when referencing an encryption key, use the
-``keyAltName`` option instead of ``keyId``.
+.. note::
+
+   Prior to adding a new key alternate name, you must create a partial, unique
+   index on the ``keyAltNames`` field. Client-Side Field Level Encryption
+   depends on server-enforced uniqueness of key alternate names.
 
 .. literalinclude:: /examples/key_alt_name.php
    :language: php
diff --git a/tests/ExamplesTest.php b/tests/ExamplesTest.php
@@ -201,11 +201,17 @@ public function testEncryptionExamples(string $file, string $expectedOutput): vo
     {
         $this->skipIfClientSideEncryptionIsNotSupported();
 
-        $this->assertExampleOutput($file, $expectedOutput);
-
-        // Clean up metadata and key vault collections
+        /* Ensure that the key vault, collection under test, and any metadata
+         * collections are cleaned up before and after the example is run. */
         $this->dropCollection('test', 'coll', ['encryptedFields' => []]);
         $this->dropCollection('encryption', '__keyVault');
+
+        /* Ensure the key vault has a partial, unique index for keyAltNames. The
+         * key management examples already do this, so this is mainly for the
+         * benefit of other scripts. */
+        $this->setUpKeyVaultIndex();
+
+        $this->assertExampleOutput($file, $expectedOutput);
     }
 
     public static function provideEncryptionExamples(): Generator
@@ -342,11 +348,15 @@ public function testQueryableEncryptionExamples(string $file, string $expectedOu
 
         $this->skipIfServerVersion('<', '7.0.0', 'Queryable encryption tests require MongoDB 7.0 or later');
 
-        $this->assertExampleOutput($file, $expectedOutput);
-
-        // Clean up metadata and key vault collections
+        /* Ensure that the key vault, collection under test, and any metadata
+         * collections are cleaned up before and after the example is run. */
         $this->dropCollection('test', 'coll', ['encryptedFields' => []]);
         $this->dropCollection('encryption', '__keyVault');
+
+        // Ensure the key vault has a partial, unique index for keyAltNames
+        $this->setUpKeyVaultIndex();
+
+        $this->assertExampleOutput($file, $expectedOutput);
     }
 
     public static function provideQueryableEncryptionExamples(): Generator
@@ -452,4 +462,15 @@ private function assertExampleOutput(string $file, string $expectedOutput): void
 
         $this->assertStringMatchesFormat($expectedOutput, $this->getActualOutputForAssertion());
     }
+
+    private function setUpKeyVaultIndex(): void
+    {
+        self::createTestClient()->selectCollection('encryption', '__keyVault')->createIndex(
+            ['keyAltNames' => 1],
+            [
+                'unique' => true,
+                'partialFilterExpression' => ['keyAltNames' => ['$exists' => true]],
+            ]
+        );
+    }
 }
