diff --git a/doc/changelog.rst b/doc/changelog.rst index c53ec2201a..b2fcb7fa24 100644 --- a/doc/changelog.rst +++ b/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 ------------------------- diff --git a/doc/conf.py b/doc/conf.py index 7b1580de32..ff330b59a4 100644 --- a/doc/conf.py +++ b/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/]*", ] diff --git a/doc/examples/encryption.rst b/doc/examples/encryption.rst index e86eb7733d..5568b0d741 100644 --- a/doc/examples/encryption.rst +++ b/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://git@github.com/mongodb/mongo-python-driver.git@4.2.0b0#egg=pymongo[encryption]" + +Additionally, ``libmongocrypt`` must be installed 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