Code review feedback

Demonstrates schema validation errors in example scripts

Relocates local schema section after server-side schema, and clarifies that it should be used in conjunction with server-side schemas (not instead of).

Revise comments and variable names in scripts and update expected output for tests accordingly.

Author: jmikola

docs/examples/create_data_key.php

@@ -11,21 +11,24 @@
 // Generate a secure local key to use for this script
 $localKey = new Binary(random_bytes(96));
 
-/* Create a client with no encryption options. Additionally, create a
- * ClientEncryption object to manage data keys. */
+// Create a client with no encryption options
 $client = new Client($uri);
 
+// Create a ClientEncryption object to manage data encryption keys
 $clientEncryption = $client->createClientEncryption([
     'keyVaultNamespace' => 'encryption.__keyVault',
     'kmsProviders' => [
         'local' => ['key' => $localKey],
     ],
 ]);
 
-/* Drop the key vault collection and create an encryption key. This would
- * typically be done during application deployment. To store the key ID for
- * later use, you can use serialize() or var_export(). */
+/* 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');
 
 print_r($keyId);

docs/examples/csfle-automatic_encryption-local_schema.php

@@ -3,6 +3,7 @@
 use MongoDB\BSON\Binary;
 use MongoDB\Client;
 use MongoDB\Driver\ClientEncryption;
+use MongoDB\Driver\Exception\ServerException;
 
 require __DIR__ . '/../../vendor/autoload.php';
 
@@ -11,62 +12,75 @@
 // Generate a secure local key to use for this script
 $localKey = new Binary(random_bytes(96));
 
-/* Create a client with no encryption options. Additionally, create a
- * ClientEncryption object to manage data keys. */
+// Create a client with no encryption options
 $client = new Client($uri);
 
+// Create a ClientEncryption object to manage data encryption keys
 $clientEncryption = $client->createClientEncryption([
     'keyVaultNamespace' => 'encryption.__keyVault',
     'kmsProviders' => [
         'local' => ['key' => $localKey],
     ],
 ]);
 
-/* Drop the key vault collection and create an encryption key. Alternatively,
- * this key ID could be read from a configuration file. */
+/* 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]);
 $keyId = $clientEncryption->createDataKey('local');
 
-/* Create a client with automatic encryption enabled. Specify a schemaMap option
- * to enforce a local JSON schema. */
+/* Define a JSON schema for the encrypted collection. Since this only utilizes
+ * encryption schema syntax, it can be used for both the server-side and local
+ * schema. */
+$schema = [
+    'bsonType' => 'object',
+    'properties' => [
+        'encryptedField' => [
+            'encrypt' => [
+                'keyId' => [$keyId],
+                'bsonType' => 'string',
+                'algorithm' => ClientEncryption::AEAD_AES_256_CBC_HMAC_SHA_512_DETERMINISTIC,
+            ],
+        ],
+    ],
+];
+
+/* Create another client with automatic encryption enabled. Configure a local
+ * schema for the encrypted collection using the "schemaMap" option. */
 $encryptedClient = new Client($uri, [], [
     'autoEncryption' => [
         'keyVaultNamespace' => 'encryption.__keyVault',
         'kmsProviders' => ['local' => ['key' => $localKey]],
-        'schemaMap' => [
-            'test.coll' => [
-                'bsonType' => 'object',
-                'properties' => [
-                    'encryptedField' => [
-                        'encrypt' => [
-                            'keyId' => [$keyId],
-                            'bsonType' => 'string',
-                            'algorithm' => ClientEncryption::AEAD_AES_256_CBC_HMAC_SHA_512_DETERMINISTIC,
-                        ],
-                    ],
-                ],
-            ],
-        ],
+        'schemaMap' => ['test.coll' => $schema],
     ],
 ]);
 
-// Drop and create the collection.
+/* Create a new collection for this script. Configure a server-side schema by
+ * explicitly creating the collection with a "validator" option.
+ *
+ * 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');
+$encryptedClient->selectDatabase('test')->createCollection('coll', ['validator' => ['$jsonSchema' => $schema]]);
 $encryptedCollection = $encryptedClient->selectCollection('test', 'coll');
 
-/* Using the encrypted client, insert and find a document. The encrypted field
- * will be automatically encrypted and decrypted. */
-$encryptedCollection->insertOne([
-    '_id' => 1,
-    'encryptedField' => 'mySecret',
-]);
+/* Using the encrypted client, insert and find a document to demonstrate that
+ * the encrypted field is automatically encrypted and decrypted. */
+$encryptedCollection->insertOne(['_id' => 1, 'encryptedField' => 'mySecret']);
 
 print_r($encryptedCollection->findOne(['_id' => 1]));
 
 /* Using the client configured without encryption, find the same document and
- * observe that the field is not automatically decrypted. Additionally, the JSON
- * schema will prohibit inserting a document with an unencrypted field value. */
+ * observe that the field is not automatically decrypted. */
 $unencryptedCollection = $client->selectCollection('test', 'coll');
 
 print_r($unencryptedCollection->findOne(['_id' => 1]));
+
+/* Attempt to insert another document with an unencrypted field value to
+ * demonstrate that the server-side schema is enforced. */
+try {
+    $unencryptedCollection->insertOne(['_id' => 2, 'encryptedField' => 'myOtherSecret']);
+} catch (ServerException $e) {
+    printf("Error inserting document: %s\n", $e->getMessage());
+}

docs/examples/csfle-automatic_encryption-server_side_schema.php

@@ -3,6 +3,7 @@
 use MongoDB\BSON\Binary;
 use MongoDB\Client;
 use MongoDB\Driver\ClientEncryption;
+use MongoDB\Driver\Exception\ServerException;
 
 require __DIR__ . '/../../vendor/autoload.php';
 
@@ -11,63 +12,67 @@
 // Generate a secure local key to use for this script
 $localKey = new Binary(random_bytes(96));
 
-/* Create a client with no encryption options. Additionally, create a
- * ClientEncryption object to manage data keys. */
+// Create a client with no encryption options
 $client = new Client($uri);
 
+// Create a ClientEncryption object to manage data encryption keys
 $clientEncryption = $client->createClientEncryption([
     'keyVaultNamespace' => 'encryption.__keyVault',
     'kmsProviders' => [
         'local' => ['key' => $localKey],
     ],
 ]);
 
-/* Drop the key vault collection and create an encryption key. Alternatively,
- * this key ID could be read from a configuration file. */
+/* 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]);
 $keyId = $clientEncryption->createDataKey('local');
 
-// Create a client with automatic encryption enabled
+// Create another client with automatic encryption enabled
 $encryptedClient = new Client($uri, [], [
     'autoEncryption' => [
         'keyVaultNamespace' => 'encryption.__keyVault',
         'kmsProviders' => ['local' => ['key' => $localKey]],
     ],
 ]);
 
-/* Drop and create the collection. Specify a validator option when creating the
- * collection to enforce a server-side JSON schema. */
-$validator = [
-    '$jsonSchema' => [
-        'bsonType' => 'object',
-        'properties' => [
-            'encryptedField' => [
-                'encrypt' => [
-                    'keyId' => [$keyId],
-                    'bsonType' => 'string',
-                    'algorithm' => ClientEncryption::AEAD_AES_256_CBC_HMAC_SHA_512_DETERMINISTIC,
-                ],
+// Define a JSON schema for the encrypted collection
+$schema = [
+    'bsonType' => 'object',
+    'properties' => [
+        'encryptedField' => [
+            'encrypt' => [
+                'keyId' => [$keyId],
+                'bsonType' => 'string',
+                'algorithm' => ClientEncryption::AEAD_AES_256_CBC_HMAC_SHA_512_DETERMINISTIC,
             ],
         ],
     ],
 ];
 
+/* 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' => $validator]);
+$encryptedClient->selectDatabase('test')->createCollection('coll', ['validator' => ['$jsonSchema' => $schema]]);
 $encryptedCollection = $encryptedClient->selectCollection('test', 'coll');
 
-/* Using the encrypted client, insert and find a document. The encrypted field
- * will be automatically encrypted and decrypted. */
-$encryptedCollection->insertOne([
-    '_id' => 1,
-    'encryptedField' => 'mySecret',
-]);
+/* Using the encrypted client, insert and find a document to demonstrate that
+ * the encrypted field is automatically encrypted and decrypted. */
+$encryptedCollection->insertOne(['_id' => 1, 'encryptedField' => 'mySecret']);
 
 print_r($encryptedCollection->findOne(['_id' => 1]));
 
 /* Using the client configured without encryption, find the same document and
- * observe that the field is not automatically decrypted. Additionally, the JSON
- * schema will prohibit inserting a document with an unencrypted field value. */
+ * observe that the field is not automatically decrypted. */
 $unencryptedCollection = $client->selectCollection('test', 'coll');
 
 print_r($unencryptedCollection->findOne(['_id' => 1]));
+
+/* Attempt to insert another document with an unencrypted field value to
+ * demonstrate that the server-side schema is enforced. */
+try {
+    $unencryptedCollection->insertOne(['_id' => 2, 'encryptedField' => 'myOtherSecret']);
+} catch (ServerException $e) {
+    printf("Error inserting document: %s\n", $e->getMessage());
+}

docs/examples/csfle-explicit_encryption.php

@@ -11,23 +11,24 @@
 // Generate a secure local key to use for this script
 $localKey = new Binary(random_bytes(96));
 
-/* Create a client with no encryption options. Additionally, create a
- * ClientEncryption object to manage data keys. */
+// Create a client with no encryption options
 $client = new Client($uri);
 
+// Create a ClientEncryption object to manage data encryption keys
 $clientEncryption = $client->createClientEncryption([
     'keyVaultNamespace' => 'encryption.__keyVault',
     'kmsProviders' => [
         'local' => ['key' => $localKey],
     ],
 ]);
 
-/* Drop the key vault collection and create an encryption key. Alternatively,
- * this key ID could be read from a configuration file. */
+/* 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]);
 $keyId = $clientEncryption->createDataKey('local');
 
-// Select and drop a collection to use for this example
+// Create a new collection for this script
 $collection = $client->selectCollection('test', 'coll');
 $collection->drop();
 
@@ -37,12 +38,13 @@
     'keyId' => $keyId,
 ]);
 
-$collection->insertOne(['encryptedField' => $encryptedValue]);
+$collection->insertOne(['_id' => 1, 'encryptedField' => $encryptedValue]);
 
-/* Query for the document. The field will not be automatically decrypted
- * because the client was not configured with an autoEncryption driver option.
- * Manually decrypt the field value using the ClientEncryption object. */
+/* Using the client configured without encryption, find the document and observe
+ * that the field is not automatically decrypted. */
 $document = $collection->findOne();
 
-print_r($document->encryptedField);
-print_r($clientEncryption->decrypt($document->encryptedField));
+print_r($document);
+
+// Manually decrypt the field
+printf("Decrypted: %s\n", $clientEncryption->decrypt($document->encryptedField));

docs/examples/csfle-explicit_encryption_automatic_decryption.php

@@ -20,20 +20,21 @@
     ],
 ]);
 
-// Create a ClientEncryption object to manage data keys
+// Create a ClientEncryption object to manage data encryption keys
 $clientEncryption = $client->createClientEncryption([
     'keyVaultNamespace' => 'encryption.__keyVault',
     'kmsProviders' => [
         'local' => ['key' => $localKey],
     ],
 ]);
 
-/* Drop the key vault collection and create an encryption key. Alternatively,
- * this key ID could be read from a configuration file. */
+/* 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]);
 $keyId = $clientEncryption->createDataKey('local');
 
-// Select and drop a collection to use for this example
+// Create a new collection for this script
 $collection = $client->selectCollection('test', 'coll');
 $collection->drop();
 
@@ -43,10 +44,10 @@
     'keyId' => $keyId,
 ]);
 
-$collection->insertOne(['encryptedField' => $encryptedValue]);
+$collection->insertOne(['_id' => 1, 'encryptedField' => $encryptedValue]);
 
-/* Query for the document. The field will still be automatically decrypted
- * because the client was configured with an autoEncryption driver option. */
+/* Using the client configured with encryption (but not automatic encryption),
+ * find the document and observe that the field is automatically decrypted. */
 $document = $collection->findOne();
 
-print_r($document->encryptedField);
+print_r($document);

docs/examples/key_alt_name.php

@@ -3,6 +3,7 @@
 use MongoDB\BSON\Binary;
 use MongoDB\Client;
 use MongoDB\Driver\ClientEncryption;
+use MongoDB\Driver\Exception\ServerException;
 
 require __DIR__ . '/../../vendor/autoload.php';
 
@@ -11,23 +12,33 @@
 // Generate a secure local key to use for this script
 $localKey = new Binary(random_bytes(96));
 
-/* Create a client with no encryption options. Additionally, create a
- * ClientEncryption object to manage data keys. */
+// Create a client with no encryption options
 $client = new Client($uri);
 
+// Create a ClientEncryption object to manage data encryption keys
 $clientEncryption = $client->createClientEncryption([
     'keyVaultNamespace' => 'encryption.__keyVault',
     'kmsProviders' => [
         'local' => ['key' => $localKey],
     ],
 ]);
 
-/* Drop the key vault collection and create an encryption key with an alternate
- * name. This would typically be done during application deployment. To store
- * the key ID for later use, you can use serialize() or var_export(). */
+/* 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']]);
 
+/* Attempt to create a second key with the same name to demonstrate that the
+ * unique index is enforced. */
+try {
+    $clientEncryption->createDataKey('local', ['keyAltNames' => ['myDataKey']]);
+} catch (ServerException $e) {
+    printf("Error creating key: %s\n", $e->getMessage());
+}
+
 // Encrypt a value, using the "keyAltName" option instead of "keyId"
 $encryptedValue = $clientEncryption->encrypt('mySecret', [
     'algorithm' => ClientEncryption::AEAD_AES_256_CBC_HMAC_SHA_512_DETERMINISTIC,