PHPLIB-492: Create tutorial for client side encryption

Author: alcaeus

docs/tutorial.txt

@@ -10,6 +10,7 @@ Tutorials
    /tutorial/commands
    /tutorial/custom-types
    /tutorial/decimal128
+   /tutorial/fle
    /tutorial/gridfs
    /tutorial/indexes
    /tutorial/tailable-cursor

docs/tutorial/fle.txt

@@ -0,0 +1,164 @@
+======================
+Client Side Encryption
+======================
+
+.. default-domain:: mongodb
+
+.. contents:: On this page
+   :local:
+   :backlinks: none
+   :depth: 1
+   :class: singlecol
+
+Cliend Side Encryption allows administrators and developers to encrypt specific
+data fields in addition to other MongoDB encryption features.
+
+
+Automatic encryption and decryption
+-----------------------------------
+
+.. note::
+
+   Auto encryption is an enterprise only feature.
+
+The following example assumes the key and schema have already been created in
+MongoDB. The example uses a local key, however using AWS Key Management Service
+is also an option. The data in the ``encryptedField`` field is automatically
+encrypted on the insert and decrypted when using find on the client side.
+
+.. code-block:: php
+
+   <?php
+
+   use MongoDB\BSON\Binary;
+   use MongoDB\Client;
+
+   $localKey = new Binary('<binary key data>', Binary::TYPE_GENERIC);
+
+   $autoEncryptionOpts = [
+       'keyVaultNamespace' => 'admin.datakeys',
+       'kmsProviders' => [
+           'local' => ['key' => $localKey],
+       ],
+   ];
+
+   $encryptedClient = new Client(null, [], ['autoEncryption' => $autoEncryptionOpts]);
+
+   $collection = $encryptedClient->selectCollection('test', 'coll');
+   $collection->drop(); // clear old data
+
+   $collection->insertOne(['encryptedField' => '123456789']);
+
+   var_dump($collection->findOne([]));
+
+
+Specifying an explicit schema for encryption
+--------------------------------------------
+
+The following example shows how to create a new key and store it in the key
+vault collection. The encrypted client configures an explicit schema for
+encryption using the newly created key.
+
+.. note::
+
+   Supplying a ```schemaMap``` provides more security than relying on JSON
+   schemas obtained from the server. It protects against a malicious server
+   advertising a false JSON schema, which could trick the client into sending
+   unencrypted data that should be encrypted.
+
+.. code-block:: php
+
+   <?php
+
+   use MongoDB\BSON\Binary;
+   use MongoDB\Client;
+   use MongoDB\Driver\ClientEncryption;
+
+   $localKey = new Binary('<binary key data>', Binary::TYPE_GENERIC);
+
+   $clientEncryptionOpts = [
+       'keyVaultNamespace' => 'admin.datakeys',
+       'kmsProviders' => [
+           'local' => ['key' => $localKey],
+       ],
+   ];
+
+   $client = new Client();
+   $clientEncryption = $client->createClientEncryption($clientEncryptionOpts);
+
+   // Create new key in the key vault and store its ID for later use
+   $keyId = $clientEncryption->createDataKey('local');
+
+   $autoEncryptionOpts = [
+       'keyVaultNamespace' => 'admin.datakeys',
+       '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,
+                       ],
+                   ],
+               ],
+           ],
+       ],
+   ];
+
+   $encryptedClient = new Client(null, [], ['autoEncryption' => $autoEncryptionOpts]);
+
+   $collection = $encryptedClient->selectCollection('test', 'coll');
+   $collection->drop(); // clear old data
+
+   $collection->insertOne(['encryptedField' => '123456789']);
+
+   var_dump($collection->findOne([]));
+
+
+Manually encrypting and decrypting values
+-----------------------------------------
+
+In the Community edition of MongoDB, you will have to manually encrypt and
+decrypt values before storing them in the database. The following example
+assumes that you have already created an encryption key in the key vault
+collection and explicitly encrypts and decrypts values in the document.
+
+.. code-block:: php
+
+   <?php
+
+   use MongoDB\BSON\Binary;
+   use MongoDB\Client;
+   use MongoDB\Driver\ClientEncryption;
+
+   $localKey = new Binary('<binary key data>', Binary::TYPE_GENERIC);
+   $keyId    = new Binary('<UUID of encryption key', Binary::TYPE_UUID);
+
+   $clientEncryptionOpts = [
+       'keyVaultNamespace' => 'admin.datakeys',
+       'kmsProviders' => [
+           'local' => ['key' => $localKey],
+       ],
+   ];
+
+   $client = new Client();
+   $clientEncryption = $client->createClientEncryption($clientEncryptionOpts);
+
+   $collection = $client->selectCollection('test', 'coll');
+   $collection->drop(); // clear old data
+
+   $encryptionOpts = [
+       'keyId' => $keyId,
+       'algorithm' => ClientEncryption::AEAD_AES_256_CBC_HMAC_SHA_512_DETERMINISTIC,
+   ];
+   $encryptedValue = $clientEncryption->encrypt('123456789', $encryptionOpts);
+
+   $collection->insertOne(['encryptedField' => $encryptedValue]);
+
+   $document = $collection->findOne();
+   var_dump($clientEncryption->decrypt($document->encryptedField));