PYTHON-3299 Add Automatic Queryable Encryption Example to Docs (#964)

Author: blink1073

doc/changelog.rst

@@ -10,7 +10,7 @@ PyMongo 4.2 brings a number of improvements including:
 
 - Support for MongoDB 6.0.
 - Support for the Queryable Encryption beta with MongoDB 6.0. Note that backwards-breaking
-  changes may be made before the final release.
+  changes may be made before the final release.  See :ref:`automatic-queryable-client-side-encryption` for example usage.
 - Provisional (beta) support for :func:`pymongo.timeout` to apply a single timeout
   to an entire block of pymongo operations.
 
@@ -41,6 +41,7 @@ in this release.
 .. _PYTHON-2885: https://jira.mongodb.org/browse/PYTHON-2885
 .. _PYTHON-3167: https://jira.mongodb.org/browse/PYTHON-3167
 .. _PyMongo 4.2 release notes in JIRA: https://jira.mongodb.org/secure/ReleaseNote.jspa?projectId=10004&version=33196
+.. _Queryable Encryption: automatic-queryable-client-side-encryption
 
 Changes in Version 4.1.1
 -------------------------

doc/conf.py

@@ -85,6 +85,7 @@
 # so this link results in a 404.
 linkcheck_ignore = [
     "https://github.com/mongodb/specifications/blob/master/source/server-discovery-and-monitoring/server-monitoring.rst#requesting-an-immediate-check",
+    "https://github.com/mongodb/libmongocrypt/blob/master/bindings/python/README.rst#installing-from-source",
     r"https://wiki.centos.org/[\w/]*",
 ]
 

doc/examples/encryption.rst

@@ -336,6 +336,79 @@ data key and create a collection with the
   if __name__ == "__main__":
       main()
 
+.. _automatic-queryable-client-side-encryption:
+
+Automatic Queryable Encryption (Beta)
+`````````````````````````````````````
+
+PyMongo 4.2 brings beta support for Queryable Encryption with MongoDB 6.0.
+
+Queryable Encryption is the second version of Client-Side Field Level Encryption.
+Data is encrypted client-side. Queryable Encryption supports indexed encrypted fields,
+which are further processed server-side.
+
+You must have MongoDB 6.0rc8+ Enterprise to preview the capability.
+
+Until PyMongo 4.2 release is finalized, it can be installed using::
+
+  pip install "pymongo@git+ssh://[email protected]/mongodb/[email protected]#egg=pymongo[encryption]"
+
+Additionally, ``libmongocrypt`` must be installed from `source <https://github.com/mongodb/libmongocrypt/blob/master/bindings/python/README.rst#installing-from-source>`_.
+
+Automatic encryption in Queryable Encryption is configured with an ``encrypted_fields`` mapping, as demonstrated by the following example::
+
+  import os
+  from bson.codec_options import CodecOptions
+  from pymongo import MongoClient
+  from pymongo.encryption import Algorithm, ClientEncryption, QueryType
+  from pymongo.encryption_options import AutoEncryptionOpts
+
+
+  local_master_key = os.urandom(96)
+  kms_providers = {"local": {"key": local_master_key}}
+  key_vault_namespace = "keyvault.datakeys"
+  key_vault_client = MongoClient()
+  client_encryption = ClientEncryption(
+      kms_providers, key_vault_namespace, key_vault_client, CodecOptions()
+  )
+  key_vault = key_vault_client["keyvault"]["datakeys"]
+  key_vault.drop()
+  key1_id = client_encryption.create_data_key("local", key_alt_names=["firstName"])
+  key2_id = client_encryption.create_data_key("local", key_alt_names=["lastName"])
+
+  encrypted_fields_map = {
+      "default.encryptedCollection": {
+        "escCollection": "encryptedCollection.esc",
+        "eccCollection": "encryptedCollection.ecc",
+        "ecocCollection": "encryptedCollection.ecoc",
+        "fields": [
+          {
+            "path": "firstName",
+            "bsonType": "string",
+            "keyId": key1_id,
+            "queries": [{"queryType": "equality"}],
+          },
+            {
+              "path": "lastName",
+              "bsonType": "string",
+              "keyId": key2_id,
+            }
+        ]
+      }
+  }
+
+  auto_encryption_opts = AutoEncryptionOpts(
+            kms_providers, key_vault_namespace, encrypted_fields_map=encrypted_fields_map)
+  client = MongoClient(auto_encryption_opts=auto_encryption_opts)
+  client.default.drop_collection('encryptedCollection')
+  coll = client.default.create_collection('encryptedCollection')
+  coll.insert_one({ "_id": 1, "firstName": "Jane", "lastName": "Doe" })
+  docs = list(coll.find({"firstName": "Jane"}))
+  print(docs)
+
+In the above example, the ``firstName`` and ``lastName`` fields are
+automatically encrypted and decrypted.
+
 .. _explicit-client-side-encryption:
 
 Explicit Encryption